@miroshnik/elves 0.0.0 → 2026.1018.0

package/skills/slot/scripts/slot.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env bun
+/**
+ * slot — a queue for heavy runs on the machine (the slot skill): a command goes when one of SLOTS slots is free, the rest
+ * wait in arrival order and print whom they wait for. Parallel agent sessions ran the full check at once, each runner on
+ * all cores, and the runs hit timeouts (tests/capabilities/slot).
+ *
+ * A slot is a ticket file `<time>-<pid>` in `slots/` of the personal configuration directory: the name sets the order, the
+ * PID tells whether the owner is alive. A dead process, even one killed without cleanup, has its ticket ignored and removed
+ * by the first one to see it: there are no locks to remove by hand. The command gets ELVES_SLOT_CPUS: all slots together
+ * take half of the cores.
+ *
+ * An agent's sandbox doesn't let the configuration be written: the ticket goes to `elves/slots` of the temp directory
+ * (Claude Code's sandbox gives all sessions of the user one TMPDIR), and the queue is read from all places at once — runs
+ * inside and outside the sandbox wait for each other. No place takes the ticket — one warning line and the command runs
+ * without the queue.
+ *
+ * No queue in CI (the machine is given to the run) and inside a slot (ELVES_SLOT): a script that calls another script
+ * through the queue would otherwise wait for itself.
+ *
+ * The flow's former name (#545): a project whose copy `update` hasn't brought yet runs the slot of an earlier release —
+ * it queues in its own place of the temp directory (FORMER_TEMP), exports only the queue variables under the former name
+ * (FORMER_ENV), and its runner configs and `turbo.json` pass those. So the queue is read from the former temp place too,
+ * the queue variables go under both names, and either name marks a nested call.
+ *
+ * A package.json script takes its slot with `--for <shell PID>` (the project's shim `.agents/slot.sh` runs `elves slot
+ * --for $$`): the ticket carries the script's shell, not this process, and the queue variables are printed for the shell
+ * to export — the command runs as a plain command of the script, visible to tools that read package.json (knip).
+ *
+ * Runs under Bun (`bun slot.ts`), only node: APIs. A project without a copy of the flow runs it from its package as
+ * `elves slot` (bin/elves.ts imports `main` and `HELP`): the queue starts only when this file is the entry point.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * `--help`, `-h` as the first argument — the rest go to the command (tests/standards/cli-help): synopsis, what, examples;
+ * `elves slot` prints it under its name.
+ */
+export const HELP = `slot '<command>' [arguments…]
+slot --for <PID>
+
+Runs the command through sh, the arguments appended to its end, as with npm run; waits while two heavy runs are going on
+the machine, then runs with ELVES_SLOT_CPUS — a quarter of the cores. --for — takes a slot for the shell <PID> of a
+package.json script, held until the shell exits, and prints the export of ELVES_SLOT, ELVES_SLOT_CPUS for it — the
+project's shim runs it: ". .agents/slot.sh && <command>". No queue in CI and inside a slot. The exit code is the
+command's; with --for — 0, nothing printed without the queue.
+
+Examples:
+  slot 'vitest run'
+  slot 'bun test' tests/standards
+`;
+
+/** Heavy runs on the machine at once. */
+const SLOTS = 2;
+/** Runner workers per slot: all slots together get half of the cores, the other half is for the human, the app and the agents. */
+const CPUS = Math.max(1, Math.floor(os.availableParallelism() / 2 / SLOTS));
+/** How often a waiting process looks at the queue, ms: a directory of a few files is read in microseconds. */
+const POLL = 250;
+/**
+ * Pause before confirming "I am among the first SLOTS", ms: the ticket time is taken before the file is written, and a
+ * ticket with an earlier time may not have reached the disk yet when the queue was read.
+ */
+const SETTLE = 50;
+/** A waiting process reminds whom it waits for once per this many ms, even if the queue hasn't moved. */
+const REMIND = 60_000;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+/**
+ * The queue variables under the flow's former name, exported next to ours for one transition: runner configs and
+ * `turbo.json` of projects read and pass `AI_DEV_SLOT_CPUS` and `AI_DEV_SLOT` until they are renamed, and the slot of an
+ * earlier release marks a nested call with `AI_DEV_SLOT` only.
+ */
+const FORMER_ENV = { ELVES_SLOT: "AI_DEV_SLOT", ELVES_SLOT_CPUS: "AI_DEV_SLOT_CPUS" } as const;
+/** The temp directory's place of the slot of an earlier release (FORMER_ENV): its tickets are read, ours aren't written there. */
+const FORMER_TEMP = "ai-dev";
+
+interface Ticket {
+  name: string;
+  cwd?: string;
+  cmd?: string;
+  since?: number;
+}
+
+/** An argument for sh: a plain word as is, anything else in single quotes. */
+const quote = (s: string) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`);
+
+/** Whether the process is alive: signal 0 only checks; EPERM — alive, but someone else's. */
+function alive(pid: number) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Where tickets live, in the order a ticket is written: the personal configuration, then the temp directory — an agent's
+ * sandbox doesn't let the configuration be written, while its TMPDIR is shared by the sandbox's sessions; Claude Code
+ * passes its sandbox's temp directory as CLAUDE_TMPDIR outside the sandbox too, so runs outside wait for runs inside.
+ * The personal configuration directory — the same expression in all scripts (tests/standards/config-dir).
+ */
+function places() {
+  const config = process.env.ELVES_CONFIG_DIR || process.env.AI_DEV_CONFIG_DIR || [path.join(os.homedir(), ".config", "elves"), path.join(os.homedir(), ".config", "ai-dev")].find((d) => existsSync(d)) || path.join(os.homedir(), ".config", "elves");
+  const temps = [os.tmpdir(), process.env.CLAUDE_TMPDIR].filter((d): d is string => !!d);
+  return [...new Set([config, ...temps.map((d) => path.join(d, "elves"))].map((d) => path.join(path.resolve(d), "slots")))];
+}
+
+/** Places the queue is read from: ours and the temp places of the slot of an earlier release (FORMER_TEMP). */
+function readPlaces(dirs: string[]) {
+  const former = [os.tmpdir(), process.env.CLAUDE_TMPDIR].filter((d): d is string => !!d).map((d) => path.join(path.resolve(d), FORMER_TEMP, "slots"));
+  return [...new Set([...dirs, ...former])];
+}
+
+/** Live tickets of all places in arrival order; tickets of dead processes are removed where the directory can be written. */
+function queue(dirs: string[]): Ticket[] {
+  const out: Ticket[] = [];
+  for (const dir of dirs) {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      continue; // no one has queued here yet
+    }
+    for (const name of names) {
+      const pid = Number(/^\d+-(\d+)$/.exec(name)?.[1]);
+      if (!pid) continue;
+      if (!alive(pid)) {
+        try {
+          rmSync(path.join(dir, name), { force: true });
+        } catch {
+          /* a sandbox can't write here: the ticket just doesn't count, a run outside the sandbox removes it */
+        }
+        continue;
+      }
+      let info = {};
+      try {
+        info = JSON.parse(readFileSync(path.join(dir, name), "utf8"));
+      } catch {
+        /* the ticket was just created and is still empty */
+      }
+      out.push({ ...info, name });
+    }
+  }
+  return out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+const duration = (ms: number) => (ms < 60_000 ? `${Math.round(ms / 1000)} s` : `${Math.floor(ms / 60_000)} min ${Math.round((ms % 60_000) / 1000)} s`);
+
+/** A path under the home directory — from `~`. */
+function tilde(p: string) {
+  const home = os.homedir();
+  return p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p;
+}
+
+/** Who holds the slot: the directory, the command and how long it has been running. */
+function holder(t: Ticket) {
+  const cwd = t.cwd ? tilde(t.cwd) : "?";
+  const cmd = (t.cmd ?? "?").replace(/\s+/g, " ");
+  return `${cwd}: ${cmd.length > 80 ? cmd.slice(0, 79) + "…" : cmd}${t.since ? ` (${duration(Date.now() - t.since)})` : ""}`;
+}
+
+/**
+ * The command of the package.json script that sourced the shim, for whoever waits for its slot: npm and bun give the
+ * script's text in npm_lifecycle_script — without the shim's prefix (`. .agents/slot.sh &&`, a copy's slot.sh of an
+ * earlier install) it is the command; otherwise the script's name.
+ */
+function scriptCommand() {
+  const text = process.env.npm_lifecycle_script;
+  return text ? text.replace(/^\.\s+\S*slot\.sh\s*&&\s*/, "") : process.env.npm_lifecycle_event;
+}
+
+/** The command through sh with the environment on top of our own; signals go to it. Exit code — its code, killed by a signal — 128 + number. */
+function run(command: string, env: Record<string, string>) {
+  return new Promise<number>((resolve) => {
+    const child = spawn(command, { shell: true, stdio: "inherit", env: { ...process.env, ...env } });
+    for (const s of SIGNALS) process.on(s, () => child.kill(s));
+    child.on("error", (e) => {
+      process.stderr.write(`slot: ${e.message}\n`);
+      resolve(127);
+    });
+    child.on("exit", (code, signal) => resolve(code ?? 128 + (signal ? os.constants.signals[signal] : 0)));
+  });
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [first, ...rest] = argv;
+  if (first === "-h" || first === "--help") return process.stdout.write(HELP), 0;
+  if (!first) return process.stderr.write(HELP), 2;
+  // --for: the slot is the shell's — it holds the ticket, gets the variables and runs the command itself
+  const shell = first === "--for" ? Number(rest[0]) : 0;
+  if (first === "--for" && !(rest.length === 1 && Number.isInteger(shell) && shell > 0 && alive(shell))) {
+    return process.stderr.write(`slot: --for takes the PID of a running shell, got ${rest.join(" ") || "nothing"}\n${HELP}`), 2;
+  }
+  const command = [first, ...rest.map(quote)].join(" ");
+  // without the queue the command goes at once; a script's shell has nothing to export
+  const free = () => (shell ? 0 : run(command, {}));
+  const ci = process.env.CI && !/^(0|false)$/i.test(process.env.CI);
+  if (ci || process.env.ELVES_SLOT || process.env[FORMER_ENV.ELVES_SLOT]) return free();
+
+  const dirs = places();
+  const read = readPlaces(dirs);
+  const name = `${String(Date.now()).padStart(15, "0")}-${shell || process.pid}`;
+  let file = "";
+  const enqueue = () => {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ cwd: process.cwd(), cmd: shell ? scriptCommand() : command, since: Date.now() }));
+  };
+  const refused: string[] = [];
+  for (const dir of dirs) {
+    file = path.join(dir, name);
+    try {
+      enqueue();
+      break;
+    } catch (e) {
+      refused.push(`${tilde(dir)} (${(e as NodeJS.ErrnoException).code ?? (e as Error).message})`);
+      file = "";
+    }
+  }
+  if (!file) {
+    process.stderr.write(`slot: running without the queue — no place takes the ticket: ${refused.join(", ")}\n`);
+    return free();
+  }
+  // the shell's ticket stays when we exit with its slot: the queue removes it when the shell is gone
+  let held = false;
+  const drop = () => {
+    if (!held) rmSync(file, { force: true });
+  };
+  process.on("exit", drop);
+  // while waiting, a signal removes the ticket and exits; in a slot, signals go to the command (run)
+  const quit = (s: NodeJS.Signals) => (drop(), process.exit(128 + os.constants.signals[s]));
+  for (const s of SIGNALS) process.on(s, quit);
+
+  const t0 = Date.now();
+  let confirmed = false;
+  let told = "";
+  let toldAt = 0;
+  for (;;) {
+    // the shell is gone while waiting (killed) — its ticket would be put back forever
+    if (shell && !alive(shell)) return 1;
+    let q = queue(read);
+    let i = q.findIndex((t) => t.name === name);
+    if (i < 0) {
+      enqueue(); // the ticket was removed from outside (the directory cleaned by hand) — the same place in the queue
+      q = queue(read);
+      i = q.findIndex((t) => t.name === name);
+    }
+    if (i >= 0 && i < SLOTS) {
+      if (confirmed) break;
+      confirmed = true;
+      await new Promise((r) => setTimeout(r, SETTLE));
+      continue;
+    }
+    confirmed = false;
+    const holders = q.slice(0, SLOTS);
+    const who = holders.map((t) => t.name).join(" ");
+    if (who !== told || Date.now() - toldAt >= REMIND) {
+      const ahead = i - SLOTS;
+      process.stderr.write(`slot: waiting for the machine queue — running ${holders.map(holder).join("; ")}${ahead ? `; ${ahead} more ahead` : ""}\n`);
+      [told, toldAt] = [who, Date.now()];
+    }
+    await new Promise((r) => setTimeout(r, POLL));
+  }
+  for (const s of SIGNALS) process.off(s, quit);
+  if (told) process.stderr.write(`slot: waited ${duration(Date.now() - t0)}\n`);
+  const own = { ELVES_SLOT: name, ELVES_SLOT_CPUS: String(CPUS) };
+  const env = { ...own, ...Object.fromEntries(Object.entries(own).map(([k, v]) => [FORMER_ENV[k as keyof typeof own], v])) };
+  if (shell) {
+    held = true;
+    process.stdout.write(`export ${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(" ")}\n`);
+    return 0;
+  }
+  const code = await run(command, env);
+  drop();
+  return code;
+}
+
+if (import.meta.main) process.exit(await main(process.argv.slice(2)));

package/skills/spec/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: spec
+description: Specification from tests — the spec canon (canon.md), deterministic scripts and a checks harness. spec-doc builds docs/spec from runner reports (Vitest/Jest, Playwright, bun JUnit) along tests/capabilities, tests/architecture and tests/standards, with prose from JSDoc; spec-diff prints removed, changed and added test names for the PR body; spec-publish publishes docs/spec to the spec branch after a merge, spec-run finds the green run for it; spec-shard splits CI shards by the last green run's durations; spec-claims checks entry points against the call log; spec-break proves a check can fail; spec-exceptions moves exceptions.ts into exceptions/; harness.ts — mechanical checks (registry + invariant). When — before creating a PR; in CI on a PR and after a merge; reading a project's spec; wiring spec into a project's CI; a convention must hold for every item, not an example; proving a test catches a breakage; asked what the system does or which requirements a PR removes — even if "specification" wasn't said.
+allowed-tools: Bash(bun *skills/spec/scripts/spec-doc.ts *) Bash(bun *skills/spec/scripts/spec-diff.ts *) Bash(bun run spec:*) Bash(bun *skills/spec/scripts/spec-claims.ts *) Bash(bun *skills/spec/scripts/spec-break.ts *) Bash(bun *skills/spec/scripts/spec-exceptions.ts *) Bash(pnpm spec:*) Bash(bunx vitest run *) Bash(git status *) Bash(git diff *)
+---
+
+# spec — documentation from test names, spec diff in the PR
+
+The "Specification — decisions" rule is `canon.md` next to this file (the spec
+canon moved out of the `AGENTS.md` core; read it when you write or migrate a
+test, add a check, an exception, a standard): a decision exists while a
+mechanism checks it — a test, a lint rule, a check over the architecture
+model; each is wrapped in a runner test. So the documentation is the `tests/`
+tree and the test names, and the diff of tests in a PR is the spec diff. The
+scripts in `scripts/` do this deterministically, without a model and without
+per-repository configuration:
+
+- `spec-doc.ts` — runner reports and test JSDoc → `docs/spec/` (or a single
+  document to stdout);
+- `spec-diff.ts` — test names on the base branch and in HEAD → three lists for
+  the PR body: removed, changed, added;
+- `spec-publish.ts` — the built `docs/spec` → the `spec` branch (CI after a
+  merge: a run on `main` or the PR run's artifact); `main` has no
+  documentation;
+- `spec-run.ts` — for publishing on a PR merge: the green run that checked
+  exactly the tree of the merge commit; none — publishing is skipped;
+  `--artifact` — the last green run's reports for `spec-shard`, one for all
+  shards of a run (green by its start);
+- `spec-shard.ts` — a CI shard's test files by the last green run's
+  durations, not by the count of tests: greedily, the longest into the
+  lightest shard; the runner gets them as filters instead of `--shard`
+  (`ci.md`, "Shards by durations");
+- `spec-claims.ts` — after a run: every entry point is called by a capability
+  test (the harness's `journal`, `resetJournal` at the start of the run),
+  registry ids don't repeat, journal ids come from the registry; the JUnit
+  report goes to `spec-doc`;
+- `spec-break.ts` — check by breaking: edit the code, run the test, always
+  revert (even after an interruption); ✅ failed / ❌ didn't fail for each
+  breakage;
+- `spec-exceptions.ts` — moves the decision folders' `exceptions.ts` into an
+  `exceptions/` directory, one file per exception (section "spec-exceptions");
+- `harness.ts` — a library for the project's tests: a mechanical check
+  registers ordinary runner tests and gets into the spec (section "Checks").
+
+Running: `bun --no-env-file <skill dir>/scripts/spec-doc.ts …` — TypeScript
+without a build and without dependencies. Syntax, flags and exit codes — each
+script's `--help`; what a script does in detail and why — `reference.md` next
+to this file. The skill directory is the one holding this file
+(`${CLAUDE_SKILL_DIR}` in Claude Code, `~/.claude/skills/spec`,
+`~/.agents/skills/spec` or an Elves clone). The repository root is `git
+toplevel` (or `--root DIR`); the tree is `tests/` at the root. In a repository wired up per the "Wiring into a
+repository" section — its `spec:doc` and `spec:diff`, not the scripts from the
+skill directory: the project's package version is pinned for CI.
+
+## What to run when
+
+| Moment | Action |
+|---|---|
+| Before a PR | 1. a test run with a JSON report (don't run e2e: for the names `playwright test --list --reporter=json > .spec-playwright.json` is enough); 2. `spec-doc --strict` with both reports — the tree and the main files are in order (`docs/spec` is in `.gitignore`, not committed); 3. `spec-diff --scenarios <task body>` → the `## Spec (tests)` section (in the project language) with the scenario check, into the PR body |
+| In CI on a PR | shards — `spec-shard` (`ci.md`); run → `spec-doc --strict` (section "spec-doc"); `spec-diff` into the summary |
+| In CI after a merge | a run on `main` → `spec-doc` → `spec-publish`; without CI on `main` — `docs/spec` from the PR run's artifact and `spec-publish --source <merge SHA>` (`ci.md`). The `spec` branch = the built `docs/spec`, the script verifies it after the push |
+| Read a project's spec | `git fetch origin spec && git show origin/spec:README.md` (pages — `capabilities/<name>.md`…) or the tests themselves |
+| Asked for documentation, "what does the system do" | `spec-doc <report> --stdout` — one document, files aren't touched |
+| Asked which requirements a PR removed | `spec-diff` — the «Removed» list comes first |
+| A project moves to a test spec | section "Wiring into a repository": installing the flow, scripts under Bun, workflow; migrating the old spec's requirements — `migration.md` (outcomes, removal categories, "the spec fell behind the code") |
+| A convention for all items (mutations, routes, files) | `invariant` in `tests/standards/<name>/<name>.test.ts` — section "Checks" |
+| Prove that a check can fail (migrating an old spec, a "covered" review) | `spec-break` — a breakage aimed at the check, one per run |
+| After running all tests and shards | `spec-claims` — every entry point is called by a capability test; its report goes to `spec-doc` together with the runner reports |
+| The harness failed «exceptions are one file per element in exceptions/, not exceptions.ts» | `spec-exceptions` — section "spec-exceptions" |
+| spec-doc warns that `names.exceptions` «isn't read — names aren't exceptions any more, delete it» | delete that directory or file (#447) |
+
+## Reports for spec-doc
+
+The format is detected from the content; several reports can be passed at
+once (Vitest + Playwright + bun test), identical tests are merged.
+
+| Runner | Command |
+|---|---|
+| Vitest (and Jest — same format) | `vitest run --reporter=default --reporter=json --outputFile.json=.spec-report.json` |
+| `bun test` | `bun test --reporter=junit --reporter-outfile=.spec-report.xml` — JUnit with nested `testsuite` per describe |
+| Playwright | `PLAYWRIGHT_JSON_OUTPUT_NAME=.spec-playwright.json playwright test --reporter=json` |
+| Playwright without a run (before a PR) | `playwright test --list --reporter=json > .spec-playwright.json` — the tree and names without browsers, tests show as skipped: for `spec-doc --strict` and `spec-diff`, not for publishing |
+
+Reports are temporary files, in `.gitignore`; a report from CI with someone
+else's absolute paths works. The runner itself merges shards (blob reports →
+one JSON, section "Wiring into a repository"); don't pass shard reports
+separately (`reference.md`, "Report formats").
+
+## spec-doc
+
+A page per decision folder is a story in three layers: the `<folder>.md`
+description (**why**), `describe` sections with prose from their JSDoc
+(**what it can do**), the section's tests in a collapsed block (**what checks
+it**); plus the `README.md` index and `architecture.md` from the model
+`tests/architecture/model.ts`. `--strict` — exit code 1 when:
+
+- a test is outside `tests/capabilities/<name>`, `tests/architecture/<name>`
+  and `tests/standards/<name>` (in `src/`, in `tests/unit/`, a file directly in
+  `tests/capabilities/`) — «Outside the tree», a signal to move it;
+- a folder has no main file `tests/<kind>/<name>/<name>.*` (in a monorepo also
+  `tests/<kind>/<name>/<package>/<name>.*`): its `describe` order is the order
+  of the story;
+- a folder has no description `tests/<kind>/<name>/<name>.md`;
+- a test file has a JSDoc header (its text belongs in `<folder>.md` or in
+  `//`), or a standard's main file is still `rule.*` (rename it to `<name>.*`);
+- a `<!-- spec: c4-context -->` marker (`c4-container`, `c4-component`,
+  `c4-modules`) is unknown or has no model; the model doesn't load — exit
+  code 2.
+
+Names of `describe` and `it` are statements in the project language
+(`language` in `.agents/elves.json`): an identifier, a function or file name,
+a path — a warning line, no exit code.
+
+**Prose:** `<folder>.md` — why, the reason and the rejected alternatives (its
+first paragraph is the index description); JSDoc `/** … */` before `describe`
+or `it` — one to three sentences where the name isn't enough; `//` doesn't go
+into the documentation. Each file, the order, names, an example —
+`reference.md`, "spec-doc output" and `reference.md`, "Writing prose".
+
+## spec-diff
+
+The ready `## Spec (tests)` section for the PR body: test names compared
+**statically** — the `tests/` files at two revisions via `git show`, without a
+run. The removed come first: a removed test is a removed requirement. Then
+«Changed» (renames), «Added» and, only if they changed, «Architecture model»,
+«Exceptions», «Harness checks».
+
+- The base is the merge-base of `--base` (default `origin/main`) and HEAD;
+  before running — `git fetch origin`, otherwise `origin/main` is stale.
+  `--worktree` — the working tree instead of HEAD, to look before a commit.
+- `--scenarios` — the task body (`gh issue view N --json body --jq .body | …
+  --scenarios -`): its `## Scenarios` section against the added and changed
+  tests — «### Task scenarios»; a scenario that became a test is named the
+  same as the test, ❌ — a scenario without a test.
+- Tests that the harness generates are only in the report: `--report <report>`
+  (repeatable) — the head from the PR run's report, the base from `tests.json`
+  of the `spec` branch.
+- More tests than `--limit` (100) — a per-folder summary; `--full` — the full
+  list.
+- The section is inserted into the PR body as a whole (after `Closes #N`); on
+  new commits with tests — regenerate it and replace it.
+
+Matching, renames, a move into the tree, an example — `reference.md`,
+"spec-diff output".
+
+## spec-publish, spec-run — after a merge
+
+In CI (`ci.md`). `spec-publish` puts the built `docs/spec` at the root of the
+`spec` branch, `Source: <SHA>` in the commit, without touching the working
+copy, and verifies the remote branch after the push; `--check` — comparison
+only. `spec-run --tree <hash>` — without CI on `main`: the green run that
+checked the merge commit's tree; stdout empty — publishing is skipped. Details
+— `reference.md`, "spec-publish" and `reference.md`, "spec-run".
+
+## spec-break
+
+A decision's check must be able to fail. The agent picks the breakage for one
+check (this is not mutation testing): `--find` occurs in the file exactly
+once; a plan of several — each a separate run. A baseline run goes first: red
+even without a breakage — exit code 2. After an interruption without a revert
+— the next run or `--restore`. Details — `reference.md`, "spec-break".
+
+## spec-exceptions
+
+A decision's exceptions are the folder's `exceptions/` directory, one file per
+exception (`<item>.json`: `{ item, rule?, issue, reason }`), not an array in
+`exceptions.ts`. `spec-exceptions` moves each `exceptions.ts` of a decision
+folder there and rewrites the imports (`exceptionsIn()`) and the paths in
+`package.json` and workflows; a `!` line — fix by hand. A repeated run changes
+nothing. Details — `reference.md`, "spec-exceptions".
+
+## Checks — `harness.ts`, `architecture.ts`, `spec-claims.ts`
+
+A mechanical check is runner tests (or a report in the runner's format): they
+are in the report, and so in `docs/spec` and in `spec-diff`. Import — from the
+project's package (`@miroshnik/elves/spec/harness`, `…/spec/architecture`,
+`…/spec/eslint-config`), the runner doesn't matter — `it` passes the test in. Which check for what and how to wire
+each one — `checks.md` next to this file:
+
+- a convention on every item of a registry from the code — `invariant`
+  (`standards/<name>/`);
+- a lint rule — `examples`, `eslintLinter`, the folder's `eslint.ts` fragment
+  collected by `collectEslint`;
+- out of scope and exceptions — `fileOf`, marks `spec-outside(<decision>)` /
+  `spec-exception(<decision>) #N`, `exceptionsIn()`, `lintExceptions`;
+- the architecture model (modules, external systems, containers, workspace
+  packages) — `architecture/model.ts`, `architecture`, `boundariesConfig`,
+  `networkGuard`, `cspConnectSrc`, `deployUnits`, `workspacePackages`;
+- interaction order in a scenario — `trace`, `sequence`;
+- every entry point is called by a capability test — `journal` +
+  `spec-claims` (`standards/entry-points/`);
+- no code without a consumer — `deadCode` (knip);
+- environment variables — `envVars`, `dotenvNames`, `configGet`.
+
+## Wiring into a repository
+
+The scripts and modules come from the project's package — `@miroshnik/elves`
+in `devDependencies`, committed with its version: the scripts run as
+`bun --no-env-file node_modules/.bin/elves spec-…`, a Node project included
+(in CI — `oven-sh/setup-bun@v2`); on Yarn 2+, which runs the `.ts` bin by
+Node and has no `node_modules` with PnP, —
+`bunx @miroshnik/elves@"$(jq -r '.devDependencies["@miroshnik/elves"]' package.json)" spec-…`
+(`install` writes this form there); the modules the project's tests and config import
+(`@miroshnik/elves/spec/harness`, `…/spec/architecture`,
+`…/spec/eslint-config`) load under the project's own runner on Node — from
+the package's build. Each step with its details — `reference.md`,
+"Wiring into a repository"; an old spec's requirements — `migration.md`.
+
+1. **Install** at the project root, the result into a commit:
+   `bunx @miroshnik/elves install` — the package version, the manifest, the
+   shim and the `AGENTS.md` block; update — `update` in the current task's
+   branch, a few lines.
+2. **Scripts** in `package.json` and CI — the package's `elves` under
+   `bun --no-env-file`: the bare bin would load the project's env files;
+   reports — those the project has:
+   ```json
+   "spec:doc": "bun --no-env-file node_modules/.bin/elves spec-doc .spec-report.json .spec-playwright.json .spec-claims.xml --strict",
+   "spec:diff": "bun --no-env-file node_modules/.bin/elves spec-diff",
+   "spec:publish": "bun --no-env-file node_modules/.bin/elves spec-publish",
+   "spec:claims": "bun --no-env-file node_modules/.bin/elves spec-claims --entries tests/standards/entry-points/entries.ts"
+   ```
+   Standards and architecture run once — the `test:spec` script, a fast CI job
+   of its own; `test` excludes them, e2e doesn't run them (`checks.md`):
+   ```json
+   "test": "vitest run --exclude 'tests/standards/**' --exclude 'tests/architecture/**'",
+   "test:spec": "vitest run tests/standards tests/architecture"
+   ```
+   In `.gitignore`: `docs/spec/`, `.spec-*.json`, `.spec-*.xml`,
+   `.spec-meta/`, `.spec-journal/`, `vitest-blob/`, `blob-report/`,
+   `playwright-blob/`.
+3. **`docs/spec/` isn't committed to `main`** — CI publishes it to the `spec`
+   branch.
+4. **CI** — a shard's files from `spec-shard` by the last green run's
+   durations, shards write blob reports, a `spec` job merges them and builds
+   `docs/spec` with `--strict`, only `spec-publish` has a write token,
+   `spec-diff` is a light job of its own: the workflow fragment — `ci.md`.
+5. **Monorepo** — a decision's tests in package subfolders
+   `tests/<kind>/<name>/<package>/`, each package with its own runner project;
+   run from the repository root.
+
+## Limitations to know about
+
+A test's name is a string known without a run (a literal, a template without
+substitutions): otherwise it isn't in the `spec-diff` lists — a line in
+stderr. Vitest and `bun test` reports don't contain the skip reason — keep it
+in the test name or in a comment next to it. On `main` everything must be ✅
+or ⏭️ with a reason. The rest — `reference.md`, "Limitations to know about".