runcastle 1.2.7 → 1.2.10

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

@@ -1,7 +1,7 @@
 ---
 name: ideate
 description: The runcastle ideation session. Grill the human relentlessly about a feature, lock decisions incrementally into decisions.md, then drive spec and tickets out of the same unbroken context. Entry skill for kind=ideation sessions.
-disable-model-invocation: false
+disable-model-invocation: true
 ---
 <!-- Forked from Matt Pocock's grilling + grill-with-docs skills, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
 
@@ -15,9 +15,17 @@ Everything happens in this one window. **Never compact. Never `/clear`. Never su
 
 ## 0. Orient
 
-1. Call `mcp__runcastle__get_feature_context`. It returns the feature (`slug`, `title`, `oneLiner`), current `phase`, the docs already on disk (`brief.md`, and any `decisions.md` — **this may be a resumed session; read what is already locked and do not re-ask it**), and any tickets.
+1. Call `mcp__runcastle__get_feature_context`. It returns the feature (`slug`, `title`, `oneLiner`), current `phase` and `lap`, the canonical docs inlined in `docs[]` (`brief.md`, and any `decisions.md` — **this may be a resumed session; read what is already locked and do not re-ask it**), an index of every other doc in `moreDocs[]` (fetch one with `mcp__runcastle__read_feature_doc({ relPath })`), and any tickets.
 2. Decisions live at `docs/features/<slug>/decisions.md` in this worktree. The injected system prompt carries the slug and paths; trust `get_feature_context` for the live state.
-3. `mcp__runcastle__record_event({ type: "ideation.started", message: "<feature title>" })`.
+
+**Your tools**, and there are not many — this session's real work is the conversation:
+
+- `mcp__runcastle__get_feature_context` / `mcp__runcastle__read_feature_doc` / `mcp__runcastle__list_tickets` — the record.
+- `mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true })` — park scope creep as a draft feature (§1). `draft: true` is the only door open to you; a full create belongs to the project session.
+- `mcp__runcastle__escalate_to_map` + `mcp__runcastle__emit_waypoints` — the escalation branch (§3). This is the entire entry point into mapped ideation: no other surface charts a map from a linear feature.
+- `mcp__runcastle__complete_phase` — the phase boundaries (§4), and the ones `/runcastle:spec` and `/runcastle:tickets` cross after you.
+- `mcp__runcastle__emit_tickets` — used by `/runcastle:tickets`, not by you directly.
+- `mcp__runcastle__record_event` — the feature timeline. Most state changes already emit their own event; only reach for this when the timeline would otherwise have no record at all.
 
 ## 1. Grill relentlessly
 
@@ -44,9 +52,7 @@ The moment a decision locks, append it to `docs/features/<slug>/decisions.md`
 **Why:** <the reason / the trade-off chosen over the alternatives>
 ```
 
-Keep `decisions.md` free of implementation minutiae — it is the record of *what was decided and why*, the raw material spec and tickets are built from. `complete_phase` checkpoints the file into git for you; you just write it.
-
-Every few locked decisions, `mcp__runcastle__record_event({ type: "decision.locked", message: "<n> decisions locked" })`.
+Keep `decisions.md` free of implementation minutiae — it is the record of *what was decided and why*, the raw material spec and tickets are built from. `complete_phase` checkpoints the file into git for you; you just write it. The file is the record — do not narrate it onto the timeline as you go.
 
 ## 3. Escalation branch — when the feature outgrows this window
 
@@ -67,7 +73,7 @@ Some features are too big for one unbroken context. The tells: you are rabbit-ho
 
 When the human confirms shared understanding and the open questions are answered or explicitly deferred:
 
-`mcp__runcastle__complete_phase({ phase: "ideation" })` → returns `{ ok, nextPhase }`. If `ok: false`, it names what the gate wants (e.g. `decisions.md` missing) — fix it and retry. Then `record_event({ type: "phase.completed", message: "ideation" })`.
+`mcp__runcastle__complete_phase({ phase: "ideation" })` → returns `{ ok, nextPhase }`. If `ok: false`, it names what the gate wants (e.g. `decisions.md` missing) — fix it and retry. It logs its own timeline event; do not add one.
 
 ## 5. Spec → tickets — stay in this window
 
@@ -81,4 +87,4 @@ Do not open a new session for these. They run here, on top of everything you jus
 
 > Tickets are in the runcastle UI. Review the ticket cards and click **Burn** to start the AFK agents. That is the next step — I will stop here.
 
-Do **not** implement anything. Do **not** start burning. The two human clicks (Burn, then Merge after test-drive) are the only gates left, and they belong to the human.
+Do **not** start burning. The two human clicks (Burn, then Merge after test-drive) are the only gates left, and they belong to the human. (You do not write code here either — that rule is in your injected prompt and enforced by the edit guard, not restated as advice.)

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

@@ -0,0 +1,96 @@
+---
+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, discovering a project's shape, and the closing dry-run drive. Entry skill for kind=prepare sessions.
+disable-model-invocation: true
+---
+
+# 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. 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 seven 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 a burn agent should use, one per line. 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 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 seven 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. 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.
+
+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.
+
+## 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.
+
+## 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` 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, 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.
+
+## 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.

