br

スキル：br — Ralph の生産ライン（BR エンジニアリング → フレーム → ハーネス付きループ）

BR = Business Requirements — br/BR.md に格納されている、確定済みの要件仕様です。このスキルは動詞ではなく、生成する中心的な成果物にちなんで名付けられています。すべてのフレームとすべての条項はこのファイルまで遡れるため、「製品の不具合 ⇔ BR の不具合」（GH#15、2026-07-03）は、この生産ラインのスローガンではなく前提です。

1 つの名前を持つハブ：ユーザーが説明するのは範囲（interview / compile / slice / run / status）であり、複数のコマンドを覚える必要はありません。基盤：council 028（薄切り、人間をループに含める）＋ council 031/032（必須条件 6 つを備えた loop v1 — 勝者 Taleb mean-rank 1.0）。

概要

目的とコンテキスト

• 目的： ユーザーの未加工の要件文書を、BR エンジニアリング → フレーム → ハーネス付きループという生産ラインを通じて、規律ある製品に変換します。すべてのフレームと条項は br/BR.md まで遡れます。
• トリガー（使用するタイミング）：
  • ユーザーが要件文書（未加工／非構造化）を持っていて、規律ある製品に変換したい場合。
  • ユーザーが interview / 要件インタビュー / BR 作成 / frame のスライス / frame の実行 / 生産ラインのステータス / ralph と言った場合。
• 対象外： llmwiki/raw/ への書き込み；すでに実装済みの決定論的ツール（frame-lint.py、loop-runner.py、build-line-status.py…）の書き直し；人に代わって commit / merge すること；/br run の外で UI を手作業で変更すること；自動発火フック。

メンタルモデル

llmwiki/raw/ → interview（S1–S10 の仕様記入済み + 追加質問） → compile（clause_id + 「現在背負っている仮定」 + BR.clauses.json を含む BR.md） → slice（depends_on を持つ frames、frame-lint がゲート） → run（6 つのブレーキを備えた loop-runner、フレームごとの commit、トレース台帳） → qc / find / status（不具合→frame→clause を遡る）。ユーザーは範囲だけを説明し、ハブがモードを選びます。

入力と出力の契約

	フィールド	必須？	意味
