Repository navigation
Closed
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Description
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
- A grounding check (in validate-plan.py or a sibling script invoked alongside it) strips any
#anchorsuffix and verifies eachreferences/target_surfaceentry that looks like a repo path resolves against the repo root. - 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).
- 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. - The repo root is resolved explicitly (e.g.
git rev-parse --show-toplevelor the script location), not from the current working directory. - 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
#anchorbefore 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 usesscripts/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 withhttp/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.pytests/test_initiative_planner.bats
Story prepared by the BMAD Scrum Master (Bob) for epic #597. Status: ready-for-dev.
Metadata
Metadata
Assignees
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Activity
don-petry commentedon Jun 14, 2026
Dev-Lead Implementation Plan
Issue: #602 — [Phase 2] Grounding check: verify references/target_surface paths resolve
Scope
Extend
validate-plan.pywith a grounding check that strips any#anchorsuffix and verifies eachreferences/target_surfaceentry 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, barediscussion #NNN, anchor-only strings).Implementation Checklist
repo_root()helper tovalidate-plan.pyresolving root viagit 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)looks_like_path()heuristic (documented in code): enforce only entries containing/or ending in a known file extension; skiphttp*,discussion,#-prefixed, and bare-prose entries. (AC Add @claude delegation, auto-merge, and rebase handling #3)check_grounding()that, per story, strips the first#anchor and verifies each path-likereferences/target_surfaceentry 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)check_grounding()intomain()after the DAG checks so it uses the existingfail()non-zero exit contract.Tests to Write
references/target_surfacepath fails with a story-id-scoped message and non-zero exit.discussion #593) does NOT fail the grounding check.Test Command
bats tests/test_initiative_planner.bats(full suite), thenbash .dev-lead/scripts/dev-lead-lint.shdon-petry commentedon Jun 14, 2026
Dev-Lead: Implementation Complete
Plan Execution
repo_root()— resolves root viagit 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)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)check_grounding()— per story, strips the first#anchorand verifies each path-likereferences/target_surfaceentry resolves under repo root;fail()s on the first miss naming the story id, field, and missing path (non-zero via the existingfail()contract). (AC test issue from agent #1, Go-live improvements for PR review agent #2)check_grounding(stories, repo_root())intomain()after the DAG checks, before the success print.discussion #593) do not false-fail. (AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5)Test Results
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_compilepasses.Files Changed
scripts/initiative-planner/validate-plan.py: addedrepo_root(),looks_like_path(),check_grounding()and asubprocessimport; wired the grounding check intomain().tests/test_initiative_planner.bats: added 3 grounding cases (real-paths pass, fabricated-path fails, prose-not-a-path).Notes
fail()(exit 1), so the workflow stops beforeapply-planruns.www.example.com/foowould be treated as a path (contains/); this is documented and acceptable since planner citations use real repo paths orhttp(s)/discussion #Nprose.lint.ymlbats-list update is needed.feat: implement issue #602 — grounding check: verify references/targe…