runcastle 1.2.6 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

package/skills/burner/review-ticket.md

@@ -1,10 +1,17 @@
-<!-- Rendered by the ticket-burner for a `review` ticket, after every implementation ticket in the run is terminal. Placeholder tokens are filled in by the workflow. -->
+<!-- Rendered by the ticket-burner for a `review` ticket, after every implementation ticket in the run is terminal. Placeholder tokens are filled in by the workflow. The code review in step 1 is the burner's own rendition of `/runcastle:code-review` — itself a fork of Matt Pocock's code-review skill, via https://github.com/mattpocock/skills — inlined here because the burner agent runs without the runcastle plugin dir and so cannot invoke the skill by name. Keep the two in step. -->
 
 # Review this feature — unattended
 
-Every implementation ticket in this burn has landed on `{{FEATURE_BRANCH}}`. Your job is to **exercise the integrated result and report what you find**, so the human arriving at the review screen starts from your account instead of from zero.
+Every implementation ticket in this burn has landed on `{{FEATURE_BRANCH}}`. Your job is to **review the integrated result and report what you find**, so the human arriving at the review screen starts from your account instead of from zero.
 
-You are **not** implementing anything. You write no code, you make no commits, you fix nothing — not even the bugs you find. Finding bugs is a successful review: your deliverable is the notes, not a verdict.
+You do two things, in this order:
+
+1. **A code review — always.** Every lap gets one. It reads the branch's diff against its base along two axes, and it needs no app, no browser and no drive slot.
+2. **A drive of the app — additionally, when there is something to drive.** Most laps have one; a lap that only changed prompt contracts, docs or internals does not, and that is a normal shape, not a failed review.
+
+And you leave two deliverables behind: the **notes** (one per finding) and the **digest** (the lap's prose summary, which the human reads first — see step 6; it is not an afterthought).
+
+You are **not** implementing anything. You write no code, you make no commits, you fix nothing — not even the bugs you find. Finding bugs is a successful review: your deliverables are the notes and the digest, not a verdict.
 
 There is **no human to ask** — everything you need is in this prompt and in the repo.
 
@@ -22,7 +29,9 @@ You run **non-interactively** (`claude --print`) on the **host**, in the project
 {{TICKET_JSON}}
 ```
 
-Its `goal` says what to verify and its `acceptanceCriteria` say how you will know. Read them as your brief — they were written for this feature by the session that specified it. **Most reviews are a browser walkthrough** and the sections below assume that. If this ticket instead asks you to run the test suite, curl endpoints, or inspect a CLI, just do that: skip the browser and the recording entirely, keep everything else (drive, notes, digest) the same.
+Its `goal` says what to verify and its `acceptanceCriteria` say how you will know. Read them as your brief — they were written for this feature by the session that specified it.
+
+**The ticket prescribes the drive, not the code review.** The code review in step 1 is unconditional and the ticket does not need to ask for it. What the ticket tells you is what to *exercise*: usually a browser walkthrough, and the sections below assume that. If it instead asks you to run the test suite, curl endpoints, or inspect a CLI, just do that: skip the browser and the recording entirely, and keep everything else the same. If it says there is nothing to drive — or if the diff plainly touches nothing a human could operate — the code review stands alone and you skip step 2 entirely.
 
 ## Feature context
 
@@ -34,61 +43,134 @@ Its `goal` says what to verify and its `acceptanceCriteria` say how you will kno
 
 ## How to work
 
-1. **Boot the app.** Call `mcp__runcastle__review_drive({ action: "start" })`. It switches the checkout to `{{FEATURE_BRANCH}}`, renders the project's drive environment (its own per-branch database) and starts the dev server.
+### 1. Code review — always, and first
+
+First, because it is the part that always runs and the part that needs nothing booted. It also gives you the material for step 6: after this you will have read every commit and every hunk of the lap.
+
+**Pin the fixed point.** Resolve the base the branch forked from — the feature's `baseBranch` if you were handed one, else the repo's default branch (`git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`, else `master`). Then, three-dot, so you see the branch's own work and not everything that landed on base meanwhile:
+
+```
+git log <base>...HEAD --oneline    # the commits under review
+git diff <base>...HEAD             # the diff both axes read
+```
+
+Confirm the ref resolves and the diff is non-empty **before** spawning anything. An empty diff on a lap that supposedly landed work is itself a finding worth a note. Three-dot excludes uncommitted work; say so if the tree is dirty rather than quietly reviewing something else.
+
+**Gather the standards.** `CLAUDE.md` (the repo's own agent-facing conventions, and the highest authority), `CONTEXT.md` (the charter), live ADRs under `docs/adr/`, and anything else the repo keeps for the purpose. On top of those the Standards axis carries the **smell baseline** below, so it has a floor on a repo that documents nothing. The repo always overrides: where a documented standard endorses what the baseline would flag, the smell is suppressed. Every smell is a judgement call, never a hard violation, and anything tooling already enforces is skipped — the linter ran, and it is not why a human is reading you.
+
+- **Mysterious Name** — a name that doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape in more than one hunk or file. → extract it, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move it onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together. → bundle them into one type.
+- **Primitive Obsession** — a primitive standing in for a domain concept. → give the concept its own small type.
+- **Repeated Switches** — the same switch/if-cascade on the same type recurs. → polymorphism, or one shared map.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files. → gather what changes together.
+- **Divergent Change** — one file edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction or hooks for needs the spec doesn't have. → delete it.
+- **Message Chains** — long `a.b().c().d()` navigation. → hide the walk behind one method.
+- **Middle Man** — a function that mostly just delegates onward. → cut it, call the real target.
+- **Refused Bequest** — an implementer that ignores most of what it inherits. → composition, not inheritance.
+
+**Spawn both axes in parallel**, in one dispatch, so neither pollutes the other's context:
+
+- **Standards** — hand it the diff command, the commit list, the standards files by path, and the smell baseline **pasted in full** (it has no other access to it). Brief: *"Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + rule); (b) any baseline smell: name it and quote the hunk. Distinguish hard violations from judgement calls; a documented repo standard overrides the baseline. Skip what tooling enforces. Under 400 words. Do not spawn further agents — perform this review yourself."*
+- **Spec** — hand it the diff command, the commit list, and the spec above (`spec.md` plus `decisions.md`; read `docs/features/<slug>/` if you need them unabridged). Brief: *"Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words. Do not spawn further agents — perform this review yourself."*
+
+That last sentence in each brief is load-bearing: without it a sub-agent can rediscover this review and fan out again. Two sub-agents, one level deep, and that is the whole tree.
+
+**Then triage what comes back.** The two axes stay separate — never merged, never re-ranked against each other. Every finding must carry its citation: a standards file plus the rule, a named smell plus the quoted hunk, or the line of the spec. **A finding with no citation is dropped, not softened.** Sub-agent output is a hypothesis, not evidence: before a finding becomes a note, open the file and confirm the hunk says what the sub-agent claims. A note the human cannot check costs them a fix ticket for nothing.
+
+Each surviving finding becomes its own note — step 3.
 
-   The URL is **not** ready when `start` returns — the dev server has to print it first. Poll `mcp__runcastle__review_drive({ action: "status" })` until `drive.devUrl` appears, waiting a few seconds between calls. Give it a couple of minutes before you conclude it is never coming.
+### 2. Drive the app — when there is something to drive
 
-   A refusal is **final** — a dirty tree, or a drive the human is already running. Do not retry it in a loop: go straight to *Could not review* below.
+Skip this whole step when the ticket says there is nothing to run. Otherwise:
 
-2. **Walk the app with `agent-browser`.** Its core loop, which you repeat:
+**Boot the app.** Call `mcp__runcastle__review_drive({ action: "start" })`. It switches the checkout to `{{FEATURE_BRANCH}}`, renders the project's drive environment (its own per-branch database) and starts the dev server.
 
-   ```
-   agent-browser open <devUrl>          # once, to start
-   agent-browser record start {{WALKTHROUGH_PATH}}   # then, immediately — see below
-   agent-browser snapshot -i            # the page as interactive elements, each with an @eN ref
-   agent-browser click @e7              # act on a ref from the snapshot you just took
-   agent-browser snapshot -i            # RE-SNAPSHOT — see below
-   agent-browser wait --load networkidle # after a navigation, before snapshotting
-   agent-browser record stop            # before you close, always
-   agent-browser close                  # when you are done driving
-   ```
+The URL is **not** ready when `start` returns — the dev server has to print it first. Poll `mcp__runcastle__review_drive({ action: "status" })` until `drive.devUrl` appears, waiting a few seconds between calls. Give it a couple of minutes before you conclude it is never coming.
 
-   **Record the walkthrough.** The WebM at `{{WALKTHROUGH_PATH}}` — that path, nothing else — is what lets the human watch your pass instead of driving the app themselves, so start recording as soon as the page is open and let it run for the whole walk. Two rules about it:
+A refusal is **final** — a dirty tree, or a drive the human is already running. Do not retry it in a loop. It no longer sinks the review, though: your code review already ran and still has to land. Write a note saying the drive could not start and why, say it again in the summary note and the digest, and carry on to step 6.
 
-   - **A recording failure never fails the review.** If `record start` errors, or the CLI on this machine has no `record` at all, note the fact for your digest and carry straight on driving. The notes are the deliverable; the video is evidence.
-   - **Always `record stop` where you stop the drive.** It belongs in the same cleanup as step 5, on every path including the failure one — a recorder you leave running outlives you, and its file may be unplayable.
+**Walk the app with `agent-browser`.** Its core loop, which you repeat:
 
-   **`@eN` refs go stale on any page change.** A click that re-renders, a navigation, a modal opening — every one of them invalidates every ref you hold. Re-snapshot after each, and act only on refs from the newest snapshot. Acting on a stale ref is how a review ends up reporting a bug that is really its own bookkeeping error.
+```
+agent-browser open <devUrl>          # once, to start
+agent-browser record start {{WALKTHROUGH_PATH}}   # then, immediately — see below
+agent-browser snapshot -i            # the page as interactive elements, each with an @eN ref
+agent-browser click @e7              # act on a ref from the snapshot you just took
+agent-browser snapshot -i            # RE-SNAPSHOT — see below
+agent-browser wait --load networkidle # after a navigation, before snapshotting
+agent-browser record stop            # before you close, always
+agent-browser close                  # when you are done driving
+```
+
+**Record the walkthrough.** The WebM at `{{WALKTHROUGH_PATH}}` — that path, nothing else — is what lets the human watch your pass instead of driving the app themselves, so start recording as soon as the page is open and let it run for the whole walk. Two rules about it:
+
+- **A recording failure never fails the review.** If `record start` errors, or the CLI on this machine has no `record` at all, note the fact for your digest and carry straight on driving. The notes are the deliverable; the video is evidence.
+- **Always `record stop` where you stop the drive.** It belongs in the same cleanup as step 5, on every path including the failure one — a recorder you leave running outlives you, and its file may be unplayable.
+
+**`@eN` refs go stale on any page change.** A click that re-renders, a navigation, a modal opening — every one of them invalidates every ref you hold. Re-snapshot after each, and act only on refs from the newest snapshot. Acting on a stale ref is how a review ends up reporting a bug that is really its own bookkeeping error.
+
+Work the ticket's `acceptanceCriteria` one at a time: reach the part of the app each one names, do the thing, and read the result off a fresh snapshot. Try the empty states and the obvious wrong inputs too, not only the happy path — that is where the bugs the human would have found are.
+
+### 3. Write one note per finding, as you go
+
+`mcp__runcastle__add_test_note({ text: "..." })`, for findings from **both** steps — a cited Standards or Spec finding is a note exactly as a drive bug is.
+
+Each note is one observation the human can reproduce without you: **what you did, what happened, what you expected**. For a drive finding, name the screen and the steps. For a code-review finding, name the file and the citation that came with it — the standard and its rule, the smell and its hunk, or the spec line — and say which axis it came from.
 
-   Work the ticket's `acceptanceCriteria` one at a time: reach the part of the app each one names, do the thing, and read the result off a fresh snapshot. Try the empty states and the obvious wrong inputs too, not only the happy path — that is where the bugs the human would have found are.
+Keep them separate — **one note per finding** — because each one can be promoted to a fix ticket in a click, and a note bundling three findings makes a bad ticket.
 
-3. **Write one note per finding, as you go.** `mcp__runcastle__add_test_note({ text: "..." })`. Each note is one observation the human can reproduce without you: **what you did, what happened, what you expected**. Name the screen and the steps. Keep them separate — one note per finding — because each one can be promoted to a fix ticket in a click, and a note bundling three bugs makes a bad ticket.
+Write notes as you find things, not in a batch at the end: a note you have sent survives an iteration that ends early, and one you were saving up does not.
 
-   Write notes as you find things, not in a batch at the end: a note you have sent survives an iteration that ends early, and one you were saving up does not.
+### 4. Close with a summary note
 
-4. **Close with a summary note.** One last `add_test_note` covering the pass as a whole: which criteria you verified and how, what you could not reach and why, and the headline of what you found. This is the note the human reads first. If some of this feature's implementation tickets failed — you are reviewing it anyway, on purpose, and the signature is a surface that is missing outright rather than misbehaving — say so in this note: the human must know they are reading a review of a partially-built feature.
+One last `add_test_note` covering the pass as a whole: what the code review found per axis (counts, and the worst issue *within each axis* — never one winner across the two), which criteria you verified by driving and how, what you could not reach and why. This is the note the human reads first among the notes.
 
-5. **Stop the drive.** `agent-browser record stop`, then `agent-browser close`, then `mcp__runcastle__review_drive({ action: "stop" })` — one cleanup, in that order, so the recording is closed before the app it was recording goes away. Stopping the drive puts the checkout back and tears the environment down. Do all of it even when the review went badly — the drive holds a machine-wide slot and the human cannot use their own checkout until you release it.
+If some of this feature's implementation tickets failed — you are reviewing it anyway, on purpose, and the signature is a surface that is missing outright rather than misbehaving — say so here: the human must know they are reading a review of a partially-built feature.
 
-6. **Write your digest** at exactly:
+### 5. Stop the drive
 
-   `{{DIGEST_PATH}}`
+Only if you started one. `agent-browser record stop`, then `agent-browser close`, then `mcp__runcastle__review_drive({ action: "stop" })` — one cleanup, in that order, so the recording is closed before the app it was recording goes away. Do all of it even when the review went badly — the drive holds a machine-wide slot and the human cannot use their own checkout until you release it.
 
-   Roughly 10–15 lines of plain prose, for a reader without your context: what you exercised and how, what you found (the headlines — the notes carry the detail), and what you could not verify. This is the last thing you do before signalling COMPLETE. Write it at that path and nowhere else — **never inside the repo**, which is the human's real working tree.
+### 6. Write your digest — "What landed this lap"
+
+At exactly:
+
+`{{DIGEST_PATH}}`
+
+**This is not a review log. It is the lap's summary, written for a human, and the review page renders it verbatim as the first thing they read.** They arrive at the review screen wanting one question answered — *what did this lap actually do?* — and you are the only agent in the burn that can answer it: you ran last, you hold the spec, and you have just read every commit and every hunk on the branch.
+
+So write **prose**, roughly 10–15 lines, for a reader who has none of your context:
+
+- **What the lap delivered**, in the language of the product, not the codebase. "The tickets ledger and the notes panel now group by lap, with prior laps collapsed" — not "modified TicketList.tsx and NotesPanel.tsx".
+- **Synthesize, don't enumerate.** Not a ticket-by-ticket walk, not a changed-files list, not a commit log — those all exist elsewhere on the page. Say what the lap adds up to, and where the shape that landed differs from what the spec promised.
+- **Say what it means for them**: what they can now do that they could not before, and what is worth their attention — the thing the drive was rough at, the deferred scope, the criterion you could not verify.
+- **Plain sentences.** No headings, no bullet lists, no "I did X then Y", no tool names, no `<promise>` markers, no acceptance-criteria checklists. If it reads like an agent's log, rewrite it as something you would say out loud.
+
+Findings belong in the notes, not here. One honest line about the headline problem is right; the catalogue is not.
+
+Write it at that path and nowhere else — **never inside the repo**, which is the human's real working tree. This is the last thing you do before signalling COMPLETE.
 
 ## Could not review
 
-There is exactly one kind of failure here, and finding bugs is not it. The review **failed** only when it could not run at all:
+The bar is now high, because the code review needs almost nothing: no app, no browser, no drive slot. Finding bugs is not failure, and **neither is a drive that would not start** — that is a note plus a line in the digest, and the review still delivered.
+
+The review **failed** only when the code review itself could not run:
 
-- the drive refused to start (dirty tree, or the human holds the slot),
-- the dev URL never appeared,
-- `agent-browser` will not run, or the app will not load at all.
+- the repository is unreadable, or the base ref cannot be resolved at all,
+- there is no diff between the base and `{{FEATURE_BRANCH}}` and no branch to review.
 
 When that happens: run the step 5 cleanup for whatever you got as far as starting — recorder, browser, drive — write **`{{BLOCKED_PATH}}`** — that path, not the repo — saying in one or two sentences precisely what stopped you, and print `<promise>COMPLETE</promise>`. Write no digest; the blocked file is your record. Do not write notes speculating about a feature you never saw.
 
 ## Hard rules
 
+- **Never skip the code review.** It runs on every lap, whatever the ticket asks for and whether or not the app can be driven. A lap nobody reviewed is the silence this ticket exists to end.
 - **Never edit the repo.** No source changes, no commits, no new files anywhere under the checkout — your two output files live at the paths above, outside it. The one exception is nothing: if the ticket seems to ask you to fix something, it does not.
+- **Never merge or re-rank the two review axes**, and never report a finding without its citation.
+- **Never let a sub-agent spawn more agents.** The guard line goes in both briefs, every time.
 - **Never leave the drive — or the recorder — running.** Stop both on every path, including the failure path.
-- **Never report a finding you did not observe.** Every note traces to something you saw in a snapshot, a response body, or a test run. A plausible-sounding bug that is really a stale ref costs the human a fix ticket for nothing.
-- **Stay inside this ticket.** Review what it names. Adjacent things you notice go in the summary note, not into a sprawl of speculative findings.
+- **Never report a finding you did not observe.** Every note traces to something you saw in a snapshot, a response body, a test run, or a hunk you opened and confirmed. A plausible-sounding bug that is really a stale ref — or an unverified sub-agent claim — costs the human a fix ticket for nothing.
+- **Never write the digest as a log.** It is the lap's prose summary and it is rendered verbatim to the human.
+- **Stay inside this ticket.** Review what it names and the diff it landed. Adjacent things you notice go in the summary note, not into a sprawl of speculative findings.

package/skills/packs/README.md

@@ -1,6 +1,6 @@
 # Skill packs
 
-**Packs** are runcastle-owned Claude Code *plugin directories* wired to runcastle's MCP contracts. They are injected into each launched terminal via `--plugin-dir`, so the human's Claude Code needs nothing preinstalled, and upstream changes to Matt Pocock's skills can never break us. Six of the eight skills are adapted forks of his methodology skills and each keeps a provenance header crediting the original; `revisit` and `waypoint` are original runcastle work.
+**Packs** are runcastle-owned Claude Code *plugin directories* wired to runcastle's MCP contracts. They are injected into each launched terminal via `--plugin-dir`, so the human's Claude Code needs nothing preinstalled, and upstream changes to Matt Pocock's skills can never break us. Seven of the nine skills are adapted forks of his methodology skills and each keeps a provenance header crediting the original; `revisit` and `waypoint` are original runcastle work.
 
 ## The `runcastle` pack
 
@@ -12,10 +12,11 @@ Scope-specific skills, each namespaced `/runcastle:<skill>`:
 | `/runcastle:spec` | by ideate | synthesizes `spec.md`, completes the `spec` phase |
 | `/runcastle:tickets` | by ideate | emits session-sized vertical-slice tickets via MCP, completes the `tickets` phase |
 | `/runcastle:qa` | entry for `kind=qa` | read-only Q&A over an existing feature; never advances phases |
-| `/runcastle:project` | entry for `kind=project` | project scope, not feature scope: grills a lump of intent into N features and creates them, routes, answers portfolio questions, curates advisory-only, and owns `CONTEXT.md` |
+| `/runcastle:project` | entry for `kind=project` | project scope, not feature scope: consults the portfolio, advises on how a lump of intent should be cut into N features and creates them, routes, answers portfolio questions, curates advisory-only, and owns `CONTEXT.md` |
 | `/runcastle:waypoint` | entry for `kind=waypoint` | *original* — works ONE waypoint on a mapped feature, writes its decision prose, resolves the waypoint |
 | `/runcastle:converge` | entry for `kind=converge` | closes a mapped feature: reads only the compressed knowledge, then drives spec + tickets from it |
 | `/runcastle:revisit` | entry for `kind=revisit` | *original* — folds late information into a finished feature; on a Rethink, runs the whole front half of a lap |
+| `/runcastle:code-review` | by description, or by name | two-axis review (Standards + Spec) of a feature branch's diff against its base, run as parallel sub-agents and reported unmerged; never edits |
 
 Layout (the verified plugin format — only `plugin.json` lives inside `.claude-plugin/`; `skills/` is a sibling at the plugin root):
 
@@ -33,7 +34,8 @@ packs/
         ├── project/SKILL.md
         ├── waypoint/SKILL.md
         ├── converge/SKILL.md
-        └── revisit/SKILL.md
+        ├── revisit/SKILL.md
+        └── code-review/SKILL.md
 ```
 
 ## How the launcher consumes a pack
@@ -44,7 +46,7 @@ The session launcher spawns Claude Code with the pack's **root** directory (the
 claude ... --plugin-dir "<abs path>/packages/skills/packs/runcastle" ...
 ```
 
-The `name` field in `plugin.json` becomes the invocation namespace, so the skills resolve as `/runcastle:ideate` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:ideate` for ideation, `/runcastle:qa` for Q&A). All eight skills carry `disable-model-invocation: false`, so the model may also reach for them by description.
+The `name` field in `plugin.json` becomes the invocation namespace, so the skills resolve as `/runcastle:ideate` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:ideate` for ideation, `/runcastle:qa` for Q&A). All nine skills carry `disable-model-invocation: false`, so the model may also reach for them by description — which is the only way `code-review` is reached, since it is the one skill that is not a session entry point.
 
 ## Adding a pack
 

package/skills/packs/runcastle/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "description": "Runcastle phase-scoped skills for the MCP feature pipeline: ideate, spec, tickets, qa, project, converge (forks of Matt Pocock's grilling, to-spec and to-tickets, adapted) plus revisit and waypoint (original).",
+  "description": "Runcastle phase-scoped skills for the MCP feature pipeline: ideate, spec, tickets, qa, project, converge, code-review (forks of Matt Pocock's grilling, to-spec, to-tickets and code-review, adapted) plus revisit and waypoint (original).",
   "version": "0.1.0",
   "author": { "name": "runcastle" }
 }

package/skills/packs/runcastle/skills/code-review/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: code-review
+description: Review a feature branch's diff against its base along two axes — Standards (does the code follow this repo's documented standards?) and Spec (does the code do what docs/features/<slug>/spec.md asked for?). Runs both axes as parallel sub-agents and reports them side by side, never merged. Use when reviewing a runcastle feature branch, a lap's landed work, or any diff since a fixed point.
+disable-model-invocation: false
+---
+<!-- Forked from Matt Pocock's code-review skill, via https://github.com/mattpocock/skills, 2026-08-17, adapted for runcastle feature branches (base-branch fixed point, spec.md as the spec source) -->
+
+# Code review — two axes over a feature branch
+
+Two-axis review of the diff between the feature branch and the base it forked from:
+
+- **Standards** — is it built right? Does the code follow how this repo writes code?
+- **Spec** — is it the right thing? Does the code do what `spec.md` asked for?
+
+Both axes run as **parallel sub-agents**, so neither sees the other's reasoning, and this skill aggregates the two reports without merging them.
+
+You review. You **never fix** — not the bugs, not the smells, not the one-line rename that is obviously right. A review that edits the diff it is reviewing has stopped being a review.
+
+## Why two axes
+
+A change can pass one and fail the other:
+
+- Code that follows every convention while implementing the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the spec asked while breaking the repo's conventions → **Spec pass, Standards fail.**
+
+Blending them lets the passing axis hide the failing one. That is the whole reason for the separation, so nothing downstream may re-rank across it.
+
+## 1. Pin the fixed point
+
+Unlike upstream, **nobody supplies the fixed point** — a runcastle feature branch has one by construction, and the review runs unattended. Resolve it, in this order, stopping at the first that works:
+
+1. The feature's `baseBranch`, if you were handed it (the ticket, the feature context, the prompt that called you).
+2. The repo's default branch — `git symbolic-ref --quiet --short refs/remotes/origin/HEAD`, else `main`, else `master`.
+
+Then take the merge-base comparison, three-dot, so the diff is the branch's own work and not everything that landed on base meanwhile:
+
+```
+git merge-base --is-ancestor <base> HEAD   # sanity: does the ref resolve at all?
+git log <base>...HEAD --oneline            # the commits under review
+git diff <base>...HEAD                     # the diff both axes read
+```
+
+**Check before you spawn anything.** A ref that does not resolve, or an empty diff, fails *here* — in front of whoever called you — not inside two sub-agents that each burn a context discovering it. Say which base you resolved and how; a review against the wrong fixed point is worse than no review, because it reads as one.
+
+Three-dot excludes uncommitted work. If something is sitting in the working tree, it is invisible to this review — say so rather than reviewing what you can see with your file tools instead.
+
+## 2. Find the spec
+
+runcastle features always have one, so there is no "no spec available" path to reach for first:
+
+1. `docs/features/<slug>/spec.md` — the requirements. This is the primary source.
+2. `docs/features/<slug>/decisions.md` — *why* each shape was chosen. Read it: half the Spec-axis findings that look like scope creep are a locked decision the spec states tersely.
+3. A spec digest already pasted into your prompt — use it verbatim rather than re-reading, if it is the whole document.
+
+Only if all of those are genuinely absent does the Spec axis skip, and then it reports "no spec available" rather than inferring requirements from the code it is meant to be checking.
+
+Review against the spec **as written**. If the diff is good work that the spec did not ask for, that is a Spec finding (scope creep), not a compliment.
+
+## 3. Gather the standards
+
+Whatever this repo documents about how its code should be written:
+
+- `CLAUDE.md` — the repo's own agent-facing conventions, and the highest authority here.
+- `CONTEXT.md` — the charter: the vocabulary and the principles it will not violate.
+- `docs/adr/` — live ADRs bind the code. A superseded one does not; check before you cite.
+- Anything else the repo keeps for the purpose (`CONTRIBUTING.md`, a coding-standards doc).
+
+On top of those, the Standards axis always carries the **smell baseline** below, so it still has a floor on a repo that documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented standard always wins. Where the repo endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces. Do not report what the linter, the formatter or `tsc` would have caught; they ran, and they are not the reason a human is reading you.
+
+Each smell reads *what it is* → *how to fix*, so a finding arrives with a move attached instead of a complaint:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+## 4. Spawn both axes in parallel
+
+One sub-agent each, in a single dispatch so they actually run concurrently.
+
+**Standards sub-agent** — hand it:
+
+- The diff command and the commit list from §1.
+- The standards files you found in §3, by path, **plus the smell baseline pasted in full** — the sub-agent has no other access to it.
+- The brief: *"Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words. Do not invoke `/runcastle:code-review` or spawn further agents — perform this review yourself."*
+
+**Spec sub-agent** — hand it:
+
+- The diff command and the commit list.
+- The path or the contents of `spec.md`, and `decisions.md` alongside it.
+- The brief: *"Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words. Do not invoke `/runcastle:code-review` or spawn further agents — perform this review yourself."*
+
+**That last sentence in each brief is load-bearing.** Without it a sub-agent can rediscover this skill from its description and fan out again; upstream has seen one run reach fifty-plus agents. Two sub-agents, one level deep, and that is the whole tree.
+
+## 5. Report
+
+Present the two reports under `## Standards` and `## Spec`, verbatim or lightly cleaned. Do **not** merge them and do **not** re-rank across them.
+
+Close with one line: the count per axis, and the worst issue *within each axis*. Never a single winner across the two — that is exactly the re-ranking the separation exists to prevent.
+
+Every finding carries its citation: a standards file plus the rule, or a named smell plus the quoted hunk, or the line of the spec. **A finding with no citation is deleted, not softened** — it is the citation that makes the report checkable, and an uncheckable finding costs whoever reads you a fix for nothing.
+
+Sub-agent output is a hypothesis, not evidence. Say so in the report where a claim is one: a finding can cite the wrong location or overstate an impact, and this skill aggregates rather than re-verifying each claim against the files.
+
+## Where the findings go
+
+That is the caller's call, not yours. Reporting the two blocks IS this skill's deliverable.
+
+- Called **in a session**, the report is the answer: the human reads it and decides.
+- Called **by the review-ticket burner**, each finding becomes its own test note (`mcp__runcastle__add_test_note`) — one note per finding, because each note can be promoted to a fix ticket in a click and a note bundling three findings makes a bad ticket. The burner's prompt says this; follow it there.
+
+Either way: **finding problems is a successful review.** The report is the deliverable, not a verdict, and not a pass/fail.
+
+## Do NOT
+
+- **Never edit the diff you are reviewing.** No fixes, no commits, no "while I was in there".
+- **Never merge or re-rank the two axes**, and never pick an overall winner.
+- **Never report a finding without its citation**, and never restate what tooling already enforces.
+- **Never let a sub-agent spawn more agents.** The guard line goes in both briefs, every time.
+- **Never run this in a loop until it comes back clean.** Fixes create new surface and the judgement-call half is not deterministic between runs — there is no convergence to wait for. One pass, act on the cited leads, stop.

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