In	llmwiki/raw/ 内の未加工文書	はい（interview モード）	読み取り専用；空の場合はユーザーに文書を配置するよう依頼
In	記入済みの br/interview/NNN-answers.md	はい（compile モード）	field-id に沿ったユーザーの実際の回答
In	ユーザーが説明する範囲	はい	interview · compile · slice · run · find · qc · status · sync · contract · rail
In	フラグ --proactive · --lens-fill · --ack-tier · --worktree · --dry-run	いいえ	オプションの分岐（Branches を参照）
Out	br/spec-filled.md、br/interview/NNN-{questions.html,answers.md}	interview モード	各フィールドに status + provenance を含む
Out	br/BR.md、br/BR.clauses.json、br/DESIGN.md（UI がある場合）	compile モード	check-contract がグリーン
Out	br/frames/*.md、br/frames/index.md、br/prompts.md	slice モード	frame-lint がグリーン
Out	frame(<id>) commit、br/frames/<id>.run.json、.checkpoints.jsonl	run モード	1 行の要約 + medic
Out	br/line-status.{json,html} + llmwiki/html/line-status.html	status モード	3 行の要約

ルールと機能

• RULE-01（必須）：人間が最後のゲート — frame の出力を自動で commit / merge しません。dry-run を行い、人間の承認を得ます（council 028）。
• RULE-02（必須）：ブレーキは侵害不可 —「完了させるため」に max_iter を引き上げたり、ガードを無効にしたりすることは決してありません。ブレーキのかけすぎは、ブレーキ不足より安上がりです（council 031/032）。
• RULE-03（必須）：プロンプトでの指示は安全策ではありません — scope-jail/test-hash は決定論的なコード（loop-runner guard 5/6）であり、プロンプト内の指示ではありません（council の全 5 席）。
• RULE-04（必須）：Lens-fill は常に verified: false — 実際の回答と混ぜず、常に「現在背負っている仮定」の表に表示します。
• RULE-05（必須）：最初のサイクルでは人間をループに含めるスライサー — まだ完全自動ではありません（スライサーの不具合は相関した不具合であり、影響範囲 = BR 全体）。
• RULE-06（必須）：ファイル優先、オンデマンド — すべての成果物は持ち運び可能なファイルです。スキルは手動で呼び出し、自動発火フックは使用しません（ADR-004）。
• RULE-07（必須）：閲覧者向けに生成する HTML では、用語を説明し、フルパスを出力します（R16）。
• 機能：未加工文書とコードベースを読み取る；br/ 配下に成果物を書き込む；決定論的ツール（lint、loop、monitor）をローカルで実行する；ツールを厳しく制限したモデルアダプターを呼び出す；確認を得た後にのみ外部トラッカーに issue を作成する。

失敗境界

• llmwiki/raw/ が空 → 確認：ユーザーにドキュメントを入れるよう依頼します。
• br-fill.py check-contract が赤 → コンパイル 失敗。緑になるまで BR を修正します。
• frame-lint.py check が赤、または working-tree が汚れている → /br run は ブロック（実行を拒否します）。
• tier: compensable/irreversible の Frame に --ack-tier がない → ブロック（TIER-GATE）。
• KILL 条件（例：diff-jail が2回以上発動／test-hash が1回発動）に該当 → run 全体を キャンセル。救済も、ブレーキの解除もできません。
• Frame が赤 → 下位のブランチは status: blocked（一部完了）。無関係なブランチは引き続き実行します。
• UI チェックに実際の画像ファイルと MANIFEST.json がない → 失敗として扱います（未実施）。

方法

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	ユーザーの発言	ユーザーが説明した範囲に基づいてモードを選択します（hub 1-name）	mode	あいまいな場合 → 再確認
W02	judgment	llmwiki/raw/ + spec-template	Mode 1 interview：raw を S1–S10 に整理し、gap-diff を行い、questions.html + answers.md を生成します	2 file NNN	raw が空 → 確認；--proactive → B01
W03	deterministic	—	停止 — ユーザーが HTML を開き、answers.md に記入します	記入済み answers	--lens-fill → B02
W04	judgment	spec-filled + answers	Mode 2 compile：BR.md + BR.clauses.json（UI がある場合は DESIGN.md も）	BR	—
W05	deterministic	BR	Gate br-fill.py check-contract	緑	赤 → BR を修正し、W05 を繰り返します
W06	judgment	BR.md	Mode 3 slice：スライスを提案し、ユーザーによる各スライスの承認のため停止して、テンプレートに従って frame を記述します	frames + index	—
W07	deterministic	frames	frame-lint.py check + br-prompts.py sync でゲートします	lint が緑	赤 → frame を修正し、W07 を繰り返します
W08	effect	frame	Mode 4 run：br-run.py run（tier-gate、lint、ツリーのクリーンチェック、loop-runner、commit、run_log_ref、トレースログ）	frame の commit + run log	赤 → 下位のブランチをブロック；KILL → run を破棄
W09	deterministic	frames + run log + BR	Mode 5 status：build-line-status.py build + 3行の要約	line-status.html	エラーが assumed に該当 → 次のサイクルで W02 に戻ります

各ステップの詳細（W01–W09 とすべての補助モードに関する正確な情報源）：

決定論的なツール（ビルド済み + セルフテスト済み — 再実装禁止）

Tool	用途	selftest
skills/br/assets/spec-template.md	標準 spec セット S1–S10（すべてのプロジェクトで参照する枠組み）	—
skills/br/assets/frame-template.md	すべての frame 用の決定論的テンプレート（frontmatter + 人が読んで理解できる本文の4セクション）	—
skills/br/assets/design-template.md	再利用可能な設計テンプレート（Google design-doc の枠組み + /high-end-visual-design から読み込む design system）→ br/DESIGN.md にコピーします	—
fdk/tools/frame-lint.py	7つのルールで frame をゲートします（schema · scope · test-first · freshness · DAG · exclusive-scope lease 付き · content）	frame-lint.py selftest
harness/scripts/loop-runner.py	6つのブレーキを備えた loop（max_iter·budget·no_progress·escalate·diff-jail·test-hash）	loop-runner.py selftest
fdk/tools/build-line-status.py	決定論的なモニター（frame·run-log·BR → json+html、--check）	build-line-status.py selftest

ランタイム成果物はプロジェクトのルートにある br/ に格納されます（skill 内ではありません）：br/spec-filled.md、 br/interview/NNN-{questions.html,answers.md}、br/BR.md、br/BR.clauses.json、br/frames/*.md、 br/frames/index.md、br/frames/<id>.run.json、br/line-status.{json,html}。

Mode 1 — /br interview

1. llmwiki/raw/ 内のファイルをすべて読みます（読み取りのみ。raw/ への書き込みは禁止です）。空の場合は、資料を入れるようユーザーに尋ねます。
2. 標準仕様一式 skills/br/assets/spec-template.md と照合し、raw から情報を取り出して各フィールド S1–S10 に対応付け、br/spec-filled.md に記入します。各フィールドには status（filled|missing|conflict|assumed）と provenance（raw:<file>）を記録します。
3. ギャップ差分：missing／conflict のフィールドから質問一式を生成します。**各フィールドは、明確な仕様を1つ（rigor /orca-workflow）**として扱います。質問では、そのフィールドが何をするものかと、「何をもって回答が十分とするか」（フィールドの受け入れ基準）を示し、曖昧な質問はしません。同じ通し番号 NNN で2つのファイルを作成します。
   • br/interview/NNN-questions.html — セクション別に表示し、用語の説明と各フィールドの十分性基準を含め、フルパスで表示（R16）、ダークモード対応。質問するのは不足部分のみです。
   • br/interview/NNN-answers.md — フィールド ID ごとに記入ブロックを用意します（例：## S4.2 … 空欄）。ユーザーが回答を入力します。 3b. --proactive（T-260714-01、略称 /br auto） — 質問にすべて回答する代わりに、不足部分を機械に埋めさせたい場合：python3 fdk/tools/br-fill.py fill --root . を実行します（必須、モデル不使用）。ツールはレジストリのデフォルト（skills/br/assets/defaults.yaml — 26 のループ条件と github/spec-kit の慣例の表。プロジェクトの上書き設定 br/defaults.yaml は、同じフィールドが重複する場合に優先）を参照し、次の2グループを出力します。
   • 機械入力の提案 → NNN-answers.md に貼り付けます。各項目の filled_by: <source>:<refs> と verified: false はそのまま保持します（lens-fill の規律は機械入力のすべての段階に適用されます）。
   • 実際に尋ねる質問（フィールド carve-out — 認証／権限、信頼境界、金銭 — およびデフォルトのないフィールド）：Impact × Uncertainty に基づいて最大5問を選び（carve-out は先に順位付けされ、質問枠を優先的に占めます）、questions.html に追加します。上限を超えた分は lens-fill します（手順5）。carve-out に機械が値を設定することは決してありません。レジストリに項目がある場合も、lens の場合も同様です。
4. 停止 — HTML を開いて確認し、answers.md に記入するようユーザーに伝えます。
5. ユーザーが --lens-fill を指定した場合（または「確信のない項目を専門家に埋めさせて」と指示した場合）：python3 harness/scripts/council.py roster --case product --json で lens を選び、ユーザーが「不確か」とした missing フィールドを埋めます。各フィールドに filled_by: lens:<name> と verified: false を記録します。ユーザーの実際の回答とは混在させません。

Mode 2 — /br compile

1. 記入済みの br/spec-filled.md と br/interview/*-answers.md を読みます。
2. br/BR.md を生成します。各条項に clause_id（フィールド ID を継承。例：S4.2）と provenance（raw|user|lens:<name>）を付けます。ファイル先頭に 「引き受けている仮定」 の表を置き、lens／assumed の全条項を列挙します（fail-fast：何に賭けているかを一目で確認できます）。
   • UI のある製品（S7.5）：br/DESIGN.md を参照する NFR 条項を1つ（例：N01 インターフェース）確定します。design のルールを BR に転記してはいけません。同時に skills/br/assets/design-template.md を br/DESIGN.md にコピーし、その製品向けに §1／§2／§4／§6／§7 を記入します（継承する §3／§5 はそのまま保持します）。BR = theme/design が必要、DESIGN.md = design がどのように見えるか。
3. br/BR.clauses.json を生成します：{clause_id: {provenance, assumed: bool, fields: ["S4.2", …]}} — fields は、その条項が実現する仕様フィールド S1–S10 を示します（契約チェックサムのキー）。monitor（/br status）はこのファイルを読み、assumed 条項をオレンジ色で表示します。「引き受けている仮定」の表は fill 元（default／spec-kit／lens）ごとにまとめ、レビュー担当者が何をどこから仮定しているか確認できるようにします。
4. 契約チェックサムのゲート（G1 修正 — council c9dc13d）： python3 fdk/tools/br-fill.py check-contract --root . を実行します。S1–S10 の必須フィールドすべてに対応する条項が必要です。赤なら compile は FAIL です。緑になるまで BR を修正します。「compile は完了したが契約に穴がある」という状態は認めません。

モード 3 — /br slice

1. br/BR.md を読みます。スライスの一覧を提案します。各スライスは {clause_ids, 想定 scope_code（≤3 ファイル）、scope_test、acceptance_test、**depends_on**} です。各スライスについてユーザーの確認・修正・統合・分割を待ちます（人間が介在するループ — スライサー相関エラーの防止策です）。最初のバッチは ≤ 3～5 フレームです。
   • depends_on は必ず検討しますが、必ずしも指定が必要なわけではありません（GH#75、Atomic Task Graph の蒸留）。処理の連鎖はリストではなくグラフです。B が A の構築した API／ストア／スキーマを呼び出す場合など、A が成功していなければ B が 成功できない ときは、Frame B に depends_on: [frame-A] を指定します。依存がなければ depends_on: [] とします。正しく指定すれば、モード 4 で 3 つのメリットが得られます。実行順序が自動的に正しくなり、失敗したフレームが下流のブランチを自動的にブロックし、フレームを修正したときはそのブランチだけを再実行すれば済みます。適当に指定すると（「それっぽい」という理由でつなぐと）、並列実行が失われ、不要な待ち時間が生じます。本当の依存関係がある場合のみつないでください。
2. br/frames/frame-NNN-<slug>.md を skills/br/assets/frame-template.md のテンプレートに従って作成します（スキーマ v0 ＋必須の本文 5 セクション：業務 · 入力／出力 · 仕様（FR/SC） · 受け入れ基準 · 対象外 — 後から読む人が理解できるように記述します。frame-lint R7 による厳格なチェックがあります。frame_id には業務内容を表す slug が必要で、muc_tieu を汎用的なものにしてはならず、各フレームに明確な FR-id／SC-id が必要で、セクションを空にしてはなりません）。さらに parent_br_hash = sha256(br/BR.md) を設定します。
3. フレームの frontmatter からレジストリ br/frames/index.md（frame_id · clause_ids · scope_code · status · run_log_ref の表）を生成します。
4. 次のチェックを実行します。python3 fdk/tools/frame-lint.py check br/frames --root . — すべて成功して初めてスライス完了とみなします（R6 の exclusive-scope チェックを含みます。未完了の 2 つのフレームが同じファイルを取り合ってはなりません）。
   • R6 は不動産登記ではなく、賃貸契約です。 完了したフレーム（run-log の verdict: SUCCESS）はファイルを保持する権利を手放します。そのため、新しいフレームが、以前のフレームが保持していた起動ポイント（main.ts、state.ts、server.ts など）に接続できます。リースがなければ、コードは成功しても新機能がユーザーに届きません（walleye 2026-09-10：4 つのフレームが成功したのに、プレイヤーには何も見えません）。未完了の 2 つのフレームが同じファイルを保持すると、依然として失敗します。ただし、depends_on で順番に並べられている場合（このフレームがもう一方の祖先である場合）は例外です。この場合、同時に変更することがないため、同じ main.ts に複数の機能を順番に接続できます。_manifest.json は最後の借主（子孫）にファイルを割り当てます。
   • 各機能には、起動ポイントへ配線するスライスが必要です。 UI フレームの受け入れは、単独モジュールのユニットテストではなく、実際のインターフェースを通るテスト（e2e／route-shots）で行います。
5. python3 fdk/tools/br-prompts.py sync を実行し、新しいフレームのプロンプト項目を br/prompts.md に追加します（ユーザーはすぐに手動で編集できます）。

モード 4 — /br run <frame>

決定的な呼び出し方（配線済み — デフォルトはインプレース、作業ツリーは1つのみ）：

python3 fdk/tools/br-run.py run br/frames/<frame>.md --root .
# xem prompt sẽ gửi mà không chạy: thêm --print-prompt
# chạy cả hàng đợi resumable: python3 fdk/tools/br-queue.py run --queue br/queue.yaml
# sửa 1 frame → chạy lại ĐÚNG nhánh của nó, không cả dây chuyền:
#   python3 fdk/tools/br-queue.py affected <frame_id> --queue br/queue.yaml --reset
#   python3 fdk/tools/br-queue.py run --queue br/queue.yaml
# cần cô lập thư mục thật sự (hiếm): thêm --worktree

キューは手入力した順序ではなく、グラフに沿って実行されます（GH#75 — Atomic Task Graph の蒸留、arXiv 2607.01942）：

• トポロジカル順序：br-queue は各フレームの depends_on を読み取り、自動で順序を決めます（依存関係がなければ、宣言された順序を維持します。従来のキューと同じ実行になります）。
• 赤いフレームは、その下流のブランチ全体をブロックします（status: blocked、blocked_by を記録）：そのブランチの入力は壊れており、続行しても確実に失敗する処理にモデルの実行回数を費やすだけです。関係のないブランチは通常どおり実行されます。フレームの失敗がパイプライン全体を止めることはなくなりました。
• 局所的な修正（affected）：フレームを修正すると、そのフレームと下流のブランチだけが pending に戻り、ほかの成功済みフレームはそのまま維持されます。ここがコスト削減につながります。以前は、連鎖の途中でフレームが失敗すると、必要以上に再実行する必要がありました。
• サブグラフ再利用キャッシュは実装しません（論文にはありますが、意図的に採用していません）：status: done のフレームはすでにスキップされるため、数十フレーム規模でハッシュベースのキャッシュを追加しても、古い状態を使うバグを生むだけです。論文自体の制限もここに当てはまります。グラフが小さく、acceptance_test が決定的ならメリットは変わりませんが、グラフが非常に大きい場合やテスト／ツールの結果が不安定な場合は、この実行スケジュールの効果が失われます。 br-run.py は自動で次の処理を行います：（0）TIER-GATE — frontmatter で tier: compensable|irreversible を宣言したフレーム（元に戻せない副作用：外部 API の呼び出し、メールの送信、DB への書き込み）は、実行者が --ack-tier を指定して再実行するまでブロックされます（SHEPHERD の gate-before-materialize）。（1）frame-lint。（2）作業ツリーがクリーンか確認。（3）現在のツリー内で loop-runner を実行し、revise はすでに fdk/tools/br-revise.py を参照しています（skills/br/assets/revise-prompt.md をレンダリング → ツールを制限した claude -p）。（4）フレームが成功したら現在のブランチにコミットし、メッセージに frame_id を付加します（revert／blame の基点）。（5）1行の要約を出力。（6）フレームに run_log_ref を記録。（7）TRACE ログ .checkpoints.jsonl にチェックポイントを記録します（checkpoint-trace／SHEPHERD — 既存のコミットを指すレコードで、二重コミットはしません）。パイプライン全体を確認するには、python3 fdk/tools/checkpoint.py list を実行します。任意のフレーム名を指定してパイプライン全体をロールバックするには、checkpoint.py rollback <frame_id> を実行します（履歴を保持し、指定した時点以降に発生した不可逆な tier の副作用について警告します）。

インプレースがデフォルトである理由（ユーザーからのフィードバック、05/07）： N 個のフレームに対して N 個の worktree を作ると、誰も見ないフォルダーが N 個できてしまいます。通常のユーザーは「アプリを起動して確認」するため、修正は実行中のアプリが使うツリーにすぐ反映される必要があります。スコープ外の変更を防ぐのは HARNESS（各ループでの diff-jail による revert ＋ FINAL SCOPE SWEEP ＋ test-hash ＋ scope_clean ＋ R6 exclusive-scope）であり、フォルダーの分離ではありません。結果に納得できない場合は、git revert <commit frame> を実行します。

手動で行う場合の同等の手順（手作業で微調整が必要な場合）：

1. frame-lint check で対象フレームが成功していることを確認します。作業ツリーがクリーンであること（git status --porcelain が空であること）を確認します。変更がある場合は拒否されます。
2. フレームの baseline_ref から専用の git worktree を作成します（ファイルシステムの jail — 最初のフレームでは harness／hook／CI に触れません）。
3. ループを実行します。フレームごとに WORKTREE BRANCH にコミットします（main ではありません）。マージは引き続き人が手動で行います：

   python3 harness/scripts/loop-runner.py run \
     --verify "<acceptance_test>" --revise "<adapter claude -p>" \
     --state "<scope_code>" --scope "<scope_code>" --protect "<scope_test>" \
     --baseline "<baseline_ref>" --commit-on-success \
     --commit-message "frame(<frame_id>): <muc_tieu> [<clause_ids>]" \
     --max-iter <g> --budget-seconds <g> --no-progress-k <g> --escalate-after <g> \
     --log br/frames/<id>.run.json --cwd <worktree>
   

   revise アダプターは、ツールを制限した claude -p です（--allowedTools Edit,Write,Read,Grep,Glob — 自由な Bash は不可、ネットワークも不可）。プロンプトは muc_tieu ＋ scope_code ＋ 直近の verify 失敗時の出力から生成されます。 フレームからコードへの追跡（前提条件 — どのフレームがどのコードを生成したかを確実に特定し、スコープ外の変更を防ぐため）：
   • Run-log には changed_files として、フレームが実際に変更したファイルを記録します（予定されていたスコープとは異なる場合があります）。すべてのファイルが scope_code に含まれる場合は scope_clean=true となります。attempted_out_of_scope には、フレームがスコープ外で書き込もうとしたものの、revert されたファイルを記録します。
   • FINAL SCOPE SWEEP：PROTECT_VIOLATION を含め、ループが停止するたびに、loop-runner は scope_code 外のすべてのファイルを元に戻します。そのため worktree は常にスコープ内に収まり、changed_files は常に scope_code の部分集合になります。これはプロンプトの指示だけに頼らない、完全な制御です。
   • --commit-on-success は、verdict=SUCCESS かつ scope_clean の場合にのみコミットします。メッセージには frame_id が付加され、git blame で該当フレームを正確に追跡できます。差分の計算に使う --baseline は、開始時点の worktree の元のコミットです（通常は HEAD）。

プロンプトとキュー（複数のフレームを実行し、再開できます）

• 📒 PROMPT 総台帳（最優先の情報源 #1。ユーザーが手動で編集でき、モデルは不要）：br/prompts.md — ファイルは1つで、各フレームに ## <frame_id> の項目があります。ファイルを開いてフレームを探し、自由に内容を編集・追加してください（placeholder {{...}} はそのままにしておくと、実行時に機械が入力します）。python3 fdk/tools/br-prompts.py sync は新しいフレームの項目を自動で追加し、手動編集済みの項目を決して上書きしません（各 /br slice の後に実行してください）。list／get <frame_id> で確認できます。実行時の優先順位：プロンプト台帳 > キュー内のプロンプト > prompt_file > デフォルトテンプレート。
• ベーステンプレート（台帳のシード）：skills/br/assets/revise-prompt.md。アダプター fdk/tools/br-revise.py は優先されるソースをレンダリングし、claude -p を呼び出します（使用可能なツールを制限）。送信されるプロンプトを確認するには、br-revise.py run --frame <f> --verify "<cmd>" --print を実行します。
• QUEUE ファイル（br/queue.yaml、サンプル skills/br/assets/queue.example.yaml）：順番に実行するフレームの一覧です。各項目には prompt_file:（テンプレートファイルを指定）または prompt:（テキストを直接記述。placeholder も引き続き使用可能）のどちらかを指定します。ドライバー fdk/tools/br-queue.py run --queue br/queue.yaml は各項目を実行し、項目ごとに status を書き戻します → キューを再実行すると done をスキップして続きから実行します（再開）。--dry-run で各項目に使われるプロンプトを確認でき、list で状態を確認できます。
• claude -p アダプターは verified:false（BNAL）の境界です。テンプレート・キュー・レンダリングはすべて決定論的で、セルフテストもあります（br-revise.py selftest、br-queue.py selftest）。

4. KILL 条件を先に記述します（via negativa）。例：diff-jail が2回以上発動／test-hash が1回発動したら、実行全体を破棄し、救済もブレーキ解除もしません。
5. ループが停止したら、1行の要約（判定・ループ回数・diffstat・最後の verify コマンド）を出力し、python3 fdk/tools/medic.py --ci を実行します。STOP — worktree の diff を読んだ人が、マージ・続行・破棄を自分で判断します。
6. run_log_ref と outcome をフレームとレジストリに記入します。発生しなかったことも含め、教訓を記録します（どのブレーキも発動しなかった場合も記録）。

Mode 4b — /br find <file-hoặc-từ-khoá> — エラー箇所を指定して、担当フレーム／プロンプトを特定

一般的な利用フロー：アプリを起動 → エラーを見つける → 該当箇所を指定：

python3 fdk/tools/br-find.py "src/auth/login.py"     # theo file
python3 fdk/tools/br-find.py "đăng nhập"              # theo từ khoá / clause

出力：担当フレーム（実際に変更されたファイル > scope_code > キーワードの順で照合）・BR 条項・プロンプトの場所（queue.yaml 内に直接記述／prompt_file／デフォルトテンプレート）・プロンプトを修正した後にそのフレームだけを再実行する正確なコマンド。R6 exclusive-scope（frame-lint）により、各ファイルは常に1つのフレームだけに属するため動作します。ファイルの所有権が lease によって移った場合、担当フレームは最後に借り受けた側（_manifest.json）です。履歴は git blame で frame(<id>) コミットを確認します。

Mode 4c — /br qc [frame] — モックアップ／フレームに対するシニア QC 監査（LLM による4項目）

モックアップ／フレームが完成して緑になったら、シニアによる目視チェックを実行します（コストが高い LLM を手動で呼び出します。低コストで決定論的なチェックは各 /br run の後に自動実行済みです）。

• Code： /qc-code を呼び出します（Skill tool → qc-code）。フレームの diff を確認し、security／performance／naming／logic の4項目を監査して、再現テスト qc-* を生成します。
• UI/UX： /qc-uiux を呼び出します（Skill tool → qc-uiux）。モックアップを監査し、a11y／hierarchy／consistency／antipattern の4項目を確認します。測定可能な項目（contrast／tap-target／overlap／misalign／missing-label）は headless visual-qa エンジンで実行します。

  node skills/visual-qa/assets/route-shots.mjs <base-url-mockup> --audit
  

• 判定が修正必要の場合は、フレームを確定する前に修正します。参考情報 — LLM の判定は意見であり、エンジンの測定値と qc-* テストが強制的なチェックです（/br run と verify-before-commit のステップ3bですでに自動実行済み）。フレームの指定がない場合は、既存のモックアップルートを監査します。

Mode 5 — /br status

1. python3 fdk/tools/build-line-status.py build --root . → br/line-status.json + llmwiki/html/line-status.html。
2. 3行の要約を出力します（全体の状態・特に注目すべきフレーム・HTML のパス）。ページではエラー→フレーム→条項をさかのぼって確認できます。assumed とされた条項はオレンジ色で表示されます。エラーが assumed に該当する場合は、次のサイクルで /br interview に戻ります。

モード 6 — /br sync（frame ↔ GitHub のサブイシュー）

automazeio/ccpmを参考にします。各 frame を1つの GitHub サブイシューにし、チームが進捗と引き継ぎを確認できるようにします。来歴（clause_id/manifest）の再実装はしません（ccpm よりすでに詳細なため）。gh 上に薄い同期レイヤーを追加するだけです。

1. python3 fdk/tools/br-sync.py sync br/frames --root . --repo <owner/repo> --dry-run — 必ず先に dry-run を実行します（gh の呼び出しも、マッピングの書き込みも行いません）。
2. 問題がないことを確認したら --dry-run を外します → 未マッピングの frame にサブイシューを作成し、br/frames/issue-mapping.json に記録します。冪等です。--epic で epic-issue を作成できます。status/selftestも利用できます。
3. Issue の作成はリポジトリ外部への操作です → --dry-run を外す前に確認してください。

モード 7 — /br contract（実装を確定する UI Contract、md+html）

CODE（frame）軸と DISPLAY（screen/route）軸を分離します。すべてのプロジェクトで次の形式に統一します。

1. Frame に ui_role: none|screen|panel|widget|form|action + ui_screen（frame-template）+「## UI の動作」のセクションを宣言します。
2. br/ui-layout.yaml：nav_style + screens[]（id·title·実際の route·frames[]）。このファイルを編集して画面をまとめても、frame には触れません。
3. python3 fdk/tools/br-contract.py build br/frames --layout br/ui-layout.yaml --root . → br/UI-CONTRACT.md + .html。frame·役割·ui_role·画面·route·clause·acceptance の表 + frame/画面/route の件数 + 不整合の警告が生成されます。selftestも利用できます。

分岐

ID	種別	条件	動作	スキップ／失敗	再合流
B01	user_optional	interview で --proactive（/br autoの短縮形）	br-fill.py fill が機械入力候補（verified: false）+ Impact × Uncertainty に基づく実際の質問を最大5つ提案します。carve-out は機械入力の値を受け付けません	上限超過 → lens-fill	W03
B02	user_optional	--lens-fill または「専門家に不確かな項目を埋めてもらう」	council.py roster --case product --json を実行し、ユーザーが不確かと指定した不足フィールドを入力して、filled_by: lens:<名前> + verified: false の印を付けます	実際の回答と混ぜません	W04
B03	conditional_required	UI のある製品（S7.5）	NFR clause から br/DESIGN.md を参照します。design-template.md を br/DESIGN.md にコピーし、§1/§2/§4/§6/§7 を記入します	UI がない場合 → スキップ	W05
B04	conditional_required	frame の ui_role が none 以外	コード作成前に /design-twice を実行します。acceptance_test は visual-qa route-shots.mjs --assert です	## Design（design-twice） セクションがない場合 → frame は未完了	W08
B05	conditional_required	frame が tier: compensable または irreversible を宣言	--ack-tier を付けて再実行するまでブロックします	ack なし → 実行しません	W08
B06	capability_optional	実際にディレクトリを分離する必要がある場合（まれ）	--worktree を追加するか、baseline_ref から独立した worktree を作るなど、同等の手順を手動で実行します	—	W08
B07	user_optional	複数の frame を実行する／1つの frame を修正する	トポロジカル順に br-queue.py run --queue br/queue.yaml を実行します。affected <frame_id> --reset で該当する分岐のみを再実行します	赤い frame は下位の分岐をブロックします	W09
B08	user_optional	/br find <ファイルまたはキーワード>	モード 4b：br-find.py が担当 frame + clause + prompt の箇所 + 再実行コマンドを出力します	—	W08（prompt を修正して再実行）
B09	user_optional	/br qc [frame]	モード 4c：/qc-code + /qc-uiux（参考）。判定が「要修正」の場合 → frame を確定する前に修正します	—	W08
B10	user_optional	/br sync	モード 6：まず br-sync.py sync --dry-run を実行し、確認後に --dry-run を外します	確認しない場合 → dry-run の段階で停止	終了
B11	user_optional	/br contract	モード 7：br-contract.py build → br/UI-CONTRACT.md + .html	—	終了
B12	user_optional	/br rail off または skip	frame-lint … --soft-off を使ってソフトゲート（R7 content · visual-qa UI · assumption-gate）を無効にします。ハードブレーキは維持されます	skip は1回後に自動で再有効化されます	W08

検証と停止

必須：frame-lint.py check（7つのルール）、br-fill.py check-contract、loop-runner の6つのブレーキ＋FINAL SCOPE SWEEP、各ループ後の medic.py --ci、各ツールのセルフテスト（frame-lint.py selftest、loop-runner.py selftest、build-line-status.py selftest、br-revise.py selftest、br-queue.py selftest）。レビューが必要です（人が最終ゲートです）：回答を承認し、slice の各スライスを承認し、frame の diff を読んだうえで、マージ／続行／破棄を自分で判断します。記録された STOP 地点で停止モードに入り、ループはブレーキに従って停止します。ブレーキを引き上げてはいけません。

例

• 成功例： ユーザーが要件を含む3つのファイルを llmwiki/raw/ に置き、「BRを作成」と伝える → interview が br/interview/001-questions.html を生成し、不足している7つのフィールドを質問 → ユーザーが回答 → compile により br/BR.md が生成され、check-contract が成功 → slice が4つのスライスを提案し、ユーザーが承認 → frame-lint.py check br/frames --root . が成功 → br-run.py run br/frames/frame-001-dang-nhap.md --root . → SUCCESS、frame(frame-001-dang-nhap): … をコミットし、1行の要約＋medic。
• 境界／失敗例： git status --porcelain が空でない状態で /br run → 実行を拒否します。メール送信を行う frame が tier: irreversible を宣言 → --ack-tier が指定されるまで TIER-GATE がブロックします。Frame-003 が失敗 → Frame-004（depends_on: [frame-003]）は status: blocked になり、関係のない Frame-005 は引き続き実行されます。

参考 — 統一された Stream UI ＋明確な Spec（distill hallmark ＋ orca-workflow）

複数の frame にまたがるパイプラインの2つの弱点を、2つの distill メカニズムで補います。

A. FRAME 間で統一された UI/UX（distill hallmark）。 各 frame は loop-runner を通じて独立して実行されるため、frame ごとに見た目が異なり、モックアップがつぎはぎになりやすくなります。hallmark の仕組み：br/DESIGN.md = ロックされたトークンシステムであり、最初に読み込んですべての選択に優先させます。逆転のルール — frame は多様化するのではなく、同じもの（共通のシステム）でなければなりません。locked-token — すべての色／フォント／間隔は名前付きトークン（var(--…)）を参照し、インラインは禁止です。これを /br に適用します。

• /br compile は design-template.md を br/DESIGN.md にコピーし、§4 と §4.1 のトークン表（ロックされたトークン）を真実のソースとします。
• ## UI hoạt động ra sao の frame UI では DESIGN.md のトークンのみを使用します。新しい値を追加する場合は、DESIGN.md にトークンを追加して参照してください。frame 内で独自に作ってはいけません。
• トークンのずれは /qc-uiux（一貫性チェック）＋ engine visual-qa によって検出されます。これにより「stream」は注意書きではなく、決定的なゲートで実行されます。その結果、frame-01 と frame-09 は同じ製品のように見えます。

B. すべての frame ＋ interview 画面に明確な SPEC が必要（/orca-workflow を参考）。 Propose は永続的な ID の FR/SC と acceptance を生成します。/br では、その厳密さをすべての工程に適用します。

• Frame： frame-template に ## Spec (FR/SC) セクションを設けます（frame-lint R7 が厳格にチェック）。各 frame は FR-id（システムが必ず…）＋ SC-id（人が測定）を宣言し、acceptance_test は SC の証拠となります。各受け入れ条件の行は FR にたどれる必要があります。明確な FR/SC がない frame は未完了です。interview にフィールドが不足している場合と同じです。
• Interview： 質問する各フィールド S1–S10 は、明確な SPEC でなければなりません。質問にはフィールドの目的と「どのような回答なら十分か」という基準を明記します（曖昧な質問はしません）。missing/assumed のままのフィールドは SPEC が不十分であり、見落とされないよう「引き継がれている仮定」の表に表示します。

参考 — UI frame の DESIGN サイクル（skill /design-twice）— コードを書く前に実行

ui_role≠none のすべての frame で必須です。UI コードを1行でも書く前に /design-twice を実行して、根本から異なる2～3案を作成し、比較して1案を選び、その後 frame 自体に ## Thiết kế (design-twice) セクション（3案＋選んだ案＋理由＋不採用案から取り入れた要素）を記録します。

• 理由： 最初のアイデアは最も思いつきやすいものであり、最良のアイデアとは限りません。比較する案がなければ、agent は唯一の案を継ぎはぎで修正するしかなく、修正のたびに新しい問題が生まれます（Lume theme：5回の修正）。
• 設計サイクルに戻るべき兆候： 同じ箇所を2回目に修正している場合、またはユーザーが具体的な問題を指摘せずに「見た目が悪い／ダサい／気に入らない」と言う場合 ⇒ 形そのものが間違っています。さらに修正しても時間の無駄です。
• ## Thiết kế (design-twice) セクションがない UI frame は未完了です（R7 では内容不足として扱われます）。
• 設計が完了してから ## UI hoạt động ra sao → コード → 下記の /visual-qa ゲートへ進みます。

Reference — UI フレーム向け視覚セルフチェックのループ（skill /visual-qa）

原則（個別の再チェック規則ではありません）： UI を修正する場合は、そのフレームの仕様とコードを編集してから /br run を再実行します。「フレームを再実行するだけで UI を自動的に再検証」するには、UI フレームの acceptance_test 自体を visual-qa にする必要があります。テスト対象は UI であり、別途実行するユニットテストではありません。ここが大きなレバレッジポイントです。エージェントに「忘れずに再確認して」と念を押す必要はありません。フレーム自体の検証ループに UI チェックも含まれるためです。

• ui_role≠none のフレームには、次を設定します：acceptance_test: "node skills/visual-qa/assets/route-shots.mjs --base <url> --route <route> --assert --user <u> --pass <p> --out <dir>" → route が 200 でない、または空の場合は exit 1 → UI が正しくレンダリングされるまでフレームは RED になります。修正のたびに /br run を再実行すれば、自動的に再検証されます。
• green の後、エージェントは画像を読み込み（skill /visual-qa）、FINDINGS.md（route・深刻度・修正方法）を作成します。各 finding をフレームの仕様とコードの修正として反映し、/br run を再実行します。ユニットテストでは見つからないテーマ・ブランド・空状態の問題を検出します。MCP 拡張機能で localhost のエラーが発生した場合にも使用します。
• /br run の外で UI を手作業で修正することは禁止です（p28 05/07 の負債）：手作業での修正はゲートを失わせ、再検証も行われません。UI の修正はすべてフレームを通してください。

Reference — Rail — パイプラインのハーネス切り替え（/br rail on|off|skip）

「On the rails」は、監視下にある状態を意味します。デフォルトは ON — /br を使用すると、セッション中は自動的に ON になります。

• python3 fdk/tools/br-rail.py status --root . → 状態を表示し、いつでも切り替え可能であることを必ず案内します。
• on（完全な監視） · off（再度有効にするまでソフトゲートを無効化） · skip（ソフトゲートをちょうど 1 回だけスキップし、その後は自動的に再有効化して警告）。
• 安全性（不変）： off/skip で無効化されるのはソフトゲートのみです — R7 content · visual-qa UI · assumption-gate。ハードブレーキ（diff-jail · test-hash · scope-clean）+ R1–R6 の構造 + セキュリティフックは、ここから無効化されることはありません。
• 配線： /br run の開始時に br-rail.py consume を読み込み、off/skip の場合は frame-lint … --soft-off を呼び出します（R7+assumption をスキップ）。loop-runner のハードブレーキはそのまま維持されます。実行のたびに Rail の状態と注意喚起の行を表示します。

Reference — 言葉より証拠（UI チェック規則 — feedback 2026-07-13）

UI／視覚チェックが有効となるのは、実際の画像ファイル + route→画像→bytes を列挙した MANIFEST.json がある場合のみです（skill /visual-qa）。ファイルがなければ、未実施として fail となり、モデルが何を述べても変わりません。UI を修正した後は、再撮影してからもう一度読み込み、green にする必要があります。推論で「合格」にすることは禁止です。（これは /fdk の規則でもあります。）