clowder-labs · bouillipx · Mar 4, 2026 · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
@@ -143,6 +143,16 @@ jobs:
       - name: Check governance evidence-first contract (structure + semantics)
         run: ./scripts/ci/check_governance_evidence_truth.sh
 
+  governance-traceability:
+    name: governance-traceability
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check governance traceability contract (template + indexes + TODO linkage)
+        run: ./scripts/ci/check_governance_traceability.sh
+
   p0-gate:
     name: p0-gate
     runs-on: ubuntu-latest

@@ -103,6 +103,8 @@
 | `features/README.md` | 特性聚合文档规范：单一状态源、证据回写与归档迁移 |
 | `guides/Team_Agent_Collab_Playbook.md` | 团队并行开发协作手册，含 spec-driven 认领粒度与 execution board 规则 |
 | `guides/Tool_Approval_Memory.md` | 工具审批记忆使用指南：pending/grant/deny/revoke、scope/matcher、持久化与接线方式 |
+| `features/templates/feature_aggregation_template.md` | 特性聚合模板：用于新建 `docs/features/<change-id>.md` |
+| `features/archive/README.md` | 特性聚合归档索引：记录已归档 change 的入口与迁移规则 |
 
 ---
 

@@ -25,7 +25,32 @@
 - `### Behavior Verification`
 - `### Risks and Rollback`
 - `### Review and Merge Gate Links`
+- CI gate command: `./scripts/ci/check_governance_traceability.sh`
 - CI gate command: `./scripts/ci/check_governance_evidence_truth.sh`
 
 5. Archive
 - Move completed docs to `docs/features/archive/` after closeout.
+
+## Template
+
+- Canonical template: `docs/features/templates/feature_aggregation_template.md`
+
+## Active Entries
+
+- `docs/features/agentscope-d2-d4-thinking-transport.md`
+- `docs/features/agentscope-d5-safe-compression.md`
+- `docs/features/agentscope-d7-plan-state-tools.md`
+- `docs/features/enhance-doc-governance-traceability.md`
+- `docs/features/p0-conformance-gate.md`
+- `docs/features/p0-default-eventlog.md`
+- `docs/features/p0-step-driven-execution.md`
+
+## Archive Index
+
+- `docs/features/archive/README.md`
+
+## Migration Rules
+
+- Active feature docs live in `docs/features/` until completion-archive.
+- Closeout must update this active index and the archive index in the same change.
+- Archived feature docs move to `docs/features/archive/` and keep stable evidence links.
@@ -2,8 +2,9 @@
 change_ids: ["agentscope-d2-d4-thinking-transport"]
 doc_kind: feature
 topics: ["agentscope", "transport", "thinking", "tool-events", "model-response"]
+todo_ids: ["D2-1", "D2-2", "D2-3", "D2-4", "D4-1", "D4-2", "D4-3", "D4-4"]
 created: 2026-03-02
-updated: 2026-03-02
+updated: 2026-03-03
 status: draft
 mode: openspec
 ---

@@ -0,0 +1,17 @@
+# Feature Aggregation Archive
+
+`docs/features/archive/` stores completed change aggregation docs after closeout.
+
+## Archived Entries
+
+- `docs/features/archive/client-capability-discovery-and-host-tests.md`
+- `docs/features/archive/client-external-control-plane-v1.md`
+- `docs/features/archive/client-headless-event-envelope-v1.md`
+- `docs/features/archive/client-host-orchestration-doc-baseline.md`
+- `docs/features/archive/refactor-dare-agent-structure-split.md`
+
+## Archive Migration Rules
+
+- Move a feature doc here only after the corresponding change is archived or explicitly closed.
+- Archive moves must preserve evidence links and OpenSpec artifact paths.
+- The active index at `docs/features/README.md` must be updated in the same change that performs the archive move.
@@ -3,7 +3,7 @@ change_ids: ["enhance-doc-governance-traceability"]
 doc_kind: feature
 topics: ["documentation-governance", "traceability", "skills"]
 created: 2026-02-28
-updated: 2026-03-02
+updated: 2026-03-04
 status: active
 mode: openspec
 ---
@@ -30,60 +30,77 @@ Unify documentation management structure, lifecycle governance, and SOP-to-skill
 ## Evidence
 
 ### Commands
+- `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py tests/unit/test_governance_evidence_truth_gate.py`
+- `./scripts/ci/check_governance_traceability.sh`
 - `./scripts/ci/check_governance_evidence_truth.sh`
-- `openspec validate --changes enhance-doc-governance-traceability`
-- `openspec status --change enhance-doc-governance-traceability --json`
+- `openspec validate enhance-doc-governance-traceability --type change --strict --json --no-interactive`
 
 ### Results
