* enhance(#4487): stamp windows-ledger entries with the resolved milestone Broken-windows ledger entries (`.planning/WINDOWS.md`) carry `phase` as a bare number. Phase numbers are unique only within one active phases/ directory -- `milestone complete` archives phases and frees their numbers for reuse, so two milestones routinely produce entries sharing the same phase value with nothing distinguishing them. Since `/gsd-ship` blocks while any entry is open, an already-archived milestone's open entries could silently block shipping the CURRENT milestone, with no supported way to attribute which entry belonged to which milestone short of manually cross-referencing MILESTONES.md timestamps against decision IDs that happened to appear in description prose. Added an optional `milestone: string | null` field to WindowEntry, stamped by `windows append` (cmdWindowsAppend, which already does file I/O) from the workstream's resolved milestone version. Reused the existing `readCurrentMilestoneVersion` (workstream-inventory.cts -- STATE.md `milestone:` frontmatter first, ROADMAP.md in-progress marker as fallback) rather than writing a parallel implementation: exported it via that module's existing `export = {...}` CJS-interop convention (matching the `import ... = require(...)` pattern already used in workstream.cts/init.cts). appendWindow itself stays pure -- it accepts milestone as an optional input field and passes it through; only the CLI-facing cmdWindowsAppend resolves it from disk. Backward compatible by construction: validateEntryShape does NOT add `milestone` to its required fields, so an existing ledger entry with no milestone key at all parses without error and reads back as null -- exactly "recorded before this change," no migration needed. The rendered markdown table is deliberately left unchanged (the issue's own words: "the JSON is the source of truth"); adding a table column would be a separate, larger change than adding an optional JSON field. Two smaller gaps the issue itself flags as separable ("happy to split them out") are explicitly NOT addressed here: no verb to amend an entry's description, and the table/JSON drift-repair advice that can destroy table-only edits on a parse failure. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#4487): preserve absent-vs-null milestone through parse/render roundtrip validateEntryShape stamped an explicit `milestone: null` onto every entry lacking the key, so a pre-#4487 ledger entry gained permanent JSON churn ("milestone": null) the first time ANY entry in the ledger was touched -- breaking the pure parse/render roundtrip-identity property test (render(parse(render(ledger))) must equal render(ledger)) and, in real usage, contaminating unrelated entries' diffs on every append/waive/fixed of an old ledger. Fixed by distinguishing "key genuinely absent" (undefined -- JSON. stringify drops it, matching pre-#4487 behavior exactly) from "recorded but unresolvable" (explicit null, the real signal appendWindow stamps on brand-new entries). WindowEntry.milestone is now optional (`milestone?: string | null`) so returning undefined type-checks. Updated tests/broken-windows.test.cjs's roundtrip property generator to exercise all three states (absent/null/string) -- its prior silence on this field is exactly what let the regression through. Also corrected the earlier backward-compatibility test's assertion: a pre-#4487 entry reads as milestone: undefined, not null, and re-rendering it must not introduce a milestone key at all. Also ran npm run regen:derived: docs/features/broken-windows-ledger.md (edited in an earlier commit) had never been propagated to its generated docs/FEATURES.md projection, which is what was independently failing tests/features-index-gate.test.cjs and, as a side effect of staleness, tripping tests/fragment-single-edit-propagation.install. test.cjs's second-source-surface check. Manually verified via the compiled lib (500 fast-check iterations plus direct legacy/new-entry roundtrip checks) before wiring the test file, since this repo blocks local node --test. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#4487): materialize milestone via conditional spread, not undefined assignment An object literal property set to `milestone: undefined` is still an OWN property -- `'milestone' in entry` reads true regardless of the assigned value, only JSON.stringify treats undefined specially. My prior commit's own new backward-compat test asserted `'milestone' in entry === false` for a pre-#4487 entry and failed on exactly this. Switched to conditionally spreading the key in only when the source object actually had it, so a genuinely absent milestone is not materialized at all -- matching both the `in` check and JSON serialization. Re-verified via the compiled lib (500 fast-check roundtrip iterations, plus the specific in/undefined/JSON assertions the failing test makes) before re-running gsd-test. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#4487): backfill changeset pr number to 4583 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
@@ -183,6 +183,25 @@ describe('broken-windows: appendWindow', () => {
|
||||
// 10 cells = 11 cell-separator pipes per row (leading + 9 internal + trailing).
|
||||
assert.equal(unescapedPipes, 11, 'table row must have exactly 11 unescaped pipes (10 cells) — backslash-pipe in description must NOT add a split');
|
||||
});
|
||||
|
||||
// #4487: phase numbers are unique only within one active phases/ directory —
|
||||
// milestone complete archives phases and frees their numbers for reuse, so
|
||||
// two milestones can produce entries sharing the same `phase` value with
|
||||
// nothing to distinguish them. appendWindow itself is pure (no I/O), so the
|
||||
// milestone value is a caller-supplied input, not resolved here — this pins
|
||||
// that it flows through untouched, and defaults to null when omitted
|
||||
// (an entry recorded before this field existed reads the same way).
|
||||
test('milestone input flows through to the entry (#4487)', () => {
|
||||
const led = emptyLedger('now');
|
||||
const { entry } = appendWindow(led, makeEntry({ milestone: 'v2.0' }), { now: 't' });
|
||||
assert.equal(entry.milestone, 'v2.0');
|
||||
});
|
||||
|
||||
test('milestone defaults to null when the caller omits it (#4487)', () => {
|
||||
const led = emptyLedger('now');
|
||||
const { entry } = appendWindow(led, makeEntry(), { now: 't' });
|
||||
assert.equal(entry.milestone, null);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -203,6 +222,13 @@ describe('broken-windows: markWaived', () => {
|
||||
assert.equal(openCount(led), 0); // waived does not block
|
||||
});
|
||||
|
||||
test('waive preserves the entry\'s milestone (#4487 — object-spread transition must not drop it)', () => {
|
||||
let led = emptyLedger('now');
|
||||
({ ledger: led } = appendWindow(led, makeEntry({ milestone: 'v2.0' }), { now: 't1' }));
|
||||
led = markWaived(led, 1, 'reason', { now: 't2' });
|
||||
assert.equal(led.entries[0].milestone, 'v2.0');
|
||||
});
|
||||
|
||||
test('waive with empty reason throws (boundary: limit-1 = 0 chars)', () => {
|
||||
let led = emptyLedger('now');
|
||||
({ ledger: led } = appendWindow(led, makeEntry(), { now: 't1' }));
|
||||
@@ -264,6 +290,13 @@ describe('broken-windows: markFixed', () => {
|
||||
assert.equal(openCount(led), 0);
|
||||
});
|
||||
|
||||
test('fixed preserves the entry\'s milestone (#4487 — object-spread transition must not drop it)', () => {
|
||||
let led = emptyLedger('now');
|
||||
({ ledger: led } = appendWindow(led, makeEntry({ milestone: 'v2.0' }), { now: 't1' }));
|
||||
led = markFixed(led, 1, { now: 't2' });
|
||||
assert.equal(led.entries[0].milestone, 'v2.0');
|
||||
});
|
||||
|
||||
test('fixed on unknown id throws', () => {
|
||||
const led = emptyLedger('now');
|
||||
assert.throws(
|
||||
@@ -299,6 +332,12 @@ describe('broken-windows: parse/render roundtrip property', () => {
|
||||
phase: arbPhase,
|
||||
description: arbText,
|
||||
status: arbStatus,
|
||||
// #4487: three-way split so the roundtrip property actually exercises
|
||||
// all of "key absent" (pre-#4487 entry), "explicit null" (recorded but
|
||||
// unresolvable), and "a real string" -- these three states must each
|
||||
// survive parse/render identically, which is exactly the distinction
|
||||
// validateEntryShape/renderLedger have to get right.
|
||||
milestoneCase: fc.constantFrom('absent', 'null', 'string'),
|
||||
}).map((e) => ({
|
||||
id: e.id,
|
||||
kind: e.kind,
|
||||
@@ -310,6 +349,7 @@ describe('broken-windows: parse/render roundtrip property', () => {
|
||||
reason: e.status === 'waived' ? 'justified' : '',
|
||||
recorded_at: '2026-07-19T00:00:00Z',
|
||||
resolved_at: e.status === 'open' ? null : '2026-07-19T01:00:00Z',
|
||||
...(e.milestoneCase === 'absent' ? {} : { milestone: e.milestoneCase === 'null' ? null : 'v2.0' }),
|
||||
}));
|
||||
|
||||
const arbLedger = fc.array(arbEntry, { maxLength: 6 }).map((entries) => {
|
||||
@@ -397,6 +437,58 @@ describe('broken-windows: parseLedger fail-closed', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// #4487: milestone field backward compatibility
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('broken-windows: parseLedger backward compatibility for the #4487 milestone field', () => {
|
||||
const rawWithNoMilestoneKey = [
|
||||
'---',
|
||||
'schema_version: 1',
|
||||
'open_count: 1',
|
||||
'waived_count: 0',
|
||||
'fixed_count: 0',
|
||||
'total_count: 1',
|
||||
'last_updated: 2026-01-01T00:00:00.000Z',
|
||||
'---',
|
||||
'',
|
||||
'```json',
|
||||
JSON.stringify([
|
||||
{
|
||||
id: 1,
|
||||
kind: 'stub',
|
||||
phase: '3',
|
||||
file: '',
|
||||
line: null,
|
||||
description: 'old entry',
|
||||
status: 'open',
|
||||
reason: '',
|
||||
recorded_at: '2026-01-01T00:00:00.000Z',
|
||||
resolved_at: null,
|
||||
// deliberately no `milestone` key
|
||||
},
|
||||
], null, 2),
|
||||
'```',
|
||||
'',
|
||||
].join('\n');
|
||||
|
||||
test('an entry with NO milestone key at all (pre-#4487 shape) parses without error, reading as undefined', () => {
|
||||
const ledger = parseLedger(rawWithNoMilestoneKey);
|
||||
// Not `null`: an explicit null is the "recorded, but unresolvable"
|
||||
// signal appendWindow stamps on NEW entries. A pre-#4487 entry never
|
||||
// recorded anything -- it must read as genuinely absent (`undefined`),
|
||||
// the only representation JSON.stringify will also omit on re-render.
|
||||
assert.equal(ledger.entries[0].milestone, undefined, 'an entry recorded before this field existed must read as milestone: undefined (absent), not null');
|
||||
assert.equal('milestone' in ledger.entries[0], false, 'the key itself must not be materialized for a pre-#4487 entry');
|
||||
});
|
||||
|
||||
test('re-rendering a parsed pre-#4487 entry does not stamp a milestone key into the JSON (no drive-by churn)', () => {
|
||||
const ledger = parseLedger(rawWithNoMilestoneKey);
|
||||
const rendered = renderLedger(ledger);
|
||||
assert.doesNotMatch(rendered, /"milestone"/, 'parsing then re-rendering a legacy entry must not introduce milestone: null noise the entry never had');
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CLI: gsd-tools windows status (acceptance: clean-ship on empty)
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -724,6 +816,57 @@ describe('broken-windows CLI: windows append', () => {
|
||||
assert.equal(obj2.ledger.entries[0].id, 1);
|
||||
});
|
||||
|
||||
// #4487: cmdWindowsAppend (unlike the pure appendWindow) resolves the
|
||||
// milestone itself from disk, reusing workstream-inventory.cts's existing
|
||||
// readCurrentMilestoneVersion (STATE.md `milestone:` frontmatter first,
|
||||
// ROADMAP.md in-progress marker as fallback) rather than a new parallel
|
||||
// implementation.
|
||||
test('append stamps the milestone resolved from STATE.md frontmatter (#4487)', (t) => {
|
||||
const tmp = createTempDir('bw-append-milestone-state-');
|
||||
t.after(() => cleanup(tmp));
|
||||
fs.mkdirSync(path.join(tmp, '.planning'), { recursive: true });
|
||||
fs.writeFileSync(
|
||||
path.join(tmp, '.planning', 'STATE.md'),
|
||||
'---\nmilestone: v2.0\n---\n# Project State\n',
|
||||
'utf-8',
|
||||
);
|
||||
const res = runGsdTools(
|
||||
['windows', 'append', '--kind', 'stub', '--phase', '5', '--description', 'x'],
|
||||
tmp,
|
||||
);
|
||||
assert.equal(res.success, true, `stderr: ${res.error || ''}`);
|
||||
assert.equal(JSON.parse(res.output).entry.milestone, 'v2.0');
|
||||
});
|
||||
|
||||
test('append stamps null when no milestone is resolvable (#4487)', (t) => {
|
||||
const tmp = createTempDir('bw-append-milestone-none-');
|
||||
t.after(() => cleanup(tmp));
|
||||
const res = runGsdTools(
|
||||
['windows', 'append', '--kind', 'stub', '--phase', '5', '--description', 'x'],
|
||||
tmp,
|
||||
);
|
||||
assert.equal(res.success, true, `stderr: ${res.error || ''}`);
|
||||
assert.equal(JSON.parse(res.output).entry.milestone, null);
|
||||
});
|
||||
|
||||
test('append falls back to the ROADMAP in-progress marker when STATE.md has no milestone field (#4487)', (t) => {
|
||||
const tmp = createTempDir('bw-append-milestone-roadmap-fallback-');
|
||||
t.after(() => cleanup(tmp));
|
||||
fs.mkdirSync(path.join(tmp, '.planning'), { recursive: true });
|
||||
fs.writeFileSync(path.join(tmp, '.planning', 'STATE.md'), '---\nstatus: executing\n---\n# Project State\n', 'utf-8');
|
||||
fs.writeFileSync(
|
||||
path.join(tmp, '.planning', 'ROADMAP.md'),
|
||||
'# Roadmap\n\n## 🚧 **v3.1** — In Progress\n',
|
||||
'utf-8',
|
||||
);
|
||||
const res = runGsdTools(
|
||||
['windows', 'append', '--kind', 'stub', '--phase', '5', '--description', 'x'],
|
||||
tmp,
|
||||
);
|
||||
assert.equal(res.success, true, `stderr: ${res.error || ''}`);
|
||||
assert.equal(JSON.parse(res.output).entry.milestone, 'v3.1');
|
||||
});
|
||||
|
||||
test('append a second entry gets id=2', (t) => {
|
||||
const tmp = createTempDir('bw-append-second-');
|
||||
t.after(() => cleanup(tmp));
|
||||
|
||||
Reference in New Issue
Block a user