53ea8e0664
* fix(#3057): refuse the write when the duplicate scan cannot complete writeManifest documents itself as a fail-closed duplicate guard: if any existing manifest shares plan_id with a different, non-terminal job_id it must refuse, because dispatching again would duplicate the external job. It could not honour that. The scan reads every sibling manifest looking for the duplicate, and an unreadable or unparseable sibling was `continue`d past. If the corrupt file was the one holding the live duplicate, the scan found nothing and a duplicate external job dispatched. The asymmetry is what gives it away: a malformed TARGET refused with malformed_existing because clobbering is unacceptable, while a malformed SIBLING was skipped — yet siblings are the only thing the duplicate check reads. Adds a scan_incomplete verdict that refuses and names the offending file, so an operator can quarantine or repair it. Fail-closed alone would let one stale corrupt manifest wedge every dispatch for that planning dir permanently; naming the file is what makes refusing survivable. malformed_existing is untouched, so the target/sibling distinction stays visible. The docstring is updated — it previously stated a rule the function did not keep. memFs() gains an optional failReads map so these branches are reachable at all; they had zero coverage because the fake could not express a per-file read fault. The signature is additive and every existing caller is unchanged. The regression is proved by a pair, not a single test. A control writes a readable sibling holding a genuine non-terminal duplicate and asserts duplicate_plan_id, establishing the scenario is real; the regression then makes that same path unreadable and asserts scan_incomplete. A first draft of this test used a corrupt-JSON fixture containing no plan_id at all while its comment claimed otherwise — it duplicated the unparseable-sibling case and proved nothing, which is the defect class this phase exists to remove. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3057): make a guard's failure distinguishable from its benign result Wave 1 of the negative-space backfill: the branches where a guard that could not verify something reported the same value it reports when everything is fine. That indistinguishability is the defect; every fix here makes the two states tellable apart, and every test proves it with a pair — one for the failure, one for the benign case. A single test cannot establish that two states are distinguishable, which is the whole property being fixed. state.cts phaseInventoryProvider returned null for both a real disk-scan failure and a genuinely empty phases dir, so `state rebuild` could report success while phase-table reconciliation never ran. It now returns a discriminated result and the CLI surfaces phase_inventory_scan_failed plus a reason. The reason field turned out never to have been wired into the emitted JSON at all — it existed only as an internal variable — so a test could only assert on the operator-facing note. It is a real field now. state.cts treated an unreadable lock body the same as an empty one, applying the 1-second stealable floor. A lock we cannot read is not a lock we know is stale; an unreadable body is now held to the deadman ceiling like a live holder. verification.cts findStaleVerificationSummary returned null on any fs, scan or clock failure — meaning "not stale". It now returns a discriminated StaleCheckResult and the caller records that the check was indeterminate. git-base-branch resolveBaseBranch returned 'main' both when no candidate branch existed and when every git tier timed out. A diagnostics variant now reports whether the answer was verified, and the CLI writes an unverified-fallback note to stderr. The stdout contract five workflows parse is untouched. worktree-safety snapshotWorktreeInventory left exists:true when statSync threw, so a guard that could not check reported the worktree present; exists is now tri-state and a stat failure surfaces as an 'unverified' finding. planWorktreePrune reported 'no_worktrees' for a parse failure, which is not the same as an empty list — and it drives a prune. It now reports 'parse_failed'. Fixing the inventory change exposed a second fail-open in verify.cts: the validate-health consumer silently dropped findings whose kind it did not recognise, so the new kind would have vanished. That is closed too — worth noting that the survey enumerated producers of degraded verdicts, not consumers that discard them. worktree-base-ref and state-transition gain the distinguishing signal without changing what they do: headAbsenceVerified, and a phase-inventory scan meta. Whether those guards should ACT differently is a product question this change does not answer, and both are flagged rather than quietly settled. rescueSummaryArtifacts is left alone: rescuing on an uncertain cat-file is deliberate per #2556. It now has tests proving it, and a recorded negative finding — git cat-file -e returns 128 for both "absent from HEAD" and a fatal error, so "uncertain" and "certain-and-fine" are not separable at the git level. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3057): assert typed values, not rendered text Ten assertions in the rebuild CLI suite matched substrings of produced output — STATE.md body fields, a markdown table row, an audit-log heading, and JSON keys read as text. CONTRIBUTING prohibits that: if the code under test produces text, the test asserts on its structured surface instead. No production surface had to be built. Every one already existed and was already compiled into bin/lib: stateExtractField for body fields, parseMarkdownTable for the phase table, collectSection for the audit-log section, and result.data.log — already a typed RebuildLogEntry[]. The tests were matching rendered text sitting next to the structured data. One of those assertions was passing for the wrong reason. `stdout.includes ('rebuilt')` matched the JSON KEY name, not a value: the dry-run path emits `mutated` and the real path emits `rebuilt`, so it would have passed whether the value was true or false. It now asserts the value. external-job's refusal already had to name the offending file — that naming is why the fail-closed variant is survivable rather than a permanent wedge — but the tests proved it by substring of a prose message. The failure result now carries offendingPath as its own field and the tests assert it by value. The human message is unchanged; operators read it. Array membership is left alone. `phaseIds.includes('99')` and `result.updated.includes('Completed Phases')` are membership checks on real arrays, not text matching, and converting them would weaken nothing and clarify nothing. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3057): execute acquireStateLock instead of grepping its source The non-EEXIST lock test asserted on the TEXT of the built .cjs and never called acquireStateLock. It carried an allow-test-rule: architectural-invariant exemption to permit that. A source grep proves a literal is present in a file, not that the behaviour works — it is weaker than a liveness test, which at least runs the code, and it was the only coverage the fatal-errno path had. Replaced with tests that inject the errno through fs and assert what actually happens: a fatal EACCES propagates out of acquireStateLock with zero backoff sleeps, while EAGAIN/EINTR/EINVAL/EIO/ENOENT/ESTALE/EPERM/EBUSY retry once and succeed. The exemption is removed and its allowlist entry with it. One old assertion is deliberately not carried over: it checked the retryable errnos were expressed as a Set rather than an inline literal. That is a shape check with no runtime signature; the behavioural tests fail if the code reverts to the old inline check, which is the regression it was really guarding. The #3057 lock-body tests move into that same file rather than a new one, which is what lint-test-file-count asks for and puts every acquireStateLock test in one place. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3057): surface an indeterminate staleness check to its callers An isolated review caught an inconsistency inside this wave. Two of the three "add the distinguishing signal" fixes wire through to something a user sees: git base-branch writes an unverified-fallback diagnostic to stderr, and an unverifiable worktree surfaces as a W020 finding. The third set staleCheckIndeterminate on readVerificationStatus's result and nothing read it. A signal nobody consumes leaves the fail-open exactly as silent as before: the staleness check could fail and the operator saw precisely what they would see if the answer were genuinely "not stale". That is the defect this issue exists to remove, so it is not defensible as scaffolding when its two siblings in the same change already wire through. All five callers now surface it, each through the channel it already had rather than a mechanism imposed uniformly: phase complete adds it to its existing warnings array and, on the blocked path, as an additive note on the error text; init and roadmap carry it as a field on output they already emit; the UAT report carries it without ever gating passed/blockers; workstream inventory takes an injectable writeDiagnostic mirroring the git base-branch idiom, because its return shape had nowhere to hang a per-phase field without rippling the builder's types. The routing decision is unchanged everywhere. What changes is only that a caller and an operator can now tell a failed check from a completed one. That diagnostic carries structured meta rather than being asserted by regex — the default still writes only the human message to stderr, but tests assert phaseDir and reason by value. Two earlier assertions in this branch were converted the same way; this was the last raw-text assertion left. Also records a scope correction: the completePhaseCore guards now compare stateReplaceField's result to the body instead of testing truthiness, so a field whose substitution produced identical text no longer reports as updated. That is a real behaviour fix, not the signal-only change this file was described as carrying, and its tests cover both the changed and unchanged cases. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3057): bound two heavy subprocesses for a loaded bench, not an idle one The remote matrix surfaced three failures unrelated to this branch's changes. All were bad tests, and a re-run would have hidden every one of them. The reviewer-flags parse block bounded bash -> node -> a full gsd-tools cold start at 5 seconds. On a bench running thirty thousand tests in parallel that is not a hang, it is a busy machine. Raised to 30s, matching the convention sibling suites already use for script invocations, with a comment saying what the budget covers so nobody tightens it back. Two further copies of the same 5-second spawn in the same file had the identical defect and are raised too — they were not in the failure report, but they will be next time. The fragment-propagation test bounded npm run regen:derived — a full build plus eight generators, the heaviest subprocess in the suite — at five minutes, and node22 was killed near the end. The captured output proves it: every generator had written its files and gen:install-tree had emitted all fifteen runtimes before the kill. Raised to fifteen minutes. That failure read as `null !== 0`, which says nothing. status null means killed, not a non-zero exit, and the two want different responses: one is a timeout to size correctly, the other is a real build break. The assertion now distinguishes them and names the signal. Neither test's assertions were weakened and no retry was added. A retry here would suppress exactly the signal the timeout exists to produce. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3057): capture fd 1 through the mock tracker, not a raw reassignment The phase suite reported zero test results on both lanes while running for five and a half minutes and exiting 1. No assertion text, no stderr, four events for the whole file: enqueue, start, dequeue, complete. That shape is not a failing assertion — it is the runner being unable to read the child at all, because it parses its event stream from the child's stdout. The cause was the capture helper reassigning fs.writeSync directly. Proven rather than assumed: a standalone probe patched fs.writeSync and called process.stdout.write, and the interception fired only when fd 1 resolved to a FILE, not when it was a pipe. The remote runner captures the event stream to a file, so a helper that was invisible against a pipe swallowed the reporter's own output on the bench. That is also why the two sibling suites wired the same way in this change pass cleanly — they use the mock tracker, the seam io.test.cjs established for this exact function. The helper now uses t.mock.method with an explicit restore after each call, so teardown belongs to node:test rather than a second hand-rolled implementation, and the interception cannot outlive the one synchronous call it wraps even if that call throws. Ten call sites thread the test context through; three test callbacks gained the parameter they lacked. The three B3 tests are untouched — same assertions, same fault injection. Only how the context reaches the helper changed. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#3057): capture phase-complete output from a subprocess, not fd 1 Two attempts to make in-process fd-1 interception safe both failed on the bench. The suite reported zero test results on either lane while exiting 1 — four events for the whole file — because the runner parses its event stream from the child's stdout, and process.stdout.write routes through fs.writeSync whenever fd 1 resolves to a file, which is how the runner captures. Patching that seam anywhere in a file can therefore destroy the file's own reporting, and tightening the window only moved the runtime from 326s to 125s without recovering a single event. So the interception is gone rather than tuned. The helper now spawns gsd-tools as a real subprocess and reads stdout the way the OS already gives it to us, which is what the rest of the suite does. It asserts the command succeeded before parsing, so a genuine failure can no longer present as a JSON parse error. The two fault-injecting tests could not survive that move as written: a subprocess cannot see a mock installed in the parent. Instead of reinstating the interception they now produce the fault on disk — the summary artifact is created as a dangling symlink, so the staleness check's real statSync throws inside the child. That is a more honest fixture than a mock in any case, since it is a condition a user's tree can actually be in. Skipped on Windows, matching the existing symlink precedent in the write-guard suite. Three further call sites turned out to depend on parent-process writeFileSync mocks the subprocess could not see. Those call the CJS function directly, which is what they always wanted — they never needed stdout at all. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3057): one name for one signal, one encoding for one distinction Standards review found four things this branch introduced, all of them inconsistencies with itself rather than with the repo. One upstream bit reached its consumers under three names — verification_stale_check_indeterminate in two modules, the same value with "stale" dropped in a third, and stderr only in the fourth. Standardised on the long name wherever it is a field. The workstream inventory keeps its stderr channel, since its return shape has nowhere to hang a per-phase field without rippling the builder's types, but it now says the same word for the same thing. worktree-safety encoded one three-way distinction two ways in a single file: a named union for a finding's kind, and boolean|null for an inventory entry's existence. The second is now a named union too. Two assertions matched human prose because the blocked and non-blocked completion paths carried no typed field for the signal. Both now assert typed values. The first round of this fix added the field but left the regex beside it, which is the banned pattern sitting next to its own replacement; the second removed it and added an assertion on the reason enum so nothing was lost. The remaining two were reasoned away before being fixed, and both reasons were bad. "No typed surface exists" is the condition CONTRIBUTING says to fix by adding one — it took three lines. "The file already does this dozens of times" is not licence to add instance number thirty-one; a convention that violates a documented rule is debt, not precedent. Vocabulary differing across DIFFERENT modules is left alone: CONTEXT.md rejects a single shared result envelope, so per-module shapes are precedented, and a baseline smell does not outrank a documented standard. A census of every line this branch adds to a test file now finds no regex or substring assertion on produced prose: 87 strictEqual, 25 ok (all non-empty or shape guards), 12 equal, 3 throws (all typed err.code predicates), 3 deepStrictEqual, 2 notStrictEqual. Refs #3051 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3057): backfill changeset pr number to 3088 --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1865 lines
98 KiB
JavaScript
1865 lines
98 KiB
JavaScript
'use strict';
|
|
|
|
// Regression + projection coverage for the workstream-inventory module.
|
|
// #1913: status must be derived from authoritative shipped signals (milestone
|
|
// archive snapshot / ROADMAP SHIPPED marker), not trusted from the mutable
|
|
// STATE.md `Status` field.
|
|
|
|
const { describe, test, before, after } = require('node:test');
|
|
const assert = require('node:assert/strict');
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
const { cleanup } = require('./helpers.cjs');
|
|
const { createFixture, seedWorkstream } = require('./fixtures/index.cjs');
|
|
const { buildWorkstreamInventory, isCompletedInventory, pickRollupWinners } = require('../gsd-core/bin/lib/workstream-inventory-builder.cjs');
|
|
const { inspectWorkstream } = require('../gsd-core/bin/lib/workstream-inventory.cjs');
|
|
const { VERIFIER_STATUSES } = require('../gsd-core/bin/lib/verification.cjs');
|
|
const { phaseKeyFromDir, phaseKeyFromProse, phaseKeyFromToken } = require('../gsd-core/bin/lib/phase-id.cjs');
|
|
const fc = require('fast-check');
|
|
|
|
const STALE_STATE = 'status: executing\n';
|
|
const IN_PROGRESS_ROADMAP =
|
|
'# Roadmap\n## Milestones\n- v2.0 Test — IN PROGRESS\n## Phases\n### Phase 1: Foo\n**Goal:** foo\n';
|
|
|
|
describe('#1913 — workstream status derived from authoritative shipped signals', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
test('builder: milestoneShipped overrides a stale executing field (derived + conflict)', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
name: 'ws-a',
|
|
projectDir: tmpDir,
|
|
workstreamDir: path.join(tmpDir, '.planning', 'workstreams', 'ws-a'),
|
|
phaseDirNames: [],
|
|
activeWorkstreamName: '',
|
|
phaseFilesCounts: [],
|
|
roadmapPhaseCount: 0,
|
|
stateProjection: { status: 'executing', current_phase: null, last_activity: null },
|
|
filesExist: { roadmap: true, state: true, requirements: true },
|
|
milestoneShipped: true,
|
|
});
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
assert.equal(inv.status_conflict, true);
|
|
});
|
|
|
|
test('builder: no shipped signal → field status, no conflict', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
name: 'ws-b',
|
|
projectDir: tmpDir,
|
|
workstreamDir: path.join(tmpDir, '.planning', 'workstreams', 'ws-b'),
|
|
phaseDirNames: [],
|
|
activeWorkstreamName: '',
|
|
phaseFilesCounts: [],
|
|
roadmapPhaseCount: 0,
|
|
stateProjection: { status: 'executing', current_phase: null, last_activity: null },
|
|
filesExist: { roadmap: true, state: true, requirements: true },
|
|
milestoneShipped: false,
|
|
});
|
|
assert.equal(inv.status, 'executing');
|
|
assert.equal(inv.status_source, 'field');
|
|
assert.equal(inv.status_conflict, false);
|
|
});
|
|
|
|
test('inspectWorkstream: shipped archive snapshot + stale executing STATE → derived complete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-archived' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), STALE_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), IN_PROGRESS_ROADMAP);
|
|
// Authoritative shipped signal: an archived milestone snapshot.
|
|
fs.mkdirSync(path.join(wsDir, 'milestones'), { recursive: true });
|
|
fs.writeFileSync(path.join(wsDir, 'milestones', 'v1.0-ROADMAP.md'), '# v1.0 archived\n');
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-archived', { active: null });
|
|
assert.ok(inv, 'inventory should be produced');
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
assert.equal(inv.status_conflict, true);
|
|
});
|
|
|
|
test('inspectWorkstream: ROADMAP SHIPPED marker + stale executing STATE → derived complete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-shipped' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), STALE_STATE);
|
|
fs.writeFileSync(
|
|
path.join(wsDir, 'ROADMAP.md'),
|
|
'# Roadmap\n## Milestones\n<details><summary>✅ v1.0 MVP - SHIPPED 2026-06-01</summary>\n## Phases\n### Phase 1: Foo\n**Goal:** foo\n'
|
|
);
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-shipped', { active: null });
|
|
assert.ok(inv, 'inventory should be produced');
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
assert.equal(inv.status_conflict, true);
|
|
});
|
|
|
|
test('inspectWorkstream: no shipped signals + executing STATE → field status, no conflict', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-active' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), STALE_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), IN_PROGRESS_ROADMAP);
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-active', { active: null });
|
|
assert.ok(inv, 'inventory should be produced');
|
|
assert.equal(inv.status, 'executing');
|
|
assert.equal(inv.status_source, 'field');
|
|
assert.equal(inv.status_conflict, false);
|
|
});
|
|
});
|
|
|
|
describe('isCompletedInventory — ADR-2207 status lifecycle', () => {
|
|
test('terminal "milestone complete" variants are completed', () => {
|
|
assert.ok(isCompletedInventory('1.0 milestone complete'));
|
|
assert.ok(isCompletedInventory('Milestone complete'));
|
|
assert.ok(isCompletedInventory('milestone complete'));
|
|
});
|
|
|
|
test('intermediate "All phases complete" is NOT completed (ADR-2207)', () => {
|
|
assert.ok(!isCompletedInventory('All phases complete'),
|
|
'All phases complete is an intermediate state — milestone not yet formally closed');
|
|
});
|
|
|
|
test('archived is completed', () => {
|
|
assert.ok(isCompletedInventory('archived'));
|
|
});
|
|
|
|
test('active statuses are NOT completed', () => {
|
|
assert.ok(!isCompletedInventory('Ready to plan'));
|
|
assert.ok(!isCompletedInventory('In progress'));
|
|
assert.ok(!isCompletedInventory('Executing'));
|
|
});
|
|
});
|
|
|
|
// #2562: progress/status must be DERIVED from on-disk artifacts scoped to the
|
|
// CURRENT milestone — never a project-lifetime "ever shipped anything" signal,
|
|
// never a denominator that silently drops declared-but-unscaffolded phases, and
|
|
// never counting a phase with a failing VERIFICATION verdict as complete.
|
|
describe('#2562 — progress/status scoped to the current milestone (derived from artifacts)', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
const BUILDER_BASE = {
|
|
projectDir: '/tmp/ws-proj',
|
|
workstreamDir: '/tmp/ws-proj/.planning/workstreams/ws',
|
|
activeWorkstreamName: '',
|
|
stateProjection: { status: 'executing', current_phase: null, last_activity: null },
|
|
filesExist: { roadmap: true, state: true, requirements: true },
|
|
milestoneShipped: false,
|
|
};
|
|
|
|
// ── Defect 3: verification-gated completeness (builder unit) ─────────────────
|
|
test('builder: SUMMARY≥PLAN but a human_needed verdict is NOT complete', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
...BUILDER_BASE,
|
|
name: 'ws',
|
|
phaseDirNames: ['1-a', '2-b'],
|
|
phaseFilesCounts: [
|
|
{ directory: '1-a', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
{ directory: '2-b', planCount: 4, summaryCount: 4, inMilestone: true, verificationStatus: 'human_needed' },
|
|
],
|
|
roadmapPhaseCount: 2,
|
|
currentMilestonePhaseCount: 2,
|
|
});
|
|
assert.equal(inv.phases.find(p => p.directory === '2-b').status, 'in_progress');
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.equal(inv.progress_percent, 50);
|
|
});
|
|
|
|
test('builder: missing/unknown verdict still counts complete (no verifier-off regression)', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
...BUILDER_BASE,
|
|
name: 'ws',
|
|
phaseDirNames: ['1-a'],
|
|
phaseFilesCounts: [
|
|
{ directory: '1-a', planCount: 2, summaryCount: 2, inMilestone: true, verificationStatus: 'missing' },
|
|
],
|
|
roadmapPhaseCount: 1,
|
|
currentMilestonePhaseCount: 1,
|
|
});
|
|
assert.equal(inv.phases[0].status, 'complete');
|
|
assert.equal(inv.progress_percent, 100);
|
|
});
|
|
|
|
// ── Defect 2: denominator includes declared-but-unscaffolded phases (builder) ─
|
|
test('builder: current-milestone denominator counts a phase with no directory', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
...BUILDER_BASE,
|
|
name: 'ws',
|
|
phaseDirNames: ['1-a', '2-b'], // phase 3 declared for the milestone but never scaffolded
|
|
phaseFilesCounts: [
|
|
{ directory: '1-a', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
{ directory: '2-b', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
],
|
|
roadmapPhaseCount: 2,
|
|
currentMilestonePhaseCount: 3,
|
|
});
|
|
assert.equal(inv.roadmap_phase_count, 3);
|
|
assert.equal(inv.completed_phases, 2);
|
|
assert.equal(inv.progress_percent, 67, 'the dirless third phase keeps this below 100');
|
|
});
|
|
|
|
// ── Defect 1: prior-milestone phases must not inflate the numerator (builder) ─
|
|
test('builder: completed prior-milestone dirs are excluded from the current rollup', () => {
|
|
const inv = buildWorkstreamInventory({
|
|
...BUILDER_BASE,
|
|
name: 'ws',
|
|
phaseDirNames: ['1-old', '2-cur'],
|
|
phaseFilesCounts: [
|
|
{ directory: '1-old', planCount: 3, summaryCount: 3, inMilestone: false, verificationStatus: 'passed' },
|
|
{ directory: '2-cur', planCount: 2, summaryCount: 0, inMilestone: true, verificationStatus: 'missing' },
|
|
],
|
|
roadmapPhaseCount: 2,
|
|
currentMilestonePhaseCount: 1,
|
|
});
|
|
assert.equal(inv.completed_phases, 0);
|
|
assert.equal(inv.total_plans, 2, 'only the current-milestone directory contributes plans');
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// ── inspectWorkstream integration (all three defects, end-to-end) ────────────
|
|
function writeWsPhase(wsDir, slug, { plans = 0, summaries = 0, verification } = {}) {
|
|
const dir = path.join(wsDir, 'phases', slug);
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
for (let i = 1; i <= plans; i++) fs.writeFileSync(path.join(dir, `0${i}-PLAN.md`), '# plan\n');
|
|
for (let i = 1; i <= summaries; i++) fs.writeFileSync(path.join(dir, `0${i}-SUMMARY.md`), '# summary\n');
|
|
if (verification) fs.writeFileSync(path.join(dir, '01-VERIFICATION.md'), `---\nstatus: ${verification}\n---\n`);
|
|
}
|
|
|
|
const MS_STATE = 'milestone: v2.0\nstatus: executing\n';
|
|
// Milestone-grouped Progress table: v2.0 declares phases 3,4,5; 1,2 are shipped v1.0.
|
|
const MS_ROADMAP = [
|
|
'# Roadmap', '', '## Progress', '',
|
|
'| Phase | Milestone | Plans | Status | Done |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
'| 1. Old A | v1.0 | 2/2 | Complete | - |',
|
|
'| 2. Old B | v1.0 | 2/2 | Complete | - |',
|
|
'| 3. New A | v2.0 | 1/1 | Complete | - |',
|
|
'| 4. New B | v2.0 | 0/1 | In Progress | - |',
|
|
'| 5. New C | v2.0 | 0/1 | Not started | - |',
|
|
'',
|
|
].join('\n');
|
|
|
|
test('inspectWorkstream: prior-milestone dirs + a dirless current phase → not complete, not 100%', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-scope' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), MS_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), MS_ROADMAP);
|
|
writeWsPhase(wsDir, '1-old-a', { plans: 2, summaries: 2, verification: 'passed' });
|
|
writeWsPhase(wsDir, '2-old-b', { plans: 2, summaries: 2, verification: 'passed' });
|
|
writeWsPhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writeWsPhase(wsDir, '4-new-b', { plans: 1, summaries: 0 }); // in progress; phase 5 has NO dir
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-scope', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 3, 'denominator = v2.0 phases {3,4,5}, incl. dirless 5');
|
|
assert.equal(inv.completed_phases, 1, 'only phase 3; shipped v1.0 phases 1,2 excluded');
|
|
assert.equal(inv.progress_percent, 33);
|
|
assert.notEqual(inv.status, 'milestone complete');
|
|
assert.equal(inv.status, 'executing');
|
|
});
|
|
|
|
// Reporter's minimal fixture (issue #2562): a FLAT Progress table (no Milestone
|
|
// column, so milestone scoping cannot engage) where phase 2 is declared as a
|
|
// table row only — no `### Phase 2` heading, no directory. The heading-only
|
|
// count sees just phase 1 and silently drops phase 2 from the denominator.
|
|
test('inspectWorkstream: flat Progress table — a table-only phase still counts in the denominator', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-flat' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), 'status: executing\n');
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
'# Roadmap', '', '## Phases', '', '### Phase 1: Foo', '**Goal:** foo', '',
|
|
'## Progress', '',
|
|
'| Phase | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- |',
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
'| 2. Bar | 0/1 | Not started | - |',
|
|
'',
|
|
].join('\n'));
|
|
writeWsPhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-flat', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2, 'table-only phase 2 must not vanish from the denominator');
|
|
assert.equal(inv.phases[0].status, 'in_progress', 'gaps_found verdict is not complete');
|
|
assert.equal(inv.completed_phases, 0);
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// A sub-phase inserted mid-milestone (`3.1-…`) has no Progress-table row. It
|
|
// inherits its parent's milestone and must land on BOTH sides of the rollup:
|
|
// numerator-only would let completed_phases exceed the denominator and cap
|
|
// back to 100%, reintroducing the very defect this issue is about.
|
|
test('inspectWorkstream: a dir-only sub-phase counts in BOTH numerator and denominator', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-subphase' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), MS_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), MS_ROADMAP);
|
|
// v2.0 declares 3,4,5. All three complete, PLUS a dir-only 3.1 still in progress.
|
|
writeWsPhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writeWsPhase(wsDir, '3.1-inserted', { plans: 2, summaries: 0 });
|
|
writeWsPhase(wsDir, '4-new-b', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writeWsPhase(wsDir, '5-new-c', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-subphase', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 4, 'denominator = declared {3,4,5} + inherited 3.1');
|
|
assert.equal(inv.completed_phases, 3);
|
|
assert.equal(inv.progress_percent, 75, 'the in-progress sub-phase must hold this below 100');
|
|
assert.equal(inv.total_plans, 5, 'the sub-phase contributes its plans too');
|
|
});
|
|
|
|
test('inspectWorkstream: a PRIOR-version snapshot does not mark the current milestone complete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-prior-snap' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), MS_STATE); // current milestone = v2.0
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), MS_ROADMAP);
|
|
fs.mkdirSync(path.join(wsDir, 'milestones'), { recursive: true });
|
|
fs.writeFileSync(path.join(wsDir, 'milestones', 'v1.0-ROADMAP.md'), '# v1.0 archived\n');
|
|
writeWsPhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-prior-snap', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'executing', 'v1.0 snapshot must not mark v2.0 complete');
|
|
assert.equal(inv.status_source, 'field');
|
|
});
|
|
|
|
test('inspectWorkstream: the CURRENT-version snapshot marks the milestone complete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-cur-snap' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), MS_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), MS_ROADMAP);
|
|
fs.mkdirSync(path.join(wsDir, 'milestones'), { recursive: true });
|
|
fs.writeFileSync(path.join(wsDir, 'milestones', 'v2.0-ROADMAP.md'), '# v2.0 archived\n');
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-cur-snap', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
});
|
|
});
|
|
|
|
// #2562 review round 2 — every one of these is a DISTINCT way to reproduce this
|
|
// issue's own symptom ("milestone complete"/100% while phases are incomplete),
|
|
// introduced by deriving the two sides of the rollup from different phase-key
|
|
// derivations rather than from the phase-id owner module. Each test reddens when
|
|
// only its own fix is reverted.
|
|
describe('#2562 — milestone scoping boundaries (one phase-key derivation)', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
function writePhase(wsDir, slug, { plans = 0, summaries = 0, verification } = {}) {
|
|
const dir = path.join(wsDir, 'phases', slug);
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
for (let i = 1; i <= plans; i++) fs.writeFileSync(path.join(dir, `0${i}-PLAN.md`), '# plan\n');
|
|
for (let i = 1; i <= summaries; i++) fs.writeFileSync(path.join(dir, `0${i}-SUMMARY.md`), '# summary\n');
|
|
if (verification) fs.writeFileSync(path.join(dir, '01-VERIFICATION.md'), `---\nstatus: ${verification}\n---\n`);
|
|
}
|
|
|
|
function roadmapWithRows(rows) {
|
|
return [
|
|
'# Roadmap', '', '## Progress', '',
|
|
'| Phase | Milestone | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
...rows,
|
|
'',
|
|
].join('\n');
|
|
}
|
|
|
|
const V2_STATE = 'milestone: v2.0\nstatus: executing\n';
|
|
|
|
// A zero-padded roadmap table against zero-padded directories. Deriving the
|
|
// table key with one regex and the directory key with another put `01` and `1`
|
|
// in different key spaces: NOTHING matched, every phase fell out of the
|
|
// milestone, and the rollup reported 0% while listing both phases complete.
|
|
test('zero-padded table rows match zero-padded directories', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-padded' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 01. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 02. Beta | v2.0 | 1/1 | Complete | - |',
|
|
]));
|
|
writePhase(wsDir, '01-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '02-beta', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-padded', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2);
|
|
assert.equal(inv.completed_phases, 2, 'padded dirs must match padded table rows');
|
|
assert.equal(inv.progress_percent, 100);
|
|
assert.deepEqual(inv.phases.map(p => p.status), ['complete', 'complete'],
|
|
'phases[] and the rollup must agree');
|
|
});
|
|
|
|
// The mirror image: an UNPADDED table against PADDED directories. Padding is a
|
|
// presentation choice on either side; one key function makes it irrelevant.
|
|
test('unpadded table rows match padded directories (and vice versa)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-mixed-pad' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 2. Beta | v2.0 | 0/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '01-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '02-beta', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-mixed-pad', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2, 'the two phases must not double-count as four');
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.equal(inv.progress_percent, 50);
|
|
});
|
|
|
|
// A project-code-prefixed directory (`PROJ-05-…`). The bespoke `^0*(\d+…)`
|
|
// directory parser yielded null for these, excluding EVERY directory from the
|
|
// milestone and pinning the workstream at 0% forever.
|
|
test('project-code-prefixed directories are scoped, not excluded', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-projcode' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| PROJ-01. Shipped | v1.0 | 1/1 | Complete | - |',
|
|
'| PROJ-05. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| PROJ-06. Beta | v2.0 | 0/1 | In Progress | - |',
|
|
]));
|
|
// The prior-milestone directory is the discriminator: a phase key that never
|
|
// resolves collapses scoping to the whole roadmap, and PROJ-01 sneaks into
|
|
// the current rollup as a third completed phase.
|
|
writePhase(wsDir, 'PROJ-01-shipped', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, 'PROJ-05-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, 'PROJ-06-beta', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-projcode', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2, 'denominator = v2.0 phases only');
|
|
assert.equal(inv.completed_phases, 1, 'prefixed dirs must scope, not be excluded outright');
|
|
assert.equal(inv.progress_percent, 50);
|
|
});
|
|
|
|
// The load-bearing invariant of the whole fix, stated directly: however a
|
|
// roadmap decorates a phase reference (padding, project code, markdown
|
|
// emphasis, a `Phase ` label, trailing prose), the key it yields must equal
|
|
// the key its own directory yields. Every blocker above is an instance of
|
|
// this property failing.
|
|
test('property: a table cell and its directory always yield the same phase key', () => {
|
|
// Padding and project code are decoration and vary INDEPENDENTLY on the two
|
|
// sides — that independence is the point. Comparing an identically-decorated
|
|
// token against itself would pass vacuously.
|
|
fc.assert(fc.property(
|
|
fc.integer({ min: 1, max: 400 }),
|
|
fc.option(fc.integer({ min: 1, max: 99 }), { nil: null }),
|
|
fc.constantFrom('', '0', '00'),
|
|
fc.constantFrom('', '0', '00'),
|
|
fc.constantFrom('', 'PROJ-', 'CK-', 'MEM-'),
|
|
fc.constantFrom('', 'PROJ-', 'CK-', 'MEM-'),
|
|
fc.constantFrom('', '**', '`'),
|
|
fc.constantFrom('', 'Phase '),
|
|
fc.stringMatching(/^[a-z][a-z-]{0,20}$/),
|
|
(num, sub, cellPad, dirPad, cellCode, dirCode, emphasis, label, slug) => {
|
|
const suffix = sub === null ? '' : `.${sub}`;
|
|
const cell = `${emphasis}${label}${cellCode}${cellPad}${num}${suffix}. Some Name${emphasis}`;
|
|
const dir = `${dirCode}${dirPad}${num}${suffix}-${slug}`;
|
|
assert.equal(phaseKeyFromProse(cell), phaseKeyFromDir(dir),
|
|
`cell ${JSON.stringify(cell)} and dir ${JSON.stringify(dir)} must share a key`);
|
|
},
|
|
), { numRuns: 1000 });
|
|
});
|
|
|
|
// A blank Milestone cell must not silently delete the phase from BOTH sides of
|
|
// the calculation — that is how an unstarted phase vanished and the remaining
|
|
// completed one rounded the workstream to 100%.
|
|
test('a blank Milestone cell keeps the phase in the denominator', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-blank-cell' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 2. Beta | | 0/1 | Not started | - |',
|
|
'| 3. Gamma | TBD | 0/1 | Not started | - |',
|
|
]));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-blank-cell', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 3, 'unattributable rows degrade over-inclusively');
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.equal(inv.progress_percent, 33);
|
|
assert.notEqual(inv.progress_percent, 100);
|
|
});
|
|
|
|
// A bullet that merely NAMES the current version with a checkmark is prose
|
|
// about a phase, not a milestone verdict. Reading it as a shipped signal
|
|
// reproduces this issue's exact symptom.
|
|
test('a checkmarked bullet naming the version does NOT mark the milestone shipped', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-bullet-tick' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 2. Beta | v2.0 | 0/1 | In Progress | - |',
|
|
]),
|
|
'## Plans',
|
|
'- [x] 03-01: Ship the v2.0 login endpoint ✅',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '2-beta', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-bullet-tick', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'executing');
|
|
assert.equal(inv.status_source, 'field');
|
|
assert.equal(inv.progress_percent, 50);
|
|
});
|
|
|
|
// `\b` does not bound a version token: `.` is a non-word character, so a naive
|
|
// `\bv2\.0\b` matches inside `v2.0.1`. A shipped SIBLING patch release must not
|
|
// close the current milestone.
|
|
test('a shipped v2.0.1 heading does NOT mark v2.0 shipped', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-version-boundary' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
roadmapWithRows(['| 1. Alpha | v2.0 | 0/1 | In Progress | - |']),
|
|
'## v2.0.1 Patch — ✅ SHIPPED',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-version-boundary', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'executing');
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// `phaseKeyFromToken` strips leading zeros per hyphen-separated segment before
|
|
// `normalizePhaseName` runs — which is BEFORE that function strips the
|
|
// project-code prefix. lint-phase-id-drift exempts phase-id.cts by design, so
|
|
// it is silent here by construction; these cases are the coverage instead.
|
|
test('key derivation is symmetric across project codes and hyphenated ids', () => {
|
|
for (const [token, dir] of [
|
|
['CK-01', 'CK-01-x'],
|
|
['CK-1', 'CK-001-x'], // padding differs across the prefix
|
|
['M1-2', 'M1-2-x'],
|
|
['P0.3-2', 'P0.3-2-x'], // letter-prefixed leading segment, preserved verbatim
|
|
['01-02', '01-02-x'],
|
|
]) {
|
|
assert.equal(phaseKeyFromToken(token), phaseKeyFromDir(dir),
|
|
`token ${token} and dir ${dir} must share a key`);
|
|
}
|
|
// Known, PRE-EXISTING asymmetry, pinned so it is not "fixed" by accident:
|
|
// in a DIRECTORY a single-digit segment after the phase number is a slug
|
|
// word, not a sub-phase (#2043/#2232 — `extractPhaseToken`), so `M1-46-6-rs`
|
|
// is phase 46. A ROADMAP token `M1-46-6` has no slug and is phase 46-06.
|
|
// Unchanged by #2562: both sides behaved this way before.
|
|
assert.equal(phaseKeyFromToken('M1-46-6'), '46-06');
|
|
assert.equal(phaseKeyFromDir('M1-46-6-rs-x'), '46');
|
|
});
|
|
|
|
// The Builder's invariant throw is a contract assertion for external callers.
|
|
// `listWorkstreamInventories` loops every workstream with no try/catch, so a
|
|
// reachable throw would take down `workstream list`/`status`/`progress` for
|
|
// ALL workstreams — this pins that the real reader cannot construct one, with
|
|
// every adversarial shape at once.
|
|
test('inspectWorkstream cannot trip the Builder invariant', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-adversarial' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Prior | v1.0 | 2/2 | Complete | - |',
|
|
'| 01. Dupe | v2.0 | 1/1 | Complete | - |',
|
|
'| 2. Dirless | v2.0 | 0/1 | Not started | - |',
|
|
'| 3. Unattributed | | 0/1 | Not started | - |',
|
|
'| PROJ-04. Prefixed | v2.0 | 1/1 | Complete | - |',
|
|
]));
|
|
writePhase(wsDir, '1-prior', { plans: 2, summaries: 2, verification: 'passed' });
|
|
writePhase(wsDir, '01-dupe', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '1-dupe-stale', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '001-dupe-staler', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, 'PROJ-04-prefixed', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '3.1-inserted', { plans: 1, summaries: 0 });
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-adversarial', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.ok(inv.completed_phases <= inv.roadmap_phase_count,
|
|
`numerator ${inv.completed_phases} must not exceed denominator ${inv.roadmap_phase_count}`);
|
|
assert.ok(inv.progress_percent < 100, 'incomplete phases must keep this below 100');
|
|
});
|
|
|
|
// A flat table earlier in the document must not shadow the milestone-grouped
|
|
// table that carries the attribution: every row would come back unattributed,
|
|
// be treated as current-milestone, and silently re-admit prior phases.
|
|
test('a milestone-grouped table wins over an earlier flat table', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-two-tables' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
'# Roadmap', '', '## Summary', '',
|
|
'| Phase | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- |',
|
|
'| 1. Prior | 2/2 | Complete | - |',
|
|
'| 2. Alpha | 1/1 | Complete | - |',
|
|
'| 3. Beta | 0/1 | Not started | - |',
|
|
'', '## Progress', '',
|
|
'| Phase | Milestone | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
'| 1. Prior | v1.0 | 2/2 | Complete | - |',
|
|
'| 2. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 3. Beta | v2.0 | 0/1 | Not started | - |',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-prior', { plans: 2, summaries: 2, verification: 'passed' });
|
|
writePhase(wsDir, '2-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-two-tables', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2, 'denominator = v2.0 phases {2,3}');
|
|
assert.equal(inv.completed_phases, 1, 'the shipped v1.0 phase must stay out');
|
|
assert.equal(inv.progress_percent, 50);
|
|
});
|
|
|
|
// An in-progress marker on the milestone heading always wins over a checkmark
|
|
// elsewhere on the same line — the active-wins rule the sectioniser applies.
|
|
test('an in-progress marker on the milestone heading beats a checkmark', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-active-wins' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
roadmapWithRows(['| 1. Alpha | v2.0 | 0/1 | In Progress | - |']),
|
|
'## v2.0 Launch — 🚧 IN PROGRESS (phase 1 scaffolded ✅)',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-active-wins', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'executing');
|
|
assert.equal(inv.status_source, 'field');
|
|
});
|
|
|
|
// The current milestone's OWN shipped heading is still honoured — the boundary
|
|
// fix must not cost the signal it exists to carry.
|
|
test('the current milestone\'s own shipped heading still marks it complete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-own-heading' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
roadmapWithRows(['| 1. Alpha | v2.0 | 1/1 | Complete | - |']),
|
|
'## v2.0 Launch — ✅ SHIPPED',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-own-heading', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
});
|
|
|
|
// Bug #2445's scenario: a stale directory colliding on phase number with a
|
|
// current one. Counting the numerator per-DIRECTORY while the denominator
|
|
// counts distinct PHASES pushed completed_phases past the denominator, where
|
|
// the old Math.min cap reported 100% and hid the unstarted phase.
|
|
test('a stale same-numbered directory does not double-count the numerator', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-dupe-dir' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
'| 2. Beta | v2.0 | 0/1 | Not started | - |',
|
|
]));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '01-alpha-old', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-dupe-dir', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 2);
|
|
assert.equal(inv.completed_phases, 1, 'two dirs, one phase');
|
|
assert.equal(inv.progress_percent, 50, 'the unstarted phase 2 must stay visible');
|
|
});
|
|
|
|
// The builder is the pure seam: a caller that hands it an inconsistent pair
|
|
// must fail loudly rather than have Math.min round the contradiction to 100%.
|
|
test('builder: a numerator above the denominator throws instead of capping to 100%', () => {
|
|
assert.throws(() => buildWorkstreamInventory({
|
|
name: 'ws',
|
|
projectDir: '/tmp/ws-proj',
|
|
workstreamDir: '/tmp/ws-proj/.planning/workstreams/ws',
|
|
activeWorkstreamName: '',
|
|
stateProjection: { status: 'executing', current_phase: null, last_activity: null },
|
|
filesExist: { roadmap: true, state: true, requirements: true },
|
|
milestoneShipped: false,
|
|
phaseDirNames: ['1-a', '2-b', '3-c'],
|
|
phaseFilesCounts: [
|
|
{ directory: '1-a', phaseKey: '01', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
{ directory: '2-b', phaseKey: '02', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
{ directory: '3-c', phaseKey: '03', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: 'passed' },
|
|
],
|
|
roadmapPhaseCount: 3,
|
|
currentMilestonePhaseCount: 2,
|
|
}), /invariant violated/);
|
|
});
|
|
|
|
// The builder hand-lists the verdicts that disqualify a phase from `complete`.
|
|
// Pin it to the verifier's own vocabulary so a new emitted status cannot land
|
|
// without a decision here.
|
|
test('parity: every verifier status other than passed blocks completeness', () => {
|
|
const nonPassing = VERIFIER_STATUSES.filter(s => s !== 'passed');
|
|
assert.ok(nonPassing.length > 0, 'guard: the verifier must emit a non-passing status');
|
|
for (const status of nonPassing) {
|
|
const inv = buildWorkstreamInventory({
|
|
name: 'ws',
|
|
projectDir: '/tmp/ws-proj',
|
|
workstreamDir: '/tmp/ws-proj/.planning/workstreams/ws',
|
|
activeWorkstreamName: '',
|
|
stateProjection: { status: 'executing', current_phase: null, last_activity: null },
|
|
filesExist: { roadmap: true, state: true, requirements: true },
|
|
milestoneShipped: false,
|
|
phaseDirNames: ['1-a'],
|
|
phaseFilesCounts: [
|
|
{ directory: '1-a', phaseKey: '01', planCount: 1, summaryCount: 1, inMilestone: true, verificationStatus: status },
|
|
],
|
|
roadmapPhaseCount: 1,
|
|
currentMilestonePhaseCount: 1,
|
|
});
|
|
assert.equal(inv.phases[0].status, 'in_progress', `verifier status "${status}" must not count complete`);
|
|
}
|
|
});
|
|
|
|
// The scoping reads the WORKSTREAM's ROADMAP/STATE pair, not the project root's.
|
|
// getMilestonePhaseFilter resolves via planningDir(cwd, ws); without the ws
|
|
// argument it falls back to GSD_WORKSTREAM, which a loop over workstreams
|
|
// cannot set per iteration.
|
|
test('scoping reads the workstream ROADMAP, not the project-root ROADMAP', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-not-root' });
|
|
fs.writeFileSync(path.join(tmpDir, '.planning', 'ROADMAP.md'), [
|
|
'# Root Roadmap', '', '## v2.0 Root — ✅ SHIPPED', '', '### Phase 9: Root only', '**Goal:** root', '',
|
|
].join('\n'));
|
|
fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'milestone: v2.0\nstatus: milestone complete\n');
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 0/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-not-root', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'executing', 'the ROOT roadmap\'s shipped v2.0 must not leak in');
|
|
assert.equal(inv.roadmap_phase_count, 1, 'root-only phase 9 must not join the denominator');
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// ─── The declared-but-empty current milestone ──────────────────────────────
|
|
//
|
|
// STATE.md's `milestone:` field updates the moment `/gsd-new-milestone` writes
|
|
// the heading; the Progress table and phase sections land later. In that
|
|
// window nothing attributes a phase to the current milestone. Scoping used to
|
|
// switch OFF there, and the fallback counted the project's ENTIRE phase
|
|
// history as both numerator and denominator — so a milestone with no work
|
|
// done reported 100% off its predecessors'. #2562's own symptom, other route.
|
|
//
|
|
// Three ROADMAP shapes reach it and each needs its own witness; the fourth is
|
|
// the legacy shape that must NOT be caught.
|
|
const V3_STATE = 'milestone: v3.0\nstatus: executing\n';
|
|
const PRIOR_ROWS = [
|
|
'| 1. Alpha | v1.0 | 1/1 | Complete | - |',
|
|
'| 2. Beta | v2.0 | 1/1 | Complete | - |',
|
|
];
|
|
|
|
function seedTwoShippedPhases(name, roadmap) {
|
|
const wsDir = seedWorkstream(tmpDir, { name });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V3_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmap);
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '2-beta', { plans: 1, summaries: 1, verification: 'passed' });
|
|
return wsDir;
|
|
}
|
|
|
|
// The common shape: `## v3.0` exists but has no phases under it yet. The
|
|
// milestone filter DOES locate the section (setting versionScoped), then the
|
|
// zero-phase pass-all degrade resets versionScoped to false — erasing the only
|
|
// evidence that the milestone exists. versionSectionFound survives that reset.
|
|
test('a located-but-empty current milestone reports 0%, not its predecessors\' 100%', () => {
|
|
const wsDir = seedTwoShippedPhases('ws-empty-section', [
|
|
'# Roadmap', '',
|
|
'## v1.0', '', '### Phase 1: Alpha', '',
|
|
'## v2.0', '', '### Phase 2: Beta', '',
|
|
'## v3.0 — Next', '',
|
|
roadmapWithRows(PRIOR_ROWS),
|
|
].join('\n'));
|
|
assert.ok(fs.existsSync(wsDir));
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-empty-section', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 0, 'v1.0/v2.0 phases must not count toward v3.0');
|
|
assert.equal(inv.roadmap_phase_count, 0, 'v3.0 declares no phases');
|
|
assert.equal(inv.progress_percent, 0, 'an unstarted milestone must never report 100%');
|
|
});
|
|
|
|
// No v3.0 section at all, but the ROADMAP versions its other milestones — so
|
|
// the filter reports missingExplicitVersion rather than a located section.
|
|
test('a current milestone absent from a versioned roadmap reports 0%', () => {
|
|
seedTwoShippedPhases('ws-absent-section', [
|
|
'# Roadmap', '',
|
|
'## v1.0', '', '### Phase 1: Alpha', '',
|
|
'## v2.0', '', '### Phase 2: Beta', '',
|
|
roadmapWithRows(PRIOR_ROWS),
|
|
].join('\n'));
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-absent-section', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 0);
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// Unversioned phase headings, but the Progress table attributes every row to
|
|
// another milestone. Neither filter flag fires; the table is the only witness.
|
|
test('a progress table attributing every row elsewhere reports 0%', () => {
|
|
seedTwoShippedPhases('ws-rows-elsewhere', [
|
|
'# Roadmap', '',
|
|
'### Phase 1: Alpha', '', '### Phase 2: Beta', '',
|
|
roadmapWithRows(PRIOR_ROWS),
|
|
].join('\n'));
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-rows-elsewhere', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 0);
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// The boundary. A free-form ROADMAP attributes no versions at all: its rows
|
|
// parse unattributed, land in the current milestone, and must keep reporting
|
|
// 100%. readCurrentMilestoneVersion hands back a non-null version for nearly
|
|
// every project, so scoping on `currentVersion` alone would zero these out.
|
|
test('a legacy roadmap with no version attribution keeps its whole-roadmap count', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-legacy-freeform' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V3_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
'# Roadmap', '', '### Phase 1: Alpha', '', '### Phase 2: Beta', '',
|
|
'## Progress', '',
|
|
'| Phase | Plans Complete | Status |',
|
|
'| --- | --- | --- |',
|
|
'| 1. Alpha | 1/1 | Complete |',
|
|
'| 2. Beta | 1/1 | Complete |', '',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-alpha', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '2-beta', { plans: 1, summaries: 1, verification: 'passed' });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-legacy-freeform', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 2, 'unattributed phases belong to the current milestone');
|
|
assert.equal(inv.progress_percent, 100, 'legacy free-form projects must not regress to 0%');
|
|
});
|
|
|
|
// Degrade direction: over-inclusive, never under. A phase scaffolded before
|
|
// the ROADMAP caught up is claimed by NO milestone, so the empty current one
|
|
// adopts it rather than dropping it from both sides of the rollup — hiding
|
|
// real work would be the same class of defect as inventing it.
|
|
test('a phase scaffolded before the roadmap catches up joins the empty milestone', () => {
|
|
const wsDir = seedTwoShippedPhases('ws-scaffold-first', [
|
|
'# Roadmap', '',
|
|
'## v1.0', '', '### Phase 1: Alpha', '',
|
|
'## v2.0', '', '### Phase 2: Beta', '',
|
|
'## v3.0 — Next', '',
|
|
roadmapWithRows(PRIOR_ROWS),
|
|
].join('\n'));
|
|
writePhase(wsDir, '3-gamma', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-scaffold-first', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.roadmap_phase_count, 1, 'the unclaimed phase 3 is v3.0\'s, and its only one');
|
|
assert.equal(inv.completed_phases, 0, 'it is started, not finished');
|
|
assert.equal(inv.progress_percent, 0);
|
|
});
|
|
|
|
// The invariant throw at the builder fires on `completedPhases > denominator`.
|
|
// A scoped milestone with a zero denominator sits one bad exclusion away from
|
|
// crashing `workstream list` on every freshly-declared milestone — a worse
|
|
// failure than a wrong percentage. Pin that it stays a number.
|
|
test('a zero-denominator scoped milestone does not trip the rollup invariant', () => {
|
|
seedTwoShippedPhases('ws-zero-denominator', [
|
|
'# Roadmap', '', '## v3.0 — Next', '', roadmapWithRows(PRIOR_ROWS),
|
|
].join('\n'));
|
|
|
|
assert.doesNotThrow(() => inspectWorkstream(tmpDir, 'ws-zero-denominator', { active: null }));
|
|
const inv = inspectWorkstream(tmpDir, 'ws-zero-denominator', { active: null });
|
|
assert.equal(inv.progress_percent, 0);
|
|
assert.equal(inv.phases.length, 2, 'the phases themselves stay listed, they just do not count');
|
|
});
|
|
});
|
|
|
|
// #2562 review round 4 — `status` was the one field still asserted from an
|
|
// un-cross-validated shipped marker: `progress_percent` derived from artifacts
|
|
// while `status` echoed the marker, so the two could contradict each other in a
|
|
// single payload. That IS this issue's symptom, reached through `status`.
|
|
//
|
|
// The cross-check differs by signal strength, and using one check for both
|
|
// regresses the archived case — see the builder comment. These four pin both
|
|
// halves plus the window where the STATE field re-asserts the refused claim.
|
|
describe('#2562 — a shipped marker its own artifacts contradict is not asserted as status', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
const V2_STATE = 'milestone: v2.0\nstatus: executing\n';
|
|
const V2_SHIPPED_STATE = 'milestone: v2.0\nstatus: milestone complete\n';
|
|
// v2.0 declares phases 3 and 4. Rows survive archiving: `milestone complete`
|
|
// COPIES ROADMAP.md to the snapshot (milestone.cts:671-674) and never
|
|
// truncates the live file.
|
|
const V2_ROADMAP = shipped => [
|
|
'# Roadmap', '',
|
|
`## Milestone v2.0 — Two${shipped ? ' — ✅ SHIPPED' : ''}`, '',
|
|
'## Progress', '',
|
|
'| Phase | Milestone | Plans | Status | Done |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
'| 3. New A | v2.0 | 1/1 | Complete | - |',
|
|
'| 4. New B | v2.0 | 0/1 | In Progress | - |',
|
|
'',
|
|
].join('\n');
|
|
|
|
function writePhase(wsDir, slug, { plans = 0, summaries = 0, verification } = {}) {
|
|
const dir = path.join(wsDir, 'phases', slug);
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
for (let i = 1; i <= plans; i++) fs.writeFileSync(path.join(dir, `0${i}-PLAN.md`), '# plan\n');
|
|
for (let i = 1; i <= summaries; i++) fs.writeFileSync(path.join(dir, `0${i}-SUMMARY.md`), '# summary\n');
|
|
if (verification) fs.writeFileSync(path.join(dir, '01-VERIFICATION.md'), `---\nstatus: ${verification}\n---\n`);
|
|
}
|
|
|
|
function writeSnapshot(wsDir) {
|
|
fs.mkdirSync(path.join(wsDir, 'milestones'), { recursive: true });
|
|
fs.writeFileSync(path.join(wsDir, 'milestones', 'v2.0-ROADMAP.md'), '# v2.0 archived\n');
|
|
}
|
|
|
|
test('a live-ROADMAP SHIPPED heading is refused while the milestone is incomplete', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-heading-lies' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), V2_ROADMAP(true));
|
|
writePhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '4-new-b', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-heading-lies', { active: null });
|
|
assert.ok(inv);
|
|
assert.notEqual(inv.status, 'milestone complete', 'phase 4 is unfinished — the heading is a claim, not a fact');
|
|
assert.equal(inv.milestone_shipped_unverified, true);
|
|
assert.equal(inv.progress_percent, 50, 'status and percent must agree');
|
|
});
|
|
|
|
// Nothing on disk contradicts the archive: `milestone complete` MOVES phase
|
|
// dirs into `milestones/v2.0-phases/` (milestone.cts:755-762) while leaving
|
|
// the Progress rows, so a correctly-archived milestone reads 0/2 by
|
|
// construction. Gating this on the completeness ratio — the obvious single
|
|
// fix — reddens here and strips `milestone complete` from every archived
|
|
// milestone in every project.
|
|
test('an archived snapshot survives its phase dirs being moved out (no ratio gate)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-archived-clean' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), V2_ROADMAP(false));
|
|
writeSnapshot(wsDir); // phases/ is empty — the dirs are under milestones/v2.0-phases/
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-archived-clean', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.status, 'milestone complete');
|
|
assert.equal(inv.status_source, 'derived');
|
|
assert.equal(inv.milestone_shipped_unverified, false);
|
|
});
|
|
|
|
// The narrow predicate "a live dir that is itself unfinished" was NOT enough:
|
|
// here the live dir is COMPLETE and the unfinished phase 2 is declared with no
|
|
// directory, so nothing is live-and-unfinished and the marker sailed through,
|
|
// reproducing the reported symptom verbatim (`milestone complete` beside 50%).
|
|
// What makes the ratio meaningful again is simply that the archive is dirty —
|
|
// any in-milestone directory outliving it — so the check is the conjunction.
|
|
test('an archived snapshot is refused when a COMPLETE live dir sits beside a dirless phase', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-archived-dirty' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), V2_ROADMAP(false));
|
|
writeSnapshot(wsDir);
|
|
writePhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' }); // complete, still live
|
|
// phase 4 is declared in the Progress table with NO directory
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-archived-dirty', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.equal(inv.roadmap_phase_count, 2, 'the dirless phase 4 stays in the denominator');
|
|
assert.equal(inv.progress_percent, 50);
|
|
assert.notEqual(inv.status, 'milestone complete', 'status must not contradict the percentage');
|
|
assert.equal(inv.milestone_shipped_unverified, true);
|
|
});
|
|
|
|
// `milestone complete` does not advance STATE's `milestone:` field
|
|
// (state-transition.cts:1335 writes status/last_activity only; :1224 is the
|
|
// separate new-milestone path), so a phase can be added or reopened while the
|
|
// shipped version is still current. That live dir DOES contradict the archive.
|
|
test('an archived snapshot is refused once a phase is reopened under it', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-archived-reopened' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), V2_ROADMAP(false));
|
|
writeSnapshot(wsDir);
|
|
writePhase(wsDir, '4-new-b', { plans: 2, summaries: 1 }); // reopened after the archive
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-archived-reopened', { active: null });
|
|
assert.ok(inv);
|
|
assert.notEqual(inv.status, 'milestone complete');
|
|
assert.equal(inv.milestone_shipped_unverified, true);
|
|
});
|
|
|
|
// The refusal must not leak back in through the STATE field, which is
|
|
// operator-written and in this window commonly says the same thing.
|
|
test('a refused marker is not re-asserted by a STATE field claiming the same', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-field-echo' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_SHIPPED_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), V2_ROADMAP(true));
|
|
writePhase(wsDir, '3-new-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
writePhase(wsDir, '4-new-b', { plans: 1, summaries: 0 });
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-field-echo', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(isCompletedInventory(inv.status), false, 'neither source may assert completion here');
|
|
assert.equal(inv.status_conflict, true, 'the field disagrees with the artifacts');
|
|
assert.equal(inv.milestone_shipped_unverified, true);
|
|
});
|
|
});
|
|
|
|
// #2645 — deleting a *-VERIFICATION.md must never raise reported completion.
|
|
// #2562 gated completeness on the verdict READ FRESH from disk every call:
|
|
// "verifier ran gaps_found, report later deleted" and "verifier never ran"
|
|
// both read as the internal 'missing' sentinel, and only the fresh read was
|
|
// consulted — so deleting the evidence file alone was enough to silently
|
|
// raise completed_phases/progress_percent. The fix persists the last REAL
|
|
// verdict observed per phase key in a ledger file living at the WORKSTREAM
|
|
// level (`.verification-ledger.json`, sibling to STATE.md/ROADMAP.md),
|
|
// consulted only when the live read comes back 'missing'.
|
|
describe('#2645 — deleting a verification report must not raise completeness', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
const FLAT_STATE = 'status: executing\n';
|
|
function flatRoadmap(rows) {
|
|
return [
|
|
'# Roadmap', '', '## Progress', '',
|
|
'| Phase | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- |',
|
|
...rows,
|
|
'',
|
|
].join('\n');
|
|
}
|
|
|
|
function writePhase(wsDir, slug, { plans = 1, summaries = 1, verification } = {}) {
|
|
const dir = path.join(wsDir, 'phases', slug);
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
for (let i = 1; i <= plans; i++) fs.writeFileSync(path.join(dir, `0${i}-PLAN.md`), '# plan\n');
|
|
for (let i = 1; i <= summaries; i++) fs.writeFileSync(path.join(dir, `0${i}-SUMMARY.md`), '# summary\n');
|
|
if (verification) fs.writeFileSync(path.join(dir, '01-VERIFICATION.md'), `---\nstatus: ${verification}\n---\n`);
|
|
return dir;
|
|
}
|
|
|
|
function verificationFilePath(wsDir, slug) {
|
|
return path.join(wsDir, 'phases', slug, '01-VERIFICATION.md');
|
|
}
|
|
|
|
// Row 1 — failing-first regression, the issue's own reproduction sequence.
|
|
test('deleting a gaps_found report after it was observed does not raise completeness (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-gaps' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
|
|
const before1 = inspectWorkstream(tmpDir, 'ws-2645-gaps', { active: null });
|
|
assert.ok(before1);
|
|
assert.equal(before1.phases[0].status, 'in_progress', 'gaps_found must not count as complete');
|
|
assert.equal(before1.completed_phases, 0);
|
|
assert.equal(before1.progress_percent, 0);
|
|
|
|
fs.unlinkSync(verificationFilePath(wsDir, '1-foo'));
|
|
|
|
const after1 = inspectWorkstream(tmpDir, 'ws-2645-gaps', { active: null });
|
|
assert.ok(after1);
|
|
assert.equal(after1.phases[0].status, 'in_progress',
|
|
'deleting the failing report must not flip the phase to complete');
|
|
assert.equal(after1.completed_phases, 0, 'deleting evidence must never raise completed_phases');
|
|
assert.equal(after1.progress_percent, 0, 'deleting evidence must never raise progress_percent');
|
|
});
|
|
|
|
// Row 2 — the other FAILING_VERIFICATION_STATUSES member.
|
|
test('deleting a human_needed report after it was observed does not raise completeness (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-human' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'human_needed' });
|
|
|
|
inspectWorkstream(tmpDir, 'ws-2645-human', { active: null }); // observe while present
|
|
fs.unlinkSync(verificationFilePath(wsDir, '1-foo'));
|
|
|
|
const after = inspectWorkstream(tmpDir, 'ws-2645-human', { active: null });
|
|
assert.ok(after);
|
|
assert.equal(after.phases[0].status, 'in_progress');
|
|
assert.equal(after.completed_phases, 0);
|
|
assert.equal(after.progress_percent, 0);
|
|
});
|
|
|
|
// Row 3 — criterion 2: verifier-disabled projects (no report ever written)
|
|
// must still be able to reach 100%.
|
|
test('a phase that was never verified still reaches complete (#2645, criterion 2)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-never' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1 }); // no verification file, ever
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-2645-never', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'complete');
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.equal(inv.progress_percent, 100);
|
|
});
|
|
|
|
// Row 4 — criterion 3: same on-disk shape as row 3 (no file), across TWO
|
|
// reads, must behave IDENTICALLY — the ledger must not newly gate a phase
|
|
// that was simply never verified in the first place.
|
|
test('a not-yet-verified phase is not newly gated by the ledger (#2645, criterion 3)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-not-yet' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1 });
|
|
|
|
const first = inspectWorkstream(tmpDir, 'ws-2645-not-yet', { active: null });
|
|
const second = inspectWorkstream(tmpDir, 'ws-2645-not-yet', { active: null });
|
|
assert.equal(first.progress_percent, 100);
|
|
assert.equal(second.progress_percent, 100, 'a second read must not change the outcome');
|
|
assert.equal(second.phases[0].status, 'complete');
|
|
});
|
|
|
|
// Row 5 — recovery: a genuinely re-verified phase must not be pinned by an
|
|
// earlier failing verdict the ledger remembers.
|
|
test('a re-verified passed phase is not pinned by an earlier failing ledger entry (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-recover' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
inspectWorkstream(tmpDir, 'ws-2645-recover', { active: null }); // observe gaps_found
|
|
|
|
// Re-verify: overwrite the report with a passing verdict.
|
|
fs.writeFileSync(verificationFilePath(wsDir, '1-foo'), '---\nstatus: passed\n---\n');
|
|
const reverified = inspectWorkstream(tmpDir, 'ws-2645-recover', { active: null });
|
|
assert.equal(reverified.phases[0].status, 'complete', 'a genuine re-verify must count');
|
|
|
|
// Delete the now-passing report — the ledger's newest real verdict is
|
|
// 'passed', which is not in the failing set, so this must stay complete.
|
|
fs.unlinkSync(verificationFilePath(wsDir, '1-foo'));
|
|
const afterDelete = inspectWorkstream(tmpDir, 'ws-2645-recover', { active: null });
|
|
assert.equal(afterDelete.phases[0].status, 'complete',
|
|
'the ledger must hold the newest verdict, not an earlier failing one');
|
|
});
|
|
|
|
// Row 6 — criterion 4: the ledger must not live inside the phase directory
|
|
// whose file is the one being deleted.
|
|
test('ledger file lives outside the phase directory it protects (#2645, criterion 4)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-location' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
const phaseDir = writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
inspectWorkstream(tmpDir, 'ws-2645-location', { active: null });
|
|
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
assert.ok(fs.existsSync(ledgerPath), 'the ledger must be persisted somewhere');
|
|
assert.ok(!ledgerPath.startsWith(phaseDir + path.sep) && ledgerPath !== phaseDir,
|
|
'the ledger must not live inside the phase directory');
|
|
|
|
// Deleting the ENTIRE phase directory (not just the report) must not
|
|
// touch the ledger — this is what "not the same file" is protecting
|
|
// against in the realistic case.
|
|
cleanup(phaseDir);
|
|
assert.ok(fs.existsSync(ledgerPath), 'removing the phase directory must not remove the ledger');
|
|
});
|
|
|
|
// Row 7 — Bug #2445 dedup safety: a stale duplicate directory sharing the
|
|
// same phase key must not be able to clobber the WINNING (newest)
|
|
// directory's ledger entry with its own stale/leftover verdict.
|
|
test('a stale duplicate directory cannot clobber the ledger entry of the live directory (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-dupe' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
'| 2. Bar | 0/1 | Not started | - |',
|
|
]));
|
|
// Stale leftover directory (older mtime), leftover gaps_found report.
|
|
const staleDir = writePhase(wsDir, '01-foo-old', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const oldTime = new Date('2020-01-01T00:00:00Z');
|
|
fs.utimesSync(staleDir, oldTime, oldTime);
|
|
// Live/winning directory (newer mtime), currently passed.
|
|
const liveDir = writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'passed' });
|
|
const newTime = new Date('2026-01-01T00:00:00Z');
|
|
fs.utimesSync(liveDir, newTime, newTime);
|
|
|
|
const before7 = inspectWorkstream(tmpDir, 'ws-2645-dupe', { active: null });
|
|
assert.ok(before7);
|
|
assert.equal(before7.completed_phases, 1, 'the winning (newest) directory is passed');
|
|
|
|
// Delete the WINNING directory's report. If the stale directory's
|
|
// gaps_found had clobbered the ledger, this phase key would now
|
|
// incorrectly read gaps_found and never recover. It must instead read
|
|
// the winning directory's own remembered 'passed'.
|
|
fs.unlinkSync(path.join(liveDir, '01-VERIFICATION.md'));
|
|
|
|
const after7 = inspectWorkstream(tmpDir, 'ws-2645-dupe', { active: null });
|
|
assert.ok(after7);
|
|
assert.equal(after7.completed_phases, 1,
|
|
"the ledger must remember the WINNING directory's passed verdict, not the stale duplicate's gaps_found");
|
|
});
|
|
|
|
// Row 8 — boundary: an EXACT mtime tie between two same-keyed directories.
|
|
// The builder's own tie-break (`rollupDirByKey`) walks
|
|
// `[...phaseDirNames].sort()` and keeps the incumbent on a tie
|
|
// (first-in-sort-order wins, since only a STRICTLY newer mtime replaces
|
|
// it). The ledger's winner selection must walk the SAME sorted order so
|
|
// the two deterministically agree on which directory wins — not merely
|
|
// "some directory wins" (a prior version of this test asserted only
|
|
// `completed_phases === 0 || 1`, which is true regardless of agreement and
|
|
// caught nothing; both `01-foo-a`/`01-foo-b` sort deterministically, so the
|
|
// outcome here is not a coin flip).
|
|
test('an exact mtime tie resolves the ledger winner by sort order, matching the builder (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-tie' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
]));
|
|
const tieTime = new Date('2025-06-01T00:00:00Z');
|
|
// '01-foo-a' sorts before '01-foo-b' — with equal mtimes, BOTH the
|
|
// builder's rollup and the ledger's winner selection must keep the
|
|
// incumbent '01-foo-a' (passed), never adopt '01-foo-b' (gaps_found).
|
|
const dirA = writePhase(wsDir, '01-foo-a', { plans: 1, summaries: 1, verification: 'passed' });
|
|
fs.utimesSync(dirA, tieTime, tieTime);
|
|
const dirB = writePhase(wsDir, '01-foo-b', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
fs.utimesSync(dirB, tieTime, tieTime);
|
|
|
|
assert.doesNotThrow(() => inspectWorkstream(tmpDir, 'ws-2645-tie', { active: null }));
|
|
const inv = inspectWorkstream(tmpDir, 'ws-2645-tie', { active: null });
|
|
assert.ok(inv);
|
|
// Deterministic, not "either is fine": the builder's own rollup counts
|
|
// exactly the sort-order incumbent (01-foo-a, passed) as complete.
|
|
assert.equal(inv.completed_phases, 1,
|
|
'the sort-order incumbent (01-foo-a, passed) must be the one the builder counts complete');
|
|
|
|
// Concrete cross-check that the LEDGER's winner selection agrees with the
|
|
// builder's, not just that this run's numbers happen to match: delete
|
|
// 01-foo-a's report (unlink bumps the directory's mtime — restore it to
|
|
// the exact tie value so the SECOND read still sees a genuine tie, not a
|
|
// newest-mtime win). If the ledger's winner selection had instead picked
|
|
// 01-foo-b (the bug this test guards — unsorted iteration disagreeing
|
|
// with the builder's sorted `rollupDirByKey`), this phase key's
|
|
// remembered verdict would be 'gaps_found' and the phase would flip to
|
|
// in_progress. It must instead stay complete, because the ledger
|
|
// remembers 01-foo-a's 'passed' — the same directory the builder uses.
|
|
fs.unlinkSync(path.join(dirA, '01-VERIFICATION.md'));
|
|
fs.utimesSync(dirA, tieTime, tieTime); // restore the tie the unlink disturbed
|
|
const afterDelete = inspectWorkstream(tmpDir, 'ws-2645-tie', { active: null });
|
|
assert.equal(afterDelete.completed_phases, 1,
|
|
"the ledger must have remembered the sort-order incumbent's 'passed' verdict, not the other directory's gaps_found");
|
|
});
|
|
|
|
// Row 9 — property: whatever sequence of REAL verdicts is observed for a
|
|
// phase key, once the file goes missing the ledger must replay exactly the
|
|
// LAST one observed — never an earlier one, never a synthesized value.
|
|
//
|
|
// #2645 review: `'stale'` is deliberately EXCLUDED here, not merely
|
|
// forgotten. Writing a literal `status: stale` frontmatter value does NOT
|
|
// round-trip as `'stale'` — `readVerificationStatus`
|
|
// (`src/verification.cts`) explicitly excludes `'stale'` from its raw-file
|
|
// routing lookup (`rawStatus !== 'stale'`) and falls through to the
|
|
// "Unknown value" branch, returning `'unknown'` instead. A genuine
|
|
// `'stale'` verdict is only reachable via `findStaleVerificationSummary`'s
|
|
// mtime comparison (a SUMMARY file newer than the VERIFICATION file), not
|
|
// by writing the word into the file. Including `'stale'` in this array
|
|
// without accounting for that would silently substitute `'unknown'` on
|
|
// every iteration and still pass (both are non-failing) — a docstring
|
|
// claiming "real verdicts" coverage it does not actually exercise.
|
|
// `'stale'` handling is explicitly out of scope for this issue (#2348) and
|
|
// is not gated by `FAILING_VERIFICATION_STATUSES` either way.
|
|
test('property: the ledger always replays the most recently observed real verdict after deletion (#2645)', () => {
|
|
const REAL_STATUSES = ['passed', 'gaps_found', 'human_needed', 'unknown'];
|
|
const FAILING = new Set(['gaps_found', 'human_needed']);
|
|
fc.assert(fc.property(
|
|
fc.array(fc.constantFrom(...REAL_STATUSES), { minLength: 1, maxLength: 6 }),
|
|
(sequence) => {
|
|
const wsName = `ws-2645-prop-${Math.random().toString(36).slice(2)}`;
|
|
const wsDir = seedWorkstream(tmpDir, { name: wsName });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
]));
|
|
const dir = writePhase(wsDir, '1-foo', { plans: 1, summaries: 1 });
|
|
const reportPath = path.join(dir, '01-VERIFICATION.md');
|
|
|
|
let lastReal = null;
|
|
for (const status of sequence) {
|
|
fs.writeFileSync(reportPath, `---\nstatus: ${status}\n---\n`);
|
|
inspectWorkstream(tmpDir, wsName, { active: null }); // observe
|
|
lastReal = status;
|
|
}
|
|
fs.unlinkSync(reportPath);
|
|
|
|
const inv = inspectWorkstream(tmpDir, wsName, { active: null });
|
|
const expectComplete = !FAILING.has(lastReal);
|
|
assert.equal(inv.phases[0].status === 'complete', expectComplete,
|
|
`after observing ${JSON.stringify(sequence)} then deleting, status must reflect the last real verdict (${lastReal})`);
|
|
|
|
cleanup(wsDir);
|
|
},
|
|
), { numRuns: 25 });
|
|
});
|
|
|
|
// Row 10 — CONTRIBUTING.md "Filesystem writes and installers": code that
|
|
// writes under `.planning` needs fault-injection coverage. A corrupted
|
|
// `.verification-ledger.json` (bad JSON, or valid JSON of the wrong shape)
|
|
// must degrade to "nothing remembered", never throw and never break the
|
|
// read-only commands this ledger is a side effect of.
|
|
test('a corrupted ledger file degrades to no memory instead of throwing (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-corrupt-ledger' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
// Not valid JSON at all.
|
|
fs.writeFileSync(ledgerPath, 'not json{{{');
|
|
assert.doesNotThrow(() => inspectWorkstream(tmpDir, 'ws-2645-corrupt-ledger', { active: null }));
|
|
|
|
// Valid JSON, wrong shape (array instead of object) — must also degrade,
|
|
// not partially trust it.
|
|
fs.writeFileSync(ledgerPath, '["gaps_found"]');
|
|
const inv = inspectWorkstream(tmpDir, 'ws-2645-corrupt-ledger', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress', 'the live gaps_found read still governs regardless of ledger corruption');
|
|
});
|
|
|
|
// Row 10b — the path Row 10 does NOT exercise (a live report is present in
|
|
// both its cases, so the live read governs regardless of ledger state).
|
|
// With the report ALSO absent, a corrupt ledger must fail CLOSED — an
|
|
// unreadable/malformed ledger for an ADOPTED workstream (the ledger file
|
|
// exists) is treated as "present, no trustworthy entry", exactly like
|
|
// "present, no entry for this phase", NOT as "absent" (pre-adoption). This
|
|
// is the fail-open→fail-closed distinction the maintainer's review required.
|
|
test('a corrupted ledger with no live report fails closed instead of completing (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-corrupt-no-report' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
// Adopt the ledger for real (a genuine observation), matching the shape
|
|
// of an actually-used workstream, THEN corrupt it and remove the report —
|
|
// this is the realistic "ledger existed, now can't be trusted, AND the
|
|
// evidence that would let the live read cover for it is also gone" case.
|
|
const before = inspectWorkstream(tmpDir, 'ws-2645-corrupt-no-report', { active: null });
|
|
assert.equal(before.completed_phases, 0, 'guard: starts correctly gated by the live gaps_found verdict');
|
|
|
|
fs.unlinkSync(path.join(wsDir, 'phases', '1-foo', '01-VERIFICATION.md'));
|
|
fs.writeFileSync(ledgerPath, 'not json{{{');
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-corrupt-no-report', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress',
|
|
'a corrupt ledger for an adopted workstream must fail closed, not silently permit completion');
|
|
assert.equal(inv.completed_phases, 0, 'the percentage must not rise just because the ledger became unreadable');
|
|
});
|
|
|
|
// Row 13 — "delete the ledger" case #1: the ledger file is removed, but
|
|
// the phase's report is STILL PRESENT and still fails verification. This
|
|
// must never raise completeness (the live read governs regardless of
|
|
// ledger presence), and the deletion must be SELF-HEALING: the very next
|
|
// read that observes the still-present real verdict recreates the ledger.
|
|
test('deleting only the ledger file (report still present) does not raise completeness and self-heals (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-delete-ledger-only' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
inspectWorkstream(tmpDir, 'ws-2645-delete-ledger-only', { active: null }); // adopt
|
|
assert.ok(fs.existsSync(ledgerPath), 'guard: the ledger must exist before deleting it is meaningful');
|
|
|
|
fs.unlinkSync(ledgerPath);
|
|
const afterLedgerDelete = inspectWorkstream(tmpDir, 'ws-2645-delete-ledger-only', { active: null });
|
|
assert.equal(afterLedgerDelete.completed_phases, 0,
|
|
'the still-present gaps_found report must keep this gated regardless of the ledger');
|
|
assert.ok(fs.existsSync(ledgerPath), 'a read that observes a real verdict must recreate/self-heal the ledger');
|
|
});
|
|
|
|
// Row 14 — the DISCLOSED, ACCEPTED residual gap, pinned deliberately so it
|
|
// is never mistaken for a silent regression: deleting the report AND the
|
|
// ledger TOGETHER, after a failing verdict was already observed and
|
|
// recorded, returns this phase key to the pre-adoption `'absent'` ledger
|
|
// state — indistinguishable, by design, from a workstream that never used
|
|
// the verifier at all (criteria 2/3 require exactly that indistinguishability
|
|
// for a workstream that HASN'T adopted the ledger). This is the "prospective
|
|
// only" limitation named in the changeset: any durable store that must fail
|
|
// OPEN when wholly absent (to avoid gating every pre-existing project on
|
|
// upgrade) has this property at its own root. The bar is raised from "delete
|
|
// one file" to "delete two files in two different directories, one of which
|
|
// this issue's own reproduction never needed to touch" — not eliminated.
|
|
test('deleting the report AND the ledger together reopens the pre-adoption window (documented, not a regression) (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-delete-both' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
inspectWorkstream(tmpDir, 'ws-2645-delete-both', { active: null }); // adopt + observe gaps_found
|
|
assert.ok(fs.existsSync(ledgerPath));
|
|
|
|
fs.unlinkSync(path.join(wsDir, 'phases', '1-foo', '01-VERIFICATION.md'));
|
|
fs.unlinkSync(ledgerPath);
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-2645-delete-both', { active: null });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'complete',
|
|
'documented limitation: removing BOTH files returns this phase to the pre-adoption/never-verified state — ' +
|
|
'this is the accepted "prospective only" boundary, not a bug in this fix');
|
|
});
|
|
|
|
// Row 11 — fault injection per CONTRIBUTING.md: read-only target directory
|
|
// / partial write failure. Monkeypatch `fs.writeFileSync` to throw only for
|
|
// the ledger's WRITE TARGET (delegating everything else to the real
|
|
// implementation, since STATE.md/ROADMAP.md/phase files also go through
|
|
// the same fs module) — `inspectWorkstream` must still return a valid
|
|
// inventory rather than propagating the write failure. Restored via
|
|
// `t.after()` (never `try/finally` in a test body — CONTRIBUTING.md:344 —
|
|
// and never `chmod 0o000`, which root bypasses in CI).
|
|
//
|
|
// #2645 review: the write target is the ledger's TEMP file
|
|
// (`<ledgerPath>.<pid>.tmp`), not `ledgerPath` itself — the write is
|
|
// atomic (temp file + rename, #2645 review). Matching only the exact
|
|
// final path here made this mock a no-op once atomicity landed (the real
|
|
// write always succeeded, so the assertion that follows failed): fixed to
|
|
// match anything starting with `ledgerPath`, which covers the temp file
|
|
// regardless of its exact suffix.
|
|
test('a write failure on the ledger file does not break inspectWorkstream (#2645)', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-write-fail' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
const originalWriteFileSync = fs.writeFileSync;
|
|
fs.writeFileSync = (targetPath, ...rest) => {
|
|
if (typeof targetPath === 'string' && targetPath.startsWith(ledgerPath)) {
|
|
throw new Error('injected: simulated read-only target directory');
|
|
}
|
|
return originalWriteFileSync(targetPath, ...rest);
|
|
};
|
|
t.after(() => { fs.writeFileSync = originalWriteFileSync; });
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-write-fail', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress', 'the inventory is still correct even though persistence failed');
|
|
assert.ok(!fs.existsSync(ledgerPath), 'the failed write must not have left a partial/corrupt ledger file');
|
|
const leftoverTmp = fs.readdirSync(wsDir).filter(name => name.startsWith('.verification-ledger.json.') && name.endsWith('.tmp'));
|
|
assert.deepEqual(leftoverTmp, [], 'a failed temp-file write must not leave an orphaned temp file behind');
|
|
});
|
|
|
|
// Row 12 — the read-side counterpart: a read failure on the ledger path
|
|
// specifically (e.g. permission denied) must also degrade rather than
|
|
// throw, and must not mask the live on-disk verdict for THIS call.
|
|
test('a read failure on the ledger file does not break inspectWorkstream (#2645)', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-read-fail' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | Complete | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
// Seed a ledger entry via a real (unmocked) observation first.
|
|
inspectWorkstream(tmpDir, 'ws-2645-read-fail', { active: null });
|
|
assert.ok(fs.existsSync(ledgerPath), 'guard: the ledger must exist before the read-failure case is meaningful');
|
|
|
|
const originalReadFileSync = fs.readFileSync;
|
|
fs.readFileSync = (targetPath, ...rest) => {
|
|
if (typeof targetPath === 'string' && targetPath === ledgerPath) {
|
|
throw new Error('injected: simulated permission denied');
|
|
}
|
|
return originalReadFileSync(targetPath, ...rest);
|
|
};
|
|
t.after(() => { fs.readFileSync = originalReadFileSync; });
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-read-fail', { active: null }); });
|
|
assert.ok(inv);
|
|
// The ledger read failed (treated as 'corrupt', not 'absent', since the
|
|
// file DOES exist) — this workstream has adopted the ledger, so this
|
|
// falls CLOSED. The report is still live on disk with a real
|
|
// (non-missing) gaps_found verdict though, so the phase is correctly
|
|
// in_progress from the LIVE read regardless — the fail-closed path isn't
|
|
// even reached for this phase (its live read isn't 'missing').
|
|
assert.equal(inv.phases[0].status, 'in_progress');
|
|
});
|
|
|
|
// Row 15 — CONTRIBUTING.md fault-injection: broken symlink. `readFileSync`
|
|
// FOLLOWS symlinks, so a broken symlink at the ledger path reports the
|
|
// SAME `ENOENT` as genuine absence via errno alone — `readVerificationLedger`
|
|
// disambiguates with `lstatSync` (which does NOT follow symlinks) before
|
|
// concluding `'absent'`. This is the realistic worst case: the durable
|
|
// memory is unreadable AND there is no live report to fall back on.
|
|
test('a broken symlink at the ledger path fails closed instead of falling open to pre-adoption (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-broken-symlink' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
const before = inspectWorkstream(tmpDir, 'ws-2645-broken-symlink', { active: null }); // adopt
|
|
assert.equal(before.completed_phases, 0, 'guard: gated by the live gaps_found verdict');
|
|
|
|
fs.unlinkSync(path.join(wsDir, 'phases', '1-foo', '01-VERIFICATION.md'));
|
|
fs.unlinkSync(ledgerPath);
|
|
fs.symlinkSync(path.join(wsDir, 'does-not-exist-target'), ledgerPath);
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-broken-symlink', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress',
|
|
'a broken symlink is evidence something existed — it must fail closed, not fall open to pre-adoption behavior');
|
|
assert.equal(inv.completed_phases, 0, 'the percentage must not rise because the ledger became a broken symlink');
|
|
});
|
|
|
|
// Row 15b — pins the lstat fail-closed fix specifically. The broken-symlink
|
|
// disambiguation in `readVerificationLedger` calls `fs.lstatSync` after
|
|
// `fs.readFileSync` reports `ENOENT`, to tell "genuinely absent" from "a
|
|
// symlink entry exists, its target does not". A REVIEW caught that the
|
|
// `catch` around that `lstatSync` call originally treated ANY lstat
|
|
// failure as proof of absence — but only `lstatSync` ITSELF reporting
|
|
// `ENOENT` is genuine proof; a DIFFERENT lstat failure (a raced permission
|
|
// change, a path component that became inaccessible between the two
|
|
// calls, …) is not evidence the file was never there, and must fail
|
|
// CLOSED like every other path in that function. Double-fault both calls
|
|
// to pin this: `readFileSync` throws `ENOENT` (as it does for a genuinely
|
|
// missing path or file), `lstatSync` throws something else (`EACCES`) —
|
|
// this combination is impossible to produce with a real filesystem state
|
|
// (if the path is genuinely gone, `lstatSync` reports `ENOENT` too), so it
|
|
// is monkeypatched directly rather than constructed on disk; this is what
|
|
// "a future edit could re-widen that catch and fall open again silently"
|
|
// means without a test — the double-fault CANNOT be exercised any other
|
|
// way. Restored via `t.after()`.
|
|
test('a non-ENOENT lstat failure during broken-symlink disambiguation fails closed, not open (#2645)', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-lstat-double-fault' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
const before = inspectWorkstream(tmpDir, 'ws-2645-lstat-double-fault', { active: null }); // adopt
|
|
assert.equal(before.completed_phases, 0, 'guard: gated by the live gaps_found verdict');
|
|
fs.unlinkSync(path.join(wsDir, 'phases', '1-foo', '01-VERIFICATION.md'));
|
|
|
|
const originalReadFileSync = fs.readFileSync;
|
|
const originalLstatSync = fs.lstatSync;
|
|
fs.readFileSync = (targetPath, ...rest) => {
|
|
if (typeof targetPath === 'string' && targetPath === ledgerPath) {
|
|
throw Object.assign(new Error('injected: simulated missing ledger'), { code: 'ENOENT' });
|
|
}
|
|
return originalReadFileSync(targetPath, ...rest);
|
|
};
|
|
fs.lstatSync = (targetPath, ...rest) => {
|
|
if (typeof targetPath === 'string' && targetPath === ledgerPath) {
|
|
throw Object.assign(new Error('injected: simulated raced permission fault'), { code: 'EACCES' });
|
|
}
|
|
return originalLstatSync(targetPath, ...rest);
|
|
};
|
|
t.after(() => {
|
|
fs.readFileSync = originalReadFileSync;
|
|
fs.lstatSync = originalLstatSync;
|
|
});
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-lstat-double-fault', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress',
|
|
'a non-ENOENT lstat failure is not proof of absence — it must fail closed (corrupt), not fall open (absent)');
|
|
assert.equal(inv.completed_phases, 0, 'the percentage must not rise because of an ambiguous double-fault read');
|
|
});
|
|
|
|
// Row 16 — CONTRIBUTING.md fault-injection: missing/uncreatable parent
|
|
// directory for the write side. Monkeypatch `fs.mkdirSync` to throw only
|
|
// for the workstream directory (delegating everything else), simulating a
|
|
// parent directory `writeVerificationLedger` cannot ensure exists.
|
|
test('an uncreatable parent directory on write does not break inspectWorkstream (#2645)', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-no-parent-dir' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
const originalMkdirSync = fs.mkdirSync;
|
|
fs.mkdirSync = (targetPath, ...rest) => {
|
|
if (typeof targetPath === 'string' && targetPath === wsDir) {
|
|
throw new Error('injected: simulated missing/uncreatable parent directory');
|
|
}
|
|
return originalMkdirSync(targetPath, ...rest);
|
|
};
|
|
t.after(() => { fs.mkdirSync = originalMkdirSync; });
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-no-parent-dir', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress', 'the live report still governs even though persistence failed');
|
|
assert.ok(!fs.existsSync(ledgerPath), 'a write that could not ensure its directory must not leave a ledger file');
|
|
});
|
|
|
|
// Row 17 — CONTRIBUTING.md fault-injection: rename failure and temp-file
|
|
// cleanup, now applicable because the write is atomic (temp file + rename,
|
|
// #2645 review). Monkeypatch `fs.renameSync` to throw only for the ledger's
|
|
// rename — the temp file must be written, the rename must fail, and the
|
|
// orphaned temp file must be cleaned up rather than accumulating.
|
|
test('a rename failure during the atomic ledger write cleans up the temp file (#2645)', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-rename-fail' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), FLAT_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), flatRoadmap([
|
|
'| 1. Foo | 1/1 | In Progress | - |',
|
|
]));
|
|
writePhase(wsDir, '1-foo', { plans: 1, summaries: 1, verification: 'gaps_found' });
|
|
const ledgerPath = path.join(wsDir, '.verification-ledger.json');
|
|
|
|
const originalRenameSync = fs.renameSync;
|
|
fs.renameSync = (src, dest) => {
|
|
if (typeof dest === 'string' && dest === ledgerPath) {
|
|
throw Object.assign(new Error('injected: simulated rename failure'), { code: 'EPERM' });
|
|
}
|
|
return originalRenameSync(src, dest);
|
|
};
|
|
t.after(() => { fs.renameSync = originalRenameSync; });
|
|
|
|
let inv;
|
|
assert.doesNotThrow(() => { inv = inspectWorkstream(tmpDir, 'ws-2645-rename-fail', { active: null }); });
|
|
assert.ok(inv);
|
|
assert.equal(inv.phases[0].status, 'in_progress', 'the live report still governs even though persistence failed');
|
|
assert.ok(!fs.existsSync(ledgerPath), 'a failed rename must not leave a ledger file at the final path');
|
|
const leftoverTmp = fs.readdirSync(wsDir).filter(name => name.startsWith('.verification-ledger.json.') && name.endsWith('.tmp'));
|
|
assert.deepEqual(leftoverTmp, [], 'a failed rename must not leave an orphaned temp file behind');
|
|
});
|
|
|
|
// Row 18 — BLOCKER regression, and THIS IS THE ONLY ROW THAT PROVES IT
|
|
// END TO END. `pickRollupWinners` (`workstream-inventory-builder.cts`) is
|
|
// the SINGLE shared implementation both `buildWorkstreamInventory`'s
|
|
// `rollupDirByKey` and `inspectWorkstream`'s ledger-winner selection now
|
|
// call. An earlier version of the ledger selection was a SEPARATE
|
|
// hand-written copy that omitted the `includeItem` (milestone-scoping)
|
|
// filter — so in a scoped workstream, a stale OUT-of-milestone directory
|
|
// sharing a phase key with the live IN-milestone one, with a newer mtime
|
|
// (plausible after a checkout/rebase resets mtimes), could win the
|
|
// LEDGER's selection while losing the BUILDER's. `isLedgerWinner` would
|
|
// then be false for the live directory, so deleting ITS
|
|
// `*-VERIFICATION.md` would never consult the ledger — reopening #2645's
|
|
// hole for the phase that actually counts toward `completed_phases`,
|
|
// reachable with a plain `rm`, no ledger tampering.
|
|
//
|
|
// This test constructs that EXACT collision directly — one synthetic key
|
|
// shared by two entries, one included (in-milestone) and one excluded
|
|
// (out-of-milestone), the excluded one given the larger mtime — and
|
|
// proves `pickRollupWinners` applies the filter BEFORE comparing mtimes.
|
|
//
|
|
// Row 19 (below) does NOT reproduce this same-key collision through the
|
|
// real `phaseKeyFromDir` / `isDirInCurrentMilestone` pipeline — extensive
|
|
// probing (documented in `10-diagnosis.md`'s "Fourth note") found no
|
|
// directory-naming pair that shares a rollup key while diverging in
|
|
// milestone membership under the CURRENT roadmap-parser implementation;
|
|
// every membership-determining path collapses to the same phase-number
|
|
// extraction the rollup key already uses. Row 19 instead pins a narrower,
|
|
// real, DISTINCTLY-keyed guarantee (an out-of-milestone phase's verdict is
|
|
// never written into the ledger at all) — genuinely useful coverage, but
|
|
// NOT a substitute for this row: it does not exercise the collision path,
|
|
// and the pre-fix code would have passed it too.
|
|
test('pickRollupWinners: an excluded (out-of-milestone) item can never win over an included one, even with a newer mtime (#2645)', () => {
|
|
const liveInMilestone = { key: 'shared', mtimeMs: 100, inMilestone: true, label: 'live' };
|
|
const staleOutOfMilestone = { key: 'shared', mtimeMs: 999999, inMilestone: false, label: 'stale' }; // far newer mtime, but excluded
|
|
const scoped = true;
|
|
|
|
const winners = pickRollupWinners(
|
|
[liveInMilestone, staleOutOfMilestone], // pre-sorted input, as both real call sites provide
|
|
(item) => item.key,
|
|
(item) => item.mtimeMs,
|
|
(item) => !(scoped && item.inMilestone === false),
|
|
);
|
|
|
|
assert.equal(winners.get('shared'), liveInMilestone,
|
|
'the excluded stale directory must never win the key, regardless of its mtime advantage');
|
|
assert.equal(winners.get('shared').label, 'live');
|
|
|
|
// The mirror image, sorted the OTHER way — order-of-iteration must not
|
|
// matter once the filter is applied; only inclusion + mtime should.
|
|
const winnersReversed = pickRollupWinners(
|
|
[staleOutOfMilestone, liveInMilestone],
|
|
(item) => item.key,
|
|
(item) => item.mtimeMs,
|
|
(item) => !(scoped && item.inMilestone === false),
|
|
);
|
|
assert.equal(winnersReversed.get('shared'), liveInMilestone);
|
|
|
|
// Unscoped (scoped=false): the exclusion never engages, so the newer
|
|
// mtime wins normally — pinning that the filter is scoping-conditional,
|
|
// not an unconditional "in-milestone always wins" rule.
|
|
const unscoped = false;
|
|
const winnersUnscoped = pickRollupWinners(
|
|
[liveInMilestone, staleOutOfMilestone],
|
|
(item) => item.key,
|
|
(item) => item.mtimeMs,
|
|
(item) => !(unscoped && item.inMilestone === false),
|
|
);
|
|
assert.equal(winnersUnscoped.get('shared'), staleOutOfMilestone,
|
|
'when scoping is off, the plain newest-mtime rule applies with no exclusion');
|
|
});
|
|
|
|
// Row 19 — NOT the collision blocker (see Row 18's comment — this does
|
|
// not reproduce it and the pre-fix code would pass this too). What this
|
|
// DOES cover: in a genuinely SCOPED workstream (roadmap has a Milestone
|
|
// column, STATE.md carries `milestone:`), a DISTINCTLY-keyed
|
|
// out-of-milestone phase's real verdict must never be written into the
|
|
// ledger at all — proving the REAL `inspectWorkstream` read/write path
|
|
// threads `scoped`/`inMilestone` into the ledger write gate correctly, end
|
|
// to end, for the (much more common) non-colliding case. `1-old` (v1.0)
|
|
// and `2-new` (v2.0) are DIFFERENT phase keys, not a shared one.
|
|
test('milestone scoping: a distinctly-keyed out-of-milestone phase is never written into the ledger (#2645)', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-2645-scoped-ledger' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), 'milestone: v2.0\nstatus: executing\n');
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), [
|
|
'# Roadmap', '', '## Progress', '',
|
|
'| Phase | Milestone | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
'| 1. Old | v1.0 | 1/1 | Complete | - |',
|
|
'| 2. New | v2.0 | 1/1 | In Progress | - |',
|
|
'',
|
|
].join('\n'));
|
|
writePhase(wsDir, '1-old', { plans: 1, summaries: 1, verification: 'gaps_found' }); // prior milestone
|
|
writePhase(wsDir, '2-new', { plans: 1, summaries: 1, verification: 'gaps_found' }); // current milestone
|
|
|
|
const inv = inspectWorkstream(tmpDir, 'ws-2645-scoped-ledger', { active: null });
|
|
assert.ok(inv);
|
|
// Guard: confirm scoping is actually active and phase 1 really is
|
|
// excluded from the rollup — otherwise this test would not exercise
|
|
// anything.
|
|
assert.equal(inv.roadmap_phase_count, 1, 'guard: denominator = v2.0 phases only, scoping is active');
|
|
|
|
const ledgerRaw = fs.readFileSync(path.join(wsDir, '.verification-ledger.json'), 'utf-8');
|
|
const ledger = JSON.parse(ledgerRaw);
|
|
assert.ok(!('01' in ledger) && !('1' in ledger),
|
|
'the out-of-milestone phase (1-old) must never be written into the ledger, regardless of its key form');
|
|
assert.ok(('02' in ledger) || ('2' in ledger),
|
|
'the in-milestone phase (2-new) must be recorded normally');
|
|
});
|
|
});
|
|
|
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
// #3057 B3: inspectWorkstream surfaces an indeterminate staleness check
|
|
//
|
|
// readVerificationStatus's internal staleness check can fail (fs /
|
|
// scanPhasePlans / clock error). Pre-#3057 B3 wiring, that failure was
|
|
// dropped here — `liveVerificationStatus` used only `.status` — so nothing
|
|
// could ever distinguish "checked; nothing is stale" from "could not check".
|
|
// `WorkstreamInventory`'s own return shape has no per-phase verification
|
|
// detail to carry this on, so it is surfaced via the SAME injectable
|
|
// stderr-diagnostic seam #3057 B4 added to cmdGitBaseBranch (see
|
|
// tests/git-base-branch.test.cjs), never via a change to `phases[]`/
|
|
// `completed_phases` — the rollup routing must stay byte-identical.
|
|
// ─────────────────────────────────────────────────────────────────────────────
|
|
|
|
describe('#3057 B3: inspectWorkstream — verification staleness-check indeterminate is surfaced', () => {
|
|
let tmpDir;
|
|
before(() => { tmpDir = createFixture(); });
|
|
after(() => cleanup(tmpDir));
|
|
|
|
const V2_STATE = 'milestone: v2.0\nstatus: executing\n';
|
|
|
|
function roadmapWithRows(rows) {
|
|
return [
|
|
'# Roadmap', '', '## Progress', '',
|
|
'| Phase | Milestone | Plans Complete | Status | Completed |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
...rows,
|
|
'',
|
|
].join('\n');
|
|
}
|
|
|
|
/** Writes a verified phase directory with a deterministic (never-stale) mtime ordering. */
|
|
function writeVerifiedPhase(wsDir, slug) {
|
|
const dir = path.join(wsDir, 'phases', slug);
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
const summaryPath = path.join(dir, '01-SUMMARY.md');
|
|
const verificationPath = path.join(dir, '01-VERIFICATION.md');
|
|
fs.writeFileSync(path.join(dir, '01-PLAN.md'), '# plan\n');
|
|
fs.writeFileSync(summaryPath, '# summary\n');
|
|
fs.writeFileSync(verificationPath, '---\nstatus: passed\n---\n');
|
|
// Deterministic mtime ordering — never rely on write-order clock ties.
|
|
const older = new Date('2026-01-01T00:00:00.000Z');
|
|
const newer = new Date('2026-01-01T00:01:00.000Z');
|
|
fs.utimesSync(summaryPath, older, older);
|
|
fs.utimesSync(verificationPath, newer, newer);
|
|
return { summaryPath, verificationPath };
|
|
}
|
|
|
|
test('an fs failure inside the staleness check writes a stderr diagnostic; the rollup is UNCHANGED', (t) => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-3057-b3-fault' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
]));
|
|
const { summaryPath, verificationPath } = writeVerifiedPhase(wsDir, '1-alpha');
|
|
const origStatSync = fs.statSync;
|
|
|
|
t.mock.method(fs, 'statSync', function injectedStaleCheckFault(target, ...args) {
|
|
const targetPath = String(target);
|
|
if (targetPath === verificationPath || targetPath === summaryPath) {
|
|
throw new Error('injected stat failure (#3057 B3)');
|
|
}
|
|
return origStatSync.call(fs, target, ...args);
|
|
});
|
|
|
|
const calls = [];
|
|
const inv = inspectWorkstream(tmpDir, 'ws-3057-b3-fault', {
|
|
active: null,
|
|
writeDiagnostic: (message, meta) => { calls.push({ message, meta }); },
|
|
});
|
|
|
|
assert.ok(inv);
|
|
// Pre-existing no-throw fail-open routing is UNCHANGED: the rollup counts
|
|
// exactly what it would without the injected fault.
|
|
assert.equal(inv.completed_phases, 1, 'rollup routing unchanged');
|
|
assert.strictEqual(calls.length, 1, 'an indeterminate staleness check must write exactly one diagnostic');
|
|
assert.strictEqual(calls[0].meta.phaseDir, '1-alpha', 'diagnostic meta should name the affected phase directory');
|
|
assert.strictEqual(calls[0].meta.reason, 'staleCheckIndeterminate', 'diagnostic meta should carry a stable reason');
|
|
});
|
|
|
|
test('a completed staleness check that finds nothing stale writes NO diagnostic', () => {
|
|
const wsDir = seedWorkstream(tmpDir, { name: 'ws-3057-b3-ok' });
|
|
fs.writeFileSync(path.join(wsDir, 'STATE.md'), V2_STATE);
|
|
fs.writeFileSync(path.join(wsDir, 'ROADMAP.md'), roadmapWithRows([
|
|
'| 1. Alpha | v2.0 | 1/1 | Complete | - |',
|
|
]));
|
|
writeVerifiedPhase(wsDir, '1-alpha');
|
|
|
|
const calls = [];
|
|
const inv = inspectWorkstream(tmpDir, 'ws-3057-b3-ok', {
|
|
active: null,
|
|
writeDiagnostic: (message, meta) => { calls.push({ message, meta }); },
|
|
});
|
|
|
|
assert.ok(inv);
|
|
assert.equal(inv.completed_phases, 1);
|
|
assert.strictEqual(calls.length, 0, 'a completed, non-stale check must not write any diagnostic');
|
|
});
|
|
});
|