8442d984b9
* test(#3809): generalize dead-ref guard into a rule table (failing first)
The #2020 guard hardcoded `sdk/(src|dist|handlers)/` — the three dead paths
that had caused that storm. That proved those three paths were gone and said
nothing about the class, so #3809 reproduced the identical Windows find.exe
storm under a different token and the guard could not see it.
Replaces the single regex with a rule table over the same runtime-loaded
markdown surface, adds `commands/` to the scan set (previously uncovered),
and adds rule B: the runtime shim filename must never appear in command
position, because it is not a PATH command and an agent that meets it falls
back to locating the file.
Rule B's matcher is deliberately lenient — the launcher's own resolver
assignment, `node <path>/<shim>` calls, bare paths, and prose that names the
file all stay unflagged, each pinned by a negative-space row.
This commit is expected to FAIL: 50 offenders across 23 files remain in the
tree. The remediation lands next.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3809): route every workflow call through the gsd_run launcher
50 places across 23 runtime-loaded workflow, agent, reference, and command
files instructed the agent to run the runtime shim by filename. That filename
is not on PATH under any name -- package.json ships gsd-core, gsd-tools,
gsd_run and gsd-mcp-server -- so the call exited 127, the file-shaped token
sent the agent looking for the file, and on Git Bash for Windows the resulting
`find /` walked the entire drive (7268 CPU-seconds in the report) until
somebody killed it by hand.
CONTEXT.md -> Runtime Launcher Module already makes gsd_run the single entry
point: "Canonical space-safe shell preamble (`gsd_run`) used by every workflow
bash block to invoke the GSD runtime CLI." These sites predate that rule --
they trace to 0e6907050 (docs(#195): migrate workflow markdown off gsd-sdk
query), which swapped one non-PATH token for another.
Two further instances of the same class surfaced during remediation and are
fixed here rather than left for later:
- references/model-profiles.md prescribed `node <shim> effort sync` with no
path at all; node resolves a bare filename against cwd, so it fails the
same way.
- references/universal-anti-patterns.md rule 25 instructed every agent to
"use <shim>" when shelling out. That rule did not contain the defect, it
prescribed it repo-wide.
Five "(or legacy <shim>)" parentheticals left dangling by the substitution are
removed; after the rewrite they offered the non-resolving form as an
alternative.
The guard from the previous commit now passes. Its node-prefix exemption was
tightened to require a path separator, which is what exposed model-profiles.
Fixes #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3809): key the guard on the CLI's whole verb roster, not observed usage
Review found the first cut of rule B repeating the very mistake it exists to
prevent. Its verb set held query, commit and effort -- the verbs that happened
to appear in the tree -- so it could not see `<shim> phase add`,
`<shim> state load`, `<shim> verify ...` or twenty-odd other real single-word
subcommands. A guard that only recognises yesterday's offenders is not a guard.
The set is now the CLI's full advertised roster, unioned from the usage banner
and HOST_COMMAND_ROUTERS (which carries verification, planning, uat, stats,
todo and windows, all absent from the banner).
Widening it immediately caught a live offender the first pass had missed:
references/planning-config.md prescribed `node <shim> worktree set-baseref`
with no path. Fixed here.
Also drops the "a hyphen or a dot means subcommand" heuristic, which was
unsound for prose -- it flagged `built-in` and `v1.2`. Detection now keys
entirely on the roster, testing the first dot-segment so that phase.add and
state.patch still match while prose does not. Both false positives are pinned
as negative-space rows.
Guard verified against the pre-fix tree at origin/next: 52 offenders across 25
files, and 0 after this branch's remediation.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3809): derive the verb roster from the router; repair launcher parity
Standards review caught the guard repeating the defect it exists to prevent.
Its verb list was a hand-copied literal -- and worse, transcribed from an
INSTALLED older binary, so it was missing 22 verbs this tree actually ships
(websearch, windows, state-snapshot, context-predicates and the dispatch-*
family among them). gsd-tools.cjs already carries three hand-maintained
rosters whose drift is a named defect pinned by the parity test in
tests/commands.test.cjs; a hand-copied fourth was that same defect wearing a
guard's clothes.
The roster is now derived from HOST_COMMAND_ROUTERS + TOP_LEVEL_USAGE, lazily
and memoised, with `query` supplemented explicitly -- it dispatches through
the routing hub ahead of the host-router table, so it appears in neither
export, yet 45 of the 50 offenders used it. A parity test pins the derivation.
Two regressions this branch introduced, both caught by the remote runner:
- runtime-launcher-parity: rewriting a comment in gsd-research-synthesizer.md
put a `gsd_run` token at line 65 while the canonical preamble sits at 158,
breaking "exactly ONE preamble, before the first gsd_run call". The comment
is descriptive and needs no command token at all; it now names none.
- The #2751 guard's PROSE_ALLOWLIST entry for that same line went stale once
the line stopped carrying a bare mention. Pruned, exactly as that guard's
own stale-entry test instructs.
Also corrects git-planning-commit.md, where the first pass rewrote only the
trailing "legacy" clause and left the sentence reading backwards.
Note the #2751 guard and this one are complementary, not duplicates: its regex
requires whitespace immediately after `gsd-tools`, so it cannot match the
`.cjs` form, and this one only matches the `.cjs` form.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#2751): extend the bare-command guard to references/ and commands/
The #2751 guard has only ever scanned agents/ and gsd-core/workflows/. Two
runtime-loaded directories were never in its scan set, and 47 bare
`gsd-tools <verb>` calls had accumulated there unseen -- the same defect that
guard exists to catch, in the rooms it never entered.
- gsd-core/references/: 37 calls, all rewritten to gsd_run. references are
fragments inlined into a parent that defines the launcher, which is why 21
of the 22 files already using gsd_run carry no local preamble.
- commands/gsd/: 10 operative calls rewritten. The remaining 10 are
descriptive prose ("resolved inside the workflow via ...") and are
allowlisted with reasons, bringing PROSE_ALLOWLIST to 15.
commands/ also came under launcher propagation. sync-runtime-launcher.cjs
walked only WORKFLOWS_DIR and AGENTS_DIR, so every preamble under commands/
was a hand-pasted copy nothing propagated and no test checked -- graphify.md
had accumulated five. It now walks COMMANDS_DIR too, which collapses those
five to the canonical one-per-file, and runtime-launcher-parity gains a
(B-commands) arm mirroring (B-agents) exactly so the placement stays honest.
The parity arm keys on shell blocks, so commands/gsd/workstreams.md and
config.md -- which name gsd_run only in inline backtick prose -- are exempt,
as they should be. gsd_run is itself a shipped npm bin, so those inline
instructions resolve from PATH exactly as the gsd-tools form they replace did.
skills/ is deliberately NOT added to either guard's scan set: it is generated
from commands/ and pinned by lint:generated-sync, so guarding the source
guards both, and scanning the mirror would double-report every future
offender. Regenerated here.
Refs #2751, #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test(#3809): acknowledge the one emitted file this change grows
The emitted-attribution gate failed on the previous sha: gsd-research-synthesizer.md
grew 3 bytes (13847 -> 13850) with no acknowledgment. The substitution SHRANK the
other 19 emitted files, which is why the growth arm was not expected to fire at all.
The 3 bytes are unavoidable. Line 65 is a descriptive comment inside a fenced block;
naming any command there puts a gsd_run token ahead of the file's canonical preamble
at line 158, which runtime-launcher-parity's (B-agents) arm correctly rejects. So the
comment names no command and says where the config is actually loaded instead, which
reads longer than the token it replaced.
Acks only the path the gate reported, per the fragment rules.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* revert(#2751): drop the commands/ half — three contracts pin it in place
The remote runner refuted the commands/ extension outright. Reverting it and
keeping the references/ conversion, which passed.
What broke, all of it caused by bringing commands/ under launcher propagation:
- graphify.md's five per-block preambles are LOAD-BEARING, not accumulated
drift. tests/graphify-visualization.test.cjs extracts individual Step-3
shell chains and executes them standalone, so each fenced block needs its
own definition of gsd_run. Collapsing them to the canonical one-per-file
produced `bash: gsd_run: command not found`, exit 127, across four tests.
The "define once per file" contract holds for workflows and agents because
nothing extracts their blocks in isolation; commands/ is not like that.
- explore.md broke "the preamble that DEFINES gsd_run must appear before the
first USE of gsd_run anywhere in the file".
- tests/gsd-tools-path-refs.test.cjs (#1766) ASSERTS that
commands/gsd/workstreams.md contains the literal string
`gsd-tools query workstream.list`. Rewriting it to gsd_run contradicts a
test that pins the opposite, so the two guards disagree about that file by
construction.
So commands/ is not a scan-set widening. It needs those contracts reconciled
first, and that is its own change. SCAN_DIRS keeps gsd-core/references/ and
drops commands/, the ten commands/ allowlist entries go with it (back to 5),
and the reasoning is recorded in the guard itself so the next person does not
rediscover it by burning a matrix run.
commands/gsd/import.md keeps its #3809 fix — that one is the .cjs form this
PR exists to remove, and it is untouched by any of the above.
Refs #2751, #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* revert(#3809): restore explore.md's Step 1 preamble placement
Running the launcher sync script processed workflows/ and agents/ too, not
just the commands/ directory the run was aimed at, and it MOVED
gsd-core/workflows/explore.md's preamble from Step 1 down to Step 3.
The script inserts into the first bash block that USES gsd_run. explore.md's
Step 1 block only DEFINES it, and that placement is deliberate -- the file
says so on the line above: "Placed in Step 1 rather than Step 3 so declining
the research offer cannot leave Step 5's commit call unbootstrapped."
tests/explore-command.test.cjs pins it.
explore.md carried no #3809 offender, so reverting it costs this fix nothing.
This was collateral from invoking the sync script at all, not from the
COMMANDS_DIR change, which is why the earlier commands/ revert did not catch it.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore(#3809): backfill PR number into changeset fragments
pr:0 -> pr:3815 for both fragments now that the PR exists.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(#3809): drop the hand-rolled regex escaper CodeQL flagged
CodeQL raised js/incomplete-sanitization (HIGH) on the guard's pattern build:
`SHIM.replace(/\./g, '\\.')` escapes the dot and nothing else, so it does not
escape backslashes. It blocked PR #3815.
The repo already bans this shape -- local/no-adhoc-regex-escape exists exactly
to stop hand-rolled escapers, with the canonical one in src/pattern.cts. Rather
than reach for that helper, the pattern now carries no escaping logic at all:
SHIM is a compile-time constant whose only metacharacter is the dot, so the
regex source is spelled out literally. The generated source string is
byte-identical to what the replace() produced, verified before and after --
0 offenders on this tree, 52 against origin/next, unchanged.
A drift pin asserts SHIM_PATTERN still matches SHIM exactly, and that the dot
is escaped rather than acting as a wildcard, so the two cannot separate.
Refs #3809
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# Runtime-Aware Subagent Dispatch (epic #2505 Phase 4 / #2508)
|
|
|
|
GSD workflows dispatch specialized subagents by role (planner, executor,
|
|
verifier, …). On **named-dispatch runtimes** (Claude Code, OpenCode, Cursor,
|
|
Cline, … — every runtime whose descriptor declares `hostIntegration.dispatch.namedDispatch: true`), the role name dispatches the named subagent directly.
|
|
|
|
On **built-in-only runtimes** (kimi-code — three built-in subagents only:
|
|
`coder`, `explore`, `plan`; no custom registration per
|
|
`moonshotai.github.io/kimi-code/en/customization/agents`), a GSD role name is
|
|
unknown and the dispatch must use the closest built-in.
|
|
|
|
## Resolution
|
|
|
|
Before dispatching a subagent by role, resolve the type for the current runtime
|
|
via the `resolve-dispatch-type` query. Pass the requested role name; the query
|
|
returns the name unchanged on named-dispatch runtimes and maps to the closest
|
|
built-in (`coder`/`explore`/`plan`) on kimi-code. The `|| echo` fallback
|
|
preserves named-dispatch behavior on older GSD installs that lack the query.
|
|
|
|
The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3 / #2510) regardless of the
|
|
resolved type — on non-Claude runtimes with no `agent_skills` config,
|
|
`gsd_run query agent-skills <role>` returns the installed agent prompt as
|
|
the block. So a coder dispatch with the planner persona injected gives kimi-code
|
|
the planner's behavior in the coder built-in's process.
|
|
|
|
## Suffix → built-in map
|
|
|
|
| Agent role suffix | Built-in | Rationale |
|
|
|---|---|---|
|
|
| `-planner`, `-roadmapper`, `-selector`, `-spec` | `plan` | Plans/designs; no file writes |
|
|
| `-researcher`, `-mapper`, `-checker`, `-verifier`, `-auditor`, `-analyzer`, `-synthesizer`, `-profiler`, `-curator`, `-classifier`, `-reviewer` | `explore` | Read-only investigation |
|
|
| everything else (`-executor`, `-fixer`, `-writer`, `-debugger`, …) | `coder` | General-purpose with full tool set |
|
|
| `general-purpose`, `general`, `default`, `sonnet`, `opus`, `haiku` | `coder` | Already-generic names |
|
|
|
|
## Why not a hook?
|
|
|
|
Kimi Code's documented PreToolUse hook API
|
|
(`moonshotai.github.io/kimi-code/en/customization/hooks`) supports only
|
|
`permissionDecision: allow|deny` on blockable events — it cannot rewrite the
|
|
dispatch payload's role field in flight. A PreToolUse-remap hook (the epic's
|
|
original "Option B") is therefore infeasible; this per-dispatch resolution
|
|
(Option A) is the documented-API-correct path.
|