@outerlayer/cli 0.1.1 → 0.4.0

package/dist/work-open-pr-cmd-4SSQZMYG.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { runWorkPr, WorkPrCommandError } from './chunk-DVYHCMB2.js';
+import { resolveCredentials } from './chunk-5DLBAXY5.js';
+import './chunk-BFESLKPP.js';
+import './chunk-6Y63SXFO.js';
+import './chunk-G7FSV7JX.js';
+import './chunk-WZBHBH3J.js';
+import { defaultFetch } from './chunk-BCLJSQCV.js';
+import './chunk-BOLTI6LR.js';
+import './chunk-EABW6AJQ.js';
+import './chunk-M5POMKKW.js';
+import './chunk-ZM2IMMYN.js';
+import './chunk-BJ3KTMDH.js';
+import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+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 {
+};
+function spawnGh(args, cwd) {
+  const result = spawnSync("gh", args, { cwd, encoding: "utf8" });
+  if (result.error !== void 0) {
+    return { status: 127, stdout: "", stderr: `could not run gh: ${result.error.message}` };
+  }
+  return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+function firstLine(text) {
+  return text.trim().split("\n")[0] ?? "";
+}
+function readBody(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    throw new WorkOpenPrCommandError(`cannot read --body-file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function openThroughGateway(creds, workItem, title, body, fetchImpl) {
+  const endpoint = new URL(`/v1/work-items/${encodeURIComponent(workItem)}/pull-request`, creds.url).toString();
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "PUT",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${creds.apiKey}`,
+        "x-outerlayer-app-id": creds.appId
+      },
+      body: JSON.stringify({ title, body })
+    });
+  } catch (err) {
+    throw new WorkOpenPrCommandError(`network error reaching ${endpoint}: ${String(err)}`);
+  }
+  let json;
+  try {
+    json = await response.json();
+  } catch {
+    throw new WorkOpenPrCommandError(
+      `${endpoint} answered ${response.status} with a body that is not JSON \u2014 the request may not have reached the gateway`
+    );
+  }
+  if (!response.ok || !json.data) {
+    if (response.status === 401) {
+      throw new WorkOpenPrCommandError(
+        json.error?.message ?? "not authorized \u2014 the item key is unknown, expired, or its claim has ended."
+      );
+    }
+    throw new WorkOpenPrCommandError(json.error?.message ?? `request failed (${response.status})`);
+  }
+  return json.data;
+}
+async function openWithGh(opts, title, bodyFile, cwd) {
+  const runGh = opts.runGh ?? spawnGh;
+  const viewed = runGh(["pr", "view", "--json", "number"], cwd);
+  let existing;
+  if (viewed.status === 0) {
+    try {
+      const parsed = JSON.parse(viewed.stdout);
+      if (typeof parsed.number === "number") existing = parsed.number;
+    } catch {
+    }
+  }
+  const written = existing === void 0 ? runGh(["pr", "create", "--title", title, "--body-file", bodyFile], cwd) : runGh(["pr", "edit", String(existing), "--title", title, "--body-file", bodyFile], cwd);
+  if (written.status !== 0) {
+    const verb = existing === void 0 ? "create" : "edit";
+    throw new WorkOpenPrCommandError(`gh pr ${verb} failed: ${firstLine(written.stderr) || `exit ${written.status}`}`);
+  }
+  const urlMatch = /https:\/\/\S+\/pull\/(\d+)/.exec(written.stdout);
+  const number = existing ?? (urlMatch ? Number(urlMatch[1]) : void 0);
+  if (number === void 0) {
+    throw new WorkOpenPrCommandError("gh pr create printed no pull request URL, so there is no pull request to declare");
+  }
+  let declared;
+  try {
+    declared = await runWorkPr({
+      number,
+      repo: opts.repo,
+      sessionId: opts.sessionId,
+      cwd,
+      home: opts.home,
+      env: opts.env,
+      url: opts.url,
+      apiKey: opts.apiKey,
+      appId: opts.appId,
+      fetchImpl: opts.fetchImpl,
+      quiet: true
+    });
+  } catch (err) {
+    if (err instanceof WorkPrCommandError) {
+      throw new WorkOpenPrCommandError(
+        `the pull request is ${existing === void 0 ? "open" : "edited"} (#${number}) but declaring it on the item failed: ${err.message}`
+      );
+    }
+    throw err;
+  }
+  const repository = declared.data.repository;
+  return {
+    repository,
+    number,
+    url: urlMatch ? urlMatch[0] : `https://${repository.startsWith("github.com/") ? repository : `github.com/${repository}`}/pull/${number}`,
+    created: existing === void 0
+  };
+}
+async function runWorkOpenPr(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  if (opts.title === void 0 || opts.title.trim() === "") {
+    throw new WorkOpenPrCommandError("pass --title");
+  }
+  if (opts.bodyFile === void 0 || opts.bodyFile === "") {
+    throw new WorkOpenPrCommandError("pass --body-file <path>");
+  }
+  const body = readBody(opts.bodyFile);
+  const creds = resolveCredentials({ url: opts.url, apiKey: opts.apiKey, appId: opts.appId, home: opts.home ?? homeFromEnv(env), env });
+  let data;
+  if (creds.apiKey.startsWith(ITEM_KEY_PREFIX)) {
+    const workItem = env.OUTERLAYER_WORK;
+    if (workItem === void 0 || workItem === "") {
+      throw new WorkOpenPrCommandError("an item key names its work item through OUTERLAYER_WORK, which is not set");
+    }
+    data = await openThroughGateway(creds, workItem, opts.title, body, opts.fetchImpl ?? defaultFetch);
+  } 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}`;
+  if (!opts.quiet) process.stdout.write(output + "\n");
+  return { data, output };
+}
+
+export { WorkOpenPrCommandError, runWorkOpenPr };

package/dist/work-pr-cmd-6AN6RRQJ.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+export { WorkPrCommandError, runWorkPr } from './chunk-DVYHCMB2.js';
+import './chunk-BFESLKPP.js';
+import './chunk-G7FSV7JX.js';
+import './chunk-WZBHBH3J.js';
+import './chunk-BCLJSQCV.js';
+import './chunk-BOLTI6LR.js';
+import './chunk-EABW6AJQ.js';
+import './chunk-M5POMKKW.js';
+import './chunk-ZM2IMMYN.js';
+import './chunk-BJ3KTMDH.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outerlayer/cli",
-  "version": "0.1.1",
-  "description": "OuterLayer CLI: init/doctor (hooks + daemon onboarding), watch, scan, and eval (validate/mine/qualify/report — execution-verified evals from your own PRs)",
+  "version": "0.4.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.",
   "repository": {
@@ -26,6 +26,7 @@
   "files": [
     "dist",
     "!dist/**/*.map",
+    "skill-pack",
     "LICENSE"
   ],
   "publishConfig": {
@@ -38,21 +39,30 @@
     "test:mutate": "stryker run",
     "typecheck": "tsc --noEmit",
     "bench:hook": "node scripts/bench-hook.mjs",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:wsl2": "vitest run --config vitest.e2e-wsl2.config.ts",
+    "test:e2e:macos": "vitest run --config vitest.e2e-macos.config.ts"
   },
   "devDependencies": {
     "@outerlayer/capture": "0.1.0",
     "@outerlayer/context-format": "0.1.0",
+    "@outerlayer/runner-signature": "0.1.0",
     "@outerlayer/session-schema": "0.1.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "^22.20.1",
     "commander": "^15.0.0",
+    "http-message-sig": "0.3.0",
+    "structured-headers": "2.0.3",
     "tsup": "^8.5.0",
     "typescript": "^5.5.3",
     "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=22"
+  },
+  "dependencies": {
+    "@devcontainers/cli": "0.89.0"
   }
 }

package/skill-pack/maintained/amend/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: amend
+description: >
+  Answer the review threads waiting on an agent on an open pull request: read each
+  thread a person handed to an agent, fix what it says on the pull request's branch,
+  reply on the thread with a replacement artifact or a sentence, and push. Use when a
+  work item has threads waiting on an agent, or when asked to "answer the review" or
+  "fix what the reviewer failed". Invoke with /amend.
+---
+
+Answer every thread waiting on an agent on one work item's pull request, then
+stop. A work item has one general thread and one thread per acceptance
+criterion. A person's fail, or a plain comment from a person, leaves a thread
+waiting on an agent. The person's newest comment says what they want. This
+skill never records a verdict. Only a person passes or fails a thread. A
+session can only reply.
+
+A session never records a pass or fail on an artifact.
+
+The work item is `OUTERLAYER_WORK`, the work item's number. Check out the pull
+request's branch first if the working tree is not already on it.
+
+## Arguments
+
+- `--unattended`: no person is watching. Never ask a question. Anything that
+  needs a person becomes a hand-off (step 5), never a stop that leaves a thread
+  silently waiting on an agent.
+
+## Steps
+
+1. **Read the threads.**
+   `outerlayer work threads --item "$OUTERLAYER_WORK" --json` prints
+   `{ "general": <thread>, "criteria": [<thread>, ...] }`. Each thread carries
+   `criterion` (null for the general thread), `waitingOn` (`agent`, `person` or
+   null), `verdict`, `proof` and `comments`. Each comment carries `author`
+   (`kind` is `person` or `agent`), `body`, `action` and `artifact`. Keep the
+   threads whose `waitingOn` is `agent`. If none is, say so and stop: there is
+   nothing to answer. Then read `outerlayer work status --item "$OUTERLAYER_WORK" --json`
+   for the pull request in `pullRequests` (`repository`, `prNumber`).
+2. **Re-orient.** Read the issue the item names and the pull request, including
+   its evidence comment, through the team's tracker tool or the git host. The
+   issue body is the spec. Find each thread's criterion there. Read every
+   person's comment since the last agent comment on the thread. Read them
+   literally: they are the reviewer's instruction.
+3. **Decide each thread.** For each waiting thread, pick one:
+   - **Fix it.** The comment names something the change got wrong or did not
+     show. Change the code, tests, docs or evidence so the criterion is met as
+     written.
+   - **The spec is wrong.** The comment shows the criterion cannot be met as
+     written, for example because it names a path a repository rule forbids. A
+     session never rewrites a criterion on its own. Hand it off (step 5), naming
+     the exact wording change the owner should make.
+   - **Cannot tell.** The comment is ambiguous. Hand it off, quoting it and
+     saying what you would need to know.
+4. **Fix, prove, reply.** For each thread you fix:
+   - Make the change on the pull request's branch. Keep it to what the comment
+     asks. Do not refactor around it.
+   - Run the tests that cover the criterion, then the repository's full
+     pre-push checks through a normal `git push`. Never bypass a hook. If the
+     git host drops the connection during a long gate, push again with
+     `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=20 -o ServerAliveCountMax=60"`.
+   - **When the thread asks for new proof** (a criterion thread whose proof the
+     person failed), capture it after the fixed state exists, in the form the
+     criterion declares (`proof: screenshot` and so on) or the form of the
+     current proof. Emit it bound to that criterion, without `--replaces`.
+     Attaching it on the thread supersedes the old proof.
+     `outerlayer emit artifact <file> --caption "<what it shows>" --for <criterion>`.
+     Note the id it prints. Run `outerlayer sync` so the artifact reaches the
+     server. The attach looks it up there and refuses an artifact it cannot
+     find. Then reply:
+     `outerlayer work comment --item "$OUTERLAYER_WORK" --criterion <criterion> --body "<what changed>" --artifact <uuid> --attach`.
+     A replacement whose bytes match the current proof is flagged `unchanged`
+     and keeps the turn where the person's comment left it, so the thread
+     still waits on you.
+   - **Otherwise** (the general thread, or a fix that needs no new proof),
+     reply with a sentence naming what changed and the commit:
+     `outerlayer work comment --item "$OUTERLAYER_WORK" [--criterion <criterion>] --body "<what changed>" --ready`.
+     Omit `--criterion` on the general thread.
+5. **Hand off what you cannot fix.** Reply on the thread with `--ready` and a
+   body of one sentence of fact, then the decision a person must make. For a
+   spec problem, quote the criterion and give the replacement wording.
+   `--ready` hands the thread back to a person.
+6. **Check nothing is left waiting.** Read the threads again. No thread you
+   started with may still be waiting on an agent. If one is, the reply did not
+   land or was flagged `unchanged`. Find out why and fix it, or report it.
+7. **Report.** Comment once on the pull request: one line per thread, naming the
+   criterion (or the general thread) and saying fixed (with the replacement) or
+   handed off (with the reason). Plain language. No session labels, no raw
+   command output.
+
+## Rules
+
+- **Answer only threads waiting on an agent.** A thread waiting on a person, or
+  on no one, is not yours to reply on.
+- **One thread, one proof.** Never attach an artifact that does not prove that
+  thread's criterion. The attach refuses an artifact bound to a different
+  criterion.
+- **A person decides.** Never pass `--pass` or `--fail`, never mark a check as
+  a person, and never edit the issue's criteria.
+- **Stay on the branch.** Push to the pull request's own branch. Never open a
+  second pull request, and never force-push over someone else's commits.
+- **Write for a reader who was not here.** Every comment, commit and reply
+  follows the repository's writing rule: outcome first, short sentences, plain
+  words.

