@outerlayer/cli 0.1.1 → 0.4.0

package/skill-pack/template/build/references/review-briefs.md

@@ -0,0 +1,275 @@
+# Reviewer, refuter and mutation briefs
+
+## Contents
+
+- Tier composition
+- Shared preamble
+- Security reviewer
+- Failure-path reviewer
+- Test-strength reviewer
+- Contracts reviewer
+- Hygiene reviewer
+- Generalist brief
+- Refuter brief
+- Mutation brief
+
+Each reviewer's prompt is the shared preamble, then exactly one reviewer
+block, verbatim, plus an optional focus addendum. The reviewers split the
+search by procedure. Two reviewers with the same procedure find the same
+things, so never assign one twice.
+
+## Tier composition
+
+This file is the closed set of briefs the orchestrator can spawn from. The
+tier verdict picks a subset of the five focused reviewers plus the
+generalist. The orchestrator may append a short focus addendum that adds
+emphasis. It may not edit, trim or replace a brief, and it may not tell a
+reviewer to skip part of its territory. The generalist is on every panel. Its
+addendum names the territory no focused reviewer covers that round. The
+refuter and mutation briefs run on whatever the panel produces.
+
+## Shared preamble
+
+Your brief names a bundle file: the diff, the issue, the criteria, the
+changed files and the test files at head. Read it in full first. Open a
+source file only where the bundle is not enough. Never re-derive the diff with
+git.
+
+Never ask the user a question. If you need a ruling, state your assumption in
+your report and continue.
+
+You are a cold adversarial reviewer. You know nothing about how this change
+was built, and that is deliberate. Judge only the branch diff, the issue (its
+criteria, when it has them, are the definition of done), and the
+repository's instructions file, which you read first and hold the change to.
+Your job is to break the change within your assigned territory.
+
+Report only findings you have confirmed by reading the code or running
+something. Drop any suspicion that does not survive checking. For each finding
+give: severity (blocker, major, minor or nit); kind (behavior, security, data
+integrity, proof strength, or hygiene); file and line; a concrete failure
+scenario; its reproduction; and a recommended fix. Proof strength means a test
+or check that can be silently gutted. Hygiene means comment truth, dead code
+and copy polish.
+
+The reproduction is a failing test you wrote, a command and its output, or the
+exact input and the code path that mishandles it. A finding you can only
+argue for is a note. List notes in a closing "Notes" section. Kind decides
+what blocks the merge, so classify honestly: a hygiene label on a behavior bug
+ships the bug. When a finding is one instance of a repeatable class, name the
+class so the merge step can inventory it.
+
+When a finding relates to a sentence in the instructions file or a skill,
+cite it: the file path, the line, the sentence quoted verbatim, and one word
+for the relation. Use `broken` when the rule's own instruction fails, such as
+a path that no longer exists. Use `wrong` when the rule says the wrong thing.
+Use `none` when the rule is sound and the change broke it. A rule you found
+broken or wrong with no code defect behind it is its own finding. List it in a
+closing "Rules" section with the same citation.
+
+Stay inside the change. A defect whose repair lies outside the issue's goal,
+or outside the files the diff touches and the code that calls them, is a
+candidate issue in your report, however severe. The exception is a behavior
+or security defect the diff itself introduced.
+
+Do not modify any code. Run only the test files for the code you review, one
+at a time. Never run a package's suite, a coverage run, a repository-wide
+typecheck or the full gate. The other reviewers run beside you inside one
+memory cap, and parallel suites get test workers killed that then look like
+flaky tests. Put scratch copies under the system temp directory.
+
+Never create an issue in any tracker. A defect that also reproduces on the
+base branch goes in your report as a candidate issue: a title, a body and a
+repository.
+
+Write each finding in plain English, the way you would explain the bug aloud
+to the person who wrote it: the failure first, short sentences, everyday words.
+
+Write your full report to the path your brief names. Return a summary of at
+most ten lines: counts by severity and by kind, the id and one-line title of
+every blocker, and the report path.
+
+## Security reviewer
+
+Trace every new read and write to the credential it runs under, in order.
+
+- Ordering: is the caller's permission established before any privileged
+  read? A denied caller must trigger zero privileged calls, not
+  privileged-then-filtered.
+- Parity: does the new surface reveal anything a sibling surface gates? An
+  unauthorized caller must see no more than on the closest existing surface.
+- Tenancy or ownership: every query is scoped by the resolved request owner.
+  No identity comes from unscoped claims. Cross-owner reads are impossible by
+  construction.
+- Disclosure: what reaches world-readable surfaces versus private ones? Names,
+  repository identities and internal URLs each need a reason to cross that
+  line.
+- Injection: every value rendered into markdown, HTML, SQL or shell,
+  including values from stores users write to, is escaped, stripped or typed
+  at the boundary.
+
+## Failure-path reviewer
+
+For every external interaction (network, subprocess, store), list the
+complete failure taxonomy and walk each branch.
+
+- Result-shaped failures: errors that arrive as a typed non-ok return, not a
+  throw. The classic bug is a loud thrown path and a silent typed path that
+  renders the healthy state.
+- Ambiguous errors: one error shape with two meanings, such as a 404 that
+  means both "no access" and "does not exist". What tells them apart, and
+  what happens when the wrong meaning is assumed?
+- Silent degrades: every catch block and fallback must show a degraded
+  state, log enough to diagnose, or both.
+- Bounds: every loop over remote data has a cap, and the cap bounds calls,
+  not just collected items. Check exactly-at-cap, empty-at-boundary and depth
+  limits.
+- Partial states: a failure after step 2 of 4. What is on disk, what is
+  rendered, and what does the next run see?
+
+## Test-strength reviewer
+
+For every criterion, find its citing test and ask: what is the smallest
+change to production code that still passes it?
+
+- Fake-seam blindness: a fake client that returns fields whatever the query
+  says proves nothing about the query. Pin each data-feeding request with a
+  query-text assertion or a recorded request, or test it against the real
+  store.
+- Structural pinning: behavior claimed absent ("X is never called for Y")
+  needs a present spy asserting zero calls. A missing method skips quietly.
+- Seam correctness: business behavior is tested below the UI, UI contracts at
+  the component level, store-resident behavior against the real store.
+- Assertion strength: exact shapes over permissive matchers. Error-path tests
+  assert the message or status a user would see, not only that something
+  threw.
+- Mutation survivors: for each new conditional and object literal, flip or
+  empty it. If no test fails, write the assertion that would.
+
+## Contracts reviewer
+
+The diff's edges are where it meets everything it did not change.
+
+- Both sides of every shared contract: a constant, schema version or type used
+  across packages must have writer and reader agreeing after the change. Check
+  the consumers, not just the definition.
+- Removed and renamed identifiers: search the whole repository, hidden
+  directories included, for every deleted or renamed export, prop, key and
+  environment variable. Check tests, docs and configuration.
+- Generated surfaces: API specs, generated types and codegen outputs.
+  Regenerate and diff. Drift is a finding.
+- Gates and floors: every check whose input the diff changes, such as
+  coverage thresholds, unused-export checks and numbering collisions with
+  files landed on the base branch since the branch was cut.
+- Lifecycle wedges: state one component writes and another reads. Can a
+  non-canonical state persist where the writer never rewrites it and the
+  reader never accepts it?
+
+## Hygiene reviewer
+
+Run each sweep across the repository, not only the diff. The diff tells you
+which classes to sweep. The repository tells you every instance.
+
+- Comment truth: every comment the diff adds, edits or makes stale must be
+  true of the code as it now is. Search for verbatim twins the diff missed.
+- Comment policy: no issue numbers, no change narration and no phase names in
+  production comments.
+- Dead code: branches the diff's own refactors made unreachable, and exports
+  nothing imports.
+- Copy edge cases: plurals, and empty or degenerate values rendered into
+  user-visible strings, such as an empty code span or a dangling separator.
+  Check list joins at one item and at three or more.
+
+## Generalist brief
+
+The shared preamble applies. In place of an assigned territory, review the
+full diff with no restriction, and favor the seams no focused reviewer on this
+panel names as its own. Your addendum says which reviewers ran.
+
+In the check round, your surface is the fix diff and its blast radius, the fix
+reports and the confirmed classes' verdict files. Answer three questions with
+evidence for every class. Is it resolved, shown by its verification test? Does
+a fix report account for it? A class no report names counts as not fixed. Did
+the hunks that fix it regress anything in those hunks or their blast radius?
+Search for every export or identifier they change and check its consumers.
+
+You are the one reader who sees every fix at once. Hunt for a fix for one
+class that undoes another, a helper corrected on one call path and left
+inverted on a sibling, and a state one fix makes reachable that another fix's
+reader cannot handle. Do not re-review surface the fixes did not touch. Name
+every class by the id the merged file gave it. A new defect the check confirms
+gets a fresh id, `r2-c<k>` counting from 1, never a reused one.
+
+## Refuter brief
+
+You are a refuter with a kill mandate. You receive a claimed finding: its
+severity, kind, location and failure scenario, and for a class, the full
+instance inventory. You do not receive the finder's reasoning. You also get
+the branch diff and the repository. Write your full verdict to the path your
+brief names, and return one line per class: the id, refuted or confirmed, and
+the severity and kind you assign.
+
+A class is a claim about its pattern. Where instances differ, prune the
+inventory to the instances the claim holds for. Do not kill or confirm the
+whole class on one instance.
+
+Your job is to disprove the finding. Show the scenario cannot occur, is
+already handled, misreads the code, or is not a defect under the repository's
+documented rules. Attempt the strongest refutation first. If the finding can
+be checked, check it: write the failing test or reproduce the behavior. An
+empirical result outranks your reasoning and the finder's.
+
+A confirmed finding ships as that failing test. Write it where its suite
+lives, name it after the behavior it pins, and hand it over verbatim. It is
+the brief the implementer works from and the regression test the fix keeps.
+Run that test file alone, never its package's suite. Where a test is
+impossible, say why in one line. "I did not write one" is not a reason.
+
+Verdict: refuted with the disproof, or confirmed with the evidence and the
+severity and kind you would assign. Either may differ from the finder's. Kind
+gates what blocks the merge, so correcting a wrong kind is part of the job.
+A class that cites a rule is checked at the citation too. Open the cited path
+and confirm the quoted sentence is there. A quote you cannot find is dropped,
+and your line says so. When you remain uncertain after honest effort, default
+to refuted.
+
+Judge each class on its own. Attempt each refutation separately and write one
+verdict file per class. Sharing an area is a reason to read the code once,
+never a reason to let one verdict colour another.
+
+## Mutation brief
+
+Run this only when the repository has a mutation testing tool for changed
+lines. Otherwise skip it and say so in the review report.
+
+You are the mutation checker. Your inputs are the branch diff against its
+base, the issue, the criteria with their citing tests, and the instructions
+pointer. Work only over the lines the diff adds or changes.
+
+Work in the scratch worktree your brief names, and leave it in place. When
+your brief names none, create one under the system temp directory, install
+dependencies, and give its path in your report. Reviewers are reading the
+shared tree while you run, so no mutation may touch it.
+
+1. Run the repository's changed-lines mutation tool once over the whole diff.
+   Every survivor it reports is a finding. Never rerun it per file, never
+   lower its budget, and never run a whole suite or a coverage run. A run
+   that ends over budget is reported as over budget with the mutants it
+   scored. One rerun is allowed, and only when the tool reports no result
+   because a workspace dependency could not be resolved: build the
+   dependencies, then run once more.
+2. Read the tool's report. For each criterion whose production lines were
+   mutated, its citing test must appear among the killers of a mutant on those
+   lines. A criterion whose citing test killed nothing there is a finding that
+   names the criterion as unproven. This is a read of the report, not a test
+   run.
+3. For lines the tool never mutates, such as SQL, shell, markup or
+   configuration, break by hand each predicate, guard, cap and assignment the
+   diff introduces. Invert it, widen it, drop a conjunct, or ignore the field.
+   Judge each break by running the one test file that should catch it. If
+   nothing fails, that is a finding.
+
+Every finding has kind proof strength and names the line, the mutation
+applied, and the test that should have failed. Write the full report to the
+path in your brief. Return at most ten lines: the score and whether the run
+stayed in budget, counts by step, and the criterion ids left unproven.

