fix(#3809): route runtime-loaded markdown through the gsd_run launcher (#3815)

* 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>
This commit is contained in:
Tom Boucher
2026-08-24 11:47:37 -04:00
committed by GitHub
parent 8ed105c8a4
commit 8442d984b9
40 changed files with 416 additions and 116 deletions

View File

@@ -43,7 +43,7 @@ Exit.
</step>
<step name="add_phase">
**Delegate the phase addition to `gsd-tools.cjs query phase.add`:**
**Delegate the phase addition to `gsd_run query phase.add`:**
```bash
RESULT=$(gsd_run query phase.add "${description}")
@@ -107,7 +107,7 @@ Roadmap updated: .planning/ROADMAP.md
</process>
<success_criteria>
- [ ] `gsd-tools.cjs query phase.add` executed successfully
- [ ] `gsd_run query phase.add` executed successfully
- [ ] Phase directory created
- [ ] Roadmap updated with new phase entry
- [ ] STATE.md updated with roadmap evolution note

View File

@@ -61,7 +61,7 @@ These items are open. Choose an action:
```
If user chooses [A] (Acknowledge):
1. Re-run `gsd-tools.cjs query audit-open --json` to get structured data.
1. Re-run `gsd_run query audit-open --json` to get structured data.
2. Acknowledge every open item through the `audit-open acknowledge` CLI writer — this is what actually suppresses each item starting at the NEXT `audit-open` scan; the STATE.md table in step 3 is a disclosure record only, it is no longer the suppression mechanism. Every acknowledge call's exit status is accumulated (`ACK_FAILURES`); the step HALTS before closing if any failed — a refusal (`unsupported_heading_shape`, `ambiguous`, `not_found`, missing file, etc.) must never be silently discarded and let the close proceed as if everything were suppressed. `AUDIT_JSON` uses the same `@file:` large-payload sentinel handling `INIT_MANAGER` uses in `verify_readiness` below — `io.output` swaps any JSON payload over 50000 chars for a `@file:<path>` marker, and feeding that literal string to `jq` would silently make every loop body below iterate zero times:
```bash
AUDIT_JSON=$(gsd_run query audit-open --json)
@@ -162,8 +162,8 @@ If user chooses [A] (Acknowledge):
exit 1
fi
```
`todos` is the only category the scanner caps (5 entries per scan, with a remainder count for the rest). Re-run `gsd-tools.cjs query audit-open --json` (through the same `@file:` handling above) and repeat the `todos` block until it reports no `todos` items — every other category always returns its full open set in one pass.
3. Re-run `gsd-tools.cjs query audit-open --json` once more and write the items just acknowledged as new rows to STATE.md under `## Deferred Items` — append to the existing table (creating the section if absent) rather than overwriting it, preserving rows recorded at earlier milestone closes:
`todos` is the only category the scanner caps (5 entries per scan, with a remainder count for the rest). Re-run `gsd_run query audit-open --json` (through the same `@file:` handling above) and repeat the `todos` block until it reports no `todos` items — every other category always returns its full open set in one pass.
3. Re-run `gsd_run query audit-open --json` once more and write the items just acknowledged as new rows to STATE.md under `## Deferred Items` — append to the existing table (creating the section if absent) rather than overwriting it, preserving rows recorded at earlier milestone closes:
```markdown
## Deferred Items
@@ -189,7 +189,7 @@ Acknowledging is verdict-preserving and self-invalidating: it never rewrites the
If output shows all clear (no open items): set `closeout_type=verified_closeout`. If the audit JSON's `acknowledged.total` is `0`, print `All artifact types clear.` and proceed. Otherwise the close is clean only because `{acknowledged.total}` item(s) acknowledged at an earlier milestone close are still being suppressed, not because everything was fixed this time — print `All artifact types clear ({acknowledged.total} previously acknowledged item(s) still suppressed — see STATE.md Deferred Items).` and record `Known verification overrides: 0 newly acknowledged, {acknowledged.total} carried forward from a prior close (see STATE.md Deferred Items)` in the MILESTONES.md entry before proceeding.
SECURITY: Audit JSON output is structured data from the `audit-open` query handler (same JSON contract as legacy `gsd-tools.cjs audit-open`) — validated and sanitized at source. The `audit-open acknowledge` writer is the only path that sets the `audit_acknowledged` suppression marker — it snapshots each artifact's current state itself from the identifiers passed on the command line, so this workflow never hand-authors the marker. When writing the STATE.md disclosure table, item identifiers, statuses, and deferred-item text are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
SECURITY: Audit JSON output is structured data from the `audit-open` query handler (same JSON contract as legacy `gsd_run audit-open`) — validated and sanitized at source. The `audit-open acknowledge` writer is the only path that sets the `audit_acknowledged` suppression marker — it snapshots each artifact's current state itself from the identifiers passed on the command line, so this workflow never hand-authors the marker. When writing the STATE.md disclosure table, item identifiers, statuses, and deferred-item text are sanitized via `sanitizeForDisplay()` before inclusion. Never inject raw user-supplied content into STATE.md without sanitization.
</step>
<step name="verify_readiness">
@@ -353,7 +353,7 @@ Key accomplishments for this milestone:
<step name="create_milestone_entry">
**Note:** MILESTONES.md entry is now created automatically by `gsd-tools.cjs query milestone.complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
**Note:** MILESTONES.md entry is now created automatically by `gsd_run query milestone.complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
If additional details are needed (e.g., user-provided "Delivered" summary, git range, LOC stats), add them manually after the CLI creates the base entry.
@@ -517,7 +517,7 @@ AskUserQuestion: "Archive completed quick tasks into this milestone too?" with o
If "Yes": set `ARCHIVE_QUICK_FLAG="--archive-quick"`. If "Skip" (or `.planning/quick/` is empty): set `ARCHIVE_QUICK_FLAG=""`.
**Delegate archival to `gsd-tools.cjs query milestone.complete`:**
**Delegate archival to `gsd_run query milestone.complete`:**
```bash
ARCHIVE=$(gsd_run query milestone.complete "v[X.Y]" --name "[Milestone Name]" $ARCHIVE_QUICK_FLAG)

View File

@@ -18,7 +18,7 @@ Claude App cannot forward TUI menu selections back to the host.
- Per-session: pass `--text` flag to any command (e.g.,
`/gsd:discuss-phase --text`)
- Per-project: `gsd-tools.cjs query config-set workflow.text_mode true`
- Per-project: `gsd_run query config-set workflow.text_mode true`
Text mode applies to ALL workflows in the session, not just discuss-phase.

View File

@@ -431,7 +431,7 @@ CROSS_AI_TIMEOUT=$(gsd_run query config-get workflow.cross_ai_timeout 2>/dev/nul
**If no plans are marked for cross-AI:** Skip to execute_waves.
**If plans are marked but `cross_ai_command` is empty:** Error — tell user to set
`workflow.cross_ai_command` via `gsd-tools.cjs query config-set workflow.cross_ai_command "<command>"`.
`workflow.cross_ai_command` via `gsd_run query config-set workflow.cross_ai_command "<command>"`.
**For each cross-AI plan (sequentially):**
@@ -1530,7 +1530,7 @@ For 1M+ context models, consider:
</context_efficiency>
<failure_handling>
- **Quota / rate-limit (any runtime — #3095):** Agent return body contains a sentinel like `usage limit`, `rate limit`, `429`, `too many requests`, `RESOURCE_EXHAUSTED`, `usage_limit_reached`. Route via `gsd-tools.cjs query agent.classify-failure` → `class: "quota-exceeded"`. Do not offer retry-now; the right action is wait-for-reset and resume.
- **Quota / rate-limit (any runtime — #3095):** Agent return body contains a sentinel like `usage limit`, `rate limit`, `429`, `too many requests`, `RESOURCE_EXHAUSTED`, `usage_limit_reached`. Route via `gsd_run query agent.classify-failure` → `class: "quota-exceeded"`. Do not offer retry-now; the right action is wait-for-reset and resume.
- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not GSD. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip

View File

@@ -68,7 +68,7 @@ Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix
```bash
PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
# config settings can be fetched via gsd-tools.cjs query config-get if needed
# config settings can be fetched via gsd_run query config-get if needed
```
<if mode="yolo">
@@ -428,7 +428,7 @@ Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready f
handles STATE.md/ROADMAP.md updates centrally after merging worktrees to avoid
merge conflicts).
Update STATE.md using gsd-tools.cjs query (or legacy gsd-tools) state mutations:
Update STATE.md using gsd_run query (or legacy gsd-tools) state mutations:
```bash
# Auto-detect parallel mode: .git is a file in worktrees, a directory in main repo
@@ -465,7 +465,7 @@ gsd_run query state.add-blocker --text-file "${BLOCKER_TEXT_FILE}"
</step>
<step name="update_session_continuity">
Update session info using gsd-tools.cjs query (or legacy gsd-tools):
Update session info using gsd_run query (or legacy gsd-tools):
```bash
gsd_run query state.record-session \

View File

@@ -47,7 +47,7 @@ Exit.
</step>
<step name="insert_phase">
**Delegate the phase insertion to `gsd-tools.cjs query phase.insert`:**
**Delegate the phase insertion to `gsd_run query phase.insert`:**
```bash
RESULT=$(gsd_run query phase.insert "${after_phase}" "${description}")
@@ -143,10 +143,10 @@ Project state updated: .planning/STATE.md
<success_criteria>
Phase insertion is complete when:
- [ ] `gsd-tools.cjs query phase.insert` executed successfully
- [ ] `gsd_run query phase.insert` executed successfully
- [ ] Phase directory created
- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
- [ ] `gsd-tools.cjs query state.add-roadmap-evolution ...` returned `{ added: true }` or `{ added: false, reason: "duplicate" }`
- [ ] `gsd-tools.cjs query state.patch` returned matched next-phase pointer field(s)
- [ ] `gsd_run query state.add-roadmap-evolution ...` returned `{ added: true }` or `{ added: false, reason: "duplicate" }`
- [ ] `gsd_run query state.patch` returned matched next-phase pointer field(s)
- [ ] User informed of next steps and dependency implications
</success_criteria>

View File

@@ -33,7 +33,7 @@ Parse JSON for: `milestone_version`, `milestone_name`, `phase_count`, `completed
- `manager_flags.plan` — appended to plan agent init command
- `manager_flags.execute` — appended to execute agent init command
These are empty strings by default. Set via: `gsd-tools.cjs query config-set manager.flags.discuss "--auto --analyze"`
These are empty strings by default. Set via: `gsd_run query config-set manager.flags.discuss "--auto --analyze"`
**If error:** Display the error message and exit.

View File

@@ -602,7 +602,7 @@ VALIDATION_EXISTS=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
If missing and Nyquist is still enabled/applicable — ask user:
1. Re-run: `/gsd:plan-phase {PHASE} --research ${GSD_WS}`
2. Disable Nyquist with the exact command:
`gsd-tools.cjs query config-set workflow.nyquist_validation false`
`gsd_run query config-set workflow.nyquist_validation false`
3. Continue anyway (plans fail Dimension 8)
Proceed to Step 7.8 (or Step 8 if pattern mapper is disabled) only if user selects 2 or 3.

View File

@@ -9,7 +9,7 @@
3. Status gate: reject `superseded`/`rejected`/`deprecated`; warn on `proposed`; missing status defaults to `accepted`.
4. Empty-decisions fallback: if all parsed ADRs have zero `decisions[]`, emit `ADR ingest produced no locked decisions; fall back to discuss-phase for this phase.` and exit with `/gsd:discuss-phase {N}` guidance.
5. Generate CONTEXT.md using `<domain>`, `<decisions>`, `<canonical_refs>`, `<specifics>`, `<deferred>`, `<scope_fence>`, map `consequences_positive[]` to Success Criteria and `consequences_negative[]` to Risk Summary, and include `**Source:** ADR Ingest Express Path ({INGEST_PATH})`.
6. Commit with `gsd-tools.cjs query commit "docs(${padded_phase}): generate context from ADR ingest" --files "${phase_dir}/${padded_phase}-CONTEXT.md"` and set `context_content`; continue to step 5.
6. Commit with `gsd_run query commit "docs(${padded_phase}): generate context from ADR ingest" --files "${phase_dir}/${padded_phase}-CONTEXT.md"` and set `context_content`; continue to step 5.
**Effect:** This bypasses step 4 (Load CONTEXT.md) since CONTEXT.md was synthesized from ADR input.

View File

@@ -1,7 +1,7 @@
<purpose>
Orchestrate the full developer profiling flow: consent, session analysis (or questionnaire fallback), profile generation, result display, and artifact creation.
This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing `gsd-tools.cjs query` handlers (with legacy `gsd-tools.cjs` parity where needed) and the gsd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX.
This workflow wires Phase 1 (session pipeline) and Phase 2 (profiling engine) into a cohesive user-facing experience. All heavy lifting is done by existing `gsd_run query` handlers and the gsd-user-profiler agent -- this workflow orchestrates the sequence, handles branching, and provides the UX.
</purpose>
<required_reading>
@@ -386,7 +386,7 @@ gsd_run query generate-claude-profile --analysis "$ANALYSIS_PATH" --global --jso
Display: "✓ Added profile section to $HOME/.claude/CLAUDE.md"
**Error handling:** If any `gsd-tools.cjs query` or gsd-tools.cjs call fails, display the error message and use AskUserQuestion to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact.
**Error handling:** If any `gsd_run query` call fails, display the error message and use AskUserQuestion to offer "Retry" or "Skip this artifact". On retry, re-run the command. On skip, continue to next artifact.
---
@@ -461,7 +461,7 @@ rm -f "$ANALYSIS_PATH" 2>/dev/null
- [ ] Profile written to USER-PROFILE.md via write-profile subcommand
- [ ] Result display shows report card table and highlight reel with evidence
- [ ] Artifact selection uses multiSelect with all options pre-selected
- [ ] Artifacts generated sequentially via gsd-tools.cjs query (or gsd-tools.cjs) subcommands
- [ ] Artifacts generated sequentially via `gsd_run query` subcommands
- [ ] Refresh diff shows changed dimensions when --refresh was used
- [ ] Temp files cleaned up on completion
</success_criteria>

View File

@@ -44,11 +44,11 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/gsd:new-project`.
</step>
<step name="load">
**Use structured extraction from `gsd-tools.cjs query` (or legacy gsd-tools.cjs):**
**Use structured extraction from `gsd_run query`:**
Instead of reading full files, use targeted tools to get only the data needed for the report:
- `ROADMAP=$(gsd-tools.cjs query roadmap.analyze)`
- `STATE=$(gsd-tools.cjs query state-snapshot)`
- `ROADMAP=$(gsd_run query roadmap.analyze)`
- `STATE=$(gsd_run query state-snapshot)`
This minimizes orchestrator context usage.
</step>
@@ -96,7 +96,7 @@ Use this instead of manually reading/parsing ROADMAP.md.
> blocks are a secondary config aid that may be significantly stale — do NOT use the
> CLAUDE.md project description as a source for any progress report field.
**Generate progress bar from `gsd-tools.cjs query progress` / `progress.json`, then present rich status report:**
**Generate progress bar from `gsd_run query progress` / `progress.json`, then present rich status report:**
```bash
# Get formatted progress bar

View File

@@ -647,7 +647,7 @@ Use Edit tool to make these changes atomically
**Step 8: Final commit and completion**
Stage and commit quick task artifacts. This step MUST always run — even if the executor already committed some files (e.g. when running without worktree isolation). The `gsd-tools.cjs query commit` command (or legacy `gsd-tools.cjs` commit) handles already-committed files gracefully.
Stage and commit quick task artifacts. This step MUST always run — even if the executor already committed some files (e.g. when running without worktree isolation). The `gsd_run query commit` command handles already-committed files gracefully.
Build file list:
- `${QUICK_DIR}/${quick_id}-PLAN.md`

View File

@@ -78,7 +78,7 @@ Wait for confirmation.
</step>
<step name="execute_removal">
**Delegate the entire removal operation to `gsd-tools.cjs query phase.remove`:**
**Delegate the entire removal operation to `gsd_run query phase.remove`:**
```bash
RESULT=$(gsd_run query phase.remove "${target}")
@@ -141,7 +141,7 @@ Would you like to:
- Don't remove completed phases (have SUMMARY.md files) without --force
- Don't remove current or past phases
- Don't manually renumber — use `gsd-tools.cjs query phase.remove` which handles all renumbering
- Don't manually renumber — use `gsd_run query phase.remove` which handles all renumbering
- Don't add "removed phase" notes to STATE.md — git commit is the record
- Don't modify completed phase directories
</anti_patterns>
@@ -150,7 +150,7 @@ Would you like to:
Phase removal is complete when:
- [ ] Target phase validated as future/unstarted
- [ ] `gsd-tools.cjs query phase.remove` executed successfully
- [ ] `gsd_run query phase.remove` executed successfully
- [ ] Changes committed with descriptive message
- [ ] User informed of changes
</success_criteria>

View File

@@ -434,7 +434,7 @@ AskUserQuestion([
If "Other (Group B or custom)" is selected, prompt the user to enter the runtime name as a free-text string.
If the selected runtime differs from the stored `runtime` key, update `runtime` via
`gsd-tools.cjs query config-set runtime <value>` before proceeding to Step C.
`gsd_run query config-set runtime <value>` before proceeding to Step C.
**Step C — Configure tier overrides for the selected runtime:**
@@ -494,7 +494,7 @@ change.
Merge the new settings into the existing config at `$GSD_CONFIG_PATH`. This merge is the
core correctness invariant: **preserve every unrelated key** — do not clobber siblings.
Apply each selected value via `gsd-tools.cjs query config-set <key> <value>` so the central
Apply each selected value via `gsd_run query config-set <key> <value>` so the central
validator (`isValidConfigKey`) accepts the write and the deep-merge preserves unrelated
keys and sibling sub-objects.
@@ -567,7 +567,7 @@ anything not listed in Sections 1–8 MUST survive the update):
```
Never emit a full overwrite of the file that omits keys the user did not touch. Always
route each write through `gsd-tools.cjs query config-set` so sibling preservation is handled by
route each write through `gsd_run query config-set` so sibling preservation is handled by
the central setter.
</step>
@@ -807,7 +807,7 @@ UI/AI phase gates), use /gsd:settings.
- [ ] Numeric inputs validated — non-numeric rejected and re-prompted
- [ ] Branch-template inputs validated — non-default must contain a placeholder
- [ ] Null-allowed fields accept an empty input as a clear
- [ ] Writes routed through `gsd-tools.cjs query config-set` so unrelated keys are preserved
- [ ] Writes routed through `gsd_run query config-set` so unrelated keys are preserved
- [ ] Section 7 shows current runtime and built-in tier table
- [ ] Group B runtimes display "(no built-in default — your runtime handles model selection)"
- [ ] Override set/clear/keep paths all work correctly for each tier

View File

@@ -53,7 +53,7 @@ If no `.planning/` directory exists, inform the user to run `/gsd:new-project` f
</step>
<step name="mvp_summary">
**MVP phase summary.** Read all phases via `gsd-tools.cjs query roadmap.analyze` (Phase 1's `cmdRoadmapAnalyze` surfaces a `mode` field per phase). Count phases by mode:
**MVP phase summary.** Read all phases via `gsd_run query roadmap.analyze` (Phase 1's `cmdRoadmapAnalyze` surfaces a `mode` field per phase). Count phases by mode:
```bash
ANALYZE=$(gsd_run query roadmap.analyze)

View File

@@ -221,6 +221,6 @@ updated: {today ISO date}
- Slugs from $ARGUMENTS are sanitized before use in file paths: only [a-z0-9-] allowed, max 60 chars, reject ".." and "/"
- File names from readdir/ls are sanitized before display: strip non-printable chars and ANSI sequences
- Artifact content (thread titles, goal sections, next steps) rendered as plain text only — never executed or passed to agent prompts without DATA_START/DATA_END boundaries
- Status fields read via gsd-tools.cjs query frontmatter.get — never eval'd or shell-expanded
- The generate-slug call for new threads runs through gsd-tools.cjs query (or gsd-tools) which sanitizes input — keep that pattern
- Status fields read via gsd_run query frontmatter.get — never eval'd or shell-expanded
- The generate-slug call for new threads runs through gsd_run query (or gsd-tools) which sanitizes input — keep that pattern
</security_notes>

View File

@@ -131,7 +131,7 @@ Resolve before transition. Review: `/gsd:audit-uat`
```
This preliminary check blocks obviously unresolved verification early, ahead
of the authoritative gate below. `gsd-tools.cjs query phase.complete` (in
of the authoritative gate below. `gsd_run query phase.complete` (in
`update_roadmap_and_state`) remains the authoritative stale-aware gate and
fail-closes unless canonical verification status is `passed`.
@@ -197,7 +197,7 @@ If found, delete them — phase is complete, handoffs are stale.
<step name="update_roadmap_and_state">
**Delegate ROADMAP.md and STATE.md updates to `gsd-tools.cjs query phase.complete`:**
**Delegate ROADMAP.md and STATE.md updates to `gsd_run query phase.complete`:**
```bash
TRANSITION=$(gsd_run query phase.complete "${current_phase}")
@@ -333,7 +333,7 @@ This step is fully delegated to `graduation.md`. It handles guard checks (featur
<step name="update_current_position_after_transition">
**Note:** Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by `gsd-tools.cjs query phase.complete` in the update_roadmap_and_state step.
**Note:** Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by `gsd_run query phase.complete` in the update_roadmap_and_state step.
Verify the updates are correct by reading STATE.md. If the progress bar needs updating, use:
@@ -437,7 +437,7 @@ Resume file: None
**MANDATORY: Verify milestone status before presenting next steps.**
**Use the transition result from `gsd-tools.cjs query phase.complete`:**
**Use the transition result from `gsd_run query phase.complete`:**
The `is_last_phase` field from the phase complete result tells you directly:
- `is_last_phase: false` → More phases remain → Go to **Route A**

View File

@@ -296,8 +296,8 @@ installer does not know about and will delete during the wipe.
**Do not use bash path-stripping (`${filepath#$RUNTIME_DIR/}`) or `node -e require()`
inline** — those patterns fail when `$RUNTIME_DIR` is unset and the stripped
relative path may not match manifest key format, which causes CUSTOM_COUNT=0
even when custom files exist (bug #1997). Use `gsd-tools.cjs query detect-custom-files`
or the bundled `gsd-tools.cjs detect-custom-files` path — both resolve paths
even when custom files exist (bug #1997). Use `gsd_run query detect-custom-files`
or the bundled `gsd_run detect-custom-files` path — both resolve paths
reliably with Node.js `path.relative()`.
First, resolve the config directory (`RUNTIME_DIR`) from the install scope

View File

@@ -635,7 +635,7 @@ All tests passed. Phase {phase} marked complete.
<step name="scan_phase_artifacts">
Run phase artifact scan to surface any open items before marking phase verified:
`audit-open` is CJS-only until registered on `gsd-tools.cjs query`:
`audit-open` is CJS-only until registered on `gsd_run query`:
```bash
gsd_run query audit-open --json