[Phase 2] Grounding check: verify references/target_surface paths resolve

[github-actions]

Story

As a maintainer trusting Bob's Dev Notes,
I want validation to confirm every references and target_surface path in the plan resolves in the checkout, flagging hallucinated anchors,
so that stories can't ship citing files that don't exist, so dev-lead never chases a phantom path.

Acceptance Criteria

1. A grounding check (in validate-plan.py or a sibling script invoked alongside it) strips any #anchor suffix and verifies each references/target_surface entry that looks like a repo path resolves against the repo root.
2. A path that does not resolve fails the check with a message naming the story id and the missing path, exiting non-zero (consistent with validate-plan.py's fail() contract).
3. Entries that are clearly not file paths (a bare discussion #593, a URL) are not treated as paths and do not cause false failures; the heuristic is documented in code.
4. The repo root is resolved explicitly (e.g. git rev-parse --show-toplevel or the script location), not from the current working directory.
5. Existing fixtures (which cite real paths) still pass; a new bats case adds a story citing a nonexistent path and asserts the failure.

Tasks / Subtasks

• Implement the path-resolution check, stripping the #anchor before testing existence. (AC: test issue from agent #1, Optimize review: small-PR and incremental fast paths #4)
• Implement and document the path-vs-prose heuristic so URLs and bare citations are skipped. (AC: Add @claude delegation, auto-merge, and rebase handling #3)
• Wire failure into the non-zero exit path with a story-id-scoped message. (AC: Go-live improvements for PR review agent #2)
• Add bats coverage: real paths pass; a fabricated path fails. (AC: feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

• references/target_surface are free-form strings in plan.schema.json; the schema example uses scripts/engine.sh#tier-routing (with anchor) and the fixture uses scripts/engine.sh. Split on the first # for the file-existence test.
• validate-plan.py runs in the workflow checkout (.github/workflows/initiative-planner.yml:147-156 runs it after gather-context with the repo checked out), so relative paths resolve against the repo root — establish that root explicitly rather than relying on cwd.
• Document the heuristic for path vs prose: e.g. only enforce entries containing / or ending in a known extension, and skip anything starting with http/discussion/# — see open_questions.
• Keep it a HARD validation failure consistent with validate-plan.py's fail() at validate-plan.py:23-27, so the workflow stops before apply-plan runs.
• Testing: extend tests/test_initiative_planner.bats with a fabricated-path fixture variant; the suite already drives validate-plan.py directly.

Project Structure Notes

Fits cleanly into validate-plan.py (the existing semantic-gate home) or a sibling invoked from the same workflow step. Prefer extending validate-plan.py to keep one validation entry point.

References

• scripts/initiative-planner/validate-plan.py#L23-L70
• scripts/initiative-planner/plan.schema.json
• .github/workflows/initiative-planner.yml#L147-L156
• tests/test_initiative_planner.bats

Likely target surface

• scripts/initiative-planner/validate-plan.py
• tests/test_initiative_planner.bats

Story prepared by the BMAD Scrum Master (Bob) for epic #597. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #602 — [Phase 2] Grounding check: verify references/target_surface paths resolve

Scope

Extend validate-plan.py with a grounding check that strips any #anchor suffix and verifies each references/target_surface entry that looks like a repo path resolves against an explicitly-resolved repo root, failing (non-zero, story-id-scoped message) on a missing path while skipping non-path prose (URLs, bare discussion #NNN, anchor-only strings).

Implementation Checklist

• Add repo_root() helper to validate-plan.py resolving root via git rev-parse --show-toplevel, falling back to the script location (Path(__file__).resolve().parents[2]) — never cwd. (AC Optimize review: small-PR and incremental fast paths #4)
• Add looks_like_path() heuristic (documented in code): enforce only entries containing / or ending in a known file extension; skip http*, discussion, #-prefixed, and bare-prose entries. (AC Add @claude delegation, auto-merge, and rebase handling #3)
• Add check_grounding() that, per story, strips the first # anchor and verifies each path-like references/target_surface entry resolves under repo root; fail() with the story id + missing path on the first miss. (AC test issue from agent #1, Go-live improvements for PR review agent #2)
• Wire check_grounding() into main() after the DAG checks so it uses the existing fail() non-zero exit contract.

Tests to Write

• bats: well-formed plan with real cited paths still passes (covered by existing case; confirm green).
• bats: a story citing a fabricated references/target_surface path fails with a story-id-scoped message and non-zero exit.
• bats: a story whose references are pure prose (URL / discussion #593) does NOT fail the grounding check.

Test Command

bats tests/test_initiative_planner.bats (full suite), then bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Added repo_root() — resolves root via git rev-parse --show-toplevel (run from the script dir), falling back to the script location (parents[2]), never cwd. (AC Optimize review: small-PR and incremental fast paths #4)
• Added looks_like_path() heuristic, documented in code: skip URLs (http*), anchor-only (#…) and bare cross-refs (discussion …); treat as a path only when the entry contains / or ends in a known extension. (AC Add @claude delegation, auto-merge, and rebase handling #3)
• Added check_grounding() — per story, strips the first #anchor and verifies each path-like references/target_surface entry resolves under repo root; fail()s on the first miss naming the story id, field, and missing path (non-zero via the existing fail() contract). (AC test issue from agent #1, Go-live improvements for PR review agent #2)
• Wired check_grounding(stories, repo_root()) into main() after the DAG checks, before the success print.
• Added bats coverage: real paths pass (anchor stripped), a fabricated path fails with a story-id-scoped message, and prose citations (URL / discussion #593) do not false-fail. (AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Test Results

1..20
ok 1 validate-plan accepts a well-formed acyclic plan
ok 2 validate-plan accepts open_questions carrying a blocking flag
ok 3 validate-plan grounding: accepts real cited paths (with #anchor stripped)
ok 4 validate-plan grounding: rejects a story citing a nonexistent path
ok 5 validate-plan grounding: prose citations (URL, bare discussion ref) are not treated as paths
ok 6 validate-plan rejects a self-blocking story
ok 7 validate-plan rejects a dependency cycle (with an entry point present)
ok 8 validate-plan rejects a dangling blocked_by reference
ok 9 validate-plan rejects a plan with no entry point
ok 10 apply-plan (DRY_RUN) creates epic + stories + edges and posts comment
ok 11 apply-plan threads distinct issue numbers in dry-run
ok 12 apply-plan NEVER applies initiative:auto to any created issue
ok 13 apply-plan marks hands_off story with hold + hands-off labels
ok 14 existing-issue prerequisite edge references the real issue number
ok 15 apply-plan gates on a blocking open question: creates zero issues and exits 0
ok 16 apply-plan blocking gate posts the open questions back to the discussion
ok 17 apply-plan does NOT gate on a non-blocking open question
ok 18 apply-plan skips creation when an epic already exists for the discussion
ok 19 apply-plan still creates the full DAG when no existing epic is found
ok 20 story bodies are rendered in the BMAD create-story template

Repo lint (bash .dev-lead/scripts/dev-lead-lint.sh): all checks passed (52 shell files + 4 agent profiles). No Python linter is configured in this repo; python3 -m py_compile passes.

Files Changed

• scripts/initiative-planner/validate-plan.py: added repo_root(), looks_like_path(), check_grounding() and a subprocess import; wired the grounding check into main().
• tests/test_initiative_planner.bats: added 3 grounding cases (real-paths pass, fabricated-path fails, prose-not-a-path).

Notes

• The grounding check is a HARD failure consistent with fail() (exit 1), so the workflow stops before apply-plan runs.
• Heuristic is intentionally conservative: a scheme-less URL like www.example.com/foo would be treated as a path (contains /); this is documented and acceptable since planner citations use real repo paths or http(s)/discussion #N prose.
• No new test file was added, so no lint.yml bats-list update is needed.