git:20261008.870c2d9 to git:20261008.4855c44

# AGENTS.md

## What this repo is

A collection of **Agent Skills** (Markdown SOPs + helper Bash scripts) published

as both a Claude Code marketplace (`.claude-plugin/marketplace.json`) and a

Cursor marketplace (`.cursor-plugin/marketplace.json`). It is not a deployable

service. There are no repo-level dependency manifests (no `package.json`,

lockfile, or Makefile at the root); the toolchain — `bash`, `git`, Node.js/npm,

and `python3` 3.11+ (`tomllib`) — is expected to be preinstalled, so a startup

update script has nothing to install.

Components:

- `skills/implementation-loop/` — the backend-neutral implementation loop skill.

Uniform backend modules live under `backends/{claude,codex,grok,cursor}/`, each with

`dispatch.sh`, `runtime.md`, `selftest.sh`, and `fixture-driver.sh`; grok also

has `verify-worktree.sh`. `backends/backends.tsv` registers their capabilities.

Shared suites and the opt-in real-backend gate live under `tests/`; the frozen

Codex matrix is `tests/codex-cases.tsv`. `scripts/run-gate.sh` remains the

backend-neutral gate, while the other eight `scripts/*.sh` executables are

one-release forwarding shims removed in 0.5.0. The shared observable interface

is recorded in `references/dispatch-contract.md` and enforced by the contract

suites. `scripts/loop-coordinator` is the foreground, headless coordinator:

it drafts specs through a judge, records engineer approval, and performs a

diagnostic diff review. Its operator guide is `references/coordinator.md`;

`tests/coordinator-selftest.sh` uses temporary repositories and CLI stubs.

`lib/loopauth/` is stdlib-only python3 shared by `scripts/loop-journal`,

`scripts/loop-index`, and `scripts/loop-authority` (canonical JSON and

digests, the task-graph-v1 schema-2 vocabulary, the pure reducer, and the

0a.2 authority store: records, framing, keys and seals, the git anchor,

recovery, the operator-TTY ceremonies, the admission registry, and

`tools.py`, the one subprocess wrapper with its closed command table; and

0a.3's read-only verification of claimed references, `refs.py`,

`eligibility.py`, and `journal_read.py`, behind `loop-authority refs`); each

imports it only from the `lib/` beside its real `scripts/` directory and

refuses a symlinked `lib/`. `scripts/loop-authority-verify` is the

independent authority verifier and imports nothing from `lib/loopauth`.

Both authority wrappers write nothing themselves and run their Python entry

file beside them (`scripts/loop-authority.py`,

`scripts/loop-authority-verify.py`). The authority store is described in

`references/state-schema.md` section 6; ceremonies need a terminal, and

`LOOP_AUTHORITY_TEST=1` (tests only) admits a `file://` remote that can only

ever form a non-authorizing test lineage.

- `skills/engineering-mode/` — goal-first wrapper over the loop. Shared

playbooks in `references/playbooks/`, plus `scripts/tree-oid.sh` and its

selftest.

- `skills/web-slides/` — a scaffolder (`scripts/scaffold.sh`) that generates a

runnable Vite + React + TypeScript slide deck. The only runnable "app".

- `cursor-implementation-loop/` — the generated Cursor plugin port. It ships

two skills (`cursor-implementation-loop`, `cursor-engineering-mode`) and two

agents (`agents/loop-implementer.md`, `agents/loop-independent-reviewer.md`).

Edit shared inputs under `skills/` or Cursor-authored inputs under

`hosts/cursor/`, then run `bash build.sh`; do not hand-edit the generated

tree. Manifest: `.cursor-plugin/plugin.json`.

- `build.sh`, `hosts/cursor/`, `tests/build-{inventory.py,selftest.sh}` — the

deterministic Cursor-package generator, its host-only overlay, and its

external-inventory/selftest tooling. `bash build.sh --check` verifies the

committed tree and its recorded version decision without rewriting it.

- `install-cursor.sh` / `install-cursor-selftest.sh` — root-level one-line

installer for the Cursor plugin (`curl … install-cursor.sh | bash`), plus its

own selftest.

- `plans/`, `docs/` — design plans and review records; prose only, no CI hooks.

