AGENTS.md · diff

git:20261008.8980f15 to git:20261008.b58bbe3

22 added, 8 removed. Audit B to B.

# 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); each

+ `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

`selftest: PASS (2020 checks)` (2016 baseline checks plus four deterministic

sample-retry controls), including the real

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 (94 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 and of

an epoch-rotation frame, each followed by the verifier and recovery, 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) + 2 + 4 = G + R + 4 for planned

lengths G and R, which is 6466 checks measured on the judge's macOS host

(6460 cuts: genesis frame 1 and a rotation frame). The count follows the

two 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 frame, the same code as the revocation and 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 two sizes once

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

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

`--crash-matrix --shard K/8 --sizes G,R --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`, 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, the closed command table, token and stage refusals at

- every sink, 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 (471 checks)`.

+ 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)`.

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`.