golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(#3186): one shared phase-completion predicate, disk-strict (#3306)

Browse Source 
* docs(#3186): record the disk-strict completion decision in ADR-3180 7.4

The maintainer decided #2957 on 2026-08-08: disk state is authoritative and a
ROADMAP checkbox is a human annotation with no machine authority. Section 7.4
still carried the OPEN QUESTION and was marked blocked, so the contract said one
thing and the tracker another.

Recorded per section 7's own rule - a behavior not stated there is not decided,
and amending a rule is an ADR amendment rather than a code change with a comment.
The decision comment names Phase 4's PR as the carrier of this edit and makes it
an acceptance criterion that the text be in the tree before implementation
begins, so this lands first, alone, ahead of any code.

Also clears the stale blocked-on-2957 row in the guard roster.

* refactor(#3186): one shared phase-completion predicate, disk-strict

isPhaseComplete in verification.cts becomes the single owner. It calls
readVerificationStatus UNCONDITIONALLY - plan count is not a precondition - so a
zero-plan phase with a passing VERIFICATION.md is complete. That is #3168: init
gated the read on a plan count and synthesized a not_required sentinel, so
phase.complete succeeded while init.manager reported incomplete for the same
phase.

The guard, built and run before scope was fixed per Amendment 3, found 9
re-derivations where the ADR named 3. Four were unnamed, including one in the
prompt layer: mvp-phase.md ORed a ticked checkbox with disk status, which under
disk-strict is the divergence itself.

Per the #2957 decision, a ticked ROADMAP checkbox is a human annotation with no
machine authority. The overrides in roadmap analyze and init manager are deleted
rather than generalized; the user's checkbox stays in ROADMAP.md, only its
authority goes.

scanPhasePlans.completed and buildWorkstreamInventory are deliberately NOT folded
- they answer 'are all plans summarized', which is a different question, and
folding them would either over-report completion or invert the dependency
direction between Phase 1's owner and this one.

Verified on the remote runner.

* fix(#3186): close seven review findings and record the missing-verdict rule

The isolated review reproduced a write-path regression I introduced: migrating
cmdRoadmapUpdatePlanProgress dropped its summaryCount>=planCount gate, so a phase
with a fresh passing verification plus a newly-added unsummarized plan reported
complete AND wrote a checkbox into ROADMAP.md while phase complete refused. The
owner stays right per 7.4 - plan count is not a completion precondition - so the
gate is restored at the write site as an explicit composition, mirroring the
separate 2648 unexecuted-plan gate cmdPhaseComplete already carries.

The spec axis was right that my 0.x-split reasoning was too permissive. The 2957
decision names buildStateFrontmatter as one of the three that must converge, and
buildWorkstreamInventory combined a summaries-met local with verification data to
decide the same verdict - Decision 4(c)'s named bypass, and it reproduced 3168 in
a third surface. Both now route through the owner. The raw scanPhasePlans helper
stays: it answers are-plans-summarized, which genuinely is a different question.

Maintainer decision recorded in 7.4: a missing verdict is not a passing one, so
an absent VERIFICATION.md means not complete everywhere. That retires 2645's
verifier-disabled tolerance and inverts its Goodhart incentive - deleting the
evidence now lowers completion instead of raising it.

Guard hardened: block-form count gates and algebraic restatements are caught, and
the header now discloses its remaining limits instead of overclaiming.

Verified on the remote runner.

* fix(#3186): route state sync through the owner and catch bare completed reads

The matrix found 52 failures. 51 were fixtures asserting the old semantics: a
phase with plans and summaries but no VERIFICATION.md used to count complete and
correctly no longer does. Each fixture now carries a passing verification where
that is what the test was actually about, rather than having its assertion
weakened.

The 52nd was a real 10th re-derivation the guard could not see. cmdStateSync
destructured scanPhasePlans().completed directly - a bare field read, not a
comparison - and used it as a completion verdict, so state sync and state json
disagreed on completed_phases for identical disk state. Routed through the owner.

Guard gains shape (d): any read of .completed off a scanPhasePlans() result
outside plan-scan.cts, in chained, destructured and indirect forms, function
scoped with no line window. It cannot tell a summaries-met read from a completion
read - that is data flow - so it flags every one and requires a written-reason
exemption, which is the same discipline shapes a-c already use. The blind spot is
disclosed in the header rather than overclaimed.

The emitted-attribution failure was also mine, not pre-existing: the mvp-phase.md
checkbox-OR removal moves emitted bytes, acknowledged in tests/emitted-drift-acks.

Verified on the remote runner.

* test(#3186): give the nested-plans sync fixture a passing verification

Last 3 matrix failures were one failure echoing up two describe levels. Phase
01-alpha had plans and summaries but no VERIFICATION.md, so under disk-strict
completed stayed 0 and no Progress change was emitted - correct new behavior, not
a regression.

Added the passing verification rather than dropping the Progress expectation, so
the test still covers what #3257 is about: that a nested plans/ layout is counted
and not undercounted. Probe against the built lib confirms
Progress: 0% -> 50% alongside Total Plans in Phase: 0 -> 3.

* chore(#3186): backfill changeset PR number

pr:0 placeholder replaced with the real number now that #3306 exists.

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-10 10:18:29 -04:00
committed by GitHub
parent 96a82bbffb
commit e201cde73c
25 changed files with 2849 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
tests/state.test.cjs
View File

@@ -2054,6 +2054,11 @@ describe('milestone-scoped phase counting in frontmatter', () => {
// Add a plan to each
fs.writeFileSync(path.join(phaseDir, `${padded}-01-PLAN.md`), '# Plan');
fs.writeFileSync(path.join(phaseDir, `${padded}-01-SUMMARY.md`), '# Summary');
// Disk-strict completion (ADR-3180 §7.4, #3186): a plan+summary count no
// longer implies "complete" — only a passing *-VERIFICATION.md does. Both
// milestone phases (5 and 6) get one so this test still exercises milestone
// SCOPING, not the (now-separate) completion predicate.
if (i === 5 || i === 6) writePassedVerification(tmpDir, `${padded}-phase-${i}`, padded);
}
// Write a STATE.md and trigger a write that will sync frontmatter
@@ -2071,7 +2076,7 @@ describe('milestone-scoped phase counting in frontmatter', () => {
const output = JSON.parse(jsonResult.output);
assert.strictEqual(Number(output.progress.total_phases), 2, 'should count only milestone phases (5 and 6), not all 6');
assert.strictEqual(Number(output.progress.completed_phases), 2, 'both milestone phases have summaries');
assert.strictEqual(Number(output.progress.completed_phases), 2, 'both milestone phases have a passing verification');
});
test('total_phases includes ROADMAP phases without directories', () => {
@@ -2097,6 +2102,10 @@ describe('milestone-scoped phase counting in frontmatter', () => {
fs.mkdirSync(phaseDir, { recursive: true });
fs.writeFileSync(path.join(phaseDir, `${padded}-01-PLAN.md`), '# Plan');
fs.writeFileSync(path.join(phaseDir, `${padded}-01-SUMMARY.md`), '# Summary');
// Disk-strict completion (ADR-3180 §7.4, #3186): give each of the 4
// phases-with-directories a passing verification so this test still
// exercises ROADMAP-vs-disk SCOPING, not the completion predicate.
writePassedVerification(tmpDir, `${padded}-phase-${i}`, padded);
}
fs.writeFileSync(
@@ -2112,7 +2121,7 @@ describe('milestone-scoped phase counting in frontmatter', () => {
const output = JSON.parse(jsonResult.output);
assert.strictEqual(Number(output.progress.total_phases), 6, 'should count all 6 ROADMAP phases, not just 4 with directories');
assert.strictEqual(Number(output.progress.completed_phases), 4, 'only 4 phases have summaries');
assert.strictEqual(Number(output.progress.completed_phases), 4, 'only 4 phases have a passing verification');
});
test('without ROADMAP counts all phases (pass-all filter)', () => {
@@ -2339,6 +2348,12 @@ describe('progress counters correct after plan execution (#1589)', () => {
fs.writeFileSync(path.join(phase02Dir, '02-02-PLAN.md'), '# Plan\n');
fs.writeFileSync(path.join(phase02Dir, '02-02-SUMMARY.md'), '# Summary\n');
// Disk-strict completion (ADR-3180 §7.4, #3186): a passing *-VERIFICATION.md
// is what makes a phase complete now, not plan/summary parity — this test is
// about percent DERIVATION, so give both phases one.
writePassedVerification(tmpDir, '01-foundation', '01');
writePassedVerification(tmpDir, '02-api', '02');
// Body Progress: still says 0% (stale — never updated by update-progress)
fs.writeFileSync(
path.join(tmpDir, '.planning', 'STATE.md'),
@@ -2416,6 +2431,14 @@ describe('progress counters correct after plan execution (#1589)', () => {
fs.writeFileSync(path.join(phase04Dir, '04-02-PLAN.md'), '# Plan\n');
fs.writeFileSync(path.join(phase04Dir, '04-02-SUMMARY.md'), '# Summary\n');
// Disk-strict completion (ADR-3180 §7.4, #3186): give all 4 phases a
// passing verification so this test still exercises the STALE-FRONTMATTER
// rebuild, not the (now-separate) completion predicate.
writePassedVerification(tmpDir, '01-phase', '01');
writePassedVerification(tmpDir, '02-phase', '02');
writePassedVerification(tmpDir, '03-phase', '03');
writePassedVerification(tmpDir, '04-phase', '04');
// Write STATE.md with stale frontmatter matching the bug report exactly
fs.writeFileSync(
path.join(tmpDir, '.planning', 'STATE.md'),
@@ -9973,6 +9996,10 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
fs.writeFileSync(path.join(plansDir, planFile), '# Plan\n');
fs.writeFileSync(path.join(plansDir, summaryFile), '# Summary\n');
}
// Disk-strict completion (ADR-3180 §7.4, #3186): a passing
// *-VERIFICATION.md is what makes a phase complete, not plan/summary
// parity — this test is about nested plans/ COUNTING, not the predicate.
writePassedVerification(tmpDir, phaseSlug, `0${phase}`);
}
writeRoadmap(tmpDir, [1, 2]);
@@ -9987,7 +10014,7 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
const progress = JSON.parse(jsonResult.output).progress;
assert.strictEqual(Number(progress.total_plans), 6, 'total_plans must count nested plans/ files (2 phases × 3 plans)');
assert.strictEqual(Number(progress.completed_plans), 6, 'completed_plans must count nested summary files (2 phases × 3 summaries)');
assert.strictEqual(Number(progress.completed_phases), 2, 'completed_phases: both phases have summaries >= plans');
assert.strictEqual(Number(progress.completed_phases), 2, 'completed_phases: both phases have a passing verification');
});
test('counts PLAN-NN-slug form (bare PLAN- prefix, no phase prefix)', () => {
@@ -10025,6 +10052,9 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
fs.writeFileSync(path.join(phaseDir, '01-02-PLAN.md'), '# Plan\n');
fs.writeFileSync(path.join(phaseDir, '01-01-SUMMARY.md'), '# Summary\n');
fs.writeFileSync(path.join(phaseDir, '01-02-SUMMARY.md'), '# Summary\n');
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes the phase complete now.
writePassedVerification(tmpDir, '01-init', '01');
writeRoadmap(tmpDir, [1]);
writeStateFile(tmpDir, { phase: '01' });
@@ -10038,7 +10068,7 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
const progress = JSON.parse(jsonResult.output).progress;
assert.strictEqual(Number(progress.total_plans), 2, 'flat layout: top-level *-PLAN.md files counted');
assert.strictEqual(Number(progress.completed_plans), 2, 'flat layout: top-level *-SUMMARY.md files counted');
assert.strictEqual(Number(progress.completed_phases), 1, 'flat layout: phase complete when summaries >= plans');
assert.strictEqual(Number(progress.completed_phases), 1, 'flat layout: phase complete with a passing verification');
});
test('no double-count when both top-level and nested plan files coexist', () => {
@@ -10081,6 +10111,9 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
// One top-level plan
fs.writeFileSync(path.join(phaseDir, '01-01-PLAN.md'), '# Plan\n');
fs.writeFileSync(path.join(phaseDir, '01-01-SUMMARY.md'), '# Summary\n');
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes the phase complete now.
writePassedVerification(tmpDir, '01-init', '01');
writeRoadmap(tmpDir, [1]);
writeStateFile(tmpDir, { phase: '01' });
@@ -10094,7 +10127,7 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
const progress = JSON.parse(jsonResult.output).progress;
assert.strictEqual(Number(progress.total_plans), 1, 'empty plans/ must not add phantom plan count');
assert.strictEqual(Number(progress.completed_plans), 1, 'empty plans/ must not affect summary count');
assert.strictEqual(Number(progress.completed_phases), 1, 'phase complete: 1 summary >= 1 plan');
assert.strictEqual(Number(progress.completed_phases), 1, 'phase complete with a passing verification');
});
test('PLAN-OUTLINE.md files are excluded from nested plan count', () => {
@@ -10168,6 +10201,9 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
fs.writeFileSync(path.join(plansDir, `${num}-PLAN-${pad}-task${p}.md`), '# Plan\n');
fs.writeFileSync(path.join(plansDir, `${num}-SUMMARY-${pad}-task${p}.md`), '# Summary\n');
}
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes a phase complete now.
writePassedVerification(tmpDir, `0${num}-phase-${num}`, `0${num}`);
}
writeRoadmap(tmpDir, [1, 2]);
@@ -10182,7 +10218,7 @@ describe('buildStateFrontmatter nested plans/ layout (#3257)', () => {
const progress = JSON.parse(jsonResult.output).progress;
assert.strictEqual(Number(progress.total_plans), 7, 'reporter scenario: total_plans must be 7');
assert.strictEqual(Number(progress.completed_plans), 7, 'reporter scenario: completed_plans must be 7');
assert.strictEqual(Number(progress.completed_phases), 2, 'reporter scenario: both phases complete');
assert.strictEqual(Number(progress.completed_phases), 2, 'reporter scenario: both phases have a passing verification');
assert.strictEqual(Number(progress.percent), 100, 'reporter scenario: 100% when all plans have summaries');
});
});
@@ -10419,6 +10455,13 @@ describe('cmdStateSync nested plans/ layout (#3257)', () => {
fs.writeFileSync(path.join(plansDir, `1-SUMMARY-${pad}-t.md`), '# Summary\n');
}
}
// Disk-strict completion (ADR-3180 §7.4, #3186): a passing *-VERIFICATION.md
// is what makes a phase complete now, not plan/summary counts alone. Phase
// 01-alpha is the one this test intends to be "complete" (fully planned and
// summarized), so give it a passing verification too — otherwise completed
// phases = 0 and no Progress change is emitted, which isn't what this test
// (nested plans/ summing correctly) is about.
writePassedVerification(tmpDir, '01-alpha', '01');
const stateContent = [
'# Project State',
@@ -10692,6 +10735,10 @@ describe('buildStateFrontmatter cache invalidation (#1967)', () => {
fs.mkdirSync(phase2);
fs.writeFileSync(path.join(phase2, '02-1-PLAN.md'), '---\nphase: 2\nplan: 1\n---\n# Plan\n');
fs.writeFileSync(path.join(phase2, '02-1-SUMMARY.md'), '---\nstatus: complete\n---\n# Summary\n');
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes a phase complete now — this test is about CACHE
// invalidation, not the completion predicate, so give phase 2 one.
fs.writeFileSync(path.join(phase2, '02-VERIFICATION.md'), '---\nstatus: passed\n---\n# Verification\n');
// Second write in the SAME process — must see the new phase
const content2 = fs.readFileSync(statePath, 'utf-8');
@@ -11551,9 +11598,12 @@ describe('bug #1446 — state sync writes corrected (lower) total_phases', () =>
const dir = path.join(planning, 'phases', d);
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(path.join(dir, 'PLAN.md'), '# Plan\n', 'utf-8');
// Mark 01 and 02 as complete (2 summaries)
// Mark 01 and 02 as complete: disk-strict completion (ADR-3180 §7.4,
// #3186) requires a passing *-VERIFICATION.md, not just a summary — a
// summary alone no longer implies completion.
if (d !== '03-gamma') {
fs.writeFileSync(path.join(dir, 'PLAN-SUMMARY.md'), '# Summary\n', 'utf-8');
fs.writeFileSync(path.join(dir, `${d.slice(0, 2)}-VERIFICATION.md`), '---\nstatus: passed\n---\n# Verification\n', 'utf-8');
}
}
});
@@ -11576,10 +11626,14 @@ describe('bug #1446 — state sync writes corrected (lower) total_phases', () =>
3,
`total_phases must be corrected to 3 (derived), not kept at 10 (stale). Got ${state.progress.total_phases}`,
);
// completed_phases ratchet still works: existing 2 ≥ disk-derived → keep 2
assert.ok(
state.progress.completed_phases >= 2,
`completed_phases must be at least 2 (ratchet). Got ${state.progress.completed_phases}`,
// Disk-strict (ADR-3180 §7.4, #3186): completed_phases is recomputed from
// disk on every sync (resync=true bypasses the curated-progress ratchet),
// so it must equal the number of phases with a passing *-VERIFICATION.md
// (01 and 02), not a preserved/ratcheted stale frontmatter value.
assert.equal(
state.progress.completed_phases,
2,
`completed_phases must be 2 (01 and 02 have a passing verification). Got ${state.progress.completed_phases}`,
);
});
});
@@ -11663,6 +11717,11 @@ function seedProject(prefix, roadmap, completeDirs) {
if (completeDirs.includes(d)) {
fs.writeFileSync(path.join(dir, 'PLAN.md'), '# Plan\n', 'utf-8');
fs.writeFileSync(path.join(dir, 'SUMMARY.md'), '# Summary\n', 'utf-8');
// Disk-strict completion (ADR-3180 §7.4, #3186): a passing
// *-VERIFICATION.md is what makes a phase complete now, not a summary
// alone — this suite is about RETIRED-phase exclusion, not the
// completion predicate itself.
fs.writeFileSync(path.join(dir, `${d}-VERIFICATION.md`), '---\nstatus: passed\n---\n# Verification\n', 'utf-8');
}
}
return tmpDir;
@@ -11800,6 +11859,9 @@ function seedFromSpecs(prefix, specs) {
if (s.shipped) {
fs.writeFileSync(path.join(dir, 'PLAN.md'), '# Plan\n', 'utf-8');
fs.writeFileSync(path.join(dir, 'SUMMARY.md'), '# Summary\n', 'utf-8');
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes a phase complete now.
fs.writeFileSync(path.join(dir, `${s.dir}-VERIFICATION.md`), '---\nstatus: passed\n---\n# Verification\n', 'utf-8');
}
}
return tmpDir;
@@ -11889,6 +11951,9 @@ describe('bug #1514 — retired exclusion across phase shapes', () => {
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(path.join(dir, 'PLAN.md'), '# Plan\n', 'utf-8');
fs.writeFileSync(path.join(dir, 'SUMMARY.md'), '# Summary\n', 'utf-8');
// Disk-strict completion (ADR-3180 §7.4, #3186): only a passing
// *-VERIFICATION.md makes a phase complete now.
fs.writeFileSync(path.join(dir, `${d}-VERIFICATION.md`), '---\nstatus: passed\n---\n# Verification\n', 'utf-8');
}
tmpDir = tmp;
const result = runGsdTools(['state', 'json'], tmpDir);