ADR-014: 選用 BR 業務需求與規格追溯
ADR 編號: 014 狀態: 已採納 (Accepted) 提案日期: 2026-09-14 決策日期: 2026-09-14 最後修訂: 2026-09-14 決策者: 團隊 P4 第二輪 peer review 確認 範圍: 選用 BR、需求來源、規格涵蓋、方法論 consumers
發布前的目錄分層修訂另見 ADR-015，已於第 2 輪審閱通過。本篇保留 ADR-014 原採納契約與驗證歷史。
部分取代：本篇多處所述「保持 UAT schema 5 完整檔案指紋」為當時的 UAT 契約。UAT 來源指紋其後由 ADR-016 改為 schema 6 來源分層（BR 原文以
uat-extra宣告、bytes 摘要宣告段落）；schema 5 指南仍以雙讀方式支援。BR 語意 projection 與 UAT 摘要互不替代的原則不變。
摘要
加入選用 BR 業務需求層，保留概略需求與來源，追溯內部規格如何回應。沒有 BR 的專案照常運作，有 BR 的專案也允許沒有 BR 來源的內部需求。本決策已於 P4 第二輪成果審閱通過；框架工作樹已完成實作，commit／fleet publish 另依明示授權執行。
規劃審閱結論
2026-09-14 第三輪 peer review 通過 P1 設計方向：BR 選用、不提高既有規格門檻，採 depends_on + 涵蓋說明 + 獨立 BR sidecar，並認可下列 D1–D4 方向。前兩輪共 17 項意見均已處置，第三輪無新增或未處置意見、無 blocking／major。
P1 當時只解鎖 P2 契約定稿，不解鎖 commit／publish。當時 ADR 維持 Proposed；P2 定案 schema、sidecar 路徑與共用 helper 邊界，P3 完成實作，P4 成果審閱通過後才改 Accepted。後續多階段工作記於共享 backlog FU-96；本節保存規劃通過的範圍與限制，不代表正式方法論已生效。
P1 預檢已完成文件站 build:docs-only、lint:llms-txt（MISSING 0／STALE 0）及差異檢查；下列 20 項的 P3 機械測試與方法論走查結果見「P3 實作與驗證」，P4 第二輪已通過，結論見下節。
P2 契約定稿產物
P2 已將 D1–D4 的具體契約寫入 .claude/rules/m-business-requirements.md（schema 1），
可複製模板收在 規格撰寫指南（docs-methodology/specs/README.md）。
以下保留 P1 的方案與理由；P2 的欄位、序列化與狀態判定以核心規則為準，P3 工具須依其實作。
| 決策 | P2 定稿 |
|---|---|
| D1 | BR-{NNN}.md + kind／id／br_schema；自然語言正文、來源與確認分離；專用路徑避免與 Business Rule 編號混淆 |
| D2 | br-semantic-v1：五個語意區段與來源 identity／revision 等欄位確定性序列化；SHA-256；US 同目錄 .br-sources.json，核對不改 US |
| D3 | draft 預設，reference 排除；finalize 為團隊定案、confirm 為業務確認，事件綁語意 digest；assess 選用 |
| D4 | 每 BR .br-coverage.json 保存整體涵蓋確認，綁 BR、直接 US 集合及補充規格 bytes；核對、涵蓋、交付分開 |
只共用 UAT 的 bytes SHA-256 helper，預定抽到既有 uat/scripts/fingerprint_common.py； 不抽其 path／manifest／serializer，保持 UAT schema 5 完整檔案指紋與例外行為。 來源定位補記屬 metadata，但來源 identity／revision 變更及待澄清問題變更均需重核； 「語意」是固定 projection，不宣稱能判斷同義文字。
P2 只完成可實作契約與模板，並未完成 parser、sidecar writer 或 consumer 整合。 P2 時 ADR 保持 Proposed，P3 按下列驗證計畫留證後進 P4；P1 的通過不替代 P4 成果審閱。
P2 預檢：BR 模板 YAML／sidecar JSON 欄位及核心規則 paths 解析通過，文件站建置與 llms 索引檢查通過；Codex 相容層 12 個 AGENTS／58 個 skill adapters 驗證通過。這些是文件與投影檢查，不是尚未實作的 BR 行為測試。
背景與已確認原則
目前方法論以 Roadmap、Feature List、Epic、US、SBE 展開開發需求，缺少對研究、訪談／會議記錄、工作說明書（SOW）與報價項目的共同追溯入口。這些來源常概略、不完整，卻可能包含必須回應的要求或已約定的交付範圍。
使用者已確認
- 採用 BR（Business Requirement，業務需求），編號形式為 BR-001。
- BR 可描述目標、問題、功能期待、使用情境、規則或交付要求；允許概略、模糊與不完整，不強制改寫為功能清單或 Use Case。
- BR 保留來源與原意；開發需求規格負責澄清、拆解與展開，必須能追溯如何回應 BR。
- BR 是選用能力，不是既有需求規劃與實作流程的必要前置。
- 此次方法論擴充須經 peer review。
建議的邊界
- 原始材料 → BR → 開發規格是可選的來源路徑；既有 Roadmap → Epic → US → SBE 主幹照常運作，Feature List 保持功能總覽角色。
- 沒有 BR 的專案不建立空文件、不要求補編號、不產生缺 BR 警告、不增加 Sprint／impl／progress 閘門。
- 有 BR 也允許內部發起的 US 不引用 BR；未引用本身不算缺陷。檢查方向以「每項 BR 是否被處置」為主。
- 存在明示 BR 引用卻找不到目標時，仍應報斷鏈；不能用「BR 選用」掩蓋失效引用。
- BR 存在或被引用，不代表已確認、已承諾、已納入本期交付或已滿足。
- 本次規劃不建立真實客戶 BR，不從參考實作需求反向杜撰來源。
預計實作範圍
以下為預計變更面，實作階段需完整讀取每支 consumer 與較近的 AGENTS.md，逐檔確認必要性。
| 層面 | 預計檔案／位置 | 變更目的 |
|---|---|---|
| 核心契約 | 新增 .claude/rules/m-business-requirements.md | BR 定義、選用行為、編號、來源、涵蓋語意與單一事實來源 |
| BR 作者工具 | 新增 .claude/skills/br/SKILL.md 與必要 assets | 從素材整理、建立、修訂、即時列出 BR；首次登錄導覽；不替人確認承諾 |
| 規劃入口 | .claude/skills/{roadmap,feature-list,epic,us}/SKILL.md | 依本次範圍讀 BR、保留未決事項、建立直接引用與涵蓋說明 |
| 依賴及變更 | .claude/rules/{m-depends-on,m-change-management}.md、.claude/skills/impact/SKILL.md | BR 變更的直接／間接影響；辨識內容變更後需重審的涵蓋結論 |
| 上游同步 | .claude/skills/{impl,us,analyze}/SKILL.md 與共用解析 assets | BR 語意指紋及核對基線；排除純 metadata 更新的提問，納入未提交的語意變更 |
| BR 導覽 | {docsRoot}/sidebars.ts 與 category 設定 | 首次實際 BR 才建立 generated-index；不新增衍生 README，保留既有人工內容 |
| 一致性分析 | .claude/skills/analyze/SKILL.md | BR 盤點、斷鏈與重號、規劃關聯、US 涵蓋、缺口及證據區分 |
| 相容性契約 | .claude/rules/{m-doc-version,m-features-link,m-dev-guardrails}.md 與相關 consumers | 盤點是否需補充 BR 選用／版本語意；不將 BR 新增為必要輸入 |
| 索引與說明 | .claude/rules/{m-methodology,m-skill-execution,m-persona-suggest}.md；appfuse-docs/docs-methodology/ 相關指南與 ADR | 登錄新規則／skill、選用流程與 Persona 建議；本 ADR 於 P4 成果審閱通過後改為 Accepted |
| 衍生相容層 | .agents/、AGENTS.md | 由 migrate-agent-config 生成並驗證，不能手改 wrapper 當作完成 |
| 發布與 scaffold | methodology／scaffold 現有機制 | 驗證發布只帶方法論與模板，不能把來源客戶材料或真實 BR 當框架預設內容 |
sbe、assess、checklist、impl、progress、sprint、next、api-spec 及其 native scripts 列入 consumer audit：只修改確有衝突或需要辨識新欄位的地方，避免將 BR 複製到整條鏈或增設流程門檻。既有研究與逐字稿位置沿用，不強制搬移原始檔案。
提案內容
1. BR 最小格式與來源
建議每個 BR 一份 Markdown，放在 {docsRoot}/docs/specs/business-requirements/BR-{NNN}.md；穩定檔名不含可變標題。導覽採 Docusaurus category generated-index，不維護另一份 BR 索引 Markdown；/br list 即時掃描文件產生列表，/analyze 唯讀產生涵蓋報告。純 ID 檔名刻意避免概略需求澄清、更名時造成來源連結反覆搬移；可讀標題放在 H1／sidebar_label。代價是檔案清單較不易辨讀，由上述導覽補足。
| 內容 | 要求 | 說明 |
|---|---|---|
| ID | 必填 | 在同一 docsRoot 需求庫唯一，至少三位數、可擴展，不回收編號 |
| 標題與需求陳述 | 必填 | 保留業務語言，不要求驗收標準或完整流程 |
| 來源 | 必填記錄 | 文件／會議／對話識別及定位；來源待補時明記待補，仍可保存草稿 |
| 確認狀態 | 必填、預設待確認 | 與文件成熟度、交付進度及是否承諾分開 |
| 澄清與未決事項 | 選填 | 清楚區別來源原意、團隊解讀與尚待確認的推論 |
| 承諾依據 | 選填 | 指向來源版本及條款／項目；沒有依據不能自動推定已承諾 |
| 範圍處置與變更紀錄 | 按需 | 延後／排除／撤回／拆分／合併須保存理由與確認依據 |
來源可有多筆，記錄檔案或連結、版次／日期、頁碼／段落／時間戳／項目號；無法讀取時報「未核實來源」，不杜撰原文。只有明確授權修改來源時才動原始材料，BR 澄清不回寫成原始紀錄。
建議接受 reference／draft／published，新 BR 預設 draft。reference 只表示示例，不計入專案涵蓋；published 只表示團隊已整理定案，不表示業務確認或交付承諾，也不是 US 實作前置。
/assess對 BR 檢查原意忠實度、來源與未決標記，不要求 US 級驗收規格；定案可標 published，但不更新業務確認、不連動 SBE、不觸發 Feature sync。- BR 的
/assess為選用。m-persona-suggest對 BR 只建議review_scope含 BR 的既有 Persona，不假定必有客戶／業務 Persona，也不自動建立。沒有匹配者時建議由需求提出者或指定人員確認；不阻擋 BR 保存或團隊明示定案。建議由/br提供人工定案入口，記錄操作者、日期及定案依據後標 published；缺 Persona 不等於自動 published，亦不宣稱已通過 assess。既有/assess必須有 Persona 的前置條件保持不變，US 的 published 流程亦不因此放寬。P2 定義入口與紀錄格式，P3 同步 br／assess／m-persona-suggest／m-doc-version。 - scaffold 不複製來源專案的真實 BR／客戶材料；只能明示選取已去識別的示例，並標 reference。空專案不產生 BR 目錄或空 category。
/prune-reference不因 BR 為 reference 就自動刪除；明確列入所選參考域且無保留文件引用時才列入待確認刪除集，否則保留並報告。draft／published BR 永不由 prune 刪除。- P3 必須同步
m-doc-version、m-depends-on的適用範圍與 consumer 表，並更新 assess、scaffold、prune-reference 的明示分支；不能只靠路徑自動套用舊行為。
2. 追溯與涵蓋分工
建議先沿用 depends_on 的 docs 相對路徑宣告直接 BR 依賴，不立即新增另一個只存 BR ID 的重複欄位。內部文件增加選用「BR 涵蓋說明」區段，描述 BR、所回應的部分、對應規格段落及缺口；報告由上述來源推導。
depends_on是依賴邊的單一事實來源；涵蓋說明只記語意與規格依據，不另維護下游名單或全局完成狀態。analyze檢查區段引用與依賴宣告一致。- Epic 引用 BR 可證明已規劃；不能因 Epic 下有多個 US 就推定全部 US 均涵蓋該 BR。
- US 實際回應 BR 時直接宣告該依賴與涵蓋說明，支援一對多及多對多；SBE 透過 US 追溯，只有直接依據 BR 時才另加直接依賴。
- 現有 Roadmap／Feature List 有 frontmatter，Roadmap 亦在 m-doc-version／m-depends-on 適用範圍。其 skill 範本仍存在「不加 frontmatter」的不同描述，屬 BR 導入前已存在的漂移；明確併入 P3 的兩支 skill 範本修正，不另開重複 follow-up。修正只對齊既有 sidebar_position／version 與適用的依賴規則，不將 BR 變成必填；以無 BR 的產出案例獨立驗證。不能將此漂移誤稱為無法宣告依賴。
- 真正限制是粒度：Feature List 的文件級依賴不能表示單一 F-NN 與 BR 的對應。第一版不新增「來源 BR」表格欄位，規劃關聯由 Roadmap／Epic 的 depends_on 記錄；Feature List 沿既有 features → US → BR 反查，報告標示衍生關係，不推定每個 Feature 涵蓋 US 引用的全部 BR。
- 只有 Roadmap／Epic 的依賴仍只能證明已規劃，顯示「尚未建立 US 涵蓋」。既有 Feature List 若已有文件級 BR 依賴則保留，只報文件級，不能投影為逐列關係。
- 技術限制或非功能要求可引用設計／測試文件作補充證據；無適合 US 時明記專項驗證需求，不為填表而虛構 US。
曾考慮新增結構化 business_requirements 欄位，承載 ID 與涵蓋說明，再由工具推導 dependency edges。優點是容易解析；成本是所有依賴 consumers 必須同步支援，且不能再要求人手維護相同 BR 的 depends_on。P1 已選擇沿用 depends_on，不混用兩套權威來源。
2a. impact 掃描與缺漏補齊
現有 impact Step 3 雖概述「所有 Markdown」，明列範圍只有 user-stories、sbe、design/api-specs、testing/test-plans；未涵蓋 epics／roadmap。P3 必須修正概述與枚舉清單，同時加入 specs/epics/**/*.md、specs/roadmap.md、specs/feature-list.md、specs/business-requirements/**/*.md，才能測試 BR → Epic → US → SBE 的反查。
--fix-missing 保留 SBE／test-plan 的既有直接依賴建議。新增範圍只在正文已有可核實的直接 BR／規劃來源時建議補齊；沒有 BR、根節點 BR 沒有 depends_on、內部 US 無 BR 都不是缺漏，不生成空欄位。外部網址、PDF 頁碼、逐字稿時間戳屬來源定位，不硬塞進只接受 docs Markdown 的 depends_on。拆併指標與來源資訊也不自動視為依賴邊，避免循環與錯誤影響集合。
2b. impl 上游更新成本與方案比較
現有 /impl Step 2.4 用 git log -1 --format=%ct 比較上游與 US 最後提交時間（不是 filesystem mtime）；上游較新會詢問是否繼續。直接引用 BR 而原封沿用這個機制，會讓來源補記或確認狀態更新也觸發提問，且漏掉未提交的內容變更。
| 方案 | 優點 | 成本與取捨 |
|---|---|---|
| depends_on + BR 語意指紋（建議） | 沿用依賴圖；metadata 更新不觸發 impl 提問 | impl／us／analyze 須共用 BR 語意抽取及基線規格；P3 明列為必要工作 |
| 獨立 business_requirements 欄位 | 可結構化表示 BR 與涵蓋說明 | impact 等 consumers 必須建立新圖邊；仍須處理來源變更，不因避開 mtime 就解決 stale |
| 需求與 metadata 分檔 | impl 只引用需求檔，降低噪音 | 每個 BR 至少兩檔，編號／移動／來源維護成本增加；需求檔仍可能有排版更新 |
| 接受目前時間比較 | 改動最少 | 純 metadata 也攔問，且未提交變更有盲點；不建議 |
建議的指紋邊界：BR 的需求陳述、規則、已採用澄清、納入／排除／延後／撤回、承諾範圍屬語意內容；sidebar、顯示標題、來源定位補記、未改原意的確認人／日期與稽核紀錄屬 metadata。更換來源版本、改變承諾或採用新解讀必須反映語意內容，不能藉放入 metadata 規避更新。無法辨識的內容以待判讀處理，不默認 metadata。
P2 定義正規化格式與 schema；US 對應的核對紀錄保存直接 BR 語意指紋，初次撰寫／明示核對後更新，單純讀取不得更新。impl 只對 BR 依賴改用工作區內容指紋（含未提交變更），其餘上游沿現制。指紋相同直接繼續；語意改變、基線缺失或無法解析時才提示核對，不自動回退。這不是要求 BR published，而是既有明示依賴的同步檢查。涵蓋確認另綁定 BR 與相關規格的內容指紋；US 已核對來源不等於「完整涵蓋」已確認。
與既有 UAT 指紋工具的關係
已核實 .claude/skills/uat/scripts/evidence.py 的 sha256_bytes／sha256_path、current_source_manifest 及 stamp_guide／驗證流程：schema 5 記錄完整檔案 bytes 的 SHA-256、排序的來源集合、generator、stage 與 target module；--extra-input 亦雜湊完整檔案。它沒有 BR 語意抽取或文字正規化，不能宣稱直接共用即可排除 BR metadata。
建議共用 SHA-256 演算法及「重算來源集合與內容、比對已確認快照」原則；P2 盤點可抽出的純雜湊、路徑與確定性序列化 helper，P3 若抽成共用模組，須保持 UAT schema 5 的輸入 bytes、輸出與驗證結果相容，並加入回歸驗證。BR 另外定義具版本的語意 projection，以 UTF-8 確定性序列化後交給相同 SHA-256 primitive；不能複製 UAT runner 再自行演進另一份 hash 實作。
BR sidecar 採獨立 kind／schema，沿用 generator、algorithm、排序來源與明示確認的慣例，不冒充 UAT schema 5，也不要求 BR 具有 UAT stage／target module。projection 版本不符、來源集合或語意 digest 改變，均視為核對失效；不以 mtime 或人工修訂號替代內容比較。兩種 projection 各有用途，不能互相代替驗證結論。
BR 基線不自動加入 UAT --extra-input，避免核對 metadata 再次讓 UAT stale。若某 BR 原文確實是 UAT 命題的直接依據，仍依 uat-script 的來源規則納入該檔，接受其完整檔案變更會使 UAT stale；不以 BR 語意指紋削弱既有 UAT 證據契約。
核對紀錄落點與副作用
| 候選 | 對下游的影響 | 建議 |
|---|---|---|
| US frontmatter 內存 digest／核對時間 | 每次核對都改 US，更新 Git 時間，亦改變 UAT 對 US 的完整檔案 hash | 不採用，避免產生與需求無關的連鎖失效 |
| 每 US 獨立 sidecar | 單純核對只改 JSON；US 真正需求修訂仍依既有規則影響下游 | 優先方案，P2 定案路徑與 schema |
| 集中式 BR 核對登錄表 | 不直接改 US，但多人更新易衝突、需另管逐 US 項目生命週期 | 不建議作第一版 |
建議路徑為 US 同目錄的 {usFileStem}.br-sources.json，以檔名慣例探索，不新增或反覆改寫 US frontmatter 指標。sidecar 隨 Git 管理、只記基線與確認證據，不重複成為依賴圖 SoT；目前直接來源集合仍由 US 的 depends_on 推導，與 sidecar 比較可偵測增刪依賴。沒有 BR 依賴的 US 不產生 sidecar。
核對紀錄須綁 US 路徑與內容 digest，防止 US 已改卻沿用舊的確認；單純更新 sidecar 不改 US，實際改 US 則保留所有既有下游失效行為。P2 另定義 US 更名、sidecar 遺失、衝突及 reference／scaffold 排除策略。不得讓 SBE／API Spec 自動依賴核對 sidecar，也不得將其當 UAT 驗收結果。P3 驗證現有 consumers 是否會廣泛掃 JSON 或誤納副檔，不把「副檔」本身當成無副作用保證。
2c. 選用導覽
P3 納入 {docsRoot}/sidebars.ts 與 category 設定。/br 首次建立實際 BR 時才增設 category，使用 generated-index + autogenerated 子項；不產生 README 索引，也不由 analyze 寫入。無 BR 不登錄空 category。若既有 README 有人工內容則保留並沿用，不覆寫為衍生列表。scaffold 排除全部 BR 後亦須移除失效的 BR category 設定；既有專案保留已撤回 BR 作歷史，通常不形成空目錄。
3. 涵蓋報告與變更
報告分開呈現以下面向，不合併為單一完成百分比：
| 面向 | 呈現 |
|---|---|
| 規劃關聯 | BR 對應哪些 Roadmap／Feature List／Epic |
| 規格涵蓋 | 未展開、部分涵蓋、待澄清、涵蓋候選；附對應 US／規格段落與具體缺口 |
| 範圍處置 | 納入、延後、排除、撤回等依據；延後與排除不算已滿足 |
| 交付證據 | 對應 US 現有階段、測試／UAT 證據與未完成事項；無證據即明示 |
AI 的語意比較是涵蓋建議；「完整涵蓋」須經人確認，不能只靠 ID 連結數、關鍵字或 US published 判定。US 全部完成也不能取代客戶對 SOW 的驗收；需要對外確認時另記確認依據。
BR 原意或範圍變更後，重跑 impact／analyze，舊涵蓋結論標記待重新確認；若內部規格因此修訂，再依現有 change-management 決定回退。不能因 BR 任意文字更新就自動回退所有 US。保存確認時對應的 BR 與規格內容版本／指紋，是實作階段需定案的 stale 判定方式。
BR 拆分、合併或撤回保留舊 ID 與取代關係，不靜默刪除或重編。中途導入時，只補已核實的來源關係，其餘維持未連結；不要求歷史 US 全量回填。
4. 分階段工作與人審
| 階段 | 產出 | 完成條件 |
|---|---|---|
| P1 規劃送審（本輪） | 本提案、變更面、待決點與驗證案例 | 審閱者確認 BR 選用、不提高規格門檻、追溯與涵蓋分工 |
| P2 契約定稿 | ADR、核心 rule、BR 模板與引用範例 | D1–D4 收斂；schema、來源／確認狀態、單一事實來源一致 |
| P3 工具與整合 | br skill、規劃／analyze／impact consumers、索引與指南、生成的 Codex 層 | 無 BR 路徑保持相容；有 BR 路徑可完整走查 |
| P4 成果送審 | 實際差異、預檢結果、正反案例證據 | 新的 methodology 成果簡報通過；規劃通過不取代成果審閱 |
| P5 收尾與發布 | 決策持久化、經審閱的 commit、依授權執行 methodology publish | 結論已落 ADR／rules；確認發布範圍後使用既有發布機制 |
P1 規劃已通過；P2 契約與模板、P3 工具與 consumer 整合已完成於工作樹，P4 第二輪已通過並完成結論落點、關閉暫時簡報；P5 commit／publish 尚待明示授權。ADR 已改 Accepted。
已通過方向與 P2 定稿事項 D1–D4
以下方向已通過 P1 規劃審閱；具體契約仍於 P2 定稿，整份 ADR 在 P4 前維持 Proposed。
| ID | 已通過方向 | P2 定稿／P4 驗證重點 |
|---|---|---|
| D1 | 一 BR 一檔、純 ID；category generated-index，無同步 README | 命名穩定性與閱讀成本 |
| D2 | depends_on + 涵蓋說明；impact 擴掃；共用 SHA-256 primitive、獨立 BR projection／sidecar；Feature 表不加欄 | P2 定案 sidecar 路徑／schema、helper 共用與下游副作用；不改 UAT hash 語意 |
| D3 | reference／draft／published 與業務確認分離；BR assess 選用、可人工明示定案；scaffold／prune 明示路由 | 不強制建立 Persona、不隱含套用 US 流程、不複製真實 BR |
| D4 | 涵蓋建議與交付證據分開；人確認綁內容指紋 | 第一版不自動宣稱客戶已驗收；schema 於 P2 定稿 |
驗證計畫
- 完全無 BR：既有 roadmap／US／analyze／impl／progress 行為不增加必填項、警告或空產物。
- 已有 BR 但內部 US 無 BR：合法，不能列為未滿足業務要求；BR 自身未展開仍須列出。
- 明示 BR 引用但文件不存在、ID 重複或格式損壞：精準報錯；不默認為未啟用。
- 模糊 BR、多筆來源、待補來源：可保存，不生成虛構驗收條件、承諾或確認紀錄。
- 一個 BR 拆多個 US／一個 US 涵蓋多個 BR：逐項列出部分、缺口與證據，不以連結數當完整率。
- 只有 Epic 或規劃文件關聯：顯示規劃層，不能推定 US 已完整涵蓋。
- BR 延後／排除／撤回：保留理由與來源，不計已滿足；拆併後舊 ID 仍可解析。
- BR 原意變更：反查直接及間接規格、列出規劃連結限制、舊涵蓋結論待重審；不自動推進或回退階段。
- US published／E2E pass／全部 US 完成：分別列為規格或交付證據，不代替 BR 涵蓋確認及對客戶驗收。
- 中途導入、reference 文件、scaffold／publish：不強制回填歷史、不計參考樣本為真實 BR、不散佈來源客戶資料。
- UI／Headless 兩軌及 work 分支：既有 readiness、共享進度保護與 UAT evidence 要求保持有效。
- 若增加 parser／生成腳本：以小型隔離 fixtures 驗證空集、重號、斷鏈、多對多、刪改後 stale、重跑不變性；方法論語意走查與機械測試結果分開報告。
- BR metadata 已提交更新但語意不變，impl 不提問；語意變更即使未提交仍可偵測；其他上游維持現制。
- impact 可走 BR → Roadmap／Epic → US → SBE；fix-missing 不將無 BR、根節點或內部需求判成缺漏。
- 首次 BR 才出現 category；無 BR 的建置無空 category；重跑 br 不產生同步索引檔。
- reference BR 不計涵蓋、assess 不連動 SBE／features sync、prune 保留被引用示例、scaffold 不複製真實來源。
- 單純核對只改 BR sidecar，US bytes／Git 文件歷史不變；既有 UAT 基線亦不因未列入來源的 sidecar 更新失效。US 實際修訂與 UAT 明示的 BR 原文來源變更仍按原契約失效。
- 共用 helper 前後，既有 UAT schema 5 相同輸入 bytes 產生相同 SHA-256 與驗證結果；BR projection metadata 等價／語意變更、schema 不符及來源增刪分別驗證。
- 無匹配 Persona 可保存並人工明示定案 BR，不假稱 assess 通過，不自動 published；有 Persona 才建議選用 assess，US 品質門檻不變。
- 無 BR 的 roadmap／feature-list 產出符合既有 frontmatter 規則；修正既有漂移不產生 BR 必填、空欄或警告。
後果與限制
BR 維持低門檻，但追溯工具需要處理粒度、指紋與版本分流，不能視為單純加欄位。第一版 Feature List 只有衍生追溯，無直接逐列來源管理；AI 不可把衍生關係當作完整涵蓋。原始材料與確認依據仍由團隊維護。
本 ADR 保留決策與取捨；正式操作規範已落 rules／skills。P4 成果已通過，commit／publish 仍依明示授權執行。
P3 實作與驗證
2026-09-14，實作保留於工作樹，基線 47a5ba4acd462c5be6b0d00681037849b838f2b2。新 /br skill 由 br_model.py 解析 YAML／Markdown 與語意 projection，br_trace.py 共用核對／涵蓋 verifier、產生待確認計畫及原子寫入；Python 相依固定於 requirements.txt。scaffold_copy.py 僅用標準函式庫，複製前套 Git ignore 與來源排除。UAT 只抽 SHA-256 primitive，schema 5 與 manifest 不變。
Roadmap／Feature List／Epic／US、impl、analyze、impact、assess、scaffold／prune 及 uat-script 已整合；impact 完整走訪有向依賴，不在第三層截斷。規則 consumer 表、選用流程指南、索引與 Codex 薄相容層同步。未修改實際產品 US、SBE、進度或客戶資料。
機械驗證
.claude/skills/br/scripts/test_br_trace.py與test_boundaries.py共 39 項通過：嚴格格式／路徑／指紋、核對與涵蓋、原子寫入競爭、scaffold、UAT 邊界。- 原 UAT
test_evidence.py9 項通過；另載入基線 HEAD 的 evidence.py，逐項比對相同 bytes SHA-256、完整 source manifest、current 報告及來源改變後的 stale 錯誤，結果相同。 - 無 BR 的實際 docs 目錄執行 list 回空集合，沒有建立 BR 產物。Roadmap／Feature List 範本解析有
version: draft，沒有 BR 必填或空 depends_on。 - 隔離 Docusaurus fixture 走無 BR → 原生 draft + sidebar generated-index／autogenerated → filtered scaffold + 清空 category 三種建置；沒有產生 BR README，相同 draft 重跑 no-op。sidebar 編輯仍由 skill 依專案配置執行，並非 parser 自動改 TS。
- 框架文件站
build:docs-only通過；llms 索引 MISSING 0／STALE 0。Codex 相容層以 migrate-agent-config audit → sync → validate 驗證，無手改 wrapper。
重跑原生測試（{python} 為已安裝 BR requirements 的隔離 Python）：
{python} -m unittest discover -s .claude/skills/br/scripts -p 'test_*.py'
python3 -m unittest discover -s .claude/skills/uat/scripts -p test_evidence.py
python3 .agents/skills/migrate-agent-config/scripts/migrate.py validate
npm --prefix appfuse-docs run lint:llms-txt
npm --prefix appfuse-docs run build:docs-only
20 項案例對照
「走查」表示依實際 skill／rule 分支逐項檢視，不冒充獨立代理或人工審閱；fixture 中的確認者與批准皆為合成資料，不是業務確認。
| 案例 | 證據與結果 |
|---|---|
| 1–2 無 BR／內部 US | no-BR／empty-library fixtures 通過；consumer 無 BR 分支走查，不加門檻 |
| 3 斷鏈、重號、格式損壞 | broken-reference、canonical-ID、strict-YAML／JSON、unknown-section、escape／symlink 測試通過 |
| 4 概略／多來源 | multiple-sources fixture 保留「待補」；草稿 skill 不填虛構承諾的流程走查 |
| 5 多對多 | many-to-many fixture 通過；full 仍要求人檢閱 gaps／scope，非數連結 |
| 6 僅規劃 | plan-only-Epic 不可 full 測試通過；analyze 分開規劃／涵蓋 |
| 7 範圍／拆併 | excluded-full 拒絕、missing-replacement／cycle 測試；deferred 與交付分離走查 |
| 8 語意變更 | semantic-stale／new-US-coverage-stale 通過；impact 與回退分流走查 |
| 9 完成不等於驗收 | br／analyze／uat-script 狀態與證據分工走查，不改進度 |
| 10 中途導入／scaffold | reference 拒絕、source-material／sidecar 複製排除測試；methodology namespace 只同步方法論，未執行實際 publish |
| 11 UI／Headless／work | impl 原品質表與 work 共享進度保護保留；未跑真實產品 UI／API 實作與多人協作 |
| 12 parser fixtures | 39 項自動化測試含 no-op、刪改、多對多、衝突與失效 |
| 13 metadata／未提交 | metadata-current、semantic-stale 與 US-raw-stale fixtures 通過；其他上游時間分支保持 |
| 14 impact | 掃描範圍、完整走訪及 fix-missing 根節點例外走查；圖 SoT 仍是 depends_on |
| 15 導覽 | 三種隔離 Docusaurus 建置及 draft no-op 走查，無 generated README |
| 16 reference／prune／assess | scaffold 機械測試；prune 保留有入向引用的示例與團隊文件、BR assess 不 sync 的分支走查 |
| 17 只寫 sidecar | US bytes／mtime 保持、未列 sidecar 不影響 UAT、US 或明示 BR 原文改變仍 stale 測試通過 |
| 18 UAT 相容 | 基線與工作樹 hash／manifest／current／stale 全等，原 9 項及新 UAT 邊界測試通過 |
| 19 Persona 選用 | BR finalize 與 confirm 分離的原生測試；無 Persona finalize 入口及 assess 分支走查，US 門檻保留 |
| 20 舊範本漂移 | Roadmap／Feature List 範本 YAML 解析通過，未增加 BR 欄位 |
限制與 P4 審閱焦點
人類批准由 skill 工作流程取得，approvalSha256 只綁定內容快照，不是身分簽章。自然語言藏入 metadata、未列入的補充證據、來源是否充分去識別、scope 是否完整仍需人工判斷。原子 replace 前重讀可攔截已觀察到的競爭修改，不提供跨工具交易鎖。確認與來源快照不等於交付／客戶驗收。這些是本次明示邊界，並非已通過 P4 的風險接受。
P4 第一輪處置
第一輪審閱結論為需修改（4 major、13 minor、4 question），設計方向未變。作者已處置全部 21 項，第二輪無新意見並通過，ADR 改 Accepted；未 commit／publish。
- 修正確認事件表格外追加：prepare 重新解析輸出，要求完整歷史加新事件恰為解析結果，否則拒絕寫入。補 setext H1、非 BR 依賴不觸發 BR 檢查、未知 BR 訊息、損壞 frontmatter 修復邊界。
- scaffold 機械排除
docs/specs/transcripts/，先檢查 Git working tree；工具以 canonical 絕對路徑定位。去識別 reference 範例由 scaffold skill 在 filtered copy 後另建，不開複製原始 BR 的通道。 - Persona 值域、BR 表列索引、impact 明確掃描範圍及 BR-only analyze 前置分支均已補齊。修正 sidebar 模板、Skills 分類標題及入向錨點；FU-96 改以共享檔案路徑定位。
- 明記 YAML serializer 會移除註解及改寫引號風格；prepare 顯示完整差異，仍要求 projection 不變。BR runtime 缺漏先建立隔離環境，安裝／helper 失敗停止 BR 相依操作，不降級假報核對成功；無 BR 分支不受影響。
本輪 BR 回歸共 46 項通過（原 39 項加 7 項），舊 UAT 9 項通過。R1 的 39 項及三種隔離建置記錄保留為前輪證據。UAT skill 5.1.1 是同目錄 evidence.py 委派共用 helper 的修補版，不代表 schema／工作流程改變。第 1 輪簡報誤把執行中的 migration lock 納入檔數，已移除；第 2 輪範圍另包含 Persona 與標題錨點引用文件。
P4 最終審閱結論與收尾
2026-09-14，第 2 輪實作成果審閱 通過，沒有新意見。第一輪 21 項（4 major、13 minor、4 question）處置均經審閱者逐條對照工作區核實；無 open 意見、無 blocking／major。
審閱者重跑 BR 46 項、UAT 9 項、Codex 相容層 12 AGENTS／59 adapters、llms 索引、文件建置及 diff 檢查，均通過。審閱確認以下為可接受的明示邊界：自然語言藏於 metadata、未列入的補充證據、來源去識別是否充分仍需人工判斷；快照重讀與原子 replace 不提供跨工具交易鎖。YAML serializer 的格式副作用與人工修復邊界已記入核心規則及 skill。
本次通過解鎖 peer-review close 與 ADR Accepted；不自行授權 commit／publish。決策與測試證據保存於本 ADR，契約保存於 m-business-requirements.md，P5 待辦保留 FU-96。暫時簡報 20260914-br-methodology-implementation 完成落點後刪除，後續不依賴該檔續作。