@outerlayer/cli 0.13.0 → 0.14.0

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.0",
   "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,70 @@
+{
+  "schemaVersion": 1,
+  "files": {
+    ".outerlayer/policy.yaml": [
+      "1d874f1f521a79fc286ed5400c20022921e017f48e60e474015fedc29a1130a2",
+      "78c95632b51600df0cb2e206d843e75789ccba2f80fd8dfab36d16239062b008"
+    ],
+    ".outerlayer/skills/build/SKILL.md": [
+      "5cf9bd75fb1f984f6e6b470d1f1581dc06168abf062448e6f43711fed8f6632a",
+      "6177ea457be0d238659640e6d29807708d60d68533ae3ff93af10fb513139ced",
+      "77cab8b446fb1aa865710f7cb8356c5334301a942f58f9243766bf1acf1377ad",
+      "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",
+      "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/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
@@ -218,6 +219,9 @@ Run them in order.
 
        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,12 +61,12 @@ 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.
+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. Emit it:
 
@@ -76,8 +76,36 @@ 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/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.

package/skill-pack/template/writing-specs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-specs
-description: How to write a feature spec: problem framing, goals and non-goals, assumptions, and acceptance criteria in Given/When/Then, before implementation begins. Use when asked to "write a spec", "spec this out", "write a PRD", "draft acceptance criteria", or when shaping the issue for a new feature.
+description: Describes how to write a feature spec before implementation begins - problem framing, goals and non-goals, assumptions, acceptance criteria in Given/When/Then, and the docs and structural verdicts. Use when asked to "write a spec", "spec this out", "write a PRD", "draft acceptance criteria", or when shaping the issue for a new feature.
 ---
 
 # Writing Specs
@@ -10,8 +10,9 @@ in the issue body: one clean spec, edited in place as the shape is agreed,
 never a trail of amendment comments. Its acceptance criteria sit under an
 `## Acceptance criteria` heading. Each criterion has an id, and an id is any
 stable label the team chooses, such as `LOGIN-01` or `AC-12-03`. Pick a scheme
-once and keep to it. Planning scratch is local and disposable. Nothing durable
-belongs there.
+once and keep to it. The body also records the docs and structural verdicts,
+each with a one-line reason. Planning scratch is local and disposable. Nothing
+durable belongs there.
 
 ## Lead with a summary block
 
@@ -104,6 +105,30 @@ implementing. Never write them by reading the finished implementation back.
   changes. The proof shows the running page, never a component render. The
   emitting-evidence skill covers capture.
 
+## The two verdicts
+
+Every feature spec declares two verdicts, each with a one-line reason. They
+are decided when the spec is written, and decided again from the finished
+change before the pull request opens.
+
+- **Docs.** `docs-required` when the change alters what a user sees or does.
+  Judge it against the repository's own docs: a `README.md`, a `docs/`
+  directory, a docs site. A new capability with no page yet is
+  `docs-required` too, and its criterion names the page to add. That no page
+  covers it is a reason to write one, not a reason to skip. Generated
+  reference, such as an API spec rendered as pages, is not a docs surface. A
+  new endpoint still needs a guide when using it takes a step the reference
+  cannot show, such as a credential to create or calls to make in order. When
+  required, the spec carries a criterion naming the page and its proof form.
+- **Structural.** `structural-required` when the change adds a package or an
+  app, introduces a seam between components, or moves data across a
+  boundary. When in doubt, say required: approval is where it gets argued
+  down. A structural change is worth planning before it is implemented.
+
+A verdict reversed when the change is finished is not a fault. The gap
+between the two calls is the useful signal, so state it rather than quietly
+adopting the later one.
+
 ## Honest limits
 
 A criterion may carry prose admitting what it does not cover. Useful idioms:
@@ -132,3 +157,11 @@ the one most often skipped. Re-reading your own spec does not satisfy it. Run it
 against the issue body as published, not the draft in the working tree. A spec
 whose design lives in links the reader cannot follow fails this test, and that
 failure is invisible to whoever wrote it.
+
+## Writing rules for the instructions file
+
+The reader test holds a spec to the rules in
+[references/agents-snippet.md](references/agents-snippet.md): write for a
+reader who was not in the session, and keep session history out of code
+comments. Paste that file into the repository's instructions file, such as
+`AGENTS.md`, to hold every agent's prose to the same rules.

package/skill-pack/template/writing-specs/references/agents-snippet.md

@@ -0,0 +1,57 @@
+<!-- outerlayer:writing-rules -->
+## Write for a reader who was not in the session
+
+This applies to anything a person reads: replies, commit messages, pull
+request titles and bodies, issue bodies, review comments, docs and code
+comments.
+
+The reader test: someone who knows this codebase but has never seen this
+session, the skill that ran it, or any label coined while working. If they
+would have to ask what a word means, explain it or cut it. Names made up
+during a session never appear in anything published: reviewer names, round
+labels, finding ids like C1 or N3, stage names, internal agent roles.
+Describe the thing instead.
+
+Lead with the outcome. One sentence: what changed, or what you found. Then
+only the detail that changes what the reader does next. Keep exact paths,
+numbers, identifiers and caveats. Cut the packaging around them.
+
+A sentence carries one idea and stays under about 20 words. A sentence with
+three clauses becomes three sentences. Break paragraphs often.
+
+Say what you mean. Use the literal phrase, not a metaphor or a flourish:
+"a parameter worth varying", not "a dial worth turning". Use everyday words:
+"use", not "leverage"; "start", not "initiate"; "so", not "thereby".
+
+Session telemetry, review-round tables, agent counts and raw command output
+belong in the report to the person who asked. They never go in a pull
+request or issue body.
+
+Before posting, read the text as that outsider. If they would stall on a
+term or a sentence, rewrite it.
+
+## Code comments
+
+A comment states a present-tense fact the code cannot express: a why, a
+constraint, a gotcha or an invariant. Everything else is noise that leaks
+the history of how the code was written.
+
+Never put these in a comment, a test title or a user-facing string:
+
+- Change narration: "previously…", "now uses…", "removed X", "renamed from
+  Y". Version control holds what changed. The comment says why the current
+  code is the way it is.
+- Issue, pull request or ticket numbers. They mean nothing to a reader
+  without access. If the context matters, restate its substance.
+- Project codenames, phase labels and spec section references. Describe
+  the behavior instead.
+- Labels from a working session: reviewer names, round labels, finding ids.
+
+One exception: an acceptance-criterion id may sit in a comment directly
+above the test that proves it, so a reader can find the test from the
+criterion. Never put it in the test's title.
+
+Keep comments that document constraints, invariants, footguns, security
+posture and real rationale, and do not weaken them when editing nearby. If
+a comment narrates a change but carries a real reason, rewrite it as
+present-tense rationale rather than deleting it.

package/skill-pack/template/writing-tests/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: writing-tests
+description: Writes and reviews tests that catch a specific bug - assertion strength, the seam each test binds at, binding a test to an acceptance-criterion id, and checking by mutation that a test would notice a break. Use when writing or changing any test, when binding a test to a criterion id, when reviewing whether a test proves anything, or when a mutation tool reports survivors.
+---
+
+# Writing tests
+
+A test earns its place by catching a specific bug. Before keeping one, ask:
+what is the smallest change to production code that would still pass this
+test? If the answer is "almost anything", the test checks wiring, not
+behavior. Strengthen it or delete it.
+
+The rules here hold in any language and any test framework. The examples
+use TypeScript with a Jest-style `expect`. Read each one as the equivalent
+assertion in the repository's own framework.
+
+## Assertion strength
+
+These pass for almost any implementation, so they are never the only proof
+in a test:
+
+- An "is defined" or "is not null" check passes for any value at all.
+- A truthy or falsy check. Assert the exact value instead.
+- "Was called" proves it ran, not what it ran with.
+- "Does not throw" on its own. Assert the return value too.
+
+Negative forms state a real expectation and are fine: "was never called",
+"is absent". Prefer:
+
+- Exact equality on the actual return value or the whole object shape.
+- "Called with" and the full argument shape.
+- Positional equality on lists. It catches reordering and off-by-one.
+- A negative assertion that pins an injection path shut, such as
+  `expect(query).not.toContain(rawUserValue)`.
+- On an error path, the message or status a user or operator sees, not only
+  that something failed.
+
+Do not pin brittle internals: exact log strings, incidental call counts, the
+order of unrelated calls. Those break on refactors without catching bugs.
+
+## Choose the seam
+
+Name the seam before writing the test: the boundary the test drives the code
+through.
+
+- Business behavior is proven below the user interface, in the service or
+  the pure function.
+- A user interface contract is proven at the component level, through what
+  the user sees and does.
+- Behavior that lives in the data store, such as an access rule, a trigger
+  or the real shape of a query, is proven against the real store.
+- A criterion that spans two seams gets two tests, one at each.
+
+Check two blind spots every time:
+
+- **Fake-seam blindness.** A fake that returns every field whatever the query
+  asked for proves nothing about the query. Pin the contract: assert the
+  request the code sent, make the fake honor what was asked for, or test
+  against the real dependency.
+- **Structural pinning.** "X is never called for Y" needs a spy that is
+  present and asserts zero calls. A missing fake skips silently, exactly like
+  the real skip.
+
+A field that crosses a module or package boundary needs an assertion at every
+hop: writer, relay, reader. Pinning only the ends leaves the middle free to
+drop it.
+
+## Bind a test to its criterion
+
+When a spec has acceptance criteria with ids, the test that proves a
+criterion carries the id in a comment directly above the test, never in its
+title:
+
+```ts
+// proves LOGIN-03
+it("refuses a password reset for an unknown address without saying so", () => {
+  // ...
+});
+```
+
+The title says what the test proves to someone reading a failure. The
+comment lets a reader, or a script, find the test from the criterion. Never
+put a criterion id in a comment that is not that binding, because a reader
+will take it as one.
+
+Write the test from the criterion's words, at the seam it names, before the
+implementation exists. Run it and read the failure. It must fail because the
+behavior is absent, not because of a typo or a missing import.
+
+A criterion with a proof form such as `(proof: screenshot)` is proven by the
+evidence a reviewer sees, not by a test. It may still have one.
+
+## Mutation: prove the test would notice
+
+A green suite proves the tests run, not that they would catch a bug. Check
+the code the change adds or alters.
+
+**By hand.** For every condition, guard, limit and assignment the change
+adds, break it: invert it, widen it, drop half of an `and`, ignore the field.
+Run the one test file that should catch it. If nothing fails, write the
+assertion that would. Then take each criterion and break the production code
+it describes. Its test must fail. A test bound to a criterion that survives
+the break is not coverage.
+
+**With a tool.** Mutation testing is optional. Where the repository has a
+mutation tool, run it over the changed lines only. Each mutant that survives
+is a test still to write, not a score to accept. Two mutants are equivalent
+only when no observable output can differ; say why when you claim it. Hand
+breaks still matter for files the tool does not mutate, such as SQL, shell
+scripts, markup and configuration.
+
+## The repository's own rules
+
+The instructions file may name test commands, required checks, mocking rules
+or coverage thresholds. Those come first where they are stricter than this
+skill. Add them here when they are the team's standard, because this file is
+the team's to edit.