enhance(#2572): run the verify-summary artifact check against phase SUMMARYs (#2685)

* enhance(#2572): run the verify-summary artifact check against phase SUMMARYs (W025)

The artifact<->git check has existed since the beginning but was only ever
pointed at .planning/research/SUMMARY.md (new-project.md:1145,
new-milestone.md:425). Phase summaries -- the ones that actually claim
"I created these files" -- were never checked.

- extract verifySummaryCore from cmdVerifySummary: same checks, lifted out of
  the output() wrapper so callers consume {passed, checks, errors} directly
  instead of shelling out and re-parsing JSON; cmdVerifySummary is now a thin
  adapter over it
- validate.health gains advisory W025 per phase SUMMARY with missing files

Advisory only: appends to warnings[], never touches status escalation beyond
the channel's own warning semantics, the repair set, or readVerificationStatus.

Resolves both open questions from triage: (a) commits_exist is deliberately NOT
surfaced -- its hash pattern matches any hex-shaped token in prose, too loose to
show a user; (b) a phase carries N per-plan summaries plus a legacy bare
SUMMARY.md, so all of them are checked via the repo-wide filter.

* chore(#2572): add changeset fragment

* feat(#2572): move the SUMMARY artifact check to phase completion

Responds to the #2685 review. Three substantive changes.

Seam (Blocker 2). The check now runs in cmdPhaseComplete, the seam the
issue body cited (src/phase.cts:~1745), not validate.health. That channel
does exist: cmdPhaseComplete declares warnings[], populates it from the
UAT/VERIFICATION pre-scan, and emits it. The cycle objection raised
against the earlier deviation holds for state.cts only -- verify.cts has
no transitive import path to phase.cts, so phase.cts -> verify.cjs adds
no cycle (verified over every src/*.cts). Moving it also retires the
retroactive firing across all historical phases: this fires once, at
completion, for the phase being completed.

Extraction (Blocker 1). Pattern 2 now excludes [ and ] from its path
class. The SUMMARY templates prescribe a YAML flow sequence
(key-files.created: [a.ts, b.ts]) and the label matches case-insensitively,
so the class previously captured the literal [ and produced a candidate
that can never exist on disk -- firing on healthy projects built from the
templates GSD itself ships. Stripping frontmatter was the other offered
remedy; measured across all three shipped templates it is a no-op on top
of the exclusion, so it is not carried. Consequence named in-code: the
key-files block still is not read, which needs a real frontmatter parse.

Also narrowed to the noise classes confirmed in review -- globs, bare
hostnames, and paths resolving outside the project are skipped rather
than reported, and the containment guard the old comment claimed now
actually exists.

Budget (Majors 1 and 3). verifySummaryCore takes a checkCommits option;
phase completion passes false, so the discarded git cat-file probes are
not spawned at all. It also passes Infinity, so every referenced file is
reported instead of the first two -- a summary listing twelve files of
which nine are missing now says nine, not zero. The verb keeps its
historical 2-file default.

Tests (Major 2). The vacuous fixtures are gone with the health block.
The replacements use /-bearing paths that genuinely extract, and each
fix was mutation-checked: un-anchoring pattern 2, dropping the glob,
hostname or containment filter, forcing commit checking on, and
re-capping at 2 each fail at least one test.

* docs(#2572): describe the phase-completion SUMMARY artifact check

The W025 text under /gsd-health is withdrawn with the health seam; the
check is documented where it now runs, under `phase complete` in
docs/CLI-TOOLS.md.

Both the docs and the changeset previously overclaimed: they said a
referenced file not on disk is warned about, while at most two candidates
per SUMMARY were ever examined. The cap is gone at this seam, so the
claim now holds -- and the text states the limits that remain, rather
than leaving them to be discovered: the key-files frontmatter block is
not read, commit hashes are not resolved, and globs, URLs, bare
hostnames and out-of-project paths are skipped rather than reported.

---------

Co-authored-by: CI Rebase Check <ci@gsd-redux>
This commit is contained in:
Rezolv
2026-07-28 18:31:33 -04:00
committed by GitHub
parent 6932fb16d7
commit 7e8f6a6d7d
6 changed files with 567 additions and 17 deletions

View File

@@ -9449,3 +9449,153 @@ describe('issue #2334: ghost-REQ-ID classification must probe write surfaces, no
},
);
});
// ─── #2572: phase-SUMMARY artifact↔disk advisory at phase completion ─────────
//
// A SUMMARY asserts "I created these files". Until #2572 nothing checked that
// claim for phase summaries — `verify-summary` existed but was only ever
// pointed at `.planning/research/SUMMARY.md`, so an interrupted or
// over-reported phase counted toward 100% silently.
//
// The advisory joins the existing `warnings[]` channel of `phase complete`
// (rendered by execute-phase.md's "If has_warnings is true" step). It is
// advisory ONLY: the completion GATE is readVerificationStatus, untouched here.
function build2572SummaryArtifactFixture() {
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-2572-artifact-'));
const planDir = path.join(tmpDir, '.planning');
const dirtyDir = path.join(planDir, 'phases', '01-dirty');
const cleanDir = path.join(planDir, 'phases', '02-clean');
fs.mkdirSync(dirtyDir, { recursive: true });
fs.mkdirSync(cleanDir, { recursive: true });
fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
// Only these two land on disk.
fs.writeFileSync(path.join(tmpDir, 'src/landed-one.ts'), 'x\n');
fs.writeFileSync(path.join(tmpDir, 'src/landed-two.ts'), 'x\n');
fs.writeFileSync(path.join(planDir, 'ROADMAP.md'), [
'# Roadmap', '',
'- [ ] Phase 01: Dirty',
'- [ ] Phase 02: Clean', '',
'### Phase 01: Dirty',
'**Goal:** Ship the dirty thing',
'**Plans:** 1 plans', '',
'### Phase 02: Clean',
'**Goal:** Ship the clean thing',
'**Plans:** 1 plans', '',
'## Progress', '',
'| Phase | Plans Complete | Status | Completed |',
'|-------|----------------|--------|-----------|',
'| 01. Dirty | 0/1 | Not started | - |',
'| 02. Clean | 0/1 | Not started | - |',
'',
].join('\n'));
fs.writeFileSync(path.join(planDir, 'STATE.md'), [
'# State', '',
'**Current Phase:** 01',
'**Current Phase Name:** Dirty',
'**Status:** In progress',
'**Completed Phases:** 0',
'**Total Phases:** 2',
'**Progress:** 0%',
'',
].join('\n'));
fs.writeFileSync(path.join(dirtyDir, '01-01-PLAN.md'), '# Plan\nDo the work.\n');
// Frontmatter uses the shipped template's YAML flow sequence on purpose: the
// bracket artifact it once produced must not surface as a phantom warning.
fs.writeFileSync(path.join(dirtyDir, '01-01-SUMMARY.md'), [
'---',
'phase: 01-dirty',
'key-files:',
' created: [src/landed-one.ts, src/never-landed.ts]',
'status: complete',
'---', '',
'# Phase 1 Summary', '',
'Created `src/landed-one.ts` and `src/never-landed.ts`.',
'',
].join('\n'));
fs.writeFileSync(path.join(cleanDir, '02-01-PLAN.md'), '# Plan\nDo the work.\n');
fs.writeFileSync(path.join(cleanDir, '02-01-SUMMARY.md'), [
'---',
'phase: 02-clean',
'key-files:',
' created: [src/landed-two.ts]',
'status: complete',
'---', '',
'# Phase 2 Summary', '',
'Created `src/landed-two.ts`.',
'',
].join('\n'));
return { tmpDir };
}
describe('#2572: phase complete warns when a SUMMARY claims files that never landed', () => {
test('#2572-1: a SUMMARY naming a file that is not on disk produces a warning at completion', () => {
const { tmpDir } = build2572SummaryArtifactFixture();
try {
const { output } = runVerifiedPhaseComplete(['phase', 'complete', '1'], tmpDir);
const parsed = JSON.parse(output);
const warnings = parsed.warnings || [];
assert.ok(
warnings.some((w) => w.includes('src/never-landed.ts')),
`#2572-1 FAILED: expected a warning naming src/never-landed.ts, got: ${JSON.stringify(warnings)}`,
);
assert.ok(
warnings.some((w) => w.includes('01-01-SUMMARY.md')),
`#2572-1 FAILED: the warning must name the SUMMARY it came from, got: ${JSON.stringify(warnings)}`,
);
assert.strictEqual(parsed.has_warnings, true, '#2572-1 FAILED: has_warnings must be true');
} finally {
cleanup(tmpDir);
}
});
test('#2572-2: the advisory is ADVISORY — completion still succeeds and reports the phase complete', () => {
const { tmpDir } = build2572SummaryArtifactFixture();
try {
const { output } = runVerifiedPhaseComplete(['phase', 'complete', '1'], tmpDir);
const parsed = JSON.parse(output);
assert.strictEqual(parsed.completed_phase, '1', '#2572-2 FAILED: completion must not be blocked by the advisory');
assert.strictEqual(parsed.state_updated, true, '#2572-2 FAILED: STATE.md must still be written');
} finally {
cleanup(tmpDir);
}
});
test('#2572-3 (control): a phase whose SUMMARY files all exist emits NO artifact warning', () => {
const { tmpDir } = build2572SummaryArtifactFixture();
try {
const { output } = runVerifiedPhaseComplete(['phase', 'complete', '2'], tmpDir);
const parsed = JSON.parse(output);
const warnings = parsed.warnings || [];
assert.ok(
!warnings.some((w) => /not on disk/.test(w)),
`#2572-3 FAILED: a clean phase must emit no artifact advisory. This is the ` +
`"absent for a clean one" half — and the fixture references a real '/'-bearing ` +
`path, so silence here is earned, not vacuous. Got: ${JSON.stringify(warnings)}`,
);
} finally {
cleanup(tmpDir);
}
});
test('#2572-4: the shipped template frontmatter flow sequence produces no phantom "[path" warning', () => {
const { tmpDir } = build2572SummaryArtifactFixture();
try {
const { output } = runVerifiedPhaseComplete(['phase', 'complete', '2'], tmpDir);
const warnings = JSON.parse(output).warnings || [];
assert.ok(
!warnings.some((w) => w.includes('[src/')),
`#2572-4 FAILED (#2685 Blocker 1): a YAML flow sequence in frontmatter must not ` +
`leak a bracket-prefixed candidate. Got: ${JSON.stringify(warnings)}`,
);
} finally {
cleanup(tmpDir);
}
});
});