diff --git a/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/proposal.md b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/proposal.md new file mode 100644 index 000000000..9b0db9c88 --- /dev/null +++ b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/proposal.md @@ -0,0 +1,22 @@ +## Why + +GitHub issue #451 回報 spec 與可執行 workflow 之間的 merge 契約矛盾：`openspec/specs/agent-operability-governance/spec.md`（`Agent SHALL 對每個完成的 work item 走 buffered ship-cycle 自動化` requirement，第 47 行與第 53 行）寫官方 gate 全綠時 SHALL **squash-merge**；但可執行的 `.claude/workflows/ship-item.md`（第 19 行、第 125 行）與 enforcing test `scripts/tests/test-agent-governance-check.ps1`（~875 行）都要求 `gh pr merge ... --merge --match-head-commit `——即 non-squash merge commit，用以保留 lifecycle `subject_commit` 的 ancestry 可追溯性。三方對照下 spec 是過時、與現況行為不符的一方：workflow 與 enforcing test 互相一致，且 test 直接斷言 ship-item.md 不得含 `--squash --match-head-commit`。 + +本 change 僅把 spec 的措辭改回與可執行行為一致，不改變任何 runtime / workflow / test 行為。 + +## What Changes + +- `openspec/specs/agent-operability-governance/spec.md`：修訂 `Agent SHALL 對每個完成的 work item 走 buffered ship-cycle 自動化` requirement 內兩處 `squash-merge` 措辭（requirement 本文一處、`完成 work item 後自動 ship 並守 buffered gate` scenario 一處）為 `merge`（merge commit、non-squash、保留 lifecycle ancestry），其餘措辭（官方 gate all-green 條件、不 merge 過 production 真 P1/P2、不偽裝 CI 綠、buffer cycle 規則）維持不變。 + +## Non-goals + +- 不修改 `.claude/workflows/ship-item.md`（已正確，是可執行行為權威）。 +- 不修改 `scripts/tests/test-agent-governance-check.ps1`（enforcing test，已正確；此檔屬 `scripts/lib/self-referential-bootstrap.ps1` 分類的驗證機制路徑，不在本 change 編輯範圍）。 +- 不修改任何 production runtime 行為；本 change 純粹是 spec 文字對齊，修正 spec 落後於已落地行為的漂移。 + +## Impact + +- Affected capabilities：`agent-operability-governance`（MODIFIED requirement）。 +- Affected files：`openspec/specs/agent-operability-governance/spec.md`（經由本 change 的 spec delta 於 archive 時套用）。 +- Product / runtime / deploy behavior：無。 +- Git / PR workflow：無新行為；本 change 消除 spec 與既有 ship-cycle 執行/驗證行為之間的文字矛盾。 diff --git a/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/specs/agent-operability-governance/spec.md b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/specs/agent-operability-governance/spec.md new file mode 100644 index 000000000..447507110 --- /dev/null +++ b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/specs/agent-operability-governance/spec.md @@ -0,0 +1,19 @@ +# agent-operability-governance — Spec Delta (align-ship-cycle-merge-ancestry) + +## MODIFIED Requirements + +### Requirement: Agent SHALL 對每個完成的 work item 走 buffered ship-cycle 自動化 + +Agent 完成一個可驗證的 work item 後 SHALL 依 `.claude/workflows/ship-item.md` 定義的 ship-cycle 自動 commit → push → 開 PR → 觀測 CI 與 reviewer comment → 在官方 gate（pr-review-agent + CodeRabbit）全綠且當前 head 無新 substantive P1/P2 時 merge（merge commit、non-squash，保留 lifecycle `subject_commit` ancestry）並 closeout。Agent SHALL NOT merge 過 production code 的真 P1/P2，SHALL NOT 偽裝 CI 綠；non-production 產物（evidence/docs scaffolding）的 advisory nit 在官方 gate 全綠時 MAY judgment-merge。 + +#### Scenario: 完成 work item 後自動 ship 並守 buffered gate + +- **WHEN** agent 完成一個 work item 並 commit 到 feature branch +- **THEN** agent SHALL push、開 PR、`gh pr checks --watch` 等 CI、再留 ~90-120s reviewer buffer +- **AND** 僅在官方 gate 全綠且當前 head 無新 substantive P1/P2 時 SHALL merge（merge commit、non-squash，保留 lifecycle ancestry）並 closeout +- **AND** 有新 substantive 發現時 SHALL 修復並對每個 push 重跑 buffer cycle，SHALL NOT 只看 check 狀態就 merge + +#### Scenario: 不 merge 過 production code 真 P1/P2 + +- **WHEN** reviewer 在 CI 變綠後對 production code 貼出新的 P1/P2 +- **THEN** agent SHALL NOT merge，SHALL 先修復再重跑 ship-cycle diff --git a/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/tasks.md b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/tasks.md new file mode 100644 index 000000000..f2f3d471c --- /dev/null +++ b/openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/tasks.md @@ -0,0 +1,13 @@ +# Tasks — align-ship-cycle-merge-ancestry + +## 1. Spec delta + +- [x] 1.1 於 `openspec/changes/align-ship-cycle-merge-ancestry/specs/agent-operability-governance/spec.md` 寫 `## MODIFIED Requirements`，完整重寫 `Agent SHALL 對每個完成的 work item 走 buffered ship-cycle 自動化` requirement 全文（含兩個既有 Scenario），把兩處 `squash-merge` 改為 `merge`（merge commit、non-squash、保留 lifecycle ancestry），其餘措辭不變。 +- [x] 1.2 確認未觸碰 `.claude/workflows/ship-item.md`、`scripts/tests/test-agent-governance-check.ps1`、`openspec/changes/archive/` 既有內容。 + +## 2. 驗證與 archive + +- [x] 2.1 `npx openspec validate align-ship-cycle-merge-ancestry --strict` 通過。 +- [x] 2.2 `npx openspec archive align-ship-cycle-merge-ancestry` 落地 spec，確認 `openspec/specs/agent-operability-governance/spec.md` 兩處已改為 `merge`、grep 該 requirement 無 `squash-merge` 殘留。 +- [x] 2.3 更新 `openspec/lifecycle-ledger.json` 新增本 change 的 archived row（欄位形狀比照既有 archived 範例）。 +- [x] 2.4 跑 `node --test scripts/tests/test-openspec-machine-truth.mjs`、`node --test scripts/tests/test-ai-coding-metrics.mjs`、`scripts/tests/verify-openspec-lifecycle.ps1 -BaseRef origin/main`、`scripts/tests/test-openspec-lifecycle-archive-diff.ps1`、`scripts/tests/test-openspec-ledger-reconciliation.ps1`、`scripts/tests/test-agent-governance-check.ps1`，全綠或誠實回報。 diff --git a/openspec/lifecycle-ledger.json b/openspec/lifecycle-ledger.json index ca7d3dce3..389f546b1 100644 --- a/openspec/lifecycle-ledger.json +++ b/openspec/lifecycle-ledger.json @@ -375,6 +375,24 @@ "subject_commit": "257e8f1fa54f780c16d7c9a0620d2bf716922636", "archive_debt": null }, + { + "id": "align-ship-cycle-merge-ancestry", + "status": "archived", + "owner": "repository-maintainer", + "current_slice": "spec squash-merge 措辭改對齊 ship-item.md/enforcing test 的 merge ancestry 契約，已 archived(2026-08-11)", + "blocked_by": [], + "last_verified": "2026-08-11T00:00:00Z", + "task_ledger": { + "completed": 6, + "total": 6 + }, + "evidence_refs": [ + "openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/proposal.md", + "openspec/changes/archive/2026-08-11-align-ship-cycle-merge-ancestry/tasks.md" + ], + "subject_commit": "bccf251319b50a64806592cd0b4709c186e9c1f4", + "archive_debt": null + }, { "id": "align-workflow-v3-with-saas-roadmap", "status": "archived", diff --git a/openspec/specs/agent-operability-governance/spec.md b/openspec/specs/agent-operability-governance/spec.md index 026fafc09..2591f8f0a 100644 --- a/openspec/specs/agent-operability-governance/spec.md +++ b/openspec/specs/agent-operability-governance/spec.md @@ -44,13 +44,13 @@ Every user-facing capability SHALL be verifiable from a frontend screen. Complet ### Requirement: Agent SHALL 對每個完成的 work item 走 buffered ship-cycle 自動化 -Agent 完成一個可驗證的 work item 後 SHALL 依 `.claude/workflows/ship-item.md` 定義的 ship-cycle 自動 commit → push → 開 PR → 觀測 CI 與 reviewer comment → 在官方 gate（pr-review-agent + CodeRabbit）全綠且當前 head 無新 substantive P1/P2 時 squash-merge 並 closeout。Agent SHALL NOT merge 過 production code 的真 P1/P2，SHALL NOT 偽裝 CI 綠；non-production 產物（evidence/docs scaffolding）的 advisory nit 在官方 gate 全綠時 MAY judgment-merge。 +Agent 完成一個可驗證的 work item 後 SHALL 依 `.claude/workflows/ship-item.md` 定義的 ship-cycle 自動 commit → push → 開 PR → 觀測 CI 與 reviewer comment → 在官方 gate（pr-review-agent + CodeRabbit）全綠且當前 head 無新 substantive P1/P2 時 merge（merge commit、non-squash，保留 lifecycle `subject_commit` ancestry）並 closeout。Agent SHALL NOT merge 過 production code 的真 P1/P2，SHALL NOT 偽裝 CI 綠；non-production 產物（evidence/docs scaffolding）的 advisory nit 在官方 gate 全綠時 MAY judgment-merge。 #### Scenario: 完成 work item 後自動 ship 並守 buffered gate - **WHEN** agent 完成一個 work item 並 commit 到 feature branch - **THEN** agent SHALL push、開 PR、`gh pr checks --watch` 等 CI、再留 ~90-120s reviewer buffer -- **AND** 僅在官方 gate 全綠且當前 head 無新 substantive P1/P2 時 SHALL squash-merge 並 closeout +- **AND** 僅在官方 gate 全綠且當前 head 無新 substantive P1/P2 時 SHALL merge（merge commit、non-squash，保留 lifecycle ancestry）並 closeout - **AND** 有新 substantive 發現時 SHALL 修復並對每個 push 重跑 buffer cycle，SHALL NOT 只看 check 狀態就 merge #### Scenario: 不 merge 過 production code 真 P1/P2