@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/review-work/SKILL.md

@@ -1,128 +1,171 @@
 ---
 name: review-work
-description: Use when reviewing implementation or integrated work, whether reviewing work you produced or acting as an independent reviewer.
+description: Use when judging implementation or integrated work through self-review or independent review, or when adjudicating a returned independent review report.
 ---
 
 # Review Work
 
-Judge whether work is correct, suitable, and sufficiently evidenced for its intended boundary.
+Judge whether implementation or integrated work is correct, suitable, and sufficiently evidenced for a named boundary.
 
-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.
+Review provides judgment. [Verify Work](../../skills/verify-work/SKILL.md) establishes what direct evidence proves. Review may find that evidence insufficient, but it does not replace verification or authorize changes.
 
-## Choose The Review Role
+## Select One Route
 
-Choose the role before reviewing:
+Choose the route before reviewing:
 
-- **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.
+- **Self-review:** you produced the reviewed state.
+- **Independent review:** you did not produce the reviewed state and are reviewing from a separate context.
+- **Adjudication:** an independent reviewer returned a report and you are deciding what its findings establish and what follows.
 
-Reading this skill does not create independence. If you produced the work, do not present your own judgment as independent review. Before preparing or performing a separately selected independent review, read the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md).
+Self-review and independent review use the same review kernel below. Adjudication consumes a completed review; it is not another review.
+
+Do not cross roles inside an independent reviewer context. The independent reviewer reports and stops. The receiving agent may then enter adjudication.
 
 ## Establish The Boundary
 
-Understand:
+Identify only what the judgment needs:
 
-- the accepted outcome, requirements, and non-goals;
-- the implementation, diff, or integrated work product;
+- the future action or boundary the review protects;
+- the exact implementation, diff, commit, or integrated state;
+- accepted outcome, requirements, and non-goals;
 - 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.
+- risks and interactions capable of changing whether the boundary may be crossed.
+
+Inspect the reviewed state and source truth directly. Do not judge only the producer's summary, reasoning, or claimed result.
 
-Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Before reviewing work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, or failure behavior with security consequences, read the [Security Risk Lens](references/security-risk-lens.md).
+Before reviewing changes to trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies, code execution, or security-sensitive failure behavior, read the [Security Risk Lens](references/security-risk-lens.md).
 
-Review Work owns the review boundary, lenses, and judgment. When source inspection branches among several plausible observers or is likely to be broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one environment interaction. It returns evidence to the same review role. Skip it for an obvious diff, file, or source-truth read.
+When inspection could branch broadly among several useful observers, use [Action Selection](../../skills/action-selection/SKILL.md). Skip it for an obvious diff, file, test, or source-truth read.
 
-## Review Proportionately
+## Apply The Shared Review Kernel
 
-Apply only lenses that can materially change the result:
+Use only lenses capable of changing the boundary judgment:
 
 - **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.
+- **Failure and risk:** material errors, recovery, permissions, data, and compatibility behave safely.
+- **Evidence:** verification supports the claims at the required observing 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.
+- **Maintainability:** behavior remains understandable and changeable without hidden policy or fragile coupling.
 
-A pass is valid. Do not invent items, report preferences or hypothetical completeness, reopen intentional deferrals, or treat ordinary reversible choices as issues.
+Review the resulting state, not the producer's intention. Use a high evidence bar, not a high item count. Finding no material issue is valid.
 
-A possible edge case is not an Issue merely because it can be imagined:
+### Classify Before Calling Something An Issue
 
-```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
-```
+Ask in order:
 
-## Classify Independent Review Items
+1. **Is the required behavior or source truth settled?**
+   - No: **Question**.
+2. **Are reachability and material consequence supported?**
+   - No: **Needs evidence**.
+3. **Does the reviewed boundary require correction?**
+   - Yes, and the boundary cannot be crossed safely: **Blocking Issue**.
+   - Yes, but correction can be deferred safely: **Non-blocking Issue**.
+4. **Would the change merely be useful beyond this boundary?**
+   - Omit it by default.
+   - Use **Improvement** only when materially relevant or explicitly requested.
 
-- **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.
+A material **Needs evidence** observation must name the claim, required observing boundary, available evidence and its limit, why the gap affects judgment, and the smallest evidence that could disagree.
 
-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 turn preferences, imagined edge cases, intentional deferrals, or hypothetical completeness into Issues.
 
-Use the most consequential applicable judgment:
+An Issue must identify:
 
