@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/review-artifact/references/reviewer-prompt.md

@@ -1,57 +1,148 @@
-# Artifact Reviewer Prompt
+# Independent Artifact Reviewer Contract
 
-Use this when dispatching a reviewer subagent. For second and later iterations, include the iteration context so the reviewer does not blindly re-raise stale findings.
+Use this when preparing an independent review of a durable artifact.
 
-```text
-You are an artifact reviewer. Review whether this artifact is fit to guide future work.
+The reviewer did not produce the artifact. Give them the artifact, source truth, and evidence needed to judge it directly. The reviewer reports review items without editing.
 
-Artifact:
-[ARTIFACT_PATH]
+## Required Context
 
-Artifact type:
-[spec | plan | handoff | decision note | discovery note | other]
+Provide:
 
-Source context to inspect:
-[DOCS_TESTS_POLICIES_ADRS_CODE_PATHS]
+- artifact path, type, current state, and intended use;
+- accepted outcome, requirements, and non-goals;
+- owner decisions and unresolved questions;
+- relevant code, tests, policies, ADRs, and established behavior;
+- the artifact-specific schema or format contract when one exists;
+- upstream and downstream artifacts in dependency order;
+- known evidence gaps;
+- review number and, for a follow-up, prior items, adjudication, revisions, and new evidence.
 
-Iteration context, if this is not the first review:
-- Review pass number: [2 | 3]
-- Prior findings: [SUMMARY]
-- Parent adjudication: [ACCEPTED_REJECTED_QUESTION_NEEDS_EVIDENCE]
-- Owner clarifications: [DECISIONS_OR_NONE]
-- Changed sections: [SECTIONS_OR_NONE]
-- Remaining risk to focus on: [RISK]
+For an artifact package, identify upstream authority and which work remains provisional or dependent.
 
-Check:
+## Reviewer Prompt
 
-- Completeness: enough is present to proceed.
-- Evidence: load-bearing claims point to live evidence or explicit decisions.
-- Clarity: a fresh agent can act without transcript memory.
-- Consistency: artifact agrees with itself and source context.
-- Artifact identity: durable or strict-workflow artifacts have useful owner, status, source, and change-history signals.
-- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
-- Design depth: module, interface, seam, adapter, or slice choices do not spread coordination across callers, tests, docs, or future agents.
-- Adversarial risk: artifact cannot smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+```md
+# Independent Artifact Review
 
-Calibration:
+Review an artifact you did not produce. Inspect the complete artifact and source evidence directly. Report review items without editing. The review ends with this report; do not revise the artifact, dispatch a follow-up, or keep reviewing merely to obtain Pass.
 
-- Only flag issues that would cause wrong work, blocked work, hidden decisions, or stale authority.
-- Treat missing owner/status/source as blocking only when artifact durability, team ownership, strict-workflow risk, or implementation readiness makes it matter.
-- Do not nitpick style.
-- Review can pass.
-- Do not edit files.
-- Do not resolve owner decisions.
-- Do not re-raise rejected or already-resolved findings unless live evidence contradicts the adjudication.
-- If review does not pass, classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
-- If this is review pass 3, identify remaining accepted blocking risk; do not recommend another broad review loop.
+A pass is valid. Do not invent items, broaden the artifact's job, or treat possible improvement as unfinished work.
 
-Output:
+## Artifact And Intended Use
 
-Status: Pass | Blocking | Non-blocking | Question
+- Artifact: [path]
+- Type: [working record | spec | PRD | issue | API contract | technical design | migration contract | plan | decision record | ADR | handoff | other]
+- Reviewed state: [revision, hash, or other identity]
+- Intended use: [decision or future action this artifact must support]
+- Dependency order: [upstream -> downstream, or standalone]
 
-Findings:
-- [Blocking | Non-blocking | Question] [location]: [issue] - [why it matters]
+## Accepted Outcome And Non-Goals
 
