* feat(#2401): ground <automated> verify-command paths and inherit prior-phase commands Adds a deterministic resolvability probe over each PLAN.md <automated> verify command and surfaces the nearest prior phase's proven commands to the planner at every context window. - src/verify-command-grounding.cts: recognizer (not a shell interpreter) that grounds a leading cd <literal> chain and npm --prefix <literal>, and reports unresolvable rather than guessing. Never executes command text. - gsd-tools check verify-command-paths <N>: per-phase probe, wired into plan-phase.md before the plan-check pass. - init.plan-phase gains prior_verify_commands, ungated by context_window. - gsd-plan-checker: new Verify Command Path Resolvability dimension that reports the failing target and never prescribes a replacement. Also fixes first-match-wins prefix bucketing in scripts/lint-test-file-count.cjs (readdir order is not stable across platforms, so a module whose name extends another's with a hyphen bucketed differently on Linux than on macOS). Closes #2401 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2401): ground the canonical --prefix form, quoted paths, and absolute cd resets Independent review found three defects in the recognizer: - npm --prefix DIR run SCRIPT never reached the script-existence check, because the pattern required npm and run to be adjacent. That is the form the docs tell planners to prefer, so script_missing never fired for it. The prefix flag and its value are now stripped before matching. - --prefix captured with \S+, so a quoted path containing a space was truncated to a stray opening quote and reported as a missing directory - a false blocker, worse than the bug this feature fixes. The capture is now quote-aware. - A chained cd whose later segment was absolute concatenated instead of resetting, producing a nonsense path and another false blocker. The fold now resets on an absolute segment. Also replaces the bespoke phase-directory regex with the canonical phase-id helpers. Real phase directories are NN-slug, not phase-N-slug, so the prior-command harvest matched nothing outside its own fixtures and the planner-inheritance half of this feature was dead code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * refactor(#2401): source task blocks from the canonical sectionizer The module carried its own copy of the <task>-block grammar - a fourth hand-rolled mirror of the one markdown-sectionizer owns. verify.cts keeps its copy only because it needs the type= attribute the canonical helper discards; this module never reads that attribute, so it can share the owner outright instead of adding a test around a copy. extractAutomatedCommands now takes task bodies from extractTaggedBlocks and the out-of-task remainder from stripTaggedBlocks. A task-grammar parity test pins the attributed task-name set against the canonical helper across six awkward task shapes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2401): extract agent-file overflow to references and repair the property arbitrary The remote matrix run came back red with 19 failures, four root causes: - agents/gsd-plan-checker.md and agents/gsd-planner.md both blew the 49152 agent cap. Their bodies move to gsd-core/references/, leaving @-reference stubs, per the documented overflow pattern. - The new checker dimension invoked gsd_run before the canonical preamble that defines it. The call is deleted outright: plan-phase.md already runs the probe and hands the result in as {VERIFY_PATHS}, so the dimension consumes that rather than re-running anything. - fc.fullUnicodeString does not exist in fast-check 4.8.0. Replaced with fc.string({ unit: 'binary' }), which covers the same 0000-10FFFF range. - Three runtime-loaded files grew; acknowledged in the existing ack fragments that already own those bare filenames, since two ack sources may never name the same path. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(#2401): regenerate golden install-tree fixtures for the new references Adding two files under gsd-core/references/ changes what the installer emits into every runtime's tree, so all 19 golden install-parity fixtures went stale. Regenerated with npm run gen:install-tree; the delta is exactly the two new reference paths per runtime, no removals. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#2401): backfill changeset pr number to 3678 * fix(#2401): treat ~ as a home expansion only at the start of a path Windows CI caught this on both shards; the Linux-only remote matrix cannot see it. The dynamic-path refusal rejected ~ anywhere, and a GitHub Windows runner's tmpdir is an 8.3 short name - C:\Users\RUNNER~1\AppData\Local\Temp - so a valid absolute Windows path came back unresolvable/dynamic_path. This was a production bug, not a test artifact: any Windows user whose project path carries an 8.3 short name, or any literal ~, silently lost the probe entirely - every command degrading to unresolvable with no explanation. ~ is a home expansion only at the start of a path; elsewhere it is an ordinary literal. The check is now split: $, backtick, *, ? and newline stay refused anywhere (substitution and globs, and the glob characters are illegal in Windows path components regardless), while ~ is refused only leading, tolerating one leading quote since the check runs before quote stripping. The prior tests only caught this on Windows because only Windows puts a ~ in tmpdir. Four new tests pin it on every platform via a fixture directory literally named RUNNER~1. 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:
17
gsd-core/references/planner-verify-command-grounding.md
Normal file
17
gsd-core/references/planner-verify-command-grounding.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Verify Command Grounding (#2401)
|
||||
|
||||
> Reference file for gsd-planner agent. Loaded on-demand via `@` reference.
|
||||
|
||||
**Inherit the command that already worked.** The planning context carries
|
||||
`prior_verify_commands` — the `<automated>` commands from the most recent prior phase that had
|
||||
any, surfaced **at every context window**, not only on 1M-class models. When this phase's build
|
||||
or test story is the same one a prior phase already proved, **reuse that command verbatim**
|
||||
rather than re-deriving a path. Re-invention is what produced `cd ../../frontend && npm run
|
||||
lint` against a directory that holds no `package.json`, and cost two revision cycles.
|
||||
|
||||
Ground every path you do author: a command's `cd` target or `npm --prefix` target must be a
|
||||
directory that exists (or that an earlier task in this phase creates) and, for an npm/make
|
||||
command, must hold the matching `package.json`/`Makefile`. `npm --prefix <dir> run <script>` is
|
||||
preferred over `cd <dir> && npm run <script>` — it does not depend on the executor's cwd. If
|
||||
`prior_verify_commands` is empty and you cannot ground a path, say so in the plan instead of
|
||||
guessing one.
|
||||
42
gsd-core/references/verify-command-path-resolvability.md
Normal file
42
gsd-core/references/verify-command-path-resolvability.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Verify Command Path Resolvability (#2401)
|
||||
|
||||
> Reference file for gsd-plan-checker agent. Loaded on-demand via `@` reference.
|
||||
|
||||
**Question:** Does each `<automated>` command's target directory actually resolve from the
|
||||
executor's cwd (the project root)? Format sanity above asks whether the *pattern* can match;
|
||||
this asks whether the command can *run at all*.
|
||||
|
||||
**Do not hand-reason the filesystem.** #2401 is precisely the failure of doing so: this
|
||||
checker flagged a bad `cd ../../frontend` (correct), then prescribed two successively-wrong
|
||||
replacement paths — the second citing a `package.json` that did not exist. Consume the
|
||||
deterministic probe result, never re-derive it yourself.
|
||||
|
||||
`gsd-core/workflows/plan-phase.md` already runs the probe **before** spawning this checker and
|
||||
interpolates the result into the verification prompt as `{VERIFY_PATHS}`, inside a
|
||||
`<verify_command_path_probe>` block. This dimension reads that already-supplied JSON — it never
|
||||
invokes `gsd_run check verify-command-paths` itself. If `{VERIFY_PATHS}` is absent from the
|
||||
prompt, treat this dimension as silent (nothing to check) rather than trying to run the probe.
|
||||
|
||||
The probe never executes command text (PLAN.md is untrusted, LLM-authored). It recognizes two
|
||||
grounded forms — a leading `cd <literal>` chain and `npm --prefix <literal>` — and refuses to
|
||||
guess at anything else.
|
||||
|
||||
**Process:** for each row in `.commands`, act on `severity` only:
|
||||
|
||||
| `severity` | `reason` | Action |
|
||||
|---|---|---|
|
||||
| `blocker` | `missing_dir` / `no_manifest` | **BLOCKER** — quote `rawTarget` and `target` verbatim |
|
||||
| `warning` | `dynamic_path` / `outside_root` / `script_missing` / `manifest_unreadable` | **WARNING** |
|
||||
| `none` | — | silent |
|
||||
|
||||
Rules:
|
||||
- **Report, never prescribe.** State the target that failed to resolve and what was missing.
|
||||
Choosing the replacement is the planner's job — it now receives the prior phase's proven
|
||||
commands (see `prior_verify_commands` in the planning context).
|
||||
- `status: pending_creation` means an earlier task in this phase creates that directory. **Not
|
||||
a finding.** Say nothing.
|
||||
- `unresolvable` means the probe could not ground the path (a variable, glob, substitution, or
|
||||
`~`). That is a WARNING, never a BLOCKER — and never a licence to guess the literal path.
|
||||
- A non-empty `readError` means the probe **could not look**. Report that as a WARNING in its
|
||||
own words; it is not a clean bill of health.
|
||||
- `MISSING …` sentinels are Dimension 8's business — this dimension stays silent on them.
|
||||
@@ -94,7 +94,9 @@ When the tdd capability's `workflow.tdd_mode` is active (resolved via the plan:p
|
||||
|
||||
When `CONTEXT_WINDOW >= 500000`, the planner prompt includes the 3 most recent prior-phase CONTEXT.md/SUMMARY.md files plus any phases in the current phase's `Depends on:` field (explicit deps load regardless of recency).
|
||||
|
||||
Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status` (#3569), `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`, `granularity`.
|
||||
**#2401 — `prior_verify_commands` is NOT part of that enrichment and is never gated on `CONTEXT_WINDOW`.** It is a handful of one-line `<automated>` commands harvested from the nearest prior phase that had any; the payload is tiny and its absence at 200k is exactly what made the planner re-invent a verify command and author an unrunnable path. Surface it at every context window.
|
||||
|
||||
Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status` (#3569), `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`, `granularity`, `prior_verify_commands` (#2401 — array of `{phase, plan, task, command}`, possibly empty; emitted at every context window).
|
||||
|
||||
**#2517:** omit the `model=` param from an `Agent()` call when its `researcher`/`planner`/`checker`_model is `"inherit"` or empty — passing `model=""` 404s on non-Claude runtimes; omitting inherits the orchestrator model (mirrors execute-phase).
|
||||
|
||||
@@ -725,6 +727,17 @@ ${CONTEXT_WINDOW >= 500000 ? `
|
||||
- Skip all other prior phases to stay within context budget
|
||||
` : ''}
|
||||
</required_reading>
|
||||
${prior_verify_commands.length > 0 ? `
|
||||
<proven_verify_commands>
|
||||
**Verify commands the previous phase actually ran (#2401) — reuse before re-deriving.** These
|
||||
are the `<automated>` commands from the nearest prior phase that had any. They resolved from
|
||||
the executor's cwd in a real run, so a path here is grounded evidence, not a guess. When this
|
||||
phase's build/test story is the same, **copy the command verbatim**; do not re-derive a
|
||||
directory. Surfaced at every context window — not part of the 1M enrichment above.
|
||||
|
||||
{For each entry in \`prior_verify_commands\`: \`- Phase {phase} · {task}: \\\`{command}\\\`\`}
|
||||
</proven_verify_commands>
|
||||
` : ''}
|
||||
${API_SURFACE_PATH ? `
|
||||
<intel_surface_hint>
|
||||
**API Surface (HINT — may be incomplete):** When \`intel.enabled\` is true, \`${API_SURFACE_PATH}\` lists symbols extracted from the codebase by regex/JS analysis. Prefer symbols listed there when referencing existing code. This surface is regex/JS-derived and MAY BE INCOMPLETE — a symbol's absence means *unknown*, not *nonexistent*. Never treat the surface as exhaustive. If you reference a symbol that is not in the surface and this phase creates it, list it under "Artifacts this phase produces".
|
||||
@@ -971,6 +984,15 @@ Display banner:
|
||||
◆ Spawning plan checker... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
|
||||
```
|
||||
|
||||
**Verify-command path probe (#2401).** Before spawning, run the deterministic resolvability
|
||||
probe and hand its JSON to the checker. It never executes command text and never prescribes a
|
||||
replacement path — it reports which `<automated>` targets resolve, which do not, and which it
|
||||
refused to guess at. Handing it over is what stops the checker hand-reasoning the filesystem.
|
||||
|
||||
```bash
|
||||
VERIFY_PATHS=$(gsd_run check verify-command-paths "${PHASE}" --raw)
|
||||
```
|
||||
|
||||
Checker prompt:
|
||||
|
||||
```markdown
|
||||
@@ -990,6 +1012,19 @@ Checker prompt:
|
||||
|
||||
${AGENT_SKILLS_CHECKER}
|
||||
|
||||
<verify_command_path_probe>
|
||||
**Deterministic verify-command path probe (#2401)** — already run; do NOT re-derive these
|
||||
verdicts by reading the filesystem yourself. Act on `severity` per the "Verify Command Path
|
||||
Resolvability" dimension: `blocker` → BLOCKER, `warning` → WARNING, `none` → silent.
|
||||
`status: pending_creation` is not a finding. A non-empty `readError` means the probe could not
|
||||
look — a WARNING, not a pass. Report the failing target verbatim; never prescribe a
|
||||
replacement path.
|
||||
|
||||
```json
|
||||
{VERIFY_PATHS}
|
||||
```
|
||||
</verify_command_path_probe>
|
||||
|
||||
<review_incorporation_verification>
|
||||
**If Mode is reviews:** Read REVIEWS.md and verify each current actionable review finding is visible in executable PLAN.md content or explicitly deferred/rejected in the relevant PLAN.md. A finding remains actionable if it requires a concrete plan task, `<action>`, `<acceptance_criteria>`, `<verify>`, `must_haves`, threat-model item, stale-path correction, or execution contract change before /gsd:execute-phase runs.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user