Tekton — 1つの共有モデルでアーキテクチャを共同設計する
これは何か
人間↔エージェントのアーキテクチャ協業のための基盤です。設計は1つのYAMLモデルに集約され、両者が編集します。Gitがラウンドトリップを支えます。あなたはそれを見る（HTMLビューア）ことができ、私は同じモデルを読み書きします。私たちは同じコンテキストで思考します。
これが解決する問題: 手書きのHTML/SVGドキュメントは末端のレンダリングであり、トラバース、クエリ、編集ができず、図に意味がありません。Tektonはライブモデルをレンダリングの上流に移動させます。
エンジン
scripts/tekton.py（Python 3、pyyaml）。オントロジーはreferences/ontology.md。
python3 scripts/tekton.py validate <model.arch.yaml> # 整合性チェック
python3 scripts/tekton.py lint <model.arch.yaml> # v0.2 — フィットネス関数; 違反の場合はexit 1
python3 scripts/tekton.py stats <model.arch.yaml> # ノード/エッジ/ステータス/ルールのカウント
python3 scripts/tekton.py views # 6つのビューを一覧表示
python3 scripts/tekton.py mermaid <model.arch.yaml> <view> # 生のmermaid（埋め込み/エージェント用）
python3 scripts/tekton.py render <model.arch.yaml> [-o out.html] # ブランド準拠のHTMLビューア
python3 scripts/tekton.py query <model.arch.yaml> <from> <to> # 層間パス
v0.2 オントロジーのアップグレード（アーキテクチャレビューより）
- 包含関係 — 任意のノードに
parent:+boundaryタイプ。ビューアはネストグループをレンダリングし、ダブルクリックで折りたたみ/展開（C4スタイルのドリルダウン）。 - ライフサイクル — ノードの
status:（current|target|deprecated。targetは破線でレンダリング = あるべき姿/現状を1つのモデルで表現）と、決定ノードに完全なNygard ADRフィールド（context、consequences、status、supersedes）。 - 品質特性 —
qualities:ブロック。NFRが要素をconstrains。詳細パネルと専用ビューに表示。 - フィットネス関数 —
rules:ブロック（forbid-dep、no-cycle、layer-order）。tekton lintはCIゲート可能（exit 1）。設計ループの独立検証器。
設計セッションでのエージェントの使い方
- モデルの特定/作成:
<project>/docs/design/<name>.arch.yaml（またはスケッチ用にexamples/）。 - 考えながらモデルを変更 — 会話でコンポーネント、フロー、データ、インフラ、ADRが出てくるたびに、YAML内でノード、エッジ、決定を直接追加・調整。
- 各実質的な編集後に**
validate+lint**（未解決参照、不正な型、フィットネスルール）。 renderを実行し、ビューアを正しいと提示する前に、ジオメトリ監査を実行:bash tests/visual-audit.sh <model.arch.yaml>。これにより全ビューをヘッドレスレンダリングし、ノードの重なりや空のキャプチャがあればFAILします。これなしに「図は正しい」と主張することは、最初のドッグフーディングで実際に発生した障害（in-groupエッジの切断、ノードの重複 — DOMカウントプローブでは見えず、ジオメトリでのみ検出）を引き起こします。URLに#<view>を追加してビューにディープリンク。queryでトレーサビリティの質問（「これは何に触れるのか？」）に答える — 推測は不要。- 方向転換 → 繰り返し。 人間がYAMLまたはビューアの意図を編集。git diffがハンドオフになります。
既知の外観上の残存問題（監査失敗ではない）: ジャーニーのループバックエッジはELKが任意のステップでサイクルを切断します（ループはどこかで切断する必要があります）。隣接する並列エッジのラベルが密集したグループ内で近づきすぎることがあります。
規約
- モデルファイル:
*.arch.yaml。レンダリングされたビューア:*.view.html（gitignoreするかコミットするかはお任せ）。 - 境界のあるシステムごとに1つのモデル。
externalノードとusesエッジでシステムをリンク。 - 決定（ADR）は第一級ノード — それらが
governするものにピン留め。 - Category-CのHTMLレポートはモデルの下流エクスポートとなり、情報源ではありません。
レンダリング — Mermaidではない理由
主要なビューアはカスタムレンダラーであり、Mermaidではありません。Mermaidのテーマ設定の制限ではBroomvaデザインシステム（OKLCH青軸、マットカード、獲得されたガラス、彗星グロー）を表現できず、そのdagreレイアウトは密なグラフで劣化します。代わりに: elkjsがブラウザ内でレイアウトを計算します（純粋JS → 出力は単一の自己完結型HTMLファイルのまま）、ノードはBroomvaマットカードとして描画されます（ガラスは浮動詳細パネル用に予約、DSの「ガラスは獲得される」ルールに従います）。デザイントークンはBroomvaデザインシステムからインライン化されます。tekton mermaidは、使い捨ての埋め込み/エージェント可読ターゲットとしてのみ残ります。
ロードマップ（v0 → v2）
- v0.2（現在）: YAMLモデル · validate + lint（フィットネス関数） · 6つのビュー · ブランド準拠のelkjsビューア（包含関係の折りたたみ/展開、あるべき姿/現状、クリックでトレース、ガラス詳細パネル） · 層間クエリ · Mermaidフォールバック埋め込み。
- v1: 双方向ラウンドトリップ（ビューアでのドラッグ/編集 → YAMLへのシリアライズ）。MCPサーバ（検証済みミューテーションによりエージェントが無効なモデルを出力するのを防止）。React-Flowインタラクティブキャンバスのための完全なBroomvaデザインシステムのベンダリング。
- v2: CRDT（loro）によるリアルタイムの人間↔エージェント共同編集。Prosoponへのライブ同期。
ステータス
v0ドッグフード — 内部設計ツール。設計ループが3つ以上の実際のシステムで使用されたら（スリーの法則）、スキル化（テスト済み＋登録済み）。