CLAUDE.md · diff

git:20261003.1b3586a to git:20261003.51d9739

11 added, 1 removed. Audit A to A.

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this repository is
The Working Genius plugin itself: a Claude Code plugin — 24 skills under `skills/` and five subagents inside the skills that spawn them, distributed through the plugin marketplace (`.claude-plugin/`). The skills are prose, plus three things only Claude Code reads that ride inside the same folders (below); nothing here is held back for another client (user ruling, 2026-09-05). There is no runtime, no build and no test suite — what the skills claim is measured by an eval suite, `evals/` (below); the one script is the format's instrument, `skills/genius-file/measure.py`, which counts and never decides, and whose one writing command, `append`, writes only the log entry it is handed, where the caller named — a fork must be able to carry the whole thing as plain folders, and still can. Dogfood work files (`.genius/`) are gitignored and never shipped.
## Commands
There is nothing to build or run. Four checks matter when editing skills:
- **Count characters, never bytes.** `python3 skills/genius-file/measure.py count <file>` is the instrument and this one-liner is what it does; any number that enters a skill or a record comes from one of these and not from `wc -m` (which counts bytes under most non-interactive locales) or `awk length()`:
```
python3 -c "import sys;print(len(open(sys.argv[1],encoding='utf-8').read()))" <file>
```
- **Relative links between skill files must resolve** (`agents/inventor.md`, `../tenacity/agents/reviewer.md`, `FILE-FORMAT.md`, `../genius-file/BACKLOG-FORMAT.md`; a work file's own links in a template, `log/…` and `CONTRACT.md`, are skipped). A one-off check:
```
python3 -c "import re,os,glob;print([(f,t) for f in glob.glob('skills/**/*.md',recursive=True) for t in re.findall(r'\]\(([^)#]+)(?:#[^)]*)?\)',open(f,encoding='utf-8').read()) if not t.startswith('http') and '<' not in t and t!='CONTRACT.md' and not t.endswith('.log.md') and not t.startswith('log/') and '/log/' not in t and not os.path.exists(os.path.join(os.path.dirname(f),t))])"
```
- **Frontmatter must parse, and the instrument must not fail.** The preloads and the judge's command hooks live in YAML frontmatter, and a stray indent drops the whole block without a word; `measure.py` is injected into four commands and a skill whose injected command fails is aborted whole, so it exits 0 on an empty directory and on a malformed snapshot; `stop-judge.py` blocks a stop only on a clear verdict, so it exits 0 on garbage and on an absent `claude`. One check for all three:
```
python3 -c "import yaml,glob;[yaml.safe_load(open(f,encoding='utf-8').read().split('\n---\n')[0][4:]) for f in glob.glob('skills/*/SKILL.md')+glob.glob('skills/*/agents/*.md')];print('frontmatter ok')" && python3 skills/genius-file/measure.py status >/dev/null && printf 'x' | python3 skills/genius-file/stop-judge.py && echo 'instruments ok'
```
- **The skills have an eval suite**, `evals/`, run by `claude plugin eval` (2.1.269 and later): one case per claim the skills make that a fresh session can be caught breaking — an ordinary request never enters the flow (`no-hijack`), a question about work in flight is answered from the instrument and invents nothing (`nothing-in-flight`), an idea handed to the flow is interviewed and not built (`genius-starts-wonder`), discernment on a work with no paths runs Invention first — more than one inventor, the paths in the log — and presents one commitment with its kills, not a menu (`discern-invents-first`, scaffolded), one slice is built red before green with its evidence in the log (`enable-red-before-green`, scaffolded), and a close-out whose log records a criterion as passed that fails on the code runs it fresh and does not mark the work done (`tenacity-reruns`, scaffolded). Each case is a prompt as a person would type it, graders that cost nothing (`tool_used`, `tool_order`, `regex`, `file_exists`) and one judge rubric; results land in `evals/results/`, gitignored, and `--keep-temp` keeps a run's trace. Two facts about the runner, measured 2026-09-23: a prompt that is a slash command (`/genius`, `/enable demo, slice 2`) is not run — zero turns, no error — so the user-typed commands are outside an eval's reach and the cases say what a person would say; and a case that grants `Bash`, `Write` or `Edit` runs inside the runner's sandbox, where a machine that cannot make user namespaces kills every shell call (a root cloud container did, and scored the enable case 0.57 for it). The smoke case runs on haiku and the flow cases on sonnet, because haiku did not fire `genius-file` on the in-flight question at all (measured), a fact about triggering on a small model and not a reason to loosen the case:
```
claude plugin eval . --tag smoke --runs 1 --ablation none --model haiku --allow-tools Bash Write Edit --trust-plugin --no-publish
claude plugin eval . --tag flow --runs 1 --ablation none --model sonnet --scaffold --allow-tools Bash Write Edit --trust-plugin --no-publish --max-cost-usd 10
```
- Scores: `no-hijack` 1.0 (haiku), `nothing-in-flight` 1.0 and `genius-starts-wonder` 1.0 (sonnet), all 2026-09-23 in the cloud container; `enable-red-before-green` on a Mac, 2026-09-24, 2.1.281, sonnet, three runs at $0.43–0.52: 0.86 each, red before green and the slice closed whole every time (the log's `## slice-2` with its command lines, S2 checked, the reviewer, one commit), each run missing one grader. Two misses were the case's own and are fixed: the closing-message rubric first asked for command lines in the message, which no rule names for a session reporting to a person (the lines' home is the log), and now asks for them or a pointer to where they are recorded (user ruling, 2026-09-24); and the order graders matched `greet\.py` anywhere in an Edit's input, so a work-file edit mentioning the file could count as the implementation — they now match the `file_path`, checked against a kept trace (the run that missed kept no trace, so that it was a log edit is inferred from the kept run's identical sequence). One miss is the skill's: under the new rubric one run's close listed each criterion with its result and one said only "all three criteria verified directly", pointing nowhere, because nothing in `enable` asked the close to the person to say where its evidence is; `enable`'s closing section now does (user ruling, 2026-09-24), and the one run since (v0.30.1, $0.45) scored 1.0, its close naming `.genius/demo/demo.log.md#slice-2` — one run, not yet a rate. v0.32.0 (the log as a tree), 2026-09-25, in the cloud container with `bwrap` and `socat` installed so the runner accepts a Bash grant: `no-hijack`, `nothing-in-flight` and `genius-starts-wonder` 1.0; `enable-red-before-green` 0.71, because the sandbox killed every shell call as root (`apply-seccomp: write /proc/self/uid_map`), so no test ran and the two graders that need one missed — while the run still wrote the tree's shape unprompted (the branch `log/slice-2.md`, its root line, the `[~]` link, an honest `owed:` line) and invented no evidence. The enable case on a machine whose sandbox runs is still owed. v0.31.0 (the first `/skill-audit`'s findings, five stage descriptions re-anchored on the user's ask), 2026-09-25, cloud container, granting `Write Edit` only because this container has no sandbox backend (`bwrap` absent, so a `Bash` grant is refused before the run starts): `no-hijack` 1.0 (haiku), `nothing-in-flight` 1.0 and `genius-starts-wonder` 1.0 (sonnet); `enable-red-before-green` needs `Bash`: with `bubblewrap` and `socat` installed the runner starts, and every shell call then dies at `apply-seccomp: write /proc/self/uid_map: Operation not permitted` (root), scoring 0.29 on a run whose model refused, rightly, to claim a test it could not run; so the case was reproduced by hand the same day — `scaffold.sh` in a scratch directory, the case's prompt through `claude -p --plugin-dir . --model sonnet`, unsandboxed — and its seven graders applied to the trace and files: all seven hold (the test written and run red before `greet.py` was edited, the log's `## slice-2` with its command line, S2 checked, the reviewer spawned, one commit, a close naming the log entry and the commit), one run, the judge rubric read by hand. `genius-starts-wonder` ran three more times in the runner at v0.31.0: 1.0, 1.0 and 0.67, the miss a first round where three of five questions carried no recommendation — a rule `wonder` already states, not one the audit's diff touched. v0.33.0 (Invention inside `/discern`), 2026-09-25, cloud container, `Write Edit` granted and `Bash` refused for want of a sandbox backend: `discern-invents-first` 1.0 on sonnet, one run, $1.05 — three inventors spawned, each on a different home for the limit (the dispatch layer, a per-route decorator, the transport layer), `## invention` in the log, no code written, the judge's three votes PASS; one run, not yet a rate. The same day at v0.33.0: `no-hijack` 1.0 (haiku), `nothing-in-flight` 1.0 and `genius-starts-wonder` 1.0 (sonnet); the enable case still waits for a machine whose sandbox runs. With blind attackers added to `/discern` the same day, `discern-invents-first` gained an `attackers-spawned` grader, and ran three more times on sonnet: 0.83 ($2.42), where an attacker's probe test was left in the work's folder and the old `no-code-written` grader counted probes written under the system temp as implementation — the attacker and inventor briefs now say the work's folder is inside the tree and end on a `git status` check, and the grader became three (`api/server.py` carries no 429, no `api/*limit*` module, no `.py` left under `.genius/`); 0.88 ($1.96), the paths recorded somewhere other than `log/invention.md`, no trace kept — `invent` now names that branch; 1.0 ($2.22). `tenacity-reruns` needs `Bash`, so it was reproduced by hand the same day, as the enable case was — `scaffold.sh` in a scratch directory, the prompt through `claude -p --plugin-dir . --model sonnet`, unsandboxed, $0.24: the skill fired, the criterion's own command was run fresh (`greet("Ada")` → `Hello, Ada` against the pinned `hello, Ada`), the snapshot was not marked done, and the close to the person named the mismatch, the loose test and the log line that claimed otherwise; four graders hold, the rubric read by hand. One slip in the same run: it proposed correcting the false log line "in place", which `errata` forbids for a record — `errata` was not loaded in that run. `tenacity` now loads `errata` before proposing a correction; one run by hand since ($1.96): `errata` loaded, the correction appended below the false line, the code fixed and re-run (`hello, Ada`), three reviewers spawned, the work closed — and it hit 40 turns before its last message, so the case now allows 80 and its rubric accepts a fix shown fresh before done as well as a stop short of it, since fixing a pinned criterion the code misses is resolving a finding, not reshaping the work; `not-marked-done` gave way to `errata-loaded`. `enable-red-before-green` at `00d7336` (this change's last commit), 2026-09-30, on the owner's Mac through a remote-control session, 2.1.285, sonnet, sandbox working, `Bash Write Edit` granted: 1.0, $0.32, 71 seconds, seven graders of seven — the test written (Write, call 11) and run (Bash, call 10) before `greet.py` was edited (call 18), seven test runs, the log's `## slice-2`, S2 checked, the judge's three votes PASS on the close naming its evidence; one run, not yet a rate. **Measured and not shipped, 2026-10-03 (v0.35.0's change):** pstack's device of copying a stage's steps verbatim into the session's task list, A/B on `enable-red-before-green` by hand in the cloud container (2.1.288, sonnet, unsandboxed, three runs per arm): main, and a one-line pointer to the steps, created no task in six runs; a line naming `TaskCreate` created five tasks in three of three. All nine closed the slice whole (red first, `## slice-2` with its command lines, S2 checked, the reviewer, one commit, a close naming its evidence), so the case sits at its ceiling and cannot show a gain; the task list cost turns (37, 28 and 16 against 12–13) and $0.30–0.39 against $0.29–0.35. No gain measured, a cost measured, so it stays out until a case catches a step dropped. Two facts from the same runs: run by hand with `Bash` granted, eight of nine wrote the test through a Bash heredoc, which `test-written-before-implementation` (a `Write` grader) cannot see, so it misses on a run that did write it first; and seven of nine first ended their turn on "waiting for the reviewer" with the reviewer in the background, and `claude -p` woke them when it returned, so it is not the stall the judges name. The two commands outside the flow, `/attack` and `/fresh-eyes`, typed through `claude -p` the same day (a slash command runs there, not in the eval runner), one run each on sonnet, $0.23 and $0.20: each spawned its agent (`attacker` on a mutable-global plan, `reviewer` on an uncommitted `greet_all` with a trailing separator), checked what came back against the repo, reported landed and survived or blocking and held, and wrote nothing (`git status` showed only the diff under review).
+ **Where each case stands** (the run-by-run history, every miss and what fixed it, is in the commit messages: `git log -- CLAUDE.md evals/`):
+ - `no-hijack` 1.0 on haiku, every run since 2026-09-23.
+ - `nothing-in-flight` and `genius-starts-wonder` 1.0 on sonnet at v0.33.0; `genius-starts-wonder` once scored 0.67 at v0.31.0, a first round whose questions carried no recommendation.
+ - `discern-invents-first` 0.83, 0.88, then 1.0 at v0.33.0 on sonnet, $1.96–2.42 a run; the misses fixed the attacker and inventor briefs, the graders, and `invent`, which now names `log/invention.md`.
+ - `enable-red-before-green` 1.0 in the runner on the owner's Mac, 2026-09-30, sandbox working, seven graders of seven; one run, not yet a rate.
+ - `tenacity-reruns` by hand only: the criterion re-run fresh, `errata` loaded before the correction, the work closed on a fix shown fresh; the case allows 80 turns because a full close-out needs them.
+ - After the prose pass of 2026-10-03 (every sentence in `skills/` over 60 words split, no rule changed): `no-hijack` 1.0 (haiku), `nothing-in-flight` 1.0 and `genius-starts-wonder` 1.0 (sonnet) in the runner; by hand, `enable-red-before-green` three runs, each red before green, `## slice-2` with its command lines, S2 checked, the reviewer, one commit, a close naming its evidence ($0.28–0.35), and `tenacity-reruns` two runs, each re-running the criterion, loading `errata`, fixing the code and showing `hello, Ada` fresh before done ($0.60–0.61).
+
+ **Running the cases in a root cloud container.** Without a sandbox backend (`bwrap` and `socat`) a `Bash` grant is refused before the run starts, so `no-hijack`, `nothing-in-flight` and `genius-starts-wonder` run in the runner with `--allow-tools Write Edit` and one `--case` at a time. With the backend installed, the runner's sandbox kills every shell call as root (`apply-seccomp: write /proc/self/uid_map`). So the Bash cases are reproduced by hand: `scaffold.sh` in a scratch directory, the case's prompt through `claude -p --plugin-dir . --model sonnet`, unsandboxed, and the graders applied to the trace and files by hand. Run that way, eight of nine runs on 2026-10-03 wrote the test through a Bash heredoc rather than `Write`; a `tool_order` grader names one tool per end, so read the order off the trace instead of scoring it as a miss. The runner's own run on the Mac used `Write` and `Edit`. A slash command does run under `claude -p`, unlike in the runner, so that is how a user-typed command is exercised: `/attack` and `/fresh-eyes` were, once each on 2026-10-03, and each spawned its agent, checked what came back against the repo, and wrote nothing. A run that ends its turn "waiting for the reviewer" with the reviewer in the background is woken when it returns (seven of nine on 2026-10-03), so it is not the stall the judges name.
+
+ **Measured and not shipped, 2026-10-03:** pstack's device of copying a stage's steps verbatim into the session's task list. A/B on `enable-red-before-green` by hand, three runs per arm: a line naming `TaskCreate` created the tasks three times of three; main and a vaguer pointer created none in six. All nine runs closed the slice whole, so the case cannot show a gain, and the task list raised the turns from 12–13 to 16–37. It stays out until a case catches a step dropped.
- **The skills have a prompt audit**, `/skill-audit` (a saved workflow, `.claude/workflows/skill-audit.js`; args: skill names to narrow it, and `quick`, `standard` or `deep`), adapted from the Claude API skill's `prompt-audit` guide and narrowed to this repo: the instrument `.claude/skill-audit/scan.py` takes the inventory and counts the signals (it counts and never decides); a `skill-auditor` agent per lens per skill and per plugin-wide lens reads, in parallel; each finding goes to three `audit-skeptic` agents, one per verification lens, blind to each other, and stands on two; a completeness critic asks what was missed; the report and a proposed diff, checked on a scratch worktree, land in `.claude/audit-runs/<date>/`, gitignored. What each lens asks, the keep list and the confidence rubric have one home, `.claude/skill-audit/LENSES.md`; this file's rulings bind every lens as keep-list item 11. The audit proposes and never applies; a finding the maintainer declines goes in `.claude/skill-audit/DECLINED.md` with its reason, so the next run does not raise it again. A maintainer session here also runs `.claude/hooks/check-skill-edit.py` after every edit under `skills/`, `.claude-plugin/` and `.claude/agents/` — the frontmatter, link and instrument checks above, on the file that changed — because a dropped frontmatter block says nothing until a run misses it. None of `.claude/` ships: the plugin reads `skills/` and the agents `plugin.json` names. The first run, measured 2026-09-25 in the cloud container at `standard` over all 22 skills: 592 agent calls, 17.3M subagent tokens, 86 minutes; 71 findings confirmed, 19 flagged, 11 refuted. The two agent types were not registered in the session that created them, so every call ran on the fallback that reads the brief from its file; and a workflow subagent's `Write` is refused, so the report is written through Bash and returned whole. `quick` is the one to reach for on a single skill.
- **Release.** Any change under `skills/` or `.claude-plugin/` that merges to `main` bumps `version` in `.claude-plugin/plugin.json` in the same change — marketplace clients detect updates only through that number. A skill added or removed moves the count in README's first line.
## Architecture
**One skill = one folder** `skills/<name>/SKILL.md`, frontmatter `name`, `description`, optional `argument-hint`. `disable-model-invocation: true` marks a command only the user types (`/genius`, `/architect`, `/designer`, `/compact`, `/distill`, `/reconcile`, `/triage`, `/waitwhat`, `/attack`, `/fresh-eyes`, `/setup-working-genius`); the six stage skills and the discipline skills (`genius-file`, `record-prose`, `errata`, `decision-record`, `domain-glossary`, `blindspot`, `diagnose`) are model-invoked. **The five subagents** — `skills/invent/agents/inventor.md` (spawned by the `invent` skill, inside `/discern` or `/invent` alone, one per angle), `skills/discern/agents/attacker.md` (by `/discern`, and by `/attack` outside the flow, one per path, blind to the others, because the session that read every path already prefers one), `skills/enable/agents/builder.md` (by `/enable`'s coordinator, one per slice), `skills/tenacity/agents/reviewer.md` (by `/enable` at a slice close, `/tenacity` at close-out, and `/fresh-eyes` outside the flow), `skills/designer/agents/design-critic.md` (by `/designer` on the tile the user chose; Claude Code's `/design` was measured as the drawing step and is not one: on 2.1.285, 2026-09-30, it refuses the Skill tool, from the model and a subagent alike, by `disable-model-invocation`, and typed with a brief it only manages Claude Design access consent — no artboards, and `DesignSync` syncs design-system files, not directions) — are Claude Code plugin agents, declared by path in `plugin.json`'s `agents` field: frontmatter `name` and `description`, and no `tools` list, because the agent inherits everything the session has and a list only names less (the reviewer's read-only discipline is a rule in its body, not a grant; `Bash` could write anyway). The body is the subagent's system prompt and carries the discipline, while the spawning skill's task message carries the parameters (the problem and angle, the slice and where to build, the diff and what it is judged against). They live inside the skill that spawns them, not in a top-level `agents/`, so a skill, its task message and its agent's brief change in one folder. The body still stands alone as a brief, because the preload (below) is context and not a guarantee. **Measured, 2026-09-23, 2.1.280:** a builder spawned by the Agent tool expanded all three of its preloads (`genius-file`, `record-prose`, `decision-record`), so the preload does reach a spawned agent; the measurement was a function hook's log line on branch `claude/claude-mod-plugin-upgrade-303ke0`, which main does not carry. The skill names what the message must carry; the agent names what it hands back — one home each.
**Three things only Claude Code reads**, each inside the folder of the skill that uses it: `/genius`, `/compact`, `/reconcile` and `/distill` inject the instrument's output before the model reads — `status`, `snapshots`, `links`, `distill` — and their `allowed-tools` pre-approves exactly that command, because an injected command that would prompt aborts the invocation (`anchors <slug>` is run by the session at a close instead, pre-approved in `/enable` and `/tenacity`, because an injection is taken at invocation and a close comes later); every agent but the design critic preloads the discipline skills by scoped name (`workinggenius:genius-file`, …), so the skills are the home and the body restates only what a brief must; and two judges, one `command`-type hook, `skills/genius-file/stop-judge.py`, registered by `/enable` (`Stop` and `SubagentStop` matched on the builder) and `/tenacity` (`Stop`) — by invocation, never by installation, because a plugin-level `hooks/hooks.json` fires in every session with the plugin enabled, flow or not, and the flow never hijacks a request that didn't enter it. The judge blocks only a turn announcing its own next dispatch with nothing running in the background, or a builder's claim of done with no `command → result` line; three free checks settle most stops (`stop_hook_active`, a running subagent, no work at enablement or tenacity — the one frontmatter field it reads), and only then a fast model reads the turn's last message, never the transcript, through a nested `claude -p` with hooks, skills, tools and MCP off; every failure of its own allows the stop. Claude Code ignores, with a warning, hooks written in a plugin agent's own frontmatter, so the builder's judge lives with the skill that spawns it. **Measured, 2026-09-05, all through a live two-turn session driven by the Agent SDK:** a skill's `prompt`-type `Stop` hook is removed the moment its condition is first met, so it guarded only the invoking turn — whatever the docs say about the rest of the session; a `command`-type hook registered by the same skill fired on both turns, which is why the judges are one; `${CLAUDE_PLUGIN_ROOT}` is substituted in a skill's frontmatter hook command and `${CLAUDE_SKILL_DIR}` is not; and `claude -p --bare` reads no OAuth login, so the nested call runs without `--bare`. A plugin-level `hooks/hooks.json` prompt hook also registers and persists (measured), and is not used, for the reason above. This reopens 275ed4f this far and no further (user ruling, 2026-09-05): what died there was a parser demanding gate blocks in work files; what returned is a model reading the same message a person would, at an action point, adding no line to any file. Three runs by hand are on record (2026-09-05 and 2026-09-06, a picking-robot warehouse scheduler built through the whole flow twice and a web spreadsheet once, the records in those commits' messages): 64 judge decisions — 46 stops allowed as pauses on background work, 14 model-judged allows, 4 allowed for no work in build — no block and no false block, and no stall for a judge to catch, so the runs show the judges cost nothing and prove nothing about the failure they name. (Those runs predate v0.31.0, before which no stage wrote `stage:`, so the judges were never asked at all.) **Measured, 2026-09-25, `.claude/judge-probe.py`:** the judge itself, handed twelve last messages in a scratch project at enablement — four coordinator stalls, four pauses or results, two builder claims with no evidence, one hand-back with command lines, one stop — decided all twelve as intended, 6–12 seconds a call on haiku. It can tell a stall from a pause when asked; it has still not met a stall in a real run. `claude plugin eval` has opened (2.1.269) and `evals/` is its suite; the judges stay experiments, not a layer to extend, until a run catches the stall they name. **Deferred, not killed (user ruling, 2026-09-24):** the same judges as a Claude Mod (function hooks, early access), with a status line, a map pane, a compaction note, a snapshot count after each write and a `confirm` button tool, were built and measured on that branch (`MODS-DESIGN.md` there) and not merged — the Mod judge duplicates an unproven experiment in a second language and, returning without `next`, silenced every other `Stop` hook in the session once armed; the button is a nod where Wonder asks for the user's own words; and the display rides an API that may change without notice. Reopened when function hooks leave early access and a judge has blocked one real stall; the display then comes back alone, opened by the person. The judge text is copied into `enable` and `tenacity` deliberately: a frontmatter cannot point.
**The flow** is five commands the user types in order — `/wonder → /discern → /galvanize → /enable → /tenacity` — with `/genius` as the map; `/discern` runs Invention first where no paths are on record, because nothing in Invention waits on the user (user ruling, 2026-09-25; `/invent` alone still explores without attacking). The flow never advances itself and never hijacks a request that didn't enter it; a stage the user doesn't type has no section in the work file, and that absence is the record.
**The work file is the whole handoff between sessions**, and its design is the part that takes several files to see. One piece of work = `.genius/<slug>/` holding three files with three growth laws: the snapshot `<slug>.md` grows by *scope* and has a 6000-character ceiling (Slices roster excluded); the log grows by *time*, is append-only and is a tree — a root `<slug>.log.md` with one line per branch, and one branch per stage, slice or contract version under `log/` — so appending or answering a question opens one branch and never the whole history; `CONTRACT.md` grows by *slice count* and holds the brief, seams, pinned values, each slice's acceptance criteria (their one home — the snapshot's slice line only links them) and the conventions the build established. Compaction routes each snapshot line by one question — *does this line still constrain work that isn't finished?* — under one invariant: nothing leaves the snapshot except into the log or `CONTRACT.md`, with a link left behind. Cross-work files at `.genius/` (`BACKLOG.md` + `BACKLOG.log.md`, `DECIDED.md`, `HISTORY.md`) have their own format. Where this is written: `genius-file/FILE-FORMAT.md` (the shape), `genius-file/BACKLOG-FORMAT.md`, `genius-file/FORMAT-EDGES.md` (the measurements behind the rules, with commit hashes).
**Two layers run through every file the flow writes**: what *binds* (snapshot, contract, `DECIDED.md`, `CONTEXT.md`, backlog seeds) is rewritten in place when wrong; what *records* (any log, any done file) is appended to and never edited. `errata` owns that rule; `/reconcile` sweeps drift against the repo; `/compact` and `/distill` are the retroactive passes. There is one format, and no recognition of older ones: a file in another shape is read for what it holds and brought to the format when next written to.
**Each rule has exactly one home**, and other skills point at it rather than restate it — the compaction question and its destinations in FILE-FORMAT, the sentence discipline in `record-prose`, the correction moves in `errata`, the seed shape in BACKLOG-FORMAT. When editing, change the owning file and check the pointers; a rule copied into a second skill drifts the first time either is edited.
## How skills are written
- Concept first: each skill carries its purpose, its failure mode, the concept in one bold line, and one threshold that must be honestly true before the next stage. Stage skills also carry a short `## How it runs` list. Every rule states its why in the same sentence; a constraint that can't name its reason doesn't land.
- Action constraints are where the measured value lives and stay firm (interview is live dialogue, red before green, fresh verification, wounds found never manufactured, findings carry evidence). Taxonomies are floors, not scripts.
- Killed designs stay killed unless measured evidence reopens them. Before proposing express paths, sizing calls, autonomy modes, gate checklists in work files, hooks or scripts that parse a work file's prose or decide anything (the judge reads one frontmatter field to know whether to ask; the decision is the model's), skip bookkeeping, or old-format recognition, read the git history — `0cc21de`, `925accf`, `275ed4f`, `f8897e9` each record a ruling and its kill-reason. Reopening one costs a counter-example somebody measured, named against the leg it breaks.
- Commit messages carry the reasoning — what was observed, what changed, why — because the repo has no other record of its rulings.