-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.
+- the exact location or affected path;
+- the violated requirement, source truth, or invariant;
+- supporting evidence;
+- the concrete consequence for the reviewed boundary.
 
-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.
+For a Blocking Issue, state why the boundary cannot safely be crossed. Describe correction constraints or the owning activity to re-enter. Recommend a specific correction only when it is directly supported rather than one of several material alternatives.
 
-## Adjudicate Independent Review And Route
+## Self-Review
 
-After independent review, the receiving active agent adjudicates each material item against the work, source truth, and evidence rather than forwarding the report:
+Apply the complete shared kernel to your own work. Self-review uses the same technical scrutiny as independent review but does not create independence.
 
-- **Accepted:** supported and applicable. State the actual implementation problem, boundary consequence, and whether its cause is supported, unnecessary to select a bounded correction, or uncertain.
-- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread. State why.
-- **Open:** a question or evidence gap prevents acceptance or rejection. State the concern, potential consequence, and missing evidence or decision.
+When evidence supports a clear local defect and existing authority covers its correction:
 
-A reviewer's suggested correction may bound an item, but it does not establish the cause or select the remedy. Confirm whether each accepted Issue is Blocking or Non-blocking, derive the adjudicated judgment, and do not accept the reviewer's overall judgment separately.
+1. return to the producing activity;
+2. correct the defect;
+3. re-verify the affected boundary;
+4. repeat only the affected review lenses once.
 
-- **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.
+Do not create formal review items, a judgment, a review number, or a review cycle for self-review. Do not label it independent.
 
-### Decide Whether Independent-Review Remediation Is Ready
+Return unresolved material issues to [Workflow](../../skills/workflow/SKILL.md). Use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) when the cause is unclear or correction repeats. Use [Decision Gate](../../skills/decision-gate/SKILL.md) when accepted behavior or a user-owned choice is unsettled.
 
-Remediation is ready when accepted behavior, the problem and consequence, and enough causal or decision basis support a bounded correction. When the finding is clear, the correction local, verification direct, and no material alternative or user choice remains, include adjudication and remediation in the same assistant response.
+## Independent Review
 
-Use the current response for a separate problem checkpoint when findings interact, the cause matters but remains unsupported, accepted assumptions or design are challenged, materially different corrections remain, or user input could change the approach:
+Before preparing or performing a separately selected independent review, read the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md).
 
-1. Report the adjudication, problem and consequence, cause status, settled constraints, and controlling question or evidence.
-2. Name [Discuss](../discuss/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), evidence gathering, or another affected owner as the next route, then stop and wait.
+Use supplied and already available evidence. Do not start a missing active check unless the review authority explicitly covers that exact check. Otherwise report **Needs evidence** with the claim and required observing boundary. When an exact check is covered, apply Verify Work's check-result and claim-result semantics; the review still owns the fitness judgment.
+
+Inspect and report without editing. Do not:
+
+- adjudicate your own findings;
+- select among materially different remedies;
+- perform corrections;
+- dispatch another review;
+- continue merely to obtain Pass.
+
+The independent review ends with its report.
+
+Independent judgments are:
+
+1. **Blocking:** at least one Blocking Issue exists.
+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 do not change the judgment or authorize implementation.
+
+## Adjudicate A Returned Review
+
+Before adjudicating an independent report, read [Adjudicate Work Review](references/adjudicate-work-review.md).
+
+Assess every material item against the reviewed state, source truth, and available evidence:
+
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
+- **Open:** missing evidence or a decision prevents acceptance or rejection.
+
+Do not separately accept the reviewer's overall judgment. Derive the adjudicated judgment from the dispositions.
+
+Findings are evidence, not commands or correction authority.
+
+- **Pass:** proceed.
+- **Non-blocking:** proceed with explicit deferrals.
+- **Inconclusive:** obtain the missing evidence or decision.
+- **Blocking:** do not cross the boundary; select the narrowest owning route.
 
-Continue remedy selection only when a later user turn or new evidence supplies enough support. Do not request implementation authority before selecting a remedy or wait for the user to elicit the missing analysis. The checkpoint is not another review and creates no correction or dispatch authority.
+When remediation is ready, state the supported problem, correction, rationale, verification boundary, authority state, and whether focused follow-up review remains justified. Actual correction returns to [Execute Work](../../skills/execute-work/SKILL.md).
 
-A remediation-ready route states the proposed correction and rationale, verification boundary, whether focused follow-up is needed, and authority status. Findings are evidence, not commands, and do not authorize edits. Accepted corrections return to [Execute Work](../execute-work/SKILL.md) and may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
+## Limit Independent Review
 
