[Phase 2] Register plan_json artifact type (plan rubric + structured-findings channel)

[github-actions]

Story

As a initiative-planner (Bob) and Epic #597's plan critic,
I want a plan_json artifact type registered with the fixed plan rubric and a structured-findings output channel,
so that an initiative plan.json can be reviewed by the same review brain before it is materialized.

Acceptance Criteria

1. A plan_json entry is added to the rubric registry mapping to a plan rubric (the fixed critic checklist) and a structured-findings output channel (machine-readable findings, not GitHub PR comments).
2. The content_ref adapter accepts a plan.json path and presents it to the rubric, reusing scripts/engine.sh model routing.
3. The output channel emits structured findings the planner can consume before apply-plan.sh materializes the epic/DAG.
4. pr_diff behavior is untouched (the Story 3 guard stays green); plan_json is purely additive.
5. bats coverage exercises plan_json resolution and a sample plan producing findings; the new test is registered in the lint.yml bats list.

Tasks / Subtasks

• Author the plan rubric file under prompts/ (the fixed critic checklist), grounding its checks in plan.schema.json + validate-plan.py invariants and layering adversarial/semantic critique on top. (AC: test issue from agent #1)
  • Do not duplicate the structural validator (unique ids, acyclic DAG, entry point, no dangling/self edges) — critique grounding, references, and AC quality instead.
• Add the plan_json registry entry {rubric, structured-findings channel} and a content_ref adapter that feeds a plan.json into the rubric via engine.sh. (AC: test issue from agent #1, Go-live improvements for PR review agent #2)
• Implement the structured-findings output channel (write findings JSON for the planner; do NOT call post-pr-review.sh). (AC: Add @claude delegation, auto-merge, and rebase handling #3)
• Add bats coverage, register it in lint.yml, and confirm the pr_diff guard is unchanged. (AC: Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

• The plan rubric is Epic Initiative: Adversarial plan-critic + structural gates for the initiative-planner (Bob) #597's 'fixed critic rubric.' Structural invariants already exist in scripts/initiative-planner/validate-plan.py (unique ids, no dangling/self edges, acyclic, entry point) and plan.schema.json — the rubric should layer adversarial/semantic critique (grounding, reference resolution, AC testability) on top, not re-implement the validator.
• Output channel differs fundamentally from pr_diff: plans are consumed by the planner (apply-plan.sh runs after validate-plan.py), so emit machine-readable findings JSON, NOT a GitHub review. Do not invoke post-pr-review.sh for plan_json.
• This satisfies/re-scopes [Phase 2] Adversarial plan-critic pass against the fixed rubric #603 ('Adversarial plan-critic pass against the fixed rubric') to 'invoke the review agent with the plan rubric' rather than forking a bespoke critic — coordinate so [Phase 2] Adversarial plan-critic pass against the fixed rubric #603 consumes this capability, not a parallel implementation.
• Reuse scripts/engine.sh model routing (run_agentic / deep tier); do not introduce a separate model selector.

Project Structure Notes

New rubric prompt under prompts/ (e.g. prompts/plan-review.md); registry entry + adapter in scripts/lib/; consumer wiring near scripts/initiative-planner/. Keep the structured-findings channel separate from post-pr-review.sh.

References

• scripts/initiative-planner/plan.schema.json
• scripts/initiative-planner/validate-plan.py
• scripts/initiative-planner/apply-plan.sh
• scripts/engine.sh#run_agentic
• prompts/deep-review.md
• tests/test_initiative_planner.bats

Likely target surface

• prompts/plan-review.md
• scripts/lib/review-registry.sh
• scripts/initiative-planner/
• tests/

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

[don-petry]

Dev-Lead Implementation Plan

Issue: #614 — [Phase 2] Register plan_json artifact type (plan rubric + structured-findings channel)

Scope

Register a purely-additive plan_json artifact type in the rubric registry — mapping a fixed adversarial/semantic plan rubric to a structured-findings output channel — with a content_ref adapter that feeds a plan.json into the rubric via engine.sh deep-tier routing, leaving pr_diff behavior untouched.

Implementation Checklist

• prompts/plan-review.md — the fixed critic rubric. Layers adversarial/semantic critique (grounding, reference resolution, AC testability, scope/sequencing) on top of the existing structural validator; does NOT re-implement validate-plan.py invariants.
• scripts/lib/review-registry.tsv — add the plan_json row {rubric=prompts/plan-review.md, output_channel=scripts/post-plan-findings.sh}; bump schema_version.
• scripts/lib/README.md — document the new plan_json type (structured-findings channel, not a GitHub review).
• scripts/post-plan-findings.sh — structured-findings output channel. Validates the findings JSON shape and emits machine-readable findings the planner can consume. Does NOT call post-pr-review.sh or any gh review API.
• scripts/initiative-planner/review-plan.sh — content_ref adapter/driver. Resolves {rubric, output_channel} for artifact_type=plan_json from the registry, exports the plan path, runs the rubric via engine.sh run_agentic (deep tier — reuses existing routing, no new selector), then dispatches findings through the resolved output channel.

Tests to Write

• tests/test_plan_review.bats — (1) registry resolves plan_json → plan-review.md + post-plan-findings.sh and referenced files exist; (2) pr_diff remains registered/unchanged (additive guard); (3) driver wiring: sources engine.sh + registry, dispatches plan_json, exports the plan path as content_ref, invokes the resolved channel variable, never calls post-pr-review.sh; (4) output channel: a sample plan's findings JSON is emitted as machine-readable findings, malformed findings rejected, no GitHub calls.
• Update tests/test_review_registry.bats — the Phase-1 "pr_diff is the only registered type" count assertion becomes "pr_diff is still registered" (plan_json is now additive). The [Phase 1] Regression guard locking pr_diff behavior through the contract #613 Story-3 verdict/marker regression guard stays untouched and green.
• Register tests/test_plan_review.bats in the lint.yml bats list.

Test Command

bats tests/test_plan_review.bats tests/test_review_registry.bats tests/test_pr_diff_dispatch.bats tests/test_initiative_planner.bats then full suite + bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Authored the fixed plan rubric prompts/plan-review.md — adversarial/semantic critique (grounding, reference resolution, AC testability, scope/sequencing, open-questions) layered on top of the structural validator; explicitly does not re-implement validate-plan.py / plan.schema.json invariants.
• Registered plan_json additively in scripts/lib/review-registry.tsv → {rubric: prompts/plan-review.md, output_channel: scripts/post-plan-findings.sh}; bumped schema_version 1→2 and documented the type in scripts/lib/README.md.
• Implemented the structured-findings output channel scripts/post-plan-findings.sh — validates the findings JSON shape/verdict and emits machine-readable findings for the planner. Never calls post-pr-review.sh, gh pr review, or the reviews API.
• Implemented the content_ref adapter/driver scripts/initiative-planner/review-plan.sh — resolves {rubric, output_channel} for artifact_type=plan_json, presents the plan.json path to the rubric, and reuses engine.sh run_agentic at the deep tier (no separate model selector), then delivers via the resolved channel.
• Added tests/test_plan_review.bats (22 tests) and registered it in the lint.yml bats list.
• Updated the Phase-1 "pr_diff is the only registered type" assertion in tests/test_review_registry.bats to "pr_diff stays registered" — its sole-type premise is exactly what this issue extends. The [Phase 1] Regression guard locking pr_diff behavior through the contract #613 Story-3 verdict/marker regression guard is untouched and green.

Test Results

# New plan_json coverage
$ bats tests/test_plan_review.bats        -> 22/22 ok

# Affected suites (pr_diff additive guard + planner)
$ bats test_plan_review test_review_registry test_pr_diff_dispatch test_initiative_planner -> 79/79 ok

# Full lint.yml bats list (26 files) -> 434/434 ok, 0 failures

$ bash .dev-lead/scripts/dev-lead-lint.sh -> all checks passed (shellcheck 58 files + 4 agent profiles)
$ shellcheck -S warning scripts/post-plan-findings.sh scripts/initiative-planner/review-plan.sh -> clean

Files Changed

• prompts/plan-review.md (new): the fixed plan critic rubric.
• scripts/lib/review-registry.tsv: plan_json row + schema_version: 2.
• scripts/lib/README.md: documents the plan_json type / structured-findings channel.
• scripts/post-plan-findings.sh (new): structured-findings output channel.
• scripts/initiative-planner/review-plan.sh (new): content_ref adapter/driver (engine.sh deep tier).
• tests/test_plan_review.bats (new): 22 tests — registry resolution, driver wiring, sample-plan findings.
• tests/test_review_registry.bats: additive update to the registered-types guard.
• .github/workflows/lint.yml: registers the new bats file.

Notes

• AC Optimize review: small-PR and incremental fast paths #4 (pr_diff untouched): post-pr-review.sh and the pr_diff registry row/cascade are unchanged; the [Phase 1] Regression guard locking pr_diff behavior through the contract #613 Story-3 guard stays green. plan_json is purely additive.
• Scope / [Phase 2] Adversarial plan-critic pass against the fixed rubric #603 coordination: this delivers the reusable plan-review capability (registry entry + adapter + findings channel). It is intentionally not wired into apply-plan.sh or the planner workflow as a gate — that is [Phase 2] Adversarial plan-critic pass against the fixed rubric #603's job ("invoke the review agent with the plan rubric"), which should consume review-plan.sh rather than fork a bespoke critic.
• Engine reuse: the rubric runs through engine.sh run_agentic deep tier; no new model selector was introduced.
• Testing boundary: the LLM cascade itself can't run in CI (needs a live engine), so the driver is covered by wiring tests; the output channel is exercised deterministically with a sample plan's findings JSON (AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5).