fix(#2408): fold colliding phase statuses + add W023 collision warning (#2461)

* fix(#2408): fold colliding phase statuses + add W023 collision warning

Two coupled bugs from #2408:

1. cmdStats last-write-wins status (src/commands.cts:1610-1618): when two
   on-disk phase directories normalize to the same phase key (e.g.
   `05-real/` and `05-real-stray/`), the directory-scan merge overwrote
   `status` with whatever the *current* directory in scan order computed,
   discarding `existing?.status` entirely. fs.readdirSync order is not
   stable across platforms, so /gsd-stats could silently report `Not
   Started` for a phase that is actually `Complete`. Plan/summary counts
   were already additively merged; only `status` was wrong.

   Fix: introduced a `foldPhaseStatus(a, b)` helper that returns whichever
   status is further along the precedence ladder
   `Complete > Needs Review > Executed > In Progress > Planned > Not Started`
   (with `Pending` and unrecognized statuses ranked after). The merge site
   now calls `existing ? foldPhaseStatus(existing.status, status) : status`.
   The fold is commutative, so the result is identical regardless of read
   order.

2. cmdValidateHealth had no collision-detection pass (src/verify.cts):
   codes W001-W022 cover every condition except normalized-key collisions,
   so an operator got zero signal that anything was wrong.

   Fix: added W023 — groups phaseDirEntries by their normalized phase key
   (via the existing normalizePhaseName + extractPhaseToken helpers from
   phase-id.cjs — same normalization cmdStats uses) and emits a warning
   for any group with ≥2 dirs. The warning names the normalized key, both
   directory names (sorted by comparePhaseNum for stable output), and each
   directory's independently-computed status (via determinePhaseStatus
   imported from commands.cjs). Wording is deliberately neutral — never
   guesses which directory is the real one. The optional --repair path
   from the issue is intentionally NOT implemented in this PR (the issue
   marked it lower priority and acceptance criterion 4 is vacuously
   satisfied by omission).

Triage correction applied: the issue proposed W022, but that code is
already in use for config.json model-tier validation (src/verify.cts
:1372-1391). The next free code is W023, used here.

Tests:
- tests/commands.test.cjs: integration test that 05-real/ (Complete) +
  05-real-stray/ (empty/Not Started) collide and stats reports the merged
  phase as Complete regardless of read order; plus a direct unit test of
  foldPhaseStatus asserting commutativity + correct precedence for every
  status pair + correct handling of unrecognized statuses.
- tests/health-validation.test.cjs: integration test that W023 fires on
  the collision naming both dirs + their statuses (and uses neutral
  wording), plus a negative test that no W023 fires when only one dir
  exists per key.

References: #2408; reporter's three-layer triage + acceptance criteria;
triage correction that W022 is already in use (model-tier validation).

* chore(#2408): backfill pr:2461 in .changeset/graceful-koalas-forage.md
This commit is contained in:
Tom Boucher
2026-07-20 15:49:57 -04:00
committed by GitHub
parent 455ad49ae3
commit be5113abfe
5 changed files with 279 additions and 2 deletions

View File

@@ -2154,6 +2154,75 @@ describe('stats command', () => {
assert.strictEqual(stats.phases_completed, 1);
assert.strictEqual(stats.phases.length, 1);
});
// ─── #2408: cmdStats last-write-wins fix — colliding dirs fold by precedence ──
//
// Two on-disk phase directories that normalize to the same phase key
// (e.g. `05-real/` + `05-real-stray/`) used to silently overwrite `status`
// at the directory-scan merge site (last-write-wins), so /gsd-stats could
// report `Not Started` for a phase that is actually `Complete` depending on
// fs.readdirSync order. The fix folds colliding statuses by precedence
// (Complete > Needs Review > Executed > In Progress > Planned > Not Started),
// so the furthest-along status wins regardless of read order.
test('#2408: colliding phase directories fold to the furthest-along status (Complete wins over Not Started)', () => {
// Two dirs that both normalize to phase key "05": `05-real/` (Complete)
// and `05-real-stray/` (empty → Not Started). The merged status MUST be
// Complete regardless of which directory the fs yields first.
const realDir = path.join(tmpDir, '.planning', 'phases', '05-real');
fs.mkdirSync(realDir, { recursive: true });
fs.writeFileSync(path.join(realDir, '01-01-PLAN.md'), '# Plan');
fs.writeFileSync(path.join(realDir, '01-01-SUMMARY.md'), '# Summary');
fs.writeFileSync(path.join(realDir, 'VERIFICATION.md'), '---\nstatus: passed\n---\n# Verified');
const strayDir = path.join(tmpDir, '.planning', 'phases', '05-real-stray');
fs.mkdirSync(strayDir, { recursive: true });
// ROADMAP declares Phase 5 so the dir-scan finds an explicit phase to populate.
fs.writeFileSync(
path.join(tmpDir, '.planning', 'ROADMAP.md'),
[
'# Roadmap',
'',
'## Milestone v1',
'',
'### Phase 5: Real',
'**Goal:** The real phase',
].join('\n')
);
const result = runGsdTools('stats', tmpDir);
assert.ok(result.success, `Command failed: ${result.error}`);
const stats = JSON.parse(result.output);
assert.strictEqual(stats.phases_total, 1, 'two colliding dirs must merge into one phase');
assert.strictEqual(stats.phases_completed, 1, 'Complete status must win over Not Started after the fold');
const phase05 = stats.phases.find((p) => p.number === '05');
assert.ok(phase05, 'phase 05 must appear in stats output');
assert.strictEqual(phase05.status, 'Complete', 'folded status must be Complete, not Not Started');
});
test('#2408: foldPhaseStatus is commutative and order-independent (property)', () => {
// Direct unit test of the fold: a Complete colliding with a Not Started
// must yield Complete regardless of argument order. This is the property
// that makes the merge-site fix correct independent of fs read order.
const { foldPhaseStatus, PHASE_STATUS_PRECEDENCE } = require('../gsd-core/bin/lib/commands.cjs');
assert.strictEqual(foldPhaseStatus('Complete', 'Not Started'), 'Complete');
assert.strictEqual(foldPhaseStatus('Not Started', 'Complete'), 'Complete');
assert.strictEqual(foldPhaseStatus('Complete', 'Complete'), 'Complete');
// Every recognized status folded with a lower-precedence one wins.
for (let i = 0; i < PHASE_STATUS_PRECEDENCE.length - 1; i++) {
const higher = PHASE_STATUS_PRECEDENCE[i];
const lower = PHASE_STATUS_PRECEDENCE[i + 1];
assert.strictEqual(foldPhaseStatus(higher, lower), higher, `${higher} should beat ${lower}`);
assert.strictEqual(foldPhaseStatus(lower, higher), higher, `${higher} should beat ${lower} (commutative)`);
}
// Unrecognized status never beats a recognized one.
assert.strictEqual(foldPhaseStatus('Complete', '???'), 'Complete');
assert.strictEqual(foldPhaseStatus('???', 'Complete'), 'Complete');
// Two unrecognized → returns first arg (deterministic).
assert.strictEqual(foldPhaseStatus('foo', 'bar'), 'foo');
});
});
// ─────────────────────────────────────────────────────────────────────────────