@marver-design/marver 0.21.0 → 0.22.1

package/templates/instructions/context.md

@@ -0,0 +1,123 @@
+# Context - what the product is, kept true
+
+The project's knowledge lives in `context/`, beside `design/`. Code says what is implemented;
+`context/` says what is available, how it works, why, and what is next - with evidence. The canvas
+reads the same files: every feature and project board wears the status they record.
+
+## At the start of a session
+
+Read `context/INDEX.md`, then at most two more files per question. The index routes; it never
+explains. If there is no `context/`, see "Setting up" below before you invent answers.
+
+## The files
+
+| Path | What it holds |
+|---|---|
+| `INDEX.md` | routing only, under 800 words; its capability table is generated from `map.json` |
+| `shipped.md` | **the only place availability is written** - services by environment, capabilities by who has them; for knowledge work, what was delivered to whom |
+| `product/<capability>.md` | one current contract per capability |
+| `map.json` | which code each capability lives in - the pull-request rule reads it |
+| `playbooks/<name>/PLAYBOOK.md` | how we do things - steps with checks, traps, a run log |
+| `feedback/` | the inbox: one row per piece of feedback, with its state |
+| `plans/` | proposals in flight - a plan folds into its contract when it lands |
+
+## Evidence has levels
+
+Every availability claim in `shipped.md` carries one, with a citation:
+- `confirmed` - observed in a system of record: the deploy job that ran for that service and
+  succeeded, a ci run that executed the suite. Not an environment marked "deployed" - some
+  pipelines mark it when the run stood down.
+- `reported` - a written claim, cited: a changelog line, an ops note.
+- `unknown` - neither, with the reason. An honest unknown is a correct answer.
+
+Never upgrade a level because a claim sounds sure. Commit ancestry says a change is inside a
+revision, not that the revision is running.
+
+## A contract
+
+```yaml
+---
+state: current            # current | proposed | historical
+capability: quote-intake  # the same slug as its feature board
+audience: team            # team | publishable | restricted
+reviewed: { revision: 606ad4e, scope: "apps/quote, db schema", method: "read code and tests" }
+---
+```
+
+Then: what it does and its limits; who can use it and when; how it works; what it touches (frontend,
+backend, database, workers, integrations); invariants; code and tests; decisions; its frames
+(`scene/frame` ids - say which are designed but not built); the PRs that built it; what is still
+proposed; and `## Availability` pointing at its row in `shipped.md`.
+
+- **Read the code to write it.** Cite `path:line` for every behaviour; a test file's existence is
+  not a run.
+- **No status line, no availability** ("live", "on production", "since 30 Sep") - that is
+  `shipped.md`'s alone. The check fails on both.
+- **One answer per rule.** When a plan amends a rule, write the amended rule - never "section 20
+  wins where it differs".
+- **When code and an accepted document disagree,** the contract says what the code does and the
+  conflict goes to the human. Never decide what was intended.
+
+## When you change things
+
+- **Behaviour** - update its contract in the same change. A change that leaves behaviour alone says
+  `no-contract-change: <capability> - <why>` in the pull request body.
+- **A deploy** - write its row in `shipped.md` with the run that proves it (`playbooks/` usually
+  has the release recipe).
+- **A decision** - in the project's decision log, numbered, with what it applies to.
+- **Feedback** - one row per item: source, who, when, what they said, theme, state (`new`,
+  `triaged`, `proposed`, `planned`, then `shipped` or `declined`), and what resolved it. An item is
+  `shipped` only when `shipped.md` shows its fix `confirmed` where it was raised; a `reported`
+  deploy leaves it `planned`, saying what is missing. On closing, draft - never send - a note back.
+
+## Status on the canvas
+
+Feature and project boards wear a status read from these files (the first that matches wins):
+the board's own `"status"` - `archived`, `paused`, or `blocked` with a `"reason"`; Unknown when the
+evidence cannot be read; In progress when an open plan in `plans/` names the capability (filling by
+phase: `<cap>-specs`, `<cap>-lofi`, `<cap>`); Done when `shipped.md` shows it `confirmed` in an
+availability clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled
+back", "planned") and no pre-production place (staging, preview, dev, local, testing) unless it also
+names production; Done, reported when only `reported`; To do when its contract is `state: current`; else Backlog.
+**Done is never set by hand** - `"status": "done"` fails the check. A board finds its capability by
+its own name, or `"capability": "<slug>"` in its JSON.
+
+## Audiences
+
+`team` - everyone with the repository (the default); `publishable` - may appear on a published
+canvas; `restricted` - never tracked by git (keep it under a gitignored `context/private/`). A
+frame that renders a `team` file onto a published board fails the check. A digest of restricted
+material is restricted, however it is labelled.
+
+## Setting up - when there is no `context/`
+
+Context starts with people. Ask, in one message:
+1. Who is involved - the team and their roles; clients, users, partners?
+2. Where does each relationship happen - channels, email, recorded meetings, docs, in-product
+   feedback, canvas comments?
+3. What is private, and who may see what?
+4. How is this project named in shared spaces - keywords, tags?
+
+Then, in order - this is the whole recipe; "set up our context" asks for all of it:
+1. `npx marver context init --kind product` - or `--kind knowledge` when the work is deliverables
+   for clients rather than a product people use. Record the answers in `context/people.md`.
+2. Draft from evidence: the shipped record from deploy runs and the changelog (`unknown` where
+   nothing proves it), a map from the code, contracts for the capabilities that matter now.
+3. Let the canvas read it: `npx marver init --kind <the same kind>` adds the typed folders (it never
+   moves a board); put each feature board in Features (a project in Projects), named after its
+   capability or saying `"capability": "<slug>"`; then `npx marver boards new home --type start
+   --folder start-here`.
+4. Put the check in ci - a step running `npx marver context check` on a full-history checkout
+   (`fetch-depth: 0`) - and make it pass before you hand over.
+
+**Context that exists but is scattered** - specs out of date, nobody sure what is live - is a job
+for `context/playbooks/reorganize-context/PLAYBOOK.md`, not for a rewrite.
+
+## The check
+
+`npx marver context check` - availability only in `shipped.md`, a level and a citation on every
+evidence cell, citations and links that resolve, the index under budget and equal to the map,
+audiences, feedback and contract states, playbook freshness; with `--base <ref>` (or in ci on a pull
+request) a contract change or a stated reason for every mapped change. Exit 0 pass, 1 fail, 2 cannot
+determine (fetch full history - `fetch-depth: 0`). `npx marver context index` rewrites the index's
+generated table after you change the map.

