bug: phase complete warns on historical verification/deferred requirement metadata

[j2h4u]

Summary

gsd-tools phase complete <phase> can emit false warnings from metadata that is not part of the current phase completion contract.

Symptoms

1. A *-VERIFICATION.md with current frontmatter status: passed still warns has unresolved gaps if historical metadata contains previous_status: gaps_found.
2. REQUIREMENTS.md IDs in explicitly deferred/future/v2 sections are reported as missing from the active traceability table, even when those requirements are outside the current release scope.

Expected

• Verification completion warnings should use the current frontmatter status only, not scan the whole file for stale keys.
• Traceability warnings should apply to active/current requirements, not deferred/backlog/future sections.

Observed impact

A phase can be completed successfully but still report misleading warnings, causing operators/agents to manually edit state or traceability artifacts unnecessarily.

Repro sketch

Create .planning/phases/01-x/01-VERIFICATION.md:

---
status: passed
previous_status: gaps_found
---

Then run:

gsd-tools phase complete 01

Current behavior warns about unresolved gaps even though the current status is passed.

A second repro is a REQUIREMENTS.md with ## Deferred v2 Requirements containing IDs like FILE-001, while the active Traceability table only tracks v1 IDs. phase complete warns that deferred IDs are missing from traceability.

Notes

This was observed from a Codex runtime using GSD in a downstream repo before the latest next sync, then rechecked against current next/deploy behavior.

[trek-e]

This was generated by AI during triage.

Agent Brief — confirmed-bug, ready-for-agent

Confirmed. phase complete emits two classes of false-positive warnings on historical/valid phase metadata. Two distinct defects, both in cmdPhaseComplete (src/phase.cts).

Bug 1 — VERIFICATION.md substring grep (src/phase.cts:1371-1377)

const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8');
if (/status: gaps_found/.test(content))   warnings.push(...);
if (/status: human_needed/.test(content)) warnings.push(...);

The raw regex matches status: gaps_found anywhere in the file — including inside the key previous_status: gaps_found. A frontmatter of { status: passed, previous_status: gaps_found } falsely warns even though the current status is passed.
Fix: call readVerificationStatus(phaseFullDir) from verification.cts (already exported, parses frontmatter via extractFrontmatter and reads only the status key) and warn only on the returned current status.

Bug 2 — REQUIREMENTS.md scans deferred sections (src/phase.cts:1492-1516)

const bodyReqPattern = /\*\*([A-Z][A-Z0-9]*-\d+)\*\*/g; // scans ALL of reqContent
const unregistered = bodyReqIds.filter((id) => !tableReqIds.has(id));

Bold REQ-IDs in ## Deferred v2 Requirements / ## Future / Backlog sections are collected and flagged as "missing from Traceability table" — which correctly does not track deferred IDs. No section scoping.
Fix: before scanning, truncate reqContent at the first heading matching /^#{1,6}\s+(deferred|future|backlog|out.of.scope)/im; only scan the active prefix for bold REQ-IDs.

Tests (tests/phase.test.cjs)

• VERIFICATION.md with status: passed + previous_status: gaps_found → no warning.
• REQUIREMENTS.md with a ## Deferred v2 Requirements section containing a bold ID → no traceability warning for that ID.

Relation

Same handler as #1161 but distinct surface — #1161 is date-cell idempotency on roadmapContent; this is warning heuristics. Can be fixed independently. Mind the .cts → bin/lib/*.cjs hand-sync gate.

[trek-e]

This was generated by AI during triage.

Re-triage after ADR-857 CORE implementation (targeting 1.5.0-rc.3)

The ADR-857 capability architecture (phase 6, #1183) has landed on next — optional features (tdd, schema-gate, drift, gap-analysis, profile-pipeline) are now capabilities, the verify:post / execute:wave:post hooks are wired via render-hooks, config is federated, and the conformance gate is hardened. This issue was previously confirmed-bug; it has been reset to needs-triage and re-reviewed against the updated CORE.

Re-diagnosis (against next @ ae8bb70):

Both defects from the prior triage comment are still present and unaddressed on next. ADR-857 phase 6 did not touch src/phase.cts at all — the last modification to that file was fix(#1161) (7bc330f9) which only addressed the date-cell idempotency issue, leaving the warning heuristics intact.

Bug 1 — VERIFICATION.md raw-content regex (confirmed still present)

src/phase.cts lines 1371–1377:

for (const file of phaseFiles.filter(
  (f) => f.includes('-VERIFICATION') && f.endsWith('.md'),
)) {
  const content = fs.readFileSync(path.join(phaseFullDir, file), 'utf-8');
  if (/status: human_needed/.test(content)) warnings.push(`${file}: needs human verification`);
  if (/status: gaps_found/.test(content)) warnings.push(`${file}: has unresolved gaps`);
}

The bare /status: gaps_found/ and /status: human_needed/ regexes match anywhere in the file body — including in previous_status: gaps_found frontmatter keys, historical audit sections, or code examples. A VERIFICATION.md with { status: passed, previous_status: gaps_found } falsely triggers the warning even though verification passed.

verification.cts already exports readVerificationStatus() (line 138–209, exported at line 229) which correctly scopes status extraction to the YAML frontmatter block only via extractFrontmatter (explicitly fixing DEFECT.FRONTMATTER-SCALAR-BROAD-GREP). The cmdPhaseComplete warning block at lines 1371–1377 does not call readVerificationStatus() and therefore re-introduces the defect that verification.cts was written to prevent.

Bug 2 — REQUIREMENTS.md scans deferred sections (confirmed still present)

src/phase.cts lines 1492–1498:

const bodyReqIds: string[] = [];
const bodyReqPattern = /\*\*([A-Z][A-Z0-9]*-\d+)\*\*/g;
let bodyMatch: RegExpExecArray | null;
while ((bodyMatch = bodyReqPattern.exec(reqContent)) !== null) {
  const id = bodyMatch[1];
  if (!bodyReqIds.includes(id)) bodyReqIds.push(id);
}

reqContent is scanned in full with no section-scoping. Bold REQ-IDs appearing under ## Deferred v2 Requirements, ## Future / Backlog, or ## Out of Scope sections are collected and then flagged as "missing from Traceability table" at lines 1511–1516 — which is correct behaviour, since the Traceability table intentionally does not track deferred IDs. The fix (truncating reqContent at the first heading matching /^#{1,6}\s+(deferred|future|backlog|out.of.scope)/im before scanning) was called out in the prior triage comment but has not been applied.

ADR-857 interaction: The review verification capability migration (#1147, commit 1b880fef) moved verify:post and execute:wave:post workflow hooks into capabilities, but this is the agent/workflow layer. The in-process cmdPhaseComplete warning logic in src/phase.cts is not a capability hook — it runs inline inside the phase complete CLI command handler and was entirely unaffected by the ADR-857 migrations.

Area: area: workflow

Recommended disposition: Still a valid confirmed bug — both defects are reproducible against next @ ae8bb707. Ready for an agent fix. The fix path is well-scoped: (1) replace the raw-regex VERIFICATION block with a call to readVerificationStatus() from verification.cts and warn only on status === 'gaps_found' || status === 'human_needed'; (2) truncate reqContent before the first deferred/future/backlog heading before running the body REQ-ID scan. Tests needed per RULESET.TESTS.regression-must-fail-first.