spec-to-done

spec-to-done — 指揮官手冊(主對話 SOP)

把一份已經使用者核准的 spec(brainstorming 產物)自主推進到 merged PR + browser evidence + 四項回報。 主對話 = 指揮官:只做 (a) phase 之間讀 StructuredOutput 比 gate 規則、(b) 配 args、(c) 命中強制停下點就輸出 hold block。苦工全在 named workflows 的 subagent(獨立 context)。

本技能是 Lane S 的明確 opt-in 流程；agents/openai.yaml 已禁止 implicit invocation。不得因任務非平凡、文字含「完成」、changed path 位於 code/tests，或模型主觀判斷而自行啟動。

Source of truth 聲明:本檔是 spec-to-done 的 Codex adapter copy；程序 gate / resume / evidence / ship 語義必須精準對齊 .claude/skills/spec-to-done/SKILL.md。phase 集合、durable state canonical path 與完整 closed held enum 的 machine source of truth 是 agent-contracts/spec-to-done.contract.json；本檔不複製完整 raw enum。std-*.js 與 ship-item 的 canonical runtime 仍在 .claude/workflows/(compose,不重造)，但 P6 目前依量測 runtime capability fail closed，Codex 不得假裝它已可 merge。

Machine contract（Claude/Codex 共用）

• phases 必須逐字等於 contract 的 P0,P1,P3,P4,P5,P6,P7；不存在 P2。
• durable state 唯一路徑是 contract 的 artifacts/spec-to-done/{slug}-state.md。
• reason= 只能取 contract durable_state.held_reasons 的 closed enum；低階補充只能寫 heldDetail／診斷=，不得創造新 reason 或複合 reason。
• .claude/skills/spec-to-done/validate-state.mjs 是兩平台共用 validator，直接載入 machine contract；contract 缺失、malformed 或 state 值不在 closed enum 都 fail closed。

Codex 對齊補充(只配接,不改 gate)

