runcastle 1.6.3 → 1.6.4

package/skills/packs/runcastle/skills/feature/references/rounds.md

@@ -1,97 +0,0 @@
-# Running rounds
-
-Load this when you are about to dispatch a round, or you have just been woken by
-one coming back.
-
-A round is how workers build: each gets one ticket, a clean sandbox and the full
-brief, and works on its own branch that lands on the feature branch. You
-dispatch it, you are woken when it comes back, you check what it did, and you
-plan the next move.
-
-Start the first round only after the human's explicit yes in chat, and ask again
-before any round the agreed plan did not settle (SKILL.md, "The human's yes").
-If designs wait uncommitted in the worktree, the human's yes commits them first;
-an orchestrator relay never does (`./design.md`, section 8).
-
-## What you run on
-
-`get_feature_context` carries:
-
-- `rounds` — every round so far, numbered from 1: the tickets it held, how it ended, its gates.
-- `latestReady` — your newest ready declaration, if any.
-- `driveActive` — the human is test-driving this feature right now.
-- `stopped` — the human pressed Stop and has not replied since.
-- `waitingReason` — why the feature is waiting on the human, if it is.
-- `burnConcurrency` — how many workers the project runs at once.
-
-## Plan a round
-
-1. **Write the tickets** with `emit_tickets`, or reshape pending ones with
-   `update_ticket` / `cancel_ticket`, following `./tickets.md`. Then **dispatch**
-   with `dispatch_round({ seqs })`, naming exactly the pending tickets this round
-   covers. Tickets you do not name wait for a later round. A ticket may stay
-   blocked by tickets that landed or were cancelled in an earlier round: those
-   count as satisfied. A blocker that is still pending or failed must be named
-   in the same round.
-2. **Every worker task names its deliverable and how it is checked.** A worker
-   with no stated check reports success on its own terms. Say what is built and
-   what proves it: a test where one is worth writing, the command that passes, the screen
-   that shows it.
-3. **Keep the round to `burnConcurrency` workers or fewer.** A soft cap: workers
-   past it only queue, and a wider round has more to reconcile when it returns.
-4. **Contract first when the work spans layers.** When workers on different
-   layers must agree on a shape — types, an API, a schema — make one ticket land
-   that contract in code and make the others `blockedBy` it in the same round.
-   **Contracts live in code, never in a doc**: workers trust the code.
-5. **UI work names the design references.** A ticket that touches UI tells its
-   worker which design docs to follow — the project's own design system docs and
-   any design references in this feature's docs — and asks it to plan the
-   screen, build it, then critique it against those docs with screenshots.
-
-Workers do not talk to each other or to you. They report through their digests,
-their ticket status and their commits. A worker that finds the contract wrong
-stops and says so in its digest; reconciling it is your job, between rounds.
-
-## When a round comes back
-
-You are woken with the round's outcome, each ticket's status, the verify-gate
-result, any review findings and where the digests are.
-
-1. **Trust the record over the prose.** Ticket status, the gates and the commits
-   are what happened; a digest is a worker's account of it. Read each digest
-   with `get_ticket({ seq })`, and where the two disagree, believe the record.
-2. **Reconcile.** Did a worker report the contract wrong, or change something
-   another relied on? Did a decision turn out wrong? Fix the contract in code,
-   amend `decisions.md` and `spec.md` when what was decided changed, and update
-   the pending tickets. A contract reported wrong is a reason to re-plan.
-3. **Handle review findings.** A finding stays open until you resolve it: fix it
-   in a round or yourself, or dismiss it and say why. A review reports useless
-   tests as low-severity observations, never defects: when the round you are
-   planning already mints a fix ticket, fold them into it (one acceptance
-   criterion: delete or rewrite the named tests), so they go at no extra sandbox
-   cost. Never mint a ticket only to delete useless tests.
-4. **Decide the next move**:
-   - small leftovers → fix them yourself;
-   - more work, or a failed ticket to retry → plan the next round;
-   - a question only the human can answer → ask it in chat and call `wait_for_you({ why })`;
-   - the feature does what the plan says → run the checks and declare ready (SKILL.md, "Ready for the human").
-
-A failed round is just what came back. Re-plan, retry or fix it yourself.
-`declare_ready` warns when the last round had failures; pass that on.
-
-## While and after the human drives
-
-Never dispatch while the feature is being driven (`driveActive`). Your own
-commits wait until the drive stops. When the human reports back, follow
-SKILL.md, "After a drive"; when you are satisfied again, declare ready with a
-new scenario.
-
-## What the server refuses
-
-`dispatch_round` is refused, with the reason, for a draft or shipped feature,
-while a round is already running, while the human is driving this feature, and
-after the human pressed Stop until they have replied. It is also refused when a
-ticket you name is blocked by a ticket outside the round that is still pending
-or failed (or does not exist): the refusal lists each such edge, and the fix is
-to name that blocker in the round too. `stop_round` stops the running round;
-work that already landed stays.

