Files

Tom Boucher d98b55562c enhance(#3910 ): the raw terminator is banned by construction (#3980 )

* enhance(#3910): move the last src/ terminators onto the seam

Phase 6 bans the raw terminator by construction, which it cannot do while
violations stand. A census found 12 sites the rule would flag; nine of the ten
unsanctioned ones were owned by no phase of the epic at all — a coverage hole
in the decomposition, since P0-P2 are infra, P3 the gate modules, P4 the
scanners, P5 the fragments, P7 the hooks, P8 io.cts, and P6 itself only adds
the rule. `src/**/*.cts` now holds exactly 2 raw exits, both inside
`terminateNow`, the single sanctioned site.

`io.cts`'s `error()` is the interesting one. It was first called substantive on
"dozens of callers, contract risk" — asserted, not measured, and the
measurement refuted it: 289 call sites, zero inside a try whose catch would
swallow a throw. The real obstacle was structural instead: `terminateNow`
cannot emit exit 1, because ADR-3889 §1 makes 0 and 1 unallocatable and
`nameForExitCode(1)` throws. So the only route is `ExitError` under `runMain`,
which sets exitCode and writes stderr only when the error carries a user
message — keeping the existing stderr write and throwing a message-less
ExitError is observably identical.

That census was still too narrow, and running the CLI proved it. It asked
whether the CALL sits in a try/catch; the two regressions that surfaced were
interceptors elsewhere on the stack:

- `command-routing-hub.cts`'s `dispatch()` swallowed the ExitError into a
  HandlerFailure, so the caller emitted a duplicated, wrong stderr line on
  every Hub-routed path. It now rethrows ExitError explicitly — the same shape
  `gsd-tools.cjs` already used at two dispatch sites, so this follows an
  established idiom rather than inventing one.
- the profile-pipeline router's deliberately un-awaited `.catch(e => error(...))`
  turned an ExitError rejection into an uncaught exception; it now mirrors
  runMain's handling.

`edge-probe` and `ui-consideration-probe` gained `runMain` wrappers because
probe-core's new throwing default would otherwise have escaped them.

A follow-up sweep of every dispatcher — 19 command routers, the Hub, the
gsd-tools dispatch seams — found no further swallowing catch. The admitted
bound: ~1260 non-rethrowing catches repo-wide were scanned structurally but not
individually classified. Both real regressions were found by execution, not by
reading, so the suite is the detector that matters here.

`gsd-tools.cjs:253` stays a raw exit deliberately: it is the ensureRuntimeBuild
bootstrap, which runs before cli-exit is required, so the seam does not yet
exist. It needs a second allowlist entry, which means #3910's "single allowlist
entry" criterion is unachievable as written.

Verification runs on the remote runner.

Refs #3910

* enhance(#3910): ban the raw terminator by construction

Adds local/require-registered-exit and registers it on all four globs:
src/**/*.cts, scripts/**/*.cjs, hooks/**/*.js, gsd-core/bin/**/*.cjs.

Registering on the .cts glob is load-bearing, not redundant — the emitted .cjs
mirrors are globally eslint-ignored, so a rule registered only on the emitted
globs is blind to the sources. That is the #3496 lesson, and it is how the
previous guard became invisible: n/no-process-exit was 'error' in one block yet
fired zero times on all three surfaces that mattered.

The dead n/no-process-exit: 'off' block for hooks is deleted in the same PR.
Phase 7 migrated every hook, so the exemption now protects nothing.

Two allowlist entries, not the one #3910 anticipated. terminateNow's body is
detected STRUCTURALLY — a process.exit lexically inside a function of that name
— rather than by a path and line number that rots. The second is
gsd-tools.cjs's ensureRuntimeBuild bootstrap, an inline disable with its reason
at the call site: it runs before ./lib/cli-exit.cjs is required, so the seam
does not exist yet and no migration is possible. #3910's 'single allowlist
entry' criterion is therefore unachievable as written, and is amended with the
measurement rather than quietly missed.

The rule is proven able to FAIL, per glob: four positive controls, one for each
registered glob. A guard that cannot be shown to fire is not a guard. Four
matching negative controls pin process.exitCode as never-flagged — conflating
it with process.exit is what inflated this epic's original census 2x. An
allowlist case and a near-miss (same shape, different function name) fix the
structural detection in place.

Verification runs on the remote runner.

Refs #3910

* fix(#3910): stop the detached catch from throwing, and scope the allowlist

Review findings, one of them a regression the previous fix introduced.

_handlePipelineRejection called error() from inside a DETACHED .catch().
error() now throws, so that throw became an unhandled promise rejection — and
on Node >=15 with --unhandled-rejections=throw, Node dumps a raw stack trace
with absolute paths on top of the clean Error: line. That was impossible before
this branch, because process.exit(1) terminated synchronously before any
rejection machinery could observe it. The handler now writes byte-identical
stderr itself, in both plain and --json-errors form, and sets exitCode in
place. This was the THIRD interceptor found, and like the first two it surfaced
by running the CLI rather than by reading code.

The rule's terminateNow allowlist had no path constraint, so any function
anywhere named terminateNow across all four globs inherited it. It now requires
the structural nesting check AND a cli-exit.cts basename — still no line
numbers to rot.

The four per-glob positive controls only varied a filename inside RuleTester,
which never resolves eslint.config.mjs. Since the rule is filename-agnostic,
all four exercised identical logic and none proved the rule was WIRED — this
epic's own failure mode. A registration test now asserts the rule resolves for
a real path in each glob, and it is proven able to fail: removing one glob's
registration flips the resolved value from [2] to undefined.

Three evasions the rule cannot catch (computed member, aliasing, .call/.apply)
are documented in its header and pinned by tests, labelled as known limits
rather than endorsed, so a future change that starts catching them is a
deliberate diff.

Refs #3910

* docs(#3910): document the raw-terminator ban

Reference and Explanation via a new docs/features fragment (FEATURES.md is
generated from it, not hand-edited). How-To:
docs/how-to/resolve-a-raw-terminator-finding.md, indexed from docs/README.md —
a contributor whose code trips the rule picks among three replacements by
surface (runMain/ExitError for a CLI path, terminateNow for a hook,
process.exitCode where the process should drain), and needs to know why
process.exitCode is correct and never flagged, since conflating the two is what
inflated this epic's original census 2x.

The page also names the three patterns the rule cannot catch and says plainly
that using one to dodge it is a review finding, not a fix — documenting them
without that sentence would read as a sanctioned workaround.

docs/INVENTORY.md deliberately untouched: eslint-rules/ is not a tracked family
in the manifest (verified — a regen produced a zero diff), so a hand-written row
would desync the table from the family it claims to belong to.

Refs #3910

* fix(#3910): a catch that sniffs the message swallows an ExitError

The remote run returned 41 failures, and one of them was a live production
regression rather than a test artifact.

`cmdMilestoneComplete`'s unstarted-phase guard re-threw only when
`e.message.startsWith('Cannot mark milestone complete:')`. `error()` used to
`process.exit(1)`, uncatchable, so the guard always fired. It now throws an
ExitError carrying no message, the string test fails, and the ExitError was
silently swallowed — the guard stopped blocking milestone completion entirely.
Proven against the real CLI: pre-fix, a milestone with an unstarted phase
archived at exit 0; post-fix it is blocked at exit 1 with the intended message.

That is a guard that silently stopped guarding, which is this epic's thesis
appearing inside the phase meant to enforce it. Worth stating plainly: an
earlier census DID examine this site, saw a `throw e`, and classified it as
rethrowing. It was wrong — the rethrow is conditional, and a conditional
rethrow on an inspected message is indistinguishable from an unconditional one
unless you read the predicate.

So the class was swept rather than patched where it was tripped over. An AST
census of every CatchClause across src/, gsd-core/bin/ and scripts/ found 38
conditional rethrows. Two more had the same defect and are fixed the same way:
`config.cts`'s `'No config.json'` sniff and `gsd-tools.cjs`'s
`e.name === 'WindowsError'`. The remaining 25 are provably unreachable — every
one wraps a bare fs, YAML, manifest-require or git-exec primitive that cannot
throw ExitError — and two were scanner false positives, both explained. Each
fix is an unconditional `instanceof ExitError` rethrow placed BEFORE any
inspection, matching the idiom command-routing-hub and gsd-tools already used.

Residual bound, stated rather than implied: zero known-reachable unfixed sites,
contingent only on error() never later being called inside one of those 25
primitive try blocks.

The remaining failures were harness artifacts, and the harnesses were corrected
to the new contract rather than the assertions weakened. Tests that mocked
`process.exit` to observe termination now catch ExitError and assert its code;
tests parsing stderr as a single JSON object still assert exactly that, with
their ad-hoc `node -e` scripts wrapped in runMain so it is true. milestone and
phase-resolution-parity needed no test change — they were correctly written
against the real bug and are what caught it.

Verification runs on the remote runner.

Refs #3910

* chore(#3910): backfill the changeset PR number

Also reframes the fragment to lead with the user-visible change — the
milestone guard blocking again — rather than the narrowest of the three fixes.

Refs #3910

---------

Co-authored-by: sim <sim@local>

2026-08-28 03:15:39 -04:00

15 KiB

Raw Blame History

GSD Core documentation

Documentation is organised into four quadrants: tutorials help you learn by doing, how-to guides solve specific tasks, reference states authoritative facts, and explanation explores concepts and design decisions.

Language versions: English · Português (pt-BR) · 日本語 · 简体中文

Tutorials

Your first project — install to first shipped phase, one guaranteed path
Onboarding an existing codebase — bring GSD Core to a brownfield repo
Build your first capability — author a tiny declarative capability and watch it act in the loop
Install your first capability — install a third-party capability end-to-end: consent, verify, check for updates, remove

How-to guides

Install on your runtime — runtime-specific install steps for all 16 supported runtimes
Install a minimal GSD and add skills later — install only the core skills, then grow the surface with profiles and /gsd-surface
Attach a plugin-provided skill to a GSD agent — use the global:plugin:skill entry form to load Claude Code plugin skills into agent prompts
Discuss a phase — capture implementation decisions before planning begins
Resolve edge-coverage findings — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions
Probe edges in a non-English project — get real edge coverage on a spec written in another language, and tell "no edges here" apart from "the probe could not read it"
Resolve prohibition findings — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
Resolve an unreachable-workflow finding — wire or fully sweep a shipped workflow that no command, agent, or skill references
Acknowledge emitted-artifact drift — declare a deliberate emitted-byte ripple or workflow/agent growth in a commit trailer, and migrate an older ack fragment
Change the STATE.md schema — add, change or remove a STATE.md frontmatter key and keep the template and all five reference documents in step
Resolve verify-command path findings — fix an <automated> verify command whose target directory does not resolve from the executor's cwd
State a failing direction — say what output constitutes failure for an <automated> verify command, and migrate a phase planned before the rule
Resolve a contract-drift finding — bring an agent's completion contract, read-tag gate, or deleted-file test reference back into agreement with the registry
Resolve unreachable-guard findings — fix shell guards whose fallback arm cannot run, and tell "nothing to report" apart from "could not look"
Declare a hook's crash policy — terminate a GSD hook with allow/deny/crash, declare its ON_CRASH policy, and tell a hook's own crash apart from a check that could not run at all
Resolve a skipped capability probe — act on a coverage gate that held your phase for an unestablished scope, or a planning checkpoint that reported skipped instead of a verdict
Diagnose which gsd-tools is running — tell this package's tool apart from the predecessor's colliding binary and from a gsd-core too old to identify itself
Resolve an ESLint glob-coverage finding — bring a source file that matches no lint rule under coverage, or record a reasoned exemption
Resolve a raw-terminator finding — pick runMain/ExitError, terminateNow, or process.exitCode for a local/require-registered-exit finding, and know the two allowlist entries and the rule's documented evasions
Read the statusline freshness marker — turn on state ~N commits back, and tell "STATE.md is fresh" apart from "freshness could not be established"
Consume the planning snapshot — read planning inspect from a dashboard or harness, and tell "nothing to report" apart from "could not look"
Consume the state contract — read .planning/state.json from a workbench or editor extension, gate on the contract version, and tell "nothing to show" apart from "could not look"
Keep planning docs out of a shared repo — make .planning/ local-only, including untracking files git already tracks (the step .gitignore alone cannot do)
Publish PRs without planning artifacts — keep .planning/ committed locally, so worktrees and /gsd-undo keep working, while planning.pr_strict keeps every planning path out of the branch you push
Plan a phase — run research, decompose work, and verify plan quality
Verify a dependency-compatibility claim — act on a compatibility claim the researcher left [ASSUMED], and tell "nothing declared" apart from "a constraint is declared" and "the lookup failed"
Execute a phase — run plans in parallel waves with fresh-context subagents
Enable parallel reviewer lanes — cut a multi-reviewer /gsd-review pass toward its slowest lane, and tell a rate-limited lane apart from one that was never selected
Verify and ship — walk through completed work, diagnose failures, and create the PR
Catch complexity before it compounds — enable the post-execute refactor hook, read a proposal's score vs. anchor delta, and accept or decline it
Run phases autonomously — use autonomous mode for unattended phase execution
Handle quick and fast tasks — use /gsd-quick and /gsd-fast for ad-hoc work outside the phase loop
Configure model profiles — switch between quality, balanced, and budget model tiers
Control which host runtime GSD reports — read the agent_runtime ladder, understand what host detection looks at, and pin the runtime when detection is not what you want
Set up cross-AI review — configure a second AI to review code produced by the primary agent
Scope code review depth by path — escalate /gsd-code-review to deep for sensitive directories while the rest of the repo stays at the default depth
Work in parallel with workstreams — run independent lines of work simultaneously using workstreams
Isolate work with workspaces — use workspaces to sandbox experimental or risky changes
Debug a failed execution — diagnose and recover from broken or incomplete phase execution
Interpret scope-conformance warnings — read the advisory the worktree-wave merge emits when a plan branch commits outside its declared scope
Interpret install-shadow warnings — read the advisory GSD Core emits when a /gsd-* trigger is installed at both scopes and one silently wins, and tell "nothing to report" apart from "could not look"
Interpret state validate results — read the scope reason codes and tell "nothing to report" apart from "could not look"
Spike and sketch — use /gsd-spike and /gsd-sketch for exploratory work before committing to a plan
Design a UI phase — use the UI phase loop for frontend and visual work
Enable live-DOM verification — opt a project into browser-backed UI acceptance checks during execution, handle the browser-profile lock, and tell "nothing to report" apart from "could not look"
Develop a Capability for GSD 1.5+ — add feature Capabilities, hook fragments, and registry entries
Ship a reviewer lane in your capability — declare a reviewer body so /gsd-review discovers, invokes, and renders your external review CLI or model endpoint
List your reviewer lane in the registry — publish a lane you have built to the Reviewer Lane Registry so other people can find and install it
Take over a capability or EoS integration — assume maintainership of an existing third-party capability, reviewer lane, or EoS host integration through a handoff, an adoption fork, first-party absorption, or a de-listing
Add or update a host's integration — set a host's documentation-sourced runtime.hostIntegration axes (ADR-1239 Phase A), with the undocumented sentinel rule
Migrate an install test to the executed plan — convert an fs.existsSync-probing install test group to a value assertion against installRuntimeArtifacts's executed-plan return, and test against a fake fs adapter
Vendor a dependency — add a third-party package gsd-core/bin/** needs at runtime as a verbatim vendored artifact, keep it out of dependencies, and pick the right upstream bundle
Turn a capability off (and keep it off) — disable a capability via the surface, or gate individual hooks off without removing the capability
Drive GSD from a tracker issue — start a phase from a GitHub, Linear, or Jira issue
Migrate from GSD 2 — upgrade an existing GSD 2 project to GSD Core
Update GSD — re-run the installer to pick up the latest release
Clean up get-shit-done-cc — remove leftover old-package artifacts that cause a spurious ⬆ /gsd-update indicator after migrating to @opengsd/gsd-core
Fix the worktree base-mismatch (exit 42) error — resolve the branch-divergence condition that halts parallel phase execution
Recover and troubleshoot — fix common problems, rebuild context, and uninstall

Reference

Commands — every command with flags and examples
Configuration — full config schema, model profiles, git branching strategies
CLI tools — gsd-tools.cjs programmatic API for workflows and agents
JSON error mode — gsd-tools failure channels: faults (stderr, exit 1) vs degraded results (stdout, exit 0), and the reason-code taxonomy
Features — complete feature index
Inventory — installed skills and surface map
STATE.md schema — field-by-field reference for .planning/STATE.md
CONTEXT.md schema — field-by-field reference for .planning/phases/<N>/CONTEXT.md
PLAN.md schema — field-by-field reference for .planning/phases/<N>/PLAN.md
Planning artifacts — all .planning/ files and their roles
Review and verification capabilities — code review, security, and Nyquist capability ownership and hook contracts
Gate predicates — canonical specification of the phase-gate predicate vocabulary
Capability matrix — generated catalogue of every capability's role, tier, extension points, hook kinds, and engines.gsd
Capability manifest — the full capability.json schema and validation rules
gsd capability command — install / update / remove / list reference for third-party capabilities
Workflow fragments — in-file  marker grammar for fragmentizing workflow markdown at emission time
Reviewer Lane Registry — generated catalogue of third-party reviewer lanes, with their flags, transport, and install commands

Explanation

Context engineering — how context rot forms and how GSD Core prevents it
The phase loop — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
Multi-agent orchestration — how subagents are spawned, scoped, and coordinated
Security model — trust boundaries, permissions, and safe automation
The capability trust model — why third-party capabilities are gated by consent + integrity + reversibility, not a sandbox
How overlay capabilities compose — why first-party always wins and how the loader resolves precedence, conflicts, and fail-open load-failure warnings
Architecture — system architecture, agent model, and data flow
The Embeddable Orchestration System — one public, versioned contract for embedding GSD across many hosts
Discuss modes — assumptions mode vs interview mode for /gsd-discuss-phase
Context monitoring — context window monitoring hook architecture
Issue-driven orchestration — recipe for driving GSD from a tracker issue using existing primitives

What's new in 1.7.0 — curated highlights of the 1.7.0 release
Root README — landing page, quickstart, and documentation overview
Changelog — release history

15 KiB Raw Blame History