-- `check_governance_evidence_truth.sh`: pass.
-- `openspec validate`: pass.
-- `openspec status`: pass, `isComplete: true`.
+- `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py tests/unit/test_governance_evidence_truth_gate.py`: passed (`50 passed`) after extending the traceability gate regression suite to also cover stale active index entries, `Active Entries`-only membership checks, explicit checkpoint-to-skill pair rows, active/archive index path-family enforcement, README index-file exclusion for both active and archived entries, discrete `todo_ids` token matching, Claim Ledger-only TODO/change validation, same-record TODO/change validation, claim-scope range resolution, range-only claim-scope resolution without explicit todo tokens, full lifecycle checkpoint coverage, and date-prefixed archived change task discovery.
+- `./scripts/ci/check_governance_traceability.sh`: passed against the real repository tree after tightening active/archive index membership to canonical sections, rejecting index entries outside the correct feature-doc path family, excluding `docs/features/README.md` and `docs/features/archive/README.md` from valid feature-entry targets, requiring explicit checkpoint-to-skill pair rows in Section 7, and resolving pilot `todo_ids` only through Claim Ledger records, including same-claim scope ranges where the TODO id is only implied by the claim range.
+- `./scripts/ci/check_governance_evidence_truth.sh`: passed, confirming the new traceability assets do not break the existing evidence-first contract.
+- `openspec validate enhance-doc-governance-traceability --type change --strict --json --no-interactive`: passed (`1/1` change valid, `0` issues).
 
 ### Contract Delta
-- `schema`: evidence contract now requires a full acceptance-pack layout in every active feature doc (`Contract Delta`, `Golden Cases`, `Regression Summary`, `Observability and Failure Localization`, `Structured Review Report`).
-- `error semantics`: no runtime API `error_code` enum change; this gate now accepts framework-native error semantics (`error_code`/`error_type`/`exception_class`/`ToolResult.error`) and blocks missing declarations.
-- `retry`: CI retry does not bypass policy checks; rerun only after evidence/doc fixes, with no semantic downgrade on retry.
+- `schema`: added a canonical feature aggregation template, active/archive feature indexes, and a machine-checkable backlog-id pilot linkage for one active change.
+- `error semantics`: no runtime API change; the new traceability gate fails structurally on missing template/index/mapping assets with deterministic file-scoped messages.
+- `retry`: no retry semantic change; this slice is docs/CI only, and reruns remain deterministic after fixing the flagged governance asset.
 
 ### Golden Cases
-- Updated evidence contract baseline: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
-- Added acceptance-pack canonical spec: `docs/governance/Acceptance_Pack_Spec.md`.
-- Updated PR authoring baseline: `.github/pull_request_template.md`.
+- `docs/features/templates/feature_aggregation_template.md`
+- `docs/features/README.md`
+- `docs/features/archive/README.md`
+- `scripts/ci/check_governance_traceability.sh`
+- `tests/unit/test_governance_traceability_gate.py`
+- `docs/features/agentscope-d2-d4-thinking-transport.md`
 
 ### Regression Summary
 - Runner commands:
+  - `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py tests/unit/test_governance_evidence_truth_gate.py`
+  - `./scripts/ci/check_governance_traceability.sh`
   - `./scripts/ci/check_governance_evidence_truth.sh`
-  - `openspec validate --changes enhance-doc-governance-traceability`
-  - `openspec status --change enhance-doc-governance-traceability --json`
-- Summary: pass 3, fail 0, skip 0.
+  - `openspec validate enhance-doc-governance-traceability --type change --strict --json --no-interactive`
+- Summary: pass 4, fail 0, skip 0.
 
 ### Observability and Failure Localization
-- Event chain coverage includes `start`, `tool_call`, `end`, and `fail` events for traceable execution lifecycle.
-- Failure localization fields required for triage and review are: `run_id`, `tool_call_id`, `capability_id`, `attempt`, `trace_id`, plus at least one error locator (`error_code`/`error_type`/`exception_class`/`ToolResult.error`).
-- Gate failures must emit enough context to locate the exact document/section mismatch without full code deep-dive.
+- N/A for runtime event chain in this docs/CI governance slice.
+- Reason: this slice only adds document topology and traceability checks; it does not modify runtime event emission.
+- Fallback evidence: unit tests and both governance gate commands above exercise the failing/passing paths for template/index/mapping localization.
 
 ### Structured Review Report
 - Changed Module Boundaries / Public API: governance scope only; no new runtime public API added.
-- New State: no new cache/global/singleton runtime state; only documentation governance state tightened.
-- Concurrency / Timeout / Retry: no new concurrent runtime path; retry policy is documentation gate rerun after fixes, with unchanged timeout semantics.
-- Side Effects and Idempotency: side effects are limited to docs/CI gate outputs; idempotency relies on deterministic section checks and repeatable command outputs.
-- Coverage and Residual Risk: governance evidence and OpenSpec validation are covered; residual risk is false positives from regex-based checks when section names drift from canonical wording.
+- New State: adds one new repository gate script, one new gate test file, and canonical docs/index/template assets under `docs/features/`.
+- Concurrency / Timeout / Retry: no concurrency change; gate runs are single-process document scans with deterministic rerun behavior after fixes.
+- Side Effects and Idempotency: side effects are limited to CI/log output; repeated runs are idempotent against unchanged docs.
+- Coverage and Residual Risk: template/index/skill-mapping/TODO-linkage checks are covered; residual risk is that broader frontmatter enforcement across `docs/guides/**` and `docs/design/**` is still pending.
 
 ### Behavior Verification