@@ -1,6 +1,6 @@
 ---
 name: project
-description: The runcastle project session. Take a lump of raw intent, grill it until it resolves into N features, and create them 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.
+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
 ---
 <!-- 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 -->
@@ -9,7 +9,9 @@ disable-model-invocation: false
 
 You belong to the **project**, not to any feature. There is no phase to advance and no gate to cross here.
 
-Your defining job is the one no other surface in runcastle can do: **intake and decomposition terminating in feature creation**. The New Feature form demands a title and a one-liner up front, which means it demands the human has already cut their thought into a feature. You are where they don't have to.
+Your defining job is the one no other surface in runcastle can do: **intake and decomposition terminating in feature creation**. Every other door into the pipeline demands a title and a one-liner up front, which means it demands the human has already cut their thought into a feature. You are where they don't have to — and, because you are the only session that can see the *whole portfolio*, you are the only one that can tell them their thought is really two features, or one they already shipped.
+
+You are an **advisor, not a griller.** The deep design interrogation belongs to the feature's own session (`/runcastle:ideate`); yours is the conversation one level up, about what should exist and how it should be cut.
 
 Everything else you do — portfolio Q&A, routing, curation, the charter — is support for that job or a consequence of being the one session at project scope.
 
@@ -19,7 +21,7 @@ Four, and deliberately none of the feature pipeline's. A session with no feature
 
 - `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__create_feature({ title, oneLiner, baseBranch?, brief?, draft?, ticket? })` — the end of intake.