package/skill-pack/maintained/emitting-evidence/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: emitting-evidence
+description: >
+  Emit artifacts — screenshots, recordings, reports, logs — as proof that a
+  change works, bound to the pull request via `outerlayer emit artifact`.
+  Use when finishing work a spec criterion or tracked requirement covers,
+  when asked to "provide evidence", "attach a screenshot", or "prove it
+  works", and in CI steps that produce verifiable output.
+---
+
+An artifact is an exhibit: evidence *of* a specific change, anchored to the
+pull request and rendered in its evidence comment. Emit the few exhibits the
+spec asks for — a reviewer should see the change working, not a gallery.
+
+## When to capture
+
+Capture AFTER the state exists, never before: run the app, the test, or the
+flow first, and shoot the working result. A screenshot of code is not
+evidence; a screenshot of the rendered page is. If the state takes setup
+(seed data, a logged-in user), finish the setup, verify by eye, then capture.
+
+## Per-kind mechanics
+
+Kind is inferred from the file's media type — name files honestly. Every
+artifact shares one upload cap of 8 MiB, whatever its kind:
+
+- **screenshot** (`.png`, `.jpg`) — one focused window or region showing the
+  proven state. Crop noise; keep enough chrome (URL bar, test summary line)
+  to show it is real.
+- **video** (`.webm`, `.mp4`) — a short recording of the flow, start to
+  outcome. Video is the kind most likely to hit the 8 MiB cap: trim dead
+  time, prefer webm.
+- **report** (`.html`, `.pdf`) — generated reports: coverage, benchmark,
+  audit output. Emit the file the tool produced, unedited.
+- **log** (`.txt`, `.log`) — command output proving a run happened: test
+  runs, migrations, gate output. Pipe to a file and emit that file.
+
+Anything else uploads as plain `file` — it is never guessed into a stronger
+kind, so a `.mov` will NOT count where a video is required; convert first.
+
+## Captions
+
+One sentence, present tense, saying what the exhibit shows and what that
+proves: "Signup blocked for a disallowed domain — the 403 page renders."
+Never put secrets, tokens, or personal data in the caption — or the pixels.
+
+## Binding with --for
+
+Record the item's acceptance criteria before you bind evidence to them:
+
+    outerlayer emit criteria criteria.json
+
+The file is `{"criteria": [{"id": "LOGIN-01", "text": "…", "proof": null}]}`,
+one entry per criterion as your team wrote it. `proof` is the artifact kind
+that proves it (`video`, `screenshot`, `report`, `log`, `file`) or `null`. The
+id is yours, 1 to 64 characters of `A-Z a-z 0-9 . _ : -`. The list is the
+only source for the item's Criteria tab: nothing reads criteria out of the
+issue. Once an item has a list, an agent session cannot replace it; ask a
+person to run the command again outside the session.
+
+When a criterion is the reason you captured, bind the artifact to its
+recorded id:
+
+    outerlayer emit artifact shot.png --caption "…" --for LOGIN-01
+
+The PR comment's Evidence section shows the id next to the artifact, and the
+dashboard's Criteria tab lists the artifact on that criterion's row. An id
+the recorded list does not hold gets no row.
+
+## The noise rule
+
+Satisfy the declared proofs; don't document everything. One exhibit per
+criterion is the norm. An unrequested artifact is worth emitting only when
+it would change how a reviewer reads the diff. When in doubt, leave it out —
+evidence works because there is little of it.
+
+## Mechanics
+
+Inside a recorded session, just run the command — the artifact spools
+locally and uploads with the next `outerlayer sync`, bound to this session
+and turn. In CI, run it after the step that produced the file (repo and PR
+come from the CI environment). From a plain machine it anchors through the
+git checkout, or pass `--pr <n>` explicitly. If there is nothing to attach
+to, the command refuses — emit from the work, not from nowhere.
+
+## Report artifacts the default checks read
+
+Two report artifacts feed the default checks. Bind each to its check name with `--for`:
+
+- `--for code-review-ran` for the review report, an HTML file.
+- `--for acceptance-criteria` for the judge's report on each criterion, an HTML file. Emit it only when the issue has criteria.
+
+    outerlayer emit artifact review.html --caption "Review of the change and what it found" --for code-review-ran
+
+A session never records a pass or fail on an artifact. It emits the artifact, and a person or a check decides.
+
+## Instructions-file snippet
+
+The text to append to a repository's instructions file is in [references/agents-snippet.md](references/agents-snippet.md).