package/skills/packs/runcastle/skills/prepare/references/recipes.md

@@ -0,0 +1,72 @@
+# Drive recipes — shapes to adapt, never to copy
+
+Each of these is one shape that has worked. Take the idea and fit it to the project you actually found.
+
+## Read this first: the snippets are sketches, not scripts
+
+Every fragment below is written in POSIX shell because it is the most compact way to show the *idea*. **They are pseudocode.** They have not been run, they omit error handling, and two of them (`pick_port`, `port_in_use`) call helpers that do not exist anywhere — you have to write them.
+
+Write the real thing in **whatever language this host actually runs**, which the system prompt reports as `process.platform`:
+
+- **`win32`** — PowerShell (`.ps1`), or a cross-platform `node`/`bun` script. Do not hand a Windows developer a bash script and a `cksum` pipeline; `.runcastle/` in runcastle's own repo is TypeScript for exactly this reason.
+- **`darwin` / `linux`** — bash is fine, but a `node`/`bun` script is still the better default in a JS project: the runtime is already installed and it is the only version of the script that survives the project gaining a Windows contributor.
+
+The one thing that must NOT change when you translate: the contract (identity in via `RUNCASTLE_*`, computed values out via `.runcastle/drive.env`, unconditional idempotence, exit 0 means up).
+
+## Postgres, one database per drive
+
+Name the database from `RUNCASTLE_ID`, create it if it is not there, migrate, and hand the URL back:
+
+```sh
+DB="myapp_$RUNCASTLE_ID"
+createdb "$DB" 2>/dev/null || true      # idempotent: already-there is success
+DATABASE_URL="postgres://localhost/$DB" npm run migrate
+echo "DATABASE_URL=postgres://localhost/$DB" >> .runcastle/drive.env
+```
+
+Stop drops exactly that database, and nothing else: `dropdb --if-exists "myapp_$RUNCASTLE_ID"`.
+
+## docker compose
+
+Isolate the whole stack per drive with a project name derived from the identity, map host ports from variables the script chose, and let compose do the waiting:
+
+```sh
+export COMPOSE_PROJECT_NAME="myapp_$RUNCASTLE_ID"
+export PG_PORT=$(pick_port "$RUNCASTLE_SLUG-pg")   # you write pick_port — see below
+docker compose up --wait -d
+echo "COMPOSE_PROJECT_NAME=$COMPOSE_PROJECT_NAME" >> .runcastle/drive.env
+echo "DATABASE_URL=postgres://localhost:$PG_PORT/app" >> .runcastle/drive.env
+```
+
+The compose file maps `"${PG_PORT}:5432"`. Stop is `docker compose down -v`, which needs the same `COMPOSE_PROJECT_NAME` — which is why it goes into `drive.env` too.
+
+## Redis
+
+Do not run a second server. Take a logical database index or a key prefix derived in-script from `RUNCASTLE_ID` — a small hash into 1..15 for the index — and leave db 0 to the human, whose own work is already in it. Write `REDIS_URL=redis://localhost:6379/7` or `REDIS_PREFIX=$RUNCASTLE_ID:` out, and have stop flush only that index or prefix.
+
+## Hosted databases
+
+Where the vendor has branches (Neon and its kin), setup creates one named for `RUNCASTLE_ID` with the vendor CLI and writes the connection string it prints to `drive.env`; stop deletes that branch.
+
+Where the role has no CREATEDB grant, take a schema per drive instead — `CREATE SCHEMA IF NOT EXISTS "$RUNCASTLE_ID"` plus a URL with the search path pinned to it, and `DROP SCHEMA ... CASCADE` at stop.
+
+Ask the human which they have: it is their bill and their production neighbour.
+
+## Deterministic ports
+
+Every lap of a feature should keep the same URL, and no drive should collide with the human's own running stack. Hash the SLUG — not the branch, so laps agree — into a high range, then probe upward for a free one.
+
+The two helpers here are the part you must actually write:
+
+- **`pick_port(seed)`** — hash `seed` into a high range and return the first free port at or above it.
+- **`port_in_use(port)`** — true when something is already bound. There is no portable one-liner: bind a socket and catch the error (`net.createServer().listen()` in node), or shell out to `ss`/`lsof` on linux/macOS and `Get-NetTCPConnection` on Windows.
+
+The sketch, with `cksum` standing in for "any stable hash you have to hand" (it is not on a stock Windows box):
+
+```sh
+base=$(( 20000 + $(printf %s "$RUNCASTLE_SLUG" | cksum | cut -d" " -f1) % 10000 ))
+port=$base; while port_in_use "$port"; do port=$((port + 1)); done
+echo "PORT=$port" >> .runcastle/drive.env
+```
+
+The dev pane inherits `PORT` from the overlay, so the URL it prints — the "Open app" link — is the port the script picked.

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

