@outerlayer/cli 0.33.0-next.20261022124145 → 0.33.0-next.20261022161023

package/dist/build-info.json

@@ -1 +1 @@
-{"id":"2026-10-22T12:43:11.879Z+45d3a2f","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}
+{"id":"2026-10-22T16:41:55.061Z+a212c93","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}

package/dist/{emit-criteria-cmd-IC5OIZX2.js → chunk-J42MMS4R.js}

@@ -2,32 +2,13 @@
 import { createRequire } from 'node:module';
 import { launchRefusalForSession } from './chunk-ESVW4MJY.js';
 import { detectActiveSession, autoConnect } from './chunk-C3XLVHN6.js';
-import './chunk-B3EE7OKK.js';
-import './chunk-EWVYQLD3.js';
 import { resolveRepoIdentity } from './chunk-5DNCFOXA.js';
-import './chunk-HJYBWJAS.js';
-import './chunk-NSPRS7WK.js';
-import './chunk-G2JWZDFA.js';
 import { C } from './chunk-ANPNT6PM.js';
 import { resolveGatewayCredentials, defaultFetch, unauthorizedMessage } from './chunk-VQ2JGZSC.js';
-import './chunk-PJDQPF5N.js';
-import './chunk-JT3YO5MH.js';
-import './chunk-ESP5VZBD.js';
-import './chunk-HDSDUTX4.js';
-import './chunk-BJ3KTMDH.js';
-import './chunk-G63KT5I5.js';
-import './chunk-5BHIBJDA.js';
-import './chunk-CDDED64E.js';
-import './chunk-RA3O54FC.js';
 import { launchedItemForSession } from './chunk-T2Q7ISPE.js';
 import { parseTrackerNumber, trackerNumberError } from './chunk-WZBHBH3J.js';
-import './chunk-CRB3POP4.js';
-import './chunk-LJG6EMLJ.js';
 import { CriteriaListSchema } from './chunk-E6CO3MJE.js';
 import { homeFromEnv } from './chunk-VNVZDWO3.js';
-import './chunk-XD4ZCMA4.js';
-import './chunk-MESOOLF4.js';
-import './chunk-Z5GEFMRW.js';
 import { readFileSync } from 'fs';
 
 createRequire(import.meta.url);
@@ -129,11 +110,7 @@ async function errorCode(response) {
   }
   return { code, detail: text.replace(/\s+/g, " ").trim().slice(0, 160) };
 }
-async function runEmitCriteria(opts) {
-  const cwd = opts.cwd ?? process.cwd();
-  const home = opts.home ?? homeFromEnv();
-  const env = opts.env ?? process.env;
-  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+async function readListFile(opts) {
   let text;
   if (opts.file === "-") {
     text = await (opts.readStdin ?? readAllStdin)();
@@ -144,21 +121,25 @@ async function runEmitCriteria(opts) {
       throw new EmitCriteriaError(`cannot read "${opts.file}": ${String(err)}`);
     }
   }
-  let raw;
   if (opts.file.endsWith(".md")) {
     const criteria = criteriaFromAcceptanceFile(text);
     if (criteria.length === 0) {
       throw new EmitCriteriaError(`"${opts.file}" lists no criteria: none of its list items opens with an id such as \`AC-123-01\``);
     }
-    raw = { criteria };
-  } else {
-    try {
-      raw = JSON.parse(text);
-    } catch (err) {
-      throw new EmitCriteriaError(`"${opts.file}" is not valid JSON: ${String(err)}`);
-    }
+    return { criteria };
   }
-  const list = parseFile(raw);
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new EmitCriteriaError(`"${opts.file}" is not valid JSON: ${String(err)}`);
+  }
+}
+async function runEmitCriteria(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homeFromEnv();
+  const env = opts.env ?? process.env;
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const list = parseFile(opts.list ?? await readListFile(opts));
   const identity = resolveRepoIdentity(cwd);
   const sessionId = detectActiveSession({
     env,
@@ -212,4 +193,4 @@ async function runEmitCriteria(opts) {
   return { data, output, exitCode: 0 };
 }
 
-export { EmitCriteriaError, runEmitCriteria };
+export { EmitCriteriaError, criteriaFromAcceptanceFile, runEmitCriteria };

package/dist/{cli-5JSVOAE5.js → cli-OHQKHGEU.js}

@@ -4601,7 +4601,7 @@ of the item, and a (proof: <kind>) annotation names its proof.
   ${cliInvocation()} emit criteria acceptance/412-login.md --item 412
 `
   ).action(async (file, opts) => {
-    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-IC5OIZX2.js');
+    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-6D4D5ZBW.js');
     try {
       const result = await runEmitCriteria({
         file,
@@ -4627,7 +4627,7 @@ function registerSpecCommands(program2) {
   const run = async (action) => {
     const { WorkCommandError } = await import('./work-cmd-DYM67Z3F.js');
     try {
-      await action(await import('./spec-cmd-SLJT7MRX.js'));
+      await action(await import('./spec-cmd-ZJAPP2XZ.js'));
     } catch (err) {
       if (err instanceof WorkCommandError) {
         fail(err.message);

package/dist/emit-criteria-cmd-6D4D5ZBW.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+export { EmitCriteriaError, runEmitCriteria } from './chunk-J42MMS4R.js';
+import './chunk-ESVW4MJY.js';
+import './chunk-C3XLVHN6.js';
+import './chunk-B3EE7OKK.js';
+import './chunk-EWVYQLD3.js';
+import './chunk-5DNCFOXA.js';
+import './chunk-HJYBWJAS.js';
+import './chunk-NSPRS7WK.js';
+import './chunk-G2JWZDFA.js';
+import './chunk-ANPNT6PM.js';
+import './chunk-VQ2JGZSC.js';
+import './chunk-PJDQPF5N.js';
+import './chunk-JT3YO5MH.js';
+import './chunk-ESP5VZBD.js';
+import './chunk-HDSDUTX4.js';
+import './chunk-BJ3KTMDH.js';
+import './chunk-G63KT5I5.js';
+import './chunk-5BHIBJDA.js';
+import './chunk-CDDED64E.js';
+import './chunk-RA3O54FC.js';
+import './chunk-T2Q7ISPE.js';
+import './chunk-WZBHBH3J.js';
+import './chunk-CRB3POP4.js';
+import './chunk-LJG6EMLJ.js';
+import './chunk-E6CO3MJE.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-XD4ZCMA4.js';
+import './chunk-MESOOLF4.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);

package/dist/index.js

@@ -26,5 +26,5 @@ if (argv[0] === "claude") {
   process.exit(await runClaudeLauncher(argv.slice(1)));
 }
 (await import('./hook-fast-FJ2PMBML.js')).recordLinkExitFailure(argv);
-var { runCli } = await import('./cli-5JSVOAE5.js');
+var { runCli } = await import('./cli-OHQKHGEU.js');
 await runCli(process.argv);

package/dist/{spec-cmd-SLJT7MRX.js → spec-cmd-ZJAPP2XZ.js}

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import { criteriaFromAcceptanceFile, runEmitCriteria } from './chunk-J42MMS4R.js';
+import './chunk-ESVW4MJY.js';
 import { getJson, postJson, patchJson, WorkCommandError, resolveCredentials } from './chunk-6JNCNHSV.js';
 import { autoConnect } from './chunk-C3XLVHN6.js';
 import './chunk-B3EE7OKK.js';
@@ -19,6 +21,7 @@ import './chunk-G63KT5I5.js';
 import './chunk-5BHIBJDA.js';
 import './chunk-CDDED64E.js';
 import './chunk-RA3O54FC.js';
+import './chunk-T2Q7ISPE.js';
 import './chunk-WZBHBH3J.js';
 import './chunk-CRB3POP4.js';
 import './chunk-LJG6EMLJ.js';
@@ -115,8 +118,59 @@ async function runSpecEdit(opts) {
     payload,
     opts.fetchImpl ?? defaultFetch
   );
-  const text = [`\u2713 edited ${String(data.key)}`, `  ${String(data.url)}`, ...updatedAtLine(data)].join("\n");
-  return finish(opts, data, text);
+  const criteria = await recordEditedCriteria(opts, creds, data, criteriaFromAcceptanceFile(body));
+  const text = [`\u2713 edited ${String(data.key)}`, `  ${String(data.url)}`, ...updatedAtLine(data), ...criteria.lines].join("\n");
+  return finish(opts, criteria.result === null ? data : { ...data, criteria: criteria.result }, text);
+}
+function sameList(read, held) {
+  return read.length === held.length && read.every((criterion, i) => criterion.id === held[i].id && criterion.text === held[i].text && criterion.proof === (held[i].proof ?? null));
+}
+async function recordEditedCriteria(opts, creds, edited, criteria) {
+  if (criteria.length === 0) return { result: null, lines: [] };
+  const fetchImpl = opts.fetchImpl ?? defaultFetch;
+  let item;
+  let held;
+  try {
+    const query = new URLSearchParams({ key: opts.key });
+    if (typeof edited.tracker === "string") query.set("tracker", edited.tracker);
+    const page = await getJson(creds.url, `/v1/work-items?${query}`, creds.apiKey, creds.appId, fetchImpl);
+    item = page.data[0];
+    if (item === void 0) return { result: null, lines: [] };
+    const read = await getJson(creds.url, `/v1/work-items/${item.id}`, creds.apiKey, creds.appId, fetchImpl);
+    held = read.data.criteria?.items;
+  } catch (err) {
+    return { result: null, lines: [`\u2717 the edit's criteria were not checked against the issue's work item: ${err.message}`] };
+  }
+  const count = criteria.length;
+  const counted = `${count} ${count === 1 ? "criterion" : "criteria"}`;
+  if (held !== void 0 && sameList(criteria, held)) {
+    return { result: { item: item.number, outcome: "unchanged", count }, lines: [`  item #${item.number} already holds these ${counted}`] };
+  }
+  try {
+    await runEmitCriteria({
+      file: `the body of ${opts.key}`,
+      list: { criteria },
+      item: String(item.number),
+      quiet: true,
+      url: creds.url,
+      apiKey: creds.apiKey,
+      appId: creds.appId,
+      cwd: opts.cwd,
+      home: opts.home,
+      env: opts.env,
+      fetchImpl
+    });
+  } catch (err) {
+    const reason = err.message;
+    return {
+      result: { item: item.number, outcome: "not_recorded", count, reason },
+      lines: [
+        `\u2717 item #${item.number} is still held to its earlier criteria: ${reason}`,
+        `  To record the new ones, save the body as a .md file and run: outerlayer emit criteria <file> --item ${item.number}`
+      ]
+    };
+  }
+  return { result: { item: item.number, outcome: "recorded", count }, lines: [`\u2713 recorded ${counted} on item #${item.number}`] };
 }
 
 export { runSpecEdit, runSpecFile, runSpecSearch, runSpecTarget };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outerlayer/cli",
-  "version": "0.33.0-next.20261022124145",
+  "version": "0.33.0-next.20261022161023",
   "description": "OuterLayer CLI — commands: init, claude, connect, doctor, login, logout, sync, daemon (alias: watch), emit, findings, work, spec, runner, hooks, mcp, context. Capture and sync coding-agent sessions, and record proof of factory work.",
   "license": "Apache-2.0",
   "author": "Magu Studios, Inc.",

package/skill-pack/maintained/outerlayer-amend/SKILL.md

@@ -9,7 +9,7 @@ description: >
   the reviewer failed". Invoke with /outerlayer-amend.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 Answer every thread waiting on an agent on one work item's pull request, then
 stop. A work item has one general thread and one thread per acceptance
@@ -67,10 +67,10 @@ change, to its own branch only.
    `criterion` (null for the general thread), `waitingOn` (`agent`, `person` or
    null), `verdict`, `proof` and `comments`, each comment with its `author`,
    `body`, `action` and `artifact`. Keep the threads whose `waitingOn` is
-   `agent`: one send of notes can leave several.
-   If none is waiting and step 1 resolved no conflict, say so and stop: there
-   is nothing to answer. Take the pull request (`repository`, `prNumber`) from
-   the step 1 status JSON's `pullRequests`.
+   `agent`.
+   If none is waiting and step 1 resolved no conflict, say so and stop. Take
+   the pull request (`repository`, `prNumber`) from the step 1 status JSON's
+   `pullRequests`.
 3. **Re-orient.** The status JSON's `issue.body` is OuterLayer's copy of the
    issue. It is the spec: find each thread's criterion there. Read the pull
    request, with its evidence comment, through the git host. Read every person's comment since the last agent
@@ -80,8 +80,7 @@ change, to its own branch only.
    `reason`. When a person asks you to fix failing checks or criteria, fix
    each failing check item by its reason.
 4. **Decide each thread.** Reply on every criterion thread waiting on an
-   agent, with `--criterion`, so each note gets its answer under it. Read each
-   note and pick one:
+   agent, with `--criterion`. Read each note and pick one:
    - **Answer it.** A question gets an answer. Reply with the answer and
      change nothing. Say which file or test you looked at.
    - **Fix it.** A requested change gets a fix. Change the code, tests, docs or
@@ -139,13 +138,12 @@ change, to its own branch only.
    and why. Post the lines once on the general thread:
    `outerlayer work comment --item "$OUTERLAYER_WORK" --body "<the lines>"`.
    A plain comment from an agent leaves the general thread waiting on a person.
-   A local session also posts them on the pull request; a build's token
-   cannot. End with the same lines.
+   A local session also posts them on the pull request. End with the same lines.
 
 ## Rules
 
-- **Answer only threads waiting on an agent.** A thread waiting on a person, or
-  on no one, is not yours to reply on.
+- **Answer only threads waiting on an agent.** Never reply on one waiting on a
+  person or on no one.
 - **One thread, one proof.** Never attach an artifact that does not prove that
   thread's criterion.
 - **A person decides.** Never pass `--pass` or `--fail`, never mark a check as

package/skill-pack/maintained/outerlayer-build/SKILL.md

@@ -7,7 +7,7 @@ description: >
   skill tells you to. Only the `build` skill starts it.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 Build one issue into an evidenced pull request. `/spec` writes and gets
 approval for the issue. This skill builds it. It never writes the spec.
@@ -258,14 +258,18 @@ Run them in order.
    `"$(git rev-parse --absolute-git-dir)/build-reports/criteria.json"` and runs
    `outerlayer emit criteria` on it. The gateway decides whether a list may be
    recorded. A 409 means the item already has a recorded list. That list
-   stands, and nothing is recorded. No command returns the item's list, so the
-   build cannot read it: it holds the work to its own reading of the criteria
-   and says so in the final report. Any other refusal is written to the state
+   stands, and nothing is recorded. The script then reads the item's list with
+   `outerlayer work status --item <n> --json`. When it differs from the
+   issue's criteria, the script reports a step on the item that says so, and
+   the item's Activity tab shows it. The build holds the work to its own
+   reading of the criteria. The final report says which list the item holds
+   and how they differ. Any other refusal is written to the state
    file with its message, and the build continues. The script writes the
    outcome under `criteria` in the state file: `source` (`issue`, `drafted`,
    `item`, or `none` when even a draft holds no criterion), `recorded`,
    `count`, `list` and `numbered`. On a 409, `list` is empty, and the build's
-   reading of the criteria goes under `issueReading`.
+   reading of the criteria goes under `issueReading`. The item's own list goes
+   under `recordedList`, and `differs` says whether the two lists differ.
 
    Drafted criteria are tiered, proven and judged like any others. A drafted
    list stands like any recorded list. A later build's record

package/skill-pack/maintained/outerlayer-build/references/criteria-judge.md

@@ -27,10 +27,12 @@ Judge only that group. Other judges handle the rest.
 1. Read the criteria from the build's state file, under `criteria.list`. They
    are the item's recorded list. If the state file lacks `criteria`, read the
    `criteria` array in `criteria.json` in the build-reports directory. When
-   `criteria.source` is `item`, the item already had a recorded list that no
-   command returns, so `list` is empty. Judge `criteria.issueReading` instead,
-   and say in the report that it is the issue's reading, whose ids may differ
-   from the item's recorded list. Each has an id
+   `criteria.source` is `item`, the item already had a recorded list, so
+   `list` is empty. Judge `criteria.recordedList` instead: it is the list the
+   item is held to. When `criteria.differs` is true, say in the report that
+   the issue states other criteria. When there is no `recordedList`, judge
+   `criteria.issueReading`, and say in the report that it is the issue's
+   reading, whose ids may differ from the item's recorded list. Each has an id
    and a text, and the text is usually a Given, When and Then. Judge every criterion you were given,
    including one no line of the diff touched. A criterion with `proof: null`
    is proven by a citing test or any artifact bound to its id.

package/skill-pack/maintained/outerlayer-build/scripts/record-criteria.mjs

@@ -13,7 +13,9 @@
 // `AC-<item>-NN` in order. A drafted list is always numbered and is recorded
 // with `drafted: true`. An empty list records nothing. The script never edits
 // the issue, and never replaces a list the item already has (the gateway
-// answers 409 and the item's list stands).
+// answers 409 and the item's list stands). When that list differs from the
+// one read here, it reports a step on the item, so Work shows that the item
+// is held to criteria the issue no longer states.
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -78,6 +80,17 @@ export function readCriteria(input, item, { drafted = false } = {}) {
   return numbered ? { criteria, numbered, numberedBecause: problem } : { criteria, numbered };
 }
 
+/** The step reported on the item when its recorded list differs from the issue's. At most 80 characters. */
+export const DIFFERS_STEP = "Criteria differ from the issue: a person must replace them";
+
+/** Whether two lists hold the same criteria, in the same order, with the same text and proof. */
+export function sameCriteria(a, b) {
+  return (
+    a.length === b.length &&
+    a.every((criterion, n) => criterion.id === b[n].id && criterion.text === b[n].text && (criterion.proof ?? null) === (b[n].proof ?? null))
+  );
+}
+
 /** Sorts a failed `emit criteria` into "the item already has a list" and any other refusal. */
 export function classifyEmitFailure(message) {
   // Only the CLI's replace refusal reads "refused (409):". Other answers that
@@ -85,16 +98,20 @@ export function classifyEmitFailure(message) {
   return /\brefused \(409\):/.test(message) ? "item-list-stands" : "refused";
 }
 
+/** Runs `outerlayer`, or `npx -y @outerlayer/cli` on a machine with no `outerlayer` on PATH. */
+function runCli(spawn, args) {
+  const options = { encoding: "utf8", timeout: 120000 };
+  const run = spawn("outerlayer", args, options);
+  return run.error?.code === "ENOENT" ? spawn("npx", ["-y", "@outerlayer/cli", ...args], options) : run;
+}
+
 /**
  * Builds the `emit` function that runs `outerlayer emit criteria`; `spawn` is `spawnSync`, or a stand-in in tests.
  * A machine that ran the CLI through `npx` has no `outerlayer` on PATH, so a missing command falls back to `npx -y @outerlayer/cli`.
  */
 export function makeEmit(spawn, item) {
   return (file) => {
-    const args = ["emit", "criteria", file, "--item", item];
-    const options = { encoding: "utf8", timeout: 120000 };
-    let run = spawn("outerlayer", args, options);
-    if (run.error?.code === "ENOENT") run = spawn("npx", ["-y", "@outerlayer/cli", ...args], options);
+    const run = runCli(spawn, ["emit", "criteria", file, "--item", item]);
     if (run.status === 0) return { ok: true };
     if (run.error) return { ok: false, message: `could not run outerlayer emit criteria: ${run.error.message}` };
     if (run.signal) return { ok: false, message: `outerlayer emit criteria was stopped by ${run.signal}` };
@@ -102,6 +119,25 @@ export function makeEmit(spawn, item) {
   };
 }
 
+/** Builds the `readRecorded` function: the item's recorded list, or `null` when it cannot be read. */
+export function makeReadRecorded(spawn, item) {
+  return () => {
+    const run = runCli(spawn, ["work", "status", "--item", item, "--json"]);
+    if (run.status !== 0) return null;
+    try {
+      const items = JSON.parse(run.stdout).criteria?.items;
+      return Array.isArray(items) ? items.map((c) => ({ id: c.id, text: c.text, proof: c.proof ?? null })) : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/** Builds the `reportStep` function, which reports a step on the item. Returns whether it was recorded. */
+export function makeReportStep(spawn, item) {
+  return (name) => runCli(spawn, ["emit", "step", name, "--item", item]).status === 0;
+}
+
 function readState(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -115,7 +151,7 @@ function readState(path) {
  * the parsed criteria file. `emit(file)` runs `outerlayer emit criteria
  * <file>` and returns `{ ok: true }` or `{ ok: false, message }`.
  */
-export async function recordCriteria({ input, item, drafted = false, reportsDir, statePath, emit }) {
+export async function recordCriteria({ input, item, drafted = false, reportsDir, statePath, emit, readRecorded, reportStep }) {
   const read = readCriteria(input, item, { drafted });
   const numbering = read.numbered ? { numbered: true, numberedBecause: read.numberedBecause } : { numbered: false };
   let outcome;
@@ -132,13 +168,21 @@ export async function recordCriteria({ input, item, drafted = false, reportsDir,
     if (result.ok) {
       outcome = { source, recorded: true, ...base };
     } else if (classifyEmitFailure(result.message) === "item-list-stands") {
-      // No command returns the item's own list, so `list` stays empty; the build's reading goes under `issueReading`.
+      // `list` stays empty and the build's reading goes under `issueReading`.
+      // The item's own list goes under `recordedList` when it could be read,
+      // and `differs` says whether it is another list (`null`: unknown).
+      const recorded = readRecorded === undefined ? null : await readRecorded();
+      const differs = recorded === null ? null : !sameCriteria(recorded, read.criteria);
+      const reported = differs === true && reportStep !== undefined ? await reportStep(DIFFERS_STEP) : false;
       outcome = {
         source: "item",
         recorded: false,
         count: read.criteria.length,
         list: [],
         issueReading: read.criteria,
+        ...(recorded === null ? {} : { recordedList: recorded }),
+        differs,
+        ...(differs === true ? { differsReported: reported } : {}),
         ...numbering,
         note: "the item already has a recorded list; it stands",
       };
@@ -156,7 +200,17 @@ export function summarize(outcome) {
   const noun = n === 1 ? "criterion" : "criteria";
   const ids = outcome.numbered ? `, numbered AC-<item>-NN because ${outcome.numberedBecause}` : ", with the issue's own ids";
   if (outcome.source === "none") return "no criteria in the file; none recorded";
-  if (outcome.source === "item") return `the item already has a recorded list; it stands, and the ${n} ${noun} read here were not recorded`;
+  if (outcome.source === "item") {
+    if (outcome.differs === false) return `the item already has these ${n} ${noun} recorded`;
+    if (outcome.differs === true) {
+      const where = outcome.differsReported ? "; the item's Activity tab says so" : "; reporting it on the item failed, so say it in the final report";
+      return (
+        `the item's recorded list differs from the ${n} ${noun} read here. It stands, and the item is held to it${where}. ` +
+        "A person replaces it with `outerlayer emit criteria`"
+      );
+    }
+    return `the item already has a recorded list; it stands, and the ${n} ${noun} read here were not recorded`;
+  }
   const what = outcome.source === "drafted" ? `drafted ${n} ${noun} from the issue's description` : `read ${n} ${noun} from the issue`;
   return outcome.recorded
     ? `${what} and recorded them${outcome.source === "drafted" ? " as drafted" : ids}`
@@ -195,6 +249,8 @@ async function main(argv) {
       reportsDir: join(gitDir, "build-reports"),
       statePath: join(gitDir, "build-state.json"),
       emit: makeEmit(spawnSync, item),
+      readRecorded: makeReadRecorded(spawnSync, item),
+      reportStep: makeReportStep(spawnSync, item),
     });
     process.stdout.write(`${summarize(outcome)}\n`);
     return 0;

package/skill-pack/maintained/outerlayer-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >
   attach evidence or answer a review.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 OuterLayer is a software factory. An issue goes in. A reviewed and verified
 pull request comes out, with the evidence that backs it. An agent builds it in

package/skill-pack/maintained/outerlayer-evidence/SKILL.md

@@ -8,7 +8,7 @@ description: >
   works", and in CI steps that produce verifiable output.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 An artifact is an exhibit: evidence *of* a specific change, anchored to the
 pull request and rendered in its evidence comment. Emit the few exhibits the

package/skill-pack/maintained/outerlayer-findings/SKILL.md

@@ -12,7 +12,7 @@ description: >
   `outerlayer emit finding` command.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 ## What this is for
 
@@ -74,8 +74,7 @@ title.
 
 ## What to record in a finding
 
-Fill these in whenever you know them. They are what lets the next agent
-recognise the problem and fix its cause.
+Fill these in whenever you know them.
 
 - `--cause`: what is actually wrong. Write `unknown` when you do not know.
 - `--detail`: what happened, a few paragraphs.
@@ -124,9 +123,8 @@ failure: read the candidates, then run the same command again:
 - `--new` when none of them is the same problem. Use it rather than linking
   the nearest one.
 
-`--problem` always needs `--link-reason`. Apply rule 1 to every candidate: the
-same error is not enough, one fix has to resolve both. If a candidate's
-reports carry a different cause, it is a different problem.
+`--problem` always needs `--link-reason`. Apply rule 1 to every candidate. If
+a candidate's reports carry a different cause, it is a different problem.
 
 If a key of your finding is owned by a problem, the finding joins that problem
 whatever `--problem` you named, and the output says so.

package/skill-pack/shipped.json

@@ -86,6 +86,7 @@
       "82f75a53c591f94615dc27c099e94fcf95e2a09b95aceb38b9022d5f7f054cb0",
       "8d3a5131d0c82302279d319c51bcde74f7677e8d2e3f6cd68aa7f3ea84fa1051",
       "9039ae30d4e836b5c5cfba4a14344e46fd13694ae9e4d88e750abce34dfcd9e6",
+      "ba26711f3ac400f38e2bb78d4e410cde940e666317cd9aeb3fa949d89bb39f15",
       "fc2bec8d43764c4e4b40b0ee761b7f9ee8646950dd4e52392f652e68679f79ea"
     ],
     ".outerlayer/skills/writing-specs/SKILL.md": [

package/skill-pack/template/spec/SKILL.md

@@ -9,7 +9,7 @@ description: >
   /spec <what you want built>.
 ---
 
-Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule. Write the full command each time. Do not put it in a shell variable: zsh runs `$VAR args` as one command name, not as a command with arguments.
 
 Take one idea from a sentence to an issue a person can build from. This file
 is the procedure. The content discipline is the `writing-specs` skill: summary