@outerlayer/cli 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @outerlayer/cli
 
+## 0.14.1
+
+### Patch Changes
+
+- f47136a: The starter `/build` skill now links each criterion to the tests that cite it, so the work item's Criteria tab lists them instead of "No tests found". A new script, `criterion-citations.mjs`, runs on the criteria judge's report before it is emitted. It finds tests that name a criterion's id in a title or a comment, whatever the id's form. `outerlayer init --update` adds the script to repositories set up earlier.
+
 ## 0.14.0
 
 ### Minor Changes

package/dist/build-info.json

@@ -1 +1 @@
-{"id":"2026-10-08T21:15:36.925Z+415a9ac","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}
+{"id":"2026-10-09T00:29:08.046Z+2d52691","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outerlayer/cli",
-  "version": "0.14.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/shipped.json

@@ -9,6 +9,7 @@
       "5cf9bd75fb1f984f6e6b470d1f1581dc06168abf062448e6f43711fed8f6632a",
       "6177ea457be0d238659640e6d29807708d60d68533ae3ff93af10fb513139ced",
       "77cab8b446fb1aa865710f7cb8356c5334301a942f58f9243766bf1acf1377ad",
+      "93953397c31d47a6f1c06edb8ae2190e1d8a3fca20c616deb33991311cee39a8",
       "a6743050c5c387e962ad4264526d9a3c10edf36823e4b6829f200bf79a4e45e7",
       "b0aa9b6962675f772b67a4390c15b6b0100390983d958c656a826a066399f3d0",
       "f4e1661c6f87d7ff6d23c6182530fa0a9cb87c4dc3f31e48f2be11f32ebb2c00"
@@ -27,6 +28,7 @@
     ".outerlayer/skills/build/references/release.md": [
       "0b0af40c82473cf192f697537ed5a84801a14e79bb11790d72226d7f7f49cca0",
       "1113259bdf7d8c28edcbdb9b4c83c2f2bd4c5eaf817cf30bf428478ff91694e9",
+      "1f4fe97ca8f11d6681db5734f3103af5ea175a9472ff1d38b10cb463f4956a6a",
       "4687f56bcec766f1926d58a208418f800a1727c073b5e6047b40e3aaac2bd6c9",
       "81a764eb317fcb4672bedd35e7b9aa68d1c0b73f82fc2dfa03e5a78758db8f14",
       "985e02b98105b00c356014e003b2d60e9c458c3dcbeef7378274ccb84af031fc"
@@ -40,6 +42,9 @@
       "6f93e2ae74d3c02a0d4c14a6b2c805f523d234a8c56789f40a7c7c59700ef277",
       "9d4d2e5e0307ea8c38cf885cd67d06a939b7fc2bed65f5080ca9610178949d74"
     ],
+    ".outerlayer/skills/build/scripts/criterion-citations.mjs": [
+      "0902118ec216182f9d0ba0f6c7966306ad6891d8e846022123d3f86aaf175fce"
+    ],
     ".outerlayer/skills/build/scripts/record-criteria.mjs": [
       "36f19e730bc220fa21622b3bb0a306999f038b8220a0a07a1efe21ec0f748729",
       "596e9a78e62cbea040a3bf428cd54bf59687e9e89001fad719304f88d03ca2ea",

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

@@ -215,8 +215,9 @@ 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

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

@@ -68,8 +68,11 @@ 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. Emit it:
+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

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));