package/skill-pack/maintained/emitting-evidence/references/agents-snippet.md

@@ -0,0 +1,20 @@
+<!-- outerlayer:capture-pack -->
+## Emitting evidence
+
+When you finish work a spec criterion or tracked requirement covers,
+capture the working state and emit it:
+
+    outerlayer emit artifact <file> --caption "what it shows" [--for <criterion-id>] [--pr <n>]
+
+Rules: capture AFTER the state exists (run it, then shoot it); kind comes
+from the file type (png/jpg screenshot, webm/mp4 video, html/pdf report,
+txt/log log — anything else is a plain file); every artifact caps at 8
+MiB, and video is the kind most likely to hit it; captions are one
+present-tense sentence with no secrets; bind an artifact to the id of the
+requirement it proves — `--for <id>`, from the team's own spec or
+tracker — and pick the kind that shows the state best; the platform
+records the kind and the id and shows them next to the artifact; satisfy
+what's asked for and stop — don't document everything. Inside a recorded
+session the artifact uploads on the next `outerlayer sync`; in CI it
+anchors via the CI environment; otherwise the git checkout or `--pr`
+anchors it, and with nothing to attach to the command refuses.

package/skill-pack/maintained/outerlayer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: outerlayer
+description: >
+  Explain what OuterLayer is and how work flows through it: work items, the
+  OUTERLAYER_WORK variable, the factory, and building an issue or specifying one.
+  Use when asked about OuterLayer, a work item, OUTERLAYER_WORK, "build issue
+  42", how an issue becomes a pull request, or how to attach evidence or answer
+  a review.
+---
+
+OuterLayer is a software factory. An issue goes in. A reviewed and verified
+pull request comes out, with the evidence that backs it. An agent builds it in
+this repository, on the machine it already runs on.
+
+## Work items
+
+An approved issue becomes a work item. A work item has its own number, which
+is not the issue's number. Everything the factory records about the build
+hangs off that number: the sessions, the evidence and the review threads.
+
+`OUTERLAYER_WORK` carries the work item's number, never the issue's. A session
+started without it is not recorded against any work item. Do not guess the
+number from an issue reference. Read it from `outerlayer work status --issue <n>`, or
+from the output of `outerlayer work build`.
+
+## The loop
+
+1. `/spec` agrees an issue with a person and files it once they approve.
+2. A person adds the issue on the Work page and presses **Build**. A host
+   that runs work picks it up and builds it with `/build`: implement, review,
+   run the repository's checks and open the pull request.
+3. An agent asked to add work runs `outerlayer work build --issue <n>`
+   instead. With `--local`, the person builds it on their own machine with
+   `OUTERLAYER_WORK=<number> claude "/build"`.
+4. `outerlayer emit artifact <file> --caption "<what it shows>"` attaches a
+   screenshot, recording, report or log as evidence. The `emitting-evidence`
+   skill says what to capture.
+5. `/amend` answers the review threads a person handed to an agent.
+
+Launching recorded work needs Claude Code. It is the one agent whose sessions
+OuterLayer can start with `OUTERLAYER_WORK` set and record. Other agents can
+read the files this repository emits, but they cannot be launched as work.
+
+## Reading work items
+
+When the OuterLayer MCP server is configured in this repository, its
+`list_work_items` tool lists the factory's work items. Its `get_work_item`
+tool reads one by number. It reads the key from `outerlayer login`, so if its
+tools fail, run `outerlayer login` and reconnect the server.
+
+## Keeping this repository's context current
+
+`outerlayer context emit` compiles `.outerlayer/` into the files each agent
+tool reads, such as `.claude/skills/`. This skill is maintained: that command
+rewrites it from the installed CLI, so edits to it do not last.

