feat: add gates ensuring discuss-phase decisions are translated to plans and verified (closes #2492)

[trek-e]

TL;DR

Two gates close the loop between discuss-phase decisions and downstream work, so a decision captured in CONTEXT.md <decisions> cannot silently disappear during planning or execution.

Closes #2492

What

• Plan-phase translation gate (BLOCKING). Inserted as Step 13a in workflows/plan-phase.md, after the existing requirements coverage gate and before plans are committed. Each trackable decision in <decisions> must be cited (by id D-NN or by 6+-word phrase) in at least one plan's designated sections — front-matter must_haves / truths / objective, or body sections under must_haves / truths / tasks / objective headings. HTML comments and fenced code blocks are stripped before searching, so a commented-out citation or a literal example never counts as coverage. The shell snippet wraps the SDK call with jq -e '.data.passed == true' || exit 1 so a coverage gap actually halts the workflow rather than only printing a warning.
• Verify-phase validation gate (NON-BLOCKING). Inserted as a <step name="verify_decisions"> in workflows/verify-phase.md, before behavioral_verification. Each trackable decision is searched against shipped artifacts (PLAN.md, SUMMARY.md, files modified, recent commit messages — last 200). Misses are reported in VERIFICATION.md as a warning section but do not flip the overall verification status.
• Shared parser parseDecisions() in sdk/src/query/decisions.ts — exposed as decisions.parse query handler — so Add unified post-planning gap checker for requirements and context #2493 (post-planning gap checker) can consume the same logic without duplicating decision-parsing code.
• Config key workflow.context_coverage_gate (boolean, default true). Added to WorkflowConfig, CONFIG_DEFAULTS, VALID_CONFIG_KEYS, and checkConfigGates. When false, both gates skip silently. Workstream-scoped configs are honored — the handlers thread workstream through loadConfig so per-workstream overrides take effect.

Why

The issue describes a real-world failure: discuss-phase captured ~40 decisions, plans were created without implementing several of them, and verification passed because it only checked plan objectives. Comments and workarounds don't fix this; instrumentation does.

Why the asymmetry (plan blocks, verify warns)

• Plan time is cheap. Failing at plan time costs minutes — the user re-cites the decision id in a plan, or moves the decision to Discretion.
• Verify time is expensive. Thousands of dollars of executor work has already happened. A fuzzy substring miss should not fail an otherwise green phase. The verify gate exists to surface drift, not to block.

Design decisions

1. Decision IDs are normative. discuss-phase.md already produces D-01, D-02, … — we lean on that. Citing D-NN in a plan is the deterministic, cheap path that always passes.
2. Soft phrase match uses the first 6 normalized words of the decision text and is gated on word count: decisions shorter than 6 words must be cited by id (no soft-match path exists for them).
3. Plan haystack is restricted to designated sections. This keeps the user's contract clear — there is exactly one place to put a coverage citation deliberately, and exactly one way to make a decision deliberately uncovered. Verify-phase keeps the broader artifact-wide haystack on purpose (non-blocking).
4. Opt-outs: decisions under ### Claude's Discretion (any unicode quote variant) or tagged [informational] / [folded] / [deferred] are not tracked.
5. Single source of truth for parsing. parseDecisions() is the only place that reads CONTEXT.md <decisions> blocks. Add unified post-planning gap checker for requirements and context #2493 will import it.
6. No new agent. Gates run as inline workflow steps invoking SDK query handlers — no new subagent spawn.

Documentation

• docs/CONFIGURATION.md — "Decision Coverage Gates" section with the config key, the asymmetry, the matching strategy, and opt-outs.
• docs/USER-GUIDE.md — "Decision Coverage Gates" section explaining how to write decisions the gates accept.
• docs/ARCHITECTURE.md — Phase Execution Flow diagram updated to call out both gates.
• workflows/plan-phase.md and workflows/verify-phase.md — gate insertion points, skip clauses, failure UX.

Tests

• sdk/src/query/decisions.test.ts — parser tests including fenced-code stripping, tab-indented continuation, multi-block extraction, unicode-quote discretion variants, and the relative-path resolution of decisions.parse.
• sdk/src/query/check-decision-coverage.test.ts — gate tests covering every spec case PLUS adversarial-review regressions: HTML-comment citation rejected, code-fence citation rejected, sub-6-word decision requires id, multi-summary files_modified aggregation, path-traversal rejection, workstream-scoped skip, numeric-config validation warning.
• tests/bug-2492-context-coverage-gate.test.cjs — workflow-as-prompt regression tests verifying gate steps, anchored-heading ordering, the ${CONTEXT_PATH} casing, and the || exit 1 block.

Full root suite: 5409/5409 passing. SDK gate + parser tests: 36/36 passing.

Cross-reference

Intersects with #2493 (post-planning gap checker). The shared parseDecisions() helper is the single source of truth — #2493 should import it rather than duplicate parsing logic.

Adversarial review fixes (rolled into this PR)

20 review findings against the initial commit have been fixed in three follow-up commits on this branch. Highlights:

• F1: gate snippet referenced ${context_path} (lowercase) — the BLOCKING gate would never run because the variable is defined as CONTEXT_PATH.
• F15: gate printed the failure message but lacked an exit 1 so the workflow continued past failure — now wrapped in a jq -e ... || exit 1.
• F3: gate handlers ignored the workstream arg, so workstream-scoped context_coverage_gate=false had no effect.
• F4: previous matcher accepted citations anywhere in the plan body, including inside HTML comments and code fences. Now restricted to designated sections.
• F6/F7: SUMMARY parser only saw the first files_modified block and accepted absolute / ../ paths. Now walks every summary, validates each path stays inside projectDir, and caps reads at 256 KB.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Decision Coverage Gates: Plans must reference decisions from CONTEXT.md; verify phase checks artifact coverage with warnings
  • New workflow.context_coverage_gate configuration option to enable/disable gates (enabled by default)

• Documentation

  • Architecture, configuration, and user guide updated with decision coverage gate details and matching rules

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e6c11079-874e-4a71-a120-727446083301

📥 Commits

Reviewing files that changed from the base of the PR and between 1a3d953 and b599883.

📒 Files selected for processing (16)

• docs/ARCHITECTURE.md
• docs/CONFIGURATION.md
• docs/USER-GUIDE.md
• get-shit-done/workflows/plan-phase.md
• get-shit-done/workflows/verify-phase.md
• sdk/src/config.ts
• sdk/src/query/check-decision-coverage.test.ts
• sdk/src/query/check-decision-coverage.ts
• sdk/src/query/config-gates.ts
• sdk/src/query/config-mutation.test.ts
• sdk/src/query/config-mutation.ts
• sdk/src/query/decisions.test.ts
• sdk/src/query/decisions.ts
• sdk/src/query/index.ts
• sdk/src/query/utils.ts
• tests/bug-2492-context-coverage-gate.test.cjs

---

📝 Walkthrough

Walkthrough

Implements issue #2492: two new workflow gates for decision coverage. The plan-phase gate (blocking) ensures all discuss-phase decisions from CONTEXT.md are referenced in plans. The verify-phase gate (non-blocking) validates these decisions appear in shipped artifacts and surfaces any gaps. Both gates can be disabled via configuration flag.

Changes

Cohort / File(s)	Summary
Configuration & Type System sdk/src/config.ts, sdk/src/query/utils.ts	Added context_coverage_gate boolean config flag (default true) to WorkflowConfig and CONFIG_DEFAULTS. Generalized QueryResult and QueryHandler types to support typed data payloads.
Decision Parsing sdk/src/query/decisions.ts, sdk/src/query/decisions.test.ts	New decision parser for CONTEXT.md <decisions> blocks. Extracts decision ID, text, category, and tags; marks decisions trackable/non-trackable based on section ("Claude's Discretion") and tags ([informational], [folded], [deferred]). Includes 215-line comprehensive test suite.
Coverage Gate Implementation sdk/src/query/check-decision-coverage.ts, sdk/src/query/check-decision-coverage.test.ts	Two gate handlers: checkDecisionCoveragePlan (blocking, plan-phase) validates decisions appear in plan must_haves/truths/body; checkDecisionCoverageVerify (non-blocking, verify-phase) checks decisions honored in shipped artifacts. Includes 519-line test suite with soft/strict matching, skip conditions, and path traversal guards.
Configuration & Registry sdk/src/query/config-mutation.ts, sdk/src/query/config-gates.ts, sdk/src/query/index.ts, sdk/src/query/config-mutation.test.ts	Added context_coverage_gate to config key allowlist, query registry, and config-gates response. Registered new handlers (decisions.parse, check.decision-coverage-plan, check.decision-coverage-verify).
Workflow Specifications get-shit-done/workflows/plan-phase.md, get-shit-done/workflows/verify-phase.md	Inserted mandatory decision-coverage gate after requirements validation in plan-phase (66 lines, blocking, skippable via config); added warning-only verification gate in verify-phase (52 lines, appends to VERIFICATION.md without affecting pass/fail).
Documentation docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/USER-GUIDE.md	Updated architecture diagrams to show new gates; added detailed configuration docs for both gates (covering matching logic, skip conditions, opt-out tags); added user guide documenting gate behavior, decision tagging, and config toggle.
Integration Tests tests/bug-2492-context-coverage-gate.test.cjs	End-to-end regression suite validating gate presence in workflows, correct variable passing, blocking semantics in plan-phase, non-blocking in verify-phase, and SDK wiring (config key, registry entries).

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant PlanPhase as Plan-Phase Workflow
    participant ContextMD as CONTEXT.md
    participant Plans
    participant CoveragePlan as Decision Coverage Gate
    participant StateFile as STATE.md

    User->>PlanPhase: Start planning
    PlanPhase->>ContextMD: Read <decisions> block
    ContextMD-->>PlanPhase: Extract decision list (D-01, D-02, ...)
    PlanPhase->>Plans: Load all *-PLAN.md files
    Plans-->>CoveragePlan: Decision text from must_haves, truths, body
    CoveragePlan->>CoveragePlan: Match each decision ID/phrase<br/>(strict ID or soft phrase match)
    alt All decisions covered
        CoveragePlan-->>PlanPhase: passed=true, coverage summary
        PlanPhase->>StateFile: Mark phase as planned
        PlanPhase-->>User: Planning complete
    else Decisions not covered
        CoveragePlan-->>PlanPhase: passed=false, list uncovered IDs
        PlanPhase-->>User: Decision gap detected<br/>(re-plan, mark discretion, or override)
        alt User chooses override
            PlanPhase->>StateFile: Record override for verify-phase
            PlanPhase->>StateFile: Mark phase as planned
        else User re-plans
            User->>Plans: Update plans with missing decisions
            PlanPhase->>Plans: Retry gate
        end
    end

Loading

sequenceDiagram
    participant VerifyPhase as Verify-Phase Workflow
    participant ContextMD as CONTEXT.md
    participant Plans
    participant Summaries as SUMMARY files
    participant Artifacts as Shipped Artifacts
    participant CoverageVerify as Decision Coverage Gate
    participant VerificationMD as VERIFICATION.md

    VerifyPhase->>ContextMD: Read <decisions> block
    ContextMD-->>CoverageVerify: Extract trackable decisions
    par Gather Evidence
        VerifyPhase->>Plans: Load plan contents
        Plans-->>CoverageVerify: Plan text
        VerifyPhase->>Summaries: Load SUMMARY files
        Summaries-->>CoverageVerify: Shipped artifact paths, commit subjects
        VerifyPhase->>Artifacts: Read files_modified content (bounded)
        Artifacts-->>CoverageVerify: Modified file contents
    end
    CoverageVerify->>CoverageVerify: Search for each decision<br/>(ID or phrase match)
    CoverageVerify-->>VerificationMD: Append Decision Coverage section<br/>(honored, not_honored list)
    CoverageVerify-->>VerifyPhase: blocking=false, coverage report
    VerifyPhase-->>VerifyPhase: Continue verification<br/>(decision gate does not affect<br/>pass/fail decision tree)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A) #2341: Foundational config/gates infrastructure and registry wiring that the decision-coverage gate feature builds upon.