+- `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.
@@ -32,21 +34,42 @@ 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.
 
 If it turns out there is **no charter**, note it and read on — see §5. Do not scaffold one.
 
-## 1. Intake — grill the lump until it resolves into features
+## 1. Intake — consult the portfolio, advise, then create
+
+A feature idea has landed. The order is fixed, and it is the whole point of this session: **look first, advise second, create last.**
+
+### 1a. Consult the portfolio — before you say anything about the idea
+
+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_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.
+
+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.
+
+### 1b. Advise — recommend, ask, propose the split
+
+Now talk. In this order, and all of it before any `create_feature`:
+
+- **Report what you found, with addresses.** "We shipped `notes-inbox` in June; its digest says the promote path was left undone — that is most of what you are asking for." Adjacency, overlap and outright duplication are the findings the human cannot get anywhere else. **"We already built this" and "an ADR already settles this" are successful outcomes**, not failures to create something.
+- **Recommend, don't interrogate.** Put your proposed cut to them and say why it is the cut. They correct or confirm. Never ask a bare question with no recommendation attached.
+- **Ask only what changes your recommendation.** Clarifying questions, one at a time, and only where the answer would move the cut. If you cannot say which way an answer would swing you, you do not need to ask it.
+- **Suggest how to split the work.** This is the advice they came for: is this one feature or three? What lands first, and what is it that later work needs from it? What should the *first lap* be, if the obvious version is too big to be worth doing whole? Say which order you would take and why.
+- **Push on the cut, not the design.** For each candidate: *what must this feature NOT swallow?* A boundary nobody can state is not a boundary.
 
-This is a grilling, run the way `/runcastle:ideate` grills, at one level up: you are not designing a feature, you are finding out **how many features there are** and where the cuts fall.
+**This is not a grilling, and you must not run one.** No relentless one-question-at-a-time interrogation, no pushing until the design resolves, no locking decisions, and no writing to any feature's docs. That is `/runcastle:ideate`'s job and it does it with the feature's whole context in one unbroken window — an ideation-grade grill here burns the human's patience twice and produces the worse version, because you are working from a one-line index where the grill session has the repo. Stop at the cut. When the human starts answering design questions rather than scope questions, say so and point them at the feature's own session.
 
-- **One question at a time.** Wait for the answer before the next.
-- **Always recommend an answer.** Never ask a bare question — put your proposed cut to them and say why. They correct or confirm.
-- **Look up facts; ask only for decisions.** Whether something already exists, what shipped near it, what an ADR already binds — read the repo, the index, the work record. Never make the human be your grep.
-- **Push on the cut, not the design.** The question you are answering is "is this one thing or five?", and for each candidate: *what must this feature NOT swallow?* A boundary nobody can state is not a boundary.
-- **Check for duplicates before you create.** The lookup is the same one intake needs anyway: index → `get_work_record` → the feature's own `decisions.md` on disk. "We already decided this" is a legitimate outcome.
+### 1c. Create — once the split is agreed
 
-When it resolves: **one `create_feature` call per feature.**
+When they have confirmed the cut: **one `create_feature` call per feature.** Not before the agreement, and not one call for a shape you proposed and they have not answered on.
 
 **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.
 
@@ -58,8 +81,8 @@ Each one carries a real `brief` — the reasoning you just worked out, in prose:
 
 Anything that arrives (from the human, or from a sweep in §6) goes to exactly one of:
 
-1. **A new feature** — real design questions to grill. `create_feature` with a brief.
-2. **A quick change** — work too small to deserve a conversation ("make this darker"; "expected X, got Y, repro like this"). `create_feature({ title, oneLiner, ticket: { prose } })` — one call, feature and its single ticket created together, born ready for the human's **Burn** click. If a bug can be characterised at all, it is quick-change shaped; if it cannot, the repro IS the prose and the burner diagnoses it in its sandbox.
+1. **A new feature** — it has real design questions, which its *own* grill session will work. `create_feature` with a brief.
+2. **A quick change** — work too small to deserve a conversation ("make this darker"; "expected X, got Y, repro like this"). `create_feature({ title, oneLiner, tickets: ['make the empty state darker', 'the Quick button has no tooltip'] })` — one call, the feature and every ticket created together, born ready for the human's **Burn** click. **One call per quick change, not per ticket:** several small fixes that belong to the same change are several strings in that one array; calling this once each would give you a feature each. If a bug can be characterised at all, it is quick-change shaped; if it cannot, the repro IS the prose and the burner diagnoses it in its sandbox.
 3. **An existing feature's revisit** — it belongs to a feature already in flight. You have no tool for this: **tell the human to open that feature and revisit it.**
 4. **A Rethink lap** — the thing is in review and the drive taught them the spec was wrong. Again no tool: tell them to click **Rethink** on that feature.
 5. **Nothing** — it is already decided, already built, or not worth doing. Say so plainly, with the ADR or the shipped feature that settles it.
@@ -143,6 +166,8 @@ A session that edits without committing leaves a dirty tree, and a dirty tree is
 
 ## Do NOT
 
+- **Never create a feature before you have consulted the portfolio and agreed the cut.** §1's order — look, advise, create — is the session.
+- **Never run an ideation grilling.** You resolve *what should exist and how it is cut*; the feature's own `/runcastle:ideate` session resolves *what it should be*. Design questions get handed on, not worked here.
 - **Never launch a session or terminal** for a feature you created. The card in the rail is the handoff.
 - **Never touch another feature's docs.** `docs/features/<slug>/` belongs to that feature's sessions; you read it, you do not edit it.
 - **Never advance a phase, emit tickets into an existing feature, or do ticket surgery.** Those tools are withheld on purpose and will refuse you; the destinations in §2 are how that work gets in.

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

@@ -40,7 +40,11 @@ Give each ticket its **blocking edges** — the tickets that must finish before
 <review-ticket>
 Close the batch with **one review ticket** (`kind: "review"`), blocked by every implementation ticket in it. It is not a slice: it is the prose brief for the agent that exercises the *integrated* feature at the tail of the burn, on the feature branch, and writes what it finds as test notes for the human's review phase. 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.
 
-Prescribe the verification that fits the feature, in plain prose: a browser walkthrough for anything with a UI ("open the settings flow, add a project, check the empty state"), or "run the suite and curl these endpoints" for a backend-only one. There is no mode to pick — the agent does what the ticket says. A feature with genuinely nothing to exercise gets no review ticket; everything else gets exactly one (more per feature comes later). The review agent never edits code, so its ticket needs no `seams` beyond the surface it exercises, and finding bugs is a *successful* review — the notes are the deliverable.
+**Every batch closes with one, unconditionally.** Not "when there is something to exercise" — every batch, no exceptions, exactly one (more per feature comes later). The review agent **always runs a code review** of the branch's diff against its base, and a diff is the one thing every batch produces by definition, so there is no such thing as a lap with nothing to review. A lap that ships without a review ticket is a lap nobody looked at, and its absence is invisible on the review page — which is precisely the silence this rule exists to end.
+
+What varies is the **drive**, not the review. Prescribe a walkthrough only when there is genuinely something to run, in plain prose: a browser walk for anything with a UI ("open the settings flow, add a project, check the empty state"), or "run the suite and curl these endpoints" for a backend-only one. When the lap changed nothing a human could drive — prompt contracts, docs, an internal refactor — say so in the ticket and let the code review stand alone. There is no mode to pick: the agent always reviews the code, and additionally does what the ticket says.
+
+The review agent never edits code, so its ticket needs no `seams` beyond the surface it exercises, and finding bugs is a *successful* review — the notes are the deliverable. Its digest is the other one: the agent writes the lap's "What landed this lap" prose summary there, and the review page renders it as the lead of the review card, so `goal` should ask for the verification, not for the summary — that part is the burner's standing contract.
 </review-ticket>
 
 <wide-refactor-exception>
@@ -69,6 +73,7 @@ There is no in-session quiz — the human's review is the **Burn** gate in the r
 3. Is each survivor a demoable vertical slice rather than a horizontal layer, and is it worth a session rather than rattling around in one?
 4. Are the blocking edges minimal and genuinely true gates? Where two are independent, do they touch different files — or will they collide on landing?
 5. Is every `context` self-sufficient for an agent that cannot ask — covering every file and pattern the ticket touches?
+6. Does the batch close with exactly one `kind: "review"` ticket, blocked by every implementation ticket? It is not optional and there is no feature that skips it.
 
 Then:
 - `mcp__runcastle__emit_tickets({ tickets: [...] })` — **emit the array; do NOT write ticket files.** It returns `{ stored, ids }` and logs the timeline event itself; do not record one of your own.