## Invariants CI will hold you to

`.github/workflows/selftest.yml` runs the `scripts` job, the sharded authority

crash matrix (`crash-matrix-plan`, eight `crash-matrix` shards, and

`crash-matrix-coverage`; see step 12), `authority-macos`, and `tree-oid`. Reproduce locally from

the repo root in this order — all suites are self-contained, need no network, and the

backend CLIs are **not** required (they are only needed to dispatch a live

run):

1. `bash -n` syntax checks on every shipped shell script: the builder and its

selftest, backend modules and fixture drivers, shared tests, the gate, all

forwarding shims, the two generated Cursor gate scripts, and both installer

scripts.

2. **Generated Cursor package checks:** `bash build.sh --check`, two builds into

separate temporary destinations with byte-identical external inventories,

then `bash tests/build-selftest.sh` (expect `selftest: PASS (21 checks)`).

The inventory records path, type, mode, and SHA-256 independently of the

embedded manifest. Edit `skills/` or `hosts/cursor/`, run `bash build.sh`,

and record the version decision in `hosts/cursor/version-decision.tsv`.

3. Playbooks must stay platform-neutral: no `read-only` / `investigate` words

and no `codex-dispatch` references anywhere under either

`references/playbooks/` tree.

4. `bash skills/implementation-loop/backends/codex/selftest.sh` — expect

`selftest: PASS (267 checks)`, then

`bash skills/implementation-loop/tests/gate-selftest.sh` — expect

`selftest: PASS (207 checks)`. Their split total is 474. The Codex cases

use python3 for secure state, argv, and fixture validation; python3 3.11+ is

part of the repo toolchain. The Codex suite also starts, signals, and kills

real stub processes to cover stop signals and `--recover-stale`; it needs no

network and no codex CLI.

5. `bash skills/implementation-loop/backends/grok/selftest.sh` — expect

`selftest: PASS (276 checks)`.

6. `bash skills/implementation-loop/backends/cursor/selftest.sh` — expect

`selftest: PASS (142 checks)`.

`bash skills/implementation-loop/backends/claude/selftest.sh` — expect

`selftest: PASS (307 checks)`.

7. `bash skills/implementation-loop/tests/journal-selftest.sh` — expect

`selftest: PASS (621 checks)`; `bash skills/implementation-loop/tests/index-selftest.sh`

— expect `selftest: PASS (114 checks)`; and

`bash skills/implementation-loop/tests/console-selftest.sh` — expect

`selftest: PASS (165 checks)`; and

`bash skills/implementation-loop/tests/calibration-selftest.sh` — expect

`selftest: PASS (121 checks)`. The journal, console, and calibration suites

each run `tests/link-count-cases.py`, which loads that script's Python body

and calls its `validate_regular` directly.

8. `bash skills/implementation-loop/tests/contract-core.sh`,

`bash skills/implementation-loop/tests/contract-negative.sh`, and

`bash skills/implementation-loop/tests/shim-selftest.sh` — expect all green.

The contract-core per-backend counts are claude 64, codex 66, cursor 70,

and grok 66. Contract-negative expects

`contract-negative: PASS (44 checks; 22 broken adapters rejected)`.

9. `bash skills/implementation-loop/tests/evidence-selftest.sh` (the

`scripts/loop-evidence` record card) — expect `selftest: PASS (157 checks)`.

10. `bash skills/implementation-loop/tests/coordinator-selftest.sh` — expect

`selftest: PASS (735 checks)`. It uses only local temporary repositories

and backend CLI stubs, and never calls a real agent. `COORD_SELFTEST_JOBS`

defaults to 4; set it to 1 for declaration-order serial execution.

11. `bash skills/implementation-loop/tests/reduce-selftest.sh` (`lib/loopauth`:

canonical encoding, the schema-2 vocabulary, and the reducer against a

frozen oracle of the transition table and the terminal_evidence matrix,

plus schema-2 records written through `loop-journal append --schema 2`) —

expect `selftest: PASS (803 checks)`.

12. `python3 skills/implementation-loop/tests/authority-review-selftest.py`

runs 33 offline review regression tests, including real Git writer/verifier

agreement and full-fsync routing.

