@hassangameryt/freeflow 0.8.0 → 0.9.0

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

@@ -0,0 +1,198 @@
+# Artifact Review
+
+This reference is judgment; Review Work's Rules still bind. Its Independent Review section is a contract: the context to provide and the reviewer prompt are binding as written.
+
+It covers documents that guide later work, such as a Spec, Plan, design, decision record, ADR, handoff, or skill, and accounts of work already done: a final report, a status or results note, or a Working Record. Reports And Records below adds what is particular to an account.
+
+## Establish The Artifact And Its Intended Use
+
+Goal: review the whole artifact, for the use it must actually serve.
+
+Identify the artifact's exact state, type, intended use, accepted outcome and amendments, non-goals, governing format, source basis, unresolved questions, dependencies, and evidence gaps. Inspect the complete artifact and relevant sources directly, not only its author's narrative.
+
+## Establish Which Sources Govern
+
+Goal: judge against current accepted intent, not the artifact's own baseline.
+
+Check current intent and accepted upstream requirements before dependent artifacts. Follow material amendments, supersession, and deliberately selected experimental findings. Do not infer acceptance from a proposal, a review label, a passing test, or an unexplained "user approved" summary.
+
+Distinguish accepted behavior from the suggested implementation mechanism, and check both directions: has the artifact introduced stronger obligations than the accepted outcome needs, and has it omitted accepted changes or kept a superseded baseline? An experiment can establish a fact without selecting it for production; an implementation Plan cannot ignore later accepted learning because its older version was reviewed.
+
+If upstream content is unresolved or contradictory, mark dependent material contingent rather than generating exhaustive downstream findings against an unsettled premise.
+
+## Judge The Artifact By Its Job
+
+Goal: ask of each artifact only what its job requires.
+
+- **Spec or content contract:** the accepted content, behavior, boundaries, evidence, and uncertainty needed for its intended use.
+- **Plan:** an inspectable, supported ordered strategy with scope, dependencies, assumptions, checks, and stop or invalidation conditions.
+- **Decision record or ADR:** the choice, owner, source, alternatives, rationale, consequences, and revisit or supersession conditions.
+- **Handoff:** enough truthful point-in-time context for its recipient to continue safely, without replacing the live record.
+- **Report:** every claim the reader may act on matches what happened, every evidence pointer resolves and shows what the claim says, no claim is stronger than its evidence, and unfinished, skipped, or failed work is stated.
+- **Working Record:** accurate current task state, recoverable Slices, decisions and work, compact evidence pointers with their limits, a provisional remaining route, defining artifacts and Recovery sources sufficient for a fresh context to resume, and one next useful action.
+- **Other artifact:** its declared purpose without taking over another artifact's job.
+
+A proposal can be fit for discussion without being implementation-ready. Do not block on an open question the artifact intentionally preserves and whose answer its current use does not need.
+
+## Apply The Lenses
+
+Goal: use only the lenses that can change fitness.
+
+- **Source alignment:** accepted requirements, amendments, decisions, and live facts agree with the artifact.
+- **Sufficiency:** it contains enough for its use without implying every future question is settled.
+- **Decision clarity:** required, tentative, open, deferred, and superseded material cannot be confused.
+- **Evidence and acceptance:** load-bearing claims and completion conditions have suitable observing or falsifying mechanisms.
+- **Failure and risk:** consequential behavior, failure states, forbidden outcomes, observers, and recovery are defined where required.
+- **Dependency integrity:** relevant upstream and downstream sources agree, or their contingency is explicit, and provisional material is identified honestly.
+- **Scope and minimality:** requirements and process are justified rather than speculative, mechanically exhaustive, or duplicating information owned elsewhere.
+- **Clarity and continuity:** a future reader can use the artifact without reconstructing the author's private reasoning, the full transcript, or volatile copied context.
+
+Do not demand implementation detail from a PRD, progress history from a Plan, or universal guarantees from a bounded prototype report.
+
+## Reports And Records
+
+Goal: compare an account of work done with what happened, not with how the author remembers it, so every claim the reader may act on is true and no stronger than its evidence.
+
+Identify the account's reader and the moment it serves: handing work back to the user, recovering after context loss, or handing over to another agent. Gather what it describes: the commands run and their output, changed files and commits, run results, messages sent, and the requests and decisions it cites, and read that evidence directly. Read a Working Record through [Track Work](../../../skills/track-work/SKILL.md). A claim that matches the author's earlier summary but not the output it summarizes is wrong.
+
+Instead of the lenses above, check each claim:
+
+- **Fidelity:** each statement of what was done, found, or decided matches the actions and outputs it describes. Recompute counts, totals, and costs from the source instead of trusting the stated figure.
+- **Pointers:** each commit, file, run ID, path, or link resolves, and what it shows is what the claim says.
+- **Strength:** "verified" names a check that ran on the current state; "done" is not stated for work that was drafted, partly run, or run against an earlier state. A passing subset is not "tests pass".
+- **Unfinished work:** skipped steps, failures, workarounds, and open questions are stated where the reader will see them, not left for the reader to infer from silence.
+- **Attribution:** the user's words and decisions are quoted or cited as theirs; the author's inferences are labelled as inferences.
+
+A wrong figure, a pointer that does not resolve, or a claim stronger than its evidence is an Issue when the reader could act on it: Blocking when acting on it would mislead the user or a resuming agent, Non-blocking when the error cannot change what they do. Wording and presentation preferences are not Issues.
+
+The author corrects the account; a Working Record is revised through Track Work. When a claim turns out unsupported, correct the claim or gather the missing evidence through [Verify Work](../../../skills/verify-work/SKILL.md); never adjust the evidence to match the claim.
+
+## Independent Review
+
+Use this to brief an independent reviewer of anything but work: an artifact, a report or record, or an eval definition. The reviewer receives the prompt below filled in, with the complete artifact and its sources, and reads nothing else of this skill, so the prompt must stand alone.
+
+Provide:
+
+- artifact path, type, exact reviewed state, and intended use;
+- accepted outcome, requirements, non-goals, and owner decisions;
+- unresolved questions and known evidence gaps;
+- the artifact's job and the lenses material to its intended use, each copied from this reference (for a report or record, its claim checks) or from Eval Definition Review, with whatever that section says to add;
+- for a report or record, what the account describes: the commands, outputs, files, commits, and run results its claims rest on;
+- the artifact-specific schema or format contract when one exists;
+- relevant code, tests, policies, ADRs, established behavior, and the project's Review Rules (or its `REVIEW.md`), read from the base branch;
+- upstream and downstream artifacts in dependency order, with the upstream authority and which material remains provisional or contingent;
+- what the reviewer may run: the default in Review Work's Rules, another exact covered check with its expected evidence and stop condition, or nothing;
+- the review number and, for Review 2 or 3, the previous report, its adjudication, and the revisions since the previous review's reviewed state, not the whole artifact history.
+
+```md
+# Independent Artifact Review
+
+Review an artifact state you did not produce. Inspect the complete artifact, source truth, dependencies, and evidence directly. Report without editing. The review ends with this report; do not adjudicate findings, settle owner decisions, revise anything, 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 the artifact's job or treat possible improvement as unfinished work. Lead with the few items that can change fitness for the intended use. Prior review, artifact length, polished language, or producer confidence does not establish fitness.
+
+Read the supplied evidence first. Run a check listed under May run, in your own copy, only when that evidence is missing or does not convince you; run nothing else, and make no edits, network calls, or paid runs. When a claim still lacks evidence, report **Needs evidence** with the load-bearing claim and required observing boundary. When you run a check, apply Verify Work's check-result and claim-result semantics; active evidence does not authorize revision or broaden the review.
+
+## Artifact And Intended Use
+
+- Artifact: [path]
+- Type: [spec | PRD | issue | API contract | technical design | migration contract | plan | decision record | ADR | handoff | report | working record | eval definition | other]
+- Reviewed state: [revision, hash, or other exact identity]
+- Intended use: [decision or future action this artifact must support]
+- Dependency order: [upstream -> downstream, or standalone]
+- Its job: [the job the review method gives this type]
+
+Do not require one artifact to perform another artifact's job.
+
+## Accepted Outcome And Non-Goals
+
+- 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, Review Rules, 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]
+- Lenses: [each material lens or check, with its line from the review method]
+- May run: [the project's declared checks, named | another exact covered check, its expected evidence and stop condition | nothing]
+
+For Review 2 or 3:
+
+- Previous report and its adjudication: [report path, or items with Accepted | Rejected | Open]
+- Revisions since the previous review's reviewed state and new evidence: [bounded changes and evidence]
+- Affected dependencies: [dependencies or none]
+- Remaining risk: [narrow unresolved scope]
+
+## Check
+
+Apply only the listed lenses. Review upstream authority before dependent artifacts. When an upstream problem invalidates downstream assumptions, mark affected material contingent rather than generating exhaustive downstream findings against an unsettled basis.
+
+Before calling something an Issue, ask:
+
+1. Does fitness for the intended use depend on content, source truth, or an owner decision that remains unsettled? If yes, use **Question**.
+2. Does fitness depend on a load-bearing claim or condition that available evidence cannot establish? If yes, use **Needs evidence**.
+3. Is there a supported artifact defect requiring revision for the intended use? Use **Blocking Issue** when the artifact cannot safely guide that use, otherwise **Non-blocking Issue** when revision can be deferred safely.
+4. Is the change merely useful beyond the intended use? Omit it by default; use **Improvement** only when materially relevant or requested.
+
+A defect the reviewed revision did not introduce is **Pre-existing**: report it for the user with the evidence that it predates the revision. It is never a Blocking Issue.
+
+A **Needs evidence** item must identify the load-bearing claim or condition, required observing boundary, available evidence and its limit, why the gap affects intended-use fitness, and the smallest evidence that could disagree. Establish that the claim is required. Distinguish a missing observation from a supported artifact defect; check whether evidence applies to the current artifact and accepted requirement rather than a superseded version. Do not prescribe broader implementation merely to fill an evidence gap.
+
+A Blocking Issue must identify the exact location or dependency, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and revision constraints or owning activity to re-enter. Recommend a specific revision only when source intent and dependency effects support it. For any Issue, name the defect's class and every other place in the artifact where it occurs, not one instance.
+
+For Review 2 or 3, inspect only the revisions since the previous review's reviewed state: accepted revisions, affected dependencies, new evidence, and remaining risk. Never repeat a finding already Accepted, Rejected, or fixed; reopen a Rejected one only with contradictory evidence. For each 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; do not recommend Review 4.
+
+## Judgment
+
+Blocking when at least one Blocking Issue exists; otherwise Inconclusive when a material Question or Needs evidence item prevents judgment; otherwise Non-blocking when only Non-blocking Issues remain; otherwise Pass. Improvements and Pre-existing items do not change the judgment.
+
+The report is evidence for adjudication. It is not authority over source truth, owner decisions, revisions, dependencies, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.
+
+## Output
+
+Omit empty groups. Do not include Improvements unless they are materially relevant or explicitly requested.
+
+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 or dependency, issue, violated source or responsibility, evidence, consequence, revision constraints or owning activity]
+
+#### Issues — Non-blocking
+- [location or dependency, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [load-bearing claim or condition, required observing boundary, available evidence and limit, effect on intended-use fitness, smallest evidence that could disagree]
+
+#### Pre-existing
+- [location or dependency, defect, evidence that it predates the revision, consequence]
+
+#### Improvements
+- [only when materially relevant or requested: improvement, benefit, evidence]
+
+Dependencies affected: [dependencies or none]
+Contingent material: [material and upstream condition, or none]
+Evidence gaps: [unproved claims or none]
+```