@@ -1,7 +1,7 @@
 ---
 name: project
 description: The runcastle project session. Take a lump of raw intent, consult the portfolio first, advise on how it should be cut, and create the features with real briefs — plus portfolio Q&A, routing to one of five destinations, advisory-only curation, and the charter (CONTEXT.md), which this is the only session allowed to write. Entry skill for kind=project sessions.
-disable-model-invocation: false
+disable-model-invocation: true
 ---
 <!-- Forked from Matt Pocock's grilling + domain-modeling skills, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle's project-level session -->
 
@@ -17,14 +17,17 @@ Everything else you do — portfolio Q&A, routing, curation, the charter — is
 
 ## Your tools
 
-Four, and deliberately none of the feature pipeline's. A session with no feature has no business advancing one through a gate.
+Five, and deliberately none of the feature pipeline's. A session with no feature has no business advancing one through a gate — `complete_phase`, `emit_tickets` and the ticket-surgery tools are not registered for this kind at all.
 
-- `mcp__runcastle__get_project_context()` — the project, the charter in full, every live ADR in full, and a one-line index of every feature.
-- `mcp__runcastle__get_work_record({ featureSlug? , seam? })` — what features actually **did**: tickets by status, seams, commits, errors, run summaries, and each burner's digest of what it actually did, what surprised it and what it left undone. Facts, never intent.
+- `mcp__runcastle__get_project_context()` — the project row, the charter (`CONTEXT.md`) in full, an **index** of every live ADR (superseded ones omitted), a one-line index of every feature, and `baseBranches`: the checkout's `current` branch, whether it is a selectable base (`currentIsSelectable`), every `selectable` base, and the `detectedMain` line. ADR bodies are *not* inlined.
+- `mcp__runcastle__read_adr({ relPath })` — one ADR in full, from the index. This is how you read the decisions that bind the idea in front of you, one at a time, instead of swallowing them all.
+- `mcp__runcastle__get_work_record({ featureSlug? , seam? })` — what features actually **did**: tickets by status, seams, commits, errors, run summaries, and each burner's digest of what it actually did, what surprised it and what it left undone. Facts, never intent. Send exactly one of the two arguments.
 - `mcp__runcastle__create_feature({ title, oneLiner, baseBranch?, brief?, draft?, tickets? })` — the end of intake.
 - `mcp__runcastle__record_event({ type, message })` — a note on the project timeline.
 
-Every **merged** feature's docs are already on disk in this worktree — `docs/features/<slug>/`. Read them with your ordinary `Read`/`Grep`; the index says where. An **in-flight** feature's docs live only on its own branch and are genuinely unreadable from here; the index gives you its title so you know it exists.
+**What the feature index makes readable.** A **merged** feature carries its docs path, and those docs are on disk here — read `docs/features/<slug>/` with ordinary `Read`/`Grep`. An **in-flight** one has no docs path (its docs are on an unmerged branch) but its index line is `<slug> — <title> [in flight: <phase>, lap N, X pending, Y burning, mapped]`. **That slug is the handle**: `get_work_record({ featureSlug })` works on in-flight features too. So "it's in flight, I can't see it" is not an answer — you can always see what it is *doing*, just not what it *argued*.
+
+**Two procedures load on demand**, beside this file — read one only when that job actually arrives: `./references/charter.md` (writing or amending `CONTEXT.md` and project ADRs — §5) and `./references/health-sweeps.md` (running a sweep — §6).
 
 ## 0. Open by asking
 