package/templates/playbooks/publish-canvas/PLAYBOOK.md

@@ -0,0 +1,72 @@
+---
+name: publish-canvas
+description: Use this when the canvas should be on a URL - a first publish, a republish after changes, or moving it to a new host. Steps with checks, the traps that have bitten, how to roll back.
+last_success: none
+depends_on:
+  - design/publish.json
+  - design/config.ts
+  - Dockerfile
+  - package.json
+  - "service: the canvas host (Railway or any volume-capable host)"
+  - "account: the host, and Marver Sign In or the canvas password"
+---
+
+# Publish a canvas
+
+The recipe. `design/instructions/publish.md` is the reference - every variable, both gates, the
+host contract; read it when a step here is not enough. Marver maintains this file; record your
+project's values (which account, which domain, which gate) and every run in the log at the end.
+
+## Prerequisites
+
+- `@marver-design/marver` resolves from the registry in `package.json` - a `link:` or `file:`
+  dependency cannot ride to a remote host.
+- The three decisions are made: **which boards ship** (`design/publish.json` - publishing is
+  default-closed), **who gets in** (Marver Sign In by default; the canvas password when nothing
+  external may be in the sign-in path), **collaboration** (a persistent volume for comments, or none).
+- The canvas has a name: `share: { name: "..." }` in `design/config.ts`.
+
+## Steps
+
+1. **Build locally first.** `npx marver build`.
+   *Check:* it lists exactly the boards you meant, `textures:` reports the hi-fi frames asleep, and
+   no warning names a deck with no slide frames.
+2. **Check what ships.** `npx marver context check` when the project has `context/`.
+   *Check:* no `team` or `restricted` file is reachable from a published board; a board's status
+   ships only where its publish row says `"showStatus": true`.
+3. **Commit the host files** - a `Dockerfile` (it gives the build a browser for the glass
+   textures) and a `.dockerignore` with `node_modules`, `design/.dist`, `design/.local`.
+   *Check:* `design/.dist` is gitignored and not in the upload.
+4. **Create the service once:** a persistent volume, `MARVER_DATA_DIR` on it, the gate's variables,
+   `MARVER_TRUSTED_PROXY=1` behind a proxy, `MARVER_CLI_TOKEN` generated (`openssl rand -hex 24`),
+   never chosen. *Check:* the host lists the volume mounted at the path the variable names.
+5. **Deploy** - on Railway, `railway up` from the repository root.
+   *Check:* the deploy succeeds, and the URL answers with the gate.
+6. **Walk it.** Sign in as the owner, open each published board, leave a comment, reload.
+   *Check:* the comment survives the reload, and a second account sees only what its rights allow.
+7. **Write the run** in the log below - date, revision, URL, what was checked.
+
+## Traps
+
+- **The upload is the working tree.** Untracked files and full-resolution images go up with it;
+  `marver build` ships images at full size, and a large `design/assets/` can pass the host's upload
+  cap. Keep heavy originals out of published frames, or out of the upload.
+- **A repository linked to another project uploads there.** Check which project and service the
+  host CLI is linked to before `up` - a canvas deployed onto the app's own service replaces the app.
+- **An ephemeral data directory loses every comment** on the next deploy. The volume is not optional
+  once collaboration is on.
+- **Run one instance.** The comment log is single-writer.
+- **Fonts only on your laptop** render differently in the build container; the glass textures then
+  rest live. Bundle fonts with the project.
+- **A republish never clobbers comments** - the server unions the seeded logs on boot - but tabs
+  already open keep the old textures until they reload.
+
+## Rolling back
+
+Redeploy the previous revision the same way. Comments live on the volume, not in the build, so a
+rollback keeps them; a board removed from `publish.json` hides its threads until it ships again.
+
+## Run log
+
+| Date | Revision | Who | URL | Outcome |
+|---|---|---|---|---|