`bash skills/implementation-loop/tests/authority-selftest.sh` (the 0a.2

authority store: the real `scripts/loop-authority` under a scratch `HOME`,

ceremonies driven through a Python pty, a `file://` bare remote, real

Ed25519 keys from the host `ssh-keygen`, crash injection at every protocol

cut, and the independent verifier; needs `ssh-keygen` with `-Y`, `git`,

`ssh`, and `openssl`, and runs its cases in parallel) — expect

crashes derived from every command's `CRASH_APPLICABLE` set. The

"crash matrix coverage check" section tests missing, duplicate, and

miscredited cuts independently of section order. For review-only work,

`bash skills/implementation-loop/tests/authority-selftest.sh --review-only`

runs the changed review, frozen inventory/transport, named revocation and

re-genesis scenarios, and coverage negative controls; it does not run the

frame-byte matrix. `--review-only inventory` runs just the frozen inventory,

transport, and coverage controls — expect `selftest: PASS (98 checks)`.

The pty cases require a readable macOS

`sysctl kern.bootsessionuuid` (sandbox denial is an environment failure,

not a skipped or passed case). Then the crash matrix,

`bash skills/implementation-loop/tests/authority-selftest.sh --crash-matrix`

(the real writer crashed at every frame-byte cut of genesis frame 1, of an

epoch-rotation frame, and of the active epoch's revocation frame, each

followed by the verifier and recovery -- for the revocation, the compound:

after a torn cut neither the record nor a quarantine marker, epoch 1 still

active; after the last byte the record anchored and the exact bytes of the

marker recovery's quarantine row writes -- then the classifier sweep

below; slow, parallel) — expect `selftest: PASS`, with one check per cut,

one classifier-sweep check per frame kind, and four coverage checks:

(G − 1) + (R − 1) + (V − 1) + 3 + 4 = G + R + V + 4 for planned lengths

G, R, and V. The two-frame matrix measured 6466 checks on the judge's

macOS host (6460 cuts: genesis frame 1 and a rotation frame); the

revocation frame adds V. Re-genesis frames are not in it: they keep every

named crash point, sampled real frame-byte cuts, and the full classifier

sweep in the default run. The count follows the

three frames' planned lengths N, which

include the temporary directory's path (the pinned `file://` remote) and

the ceremony's pid, tty, and start-time digits, and so vary by machine;

every run prints the enumerated cut list's count and digest

(`# crash matrix cut list: ...`). Each frame's cuts are

`<kind>:frame-byte-n` for n from 1 to N − 2 (the torn prefixes) plus

`<kind>:frame-byte-last`; the final byte is only ever `last`. A run's

frame need not be N bytes long (on Linux the pid and start-time digits

only grow). Byte n must prove a torn prefix: it is credited only to a

real crash of that kind at exactly offset n, measured on disk, of a frame

of at least n + 2 bytes, so n is never that frame's final byte. A run

whose frame is too short for byte n, or exactly n + 1 bytes long (n its

final byte, the unterminated state), is discarded — never credited as n,

never checked as the unterminated outcome under a numeric id — and

retried with a fresh ceremony process, up to 50 runs, and then the cut

fails; no other offset is ever tried or credited. `last` is credited only

to a real crash at its own frame's final byte, whatever that frame's

length. Then, for every distinct actual frame length the run's crashes

wrote (discarded runs included), per kind, the offline classifier — A2.3's

frame-1 classifier for genesis frame 1, A1.6's tail classifier for a

rotation or revocation frame, the same code as the re-genesis sweeps —

classifies every prefix 1 .. N − 1 of that exact frame, and prefixes

1 .. N − 2 must be torn and N − 1 unterminated; the unsharded run and

each shard print, per kind, the planned numeric range, the `last` cut,

and the lengths swept (`# crash matrix <kind> classifier sweep: ...`). In

CI it is its own jobs: `crash-matrix-plan` probes the three sizes once

(`--crash-matrix --plan` prints `# crash matrix sizes=G,R,V`); eight

`crash-matrix` shards (`fail-fast: false`, 120 minutes each) run

`--crash-matrix --shard K/8 --sizes G,R,V --cut-ids-out cut-ids-K-of-8.txt`

