feat(governance): add traceability gate baseline - #175
Conversation
Add the first implementation slice for enhance-doc-governance-traceability. Key changes: - add docs/features template and explicit active/archive feature indexes - add scripts/ci/check_governance_traceability.sh and unit coverage for template/index/skill-mapping/TODO-linkage checks - wire the new governance-traceability gate into ci-gate - backfill agentscope-d2-d4-thinking-transport with todo_ids as the pilot traceability example - sync Documentation_Management_Model, change tasks, and feature evidence to the repository's current governance state Rationale: The change spec was ahead of the repository reality in some areas and behind it in others. Taxonomy, frontmatter semantics, OpenSpec-vs-docs boundaries, and dual-skill workflow were already landed, but the repository still lacked a reusable feature aggregation template, explicit active/archive indexes, and a machine-checkable traceability gate for backlog-to-change linkage. This commit closes that next real gap without forcing a broad historical backfill. Verification: - ../../.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
Update the active feature aggregation doc for enhance-doc-governance-traceability with the current implementation PR and commit reference. Key changes: - add PR #175 to Review and Merge Gate Links - record implementation commit 83e1f1a in the evidence trail - keep the existing historical intent/implementation links intact while extending the current audit chain Rationale: This change now has a live implementation PR and the active feature doc should reflect that review surface. Without the PR link, the new traceability work would be verified locally but not fully connected to its current merge-gate evidence. Verification: - ./scripts/ci/check_governance_traceability.sh - ./scripts/ci/check_governance_evidence_truth.sh
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 83e1f1ae80
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Tighten the governance traceability gate in response to PR review feedback. Key changes: - validate the reverse direction of active/archive feature indexes so stale backticked entries fail the gate - switch TODO/change matching from substring search to discrete token matching to avoid prefix false positives such as D2-1 matching D2-10 - extend governance traceability gate tests with dedicated regressions for stale index entries and discrete TODO token matching - refresh the active feature evidence count after the new regression cases landed Rationale: The initial gate only verified that real feature docs were listed in the indexes and that declared TODO ids appeared somewhere in TODO ledgers. That allowed two incorrect passes: stale README entries could survive indefinitely, and prefix-like TODO ids could satisfy the gate by substring alone. This commit makes the traceability contract symmetric and exact. Verification: - ../../.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
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 07307b9331
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Tighten the governance traceability gate for the remaining PR review gaps. Key changes: - require all five lifecycle checkpoints in the checkpoint-to-skill mapping, including execution-sync and review-merge-gate - accept archived task artifacts stored under date-prefixed archive directories such as YYYY-MM-DD-<change-id> - add regressions for missing lifecycle checkpoints and date-prefixed archived change lookup - refresh feature evidence for the expanded traceability gate test count Rationale: The previous revision still allowed false greens when two required lifecycle checkpoints were removed from the governance model, and it misdetected valid archived changes because archive directories are date-prefixed in this repository. This commit brings the traceability gate in line with the actual governance contract and archive layout. Verification: - ../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py - ./scripts/ci/check_governance_traceability.sh - ./scripts/ci/check_governance_evidence_truth.sh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d99dc45c97
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Tighten the governance traceability gate in two places called out during PR #175 review. Restrict active/archive feature membership checks to the canonical markdown sections instead of matching anywhere in the README, so migration notes or other incidental references cannot satisfy index membership. Strengthen TODO-to-change resolution from file-level token co-occurrence to record-level matching. The gate now accepts either a direct ledger row containing both the todo id and change id or a Claim Ledger row whose TODO Scope range covers the declared todo id for that same change. This preserves the repository's existing range-based claim pattern while still rejecting false greens where the todo id and change id appear on different records. Add regression coverage for section-only active membership, split-record TODO/change false positives, and claim-scope range resolution. Refresh the feature evidence with the latest review threads and verification results.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 885bacc24e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Tighten the governance traceability gate so Section 7 validation no longer passes on standalone checkpoint and skill tokens. The gate now requires each lifecycle checkpoint to appear in an explicit checkpoint-to-skill mapping row with the expected skill set, which closes the false-green case raised in PR #175 review. Add a regression that deletes the mapping bullets while leaving the checkpoint list and skill contract in place, and align the traceability fixture with the current completion-archive contract. Refresh the feature evidence with the latest review thread and verification totals after the new mapping-row check.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 694e411fc7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Fix a remaining false-negative in the governance traceability gate. The TODO mapping loop previously skipped any TODO ledger file that did not contain the declared todo id as a discrete token, which prevented same-record Claim Ledger ranges such as D4-1~D4-4 from resolving ids like D4-3 when that concrete id was not repeated elsewhere in the file. Remove the premature discrete-token prefilter and let the record-level matcher evaluate each candidate ledger for either a direct todo/change row or a same-change claim-scope range hit. Add a regression that covers the range-only case with no explicit todo token present, and refresh feature evidence with the new review thread and verification totals.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb447d717b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if [[ ! -f "$path" ]]; then | ||
| log "stale $stale_label index entry in $index_file: $path" |
There was a problem hiding this comment.
check_index_entry_targets only verifies that each backticked entry exists as a file, but it never enforces that entries in ## Active Entries are under docs/features/ (non-archive) or that ## Archived Entries are under docs/features/archive/. This allows false greens where unrelated existing files are listed as feature entries (for example, adding docs/features/archive/README.md to active entries still passes), which breaks the traceability contract for canonical indexes.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 79d51df.
check_index_entry_targets now validates that reverse-direction index entries stay within the correct feature-doc path family, not just that they point at an existing file. ## Active Entries only accepts docs/features/*.md documents, and ## Archived Entries only accepts docs/features/archive/*.md documents, so entries such as docs/features/archive/README.md can no longer satisfy active feature slots.
I added a regression that leaves the real active feature entry intact, injects docs/features/archive/README.md into ## Active Entries, and verifies the gate fails with an invalid active feature index path.
Re-ran:
../../.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.shopenspec validate enhance-doc-governance-traceability --type change --strict --json --no-interactive
Tighten two remaining false-green cases in the governance traceability gate. First, active and archived index entries are now validated against their correct feature-doc path families, so unrelated existing files such as archive indexes cannot satisfy canonical feature entry slots. Second, TODO-to-change resolution is now limited to Claim Ledger records instead of any line in the TODO file, which prevents detail-board or prose mentions from impersonating the required ownership mapping. Add regressions for both cases, including an active-entry path-family violation and a detail-board line that mentions both the todo id and change id without a matching Claim Ledger row. Refresh the feature evidence with the new review threads and verification totals after the tightened index and Claim Ledger checks.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 79d51dfb29
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Tighten reverse-direction feature index validation so active and archived entry targets must be actual feature docs, not index files. The previous path-family checks still allowed docs/features/README.md and docs/features/archive/README.md because they matched the broad *.md patterns, which let non-feature index documents satisfy the canonical index contract. Add two red/green regressions covering active and archived README entries, reject README basenames inside check_index_entry_targets, and refresh feature evidence with the new review thread and verification counts. Verification: - ../../.venv/bin/python -m pytest -q tests/unit/test_governance_traceability_gate.py -k 'readme_entry' - ../../.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
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0771b9c80
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if ! text_has_discrete_token "$line" "$second_token"; then | ||
| continue | ||
| fi | ||
| if text_has_discrete_token "$line" "$first_token"; then | ||
| return 0 |
There was a problem hiding this comment.
claim_ledger_has_tokens_in_same_record currently searches the whole table row for both tokens, so a row can satisfy traceability even when the OpenSpec Change column is wrong (for example, TODO scope is D2-1, OpenSpec Change is other-change, and notes text mentions demo-change). In that case the gate returns success even though the TODO is not actually linked to the declared change in the claim record, which creates false-green CI results for the core mapping this script is enforcing.
Useful? React with 👍 / 👎.
…hecks Record the new implementation PR for the post-#175 traceability gate depth work in the active feature aggregation document. Key changes: - relabel earlier governance PRs as baseline/previous implementation references - point the current implementation PR link at #178 - preserve the active feature doc as the review and merge-gate source of truth Rationale: The branch was rebased onto the latest main before opening the new implementation PR. The feature aggregation document must reflect the current review surface so governance evidence and merge-gate history remain accurate and machine-checkable. Verification: - ./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
1 participant
Summary
governance-traceabilityCI gate for feature template/index/skill-mapping/TODO-linkage checksdocs/featurestemplate and active/archive index docsenhance-doc-governance-traceabilitytasks/evidence to current repo realityWhy
enhance-doc-governance-traceabilitywas no longer a clean0/22change in practice. Core governance contracts like taxonomy, frontmatter semantics, OpenSpec-vs-docs boundaries, and dual-skill workflow were already landed, but the repository still lacked:This PR closes that next real gap without forcing a broad historical backfill.
Scope
Included:
docs/features/templates/feature_aggregation_template.mddocs/features/archive/README.mdscripts/ci/check_governance_traceability.shtests/unit/test_governance_traceability_gate.pyci-gatewiring for the new governance traceability checktodo_idsbackfill onagentscope-d2-d4-thinking-transportenhance-doc-governance-traceabilityNot included:
enhance-doc-governance-traceabilityVerification
../../.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.shopenspec validate enhance-doc-governance-traceability --type change --strict --json --no-interactiveReview Focus
agentscope-d2-d4-thinking-transportpilot is the right minimal backfill fortodo_idslinkage