跳至主要内容

ADR-023：文檔位置與特性 Registry

狀態：已接受 (Accepted)；P0–P3 設計及實作均已逐期通過審閱 接受日期：2026-10-21 提案日期：2026-10-15 審閱：20261015-docs-registry，第 3 輪通過（受審 revision r3-959a7210380ab603）；9 條 major（R1-01～R1-06、R2-01～R2-03）均 done，無 open 或 declined；close 結論落點經使用者確認 方向審閱範圍（2026-10-15 歷史）：本 ADR 的方向與 registry／audit 原型。本次不修改任何 rule 或 skill；「影響範圍」所列修訂依實作分期另行送審，現行規則在對應分期通過前維持原狀。D2、D6、D7 的功能驗證屬 P1，本結論不代表已實作 實作接受範圍：P0 registry、P1 交換與網站、P2-1～P2-6 解析／skills／證據保留、P3 共用寫入判定／Claude adapter／安裝器及接線；P3 最終受審 revision r2-38282cca1103fcfa（ada@leandev.io）。接受不代表已下行、資料欠帳已修復或 hook 已啟用。 範圍：專案 docs 模組的文件位置、文件特性、導覽呈現、git 保存與保留規則；存取文檔的確定性入口；與人類溝通文件的存放位置

問題​

文件內容由各 skill、AI 和人類決定，這不是 docs 模組能控制的，也不應該控制。 但文件放在哪、怎麼被找到、保存多久、要不要進 git、誰能寫目前沒有單一的定義：

  • 位置分散在各 skill。 方法論 skill 與 rule 中有 70 多種路徑寫法，舊路徑遷移也是各自處理（domain-model 單檔／多檔、BR 換目錄、逐字稿有四個根目錄）。skill 會隨方法論演進而修改，位置規範無法從個別 skill 控制。
  • 正文與證據混放。 給人讀的正文和給機器驗證的證據都放在 docs/ 下，Docusaurus 不渲染非 md 檔，網站看不到證據，正文樹又被證據塞滿。
  • 與人類溝通的文件散落在 docs 模組外。 審閱簡報與證據在 .claude/peer-review/，Sprint 交付紀錄在 .claude/work/，報表樣張在 workspace output/，AI 的草稿在 /tmp。人類只能靠 AI 提供的路徑或展示副本閱讀，/work 甚至沒有網站入口。
  • 暫時文件沒有收尾。 審閱結案只刪除簡報與展示副本，證據的生命週期沒有定義而持續累積。
  • 專案之間設定漂移。 gitignore、docs-host 排除清單由各專案手寫，已出現應排除卻已提交、應排除卻未排除的情況。

2026-10-15 以原型對三個專案（開發型 florae-g1、報表型 nbsos、參考實作 appfuse-webapp-v1）對照的結果見附錄 B。

決策​

D1：與人類溝通的文件一律放在 docs 模組​

skill 與 AI 產生的、需要人類閱讀或確認的文件，一律放在已定位的 docs 模組，而且必須能從網站導覽讀到，不能只提供連結。 不得放在 .claude/、.codex/、/tmp 或 workspace 其他目錄。

  • 只給 AI 讀的 context（例如 .claude/docs/module-inventory.md）不受此限。
  • 審閱簡報、Sprint 交付紀錄、報表樣張等交換文件改放 {docsRoot}/docs/exchanges/{kind}/{id}/，原件本身就在 docs 模組，不再需要「工作樹原件＋網站展示副本」的雙份結構。
  • 這條取代 m-peer-review.md「簡報不進 git、不進 docs/」與 m-skill-execution.md 展示副本的相關規定。完整清單見影響範圍。

D2：git 是唯一的共享儲存，保留規則依用途決定​

  • 不另設外部儲存或 LFS，團隊透過 git 共享全部文件。
    • 修訂（2026-10-20，P2-6 設計通過）：Git 為一般團隊文件的預設共享儲存；已有來源契約明示不能提交的原件／證據包，保留 ADR-020 的原定 controlledRoot／evidence-location 窄例外。Git 保存來源版次、路徑基準、相對檔案清單、完整 SHA-256、取回說明及確認附件，不存憑證，也不自動搬移／下載原件或引入 LFS。本站仍須提供本輪完整固定副本與對照，不新增讀者／存取控制／部署批准關卡或第二網站；不可取得的來源明示 unavailable，不把 ignored 預覽當唯一原件。見證據保留 §6、§11。
  • 暫時文件也提交：審閱期間提交，結案時把結論落到持久位置，再從目前版本移除，歷史保留。
    • 修訂（2026-10-16，P1 實作審閱中使用者決定）：/peer-review 的審閱報告不提交。審閱簡報、證據與發布／確認紀錄放在 docs 模組交換目錄但 gitignored，只在共享工作樹與審閱預覽中，結案刪除；持久的只有結論落點。下方「審閱提交契約」的提交範圍與 stage 守衛因此不適用於審閱交換，審閱基線固定、基線後提交分類與推送祖先守衛照常。交付交換（/work）與其他暫時文件不受影響。
  • 控制 repo 增長的方法是進 git 前依用途篩選（retention），而不是事後刪除。從目前版本刪檔只會讓工作目錄與網站變乾淨，不會縮小 repo。
    • P2-6 保留判定：retention 是提交範圍的參考，完整歷史 UAT 快照與 report run 引用仍保留。blocked／未知舊資料或 index 分歧時，按原生契約及原授權精確保存／交付本次有效帳本、引用 run 與必要快照，揭露 RT 問題；不新增 commit／進度／交付閘門，不豁免原 verifier／人工接受／work 閘門，不自動刪除或 stage。工具實作已通過 P2-6 審閱；細節見證據保留 §8、§12。
  • 不改寫歷史（filter-repo），以免需要 force-push 和全員重新 clone。是否一次性清理歷史，由人另行決定。
  • 成員可以用 git clone --filter=blob:none 降低 clone 量，不影響共享。