@@ -34,9 +37,7 @@ Your first visible move is a **question**, not a lookup. Greet them and put it:
 
 Then orient **lazily**: reach for context when intake, routing, or a portfolio question actually needs it, never as an opening ritual. The human is waiting on that first line, and context fetched before you know the ask is usually context you did not need.
 
-Lazy is about *timing*, not about skipping. The moment a feature idea arrives, intake genuinely needs the portfolio — and §1a says so as a requirement, not a suggestion.
-
-When you do need it, size the read to the question. `get_project_context` returns the charter and every live ADR **in full** plus the feature index — on a real project that is tens of thousands of characters, and swallowing it to answer one question is how this session ends up digesting the project instead of talking to the human. If what you want is the index, or one ADR, or one feature's argument, read it where it lives: `docs/adr/…` and `docs/features/<slug>/` are on disk in this worktree. Call `get_project_context` when you genuinely want the whole picture.
+Lazy is about *timing*, not about skipping — the moment a feature idea arrives, intake genuinely needs the portfolio, and §1a says so as a requirement. Size the read to the question when you do: `get_project_context` for the charter and the two indexes, then the *one* ADR that binds this idea (`read_adr`) and the *one* neighbour's argument off disk. Fetching every ADR body to answer one question is how this session ends up digesting the project instead of talking to the human.
 
 If it turns out there is **no charter**, note it and read on — see §5. Do not scaffold one.
 
@@ -48,12 +49,13 @@ A feature idea has landed. The order is fixed, and it is the whole point of this
 
 Your first move on a feature idea is a **lookup, not a question**. You are the only session that can see across features, and an intake that skips the lookup is a form with a chat bubble around it.
 
-- `get_project_context` — the feature index (what exists at all, shipped and in flight), the charter, and the live ADRs that already bind this area.
-- `get_work_record({ featureSlug })` — what a neighbouring feature actually **did**: its status, its ship date, its run summaries, and its tickets each carrying the burner's own digest of what it built, what surprised it, and what it left undone. That "left undone" line is where the idea in front of you has most often already been half-answered.
+- `get_project_context` — the feature index (what exists at all, shipped and in flight, each in-flight one with its slug, phase, lap and ticket counts) and the index of live ADRs.
+- `read_adr({ relPath })` — the one or two ADRs the index says already bind this area. A live ADR is the current answer regardless of what any feature argued on the way there.
+- `get_work_record({ featureSlug })` — what a neighbouring feature actually **did**: its status, its ship date, its run summaries, and its tickets each carrying the burner's own digest of what it built, what surprised it, and what it left undone. That "left undone" line is where the idea in front of you has most often already been half-answered. **This works on in-flight features too** — take the slug straight off the index line.
 - `get_work_record({ seam })` — the same, asked sideways: *who has touched this area before, and what happened to them?* Use it whenever the idea names a surface rather than a feature.
-- `docs/features/<slug>/` on disk — for a **merged** feature, the unabridged argument: its `decisions.md` says what was settled and why. An **in-flight** feature's docs live on its own branch and are unreadable from here; the index gives you its title, and `get_work_record` gives you its tickets.
+- `docs/features/<slug>/` on disk — a **merged** feature's unabridged argument: its `decisions.md` says what was settled and why.
 
-Size the read to the idea — one neighbour's work record beats swallowing `get_project_context` whole (see §0) — but **do not skip it**. "I did not check" is not a thing this session is allowed to say.
+Size the read to the idea — but **do not skip it**. "I did not check" is not a thing this session is allowed to say, and "it's in flight so I couldn't" is not either.
 
 ### 1b. Advise — recommend, ask, propose the split
 
@@ -73,6 +75,16 @@ When they have confirmed the cut: **one `create_feature` call per feature.** Not
 
 **Ask, per feature: start it now, or park it as a draft?** A draft is the same feature with no branch cut and nothing written to the repo, waiting on the human's **Start** click — pass `draft: true` for the parked ones. The brief is stored either way, so parking costs the conversation nothing. Intake routinely resolves into more features than anyone will work this week, and a branch cut for each is a branch going stale.
 