package/skills/review-work/references/evals-and-judges.md

@@ -0,0 +1,66 @@
+# Evals And Judges
+
+Two parts, each read from its own route. Eval Definition Review is judgment; Review Work's Rules still bind. The Judge Contract is a contract: every item in it is binding for each judge use.
+
+## Eval Definition Review
+
+### Establish The Claim It Will Measure
+
+Goal: review the definition against the comparison it is meant to support.
+
+Identify the behavior and boundary under test, the arms and the one component meant to differ between them, the model and settings, the subject's prompt and visible files, every expectation and review question, and the evidence behind each seeded or real defect. Run the evaluator's loader first; a definition that does not load needs no model review.
+
+### Check That It Can Measure What It Claims
+
+Goal: a correct subject passes, a wrong one fails, and the result means what its name says.
+
+- **A correct answer can pass:** for each expectation, write or imagine the answer a sound subject would give and check that it passes. Text checks fail correct answers when they require one exact phrase, such as a function name, where a correct answer may quote the line or describe it instead.
+- **A wrong answer cannot pass:** an expectation that holds for an empty, generic, or opposite answer measures nothing. Nor can a shortcut: editing the tests, hard-coding the expected output, or text addressed to a judge.
+- **The outcome, not the path:** checks grade what the subject produced; a required order of tool calls fails valid approaches. A tool-call check is right only when the call itself is the behavior.
+- **Both sides are tested:** cases where the behavior should occur sit beside cases where it should not, and a coding task's graders cover the new behavior and the existing behavior it must not break.
+- **Names match checks:** each expectation's name and comparison say what it actually tests.
+- **Defects are real and present:** each seeded defect is shown by a check that fails with it and passes without it, or by a direct contradiction of a stated requirement. The case author is not the model being measured.
+- **Clean is clean:** a clean variant taken from history may hold a defect found later. Check it against its own requirements before trusting a clean-variant fail; a variant with a known defect is real, not clean, and is scored as such.
+- **No leaks:** nothing the subject can see, including group IDs, paths, file names, and fixture comments, hints at the defect or the expected answer. Rubric references and grader files lie outside the fixture and the subject's declared context.
+- **Arms differ only as declared:** sources, models, settings, tools, and context match except for the component under test, and each is pinned.
+- **The decision comes first:** when the result will claim one arm is better, the decision rule (measure, arms, direction, size) is declared before any run.
+- **The task is solvable:** a coding task's reference solution passes its graders (`check-tasks`), so a failure measures the subject, not the task.
+- **Participants see only what they declare:** each pipeline stage's inputs and a simulated user's card hold what that participant should know and nothing that hints at the answer.
+- **A shell is confined:** a subject gets a shell only behind a declared isolation that the evaluator verifies, never the host's own.
+- **Judges see enough:** a grader or advisory reviewer receives the full output it judges and the material the question is about; answers given over truncated or missing evidence are not results.
+
+### Classify What You Find
+
+A check that a correct answer fails, a defect not shown present, a clean variant with a known defect, a leak, an unsolvable task, or a comparison claim with no decision rule declared is Blocking for spending on runs, because the result would be wrong whatever the subject does. Gaps in coverage beyond the claim are Improvements unless the claim depends on them.
+
+### Independent Review
+
+Brief it with the prompt in [Artifact Review](artifact.md#independent-review), taking the lenses from the checks above. Its job: it loads, a correct answer can pass every expectation and a wrong one cannot, each expectation checks what its name and text claim, every seeded or real defect is shown present, every clean variant is free of known defects, and nothing the subject can see reveals the answer. Also provide the evaluator's definition format, its loader's result, and the evidence that each seeded or real defect is present.
+
+### Where Revisions Go
+
+Revise the definition before running it. After a run, a fault found in a definition is recorded with the results it affected, and those results are read with it; do not quietly rescore them.
+
+## Judge Contract
+
+When an item cannot be met, say which, and treat the verdict as weaker evidence rather than presenting it as if the item held.
+
+### Record And Do For Every Judge
+
+1. **Identity:** the model ID, provider, model family, thinking or effort setting, prompt hash, date, and anything loaded into the judge that can change what it is sent, such as an extension that rewrites the system prompt.
+2. **Independence:** the judge did not produce what it judges. Record its family relative to the producer's as same, different, or unknown. Repeated calls to the same model are one vote, not several.
+3. **Inputs:** record what the judge saw and what was withheld. It sees the complete output it judges and the material its question is about; a verdict over truncated or missing evidence is not a verdict on that question. Withhold arm names, the producer's reasoning, and deterministic grades unless the question needs them, and make sure none reaches the judge through paths or file names.
+4. **Verdict with evidence:** each verdict cites the evidence it rests on. Give no benefit of the doubt; "unclear" is a valid answer and is reported as such.
+5. **Order:** when comparing outputs, record the order shown, and swap it to check that position did not decide the verdict.
+6. **Combining rule:** when more than one verdict exists, name the rule (unanimous, majority, or any) before seeing them. Stricter rules cost detection; looser rules mostly add false alarms.
+7. **Calibration:** record whether this judge configuration has been checked against cases with known answers, and the result. An uncalibrated judge's verdict is advisory.
+
+A judge's verdict is evidence for adjudication or for a measured comparison. It is never canonical grading, acceptance, or authority to change the work.
+
+### Rubric Judges
+
+A rubric judge answers fixed questions about one output at a time, such as Evaluate Behavior's `review --rubric`. The items above apply, and:
+
+- Judge each output alone, blind to its arm or producer, so no order effect arises and item 5 needs no swap.
+- The combining rule (item 6) is declared in the evaluation definition before any run, not chosen when verdicts arrive.
+- Calibration status (item 7) belongs to the judge configuration: its model, thinking setting, anything loaded into it, and the rubric. Record it per configuration; a change in any of them makes a new, uncalibrated judge.

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

@@ -0,0 +1,177 @@
+# Work Review
+
+This reference is judgment; Review Work's Rules still bind. Its Independent Review section is a contract: the brief and the reviewer's instructions are binding as written.
+
+## Establish What The Review Protects
+
+Goal: judge the actual state against its real sources, not the producer's account of it.
+
+Identify the exact code, diff, commit, or integrated state; its accepted outcome, non-goals, relevant requirements and amendments; the future action being protected; and the verification evidence and gaps.
+
+Inspect the actual state and governing sources, not just the producer's summary or explanation. A detailed execution contract can itself have been mistaken; check the user outcome before judging compliance with the suggested implementation steps.
+
+## Apply The Lenses
+
+Goal: use only the lenses that can change the boundary judgment.
+
+- **Source alignment:** required behavior and accepted amendments are implemented without omission or invented obligations.
+- **Correctness and integration:** reachable paths, affected callers, states, and components work together without regressions.
+- **Safety evidence:** name the one fact the change's safety rests on and grade how it is known, weakest first: asserted; cited at file:line; reasoned through; scripted against the real code; reproduced in the running app. A text search for callers stops at dynamic dispatch, configuration and feature flags, generated code, library source at the pinned version, wire formats and stored columns, and code in other languages or repositories that reads the same data; look there before grading the fact above reasoned.
+- **Failure and risk:** material errors, recovery, permissions, data, and compatibility are handled safely, as required.
+- **Evidence and acceptance:** claims are supported at their required observing boundaries, not merely by green summaries.
+- **Scope and minimality:** complexity and coordination serve requirements or demonstrated needs rather than optional stronger guarantees.
+- **Maintainability:** behavior and failure paths remain understandable and changeable, without hidden policy or fragile coupling.
+
+More implementation is not better: check both missing accepted work and unnecessary additions. A prototype result is not production acceptance, and a test protecting a mechanism does not make that mechanism required. If the implementation follows an artifact whose baseline conflicts with a later accepted change, expose that source mismatch rather than choose whichever source makes the work pass.
+
+## Two Checks In Self-Review
+
+Goal: the user sees every choice nobody agreed, and no existing check was bent to fit the work.
+
+When self-reviewing your own work, also run:
+
+- **Decision check:** run [Discuss Work](../../../skills/discuss-work/SKILL.md#account-at-the-end)'s decision check against its decision list (with a Working Record, `sources/decisions.md`).
+- **Test-integrity check:** run Verify Work's [test-changes](../../../skills/verify-work/scripts/test-changes.mjs) script from the work's base, and settle each listed change to an existing test, fixture, or shared setup as [Test Design](../../../skills/verify-work/references/test-design.md)'s Rule requires.
+
+## Security Risk Lens
+
+This section is judgment, with two Rules: security-sensitive product behavior stays user-owned, so never invent access, retention, logging, or fail-open or fail-closed policy during review; and never copy secrets, credentials, unrestricted personal data, or sensitive payloads into review context. It helps frame review and does not replace repository security policy, threat modeling, specialist review, or stack-specific hardening guidance.
+
+### Establish Authority
+
+Identify:
+
+- assets and data requiring protection;
+- actors, roles, tenants, and privilege levels;
+- trust boundaries and external systems;
+- accepted security and privacy policy and threat model;
+- compatibility and failure behavior that security controls must preserve.
+
+### Trace The Paths
+
+Review the affected path from boundary to effect:
+
+- authentication: who or what is this actor;
+- authorization: may this actor perform this operation on this resource;
+- input: validation, canonicalization, size, encoding, and injection surfaces;
+- output: escaping, disclosure, error detail, and side channels;
+- data: collection, transport, storage, isolation, retention, deletion, and audit;
+- 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 or fail-closed behavior.
+
+Look for confused-deputy and cross-tenant paths, not only malformed input.
+
+### Require Boundary-Matched Evidence
+
+Prefer evidence at the real boundary:
+
+- 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 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.
+
+Use the smallest sanitized evidence that supports the item.
+
+### 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 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 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. Omit theoretical hardening, preference, or hypothetical completeness.
+
+Do not omit an observed security issue because the selected lenses were narrower. Name the asset, path, precondition, consequence, evidence, and source requirement.
+
+### Return Through The Selected Role
+
+For self-review, route a security concern that changes the route to its owner: Execute Work's [diagnose](../../../skills/execute-work/references/diagnose.md) for unknown exploitability or cause, [Discuss Work](../../../skills/discuss-work/SKILL.md) for missing policy or accepted-risk decisions, Execute Work's [design](../../../skills/execute-work/references/design.md#pressure-signals) when trust decisions spread across callers, and [Deliver Work](../../../skills/deliver-work/SKILL.md)'s launch route 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.
+
+## Independent Review
+
+Use this to brief an independent reviewer of work, and, as that reviewer, to review it.
+
+### The Brief
+
+The brief points to where the reviewer finds each input; the reviewer reads them itself. Never paste the requirements, the diff, the docs, or the evidence into it, and never send only your summary of them. Write the brief in this shape, one labelled line each:
+
+```md
+Review: [1 | 2 | 3]
+Boundary: [the protected future action]
+Reviewed state: [commit]
+Method: [path to Review Work's SKILL.md] and its references/work.md
+Agreement: [path to the Working Record, read through its resume view, or to the accepted outcome, requirements and non-goals; plus any Spec or Plan it names]
+Docs: [paths to the dev docs covering the changed files, read from the base branch | none]
+Review rules: [path to the project's Review Rules or REVIEW.md, read from the base branch | none]
+Diff: [base]..[head]
+Evidence: [path to the verification evidence and known gaps; check it, don't trust it | none]
+May run: [the project's declared checks, named | another exact covered check, its expected evidence and stop condition | nothing]
+Previous report: [Review 2 or 3 only: path to the previous report and its adjudication]
+Report: [path to write the report to]
+```
+
+Write each path in backticks. Add a `Lenses:` line only to narrow the review to the lenses material to this boundary, and a `Notes:` line pointing to the invariant, state owner, affecting paths, observer, forbidden mutations, prior-state requirements, adversarial disproof, mutation footprint and fidelity limits when state transitions or proof integrity matter. `May run` defaults to what Review Work's Rules allow a reviewer. For Review 2 or 3, the diff is the range since the previous review's reviewed state, not the whole change.
+
+[review-packet](../scripts/review-packet.mjs) writes this brief for you: `node <review-work-directory>/scripts/review-packet.mjs --review <n> --base <ref> --task <task folder> --boundary <the protected action>` fills every line it can (the Review 2 or 3 diff from the previous brief's reviewed state, the docs covering the changed files, the declared checks), leaves the rest empty and runs check-brief. Before dispatching, run [check-brief](../scripts/check-brief.mjs) on the brief: `node <review-work-directory>/scripts/check-brief.mjs <brief> [--root <repository>]`. It refuses a brief missing a required line or naming a path or commit that does not exist. Dispatch only a brief it accepts; if it cannot run, check the same by hand and say so in the record.
+
+A reviewer that cannot read files is a host gap: record it, and do not paste the inputs instead.
+
+### Reviewing As The Independent Reviewer
+
+The reviewer reads this section, not a copy of it.
+
+Review work you did not produce. Inspect the work, source truth, and evidence the brief points to 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. Lead with the few items that can change the boundary judgment; prior review, urgency, implementation effort, or producer confidence does not establish correctness.
+
+Read the brief's pointers: the agreement (through the Working Record's resume view when the brief names one), the docs, the Review Rules, and the diff. Then read the evidence as claims to check. Run a check listed under `May run`, in your own copy, only when that evidence is missing or does not convince you; run nothing else, and make no edits, network calls, or paid runs. When a claim still lacks evidence, report **Needs evidence** with the claim and required observing boundary. When you run a check, apply Verify Work's check-result and claim-result semantics; active evidence does not authorize editing or broaden the review.
+
+Apply the lenses the brief names, or all of those under Apply The Lenses. Do not search for unrelated issues. Report an out-of-scope issue only when it materially affects whether this boundary may be crossed. Classify each item and determine the judgment as Review Work's SKILL.md does: "Classify Before Calling Something A Defect" and the independent judgment under "Perform A Selected Independent Review".
+
+For Review 2 or 3, inspect only the diff since the previous review's reviewed state: accepted corrections, affected interactions, new evidence, and remaining risk. Never repeat a finding already Accepted, Rejected, or fixed; reopen a Rejected one only with 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.
+
+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. Write it in this shape, omitting empty groups and Improvements that are neither materially relevant nor requested:
+
+```md
+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]
+
+#### Pre-existing
+- [location, defect, evidence that it predates the change, consequence]
+
+#### Improvements
+- [only when materially relevant or requested: improvement, benefit, evidence]
+
+Evidence gaps: [unproved claims or none]
+```

package/skills/review-work/scripts/check-brief.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Checks a work reviewer's pointer brief (references/work.md, "The Brief") before it is dispatched: every
+// required labelled line is present, every backticked path it points to exists, and every commit it names resolves.
+// It checks pointers only; whether they point to the right inputs is the initiator's judgment.
+// Usage: check-brief.mjs <brief> [--root <repository>] [--json]
+// Paths resolve against --root (default: the current directory); absolute paths are allowed, and a "#anchor" suffix is
+// ignored. Exit code 0 when the brief passes, 1 when it has problems, 2 on a usage error.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+const USAGE = "Usage: check-brief.mjs <brief> [--root <repository>] [--json]";
+
+// Lines every brief carries. "paths" lines must point to at least one existing file unless "none" is allowed and given.
+const REQUIRED = [
+  { label: "Review", kind: "number" },
+  { label: "Boundary", kind: "text" },
+  { label: "Reviewed state", kind: "commit" },
+  { label: "Method", kind: "paths" },
+  { label: "Agreement", kind: "paths" },
+  { label: "Docs", kind: "paths", none: true },
+  { label: "Review rules", kind: "paths", none: true },
+  { label: "Diff", kind: "range" },
+  { label: "Evidence", kind: "paths", none: true },
+  { label: "May run", kind: "text" },
+  { label: "Report", kind: "report" },
+];
+const OPTIONAL = [
+  { label: "Previous report", kind: "paths" },
+  { label: "Lenses", kind: "text" },
+  { label: "Notes", kind: "text" },
+];
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: { root: { type: "string" }, json: { type: "boolean", default: false } },
+  });
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const { values, positionals } = parsed;
+if (positionals.length !== 1) fail(USAGE);
+const briefPath = resolve(positionals[0]);
+if (!existsSync(briefPath)) fail(`no such brief: ${positionals[0]}`);
+const root = resolve(values.root ?? ".");
+
+// A labelled line is "Label: value" at the start of a line, optionally as a list item or in bold ("**Label:**").
+const known = [...REQUIRED, ...OPTIONAL];
+const lines = new Map();
+for (const raw of readFileSync(briefPath, "utf8").split("\n")) {
+  const match = raw.match(/^\s*(?:[-*]\s+)?(?:\*\*)?([A-Za-z ]+?):(?:\*\*)?\s*(.*)$/);
+  if (!match) continue;
+  const spec = known.find((each) => each.label.toLowerCase() === match[1].trim().toLowerCase());
+  if (spec && !lines.has(spec.label)) lines.set(spec.label, match[2].trim());
+}
+
+const problems = [];
+const problem = (label, message) => problems.push({ line: label, problem: message });
+
+const commitOf = (ref) => {
+  try {
+    return execFileSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+const unquote = (value) => value.replace(/^`|`$/g, "").trim();
+const pathsIn = (value) => [...value.matchAll(/`([^`]+)`/g)].map((match) => match[1].replace(/#.*$/, "").trim());
+const at = (path) => (isAbsolute(path) ? path : resolve(root, path));
+
+function check(spec, value) {
+  if (!value) return problem(spec.label, "is empty");
+  if (spec.none && /^none\.?$/i.test(value)) return;
+  if (spec.kind === "number") {
+    const round = Number(value.match(/\d+/)?.[0]);
+    if (![1, 2, 3].includes(round)) problem(spec.label, `must be 1, 2 or 3, not "${value}"`);
+  } else if (spec.kind === "commit") {
+    const ref = unquote(value.split(/\s+/)[0]);
+    if (!commitOf(ref)) problem(spec.label, `names no commit in ${root}: ${ref}`);
+  } else if (spec.kind === "range") {
+    const range = unquote(value.split(/\s+/)[0]);
+    const ends = range.split(/\.{2,3}/);
+    if (ends.length !== 2 || !ends[0] || !ends[1]) return problem(spec.label, `must be <base>..<head>, not "${value}"`);
+    for (const end of ends) if (!commitOf(end)) problem(spec.label, `names no commit in ${root}: ${end}`);
+  } else if (spec.kind === "paths") {
+    const paths = pathsIn(value);
+    if (!paths.length)
+      return problem(spec.label, `points to no path; write each path in backticks${spec.none ? ', or "none"' : ""}`);
+    for (const path of paths)
+      if (!existsSync(at(path))) problem(spec.label, `points to a path that does not exist: ${path}`);
+  } else if (spec.kind === "report") {
+    const [path] = pathsIn(value);
+    if (!path) return problem(spec.label, "names no report path in backticks");
+    if (!existsSync(dirname(at(path)))) problem(spec.label, `is in a folder that does not exist: ${dirname(path)}`);
+  }
+}
+
+for (const spec of REQUIRED) {
+  if (!lines.has(spec.label)) problem(spec.label, "is missing");
+  else check(spec, lines.get(spec.label));
+}
+for (const spec of OPTIONAL) if (lines.has(spec.label)) check(spec, lines.get(spec.label));
+const round = Number(lines.get("Review")?.match(/\d+/)?.[0]);
+if ((round === 2 || round === 3) && !lines.has("Previous report"))
+  problem("Previous report", `is missing; Review ${round} needs the previous report and its adjudication`);
+
+const ok = problems.length === 0;
+if (values.json) {
+  console.log(JSON.stringify({ command: "check-brief", brief: briefPath, root, ok, problems }, null, 2));
+} else if (ok) {
+  console.log(`Brief passes: ${positionals[0]}`);
+} else {
+  console.log(`Brief refused: ${positionals[0]}`);
+  for (const each of problems) console.log(`- ${each.line}: ${each.problem}`);
+}
+process.exit(ok ? 0 : 1);