Executive map
目前成果：一套「失敗關閉」的工作流控制面
Better Workflows 的核心價值不是讓 agent 多跑幾步，而是把「路由、執行、證據、審查、副作用與完成」拆成可驗證的狀態邊界。任何關鍵 binding 不一致，結果都不是勉強通過，而是回到 blocked / indeterminate。
控制面，不是無界 runtime
repo 自己將系統定位為 governed control plane：它決定可以怎麼做、需要什麼證據與何時能進入終態；真正的 agent runtime 仍在外部。
architecture.md:6–35狀態由資料推導
TaskContract v2、ledger event、typed evidence、review package 和 provider receipt 是權威資料；自由文字 PASS、舊對話或「我已做完」不是狀態來源。
evidence-and-state.md:1–77安全性換來運作成本
多層 binding 與 7/8 witness replay 大幅提升可追溯性，也提高首次理解與環境維護成本。這是設計取捨，不是測得的使用者體驗結論。
attestations.mjs:151–245執行成功、證據有效、外部副作用已對帳、可以宣告完成是四個不同問題。Better Workflows 刻意不讓它們互相代替。
Architecture map
一條請求，經過八個權威邊界
點選節點，看每一層「接收什麼、產生什麼、不能越權做什麼」。這張圖呈現的是權威與資料方向，不代表每個 template 都必須跑完全部節點。
FACT Graph View 是 read-only projection；不是 policy engine、authority、scheduler、runtime 或 persistence。JSON 是 canonical，Mermaid 只是呈現層。 SKILL.md:182–206
Mechanism inventory
Mode 決定驗證強度；Template 決定工作骨架
Routing 先依優先序選入口與 template，再用五個風險軸推導 mode。Mode 可以被提高，不能被低於 policy floor；direct 則是刻意的例外：它不建立 governed run。
Route precedence
明確 entry / template → workspace selector → personal selector → built-in auto。Route receipt 會綁定 catalog、profile、goal、scope、capability、bundle 與 autonomy digests，並且只能 claim 一次。
routing.mjs:788–1055TaskContract v2
凍結 goal、scope、acceptance、evidence、authority、stages、gates 與 control-plane policy。Mutation authority 固定由 root 持有，autonomy 也必須明列。
core.mjs:1022–1402Template graph
13 個 template 合計 60 stages。Graph validation 檢查 cycle、dangling edge、endpoint 相容性與 provenance；目前基線 diagnostics 為 0。
graph.mjs:400–62713 governed playbooks
目前 template 全景
依 default mode 篩選。Stage 數是 TaskContract v2 的執行骨架，不等於 agent 數；GitHub Actions dispatch 目前 deferred，因 mutable ref 無法原子綁定 preflight revision；deploy / release 等尚未具 adapter 的動作也明確 deferred。
Evidence dataflow
證據不是附件，而是狀態轉移的輸入
一筆 evidence 要通過 kind contract、producer allowlist、payload schema、semantic success、freshness binding 與 digest 重算，才可能被 ledger 或 completion 使用。呼叫端自行聲稱的 acceptanceIds 會被清空重建。
10 FAMILIES
evidence-contracts-v1.json · live count
persisted evidence 在 derive state、review、action token 與 completion 階段仍會被重新載入、重新驗證。這能阻止舊證據、錯 revision 或假 acceptance 悄悄通過。
Ledger laboratory
狀態不是存下來的結論，而是事件重播的結果
下面是縮小版教學模擬。真實 reducer 會校驗 TaskContract v2、stage dependency、固定 budget、root actor、expectedLedgerDigest 與 typed evidence；這裡只用來建立操作直覺，不是 production runner。
依序加入事件
觀察 ready set 與 task state 如何由 event log 推導。你不能直接按「完成」改 state。
狀態不能憑空出現。
ledger.mjs:3–348 真實 transition 使用 expectedLedgerDigest 做 optimistic concurrency；stale writer、未知 dependency、cycle、超 budget 或無 typed evidence 的 complete 都會失敗。
Review → action → completion
副作用不是「呼叫完」就算完成
對 merge、push、cache publish 等外部動作，系統先凍結 exact review identity，再發出一次性短效 token，透過固定 provider wrapper 執行，最後以 receipt 對帳成 success / failure / unknown。Unknown 絕不能靠盲目重試消失。
base/head/mergeBase/scope/diff/contract/template/sentinel 全綁定。
P0 不可 accepted-risk；P0/P1 必須清空，critical 還需獨立 critic。
檢查 authority、ledger readiness、evidence、provider adapter 與 current sentinel。
預設 300 秒；hash 綁定、一次性、固定 executable / argv。
provider receipt 對帳 terminal outcome；unknown 保持 indeterminate。
再次 capture sentinel，重驗 evidence、ledger、review、remote/cache live state。
Review identity
Finding ID 穩定；review package 也綁定 declared reviewProfile digest。Legacy profile 不冒充 kernel；只有 self-improve pilot 具 exact work-unit、source-quote 與 finder/verifier separation，且仍是 shadow-only。
Action authority
Token 不只是 nonce：它綁 action request、contract、source、review、evidence、provider、remote 與 idempotency key；consume 時全部重驗。
core.mjs:5016–5803Terminal decision
completion 前後各 capture 一次 source sentinel，並把 evidence、ledger、review、sentinel digests 寫入 completionDecision；任何 drift 都是 inconclusive。
core.mjs:2335–2803Replay taxonomy
Replay 不是一件事：程式中至少有三種語義
它們共享同一個精神——從持久化、可驗證的輸入重建結論——但輸入、輸出與失敗策略完全不同。切換頁籤比較，不要把 evaluator replay 誤認為 ledger replay，也不要把 reconciliation 當重送請求。
公開 state contract 明確說明：resume 從 run directory、contract、ledger、evidence、review、receipt 與 sentinel 繼續；不還原 hidden reasoning，也不以舊 transcript 當 authority。
Self-improve evaluator replay
真正被重播的是固定 corpus、快照、prompt 與 host witness
Self-improve v2.4 不從歷史對話「學習」。它比較 immutable baseline 與 candidate snapshot，使用固定 evaluation corpus；host 以 tool-free、single-request、strict JSON 方式產生 7 或 8 個獨立 witness，sbw 再離線重建 prompt、驗簽、計分與重算 comparison。
Purpose selector
每個 class 同時覆蓋 train 與 holdout；64 assertions 中 34 個標記為 hard-safety。
eval corpus v2.4 · live countbaseline 三次、candidate 三次，取 per-case median；migration 另外加入 train baseline，總數成為 8。
self-improve.mjs:1393–1522canonical Responses body 明列 tools: []、tool_choice: none；transcript lifecycle 要完整且 observedToolCalls=0。
host-trust.mjs:350–391Trust boundary
Repo 能描述政策；Host 才能證明它真的照政策執行
Critical evaluator 的信任根不在可被 candidate 修改的 repository 裡，而在固定 host path、root-owned bundle、簽章 manifest 與 launcher。這條鏈同時限制 executable、cwd、run-as 身分、請求內容、上游與 witness 生命週期。
clean worktree、full SHA、candidate / baseline digests
root status 綁定 path、binary、schema、compatibility
絕對 root-owned executable、固定 cwd、drop uid/gid
nonce-bound、本機單次入口、固定 upstream
single user input、tools off、strict JSON schema
request / response / runtime / model / issuer 綁定
驗簽、distinct witness、重建 prompt 與 comparison
它防的是什麼？
Candidate 不能靠修改 repo 內 evaluator、prompt 或 transcript 就替自己背書；run-as 與 host bundle 也必須對得上 standing consent 與 immutable manifest。
attestations.mjs:166–439平台邊界
RISK 固定 /usr/bin/sudo、root-owned host path、Mach-O / launcher 等機制顯示 critical host trust 目前高度依賴 macOS / Unix host 假設；repo 內沒有跨平台等價實作的證據。
Bounded autonomy
Autopilot 是有簽章的權限預算，不是「全自動」開關
Profile 綁定 repo、branch、worktree、expiry 與數量限制；每個 action 先分類成 automatic、human-required 或 denied。Preflight 不成立時留下可 resume 的 blocked state，而不是降級繞過。
| Decision | 可做的事 | 為什麼 |
|---|---|---|
讀取、測試、evaluator replay、commit、cache publish、推送 codex/*、建立一個 dev PR | 所有動作仍要通過 source、contract、ledger、review、token、provider 與 reconciliation gates。 | |
| host boot / upgrade / revoke、merge、deploy、推 dev/main、cleanup | 屬於信任根變更、共享分支或不可逆 delivery 邊界。 | |
| 密碼／互動 sudo、無界 shell、admin bypass、未 pin 的 executable | 不能用 consent 擴大成任意 host authority。 |
Immutable publication
Cache 發布分成「檔案已落地」與「結果可被信任」
Publication 採版本鎖、不可覆寫與 pending → ready 兩階段 marker。檔案 rename 完成後仍只算 pending；provider action reconciliation 成功，且 target identity / digest、run / attempt / receipt 全部相符，才會 promote ready。
Election
two-phase lock、process incarnation digest；未知或仍活著的 owner 不可被接管。
Exact snapshot
只接受 clean source binding、committed snapshot 與精確 bundle digest。
Rename + marker
immutable version，不覆寫；marker 綁 source、run、attempt。
Provider truth
provider receipt 對帳；unknown 不可冒充 failure 或 success。
Promotion
同一 version lock 下驗證 target identity / digest 與 exact receipt 後完成。
Crash recovery
Recovery 只能針對同一 source/run/attempt/pending marker 與既存 target 繼續；它不重新 publish。這把「重試」轉成「查明既存 side effect」。
publication.mjs:2109–2189Stale lock
釋放前先 quarantine；只有能證明 process incarnation 已不存在才能回收。macOS identity 綁 PID、boot time 與 process start；任一資訊不可讀都回到 unknown，而不是冒險接管。
publication.mjs:704–787 publication.mjs:867–1149Strengths, risks & unknowns
做得好的、需要盯住的、目前不能證明的
這一章刻意把程式可直接證明的 fact，與研究者的 inference / risk / unknown 分開。風險不是 bug 清單；unknown 也不是負面評價，而是 repo 證據的邊界。
信任邊界具體
Source、contract、evidence、review、action、provider、host 全有獨立 identity 與 digest；關鍵流程普遍採 fail-closed。
Replay 可重算
Ledger reducer、evaluator comparison 與 provider reconciliation 都以 persisted inputs 重建，不需要信任對話記憶。
副作用可對帳
一次性 token、fixed wrapper、idempotency key、terminal receipt、pending/ready publication 把「執行」和「完成」拆開。
核心模組集中
core.mjs 約 6.6k 行、CLI 約 2.5k 行。這不證明品質差，但意味變更 blast radius、review 認知負擔與拆分需求值得持續觀察。
驗證成本可觀
26 個 lib 模組約 23.4k 行，18 個 test 檔約 18.3k 行、379 cases。深度是優點，也會帶來全量 eval 時間與維護成本。
live inventory可視性刻意受限
Graph View 只投影 allowlisted structure，避免暴露敏感 payload。代價是 live observability 不等於完整 trace viewer；文件與工具不能過度承諾。
graph.mjs:183–397實際採用與體感
repo 沒有 production usage telemetry，因此無法從原始碼判定使用頻率、平均完成時間或使用者最常卡住的 gate。
跨平台等價性
一般 Node 控制面可能可攜，但 repo 證據不足以證明 critical host trust 在 Linux / Windows 有相同保證。
Live provider readiness
本次是 source-bound 文件研究，沒有使用外部 credentials 執行 merge、push 或 publish，因此不把 live provider 狀態列為已驗證。
本次以 current implementation baseline 執行 docs、fixtures、skills 與 graph checks；reviewProfile bindings 與 101-kind catalog 均可重驗。完整 evaluator replay、cache publication 與 provider delivery 仍由各自 workflow gate 管理，不能從本次文件檢查推導 side-effect authority。
Reading lenses
同一套系統，三種閱讀高度
切換你的角色。新手先建立安全直覺，資深工程師追 identity 與 state derivation，CTO 則關注 authority、failure domain 與可營運性。
先懂四個名詞
Template 是骨架；Mode 是驗證強度；Contract 是範圍與權限；Evidence 是能改變狀態的型別證明。
跑無副作用命令
從 help、templates、graph validate 與 eval 開始。先看輸出與 diagnostics，不直接碰 action token。
Blocked 是正常狀態
缺 evidence、source drift 或 provider unknown 並非工具壞掉；它是控制面拒絕假裝確定。
沿 digest 讀程式
從 route receipt → contractDigest → sourceBindingDigest → ledgerDigest → reviewPackageDigest → action / receipt → completionDecision。
找 reducer，不找 mutable flag
Ledger 與 replay 的核心問題是：「這個狀態能否由 canonical input 重算？」修改時優先保持 deterministic derivation。
測 stale、drift、unknown
Happy path 之外，重點是 stale digest、double consume、provider unknown、crash recovery、wrong head 與 unauthorized producer。
誰能改什麼？
Root-only mutation、signed standing consent、autonomy budget 與 human-required actions 形成可稽核責任邊界。
安全是否可營運？
要量測 blocked reason、eval latency、witness failure、reconciliation unknown、host bundle drift 與 recovery 成功率。
下一個槓桿點
優先降低核心模組認知負擔、補足可觀測指標、明定 host platform matrix，再擴充 provider adapters。
Senior checkpoint
資深工程師的 code review 核心：binding 是否完整、derivation 是否可重算
每次新增欄位或 action，都要問：它進入 canonical digest 了嗎？persist 後會重驗嗎？stale writer 會被拒絕嗎？unknown 是否可能被錯誤壓成 failure？
CTO checkpoint
CTO 的判斷題：證據治理是否同時帶來可營運的交付速度
目前 source 顯示強健的 authority 與 fail-closed 設計；下一步管理證據應聚焦實際 blocked 分布、端到端 lead time、recovery 效率、host 維護成本與 provider coverage，而非只看 test 綠燈。
Change code safely
改 Code 守則：從 contract 邊界往外推，不從 UI 往內猜
控制面程式的 bug 常出現在「新增功能但漏綁 identity」或「錯把 unknown 當 failure」。以下是最小且可重複的修改順序。
新增 evidence kind
- 先在 evidence contract 定義 producer、family、required fields、freshness 與 success predicate。
- 讓 admission 重算 payload digest；不要信任 caller acceptanceIds。
- 補 positive、wrong producer、stale revision、bad digest、semantic failure 測試。
- 確認 ledger / review / completion 消費端會重新驗證。
新增 side-effect action
- 先定 authority 與 exact contract gate，再建立 fixed provider adapter。
- Token 綁 source、review、evidence、remote/resource 與 idempotency key。
- 只允許 wrapper execute；consumer 端再次重驗所有 binding。
- 設計 success / failure / unknown reconciliation 與 crash recovery，再談 retry。
修改 ledger / stage
- 保持 event append-only、static dependency、acyclic graph 與固定 budget。
- 新增 event 時更新 reducer 與 canonical digest，而不是新增 mutable shortcut。
- 測 concurrent stale ledger digest、budget exhaustion、invalid transition。
修改 self-improve evaluator
- 分清 ordinary policy change、evaluator migration、safety remediation、quality remediation。
- Corpus/version/migration 要保持 inherited coverage 與 target-only headroom。
- Prompt、snapshot、host request 與 replay reconstruction 必須完全同源。
唯讀導覽
完整驗證
測試綠燈只能證明已覆蓋的 contract；它不能授權 merge、deploy、host trust 變更或外部 side effect。先定權限與 reconciliation，再補實作。
Source explorer
每個重要判斷，都能走回原始碼
以下 locator 以本次觀測 revision 為準。可依類型篩選；FACT 是程式或文件直接陳述，INFERENCE / RISK 是研究解讀，UNKNOWN 代表本次 source scope 無法證明。
observedAt: 2026-08-15T00:05:00+08:00 · revision: c5abd1fe7c580773c1cacb81dc0c01b58bf086d6 · worktree: clean · scope: working tree + HEAD · installed template sourceDigest: f1371f5477f6650a7d8999b7d2d8e99437db7286b75a8ef488cd31f56db3c8ab
validatedAt: 2026-08-15T00:05:00+08:00 · graph diagnostics: 0 · review-profile binding checks: PASS · evidence catalog: 101 kinds
snapshotBoundary: implementation baseline c5abd1f；本次文件同步新增 review capability profiles、101-kind catalog 說明與 HTML source locators；未執行 provider side effects。