審閱提交契約（暫時交換文件提交後，「通過才解鎖成果」的閘門仍須成立）：

  • 提交範圍：審閱提交只能包含該次交換的目錄（例如 {docsRoot}/docs/exchanges/reviews/{briefId}/），逐檔以精確路徑 stage；提交前 git diff --cached --name-only 必須全部落在該目錄內，否則中止。被審成果（程式碼、規格、方法論）不得夾帶，仍依 m-peer-review.md 不變量二在通過後才提交。Sprint 交付紀錄沿 m-work.md 既有的 delivery commit 契約（只改本工作 request）。
  • 審閱基線固定不動：交換文件在建立時記錄審閱基線 {reviewBase}，整個審閱期間不更新。成果範圍＝從 {reviewBase} 到目前工作樹的完整差異（包含 {reviewBase} 之後的提交），排除交換目錄。因此審閱提交讓 HEAD 前進不影響成果範圍，成果被意外提交後也仍完整列入審閱。
  • 基線之後的提交逐一分類：{reviewBase} 之後、交換目錄以外的每個提交都必須記錄在交換文件並分類：
    • 本成果的提交（例如意外提交）：留在成果範圍內，照常審閱；通過前不得推送到共享分支。
    • 外部提交（他人合併等）：只觸及成果範圍以外的檔案時，該等檔案從範圍排除並列出清單，重新發布（D6）；觸及成果範圍內的檔案時停止，由人決定重新起審或拆分成果，不能靠移動基線讓差異消失。
    • 有任何提交仍未分類時，status 報告範圍未確定，不得通過或結案。
  • 驗證要求：P1 須以測試證明：stage 守衛拒絕交換目錄外的檔案；連續審閱提交後成果範圍不變；成果意外提交後仍完整列入範圍；外部提交不重疊時正確排除並列出、重疊時停止；有未分類提交時 status 報告範圍未確定。

