@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/track-work/scripts/working-record.mjs

@@ -1,122 +1,316 @@
 #!/usr/bin/env node
 
-import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
-import { CommittedResultError } from "./lib/record-store.mjs";
-import { WorkingRecordError, fail } from "./lib/model.mjs";
-import { baseEnvelope, errorItems } from "./lib/result.mjs";
-import { executeCommand, readJsonInput } from "./lib/commands.mjs";
+import { rm } from "node:fs/promises";
+import { cwd } from "node:process";
+import { dirname } from "node:path";
+import { canonicalLines, joinLines, slugify, TASK_STATES } from "./lib/format.mjs";
+import { parseDocument, validateDocument } from "./lib/document.mjs";
+import { runTransition } from "./lib/transitions.mjs";
+import {
+  createRecordPath,
+  displayPath,
+  readInput,
+  readRecord,
+  resolveRecordPath,
+  writeInitialAtomically,
+} from "./lib/store.mjs";
+import { renderFull, renderResume } from "./lib/views.mjs";
 
-function parseCliArgs(args) {
-  const positionals = [];
+function usage() {
+  return [
+    "Usage:",
+    "  working-record.mjs init --root <path> --name <task name> [--input <file|->]",
+    "  working-record.mjs view resume|full --record <record.md>",
+    "  working-record.mjs validate --record <record.md>",
+    "  working-record.mjs <slice|checkpoint|decision|task> <operation> ...",
+  ].join("\n");
+}
+
+const COMMAND_HELP = new Map([
+  [
+    "slice",
+    [
+      "Usage: working-record.mjs slice <operation> ...",
+      "Operations: slice propose, slice start, slice start-direct, slice pause, slice resume, slice close, slice reopen.",
+      "Run working-record.mjs <group> <operation> --help for options and input fields.",
+      "Use --input - to read Markdown fragments from stdin.",
+    ].join("\n"),
+  ],
+  [
+    "checkpoint",
+    [
+      "Usage: working-record.mjs checkpoint <operation> ...",
+      "Operations: checkpoint propose, checkpoint activate, checkpoint defer, checkpoint resume, checkpoint close.",
+      "Run working-record.mjs <group> <operation> --help for options and input fields.",
+      "Use --input - to read Markdown fragments from stdin.",
+    ].join("\n"),
+  ],
+  [
+    "decision",
+    [
+      "Usage: working-record.mjs decision <operation> ...",
+      "Operations: decision add, decision supersede, decision retire.",
+      "Run working-record.mjs <group> <operation> --help for options and input fields.",
+      "Use --input - to read Markdown fragments from stdin.",
+    ].join("\n"),
+  ],
+  [
+    "task",
+    [
+      "Usage: working-record.mjs task <operation> ...",
+      "Operations: task set-state.",
+      "Run working-record.mjs <group> <operation> --help for options and input fields.",
+    ].join("\n"),
+  ],
+  [
+    "init",
+    "Usage: init --root <path> --name <task name> [--state <state>] [--input <file|->]\nInput: Goal and Next useful action required; the seven Current Context headings are accepted. Use --input - to read Markdown fragments from stdin.",
+  ],
+  ["view", "Usage: view resume|full --record <record.md>"],
+  ["validate", "Usage: validate --record <record.md>"],
+  [
+    "slice propose",
+    "Usage: slice propose --record <record.md> --title <title> --input <file|->\nInput: Intended result required; Type, Expected evidence, and Dependencies optional. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "slice start",
+    "Usage: slice start --record <record.md> --title <proposal title> --next-action <text> --input <file|->\nInput: Authority source, Scope, Expected evidence, Stop condition, and Starting state required. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "slice start-direct",
+    "Usage: slice start-direct --record <record.md> --title <title> --next-action <text> --input <file|->\nInput: Intended result, Authority source, Scope, Expected evidence, Stop condition, and Starting state required; Future Work is unchanged. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "slice pause",
+    "Usage: slice pause --record <record.md> --reason <reason> --resume-when <condition> --next-action <text>",
+  ],
+  ["slice resume", "Usage: slice resume --record <record.md> --resolution <source> --next-action <text>"],
+  [
+    "slice close",
+    "Usage: slice close --record <record.md> --state <completed|blocked|abandoned> --next-action <text> --input <file|->\nInput: Result, Evidence and limits, and Task effect required. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "slice reopen",
+    "Usage: slice reopen --record <record.md> --id <S-NNN> --next-action <text> --input <file|->\nInput: fresh Authority source, Scope, Expected evidence, Stop condition, and Starting state required. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "checkpoint propose",
+    "Usage: checkpoint propose --record <record.md> --title <title> --input <file|->\nInput: Type, Condition, and Applies to required. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "checkpoint activate",
+    "Usage: checkpoint activate --record <record.md> --title <proposal title> [--next-action <text>]",
+  ],
+  ["checkpoint defer", "Usage: checkpoint defer --record <record.md> --id <C-NNN> [--next-action <text>]"],
+  ["checkpoint resume", "Usage: checkpoint resume --record <record.md> --id <C-NNN> [--next-action <text>]"],
+  [
+    "checkpoint close",
+    "Usage: checkpoint close --record <record.md> --id <C-NNN> --state <completed|cancelled|replaced> [--next-action <text>] --input <file|->\nInput: Result and Task effect required; Evidence optional; Reason required for cancelled or replaced; Replaced by required for replaced. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "decision add",
+    "Usage: decision add --record <record.md> --title <title> --input <file|->\nInput: Decision, Established by, Rationale, Consequences, and Revisit when required; Source references optional. Use --input - to read the fragment from stdin.",
+  ],
+  [
+    "decision supersede",
+    "Usage: decision supersede --record <record.md> --id <D-NNN> --title <title> --input <file|->\nInput: Decision, Established by, Rationale, Consequences, and Revisit when required; Source references optional. Use --input - to read the fragment from stdin.",
+  ],
+  ["decision retire", "Usage: decision retire --record <record.md> --id <D-NNN> --reason <reason>"],
+  [
+    "task set-state",
+    "Usage: task set-state --record <record.md> --state <active|paused|completed|abandoned> --next-action <text>",
+  ],
+]);
+
+function commandHelp(command, operation) {
+  return `${COMMAND_HELP.get([command, operation].filter(Boolean).join(" ")) ?? COMMAND_HELP.get(command) ?? usage()}\n`;
+}
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+function parseOptions(args) {
   const options = {};
-  const flags = new Set(["--dry-run", "--help"]);
+  const positionals = [];
   for (let index = 0; index < args.length; index += 1) {
-    const argument = args[index];
-    if (!argument.startsWith("--")) {
-      positionals.push(argument);
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
       continue;
     }
-    const equals = argument.indexOf("=");
-    const key = equals >= 0 ? argument.slice(0, equals) : argument;
-    if (Object.hasOwn(options, key)) fail("duplicate-option", `Option may be supplied once: ${key}`);
-    if (flags.has(key)) {
-      options[key] = true;
-      if (equals >= 0) fail("invalid-option", `${key} does not accept a value`);
+    if (options[token] !== undefined) throw new CliError(`Duplicate option: ${token}`);
+    if (token === "--help") {
+      options[token] = true;
       continue;
     }
-    const value = equals >= 0 ? argument.slice(equals + 1) : args[++index];
-    if (value === undefined || value.startsWith("--")) fail("missing-option-value", `Option requires a value: ${key}`);
-    options[key] = value;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new CliError(`Missing value for ${token}`);
+    options[token] = value;
+    index += 1;
   }
-  return { positionals, options };
+  return { options, positionals };
 }
-function usage() {
-  return `Usage: node skills/track-work/scripts/working-record.mjs <command> [options]
 
-Commands:
-  init     --root <repo> --name <short-name> [--input <json-file|->] [--dry-run]
-  view     --record <record.md> --view <resume|discuss|execute|recent|entity|full> [--entity <id-or-title>]
-  schema   --command <init|update|start|block|resume|reopen|close|unlock|migrate|compress|all> [--help]
-  update   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  start    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  block    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  resume   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  reopen   --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  close    --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  unlock   --record <record.md> --input <json-file|->
-  migrate  --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  compress --record <record.md> --expected-sha <sha256> --input <json-file|-> [--dry-run]
-  validate --record <record.md>
-  inspect  --record <record.md>
+function allowedOptions(command, operation) {
+  const common = new Set(["--root", "--record", "--input", "--help"]);
+  const withNextAction = new Set([...common, "--next-action"]);
+  if (command === "init") return new Set(["--root", "--name", "--state", "--input", "--help"]);
+  if (command === "view") return new Set(["--root", "--record", "--view", "--help"]);
+  if (command === "validate") return new Set(["--root", "--record", "--help"]);
+  if (command === "slice") {
+    if (operation === "propose") return new Set([...common, "--title"]);
+    if (operation === "start" || operation === "start-direct") return new Set([...withNextAction, "--title"]);
+    if (operation === "pause") return new Set([...withNextAction, "--reason", "--resume-when"]);
+    if (operation === "resume") return new Set([...withNextAction, "--resolution"]);
+    if (operation === "close") return new Set([...withNextAction, "--state"]);
+    if (operation === "reopen") return new Set([...withNextAction, "--id", "--title"]);
+  }
+  if (command === "checkpoint") {
+    if (operation === "propose") return new Set([...common, "--title"]);
+    if (operation === "activate") return new Set([...withNextAction, "--title"]);
+    if (operation === "defer" || operation === "resume") return new Set([...withNextAction, "--id"]);
+    if (operation === "close") return new Set([...withNextAction, "--id", "--state"]);
+  }
+  if (command === "decision") {
+    if (operation === "add") return new Set([...common, "--title"]);
+    if (operation === "supersede") return new Set([...common, "--id", "--title"]);
+    if (operation === "retire") return new Set(["--root", "--record", "--id", "--reason", "--input", "--help"]);
+  }
+  if (command === "task" && operation === "set-state")
+    return new Set(["--root", "--record", "--state", "--next-action", "--help"]);
+  return null;
+}
 
-Views emit bounded Markdown text. Other commands emit one JSON result. Existing-record mutations require the current SHA-256. Use --input - to read semantic JSON from stdin.
-`;
+function validateCommandOptions(command, operation, options) {
+  const allowed = allowedOptions(command, operation);
+  if (!allowed) throw new CliError(`Unknown command: ${command}${operation ? ` ${operation}` : ""}`);
+  for (const name of Object.keys(options)) {
+    if (!allowed.has(name))
+      throw new CliError(`Unknown option ${name} for ${command}${operation ? ` ${operation}` : ""}`);
+  }
 }
 
-export { executeCommand };
+function requireOption(options, name) {
+  const value = options[name];
+  if (!value) throw new CliError(`Missing required option: ${name}`);
+  return value;
+}
 
-async function main() {
-  const [command, ...args] = process.argv.slice(2);
-  if (!command || command === "--help" || command === "-h") {
-    process.stdout.write(usage());
-    return;
-  }
-  const { positionals, options } = parseCliArgs(args);
-  if (options["--help"]) {
-    process.stdout.write(usage());
-    return;
+function rootOption(options) {
+  return options["--root"] ?? cwd();
+}
+
+function initialContent(skeletonLines, input) {
+  if (!input.trim()) return joinLines(skeletonLines, "\n");
+  const inputLines = input.replace(/\r\n?/g, "\n").split("\n");
+  const targets = new Map();
+  const names = [
+    "Goal",
+    "What defines this task",
+    "Settled",
+    "Tentative",
+    "Open",
+    "Current direction",
+    "Boundaries",
+    "Next useful action",
+  ];
+  const allowed = new Set(names);
+  for (let index = 0; index < inputLines.length; index += 1) {
+    const levelThree = /^### (.+?)\s*$/.exec(inputLines[index]);
+    if (levelThree) {
+      const name = levelThree[1];
+      if (!allowed.has(name)) throw new CliError(`Unknown initialization heading: ${name}`);
+      if (targets.has(name)) throw new CliError(`Duplicate initialization heading: ${name}`);
+      const content = [];
+      for (let next = index + 1; next < inputLines.length; next += 1) {
+        if (/^### /.test(inputLines[next]) || /^## /.test(inputLines[next])) break;
+        content.push(inputLines[next]);
+      }
+      targets.set(name, content);
+      continue;
+    }
+    if (/^## /.test(inputLines[index])) throw new CliError(`Unknown initialization heading: ${inputLines[index]}`);
   }
-  const root = options["--root"] ? resolve(options["--root"]) : process.cwd();
-  if (positionals.length > 1) fail("invalid-arguments", "Only one positional record or task path is supported");
-  if (positionals.length === 1 && !options["--record"] && !options["--task"]) options["--record"] = positionals[0];
-  const input = await readJsonInput(options);
-  const result = await executeCommand(command, { root, options, input });
-  if (command === "view" || command === "resume-view") {
-    process.stdout.write(result.view?.content ?? "");
-  } else if (command === "schema") {
-    process.stdout.write(result.content ?? "");
-  } else {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  const output = [...skeletonLines];
+  for (const name of names) {
+    const content = targets.get(name);
+    if (!content) continue;
+    const headingIndex = output.findIndex((line) => line === `### ${name}`);
+    if (headingIndex < 0) continue;
+    let end = headingIndex + 1;
+    while (end < output.length && !/^### |^## /.test(output[end])) end += 1;
+    const trimmed = [...content];
+    while (trimmed.length && trimmed[0].trim() === "") trimmed.shift();
+    while (trimmed.length && trimmed[trimmed.length - 1].trim() === "") trimmed.pop();
+    output.splice(headingIndex + 1, end - headingIndex - 1, "", ...trimmed, "");
   }
-  if (result.status === "committed-unconfirmed") process.exitCode = 2;
-  else if (result.status === "failed") process.exitCode = 1;
+  return joinLines(output, "\n");
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+async function initialize(options) {
+  const root = rootOption(options);
+  const name = requireOption(options, "--name");
+  const state = options["--state"] ?? "active";
+  if (!TASK_STATES.has(state)) throw new CliError(`Invalid task state: ${state}`);
+  const input = await readInput(options["--input"], cwd());
+  const text = initialContent(canonicalLines(name, state), input);
+  parseDocument(text);
+  const created = await createRecordPath(root, name, slugify(name));
   try {
-    await main();
+    await writeInitialAtomically(root, created.path, text);
   } catch (error) {
-    if (error instanceof CommittedResultError) {
-      process.stdout.write(`${JSON.stringify(error.result, null, 2)}\n`);
-      process.exitCode = 2;
-    } else {
-      const knownError = error instanceof WorkingRecordError;
-      const command = process.argv[2] ?? null;
-      if (command === "view" || command === "resume-view") {
-        process.stdout.write(`Track Work view failed [${error.code ?? "view-failed"}]: ${error.message}\n`);
-        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
-      } else if (command === "schema") {
-        process.stdout.write(`Track Work schema failed [${error.code ?? "schema-failed"}]: ${error.message}\n`);
-        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
-      } else {
-        const result = baseEnvelope(command, command, knownError ? error.record : null);
-        if (!result.record && knownError && error.details?.path) {
-          result.record = {
-            path: error.details.path,
-            confirmation: "unavailable",
-            sha256: error.details.sha256 ?? null,
-            schemaVersion: null,
-            taskState: null,
-            lastUpdated: null,
-            currentSlice: null,
-            unavailable: ["recordProjectionUnavailable"],
-          };
-        }
-        result.errors = errorItems(knownError ? error : new WorkingRecordError("unexpected-error", error.message));
-        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-        process.exitCode = error instanceof WorkingRecordError ? error.exitCode : 1;
-      }
-    }
+    if (error?.exitCode !== 2) await rm(dirname(created.path), { recursive: true, force: true }).catch(() => undefined);
+    throw error;
+  }
+  return `${created.path}\n`;
+}
+
+async function readExisting(options) {
+  const root = rootOption(options);
+  const recordOption = requireOption(options, "--record");
+  const loaded = await readRecord(root, resolveRecordPath(root, recordOption));
+  return { root, ...loaded };
+}
+
+async function runCore(command, rest) {
+  const { options, positionals } = parseOptions(rest);
+  const operation = positionals[0];
+  if (options["--help"]) return commandHelp(command, operation);
+  validateCommandOptions(command, operation, options);
+  if (command === "init") return initialize(options);
+  if (command === "view") {
+    if (positionals.length > 1) throw new CliError("View accepts only resume or full");
+    const view = positionals[0] ?? options["--view"];
+    if (!view || !["resume", "full"].includes(view)) throw new CliError("View must be resume or full");
+    const loaded = await readExisting(options);
+    if (view === "full") return renderFull(loaded.text);
+    return renderResume(loaded.text);
+  }
+  if (command === "validate") {
+    if (positionals.length) throw new CliError("Validate does not accept positional arguments");
+    const loaded = await readExisting(options);
+    validateDocument(parseDocument(loaded.text));
+    return `valid\n${displayPath(loaded.root, loaded.path)}\n`;
+  }
+  if (positionals.length !== 1) throw new CliError(`Expected one operation for ${command}`);
+  const loaded = await readExisting(options);
+  const input = await readInput(options["--input"], cwd());
+  return runTransition(command, positionals, options, input, loaded);
+}
+
+try {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "help") {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    process.stdout.write(await runCore(command, rest));
   }
+} catch (error) {
+  process.stderr.write(`Error: ${error.message}\n`);
+  process.exitCode = error.exitCode ?? 1;
 }

package/skills/verify-work/SKILL.md

@@ -11,7 +11,7 @@ Verification is factual: what ran, what happened, and what that result proves. T
 
 ## Name The Claim
 
-State the claim before choosing the check. Include the behavior or property and the boundary where it must hold.
+State the claim before choosing the check. Include the behavior or property and the boundary where it must hold. Keep this compact when both are obvious; do not let an available check silently narrow a broader claim.
 
 Claims may concern:
 
@@ -22,21 +22,21 @@ Claims may concern:
 - performance or resource bounds;
 - artifact completeness or repository state.
 
-Do not let an available check silently narrow a broader claim.
-
 ## Choose Evidence That Can Disagree
 
 Use the smallest direct evidence that can falsify the claim. Evidence must be fresh for the code, configuration, environment, and artifact being assessed.
 
-Verification inherits the current authority envelope. Existing evidence may be inspected without a new run. Run a new active check only when that envelope covers it directly or as contained verification; otherwise return its purpose, expected evidence, and stop condition to Workflow and wait.
+Verification inherits the current authority envelope. Existing evidence may be inspected without a new run. Run a new active check only when that envelope covers it directly or as contained verification; otherwise return its purpose, expected evidence, and stop condition to [Workflow](../../skills/workflow/SKILL.md) and wait.
+
+Verify Work owns the claim and required evidence boundary. When several covered observers can falsify the same claim, or the likely check is broad, use [Action Selection](../../skills/action-selection/SKILL.md) to choose and bound one environment interaction. It returns the observation; Verify Work interprets and classifies support. Skip it when one exact check is already selected.
 
-Verify Work owns the claim and required evidence boundary. When several covered observers can falsify the same claim, or the likely check is broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one environment interaction. It returns the observation; Verify Work interprets and classifies support. Skip it when one exact check is already selected.
+Before running covered checks concurrently, compare what each may write or remove. Run checks serially when they share generated directories, caches, build outputs, package roots, fixture state, ports, databases, or intentional stale-artifact files. A concurrency-induced red signal is orchestration evidence, not automatically an implementation defect; reproduce it under a non-overlapping or serial schedule before changing production code.
 
 Passing tests do not prove behavior they do not exercise. A happy path does not prove failure handling. Source inspection does not prove runtime execution. A helper call does not prove registration, host dispatch, or installed-package behavior.
 
 Before selecting or running evidence:
 
-- read [integration evidence](references/integration-evidence.md) when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, absence counter, or a check that may mutate shared state;
+- read [integration evidence](references/integration-evidence.md) when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, or absence counter;
 - read [browser runtime evidence](references/browser-runtime-evidence.md) when a claim depends on rendered UI, browser behavior, accessibility, client networking, console state, visual output, or browser runtime performance;
 - read [performance evidence](references/performance-evidence.md) when verifying latency, throughput, memory, CPU, bundle, query, rendering, capacity, or resource-regression claims.
 
@@ -50,25 +50,28 @@ Once the selected check is authorized:
 
 1. Run the complete selected check.
 2. Read the relevant output, exit status, and lower-level evidence that can contradict a summary.
-3. Confirm the intended success or failure path and observing boundary were exercised.
-4. Compare the observation with the exact claim and source requirement.
-5. Preserve contradictory evidence; do not rerun until an unfavorable result disappears.
-6. State unavailable, stale, partial, or reduced-fidelity evidence honestly.
+3. Confirm the defined assertion and intended success or failure path were exercised.
+4. Confirm the observing boundary actually matched the claim.
+5. Compare the observation with the exact claim and source requirement.
+6. Preserve contradictory evidence; do not rerun until an unfavorable result disappears.
+7. State unavailable, stale, partial, or reduced-fidelity evidence honestly.
 
 Do not convert missing evidence into zero, safe, passed, or probably correct. If the user skips a check, respect that choice and leave the corresponding claim unverified.
 
-Do not change implementation, tests, checks, specs, policies, or acceptance merely to make the signal green. When the cause of a contradiction is unclear, report the contradiction rather than inventing one.
+Do not change implementation, tests, checks, Specs, policies, or acceptance merely to make the signal green. When the cause of a contradiction is unclear, report the contradiction rather than inventing one.
 
 ## Classify The Result
 
 Keep check execution separate from claim support.
 
-**Check result:**
+**Check result** is relative to the check's defined assertion—not whether the target operation happened to succeed or fail:
 
-- **Passed:** the check completed successfully.
-- **Failed:** the check completed and observed a failure.
-- **Error:** the check itself did not execute validly.
-- **Unavailable:** the required check could not be run.
+- **Passed:** the check executed validly and its defined assertion held.
+- **Failed:** the check executed validly and its defined assertion did not hold.
+- **Error:** the observing mechanism or check execution was invalid.
+- **Unavailable:** the required check could not be attempted safely or reliably.
+
+A check can Pass while intentionally observing rejection, failure, rollback, or fail-closed behavior.
 
 **Claim result:**
 
@@ -77,11 +80,34 @@ Keep check execution separate from claim support.
 - **Inconclusive:** evidence exists but cannot establish or refute the claim at the required boundary.
 - **Unavailable:** the required evidence cannot currently be obtained safely or reliably.
 
-A passed check may still leave the claim inconclusive. A failed check may expose an implementation defect, an invalid check, an environment problem, or a source conflict; classify only what evidence supports.
+A Passed check may still leave the claim Inconclusive. A Failed check may expose an implementation defect, an invalid expectation, an environment problem, or a source conflict; classify only what evidence supports.
+
+When contradictory evidence is unexplained or failure repeats, read [Diagnose Failure](../../skills/diagnose-failure/SKILL.md). When evidence exposes a user-owned decision or source conflict, read [Decision Gate](../../skills/decision-gate/SKILL.md).
+
+## Return Evidence To Review
+
+When verification answers a review **Needs evidence** item, preserve the original review-item pointer, claim, required observing boundary, available evidence and prior limit, and why the gap affects review judgment.
+
+Return the verification result to the receiving agent for adjudication:
+
+- **Supported:** the factual gap may be resolved; do not infer review Pass.
+- **Contradicted:** the finding may be established, invalidated, or expose a source conflict; do not classify the review item here.
+- **Inconclusive:** the review item remains Open when the gap is material.
+- **Unavailable:** the review item remains Open and the observing limitation must remain explicit.
 
-When contradictory evidence is unexplained or failure repeats, read [Diagnose Failure](../diagnose-failure/SKILL.md). When evidence exposes a user-owned decision or source conflict, read [Decision Gate](../decision-gate/SKILL.md).
+Verification does not revise the independent review report, adjudicate findings, authorize correction, or select follow-up review.
+
+## Report Proportionately
+
+For one straightforward Supported claim with an obvious check and boundary, use the compact form:
+
+```text
+Claim @ required boundary: Supported ([check result]) by [evidence].
+Proves:
+Does not prove:
+```
 
-## Report
+Use the full form when the result is Contradicted, Inconclusive, or Unavailable; several claims or boundaries are involved; evidence conflicts; the claim is consequential; or the result returns to review adjudication:
 
 ```text
 Claim:
@@ -94,4 +120,4 @@ Does not prove:
 Required next evidence:
 ```
 
-Omit `Required next evidence` when the claim is fully supported or contradicted. When the result changes or ends the current path, use [Workflow](../workflow/SKILL.md) to choose what follows.
+When returning evidence for adjudication, prepend `Review item:` with the original item pointer. Omit `Required next evidence` when the claim is fully Supported or Contradicted. When the result changes or ends the current path, return it to [Workflow](../../skills/workflow/SKILL.md) to choose what follows.

package/skills/verify-work/references/browser-runtime-evidence.md

@@ -52,4 +52,4 @@ Stop or downgrade the claim when:
 - only a nearby path, screenshot, or mocked page was tested;
 - browser evidence contradicts tests, specs, or accepted behavior.
 
-Read [Diagnose Failure](../../diagnose-failure/SKILL.md) for unexplained browser failures. Read [Decision Gate](../../decision-gate/SKILL.md) when browser evidence conflicts with accepted behavior or exposes a user-owned decision.
+Read [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md) for unexplained browser failures. Read [Decision Gate](../../../skills/decision-gate/SKILL.md) when browser evidence conflicts with accepted behavior or exposes a user-owned decision.

package/skills/verify-work/references/integration-evidence.md

@@ -1,6 +1,6 @@
 # Integration Evidence
 
-Read this before selecting or running evidence when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, absence counter, or a check that may mutate shared state.
+Read this before selecting or running evidence when a claim depends on a registered callback or executor, host lifecycle, producer invocation, fallback protocol, installed package, or absence counter.
 
 ## Match The Boundary
 
@@ -28,12 +28,6 @@ A zero value proves absence only when:
 
 Prefer an adversarial disproof: bypass the producer, forge or replay the event, call the helper directly, or resolve code from the checkout instead of the installed root. The proof should fail before downstream work when the claimed boundary was not crossed.
 
-## Compare Mutation Footprints
-
-Before running checks concurrently, compare what each check may write or remove. Run checks serially when they share generated directories, caches, build outputs, package roots, fixture state, ports, databases, or intentional stale-artifact files.
-
-A concurrency-induced red signal is orchestration evidence, not automatically an implementation defect. Reproduce it under a non-overlapping or serial schedule before changing production code.
-
 ## Claim Map
 
 For sensitive or proof-bearing claims, record:

package/skills/verify-work/references/performance-evidence.md

@@ -54,4 +54,4 @@ Stop or downgrade the claim when:
 - only a nearby operation improved;
 - required production evidence is unavailable.
 
-Read [Diagnose Failure](../../diagnose-failure/SKILL.md) for unexplained regressions. Read [Decision Gate](../../decision-gate/SKILL.md) when the next step depends on a product, SLO, cost, or resource tradeoff owned by the user.
+Read [Diagnose Failure](../../../skills/diagnose-failure/SKILL.md) for unexplained regressions. Read [Decision Gate](../../../skills/decision-gate/SKILL.md) when the next step depends on a product, SLO, cost, or resource tradeoff owned by the user.