@outerlayer/cli 0.12.0 → 0.14.0

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

@@ -1,13 +1,19 @@
 #!/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.
+// Records the criteria the build read from the issue, or drafted for an issue
+// that has none, and notes the outcome in the build's state file. The agent
+// reads the issue and writes the criteria file; this script checks it, gives
+// the criteria ids, runs `outerlayer emit criteria`, and handles its answer.
+// Needs only Node.
 //
-//   node record-criteria.mjs --item <number> --issue-file <path>
+//   node record-criteria.mjs --item <number> --criteria-file <path> [--drafted]
 //
-// 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.
+// The criteria file is `{ "criteria": [{ "id"?, "text", "proof"? }] }`, in
+// the order the issue lists them. The ids are kept only when every criterion
+// carries one that fits the id grammar; otherwise every criterion is numbered
+// `AC-<item>-NN` in order. A drafted list is always numbered and is recorded
+// with `drafted: true`. An empty list records nothing. The script never edits
+// the issue, and never replaces a list the item already has (the gateway
+// answers 409 and the item's list stands).
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -15,118 +21,64 @@ import { pathToFileURL } from "node:url";
 
 /** Mirrors ARTIFACT_KINDS in @outerlayer/session-schema (a test pins them equal); this script imports no packages. */
 export const PROOF_KINDS = ["video", "screenshot", "report", "log", "test", "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;
+/** Mirrors ArtifactCriterionIdSchema in @outerlayer/session-schema (a test pins them equal). */
+export const CRITERION_ID = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** Mirrors CHECK_BOUND_ARTIFACT_IDS in @outerlayer/session-schema (a test pins them equal): ids that name a check, not a criterion. */
+export const RESERVED_IDS = ["code-review-ran", "acceptance-criteria"];
+const PROOF_IN_TEXT = /\(proof:\s*([a-z]+)\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;
-}
+/** A criteria file the agent must fix before anything is recorded. */
+export class CriteriaFileError extends Error {}
 
-function stripCheckbox(text) {
-  return text.replace(/^\[[ xX]\]\s+/, "");
+/** The proof a criterion declares: the file's `proof` when it is an artifact
+ * kind, else a `(proof: <kind>)` written in its text, else `null`. */
+function proofOf(entry) {
+  if (PROOF_KINDS.includes(entry.proof)) return entry.proof;
+  const written = PROOF_IN_TEXT.exec(entry.text)?.[1]?.toLowerCase();
+  return PROOF_KINDS.includes(written) ? written : null;
 }
 
-/** 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;
-  }
+/** Why the written ids cannot be kept, or `null` when they can. */
+function idProblem(entries) {
+  const ids = entries.map((entry) => entry.id);
+  const missing = ids.filter((id) => typeof id !== "string" || id.trim() === "").length;
+  if (missing === ids.length) return "no criterion carried an id";
+  if (missing > 0) return "only some criteria carried an id";
+  const bad = ids.find((id) => !CRITERION_ID.test(id));
+  if (bad !== undefined) return `the id ${JSON.stringify(bad)} does not fit the id grammar`;
+  const reserved = ids.find((id) => RESERVED_IDS.includes(id));
+  if (reserved !== undefined) return `the id ${JSON.stringify(reserved)} names a check, not a criterion`;
+  const repeated = ids.find((id, n) => ids.indexOf(id) !== n);
+  if (repeated !== undefined) return `the id ${JSON.stringify(repeated)} appears twice`;
   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}}
+ * Turns the agent's criteria file into the list `outerlayer emit criteria`
+ * takes. Throws {@link CriteriaFileError} for a file the agent must fix.
+ * @returns {{criteria: Array<{id:string,text:string,proof:string|null}>, numbered: boolean, numberedBecause?: 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",
-    };
+export function readCriteria(input, item, { drafted = false } = {}) {
+  if (typeof input !== "object" || input === null || !Array.isArray(input.criteria)) {
+    throw new CriteriaFileError('the criteria file must be { "criteria": [ ... ] }');
   }
-  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: [] };
+  const entries = input.criteria.map((entry, n) => {
+    if (typeof entry !== "object" || entry === null || typeof entry.text !== "string" || entry.text.trim() === "") {
+      throw new CriteriaFileError(`criteria[${n}] needs the criterion's text`);
+    }
+    return { id: entry.id, text: entry.text.trim(), proof: entry.proof };
+  });
+  const problem = drafted ? "the build drafted them" : idProblem(entries);
+  const numbered = entries.length > 0 && problem !== null;
+  const criteria = entries.map((entry, n) => ({
+    id: numbered ? `AC-${item}-${String(n + 1).padStart(2, "0")}` : entry.id,
+    text: entry.text,
+    proof: proofOf(entry),
+  }));
+  return numbered ? { criteria, numbered, numberedBecause: problem } : { criteria, numbered };
 }
 
-/** Sorts a failed `emit criteria` into "the item already has a person's list" and any other refusal. */
+/** Sorts a failed `emit criteria` into "the item already has a list" and any other refusal. */
 export function classifyEmitFailure(message) {
   // Only the CLI's replace refusal reads "refused (409):". Other answers that
   // carry a 409, such as a lost race, read "emit failed (409):".
@@ -153,40 +105,39 @@ function readState(path) {
 }
 
 /**
- * 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 }`.
+ * Records the criteria and notes the outcome in the state file. `input` is
+ * the parsed criteria 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);
+export async function recordCriteria({ input, item, drafted = false, reportsDir, statePath, emit }) {
+  const read = readCriteria(input, item, { drafted });
+  const numbering = read.numbered ? { numbered: true, numberedBecause: read.numberedBecause } : { numbered: false };
   let outcome;
-  if (found.shape === "none") {
-    outcome = { source: "none", recorded: false, count: 0, list: [], ...(found.note ? { note: found.note } : {}) };
+  if (read.criteria.length === 0) {
+    outcome = { source: "none", recorded: false, count: 0, list: [] };
   } else {
     mkdirSync(reportsDir, { recursive: true });
     const file = join(reportsDir, "criteria.json");
-    writeFileSync(file, `${JSON.stringify({ criteria: found.criteria }, null, 2)}\n`);
+    const list = drafted ? { criteria: read.criteria, drafted: true } : { criteria: read.criteria };
+    writeFileSync(file, `${JSON.stringify(list, null, 2)}\n`);
     const result = await emit(file);
-    const base = { count: found.criteria.length, list: found.criteria };
+    const source = drafted ? "drafted" : "issue";
+    const base = { count: read.criteria.length, list: read.criteria, ...numbering };
     if (result.ok) {
-      outcome = { source: found.shape === "ids" ? "issue-ids" : "issue-bullets", recorded: true, ...base };
+      outcome = { source, recorded: true, ...base };
     } else if (classifyEmitFailure(result.message) === "item-list-stands") {
-      // No command returns the item's own list, so `list` stays empty; the issue's reading goes under `issueReading`.
+      // No command returns the item's own list, so `list` stays empty; the build's reading goes under `issueReading`.
       outcome = {
         source: "item",
         recorded: false,
-        count: found.criteria.length,
+        count: read.criteria.length,
         list: [],
-        issueReading: found.criteria,
+        issueReading: read.criteria,
+        ...numbering,
         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,
-      };
+      outcome = { source, recorded: false, ...base, refusal: result.message };
     }
   }
   mkdirSync(dirname(statePath), { recursive: true });
@@ -197,12 +148,13 @@ export async function recordCriteria({ body, item, reportsDir, statePath, emit }
 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";
+  const ids = outcome.numbered ? `, numbered AC-<item>-NN because ${outcome.numberedBecause}` : ", with the issue's own ids";
+  if (outcome.source === "none") return "no criteria in the file; none recorded";
+  if (outcome.source === "item") return `the item already has a recorded list; it stands, and the ${n} ${noun} read here were not recorded`;
+  const what = outcome.source === "drafted" ? `drafted ${n} ${noun} from the issue's description` : `read ${n} ${noun} from the issue`;
   return outcome.recorded
-    ? `recorded ${n} ${noun} from ${shape}`
-    : `read ${n} ${noun} from ${shape} but the record was refused: ${outcome.refusal}`;
+    ? `${what} and recorded them${outcome.source === "drafted" ? " as drafted" : ids}`
+    : `${what} but the record was refused: ${outcome.refusal}`;
 }
 
 async function main(argv) {
@@ -211,9 +163,16 @@ async function main(argv) {
     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");
+  const criteriaFile = arg("--criteria-file");
+  if (!item || !/^\d+$/.test(item) || !criteriaFile) {
+    process.stderr.write("usage: record-criteria.mjs --item <number> --criteria-file <path> [--drafted]\n");
+    return 2;
+  }
+  let input;
+  try {
+    input = JSON.parse(readFileSync(criteriaFile, "utf8"));
+  } catch (err) {
+    process.stderr.write(`cannot read the criteria file "${criteriaFile}": ${err.message}\n`);
     return 2;
   }
   const git = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { encoding: "utf8" });
@@ -222,15 +181,22 @@ async function main(argv) {
     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;
+  try {
+    const outcome = await recordCriteria({
+      input,
+      item,
+      drafted: argv.includes("--drafted"),
+      reportsDir: join(gitDir, "build-reports"),
+      statePath: join(gitDir, "build-state.json"),
+      emit: makeEmit(spawnSync, item),
+    });
+    process.stdout.write(`${summarize(outcome)}\n`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof CriteriaFileError)) throw err;
+    process.stderr.write(`${err.message}; fix the criteria file and run again\n`);
+    return 2;
+  }
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exitCode = await 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.

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.