D3：Registry 定義位置與特性，路徑決定類型​

  • 每種文件類型在 registry 宣告位置與特性（Schema）。檔案的類型由路徑決定，不靠 frontmatter，pdf、json、xml 也能一致處理；frontmatter 只保留 version 等狀態欄位。
  • 共用層隨 docs-site bundle 發布，與站台骨架同一個發布單位、一起 audit。
  • 專案層放在 docs 模組（比照 site.project.ts）。專案層只能新增類型或對共用類型追加舊路徑，不能改寫共用類型的特性，避免 fleet 內同一類型的行為不一致。合併規則：
    • 各層的 defaults 只套用到該層自己宣告的類型；專案層的預設值不影響共用類型。
    • 專案層宣告與共用類型同 id 的類型一律拒絕。
    • 追加舊路徑只能透過 extendCommon: [{id, legacy}]，除 id、legacy 外的欄位一律拒絕。
  • 索引頁繼承所屬類型：README.md、index.md、_category_.json 等索引／分類檔以 inherit: container 宣告，保存與發布限制（lifecycle、retention、distribution、close、scope、downstream、git）一律取所在目錄的類型，只保留自己的呈現方式；沒有所屬類型時才用索引類型自己的值。避免審閱證據或報表 run 目錄裡的 README 被當成持久、可部署的一般頁面。
  • 交換目錄必須有容器類型：每種 temporary 交換（例如 {docsRoot}/docs/exchanges/reviews/{id}/）都要宣告一個涵蓋整個目錄（.../{id}/**）的容器類型，與交換本身同樣是 temporary。目錄根部的索引頁、分類設定以及沒有被更精確類型命中的檔案都歸屬這個容器，保存與發布限制不會因為檔名是索引或尚未分類而消失（lint R11）。
  • gitignore 條目、docs-host 排除清單、scaffold 排除清單、導覽分類、llms.txt 都由 registry 產生，不再分散手寫。

D4：以確定性程式作為存取入口，只管結構不代理內容​

  • 入口是一支程式（暫名 docs.py），不是 skill。skill 是給 AI 讀的指令，無法保證被呼叫、也無法保證結果一致；做法比照既有的 br_trace.py、evidence.py、docs-site/update.py、/progress native 腳本。
  • 入口只負責結構：resolve（類型＋id 解析成路徑，含舊位置）、create、register（導覽與 llms.txt）、publish（呈現給人確認）、close（收尾）、audit。
  • 內容照常用 Read／Edit 寫在解析出的路徑，保留 m-peer-review.md 寫前重讀、最小 Edit、欄位所有權等紀律。
  • 修訂（2026-10-16，P2-1 設計審閱通過）：不設 create。內容由 skill 以 Write／Edit 撰寫，create 剩下的「確認不存在、算出安全路徑」與 resolve 回傳新路徑時相同。resolve 的「含舊位置」由 registry 的查詢樣式（locate）實現：在該類型所有既有檔案（含舊佈局）中以識別參數（key）判定同一份文件，多個候選或無法解析的檔案即拒絕；找不到才產生新路徑，回傳前另做執行期驗證。register 只維護 llms.txt 的受管區塊，permalink 取自站台的路由紀錄。規範見 文件解析與索引規格。
  • 三層防線：事前由 skill／rule 規定先 resolve；寫入當下以 PreToolUse hook 拒絕寫到 registry 未登記的 docs 模組位置；事後由 audit 抓人類與 hook 管不到的寫入。
    • P3 設計澄清（2026-10-20，第 2 輪設計審閱通過）：寫前攔截限已安裝的 Claude Code Write／Edit 與 registry 掃描根；NotebookEdit、shell／MCP、外部編輯器及 .codex/／/tmp 等根外語意義務不宣稱已機械覆蓋。唯一分類的 legacy 仍可維護，不強制搬檔。workspace 先對應實體根，根以上的祖先別名可接受，根以下 symlink 仍拒絕。既有未登記檔與 audit waiver 不構成寫入例外；獨立安裝器先列完整影響，清單非空不寫設定，不能把 methodology publish 視為已啟用。完整契約見文件寫入守衛 §4～§8／§12；第 2 輪已核對四項修訂，受審 revision r2-a2b1504b61f97ef6，完整結論見該規格 §13。P3 工具尚未實作或啟用，ADR 維持 Proposed。

D5：方法論未定義的類型與清除原則​

  • 提供通用類型 other。專案遇到方法論未定義的文件時，在專案層以 base: other 宣告，必須寫用途（purpose）；audit 會把它列為框架擴充建議，由專案向框架提出。
  • 目前已存在但方法論沒有產出者契約的類型，依同一方式處理：共用者列為 proposed，專案特有者列為專案擴充。
  • 文件是否清除依用途決定，不依有沒有類型決定。 清除由 retention 與 close 表達。

D6：呈現版本與確認綁定​

取消「工作樹原件＋展示副本」後，原件在 docs 模組直接呈現；確認仍必須綁定到明確的版本：

  • revision：publish 每次呈現產生 revision，由三部分雜湊而成：受確認內容、本輪成果清冊（路徑＋SHA-256）、呈現環境識別（docs-site bundle 雜湊、站台設定檔雜湊、Docusaurus 版本）。
  • 雜湊邊界：受確認內容＝交換原件的實質內容，不含確認與發布本身的紀錄：
    • 確認紀錄（審閱結論、人工確認）寫在交換目錄的獨立確認檔，每筆寫明所確認的 revision；確認檔不在雜湊範圍內。
    • 原件中鏡像確認狀態的欄位（標頭狀態、審閱紀錄的結論欄）與記錄 revision／入口的展示欄，同樣排除在雜湊外。
    • 其他內容（動機、範圍、意見與處置、預檢等）都在雜湊範圍內；審閱者新增意見屬實質變更，會產生新 revision。
    • 因此寫入確認不會讓所確認的 revision 失效；實質內容、成果或呈現環境改變則一定產生新 revision。
  • 發布紀錄：publish 在交換目錄寫入發布紀錄（revision、輪次、來源路徑與雜湊、成果清冊、呈現環境識別、頁面 URL），頁面本身顯示 revision、輪次與來源雜湊。
  • 核對證據：publish 取回實際送出的頁面，確認顯示的 revision 與發布紀錄相同，並逐一取回附件比對 SHA-256；只拿到 HTTP 200 或舊 build 不算完成。
  • 確認綁定：審閱結論與人工確認紀錄必須寫明 revision。受確認內容、成果或呈現環境任何一項改變都產生新 revision 並更新入口，先前的確認不沿用，需要重新確認。
  • 驗證要求：P1 須以測試證明：寫入確認紀錄及其鏡像欄位後 revision 不變；修改任一實質段落、成果檔或呈現環境識別後 revision 改變；確認檔中引用舊 revision 的確認不被當成目前版本的確認。
  • status（唯讀）比對目前計算的 revision 與記錄值，不一致時報告「需重新發布」，不在唯讀模式重建。
  • 寫前重讀、最小 Edit、欄位所有權等編輯紀律不變。

D7：preview-only 在標準建置的編譯前排除​

原件搬進 docs/ 後會被 Docusaurus 編譯成頁面、側欄、搜尋索引與 JS chunk，只靠 host 的 copyDocsBuild 路徑排除不夠：

  • 標準建置在編譯前排除 distribution=preview-only 的來源：由 registry 推導 docs plugin 的 exclude 樣式，並同步排除其導覽、搜尋索引、sitemap 與 llms.txt 項目；對應的靜態檔也不輸出。
  • 只有審閱預覽（start:docs-only，DOCS_SITE_REVIEW=1）納入 preview-only 來源。
  • 驗收：標準建置後掃描全部產物（HTML、JS chunk、搜尋索引、sitemap、llms.txt），不得出現任何 preview-only 來源的路徑或識別。此為 P1 遷移條件。

Schema​

欄位​

欄位值預設說明
id、title—必填類型識別
categorysource／spec／design／verification／tracking／guide／reference／exchange／site／other必填領域分類，決定導覽分類
roledocument（給人讀）／data（結構化事實來源）／evidence（給機器驗證）／exchange（AI 與人交換）／projection（由他處產生）／config（站台設定）必填決定存放層與呈現方式
pathsglob，錨點 {docsRoot}／{workspace}／{module}必填權威位置
legacyglob[]舊位置；resolve 會找到，audit 會報出
priority整數0同一檔案符合多個類型時決勝（例如 README 判為索引頁）
lifecyclepersistent／temporary／regenerable／personal／scratch必填決定 git 與收尾
close{trigger, owner}—temporary 必填
derivedFrom{source, generator}—regenerable／derived 必填
retentionall／referenced／referenced+latest／with-source／remove-at-close／regenerate／local-onlyall依用途的保留規則；決定哪些檔案進 git、何時從目前版本移除
authoritysource／derivedsource—
writer{mode: open｜single｜field-owned｜generator, by: [...]}必填寫入權
changeversioned／append-only／regenerate／freefree變更管制；versioned 依 m-doc-version、m-change-management
scopeteam／branch／personalteam共享範圍
presentationpage／asset-index／confirm-entry／hidden必填網站呈現；除 hidden 外都必須能從導覽讀到
distributionsite（隨站台部署）／preview-only（只在審閱預覽出現；標準建置於編譯前排除，見 D7）／workspace（不進網站）site取代現行只靠 DOCS_SITE_REVIEW 與 copyDocsBuild 的排除
downstreamexclude／reference／neutral依 categoryscaffold 下行行為
git + gitReasontracked／ignored由 lifecycle 推導只在例外時填寫，且必須寫理由
belongsTous／epic／rpt／sprint／brief／work／style…—專題視角，例如某份 RPT 的全部文件
base + purposeother ＋ 用途說明—專案擴充類型
inheritcontainer—索引／分類檔繼承所在目錄類型的保存與發布限制（D3）
statusestablished（方法論已定義）／proposed（本提案）／extension（專案擴充，建議框架納入）／deprecatedestablished—

git 推導：persistent、temporary 推導為 tracked；regenerable、personal、scratch 推導為 ignored。

推導規則（registry lint）​

規則內容
R1temporary 必須宣告 close、retention=remove-at-close，且不可隨標準站台部署
R2regenerable 或 derived 必須宣告 derivedFrom，writer 必須是 generator
R3personal 必須 scope=personal、presentation=hidden
R4evidence 的 change 只能是 append-only 或 regenerate，且必須明示 retention
R5exchange 不可是 regenerable
R6需求來源必須 downstream=exclude
R7presentation 不是 hidden 的類型，位置必須在 docs 模組內（D1）
R8覆寫 git 推導值時必須寫 gitReason
R9base: other 必須寫 purpose
R10inherit 只允許 container，且必須設 priority 才能先於所屬類型命中
R11temporary 類型必須有一個同為 temporary、涵蓋整個交換目錄（.../{id}/**）的容器類型

合併規則違反（專案層同 id 類型、extendCommon 夾帶 legacy 以外欄位）在載入時直接拒絕，不列為 lint 警告。

對照檢查（audit）​

檢查判定
未登記掃描範圍內的檔案沒有對應類型
多重比對同一檔案以相同分數符合兩個類型
git 不符實際狀態與推導或覆寫值不同
page 無法渲染宣告為頁面的事實來源類型中混有非 md 檔
網站不可達應呈現卻不在站台索引範圍（css、js、字型等相依資源不計）
證據在正文樹evidence 放在 {docsRoot}/docs/ 下且沒有索引頁
暫時文件孤兒審閱證據或展示副本找不到對應簡報
舊位置檔案命中 legacy
索引繼承索引／分類檔依所屬類型判定 git 與保存限制，並列出繼承來源

影響範圍​

本提案通過後須同步修訂（由本變更一起送審，各項實作依分期）：

對象修訂
m-peer-review.md、/peer-review簡報與證據改放 {docsRoot}/docs/exchanges/reviews/{briefId}/，審閱期間提交、結案移除（2026-10-16 修訂為不提交、結案刪除，見 D2）；取消工作樹原件＋展示副本的雙份結構；「不進 git、不進 docs/」不變量改寫；加入審閱提交範圍與基線契約（D2）、呈現版本與確認綁定（D6）
m-skill-execution.md「專案文檔的人類瀏覽與確認入口」的暫時展示副本段改為原件直接呈現；明列 D1；確認綁定 revision，內容或呈現環境改變後重新確認（D6）
m-work.md、/work交付紀錄改放 {docsRoot}/docs/exchanges/work/{workId}/；delivery commit 只改本工作 request 的契約維持
m-docs-site.md、/docs-site（含 bundle 的 docs-site.cjs）共用 registry 進 bundle；exchanges 分類與證據索引頁；目前只索引 static/reviews、static/reports 的入口規則改由 registry 推導；audit 納入 registry 檢查；gitignore 與 host 排除由 registry 產生；preview-only 於標準建置編譯前排除及產物掃描（D7）
團隊指南 project-documentation.md「Peer review 原件留在共享工作樹、網站提供展示副本」段落改寫為 D1
m-methodology.md索引登錄 registry 規則與入口程式
/report、ADR-020workspace output/ 只放未給人看的中間產物；ADR-020「原樣張放受控儲存」需與 D2「git 為唯一共享空間」對齊
/uat、/report 證據宣告 retention，只提交被引用與最新的 run
/handoffP2-5 設計已決：維持 personal／workspace／hidden／local-only 的個人便條紙，不移入 docs 模組；見其他類型遷移 §6.3
各產出文件的 skill路徑段落改為引用 registry 類型；逐步遷移，不一次改寫
.claude/settings.jsonP3 新增 PreToolUse hook

實作分期​

分期內容解鎖條件
P0共用 registry＋專案層、docs.py audit（唯讀）；三專案跑 audit 定基線本 ADR 通過
P1交換文件移入 docs 模組（peer-review、work）；現有孤兒依用途處理；publish／close 與 revision（D6）；審閱提交守衛（D2）；preview-only 編譯前排除（D7）P0 通過，且首次提交任何交換文件或證據前必須具備：依用途篩選（只提交被引用與最新的 run／附件，其餘留在本機）、被引用證據的保留檢查、close 前的結論落點檢查；D2 守衛與基線分類測試通過；D6 雜湊邊界測試通過；標準建置產物掃描不含 preview-only
P2resolve／register（不設 create，見 D4 修訂）；skill 改版時逐一改用 registry 類型；retention 的自動判定與全面套用（P1 已有首次提交前的篩選檢查）P1 通過
P3PreToolUse hook 阻擋未登記位置的寫入registry 穩定、P2 主要 skill 完成遷移

待決​

  1. 已決（P2-5，2026-10-19）：handoff.md 維持 personal／workspace／hidden／local-only，不移入團隊 docs；見其他類型遷移 §6.3。
  2. 已決（P2-6 設計，2026-10-20）：Git 共享為預設；既有來源契約明示不能提交之原件／證據包採 D2 窄例外，Git 保存 locator／摘要／確認，同一內部文檔站提供完整對照；見證據保留 §6。
  3. 已決（P1／P2-6 設計）：交換證據放 static/exchanges/{kind}/{id}/evidence/；UAT 快照、report 帳本／runs 維持原位，不為清除正文樹提示而搬移。原生路徑／指紋及已有逐檔瀏覽／展示副本契約不改；見證據保留 §1、§3。
  4. 各 proposed／extension 類型的最終歸屬（附錄 A、附錄 B）。
  5. 專案層 registry 的檔名與位置。

考量的方案​

方案取捨
維持各 skill 自行定義位置skill 隨方法論演進而改，位置無法控制；未採用
以一支「存取文檔的 skill」作為入口無法保證被呼叫、結果不確定，巢狀載入成本高；改用確定性程式（D4）
入口代理全部讀寫（含內容）失去最小 Edit 與欄位所有權，入口會隨內容規則一直改；改為只管結構
外部儲存或 LFS 存放大型證據團隊只以 git 共享；未採用（D2）
定期從 git 刪舊檔縮小 repo歷史仍保留，repo 不會變小；改為進 git 前依用途篩選
改寫歷史縮小 repo需要 force-push 與全員重新 clone；不納入常規流程
工作樹原件＋網站展示副本（現行）兩份內容需同步、易遺留孤兒、/work 沒有入口；改為原件直接放在 docs 模組（D1）
frontmatter 宣告類型非 md 檔沒有 frontmatter；改為路徑決定類型
preview-only 只靠 host 路徑排除（現行）原件搬進 docs/ 後仍會被編譯進頁面、索引與 JS；改為編譯前排除（D7）
專案層可覆寫共用類型fleet 內同一類型行為會分歧；改為分層隔離、只允許追加舊路徑（D3）

附錄 A：共用層類型草案​

已由正式工具取代：P0 起共用層 registry 為 docs-site bundle 的 docs-registry.json，唯讀入口為 docs.py，規範見 文檔 Registry 規格。以下原型保留作為本 ADR 的審閱證據，不再更新。

registry 原型與 audit 原型： registry.common.json、 audit.py（唯讀，用法見檔頭）、 test_audit.py（索引繼承與分層合併的契約測試）。 section-index、category-config 宣告 inherit: container，下表列的是沒有所屬類型時的值。

類型名稱categoryrolelifecycleretentionwriterpresentation狀態
section-index分類索引頁sitedocumentpersistentallopenpageestablished
category-configDocusaurus 分類設定siteconfigpersistentallopenhiddenestablished
site-asset站台圖檔siteconfigpersistentallopenhiddenestablished
site-source站台原始碼與設定siteconfigpersistentallopen（/docs-site）hiddenestablished
design-reference設計參考頁designdocumentpersistentallopenasset-indexproposed
br業務需求 BRsourcedocumentpersistentallopen（/br）pageestablished
requirements-transcript需求訪談／會議逐字稿sourcedocumentpersistentallopen（/transcribe）pageestablished
requirements-research需求研究資料sourcedocumentpersistentallopenpageestablished
meeting-transcript設計／其他會議逐字稿designdocumentpersistentallopen（/transcribe）pageestablished
roadmapRoadmapspecdocumentpersistentallopen（/roadmap）pageestablished
feature-listFeature Listspecdocumentpersistentallsingle（/feature-list、/progress）pageestablished
epicEpicspecdocumentpersistentallopen（/epic）pageestablished
usUser Storyspecdocumentpersistentallopen（/us）pageestablished
sbeSBE 場景specdocumentpersistentallopen（/sbe）pageestablished
checklist需求品質檢核／評估摘要specdocumentpersistentallopen（/checklist、/assess）pageestablished
analysis-report一致性分析報告specdocumentpersistentallsingle（/analyze）pageestablished
development-plan開發計畫specdocumentpersistentallopenpageproposed
report-spec報表規格 RPTspecdocumentpersistentallopen（/report）pageestablished
domain-model領域模型designdocumentpersistentallopen（/domain-model）pageestablished
data-model資料模型designdocumentpersistentallopenpageestablished
api-specAPI Specdesigndocumentpersistentallopen（/api-spec）pageestablished
decision-recordADRdesigndocumentpersistentallopenpageestablished
personaPersonadesigndocumentpersistentallopen（/persona）pageestablished
system-context系統脈絡designdocumentpersistentallopen（/system-context）pageestablished
roles-and-accounts角色與帳號設計designdocumentpersistentallopenpageproposed
design-example設計範例designdocumentpersistentallopenpageestablished
report-style報表樣式定義designdocumentpersistentallopen（/report）pageestablished
report-style-data報表樣式結構化資料designdatapersistentallopen（/report）hiddenestablished
report-layout報表採用樣板designdocumentpersistentallopen（/report）asset-indexestablished
uat-guideUAT 驗收指南verificationdocumentpersistentallsingle（/uat-script）pageestablished
uat-guide-sourcesUAT 指南來源 sidecarverificationevidencepersistentwith-sourcegenerator（/uat-script）hiddenestablished
uat-resultUAT 驗收結果verificationevidencepersistentallsingle（/uat）asset-indexestablished
uat-snapshotUAT 來源快照verificationevidencepersistentreferencedgenerator（/uat）hiddenestablished
uat-equivalenceUAT 等價處置紀錄verificationevidencepersistentallgenerator（/uat）hiddenestablished
test-result測試結果報告verificationdocumentpersistentallopenpageestablished
test-data-seed測試資料 seed 說明verificationdocumentpersistentallopenpageestablished
sim-plan模擬計畫verificationdocumentpersistentallopen（/sim-plan）pageestablished
report-evidence報表驗證證據verificationevidencepersistentreferenced+latestgenerator（/report）asset-indexestablished
report-preview報表樣張預覽verificationprojectionregenerableregenerategenerator（/report）confirm-entryestablished
report-restoration原樣張還原對照verificationprojectionregenerableregenerategenerator（/report）confirm-entryestablished
sprintSprint 文檔trackingdocumentpersistentallsingle（/sprint、/progress）pageestablished
progress-index進度總覽trackingdocumentpersistentallsingle（/progress）pageestablished
follow-upsFollow-up backlogtrackingdocumentpersistentallsingle（/follow-up）pageestablished
work-log工作日誌trackingdocumentpersistentallopenpageproposed
guide開發指引guidedocumentpersistentallopenpageestablished
operations維運手冊guidedocumentpersistentallopenpageestablished
rfc框架 RFCguidedocumentpersistentallopen（/rfc）pageestablished
openapi-pagesOpenAPI 參考頁referenceprojectionregenerableregenerategenerator（sync-static.js）pageestablished
openapi-specOpenAPI YAMLreferenceprojectionregenerableregenerategenerator（sync-static.js）hiddenestablished
javadocServer Javadocreferenceprojectionregenerableregenerategenerator（sync-static.js）asset-indexestablished
llms-indexAI 站內索引referenceprojectionpersistentallopenhiddenproposed
module-inventory模組清單referenceprojectionpersistentallgenerator（/scaffold-project、/scaffold-module）hiddenestablished
peer-review-exchange審閱交換目錄exchangeexchangetemporaryremove-at-closefield-owned（/peer-review）pageproposed
peer-review-brief審閱簡報exchangeexchangetemporaryremove-at-closefield-owned（/peer-review）pageproposed
peer-review-evidence審閱證據exchangeevidencetemporaryremove-at-closegenerator（/peer-review）asset-indexproposed
review-display審閱展示副本exchangeprojectionregenerableregenerategenerator（/peer-review）confirm-entrydeprecated
work-requestSprint 工作交付請求exchangeexchangepersistentallsingle（/work）pageproposed
work-progress工作分支進度trackingdocumentpersistentallsingle（/work）pageproposed
work-evidence工作整合證據exchangeevidencepersistentreferencedgenerator（/work）asset-indexproposed
handoff交接便條紙exchangeexchangepersonallocal-onlysingle（/handoff）hiddenestablished
report-scratch報表本機暫存輸出verificationprojectionscratchlocal-onlygenerator（/report）hiddenestablished
module-doc模組內說明文件guidedocumentpersistentallopenhiddenproposed
feature-changelogFeature Changelogtrackingdocumentpersistentallopen（/release-app）hiddenestablished
other其他（通用）otherdocumentpersistentallopenpageestablished

附錄 B：三專案對照（2026-10-15）​

以附錄 A 的 registry 加上各專案擴充層，由 audit 原型唯讀掃描。掃描範圍：docs 模組全部（排除 node_modules、build、.docusaurus）、workspace 的 .claude/{peer-review,work,docs,handoff.md} 與 output/、各模組的 docs/ 與 FEATURE_CHANGELOG.md。

覆蓋率​

專案型態掃描檔數命中類型未登記
florae-g1方法論開發3,751443 檔（無產出者的 *.audit.json 2 個、討論稿 1 份）
nbsos報表開發6,6763012 檔（US 目錄內的 UC 文件、-old 檔、pdf；設計文件 1 份）
appfuse-webapp-v1參考實作9,786476 檔（審閱目錄根部的 log 3 個，另 3 檔同 florae）

這組特性能描述三個專案的現況；未登記的檔案都是真正的例外。

加入索引繼承後重跑，三個專案的違規與欠帳不變；索引頁全部找到所屬類型（例如 nbsos 訪談目錄的 _category_.json 繼承需求逐字稿）。參考實作多出的檔案只來自本次審閱自身的簡報與證據。

違規與欠帳​

#問題florae-g1nbsos參考實作
1暫時證據沒有收尾（孤兒）—6 目錄／50 MB26 目錄／153 MB
2可重建檔案已提交—原樣張還原副本 100 檔—
3證據在正文樹UAT 證據 2,100 檔／29 MB報表證據 4,052 檔／221 MBUAT 證據 2,068 檔／28 MB
4與人類溝通的文件在 docs 模組外（D1）交付紀錄 27 檔審閱證據 185 檔審閱證據 4,129 檔
5網站不可達UAT 結果 54報表證據 4,039、PDF 樣張 24UAT 結果 52、設計語言證據 43
6方法論沒有產出者契約的類型6 類6 類9 類

第 4 項在 D2 下應提交，但其中孤兒（第 1 項）應先依用途處置，不是直接提交。

git 實際佔用（nbsos）​

項目數值
repo 壓縮後總大小151 MB
報表證據目前追蹤的檔案4,642 個；內容不重複者 2,326 個，壓縮後 93 MB
歷史中的報表證據94 MB，幾乎等於目前版本
報表 run20 份 RPT、218 次 run、共 144 MB；只保留最新 run 為 27 MB

git 會對相同內容去重，因此檔案數遠大於實際佔用。增長來自持續提交新 run，referenced+latest 保留規則的效果介於 27 MB 與 144 MB 之間，取決於被驗收引用的 run 數量。

方法論沒有產出者契約的類型​

類型出現在處理
設計參考頁（static/design-reference）三個專案proposed：找出來源後決定
開發計畫、角色與帳號設計、工作日誌florae-g1、參考實作proposed：補產出者或歸入 guide
模組內說明文件（host、server 的 docs/）三個專案proposed：依 D1 判斷是否屬於與人類溝通的文件
既有系統實作規格、報表來源摘要、PDF 樣張、報表樣式資產nbsosextension：報表類可能應升到共用層
設計語言對齊證據、參考實作稽核證據、UAT 證據來源對應、測試靜態證據參考實作（florae-g1 有測試靜態證據）extension：需定義用途與保留規則

P0 正式工具基線（2026-10-15）​

P0 以 docs.py audit 依規格 §10 重跑三專案（唯讀；下游以 --registry-common／--registry-project 覆寫，未寫入任何下游檔案）。每個專案兩組：只用共用層，以及共用層加上本附錄當時專案擴充改寫成 schema 1 的草稿。

專案組別檔數命中類型未登記應追蹤卻忽略應忽略卻追蹤孤兒交換證據在正文樹不可達不在 docs 模組
florae-g1共用層3,7514440002,1005727
florae-g1＋專案草稿3,7514530002,1005827
nbsos共用層6,676276919610064,0694,583185
nbsos＋專案草稿6,676311219610064,0814,607185
參考實作共用層9,84145584,1830202,067554,183
參考實作＋專案草稿9,8414964,1830202,0681064,183

參考實作的檔數與審閱證據數含當時進行中的 P0 實作審閱證據，結案後即刪除。

歸因：

  • 兩組之間的差異全部來自專案擴充（輸入差異），與工具判定無關：例如 nbsos 的未登記 69 → 12。
  • 與原型在同一份檔案上的差異只有刻意的規則改變：
    • 新增 agent-local-settings（個人設定，ignored），三專案各少一筆誤報；
    • 新代碼「不在 docs 模組」（D1）把相依資源也算進去，並涵蓋 page 類型；
    • md／mdx 不計入不可達（會渲染成頁面）；
    • 孤兒以 (kind, id) 分組：參考實作 26 個舊證據目錄＝20 個審閱。
  • 本附錄前述的違規與欠帳在正式工具中全部重現。

原型限制​

  • 網站可達性依 docs-site.cjs 現行索引規則靜態判斷，沒有啟動站台逐頁核對。
  • 孤兒以「目錄名稱去掉 -evidence／-reviewer／-rN 後綴＝簡報 id」推測；報表專案的展示副本目錄不以簡報 id 命名，可能誤判。
  • 沒有檢查 scaffold 排除清單、frontmatter 一致性與 llms.txt 覆蓋率；retention 只估算，未實作判定。
  • 測試只涵蓋索引繼承（含交換目錄根部）、分層合併與 R11；D2 的提交守衛、D6 的 revision 與 D7 的建置排除屬 P1 實作，原型未涵蓋。

變更歷史​

日期變更
2026-10-15草案：D1–D5、schema、推導規則與三專案對照
2026-10-15第 1 輪審閱（6 條 major）處置：D3 補分層合併規則與索引繼承；D2 補審閱提交契約；新增 D6 呈現版本與確認綁定、D7 preview-only 編譯前排除；P1 補首次提交前的篩選與結論落點條件；原型補索引繼承、分層隔離與契約測試
2026-10-15第 2 輪審閱（3 條 major）處置：D3 補交換目錄容器類型與 lint R11；D2 改為審閱基線固定、基線後提交逐一分類；D6 定義確認紀錄與受確認內容的雜湊邊界；P1 驗證條件同步；原型補容器類型與 3 個測試
2026-10-15第 3 輪審閱通過（revision r3-959a7210380ab603）；狀態維持 Proposed，P0–P3 實作與待決點記入 follow-up
2026-10-15P0 設計通過審閱（20261015-docs-registry-p0，第 3 輪，revision r3-11470bae46a0d5bd），操作規範見 文檔 Registry 規格；實作待進行
2026-10-15P0 實作：共用層 registry 進 docs-site bundle 並投影到參考實作 app-docs；docs.py（lint／classify／audit）與 38 個測試；附錄 A 原型註明已由正式工具取代；三專案基線待 P0 實作審閱
2026-10-15P0 實作通過審閱（20261015-docs-registry-p0-impl，第 3 輪，revision r3-4d58c60ef77aecc0；5 條意見均處置）；附錄 B 新增 P0 正式工具基線；狀態維持 Proposed，P1–P3 待進行
2026-10-15P1 設計通過審閱（20261015-docs-exchanges-p1，第 3 輪，revision r3-6940c07d011ead6f；6 條 major 均處置），操作規範見 交換文件規格；待決 3 的交換證據部分已決（證據放 static/exchanges/，正文放 docs/exchanges/）；狀態維持 Proposed，P1 實作待進行
2026-10-16P1 實作：docs.py 新增 evidence／publish／status／close；registry 新增 peer-review-static、review-record、work-receipt、work-exchange，證據移到 static 樹；docs-site bundle 加入 preview-only 編譯前排除、建置後 finalize、交換頁附件索引與審閱預覽狀態檔；/peer-review 2.0.0、/work、/docs-site 與相關 rules 改寫；規格頁 §15 記錄實作中確認的三處修訂；送審中
2026-10-16P1 實作第 1 輪審閱：6 條意見（5 major、1 minor）處置；使用者決定審閱報告不提交，D2 加修訂：審閱交換 gitignored、結案刪除，publish／close 不再提交；刪除參考實作 20 個舊審閱孤兒（使用者確認），參考實作 docs.py audit --fail-on error 通過
2026-10-16P1 實作通過審閱（20261016-docs-exchanges-p1-impl，第 4 輪，revision r4-3b0c6db130f8a561；9 條意見均處置：R1-01～R1-06、R2-01、R2-02、R3-01）；狀態維持 Proposed，下游 publish／apply 與 P2–P3 待進行
2026-10-16P2 分六階段（P2-1 工具 → P2-2 規格類 → P2-3 設計類 → P2-4 驗證類 → P2-5 其他 → P2-6 保留），全部通過後才一次 /methodology publish。P2-1 設計通過審閱（20261016-docs-resolve-p2-1，第 4 輪，revision r4-cfb48816b403fb1f；8 條意見均處置：R1-01～R1-06、R2-01、R3-01），規範見 文件解析與索引規格；D4 修訂為不設 create；狀態維持 Proposed，P2-1 實作待進行
2026-10-16P2-1 實作：docs.py 新增 resolve、register，registry 欄位 template／locate／params／key／example 與 lint R12，audit 新增 DR-UNPARSED-LOCATION／DR-INDEX-STALE／DR-INDEX-UNVERIFIED；bundle 新增 docs-site-routes 外掛（路由紀錄）；registry 新增四個缺口類型（73 類）；修正 P1 去數字前綴的日期與版號例外；/docs-site 1.4.0；規格頁 §10 記錄實作中確認的修訂；參考實作 llms.txt 首次導入受管區塊，經使用者決定一併刪除移植時遺留的 150 條死連結
2026-10-16P2-1 實作通過審閱（20261016-docs-resolve-p2-1-impl，第 3 輪，revision r3-1b702f80d5efef53；4 條意見均處置：R1-01 路由紀錄的設定雜湊綁定設定求值時點、R1-02 含空白的 permalink、R1-03 參數 regex 的完整比對、R2-01 已刪除含空白網址的回報）；新增實際站台回歸測試 test_routes_site.py；狀態維持 Proposed，P2-2～P2-6 與 P3 待進行
2026-10-16P2-2 設計通過審閱（20261016-docs-resolve-p2-2，第 2 輪，revision r2-5e84d64ae316bd91；3 條意見均處置），規範見 規格類遷移：七個規格類型加範本、從 checklist 拆出 assess-summary、resolve --list 與 DR-DUPLICATE-KEY、skill 讀取來源與建立成果分開且保留現行查無處置；範本已以 fleet 9 個 workspace 的實際檔案驗證；狀態維持 Proposed，P2-2 實作待進行
2026-10-17P2-2 實作通過審閱（20261016-docs-resolve-p2-2-impl，第 3 輪，revision r3-68c366ec3bd9f80d；6 條意見均處置：R1-01～R1-04、R2-01、R2-02）：七個規格類型加範本並拆出 assess-summary（74 類）；resolve --list、classify 回傳 params、audit DR-DUPLICATE-KEY；共用契約 /docs-site 的 references/doc-locations.md；8 個規格類 skill 改用 resolve／register；規格頁 §9 記錄 10 項實作修訂；審閱中發現證據附件與簡報宣稱不符（R1-04），/peer-review 2.1.0 補上證據須記錄實際命令與輸出並逐一核對；狀態維持 Proposed，P2-3～P2-6 與 P3 待進行
2026-10-17P2-3 設計通過審閱（20261017-docs-resolve-p2-3，第 2 輪，revision r2-ed0145d21ad1c955；2 條意見均處置），規範見 設計類遷移：domain-model、api-spec、persona、system-context 加範本，domain-model 拆出多檔的 domain-model-part，新增 api-spec-draft 承接 .generated.md 草稿，範本已以 fleet 9 個 workspace 的實際檔案驗證；審閱修訂：/persona 區分檔案 ID 與顯示名稱（不符 ID 格式的名稱不傳給 resolve，改以 frontmatter 比對）（R1-01）、/domain-model 遷移除 register 重建區塊外，定向清理區塊外指向舊模型路由的手寫條目並納入完成條件（R1-02）；狀態維持 Proposed，P2-3 實作待進行
2026-10-19P2-3 實作通過審閱（20261017-docs-resolve-p2-3-impl，第 2 輪，revision r2-e0da1ddeec030484；2 條 minor 均處置）：registry 76 類，4 個設計類 skill 改用 resolve／register，參考實作投影完成；35 項走查與設計類測試通過。R1-01 將讀取方位置字樣更新明列至文件解析與索引規格 §1 的 P2-5 範圍；R1-02 將缺少概覽時的讀取略過、產出時建立及來源揭露落回 /domain-model 與設計類遷移規格 §7。狀態維持 Proposed，P2-4～P2-6 與 P3 待進行；P2 全部通過後才統一 publish。
2026-10-19P2-4 設計通過審閱（20261019-docs-resolve-p2-4，第 2 輪，受審 revision r2-d42627c241c93b4e；1 條 major、3 條 minor 均處置），規範見驗證類遷移：九類範本、兩種規劃備註分類、完整 stem 作 UAT 物理 key、原生唯讀 resolve-route；R1-01 明訂操作 context 以 workspace／docs／registry 雜湊隔離、每類型列舉一次、寫入失效與效能驗收；R1-02 明訂 project.json 完整登記 key、新建專用 --module-key 與孤兒資料等拒絕出口；R1-03 明訂 RPT 按數值比對、保留既有 raw ID、新建至少三位及數值取號；R1-04 確認畸形指南會阻擋全域列舉與整合閘門，依 audit 的 DR-UNPARSED-LOCATION 修復，不改成場景失敗或回退進度。動態 run／snapshot／bundle 與 report helper 保留原生契約，retention 及 ADR-020／D2 儲存衝突留待 P2-6。狀態維持 Proposed，P2-4 實作、P2-5～P2-6 與 P3 待進行；P2 全部通過後才統一 publish。
2026-10-19P2-4 實作通過審閱（第 2 輪，受審 revision r2-1c498ed422a45d74；3 條 minor 均處置），落點見驗證類遷移 §8：registry 78 類，五個 skill、原生 UAT 位置橋接與唯讀 resolve-route、參考實作投影及 adapter 完成；最終程式碼完整 UAT 回歸 346 項、report 34 項與 docs-only 建置通過。R1-01 的單筆 resolve 子程序成本由 FU-144 承接，規格記錄現況；R1-02 統一最終完整回歸證據，R1-03 將共用文字集中至 doc-locations.md。既有 server Javadoc 編譯失敗由 FU-143 承接，歷史證據、人工接受及動態附件契約不變。狀態維持 Proposed，P2-5～P2-6 與 P3 待進行；P2 全部通過後才統一 publish。
2026-10-19P2-5 設計通過第 2 輪審閱（受審 revision r2-ab16fccf66eeb394；1 條 major、2 條 minor 均處置），規範與結論見其他類型遷移 §10。採用九個 writer／BR 與 progress 原生接線、四用途來源 Markdown、持久 RFC 提交稿、簡報 static 及 Storybook／框架 multi-instance 邊界。R1-01 明訂 source／target 基線的動態進度保護集與 m-work／work／progression 同批實作；R1-02 接受簡報兩類 site，含草稿版次及全部成員，揭露容量影響並要求 bytes 驗證；R1-03 明訂整 repo 可達 Git 歷史的保守取號與不可靠上界處置。handoff 維持 personal／workspace／hidden／local-only，對應待決已解。狀態維持 Proposed，正式 registry 仍為 78 類，P2-5 實作、P2-6 與 P3 待進行；P2 全部通過後才統一 publish。
2026-10-20P2-5 實作已完成、待實作審閱，接線及驗證見其他類型遷移 §11：registry 88 類／12 種範本，BR model／trace 與 progress updater 共用位置橋接；WORKTREE／INDEX／target＋merge-base 共享進度保護、九個 writers 與 readers、參考實作投影與 adapters 已接線。最終 UAT 346 項、BR 66 項、progress 17＋4 項、work 守衛 14 項及 registry／站台 fixture 通過；簡報兩版 10 檔 bytes／HTTP 核對及九 workspace 108 次唯讀列舉通過。legacyLayer 區分 common 舊域與 project locate，精確 singleton priority 20 避免被根目錄 section-index 遮蔽。保留原批准、歷史資料及 Storybook 權威；本列不是實作通過結論。狀態維持 Proposed，P2-6／P3 與 FU-144 未處理，P2 全部通過後才統一 publish。
2026-10-20P2-5 實作通過第 2 輪審閱（受審 revision r2-6e4865a564799b15，審閱者 ada@leandev.io；兩項 minor 均處置），結論見其他類型遷移 §11。R1-01：merge 從可信 target checkout 執行，匯入 resolver 前核對 protected.py 與非 test_ docs-site Python 工具檔集合／bytes 等同 target Git blobs，完成前重驗；全套 work 回歸 17 項通過。R1-02：簡報版次只在同一 (kind, packageId) 內取數值最大值加一，空集合 v1。registry 88 類與原生接線維持；第 1 輪 BR／progress／UAT／docs-site 來源未變，保留原回歸。狀態維持 Proposed，下一步 P2-6 設計與審閱；P2 全部通過後才統一 publish，本輪未 commit、下行或部署。
2026-10-20P2-6 設計提案完成、待審閱，見證據保留：UAT 完整歷史快照閉包、report 整 run／歷史接受／latest、唯讀 retention 查詢與提交前參考接線（不新增交付閘門；blocked 保留本次有效成果的精確保存／交付出口）；提議既有不能提交原件／證據包採 D2 窄例外並新增 report-source。此為提案，D2 現行決策、registry 88 類及既有資料不變，尚未實作、清理或下行。
2026-10-20P2-6 設計通過第 2 輪審閱（受審 revision r2-87cfce29bd2c9c8c，審閱者 ada@leandev.io；1 項 major、1 項 minor 均處置），結論見證據保留 §11。採完整歷史快照／run 閉包、唯讀不刪除、證據原位與 D2 窄例外、report-source 分類；R1-01 明訂 retention 為提交參考及 blocked 的本次成果交付出口，R1-02 更正 methodology 標的與分期解鎖。D2 與 ADR-020 保存說明已補齊；registry 仍 88 類，89 類候選及原生功能／鎖／驗收待實作。狀態維持 Proposed，實作另送審、P2 全通過後才下行，本輪未清理、commit 或部署。

2026-10-20：P2-6 實作第 2 輪審閱通過​

P2-6 實作已通過第 2 輪審閱（受審 revision r2-19ace3c868307bfa，審閱者 ada@leandev.io），完整結論見證據保留 §12。唯讀 retention／原生匯出、協作鎖、audit 及提交參考接線完成，canonical／參考實作為 89 類。R1-01 限縮 JSON 根啟發式並保留跨型別 pin 的保守出口；R1-02 依原生路由回取歷史 sidecar 並攜帶 originalPath 遞迴展開；R1-03 統一讀寫鎖排序。R2-01 的舊帳本 resultPath 資料欠帳另由 FU-145 承接，本輪不修資料。

P2-1～P2-6 設計與實作均已通過，P2 下行仍待另行授權及正式發布流程；P3 尚待完成，ADR 維持 Proposed。既有證據原位與接受指紋保留；blocked 不新增交付閘門，保留本次有效成果精確交付出口。FU-126／FU-134、FU-143／FU-144／FU-145 獨立追蹤，本輪不清理或部署。

2026-10-20：P3 設計第 2 輪審閱通過​

P3 設計已通過第 2 輪審閱（受審 revision r2-a2b1504b61f97ef6，審閱者 ada@leandev.io），完整契約及結論見文件寫入守衛 §4～§8／§13。R1-01 定義實體 workspace 與祖先別名界線；R1-02 定義既有未登記檔／waiver 的完整盤點及安裝前對帳；R1-03 明列 NotebookEdit 未覆蓋並禁止 defer；R1-04 保存三項裁決並同步 Registry §5／§6 與 D4。

設計通過不代表 hook 已實作或啟用。參考實作 57 份既有未登記檔原位保留，須完成用途／位置對帳才可安裝；現行 audit waiver 與原生接受不改。後續依規格實作共用判定、adapter／安裝器及 G1～G8 驗收，再另送實作審閱。P3 尚未完成，ADR 維持 Proposed；方法論下行與部署另依原流程，不在本次設計結案執行。

2026-10-20：P3 實作送審​

共用 check-write、Claude Write／Edit adapter、獨立安裝器及 G1～G8 驗證已接線，詳見文件寫入守衛 §14。原生演練揭露兩項修訂：bootstrap 必須先驗證 adapter stdout 再交平台；從模組啟動時明示 --settings 載入 workspace 片段。這些修訂與效能、設定競爭窗口及實測覆蓋一併交實作審閱，不由作者自行視為通過。57 份既有未登記檔仍使安裝器拒絕，settings／原生帳本未改；ADR 維持 Proposed，未啟用、下行或部署。

2026-10-21：P3 實作第 2 輪審閱通過，ADR Accepted​

P3 實作通過第 2 輪審閱（受審 revision r2-38282cca1103fcfa，審閱者 ada@leandev.io）；R1-01～R1-05 五條 minor 均經重現確認，無 open 或 declined，無 blocking／major。完整結論見文件寫入守衛 §16。定案採用 common check-write、Write／Edit 否決 adapter、驗證輸出的 bootstrap、獨立設定安裝、legacy 相容與完整未登記檔前置；模組明示 --settings、always-on 規則、WG-LOCKED／輸入診斷及 scaffold 設定責任均已補齊。接受已揭露 TOCTOU，沒有 OS CAS 或全工具覆蓋承諾。

P0–P3 逐期設計／實作全部通過，ADR 由 Proposed 改 Accepted。參考實作 57 份未登記檔仍原位保留，安裝器拒絕且不動 settings；52 份原生帳本與人工接受保留，FU-142 的對帳／正式下行／逐站安裝及 FU-145 的舊路徑修復仍待完成。Accepted 不等於已啟用或 fleet 已完成；本次未提交推送、下行或部署。