* feat(#1950): broken-windows ledger — cross-phase defect register gating ship
Adds a new capability (#1950) that operationalizes GSD's
no-defer discipline as a tracked, enforced artifact:
accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths
across phases, and /gsd-ship blocks while any entry is open.
Implementation:
- src/broken-windows.cts → gsd-core/bin/lib/broken-windows.cjs: typed IR +
I/O entry points (parseLedger/renderLedger/appendWindow/markWaived/markFixed
+ cmdWindowsStatus/Append/Waive/MarkFixed). Frozen REASON enum for typed
error assertions. Windows-safe atomic rename with retry on transient
EPERM/EBUSY/EACCES.
- gsd-tools.cjs: new subcommand (status | append | waive | fixed),
wired via routeWindows + HOST_COMMAND_ROUTERS.windows.
- capabilities/broken-windows/capability.json: one ship:pre gate with
artifact-frontmatter-equals predicate on WINDOWS.md open_count == 0.
activationKey windows.enabled (default true) + sibling windows.enforce
(default true, separate so tracking can precede enforcement).
- gsd-core/workflows/ship.md: capId==broken-windows branch in preflight,
sibling to security — reads gsd_run windows status --raw, fails closed
on open_count > 0 or unreadable ledger.
- agents/gsd-executor.md: extends the existing ## Known Stubs instruction
to also append to WINDOWS.md via gsd_run windows append (best-effort,
never blocks execution).
- agents/gsd-verifier.md: new Step 8b — record unmet truths + human-verify
items in WINDOWS.md.
- gsd-core/workflows/progress.md: surfaces open + waived counts.
- docs/COMMANDS.md + CONTEXT.md glossary entry + docs/INVENTORY.md:
document the gate, waiver mechanism, and new module.
- tests/broken-windows.test.cjs: pure + CLI behavioral coverage + fast-check
roundtrip property; fail-closed on malformed ledger; security boundary on
path traversal in --file.
Backward-compatible: a project with no .planning/WINDOWS.md reports
open_count: 0 and ships cleanly. Disable enforcement per-project with
gsd config-set windows.enforce false (tracking continues, gate stays open).
* chore(#1950): ratchet size baselines, defer verifier integration
- Workflow size baseline: ship.md 25575→27928, progress.md 31789→32632
(broken-windows preflight branch + open-windows surface).
- Agent size baseline: gsd-executor.md 46644→47951 (Known Stubs → also
appends to WINDOWS.md). gsd-verifier.md unchanged.
- LARGE_CAP (49152) preempted the planned verifier integration
(gsd-verifier.md was at 49140 pre-PR — 12 bytes of headroom, not the
documented 'real headroom'). Verifier integration deferred to a follow-up
PR that extracts the VERIFICATION.md template (lines 739-859) to
gsd-core/references/ — a pre-existing cap-tightness defect this PR
exposed but does not expand scope to fix. Verifier integration is not in
the issue's acceptance criteria (executor writes is; unmet-truths
recording was an enhancement, not a gate).
* fix(#1950): gate default-off, rename to workflow.windows_enforce, regen goldens
Test-failure-driven fixes after first gsd-test run on db8733c8f failed 44
cases (pre-existing structural tests encoded 'ship:pre has 1 gate' / 'all
caps off → empty hooks'):
- capability manifest: rename windows.enabled+windows.enforce (default
true) → single federated key workflow.windows_enforce (default FALSE,
opt-in). Matches security's workflow.security_enforce convention and
makes the adr857 all-caps-off test pass without modification (the test's
buildAllFalseConfig handles workflow.* out of the box). Default-OFF keeps
the gate out of the registry's default ship:pre resolution so existing
loop-hooks-ship-pre-e2e structural assertions (exactly 1 gate, capId
'security') stay valid; users opt in via
gsd config-set workflow.windows_enforce true.
- drop activationKey (security doesn't have one either; workflow.* key
doubles as the activation toggle).
- regenerate docs/reference/capability-matrix.md to include broken-windows
(capability-matrix-sync test).
- regenerate tests/fixtures/golden-install-parity/*.json (18 runtimes) —
installer now emits the new capability + lib file.
- update CONTEXT.md, docs/COMMANDS.md, docs/FEATURES.md, ship.md,
agents/gsd-executor.md to use the new key name and /gsd:colon slash
syntax (slash-command-namespace test).
- restore accidentally-regressed /gsd:capture in progress.md.
Tracking-only by default; enforcement is opt-in. Acceptance criterion
'/gsd-ship fails while any ledger entry is open' is met when
workflow.windows_enforce=true (test fixture enables it).
* test(#1950): update ship:pre structural invariants for 2-gate registry
- loop-hooks-ship-pre-e2e: the registry now declares 2 gates at ship:pre
(security + broken-windows), regardless of activation. Activation tests
above still pin security-only or empty behavior via fixtures; these
structural tests pin the REGISTRY shape, which has 2 gates as of #1950.
- workflow-size-baseline: ship.md 27928→27945 (workflow.windows_enforce
rename added 17 bytes).
* fix(#1950): review H1+H2+M1+M2+M3 — fence-injection, EACCES fail-closed, cleanup, strict line, stryker
Adversarial isolated review (Step 6.3) found 2 HIGH findings that block
the PR and 3 mediums. All addressed:
H1 (HIGH): description containing the markdown 3-backtick fence would
terminate the ledger's JSON code block early inside JSON.stringify output
(JSON doesn't escape backticks), corrupting the file and bricking the
next parse. Fix: use a 4-backtick fence (json ... ) which
JSON.stringify cannot produce on its own, AND validate that no entry
text field contains a 4-backtick run (reject at append time with new
WINDOWS_INVALID_TEXT reason code). Locked by a regression test.
H2 (HIGH): readLedgerOrNull swallowed ALL fs errors as 'no ledger',
silently returning open_count:0 on EACCES/EPERM/EIO. The ship gate
would then pass on an unreadable ledger — the precise vector the
workflow doc claims is impossible. Fix: only ENOENT returns null;
every other fs error propagates as WINDOWS_LEDGER_MALFORMED so the
gate blocks and the operator sees a real diagnostic. Locked by a
regression test that chmod 000s a ledger with open_count=1 and
asserts the result is never a false-green 0.
M1: writeLedgerAtomic left an orphaned .tmp file on rename failure.
Wrapped renameWithRetry in try/catch with best-effort unlink.
M2: validateLine silently coerced 'abc' → NaN → null, hiding type
drift. Removed the line === 0 special case (was undocumented) and
made the error message match the strict check. Now any non-positive-
integer line value throws, including strings.
M3: tests/broken-windows.test.cjs (with its fast-check property test)
was not in stryker.config.mjs DEFAULT_TEST_CMD — Stryker would mutate
src/broken-windows.cts but no test would catch the mutations,
producing false surviving-mutant scores. Added to the list.
L1 (dead throw e after error()), L7 (line boundary tests, H1/H2
regression tests, 4-backtick CLI test) also addressed.
* docs(#1950): inline concurrency + busy-wait notes (review L2+L3)
* fix(#1950): regen goldens against latest gsd-tools; correct --line 0 boundary test
gsd-test v4 caught two issues:
- goldens I regenerated earlier (commit 526682084) predated the L1
routeWindows catch-block cleanup (commit dd844d565). Regenerated
via 'npm run gen:golden' against current HEAD so the install
parity hash for gsd-tools.cjs matches.
- 'append --line boundary' test expected --line 0 to succeed with
null entry.line, but the M2 fix correctly rejects 0 (lines are
1-indexed; 0 is not a valid source line). Updated the boundary
test to assert --line 0 fails alongside -1 and 'abc'.
* chore(#1950): regen goldens after rebase onto next
* chore(#1950): quick.md baseline 50699→50993 (correct resolution from next rebase)
* chore(changeset): backfill pr:2441 in .changeset/broken-windows-ledger.md
* fix(#1950): renderTable escapes backslash before pipe (CodeQL incomplete-sanitization)
CodeQL flagged the markdown-table cell escaper:
String(s ?? '').replace(/\|/g, '\\|')
— it escapes pipe but not backslash first. A description containing '\|'
would render as '\\|' which markdown parses as 'literal backslash' +
'cell separator', splitting the column.
Fix: escape backslash FIRST (each \ → \\), then pipe (each | → \|).
Now a description with '\|' renders as '\\\\|' (literal '\\' + escaped
pipe), which markdown renders as a single '\|' inside the cell. The JSON
code block (the parse source-of-truth) was already correctly escaped via
JSON.stringify; only the display-only table was affected.
Locked by a regression test that:
1. Verifies the JSON block reparses with the description intact.
2. Walks the rendered table row counting unescaped pipes — must be
exactly 11 (the row separators for 10 cells), proving no in-cell
pipe added a split.
d16a66479a