package/skills/packs/runcastle/skills/feature/references/tickets.md

@@ -1,231 +0,0 @@
-<!-- Forked from Matt Pocock's to-tickets skill, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
-
-# Writing tickets
-
-Load this when work is worth handing to sandboxed workers and you are about to
-write, reshape or cancel tickets. Whether it is worth it is your call (SKILL.md,
-"Build it the cheapest good way"): parallel pieces, work too big for your own
-window, or long unattended work. Anything else you build yourself.
-
-Break the work into **tickets** — vertical slices, each cutting end-to-end
-through every layer it needs, each big enough to be worth a whole agent session
-and small enough to finish inside one — and emit them with
-`mcp__runcastle__emit_tickets`. Synthesize from `spec.md` and the conversation.
-The feature's existing tickets come as summary rows in `get_feature_context`;
-`mcp__runcastle__get_ticket({ seq })` holds one ticket's context, acceptance
-criteria and digest.
-
-## The one thing that makes a runcastle ticket different
-
-Each ticket is executed by a **single fresh agent, alone, in a sandbox, with
-~100k tokens and NO way to ask a follow-up question.** It sees only what you put
-in the ticket plus the code already in the repo. So — *inverting* the usual
-"avoid file paths, they go stale" rule — the ticket's `context` field **must be
-concrete and self-sufficient**: name the files to touch, the existing patterns
-to copy, the type/schema shapes, the gotchas, the commands to run and verify
-with. A ticket that assumes the agent can ask "where does X live?" is a broken
-ticket. Over-specify context; under-specify nothing.
-
-## The second thing: a ticket costs ~10 minutes before it does any work — and pays it twice if it overruns
-
-That fresh agent is fresh *every time*. Each ticket gets its own container: cold
-build, a full dependency install (measured 70–507s, ~2.5 min average), then an
-agent that re-reads the spec, the docs digest, and every file your `context`
-names — reading the repo was 16% of all agent time across 42 measured attempts.
-**This overhead is paid per ticket and is the same whether the ticket is twenty
-lines or a day's work.** Splitting one coherent piece of work into three tickets
-triples it, and adds two seams where a new agent has to reconstruct what the
-previous one had just finished learning.
-
-But that meter runs both ways. A ticket too big to finish in one pass gets no
-cheap second wind: an iteration is not a retry (ADR-0008) — the container is
-rebuilt, the install runs again, and a brand-new agent re-reads everything from
-the last commit, having lost every conclusion its predecessor reached.
-
-So size a ticket to **earn its container and still land in one pass**:
-substantial, with room left at the end for the tests, the self-review and the
-commits. Fine-grained slicing belongs *inside* a ticket, as the
-`acceptanceCriteria` list: the worker works through the criteria and
-commits each finished slice, so one ticket with six criteria orients once; six
-one-criterion tickets orient six times.
-
-Expect a **handful of substantial tickets** for a feature — roughly 4–8, each
-worth a session. A dozen thin ones means you sliced by layer or by file, not by
-behaviour. Two or three giant ones means you will pay back the containers you
-saved, with interest, when they overrun.
-
-## 1. Draft vertical slices
-
-<vertical-slice-rules>
-- Each slice cuts a narrow but COMPLETE path through every layer it needs (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer.
-- A completed slice is demoable or verifiable on its own.
-- Each slice is worth one fresh ~100k-token agent session working alone and **lands inside it** — leave room for the orientation at the front and the tests, self-review and commits at the back.
-- **Merge when a merge test holds.** Two drafts are one ticket if they touch the same files, share a type or module, or the second one's first act would be re-reading what the first just wrote. Same for the obvious siblings of one behaviour: create/edit/delete of a resource, an endpoint and the UI that calls it, code and the tests that cover it.
-- **Split only for a real reason:** (a) a genuine gate — the later work cannot be written until the earlier work's interface exists; (b) the combined work would not land in one session; (c) a prefactor, which is its own slice done first ("make the change easy, then make the easy change"); (d) parallel width, under the rule below; (e) the wide-refactor sequence below.
-- **Not reasons to split:** one ticket per file, layer, endpoint or component; keeping each ticket easy; keeping diffs small; separating tests from the code they test.
-- **Parallelism pays when the halves are file-disjoint.** Tickets with no blocking edge burn concurrently, each on its own temp branch, landing one at a time (ADR-0002) — so two substantial slices touching *different* files buy real wall-clock. Two touching the *same* files race to land, and the loser fails on a merge conflict: that width costs a re-burn. Overlapping files → merge.
-</vertical-slice-rules>
-
-Give each ticket its **blocking edges** — the tickets that must finish before it
-can start. The field is required: a ticket with no blockers gets an empty array.
-
-<review-ticket>
-**The review ticket.** Every feature ends with one, unless the human does not
-want it (SKILL.md, "Every feature ends with a review round"). Add **one** ticket
-with `kind: "review"`, blocked by every implementation ticket whose work it
-checks, or by nothing when you built the work yourself. It is not a slice: it is the brief for the agent that exercises the
-*integrated* work on the feature branch and reports what it finds as findings.
-Its `goal` says what to verify and its `acceptanceCriteria` are the things to
-check off, one per behaviour worth confirming — the review agent walks them in
-order. `emit_tickets` refuses a ticket *titled* like a review but carrying
-another kind: set the kind (or retitle it) and re-emit.
-
-The review agent works in **exactly one of two modes**, never both — a browser
-**Drive** of the app against your acceptance criteria, or **Gates**: the
-project's verify commands plus a two-axis read of the diff. Reviews that
-attempted both ran long or died having delivered neither.
-
-Make the choice obvious. Prescribe a walkthrough only when there is genuinely a
-surface to walk, in plain prose ("open the settings flow, add a project, check
-the empty state"), and write the `acceptanceCriteria` as the steps of that walk.
-When the work changed nothing a human could drive — prompt contracts, docs, an
-internal refactor, a backend-only change — say so in the ticket, and write
-criteria the gates-and-diff read can check off.
-
-**Say what to walk, never which mode.** A review ticket never directs the agent
-to Gates — no "Mode: Gates", no "skip the drive" — and the mode is the review
-agent's call from the surface you describe. Least of all give as the reason that
-the change "isn't deployed or installed yet": the drive boots **the branch** —
-the project's drive setup points it at the checkout's own code, migrations and
-assets precisely so a branch is visible in its own drive. A review ticket once
-prescribed Gates on exactly that reasoning, and a UI feature reached the human
-without ever being driven. If the state to check does not exist yet in a fresh
-drive, the `acceptanceCriteria` say how to produce it inside the drive, as far as
-the project's drive instructions allow, and then what to check.
-
-The review agent never edits code, so its ticket needs no `seams` beyond the
-surface it exercises, and finding bugs is a *successful* review. Its digest
-carries a prose summary of what landed, which the Review view leads with, so
-`goal` asks for the verification, not for the summary.
-</review-ticket>
-
-<parallelism-budget>
-**Budget the parallelism explicitly, before you emit.** A round runs up to
-`burnConcurrency` tickets at once (from `get_feature_context`), but a ticket
-cannot start until every ticket in its `blockedBy` has landed, so a round's
-wall-clock is set by its **critical path**: the longest chain of blocking edges.
-A chain of N tickets is N sequential sandboxes however wide the pool is.
-Measured at `burnConcurrency: 3`, three consecutive batches whose tickets each
-chained end to end came in at **1.09x, 1.16x and 1.00x** — the width was there
-and never spent.
-
-So, after slicing, **say it out loud in the session**:
-
-- the **critical path** — the longest chain of implementation tickets, named in order, and its length;
-- **how many tickets can run at once**, against this project's `burnConcurrency`;
-- whether that clears the bar: T implementation tickets at concurrency C want a chain no longer than roughly **T / C**.
-
-**When it does not clear the bar, reslice.** **A blocking edge is true only when
-the later ticket reads the earlier one's output**: a file it writes, a type or
-interface it defines, a schema it migrates, a stub it fills. "Related", "same
-area", "logical reading order" are not blocking edges — drop them. Where the
-edge is real, merge the two into one ticket, or pull the shared foundation
-forward into the blocker so everything else goes wide behind it.
-
-A review ticket is the tail by definition: measure the critical path over the
-implementation tickets and add it. Width only counts if it lands: parallel
-tickets touching the same files collide on landing.
-</parallelism-budget>
-
-<ship-a-scenario>
-**Ship a scenario when the state is hard to reach.** A scenario is a project
-command under `.runcastle/scenarios/` that seeds a state and prints the URL to
-land on, so a test drive starts where the feature is instead of on a blank app.
-Read `get_feature_context`'s `scenarios` field — `{ setUp, runnerConfigured,
-scenarios, fixtures }` — before you decide anything.
-
-**When `setUp` is true**, ask of each ticket: will the person driving this have
-to build state by hand to see it — an account, a cart with an expired coupon?
-
-- If yes, give the implementation ticket that builds that state an acceptance criterion: "Ship `.runcastle/scenarios/<group>/<name>.<ext>` that seeds <state> (reusing `_fixtures`) and prints `ENTRY_URL=<where>`". Name the fixtures it should reuse. When the change is an API call, the criterion also ships a sibling `.http` file at the same path with the request, and the scenario prints `TOKEN=` when the call is authenticated.
-- Name that scenario in the review ticket's `context`, if there is one, so the reviewer replays it rather than improvising the setup; and use it as the `scenario` you declare ready with.
-- Copy changes and settings toggles get none. A scenario earns its place only where reaching the state is the chore.
-- The worker writes and typechecks the scenario but cannot run it — a sandbox has no drive.
-
-**When `setUp` is false**, card nothing about scenarios. Tell the human once
-that ＋ New scenario in a test drive sets scenarios up for this project.
-</ship-a-scenario>
-
-<wide-refactor-exception>
-A **wide refactor** — one mechanical change (rename a column, retype a shared symbol) whose blast radius breaks thousands of call sites at once — cannot land green as a vertical slice. Sequence it **expand → migrate → contract**. Expand: add the new form beside the old so nothing breaks (one ticket). Migrate: move call sites over in batches sized by blast radius (per package/dir), each a ticket blocked by the expand, green throughout because the old form still exists. Contract: delete the old form once no caller remains, blocked by every migrate batch. If even the batches cannot stay green alone, let them all block a final integrate-and-verify ticket — green is promised only there.
-</wide-refactor-exception>
-
-<preview-screen-block>
-When the feature has a `preview.html` and a ticket **builds a screen that appears in it as a screen block**, point that ticket at **one named screen block**, never the file. Its **context** names the path (`docs/features/<slug>/preview.html`) and the block name, and tells the worker to find the two markers, `<!-- screen:<name> -->` and `<!-- /screen:<name> -->`, and **read only the lines between them**. Say plainly that the block shows the approved look and behaviour and **is not the implementation**: build it with the project's real components and never copy the mock's markup. **Never tell a worker to read the whole file.**
-
-A ticket with no screen does not mention the preview.
-
-A **designed-screen block** holds no mock. It names a component committed in design mode and its preview page. Point the ticket at that component file and that preview page path, not at markup.
-</preview-screen-block>
-
-<connect-designed-screens>
-A ticket that wires a **designed screen** (one committed in design mode, `design: …` commits on the feature branch) names the committed component and its preview page in its `context`, and says plainly that **the look is approved**. Its job is to **connect, never restyle**:
-
-- swap the sample data for real data (queries, API calls);
-- add the behaviour the design left out;
-- change markup only where the wiring needs it.
-
-When wiring forces a visible change (a field the design lacked, say), the worker calls it out in its digest.
-</connect-designed-screens>
-
-## 2. Build each ticket to the schema
-
-Emit an array of `TicketInput`. Number them from 1 in the array in **dependency
-order (blockers first)**; `blockedBy` holds those numbers.
-
-Each ticket:
-- **title** — `{group}: {task}`, in the domain vocabulary: `Checkout: apply the coupon at payment`.
-- **goal** — the end-to-end behaviour this ticket makes work, from the user's/caller's perspective. Not a layer list.
-- **context** — everything the sandboxed agent needs and cannot ask for: file paths, patterns to follow, type/schema shapes, gotchas, how to run and verify. Be concrete.
-- **acceptanceCriteria** — `string[]`, each independently *verifiable* (a behaviour you can observe, a command that passes). Four to eight on a substantial ticket is right; a list running well past that will not land in one pass. Criteria are observable behaviours; ask for a test as a criterion only for a bug repro or a contract worth protecting, never for its own sake. A ticket that fixes red round gates names the failing command and test files in its `context` and has one criterion that re-runs them narrowed (never the full suite — the host runs that once per round). A review reports useless tests as low-severity observations, never defects: when the round already mints a fix ticket, fold those observations into it as one criterion (delete or rewrite the named tests), and never mint a ticket only to delete useless tests.
-- **seams** — `string[]`, the public interfaces to test at (from the spec's Seams; prefer existing, prefer the highest, prefer one).
-- **blockedBy** — `number[]`, **required**, only true gates; `[]` when there are none.
-- **kind** — `"implementation"` (the default, omit it) or `"review"`.
-- **model** — optional, and usually omitted. See below.
-
-### Assigning a model (only from the annotated roster)
-
-`get_feature_context` returns `annotatedModels`: `{ id, runtime, note }` for the
-models the human wrote a use-case note against. That list is the *entire* set
-of ids you may use.
-
-- **Empty list → never set `model`.**
-- **Non-empty → set it only where a note plainly fits the ticket.** Unset is the good default.
-- **Never invent an id**, and never write one not in `annotatedModels` — the store rejects it and the whole batch fails to emit.
-
-## 3. Self-check, then emit
-
-Check yourself, in this order:
-
-1. **Can any two of these be one ticket?** Take them pair by pair; merging changes the rest.
-2. **Would any one overrun?** Split it where its files stop overlapping.
-3. Is each survivor a demoable vertical slice, worth a session?
-4. Are the blocking edges minimal and true? State the critical path and the width against `burnConcurrency`, and reslice if the chain runs longer than roughly total / concurrency. Do independent tickets touch different files?
-5. Is every `context` self-sufficient for an agent that cannot ask?
-6. If you chose a review, is there exactly one `kind: "review"` ticket, blocked by the work it checks?
-7. If `scenarios.setUp`, does every ticket that builds hard-to-reach state ship a scenario for it?
-
-Then `mcp__runcastle__emit_tickets({ tickets: [...] })` — **emit the array; do
-NOT write ticket files.** It returns `{ stored, ids }`, logs the timeline event
-itself, and opens the **Work** view beside the chat. Emit the **whole batch,
-fully enriched, in one call**; never emit placeholder contexts to enrich
-afterwards — a round dispatched mid-enrichment burns workers on placeholders.
-
-## Reshaping tickets later
-
-When something changes after tickets exist, walk the ticket list against it:
-
-- Stale but still needed → `update_ticket({ id, ...changed fields })` (pending or failed only).
-- No longer needed → `cancel_ticket({ id, reason })` (pending or failed only).
-- New work → `emit_tickets` again; tickets accumulate on the feature.
-- Landed work now wrong → a NEW ticket that corrects it. Never touch landed or running tickets.

package/skills/packs/runcastle/skills/prepare/SKILL.md

@@ -1,148 +0,0 @@
----
-name: prepare
-description: Establish a project's host settings with evidence — the dev command, the drive setup/stop scripts, the dev-database reset — by running them on the developer's own machine rather than guessing them from config. Covers the drive contract, the scenario contract it feeds, discovering a project's shape, and the closing dry-run drive. Entry skill for kind=prepare sessions.
-disable-model-invocation: false
----
-
-# Prepare — establish this project's host settings
-
-A preparation session runs in the developer's **real checkout on their own machine**, not in a sandbox. That is the whole capability it exists to use: every setting here can be *run* instead of guessed at, and a value with an account of itself is worth more than a value that merely looks plausible.
-
-Your system prompt carries the per-session facts — the repo path, which keys are still open, what has already been established and how stale it is. This skill is the method.
-
-## The order of the conversation
-
-1. Open by naming what is still open and what you need from the human for each. Do not survey the repo first; the prompt already told you the gap.
-2. Work the keys **one at a time**: propose, ask, run it if they agree, record it.
-3. If the open keys touch the drive loop, author the machinery (below) before you record the two hook commands — the settings are invocation lines for scripts that must exist.
-4. If the repo builds with a toolchain the sandbox image does not carry, author its Dockerfile (below) — the sandbox keys are worth nothing in an image that cannot run them.
-5. Close by proposing a dry-run drive (below). Values that have never been driven look exactly as trustworthy as values that run perfectly.
-
-**Ask before you act.** Anything that starts or stops a service, creates or migrates a database, installs software, or writes outside the repo needs the human to agree first: say what you are about to run and why, then wait. Their own stack is running next to yours.
-
-## The eight keys
-
-Four describe the drive loop and can only be settled here:
-
-- **`devCommand`** — spawned in a drive-owned terminal pane for the length of a test drive. The first localhost URL it prints becomes the "Open app" link.
-- **`driveSetupCommand`** / **`driveStopCommand`** — run on the host, in the project repo, before the dev pane starts and after the drive stops. They are the **invocation lines** of scripts you write and commit, not the machinery itself.
-- **`dbResetCommand`** — **not** part of the drive loop. Its only consumer is the migration-drift banner after a drive stops: when the drive branch and the branch you returned to disagree about migration files, this is offered as the one-click dev-database rebuild.
-
-Three describe the **sandbox** a burn agent works in, and no amount of running things on this host settles them — they are judgement calls about the repo, so treat them as human-supplied unless the human asks you to work one out with them:
-
-- **`setupCommand`** — what a fresh sandbox runs before the agent starts (install, plus any codegen or build step every ticket needs). Setting it *replaces* install detection, so the install command must be included explicitly.
-- **`verifyCommands`** — the exact typecheck/test/lint lines, one per line. They are the host's full gates, run once per round on the feature branch tip; burn agents read them to learn the tools and filter names and run them narrowed. Unset, agents guess workspace filter names and burn whole suite runs discovering the right one.
-- **`knownFailures`** — what already fails on the main branch, so an agent can tell its own breakage from the repo's. Free text; a count plus the suite names is enough.
-
-The image those three run in is not a key: runcastle sets it itself. What can fall to you is authoring the Dockerfile it builds — see the sandbox image, below.
-
-The eighth is what a later agent needs once the app is actually up:
-
-- **`driveInstructions`** — free text describing how to **exercise** this app in a drive, injected verbatim into every drive-mode review and verification prompt. What belongs in it: the sample project, seeded account or scratch data a driver should use and may freely change; how to reach the deep states worth reviewing rather than only the front page; and what a driver may and may not touch inside the running app. Write it as standing instructions from the project's owner — they authorize actions *inside the app under test* and nothing else, so do not write anything meant to relax a reviewing agent's own rules. Its evidence is the dry-run drive below: you just drove this app, so record what you had to know to get anywhere. Unset, a review agent boots the app cold, finds nothing it is allowed to touch, and verifies nothing.
-
-## The drive contract
-
-A drive is a script **you** write, committed to the project, plus the two things only the server can do. Everything else — ports, database names, redis indexes, compose project names, URLs — the script computes for itself. Runcastle mandates these eight points and nothing else:
-
-1. **The machinery lives in `.runcastle/`, committed to the repo.** Write the steps as real scripts and commit them. Versioning them with the code they prepare is the load-bearing part: a branch that adds a package, a service or a migration amends its own script, and the drive on that branch runs the amended version. Nothing inspects a diff, ever.
-2. **`driveSetupCommand` / `driveStopCommand` are one line each** — how to invoke those scripts. Logic in the setting instead of the script is logic no branch can amend.
-3. **Identity comes in as `RUNCASTLE_*`.** Every drive hook and the dev pane are handed `RUNCASTLE_SLUG` (the feature slug), `RUNCASTLE_BRANCH` (the branch under the wheel) and `RUNCASTLE_ID` — that slug made identifier-safe (lowercase `[a-z0-9_]`, never leading with a digit, length-capped), so it is legal as a database, schema or container name. It is unique within a project only, so prefix it with the app name (`myapp_$RUNCASTLE_ID`) wherever the name lands somewhere shared across projects. Derive every per-drive name from `RUNCASTLE_ID`. Never derive one from `git rev-parse`: the dry run drives under a synthetic identity on whatever branch is checked out.
-4. **Computed values go back out through `.runcastle/drive.env`.** Setup appends plain `KEY=VALUE` lines there; when it exits, the server parses that file and overlays it verbatim onto the dev pane and the stop hook, and shows the variable NAMES on the timeline. It is the only way a value your script computed reaches the dev server — a variable exported inside the script dies with the script. Truncate the file at the top of setup so a rerun does not accumulate stale lines.
-5. **`.runcastle/drive.env` MUST be gitignored.** Add the entry yourself. The server deletes the file when a drive ends, but a scratch file holding a connection string must never be one `git add -A` away from a commit.
-6. **Every step is unconditionally idempotent.** Install, migrate, seed, compose up — run them every time, never behind a "has anything changed?" check. A no-op on a clean tree is cheap; a skipped install on a branch that added a package is a dead drive. This is how the loop absorbs whatever a feature branch changed with no delta detection anywhere.
-7. **Exit 0 means the services are actually up.** The waits belong INSIDE the script — `docker compose up --wait`, a `pg_isready` loop, curl-until-healthy — because the dev pane starts the instant setup returns. The server waits for the app itself; it will not wait for your database.
-8. **Everything the app needs to reach its data goes out through `.runcastle/drive.env`** — above all the database URL, plus any cache or queue URL the app reads. Scenarios (below) and the dev server both get exactly that overlay and nothing else. A setup that hands the database to the dev server some other way — writing the app's own `.env.local`, say — leaves every scenario seeding the wrong database, or none, while the app looks fine.
-
-Stop undoes what setup made, **for this identity only**: drop the database it created, take its compose project down with its volumes, free its ports. The human's own stack is never yours.
-
-Writing those files is the one exception to a preparation session not editing the repo: you may write `.runcastle/` and `.gitignore` in this checkout and nothing else — a hook enforces it. Show the human the script before you commit it; it is their repo and their PR.
-
-## Scenarios
-
-A drive can land the human in a seeded state instead of a blank app. That is the **scenario contract**, a peer of the drive contract above:
-
-- A scenario is a file at `.runcastle/scenarios/<group>/<name>.<ext>`, committed. The folder is the group (`checkout/` → Checkout), the file name the display name (`expired-coupon.ts` → Expired coupon). Files and folders starting with `_` (e.g. `_fixtures/`) are shared code, never listed.
-- The project's **scenario runner** is one command with a `{file}` placeholder (`bun {file}`, `bin/rails runner {file}`). Runcastle runs it in the drive's checkout with the `RUNCASTLE_*` identity, the `drive.env` overlay (point 8 is why that overlay must carry the database), and a fresh `RUNCASTLE_SCENARIO_RUN` per run that keeps entities unique.
-- It prints `ENTRY_URL=<url>` (the last wins; relative resolves against the drive URL), and optionally `TOKEN=<value>`, a credential for API calls.
-- A sibling `.http` file at the same path (`feed/blocked-only.ts` + `feed/blocked-only.http`) is that scenario's API call, sent from the drive's API view with **Try it**.
-
-**You do not set scenarios up.** Record no runner, write no drive-only login route, add no fixtures. The first ＋ New scenario chat in a drive does all of that, where it is proven by landing the human; a route written blind here is not. Your part is point 8: a `drive.env` that carries the data.
-
-## Discover the shape before you author anything
-
-Projects differ in every dimension this touches, and a script fitted to a project you imagined is worse than no script at all. Your system prompt reports what the server could probe for itself — the platform, whether there is a compose file, whether `.runcastle/` already exists, which lockfile is present. Take those as read and find out the rest, by reading the repo and running things here:
-
-- **Workspace layout** — one package or a monorepo with workspaces, and which package the app actually is. Install, migrate and seed each run from somewhere specific.
-- **The services the app needs to boot** — database, redis, queues, object storage, a second process. Read the config and the env example, then confirm with the human.
-- **Whether the human actually uses docker for this project.** A compose file in the repo is not consent to run it.
-- **Hosted or local data stores** — a local postgres you may freely `createdb` on is a very different recipe from a hosted one where you may only branch or add a schema.
-- **How the app loads its environment** — see the audit below.
-
-Then write the smallest script that brings THAT shape up. For worked shapes to adapt — postgres-per-drive, docker compose, redis, hosted databases, deterministic ports — read `references/recipes.md`. They are illustrations, not a library: take the idea and fit it to what you found, in the language this host actually runs.
-
-## Audit how the app loads its environment
-
-The overlay is process environment, which beats a `.env` file in dotenv, Prisma and Next by default. One pattern defeats it: a loader told to clobber what is already exported — `dotenv.config({ override: true })` and its equivalents — ignores everything the script computed and quietly keeps the app on the shared database. That is a drive that looks perfect while testing the wrong data. No machinery can detect it; you are the detector.
-
-Grep the app's entry points and config for env loading and decide, for each, which side wins. Where the process environment loses: get it fixed — you may not edit app code from this session, so propose the change (usually dropping `override`) and let the human make it — or, if it must stay, record the finding with `record_event` naming the file and what it breaks, so the first confusing drive is not a mystery.
-
-## The sandbox image
-
-Burn agents do not work on this host; they work in a container. The image runcastle builds carries a JavaScript toolchain and the agent CLIs — Node, Bun, git, curl — and nothing beyond that, so a repo that builds with a JDK, a Python, a Go compiler or a Rust toolchain cannot run its own `setupCommand` there: the burn dies on `mvn: not found`. The fix is a Dockerfile committed at **`.runcastle/sandbox/Dockerfile`**. Runcastle detects it, builds it as this project's image, and every burn runs in that image from then on.
-
-Deciding whether this project needs one is part of this session — you are in the real checkout, which is where the evidence is. Read the manifests at the root and in each workspace:
-
-- `pom.xml`, `mvnw` — a JDK and Maven
-- `build.gradle`, `build.gradle.kts`, `gradlew` — a JDK and Gradle
-- `pyproject.toml`, `requirements.txt` — Python and its installer (pip, or uv where the project uses it)
-- `go.mod` — Go
-- `Cargo.toml` — Rust
-- `Gemfile` — Ruby
-
-A mixed repo gets the union: a service in Go beside a Java client needs both. Anything else the project shells out to in its setup or verify commands and the stock image lacks belongs here too — a database client, a protobuf compiler — on the same evidence, that you saw it in the repo.
-
-**A JavaScript-only repo gets no Dockerfile.** The stock image already covers it, and an unnecessary project image is one more thing to build, rebuild and keep fresh in exchange for nothing. Do not write one to be helpful.
-
-When the project does need one, what you write:
-
-- **It starts `FROM sandcastle:runcastle`** and layers onto it. That base is what keeps the agent CLIs, git and Node present; a Dockerfile from any other base is not a runcastle sandbox, and burns in it fail on the agent binary before they ever reach the toolchain.
-- **Read the stock Dockerfile before you write a single install line**, rather than assuming its distro or package manager. It is the build context runcastle scaffolds at `~/.runcastle/sandbox-build/Dockerfile` once the image has been built on this machine, and it also ships inside the installed runcastle package as `sandcastle-template/Dockerfile`. Follow its idioms — the same package manager, the same flags, the same cleanup at the end of the layer. If you cannot find it, ask the human instead of guessing what you are layering onto.
-- **The toolchain only, never the project's dependencies.** Install the JDK and Maven; do not run `mvn install` or `go mod download` at build time. Dependencies are what `setupCommand` installs per burn, from the branch's own manifests — anything baked into the image is stale the first time a branch adds a package.
-- **No package caches in layers.** Do not prime `~/.m2`, `~/.gradle`, `~/.cache/pip` or the Go module cache in a `RUN` step. Download caches are mounted into the sandbox from the host, which is how they stay current across burns; a cache baked into a layer is weight the image carries and wrong the moment a lockfile moves.
-- **Keep it minimal** — one `RUN` block where the package manager allows it, versions pinned only where the project pins them, nothing added "while we're here". Every line is a line someone maintains.
-
-It is committed project machinery, exactly like the drive scripts, for the same reason: a branch that changes the toolchain amends its own Dockerfile, and burns on that branch get the amended image. Writing it falls under the same exception — `.runcastle/` and `.gitignore`, nothing else — and the same courtesy: show the human the file before you commit it.
-
-If `.runcastle/sandbox/Dockerfile` is already there, read it and **edit conservatively**. Someone chose those lines, and a customization you do not recognize is still a decision. Say what you probed and what you think is missing — "I see `pyproject.toml` but no Python in the image" — and let the human decide. An existing Dockerfile that covers what you found needs no edit at all.
-
-**You never build the image.** That is a watched terminal action the human takes: the Enable AFK burns card offers **Build image**, and on a successful build runcastle points this project at the image itself — there is no image setting for you to work out or record. So end on it. Tell them the Dockerfile is written (or already right), that the card now offers Build image, and that burns use the project image after that click; until then they keep running in whatever image they run in today.
-
-## Recording what you establish
-
-One `record_finding` call per key, and `evidence` is not optional in spirit: record what you ran and what it printed, or what the human told you. A value with no account of itself is a guess with a source field.
-
-`userSupplied` is the one flag worth being careful with. **True** means the human GAVE you this value or confirmed it verbatim — that marks it as theirs and permanently stops automatic runs from overwriting it. Leave it **false** for anything you worked out yourself, even with them watching; that stays improvable by a later run. Getting this backwards silently retires a field from preparation forever, and the only way back is the human clearing it.
-
-Secrets: this is a development environment and the human has agreed to supply real connection strings and credentials here. Store them as given. Do not paste a secret into a timeline note or a commit message — `record_finding` is the only place a value belongs.
-
-## Closing move: propose a dry-run drive
-
-Once the open drive keys are recorded, end the session by proposing one. Recorded values that have never been driven look exactly as trustworthy as values that run perfectly, and the first person to find out otherwise is someone mid-feature with a broken environment.
-
-**Ask first.** This starts services and creates a database on their machine. Name what will run — the setup command, the dev command, the stop command — then wait. If they decline, end the session normally: the keys simply stay unverified, and the drive UI will keep saying so.
-
-On a yes, `dry_run_drive({ action })` runs it in two halves and you inspect between them:
-
-1. **`start`** — the server runs `driveSetupCommand` with the identity variables, reads back the `.runcastle/drive.env` it wrote (the reply lists the variable NAMES it parsed) and spawns `devCommand` in a real drive pane under that overlay. Identity is the reserved slug `prep-dry-run`, so `RUNCASTLE_ID` is `prep_dry_run` (in every project — the id is unique within a project only) and a script deriving from it makes e.g. `myapp_prep_dry_run`, on the current branch. Nothing is checked out.
-2. **While it is up**, check what the server cannot: the variable names came back as you meant them — and they include the database URL, or whatever the app reaches its data by (point 8). If they do not, the app is getting its data some other way that scenarios cannot see: tell the human, fix the setup script to write it to `drive.env`, and drive again. That holds for an existing setup you did not write, too. Then: the temp database exists and is FRESH, the migrations applied, and the app actually RESPONDS at the sniffed URL — the server waits for it to answer before "Open app" goes live, but only you can say the page is the right one. `status` gives you the pane and the URL while you work.
-3. **`stop`** — the server runs `driveStopCommand` under the same overlay. Then check the cleanup: temp database gone, no orphaned process, container or volume left behind.
-
-Anything off at any step, fix it — amend the script, or `record_finding` for a key — and run the WHOLE thing again until a pass is clean. Watch especially for a `myapp_prep_dry_run` left standing after the stop: an idempotent setup will happily reuse it on the next start, so a teardown that never worked reads exactly like a drive that did.
-
-The verified stamps are computed server-side from what the machinery observed, and only on a clean full pass. You cannot mark your own homework: your deeper checks decide whether to retry, never what gets stamped.
-
-Close with one line telling the human that ＋ New scenario in their next test drive sets up scenarios, so a drive can land them in the state they want to test.
-
-## When nothing is open
-
-If your system prompt says every key is already set, this session is a **confirmation**, not a preparation. Say which values are recorded and how stale they are, ask the human whether they still hold, and stop. Do not re-derive a settled value, and do not propose a dry run unasked — replacing a measured value with a fresh guess makes preparation worse, not better.