From b78c65bc05fb73b9bc7cf574846f6244469302da Mon Sep 17 00:00:00 2001 From: screenleon Date: Thu, 30 Jul 2026 15:36:13 +0900 Subject: [PATCH 1/2] docs: replan v0.11 and v0.12 roadmap --- BACKLOG.md | 306 +++++++++++++++++++++++++++++++++++++++++++++++--- DECISIONS.md | 42 +++++++ MILESTONES.md | 122 ++++++++------------ 3 files changed, 383 insertions(+), 87 deletions(-) diff --git a/BACKLOG.md b/BACKLOG.md index f3b395f9..973c589b 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -49,6 +49,16 @@ CC-001/CC-002 were consumed by PR #24 fix bundle inline, with no standalone entr | CC-527 | 🔵 active | targeted gate CLI 拆分 pass、reviewer coverage 與 tier，避免 full targeted 語意重疊 | ux/gate | 2026-07-28 | feedback:2026-07-28 | P2 | design | | CC-528 | 🔵 active | publish policy compatibility：generic 為可接受 baseline、maintainer 為 preferred，並允許 ship 驗證既有 current-tree Gate artifact | release/gate | 2026-07-30 | feedback:2026-07-30 | P1 | design | | CC-529 | 🔵 active | publish assurance observability：在 ship 成功輸出、PR body 與 finish marker 保留 embedded policy 與 baseline/preferred satisfaction | release/gate | 2026-07-30 | feedback:2026-07-30 | P2 | hygiene | +| CC-530 | 🔵 active | source-safe runtime library contract + centralized domain identifier policy | arch/reuse | 2026-07-30 | feedback:2026-07-30 | P1 | hygiene | +| CC-531 | 🔵 active | Adapter manifest contract closure：dispatch entrypoint 成為唯一 runtime authority | arch/schema | 2026-07-30 | feedback:2026-07-30 | P1 | design | +| CC-532 | 🔵 active | Gate canonical modules + generated standalone distribution + parity fixtures | arch/gate | 2026-07-30 | feedback:2026-07-30 | P1 | reuse-debt | +| CC-533 | 🔵 active | schema-derived Gate structural validator，手寫 verifier 只保留跨 artifact semantics | schema/gate | 2026-07-30 | feedback:2026-07-30 | P1 | design | +| CC-534 | 🟢 someday | `commands.tsv` 驅動 CLI routing、safe handler dispatch 與 lazy module loading | arch/DX | 2026-07-30 | feedback:2026-07-30 | P2 | design | +| CC-535 | 🟢 someday | detached-launch 上的 supervised-run primitive + versioned JSON run-spec | arch/ops | 2026-07-30 | feedback:2026-07-30 | P2 | design | +| CC-536 | 🟢 someday | 擴充 Adapter SDK 的 shared lifecycle／manifest／trace contract，保留 executor-native behavior | arch/reuse | 2026-07-30 | feedback:2026-07-30 | P2 | reuse-debt | +| CC-537 | 🟢 someday | suite metadata 與 changed-path impact mapping 資料化；full suite 維持 authoritative | ops/test | 2026-07-30 | feedback:2026-07-30 | P2 | hygiene | +| CC-538 | 🟢 someday | Host resolver／doctor 共用 primitives，Host policy 繼續由各 Host 擁有 | arch/ops | 2026-07-30 | feedback:2026-07-30 | P2 | reuse-debt | +| CC-539 | 🟢 someday | state `layout.yaml` build-time authority + generated runtime constants | arch/schema | 2026-07-30 | feedback:2026-07-30 | P2 | design | | CC-465 | 🔵 active | memory/context 關鍵詞管線 CJK 支援：抽出共用零依賴斷詞 lib，取代三處各自 ASCII-only 抽詞；工作序列起點（465→467→468→466）（2026-07-07 記憶系統深入分析） | memory | 2026-07-07 | feedback:2026-07-07 | P2 | retrieval | | CC-466 | ⏸ deferred | 記憶卡片生命週期閉環：expires_at 執行 + 關窗式 supersede + usage sidecar 休眠偵測 + doctor→distill 接線；僅在 CC-467 證明 stale/dormant card 已形成實際問題時啟動 | memory | 2026-07-07 | feedback:2026-07-07 | P2 | retrieval | | CC-467 | 🔵 active | `pmctl memory stats`：注入效益可視化（唯讀聚合器）——注入 bytes/卡片命中分佈/從未命中卡/episode 填寫率，回答「記憶有跟沒有差在哪」；排在 CC-466 之前（2026-07-07；業界僅離線 recall 評測，無 per-injection 遙測） | DX/memory | 2026-07-07 | — | P2 | retrieval | @@ -59,8 +69,8 @@ CC-001/CC-002 were consumed by PR #24 fix bundle inline, with no standalone entr | CC-018 | 🟢 someday | Codex quota 自動追蹤 + rate-limit 路徑統一（吸收 CC-269）：寫到 `~/.local/share/pm-dispatch/state/rate-limits.json`；解析 API response headers；token-usage.sh 加 Codex pool 顯示 | ux/token | 2026-05-14 | — | P3 | — | | CC-023 | ⏸ deferred | `coupling-reviewer`：PR gate 加入語言感知耦合分析（dependency-cruiser/gocyclo/coca） | ops/gate | 2026-05-14 | — | — | — | | CC-026 | 🟢 someday | `/skill-distill`：偵測重複工作流，產出草稿 skill .md | ux/memory | 2026-05-15 | — | P3 | — | -| CC-032 | 🔵 active | `[[feedback_*]]` cross-link 公開化：抽到 `docs/policies/` glossary 避免 dead link（v1.0 前置；v0.14.0 contract candidate） | process/DX | 2026-05-15 | — | P2 | — | -| CC-033 | 🔵 active | public posture reconciliation：README/協作表面 + **即刻** git history 損害盤點（audit 先行；其餘 v0.14.0） | process | 2026-05-15 | — | P2 | — | +| CC-032 | 🔵 active | `[[feedback_*]]` cross-link 公開化：抽到 `docs/policies/` glossary 避免 dead link（v1.0 前置；v0.12.0 contract candidate） | process/DX | 2026-05-15 | — | P2 | — | +| CC-033 | 🔵 active | public posture reconciliation：README/協作表面 + **即刻** git history 損害盤點（audit 先行；其餘 v0.12.0） | process | 2026-05-15 | — | P2 | — | | CC-035 | 🟢 someday | install/uninstall-guards basename+scripts/ heuristic：未覆蓋另一工具也在 scripts/ 下同名 hook 的 collision edge case | ops | 2026-05-15 | pr:#53 | P3 | — | | CC-038 | ⏸ deferred | Windows/cross-platform 鎖機制：`flock` Linux-only，未來支援需替代方案（parked: CC-370） | ops/portability | 2026-05-15 | — | — | oss | | CC-044 | ⏸ deferred | `tool-trace.jsonl` 三階段升級（吸收 CC-027b/c）：Phase 1 rotation/retention；Phase 2 bounded error counter；Phase 3 async validation | ux/memory | 2026-05-15 | — | — | — | @@ -109,7 +119,7 @@ CC-001/CC-002 were consumed by PR #24 fix bundle inline, with no standalone entr | CC-390 | ⏸ deferred | codex dispatch trace-capture 強化（FD inheritance cold-start flake；fail-closed safe；resume: stable repro；umbrella: CC-333） | arch/portability | 2026-06-15 | — | P3 | design | | CC-393 | 🟢 someday | design: portable-skill-substrate — CLI-agnostic skill 控制層（design seed after v0.6.0 N≥2；3 control skills + Portable Skill v0 frontmatter；umbrella: CC-333） | arch | 2026-06-16 | — | — | design | | CC-435 | 🟢 someday | **[poll→通知機制 single-waiter guard：條件觸發，非既定後續票]** 只有在真正出現多個 waiter 需要同時等待同一個 run_id/gate_id 的場景時才拿出來討論；候選設計見 `docs/spikes/CC-433.md` Open risks（方案 A：`flock` 搶鎖+敗者退回輪詢；方案 B：per-waiter 專屬 fifo+supervisor 廣播）。CC-434 完成後重新盤點成本效益：輪詢 vs blocking read 在單一 waiter/數分鐘等待場景下資源消耗差距趨近於零，延遲改善（≤2s→近乎即時）對人在等 gate 結果無感，而兩個方案都要在安全敏感的 supervisor 檔案引入新 race condition，投資報酬率目前不足，故不排入既定實作，僅記錄設計供未來觸發條件成立時起步。 | arch/gate | 2026-07-02 | — | P3 | design | -| CC-446 | 🔵 active | public contract candidate：stable/experimental CLI + schema、SemVer/deprecation 與 CC-296 清掃（v0.14.0；非 v1 RC） | process/DX | 2026-07-04 | — | P2 | design | +| CC-446 | 🔵 active | public contract candidate：stable/experimental CLI + schema、authority 分類、SemVer/deprecation 與 CC-296 清掃（v0.12.0；非 v1 RC） | process/DX | 2026-07-04 | — | P2 | design | | CC-447 | 🔵 active | onboarding 三 smoke：offline clean install + N-1 upgrade（v0.11.0）+ live dogfood（readiness review 後再排） | docs/ops | 2026-07-04 | — | P2 | — | | CC-449 | ✅ done | release evidence parity：suite registry、CI parity、OpenCode（吸收 CC-431）、ship/worktree smoke（v0.11.0） | ops/test | 2026-07-04 | pr:#439 | P2 | — | | CC-472 | 🟢 someday | spike: antigravity（`agy` CLI）host 唯讀 probe——比照 CC-436/CC-448 階段 1 模式，實測 command 載入能力 + hook/plugin 機制 + 五個 capability enum 的 provider/confidence 判定，不落地 `hosts/antigravity/host.yaml`；排在 CC-445 通用 install/uninstall dispatcher 之後、與 CC-448 opencode 同批或緊接其後評估（N=3 驗證點） | arch/install | 2026-07-08 | — | P3 | spike | @@ -158,10 +168,14 @@ _Terminal_ (CC-378: swept OUT to `BACKLOG-ARCHIVE.md` by `ops/backlog/archive-cl 3. 執行 [[CC-296]] deprecation 清掃（已過 v0.3.0 起多個正式版本）。 4. deprecated surface 全清點：README 仍列已標 deprecated 的 `pr-gate-handover-schema.md`（executor-contract 已明言該 fan-out 路徑 retired）——去留與 README 目錄同步，消除自相矛盾。 5. **契約可驗證性盤點**（2026-07-06 盲測稽核擴充）：(a) stable CLI 分級準則納入 `--json` 支援一致性——現僅約半數子指令支援（task/dispatch/ship/memory/worktree/trace/decision 有；backlog/guard/artifacts/gate/context/validate/pre-release 無），列 stable 的讀取型子指令應有結構化輸出或明文排除；(b) 「schema 承諾與行為不符」項逐一定案去留，如 `core/state/layout.yaml` 的 `threshold_days`（宣告但未實作，rotation 只看 bytes）。與 [[CC-451]] 同批評估——runtime 從不驗證的 schema 不應列 stable。 +6. 每份候選 manifest、schema、registry、policy 與 layout specification 都標記為 + `runtime authority`、`build-time authority` 或 `parity/documentation + specification`；runtime/build-time authority 必須有單一 consumer/generator + 路徑與 drift check，不得一面宣稱 source of truth、一面維護等價手寫實作。 **Done-when**：分級表覆蓋全部 pmctl 子指令與 schema 檔；CC-296 清掃完成；repo 內無「標 deprecated 但無移除計畫」的懸空表面；README 與分級文件互相一致。 -**Dependencies**：吸收 [[CC-296]] 執行。[[CC-451]]、[[CC-460]] command inventory、[[CC-498]] state compatibility 為事實前置。Cross-link [[CC-286]]、[[CC-357]]。v0.14.0 contract candidate；完成後才進行 v1.0 readiness review。 +**Dependencies**：吸收 [[CC-296]] 執行。[[CC-451]]、[[CC-460]] command inventory、[[CC-498]] state compatibility 為事實前置。Cross-link [[CC-286]]、[[CC-357]]、[[CC-531]]～[[CC-539]]。v0.12.0 contract candidate；完成後才進行 v1.0 readiness review。 **See**: DECISIONS.md 2026-07-04 ## CC-447 — 乾淨機器 onboarding 雙 smoke（offline + live dogfood）🔵 active @@ -182,7 +196,7 @@ _Terminal_ (CC-378: swept OUT to `BACKLOG-ARCHIVE.md` by `ops/backlog/archive-cl **Done-when**：在 v0.11.0 release candidate 上，三個 smoke 的實測報告 committed（`docs/notes/` 或票內）；clean install 與 N-1 upgrade 都有可重現證據；摔倒點全部開票；GETTING_STARTED 修正到與實測一致。 -**Dependencies**：offline/N-1 smoke 在 [[CC-497]]、[[CC-456]]、[[CC-449]]、[[CC-503]] 後，且 v0.11.0 release freeze 中執行；live smoke 不預先綁 v1.0，待 v0.14.0 後 readiness review 排程。 +**Dependencies**：offline/N-1 smoke 在 [[CC-497]]、[[CC-456]]、[[CC-449]]、[[CC-503]] 後，且 v0.11.0 release freeze 中執行；live smoke 不預先綁 v1.0，待 v0.12.0 後 readiness review 排程。 **See**: DECISIONS.md 2026-07-04 ## CC-449 — release-verify/test-e2e：ship/worktree surface 煙測 + 套件註冊完整性 lint ✅ 2026-07-21 @@ -552,7 +566,7 @@ bare-fractional catch-all 重複的 fractional-Z 分支。Gate GO 3. 更新所有 `[[name]]` 改為 `[docs/policies/.md](docs/policies/.md)` 或 `[[]]`（若決定保留 wikilink 風格、配合 CC-030 validator 擴充驗證 link target 存在）。 4. 個人偏好類 feedback memory（不適合公開）留 local memory 不對外。 **Note**: 與 CC-030 schema validator 設計協同 — 可同 PR 加上「`[[name]]` link target 必須存在」的 validation。Blocks **CC-033**。 -**Update 2026-07-17**: 排入 v0.14.0 public contract candidate（尚非 v1.0 RC）。repo 已為 public，本票的 link-target validator 綠燈為未來 stable release 的 hard constraint。 +**Update 2026-07-30**: 排入 v0.12.0 public contract candidate（尚非 v1.0 RC）。repo 已為 public，本票的 link-target validator 綠燈為未來 stable release 的 hard constraint。 **Source**: 2026-05-15 對話 — 公開前置盤點 #3（Explore 未抓到的盲點）。 ## CC-033 — Public flip checklist 與後續觀察 @@ -567,9 +581,9 @@ bare-fractional catch-all 重複的 fractional-Z 分支。Gate GO **Update 2026-07-04（rescope：flip 前提已過時）**: 2026-07-04 實測 `gh repo view` 確認 **repo 已經是 public**（`isPrivate: false`）——本票原「flip 前防護」框架失效，rescope 為 **public posture reconciliation**（v1.0 P0，DECISIONS 2026-07-04）： 1. **即刻 git history 損害盤點**（非 flip 前防護，是已曝光後的發現與處置）：原「git history 已審 clean」結論成於 2026-05-15，之後已累積 ~250 commits（含大量 dispatch trace / memory 路徑相關工作）——重掃 secrets、個人路徑、意外入 repo 的本機 artifact；發現即處置（rotate/清除/評估影響）。 2. **README posture 一致化**：README 仍寫 "private-maintainer scoped" 而 repo 實際 public——文案改為明確的「publicly readable personal distribution, not a public support contract」定位（或依 v1.0 宣稱調整），與 CONTRIBUTING（不收外部 PR、issue 無 SLA）對齊。 -3. GitHub 設定決策照原 Requirement 1（Issues/Discussions/template/labels/CITATION.cff），在 v0.14.0 完成；觀察期留到未來 stable release 後。 +3. GitHub 設定決策照原 Requirement 1（Issues/Discussions/template/labels/CITATION.cff），在 v0.12.0 完成；觀察期留到未來 stable release 後。 4. **README 使用者表面重建**（2026-07-06 盲測稽核追加）：README 只記載 15 個 command 中的 2 個（`/pm`、`/pr-gate`）、Agents 段缺 spike agent、Layout 段引用已不存在的 `settings/` 目錄且缺 `skills/`（install.sh 實際會接線）——commands/agents/skills 清單改為與實際目錄一致（可由 `commands/*.md` frontmatter description 派生），Layout 修正到與 install 行為相符。 -5. **Audit slice completed 2026-07-18**：以 `b7799c3` 為 baseline，掃描全部 493 個 reachable commits（含 2026-05-15 後 450 commits）。未發現需 rotation/history rewrite 的 credential、私鑰或誤入 runtime artifact；token-shaped matches 均為測試 fixture／字串誤判。已記錄兩項非 secret exposure（maintainer 絕對路徑、commit Gmail metadata）及一項持續防護缺口（GitHub secret scanning disabled）。處置與可重跑方法見 [docs/audits/CC-033-git-history-audit.md](docs/audits/CC-033-git-history-audit.md)。本票維持 active；README/協作表面、secret-scanning enablement verification 仍屬 v0.14.0。 +5. **Audit slice completed 2026-07-18**：以 `b7799c3` 為 baseline，掃描全部 493 個 reachable commits（含 2026-05-15 後 450 commits）。未發現需 rotation/history rewrite 的 credential、私鑰或誤入 runtime artifact；token-shaped matches 均為測試 fixture／字串誤判。已記錄兩項非 secret exposure（maintainer 絕對路徑、commit Gmail metadata）及一項持續防護缺口（GitHub secret scanning disabled）。處置與可重跑方法見 [docs/audits/CC-033-git-history-audit.md](docs/audits/CC-033-git-history-audit.md)。本票維持 active；README/協作表面、secret-scanning enablement verification 仍屬 v0.12.0。 someday → active，P3 → P2。 **Source**: 2026-05-15 對話 — 公開前置盤點 #4。 @@ -1844,9 +1858,10 @@ dimensions 都已完成；docs-only、一般功能、高風險／manual UI chang 5. Tier/mode/reviewer-policy tables 必須來自 [[CC-512]]／[[CC-513]] 的 machine-readable source 或 bounded generated markers；cross-document lint 不解析 大段自由文字。README 只保留 discoverable pointer，canonical docs 承載概念。 -6. 分兩步交付：先落 `draft terminology/map` 骨架，不宣稱 runtime 已支援；等 - [[CC-511]]～[[CC-515]]、[[CC-518]]～[[CC-521]] 收斂後再做 - `runtime-aligned finalization` 與 drift ratchet。 +6. 分兩步交付：先落 `draft terminology/map` 骨架，不宣稱 runtime 已支援； + `runtime-aligned finalization` 等 [[CC-511]] Phase B、[[CC-517]]、 + [[CC-520]]～[[CC-522]]、[[CC-527]]、[[CC-529]] 及 v0.11.0 authority closure + 收斂後再做，並加入 drift ratchet。 7. 明文記錄現階段不新增 `/deliver`、workflow profile、persistent workflow state、 preset DSL 或 FSM；若短 recipe 的真實使用證據顯示需要 wrapper，再由 [[CC-516]] 評估。 @@ -1856,8 +1871,9 @@ recipe，並準確判斷每個 assurance dimension 是 pass、未跑、不可用 lint 阻止 tier/mode/full-suite 順序重新漂移。 **Dependencies**: draft skeleton 可先行；runtime-aligned finalization 等 -[[CC-511]]～[[CC-515]]、[[CC-517]]～[[CC-521]]。排入 v0.14.0 public surface， -避免文件先承諾尚未落地的行為。 +[[CC-511]] Phase B、[[CC-517]]、[[CC-520]]～[[CC-522]]、[[CC-527]]、 +[[CC-529]]～[[CC-533]]。排入 v0.12.0 public surface，避免文件先承諾尚未落地的 +行為。 **Cross-link**: [[CC-493]]、`commands/ship.md`、`docs/review-model.md`。 @@ -2646,6 +2662,270 @@ assurance observability。 --- +## CC-530 — source-safe runtime libraries + unified identifier policy 🔵 active + +**Problem**: `runtime/lib/portable.sh` 在被 source 時直接修改 strict-mode flags， +consumer 因此必須自行保存與還原 caller state；同時 Adapter 等 domain identifier +在 enum、filesystem、router 與 dispatch resolver 使用不同 regex，合法名稱會隨入口 +改變。這兩種隱藏差異會阻礙 Gate module、Adapter manifest 與 CLI lazy-loading +後續重用。 + +**Why**: Sourceable library 應只提供 callable behavior，identifier policy 則應有 +單一 ownership。若基礎 library 會改變 shell 狀態、各 consumer 又自行定義名稱， +後續每次抽 module 都會複製 bootstrap 與 compatibility 邏輯，且安全檢查無法證明 +所有入口一致。 + +**Requirement**: + +1. 定義並機械驗證 `runtime/lib/*.sh` source contract：source 階段不得改變 shell + flags、cwd、global trap，不得寫檔、spawn process 或直接 `exit`；strict mode 與 + lifecycle ownership 留在 `runtime/bin/*`、`cli/pmctl` 與 executable Adapter。 +2. 移除 `portable.sh` 的 caller-state side effect，清理 consumer 的 flag + save/restore workaround；既有 callable behavior 與 executable error contract + 保持。 +3. 建立 centralized identifier policy，明確列出 Adapter、Host、run、operation + 等 domain 的 canonical grammar；允許 domain 間有不同規則，但同一 domain 的 + enum、manifest、filesystem、router 與 resolver 必須共用同一 validator。 +4. Source-safety fixtures 在不同 errexit/nounset/pipefail 組合下驗 flags、cwd、 + files、traps 與 process side effects；identifier conformance fixtures 覆蓋所有 + production entrypoints 與 boundary values。 + +--- + +## CC-531 — Adapter manifest dispatch entrypoint contract closure 🔵 active + +**Problem**: Built-in manifests 宣告 `runner_ref: ./dispatch.sh`，generator 卻產生 +`./run.sh`；實際 dispatch runtime 又不讀該欄位，而是硬編碼 +`adapters//dispatch.sh`。Manifest 看似是 source of truth，實際不具 +load-bearing authority，新增或改名 entrypoint 仍需修改 core runtime。 + +**Why**: v0.12.0 若要把 `adapter.yaml` 列為 public contract，必須先讓 manifest +真正控制 runtime resolution。否則文件、generator 與執行路徑會形成三份互相矛盾 +的 authority，custom Adapter 無法只靠自己的 manifest 接入。 + +**Requirement**: + +1. 定義語意明確的 canonical dispatch entrypoint 欄位；`runner_ref` 的遷移、 + deprecated alias 或拒絕策略必須明文且有 compatibility fixtures，generator 與 + built-in manifests 同步。 +2. 所有 Adapter enum、dispatch、executor routing 與 validation path 都透過同一 + manifest reader 解析 entrypoint，不再固定尋找 `dispatch.sh`；名稱驗證共用 + [[CC-530]] identifier policy。 +3. Entrypoint 必須是 Adapter 目錄內的 safe relative path；拒絕 absolute path、 + `..` escaping、symlink escaping、missing/non-executable target 與不合法 + `runner_kind` 組合。 +4. Conformance suite 證明將某 Adapter 的 entrypoint 改成 `./worker.sh` 後只改 + manifest 即可 dispatch，無須修改 `pmctl-dispatch.sh`、executor router 或其他 + shared runtime。 + +--- + +## CC-532 — Gate canonical modules + generated standalone distribution 🔵 active + +**Problem**: `runtime/bin/pr-gate.sh` 同時承擔 option parsing、policy、subject、 +scope、reviewer contract、synthesis、assurance、publication 與 copy-mode fallback， +canonical authoring source已接近 6,500 行。Portability 所需 generated snapshot +與正常 repo-layout 邏輯混在同一檔，讓每次 contract 變更都擴大 review 與 regression +surface。 + +**Why**: Gate 已是專案複雜度中心，但 copy-mode standalone portability 仍是必要 +產品能力。Canonical modules 與 generated distribution 分離後，才能在不增加 runtime +dependency、不改使用者安裝模式的前提下，讓 domain ownership、測試隔離與 code +review 回到可維護範圍。 + +**Requirement**: + +1. 依 domain 抽出 source-safe canonical modules，至少涵蓋 options、policy、 + subject、scope、reviewer contract 與 assurance；`runtime/bin/pr-gate.sh` + 成為 repo-layout composition root，首批搬移只做 behavior-preserving migration。 +2. Standalone copy-mode 由唯一 build tool 產生 distribution bundle；generated + policy/verifier fallback 不再作為日常 canonical authoring source，並延續 + [[CC-525]] 的 provenance 與 stale check。 +3. Symlink/repo-layout 安裝 canonical entrypoint，copy-mode 安裝 generated + distribution；兩者維持相同 prerequisite 與 runtime dependency。 +4. CI 的 build `--check` 拒絕 stale bundle；同一組 fixtures 比對 canonical/dist + 的 stdout、stderr、exit code 與 artifacts，並覆蓋 copy-mode 無 repo-layout + dependency 的真實執行。 + +--- + +## CC-533 — schema-derived Gate structural validator 🔵 active + +**Problem**: Gate JSON Schema 已定義 required fields、exact keys、enum、patterns、 +conditions 與 finding shape，shared jq verifier 又手寫同一份 structural model。 +Parity tests只能發現漂移，無法消除每次 contract 變更都必須同步修改 schema 與 +validator 的雙重 authority。 + +**Why**: Structural validation 與跨 artifact domain semantics 是不同責任。前者 +應由 schema authoring source 派生；後者才需要手寫 reviewer identity、subject、 +scope、evidence index、digest 與 line-boundary 驗證。分層後可降低 Gate schema +演進成本，同時保留 Bash+jq lightweight runtime。 + +**Requirement**: + +1. 由 canonical schema 派生或產生 Gate structural validator，涵蓋 required、 + type、enum、const、pattern、additional properties、array、`$ref` 與目前使用的 + conditional vocabulary；coverage surfaces 等 enum 不再手寫第二份。 +2. 手寫 verifier 只保留跨 artifact semantics，例如 expected reviewer、 + scope/subject digest、reference-index membership、snapshot line bound 與 linked + artifact integrity。 +3. Assurance/reviewer contract 的 version dispatch 與各版本 verifier 分離，legacy + compatibility 不再與 current exact-key logic 混成單一函式。 +4. Generation 在開發／build 階段完成，runtime 仍只需要 Bash+jq；CI `--check`、 + schema fixtures 與 canonical/dist parity 證明 generated fragment 未 stale 且 + semantic checks 未被結構 generator 吸收或放寬。 + +--- + +## CC-534 — registry-driven CLI router + lazy loading 🟢 someday + +**Problem**: `commands.tsv` 已驅動 help、discovery 與 lint，但 `cli/pmctl` 仍以大型 +手寫 `case`、eager library sourcing 與重複 handler checks 執行 routing。Registry +與 router 是兩份 implementation，只能靠 awk lint 比對。 + +**Why**: Command metadata 若是 build-time authority，就應同時產生安全 routing +table；如此新增 command 才能只增加 handler、registry row 與 tests，並避免每次啟動 +載入所有 command modules。 + +**Requirement**: + +1. 擴充 command registry 表達 module、handler 與 argument mode，並在 build 階段 + 產生 shell routing table；usage/stability/JSON/mutating metadata 維持同一來源。 +2. Generic router 只接受固定 repo-relative module 與 safe function-name handler， + lazy source 所選 module 後以直接函式呼叫 dispatch，不使用 `eval`。 +3. Registry lint 驗 module/handler 存在、source-safe、command path 唯一，並以 + characterization fixtures 鎖定現有 argument forwarding、help、exit 與 JSON + behavior。 +4. [[CC-530]] source-safety 完成前不啟動 migration；完成後分批轉接，避免一次改寫 + 全部 CLI contracts。 + +--- + +## CC-535 — supervised-run primitive + versioned JSON run-spec 🟢 someday + +**Problem**: `detached-launch.sh` 已正確抽出 nonce、setsid/nohup、sentinel wait 與 +process identity，但 Gate、Dispatch、Operation 上層仍各自維護 reserve、spec、 +ready、terminal claim、cancel 與 reconcile。Dispatch supervisor 另使用 +`key=value + native_b64` serialization，增加自訂 parser 與 schema drift surface。 + +**Why**: Gate 與 Dispatch 需要相同 lifecycle primitives，但擁有不同 policy、 +preflight 與 artifact semantics。窄型 supervised-run layer可收斂真正共享的 +control plane，而不演變成 generic workflow engine。 + +**Requirement**: + +1. 在 `detached-launch.sh` 上定義 reserve ID、versioned spec write/read、launch、 + ready publication、wait、terminal claim、cancel 與 reconcile primitives。 +2. Run-spec 採 versioned JSON 並以既有 jq prerequisite 驗證；native args、workdir、 + brief與 domain identity 不再使用自訂 key/value/base64 array format。 +3. Gate policy、Adapter resolution、reviewer dispatch、brief/result validation 與 + artifact synthesis保留在各 domain；不得建立 DAG、FSM、preset DSL 或 generic + workflow engine。 +4. Parent與detached supervisor仍各自在自己的 trust boundary重新執行 preflight， + 但呼叫同一 shared implementation；不得以抽象化為由刪除 defense-in-depth + invocation。 + +--- + +## CC-536 — Adapter SDK lifecycle／manifest／trace expansion 🟢 someday + +**Problem**: `dispatch-common.sh` 已共用 snapshot、basic validation、trace 與 footer， +但 Claude、Codex、OpenCode、Grok 仍重複 self-snapshot/re-exec、common option +parsing、timestamp、manifest list/scalar、isolation translation loading 與 trace +bootstrap。 + +**Why**: 重複的是 Adapter lifecycle、transport、trace 與 contract glue，不是 +executor-native behavior。擴充窄型 SDK 可讓新 Adapter 專注 native mapping，同時 +避免製造一個包含所有供應商分支的巨型通用 Adapter。 + +**Requirement**: + +1. 盤點並抽出 snapshot re-exec、common args、manifest access、isolation resolution、 + trace begin/finish 與 footer publication 等有至少兩個等價 consumer 的 primitives。 +2. Manifest access 共用 [[CC-531]] authority；source behavior 共用 [[CC-530]] + contract，且不得重新定義 identifier 或 entrypoint policy。 +3. Codex reasoning/approval/sandbox、OpenCode API fallback、Claude headless output、 + Grok model/isolation semantics 等 native behavior 保留在各 Adapter。 +4. Adapter conformance fixtures 鎖定 shared contract與每個 native translation； + 新 Adapter 的 executable主要只需 native CLI 定義、argument mapping、execution + 與 result parsing。 + +--- + +## CC-537 — data-driven test suite + impact registries 🟢 someday + +**Problem**: Test suite names與paths在同一 shell file分開維護，changed-path impact +planner又以另一個大型 `case` 維護 path→suite mapping。Lint可以比對結構，卻無法 +消除三份註冊 authority。 + +**Why**: Suite metadata與impact selection資料化後，可降低新增或改名 suite 時的 +維護成本，也能讓 broad shared-path escalation規則明確可審；但 focused planner +不得取代 authoritative full suite。 + +**Requirement**: + +1. 建立 suite registry，表達 name、path、timeout、serial group、tags 與 CI + requirement；runner與`--list`從同一 authoring source取得資料。 +2. 建立 impact registry，表達 path pattern、suite、reason與 escalation， + 並檢查 missing suite、unreachable rule、ambiguous precedence與 shared lifecycle/ + schema path缺少 broad escalation。 +3. `run-tests.sh --base`只作快速 focused selection；release/gate authoritative + evidence仍由 full runner及其 verification contract產生。 +4. 用現有 changed-path fixtures做 before/after parity，另加入新增 suite只改 + registry即可被 runner與CI發現的 regression。 + +--- + +## CC-538 — Host resolver／doctor shared primitives 🟢 someday + +**Problem**: Codex、OpenCode與Grok的root resolver幾乎使用相同演算法，只差env、 +default subdirectory與label；doctor modules也重複path normalization、command +identity、managed block、target/executable checks與diagnostic rendering。Claude +另有legacy alias conflict，不能直接套用 simple resolver。 + +**Why**: Shared primitives可降低新增Host成本，但Host policy與ownership仍必須留在 +各Host module；若把host-name switch重新放回shared runtime，會破壞目前正確的 +vertical ownership boundary。 + +**Requirement**: + +1. 提供parameterized simple-root resolver，讓無legacy alias的Host宣告label、 + primary env與default root；Claude繼續由自身resolver處理primary/legacy conflict。 +2. 抽出純mechanical doctor primitives：JSON path normalization、exact command + identity、managed block detection、target existence、executable check與common + diagnostic rendering。 +3. 每個Host仍決定設定是否正確、哪些asset屬於自己及修復建議；shared layer不得新增 + host-name `case`或吸收Host-specific policy。 +4. Conformance tests涵蓋simple resolver parity、Claude conflict semantics與各Host + doctor輸出；第二個真正consumer存在前不抽單一用途helper。 + +--- + +## CC-539 — state layout build-time authority + generated constants 🟢 someday + +**Problem**: `core/state/layout.yaml` 自稱machine-readable state layout並宣告root、 +partition、files、subdirs、schemas與writers，但runtime `state-paths.sh`仍手寫相同 +constants，再由parity tests反向比對。文件宣稱與實際runtime authority不一致。 + +**Why**: State layout是public contract candidate的基礎；若YAML只作specification就 +應明說，若作authoring authority就應在build階段產生runtime constants。維持模糊 +狀態會讓每次layout change都要求人工同步兩份模型。 + +**Requirement**: + +1. 將`core/state/layout.yaml`定為build-time authoring authority，產生 + `runtime/generated/state-layout.sh`等runtime constants；若實作盤點證明某欄位 + 只能是parity specification，必須在schema與[[CC-446]] authority表明確降級， + 不得繼續宣稱runtime直接解析。 +2. Generator涵蓋store root defaults、project/run subdirs、writer entrypoints與其他 + 真正load-bearing constants，並以`--check`拒絕stale output。 +3. Runtime啟動不得新增yq/Python或動態YAML parsing dependency；generation只發生 + 在開發/build階段。 +4. 保留`state-writer.sh` single-writer、atomic writes、rotation recovery與schema + validation；layout generation不得重寫writer boundary或migration semantics。 + +--- + ## CC-508 — 所有間接 dispatch 的 parent-operation control plane ✅ 2026-07-25 **Problem**: `pmctl gate run`、`pmctl ship --parallel`／adapter 路徑、`pmctl task dispatch` 與任何未來 producer 都可能以一個 parent operation 間接啟動一或多個 detached dispatch；但產品控制面主要只暴露個別 `pmctl dispatch cancel `。parent ID 與其子 run 沒有強制、可查的 ownership relation，也沒有一致的 producer-level cancel surface。當任一 producer 卡住、選錯 executor 或需中止時，操作者無法透過 pmctl 取消整個 operation；直接對 supervisor PID 操作會繞過 run state、sentinel 與 cancel-vs-complete 單一終態契約，並可能留下無法判定的 stale operation。 diff --git a/DECISIONS.md b/DECISIONS.md index e00238db..cd0fad03 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -7,6 +7,48 @@ H2 標題格式：## YYYY-MM-DD: <短描述> 與 BACKLOG closure 對應的 entry，內文首行寫：Closes: BACKLOG.md#-NNN --> +## 2026-07-30: pre-v1-roadmap-is-contiguous-and-active-work-only + +Relates: CC-032, CC-033, CC-358, CC-446, CC-447, CC-511, CC-514, CC-517, +CC-520, CC-521, CC-522, CC-525, CC-526, CC-527, CC-529, CC-530, CC-531, +CC-532, CC-533, CC-534, CC-535, CC-536, CC-537, CC-538, CC-539 + +**Context**: Current planning placed v0.14.0 immediately after v0.11.0 because +earlier v0.11/v0.12/v0.13 scopes had been consolidated, while the v0.11 section +also retained many already-delivered rows as phase history. That made the active +milestone look larger than its remaining work and obscured the next executable +priority. A 2026-07-30 architecture review also identified runtime-authority +closures that should be tracked before public contract classification, plus +valuable follow-ups that should remain visible without all becoming release +blockers. + +**Decision**: The active pre-v1 sequence is contiguous: v0.11.0 followed by +v0.12.0. v0.11.0 is an active-work milestone containing only new tickets or +remaining slices of non-terminal tickets; shipped history remains in CHANGELOG, +release notes and archive. v0.11 prioritizes source-safe/identifier foundations, +Adapter manifest authority, Gate correctness/security, canonical Gate +modules/generated validation, maintainer publish closure and release evidence. +The former v0.14 public contract candidate becomes v0.12.0. Architecture +follow-ups that are useful but not v0.11 blockers receive explicit someday +backlog tickets rather than disappearing from planning. + +**Alternatives considered**: (a) Keep v0.14.0 to preserve the old numbering—— +rejected because there are no active v0.12/v0.13 milestones between the two +planned releases. (b) Restore old completed v0.12/v0.13 scope as active +milestones——rejected because it would revive delivered/archive content instead +of planning new work. (c) Put every architecture recommendation into +v0.11.0——rejected because CLI routing, supervised-run, SDK, test registry, Host +primitives and state-layout generation are valuable but are not all release +blockers. + +**Constraints introduced**: Current milestones may reference only new or +non-terminal backlog work. Replanning must not copy completed/archive tickets +back into the active set or rewrite archive history. Non-milestone architecture +recommendations remain in BACKLOG with explicit IDs and boundaries. v1.0.0 is +still unscheduled and may only be considered after v0.12.0 readiness review. + +--- + ## 2026-07-30: publish-accepts-generic-baseline-and-prefers-maintainer Relates: CC-511, CC-513, CC-515, CC-517, CC-528 diff --git a/MILESTONES.md b/MILESTONES.md index 4f6dbb48..860e5dfd 100644 --- a/MILESTONES.md +++ b/MILESTONES.md @@ -9,31 +9,37 @@ --- -## Pre-v1 stabilization sequence（2026-07-17 重排；v1.0 尚未排程） +## Pre-v1 stabilization sequence（2026-07-30 重排；v1.0 尚未排程） -> 這不是 v1.0 倒數或 release forecast。以下 v0.x milestones 用來逐版消化目前已知的遷移、操作、安全、證據與公開化缺口；完成 v0.14.0 後才重新做一次 v1.0 readiness review，再決定是否建立 v1.0.0 milestone。任何未完成的 critical surface 都不能因版本接近而自動降級或略過。 +> 這不是 v1.0 倒數或 release forecast。當前規劃只維護連續的 +> v0.11.0 → v0.12.0；完成 v0.12.0 後才重新做一次 v1.0 readiness review， +> 再決定是否建立 v1.0.0 milestone。Milestone 只列新增或尚未完成的工作， +> 已交付內容由 CHANGELOG、release notes 與 archive 承接，不回填到當前工作集。 -## v0.14.0 — public contract candidate（暫定；未啟動） +## v0.12.0 — public contract candidate（暫定；未啟動） -> 最後排程更新：2026-07-23（加入 delivery assurance public surface） +> 最後排程更新：2026-07-30（原 v0.14.0 連續改編為 v0.12.0） -**主題**：完成 public posture 與 stable/experimental contract candidate；本版產物是「是否具備建立 v1.0 milestone 的事實基礎」，不是 v1.0 RC。 +**主題**：在 v0.11.0 關閉 runtime authority、Gate correctness 與 release evidence +後，完成 public posture 與 stable/experimental contract candidate。本版產物是 +「是否具備建立 v1.0 milestone 的事實基礎」，不是 v1.0 RC。 -> **設計依據**：契約凍結必須晚於 CLI discovery、state compatibility、upgrade/release evidence 與 detached recovery，避免先承諾再補安全語意。 +> **設計依據**：先消除 manifest／schema／generated distribution 的雙重 authority， +> 再承諾 stable surface，避免契約凍結後才補 runtime 語意。 ### Phase 1 — public surface | 票 | 摘要 | 狀態 | |----|------|------| | CC-032 | feedback cross-link glossary 公開化，清除 public dead/private-only link | 🔵 | -| CC-033 | README/onboarding public posture、history audit 處置、repo collaboration surface | 🔵（history audit ✅ 2026-07-18；其餘未啟動） | -| CC-514 | orthogonal assurance map、machine-derived tier/mode/policy tables 與 docs-only／functional／high-risk recipes；draft 可先行，runtime-aligned finalization 後公開 | 🔵 | +| CC-033 | README/onboarding public posture、未完成的 repo collaboration surface 與 secret-scanning verification | 🔵 | +| CC-514 | orthogonal assurance map、machine-derived tables 與 docs-only／functional／high-risk recipes | 🔵 | ### Phase 2 — contract candidate | 票 | 摘要 | 狀態 | |----|------|------| -| CC-446 | stable/experimental CLI + schema、SemVer/deprecation、deprecated surface 清掃 | 🔵 | +| CC-446 | stable/experimental CLI + schema、authority 分類、SemVer/deprecation 與 deprecated surface 清掃 | 🔵 | ### 待後續 / 明確排除 @@ -42,42 +48,52 @@ --- -## v0.11.0 — pre-v1 stabilization：state compatibility + release/operational evidence（暫定；未啟動） +## v0.11.0 — runtime authority closure + Gate correctness + release evidence（暫定；未啟動） -> 最後排程更新：2026-07-23（加入 delivery assurance correctness；原 v0.11.0／v0.12.0／v0.13.0 三版合併；CC-499 已提前隨 v0.10.0 交付） +> 最後排程更新：2026-07-30（只保留新增或尚未完成項目） -**主題**：一次消化 v1.0 前已知的 state compatibility、release/upgrade evidence 與 operational evidence 缺口。原 v0.11.0（state compatibility + writer boundary）、v0.12.0（release evidence + upgrade proof）、v0.13.0（detached recovery + operational evidence）合併為本版；其中 detached reconciliation（CC-499）已提前於 v0.10.0 出貨，不在本版 scope。 +**主題**：先關閉會在 v0.12.0 public contract candidate 前形成雙重 authority、 +安全邊界或發布證據缺口的工作。這一版不再陳列已交付的 state、host、operation、 +Gate foundation 歷史，也不從 archive 取回舊票。 -> **設計依據**：合併只降低 release closure 次數，不改變原有排序理由——state compatibility 先於 writer ratchet、evidence parity 先於 upgrade smoke、契約凍結（v0.14.0）仍晚於本版全部內容。三版合一後 tag 間隔變長，任何 critical surface 不得因版本收斂而降級或略過。 +> **優先順序**：source-safe/identifier 基礎 → Adapter contract closure → +> Gate correctness/security → Gate canonical source/generated distribution → +> maintainer publish closure → operational/release evidence。 -### Phase 1 — state compatibility surface（原 v0.11.0） +### Phase 1 — runtime foundation + Adapter authority | 票 | 摘要 | 狀態 | |----|------|------| -| CC-498 | layout/entity version 命名、`pmctl state status [--json]`、migration availability | ✅ pr:#435 | -| CC-500 | all-production-domain single-writer enforcement | ✅ pr:#438 | -| CC-507 | `state status` unreadable `VERSION` fail-closed exit contract | ✅ pr:#437 | +| CC-530 | source-safe runtime libraries + unified identifier policy | 🔵 | +| CC-531 | Adapter manifest dispatch entrypoint 成為唯一 runtime authority | 🔵 | -### Phase 2 — release evidence parity（原 v0.12.0 Phase 1） +### Phase 2 — Gate correctness + security boundary | 票 | 摘要 | 狀態 | |----|------|------| -| CC-449 | 吸收 CC-431：suite registry、CI parity、OpenCode、ship/worktree smoke | ✅ pr:#439 | +| CC-520 | synthesis findings-union parity、coverage matrix、remediation seed 與 no-silent-drop | 🔵 | +| CC-521 | actionable test-gap matrix、bounded protocol recovery 與 live recall evaluation 分層 | 🔵 | +| CC-522 | arbitrary `--test-cmd` opaque／structured negotiation；test failure 與 INCOMPLETE 分流 | 🔵 | +| CC-526 | reviewer override symlink／replacement trust-boundary hardening | 🔵 | +| CC-527 | targeted pass、reviewer coverage 與 tier 的 CLI coordinate 分離 | 🔵 | -### Phase 3 — lifecycle ownership（原 v0.12.0 Phase 2） +### Phase 3 — Gate canonical source + generated artifacts | 票 | 摘要 | 狀態 | |----|------|------| -| CC-504 | manifest-driven multi-host lifecycle，移除 Claude base-spine 特例；product receipt、selected-host ownership、legacy migration 與 doctor dispatch 完整交付 | ✅ pr:#442 | -| CC-508 | executor producer 的 parent-operation control plane：gate／ship 在 launch 前掛載 child、ownership-scoped cancel／reconcile、doctor 診斷；task dispatch 依票面不接入 | ✅ pr:#447 | +| CC-525 | 修正 verifier fallback provenance 並鎖定唯一 generator | 🔵 | +| CC-532 | 拆出 canonical Gate modules，release 時產生 standalone dist 並驗 canonical/dist parity | 🔵 | +| CC-533 | schema-derived structural validator；手寫 verifier 只保留跨 artifact 語意 | 🔵 | -### Phase 4 — shared tooling/hooks host boundary（原 v0.12.0 Phase 3） +### Phase 4 — maintainer closure + publish authorization | 票 | 摘要 | 狀態 | |----|------|------| -| CC-503 | canonical memory/payload/log roots + shared-layer content ratchet | ✅ pr:#445 | +| CC-529 | ship stdout、PR body、finish marker 保留 producer policy 與 baseline/preferred satisfaction | 🔵 | +| CC-517 | `/ship` primary review→remediation closure→conditional targeted confirmation→final affected/full tests | 🔵 | +| CC-511 Phase B | final-tree review或 verified remediation closure + current-tree full PASS → publish | ⚠️ | -### Phase 5 — operational evidence（原 v0.13.0 Phase 2） +### Phase 5 — operational evidence | 票 | 摘要 | 狀態 | |----|------|------| @@ -87,61 +103,19 @@ | 票 | 摘要 | 狀態 | |----|------|------| -| CC-447 | offline clean install + latest released tag→v0.11 RC N-1 upgrade；foreign config/memory/user data 不變。屬正式 release evidence，若 release surface 改變即重跑 | 🔵 | - -### Phase 6 — immediate publish correctness - -> 依 2026-07-23 gate/delivery orthogonality decision，先堵住與新 review schema 無關的 -> 發布漏洞：任何官方 ship path 都必須在 current tree full-suite artifact 通過後才可 -> push／開 PR。 - -| 票 | 摘要 | 狀態 | -|----|------|------| -| CC-511 Phase A | direct／parallel ship publish path 共用既有 full-result verifier；stale/partial/skip/suite/tree drift 全部 fail closed | ✅ pr:#446 | - -### Phase 7 — evidence + policy foundations - -> 實作順序：CC-512 先鎖定 machine-owned assurance coordinates；CC-513 才能在同一 -> vocabulary 上產 policy resolution；CC-515 最後把 structural evidence 與 immutable -> subject／freshness／consumer applicability 接起來。三者是不同責任，不合併成 profile。 - -| 票 | 摘要 | 狀態 | -|----|------|------| -| CC-512 | Slices A／B／C：coordinate sources／CLI resolution、machine-owned assurance envelope／evidence capture、shared verifier／parity ratchets；targeted 不再是 tier | ✅ pr:#451 | -| CC-513 | canonical resolver：minimum tier、required reviewers、mode recommendation／user-choice provenance、generic vs maintainer policy 與 tier/coverage downgrade audit | ✅ pr:#452 | -| CC-515 | immutable subject、三軸 shared verifier 與 downstream evidence link contract；scope／closure producers 分屬 CC-518／CC-517 | ✅ pr:#454 | - -### Phase 8 — existing gate structured evidence - -> 只強化既有 `pmctl gate run`；protocol completeness 與 live-model recall 分開，不新增 -> gate kind、workflow engine 或 FSM。 - -| 票 | 摘要 | 狀態 | -|----|------|------| -| CC-518 | `gate_scope_manifest_v1`：immutable subject、changed/renamed/untracked、paired tests、signals、bounded expansion/truncation | ✅ pr:#455 | -| CC-519 | selected-reviewer coverage/finding contract；sequential logical sections 與 parallel session isolation 分開 | 🔵 | -| CC-520 | synthesis findings-union parity、root-cause grouping、coverage matrix、remediation seed、no silent drop | 🔵 | -| CC-521 | actionable test-gap matrix + bounded protocol recovery；seeded live recall 僅作 quality evaluation | 🔵 | -| CC-522 | arbitrary `--test-cmd` opaque／structured negotiation；test failure 與 timeout／environment INCOMPLETE 分流 | 🔵 | - -### Phase 9 — maintainer closure + publish authorization - -| 票 | 摘要 | 狀態 | -|----|------|------| -| CC-528 | publish policy compatibility：generic current-tree initial GO 為 baseline、maintainer 為 preferred；ship 可驗證明確 supplied result | 🔵 | -| CC-529 | publish assurance observability：ship stdout、PR body、finish marker 保留 producer policy 與 baseline/preferred satisfaction | 🔵 | -| CC-517 | `/ship` primary review→local/targeted/split remediation closure→final affected/full tests；不虛稱 final-tree GO | 🔵 | -| CC-511 Phase B | final-tree review或 primary-review closure authorization + current-tree full PASS → publish | 🔵 | +| CC-447 | offline clean install + latest released tag→v0.11 RC N-1 upgrade；foreign config/memory/user data 不變 | 🔵 | ### 待後續 / 明確排除 - 沒有真實 N→N+1 path 時不建空 migration engine，也不宣稱 `state migrate` 可用。 - 真實 auth 的 end-to-end live dogfood 留到 v1 readiness review；本版先建立可重現的 offline/upgrade evidence。 - bootstrap wizard 仍由 smoke 的真實摔倒點決定，不預先實作。 -- 不從 advisory record 推導 success；無可信證據時保留 indeterminate。 -- memory product expansion 不因 telemetry 名稱相近而併入本版。 -- Tier、mode、reviewer coverage、independence、subject 與 publish authorization 不互相推論；`full` 不等於 parallel，parallel 不等於 full coverage。 -- 不在本版新增 `/deliver`、新 gate kind、workflow profile/preset、persistent workflow state 或 FSM；CC-517 只調整 repo-owned maintainer `/ship` policy，其他使用者可繼續自由組合 generic primitives。thin wrapper 只有在 CC-514 後的真實分類證據觸發 CC-516 才評估。 +- CLI registry、supervised-run kernel、Adapter SDK、test registry、Host primitive 與 + state-layout generation 先留在 backlog 評估；不因同屬架構改善就擴入 v0.11.0。 +- Tier、mode、reviewer coverage、independence、subject 與 publish authorization + 不互相推論；`full` 不等於 parallel，parallel 不等於 full coverage。 +- 不在本版新增 `/deliver`、新 gate kind、workflow profile/preset、persistent + workflow state 或 FSM。 --- From 18810516aa872c7b4a2936a5c68704b759fc26ba Mon Sep 17 00:00:00 2001 From: screenleon Date: Thu, 30 Jul 2026 15:48:25 +0900 Subject: [PATCH 2/2] docs: preserve v0.11 milestone history --- DECISIONS.md | 59 ++++++++++---------- MILESTONES.md | 149 +++++++++++++++++++++++++++++++++++--------------- 2 files changed, 136 insertions(+), 72 deletions(-) diff --git a/DECISIONS.md b/DECISIONS.md index cd0fad03..ac6ea9e2 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -7,45 +7,48 @@ H2 標題格式：## YYYY-MM-DD: <短描述> 與 BACKLOG closure 對應的 entry，內文首行寫：Closes: BACKLOG.md#-NNN --> -## 2026-07-30: pre-v1-roadmap-is-contiguous-and-active-work-only +## 2026-07-30: pre-v1-roadmap-is-contiguous-and-preserves-milestone-history Relates: CC-032, CC-033, CC-358, CC-446, CC-447, CC-511, CC-514, CC-517, CC-520, CC-521, CC-522, CC-525, CC-526, CC-527, CC-529, CC-530, CC-531, CC-532, CC-533, CC-534, CC-535, CC-536, CC-537, CC-538, CC-539 **Context**: Current planning placed v0.14.0 immediately after v0.11.0 because -earlier v0.11/v0.12/v0.13 scopes had been consolidated, while the v0.11 section -also retained many already-delivered rows as phase history. That made the active -milestone look larger than its remaining work and obscured the next executable -priority. A 2026-07-30 architecture review also identified runtime-authority -closures that should be tracked before public contract classification, plus -valuable follow-ups that should remain visible without all becoming release -blockers. +earlier v0.11/v0.12/v0.13 scopes had been consolidated. The v0.11 section already +served as both delivery history and remaining plan: completed rows across +Phase 1–8 recorded how the release foundation arrived, while other rows in +Phase 5, Phase 8 and Phase 9 retained open operational, Gate and publish work. +A first 2026-07-30 replan incorrectly replaced that section +with an active-work-only view. This removed existing milestone history even +though the intended restriction was only to avoid reviving unrelated archived +tickets. The same architecture review identified runtime-authority closures that +should be tracked before public contract classification, plus useful follow-ups +that should remain visible without all becoming release blockers. **Decision**: The active pre-v1 sequence is contiguous: v0.11.0 followed by -v0.12.0. v0.11.0 is an active-work milestone containing only new tickets or -remaining slices of non-terminal tickets; shipped history remains in CHANGELOG, -release notes and archive. v0.11 prioritizes source-safe/identifier foundations, -Adapter manifest authority, Gate correctness/security, canonical Gate -modules/generated validation, maintainer publish closure and release evidence. -The former v0.14 public contract candidate becomes v0.12.0. Architecture -follow-ups that are useful but not v0.11 blockers receive explicit someday -backlog tickets rather than disappearing from planning. +v0.12.0, and the former v0.14 public contract candidate becomes v0.12.0. +Existing v0.11 Phase 1–9 content remains intact as milestone history plus +remaining scope. New v0.11 work is appended after it as Phase 10–12: +source-safe/identifier foundations and Adapter manifest authority, Gate +security/coordinate cleanup, then canonical Gate modules/generated validation. +Architecture follow-ups that are useful but not v0.11 blockers receive explicit +someday backlog tickets rather than disappearing from planning. **Alternatives considered**: (a) Keep v0.14.0 to preserve the old numbering—— rejected because there are no active v0.12/v0.13 milestones between the two -planned releases. (b) Restore old completed v0.12/v0.13 scope as active -milestones——rejected because it would revive delivered/archive content instead -of planning new work. (c) Put every architecture recommendation into -v0.11.0——rejected because CLI routing, supervised-run, SDK, test registry, Host -primitives and state-layout generation are valuable but are not all release -blockers. - -**Constraints introduced**: Current milestones may reference only new or -non-terminal backlog work. Replanning must not copy completed/archive tickets -back into the active set or rewrite archive history. Non-milestone architecture -recommendations remain in BACKLOG with explicit IDs and boundaries. v1.0.0 is -still unscheduled and may only be considered after v0.12.0 readiness review. +planned releases. (b) Replace v0.11 with an active-work-only section——rejected +because MILESTONES also records shipped delivery history; CHANGELOG/archive do +not authorize deleting an existing milestone record. (c) Put every architecture +recommendation into v0.11.0——rejected because CLI routing, supervised-run, SDK, +test registry, Host primitives and state-layout generation are valuable but are +not all release blockers. + +**Constraints introduced**: Existing milestone delivery history must not be +removed during replanning; new scope is appended as later phases. This does not +permit copying unrelated completed/archive tickets back into the active milestone +or rewriting archive history. Non-milestone architecture recommendations remain +in BACKLOG with explicit IDs and boundaries. v1.0.0 is still unscheduled and may +only be considered after v0.12.0 readiness review. --- diff --git a/MILESTONES.md b/MILESTONES.md index 860e5dfd..934cf904 100644 --- a/MILESTONES.md +++ b/MILESTONES.md @@ -11,35 +11,39 @@ ## Pre-v1 stabilization sequence（2026-07-30 重排；v1.0 尚未排程） -> 這不是 v1.0 倒數或 release forecast。當前規劃只維護連續的 -> v0.11.0 → v0.12.0；完成 v0.12.0 後才重新做一次 v1.0 readiness review， -> 再決定是否建立 v1.0.0 milestone。Milestone 只列新增或尚未完成的工作， -> 已交付內容由 CHANGELOG、release notes 與 archive 承接，不回填到當前工作集。 +> 這不是 v1.0 倒數或 release forecast。以下 v0.x milestones 用來逐版消化目前 +> 已知的遷移、操作、安全、證據與公開化缺口；當前規劃維持連續的 +> v0.11.0 → v0.12.0，完成 v0.12.0 後才重新做一次 v1.0 readiness review， +> 再決定是否建立 v1.0.0 milestone。任何未完成的 critical surface 都不能因版本 +> 接近而自動降級或略過。Milestone 同時保留既有版本的交付歷史與 remaining plan； +> 重排只在既有 phase 後追加新工作，不移除已記錄的完成項目，也不從 archive 拉回 +> 原本不在 milestone 的舊票。 ## v0.12.0 — public contract candidate（暫定；未啟動） > 最後排程更新：2026-07-30（原 v0.14.0 連續改編為 v0.12.0） -**主題**：在 v0.11.0 關閉 runtime authority、Gate correctness 與 release evidence -後，完成 public posture 與 stable/experimental contract candidate。本版產物是 -「是否具備建立 v1.0 milestone 的事實基礎」，不是 v1.0 RC。 +**主題**：完成 public posture 與 stable/experimental contract candidate；本版產物 +是「是否具備建立 v1.0 milestone 的事實基礎」，不是 v1.0 RC。Runtime authority、 +Gate correctness 與 release evidence 仍必須先在 v0.11.0 關閉。 -> **設計依據**：先消除 manifest／schema／generated distribution 的雙重 authority， -> 再承諾 stable surface，避免契約凍結後才補 runtime 語意。 +> **設計依據**：契約凍結必須晚於 CLI discovery、state compatibility、 +> upgrade/release evidence 與 detached recovery，避免先承諾再補安全語意； +> manifest／schema／generated distribution 的雙重 authority 也必須先收斂。 ### Phase 1 — public surface | 票 | 摘要 | 狀態 | |----|------|------| | CC-032 | feedback cross-link glossary 公開化，清除 public dead/private-only link | 🔵 | -| CC-033 | README/onboarding public posture、未完成的 repo collaboration surface 與 secret-scanning verification | 🔵 | -| CC-514 | orthogonal assurance map、machine-derived tables 與 docs-only／functional／high-risk recipes | 🔵 | +| CC-033 | README/onboarding public posture、history audit 處置、repo collaboration surface | 🔵（history audit ✅ 2026-07-18；其餘未啟動） | +| CC-514 | orthogonal assurance map、machine-derived tier/mode/policy tables 與 docs-only／functional／high-risk recipes；draft 可先行，runtime-aligned finalization 後公開 | 🔵 | ### Phase 2 — contract candidate | 票 | 摘要 | 狀態 | |----|------|------| -| CC-446 | stable/experimental CLI + schema、authority 分類、SemVer/deprecation 與 deprecated surface 清掃 | 🔵 | +| CC-446 | stable/experimental CLI + schema、SemVer/deprecation、deprecated surface 清掃；補上 authority 分類 | 🔵 | ### 待後續 / 明確排除 @@ -48,52 +52,43 @@ --- -## v0.11.0 — runtime authority closure + Gate correctness + release evidence（暫定；未啟動） +## v0.11.0 — pre-v1 stabilization：state compatibility + release/operational evidence（暫定；未啟動） -> 最後排程更新：2026-07-30（只保留新增或尚未完成項目） +> 最後排程更新：2026-07-30（保留既有 Phase 1–9 交付歷史與 remaining scope； +> 在後方追加 runtime authority／Gate maintainability Phase 10–12） -**主題**：先關閉會在 v0.12.0 public contract candidate 前形成雙重 authority、 -安全邊界或發布證據缺口的工作。這一版不再陳列已交付的 state、host、operation、 -Gate foundation 歷史，也不從 archive 取回舊票。 +**主題**：一次消化 v1.0 前已知的 state compatibility、release/upgrade evidence 與 operational evidence 缺口。原 v0.11.0（state compatibility + writer boundary）、v0.12.0（release evidence + upgrade proof）、v0.13.0（detached recovery + operational evidence）合併為本版；其中 detached reconciliation（CC-499）已提前於 v0.10.0 出貨，不在本版 scope。Phase 10–12 追加 public contract candidate 前必須收斂的 runtime authority、Gate security 與 generated-source 邊界。 -> **優先順序**：source-safe/identifier 基礎 → Adapter contract closure → -> Gate correctness/security → Gate canonical source/generated distribution → -> maintainer publish closure → operational/release evidence。 +> **設計依據**：合併只降低 release closure 次數，不改變原有排序理由——state compatibility 先於 writer ratchet、evidence parity 先於 upgrade smoke、契約凍結（v0.12.0）仍晚於本版全部內容。三版合一後 tag 間隔變長，任何 critical surface 不得因版本收斂而降級或略過；新增架構工作只能在既有 phase 後追加，不覆寫已完成的 milestone history。 -### Phase 1 — runtime foundation + Adapter authority +### Phase 1 — state compatibility surface（原 v0.11.0） | 票 | 摘要 | 狀態 | |----|------|------| -| CC-530 | source-safe runtime libraries + unified identifier policy | 🔵 | -| CC-531 | Adapter manifest dispatch entrypoint 成為唯一 runtime authority | 🔵 | +| CC-498 | layout/entity version 命名、`pmctl state status [--json]`、migration availability | ✅ pr:#435 | +| CC-500 | all-production-domain single-writer enforcement | ✅ pr:#438 | +| CC-507 | `state status` unreadable `VERSION` fail-closed exit contract | ✅ pr:#437 | -### Phase 2 — Gate correctness + security boundary +### Phase 2 — release evidence parity（原 v0.12.0 Phase 1） | 票 | 摘要 | 狀態 | |----|------|------| -| CC-520 | synthesis findings-union parity、coverage matrix、remediation seed 與 no-silent-drop | 🔵 | -| CC-521 | actionable test-gap matrix、bounded protocol recovery 與 live recall evaluation 分層 | 🔵 | -| CC-522 | arbitrary `--test-cmd` opaque／structured negotiation；test failure 與 INCOMPLETE 分流 | 🔵 | -| CC-526 | reviewer override symlink／replacement trust-boundary hardening | 🔵 | -| CC-527 | targeted pass、reviewer coverage 與 tier 的 CLI coordinate 分離 | 🔵 | +| CC-449 | 吸收 CC-431：suite registry、CI parity、OpenCode、ship/worktree smoke | ✅ pr:#439 | -### Phase 3 — Gate canonical source + generated artifacts +### Phase 3 — lifecycle ownership（原 v0.12.0 Phase 2） | 票 | 摘要 | 狀態 | |----|------|------| -| CC-525 | 修正 verifier fallback provenance 並鎖定唯一 generator | 🔵 | -| CC-532 | 拆出 canonical Gate modules，release 時產生 standalone dist 並驗 canonical/dist parity | 🔵 | -| CC-533 | schema-derived structural validator；手寫 verifier 只保留跨 artifact 語意 | 🔵 | +| CC-504 | manifest-driven multi-host lifecycle，移除 Claude base-spine 特例；product receipt、selected-host ownership、legacy migration 與 doctor dispatch 完整交付 | ✅ pr:#442 | +| CC-508 | executor producer 的 parent-operation control plane：gate／ship 在 launch 前掛載 child、ownership-scoped cancel／reconcile、doctor 診斷；task dispatch 依票面不接入 | ✅ pr:#447 | -### Phase 4 — maintainer closure + publish authorization +### Phase 4 — shared tooling/hooks host boundary（原 v0.12.0 Phase 3） | 票 | 摘要 | 狀態 | |----|------|------| -| CC-529 | ship stdout、PR body、finish marker 保留 producer policy 與 baseline/preferred satisfaction | 🔵 | -| CC-517 | `/ship` primary review→remediation closure→conditional targeted confirmation→final affected/full tests | 🔵 | -| CC-511 Phase B | final-tree review或 verified remediation closure + current-tree full PASS → publish | ⚠️ | +| CC-503 | canonical memory/payload/log roots + shared-layer content ratchet | ✅ pr:#445 | -### Phase 5 — operational evidence +### Phase 5 — operational evidence（原 v0.13.0 Phase 2） | 票 | 摘要 | 狀態 | |----|------|------| @@ -103,19 +98,85 @@ Gate foundation 歷史，也不從 archive 取回舊票。 | 票 | 摘要 | 狀態 | |----|------|------| -| CC-447 | offline clean install + latest released tag→v0.11 RC N-1 upgrade；foreign config/memory/user data 不變 | 🔵 | +| CC-447 | offline clean install + latest released tag→v0.11 RC N-1 upgrade；foreign config/memory/user data 不變。屬正式 release evidence，若 release surface 改變即重跑 | 🔵 | + +### Phase 6 — immediate publish correctness + +> 依 2026-07-23 gate/delivery orthogonality decision，先堵住與新 review schema 無關的 +> 發布漏洞：任何官方 ship path 都必須在 current tree full-suite artifact 通過後才可 +> push／開 PR。 + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-511 Phase A | direct／parallel ship publish path 共用既有 full-result verifier；stale/partial/skip/suite/tree drift 全部 fail closed | ✅ pr:#446 | + +### Phase 7 — evidence + policy foundations + +> 實作順序：CC-512 先鎖定 machine-owned assurance coordinates；CC-513 才能在同一 +> vocabulary 上產 policy resolution；CC-515 最後把 structural evidence 與 immutable +> subject／freshness／consumer applicability 接起來。三者是不同責任，不合併成 profile。 + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-512 | Slices A／B／C：coordinate sources／CLI resolution、machine-owned assurance envelope／evidence capture、shared verifier／parity ratchets；targeted 不再是 tier | ✅ pr:#451 | +| CC-513 | canonical resolver：minimum tier、required reviewers、mode recommendation／user-choice provenance、generic vs maintainer policy 與 tier/coverage downgrade audit | ✅ pr:#452 | +| CC-515 | immutable subject、三軸 shared verifier 與 downstream evidence link contract；scope／closure producers 分屬 CC-518／CC-517 | ✅ pr:#454 | + +### Phase 8 — existing gate structured evidence + +> 只強化既有 `pmctl gate run`；protocol completeness 與 live-model recall 分開，不新增 +> gate kind、workflow engine 或 FSM。 + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-518 | `gate_scope_manifest_v1`：immutable subject、changed/renamed/untracked、paired tests、signals、bounded expansion/truncation | ✅ pr:#455 | +| CC-519 | selected-reviewer coverage/finding contract；sequential logical sections 與 parallel session isolation 分開 | 🔵 | +| CC-520 | synthesis findings-union parity、root-cause grouping、coverage matrix、remediation seed、no silent drop | 🔵 | +| CC-521 | actionable test-gap matrix + bounded protocol recovery；seeded live recall 僅作 quality evaluation | 🔵 | +| CC-522 | arbitrary `--test-cmd` opaque／structured negotiation；test failure 與 timeout／environment INCOMPLETE 分流 | 🔵 | + +### Phase 9 — maintainer closure + publish authorization + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-528 | publish policy compatibility：generic current-tree initial GO 為 baseline、maintainer 為 preferred；ship 可驗證明確 supplied result | 🔵 | +| CC-529 | publish assurance observability：ship stdout、PR body、finish marker 保留 producer policy 與 baseline/preferred satisfaction | 🔵 | +| CC-517 | `/ship` primary review→local/targeted/split remediation closure→final affected/full tests；不虛稱 final-tree GO | 🔵 | +| CC-511 Phase B | final-tree review或 primary-review closure authorization + current-tree full PASS → publish | 🔵 | + +### Phase 10 — runtime foundation + Adapter authority（新增） + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-530 | source-safe runtime libraries + unified identifier policy | 🔵 | +| CC-531 | Adapter manifest dispatch entrypoint 成為唯一 runtime authority | 🔵 | + +### Phase 11 — Gate security + coordinate cleanup（新增） + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-526 | reviewer override symlink／replacement trust-boundary hardening | 🔵 | +| CC-527 | targeted pass、reviewer coverage 與 tier 的 CLI coordinate 分離 | 🔵 | + +### Phase 12 — Gate canonical source + generated artifacts（新增） + +| 票 | 摘要 | 狀態 | +|----|------|------| +| CC-525 | 修正 verifier fallback provenance 並鎖定唯一 generator | 🔵 | +| CC-532 | 拆出 canonical Gate modules，release 時產生 standalone dist 並驗 canonical/dist parity | 🔵 | +| CC-533 | schema-derived structural validator；手寫 verifier 只保留跨 artifact 語意 | 🔵 | ### 待後續 / 明確排除 - 沒有真實 N→N+1 path 時不建空 migration engine，也不宣稱 `state migrate` 可用。 - 真實 auth 的 end-to-end live dogfood 留到 v1 readiness review；本版先建立可重現的 offline/upgrade evidence。 - bootstrap wizard 仍由 smoke 的真實摔倒點決定，不預先實作。 +- 不從 advisory record 推導 success；無可信證據時保留 indeterminate。 +- memory product expansion 不因 telemetry 名稱相近而併入本版。 - CLI registry、supervised-run kernel、Adapter SDK、test registry、Host primitive 與 - state-layout generation 先留在 backlog 評估；不因同屬架構改善就擴入 v0.11.0。 -- Tier、mode、reviewer coverage、independence、subject 與 publish authorization - 不互相推論；`full` 不等於 parallel，parallel 不等於 full coverage。 -- 不在本版新增 `/deliver`、新 gate kind、workflow profile/preset、persistent - workflow state 或 FSM。 + state-layout generation 以 CC-534～CC-539 保留在 backlog，不擴入 v0.11.0。 +- Tier、mode、reviewer coverage、independence、subject 與 publish authorization 不互相推論；`full` 不等於 parallel，parallel 不等於 full coverage。 +- 不在本版新增 `/deliver`、新 gate kind、workflow profile/preset、persistent workflow state 或 FSM；CC-517 只調整 repo-owned maintainer `/ship` policy，其他使用者可繼續自由組合 generic primitives。thin wrapper 只有在 CC-514 後的真實分類證據觸發 CC-516 才評估。 ---