@outerlayer/cli 0.13.0 → 0.14.1

package/dist/{work-comment-cmd-FI2TMAYQ.js → work-comment-cmd-FFUM4TJU.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { resolveCredentials, postJson, getJson } from './chunk-P4MM66C6.js';
-import './chunk-EFZLAYPE.js';
+import { resolveCredentials, postJson, getJson } from './chunk-SWHQ4LUM.js';
+import './chunk-NPQWKGUA.js';
 import { detectActiveSession } from './chunk-IP7BIBXJ.js';
-import './chunk-4QVZCVWT.js';
-import { sanitizeTerminal } from './chunk-CNFVHDHG.js';
+import './chunk-YDSMROTB.js';
+import { sanitizeTerminal } from './chunk-WUYTWNMA.js';
 import { resolveRepoIdentity } from './chunk-JXYVA45C.js';
 import './chunk-4KSQKQXE.js';
 import './chunk-N6LURUEF.js';
-import './chunk-YRYMNBGQ.js';
+import { C } from './chunk-YRYMNBGQ.js';
 import { parseTrackerNumber, trackerNumberError } from './chunk-WZBHBH3J.js';
 import { defaultFetch } from './chunk-YO4PSLVB.js';
 import './chunk-PLMTLGYH.js';
@@ -22,9 +22,6 @@ import './chunk-Z5GEFMRW.js';
 import { randomUUID } from 'crypto';
 
 createRequire(import.meta.url);
-var GREEN = "\x1B[32m";
-var DIM = "\x1B[2m";
-var RESET = "\x1B[0m";
 var WorkCommentCommandError = class extends Error {
 };
 function resolveAction(opts) {
@@ -78,7 +75,7 @@ async function runWorkComment(opts) {
   const thread = data.thread;
   const waitingOn = thread?.waitingOn ?? null;
   const criterionLabel = opts.criterion ? `criterion ${opts.criterion}` : "the general thread";
-  const output = opts.json ? JSON.stringify(data) : `${GREEN}\u2713${RESET} commented on ${criterionLabel} of item #${itemNumber} ${DIM}\xB7${RESET} waiting on ${waitingOn ?? "no one"}`;
+  const output = opts.json ? JSON.stringify(data) : `${C.green}\u2713${C.reset} commented on ${criterionLabel} of item #${itemNumber} ${C.dim}\xB7${C.reset} waiting on ${waitingOn ?? "no one"}`;
   if (!opts.quiet) process.stdout.write(output + "\n");
   return { data, output };
 }
@@ -102,7 +99,7 @@ async function runWorkThreads(opts) {
   return { data, output };
 }
 function renderThread(label, thread) {
-  const header = `${DIM}${label === "general" ? "general" : `criterion ${label}`} \xB7 waiting on ${thread.waitingOn ?? "no one"}${RESET}`;
+  const header = `${C.dim}${label === "general" ? "general" : `criterion ${label}`} \xB7 waiting on ${thread.waitingOn ?? "no one"}${C.reset}`;
   const comments = thread.comments.map(
     (c) => `  ${c.author.kind === "person" ? "person" : "agent"} ${sanitizeTerminal(c.author.name)}: ${sanitizeTerminal(c.body)}${c.action ? ` (${c.action})` : ""}`
   );

package/dist/{work-open-pr-cmd-OVHJ5I5H.js → work-open-pr-cmd-HLDWP4T2.js}

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { itemLabel, runWorkPr, WorkPrCommandError } from './chunk-6S3H3J6H.js';
-import { resolveCredentials } from './chunk-P4MM66C6.js';
-import './chunk-EFZLAYPE.js';
+import { itemLabel, runWorkPr, WorkPrCommandError } from './chunk-JJEGKEFV.js';
+import { resolveCredentials } from './chunk-SWHQ4LUM.js';
+import './chunk-NPQWKGUA.js';
 import './chunk-IP7BIBXJ.js';
-import './chunk-4QVZCVWT.js';
-import './chunk-CNFVHDHG.js';
+import './chunk-YDSMROTB.js';
+import './chunk-WUYTWNMA.js';
 import './chunk-JXYVA45C.js';
 import './chunk-4KSQKQXE.js';
 import './chunk-N6LURUEF.js';
-import './chunk-YRYMNBGQ.js';
+import { C } from './chunk-YRYMNBGQ.js';
 import { parseWorkItemEnv } from './chunk-GQD22KKN.js';
 import './chunk-WZBHBH3J.js';
 import { defaultFetch } from './chunk-YO4PSLVB.js';
@@ -25,9 +25,6 @@ import { spawnSync } from 'child_process';
 import { readFileSync } from 'fs';
 
 createRequire(import.meta.url);
-var GREEN = "\x1B[32m";
-var DIM = "\x1B[2m";
-var RESET = "\x1B[0m";
 var ITEM_KEY_PREFIX = "olitem_";
 var WorkOpenPrCommandError = class extends Error {
 };
@@ -163,7 +160,7 @@ async function runWorkOpenPr(opts) {
   } else {
     data = await openWithGh({ ...opts, env }, opts.title, opts.bodyFile, cwd);
   }
-  const output = opts.json ? JSON.stringify(data) : `${GREEN}\u2713${RESET} ${data.created ? "opened" : "edited"} ${DIM}\xB7${RESET} ${data.repository}#${data.number} ${DIM}\xB7${RESET} ${data.url}${data.workItemNumber == null ? "" : ` ${DIM}\u2192${RESET} ${itemLabel({ workItemId: "", ...data })}`}`;
+  const output = opts.json ? JSON.stringify(data) : `${C.green}\u2713${C.reset} ${data.created ? "opened" : "edited"} ${C.dim}\xB7${C.reset} ${data.repository}#${data.number} ${C.dim}\xB7${C.reset} ${data.url}${data.workItemNumber == null ? "" : ` ${C.dim}\u2192${C.reset} ${itemLabel({ workItemId: "", ...data })}`}`;
   if (!opts.quiet) process.stdout.write(output + "\n");
   return { data, output };
 }

package/dist/{work-pr-cmd-Y5TDMQ4O.js → work-pr-cmd-L77K32WK.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-export { WorkPrCommandError, itemLabel, runWorkPr } from './chunk-6S3H3J6H.js';
-import './chunk-EFZLAYPE.js';
+export { WorkPrCommandError, itemLabel, runWorkPr } from './chunk-JJEGKEFV.js';
+import './chunk-NPQWKGUA.js';
 import './chunk-IP7BIBXJ.js';
-import './chunk-4QVZCVWT.js';
-import './chunk-CNFVHDHG.js';
+import './chunk-YDSMROTB.js';
+import './chunk-WUYTWNMA.js';
 import './chunk-JXYVA45C.js';
 import './chunk-4KSQKQXE.js';
 import './chunk-N6LURUEF.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outerlayer/cli",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "OuterLayer CLI — commands: init, connect, doctor, login, logout, sync, daemon (alias: watch), emit, work, runner, hooks, mcp, import, 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/emitting-evidence/SKILL.md

@@ -104,9 +104,15 @@ Then run `outerlayer sync`, and copy the report's deep link from the pull reques
 
 Use `--result fail` when the review left a finding unfixed. Record it once. Outside a build, pass the item's number to `--item`.
 
-## The criteria report
+## The criteria report and the `acceptance-criteria` check
 
-Bind the judge's report on each criterion, an HTML file, with `--for acceptance-criteria`. No check requires it. The item page links it at the top of its Criteria tab for the reviewer. Emit it only when the item has recorded criteria.
+Bind the judge's report on each criterion, an HTML file, with `--for acceptance-criteria`. The item page links it at the top of its Criteria tab for the reviewer. Emit it only when the item has recorded criteria.
+
+Then run `outerlayer sync`, copy the report's deep link from the evidence comment the same way, and record the judge's verdict on the `acceptance-criteria` check that `outerlayer init` writes:
+
+    outerlayer emit acceptance-criteria --item "$OUTERLAYER_WORK" --result pass --link <the report's deep link>
+
+Use `--result pass` only when the judge found every criterion it judged satisfied, and `--result fail` when it found one unmet. When there is no criterion to judge, record nothing: the row reads "not proven", which is true. Skip the emit in a repository with no `.outerlayer/validators/acceptance-criteria.yaml`.
 
 A session never records a pass or fail on an artifact. It emits the artifact, and a person or a check decides.
 

package/skill-pack/shipped.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "files": {
+    ".outerlayer/policy.yaml": [
+      "1d874f1f521a79fc286ed5400c20022921e017f48e60e474015fedc29a1130a2",
+      "78c95632b51600df0cb2e206d843e75789ccba2f80fd8dfab36d16239062b008"
+    ],
+    ".outerlayer/skills/build/SKILL.md": [
+      "5cf9bd75fb1f984f6e6b470d1f1581dc06168abf062448e6f43711fed8f6632a",
+      "6177ea457be0d238659640e6d29807708d60d68533ae3ff93af10fb513139ced",
+      "77cab8b446fb1aa865710f7cb8356c5334301a942f58f9243766bf1acf1377ad",
+      "93953397c31d47a6f1c06edb8ae2190e1d8a3fca20c616deb33991311cee39a8",
+      "a6743050c5c387e962ad4264526d9a3c10edf36823e4b6829f200bf79a4e45e7",
+      "b0aa9b6962675f772b67a4390c15b6b0100390983d958c656a826a066399f3d0",
+      "f4e1661c6f87d7ff6d23c6182530fa0a9cb87c4dc3f31e48f2be11f32ebb2c00"
+    ],
+    ".outerlayer/skills/build/references/agent-briefs.md": [
+      "3c875a4f287f574eea954c6daa52b17529cdeba8ec4007d78084d911350d1218",
+      "7c2a651e7c827d8e3fb9df889d3776b552eb02d315db5ace27d2baad78aab6a5"
+    ],
+    ".outerlayer/skills/build/references/criteria-judge.md": [
+      "62db8f6d77f31ca25a9071c05429e0f639f9b2bdd7f7cb04cb14a1b0db509537"
+    ],
+    ".outerlayer/skills/build/references/evidence.md": [
+      "ceff5488bae31198ed4738ae1a230c0119f973ced439dac360eba6e24e1604f4",
+      "f27502610358e436e7ffb61d4fd281289e162f6de6b2c11396f17b2fa63802c9"
+    ],
+    ".outerlayer/skills/build/references/release.md": [
+      "0b0af40c82473cf192f697537ed5a84801a14e79bb11790d72226d7f7f49cca0",
+      "1113259bdf7d8c28edcbdb9b4c83c2f2bd4c5eaf817cf30bf428478ff91694e9",
+      "1f4fe97ca8f11d6681db5734f3103af5ea175a9472ff1d38b10cb463f4956a6a",
+      "4687f56bcec766f1926d58a208418f800a1727c073b5e6047b40e3aaac2bd6c9",
+      "81a764eb317fcb4672bedd35e7b9aa68d1c0b73f82fc2dfa03e5a78758db8f14",
+      "985e02b98105b00c356014e003b2d60e9c458c3dcbeef7378274ccb84af031fc"
+    ],
+    ".outerlayer/skills/build/references/review-briefs.md": [
+      "2c8b436795b583a61aa6f98f48611db554f0dd52b27a9ab748a7db5f96526aec"
+    ],
+    ".outerlayer/skills/build/references/review-loop.md": [
+      "155ab732ccf4c25f000853e98a27a3d2f3a022c75979601bb71d86f07983216d",
+      "5f30b56d226b279ec5f65ad73b823e3aeeac0c14f2ee539fb79cf7ba7b2cac6d",
+      "6f93e2ae74d3c02a0d4c14a6b2c805f523d234a8c56789f40a7c7c59700ef277",
+      "9d4d2e5e0307ea8c38cf885cd67d06a939b7fc2bed65f5080ca9610178949d74"
+    ],
+    ".outerlayer/skills/build/scripts/criterion-citations.mjs": [
+      "0902118ec216182f9d0ba0f6c7966306ad6891d8e846022123d3f86aaf175fce"
+    ],
+    ".outerlayer/skills/build/scripts/record-criteria.mjs": [
+      "36f19e730bc220fa21622b3bb0a306999f038b8220a0a07a1efe21ec0f748729",
+      "596e9a78e62cbea040a3bf428cd54bf59687e9e89001fad719304f88d03ca2ea",
+      "64de9445087b247b0781a4e6e025ef97b1259ce1c91819bf541decc26b8f8400"
+    ],
+    ".outerlayer/skills/spec/SKILL.md": [
+      "71e81fabf353ad6117c54e061868538bf00066b78c2528f5a8364445d1def02e",
+      "9039ae30d4e836b5c5cfba4a14344e46fd13694ae9e4d88e750abce34dfcd9e6"
+    ],
+    ".outerlayer/skills/writing-specs/SKILL.md": [
+      "a956aac4249118a058c4327c5751472883588720950d4a96f80c7e91f454bef9",
+      "eb8aa95f5e76a46ae9bf340989fb40e470fd750ded791ba80b5f8c5c325513e5"
+    ],
+    ".outerlayer/skills/writing-specs/references/agents-snippet.md": [
+      "fc47325f27cfce406a14ad71009d3687d3720deb572d40936e29fd091ca6c71d"
+    ],
+    ".outerlayer/skills/writing-tests/SKILL.md": [
+      "b00f5970b568159ca0bfbc75c3834938749ad5e2e73a80769d88bbe3c8c26737"
+    ],
+    ".outerlayer/validators/acceptance-criteria.yaml": [
+      "3b2054aa1d4bd9f7441e88eec1a3bdf61b61ad00efa79736e26a5dd601d43910"
+    ],
+    ".outerlayer/validators/code-review.yaml": [
+      "05041976e4d84d6256ed88995ea4fd1566abc6d3a9574863065cf855dcafcf70",
+      "fbdf0baca0064b09e47f5984afc322d582accd142c3377c06622bc6567b0e98c"
+    ]
+  }
+}

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

@@ -84,8 +84,9 @@ These bind the orchestrator in every phase. Rule 5 also binds every spawned agen
    "$OUTERLAYER_WORK" --json`. Each thread with `waitingOn` of `agent` holds a
    person's comment. Answer each before the run ends, as the `amend` skill does.
 5. **A session never records a pass or fail on an artifact.** It emits
-   artifacts. A person decides pass or fail. The one result a build records
-   is its own review's verdict, on the `code-review` check.
+   artifacts. A person decides pass or fail. A build records two results,
+   both verdicts of its own agents: its review's, on the `code-review`
+   check, and its criteria judge's, on the `acceptance-criteria` check.
 6. **Observed status only.** Every status claim in the final report (a gate
    result, a CI conclusion, mergeability) quotes command output observed
    after the last change it describes. No quoted output means unknown, never
@@ -214,10 +215,14 @@ Run them in order.
    which links it, and a local session with `gh pr create` and then
    `outerlayer work pr <number>`. When the build recorded criteria, from the issue or drafted, a fresh agent judges them with
    [references/criteria-judge.md](references/criteria-judge.md), and the
-   judge's HTML report is emitted:
+   judge's HTML report is linked to its tests and emitted:
 
+       node .outerlayer/skills/build/scripts/criterion-citations.mjs --report <judge-report>.html
        outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against its test"
 
+   Its verdict is recorded on the `acceptance-criteria` check, as release.md
+   says. When the state file holds no criteria, no judge runs and that
+   check gets no result, so it reads "not proven", never passed.
    Watch CI until every check has concluded.
 6. **Manual test and evidence.** Read [references/evidence.md](references/evidence.md)
    when the pull request opens, and run it. Capture the proof each criterion

package/skill-pack/template/build/references/release.md

@@ -61,23 +61,54 @@ the final report. Never record the result with another link.
 
 ## Judge the criteria
 
-When the issue has criteria, spawn one fresh agent on
-[criteria-judge.md](criteria-judge.md), with the worktree path, the base ref,
-the pull request number, the path of the build's state file, and a report
-path under `build-reports/`. Above forty
-criteria, spawn one judge per group of about forty in the same wave, each with
-its own report path, and merge their results by concatenation.
-
-The judge writes an HTML report with one verdict per criterion. Emit it:
-
+When the state file holds criteria, from the issue or drafted, spawn one
+fresh agent on [criteria-judge.md](criteria-judge.md), with the worktree path,
+the base ref, the pull request number, the path of the build's state file,
+and a report path under `build-reports/`. Above forty criteria, spawn one
+judge per group of about forty in the same wave, each with its own report
+path, and merge their results by concatenation into one report.
+
+The judge writes an HTML report with one verdict per criterion. Link each
+criterion to the tests that cite it, which the Criteria tab lists. With several
+judges, run it on the merged report. Then emit it:
+
+    node .outerlayer/skills/build/scripts/criterion-citations.mjs --report <judge-report>.html
     outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against the test that cites it"
 
 Then run `outerlayer sync`. List every unsatisfied criterion in the final
 report. A criterion that declares a proof form such as a screenshot or video is
 proven only by an artifact bound to it on the pull request. The judge cannot
 see that, so confirm each has an artifact of the declared kind, and emit any
-that is missing in the evidence phase. When no criteria were recorded, no judge
-runs and no judge report is emitted.
+that is missing in the evidence phase.
+
+## Record the criteria verdict
+
+Once the judge's report is synced, copy its deep link from the pull request's
+evidence comment. The link can take up to a minute to appear after the sync.
+If it is not there yet, wait a minute and read the comment again. Never build
+the link by hand, and never link a pull request comment. Then record the
+judge's verdict on the `acceptance-criteria` check, once:
+
+    outerlayer emit acceptance-criteria --item "$OUTERLAYER_WORK" --result pass --link <the judge report's deep link>
+
+The result is the judge's own last line. Record `--result pass` only when it
+reads `result: pass`: every criterion the judge judged is satisfied. Record
+`--result fail` when it reads `result: fail`, because a criterion is not
+satisfied. A fail is recorded as fail, never withheld. With several judges,
+record fail when any one of them failed. A criterion the judge marked
+`not-judged` neither passes nor fails this check: its declared artifact
+proves it on its own row. Drafted criteria are judged and recorded here like
+the issue's own.
+
+When the state file holds no criteria at all (`criteria.source` is `none`,
+for example because drafting found nothing to draft), no judge runs, no
+judge report is emitted, and nothing is recorded on this check. The row
+then reads "not proven" once the build's claim ends. That is deliberate: no
+criterion was judged, so the row must not read as passed, and a fail would
+claim the judge found an unmet criterion. Name the unjudged check in the
+final report. When the link has not appeared after a sync and a second look,
+stop and name it as a blocker in the final report. Never record the result
+with another link.
 
 ## Watch CI
 

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

@@ -26,7 +26,7 @@ whatever its size.
 | Floor, or larger | full | generalist + up to three | when criteria exist |
 
 An item with no criteria recorded is `small` whatever its diff, and no judge
-runs. That happens only when the build could not draft a single criterion, since
+runs, so the `acceptance-criteria` check gets no result. That happens only when the build could not draft a single criterion, since
 an issue with no criteria gets a drafted list. A drafted list
 (`criteria.source` is `drafted`) is tiered and judged like criteria the issue
 wrote.

package/skill-pack/template/build/scripts/criterion-citations.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Links each recorded criterion to the tests that cite it, by writing a
+// `criterion-citations` JSON block into the criteria judge's HTML report. The
+// work item's Criteria tab reads that block to list a criterion's tests. Run
+// it on the report just before emitting it. Needs only Node and git.
+//
+//   node criterion-citations.mjs --report <path> [--criteria-file <path>]
+//
+// The criteria come from the file `record-criteria.mjs` wrote, by default
+// `<git dir>/build-reports/criteria.json`. A test cites a criterion when the
+// criterion's id appears as a whole token in a test's title or in a comment
+// above it. Only git-tracked test files are scanned, so every link names code
+// that a commit contains. The link names the HEAD commit and is written only
+// when the origin remote is on GitHub; otherwise the test is listed unlinked.
+// A criterion no test cites gets an empty list. An existing block in the
+// report is replaced.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** A tracked file that holds tests: JS and TS `.test`/`.spec`, Python `test_*.py`/`*_test.py`, Go `*_test.go`, Ruby `*_spec.rb`. */
+export const TEST_FILE = /(?:\.(?:test|spec)\.[cm]?[jt]sx?|(?:^|\/)test_[^/]*\.py|_test\.(?:py|go)|_spec\.rb)$/;
+/** A line that is only a comment: `//`, `#`, `*`, `/*`, `--` or `<!--` first. */
+const COMMENT_LINE = /^\s*(?:\/\/|#|\*|\/\*|--|<!--)/;
+const BLOCK_ID = /<script type="application\/json" id="criterion-citations">[\s\S]*?<\/script>/;
+
+/** A criteria file the agent must fix before anything is written. */
+export class CitationInputError extends Error {}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** A pattern that finds `id` as a whole token: not inside a longer id such as `WC-10` for `WC-1`, and still found before a sentence's full stop. */
+export function idPattern(id) {
+  return new RegExp(`(?<![A-Za-z0-9_:-])${escapeRegExp(id)}(?![A-Za-z0-9_:-]|\\.[A-Za-z0-9])`);
+}
+
+/** The ids of a criteria file shaped `{ "criteria": [{ "id" }] }`. */
+export function criterionIds(input) {
+  if (typeof input !== "object" || input === null || !Array.isArray(input.criteria)) {
+    throw new CitationInputError('the criteria file must be { "criteria": [ ... ] }');
+  }
+  return input.criteria.map((entry, n) => {
+    if (typeof entry !== "object" || entry === null || typeof entry.id !== "string" || entry.id === "") {
+      throw new CitationInputError(`criteria[${n}] has no id`);
+    }
+    return entry.id;
+  });
+}
+
+/**
+ * The 1-based lines of one file's tests that cite `id`. A citation in a
+ * comment belongs to the first line after the comment that is not blank or
+ * another comment line (the test call); a citation anywhere else, such as a
+ * title, belongs to its own line. A comment with nothing after it keeps its
+ * own line.
+ */
+export function citingLines(contents, id) {
+  const pattern = idPattern(id);
+  const lines = contents.split("\n");
+  const found = new Set();
+  lines.forEach((text, index) => {
+    if (!pattern.test(text)) return;
+    if (!COMMENT_LINE.test(text)) {
+      found.add(index + 1);
+      return;
+    }
+    let next = index + 1;
+    while (next < lines.length && (lines[next].trim() === "" || COMMENT_LINE.test(lines[next]))) next += 1;
+    found.add(next < lines.length ? next + 1 : index + 1);
+  });
+  return [...found];
+}
+
+/** `owner/repo` for a github.com remote in ssh or https form, else `null`. */
+export function parseGithubRemote(remoteUrl) {
+  const trimmed = (remoteUrl ?? "").trim();
+  const match =
+    /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(trimmed) ??
+    /^(?:https?|ssh):\/\/(?:[^@/]+@)?(?:www\.)?github\.com(?::\d+)?\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(trimmed);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+/** A link to `path` at line `line` of commit `sha`, or `null` when there is no GitHub repository to link to. */
+export function testHref(repository, sha, path, line) {
+  if (!repository || !sha) return null;
+  const encoded = path.split("/").map(encodeURIComponent).join("/");
+  return `https://github.com/${repository}/blob/${sha}/${encoded}#L${line}`;
+}
+
+/**
+ * Each criterion's citing tests, as `{ [id]: [{ path, line, href }] }` in
+ * the order the ids are given. `files` is `[{ path, contents }]` for the
+ * tracked test files; tests sort by path then line.
+ */
+export function buildCitations({ ids, files, repository = null, sha = null }) {
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const result = {};
+  for (const id of ids) {
+    result[id] = sorted.flatMap(({ path, contents }) =>
+      citingLines(contents, id).map((line) => ({ path, line, href: testHref(repository, sha, path, line) })),
+    );
+  }
+  return result;
+}
+
+/** The block as HTML. `<` is escaped so no cited path or title can end the script element early. */
+export function renderBlock(citations) {
+  const json = JSON.stringify(citations).replace(/</g, "\\u003c");
+  return `<script type="application/json" id="criterion-citations">${json}</script>`;
+}
+
+/** `html` with the block set: an existing one replaced, else added before `</body>`, else appended. */
+export function withBlock(html, citations) {
+  const block = renderBlock(citations);
+  if (BLOCK_ID.test(html)) return html.replace(BLOCK_ID, () => block);
+  const at = html.lastIndexOf("</body>");
+  return at === -1 ? `${html}\n${block}\n` : `${html.slice(0, at)}${block}\n${html.slice(at)}`;
+}
+
+function git(cwd, args) {
+  const run = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return run.status === 0 ? run.stdout : null;
+}
+
+/** Reads the repository's tracked test files and its GitHub identity. `null` outside a git checkout. */
+function readRepository(cwd) {
+  const top = git(cwd, ["rev-parse", "--show-toplevel"])?.trim();
+  const tracked = top ? git(top, ["ls-files", "-z"]) : null;
+  if (!top || tracked === null) return null;
+  const files = [];
+  for (const path of tracked.split("\0").filter((p) => p !== "" && TEST_FILE.test(p))) {
+    try {
+      files.push({ path, contents: readFileSync(join(top, path), "utf8") });
+    } catch {
+      // A tracked file deleted from the working tree has no tests to read.
+    }
+  }
+  const sha = git(top, ["rev-parse", "HEAD"])?.trim() || null;
+  const repository = parseGithubRemote(git(top, ["remote", "get-url", "origin"]) ?? "");
+  return { files, sha, repository };
+}
+
+function main(argv) {
+  const arg = (name) => {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+  };
+  const report = arg("--report");
+  if (!report) {
+    process.stderr.write("usage: criterion-citations.mjs --report <path> [--criteria-file <path>]\n");
+    return 2;
+  }
+  const repo = readRepository(process.cwd());
+  if (!repo) {
+    process.stderr.write("not inside a git repository\n");
+    return 2;
+  }
+  let criteriaFile = arg("--criteria-file");
+  if (!criteriaFile) {
+    const gitDir = git(process.cwd(), ["rev-parse", "--absolute-git-dir"])?.trim();
+    criteriaFile = join(gitDir ?? "", "build-reports", "criteria.json");
+  }
+  let ids;
+  try {
+    ids = criterionIds(JSON.parse(readFileSync(criteriaFile, "utf8")));
+  } catch (err) {
+    process.stderr.write(`cannot read the criteria from "${criteriaFile}": ${err.message}\n`);
+    return 2;
+  }
+  if (!existsSync(report)) {
+    process.stderr.write(`the report "${report}" does not exist\n`);
+    return 2;
+  }
+  const citations = buildCitations({ ids, files: repo.files, repository: repo.repository, sha: repo.sha });
+  writeFileSync(report, withBlock(readFileSync(report, "utf8"), citations));
+  const cited = ids.filter((id) => citations[id].length > 0).length;
+  process.stdout.write(`linked ${cited} of ${ids.length} criteria to the tests that cite them in ${report}\n`);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exitCode = main(process.argv.slice(2));

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

@@ -1,17 +1,18 @@
 ---
 name: spec
 description: >
-  Turn an idea into an approved issue: search for duplicates, draft acceptance
-  criteria with their proof forms, split work that is too big for one story,
-  and file it after you approve it. Then offer to start the build. Use when you
-  want to write up a feature or change before building it. Invoke with
+  Turns an idea into an approved issue: searches for duplicates, drafts
+  acceptance criteria with their proof forms, decides the docs and structural
+  verdicts, splits work that is too big for one story, and files it after you
+  approve it. Then offers to start the build. Use when you want to write up a
+  feature or change before building it. Invoke with
   /spec <what you want built>.
 ---
 
 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
-block, problem before solution, non-goals and Given/When/Then criteria. Follow
-it, and do not restate it here.
+block, problem before solution, non-goals, Given/When/Then criteria and the
+two verdicts. Follow it, and do not restate it here.
 
 This skill files the issue. It does not branch, write code or run tests.
 `/build` does that, on a work item that names the issue.
@@ -41,31 +42,41 @@ Run them in order. Do not skip the approval.
    only where nothing visible changes. A criterion nobody can prove is a
    criterion nobody can build to, so give every one either a proof form or a
    named test.
-3. **Size.** More than twenty-four criteria is not one story. Above that, show
+3. **Verdicts.** Decide the docs verdict and the structural verdict as
+   `writing-specs` defines them. Give each a one-line reason. A docs-required
+   verdict adds a criterion naming the page to change or add and its proof
+   form. Record both verdicts in the issue body, so whoever builds it can
+   compare them with the finished change.
+4. **Size.** More than twenty-four criteria is not one story. Above that, show
    the work already split into slices that each stand alone. Slice one carries
    the criteria the others depend on, and the rest become their own specs. The
    user may redraw the split. Skipping it is not on offer.
-4. **Reader pass.** Send the title and body through one cold rewrite agent. Its
+5. **Reader pass.** Send the title and body through one cold rewrite agent. Its
    only inputs are the draft and one writing rule: write for a reader who was
    not in this conversation, lead with the outcome, keep sentences under about
-   twenty words, and use plain words. It never sees this conversation. Criteria keep
-   their exact wording. Check that every path, identifier, number and link
-   survived, and restore anything the rewrite dropped.
-5. **Checkpoint.** Show the drafted title and body and the criteria with their
-   proof forms, and wait for explicit approval. Before showing them, check every
-   criterion: it has an id, a Given, When and Then, and a proof form or a named
-   test. A criterion that fails the check goes back to step 2. Apply requested
+   twenty words, and use plain words. When the instructions file carries the
+   writing rules from the `writing-specs` skill's
+   `references/agents-snippet.md`, pass that section verbatim instead. The
+   agent never sees this conversation. Criteria keep their exact wording.
+   Check that every path, identifier, number and link survived, and restore
+   anything the rewrite dropped.
+6. **Checkpoint.** Show the drafted title and body, the criteria with their
+   proof forms, and both verdicts with their reasons. Wait for explicit
+   approval. Before showing them, check every criterion: it has an id, a
+   Given, When and Then, and a proof form or a named test. Check that both
+   verdicts are there, each with its reason. A criterion that fails the check
+   goes back to step 2, and a missing verdict to step 3. Apply requested
    edits, run the reader pass again over the edited text, and show it again
-   until approved. Nothing is filed before this point. A spec the user rejects
-   leaves no issue behind.
-6. **File it.** Through the team's tracker tool, file the approved title, body
-   and full criteria. Then file the slices from step 3, and only the ones the
+   until approved. Nothing is filed before this point. A spec the user
+   rejects leaves no issue behind.
+7. **File it.** Through the team's tracker tool, file the approved title, body
+   and full criteria. Then file the slices from step 4, and only the ones the
    user named. The issue is the source of truth from here on. Note its
    reference exactly as the tracker gives it: a number, or a Linear or Jira key.
-7. **Ask whether to build.** Ask the user exactly one question: build it now, or
+8. **Ask whether to build.** Ask the user exactly one question: build it now, or
    not yet. Never start work unasked, because the user may want to hold the
    issue.
-8. **Start the build.** On a yes, run `outerlayer work build --issue <reference>`,
+9. **Start the build.** On a yes, run `outerlayer work build --issue <reference>`,
    where the reference is the issue number or the Linear or Jira key exactly as
    the user typed it. Print the item number the command reports and the launch
    line:
@@ -80,5 +91,5 @@ Run them in order. Do not skip the approval.
 
 ## Scope limits
 
-One `/spec` files one issue, plus the slices the user approves in step 3. It
+One `/spec` files one issue, plus the slices the user approves in step 4. It
 files nothing in another repository. It never creates a branch or edits code.