-Use existing correction authority when it covers the result. Otherwise ask once for the correction and any warranted focused follow-up; omit follow-up when direct evidence can settle the changed boundary. Then wait; do not correct or dispatch a follow-up from the request itself. Verify authorized corrections and run 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.
+Treat review count as a budget, not a schedule.
 
-## Limit The Review Cycle
+- **Review 1:** the first selected independent review; broad by default.
+- **Review 2:** a separately selected focused follow-up when accepted corrections, new evidence, affected interactions, or remaining risk still require independent judgment.
+- **Review 3:** exceptional, separately authorized, and final. Use it only after the cause and correction boundary are understood.
 
-For one independently reviewed work state and boundary:
+A review report always ends its review. Remediation does not automatically authorize or require follow-up 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, separately authorized, and final.
+If Review 2 remains Blocking:
 
-The budget is a cap, not dispatch authority. Do not request Review 4; return control to Workflow at the cap.
+- diagnose when the blocker repeats, extends, invalidates, or exposes another consequence of prior correction, or when its cause remains uncertain;
+- return an independent clear local defect to its owner when diagnosis would add no useful understanding;
+- do not automatically correct and dispatch Review 3.
 
-After Review 2 is adjudicated Blocking, stop before another correction or Review 3:
+Do not request Review 4. A different reviewer, local correction, or renamed scope does not reset the budget. Workflow may establish a new cycle only for a materially new reviewed state and boundary.
 
-- 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 first.
-- If it is an independent clear local defect with a supported cause, return to its owner and state why diagnosis is unnecessary.
+Self-review does not consume this budget.
 
-Diagnosis follows adjudicated evidence, not reviewer judgment alone. Review 3 is final judgment after the cause and correction boundary are understood, not another attempt to discover them through patches. Workflow may 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.
+## Stop
 
-## Report
+Stop when the selected route has produced its bounded result:
 
-For self-review, report no formal result. Correct clear local issues and surface only unresolved material issues that change the route.
+- self-review: the supported state is accepted or a material issue is routed;
+- independent review: the report is complete;
+- adjudication: material items are disposed and the next route is explicit.
 
-For independent review, use the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md) and stop with its report. The receiving agent then reports the reviewer and adjudicated judgments, each material item's outcome and reason, and either the problem checkpoint or remediation-ready route defined above. Omit empty groups and support the result with source or evidence rather than confidence.
+Do not review until Pass, use review to authorize correction, or turn optional improvement into unfinished work.

package/skills/review-work/references/adjudicate-work-review.md