Suggested labels

area: core, size/XL, review: needs discussion

Suggested reviewers

• glittercowboy

Poem

🐰 In CONTEXT bright, decisions dance,
Now plans must honor every chance!
Verify checks what truly shipped,
No decision gap shall slip away stripped.
The gates stand tall, both kind and keen,
hop hop — a workflow most serene! 🎯

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[trek-e]

Adversarial review — all 20 findings resolved

Three follow-up commits on this branch (05b53881, 4b546216, b5998830) close every review finding. Branch was rebased on origin/main (which already included #2493 / #2517 / #2607 / #2551) cleanly with no conflicts before applying fixes. npm run test:coverage is green (5409/0/0); SDK gate + parser vitest is 36/36.

F#	Severity	Finding	Commit	Status
F1	Critical	${context_path} undefined — gate never ran	05b53881	Fixed
F2	Critical	Branch 3 commits behind main; potential conflicts	rebase	Fixed (clean rebase)
F3	Critical	workstream arg dropped by gate handlers	4b546216	Fixed
F4	Major	Plan haystack matched anywhere; docs claimed must_haves/truths	4b546216	Fixed (restricted to designated sections)
F5	Major	Soft-phrase length check inverted	4b546216	Fixed (word-count gate; <6-word decisions require id)
F6	Major	files_modified only first block parsed	4b546216	Fixed (per-summary matchAll + /g)
F7	Major	Path traversal / DoS via SUMMARY files_modified	4b546216	Fixed (root-containment + 256 KB cap)
F8	Major	Commit Plans substring trap in test	05b53881	Fixed (anchored heading regex)
F9	Major	Requirements Coverage Gate substring trap in test	05b53881	Fixed (anchored heading regex)
F10	Minor	MD040 fence missing language tag	05b53881	Fixed (json + text)
F11	Minor	<decisions> extractor matched inside fenced code	b5998830	Fixed (strip fences first)
F12	Minor	Continuation regex required space; dropped tabs	b5998830	Fixed (/^[ \t]/)
F13	Minor	Only first <decisions> block parsed	b5998830	Fixed (matchAll)
F14	Minor	decisions.parse ignored projectDir	b5998830	Fixed (resolves relative paths)
F15	Major	Plan-phase blocking gate had no exit 1	05b53881	Fixed (jq -e ... || exit 1)
F16	Minor	No type validation on context_coverage_gate	4b546216	Fixed (boolean check + warn on number)
F17	Minor	ls | head in verify-phase (SC2012)	b5998830	Fixed (glob loop)
F18	Minor	git log -n 50 ignored phase boundaries	4b546216	Tuned (200 + comment; non-blocking gate is precision-vs-recall)
F19	Nit	as unknown as Record casts	4b546216	Fixed (QueryResult<T> parameterized)
F20	Nit	Incomplete unicode quote stripping	b5998830	Fixed (full U+2018-201F + backtick + double-quote)

Verify-phase gate is intentionally NOT wrapped in exit 1 — it remains non-blocking by design (rationale documented inline alongside the snippet). The duplicate decision parser between bin/lib/decisions.cjs and sdk/src/query/decisions.ts is acknowledged tech debt and out of scope for this PR; it will be unified in a follow-up.

Strong regression tests added for all three Critical findings:

• F1: a workflow-test asserts the gate snippet uses ${CONTEXT_PATH} (uppercase) and explicitly does NOT use ${context_path} (lowercase).
• F2: full-suite green post-rebase.
• F3: a workstream-scoped negative test creates a feat-x workstream with context_coverage_gate: false, leaves the root config enabled, and asserts both handlers skip when called with workstream='feat-x' and run when called without.