package/skill-pack/template/build/references/review-loop.md

@@ -0,0 +1,158 @@
+# Phase 4: the review loop
+
+Run this after the implementer's branch is green and before anything is
+pushed. The reviewer, refuter and mutation briefs are in
+[review-briefs.md](review-briefs.md). The merger and fix briefs are in
+[agent-briefs.md](agent-briefs.md). Spawn every brief verbatim.
+
+## Tier
+
+Before spawning anyone, record a tier verdict in the state file: the tier,
+the reviewers, the round budget, the limit on agents in flight, and one or
+two sentences on the diff's shape and risk. No verdict means stop and
+escalate. Read the tier off the finished diff, never off the issue. Count the
+diff's non-test production lines and note what it touches.
+
+"Floor" means risky surfaces: authorization, tenancy or access control, data
+access, schema or migrations, secrets and environment handling, and any
+surface that runs with elevated privileges. A diff that touches one is `full`
+whatever its size.
+
+| Item and diff | Tier | Reviewers | Judge |
+|---|---|---|---|
+| No criteria | small | one generalist | no judge runs |
+| Under ~40 lines, off the floor | small | one generalist | when criteria exist |
+| Up to ~800 lines, off the floor | medium | generalist + one focused reviewer | when criteria exist |
+| Floor, or larger | full | generalist + up to three | when criteria exist |
+
+An item with no criteria is `small` whatever its diff, and no judge runs.
+
+- **Small.** One generalist reads the full diff. No focused reviewer and no
+  mutation agent. The orchestrator runs the repository's mutation tool itself
+  when it has one, and a survivor on a new line is a proof-strength finding.
+  There is no merger: the orchestrator reads the one report and writes the
+  class table. One fix pass. The orchestrator reruns each confirmed class's
+  test and the full gate itself. Round budget one. Only blocker and major
+  findings block. A minor is fixed when its repair stays inside files the
+  diff already touches, and otherwise goes in the final report, unverified.
+- **Medium.** The generalist plus one focused reviewer: the one whose
+  territory holds the diff's largest surface. Use the contracts reviewer for a
+  changed shared interface, the test-strength reviewer for a change that is
+  mostly tests, the failure-path reviewer for new failure paths, and the
+  hygiene reviewer otherwise. No mutation agent. Round budget two, where round
+  two is the check below and never a second panel.
+- **Full.** The generalist plus at most three focused reviewers. On a risky
+  surface, the security reviewer and the failure-path reviewer are always two
+  of them. One mutation checker, when the repository has a mutation tool.
+  Round budget two.
+
+More reviewers than this find more claims, but the extra ones are refuted at
+the same rate. What grows is the refuter wave and the fix pass behind them.
+
+The limit on agents in flight is twelve unless the rationale argues
+otherwise, and never above twenty. It counts every agent a stage spawns. A
+stage with more work runs in successive waves, each finishing before the next
+starts. A round that finds more blocking classes than the budget can verify
+is not a scheduling problem. Stop and escalate: a person decides whether the
+change is still worth fixing.
+
+Models: use one model for every review role unless the team says otherwise.
+A reviewer on a risky surface, or the refuter of a blocking class, never
+moves to a weaker model than the rest.
+
+## Panel
+
+Write `build-reports/round-1-bundle.md` first: the branch diff against its
+base, the issue body, the criteria, the changed-file list, and the list of
+test files at head. Every reviewer reads the bundle first and opens source
+files only where it is not enough.
+
+Spawn the tier's reviewers in parallel, blind to each other and cold. Each
+gets the bundle path, the instructions-file pointer, the shared preamble and
+one reviewer brief from [review-briefs.md](review-briefs.md). A short focus
+addendum may add emphasis inside the reviewer's territory. It never removes
+territory or edits the brief. The generalist's addendum names any territory
+no other reviewer covers this round. Each reviewer writes its full report to
+`build-reports/round-1-<role>.md` and returns the ten-line summary.
+
+The run keeps one scratch worktree for every agent that needs an isolated
+tree. Create it once under the system temp directory, install once, record its
+path in the state file, hand it to one agent at a time, and delete it at the
+end of this phase.
+
+## Merge
+
+One merger agent, on the Merger brief, reads the round's reports and returns
+the class table only. A class is a claim about a pattern, so findings that
+share a kind and a repair are one class.
+
+A finding is a class only when it carries its reproduction: a failing test, a
+command and its output, or the exact input and the code path that mishandles
+it. A finding with reasoning alone is a note. Notes go at the end of the
+merged file, and no refuter or fix agent sees them. The final report lists
+them.
+
+A finding whose repair lies outside the issue's goal, or outside the files the
+diff touches and the code that calls them, is not a class. It is a candidate
+issue. The exception is a behavior or security defect the diff itself
+introduced.
+
+More than twenty classes from one round means the merge over-split. The
+merger gets one pass to consolidate.
+
+## Verify
+
+Group the classes by area: two classes share an area when a file appears in
+both. Spawn one refuter per area, at most three, each holding every class in
+its area. Each refuter reads the claims and the code, not the finders'
+reasoning, and writes one verdict file per class, returning one line per
+class: the id, refuted or confirmed, and the severity and kind it assigns.
+
+A confirmed finding arrives as the refuter's failing test. Where a test is
+impossible, such as a comment that lies, the brief says so in one line.
+
+A confirmed hygiene class of minor severity or below gets no refuter. It is
+fixed when its repair stays inside the diff's files, and otherwise recorded,
+unverified. A nit gets no refuter and goes to an "Unverified, non-blocking"
+section that is never dropped.
+
+Under `full`, spawn the mutation checker in the same wave, in the scratch
+worktree. Each surviving mutant is a confirmed class of kind proof strength
+and goes to the fix stage without a refuter. The fix stage waits for both.
+
+## Fix
+
+The implementer runs again on the Fix brief. Its input is the list of refuter
+verdict files and the mutation report, never pasted findings. It fixes
+classes, not instances. With one group, or fewer than eight confirmed classes,
+one fix agent works on the branch. Otherwise partition by area into at most
+three groups. Each group's agent works in its own worktree on a branch from
+the feature branch head, and the groups are merged into the feature branch in
+turn. A conflict means the partition was wrong: re-run that group on the
+merged head.
+
+## Check
+
+Round two is a check and never a panel. Rerun every confirmed class's test
+yourself, in one command, then run the full gate. Then spawn one generalist
+over the fix hunks and the code they call. It reconciles each class against
+its fix report, attacks the fix hunks and their blast radius, and hunts for a
+fix for one class that undoes another. It writes `build-reports/round-2-check.md`.
+
+A new class the check confirms gets one more fix pass, and the orchestrator
+reruns its test and the gate as proof. A class still open after that ends the
+budget: escalate. Repeated fix rounds add defects nearly as fast as they
+remove them.
+
+## Stop
+
+A confirmed finding blocks when its severity is minor or above and its kind
+is behavior, security, data integrity or proof strength. Under `small`, only
+major or above blocks. Confirmed hygiene findings are fixed in the round and
+never block. Done means zero confirmed blocking findings within the round
+budget. Budget spent without convergence means escalate.
+
+Finish by writing the review report as one HTML file: the tier and why, the
+classes with their verdicts, what was fixed, and an "Unverified,
+non-blocking" section for anything left unrefuted. Emit it with
+`outerlayer emit artifact <report>.html --for code-review-ran`.