package/templates/playbooks/reorganize-context/PLAYBOOK.md

@@ -0,0 +1,232 @@
+---
+name: reorganize-context
+description: Reorganize an existing project's accumulated context - specs, changelogs, roadmaps, transcripts, research, boards, agent memory - so a fresh agent can answer what is available to users, how it works, why, and what is next, from the repo alone. Builds a shipped record with evidence levels, writes current contracts for a bounded first batch, adds a checker, reconciles only what that batch covers, and proves the result with a blind before/after eval. Works on a branch and never deletes. Use when specs are out of date, nobody can say what is on production, or context is scattered.
+last_success: none
+depends_on: []
+---
+
+# Reorganize a project's context
+
+`design/instructions/context.md` defines the target - the files under `context/`, what each holds,
+the evidence levels. This is how an agent gets an existing project there. Marver maintains it: it
+was first run on a client project in October 2026 (16 of 16 questions answered before and after,
+with 40% fewer tokens after), and each rule exists because that project, or an earlier draft of this
+playbook, broke it. Record your project's runs in the run log at the end.
+
+**The order matters: truth first, then authority, then files.** Moving documents before you know
+which one is right only relocates the contradiction.
+
+## Done means
+
+A fresh agent with no memory reads `context/INDEX.md` and at most two more files per question, and
+answers correctly - or says "unknown" with the reason - what each production service runs, whether a
+capability is available and to whom, how it works, why, and what is next. Every artifact that
+existed before has a recorded disposition. A blind before/after eval proves it.
+
+## Hard rules
+
+1. **Worktree and branch.** Never main. Never touch the original checkout's uncommitted changes.
+2. **Never delete.** Originals are preserved; superseded ones get a header pointing at their
+   replacement. Delete only proven disposable output, listed in the report.
+3. **Code says what is implemented, not what is intended.** When code and an accepted requirement
+   disagree, record both on the exception list - do not pick a winner silently.
+4. **Evidence has levels.** `confirmed`: observed in a system of record. `reported`: a written claim,
+   cited - a changelog line, an ops note, agent memory. `unknown`: neither. Never upgrade a level
+   because a claim sounds sure. Commit ancestry says a change is inside a revision, not that the
+   revision is running.
+5. **Stable paths stay stable.** Frame ids, board and scene slugs, URLs, comment anchors and asset
+   paths are identities. Do not move them in this pass.
+6. **Read-only outside the repo.** You may read deploy records (`gh`, a provider's status command).
+   You never deploy, migrate, query a production database, or edit agent memory. A read that needs
+   credentials you were not given is an exception-list item, not a workaround.
+7. **No secrets; mind the audience.** Never copy credentials. Record sensitive files by path and
+   hash only.
+8. **History is not rewritten.** Old changelog entries stay as written.
+9. **Bounded scope.** This pass rewrites only what the first batch of capabilities needs. Everything
+   else is inventoried and marked `deferred` - never superseded on a guess.
+
+## Phase 0 - baseline, in this order
+
+1. **The original checkout first.** In `context/reorg/start.md` (written later into the worktree,
+   from notes kept outside it): the revision, every dirty and untracked path with the hash of its
+   **working** file (`shasum`), and the tracked hashes (`git ls-files -s`).
+2. **The worktree.** `git worktree add ../<repo>-context -b context/reorganize <revision>` and work
+   only there from now on. Note that the original's dirty files are not in it.
+3. **Preimages.** Hash every context-bearing file in the worktree. This list is what Phase 9
+   compares against: untouched files must match; edited files must appear on the edit list with
+   their preimage hash and the reason.
+4. **The eval, blind.** Follow `eval.md` (beside this file). The questions go into the evaluated
+   agent's prompt; the **answer key never enters the worktree**. Run the before pass now.
+
+## Phase 1 - inventory, bounded
+
+`context/reorg/inventory.md`:
+- **Every** context-bearing path at file or folder level - docs, plans, changelogs, roadmaps,
+  feedback lists, READMEs inside apps, research, `design/` (boards, briefs, sticky notes, content
+  frames, comments), asset indexes, sync logs, `CLAUDE.md` / `AGENTS.md`, CI and scripts that
+  encode procedure, and the agent's project memory (Claude Code:
+  `~/.claude/projects/<path-slug>/memory/`). Size, last change, one-line role.
+- **Section by section** only for documents that touch the first batch (Phase 4).
+- Everything else gets disposition `deferred`.
+
+Classes: current contract · proposed · historical evidence · decision · release/validation evidence ·
+operational procedure · receipt · generated view · convention · tool state.
+
+Flag, with file and line: status lines in prose; supersession inside a current file ("section 20
+wins"); double homes ("the board is canonical, this file is its digest"); conventions pointing at
+paths that no longer exist; design status phrased as product status; hand-kept counts.
+
+Start `context/reorg/exceptions.md` now and keep adding to it in every phase.
+
+## Phase 2 - the shipped record
+
+`context/shipped.md`, two tables, every cell with an evidence level and a citation.
+
+**Services × environments** - discover the services first (deploy workflow, Dockerfiles, provider
+config), then for each: revision, deployed at, how (pipeline / by hand), evidence level + citation,
+migrations applied.
+- `confirmed` needs the run that deployed **that service** and succeeded - the job inside the deploy
+  workflow, or the provider's own deploy status - not an environment record, which some pipelines
+  mark "deployed" even when the run stood down.
+- Hand deploys leave only prose: `reported`, cite the line.
+- A health endpoint that reports no revision cannot confirm one - note the gap.
+- An API you cannot reach: `unknown`, with the error.
+
+**Capabilities** - implemented (code reference); verified (a test or recorded walk: revision,
+environment, date, scope - a test file's existence is not a run); available (which environment, and
+for which tenants - a flag or setting is separate evidence from the deploy, usually `reported`
+unless someone with access confirms it); contract link.
+
+## Phase 3 - the implementation map
+
+`context/map.json`, machine-readable because the checker reads it:
+
+```json
+{ "capabilities": { "quote-intake": { "paths": ["apps/quote/app/**"], "tests": [] } },
+  "excluded": [{ "path": "apps/run/app/preview/**", "reason": "generated from the canvas" }] }
+```
+
+Enumerate from the code: routes and actions, domain commands, tables and SQL functions, migrations
+(every mechanism - a second app may keep its own schema), queued jobs and schedules, integrations,
+config, tests. Map or exclude each, with a reason. Shared files may map to several capabilities. The
+map is routing, not proof that anything is documented.
+
+## Phase 4 - contracts, the first batch
+
+Pick 5-7 capabilities where the evidence showed contradictions or no contract. For each,
+`context/product/<capability>.md`:
+
+```yaml
+state: current
+capability: quote-intake
+audience: team            # team | publishable | restricted
+reviewed: { revision: 606ad4e, scope: "apps/quote, db schema", method: "read code and tests" }
+```
+
+Then: what it does and its limits; who can use it and when; how it works; what it touches -
+frontend, backend, database, workers, integrations; invariants; code and test references; decisions;
+its lo-fi and hi-fi frames and the PRs that built it; what is still proposed. Read the code to write
+it. Apply the plan's amendments - one answer per rule. Shared rules go once in `context/system/`.
+
+The contracts are independent: one agent each, in parallel, from one shared brief (the rules, the
+format, "no availability, no status lines", and a report back of every code-vs-document conflict and
+the exact sections it now covers, `full` or `part`). Then a second model reviews the batch against
+the code before anything relies on it - on its first run it found 18 overstated or mis-cited claims.
+A shared file maps to every contract whose behaviour it changes, or the pull-request rule misses it.
+
+## Phase 5 - the checker, before reconciling anything
+
+`scripts/context-check.mjs` (or the project's language), wired into existing CI. Inputs: front
+matter, `context/map.json`, `context/shipped.md`, the publish configuration and what it pulls in, and
+on a pull request the changed paths (`git diff --name-only <base>...<head>`, base and head from the
+CI event) and the PR body (from the event payload).
+
+Audiences decide where a file may go: `restricted` is never tracked by git and never published;
+`team` may be committed in a private repo but never published; `publishable` may appear in a
+publish. "Published" means everything a canvas build carries: the boards in its publish config, the
+frames on them, and every markdown import, image, note and asset those frames pull in.
+
+| Rule | Result |
+|---|---|
+| a `state: current` doc has a status line (`^\s*\**status\**\s*:`) - lines, not domain words like a bank account's `verified` | fail |
+| a current doc carries supersession markers ("wins where it differs", "overrides section") | fail |
+| a shipped cell has no evidence level, or `confirmed` / `reported` with no citation | fail |
+| a dead relative link, `?raw` import or asset reference under `context/` or in a frame that renders it | fail |
+| `INDEX.md` over 800 words | fail |
+| a `restricted` file tracked by git, or a `team` or `restricted` file reachable from what a publish carries | fail |
+| a PR changes mapped paths without its contract, and without `no-contract-change: <capability> - <reason>` in the PR body | fail on pull requests |
+| an `unknown` evidence cell | pass - honest unknowns are the right answer |
+| a rule it cannot evaluate (no git history, API unreachable) | exit 2, "cannot determine", printed |
+
+Exit 0 pass, 1 fail, 2 cannot determine. In CI, 2 blocks like 1 - fix the cause (fetch full history,
+grant the read). During this pass, Phase 6 may start on exit 0, or on exit 2 when every
+"cannot determine" is on the exception list with its reason.
+
+## Phase 6 - reconcile, first batch only
+
+For each document that the first batch's contracts now supersede, **only the sections they cover**:
+
+| Material | Action |
+|---|---|
+| amendment-stacked spec | its covered sections get "Superseded by `context/product/x.md`"; the file stays as history; uncovered sections stay `deferred` |
+| mixed spec | covered contract → `product/`; review diary stays; open items → backlog |
+| dated feedback lists | covered items get a resolution: contract + shipped row, or `open` |
+| roadmap in two homes | one editable source; the board renders it (`?raw`) |
+| README with contradictions | fix the covered contradiction; keep run instructions by the app |
+| changelog | untouched; its release lines are cited from `shipped.md` |
+| sync log | keep cursors and pending failures; drop "agent memory" as a target |
+| agent memory | project facts the batch needs land in their repo home; `context/reorg/memory-trim.md` proposes the rest |
+| wrong binding instructions | correct them - an agent will obey them |
+
+Diff duplicate prose before merging; check inbound references after every move.
+
+**Line citations move when you insert.** Every note added to an old document shifts the lines that
+contracts cite. Either reconcile before the contracts cite those documents, or remap every citation
+once, mechanically, from the base revision's lines to the new ones - and verify by content (the cited
+line still says what the citation claims). Never run a remap twice. Prefer line-neutral edits where a
+document is cited heavily.
+
+## Phase 7 - entry point and index
+
+- Root `AGENTS.md` is the shared entry point; tool files route to it. Keep existing binding routes
+  (for example to `design/AGENTS.md`).
+- `context/INDEX.md`, **at most 800 words**, counted by the checker: the product in five lines; the
+  capabilities with their contract and shipped row; where each role lives, including healthy homes
+  left in place; the rules (status only in `shipped.md`; a behaviour change updates its contract or
+  says `no-contract-change`; every deploy writes the record; plans fold into contracts when they
+  land; changelog lines start with kind and capability: `[product:quote]`, `[design:board]`,
+  `[infra]`, `[decision 41]`). Generated parts sit between `<!-- generated -->` fences.
+
+## Phase 8 - the exception list, asked once
+
+Everything collected since Phase 1: `unknown` availability that matters, code-vs-intent conflicts,
+disputed capability boundaries, audience and retention calls, reads that need credentials. Ask in
+one numbered batch now - or immediately, only if an item blocks the next step.
+
+| The human decides | The agent decides from evidence |
+|---|---|
+| intended behaviour where code and an accepted requirement conflict | what the code implements |
+| access, audiences, retention, redaction | inventory, hashes, references |
+| priorities, commitments, pilot scope | what is done vs still proposed |
+| disputed capability boundaries | the initial grouping (reversible) |
+
+## Phase 9 - verify
+
+`context/reorg/report.md`:
+
+| Check | Passing result |
+|---|---|
+| Preservation | untouched files match their preimage; every edited file is on the edit list with preimage and reason |
+| Disposition | every inventoried path is unchanged, edited, superseded (covered sections only) or `deferred` |
+| The checker | exit 0, or exit 2 with each "cannot determine" explained |
+| Release honesty | every availability claim carries a level and a citation, or says `unknown` |
+| Reconciliation | no Phase 1 contradiction inside the first batch survives as competing current text |
+| The eval | the after pass beats the before pass, per `eval.md` |
+
+Then stop. The report lists what moved, what was decided without asking, the open exceptions, what
+was deferred, and the memory-trim proposal. The human reviews the branch; nothing merges on its own.
+
+## Run log
+
+| Date | Revision | Who | Batch | Outcome |
+|---|---|---|---|---|

package/templates/playbooks/reorganize-context/eval.md

@@ -0,0 +1,93 @@
+# Context eval - can a fresh agent answer from the repo alone?
+
+The reorganization is judged by one thing: a fresh agent, with no memory and no chat history,
+answering real questions about the product correctly and cheaply. Run it **before** and **after**,
+the same way both times.
+
+This file is the protocol and the questions. The **answer key is a separate file**
+(`answer-key-<project>.md`) and never enters the worktree the agent reads.
+
+## Isolation - check before each pass
+
+- The agent runs in the worktree (`../<repo>-context`), a fresh process per question.
+- No agent memory for that path: Claude Code keys memory by project path, so
+  `~/.claude/projects/<worktree-slug>/memory/` must not exist. Codex keeps none by default.
+- No hook injects project context for that path (a vault feed keyed by path, a knowledge inbox).
+- The answer key, the reorg notes kept outside the worktree, and earlier pass results are not in
+  the worktree. Before the first pass, `context/` does not exist yet.
+- **A clean profile.** Global instructions also count as injected context: Claude Code loads
+  `~/.claude/CLAUDE.md`, Codex loads its global `AGENTS.md`. Launch with an empty config home and
+  only credentials in it - Claude Code: `CLAUDE_CONFIG_DIR=<empty dir>` with an API key; Codex:
+  `CODEX_HOME=<dir holding only auth>`. Confirm from the transcript's first event that no user or
+  global instruction file was loaded.
+  - *Learned on the first run:* without an API key, Claude Code cannot run clean - `--bare` needs one,
+    and a plain run loads the auto-memory that worktrees of one repository share. Codex with a
+    `CODEX_HOME` holding a copy of `auth.json` works; check `codex features list` shows `memories`
+    off, and keep each pass's session rollouts out of that home before the next pass. Copy the auth
+    only when its `last_refresh` is recent, and delete the copy after.
+- **Read-only.** Claude Code with read tools only (`--allowedTools Read,Grep,Glob`); Codex with
+  `--sandbox read-only`.
+- Same CLI, same model, same prompt, both passes.
+
+## The prompt
+
+> Answer this question using only files in this repository: <question>. Give the answer, the
+> files you used, and your confidence. If the repository cannot settle it, say "cannot tell" and
+> why. Do not run the app, query a database, call an API, or read outside this directory.
+
+## The measurement - one metric, per question
+
+Run each question as its own invocation with a machine-readable transcript (Claude Code:
+`claude -p "<prompt>" --output-format stream-json --verbose`; Codex: `codex exec --json`). From the
+transcript record:
+
+- **result** - correct / partial / wrong / cannot-tell, judged against the answer key;
+- **confident wrong** - a wrong answer given with high confidence, counted separately;
+- **bytes read** - the summed size of every tool result returned to the agent (file reads, searches,
+  listings). Measure what the model saw, not what the command printed: Codex truncates long output
+  (each result carries its `original_token_count`), so read the session rollout's tool outputs, not
+  `exec --json`'s `aggregated_output`. Record the session's **input tokens** beside it;
+- **tool calls**;
+- **out of bounds** - any read outside the worktree. One voids that answer.
+
+"Cannot tell" with the right reason counts as correct where the key says the repository genuinely
+does not hold the answer.
+
+## Pass
+
+- no confident wrong answer after;
+- more correct answers after than before - or, if the before pass was already perfect, equal;
+- fewer total bytes read after.
+
+A capable agent may already answer everything before - the first run's before pass was 16 / 16 at
+medium effort, the traps notwithstanding. Then the pass is decided on cost, and a weaker or cheaper
+profile is worth a second pair of passes to see whether the reorganization moves correctness.
+
+## The six kinds of question
+
+Write 10-16, at least one of each, from Phase 2 evidence, with the key signed off by the human where
+Phase 8 asked:
+
+1. **Shipped** - is X available, where, for whom, since when?
+2. **Behaviour** - how does surface Y work today?
+3. **Interfaces** - what runs behind action Z: jobs, mails, data written?
+4. **Why** - why was decision N taken, and does it still apply?
+5. **Next** - what is being built next, and what counts as done?
+6. **Receipts** - what did someone say about T, and where is it recorded?
+
+Include **traps**: questions where a stale spec, a design frame, or a wrong instruction gives a
+confident wrong answer today. They are the point.
+
+## Your project's questions
+
+Write them before the before pass, from Phase 2's evidence, and keep the key out of the worktree:
+
+| # | Kind | Question | Trap |
+|---|---|---|---|
+
+## Report format
+
+| # | Before: result | Before: bytes / calls | After: result | After: bytes / calls |
+|---|---|---|---|---|
+
+Write the before column before Phase 1 begins - not from memory afterwards.