79781e68eb
* 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>
106 lines
4.6 KiB
Markdown
106 lines
4.6 KiB
Markdown
# Resolve verify-command path findings
|
|
|
|
`/gsd-plan-phase` runs a deterministic probe over every `<automated>` verify command in a
|
|
phase's plans before the plan-check pass. When a command's target directory does not resolve,
|
|
the plan checker reports it and planning does not pass. This page is what to do with that
|
|
report.
|
|
|
|
The probe answers one narrow question — *can this command's target directory be grounded from
|
|
the executor's cwd?* — and it answers it without ever running the command.
|
|
|
|
## When you will see this
|
|
|
|
`/gsd-plan-phase N` returns `## ISSUES FOUND` with a blocker like:
|
|
|
|
```
|
|
Verify Command Path Resolvability — BLOCKER
|
|
Plan 02-PLAN.md, task "lint and build the frontend"
|
|
Command: cd ../../frontend && npm run lint && npm run build
|
|
rawTarget: ../../frontend
|
|
target: /Users/you/code/frontend
|
|
reason: missing_dir
|
|
```
|
|
|
|
## Fix it in three steps
|
|
|
|
### 1. Read the prior phase's proven command first
|
|
|
|
The planner is handed `prior_verify_commands` — the `<automated>` commands from the nearest
|
|
prior phase that had any — at **every** context window. If a previous phase already lints or
|
|
builds the same tree, that command resolved in a real run. Reuse it verbatim.
|
|
|
|
```bash
|
|
gsd-tools query init.plan-phase N --pick prior_verify_commands
|
|
```
|
|
|
|
If that returns commands, the fix is usually a copy-paste, not a new path.
|
|
|
|
### 2. Ground the path yourself if there is nothing to inherit
|
|
|
|
Check the target the probe reported:
|
|
|
|
```bash
|
|
ls -d <target>
|
|
ls <target>/package.json
|
|
```
|
|
|
|
Two forms are recognized. Prefer the second:
|
|
|
|
| Form | When it breaks |
|
|
|---|---|
|
|
| `cd <dir> && npm run <script>` | Depends on the executor's cwd; a relative climb resolves differently inside a worktree |
|
|
| `npm --prefix <dir> run <script>` | Independent of cwd — **prefer this** |
|
|
|
|
Rewrite the plan's `<automated>` block, then re-run `/gsd-plan-phase N`.
|
|
|
|
### 3. Re-run the probe by hand to confirm
|
|
|
|
```bash
|
|
gsd-tools check verify-command-paths N --raw
|
|
```
|
|
|
|
Every row should be `severity: none`, or carry a warning you have consciously accepted.
|
|
|
|
## Reading the report
|
|
|
|
Act on `severity`, not on `status` — a row can be `status: ok` and still carry an advisory.
|
|
|
|
| `reason` | `severity` | What to do |
|
|
|---|---|---|
|
|
| `missing_dir` | blocker | The directory is not there. Fix the path, or have an earlier task create it. |
|
|
| `no_manifest` | blocker | The directory exists but has no `package.json` / `Makefile`. You are almost certainly one level off — this is the #2401 case. |
|
|
| `script_missing` | warning | The manifest has no such script. Fine if this phase adds it; otherwise a typo. |
|
|
| `dynamic_path` | warning | The path uses a variable, glob, substitution, or `~`. The probe refuses to guess. Replace it with a literal if you can. |
|
|
| `outside_root` | warning | A bare ancestor climb (`cd ../..`). Under parallel worktree execution the base differs, so this cannot be checked. Anchor it instead. |
|
|
| `manifest_unreadable` | warning | `package.json` is unparseable, not a JSON object, or over 512 KB. Fix the manifest. |
|
|
|
|
## When the report says nothing
|
|
|
|
**An empty report is not automatically a clean bill of health.** Tell the two apart:
|
|
|
|
| What you see | What it means |
|
|
|---|---|
|
|
| `commands: []`, `readError: null` | The phase's plans contain no `<automated>` blocks to probe. |
|
|
| `commands: [...]`, every `severity: none` | Every command's target resolved. This is the clean case. |
|
|
| `readError` is a non-empty string | The probe **could not look** — the phase directory or a plan file was unreadable. Not a pass. |
|
|
| `status: not_applicable` rows | Those commands have no `cd` or `--prefix` to resolve; they run at the project root. |
|
|
| `status: pending_creation` rows | An earlier task in this phase creates that directory. Correct and expected on a greenfield phase. |
|
|
|
|
## What the probe deliberately will not do
|
|
|
|
- **It will not run your command.** PLAN.md is model-authored text; executing it from the
|
|
checker would be arbitrary code execution, and would trigger the real lint/build as a side
|
|
effect.
|
|
- **It will not suggest a replacement path.** Prescribing one is exactly the failure that
|
|
motivated this check — the checker previously guessed twice and was wrong both times, the
|
|
second time citing a `package.json` that did not exist.
|
|
- **It does not recognize every launcher.** `pushd`, `make -C`, `yarn --cwd`, `pnpm -C`, and
|
|
`cargo --manifest-path` report `unresolvable` rather than being half-parsed. Refusing to
|
|
guess is the design.
|
|
|
|
## Related
|
|
|
|
- [Verify Command Path Resolvability](../COMMANDS.md#gsd-tools-check-verify-command-paths) — the command reference
|
|
- [Resolve edge-coverage findings](resolve-edge-coverage-findings.md)
|
|
- [Resolve prohibition findings](resolve-prohibition-findings.md)
|