Files

Tom Boucher fb2d122d7f feat(#3841 ): assert gsd-tools identity on every state-mutating verb (#3848 )

* feat(#3841): assert gsd-tools identity before any state-mutating verb

only this package publishes. The path-based branches — a project-local install,
a runtime config directory — had no such guarantee; they trusted their
configured location. This closes them.

Mechanism: once resolution finishes, and before any verb runs, the preamble
probes the tool it picked with `runtime-identity --raw` and matches the answer
with a shell `case` pattern ANCHORED to the start of the compact payload
(`{"packageName":"@opengsd/gsd-core"`). An unanchored substring match accepts
the decoy `{"packageName":"get-shit-done-cc","note":"@opengsd/gsd-core"}`, which
any colliding package could publish. The outcome is exported as the two-valued
`GSD_IDENTITY_STATUS` (`ok`/`unverified`), so the gate is asserted on a VALUE
rather than on warning prose. Rollout is warn-then-fail per the #3146 ruling:
`unverified` prints one line naming BOTH causes and continues, because
`no_identity_verb` cannot tell a foreign package from an `@opengsd/gsd-core`
older than the verb, and at rollout the old-version case is the common one.

The blocker was byte budget, not design. The preamble is inlined into 112
shipped files and several sat within single-digit bytes of frozen ceilings
(`gsd-verifier.md` 16 bytes, `gsd-executor.md` 33, `execute-phase.md` 234); a
first attempt broke five of them. What made room was collapsing the resolver's
twenty near-identical `elif [ -f … ]` arms into one candidate-list helper
(`_gsd_at`), which buys far more than the assertion costs. The preamble is now
2,624 bytes against 4,500 — a net 1,876 bytes SMALLER per inlined file, so every
capped file moved away from its ceiling rather than toward it. No cap raised, no
size-budget exception added, no override token emitted.

Resolution order, every runtime-home probe, the `unset -f gsd_run` re-source
fix, the fail-closed `exit 1`, and the `CLAUDE_ENV_FILE` persistence are all
preserved byte-for-byte in substring terms; the snippet still begins with
`_GSD_SHIM_NAME=` and still ends with `fi`, which the parity extractors anchor
on. `gsd-core/references/gsd-run-resolver.md` is re-synced byte-equal.

Also fixes two stale claims found in passing: CONTEXT.md and FEATURES.md both
described an `[ -x ]` guard as the load-bearing re-source defense. That guard
was tried and REMOVED in #3831 — it rejected the bare function name, fell
through every branch, and hit `exit 1`, which kills a sourced caller's shell.
`unset -f gsd_run` is the actual mechanism.

Refs #3841

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#3841): pair the anchor's brace by requiring a closed identity payload

The matrix went red on `tests/new-project-mvp-prompt.test.cjs` — "new-project.md
has unbalanced braces: net depth 2" — plus a knock-on report from its parent
`bug #1516` describe, which is the same failure counted once at the child and
once at the block.

Root cause: that guard (:182-189, mirroring #3784 bd53925f) walks characters and
increments on `{`, decrements on `}`, with no awareness of shell quoting. It
scans `new-project.md` PLUS every `new-project/steps/*.md`, and both
`new-project.md` and `steps/auto-mode-config.md` carry one inlined preamble copy
— hence net 2 from a snippet that was off by exactly one. The unpaired brace was
the `{` inside the single-quoted `case` pattern of the identity anchor, which is
correct shell and invisible to a text scanner.

Fix in the snippet, not the guard. The pattern now anchors at BOTH ends:
`'{"packageName":"@opengsd/gsd-core"'*'}'`. That balances 51/51 with a brace that
does real work rather than a cosmetic pair — a truncated payload whose prefix
matches now fails too, where before it verified. Safe for any future additive
field: a JSON object's own closing brace is always the last character, whatever
type the last value has, which is pinned by two negative-space tests (a nested
object and an array-valued last key must both still verify). Cost: +3 bytes,
against the 1,873 the resolver fold already gave back.

The alternative considered and rejected was dropping the literal `{` for a `?`
glob. It balances too, but weakens the anchor from "must be an opening brace" to
"must be any one character", and the anchor is the entire point.

Two guards added so this cannot recur silently:
- runtime-launcher-parity (F0) pins brace balance at the SNIPPET, so the next
  edit to that pattern fails on the file it broke instead of surfacing three
  files downstream in a test whose name mentions neither the launcher nor this
  issue. It also asserts depth never goes negative, since a `}` preceding its
  `{` nets to zero while being unbalanced at every prefix.
- runtime-identity gains behavioral truncated-payload and trailing-garbage
  fixtures, so the added `}` is proven load-bearing rather than merely present.

Verified: snippet 51/51 braces; new-project combined net depth 0; the seven
other preamble-bearing files with nonzero depth are unchanged from merged next
(their own prose, not the preamble, and not in any guard's scan set); all 112
inlined copies and the resolver reference re-synced byte-equal; sync:launcher
idempotent on the second run.

Refs #3841

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#3841): backfill changeset PR number

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

2026-08-25 01:05:53 -04:00

5.7 KiB

Raw Blame History

How to diagnose which `gsd-tools` is running

Two packages publish a binary called gsd-tools: this one, and the predecessor get-shit-done-cc. They answer some of the same verb names with different behavior. This guide tells you which one you have and how to fix a bad resolution.

Use it when:

a workflow behaves unlike its documentation,
a workflow stops with gsd-tools.cjs not found … and gsd_run is not on PATH,
or you simply want to confirm which tool a project is running against.

Why this matters

#3129 is the worked example. phases.clear archives your phase directories under this package and deletes them under the predecessor. Both print success-shaped output, and .planning/ is gitignored by default, so the difference is invisible until the directories are gone.

Shipped workflows no longer resolve gsd-tools from PATH at all — they resolve gsd_run, which only this package publishes. That closes the path that caused #3129. The remaining path-based branches — a project-local install, a runtime config directory — are checked by assertion instead: the launcher probes whatever it resolved and warns when the tool cannot prove it is @opengsd/gsd-core.

If you got here from that warning, it looks like this:

WARNING: "/some/path/gsd-tools.cjs" did not prove it is @opengsd/gsd-core - it is either a
different package or an @opengsd/gsd-core older than the runtime-identity verb.

The two causes need opposite fixes, and the warning cannot tell them apart — the sections below can. The steps that follow are for confirming your setup and for fixing the cases the resolver refuses outright.

Ask the tool what it is

gsd-tools runtime-identity

A healthy GSD runtime prints:

{
  "packageName": "@opengsd/gsd-core",
  "version": "1.12.0"
}

Three other outcomes are possible, and they mean different things:

What you see	What it means
The JSON above	This is our tool. Nothing to do.
A usage screen mentioning `gsd-sdk`, exit 1	This is the predecessor's binary. See A different package owns it.
`Error: Unknown command: runtime-identity`	This is our tool, but older than the verb. See It is an old gsd-core.
Nothing runs at all	Nothing named `gsd-tools` is on your `PATH`. That is fine — workflows do not need it.

Then find out which package owns the file:

readlink -f "$(command -v gsd-tools)"

A different package owns it

The resolved path contains get-shit-done-cc, or the identity probe printed a gsd-sdk usage screen.

Workflows will not reach it — they resolve gsd_run, which that package does not publish — so this is no longer dangerous. It is still worth resolving, because you invoking gsd-tools by hand will reach the wrong tool.

If you no longer use the predecessor:

npm uninstall -g get-shit-done-cc

If you need both installed, put this package's bin directory first on PATH:

export PATH="$(npm prefix -g)/bin:$PATH"

Re-run gsd-tools runtime-identity and confirm it reports @opengsd/gsd-core.

It is an old gsd-core

The resolved path is inside @opengsd/gsd-core, but runtime-identity is not a known command. That version predates the verb. Nothing is wrong beyond being out of date:

npm install -g @opengsd/gsd-core@latest

A workflow says `gsd_run is not on PATH`

The resolver looked for gsd_run and found nothing, and none of the path-based locations matched either. It stops rather than guessing — falling back to an arbitrary gsd-tools is exactly the behavior that caused #3129.

This is expected in one specific case: an installation old enough to predate the gsd_run binary (#381). Upgrade:

npm install -g @opengsd/gsd-core@latest

Confirm the binary is now present:

command -v gsd_run

If you deliberately pin an old version, invoke workflows from a project or config directory where the path-based resolution branches apply — a local install under gsd-core/bin/gsd-tools.cjs, or your runtime's config directory — rather than relying on PATH.

Tell "not installed" apart from "wrong one installed"

These two look similar and have opposite fixes:

command -v gsd_run   || echo "gsd_run:   NOT FOUND"
command -v gsd-tools || echo "gsd-tools: NOT FOUND"

gsd_run found — workflows resolve correctly, whatever gsd-tools says.
gsd_run missing, gsd-tools present — the likely collision case. Run readlink -f "$(command -v gsd-tools)" and follow the matching section above.
Both missing — nothing is installed globally; workflows will use a local or config-directory install if one exists.

Check the assertion's own verdict

Inside a workflow shell — that is, after the launcher preamble has run — the outcome is a variable, not just a message:

printf '%s\n' "$GSD_IDENTITY_STATUS"

ok — the resolved tool proved it is @opengsd/gsd-core. Nothing to do.
unverified — it did not. Work the two sections above, in that order: rule out a foreign package first, then upgrade an old one.

The warn phase does not stop the workflow. A later release turns unverified into a refusal, so treat it as something to fix now rather than something to live with.

Runtime identity — why the launcher resolves gsd_run, and why it also asserts identity on the branches that resolution alone cannot make safe
runtime-identity — the verb's exact output
#3129 — the incident this prevents

5.7 KiB Raw Blame History

How to diagnose which gsd-tools is running