Skip to content

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

Closed

Description

@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

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.

Activity

  1. don-petry commented on Jun 14, 2026

    @don-petry
    Collaborator

    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

    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

  2. don-petry commented on Jun 14, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    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.
  3. added a commit that references this issue on Jun 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions