msd-core/docs/how-to/resolve-verify-command-path-findings.md

Resolve verify-command path findings

/msd-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

/msd-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.

msd-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:

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 /msd-plan-phase N.

3. Re-run the probe by hand to confirm

msd-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 — the command reference
• Resolve edge-coverage findings
• Resolve prohibition findings