@@ -0,0 +1,97 @@
+# Adjudicate Work Review
+
+Read this after an independent work review returns and before selecting what follows from its report.
+
+Adjudication belongs to the receiving active agent. It tests the report against the reviewed state, source truth, and evidence. It is not independent review and does not inherit the reviewer's authority or judgment.
+
+## Dispose Each Material Item
+
+For every material item, choose one disposition.
+
+### Accepted
+
+State:
+
+- the supported implementation problem;
+- its consequence for the reviewed boundary;
+- whether it is Blocking or Non-blocking;
+- whether its cause is supported, unnecessary to select a clear local correction, or uncertain.
+
+### Rejected
+
+State the concrete reason: unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
+
+### Open
+
+State:
+
+- the unresolved concern;
+- its potential boundary consequence;
+- the missing evidence or owner decision.
+
+When factual evidence is missing, restate the item as a Verify Work input: claim, required observing boundary, available evidence and its limit, and the smallest evidence that could disagree.
+
+A suggested correction may help explain a finding, but it does not establish cause, select the remedy, or authorize implementation.
+
+After disposing the items, derive the adjudicated judgment. Do not separately accept the reviewer's overall judgment.
+
+- **Pass:** no accepted Issues or material Open items remain.
+- **Non-blocking:** only accepted Non-blocking Issues remain.
+- **Inconclusive:** a material Open item prevents judgment.
+- **Blocking:** at least one accepted Blocking Issue remains.
+
+## Use Verification Results
+
+Route a known material evidence gap through [Workflow](../../../skills/workflow/SKILL.md) to [Verify Work](../../../skills/verify-work/SKILL.md). Verification produces factual evidence; it does not revise the reviewer's report or determine the review judgment.
+
+- **Supported:** re-adjudicate the evidence gap. Do not infer Pass.
+- **Contradicted:** re-adjudicate against source truth; the result may establish an Issue, invalidate one, or expose a source conflict.
+- **Inconclusive:** keep the item Open. The adjudicated review remains Inconclusive when the gap is material.
+- **Unavailable:** keep the item Open and state why the required boundary cannot currently be observed.
+
+Select focused independent follow-up only when the new evidence still requires judgment from a separate context.
+
+## Decide Whether Remediation Is Ready
+
+Remediation is ready when:
+
+- required behavior is settled;
+- the problem and boundary consequence are supported;
+- enough cause or decision basis exists to bound a correction;
+- affected interactions and dependencies are known sufficiently;
+- no material alternative or user-owned choice remains.
+
+When remediation is ready, state:
+
+- the proposed correction and rationale;
+- affected behavior and locations;
+- required ordering or constraints;
+- regression evidence and verification boundary;
+- whether focused independent follow-up remains justified;
+- the authority state.
+
+Use existing correction authority only when it covers that result. Otherwise propose the correction and any warranted follow-up once, then wait. A finding, adjudication, or selected review does not authorize mutation.
+
+Actual correction returns to [Execute Work](../../../skills/execute-work/SKILL.md). Preserve the accepted behavior; do not change tests, Specs, policies, or source truth merely to satisfy a reviewer or obtain Pass.
+
+## Route When Remediation Is Not Ready
+
+- unclear or repeated cause: [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md);
+- unsettled direction or materially different remedies: [Discuss](../../../skills/discuss/SKILL.md);
+- user-owned choice or source conflict: [Decision Gate](../../../skills/decision-gate/SKILL.md);
+- missing factual support: route the named claim through [Workflow](../../../skills/workflow/SKILL.md) to [Verify Work](../../../skills/verify-work/SKILL.md);
+- uncovered correction: propose the bounded correction and wait.
+
+When findings interact, assumptions are challenged, or user input could change the remedy, report a problem checkpoint and stop before selecting or executing a correction.
+
+## After Authorized Correction
+
+Verify the affected boundary and perform ordinary self-review.
+
+Select focused independent follow-up only when accepted corrections, affected interactions, new evidence, or remaining risk still require judgment from a separate context. Do not dispatch follow-up merely because Review 1 found an Issue or because remediation occurred.
+
+If Review 2 remains Blocking, adjudicate it before acting again. Diagnose a repeated, extending, invalidating, or causally uncertain blocker. Return an independent clear local defect to its owner when diagnosis would add no useful understanding. Review 3 remains exceptional, separately authorized, and final.
+
+## Stop
+
+Stop when every material item is Accepted, Rejected, or Open; the adjudicated judgment is supported; and the next route and authority state are explicit.

package/skills/review-work/references/independent-work-reviewer-contract.md

@@ -2,7 +2,7 @@
 
 Read this before preparing or performing a separately selected independent review of implementation or integrated work.
 
-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.
+The reviewer did not produce the reviewed state. Give them the work product, source truth, and evidence needed to judge it directly. Do not provide only the producer's summary, reasoning, or claimed result.
 
 ## Required Context
 
@@ -10,11 +10,12 @@ Provide:
 
 - the work and future action covered by the review;
 - accepted outcome, requirements, and non-goals;
-- relevant specs, plans, tests, policies, ADRs, and established behavior;
+- 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.
+- active evidence authority: none, or each exact covered check with its expected evidence and stop condition;
+- review number and, for follow-up, prior items, adjudication, corrections, and new evidence.
 
 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.
 
