New plugin: plan-grounder — ground implementation plans against real codebase

[dapi]

Summary

Agent plan-grounder inside plan-reviewer plugin (#34). Grounds implementation plan against the real codebase — verifies that plan actually maps to existing code, files, APIs, and project structure.

Concept from eTechLead stream:

Grounding каждого стейджа на кодовую базу — агент идёт в проект и проверяет, как план ложится на существующий код. Какие файлы затронет, нет ли конфликтов. Без grounding агент может писать код, который вообще не ложится на проект.

File: plan-reviewer/agents/plan-grounder.md

Problem

writing-plans has codebase access and should produce grounded plans, but:

• Same agent creates and "verifies" — no second pair of eyes
• LLMs hallucinate paths/APIs even after reading code (context drift over 50k+ tokens)
• Plans reference line numbers that shift after earlier steps
• No explicit "walk every path and verify it exists" phase
• Plans go stale: if time passes and new commits land, grounding must be re-run

What plan-grounder checks

1. File & path grounding

• Do all referenced file paths exist?
• Are Create: paths in valid directories?
• Are Modify: paths pointing to real files?
• Do line number references (e.g. file.py:123-145) match actual content?

2. API & code grounding

• Do referenced functions/methods/classes exist?
• Are function signatures correct (args, return types)?
• Do import paths resolve?
• Are referenced config keys, env vars, DB tables real?

3. Dependency & conflict grounding

• Will plan steps conflict with each other (e.g. two steps modifying same lines)?
• Are there unstaged changes or recent commits that invalidate the plan?
• Does the plan account for existing tests that might break?

4. Feasibility check

• Can the plan be executed as written?
• Are there external dependencies (APIs, services) that need to be running?
• Are there permissions/access requirements not mentioned?

Output format

Per-step findings with GRD-* prefix:

Task 1: Setup DB schema
  GRD-1  Modify: src/models/user.py:45-60     OK    file exists, lines match
  GRD-2  Create: src/models/payment.py         OK    directory exists
  GRD-3  API: User.create()                    OK    exists in user.py:23
  GRD-4  API: Payment.process()                WARN  no such method yet (created in this task?)

Task 4: Refactor auth middleware
  GRD-5  Modify: src/middleware/auth.py:12-30  FAIL  lines 12-30 are imports, not auth logic
  GRD-6  API: verify_token()                   FAIL  actual name is verify_jwt_token()
  GRD-7  Conflict: Task 2 also modifies auth.py WARN potential merge conflict

Re-grounding (stale detection)

When --reground flag is passed by orchestrator:

1. Parse plan creation date
2. git log --since=<date> --name-only — changed files
3. Cross-reference with plan's file list
4. Re-ground only affected tasks

Tools needed

• Glob, Grep, Read — for codebase verification
• Bash — for git log (stale detection)

Acceptance criteria

• Agent file: plan-reviewer/agents/plan-grounder.md
• Validates file paths exist in codebase
• Validates referenced APIs/functions/classes exist
• Detects line number drift
• Detects conflicts between plan steps
• Stale plan detection via git changes
• Per-finding output with GRD-* prefix and OK/WARN/FAIL severity

---

Parent issue: #34 (Meta: plan-reviewer orchestrator)