-Recommendation:
-[Proceed | revise artifact | ask owner decision | gather evidence]
+- Outcome: [accepted outcome]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
+- Owner decisions: [settled decisions or none]
+- Unresolved questions: [questions or none]
+
+## Source Truth
+
+- [code, tests, policies, ADRs, established behavior, upstream artifacts]
+
+## Evidence And Known Gaps
+
+- Supporting evidence: [evidence or none]
+- Known gaps: [gaps or none]
+
+## Review Scope
+
+- Review number: [1 | 2 | 3]
+- Material lenses: [source alignment | fitness and sufficiency | decision clarity | evidence and acceptance | behavior and failure contract | dependency integrity | scope and minimality | clarity and continuity]
+
+For Review 2 or 3:
+- Prior items and adjudication: [Accepted | Rejected | Open]
+- Revisions and new evidence: [bounded changes and evidence]
+- Affected dependencies: [dependencies or none]
+- Remaining risk: [narrow unresolved scope]
+
+## Judge The Artifact By Its Job
+
+- **Working Record:** accurate living task memory with recoverable slices and decisions, compact evidence pointers, and one next useful action.
+- **Spec or durable content artifact:** accepted content, behavior, boundaries, evidence, and uncertainty needed for its stated use.
+- **Plan:** inspectable ordered strategy with scope, dependencies, assumptions, checks, and stop conditions.
+- **Decision record or ADR:** decision, owner, alternatives, rationale, consequences, and revisit or supersession conditions.
+- **Handoff:** point-in-time continuation package that preserves what its recipient needs without replacing live task memory.
+- **Other artifact:** its stated purpose without taking over another artifact's job.
+
+## Check
+
+Apply only the selected lenses:
+
+- The artifact agrees with accepted requirements, owner decisions, and live facts.
+- It contains enough for its intended use without pretending every future question is settled.
+- Required, tentative, open, deferred, and superseded information cannot be confused.
+- Load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
+- Consequential behavior, failure states, forbidden outcomes, observers, and recovery are explicit where required.
+- Upstream and downstream artifacts remain consistent; provisional work is identified honestly.
+- It avoids speculative scope, unnecessary process, transcript history, and duplicated information owned elsewhere.
+- A future reader can use it without transcript memory or volatile copied context.
+
+Do not demand exhaustive edge cases. A possible condition is not an Issue unless the artifact's intended use requires it, evidence shows it matters, or omission creates material risk. Use Question when expected behavior is undefined, Needs evidence when support is missing, and Improvement for useful content not required by this boundary.
+
+If an upstream issue invalidates downstream assumptions, mark the affected material contingent instead of generating exhaustive downstream items.
+
+For Review 2 or 3, inspect only accepted revisions, affected dependencies, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior revision; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another revision. Review 3 is final for this cycle; do not recommend Review 4.
+
+## Classify Review Items
+
+- **Blocking Issue:** supported defect or risk that must be resolved before the artifact guides its intended use.
+- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirement, or owner decision is unclear.
+- **Needs evidence:** a load-bearing claim or condition cannot be established.
+- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize revision.
+
+A Blocking Issue must include its exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
+
+## Determine The Judgment
+
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
+
+## Output
+
+Review type: independent
+Review number: [1 | 2 | 3]
+Artifact: [reviewed artifact]
+Intended use: [reviewed boundary]
+Reviewed state: [state identity]
+Judgment: Pass | Non-blocking | Inconclusive | Blocking
+Reasoning: [concise evidence-backed judgment]
+Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
+
+### Review Items
+
+#### Issues — Blocking
+- [location, issue, violated source or responsibility, evidence, consequence, smallest safe correction]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [concern, missing evidence, evidence needed]
+
+#### Improvements
+- [improvement, benefit, supporting evidence]
+
+Dependencies affected: [dependencies or none]
+Evidence gaps: [unproved claims or none]
 ```
+
+## Calibration
+
+Use a high evidence bar, not a high item count. Lead with the few items that can change the artifact's fitness judgment. Prior review, artifact length, author confidence, or polished language does not establish fitness.
+
+The review is evidence for adjudication, not authority over source truth, owner decisions, revisions, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/SKILL.md

@@ -1,101 +1,126 @@
 ---
 name: review-work
-description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, handling repeated review loops, or checking work before merge/handoff.
+description: Use when reviewing implementation or integrated work, whether reviewing work you produced or acting as an independent reviewer.
 ---
 
 # Review Work
 
-Evaluate review feedback before applying it.
+Judge whether work is correct, suitable, and sufficiently evidenced for its intended boundary.
 
-Review feedback is not approval to change source of truth.
+Review provides judgment. [Verify Work](../verify-work/SKILL.md) establishes what direct evidence proves. Review may challenge whether that evidence is sufficient, but it does not replace verification or authorize changes.
 
-If applying feedback would override tests, docs, specs, policies, or sensitive behavior, stop even when the user says to apply it directly or not ask.
+## Choose The Review Role
 
-If you block any feedback item, end the final response with a direct choice question for that item. This still applies after fixing unrelated items.
+Choose the role before reviewing:
 
-External review is evidence, not authority. Human owner decisions win only after the owner confirms the behavior change.
+- **Self-review:** you produced the work. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority and re-verify. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
+- **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
 
-Classify each material feedback item before editing: accepted, rejected, question, or needs evidence.
+Reading this skill does not create independence. If you produced the work, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
 
-A non-passing review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+## Establish The Boundary
 
-The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+Understand:
 
-Hard stop: if the work has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+- the accepted outcome, requirements, and non-goals;
+- the implementation, diff, or integrated work product;
+- relevant Specs, Plans, tests, policies, ADRs, and established behavior;
+- verification evidence and known gaps;
+- risks and interactions material to the future action this review protects.
 
-Read `references/reviewer-prompt.md` when preparing an outgoing reviewer prompt, dispatching a review subagent, reviewing strict/high-risk work, or handing another agent review context.
+Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Read [the security risk lens](references/security-risk-lens.md) when the work changes a security-relevant boundary.
 
-## Review Loop Budget
+## Review Proportionately
 
-Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+Apply only lenses that can materially change the result:
 
-Three review passes is the hard cap for the same work and scope. Do not request a fourth review to chase a clean pass.
+- **Alignment and correctness:** accepted behavior is implemented without invention or omission.
+- **Regression and integration:** affected callers, states, and components remain correct together.
+- **Failure and risk:** relevant errors, recovery, permissions, data, and compatibility behave safely.
+- **Evidence:** verification supports the claims and exercised the required boundary.
+- **Design and minimality:** complexity and coordination are justified by requirements or observed failures.
+- **Maintainability:** the work can be understood and changed without hidden policy or fragile coupling.
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, module/interface design, implementation, or reviewer context is wrong or too thin.
+A pass is valid. Do not invent items, report preferences or hypothetical completeness, reopen intentional deferrals, or treat ordinary reversible choices as issues.
 
-Non-blocking findings and reviewer questions do not fail the work by default. Classify them, then defer, ask, gather evidence, or accept.
+A possible edge case is not an Issue merely because it can be imagined:
 
-## Incoming Feedback
+```text
+Required failure path is missing -> Issue
+Unsettled expected behavior -> Question
+Plausible concern without reachability or consequence evidence -> Needs evidence
+Useful resilience outside this boundary -> Improvement or omit
+Repeated related corrections -> diagnose the shared cause
+```
 
-Before editing:
+## Classify Independent Review Items
 
-- Read the full feedback.
-- Inspect the relevant code, tests, docs, and prior decisions.
-- Restate unclear feedback as a technical requirement.
-- Separate blocking issues from suggestions.
-- Check whether the feedback matches this codebase.
-- Check whether a finding is stale, already resolved, equivalent, or based on missing context.
-- Check whether repeated findings are design pressure: shallow module, bad seam, edge-case churn, or broad refactor from a narrow comment.
+- **Blocking Issue:** a supported defect, regression, omission, or risk that must be resolved before crossing the reviewed boundary.
+- **Non-blocking Issue:** a real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirements, or an owner decision is unclear.
+- **Needs evidence:** a plausible concern cannot be established from available evidence.
+- **Improvement:** a materially useful enhancement not required by this boundary. It does not affect judgment or authorize implementation.
 
-Do not blindly apply vague, broad, or sensitive feedback.
+A Blocking Issue must name the exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
 
-Do not use performative agreement. State the technical finding or act.
+Use the most consequential applicable judgment:
 
-## Stop Conditions
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
 
-Stop before editing when feedback:
+Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the work passes.
 
-- Is ambiguous.
-- Contradicts tests, docs, specs, policies, ADRs, or established behavior.
-- Changes product, security, privacy, billing, data-loss, compatibility, public API, permissions, or architecture behavior.
-- Requires guessing what the reviewer meant.
-- Would cause a broad refactor from a narrow comment.
+## Adjudicate And Route
 
-Name the conflict or uncertainty and ask which path to follow. Recommend the path supported by evidence.
+After independent review, the receiving active agent adjudicates each item against the work, source truth, and evidence:
 
-## Applying Feedback
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
+- **Open:** a question or evidence gap prevents acceptance or rejection.
 
-For multi-item review:
+Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
 
-- Apply independent clear items.
-- Stop blocked items.
-- If items interact, clarify before implementing the set.
+Route from the adjudicated result:
 
-When feedback is clear and correct and the current route is an apply-fixes pass:
+- **Pass:** proceed.
+- **Non-blocking:** proceed with explicit deferrals.
+- **Inconclusive:** gather the missing evidence or decision.
+- **Blocking:** do not cross the boundary; re-enter the narrowest owning activity, defer, or stop.
 
-- Apply one item at a time.
-- Keep the diff scoped to the review item.
-- Verify each fix.
-- Push back on incorrect feedback with code, tests, or docs.
+Review findings are evidence, not commands. They do not authorize edits. Accepted implementation corrections leave review and return to [Execute Work](../execute-work/SKILL.md); they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
 
-Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+When correction authority is not already explicit, ask once for either:
 
-If accepted findings expose shallow modules, bad seams, or complexity spread, use `../design-for-depth/SKILL.md` and route backward before broad refactoring.
+- the accepted corrections plus one warranted focused follow-up review; or
+- the accepted corrections alone when direct evidence can settle the changed boundary.
 
-## Outgoing Review
+Then wait for the user's response. Do not correct or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded correction or review.
 
-When reviewing work, lead with bugs, regressions, missing tests, and requirement gaps.
+Verify authorized corrections. Run a follow-up only when the changed boundary still needs independent judgment and that dispatch is authorized. Do not change tests, Specs, policies, or accepted behavior merely to satisfy a reviewer or obtain Pass.
 
-Classify findings:
+## Limit The Review Cycle
 
-- Blocking: must fix before proceeding.
-- Non-blocking: can defer.
-- Question: needs owner decision or more evidence.
+For one independently reviewed work state and boundary:
 
-Review can pass. Do not invent issues to justify the review.
+1. Review 1 is the normal broad review.
+2. Review 2, when needed and authorized, focuses on accepted corrections, affected interactions, and remaining risk.
+3. Review 3 is exceptional, authorized separately, and final for that cycle.
 
-When asking another agent to review, give it source truth, changed files, risk lenses, and pass/fail criteria. Do not hand it only the previous agent's summary or your chat history.
+The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the work may proceed, remain blocked, re-enter another owner, defer, or stop.
 
-Set review subagent timeouts above 10 minutes; default to 15 minutes (`timeoutMs: 900000`). If a review times out, do not reduce review depth to dodge the timeout. Increase the timeout or ask before narrowing scope.
+After Review 2 is adjudicated Blocking, stop before proposing another correction or Review 3. Classify its relationship to the prior correction:
 
-For second and later review iterations, update the prompt with prior findings, owner clarifications, accepted/rejected findings, changed files, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior correction, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another patch.
+- If it is an independent clear local defect with a supported cause, return directly to its owning activity and state why diagnosis is unnecessary.
+
+A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and correction boundary are understood, not a third attempt to discover the cause through patches. Workflow may later establish a new cycle only for a materially new reviewed state and boundary; local fixes, a different reviewer, or renamed scope do not reset it.
+
+## Report
+
+For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change the route.
+
+For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, remaining open items, and authorized or proposed next route.
+
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.

package/skills/review-work/references/reviewer-prompt.md

@@ -1,97 +1,134 @@
-# Reviewer Prompt
+# Independent Work Reviewer Contract
 
-Use this when preparing an outgoing reviewer prompt or subagent review context.
+Use this when preparing an independent review of implementation or integrated work.
 
-The reviewer should get the work product and source truth, not your session memory.
+The reviewer did not produce the work. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the author's summary, reasoning, or claimed result.
 
-## Include
+## Required Context
 
-- What was implemented or changed.
-- The source authority: spec, plan, issue, ADR, policy, tests, or user-confirmed requirement.
-- Files or diff range to inspect. If no git range exists, list concrete files.
-- Claimed verification and what still needs independent checking.
-- Risk lenses relevant to the work.
-- Required output shape and severity labels.
-- Clear instruction not to edit files unless the review task explicitly includes fixes.
-- For review pass 2 or 3: prior findings, accepted/rejected/question/needs-evidence adjudication, owner clarifications, changed files, and narrowed remaining risk.
+Provide:
 
-Do not forward only a previous-agent summary. Summaries are useful context, not authority.
+- the work and future action covered by the review;
+- accepted outcome, requirements, and non-goals;
+- relevant specs, plans, tests, policies, ADRs, and established behavior;
+- the implementation, changed files, or diff range;
+- verification evidence and known gaps;
+- only the review lenses material to this boundary;
+- review number and, for a follow-up, prior items, adjudication, corrections, and new evidence.
 
-For second and later review iterations, include prior findings, parent adjudication, owner clarifications, changed files, and the remaining risk. Do not rerun the same broad prompt after the situation narrows.
+When state transitions or proof integrity matter, also provide the invariant or state owner, affecting paths, observing mechanism, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, and fidelity limits.
 
-## Risk Lenses
+## Reviewer Prompt
 
-Pick the lenses that fit the work:
+```md
+# Independent Work Review
 
