enhance(#2401): ground verify-command paths and inherit prior-phase commands (#3678)

* 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:
Tom Boucher
2026-08-19 15:21:15 -04:00
committed by GitHub
parent 4e60dba717
commit 79781e68eb
43 changed files with 2231 additions and 7 deletions

View File

@@ -1172,6 +1172,64 @@ Extract reusable patterns, anti-patterns, and architectural decisions from compl
---
### `gsd-tools check verify-command-paths`
Deterministic resolvability probe over a phase's `<automated>` verify commands (#2401). Run
automatically by `/gsd-plan-phase` before the plan-check pass and handed to `gsd-plan-checker`;
runnable by hand to see what the checker saw.
| Argument | Required | Description |
|----------|----------|-------------|
| `N` | **Yes** | Phase number whose `-PLAN.md` files are probed |
| Flag | Description |
|------|-------------|
| `--raw` | Emit the JSON payload with no surrounding prose |
**Prerequisites:** none — an unresolvable phase degrades to a JSON payload with `readError` set
rather than failing.
**Produces:** JSON on stdout. Nothing is written to disk.
**It never executes command text.** PLAN.md is LLM-authored, so the probe only resolves paths
and stats directories; a `package.json` it finds is read for script *names* only.
It grounds exactly two forms — a leading `cd <literal>` chain and `npm --prefix <literal>` —
and refuses to guess at anything else. `pushd`, `make -C`, `yarn --cwd`, `pnpm -C`, and
`cargo --manifest-path` are not recognized today and report `unresolvable`.
Each row of `commands` carries `command`, `plan`, `task`, `status`, `severity`, `reason`,
`form`, `rawTarget`, `target`, `manifest`, `script`, `sentinel`, and `base`. There is
deliberately **no** `suggestion` field — the probe reports what failed to resolve and leaves
the replacement to the planner.
| `status` | Meaning |
|---|---|
| `ok` | Target resolved (a `reason` may still carry an advisory — see below) |
| `broken` | Target does not resolve, or holds no required manifest — **blocker** |
| `unresolvable` | The path could not be grounded (variable, glob, substitution, `~`) — warning |
| `pending_creation` | An earlier task in this phase creates the target — not a finding |
| `not_applicable` | No `cd`/`--prefix` to resolve, or a Nyquist `MISSING …` sentinel |
| `reason` | `severity` | What it means |
|---|---|---|
| `missing_dir` | `blocker` | The resolved directory does not exist, or is not a directory |
| `no_manifest` | `blocker` | The directory exists but holds no `package.json` / `Makefile` the command needs |
| `dynamic_path` | `warning` | The path contains `$`, a backtick, `*`, `?`, or `~` — refused, not guessed |
| `outside_root` | `warning` | A bare ancestor climb (`cd ../..`); the base differs under worktree execution |
| `script_missing` | `warning` | `npm run <script>` names a script the manifest does not define — this phase may add it |
| `manifest_unreadable` | `warning` | `package.json` is oversized, unparseable, or not a JSON object |
| `null` | `none` | Nothing to report |
A non-empty `readError` means the probe **could not look** — distinct from finding nothing.
```bash
gsd-tools check verify-command-paths 3 --raw # probe phase 3's verify commands
```
See [Resolve verify-command path findings](how-to/resolve-verify-command-path-findings.md).
---
## Workstream Management
### `/gsd-workstreams`