@@ -23,13 +24,17 @@ When state transitions or proof integrity matter, also provide the invariant or
 ```md
 # Independent Work Review
 
-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.
+Review work you did not produce. Inspect the supplied work, source truth, and evidence directly. Report without editing. The review ends with this report; do not adjudicate findings, fix items, dispatch follow-up, or continue merely to obtain Pass.
 
-A pass is valid. Do not invent items, broaden scope, or treat possible improvement as unfinished work.
+A pass is valid. Use a high evidence bar, not a high item count. Do not broaden scope or treat possible improvement as unfinished work.
+
+Use supplied and already available evidence. Do not start a missing active check unless the review contract explicitly authorizes that exact check. Otherwise report **Needs evidence** with the claim and required observing boundary. When an exact check is covered, apply Verify Work's check-result and claim-result semantics; active evidence does not authorize editing or broaden the review.
 
 ## Boundary
 
-[Work and future action this review covers.]
+- Protected future action: [boundary]
+- Reviewed state: [commit, tree, diff, or other exact identity]
+- Work: [diff range, changed files, implementation, or integrated result]
 
 ## Accepted Outcome And Non-Goals
 
@@ -39,12 +44,7 @@ A pass is valid. Do not invent items, broaden scope, or treat possible improveme
 
 ## Source Truth
 
-- [specs, plans, tests, policies, ADRs, and established behavior]
-
-## Work Product
-
-- Reviewed state: [commit, tree, diff, or other identity]
-- Work: [diff range, changed files, implementation, or integrated result]
+- [Specs, Plans, tests, policies, ADRs, and established behavior]
 
 ## Verification Evidence
 
@@ -56,8 +56,10 @@ A pass is valid. Do not invent items, broaden scope, or treat possible improveme
 
 - Review number: [1 | 2 | 3]
 - Material lenses: [alignment and correctness | regression and integration | failure and risk | evidence | design and minimality | maintainability]
+- Active evidence authority: [none | exact covered check, expected evidence, and stop condition]
 
 For Review 2 or 3:
+
 - Prior items and adjudication: [Accepted | Rejected | Open]
 - Clarifications: [settled decisions or none]
 - Corrections and new evidence: [changes and verification]
@@ -67,41 +69,44 @@ For Review 2 or 3:
 
 Apply only the selected lenses:
 
-- 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.
+- accepted behavior is implemented without invention or omission;
+- affected callers, states, and components remain correct together;
+- material failure paths and risks are handled safely;
+- verification supports the claims at the required boundary;
+- complexity and coordination are justified;
+- the work remains understandable without hidden policy or fragile coupling.
 
 Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed.
 
-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.
+Before calling something an Issue, ask:
 
-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.
+1. Is required behavior or source truth settled? If not, use **Question**.
+2. Are reachability and material consequence supported? If not, use **Needs evidence**.
+3. Does the boundary require correction? Use **Blocking Issue** when it cannot be crossed safely, otherwise **Non-blocking Issue** when correction can be deferred safely.
+4. Is the change merely useful beyond this boundary? Omit it by default; use **Improvement** only when materially relevant or requested.
 
-## Classify Review Items
+A **Needs evidence** item must identify the claim, required observing boundary, available evidence and its limit, why the gap affects judgment, and the smallest evidence that could disagree.
 
-- **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.
+A Blocking Issue must identify the exact location, violated requirement or source truth, evidence, concrete boundary consequence, and correction constraints or owning activity to re-enter. Recommend a specific correction only when directly supported.
 
-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.
+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 each 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; do not recommend Review 4.
 
 ## Determine The Judgment
 
-1. **Blocking:** one or more Blocking Issues exist.
+1. **Blocking:** at least one Blocking Issue exists.
 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.
+4. **Pass:** no Issues or material unresolved items remain.
+
+Improvements do not change the judgment.
 
 ## Output
 
+Omit empty groups. Do not include Improvements unless they are materially relevant or explicitly requested.
+
 Review type: independent
 Review number: [1 | 2 | 3]
-Boundary: [reviewed work and future action]
+Boundary: [reviewed work and protected future action]
 Reviewed state: [state identity]
 Judgment: Pass | Non-blocking | Inconclusive | Blocking
 Reasoning: [concise evidence-backed judgment]
@@ -110,7 +115,7 @@ Relationship to prior items (Review 2 or 3 only): [related consequence | indepen
 ### Review Items
 
 #### Issues — Blocking
-- [location, issue, violated source, evidence, consequence, smallest safe correction]
+- [location, issue, violated source, evidence, consequence, correction constraints or owning activity]
 
 #### Issues — Non-blocking
 - [location, issue, evidence, why it can be deferred]
@@ -119,16 +124,16 @@ Relationship to prior items (Review 2 or 3 only): [related consequence | indepen
 - [question, effect on judgment, required answer]
 
 #### Unresolved — Needs evidence
-- [concern, missing evidence, evidence needed]
+- [claim, required observing boundary, available evidence and limit, why the gap affects judgment, smallest evidence that could disagree]
 
 #### Improvements
-- [improvement, benefit, supporting evidence]
+- [only when materially relevant or requested: improvement, benefit, 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.
+Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or producer 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.
+The report is evidence for adjudication. It is not authority over source truth, owner decisions, corrections, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/references/security-risk-lens.md

@@ -2,7 +2,7 @@
 
 Read this before reviewing work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, or failure behavior with security consequences.
 
-This lens helps frame review. It does not replace repo security policy, threat modeling, specialist review, or stack-specific hardening guidance.
+This lens helps frame review. It does not replace repository security policy, threat modeling, specialist review, or stack-specific hardening guidance.
 
 ## Establish Authority
 
@@ -11,10 +11,10 @@ Identify:
 - assets and data requiring protection;
 - actors, roles, tenants, and privilege levels;
 - trust boundaries and external systems;
-- accepted security/privacy policy and threat model;
+- accepted security and privacy policy and threat model;
 - compatibility and failure behavior that security controls must preserve.
 
-Security-sensitive product behavior remains user-owned. Do not invent access, retention, logging, or fail-open/closed policy during review.
+Security-sensitive product behavior remains user-owned. Do not invent access, retention, logging, or fail-open or fail-closed policy during review.
 
 ## Trace The Paths
 
@@ -28,40 +28,42 @@ Review the affected path from boundary to effect:
 - secrets: source, scope, rotation, exposure, and logging;
 - execution: shell, file, URL, template, deserialization, plugin, or code-loading boundaries;
 - dependencies: provenance, permissions, known risk, update impact, and transitive behavior;
-- failure: partial state, retries, lockout, rate limits, rollback, and fail-open/closed behavior.
+- failure: partial state, retries, lockout, rate limits, rollback, and fail-open or fail-closed behavior.
 
 Look for confused-deputy and cross-tenant paths, not only malformed input.
 
-## Evidence
+## Require Boundary-Matched Evidence
 
 Prefer evidence at the real boundary:
 
-- tests proving allowed and denied roles/resources;
+- tests proving allowed and denied roles and resources;
 - negative input and injection cases;
 - dependency or configuration inspection tied to the shipped artifact;
-- logs or traces demonstrating no secret/sensitive leakage;
+- logs or traces demonstrating no secret or sensitive leakage;
 - failure-path tests for partial authorization, retry, and recovery;
 - specialist analysis for cryptography, sandboxing, identity protocols, or high-impact threats.
 
 A generic scanner pass cannot prove authorization logic or policy correctness. A unit test cannot prove deployed headers, identity configuration, or infrastructure permissions.
 
-Do not copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. Use the smallest sanitized evidence that supports the review item.
+Do not copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. Use the smallest sanitized evidence that supports the item.
 
-## Review Item Calibration
+## Calibrate Items
 
 Treat supported exploitable behavior, policy violation, unintended privilege or data exposure, unsafe failure semantics, secret leakage, or a missing required control as an Issue.
 
-Classify the Issue against the accepted security policy and reviewed boundary:
+Classify it against accepted security policy and the reviewed boundary:
 
 - **Blocking:** crossing the boundary would remain unsafe, non-compliant, or contrary to a required control.
-- **Non-blocking:** the security issue is real but can be deferred safely without violating the accepted boundary.
+- **Non-blocking:** the issue is real but can be deferred safely without violating the accepted boundary.
 
 Use **Question** when security behavior or accepted risk remains undecided. Use **Needs evidence** when a control may exist but the available test or environment cannot establish it.
 
-Treat materially useful defense-in-depth beyond the accepted boundary as an Improvement. Do not turn theoretical hardening, preference, or hypothetical completeness into an Issue.
+Treat materially useful defense in depth beyond the accepted boundary as an Improvement. Omit theoretical hardening, preference, or hypothetical completeness.
 
-Do not omit an observed security issue merely because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
+Do not omit an observed security issue because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
 
-## Route
+## Return Through The Selected Role
 
-When security evidence changes the path, use [Workflow](../../workflow/SKILL.md) to choose what follows. Use [Diagnose Failure](../../diagnose-failure/SKILL.md) for unknown exploitability or root cause, [Decision Gate](../../decision-gate/SKILL.md) for missing policy or accepted-risk decisions, [Design For Depth](../../design-for-depth/SKILL.md) when trust decisions spread across callers, and [Launch Work](../../launch-work/SKILL.md) when the concern affects production rollout.
+For self-review, return a route-changing security concern to [Workflow](../../../skills/workflow/SKILL.md). Use [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md) for unknown exploitability or cause, [Decision Gate](../../../skills/decision-gate/SKILL.md) for missing policy or accepted-risk decisions, [Design For Depth](../../../skills/design-for-depth/SKILL.md) when trust decisions spread across callers, and [Launch Work](../../../skills/launch-work/SKILL.md) when the concern affects production rollout.
+
+For independent review, classify the concern in the review report and stop. Do not route, correct, or dispatch follow-up. The receiving agent adjudicates the report and selects what follows.