-- Source-truth alignment: implementation matches spec, plan, docs, tests, and established behavior.
-- Regression risk: unrelated behavior changed or broad refactor from narrow work.
-- Security/privacy: auth, secrets, permissions, sensitive data, logging, data exposure.
-- Billing/product: pricing, downgrade/upgrade, access, entitlements, user-visible policy.
-- Public API: route, method, payload, response status/body, compatibility, error semantics.
-- Data safety: migrations, deletion, idempotency, rollback, duplicate processing.
-- Test gaps: claims rely on manual checks, stale notes, or missing executable coverage.
-- Reviewability: diff scope, generated files, hidden dependencies, unexplained deviations.
+Review work you did not produce. Inspect the supplied work, source truth, and evidence directly. Report review items without editing. The review ends with this report; do not fix items, dispatch a follow-up, or keep reviewing merely to obtain Pass.
 
-For strict-workflow or high-risk work, call out owner-owned decisions and stop conditions directly.
+A pass is valid. Do not invent items, broaden scope, or treat possible improvement as unfinished work.
 
-## Output Shape
+## Boundary
 
-Ask the reviewer to lead with findings, ordered by severity:
+[Work and future action this review covers.]
 
-```md
-## Findings
+## Accepted Outcome And Non-Goals
 
-### Blocking
-- [file:line] Title
-  - What is wrong:
-  - Why it matters:
-  - Minimal fix direction:
+- Outcome: [required result]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
 
-### Non-blocking
-- ...
+## Source Truth
 
-### Questions
-- ...
+- [specs, plans, tests, policies, ADRs, and established behavior]
 
-## Assessment
+## Work Product
 
-Ready to proceed: Yes | No | With fixes
-Reasoning: ...
-```
+- Reviewed state: [commit, tree, diff, or other identity]
+- Work: [diff range, changed files, implementation, or integrated result]
 
