@hassangameryt/freeflow 0.7.3 → 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,121 +1,151 @@
 ---
 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.
 
-## Choose The Review Role
+Review has three roles:
 
-- **Self-review:** the producer checks its own supported result before accepting or reusing it. This is the normal required route.
+- **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.
 
-An independent reviewer reports and stops. It does not adjudicate its own findings or become the fixing agent. Switching models or loading this skill does not create independence.
+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.
 
-Independent review is not automatic after implementation or self-review. Select it through Workflow 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.
+## Routes
 
-## Establish What The Review Protects
+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.
 
-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.
+| 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 |
 
-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.
+## Rules
 
-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).
+- 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.
 
-Use [Action Selection](../../skills/action-selection/SKILL.md) for uncertain or broad inspection. An obvious diff or source read does not need another selection exercise.
+## Before Any Review
 
-## Apply The Same Technical Kernel
+The project's Review Rules (or `REVIEW.md`), read from the base branch, feed the kind's classes and lenses, never a new class.
 
-Use lenses that can change the boundary judgment:
-
-- **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.
-
-Do not assume more implementation is 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. Do not choose whichever source makes the work pass or treat every unselected experiment as a production obligation.
+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.
 
 ## Classify Before Calling Something A Defect
 
+Goal: every reported item is supported and names the right kind of problem.
+
 Ask in order:
 
-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.
+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.
 
-An Issue needs an exact location or path, violated requirement or invariant, supporting evidence, and concrete consequence. A Blocking Issue must explain why the protected boundary cannot be crossed.
+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.
 
-Needs evidence must identify the claim, required observer, existing evidence and 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 automatically 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.
+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.
 
-Do not turn preferences, imagined edge cases, intentional deferrals, or hypothetical completeness into Issues. Finding no material issue is valid.
+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.
+
+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.
 
 ## Self-Review And Re-enter Narrowly
 
-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.
+Goal: catch real defects in your own result without turning review into an open-ended editing or rewriting loop.
 
-For one clear covered defect, return to the producer, correct it, re-verify the affected boundary, and repeat only affected review lenses once. Do not restart every check or add a reviewer because a local correction occurred.
+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.
 
-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, and [Decision Gate](../../skills/decision-gate/SKILL.md) for unsettled accepted behavior or a user-owned choice. Return coordination or scope changes to [Workflow](../../skills/workflow/SKILL.md).
+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.
 
-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.
+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.
 
-## Perform A Selected Independent Review
+## Route A Problem To Its Owner
 
-Before preparing or performing it, read [Independent Work Reviewer Contract](references/independent-work-reviewer-contract.md).
+When a problem is not one clear covered defect, in self-review or adjudication, send it by what changed:
 
-Use supplied and available evidence. Do not run a missing active check unless review authority covers that exact check; otherwise report Needs evidence. A covered active check uses Verify Work's check-result and claim-result semantics without changing review ownership.
+- 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.
 
-Inspect and report without edits, choosing among materially different remedies, adjudication, another review dispatch, or continuing until Pass. Recommend a specific correction only when supported rather than merely plausible.
+## The Review Gate
 
-The independent judgment is:
+Goal: at a hand-over, the work gets the independent review its risk calls for, as the user's review mode says.
 
-- **Blocking:** at least one Blocking Issue.
-- **Inconclusive:** no Blocking Issue, but a material Question or Needs evidence prevents judgment.
-- **Non-blocking:** only Non-blocking Issues remain.
-- **Pass:** no Issues or material unresolved items remain.
+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.
 
-Improvements do not change the judgment or authorize implementation. Every judgment ends the review.
+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`.
 
-## Adjudicate The Returned Report
+- `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.
 
-Read [Adjudicate Work Review](references/adjudicate-work-review.md) before adjudicating.
+A user's explicit request for an independent review authorizes it in any mode.
 
-Check each material finding against the actual reviewed state, sources, and evidence:
+The gate fires when the change touches:
 
-- **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.
+- 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.
 
-Derive the overall judgment from those dispositions; do not separately accept the reviewer's verdict. Findings are evidence, not commands or correction authority.
+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.
 
-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.
+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.
+
+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
 
-When correction is ready, state the supported problem, remedy, rationale, verification boundary, authority, and whether independent follow-up is still warranted. Actual correction belongs to [Execute Work](../../skills/execute-work/SKILL.md), not the independent reviewer.
+Goal: a separate context judges the state from the evidence and reports once.
+
+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:
+
+- **Blocking:** at least one Blocking Issue.
+- **Inconclusive:** no Blocking Issue, but a material Question or Needs evidence prevents judgment.
+- **Non-blocking:** only Non-blocking Issues remain.
+- **Pass:** no Issues or material unresolved items remain.
+
+Improvements and Pre-existing items do not change the judgment or authorize implementation or revision. Every judgment ends the review.
 
 ## Bound Independent Review
 
-Keep the existing budget for the same state and boundary:
+Goal: independent judgment is spent where it changes the outcome.
 
-- **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; use only after the cause and correction boundary are understood.
+For the same reviewed state and boundary or intended use:
 
-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. Do not automatically fix and dispatch Review 3.
+- **Review 1:** first selected independent review, broad by default.
+- **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.
 
-Do not request Review 4. Renaming scope, changing reviewers, or making a local correction does not reset the budget. Workflow may establish 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 review until Pass, lower acceptance to obtain it, or 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.