package/skill-pack/maintained/reporting-findings/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: reporting-findings
+description: >
+  Records factory problems: anything in a repository's instructions, tests, tooling or
+  local setup that cost an agent time and was not caused by its own change. Use when
+  writing a "Factory problems" section, a build or review report, a retro or session
+  summary, or any list of blockers, gotchas, flaky tests or wrong instructions. Also
+  use it the moment a CLAUDE.md, AGENTS.md or skill sentence turns out wrong or stale,
+  a test passes on rerun with no change, a gate or command misbehaves, or a setup step
+  fails for a reason outside the diff. Defines the six categories, what evidence each
+  carries, the JSON batch shape, and the `outerlayer emit finding` command.
+---
+
+## What this is for
+
+A finding is a problem in the factory, not in the change: an instruction
+that was wrong, a test that flaked, a tool or gate that misbehaved, a local
+setup trap, or a bug outside the diff. Record one whenever a report, a
+summary or a "Factory problems" section lists such a problem, so the next
+agent does not pay for it again. Findings are informational. They show on the
+work item page, grouped by category, and nothing reads them to pass or fail
+the work.
+
+## Categories
+
+Each finding has exactly one category. Put the evidence in the title, file,
+line and rule fields.
+
+### `context`
+
+An instruction, skill or rule that is wrong, broken, or silent on something you
+had to discover. Include the path of the file that holds the rule and its line.
+Set `--rule-relation` to one of:
+
+- `wrong`: the rule says the wrong thing. Quote the sentence.
+- `broken`: the rule cannot work, such as a path or command that no longer
+  exists. Quote the sentence.
+- `missing`: no rule covers what you had to discover. There is no sentence to
+  quote. Name the file where it belongs.
+
+### `flaky-test`
+
+A test that failed and then passed with no change. Include the test file and
+test name, and both commands: the one that failed and the one that passed.
+
+### `tooling`
+
+A command, script or gate that misbehaved. Include the command, what you
+expected, and what happened.
+
+### `environment`
+
+A local setup problem: a port in use, a shared database, a missing
+dependency. Include what you needed and what you found.
+
+### `defect`
+
+A bug in code outside your own change. Include the file, the line, and how to
+reproduce it.
+
+### `other`
+
+Anything else that cost you time and fits none of the above. Describe it in the
+title.
+
+## The command
+
+```bash
+outerlayer emit finding --id <short-id> --category <category> \
+  --title "<one sentence>" --file <path> [--line <n>] --where "<what you were doing>"
+```
+
+Inside a recorded session the work item is found automatically. Outside one,
+add `--item <number>`.
+
+Examples, one per category:
+
+```bash
+outerlayer emit finding --id worktree-hooks --category context \
+  --title "No document says a fresh worktree has no git hooks until yarn prepare runs" \
+  --file AGENTS.md --rule-path AGENTS.md --rule-relation missing \
+  --where "first push from a new worktree"
+
+outerlayer emit finding --id stale-path --category context \
+  --title "The build skill names a directory that no longer exists" \
+  --file .outerlayer/skills/build/SKILL.md --line 42 \
+  --rule-path .outerlayer/skills/build/SKILL.md --rule-line 42 --rule-relation broken \
+  --rule-quote "Read the plan from reports/plan.md" \
+  --where "implementation stage"
+
+outerlayer emit finding --id flaky-refresh --category flaky-test \
+  --title "refresh.test.ts fails once, then passes on rerun" \
+  --file apps/tenant-dashboard/src/lib/system/pr-session-comment/__tests__/refresh.test.ts \
+  --where "vitest run <file> failed, then passed with no change"
+
+outerlayer emit finding --id gate-skip --category tooling \
+  --title "The pre-push gate prints green when a step was skipped" \
+  --file scripts/git/pre-push-checks.mjs \
+  --where "expected a failure, got exit 0"
+
+outerlayer emit finding --id shared-db --category environment \
+  --title "A peer session reset the shared Supabase project mid-run" \
+  --file apps/tenant-dashboard/supabase/config.toml \
+  --where "needed a stable database, found it re-seeded"
+
+outerlayer emit finding --id null-read --category defect \
+  --title "readItem throws on an item with no claim" \
+  --file src/lib/work/read.ts --line 88 \
+  --where "reproduce: call readItem on a fresh item"
+
+outerlayer emit finding --id slow-hook --category other \
+  --title "The session-start hook adds about ten seconds on every launch" \
+  --file .husky/post-checkout --where "timed with time(1)"
+```
+
+To record several at once, write a JSON batch and run
+`outerlayer emit findings <file>`. The shape is:
+
+```json
+{
+  "schemaVersion": 2,
+  "headSha": "<branch head, optional>",
+  "findings": [
+    {
+      "id": "<category>-<k>",
+      "category": "tooling",
+      "title": "<one sentence>",
+      "file": "<path>",
+      "line": null,
+      "rule": null,
+      "where": { "label": "<what the agent was doing, in plain words>" }
+    }
+  ]
+}
+```
+
+`file` and `title` are always set; `line` and `rule` are `null` when there
+is nothing to put in them. A `context` finding fills `rule` with
+`{ "path", "line", "quote", "relation" }`. Leave `quote` out, rather than
+`null`, when the relation is `missing`.
+
+## When not to record one
+
+- A problem in your own change is not recorded. Fix it.
+- A cost you did not really pay is not recorded. If you noticed it in passing
+  and lost no time, leave it.
+- A problem you already recorded on this work item is not recorded twice.
+  Re-using the same `--id` replaces the earlier finding.