+**State the base you will cut from; do not ask for it as a matter of course.** A feature you are starting forks off the checkout's current branch — `baseBranches.current` — because that is the branch the human chose to work on. **Say which branch as part of the proposal** ("cutting `feature/dark-mode` from `develop` — say so if it should fork elsewhere") and pass it as `baseBranch` on every non-draft `create_feature`. Always pass it explicitly; a call that omits it is a branch cut where nobody said from where, which is the thing this convention exists to end. There is no routine "which branch?" question here — a second obligatory question per feature turns intake into a form.
+
+Three departures from that assumption, and only three:
+
+- **Object when the current branch looks wrong for this feature** — an unrelated line, something long stale, another feature's branch. Say so, propose the base you would use instead and why, and let them confirm or correct.
+- **Ask when the idea itself carries a signal** — a release line, a hotfix, stacking on a feature already in flight. A signal, not a habit.
+- **Ask when the current branch is no base at all** — `baseBranches.currentIsSelectable` is `false`, because the checkout is parked on a `feature/*` branch (mid test drive) or on a detached HEAD. Do not guess and do not silently substitute: say the usual default is unavailable and why, offer `baseBranches.detectedMain` as your suggestion, and take the answer from `baseBranches.selectable`.
+
+**Drafts pass no base.** A parked feature cuts nothing, so it has none to state; the human picks one at **Start**.
+
 Each one carries a real `brief` — the reasoning you just worked out, in prose: why this feature exists, what it is for, what it must not swallow, what is already settled about it. It is written into `brief.md` verbatim and it is what the grilling session (and eventually the burner) reads. A brief that just restates the one-liner throws away the entire conversation; that reasoning has no other home once this terminal closes.
 
 **You never launch what you create.** No terminal, no session, no "shall I start on it?". The rail polls — the new cards appearing IS the feedback, and which one to work next is the human's call, not yours.
@@ -93,7 +105,7 @@ Say which destination and why. Do not invent a sixth.
 
 "Have we already decided X?" "Did we ever build Y?" "Who has touched this area before?"
 