— the i-th enumerated cut (from 0) belongs to shard i mod 8 + 1, and each

shard prints its partition's count and digest and its classifier sweep

and uploads its credited cuts, one line each: the cut id, then the

checked run's actual frame kind, frame length, and crash offset; and

`crash-matrix-coverage` fails unless the plan and every shard succeeded

and `--crash-matrix --check-shards <dir> --sizes G,R,V`, which recomputes

the full list from the same enumerator, finds the eight lists to be

exactly its partitions, every planned cut exactly once, with every cut's

evidence crediting it: the cut's kind; for byte n, offset n and a frame

length of at least n + 2; for `last`, an offset of its frame length − 1.

The coverage job does not need the classifier sweep. The unsharded run

makes the same check over its own list. Then

`bash skills/implementation-loop/tests/registry-selftest.sh` (the frozen

admission-registry oracle, the AST reachability scan with planted-bypass

negative controls -- including 0a.3's read-only rules and transitive call

graph for `refs.py`, `eligibility.py`, and `journal_read.py` -- the closed

command table, token and stage refusals at every sink, the full request-kind

× source-state cross-product refused as dormant by every request row,

recovery and finish tokens against real crash states -- minted only from an

issued plan, once, re-proved by a fresh observation, so forged, altered,

and replayed plans and caller-built bindings mint nothing -- abandonment

that removes only the intent, missing intent-named directories, and the

revocation's quarantine child) — expect `selftest: PASS (552 checks)`.

Then `PYTHONDONTWRITEBYTECODE=1 python3 skills/implementation-loop/tests/refs-review-selftest.py` (18 offline

observation/CLI regression tests), then `bash skills/implementation-loop/tests/refs-selftest.sh` (0a.3: the

closed reference map against a frozen oracle and the live 0a.1

vocabulary, claim classification and the eligibility gate in-process, and

the real `loop-authority refs` over journals written by `loop-journal

append --schema 2` against fixture stores that are current, absent,

pending, quarantined, and in each bootstrap terminal state, with the

journal store, the authority directory, and the remote byte-identical

afterwards; needs `ssh-keygen` with `-Y` and `git`) — expect

`selftest: PASS (167 checks)`. Then

`bash skills/implementation-loop/tests/falsifier-selftest.sh` (0a.4: the

named falsifier over the final 0a tree, one check set per claim -- F1

sinks reachable only through admitted rows, with registry-selftest.sh's own

static mode re-run, six planted bypasses, alias-proof scans of the writer

entry and the verifier (every import and attribute chain resolved against

the real modules; planted aliases such as `import os as o; o.system(...)`

and `import subprocess as sp; sp.run(...)` fail), the writer entry's

loopauth accesses frozen through every alias (a planted forged-token

bypass through `s = mods["store"]`, `s._new(s.Token(...))`, `s._grant`,

and `s._fs_create` fails, and is shown live), the verifier's runner frozen

to its one `subprocess.run(argv, ...)` (an extra call planted inside it

fails), and the verifier's complete fetch argv and git environment frozen

for file://, SSH, and HTTPS remotes, the exact anchor fetch and pattern

push and exact ls-remote forms, the token-carrying in-sink anchor-ref read

and direct-ref/loose-entry guard frozen after authorization immediately

before git (removing it, dropping its token, removing its loose-entry scan,

or moving it before authorization is detected), the whole-skill Python

import-edge inventory and its

dynamic-import, subpackage, symlink and bytecode controls, alias begin/child

and stream-factory controls; F2 the frozen entry-point table

against the real parser and the ordered token trace of `recover` for every

case of the crash matrix, including both targeted marker cuts during

rotate/re-genesis's initial recovery (real crashes, frozen cut and recovery

traces, and uninstrumented-writer fidelity checks);

F3 derived rows with no entry, unminted sink traces, and the compound

children's token refusals;

F4 no generic sealing or append hatch, each row validator dominating its

record (planted dead validators, and stand-in validators in lib/loopauth or

the entry, fail), runtime registry function/table identities and row

validator values after entry imports and recorded ceremonies, frozen

reflection call sites and preparation positions; F5 recovery that never

invents authority; F6 compound

transitions that never come apart -- "both" for the active epoch's

revocation is its record anchored with writer, verifier, and refs

classifying the store quarantined by its exact rule and position (the

marker's exact bytes asserted once recovery completes from every cut), and

strict "both" also requires no residual intent; the marker-written intent

case is separately pinned as quarantined. "Abandoned" re-genesis needs

the recorded old remote tip, each with

planted half-transitions, and the every-byte crash matrix's enumerator is

checked to cover all three frame kinds -- ceremonies in-process with the TTY

stubbed, so no pty; needs `ssh-keygen` with `-Y`, `git`, and `ssh`; the crash

matrix runs in parallel beside the other modes) — expect one `F1` … `F6`

line each with `PASS`, `escape-hatch: none`,

`falsifier: PASS (2739 checks)`, and `selftest: PASS (2739 checks)`.

13. `bash cursor-implementation-loop/skills/cursor-implementation-loop/scripts/gate-selftest.sh`

— expect `selftest: PASS (207 checks)`.

14. `bash install-cursor-selftest.sh` — expect `selftest: PASS (64 checks)`.

15. Packaging checks: both marketplace JSON manifests must parse; every

`SKILL.md` (under `skills/` and `cursor-implementation-loop/skills/`) must

have non-empty `name:` and `description:` frontmatter; engineering-mode and

Codex-loop Markdown must have no dangling relative links.

16. `tree-oid` job (runs on ubuntu **and** macos):

`bash skills/engineering-mode/scripts/tree-oid-selftest.sh` and the

Cursor copy — expect `selftest: PASS (202 checks)` each. Keep these scripts

portable across GNU and BSD userlands.

## Shell gotcha: locale prefixes in forked shells

Inside `$(...)`, `( ... )`, `<( ... )`, or a function called from one of them,

write `env LC_ALL=C cmd`, never a bare `LC_ALL=C cmd` (same for `LANG` and other

`LC_*`). After a bare prefix the forked shell restores its own locale; with

Homebrew bash 5.3 on macOS and no `LANG`/`LC_*` in the environment that restore

can segfault, so the substitution returns 139 and `set -e` ends the script.

A bare prefix in a script's own main shell is safe. `env` runs external

commands only, not shell functions or builtins.

## Manual backend integration gate

`skills/implementation-loop/tests/integration-test.sh` is the manual,

opt-in pre-release gate for backend changes. It exercises the real claude, codex, grok,

and cursor-agent sandboxes, needs authenticated CLIs, and makes real API calls.

`--backend claude|grok|cursor|codex|all` is repeatable and deduplicated; `--require

codex` implies codex and fails unless every frozen non-managed Codex case runs

exactly once with no skip/failure and complete provenance. Unavailable or

logged-out backends otherwise remain skips. `--require claude` implies claude and

fails if any Claude case is skipped. CI only runs `bash -n` on this

script and never executes it.

## Running the web-slides app (non-obvious gotchas)

Scaffold, then run the Vite dev server:

```bash

cd /tmp # a scratch parent dir, NOT the repo

bash <repo>/skills/web-slides/scripts/scaffold.sh ws-demo --theme=midnight-press

cd ws-demo && npm run dev # serves http://localhost:5174/

```

- **Pass a RELATIVE target dir and run from the intended parent.** Current

`npm create vite` (create-vite v9+) resolves the project path against the

cwd and mishandles a leading `/`, so an absolute target like `/tmp/ws-demo`

gets scaffolded into `$PWD/tmp/ws-demo` and the script's later `cd` fails.

Don't scaffold from inside the repo checkout — it would drop an untracked

deck into the repo.

- The first `npm create vite` invocation may no-op while it downloads

`create-vite`; if the target dir wasn't created, just re-run — the package

is cached the second time.

- The scaffolder runs `npm install` and `npx tsc --noEmit` itself and aborts

on type errors, so a successful scaffold already typechecks.

- Dev server port is fixed to `5174` in `templates/vite.config.ts`. In the

deck: click the stage / `→` / space advances one step, `P` opens the

presenter window, `N` toggles the notes overlay. List themes with

`scaffold.sh --list-themes`; default is `midnight-press`.