epic #250: Rewrite every component invocation to name a toolkit, behind a build-time gate

[sameera]

Implements the story sub-issues of #250, one commit per story in blocked_by order.

Each commit body carries its own Closes #<story> line, so merging this PR
into main closes the stories it implements. The epic itself closes through
/nxs.close, not by merge.

Draft opened by utils/implement-epic.sh; /nxs.analyze runs against it next.

[sameera]

Conformance: Rewrite every component invocation to name a toolkit, behind a build-time gate (.nexus/tmp/epic-250)  ·  epic #250
Mode: full (record #325 @ b4c02eedcdc8089d7943145214dd9abc80feb6e2ff52a77245b4b4ed1b4fec2a)
Surface: 41 files changed, 4 stories (0 closed / 4 open — each closed by this PR's merge, per commit `Closes #<story>`)

Per-story AC conformance:
  STORY #301 The build fails when a component names a verb or capability that does not exist: 6/6 met · 0 partial · 0 unmet · 0 contradicted
  STORY #302 The TypeScript invocation sites name the executable: 4/4 met · 0 partial · 0 unmet · 0 contradicted
  STORY #303 The Python invocation sites name the Python toolkit: 5/5 met · 0 partial · 0 unmet · 0 contradicted
  STORY #304 One invocation replaces the duplicated stage prose: 3/3 met · 0 partial · 0 unmet · 0 contradicted

Invariant violations:   none
  1  gate walks `listComponentFiles(liveClaudeDir(SRC_DIR))` — the same set the composition boundary walks — ok
  2  `readToolkitSurfaces` reads `DISPATCH_NAMES` (derived from `REGISTRY`) + `nexus-gh --capabilities`; throws rather than assuming — ok
  3  gate execs only `python3 <repo>/libs/gh-toolkit/bin/nexus-gh --capabilities`, never a string from a body — ok
  4  no shipped body carries a script path, bundle path, `pnpm nexus:` alias or bare `python` (grep over `.claude/**/*.md`: 0 hits) — ok
  5  no interpolation into an executable or dispatch name; every value stays a discrete quoted argument — ok
  6  register emptied and removed; `COMPONENT_COMPOSITION_WAIVERS` is `[]`, `pending` parameter dropped — ok
  7  verb behaviour/exit codes preserved; the subverb guards reuse the existing messages and code 2. `nexus-gh --capabilities` is a new flag, but it is the record's own "dedicated machine-readable capability listing" decision, scoped to #301 — sanctioned, not a violation
  8  from-source path is one shape (`tsx libs/portable-tools/src/nexus-cli.ts <verb>`), documented only in docs/features/component-distribution/README.md, absent from every shipped body — ok
  9  `formatInvocationProblems` names body, line and offending name; parity self-test asserts both appear — ok
  10 distill Phase 5.3 collapse preserves every mode-conditional instruction (hub anchor sidecars, quoted-token discipline, member stop, stale-toolkit escalation) — ok
  11 no `python` at all in shipped bodies; Python capabilities reached as `nexus-gh <capability>` — ok
  12 `nexus` / `nexus-gh` used as single fixed literals throughout — ok

Success metrics:
  No shipped body holds a repo-relative script/executable path  →  measurable (parity gate), met
  Every invocation resolves to a declared name                  →  measurable (parity gate), met
  A migrated body cannot regress                                →  measurable, met — enforcement is unconditional since the register was removed
  Build fails naming the offending body and verb                →  measurable, met — the doctored-surface self-test in parity.spec.ts proves the axis rather than assuming it
  No component invokes a bare `python`                          →  measurable, met

Scope drift:
  - `libs/pr-acceptance` and two portable-tools specs were repointed off the deleted skill scripts onto the from-source shape / the Python entry-point file. Neither is a shipped body, so invariants 4 and 8 do not reach them; this preserves coverage that would otherwise have been deleted with the scripts.
  - `parity.spec.ts` loses ~340 lines: the #272/#273 script-vs-verb and #274 verb-vs-standalone migration axes, all of which lost their second artifact when the scripts and standalone launchers were deleted. Retirement was recorded in the axes' own comments; the durable source-vs-bundle axis survives.
  - Deleting the seven legacy skill scripts (recorded as an in-flight scope growth on #302) closes the composition-waiver register, whose completion condition named this epic.

Findings:
  low  docs/features/README.md:30-31 still instructs the reader to run `python ./.claude/skills/nxs-gh-shared/delivery_config.py backlog-query --form …`. The path does not exist and the interpreter is bare `python` — precisely the two shapes this epic removes. It is a doc, not a shipped body, so no AC, metric or invariant covers it; the named form is `nexus-gh config backlog-query --form …`, already written that way at .claude/commands/nxs.epic.md:469.
  low  Record #325 decides "the gate prints its inventory"; the implementation builds the inventory and asserts over it but never emits it. #301 AC5 ("when its inventory is read") is satisfied by the assertion, and the record's non-printing half — no committed artifact — holds. Nothing surfaces the classified inventory to a maintainer who is not reading a failure.
  note docs/features/pr-driven-delivery/live-acceptance-record.md:248 cites `.claude/skills/nxs-pr-worktree/scripts/pr_worktree.ts:127`, deleted here. It is a historical record, so a stale cite is expected rather than wrong.
  note Both toolkit names must be on the caller's path for any rewritten stage to run. #252 landed on `main` and is merged into this branch at 4aa418c, so the epic's declared blocker is satisfied at the repository level; an existing checkout still needs the install step before `/nxs.*` resolves. The epic puts this out of scope by assumption, and the permission-allowlist entries the new shapes need remain #253's.

Severity: ⛔ critical 0 · ⚠️ high 0 · medium 0 · low 2

Every acceptance criterion across the four stories is met, no decision-record invariant is broken, and all five success metrics are both moved and measurable through the parity gate. The two low findings are documentation-adjacent and outside every AC; neither blocks close.

epic: "#250"
nexus_version: 0.1.0
pr: 328
date: 2026-08-27
head: 4aa418c6dc39163345ace569582fa581480f3e16
mode: full
record: "#325"
record_hash: b4c02eedcdc8089d7943145214dd9abc80feb6e2ff52a77245b4b4ed1b4fec2a
findings: { critical: 0, high: 0, medium: 0, low: 2 }