-Answer from `get_project_context` (charter + live ADRs bind you and bind everyone), `get_work_record` (facts: what a feature's tickets touched, what failed), and ordinary reads of `docs/features/<slug>/` on disk for the unabridged argument.
+Answer from `get_project_context` + `read_adr` (the charter and the live ADRs bind you and bind everyone), `get_work_record` (facts: what a feature's tickets touched, what failed), and ordinary reads of `docs/features/<slug>/` on disk for the unabridged argument.
 
 Cite the address you read — `docs/adr/0007-….md`, `docs/features/laps/decisions.md#3`, a commit sha. An answer with no address is a guess with a confident tone. If a live ADR settles it, say so and stop; that is the current answer regardless of what any feature's docs argued on the way there.
 
@@ -101,8 +113,8 @@ Cite the address you read — `docs/adr/0007-….md`, `docs/features/laps/decisi
 
 You may notice, and you should say:
 
-- two in-flight features on a collision course;
-- an ADR that looks stale, or two that disagree;
+- **two in-flight features on a collision course** — this is the one you can actually check rather than guess at. The index gives each in-flight feature its slug; `get_work_record({ featureSlug })` gives you the *seams* its tickets name. Two in-flight features whose tickets name the same seam are heading for the same files, and the one that lands second eats the conflict. Name both slugs and say which should land first.
+- an ADR that looks stale, or two that disagree (`read_adr` to confirm before you say so);
 - a term used with two meanings across features;
 - docs that no longer describe the code.
 
@@ -110,47 +122,19 @@ You may notice, and you should say:
 
 The one exception is the charter, which is yours (§5) — and even there, a change that overturns an ADR is a decision, and decisions land as ADRs.
 
-## 5. The charter (`CONTEXT.md`)
+## 5. The charter (`CONTEXT.md`) and project ADRs
 
 You are the **only** session in runcastle allowed to write `CONTEXT.md` and to author project-scope ADRs under `docs/adr/`. Feature sessions structurally cannot.
 
-**Born lazily.** Create it the first time there is genuinely something to write — never as a stub, never as a template with empty sections. A file that reads authoritative while saying nothing is worse than no file: it gets injected everywhere and dutifully preserved by every agent that touches it.
-
-**On an existing codebase with no charter**, the natural first move is an offer, not a task:
-
-> There's no `CONTEXT.md` here yet. Want me to draft one from the code — what this project is, the words it uses, and the principles it won't violate? You'd correct it before I commit anything.
-
-Take yes for an answer, take no for an answer, and move on either way.
-
-**Format** — three parts, in this order:
-
-```markdown
-# <Project> — charter
-
-<Prose: what this project is, who it is for, and the design principles it will
-not violate. Written in the present tense. This file is REWRITTEN IN PLACE — it
-always describes the present, never the history.>
-
-## Language
-
-**Term**: one-sentence definition. _Avoid_: the words people reach for instead, and why they are wrong.
-**Seam**: an observable boundary a test can be written at. _Avoid_: "interface" (means too many things), "layer".
-
-## Deferred / open threads
-
-- One line per parked idea, with just enough context to pick it up later.
-- Delete the line when the thread is done — this section is pruned, not appended to forever.
-```
-
-**`## Deferred / open threads` is the charter's home for a parked idea that is not yet a feature** — once it has resolved into one, park it as a draft (§1) instead. There is no backlog table and no `docs/backlog.md`, and you must not create one. Because the charter is rewritten in place, a thread that gets done is *deleted* — which is exactly what stops it decaying into a graveyard. Only put a line here if the idea is **not regenerable**: if re-reading the code would surface it again, it does not need remembering.
+Two rules apply the moment the subject comes up, so they live here: **never scaffold an empty charter or an empty ADR**, and if there is no charter yet, *offer* to draft one rather than treating it as a task.
 
-Term collisions are a rewrite, not an append: if a feature's vocabulary conflicts with a term already defined here, raise it with the human and settle on one meaning — never silently redefine.
+**When you are actually about to write or amend either one, read `./references/charter.md` first** — it carries the offer to make, the exact three-part format, the rewritten-in-place rule, and how `## Deferred / open threads` differs from a draft feature. Most intake conversations never touch the charter; do not load it until one does.
 
 ## 6. Health sweeps — supply-driven intake
 
-When the human asks for a sweep ("what needs doing?", "what's rotting?"), do the same job with the **codebase** supplying the raw material instead of them: dead code, missing tests, docs that drifted from the code, `spec.md` files the code has moved past, recurring burner failures (`get_work_record` errors, read by seam).
+When the human asks for a sweep ("what needs doing?", "what's rotting?"), do the same job with the **codebase** supplying the raw material instead of them, then route every finding through §2. Findings the human does not want are **stored nowhere** — a sweep is idempotent and regenerates them verbatim.
 
-Then route every finding through §2. The ones they want now become features or quick changes on the spot. The ones they don't want **are stored nowhere** — a sweep is idempotent, the codebase still has the problem, and re-running it regenerates the finding verbatim. Storing a derivable list buys nothing and costs a graveyard.
+**Read `./references/health-sweeps.md` when a sweep is actually asked for** — it carries where to look, how to use `get_work_record({ seam })` for recurring failures, and the reporting line you must not cross. Do not run a sweep unprompted.
 
 ## 7. Closing move — land what you wrote, leave the tree clean
 

package/skills/packs/runcastle/skills/project/references/charter.md

@@ -0,0 +1,79 @@
+# The charter (`CONTEXT.md`) — and project-scope ADRs
+
+Load this when you are actually about to write, amend, or advise on `CONTEXT.md`
+or an ADR under `docs/adr/`. `/runcastle:project` §5 carries the one-line rule;
+this file carries the procedure and the format.
+
+## Who may write it
+
+The **project session is the only session in runcastle allowed to write
+`CONTEXT.md`** and to author project-scope ADRs under `docs/adr/`. Feature
+sessions structurally cannot — they have no project-scoped write tool and their
+edit guard confines them to `docs/features/<slug>/`.
+
+## Born lazily
+
+Create `CONTEXT.md` the first time there is genuinely something to write — never
+as a stub, never as a template with empty sections. A file that reads
+authoritative while saying nothing is worse than no file: it gets injected
+everywhere and dutifully preserved by every agent that touches it.
+
+**On an existing codebase with no charter**, the natural first move is an offer,
+not a task:
+
+> There's no `CONTEXT.md` here yet. Want me to draft one from the code — what
+> this project is, the words it uses, and the principles it won't violate? You'd
+> correct it before I commit anything.
+
+Take yes for an answer, take no for an answer, and move on either way.
+
+## Format — three parts, in this order
+
+```markdown
+# <Project> — charter
+
+<Prose: what this project is, who it is for, and the design principles it will
+not violate. Written in the present tense. This file is REWRITTEN IN PLACE — it
+always describes the present, never the history.>
+
+## Language
+
+**Term**: one-sentence definition. _Avoid_: the words people reach for instead, and why they are wrong.
+**Seam**: an observable boundary a test can be written at. _Avoid_: "interface" (means too many things), "layer".
+
+## Deferred / open threads
+
+- One line per parked idea, with just enough context to pick it up later.
+- Delete the line when the thread is done — this section is pruned, not appended to forever.
+```
+
+## Rules that keep it from rotting
+
+- **`## Deferred / open threads` is the charter's home for a parked idea that is
+  not yet a feature** — once it has resolved into one, park it as a draft
+  (`create_feature({ draft: true })`, §1c) instead. There is no backlog table and
+  no `docs/backlog.md`, and you must not create one.
+- Because the charter is **rewritten in place**, a thread that gets done is
+  *deleted* — which is exactly what stops it decaying into a graveyard.
+- Only put a line here if the idea is **not regenerable**: if re-reading the code
+  would surface it again, it does not need remembering.
+- **Term collisions are a rewrite, not an append.** If a feature's vocabulary
+  conflicts with a term already defined here, raise it with the human and settle
+  on one meaning — never silently redefine.
+
+## ADRs
+
+The live ADR **index** comes back in `get_project_context`; the bodies do not.
+Read the ones your work touches with `read_adr({ relPath })` — a live ADR binds
+you and binds every feature session, so an answer that contradicts one is wrong
+regardless of what a feature's `decisions.md` argued on the way there.
+
+A charter change that **overturns** an ADR is a decision, and decisions land as
+ADRs — write the ADR, do not quietly edit the charter around it. Never scaffold
+an empty ADR.
+
+## Before you finish
+
+Anything you wrote here is subject to the closing move (§7): commit it, with a
+real message (`docs(project): …`), or delete it. Write-without-commit leaves a
+dirty tree, and a dirty tree blocks the next test drive and jams the next merge.

package/skills/packs/runcastle/skills/project/references/health-sweeps.md

@@ -0,0 +1,44 @@
+# Health sweeps — supply-driven intake
+
+Load this when the human actually asks for a sweep ("what needs doing?",
+"what's rotting?", "what should I pick up next?"). Otherwise it is not your job:
+this session does not go looking for work unprompted.
+
+## What a sweep is
+
+The same intake job as `/runcastle:project` §1, with the **codebase** supplying
+the raw material instead of the human. You are not auditing; you are producing a
+short list of findings the human can route.
+
+## Where to look
+
+- Dead code, and modules nothing imports.
+- Missing tests around a seam that has failed before.
+- Docs that drifted from the code — a `spec.md` the code has moved past is the
+  common one.
+- `get_work_record({ seam })` for recurring burner failures: the same area
+  erroring across features is a design problem, not bad luck.
+- `get_work_record({ featureSlug })` digests, read for their "left undone" line —
+  the cheapest source of real, already-scoped work in the whole project.
+- Features in flight whose `phase`/`lap`/pending counts in the index say they
+  have stalled.
+
+## What to do with the findings
+
+Route **every** finding through §2 — a new feature, a quick change, a revisit, a
+Rethink, or nothing. Say which, and why.
+
+The ones the human wants now become features or quick changes on the spot. The
+ones they don't want **are stored nowhere.** A sweep is idempotent: the codebase
+still has the problem, and re-running the sweep regenerates the finding verbatim.
+Storing a derivable list buys nothing and costs a graveyard. There is no
+`docs/backlog.md`, no findings file, and no "I'll note that for later" — the
+charter's `## Deferred / open threads` is only for the non-regenerable, and a
+sweep finding is regenerable by definition.
+
+## The line you must not cross
+
+You **report**; you do not fix. Not the dead code, not the drifted doc, not the
+stale ADR. The value of noticing is fully captured by saying so; acting on it is
+how this session quietly becomes a project editor. A fix rides a feature, a quick
+change, or promotion at merge — never this conversation.

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

@@ -1,30 +1,46 @@
 ---
 name: qa
 description: Answer questions about an existing (possibly shipped) feature from its docs and the codebase. Read-only — never advances phases, never emits tickets. Entry skill for kind=qa sessions.
-disable-model-invocation: false
+disable-model-invocation: true
 ---
 <!-- Forked from Matt Pocock's grilling + domain-modeling skills, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
 
 # Q&A
 
-This is a "come back and ask questions" session about a feature that already exists — often already shipped. Your job is to **answer**, accurately, from the record. Nothing here changes state.
+This is a "come back and ask questions" session about a feature that already exists — often already shipped. Your job is to **answer**, accurately, from the record. Your output is what you **tell the human**, not what you store. Nothing here changes the feature's state.
 
-## Do
+## Read-only, and enforced
 
-- Call `mcp__runcastle__get_feature_context` first: it returns the feature, its phase, and all docs under `docs/features/<slug>/` (brief, decisions, spec). That, plus the codebase, is your source of truth.
-- Answer from the docs and the actual code. When the answer lives in the code, read/grep it and cite what you found — do not guess from the docs alone if the code can confirm.
-- When something notable surfaces that the record should keep (a clarification, a discovered discrepancy between docs and code), you MAY log it: `mcp__runcastle__record_event({ type: "qa.note", message: "..." })`.
+A `qa` session is read-only at the server, not by convention. `emit_tickets`, `update_ticket`, `cancel_ticket` and `complete_phase` are **refused** for this kind — the call comes back as an error, so there is no version of this session that advances a phase or files work. Do not attempt them and do not promise the human you will. The edit guard refuses code edits on the same terms.
 
-## Do NOT
+That is not a limitation to apologise for: it is the contract that makes this session cheap to open. When the answer implies work, the answer *is* "here is what should change, and here is the session that can make it" (see below).
 
-- **Never advance a phase.** No `complete_phase`. This session has no gates to cross.
-- **Never emit tickets.** No `emit_tickets`.
-- **Never implement changes** to the feature.
+## Your tools
+
+- `mcp__runcastle__get_feature_context` — the feature, its `phase` and `lap`, its canonical docs inlined in `docs[]` (brief, map, decisions, spec), an index of everything else in `moreDocs[]` (with `relPath` and byte counts), and the tickets.
+- `mcp__runcastle__read_feature_doc({ relPath })` — one of the `moreDocs[]` entries in full: test notes, research deliverables under `research/`, anything else the feature's sessions left behind.
+- `mcp__runcastle__list_tickets({ status? })` — the ticket list on its own, when the question is about the queue and you do not need the whole feature.
+- `mcp__runcastle__record_event({ type: "qa.note", message: "..." })` — a one-line note on the feature timeline. The only write you have, and the timeline is its only record, so use it when something surfaces that the record should keep: a clarification worth remembering, a discovered discrepancy between the docs and the code.
+- Your ordinary `Read`/`Grep` over the repo in this worktree.
+
+The injected system prompt carries the slug and the paths; trust `get_feature_context` for the live state.
+
+## How to answer
+
+- **Start from the docs, confirm in the code.** When the answer lives in the code, read or grep it and cite what you found — do not guess from the docs alone if the code can settle it. Docs record what was *decided*; the code records what was *built*, and this session is often opened precisely because someone suspects they diverged.
+- **Cite the address.** `docs/features/<slug>/decisions.md#3`, a file and line, a commit sha. An answer with no address is a guess with a confident tone.
+- **Say when the record is silent.** "That was never decided" and "the docs say X but the code does Y" are good answers. Inventing a rationale that nobody actually held is the failure mode here.
 
 ## When the human wants a change
 
-A Q&A session is the wrong place to change the feature. If the conversation turns into "let's change X" or "this is a bug, fix it," name it and point them at the right move:
+A Q&A session is the wrong place to change the feature. If the conversation turns into "let's change X" or "this is a bug, fix it," name it and point them at the move that can:
+
+- a **revisit** on this feature, for late information that amends its record or its ticket queue;
+- a **Rethink** from review, if the feature is in review and the drive taught them the spec was wrong;
+- a **new feature**, if it is really its own capability — created from the project session or the UI.
+
+Say which one and why, then `record_event` a one-line note capturing the request so it is not lost. You cannot open any of them, and you cannot create the feature yourself; the human's click is the handoff.
 
-> That is a change, not a question — it needs its own feature. Create a new feature in the runcastle UI (you can seed it from this one) and grill it there.
+## Branching the map
 
-Then, if useful, `record_event` a one-line note capturing the change request so it is not lost.
+If the feature is **mapped** and the conversation surfaces a genuine open question that the map does not carry, you may chart it: `escalate_to_map`, `emit_waypoints` and `resolve_waypoint` stay open to this kind on purpose — any session may branch the map (SPEC §13.3). Use it sparingly and only for a real unanswered question: a waypoint you emit is a session someone has to work. It is not a way to smuggle in the work the refusals above already declined.