--- phase: 07-workflow-smoke-convention-locks type: gap-decisions status: ready-for-gap-plan created: 2026-06-03 source: 07-VERIFICATION.md (gaps_found, 4/5 must-haves) operator_decisions: locked 2026-06-03 --- # Phase 7 Gap-Closure Decisions Operator-adjudicated resolution for the single verification gap (HYG-02 scope conflict + its trace:check cascade). These decisions are LOCKED — the gap-closure planner should plan TO them, not re-litigate. ## Root cause (corrected from VERIFICATION.md) VERIFICATION.md framed the gap as "HYG-02 forward-lock-only vs literal cleanup." Deeper investigation (2026-06-03) found the real root cause is broader: **traceable-reqs was adopted mid-v1.0 (commit ee722b2) but its CI hard-gate was never enforced** (GH Actions storage died; CLAUDE.md documents the gate as deferred). Result: most v1.0 reqs were seeded into the manifest with the implicit default `required_stages = ["doc"]` but **never actually doc-tagged**. The 209 `pnpm trace:check` findings break down as: | Code | Count | Nature | |---|---|---| | `missing_stage` | 72 | Reqs activated (implicit `["doc"]`) with zero doc evidence — v1.0 trace debt + not-yet-built v1.1 phases + parity backlog | | `parse_error` | 94 | Malformed illustrative tags in tagging-contract docs (e.g. `[->REQ-ID]` example prose) | | `undeclared_id` | 43 | Placeholder example IDs (`REQ-X`, `REQ-XX-NN`, `REQ-SRV-XX`, `REQ-CLI-XX`, `REQ-DEP-NN`, `REQ-ID`) used illustratively in docs | This is **not a Phase-7 regression** — Phase 7's own 4 reqs (MAP-02, MAP-15, HYG-01, HYG-02) are correctly tagged and green. ## Convention adopted: spt-core Rule 5 (activation, not premature failure) Source: `../spt-core/docs/TRACEABILITY.md` Rule 5 — > "Every requirement starts `required_stages = []` (inactive) so `check` stays > green pre-code. A milestone activates the requirements it delivers by setting > their real `required_stages`. Deferred items stay `[]` until promoted." traceable-reqs measures the **active milestone's delivery**, not archived history. Closed-milestone reqs were gated by their functional milestone gate (v1.0 validated at tag `v1.0` / commit `1f6073e`), not by trace coverage. ## Tooling prerequisite — DONE traceable-reqs upgraded **v0.1.0 → v0.1.1** globally (2026-06-03). v0.1.1 adds angle-bracket-ignore: `[->REQ-X]` is treated as illustration, not live evidence (verified empirically — v0.1.0 flagged it `parse_error`; v0.1.1 emits no finding). Backup of v0.1.0 at `C:/Users/decid/AppData/Local/Programs/traceable-reqs/traceable-reqs.0.1.0.bak.exe`. This is the enabler for the illustrative-tag fix below. ## Locked decisions (operator, 2026-06-03) ### D-1 — Manifest req activation buckets Edit `traceable-reqs.toml`. Set explicit `required_stages` per bucket: | Bucket | Req IDs | required_stages | |---|---|---| | **Phase-7 delivered (active)** | REQ-MAP-02, REQ-MAP-15, REQ-HYG-01, REQ-HYG-02 | keep as-is (activated + green) | | **Future v1.1 (phases 8–12)** | REQ-MAP-01, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 16 | `[]` — each phase re-activates its own at plan time | | **v1.0 closed milestone** | REQ-EXT-01..08, REQ-SDOC-01..06, REQ-AST-02..04, REQ-CDOC-02..03, REQ-CLI-05, REQ-SRV-02, 05, 06, 07, 08, 09, 10, 11 (+ any other v1.0 req currently defaulting to `["doc"]` without evidence) | `[]` — validated at tag v1.0; deactivate, do NOT remove | | **Parity backlog (v1.2+)** | REQ-PAR-01..08 | `[]` | **Decision basis:** operator chose "Deactivate [] (spt-core Rule 5)" over retro-tagging. Rationale: v1.0 functional gate was the milestone gate; retro-tagging ~28 archived reqs = busywork with no forward value. **IMPORTANT — deactivate, NOT remove.** Every req row stays in the manifest with its id + title intact; only `required_stages` changes to `[]`. This preserves the registry so a future milestone can re-activate (or a v1.2 parity push can promote PAR-* without re-deriving them). Note: any req CURRENTLY activated for `impl`/`unit` with real evidence (e.g. v1.0 SRV reqs that DID get impl/unit tags, or DEP reqs with CI tags) must be checked before blanket-deactivating — only deactivate reqs whose required stages are genuinely uncovered. Cross-check each missing_stage finding against existing tags before zeroing. (The 72 missing_stage list in 07-VERIFICATION.md `gaps[]` is the authoritative target set.) ### D-2 — Illustrative/placeholder tags → angle-bracket form For the 137 parse_error + undeclared_id findings across these 16 files: - 4 live: `07-CONTEXT.md`, `07-PATTERNS.md`, `07-RESEARCH.md`, `07-06-SUMMARY.md` - 12 archived under `.planning/milestones/v1.0-phases/` Convert each ILLUSTRATIVE tag (example prose showing the tagging grammar, not real evidence) to the angle-bracket form `[->REQ-ID]` per spt-core TRACEABILITY.md "Tag examples" convention. v0.1.1 ignores these. Per-occurrence judgment required: distinguish a genuine illustration (keep, angle- bracket it) from an accidental real-looking tag that should point at a declared req (fix the id). Most will be illustrations. ### D-3 — LOCAL-DEPLOY.md contradiction (code-review WR-04) `docs/deploy/LOCAL-DEPLOY.md` `## Pre-flight` (known-legacy-debt: review & continue) contradicts `## Preflight gate (MANDATORY)` (MUST exit 0). After D-1+D-2 land, `pnpm preflight` exits 0 on green state, so the MANDATORY section becomes actionable. Reconcile the two sections: the MANDATORY gate is authoritative; the older Pre-flight known-debt language should defer to it (or be removed). ### D-4 — Adopt a TRACEABILITY.md contract (recommended, mirror spt-core) Create `docs/TRACEABILITY.md` (or extend CLAUDE.md trace section) documenting the activation-not-premature-failure rule so this debt does not silently re-accumulate. Model on `../spt-core/docs/TRACEABILITY.md`. At minimum codify: reqs start `[]`, milestone activates its own, tag in the same change as evidence, illustrative tags use `[->...]`. ## Exit criteria for the gap-closure plan - `pnpm trace:check` exits 0 (zero `[must]` findings) - `pnpm preflight` exits 0 end-to-end - `docs/deploy/LOCAL-DEPLOY.md` reads consistently (no Pre-flight vs MANDATORY conflict) - Phase-7's 4 reqs remain activated + green (no accidental deactivation) - Every manifest req row preserved (deactivation = `required_stages=[]`, never deletion) - Re-run `/gsd:verify-work 7` (or re-verify) → `passed` ## Out of scope (carry forward, do not fix here) - Code-review WR-01 (`lint-atlas-hash.mjs` `_smoke` substring vs path-segment match) — Phase 8 activation watchpoint, not blocking now. - WR-02 (allowlist prefix-trust posture) — documented behavior; revisit if abused. - WR-03 (symlink handling in lint-atlas-hash) — Phase 8. - WR-05 (check-conversion-regression no forcing function) — Phase 9.