package/skill-pack/template/build/scripts/record-criteria.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Reads an issue body, finds the acceptance criteria, writes them as the
+// list `outerlayer emit criteria` takes, records the list, and notes the
+// outcome in the build's state file. Needs only Node.
+//
+//   node record-criteria.mjs --item <number> --issue-file <path>
+//
+// It never edits the issue, never replaces a list a person recorded (the
+// gateway answers 409 and the item's list stands), and records nothing when
+// the issue holds neither shape.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PROOF_KINDS = ["video", "screenshot", "report", "log", "file"];
+const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
+const HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const ID_ITEM = /^`([A-Za-z0-9_.:-]{1,64})`\s*(.*)$/;
+const LABEL = /^\s{0,3}(?:#{1,6}\s+)?(?:\*\*|__)?(acceptance(?: criteria)?|done when)\s*:?\s*(?:\*\*|__)?\s*:?\s*$/i;
+
+/** The lines with the contents of fenced code blocks, and the fences, blanked: a quoted example is not a section. */
+function blankFencedLines(lines) {
+  let fence = null;
+  return lines.map((line) => {
+    const opener = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence === null) {
+      if (opener === null) return line;
+      fence = opener[1];
+      return "";
+    }
+    if (opener !== null && opener[1][0] === fence[0] && opener[1].length >= fence.length) fence = null;
+    return "";
+  });
+}
+
+/** A bullet and the indented lines continuing it, as one string. */
+function collectItems(lines, start) {
+  const items = [];
+  let i = start;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const bullet = BULLET.exec(line);
+    if (bullet) {
+      items.push(bullet[1].trim());
+    } else if (line.trim() === "") {
+      // a blank line ends the list unless another bullet follows
+      const next = lines.slice(i + 1).find((l) => l.trim() !== "");
+      if (next === undefined || !BULLET.test(next)) break;
+    } else if (/^\s+\S/.test(line) && items.length > 0) {
+      items[items.length - 1] += ` ${line.trim()}`;
+    } else {
+      break;
+    }
+  }
+  return items;
+}
+
+function stripCheckbox(text) {
+  return text.replace(/^\[[ xX]\]\s+/, "");
+}
+
+/** The id-bearing shape: an `## Acceptance criteria` section whose every item starts with a backticked id. */
+function readIdSection(lines) {
+  const at = lines.findIndex((l) => {
+    const h = HEADING.exec(l);
+    return h !== null && h[1].length === 2 && /^acceptance criteria$/i.test(h[2]);
+  });
+  if (at === -1) return null;
+  const items = [];
+  for (let i = at + 1; i < lines.length; i++) {
+    const h = HEADING.exec(lines[i]);
+    if (h !== null && h[1].length <= 2) break;
+    const bullet = BULLET.exec(lines[i]);
+    if (bullet) items.push(bullet[1].trim());
+    else if (/^\s+\S/.test(lines[i]) && items.length > 0) items[items.length - 1] += ` ${lines[i].trim()}`;
+  }
+  if (items.length === 0) return null;
+  const parsed = items.map((item) => ID_ITEM.exec(item));
+  const withId = parsed.filter((m) => m !== null && m[2].trim() !== "").length;
+  if (withId === 0) return null;
+  if (withId < parsed.length) return { mixed: true };
+  return {
+    criteria: parsed.map((m) => {
+      const kind = /\(proof:\s*([a-z]+)\s*\)/i.exec(m[2])?.[1]?.toLowerCase();
+      return { id: m[1], text: m[2].trim(), proof: PROOF_KINDS.includes(kind) ? kind : null };
+    }),
+  };
+}
+
+/** The plain shape: an Acceptance / Acceptance criteria / Done when label, then a bullet list. */
+function readLabelledBullets(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    if (!LABEL.test(lines[i])) continue;
+    let start = i + 1;
+    while (start < lines.length && lines[start].trim() === "") start++;
+    const items = collectItems(lines, start).map(stripCheckbox).filter((t) => t !== "");
+    if (items.length > 0) return items;
+  }
+  return null;
+}
+
+/**
+ * Finds the criteria in an issue body.
+ * @returns {{shape: "ids"|"bullets"|"none", criteria: Array<{id:string,text:string,proof:string|null}>, note?: string}}
+ */
+export function parseCriteria(body, item) {
+  const lines = blankFencedLines(String(body).split(/\r?\n/));
+  const ids = readIdSection(lines);
+  if (ids?.criteria) return { shape: "ids", criteria: ids.criteria };
+  const bullets = readLabelledBullets(lines);
+  if (ids?.mixed && bullets) {
+    return {
+      shape: "none",
+      criteria: [],
+      note: "some criteria carry an id and some do not; recording nothing rather than renumbering the written ids",
+    };
+  }
+  if (bullets) {
+    return {
+      shape: "bullets",
+      criteria: bullets.map((text, n) => ({ id: `AC-${item}-${String(n + 1).padStart(2, "0")}`, text, proof: null })),
+    };
+  }
+  return { shape: "none", criteria: [] };
+}
+
+/** Sorts a failed `emit criteria` into "the item already has a person's list" and any other refusal. */
+export function classifyEmitFailure(message) {
+  // Only the CLI's replace refusal reads "refused (409):". Other answers that
+  // carry a 409, such as a lost race, read "emit failed (409):".
+  return /\brefused \(409\):/.test(message) ? "item-list-stands" : "refused";
+}
+
+/** Builds the `emit` function that runs `outerlayer emit criteria`; `spawn` is `spawnSync`, or a stand-in in tests. */
+export function makeEmit(spawn, item) {
+  return (file) => {
+    const run = spawn("outerlayer", ["emit", "criteria", file, "--item", item], { encoding: "utf8", timeout: 120000 });
+    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}` };
+    return { ok: false, message: `${run.stderr ?? ""}${run.stdout ?? ""}`.replace(/\s+/g, " ").trim() || "outerlayer emit criteria failed" };
+  };
+}
+
+function readState(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Records the issue's criteria and notes the outcome in the state file.
+ * `emit(file)` runs `outerlayer emit criteria <file>` and returns
+ * `{ ok: true }` or `{ ok: false, message }`.
+ */
+export async function recordCriteria({ body, item, reportsDir, statePath, emit }) {
+  const found = parseCriteria(body, item);
+  let outcome;
+  if (found.shape === "none") {
+    outcome = { source: "none", recorded: false, count: 0, list: [], ...(found.note ? { note: found.note } : {}) };
+  } else {
+    mkdirSync(reportsDir, { recursive: true });
+    const file = join(reportsDir, "criteria.json");
+    writeFileSync(file, `${JSON.stringify({ criteria: found.criteria }, null, 2)}\n`);
+    const result = await emit(file);
+    const base = { count: found.criteria.length, list: found.criteria };
+    if (result.ok) {
+      outcome = { source: found.shape === "ids" ? "issue-ids" : "issue-bullets", recorded: true, ...base };
+    } else if (classifyEmitFailure(result.message) === "item-list-stands") {
+      // No command returns the item's own list, so `list` stays empty; the issue's reading goes under `issueReading`.
+      outcome = {
+        source: "item",
+        recorded: false,
+        count: found.criteria.length,
+        list: [],
+        issueReading: found.criteria,
+        note: "the item already has a recorded list; it stands",
+      };
+    } else {
+      outcome = {
+        source: found.shape === "ids" ? "issue-ids" : "issue-bullets",
+        recorded: false,
+        ...base,
+        refusal: result.message,
+      };
+    }
+  }
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, `${JSON.stringify({ ...readState(statePath), criteria: outcome }, null, 2)}\n`);
+  return outcome;
+}
+
+export function summarize(outcome) {
+  const n = outcome.count;
+  const noun = n === 1 ? "criterion" : "criteria";
+  if (outcome.source === "none") return `no acceptance criteria found; none recorded${outcome.note ? ` (${outcome.note})` : ""}`;
+  if (outcome.source === "item") return `the item already has a recorded list; it stands, and the ${n} ${noun} read from the issue were not recorded`;
+  const shape = outcome.source === "issue-ids" ? "an Acceptance criteria section with ids" : "bullets under an Acceptance heading";
+  return outcome.recorded
+    ? `recorded ${n} ${noun} from ${shape}`
+    : `read ${n} ${noun} from ${shape} but the record was refused: ${outcome.refusal}`;
+}
+
+async function main(argv) {
+  const arg = (name) => {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+  };
+  const item = arg("--item");
+  const issueFile = arg("--issue-file");
+  if (!item || !/^\d+$/.test(item) || !issueFile) {
+    process.stderr.write("usage: record-criteria.mjs --item <number> --issue-file <path>\n");
+    return 2;
+  }
+  const git = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { encoding: "utf8" });
+  if (git.status !== 0) {
+    process.stderr.write(`not inside a git repository${git.error ? `: ${git.error.message}` : ""}\n`);
+    return 2;
+  }
+  const gitDir = git.stdout.trim();
+  const outcome = await recordCriteria({
+    body: readFileSync(issueFile, "utf8"),
+    item,
+    reportsDir: join(gitDir, "build-reports"),
+    statePath: join(gitDir, "build-state.json"),
+    emit: makeEmit(spawnSync, item),
+  });
+  process.stdout.write(`${summarize(outcome)}\n`);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exitCode = await main(process.argv.slice(2));