-- Happy path: governance flow remains `analysis -> master TODO -> OpenSpec slice execution` with docs as canonical source.
-- Error/fallback path: TODO fallback metadata now requires `mode: todo_fallback` + `topic_slug`, with explicit migration back to OpenSpec.
+- Happy path: the repository now has a canonical feature aggregation template, explicit active/archive feature indexes, and a green traceability gate that resolves a pilot feature doc back to its TODO ledger and owning change-id through Claim Ledger records, including scope ranges such as `D2-1~D2-4, D4-1~D4-4`, even when the concrete TODO id does not appear elsewhere in the file.
+- Error/fallback path: the new gate fails deterministically when a feature doc is missing from the `## Active Entries` section, when an active/archive index entry points at the wrong doc family, when Section 7 keeps checkpoint names but drops the actual `checkpoint -> skill` mapping rows, or when `todo_ids` and `change_ids` only co-occur in detail-board/prose lines without a matching Claim Ledger record.
 
 ### Risks and Rollback
-- Risk: CI checks not yet fully implemented as scripts may leave policy drift windows.
-- Rollback: keep contract wording changes, temporarily downgrade new CI gate checks to warning if false positives block delivery.
+- Risk: `3.2-3.4` are still open, so the new gate does not yet enforce full frontmatter coverage for every governance-tracked doc family or full master-TODO/task completeness.
+- Risk: active/archive indexes are now explicit manual ledgers, so closeout changes that forget to update them will fail the new gate.
+- Rollback: remove `governance-traceability` from `.github/workflows/ci-gate.yml` and revert the template/index additions if the new gate produces unexpected false positives.
 
 ### Review and Merge Gate Links
 - Intent PR: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126`
 - Implementation PR: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/137`
+- Current implementation PR: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175`
 - Review request: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#issuecomment-3976690386`
 - Key owner feedback: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#issuecomment-3976707233`
 - Active fix threads:
-  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#discussion_r2867257929`
-  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#discussion_r2867257932`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878449796`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878449803`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878551469`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878551474`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878634816`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878634820`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878773226`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2878885299`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2881384029`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2881384034`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/175#discussion_r2881421738`
 
 ## Next Milestone
-Implement tasks group 1-2 (taxonomy contract + standards alignment).
+Implement the remaining CI depth tasks: widen frontmatter enforcement beyond feature docs and add machine-checkable TODO/task and master-TODO/change-slice consistency checks before closeout.
@@ -0,0 +1,56 @@
+# Feature Aggregation Template
+
+Use this template for new `docs/features/<change-id>.md` entries in OpenSpec mode.
+
+```yaml
+---
+change_ids: ["<change-id>"]
+doc_kind: feature
+topics: ["topic-a", "topic-b"]
+todo_ids: ["OPTIONAL-TODO-ID"]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+status: draft
+mode: openspec
+---
+```
+
+```md
+# Feature: <change-id>
+
+## Scope
+Describe the slice boundary and the user-visible or contract-visible outcome.
+
+## OpenSpec Artifacts
+- Proposal: `openspec/changes/<change-id>/proposal.md`
+- Design: `openspec/changes/<change-id>/design.md`
+- Specs:
+  - `openspec/changes/<change-id>/specs/<spec-name>/spec.md`
+- Tasks: `openspec/changes/<change-id>/tasks.md`
+
+## Governance Anchors
+- `docs/guides/Development_Constraints.md`
+- `docs/guides/Documentation_First_Development_SOP.md`
+- Add the canonical design or governance docs changed by this slice.
+
+## Evidence
+
+### Commands
+- `exact command`
+
+### Results
+- `pass/fail + key summary`
+
+### Behavior Verification
+- Happy path:
+- Error/fallback path:
+
+### Risks and Rollback
+- Risk:
+- Rollback:
+
+### Review and Merge Gate Links
+- Intent PR:
+- Implementation PR:
+- Review thread:
+```
@@ -144,8 +144,12 @@ CI MUST validate:
 - required skill files exist,
 - checkpoint mapping is declared,
 - governance frontmatter required keys by mode (OpenSpec vs TODO fallback) are present,
+- feature aggregation template and active/archive feature indexes are present,
+- active feature index entries resolve to real feature docs and archive index entries resolve to archived docs,
+- declared `todo_ids` can be resolved back to a TODO ledger that also names the owning change-id,
 - feature aggregation links to real OpenSpec artifact paths,
 - evidence block required fields (commands/results/behavior checks/risks/rollback/review links) are present for active items,
+- traceability gate command `./scripts/ci/check_governance_traceability.sh` passes,
 - evidence-truth gate command `./scripts/ci/check_governance_evidence_truth.sh` passes,
 - required assets and linkages are present.