• Workflow({name:'std-plan' | 'std-implement' | 'std-evidence' | 'fu-adversarial-verify-generic' | 'ship-item', args:{...}}) 在 Codex copy 仍代表同一個 phase contract:相同 args、相同 StructuredOutput 欄位、相同 retry / HELD / resumeFromRunId 語義;不得用「Codex-native phase mapping」替代或省略 P4/P5/P6。
• 若當前 Codex host 沒有 Claude workflow runtime,指揮官必須用可用 native subagents / workflow artifacts 產生等價 StructuredOutput;若無法產生等價 StructuredOutput,必須 HELD,不得 parent-only 手跑後視為通過。缺欄位、null reviewer、verdict 數量不符、無 browser evidence 一律依本檔 gate 重呼或 HELD,不得視為通過。
• 在 Codex host 中,Workflow(...) 的 host-side 等價操作是 ultracode-style workflow discipline:主 agent 編排、必要時 native subagents、artifact、StructuredOutput、gate、驗證與 HELD。這不是 Claude Code dynamic workflow runtime、不是 /workflows UI、也不代表 .claude/workflows/*.js 可在 Codex 直接執行。
• P0→P1→P3→P4→P5→P6→P7 的跳號排序不可整理成 P0-P7 連號;文中的 production P1/P2 / 真 P1/P2 是 quality / production blocker 等級,不是主對話新增 phase。
• spec-to-done 的請求本身即授權本流程推進到 merged PR;不要加入「commit / push / PR / merge 必須另行明確要求」的 Codex-only 限制。只有本檔列出的 consent carve-out / destructive / production-data / credentials / billing / user-account 類 gate 需要再停下。
• Claude hook 不會自動帶入 Codex session:目前 Codex CLI 支援 repo/global hooks，但本 repo 未配置與 Claude commit/browser hooks 完全等價的 Codex hook。P6 仍由指揮官顯式把關：(a) commit 前確認 verify、diff scope 與 message；(b) user-facing merge 前確認近 24h browser screenshot/trace，否則 HELD。
• 知識圖譜雙源(見下節)在 Codex 與 Claude 同義:GitNexus = 合規主源、codebase-memory = advisory 第二意見。若當前 Codex host 未掛載某套 MCP server → 缺的那套降為「第二意見不可用」並在 note 註明,不得因第二圖譜缺席或分歧翻轉任何 gate;GitNexus 仍為唯一 risk/scope 判定來源。
• Codex native subagent 一律用 fork_turns:"none" 或完成該 bounded task 所需的最小正整數 window，禁止 full-history fork。 同一 reviewer 的 retry / 修正優先用 follow-up 重用既有 agent；同時最多 2 個 live subagents。每次 spawn / follow-up 都計入 agentCalls，state 的 runIds 必須記 codex:<actual-session-or-agent-id>，不得寫 native-* 描述標籤。

Claude/Codex 對齊契約(防 drift)

.claude/skills/spec-to-done/SKILL.md 是程序 gate / resume / evidence / ship 語義 canonical；machine phases、durable path 與 closed held enum 以 agent-contracts/spec-to-done.contract.json 為準。.codex/skills/spec-to-done/SKILL.md 只能作為 Codex adapter copy。兩份檔案可有差異,但差異必須落在下列白名單。

允許差異:

• Source-of-truth 文字可說明 Codex copy 仍以 Claude canonical 為準。
• Codex 可補充「無 Claude Workflow runtime 時如何產生等價 StructuredOutput / 何時 HELD」。
• Codex 可把 Workflow(...) 的 host-side 執行方式映射為 ultracode-style workflow discipline,但不得宣稱與 Claude Code dynamic workflow runtime 等價。
• Codex 可把 Claude haiku / sonnet / opus / fable routing tier 映射到可用 GPT model / reasoning effort。
• Codex 可補充 CLI 無 Claude hook 時的手動 commit / gstack gate 等價把關。
• Codex 可列出 .codex/skills/spec-to-done/ensure-host-native-ports-free.ps1 作為 helper fallback,但 helper 內容必須與 .claude copy 一致。
• Codex 可補充 .codex/** tracked whitelist 與 PR review 約束。
• Codex 可額外產出 runDir machine artifacts(artifacts/spec-to-done/<slug>/ 下的 capability-snapshot.json、workflow-ir.json、acceptance-evidence-map.json、risk-register.json、parameter-provenance.json、human-approval-points.json、state.jsonl、event-log.jsonl、attempt-ledger.json、command-provenance.json、evidence/evidence-ledger.json)——advisory 痕跡,不參與任何 gate 判定;Claude 端不要求產出。

禁止差異:

• 不得改 P0/P1/P3/P4/P5/P6/P7 的 phase 順序、gate 條件、HELD 值語義或 resume contract。
• 不得把 userFacing=true 的 browser evidence gate 降級成 source inspection / unit test。
• 不得讓 codebase-memory 取代 GitNexus 的正式 risk/scope 判定。
• 不得把 ultracode-style discipline 說成 Claude Code /effort ultracode、dynamic workflow runtime、/workflows UI 或背景 workflow manager。
• 不得加入「需要另行授權 commit / push / PR / merge」來覆蓋本檔既有 spec-to-done ship 語義;只有 consent carve-out 類別可再停。
• 不得移除 P5 adversarial review、P6 ship-item、OpenSpec / pr-review-agent / GitNexus fallback 揭露等 gate。
• 不得在 Codex copy 自行創造與 .claude/workflows/*.js 不相容的欄位或 StructuredOutput 名稱。
• 不得使用 machine contract closed enum 以外的 held 值或複合值；環境阻斷一律 host_env_blocked。
• 不得在 state 行使用「State 行詞彙」白名單外的行首 token、英文 schema 欄位(diagnosis= / need= / stateSchema=)或 P2 phase 編號。

改任何一份 spec-to-done skill 時,同一 PR 必須跑 drift check:

git diff --no-index -- .claude\skills\spec-to-done\SKILL.md .codex\skills\spec-to-done\SKILL.md

審查時只接受上方白名單差異;其餘 phase / gate / evidence / ship 語義差異一律視為 blocker。

四套工具的唯一切入點(AGENTS.md anti-patterns 防線)

知識圖譜雙源交叉驗證(advisory,不改 gate)

兩套知識圖譜:GitNexus = 合規主源(所有 gate 的 risk/scope 判定唯一依據),codebase-memory(mcp__codebase-memory-mcp__*)= advisory 第二意見。三種用法皆加法式,絕不讓第二圖譜翻轉任何 gate:

• (a) 並列佐證:P1 impact 預掃 / P3 per-task impact 跑 GitNexus 同時,並列查 codebase-memory(trace_path inbound / search_code),差異寫 advisory note。
• (b) UNKNOWN/crash fallback:GitNexus 回 UNKNOWN 或 LadybugDB crash 時,用 codebase-memory 取第二意見寫 note 供指揮官 resume 判斷;held 照常觸發、不自動解除。
• (c) 提速導航:不限 spec-to-done——plan / 實作階段與一般互動對話的 code analysis 先用 GitNexus query/context;codebase-memory 的 search_graph(name_pattern) / get_code_snippet(qualified_name) / trace_path 只能並列作為第二意見、GitNexus UNKNOWN/crash/unavailable 時的 advisory fallback,或用於非 gate 的快速定位後再回 GitNexus 交叉確認。雙查同一 message 可並列發出,但不得把 codebase-memory 當第一順位或取代 GitNexus discovery。

四不變式(寫進每個 impact prompt 的硬約束):

1. overallRisk / perSymbol.risk / taskImpact.overallRisk 只由 GitNexus 決定;codebase-memory 差異即使更大也不得升降 risk、不得寫 blockers。
2. codebase-memory 只寫 advisory 自由字串欄位(perSymbol.note / taskImpact.note / impl concerns)——被所有 gate 條件結構性忽略。
3. GitNexus 正常時不參與分級(只做 a/c);UNKNOWN/crash 才 fallback(b),結論仍 UNKNOWN → held 不變。
4. 方向:trace_path inbound ≡ impact upstream、outbound ≡ downstream。建模差異(節點數/術語/process)不報;只報「symbol+檔路徑對得上卻 caller 集不同」。特例:GitNexus 回 0/LOW 但 codebase-memory 找到 caller(實測 deriveIntakeFromKey)→ note 醒目標『GitNexus 疑有盲點、手動覆核』,仍不自動翻 gate。

觸發與 args(主對話填;workflow 不自取)

使用者句型:「用 spec-to-done 跑 docs/superpowers/specs/<檔>.md,user-facing」。主對話補齊:

specPath     spec 絕對路徑(必填;不存在 → 停,要路徑)
slug         spec 檔名去掉日期前綴與 -design 後綴(例 2026-06-15-demo-feature-design.md → demo-feature)
dateStamp    今天 YYYY-MM-DD(主對話算;workflow 內禁時鐘/亂數 API)
branch       feat/<slug>(或 fix/ chore/;絕不在 main 開發)
userFacing   spec 是否含使用者可操作介面(看 spec;不確定當 true)
worktreeRoot worktree 的「絕對路徑」(P0 建立後填;std-*.js 都用它串路徑,不可相對)
executionMode `full`(預設)或 `evidence-closeout`;不得在 resume 時切換
changePath   `evidence-closeout` 必填:已核准 OpenSpec change 的絕對路徑
closeoutTaskIds `evidence-closeout` 必填:明確且不重複的 task IDs(禁 wildcard/整個 change)

每個新 run 固定同一組上限，跨 phase / retry / resume 累計，不得重設：

maxAgentCalls=40; maxP5VerifierBatches=2; maxP5Rounds=2; maxEvidenceAttempts=2

remainingAgentCalls=maxAgentCalls-agentCalls.used 必須傳入每個 std-* / fu-* 等價 workflow；回傳的 agentCallsUsed 立即累加後才可決定下一步。P6 每次 ship-item 等價 workflow 呼叫另計 1 call。任何計數到頂、 workflow 試圖超額、或 resume 缺少可信計數，一律 fail-closed，不可用新 session / 新 run ID 歸零。

P0 指揮官開場(主對話親自做)

1. executionMode=full:讀 spec 全文;自檢 placeholder / 內部矛盾 / scope 歧義 → spec 矛盾 = HELD(spec 是唯一忠實源,agent 不得擅自補)。 executionMode=evidence-closeout:只在已核准 OpenSpec proposal/spec 明載 production / contract 已落地，且 closeoutTaskIds 每一項都只需 evidence、docs 或該 change 的 task ledger 時成立。P0 逐 ID 做 scope lock； 任一項仍需 production source、UI、public contract、dependency/config 變更，或語意不明，一律 HELD@P0 reason=scope_drift，不得退回 full mode 自動擴張。userFacing 沿用 change 真實分類，不得為跳過 P4 改成 false。
2. 偵測隔離:git rev-parse --git-dir ≠ --git-common-dir → 已在 linked worktree,直接用(絕不疊加)。在主 checkout 時:
   • .worktrees/<slug>/ 已存在(前次 held 殘留)→ 沿用,worktreeRoot 指向它,確認 branch 正確即可。
   • 否則:git fetch origin +refs/heads/main:refs/remotes/origin/main → git worktree add .worktrees/<slug> -b <branch> origin/main。
   • worktree 不帶 ignored/local artifact(storage/ 真 IFC、node_modules、.venv)— 讀主工作區絕對路徑或 worktree 內 npm install。
3. TodoWrite 建 P1–P7，記錄目前 git rev-parse HEAD 與四個固定上限。每次 native subagent / 等價 workflow 只記實際 codex:<session-or-agent-id>，不得以 native-* 描述標籤代替。每個 phase 結束先累加計數，再寫 state(見 Resume)。

編排(可複製;gate 讀 StructuredOutput 布林/枚舉)

⚠ Workflow 的 args 必

Content truncated.