-If review passes, the reviewer should say that clearly and name any residual test gaps or assumptions.
+## Verification Evidence
 
-If review does not pass, the reviewer should classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
+- Checks and results: [commands, observations, and results]
+- Known gaps: [gaps or none]
+- When relevant: [state owner, affecting paths, observer, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint, fidelity limits]
 
-Do not ask reviewers to invent issues. A clean pass is valid.
+## Review Scope
 
-If this is review pass 3, ask for remaining accepted blocking risk only. Do not recommend a fourth broad review loop.
+- Review number: [1 | 2 | 3]
+- Material lenses: [alignment and correctness | regression and integration | failure and risk | evidence | design and minimality | maintainability]
 
-## Minimal Template
+For Review 2 or 3:
+- Prior items and adjudication: [Accepted | Rejected | Open]
+- Clarifications: [settled decisions or none]
+- Corrections and new evidence: [changes and verification]
+- Remaining risk: [narrow unresolved scope]
 
-```md
-# Reviewer Prompt
+## Check
 
-Review the completed work. Do not edit files.
+Apply only the selected lenses:
 
-## Work Summary
+- The work satisfies accepted behavior without invention or omission.
+- Affected callers, states, and components remain correct together.
+- Relevant failure paths and material risks are handled safely.
+- Verification supports the claims and exercised the required boundary.
+- Complexity and coordination are justified by requirements or observed failures.
+- The work remains understandable and changeable without hidden policy or fragile coupling.
 
-[What changed, from the implementer summary or observed files.]
+Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed.
 
-## Source Truth
+A possible edge case is not an Issue without accepted behavior, observed reachability, or material risk. Use Question when expected behavior is unclear, Needs evidence when reachability or consequence is unsupported, and Improvement for useful resilience not required by the boundary.
 
-- [spec/plan/policy/test paths]
+For Review 2 or 3, inspect only accepted corrections, affected interactions, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior correction; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another patch. Review 3 is final for this cycle; do not recommend Review 4.
 
-## Files Or Range
+## Classify Review Items
 
-- [changed files or git range]
+- **Blocking Issue:** supported defect or risk that must be resolved before crossing this boundary.
+- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirement, or owner decision is unclear.
+- **Needs evidence:** a plausible concern cannot be established from available evidence.
+- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize implementation.
 
-## Check
+A Blocking Issue must include its exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
 
-- [risk lenses and concrete requirements]
-- [if pass 2 or 3: prior findings, adjudication, owner clarifications, changed files, and narrowed remaining risk]
+## Determine The Judgment
+
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
 
 ## Output
 
-Lead with findings by severity. Include file:line, violated requirement, risk, and minimal fix direction. If there are no findings, say so and list residual risk/test gaps.
+Review type: independent
+Review number: [1 | 2 | 3]
+Boundary: [reviewed work and future action]
+Reviewed state: [state identity]
+Judgment: Pass | Non-blocking | Inconclusive | Blocking
+Reasoning: [concise evidence-backed judgment]
+Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
+
+### Review Items
+
+#### Issues — Blocking
+- [location, issue, violated source, evidence, consequence, smallest safe correction]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [concern, missing evidence, evidence needed]
+
+#### Improvements
+- [improvement, benefit, supporting evidence]
+
+Evidence gaps: [unproved claims or none]
 ```
+
+## Calibration
+
+Use a high evidence bar, not a high item count. Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or author confidence does not establish correctness.
+
+The review is evidence for adjudication, not authority over source truth, owner decisions, corrections, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.