@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/review-work/SKILL.md

@@ -1,126 +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. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
+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.
+
+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).
 
-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.
+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.
+
+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.
+
+### Classify Before Calling Something An Issue
+
+Ask in order:
+
+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.
+
+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.
+
+Do not turn preferences, imagined edge cases, intentional deferrals, or hypothetical completeness into Issues.
+
+An Issue must identify:
+
+- the exact location or affected path;
+- the violated requirement, source truth, or invariant;
+- supporting evidence;
+- the concrete consequence for the reviewed boundary.
 
-A pass is valid. Do not invent items, report preferences or hypothetical completeness, reopen intentional deferrals, or treat ordinary reversible choices as issues.
+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.
 
-A possible edge case is not an Issue merely because it can be imagined:
+## Self-Review
 
-```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
-```
+Apply the complete shared kernel to your own work. Self-review uses the same technical scrutiny as independent review but does not create independence.
 
-## Classify Independent Review Items
+When evidence supports a clear local defect and existing authority covers its correction:
 
-- **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.
+1. return to the producing activity;
+2. correct the defect;
+3. re-verify the affected boundary;
+4. repeat only the affected review lenses once.
 
-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 create formal review items, a judgment, a review number, or a review cycle for self-review. Do not label it independent.
 
-Use the most consequential applicable judgment:
+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.
 
-1. **Blocking:** one or more Blocking Issues exist.
+## Independent Review
+
+Before preparing or performing a separately selected independent review, read the [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md).
+
+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 may still be reported.
+4. **Pass:** no Issues or material unresolved items remain.
+
+Improvements do not change the judgment or authorize implementation.
 
-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.
+## Adjudicate A Returned Review
 
-## Adjudicate And Route
+Before adjudicating an independent report, read [Adjudicate Work Review](references/adjudicate-work-review.md).
 
-After independent review, the receiving active agent adjudicates each item against the work, source truth, and evidence:
+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:** a question or evidence gap prevents acceptance or rejection.
+- **Open:** missing evidence or a decision prevents acceptance or rejection.
 
-Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
+Do not separately accept the reviewer's overall judgment. Derive the adjudicated judgment from the dispositions.
 
-Route from the adjudicated result:
+Findings are evidence, not commands or correction authority.
 
 - **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.
-
-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.
-
-When correction authority is not already explicit, ask once for either:
-
-- the accepted corrections plus one warranted focused follow-up review; or
-- the accepted corrections alone when direct evidence can settle the changed boundary.
+- **Inconclusive:** obtain the missing evidence or decision.
+- **Blocking:** do not cross the boundary; select the narrowest owning route.
 
-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 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).
 
-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.
+## Limit Independent Review
 
-## Limit The Review Cycle
+Treat review count as a budget, not a schedule.
 
-For one independently reviewed work state and boundary:
+- **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.
 
-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.
+A review report always ends its review. Remediation does not automatically authorize or require follow-up review.
 
-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.
+If Review 2 remains Blocking:
 
-After Review 2 is adjudicated Blocking, stop before proposing another correction or Review 3. Classify its relationship to the prior correction:
+- 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.
 
-- 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.
+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.
 
-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.
+Self-review does not consume this budget.
 
-## Report
+## Stop
 
-For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change the route.
+Stop when the selected route has produced its bounded result:
 
-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.
+- 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.
 
-Omit empty groups. Support material judgments and adjudication 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

@@ -0,0 +1,139 @@
+# Independent Work Reviewer Contract
+
+Read this before preparing or performing a separately selected independent review of implementation or integrated work.
+
+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
+
+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;
+- the implementation, changed files, or diff range;
+- verification evidence and known gaps;
+- only the review lenses material to this boundary;
+- 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.
+
+## Reviewer Prompt
+
+```md
+# Independent Work Review
+
+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. 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
+
+- 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
+
+- Outcome: [required result]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
+
+## Source Truth
+
+- [Specs, Plans, tests, policies, ADRs, and established behavior]
+
+## Verification Evidence
+
+- 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]
+
+## Review Scope
+
+- 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]
+- Remaining risk: [narrow unresolved scope]
+
+## Check
+
+Apply only the selected lenses:
+
+- 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.
+
+Before calling something an Issue, ask:
+
+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.
+
+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.
+
+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.
+
+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:** 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.
+
+## 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 protected 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, correction constraints or owning activity]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [claim, required observing boundary, available evidence and limit, why the gap affects judgment, smallest evidence that could disagree]
+
+#### Improvements
+- [only when materially relevant or requested: improvement, benefit, evidence]
+
+Evidence gaps: [unproved claims or none]
+```
+
+## Calibration
+
+Lead with the few items that can change the boundary judgment. Prior review, urgency, implementation effort, or producer confidence does not establish correctness.
+
+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

@@ -1,8 +1,8 @@
 # Security Risk Lens
 
-Read this when work changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, dependencies, external integrations, execution, or failure behavior with security consequences.
+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.