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-03
 status: active
 mode: openspec
 ---
@@ -30,60 +30,72 @@ 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`
+- `bash -n scripts/ci/check_governance_traceability.sh`
+- `./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`: passed (`7 passed`) after extending the traceability gate regression suite to also cover stale active index entries and discrete `todo_ids` token matching, in addition to the earlier template/index/skill-mapping/pilot-linkage checks.
+- `bash -n scripts/ci/check_governance_traceability.sh`: passed, confirming the new gate script is shell-valid before execution.
+- `./scripts/ci/check_governance_traceability.sh`: passed against the real repository tree after adding the feature template, archive index, and active feature index entries.
+- `./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`
+  - `bash -n scripts/ci/check_governance_traceability.sh`
+  - `./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 5, 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.
+- Error/fallback path: the new gate fails deterministically when a feature doc is missing from the active index, when the template/archive index is missing, when checkpoint-skill mapping drifts, or when declared `todo_ids` cannot be resolved back to a TODO ledger.
 
 ### 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`
+- Current implementation commit: `83e1f1a`
 - 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`
 
 ## 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.
 

@@ -0,0 +1,125 @@
+# Enhance Doc Governance Traceability Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Close the next real gaps in `enhance-doc-governance-traceability` by adding a reusable feature aggregation template, explicit active/archive feature indexes, a machine-checkable governance traceability gate, and one active pilot backfill.
+
+**Architecture:** Keep the existing evidence-truth gate focused on feature evidence semantics, and add a separate traceability gate for document topology, metadata, and TODO/change linkage. Use one active feature doc as the pilot so the new checks prove the contract without forcing a full historical backfill.
+
+**Tech Stack:** Markdown governance docs, shell CI scripts, Python unittest subprocess-based gate tests, GitHub Actions.
+
+---
+
+### Task 1: Define the docs/features governance surface
+
+**Files:**
+- Create: `docs/features/templates/feature_aggregation_template.md`
+- Create: `docs/features/archive/README.md`
+- Modify: `docs/features/README.md`
+- Modify: `docs/README.md`
+
+**Step 1: Write the failing test**
+
+Add a gate test that expects:
+- `docs/features/templates/feature_aggregation_template.md` to exist
+- `docs/features/README.md` to reference the template and active entries section
+- `docs/features/archive/README.md` to exist as the archive index
+
+**Step 2: Run test to verify it fails**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py -k template`
+Expected: FAIL because the template/archive index gate does not exist yet.
+
+**Step 3: Write minimal implementation**
+
+Create the template and archive index, then update `docs/features/README.md` and `docs/README.md` so the feature-doc lifecycle is discoverable from the docs navigation.
+
+**Step 4: Run test to verify it passes**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py -k template`
+Expected: PASS
+
+### Task 2: Add the governance traceability CI gate
+
+**Files:**
+- Create: `scripts/ci/check_governance_traceability.sh`
+- Create: `tests/unit/test_governance_traceability_gate.py`
+- Modify: `.github/workflows/ci-gate.yml`
+
+**Step 1: Write the failing test**
+
+Add subprocess-based tests that create a temp docs tree and assert the new gate fails when:
+- the template or archive index is missing
+- active feature docs are not listed in the active index
+- checkpoint-to-skill mapping is missing
+- a declared `todo_ids` entry cannot be found in any TODO ledger for the same change
+
+**Step 2: Run test to verify it fails**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py`
+Expected: FAIL with missing gate/script behavior.
+
+**Step 3: Write minimal implementation**
+
+Implement `scripts/ci/check_governance_traceability.sh` with repository-root override support and wire it into `ci-gate` as a dedicated job.
+
+**Step 4: Run test to verify it passes**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py`
+Expected: PASS
+
+### Task 3: Backfill one active pilot change
+
+**Files:**
+- Modify: `docs/features/agentscope-d2-d4-thinking-transport.md`
+
+**Step 1: Write the failing test**
+
+Extend the gate test so a pilot feature doc declaring `todo_ids` must be backed by a TODO ledger that contains both the same TODO ids and the owning change-id.
+
+**Step 2: Run test to verify it fails**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py -k todo`
+Expected: FAIL until the pilot doc and gate are aligned.
+
+**Step 3: Write minimal implementation**
+
+Add `todo_ids` to `docs/features/agentscope-d2-d4-thinking-transport.md` using the already-declared `D2-*` / `D4-*` mapping in `docs/todos/agentscope_domain_execution_todos.md`.
+
+**Step 4: Run test to verify it passes**
+
+Run: `../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py -k todo`
+Expected: PASS
+
+### Task 4: Sync the active governance change evidence
+
+**Files:**
+- Modify: `openspec/changes/enhance-doc-governance-traceability/tasks.md`
+- Modify: `docs/features/enhance-doc-governance-traceability.md`
+
+**Step 1: Write the failing test**
+
+No new automated test. This step is evidence synchronization after the new gate is green.
+
+**Step 2: Run verification**
+
+Run:
+- `../../.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 enhance-doc-governance-traceability --type change --strict --json --no-interactive`
+
+Expected: PASS
+
+**Step 3: Write minimal implementation**
+
+Mark only the tasks actually completed by this slice, and replace stale `openspec status` claims in the feature doc with fresh command results from this work.
+
+**Step 4: Commit**
+
+```bash
+git add docs/features docs/README.md docs/plans/2026-03-03-enhance-doc-governance-traceability-implementation.md \
+  scripts/ci/check_governance_traceability.sh tests/unit/test_governance_traceability_gate.py \
+  .github/workflows/ci-gate.yml openspec/changes/enhance-doc-governance-traceability/tasks.md
+git commit -m "feat(governance): add traceability gate baseline" -m "Add a feature aggregation template, active/archive feature indexes, a new governance traceability CI gate, and a pilot TODO-to-change backfill for an active change. This closes the next real gaps in enhance-doc-governance-traceability without forcing a broad historical docs rewrite."
+```