Intent discovery and plan requirements

Read this at Stage 2. It defines the intent summary, plan discovery, what context each reviewer receives, and the plan-readiness rules that Stage 6 (Synthesize and present) verifies requirements against.

Plan Requirements Completeness

When a plan is provided via plan:<path> or discovered from PR/branch context, inspect the contents before checking completeness. A Product Contract alone informs product intent and does not create implementation-unit obligations. When implementation units are present, check their coverage as well, including incomplete planning. Old readiness labels do not change the review scope. Legacy plans keep the existing completeness checks.

An unaddressed requirement or implementation unit is a finding on every depth path, routed by plan_source: explicit (a plan: argument or a PR-body link) yields a P1 finding with autofix_class: manual and owner: downstream-resolver, which enters the actionable queue; inferred (auto-discovered) yields a P3 finding with autofix_class: advisory and owner: human, which stays in the report only, because an inferred match is a hint, not a contract.

When plan_group: names a PR group of a plan that ships as several PRs, this diff builds only that group. Completeness covers that group's units and the requirements they trace to; units in the plan's other groups are out of scope here, not unaddressed. A plan_group: label that starts no group heading in the plan is reported in Coverage, and completeness falls back to the whole plan.

The check also runs in reverse. A behavior rule is a decision about what users or callers observe that a product owner would otherwise have made, such as silently dropping a repeated refund request. When the diff introduces a behavior rule that nothing in the plan asks for, that unrequested behavior rule is a finding on every depth path, listed with the requirements completeness results. Route it P3 with autofix_class: advisory and owner: human, whatever the plan_source, and never let it change the verdict. Whether the rule is wanted is the user's call, and a correct diff is no evidence either way. Internal structure, refactors, and handling of inputs a requirement already covers are not behavior rules.

Extract requirements from these shapes, in order:

1. Unified Product Contract -> ### Requirements
2. Legacy top-level ## Requirements
3. Legacy ## Requirements Trace

For unified plans with implementation units, also extract U-IDs from ## Implementation Units and compare against PR body/branch context when available. Do not require every Product Contract R-ID to map one-to-one to a single U-ID; verify that implemented U-IDs cite the relevant R/F/AE/KTD IDs and that no claimed U-ID is missing from the plan.

Stage 2: Intent discovery

Understand what the change is trying to accomplish. The source of intent depends on which Stage 1 path was taken:

PR/URL mode: Use the PR title, body, and linked issues from gh pr view metadata. Supplement with commit messages from the PR if the body is sparse.

Branch mode: Run git log --oneline ${BASE}..<branch-ref> using the resolved merge-base and resolved branch ref from Stage 1. Use <branch-ref> (the resolved origin/<branch> or fetched ref), not the raw <branch> argument — a remote-only branch has no matching local ref, so the raw name would fail or read a stale same-named local branch.

Standalone (current branch): Run:

echo "BRANCH:" && git rev-parse --abbrev-ref HEAD && echo "COMMITS:" && git log --oneline ${BASE}..HEAD

Combined with conversation context (plan section summary, PR description), write a 2-3 line intent summary:

Intent: Simplify tax calculation by replacing the multi-tier rate lookup
with a flat-rate computation. Must not regress edge cases in tax-exempt handling.

Pass this to every reviewer in their spawn prompt. Intent shapes how hard each reviewer looks, not which reviewers are selected. Keep any session-settled: annotations (from a plan or the conversation) out of this summary. Reviewers must not see settlement annotations (Stage 2b, Plan discovery).

When intent is ambiguous: Infer from branch name, commits, PR title/body, diff, plan:, and conversation. Write the best-effort intent summary and note uncertainty in Coverage — never block on a clarifying question.

Stage 2b: Plan discovery (requirements verification)

Locate the plan document so Stage 6 can verify requirements completeness. Check these sources in priority order — stop at the first hit:

1. **plan: argument.** If the caller passed a plan path, use it directly. Read the file to confirm it exists.
2. PR body. If PR metadata was fetched in Stage 1, scan the body for paths matching <root>/plans/*.{md,html} (unified plans may be markdown or HTML). If exactly one match is found and the file exists, use it as plan_source: explicit. If multiple plan paths appear, treat as ambiguous — demote to plan_source: inferred for the most recent match that exists on disk, or skip if none exist or none clearly relate to the PR title/intent. Always verify the selected file exists before using it — stale or copied plan links in PR descriptions are common.
3. Auto-discover. Extract 2-3 keywords from the branch name (e.g., feat/onboarding-skill -> onboarding, skill). Glob <root>/plans/* and filter filenames containing those keywords. If exactly one match, use it. If multiple matches or the match looks ambiguous (e.g., generic keywords like review, fix, update that could hit many plans), skip auto-discovery — a wrong plan is worse than no plan. If zero matches, skip.

Confidence tagging: Record how the plan was found:

• plan: argument -> plan_source: explicit (high confidence)
• Single unambiguous PR body match -> plan_source: explicit (high confidence)
• Multiple/ambiguous PR body matches -> plan_source: inferred (lower confidence)
• Auto-discover with single unambiguous match -> plan_source: inferred (lower confidence)

If a plan is found, classify by contents before extraction (see "Plan Requirements Completeness" above): treat a Product Contract without implementation planning as product intent only — it must not drive implementation-unit completeness findings. Then read its Requirements in this order — unified Product Contract -> ### Requirements, then legacy top-level ## Requirements, then legacy ## Requirements Trace — and the R-IDs (R1, R2, etc.) listed there, plus Implementation Units (current numeric subsections such as ### U1., ### U2., or ### Unit 1: under ## Implementation Units; legacy bullet or checkbox unit entries under that section also count). For HTML unified plans the same section names and R-/U-IDs appear as visible headings/anchors — match on the section name, ignoring HTML wrapper tags. Store the extracted requirements list and plan_source for Stage 6. Do not block the review if no plan is found — requirements verification is additive, not required.

When the discovered plan's Key Technical Decisions carry session-settled: annotations (classes user-directed / user-approved), extract each labeled KTD — the decision, its class, and the rejected alternative — for your own use in Stage 5 triage (step 6c). Settlement annotations are context for you (the orchestrator) only: exclude them from the Stage 2 intent summary and from every reviewer's prompt, including the cross-model adversarial pass. The point is reviewer independence: each reviewer must stay free to re-derive the rejected alternative on the merits, and you triage any settlement conflicts afterwards in Stage 5.

Stage 2c: Keep grounding review-specific

Use the project's active instructions already in context plus the current diff and source. Give each reviewer only the context relevant to its review focus; the project-standards reviewer reads the actual standards sources. If a reviewer cannot scope the affected area from the diff and supplied context, allow one targeted probe.

In pr-remote / branch-remote, current source and any targeted probe must use git show against the supplied reviewed head ref, or the supplied diff hunks when no head ref is available; never inspect workspace paths.