feat(loop): an agentic OS for this repository

[gplanchat]

Implements an agentic OS over this monorepo — the permanent layer of files, scripts and ledgers that lets a model work here unattended and be checked while it does. Nine layers, after Linas Beliūnas' How to Build an Agentic OS with Claude Fable 5 (2026-07-10), ported to this repository's PHP toolchain and to the claude CLI.

The decision, the seats, the rollout and the exceptions are recorded in WA007.

What is here

Layer	Files
1 Constitution	CLAUDE.md — 66 lines, only rules a script can check
2 Walls and gate	loop/contract.md, loop/guardrails/verify.sh
3 Heartbeat	loop/loop.sh, triage.md, conductor.md, workers/*.md
4 Trust ledger	loop/scripts/trust-log.sh
5 Standing goals	loop/verify-goals.sh, loop/goals/
6 Budget	loop/scripts/log-cost.sh, cost-check.sh
7 Optional loops	loop/retro.sh, loop/loops.md
8 Ops	Makefile, loop/RUNBOOK.md
9 Rollout	WA007, the 30-day table

The split the architecture exists for: an expensive seat decides, cheap seats execute, a fresh context judges, and a shell script votes last. The conductor is physically unable to write a file, and the gate runs exactly what CI's QA (CS + tests) and Analyse statique jobs run.

Departures from the article, and why

• No llm CLI on this machine, so every seat is claude -p --model. One CLI, no new dependency. The seats are variables: a model outage or a price change is a config edit, not an incident.
• claude -p has no --max-tokens flag. The article's script does not run as printed.
• The CLI reports total_cost_usd, so cost logging records real dollars rather than the article's token-arithmetic estimate. thinking_tokens and cache_read are still logged: the first is where surprise spend hides, the second is the only proof the cached-prefix ordering still holds.
• vendor/ is provisioned into a fresh worktree by hardlink copy from the primary checkout. It is gitignored, so every tick would otherwise die 127 before running a test. Composer's path repositories are relative symlinks, so the copy resolves against its own worktree — verified, not assumed.
• The trust tier table in the source is a published image. Only auto (20 runs, 95%) survives as text; the watch/queue thresholds are this repository's own and say so where they are defined. Same for the runbook, whose rows are built from contract.md and loop.sh's exit codes.
• Layer 0's pricing is two months stale. No figures from it are transcribed into the repository.

Repository-specific additions

• psalm-baseline.xml may never grow. A baseline entry silences a finding without fixing it — test-weakening in another coat. The gate diffs the file; the verifier fails a diff that touches it.
• documentation/adr/ is supervised-only: an ADR records what was decided when it was written (DUR000).
• loop/* branches are exempt from the prise registry, which is a deliberate exception argued in WA007 rather than an oversight.

Five bugs found by running it

None were the model's.

1. "${3:-{}}" — bash closes the expansion at the first brace, so jq received the envelope with a literal } appended and killed every tick just before the conductor's cost was logged.
2. Both seats intermittently fence their output in markdown. A fenced QUIET never equals QUIET, so a quiet repository woke the expensive seat every tick.
3. Gating execution on the auto tier deadlocked the ledger — a skill reaches auto by accumulating runs and could only accumulate them by executing. The tier gates the PR, not the attempt.
4. git diff reports neither untracked files nor worker commits. The worker prompt mandates TDD, so the new failing test was exactly the file going missing, and the verifier was judging done_when against a diff with the test cut out.
5. An empty diff wrote an unearned pass — vacuously satisfying the verifier and passing the gate. Twenty of those promote a skill that has done nothing to auto.

Checks

Check	Result
0	Every scripted call checks stop_reason before using a result
1	wc -l CLAUDE.md = 66, under 150
2	A conductor asked to write a file has the attempt recorded in permission_denials and produces no file. Gate rejects a planted CS violation (exit 8) and a widened psalm-baseline.xml; silent on a clean tree
3	Hand tick exits 0, logs triage and conductor costs, writes one dispatch row, and queued a contract-sensitive item rather than acting on it. Execute path ran end to end: worker went off-spec, the fresh-context verifier caught it, the ledger recorded 1 run / 0 passes / tier queue
4	21 passes → auto; two fails → watch with ALERT demoted in STATE.md
5	Goals with predicate true and false → exit 1, exactly one flipped. Both shipped goals tested against their fixed and broken states
6	Cache reads dominate conductor input — 54127 cached against 4 uncached on the first tick; thinking_tokens nonzero
7	Every installed loop carries its install condition; three are specified and deliberately not installed

Two things this branch does not do

• The gate cannot go green locally. illuminate/cache is in composer.lock but missing from the local vendor/, so 13 tests error. This pre-exists on origin/main in the primary checkout and is unrelated to this branch — CI installs fresh, so it should not appear here. Worth a composer install locally.
• No crontab is installed. The cron lines are text in the runbook. LOOP_PUSH defaults to 0, so nothing opens a PR until that is deliberately set — week 3 of the rollout.

One item needs a human decision before week 3: a GitHub OAuth token sits in the global Composer configuration on the development machine and is readable by any process the loop spawns. WA007 makes moving the loop to a low-privilege user a precondition for granting it push rights.