acquireStateLock was allocating a fresh SharedArrayBuffer on every retry
iteration via Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), ...).
The buffer is never mutated and never escapes, so hoisting it before the loop
is a provably-equivalent transformation — Atomics.wait always sees value 0
whether the buffer is fresh or reused.
Fixes#316
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
loadConfig called detectSubRepos(cwd) at up to 3 sites per invocation (root-config
requiresFilesystem migration, workstream-config requiresFilesystem migration, and the
planning.sub_repos filesystem re-sync) — all with the same cwd, yielding identical
results. Introduce a per-call lazy memo (getDetectedSubRepos) so the directory scan
runs at most once per loadConfig call while preserving all conditional logic. Fixes#315.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hot path in cmdRoadmapAnnotateDependencies called planData.find() on every
checklist line. Replaced with a first-wins Map built once before the loop so
each line resolves in O(1); first-wins preserves exact .find() semantics and
null-on-miss → wave-1 default is unchanged.
Fixes#314
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
intelExtractExports deduped export names with `if (!arr.includes(x)) arr.push(x)`
across ~8 extraction loops (one doubly-nested over an export block) — O(n^2).
Accumulate into Sets (add/has/size) and materialize to an array once at return.
Set dedups by value and preserves insertion order, so the returned export list
and its first-seen order are identical. Adds behavior-lock tests for dedup + order.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
parseNamedArgs re-scanned argv with indexOf/includes once per flag —
O(flags * argv) — on the command-dispatch hot path (24 call sites across
gsd-tools + init/state/validate routers). Build a first-index Map of argv
tokens in a single pass and use it for the flag lookups, dropping it to
O(argv + flags). Semantics are identical: firstIndex.get(t)??-1 === indexOf(t),
firstIndex.has(t) === includes(t); first-occurrence-wins and the value-token
rejection are preserved. Adds the first behavior-lock tests for the module.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cmdCommitToSubrepo routed each changed file to a sub-repo via
subRepos.find(...) inside the file loop — O(files * repos). Extract a pure
groupFilesBySubrepo() that buckets sub-repos by first path segment and scans
only the matching bucket, dropping it to expected O(files + repos). First-
match-in-array-order semantics (incl. multi-segment sub-repos) are preserved
exactly. Adds the first behavior-lock test for the routing path.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
learningsCopyFromProject called learningsWrite K times in one process,
and each call re-scanned the entire learnings store to dedupe — O(K*N).
Build the content_hash -> id index once at the start of the bulk import
and thread it through; single-write behavior and the return contract are
unchanged (no caller reads `id` on the created:false branch). O(K*N) ->
O(N+K). Adds a regression test asserting store scan count is independent
of import size.
The larger persistent on-disk index (atomic updates, corruption rebuild,
cross-process dedupe) is deferred — needs design decisions and is not
required to resolve the bulk-import scan this issue reports.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Pass-2 topological level assignment in cmdPhasePlanIndex dequeued its
Kahn's-algorithm queue with Array.shift(), which is O(n) per call in V8, so the
BFS was O(V^2) and slowed superlinearly on deep queues (wide fan-in plan
graphs). Extract the traversal into a pure, exported computeDependencyLevels
(rawPlans, planMap, canonicalToId) and dequeue via a head index (queue[head++])
-> O(V+E). Behavior is identical: same FIFO order, same longest-path levels,
same visited-count cycle detection. A complexity-contract comment above the loop
documents why shift() must not be reintroduced.
Adds tests/phase-dependency-levels.test.cjs with deterministic behavior and
edge-case coverage (linear chain, diamond longest-path, independent set, cycle,
canonical-prefix resolution, empty, self-loop, duplicate edge, external dep). A
timing-based complexity guard was intentionally omitted: the O(V+E) Map-build
constant dilutes the O(V^2) signal until impractical N (~1e6), so an empirical
guard is inherently flaky on contended CI — the contract is enforced by the
inline comment and correctness tests instead.
Fixes#307
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#145): extractCurrentMilestone selects active sub-milestone over closed sibling
extractCurrentMilestone used a non-global regex with content.match()
(first-match) to locate the milestone section for the STATE.md version.
When the milestone is a shared semver prefix (e.g. v8.0) and ROADMAP.md
holds both a closed sub-milestone (## v8.0 ... CLOSED/FAIL) and an active
one (## v8.0-B ... STARTED), the first match was always the closed
heading, so the active section and its phases were excised from the slice
and downstream phase ops failed with "Phase N not found in current
milestone".
Switch to a global matchAll over candidate headings, skip headings
carrying a closed marker (CLOSED/ARCHIVED/ABANDONED/SHIPPED/FAILED/FAIL/
✅/🗄️), and select the first non-closed match (falling back to the first
match when every candidate is closed, preserving legacy behavior). Anchor
the preamble slice to the first heading index so a closed sibling's body
no longer leaks into the preamble when the selected section is later.
Harden version matching with a trailing word boundary (so v8.0-B does not
match v8.0-Beta), narrow the FAIL marker to FAILED, match a bare 🗄, and
add an active-marker override (STARTED/🚧/ACTIVE) so a heading carrying an
explicit active status is never treated as closed even if its name contains
a completion word. Also anchor the preamble at the first any-version
milestone heading so unmatched sibling sections do not leak into the
preamble.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* ci(#145): add changeset fragment for milestone-selection fix
Adds the required .changeset/*.md fragment for this user-facing fix
(changeset-lint gate).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(#373): replace unquoted $GSD_SDK with space-safe gsd_run launcher
Workflow bash blocks resolved the runtime as GSD_SDK="node $GSD_TOOLS" and
invoked it unquoted ($GSD_SDK query ...). On install paths containing spaces
(e.g. /Volumes/Mini Me/...) the unquoted expansion word-split into
`node /Volumes/Mini gsd-tools.cjs ...`, failing with "Cannot find module
'/Volumes/Mini'" and getting masked by `2>/dev/null || echo "{}"` into a
silent empty state.
Replace the string variable with a single-line shell launcher that defines a
gsd_run function, invokes the runtime with a fully-quoted path and "$@", and
preserves the local-cjs / installed-gsd-tools-on-PATH fallback (#3668) plus
the loud not-found error and install hint. The launcher uses _GSD_SHIM_NAME
indirection so no workflow emits the /gsd-tools substring that the do.md
dispatcher-parity scanner would misread, and is single-line to stay within
the per-file progressive-disclosure line budgets (#2551).
The canonical launcher lives in
get-shit-done/workflows/_runtime-launcher.snippet.sh, is propagated once per
file by scripts/sync-runtime-launcher.cjs, and is locked by
tests/runtime-launcher-parity.test.cjs (fails CI on drift, on a reappearing
$GSD_SDK token, or on a /gsd-tools substring). Dependent workflow-assertion
tests are updated from $GSD_SDK to gsd_run, and the runtime launcher is
registered in CONTEXT.md.
Fixes#373
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* ci(#373): add changeset fragment and allow-test-rule for parity guard
The runtime-launcher parity test is a structural drift guard that reads
workflow markdown to assert the canonical launcher is present and the
retired $GSD_SDK / /gsd-tools tokens are absent; annotate it with
allow-test-rule per the no-source-grep lint escape hatch. Add the required
.changeset fragment for this user-facing fix.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(#373): make parity PATH-fallback assertion cross-platform (Windows)
Subtest (E) compared GSD_TOOLS against the Node-side absolute temp path,
but the value originates from git-bash which reports the POSIX form, so the
prefix comparison failed on windows-latest while the launcher itself worked
(the installed stub was invoked). Assert the resolved binary by normalized
suffix (/bin/gsd-tools, not .cjs) instead of the absolute prefix; the
behavioral stub-invocation assertion is unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: use active-workstream resolver exported by store module
* fix: wire verify codebase-drift alias and sync inventory docs
* chore: add changeset for next gate regression fixes
* fix: normalize changeset fragment metadata for docs-lint
* test(#178): update DispatchEvent factory tests to propagate parentTraceId
P1.3 test 'parentTraceId is always undefined' replaced with four P1.4
contracts: absent → undefined, string → propagated, null → undefined,
non-string → undefined (defensive normalization policy).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(#178): propagate parentTraceId through DispatchEvent factory
Stop ignoring the parentTraceId parameter added as a forward-compat hook
in P1.3. Defensive normalization: only non-null strings are propagated;
null, non-string values, and absent callers all yield undefined, keeping
P1.3 behavior intact for all existing dispatch call sites.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#178): add Hub-level parentTraceId propagation tests
Four new assertions: req.parentTraceId propagates to event, absent →
undefined (P1.3 regression), shared parentTraceId across multiple
dispatches, and unique traceId invariant despite shared parentTraceId.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(#178): plumb parentTraceId through Hub dispatch and _notifyLogger
dispatch() now reads req.parentTraceId and passes it to _notifyLogger,
which forwards it to makeDispatchEvent. Backward-compatible: callers
that omit parentTraceId emit events with parentTraceId: undefined,
identical to P1.3 behavior.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#178): add trace correlation end-to-end test
Dispatches a root command then 3 children with parentTraceId=rootTraceId.
Reads the real .gsd-trace.jsonl audit file and verifies: 4 events total,
root has no parentTraceId, all children carry rootTraceId, all traceIds
unique, JS filter returns exactly the 3 children given the root's traceId.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(#178): document traceId/parentTraceId in audit file
Update Observability section to note that audit events now carry both
traceId and parentTraceId, and explain the correlation filter pattern.
Note that leaf dispatches emit parentTraceId: undefined until the Phase 2
composer wires it automatically.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore(#178): add changeset for trace correlation seam
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#178): cover invalid parentTraceId values in DispatchEvent factory
Adds 9 new test cases for UUID v4 validation of parentTraceId:
empty string, whitespace, non-UUID, oversized, UUID v1, missing-hyphen,
extra-char (all dropped to undefined), plus UPPERCASE and lowercase v4
(both propagated). Tests are intentionally red until the implementation
commit that follows.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(#178): validate parentTraceId against UUID v4 before propagation
Adds UUID_V4_REGEX constant and isValidParentTraceId() helper to
event.cjs. makeDispatchEvent now silently coerces any parentTraceId that
fails the UUID v4 check (wrong version nibble, wrong variant, missing
hyphens, oversized, empty, etc.) to undefined. No stderr warn is emitted
— the factory remains pure and side-effect-free. Closes the correlation-
poisoning vector identified in the Codex adversarial review of PR #225.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#178): assert Hub silently drops invalid parentTraceId at the seam
Adds two tests to hub-logger-integration.test.cjs:
1. dispatch with 'junk' parentTraceId emits event with parentTraceId===undefined.
2. The logger-failure warn path is NOT triggered — the factory coerces the bad
value before onEvent is called, confirmed by zero stderr output even when a
logger that would throw on non-undefined parentTraceId is installed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#178): assert invalid parentTraceId does not poison correlation siblings
Adds one test to trace-correlation.test.cjs: dispatches a root, a valid
child (parentTraceId = rootTraceId), and an invalid child (parentTraceId =
'junk'). Asserts: valid child carries correct parentTraceId, invalid child
has parentTraceId dropped to undefined, filtering by rootTraceId yields
exactly 1 event (the valid child only), and all 3 events have unique
traceIds. Uses an isolated Hub + tmpdir to avoid shared fixture interference.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(#178): document UUID v4 contract for parentTraceId
Appends one sentence to the Observability audit-trail paragraph in
CONFIGURATION.md: parentTraceId must be canonical UUID v4 (RFC 4122);
values that don't match are silently dropped from audit output. No section
restructuring — single sentence addition only.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(#177): add DispatchEvent factory failing tests
Red tests for makeDispatchEvent shape, traceId UUID v4, uniqueness,
parentTraceId-always-undefined (P1.3), args redaction toggle, ISO 8601
timestamp, and all result variant passthrough.
* feat(#177): introduce DispatchEvent factory
makeDispatchEvent produces an immutable event record per dispatch:
- traceId: crypto.randomUUID() (UUID v4)
- parentTraceId: always undefined (P1.4 wires composer)
- command, result, timestamp (ISO 8601)
- args only included when includeArgs === true (default: omitted)
* test(#177): add arg redaction policy failing tests
Red tests for shouldIncludeArgs (GSD_AUDIT_ARGS env gating) and
redactEvent (strips args from frozen events, preserves all other
fields, returns a new object, never mutates the source).
* feat(#177): introduce arg redaction policy
shouldIncludeArgs(): only GSD_AUDIT_ARGS==='1' opts in; all other
values (unset, '', '0', 'true') default to omitting args.
redactEvent(event): returns a shallow copy of the event, dropping the
args field unless opted in. Never mutates the (frozen) source event.
* test(#177): add DispatchLogger interface failing tests
Red tests covering:
- no-op logger: silent on all events, never throws
- default logger: silent on ok, one flattened JSON line to stderr on error
- default logger: audit file creation + append-only + redaction + config gate
- GSD_AUDIT env var and config.audit.enabled config gate
- GSD_AUDIT_ARGS opt-in for args inclusion
All tests use real fs under os.tmpdir() — no mocked appendFileSync.
* feat(#177): introduce DispatchLogger with default and no-op implementations
createNoOpLogger(): silent on all events — Hub default when no logger injected.
createDefaultLogger({ cwd, config }):
- Silent on ok result
- Flattened JSON line to stderr on error: { kind, traceId, ...typedPayload }
- Append-only audit at .planning/.gsd-trace.jsonl when GSD_AUDIT=1 or config.audit.enabled
- Args redacted by default; GSD_AUDIT_ARGS=1 opts in
- Logger errors caught internally; never break dispatch callers
* test(#177): add Hub+logger integration failing tests
Red tests verifying:
- onEvent called exactly once per dispatch (ok, error, handler-throw, unknown)
- DispatchEvent shape: traceId uniqueness, command, result.kind, parentTraceId
- Logger errors contained (dispatch still returns Result, warn line to stderr)
- Hub defaults to no-op when no logger injected
- End-to-end with createDefaultLogger: silent on success, stderr on error, audit file
* feat(#177): wire DispatchLogger into CommandRoutingHub
Add optional logger param to createHub({ ..., logger }).
Defaults to createNoOpLogger() — silent, no behaviour change for callers
that don't inject a logger.
After every dispatch (success and error):
- Normalises HubResult { ok } to DispatchEvent { kind: 'ok'|error-kind }
- Calls makeDispatchEvent({ command, args, result }) to mint the event
- Calls logger.onEvent(event) exactly once
- Wraps in try/catch: logger errors emit { level:'warn', source:'DispatchLogger' }
to stderr but never propagate to dispatch callers
* chore(#177): gitignore .planning/.gsd-trace.jsonl audit file
The audit trail is local-only, append-only, and must never be committed.
Slotted under the existing "Local scratch + Claude-test artifacts" block.
* docs(#177): document GSD_AUDIT, GSD_AUDIT_ARGS, config.audit.enabled
New ## Observability section at end of CONFIGURATION.md covering:
- Default silent/stderr behaviour overview
- Stderr error JSON format
- Audit file opt-in (env var and config key)
- Args redaction policy and GSD_AUDIT_ARGS opt-in
Also slots GSD_AUDIT and GSD_AUDIT_ARGS into the existing
## Environment Variables table (alphabetical order).
* chore(#177): add changeset for observability seam
type: Added — new DispatchLogger seam with default silent/stderr/audit behaviour.
* fix(#167): support query meta-command in gsd-tools
* chore(#167): add changeset for query meta-command fix
* fix(#167): pin claude runtime in local-agent regression tests
* test(#3751): stabilize local-agent CI assertions
* refactor(hub): tighten Result<T> to typed-payload-per-kind discriminated union (#176)
Each Hub error variant now carries only its own typed payload. The generic
`errorKind` field is renamed to `kind`; `message`/`details` escape hatches
are removed from Hub-emitted errors. Factory functions (makeUnknownCommand,
makeInvalidArgs, makeHandlerRefusal, makeHandlerFailure) are exported and
used in phase-command-router.cjs. Callers switch on `result.kind`.
Part of ADR-0174 P1.2.
<!-- docs-exempt: no docs/ changes; API is internal to Hub callers -->
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(hub): act on P1.2 review findings (#176)
Addresses 4 review findings on PR #221:
- Hub now runtime-validates ok:false variants against the typed shape
and coerces malformed returns to HandlerFailure with a contract-
violation message (codex finding #1, code-review finding #1)
- catch path now preserves the original throwable for non-Error
throws via an Error wrapper with .thrown attached (codex finding #2)
- All 4 factory returns are Object.freeze'd (review finding #9)
- makeHandlerFailure validates cause is Error; non-Error causes are
wrapped with .thrown attached (review finding #10)
Tests added for each finding (TDD red → green).
Refs #176. Part of #174.
* fix(docs-lint): add docs-exempt markers to both P1.2 changeset fragments
Both `176-typed-result-discriminated-union.md` and `176-hub-p1.2-review-findings.md`
carry `type: Changed` which triggers the docs-required lint. Neither fragment had
a `<!-- docs-exempt: <reason> -->` marker, causing `docs-lint` to fail with
`FAIL_DOCS_MISSING`. Added the per-fragment exemption marker to both (the repo has
no `no-docs` label). This is a purely internal SDK refactor (ADR-0174 P1.2) with
no public docs surface.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(#170): update workflow fallback install hint package
* chore(#170): add changeset for workflow fallback hint migration
* fix(#170): mark workflow-hint test as structural text contract
* feat(hub): drop mode/sdkLoader/SdkDispatchFailed (#175)
The Command Routing Hub no longer carries dual-runtime selection.
Removes `mode` and `sdkLoader` constructor parameters and the
`SdkDispatchFailed` and `SdkLoadFailed` errorKind values. The Hub
now routes exclusively through the CJS registry / handler resolution
path. ERROR_KINDS enum shrinks from 6 to 4 values.
phase-command-router.cjs updated to construct the Hub without the
removed params (removes tryLoadSdk, getExecuteForCjs, sdkLoader fn,
mode variable, and the post-dispatch SDK output branch). The 7
remaining family routers (init, phases, roadmap, state, validate,
verify, cjs-command-router-adapter) do not use createHub directly
and require no changes.
The CJS↔SDK bridge (bin/lib/cjs-sdk-bridge.cjs) is unchanged and
remains separately invokable; its removal is tracked in Phase 4 (#190).
ADR-0012 is no longer amended in this PR — the decision is captured
in ADR-0174 (which supersedes ADR-0012 entirely as part of the
SDK-retirement migration). Amending a superseded ADR would be
redundant noise.
Tests:
- Added assertions that Hub rejects/ignores `mode` and `sdkLoader`
- Removed obsolete mode-selection branching tests
- 57/57 local tests pass
Closes#175.
Part of #174 (ADR-0174).
* chore(changeset): add docs-exempt marker (#175)
P1.1's CommandRoutingHub work has no docs/ touchpoints — the
architectural decision is captured in ADR-0174 (merged via PR #198).
Per-phase ADR amendments would create noise; the SDK-retirement
migration's docs land in Phase 6 PRs (#193-#196) once the relevant
state is removed.
Adds the standard <!-- docs-exempt: <reason> --> marker inside the
changeset fragment so lint:docs accepts the PR without forcing a
docs/ touch that would be redundant.
Refs #175. Part of #174 (ADR-0174).
* test(4): reproduce non-idempotent phase complete + unclamped percent in CJS CLI
RED regression tests for issue #4:
- T1: double invocation of cmdPhaseComplete double-increments **Completed Phases:**
in STATE.md body (blind parseInt+1 instead of deriving from ROADMAP)
- T2: progress percent can exceed 100% when Completed Phases > Total Phases
The CJS path (bin/lib/phase.cjs:cmdPhaseComplete) has the bug; the SDK path
(phase-lifecycle.ts:phaseComplete, fixed in ~PR#3520) already derives
completed_phases from ROADMAP Complete-row count, making it idempotent.
References:
- Issue #4 (open-gsd/get-shit-done-redux)
- ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
- /tmp/adr-3524-review-findings.md (architectural justification)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): add sdk/scripts/gen-phase-lifecycle-policy.mjs generator + freshness check placeholder
Generates phase-lifecycle-policy.generated.cjs from sdk/src/query/phase-lifecycle-policy.ts.
All functions in phase-lifecycle-policy.ts are pure transforms (no I/O), directly
serializable via Function.prototype.toString(). The GSDError dependency is replaced
with a lightweight stub that throws plain Error objects — CJS callers that need
process.exit(1) behavior catch these and delegate to error().
This is the "I/O adapter pattern" from ADR-3524 Section 4 applied to pure helpers.
References:
- ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
- /tmp/adr-3524-review-findings.md (architectural justification)
- Issue #4 (open-gsd/get-shit-done-redux)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): add sdk/scripts/gen-phase.mjs generator
Generates phase.generated.cjs from sdk/src/query/phase.ts.
Only pure helpers (isCanonicalPlanFile, describeNonCanonicalPlans) are generated;
async query handlers (findPhase, phasePlanIndex) are I/O-bound and remain per-side
per ADR-3524 Section 4.
References:
- ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
- /tmp/adr-3524-review-findings.md (architectural justification)
- Issue #4 (open-gsd/get-shit-done-redux)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): add sdk/scripts/gen-phase-lifecycle.mjs + core idempotency fix logic
Generates phase-lifecycle.generated.cjs providing two pure functions that are the
root-cause fix for issue #4:
1. deriveProgressFromRoadmap(roadmapContent): counts Complete rows in ROADMAP
progress table — makes completed_phases idempotent (derived from ground truth
instead of blind +1). Direct transcription of the SDK's "Root cause 1 fix"
block in phase-lifecycle.ts (~line 1644).
2. clampPercent(completed, total): percent capped at 100 — prevents >100% progress
when Completed Phases exceeds Total Phases.
Design note: the full phase lifecycle mutations (add, insert, remove, complete) are
inherently async and I/O-bound. Per ADR-3524 Section 4 ("I/O stays per-side"), those
are NOT generated. Only the pure-computation kernel is extracted, following the
I/O adapter pattern: pure logic shared; each side (CJS sync, SDK async) supplies
its own I/O adapter.
The pure functions are defined in the generator as real JS functions and serialized
via Function.prototype.toString() — same technique as gen-project-root.mjs — rather
than embedded in template literals (which would require double-escaping all regex
backslashes).
References:
- ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
- /tmp/adr-3524-review-findings.md (architectural justification)
- Issue #4 (open-gsd/get-shit-done-redux)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): emit phase.generated.cjs, phase-lifecycle.generated.cjs, phase-lifecycle-policy.generated.cjs
Three generated CJS artifacts from their respective generator scripts:
- phase.generated.cjs (1.7K): isCanonicalPlanFile + describeNonCanonicalPlans
from sdk/src/query/phase.ts
- phase-lifecycle.generated.cjs (3.6K): deriveProgressFromRoadmap + clampPercent
— the idempotency+clamp fix for issue #4
- phase-lifecycle-policy.generated.cjs (7.0K): 14 pure phase naming/directory
helpers from sdk/src/query/phase-lifecycle-policy.ts
Run to regenerate:
node sdk/scripts/gen-phase.mjs
node sdk/scripts/gen-phase-lifecycle.mjs
node sdk/scripts/gen-phase-lifecycle-policy.mjs
References:
- ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
- Issue #4 (open-gsd/get-shit-done-redux)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(4): migrate bin/lib/phase.cjs cmdPhaseComplete to use generated helpers
Replace the blind-increment + unclamped percent bug in cmdPhaseComplete with
the idempotent ROADMAP-derived approach: read freshly-updated ROADMAP, call
deriveProgressFromRoadmap() from phase-lifecycle.generated.cjs, fall back to
existing value when ROADMAP is unavailable. clampPercent() prevents >100%.
Root cause fix for issue #4: the original parseInt(completedRaw) + 1 on every
call made phase complete non-idempotent; the missing Math.min(100, ...) clamp
allowed Progress to exceed 100%.
I/O adapter pattern (ADR-3524 §4): pure computation in generated module;
CJS supplies sync readFileSync; SDK supplies async readFile. Same logic, two adapters.
Closes: Tests in 4-phase-complete-cjs-regression.test.cjs go GREEN.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): add freshness checks + npm scripts for phase generated artifacts (D4/D6)
Add check-phase-fresh.mjs, check-phase-lifecycle-fresh.mjs, and
check-phase-lifecycle-policy-fresh.mjs (same pattern as check-project-root-fresh.mjs:
import buildXCjs() from the generator, regenerate in-memory, byte-compare to committed
file, exit 1 if stale).
Add gen:phase, check:phase-fresh, gen:phase-lifecycle, check:phase-lifecycle-fresh,
gen:phase-lifecycle-policy, check:phase-lifecycle-policy-fresh to sdk/package.json.
Note: gen:phase-lifecycle / check:phase-lifecycle-fresh do not require 'npm run build'
because the generator defines pure functions directly rather than importing dist.
Update shared-module-handsync-allowlist.json: reclassify phase.cjs justification to
reflect that it now consumes phase-lifecycle.generated.cjs for cmdPhaseComplete. The
*.generated.cjs files are excluded by the lint scanner (excludes *.generated.cjs) so
no new allowlist entries are required for the generated artifacts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* ci(4): add freshness-check CI steps for phase, phase-lifecycle, phase-lifecycle-policy
Add three drift-check steps to .github/workflows/test.yml following the same
pattern as the existing freshness checks (ubuntu-latest + node 24 only):
- SDK generated phase artifact drift check
- SDK generated phase-lifecycle artifact drift check
- SDK generated phase-lifecycle-policy artifact drift check
These guard against editors modifying the generated *.cjs files directly.
They run check-phase-fresh.mjs, check-phase-lifecycle-fresh.mjs, and
check-phase-lifecycle-policy-fresh.mjs respectively (added in D4).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(4): amend ADR-3524 — phase * I/O adapter pattern for issue #4 (D8)
Append a 2026-05-23 amendment to docs/adr/3524-cjs-sdk-hard-seam.md documenting
the Phase * cooperating-sibling retirement: three new generator scripts extract
pure-computation helpers from phase.ts / phase-lifecycle.ts / phase-lifecycle-policy.ts,
cmdPhaseComplete migrates to deriveProgressFromRoadmap + clampPercent for idempotency,
freshness checks + CI steps added.
Clarifies what is NOT generated (async I/O-bound mutation handlers stay per-side per
Section 4) and notes open drift bugs #6 and #26 for traceability.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(4): add changeset fragment for cmdPhaseComplete fix
Refs #4
* fix(154): use canonical /gsd:plan-phase form in phase-lifecycle-policy.ts
Replaces the retired /gsd-plan-phase slash command reference with the
canonical colon-namespaced /gsd:plan-phase in the TS source template
string that feeds the generated CJS roadmap entry helper.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore(154): regenerate phase-lifecycle-policy.generated.cjs after slash-namespace fix
Regenerated via node sdk/scripts/gen-phase-lifecycle-policy.mjs after
fixing /gsd-plan-phase → /gsd:plan-phase in the TS source. Generated
file now contains the canonical colon form.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(154): cross-platform frontmatter regex anchor in 4-phase-complete-cjs-regression.test.cjs
Replaces /^---\n/ with /^---\r?\n/ so the frontmatter extraction helper
in the regression test tolerates Windows CRLF line endings (autocrlf=true
checkout leaves \r before \n, causing /^---\n/ to never match).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(154): add new generated CJS modules to INVENTORY.md and regenerate manifest
Adds three missing rows to the CLI Modules table:
- phase-lifecycle-policy.generated.cjs
- phase-lifecycle.generated.cjs
- phase.generated.cjs
Bumps the headline count from 74 to 77 to match the filesystem.
Also regenerates docs/INVENTORY-MANIFEST.json via
node scripts/gen-inventory-manifest.cjs --write.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(154): regenerate phase-lifecycle-policy.generated.cjs with hyphen form
Root cause: commit 6cd701f4 regenerated the CJS artifact but at that point
sdk/dist/query/phase-lifecycle-policy.js already had the correct /gsd-plan-phase
(hyphen) form while sdk/src/query/phase-lifecycle-policy.ts still had /gsd:plan-phase
(colon). The generator uses Function.prototype.toString() on the compiled dist, so
the CJS picked up the wrong string from the stale TS source that was compiled into
dist at some earlier point.
Fix: correct the TS source to /gsd-plan-phase and re-run gen-phase-lifecycle-policy.mjs
so that buildPhaseRoadmapEntry in the CJS emits the hyphen form, satisfying the
bug-3584-runtime-slash-emitters.test.cjs assertion at line 179.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(154): restore /gsd:plan-phase canonical form in phase-lifecycle-policy
Commit 0c3a9c75 incorrectly reverted the slash-namespace fix by misreading
sdk/dist/ (a build artifact in hyphen form for non-Claude runtimes) as the
authoritative source. The canonical form for Claude-facing source is
/gsd:plan-phase (colon-namespaced).
Fix: revert TS source back to /gsd:plan-phase, rebuild dist, regenerate
phase-lifecycle-policy.generated.cjs.
Fixes bug-2543-gsd-slash-namespace test failure.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(154): update INVENTORY.md CLI Modules count to 79 after rebase onto main
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(154): use hyphen form /gsd-plan-phase in persisted phase section template
- sdk/src/query/phase-lifecycle-policy.ts: use /gsd-plan-phase (routable
hyphen form) in the phase scaffold template that gets persisted to
ROADMAP.md; bug-3584 requires persisted artifacts use the hyphen form
- docs/INVENTORY.md: add missing runtime-name-policy.cjs row in CLI
Modules table
- tests/4-phase-complete-cjs-regression.test.cjs: add maxRetries/retryDelay
to rmSync calls to satisfy Windows parity ratchet (baseline was 95)
- Regenerate phase-lifecycle-policy.generated.cjs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(meta): invalidate bug-2543 outdated /gsd:<cmd> namespace invariant
The "no /gsd-<cmd> hyphen form in source files" scan (test 2 of the
describe block) is skipped via test.skip. Motivation:
- Bug-3584 (2026-05-15) introduced runtime-slash.cjs, which intentionally
emits `/gsd-${token}` for skills-based runtimes. This is the correct
canonical form for runtime-persisted strings (ROADMAP.md, STATE.md,
recommended_actions, fix hints).
- Bug-2543 was last updated 2026-05-12, three days BEFORE bug-3584 landed.
The "no hyphen form" invariant was never updated to reflect the new
two-tier model.
- PR #154 first-pass: an agent misread bug-2543 and reverted the correct
`/gsd-plan-phase` to `/gsd:plan-phase` in phase-lifecycle-policy.ts:156,
breaking tests/bug-3584-runtime-slash-emitters.test.cjs. A 2nd-pass agent
reverted.
The canonical active invariant for runtime-emitter context is:
tests/bug-3584-runtime-slash-emitters.test.cjs
The remaining 4 tests in this file (commands/gsd/ existence, command
filename slug format, transformer behavior, non-command identifier safety)
are still valid and remain active — only test 2 is skipped. This avoids
vacuous-truth (a full describe-block skip would let all assertions pass
trivially).
See CONTEXT.md § "Slash-command form: /gsd-<cmd> vs /gsd:<cmd>" (added
in the companion commit) for the full two-tier model documentation.
User directive: 2026-05-23 session authorizing this invalidation.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(context): document /gsd-<cmd> slash-command migration for AI agents
Adds CONTEXT.md § "Slash-command form: /gsd-<cmd> (current) vs /gsd:<cmd>
(legacy)" to give future agents an unambiguous reference for which form
to use in which context.
Covers:
- The two-tier model (source text → colon; runtime-emitted strings → hyphen)
- The runtime-emitter authority: get-shit-done/bin/lib/runtime-slash.cjs
- The canonical invariant test: bug-3584-runtime-slash-emitters.test.cjs
- The PR #154 incident: how an agent misread bug-2543 and applied the wrong form
- An explicit "Context for AI agents" block: stop and re-read if bug-2543 is
influencing a patch
- A note that DEFECT.AGENT-RETIRED-SLASH-SYNTAX-DRIFT.* predicates (written
pre-two-tier) are stale for runtime-emitter contexts
Also updates the stale DEFECT predicates at the end of CONTEXT.md with a
clarifying note (the predicates remain for historical reference; the new §
supersedes their fix-forward guidance for runtime-emitter contexts).
Motivation: PR #154 first-pass incident (2026-05-23 session).
Canonical runtime contract: tests/bug-3584-runtime-slash-emitters.test.cjs.
Companion: test(meta) commit invalidating bug-2543's scan.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(meta): re-activate bug-2543 scan as scoped invariant, exclude runtime-emitter contexts
Codex adversarial review of PR #164 [high finding]: the single content-scanning
test in bug-2543 was test.skip, leaving a vacuous test surface. The transformer/
filename unit tests remained active but no live source surface was guarded.
Fix: replace test.skip with an active scoped invariant.
Scope change:
- REMOVED get-shit-done/bin/lib/ from SEARCH_DIRS entirely. That directory is
runtime-emitter territory (runtime-slash.cjs, *.generated.cjs,
phase-lifecycle-policy.ts) and intentionally uses /gsd-<cmd> (hyphen) per
bug-3584's contract. Scanning it causes false positives that led to PR #154
first-pass incident.
- Added RUNTIME_EMITTER_EXCLUDES set documenting exactly why each file is exempt.
- Remaining SEARCH_DIRS (workflows/, references/, templates/, commands/gsd/,
agents/, hooks/) are Claude-facing source — colon form is correct there.
Verified: 9/9 tests pass, 0 skipped.
Canonical runtime-emitter contract: tests/bug-3584-runtime-slash-emitters.test.cjs
bug-2543's scoped scope: excludes bin/lib/ (runtime-emitter contexts).
* docs(context): rewrite slash-command section as directory-level matrix
Codex adversarial review of PR #164 [high finding]: the previous CONTEXT.md
section was internally contradictory — line 616 claimed /gsd-<cmd> was globally
canonical while lines 634/640 correctly stated Claude-facing source text uses
/gsd:<cmd>. Same document; opposite claims.
Root cause: the first push of this section (2026-05-23) overstated the hyphen
form as universal, when the project has always had a two-tier model.
Fix: replace the section with an unambiguous directory-level matrix.
New structure:
- Single table mapping each directory/surface to its correct form and enforcement.
- "How to choose" decision tree (4 steps, replaces ambiguous prose).
- "What was WRONG previously" retains historical motivation and adds the
PR #164 contradiction incident to the record.
- "Context for AI agents" updated: ban mass-rewrites based on single test failure,
cite the two-tier model explicitly.
Two-tier model (unchanged from reality, now clearly documented):
- Claude-facing source (commands/, agents/, workflows/, etc.): /gsd:<cmd> colon.
- Runtime-emitter contexts (runtime-slash.cjs, *.generated.cjs, ROADMAP.md
persistence): /gsd-<cmd> hyphen per bug-3584 invariant.
Canonical authorities: bug-2543 (colon contract), bug-3584 (hyphen contract).
* fix(workflows): replace dead /gsd-* tokens with live registry forms
Codex adversarial review of PR #164 [medium finding]: stale slash-command
references in user-facing workflow content. Registry-backed sweep confirmed
the following tokens are not in commands/gsd/ registry.
Tokens removed/updated (dead token → live registry form):
1. /gsd-remove-workspace → /gsd:workspace --remove <name>
File: get-shit-done/workflows/list-workspaces.md:58
Reason: no commands/gsd/remove-workspace.md; remove-workspace is a subcommand
of /gsd:workspace (commands/gsd/workspace.md, --remove flag).
2. /gsd-list-workspaces → /gsd:workspace --list
File: get-shit-done/workflows/remove-workspace.md:35
Reason: no commands/gsd/list-workspaces.md; list-workspaces is a subcommand
of /gsd:workspace (commands/gsd/workspace.md, --list flag).
3. /gsd-list-phase-assumptions <phase> → /gsd:discuss-phase <phase> --assumptions
File: get-shit-done/workflows/list-phase-assumptions.md:17-18 (usage block)
Reason: no commands/gsd/list-phase-assumptions.md; the workflow is invoked
via commands/gsd/discuss-phase.md with --assumptions flag.
4. /gsd-list-phase-assumptions 2 → /gsd:discuss-phase 2 --assumptions
File: get-shit-done/references/continuation-format.md:59
Reason: same as #3.
Sweep scope: user-facing markdown only (workflows/, references/). Runtime-emitter
hyphen-form references in bin/lib/ are guarded by bug-3584 and were not touched.
* chore(164): add changeset fragment for adversarial-review fixes
The 3 commits addressing Codex review touched user-facing surfaces
(get-shit-done/workflows/, get-shit-done/references/, CONTEXT.md,
bug-2543 test). Add fragment to satisfy changeset-lint.
Refs #164
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
