--- phase: 07-workflow-smoke-convention-locks plan: 10 subsystem: documentation/hygiene tags: [traceable-reqs, hygiene, convention-lock, traceability] # Dependency graph requires: - phase: 07-workflow-smoke-convention-locks provides: "07-09 — traceable-reqs.toml deactivation (D-1) enabling angle-bracket conversion value" provides: - "Zero parse_error/undeclared_id findings in live Phase-7 planning files (D-2)" - "docs/TRACEABILITY.md — activation contract codified (D-4)" affects: [07-11, future-phases] # Tech tracking tech-stack: added: [] patterns: - "Angle-bracket stage convention: [->REQ-ID] for illustrative tags in planning docs" - "Activation-not-premature-failure: required_stages = [] until phase activates" key-files: created: - docs/TRACEABILITY.md modified: - .planning/phases/07-workflow-smoke-convention-locks/07-CONTEXT.md - .planning/phases/07-workflow-smoke-convention-locks/07-PATTERNS.md - .planning/phases/07-workflow-smoke-convention-locks/07-RESEARCH.md - .planning/phases/07-workflow-smoke-convention-locks/07-GAP-DECISIONS.md - .planning/phases/07-workflow-smoke-convention-locks/07-06-SUMMARY.md - .planning/phases/07-workflow-smoke-convention-locks/07-01-PLAN.md - .planning/phases/07-workflow-smoke-convention-locks/07-01-SUMMARY.md - .planning/phases/07-workflow-smoke-convention-locks/07-02-PLAN.md - .planning/phases/07-workflow-smoke-convention-locks/07-02-SUMMARY.md - .planning/phases/07-workflow-smoke-convention-locks/07-03-PLAN.md - .planning/phases/07-workflow-smoke-convention-locks/07-04-PLAN.md - .planning/phases/07-workflow-smoke-convention-locks/07-04-SUMMARY.md - .planning/phases/07-workflow-smoke-convention-locks/07-06-PLAN.md key-decisions: - "Illustrative tags in planning docs converted to angle-bracket form per D-2 — preserves readability while eliminating scanner noise" - "docs/TRACEABILITY.md created per D-4 — durable activation contract so debt does not re-accumulate" - "All illustrations in TRACEABILITY.md itself also use angle-bracket form (threat T-07-10-02 mitigated)" requirements-completed: [HYG-02, MAP-02] # Metrics duration: ~20min completed: 2026-06-07 tasks: 2 files_changed: 14 --- # Phase 07 Plan 10: Tag Hygiene — Angle-Bracket Conversion + TRACEABILITY.md Summary Eliminated 32 parse_error + undeclared_id findings from live Phase-7 planning docs by converting illustrative tags to angle-bracket form, and created `docs/TRACEABILITY.md` codifying the activation contract so this debt cannot silently re-accumulate. ## What Was Built ### Task 1: Convert illustrative tags in live Phase-7 planning files (D-2) Converted all 32 `[must]` findings (parse_error + undeclared_id) in the 13 live Phase-7 planning files to the angle-bracket illustration form `[->REQ-ID]`. Files modified: - **07-CONTEXT.md** (line 158): bare impl placeholder → `[->REQ-XX-NN]` - **07-PATTERNS.md** (lines 45, 167, 217): code example header, ADR pattern note, Pattern D section heading - **07-RESEARCH.md** (lines 601, 626, 858): section heading, code example, compliance table row - **07-GAP-DECISIONS.md** (line 30): table cell describing parse_error nature - **07-06-SUMMARY.md** (lines 39, 131, 132): patterns-established YAML, grep verification commands - **07-01-PLAN.md** (lines 33, 64, 141): YAML frontmatter pattern, read_first description, verification command - **07-01-SUMMARY.md** (line 21): patterns-established YAML string - **07-02-PLAN.md** (lines 33, 65, 145): same pattern as 07-01 - **07-02-SUMMARY.md** (lines 59, 94): prose description, code block grep command - **07-03-PLAN.md** (lines 33, 64, 157): same pattern - **07-04-PLAN.md** (lines 36, 174): YAML frontmatter, verification command - **07-04-SUMMARY.md** (lines 37, 126): patterns-established, verification block - **07-06-PLAN.md** (lines 44, 281, 323, 324): YAML pattern, verify block grep command (×3) Real evidence tags `[doc->REQ-MAP-02]`, `[impl->REQ-HYG-01]`, `[impl->REQ-HYG-02]`, `[doc->REQ-MAP-15]` in these files were NOT modified. ### Task 2: Create docs/TRACEABILITY.md (D-4) Created 84-line traceability contract document at `docs/TRACEABILITY.md` with: - `[doc->REQ-HYG-02]` on its own line (line 3, between title and opening blockquote) - Rule 4: Activation, not premature failure — explicit `required_stages = []` contract - Rule 5: Illustrative tags use angle-bracket stage convention - Rules 1-3: manifest registry, tag-in-same-change, evidence-proximate placement - Lifecycle section: seed → per-phase activation → closed-phase deactivation - Verification section: `pnpm trace:check` and `pnpm trace:list` usage The file itself uses angle-bracket form for all illustrative tag examples (threat T-07-10-02 mitigated). ## How It Was Built Per-occurrence judgment was applied to each flagged line. All 32 findings in live Phase-7 docs were ILLUSTRATIVE (examples of tagging grammar, grep verification commands, YAML pattern fields, code examples in pattern docs). No ambiguous cases required real-tag ID fixes. For TRACEABILITY.md, one self-introduced finding was immediately caught and fixed: Rule 2 originally showed a bare stage token (stage word without angle brackets) as an example; converted to `` `[->REQ-ID]` ``. The `[doc->REQ-MAP-02]` example in Rule 5 was also converted to a self-reference (`[doc->REQ-HYG-02]`) to avoid adding MAP-02 evidence to a non-ADR doc (per plan constraint). ## Verification ``` pnpm trace:check 2>&1 | grep "phases/07-" | grep -v "07-09-PLAN|07-10-PLAN|07-11-PLAN|07-12-PLAN|07-13-PLAN" → (empty — zero findings) ✓ pnpm trace:list 2>&1 | grep -E "REQ-MAP-02|REQ-MAP-15|REQ-HYG-01|REQ-HYG-02" → [OK] REQ-HYG-01 required: [doc, impl] stages: +doc +impl -unit -int ✓ → [OK] REQ-HYG-02 required: [doc, impl] stages: +doc +impl -unit -int ✓ → [OK] REQ-MAP-02 required: [doc] stages: +doc +impl -unit -int ✓ → [OK] REQ-MAP-15 required: [doc, impl] stages: +doc +impl -unit -int ✓ grep -c "[doc->REQ-HYG-02]" docs/TRACEABILITY.md → 2 (≥ 1) ✓ docs/TRACEABILITY.md line 3 is standalone [doc->REQ-HYG-02] ✓ ``` ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 1 - Bug] TRACEABILITY.md self-introduced parse_error at line 29** - **Found during:** Task 2, immediately after creation - **Issue:** Rule 2 prose contained a bare stage token (stage word without angle brackets) in backtick code, which the scanner picked up as a parse_error - **Fix:** Converted to `` `[->REQ-ID]` `` — consistent with the rule being described - **Files modified:** docs/TRACEABILITY.md - **Commit:** 1a18efd (included in task commit) **2. [Rule 2 - Missing Critical] Rule 5 example converted to self-reference** - **Found during:** Task 2 - **Issue:** Rule 5 used `` `[doc->REQ-MAP-02]` `` as a real-tag example, which would add MAP-02 evidence to a non-ADR doc (violating plan constraint "Do NOT add [doc->REQ-MAP-02]") - **Fix:** Replaced with self-reference: "e.g. the `[doc->REQ-HYG-02]` tag at the top of this file" - **Files modified:** docs/TRACEABILITY.md - **Commit:** 1a18efd ## Self-Check: PASSED - FOUND: `.planning/phases/07-workflow-smoke-convention-locks/07-10-SUMMARY.md` - FOUND: `docs/TRACEABILITY.md` - FOUND commit `30b1ffe` (Task 1 — angle-bracket conversion) - FOUND commit `1a18efd` (Task 2 — TRACEABILITY.md)