@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/execute-work/scripts/touch-map.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// Answers "what does this change touch?" with capped, labelled query results, so the consequences of a change are in
+// front of the agent before its first edit: entry points, readers of the state, writers (where old data comes from),
+// scheduled or concurrent code, the tests that cover it, and the developer docs that cover each touched file. Each
+// block gives its count, the first results, and what it did not search. It is a query, not a verdict: the agent writes
+// a decision next to each result (Execute Work, "Find What The Change Touches").
+// Usage: touch-map.mjs (--symbol <name> | --file <path>)... [--root <repository>] [--cap <n>] [--json]
+// Searches files Git tracks and untracked files it does not ignore. Developer docs come from Write Docs'
+// docs-check.mjs --covering; when no document has a Covers line, a capped search of the docs folder stands in.
+// Exit code 0 when it reports (even nothing), 2 on a usage or Git error.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const USAGE = "Usage: touch-map.mjs (--symbol <name> | --file <path>)... [--root <repository>] [--cap <n>] [--json]";
+const DOCS_CHECK = resolve(dirname(fileURLToPath(import.meta.url)), "../../write-docs/scripts/docs-check.mjs");
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let values;
+try {
+  ({ values } = parseArgs({
+    options: {
+      symbol: { type: "string", multiple: true, default: [] },
+      file: { type: "string", multiple: true, default: [] },
+      root: { type: "string" },
+      cap: { type: "string", default: "20" },
+      json: { type: "boolean", default: false },
+    },
+  }));
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+if (!values.symbol.length && !values.file.length) fail(USAGE);
+const cap = Number(values.cap);
+if (!Number.isInteger(cap) || cap < 1) fail(`--cap must be a positive whole number\n${USAGE}`);
+
+const git = (cwd, args) =>
+  execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+let root;
+try {
+  root = resolve(git(resolve(values.root ?? "."), ["rev-parse", "--show-toplevel"]).trim());
+} catch {
+  fail("not inside a Git repository");
+}
+
+// Test files by the common layouts Verify Work's test-changes.mjs lists; enough to tell a test hit from a code hit.
+const TEST_PATH =
+  /(^|\/)(tests?|__tests__|spec|e2e|Tests)\/|\.(test|spec)\.[cm]?[jt]sx?$|_test\.(go|py|dart|exs)$|(^|\/)test_[^/]*\.py$|_spec\.rb$|(Test|Tests)\.(java|kt|cs|swift|php)$/;
+const DOC_PATH = /\.(md|mdx|rst|adoc|txt)$/i;
+const isTest = (path) => TEST_PATH.test(path);
+const isDoc = (path) => DOC_PATH.test(path);
+
+// Fixed-string git grep over tracked and untracked (not ignored) files; returns [{ path, line, text }]. Callers refine
+// with JavaScript expressions, which behave the same on every platform's Git.
+function grep(text, { word = false, paths = [] } = {}) {
+  const args = ["grep", "-n", "-I", "-F", "--no-color", "--untracked", "-e", text];
+  if (word) args.splice(1, 0, "-w");
+  if (paths.length) args.push("--", ...paths);
+  const result = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  if (result.status !== 0 && result.status !== 1) fail(`git grep failed: ${result.stderr.trim()}`);
+  return (result.stdout ?? "")
+    .split("\n")
+    .filter(Boolean)
+    .map((raw) => {
+      const match = /^(.*?):(\d+):(.*)$/.exec(raw);
+      return match ? { path: match[1], line: Number(match[2]), text: match[3].trim().slice(0, 200) } : null;
+    })
+    .filter(Boolean);
+}
+
+const block = (label, hits, notSearched) => ({
+  label,
+  count: hits.length,
+  results: hits.slice(0, cap).map((hit) => `${hit.path}:${hit.line}: ${hit.text}`),
+  cut: Math.max(0, hits.length - cap),
+  notSearched,
+});
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Explicit scheduling and concurrency primitives, not every async function, so the block stays readable.
+const SCHEDULED =
+  /\b(setTimeout|setInterval|setImmediate|queueMicrotask|requestAnimationFrame|cron|schedule(r|d)?\s*\(|new Worker|worker_threads|Promise\.(all|allSettled|race|any)|go func|goroutine|threading\.|Thread\(|asyncio\.(gather|create_task|wait)|concurrent\.futures|ThreadPool|ExecutorService|tokio::spawn|spawn\(|[Mm]utex|[Ss]emaphore|\.lock\(|withLock|debounce|throttle|retry\(|\.on\(\s*['"`]|addEventListener|setImmediate)/;
+
+// Lines in the given files that schedule work or run it concurrently.
+function scheduledIn(files) {
+  const hits = [];
+  for (const path of files) {
+    let text;
+    try {
+      text = readFileSync(join(root, path), "utf8");
+    } catch {
+      continue;
+    }
+    text.split("\n").forEach((line, index) => {
+      if (SCHEDULED.test(line)) hits.push({ path, line: index + 1, text: line.trim().slice(0, 200) });
+    });
+  }
+  return hits;
+}
+
+function symbolMap(symbol) {
+  const pattern = escape(symbol);
+  const hits = grep(symbol, { word: true }).filter((hit) => !isDoc(hit.path));
+  const definition = new RegExp(
+    `\\b(function\\*?|class|def|const|let|var|interface|type|enum|struct|trait|func|fn|module|export\\s+(default\\s+)?)\\s+${pattern}\\b|^\\s*(async\\s+)?${pattern}\\s*\\([^)]*\\)\\s*\\{`,
+  );
+  const write = new RegExp(
+    `(\\b|\\.)${pattern}\\s*(\\+\\+|--|[-+*/|&]?=(?!=))|\\b(set|write|save|store|put|insert|update|upsert|persist|delete|remove|assign)\\w*\\s*\\(\\s*['"\`]?${pattern}\\b|\\b${pattern}\\b\\s*:(?!:)|\\b(INSERT|UPDATE|DELETE)\\b.*\\b${pattern}\\b`,
+    "i",
+  );
+  const call = new RegExp(`\\b${pattern}\\s*\\(|\\bnew\\s+${pattern}\\b|['"\`/]${pattern}['"\`]`);
+  const code = hits.filter((hit) => !isTest(hit.path));
+  const definitions = code.filter((hit) => definition.test(hit.text));
+  const writers = code.filter((hit) => !definition.test(hit.text) && write.test(hit.text));
+  const entry = code.filter((hit) => !definition.test(hit.text) && !writers.includes(hit) && call.test(hit.text));
+  const readers = code.filter((hit) => !definitions.includes(hit) && !writers.includes(hit) && !entry.includes(hit));
+  const files = [...new Set(code.map((hit) => hit.path))];
+  const scheduled = scheduledIn(files.filter((path) => !isTest(path)));
+  const tests = hits.filter((hit) => isTest(hit.path));
+  const defined = [...new Set(definitions.map((hit) => hit.path))];
+  return {
+    target: symbol,
+    kind: "symbol",
+    definedIn: definitions.slice(0, cap).map((hit) => `${hit.path}:${hit.line}`),
+    blocks: [
+      block("entry points (calls, constructions, string references)", entry, [
+        "names built at run time, reflection and dynamic dispatch",
+        "other repositories, generated or ignored files",
+      ]),
+      block("readers of the state", readers, ["aliases and destructured or renamed copies", "serialized forms"]),
+      block("writers (where old data comes from)", writers, [
+        "data already stored by earlier versions: databases, files, caches, user settings",
+        "writes through an alias or a generic setter",
+      ]),
+      block("scheduled or concurrent code in the files that use it", scheduled, [
+        "callers in other files that run it concurrently",
+        "external schedulers (cron tables, CI, hosts)",
+      ]),
+      block("covering tests", tests, ["tests that reach it only indirectly", "test files outside the common layouts"]),
+    ],
+    touchedFiles: defined,
+  };
+}
+
+function fileMap(input) {
+  const path = relative(root, resolve(input)).split("\\").join("/");
+  if (path.startsWith("..")) fail(`outside the repository: ${input}`);
+  const stem = basename(path, extname(path));
+  const name = basename(path);
+  // Importers and other references: lines naming the file by its path or its stem in an import-like statement.
+  const named = new RegExp(`(^|[^A-Za-z0-9_.-])${escape(stem)}(\\.[A-Za-z0-9]+)?(['"\`)\\s:,;]|$)`);
+  const references = grep(stem).filter((hit) => hit.path !== path && !isDoc(hit.path) && named.test(hit.text));
+  const imports = references.filter((hit) =>
+    /\b(import|require|from|include|source|load|use|mod)\b|\bnode\b|\bpython\b|"(bin|main|exports|scripts)"/.test(
+      hit.text,
+    ),
+  );
+  const other = references.filter((hit) => !imports.includes(hit) && !isTest(hit.path));
+  const exists = existsSync(join(root, path));
+  const scheduled = exists ? scheduledIn([path]) : [];
+  const tests = references.filter((hit) => isTest(hit.path));
+  return {
+    target: path,
+    kind: "file",
+    exists,
+    blocks: [
+      block(
+        "entry points (importers, commands, manifests)",
+        imports.filter((hit) => !isTest(hit.path)),
+        ["dynamic imports with built paths", "registration by convention (routes, plugins found by folder)"],
+      ),
+      block("other references by name", other, [`mentions spelled other than ${name} or ${stem}`]),
+      block("scheduled or concurrent code in the file", scheduled, ["callers that run it concurrently"]),
+      block("covering tests", tests, ["tests that reach it only through other modules"]),
+    ],
+    touchedFiles: [path],
+  };
+}
+
+const maps = [...values.symbol.map(symbolMap), ...values.file.map(fileMap)];
+
+// Developer docs covering every touched file, from docs-check --covering; a capped docs search when no doc has Covers.
+const touched = [...new Set(maps.flatMap((map) => map.touchedFiles))];
+let docs = { source: "none", paths: [], notSearched: [] };
+if (touched.length && existsSync(DOCS_CHECK)) {
+  const run = spawnSync(
+    process.execPath,
+    [DOCS_CHECK, ...touched.flatMap((path) => ["--covering", path]), "--root", root, "--json"],
+    { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 },
+  );
+  if (run.status === 0) {
+    const found = JSON.parse(run.stdout);
+    const withCovers = found.documents - found.withoutCovers.length;
+    // Title and one line: the doc's first heading, and the section and line that name the file.
+    const describe = (docPath, target) => {
+      let text = "";
+      try {
+        text = readFileSync(join(root, docPath), "utf8");
+      } catch {
+        return { heading: null, line: null };
+      }
+      const lines = text.split("\n");
+      const title = lines.find((line) => /^#\s/.test(line))?.replace(/^#\s+/, "") ?? null;
+      const index = lines.findIndex((line, at) => at > 6 && (line.includes(target) || line.includes(basename(target))));
+      let section = title;
+      for (let at = index; at >= 0; at -= 1)
+        if (/^#{2,4}\s/.test(lines[at])) {
+          section = lines[at].replace(/^#+\s+/, "");
+          break;
+        }
+      const first =
+        index >= 0
+          ? lines[index]
+          : (lines.find((line, at) => at > 0 && line.trim() && !/^[#>]/.test(line.trim())) ?? "");
+      return { heading: section, line: first.trim().slice(0, 200) };
+    };
+    if (withCovers > 0)
+      docs = {
+        source: "docs-check --covering",
+        searched: found.searched,
+        paths: found.paths.map((entry) => ({
+          path: entry.path,
+          documents: entry.documents.map((doc) => ({
+            path: doc.path,
+            ...describe(doc.path, entry.path),
+            verifiedAt: doc.verifiedAt,
+            state: doc.state,
+            changedSince: doc.changed.length,
+          })),
+        })),
+        notSearched: [
+          `${found.withoutCovers.length} of ${found.documents} documents have no Covers line, so no lookup finds them`,
+          "user docs and READMEs outside the docs index",
+        ],
+      };
+    else {
+      const folder = found.searched[0] ?? "";
+      docs = {
+        source: `capped search of ${folder || "the docs folder"} (no document has a Covers line)`,
+        searched: found.searched,
+        paths: touched.map((path) => {
+          const hits = grep(basename(path), { paths: folder ? [folder] : [] }).filter((hit) => isDoc(hit.path));
+          return {
+            path,
+            documents: hits
+              .slice(0, cap)
+              .map((hit) => ({ path: hit.path, heading: null, line: `${hit.line}: ${hit.text}` })),
+            cut: Math.max(0, hits.length - cap),
+          };
+        }),
+        notSearched: ["docs that describe the code without naming the file", "staleness: no Verified at to compare"],
+      };
+    }
+  } else
+    docs = {
+      source: "unavailable",
+      paths: [],
+      notSearched: [`docs-check: ${(run.stderr || run.stdout).trim().split("\n")[0]}`],
+    };
+}
+
+const report = { command: "touch-map", root, cap, maps, docs };
+if (values.json) console.log(JSON.stringify(report, null, 2));
+else {
+  for (const map of maps) {
+    console.log(`=== ${map.kind} ${map.target}${map.kind === "file" && !map.exists ? " (does not exist yet)" : ""}`);
+    if (map.definedIn) console.log(`defined at: ${map.definedIn.join(", ") || "no definition found"}`);
+    for (const each of map.blocks) {
+      console.log(`--- ${each.label}: ${each.count}${each.cut ? ` (first ${cap} shown)` : ""}`);
+      for (const result of each.results) console.log(`  ${result}`);
+      console.log(`  not searched: ${each.notSearched.join("; ")}`);
+    }
+  }
+  console.log(`--- developer docs (${docs.source})`);
+  for (const entry of docs.paths) {
+    console.log(`  ${entry.path}`);
+    if (!entry.documents.length) console.log("    no covering document");
+    for (const doc of entry.documents)
+      console.log(
+        `    ${doc.path}${doc.heading ? ` § ${doc.heading}` : ""}${doc.state ? ` (verified at ${doc.verifiedAt ?? "none"}: ${doc.state}${doc.changedSince ? `, ${doc.changedSince} covered file(s) changed since` : ""})` : ""}${doc.line ? `\n      ${doc.line}` : ""}`,
+      );
+  }
+  if (docs.notSearched.length) console.log(`  not searched: ${docs.notSearched.join("; ")}`);
+  console.log("Write your decision next to each result: it changes too, or its users keep exactly what they get now.");
+}

package/skills/review-work/SKILL.md

@@ -1,91 +1,129 @@
 ---
 name: review-work
-description: "Use when judging implementation or integrated work through self-review or independent review, or when adjudicating a returned independent review report."
+description: "Use whenever finished work or a document is judged fit to use: reviewing code, a diff, a commit or a pull request; checking your own change before reporting it done; reviewing a spec, plan, design, ADR, handoff, skill, final report, status note or Working Record; reviewing changes to authentication, permissions, secrets, untrusted input or other security boundaries; reviewing an eval case, suite, grader or rubric before paying for its runs; preparing, dispatching or skipping an independent review; choosing a model as judge or relying on its verdict; and weighing a review report that came back."
 ---
 
 # Review Work
 
-Judge whether the actual work satisfies the accepted outcome, remains proportionate, and has enough evidence for a named boundary.
+Judge whether the actual work satisfies the accepted outcome, remains proportionate, and has enough evidence for a named boundary; or whether a complete artifact faithfully represents accepted intent and is sufficient for its named use. An artifact's internal consistency is not enough if it consistently describes the wrong outcome or an obsolete baseline.
 
-[Verify Work](../../skills/verify-work/SKILL.md) establishes what observations prove. Review judges their sufficiency and the resulting work; it does not replace verification, choose user-owned behavior, or authorize corrections.
+[Verify Work](../../skills/verify-work/SKILL.md) establishes what observations prove. Review judges their sufficiency and the resulting work or artifact; it does not replace verification, create evidence, choose user-owned behavior, settle owner decisions, or authorize corrections or revisions.
+
+Review has three roles:
+
+- **Self-review:** the producer or author checks its own supported result or artifact before accepting, reusing, or using it. This is the normal required route.
+- **Independent review:** a separately selected reviewer judges a state it did not produce, from a separate context.
+- **Adjudication:** the receiving agent checks a returned independent report and decides what its findings establish.
 
 The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
 
+## Routes
+
+Read the reference for what is under review before reviewing it; each names what to establish first, the sources that govern, and the lenses that can change the judgment for that kind.
+
+| Situation | Go to |
+| --- | --- |
+| Work: code, a diff, a commit, an implementation, or integrated state | [Work Review](references/work.md) |
+| 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 | Work Review's [Security Risk Lens](references/work.md#security-risk-lens) as well |
+| An artifact that will guide later work: a Spec, Plan, design, decision record, ADR, handoff, or skill | [Artifact Review](references/artifact.md) |
+| An account of work already done: a final report to the user, a status or results note, or a Working Record | [Artifact Review](references/artifact.md), with its [Reports And Records](references/artifact.md#reports-and-records) |
+| An eval case, suite, fixture, grader, or rubric that will be run to measure behavior, before spending on its runs | [Eval Definition Review](references/evals-and-judges.md#eval-definition-review) |
+| A hand-over: dispatching, proposing, or skipping an independent review of the work | The Review Gate, below |
+| Preparing or performing an independent review | Independent Review in [Work Review](references/work.md#independent-review) for work; in [Artifact Review](references/artifact.md#independent-review) for anything else |
+| Writing or dispatching an independent reviewer's brief | Prefill it with [review-packet](scripts/review-packet.mjs) and check it with [check-brief](scripts/check-brief.mjs), as Perform A Selected Independent Review says |
+| A model's verdict on another agent's output will be used as evidence: an independent reviewer, an eval's advisory reviewer, or a grading judge | The [Judge Contract](references/evals-and-judges.md#judge-contract), before selecting the judge or using its verdict |
+| An independent review's report has returned | [Adjudicate A Returned Review](references/adjudication.md), before acting on it |
+
 ## Rules
 
-- Independent review is never automatic after implementation or self-review. Select it through [Workflow](../../skills/workflow/SKILL.md) only when requested, or justified and authorized, to protect a concrete risk, dependency, integration, or delivery boundary. A review budget permits no dispatch by itself, and switching models or loading this skill does not create independence.
-- An independent reviewer reports and stops: no edits, no choosing among materially different remedies, no adjudication, no further dispatch, and no continuing until Pass. It runs a missing active check only when review authority covers that exact check; otherwise it reports Needs evidence.
-- Findings are evidence, not commands or correction authority. Derive the judgment from your dispositions; never adopt the reviewer's verdict wholesale. Actual correction belongs to [Execute Work](../../skills/execute-work/SKILL.md) under covered authority.
-- Never lower acceptance or change tests, Specs, policies, or source truth to obtain Pass, and never review until Pass.
-- Never request Review 4. Renaming scope, changing reviewers, or making a local correction does not reset the review budget.
+- Independent review is never automatic after implementation, after self-review, or after writing or revising a Spec or Plan. Select it only when requested, or justified and authorized, to protect a concrete risk, dependency, integration, delivery, or intended-use boundary. At a hand-over, the user's review mode `always`, or `auto` when the Review Gate below fires, authorizes it; under `off`, propose it and wait for a yes. A review budget permits no dispatch by itself, and switching models or compute profiles, or loading this skill, does not create independence: it needs a separately selected reviewer in a separate context. A reviewer from another model family is not required: it changes what gets flagged but has not been shown to find more real defects. Record the reviewer as the Judge Contract says.
+- An independent reviewer reports and stops: no edits, no owner decisions, no choosing among materially different remedies or revisions, no adjudication, no further dispatch, and no continuing until Pass. It runs only what its brief's `May run` line names: by default the project's declared checks (tests, build, typecheck, the feature map's drive steps), in its own copy, with no edits, network calls, or paid runs; another check only when the brief names it with its expected evidence and stop condition. Otherwise it reports Needs evidence.
+- Findings are evidence, not commands or authority to correct or revise. Derive the judgment from your dispositions rather than adopting the reviewer's verdict or conclusion. Actual correction of work belongs to [Execute Work](../../skills/execute-work/SKILL.md) under covered authority; actual revision of an artifact returns to the artifact's owning skill.
+- Never lower acceptance or change tests, Specs, policies, or source truth to obtain Pass. Never settle a user decision or revise upstream intent, accepted content, or owner decisions merely to make an artifact consistent or to obtain Pass. Never repeat a review merely to obtain Pass.
+- Never request Review 4. Renaming scope or intended use, changing reviewers, or making a local correction or revision does not reset the review budget.
+- Never present a review judgment or an artifact's fitness as acceptance, implementation, or execution authority.
 
-## Choose The Review Role
+## Before Any Review
 
-Goal: the review done is the one the boundary needs.
+The project's Review Rules (or `REVIEW.md`), read from the base branch, feed the kind's classes and lenses, never a new class.
 
-- **Self-review:** the producer checks its own supported result before accepting or reusing it. This is the normal required route.
-- **Independent review:** a separately selected reviewer judges a state it did not produce, from a separate context.
-- **Adjudication:** the receiving agent checks a returned independent report and decides what its findings establish.
+Before a model reviews anything, run the deterministic checks that apply and could fail on their own, such as the project's checks, a validator, a docs check, or a definition loader. Give their results to the reviewer as evidence. A model review does not replace a check that can fail mechanically.
 
-## Establish What The Review Protects
+## Classify Before Calling Something A Defect
 
-Goal: judge the actual state against its real sources, not the producer's account of it.
+Goal: every reported item is supported and names the right kind of problem.
 
-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.
+Ask in order:
 
-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.
+1. Is the relevant behavior or source truth settled (for an artifact, also the content and any owner choice its intended use depends on)? If not, report a **Question** when it affects the boundary or intended use.
+2. Are reachability, the load-bearing claim, and the material consequence supported by available evidence? If not, report **Needs evidence**, not a hypothetical defect.
+3. Does this boundary or intended use require correction or revision? If it cannot safely be crossed, report a **Blocking Issue**. If correction or revision is required but safely deferrable, report a **Non-blocking Issue**.
+4. Is it merely useful beyond this boundary or use? Omit it by default, or identify an **Improvement** when materially relevant or explicitly requested.
 
-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 [Security Risk Lens](references/security-risk-lens.md).
+A defect the change did not introduce is **Pre-existing**: report it for the user with the evidence that it predates the change, never as Blocking.
 
-Use [Action Selection](../../skills/action-selection/SKILL.md) for uncertain or broad inspection; an obvious diff or source read needs no selection exercise.
+An Issue needs an exact location, path, or dependency; the violated requirement, invariant, source, or artifact responsibility; supporting evidence; and a concrete consequence. Name the defect's class and every other place in the reviewed state where it occurs, not one instance. A Blocking Issue must explain why the protected boundary cannot be crossed or the intended use cannot proceed, and name the correction constraints or the owning activity to re-enter. Recommend a specific correction or revision only when source intent, evidence, and dependency consequences support it rather than merely make it plausible.
 
-## Apply The Same Technical Kernel
+Needs evidence identifies the load-bearing claim, required observer, existing evidence and its limit, why the gap matters, and the smallest observation that could disagree. First establish that the stronger claim is required; missing proof of an optional guarantee does not justify more work, and an optional stronger claim may be qualified rather than expanding the task. Check whether supplied observations apply to the reviewed candidate and whether material assertion changes preserved the required property. For an artifact, check which source or check state a reported pass examined and whether later changes reduced acceptance or invalidated it; a newer report cannot repair that mismatch. A missing or stale result is not itself a code defect: recover evidence or establish the observer before prescribing a fix. When you can recover it yourself, by running a check you are authorized to run or by reading the code, do so and judge from what you observed: a check the author skipped and you have since run is not Needs evidence.
 
-Goal: use only the lenses that can change the boundary judgment.
+Do not turn preferences, wording or presentation, imagined or exhaustive edge cases, intentional deferrals, or hypothetical completeness into Issues. Finding no material issue is valid.
 
-- **Alignment:** required behavior and accepted amendments are implemented without omission or invented obligations.
-- **Correctness and integration:** reachable paths, affected callers, and components work together without regressions.
-- **Failure and risk:** material errors, recovery, permissions, data, and compatibility are handled as required.
-- **Evidence:** claims are supported at their required observing boundaries, not merely by green summaries.
-- **Design and minimality:** complexity and coordination serve requirements or demonstrated needs rather than optional stronger guarantees.
-- **Maintainability:** behavior and failure paths remain understandable and changeable.
+## Self-Review And Re-enter Narrowly
 
-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.
+Goal: catch real defects in your own result without turning review into an open-ended editing or rewriting loop.
 
-## Classify Before Calling Something A Defect
+Apply the kind's lenses silently once evidence initially supports the produced result or the artifact's load-bearing facts; do not create formal review items, a numbered review cycle, or an independent-review judgment for self-review. For work, also run Work Review's decision and test-integrity checks.
 
-Goal: every reported item is supported and names the right kind of problem.
+For one clear covered defect (for an artifact, one whose revision basis is settled), return to the producing or authoring activity, correct or revise it, reconcile an artifact's affected dependencies within authority, re-verify the affected boundary or factual claims, and repeat only the affected lenses once (for an artifact, source alignment as well). Do not restart every check or add a reviewer because a local correction occurred. Route anything else as below.
 
-Ask in order:
+Stop self-review when the supported state is accepted, the artifact is fit for its agreed use, or a material issue has a clear next route. Optional polish is not permission to continue editing, and self-review is not a reason to add independent review.
 
-1. Is the relevant behavior or source truth settled? If not, report a **Question** when it affects the boundary.
-2. Are reachability and material consequence supported? If not, report **Needs evidence**, not a hypothetical defect.
-3. Does this boundary require correction? If it cannot safely be crossed, report a **Blocking Issue**. If correction is required but safely deferrable, report a **Non-blocking Issue**.
-4. Is it merely useful beyond this boundary? Omit it by default, or identify an **Improvement** when materially relevant or explicitly requested.
+## Route A Problem To Its Owner
 
-An Issue needs an exact location or path, the violated requirement or invariant, supporting evidence, and a concrete consequence; a Blocking Issue must explain why the protected boundary cannot be crossed.
+When a problem is not one clear covered defect, in self-review or adjudication, send it by what changed:
 
-Needs evidence identifies the claim, required observer, existing evidence and its limit, why the gap matters, and the smallest observation that could disagree. First establish that the stronger claim is required; missing proof of an optional guarantee does not justify more work. Check whether supplied observations apply to the reviewed candidate and whether material assertion changes preserved the required property. A missing or stale result is not itself a code defect: recover evidence or establish the observer before prescribing a fix.
+- the outcome remains settled but the implementation approach is invalidated: back to implementation preparation in Execute Work;
+- an unclear, unsupported, or repeated cause: Execute Work's [diagnose](../../skills/execute-work/references/diagnose.md);
+- changed direction or strategy, unsettled behavior or content, materially different remedies or revisions, a user-owned choice, a scope change, or a source conflict: [Discuss Work](../../skills/discuss-work/SKILL.md);
+- missing factual support: the named claim to Verify Work;
+- a correction, revision, or dependency update the current authority does not cover: propose the bounded change once and wait.
 
-Do not turn preferences, imagined edge cases, intentional deferrals, or hypothetical completeness into Issues. Finding no material issue is valid.
+## The Review Gate
 
-## Self-Review And Re-enter Narrowly
+Goal: at a hand-over, the work gets the independent review its risk calls for, as the user's review mode says.
+
+A **hand-over** is the end of the agreed work, when it goes back to the user to accept: before [Deliver Work](../../skills/deliver-work/SKILL.md) merges or opens a pull request for it, or before the final report when nothing is delivered. Self-review of an intermediate result, such as one Slice or a small local fix, needs no gate.
+
+The user sets a review mode, and optionally a reviewer model, as `"review": { "mode": ..., "model": ... }` in `.freeflow/local.json` (personal) or `.freeflow/config.json` (shared). The Runtime State shows a `Review:` line when one is set; with none, the mode is `auto`.
+
+- `auto`: the triggers below decide. When one fires, dispatch an independent review; the trigger and the mode are its authorization. When none fires, self-review is enough.
+- `off`: never dispatch on your own. When a trigger would fire, propose an independent review to the user with the trigger and its estimated cost, and run it only after their yes.
+- `always`: dispatch an independent review at every hand-over.
+
+A user's explicit request for an independent review authorizes it in any mode.
 
-Goal: catch real defects in your own result without turning review into an open-ended editing loop.
+The gate fires when the change touches:
 
-Apply the kernel silently after evidence initially supports the produced result; do not create formal review items, a numbered review cycle, or an independent-review judgment for self-review.
+- security, authentication, authorization, or secrets;
+- possible data loss, or a migration of stored data;
+- CI or release files;
+- a public interface: anything users or other code depend on, such as CLI flags, config keys, exported APIs, and skill names and descriptions;
+- a path the project's Review Rules mark sensitive;
+- anything the work agreement names for review.
 
-For one clear covered defect, return to the producer, correct it, re-verify the affected boundary, and repeat only the affected lenses once. Do not restart every check or add a reviewer because a local correction occurred.
+Judge from the diff against the base, not from how the task was described. A trigger that fires is enough; a small diff does not cancel it.
 
-When the outcome remains settled but the approach is invalidated, return for implementation preparation. Use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) for unclear or repeatedly failing causes, [Decision Gate](../../skills/decision-gate/SKILL.md) for unsettled accepted behavior or a user-owned choice, and Workflow for coordination or scope changes.
+Use the user's reviewer model when set. Otherwise use the cheapest model capable of the review: the `standard` tier. When a security, authentication, authorization, or secrets trigger fires, use a stronger model: the `security` tier. The estimated cost names the reviewer model and roughly what one review of a change this size costs on it.
 
-Stop self-review when the supported state is accepted or a material issue has a clear next route. Optional polish is not permission to continue editing.
+When the task has a Working Record, record the gate as one `Review gate` Material update through [Track Work](../../skills/track-work/SKILL.md), in the shape its [format reference](../../skills/track-work/references/working-record-format.md) defines; its tier is `standard`, `security`, or `none` when the result is `skipped`. Without a record, state the same in the hand-over report.
 
 ## Perform A Selected Independent Review
 
 Goal: a separate context judges the state from the evidence and reports once.
 
-Before preparing or performing it, read [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md). Use supplied and available evidence; a covered active check uses Verify Work's check-result and claim-result semantics without changing review ownership. Recommend a specific correction only when supported rather than merely plausible.
+The reviewer did not produce the reviewed state. Give it, or point it to, the work product or the complete artifact, source truth, dependencies, and evidence needed to judge it directly, never only the producer's summary, reasoning, claimed result, or change description. Brief a reviewer of work with pointers to where its inputs live, not pasted copies, and run [check-brief](scripts/check-brief.mjs) on the brief before dispatching, as Work Review's Independent Review says; [review-packet](scripts/review-packet.mjs) prefills that brief from the task folder, names the gate triggers the diff shows and the round budget, and runs check-brief; brief a reviewer of anything else with Artifact Review's prompt. When the task has a task directory, save the brief as `scratch/reviews/R<n>-brief.md` there and the returned report as `R<n>-report.md` beside it, where `<n>` is the review number. Delete nothing there without the user's yes.
+
+Use supplied and available evidence; a covered active check uses Verify Work's check-result and claim-result semantics without changing review ownership.
 
 The independent judgment is:
 
@@ -94,34 +132,20 @@ The independent judgment is:
 - **Non-blocking:** only Non-blocking Issues remain.
 - **Pass:** no Issues or material unresolved items remain.
 
-Improvements do not change the judgment or authorize implementation. Every judgment ends the review.
-
-## Adjudicate The Returned Report
-
-Goal: decide what the report actually establishes before acting on it.
-
-Read [Adjudicate Work Review](references/adjudicate-work-review.md) before adjudicating. Check each material finding against the actual reviewed state, sources, and evidence:
-
-- **Accepted:** supported and applicable.
-- **Rejected:** unsupported, stale, already resolved, duplicate, preference-only, out of scope, or based on a source misread.
-- **Open:** evidence or a decision is missing.
-
-Pass permits proceeding at the reviewed boundary. Non-blocking permits proceeding with explicit deferrals. Inconclusive requires the missing evidence or decision. Blocking prevents crossing the boundary and returns the smallest supported correction or reconsideration to its owner.
-
-When correction is ready, state the supported problem, remedy, rationale, verification boundary, authority, and whether independent follow-up is still warranted.
+Improvements and Pre-existing items do not change the judgment or authorize implementation or revision. Every judgment ends the review.
 
 ## Bound Independent Review
 
 Goal: independent judgment is spent where it changes the outcome.
 
-For the same state and boundary:
+For the same reviewed state and boundary or intended use:
 
 - **Review 1:** first selected independent review, broad by default.
-- **Review 2:** separately selected focused follow-up when corrections, affected interactions, new evidence, or remaining risk still require independent judgment.
-- **Review 3:** exceptional, separately authorized, and final; only after the cause and correction boundary are understood.
+- **Review 2:** separately selected focused follow-up when corrections or revisions, affected interactions or dependencies, new evidence, or remaining risk still require independent judgment.
+- **Review 3:** exceptional, separately authorized, and final; only after the cause, revision basis, and correction or dependency boundary are understood.
 
-A fix does not automatically require another review. If Review 2 remains Blocking, diagnose a repeated, extending, or unclear cause; return an unrelated clear local defect to its owner when diagnosis would add no information, rather than fix and dispatch Review 3 automatically. Workflow may start a new cycle only for a materially new reviewed state and boundary. Self-review does not consume this budget.
+A fix or revision does not automatically require another review. If Review 2 remains Blocking, adjudicate it before acting again; then diagnose a repeated, extending, invalidating, or unclear cause, and return an unrelated clear local defect to its owner when diagnosis would add no information, rather than fix and dispatch Review 3 automatically. If Review 3 remains Blocking, rethink the approach rather than correct it again: route the blocker to diagnose, or to Discuss Work when the approach itself is in question. Start a new cycle only for a materially new reviewed state and boundary or intended use. Self-review does not consume this budget.
 
 ## Stop At The Selected Result
 
-Self-review ends with acceptance or a routed issue. Independent review ends with its report. Adjudication ends with dispositions and an explicit next route. Do not turn optional improvement into unfinished work; preserve the agreed user-facing return boundary and any unresolved limits.
+Self-review ends with acceptance, supported fitness, or a routed issue. Independent review ends with its report. Adjudication ends with dispositions and an explicit next route. Do not turn optional improvement into unfinished work; preserve the agreed user-facing return boundary and any unresolved limits.

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

@@ -0,0 +1,94 @@
+# Adjudicate A Returned Review
+
+This reference is judgment; Review Work's Rules still bind. Adjudication belongs to the receiving active agent. It tests the report against the reviewed state or artifact, source truth, dependencies, 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 problem in the work or the artifact;
+- its consequence for the reviewed boundary or the intended use;
+- whether it is Blocking or Non-blocking;
+- for work, whether its cause is supported, unnecessary to select a clear local correction, or uncertain; for an artifact, whether the revision basis is supported or uncertain;
+- for an artifact, which dependencies or contingent material it affects.
+
+### Rejected
+
+State the concrete reason: unsupported, stale, resolved, duplicate, preference-only, out of scope or outside the artifact's job, or based on a source or dependency misread.
+
+Never close a security finding (one about what [Security Risk Lens](work.md#security-risk-lens) covers) as Rejected on your own: give the user the finding and your reason, and keep it Open until they agree.
+
+### Open
+
+State:
+
+- the unresolved concern, content, claim, or dependency;
+- its potential consequence for the boundary or the intended use;
+- the missing evidence or owner decision.
+
+When factual evidence is missing, hand the item to Verify Work as a Needs evidence item, with the fields Review Work's classification gives one.
+
+A suggested correction or revision may help explain a finding, but it does not establish cause, settle source intent, select the remedy or among material alternatives, or authorize implementation or revision.
+
+## Derive The Judgment
+
+After disposing the items, derive the adjudicated judgment with Review Work's independent-judgment ladder, counting only Accepted Issues and material Open items. Do not separately accept the reviewer's overall judgment.
+
+Pass permits proceeding at the reviewed boundary or with the intended use. Non-blocking permits it with explicit deferrals. Inconclusive requires the missing evidence or decision. Blocking prevents crossing the boundary or the disputed use and returns the smallest supported correction, revision, or reconsideration to its owner (for an artifact, its owning skill).
+
+## Use Verification Results
+
+Route a known material evidence gap 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. By its claim result:
+
+- **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 The Correction Or Revision Is Ready
+
+It is ready when:
+
+- required behavior is settled, or for an artifact, its job and intended use are settled;
+- the problem and its consequence are supported;
+- enough cause, source, or decision basis exists to bound the correction or revision;
+- affected interactions and upstream and downstream dependencies are known sufficiently;
+- for an artifact, the revision will not silently alter accepted content or an owner decision;
+- no material alternative or user-owned choice remains.
+
+When it is ready, state:
+
+- the proposed correction or revision and its rationale;
+- affected behavior, locations, and dependencies;
+- required ordering, constraints, or reconciliation;
+- regression evidence, acceptance checks, and the verification boundary;
+- whether focused independent follow-up remains justified;
+- the authority state.
+
+Use existing correction or revision authority only when it covers that result (for an artifact revision, also its dependency impact). Otherwise propose the change and any warranted follow-up once, then wait. A finding, adjudication, or selected review does not authorize mutation.
+
+Actual correction of work returns to [Execute Work](../../../skills/execute-work/SKILL.md). Actual revision of an artifact returns to the artifact's owning skill: [Track Work](../../../skills/track-work/SKILL.md) for a Working Record or a handoff, and [Write Docs](../../../skills/write-docs/SKILL.md) for a Spec, Plan, decision record or documentation.
+
+When it is not ready, route it as Review Work's "Route A Problem To Its Owner" says. When findings interact, assumptions or upstream authority are challenged, dependency effects remain uncertain, or user input could change the remedy or revision, report a problem checkpoint and stop before selecting or executing it.
+
+## After An Authorized Correction Or Revision
+
+For work, verify the affected boundary and perform ordinary self-review. For an artifact, re-verify affected load-bearing factual claims at their required observing boundaries, then re-check source alignment, intended-use fitness, and every affected dependency before ordinary self-review with the artifact lenses.
+
+Whether a follow-up review is warranted, and what to do when Review 2 or 3 remains Blocking, is Review Work's "Bound Independent Review". Do not dispatch follow-up merely because Review 1 found an Issue or because a correction or revision occurred.
+
+## Record The Review
+
+Append the dispositions, each with its reason, and the derived judgment to the saved report (`scratch/reviews/R<n>-report.md` when the task has a task directory; otherwise give them in the hand-over report). Keep Rejected items and their reasons, so a rejection can be checked later against what turned out to be true.
+
+When the task has a Working Record, then record one `Review` Material update per independent review through [Track Work](../../../skills/track-work/SKILL.md), in the shape its [format reference](../../../skills/track-work/references/working-record-format.md) defines. Its judgment is the adjudicated one, not the reviewer's; its effect is the next route.
+
+## Stop
+
+Stop when every material item is Accepted, Rejected, or Open; the adjudicated judgment is supported; for an artifact, affected dependencies and contingent material are explicit; and the next route and authority state are clear.