runcastle 1.2.7 → 1.2.9

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

@@ -1,7 +1,7 @@
 ---
 name: revisit
 description: Fold late-arriving information into a feature whose sessions are finished — amend the docs, then reconcile tickets (update/cancel/emit); an ordinary revisit never advances phases. Also the lap session: on a Rethink from review, digest the test drive, amend decisions + spec, emit the lap's tickets and complete ideation → spec → tickets in the one session. Entry skill for kind=revisit sessions.
-disable-model-invocation: false
+disable-model-invocation: true
 ---
 
 # Revisit
@@ -13,7 +13,7 @@ That is the ordinary revisit, and it is what the moves below describe. The one e
 ## Order of operations
 
 1. **Listen first.** The human opens with what changed. If this terminal resumed the previous conversation, use that context; do not re-grill what is already settled. Ask only the questions the NEW information raises.
-2. **Context.** Call `mcp__runcastle__get_feature_context` — it returns the feature, phase, all docs, and all tickets with their ids and statuses. You need the ticket list before any surgery.
+2. **Context.** Call `mcp__runcastle__get_feature_context` — the feature, its `phase` and `lap`, the canonical docs inlined in `docs[]` (brief, map, decisions, spec), an index of everything else in `moreDocs[]` (test notes, `research/*.md`; fetch one with `mcp__runcastle__read_feature_doc({ relPath })`), and every ticket with its id and status. The injected system prompt carries the slug and paths; trust `get_feature_context` for the live state. When all you need is ticket ids to operate on, `mcp__runcastle__list_tickets({ status? })` is the cheap call — it returns the queue without the docs.
 3. **Docs.** Capture the change as decision prose:
    - Append to `docs/features/<slug>/decisions.md` under a dated `## Revisited <date>` heading — never rewrite old decisions, supersede them ("Supersedes: <old decision>").
    - If `spec.md` exists and the change touches it, amend the affected sections in place.
@@ -29,8 +29,8 @@ That is the ordinary revisit, and it is what the moves below describe. The one e
 
 Your kickoff line reads `LAP <n> REVIEW ITERATION`. The human burned the last lap, test-drove the branch, and clicked **Rethink**: the code was right, the *spec* wasn't. `feature.rethink` has already incremented the lap and looped the feature back, so it sits at **ideation**, not review. One trip round the pipeline is a lap, and this session is the whole front half of lap `<n>` — you carry it from what-the-drive-taught to ticket cards waiting on the human's **Burn** click, in this one conversation:
 
-1. **Digest what the drive taught.** Your inputs are the previous lap's section of `docs/features/<slug>/test-notes.md` and the spec's `## Later laps` section, both injected into your context. **Both may be absent** — that is not an error and not something to go hunting for: interview the human from scratch instead. What did they hit, what surprised them, what do they want instead now they've used it?
-2. **Context.** `mcp__runcastle__get_feature_context` — the feature (including its `lap`), the docs, and the full ticket history across every lap. Skim what the last lap actually landed and what failed before you interview.
+1. **Digest what the drive taught.** Your two inputs are the previous lap's section of `docs/features/<slug>/test-notes.md` — it is in `moreDocs[]`, so read it with `mcp__runcastle__read_feature_doc({ relPath: "test-notes.md" })` (or off disk) — and the `## Later laps` section of `spec.md`, which is inlined in `docs[]`. **Both may be absent** — that is not an error and not something to go hunting for: interview the human from scratch instead. What did they hit, what surprised them, what do they want instead now they've used it?
+2. **Context.** `mcp__runcastle__get_feature_context` — the feature (including its `lap`), the docs, and the full ticket history across every lap; each ticket's own `lap` is what separates them. Skim what the last lap actually landed and what failed before you interview.
 3. **Never re-emit a promoted note.** Notes the human already promoted from the review checklist are tickets in *this* lap and arrive as ids in your context. However well such a note reads as a ticket, if its id is in front of you the work is already carded — emitting it again gives the burner the same job twice.
 4. **Grill, briefly.** A small rethink is a short grilling: a few questions, one at a time, each with your recommended answer attached. Prune and promote `## Later laps` entries with the human as part of that conversation — what the drive taught is usually what decides which deferred scope this lap picks up and which stays parked.
 5. **Amend the docs.** Append this lap's learning to `docs/features/<slug>/decisions.md` under a `## Lap <n>` heading (the convention) — never rewrite old decisions, supersede them. Then amend `spec.md` in place: the sections this lap changes, plus the pruned `## Later laps`.
@@ -46,12 +46,12 @@ If the rethink turns out to be genuinely big — whole branches of design reopen
 
 - **Never call `complete_phase` in an ordinary revisit.** It has no gates to cross; the human drives the pipeline from the UI. **Lap mode is the one exception** — advancing ideation → spec → tickets is its job (move 7), and nothing else here licenses it.
 - **Never resolve or reopen waypoints.** If a resolved waypoint's answer is now wrong, record the superseding decision in `decisions.md` — the map's history stays intact.
-- **Never implement changes.** Code changes ride tickets; the burner (or a human) implements them.
+- **Code changes ride tickets** — the burner (or a human) implements them, never this session. (The no-code rule itself is in your injected prompt and enforced by the edit guard.)
 
 ## Scope check
 
-If what the human brings is not an amendment but a whole new capability, say so:
+If what the human brings is not an amendment but a whole new capability, say so — and park it rather than losing it:
 
-> That reads like a new feature, not a revision of this one. Create it in the runcastle UI and grill it there — I can record a pointer note here.
+> That reads like a new feature, not a revision of this one. I'll park it as a draft so it isn't lost; you can start it from the runcastle UI when you want it, and it gets grilled there.
 
-Then `record_event` a one-line note so the idea is not lost.
+`mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true })` — a parked draft, no branch cut and nothing written, with the `brief` carrying why you deferred it and what it must not swallow. `draft: true` is the only door open to you; a full create belongs to the project session.

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

@@ -1,6 +1,6 @@
 ---
 name: spec
-description: Synthesize the ideation conversation and decisions.md into docs/features/<slug>/spec.md, then complete the spec phase. No interview — pure synthesis. Invoked by /runcastle:ideate.
+description: Synthesize the ideation conversation and decisions.md into docs/features/<slug>/spec.md, then complete the spec phase. No interview — pure synthesis. Invoked by /runcastle:ideate or /runcastle:converge.
 disable-model-invocation: false
 ---
 <!-- Forked from Matt Pocock's to-spec skill, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
@@ -42,6 +42,6 @@ Turn the ideation conversation plus `docs/features/<slug>/decisions.md` into a s
 
    Do **not** hardcode specific file paths or code snippets — they go stale. Exception: if the ideation produced a snippet that pins a decision more precisely than prose can (a state machine, reducer, schema, type shape), inline the decision-rich parts and note it came from that discussion.
 
-4. **Complete the phase.** `mcp__runcastle__record_event({ type: "spec.written", message: "<feature title>" })`, then `mcp__runcastle__complete_phase({ phase: "spec" })`. If the gate returns `ok: false`, it names what is missing — fix and retry.
+4. **Complete the phase.** `mcp__runcastle__complete_phase({ phase: "spec" })`. If the gate returns `ok: false`, it names what is missing — fix and retry. It logs its own timeline event and checkpoints `spec.md` into git; do not add an event of your own.
 
-Return control to `/runcastle:ideate`, which invokes `/runcastle:tickets` next.
+Return control to **the session skill that invoked you** — `/runcastle:ideate` for a linear feature, `/runcastle:converge` for a mapped one. It invokes `/runcastle:tickets` next. Do **not** invoke a session skill yourself to hand back: you are already inside one, and loading another session's entry skill would drop a whole procedure this session is not running (a converge session in particular is forbidden to grill) into the window.

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

@@ -1,6 +1,6 @@
 ---
 name: tickets
-description: Break the spec into vertical slices sized to earn a fresh sandboxed agent session and land inside it, and emit them via MCP. Then complete the tickets phase. Invoked by /runcastle:ideate.
+description: Break the spec into vertical slices sized to earn a fresh sandboxed agent session and land inside it, and emit them via MCP. Then complete the tickets phase. Invoked by /runcastle:ideate or /runcastle:converge.
 disable-model-invocation: false
 ---
 <!-- Forked from Matt Pocock's to-tickets skill, via https://github.com/mattpocock/skills, 2026-07-14, adapted for runcastle -->
@@ -63,6 +63,17 @@ Each ticket:
 - **seams** — `string[]`, the public interfaces to test at (carry them from the spec's Seams section; prefer existing, prefer the highest, prefer one).
 - **blockedBy** — `number[]`, **required**, the seq numbers (from your 1..N ordering) of the tickets that *genuinely* gate this one. Only true gates; pass `[]` when there are none — omitting it fails validation.
 - **kind** — `"implementation"` (the default, omit it) or `"review"` for the one review ticket described above.
+- **model** — optional, and usually omitted. See below.
+
+### Assigning a model (only from the annotated roster)
+
+`mcp__runcastle__get_feature_context` returns `annotatedModels`: `{ id, runtime, note }` for the models the human wrote a use-case note against, and only those. That list is the *entire* set of ids you may put in a ticket's `model`.
+
+- **Empty list → never set `model`.** The human annotated nothing, so there is no stated reason to prefer one model over another. Omit the field on every ticket.
+- **Non-empty → set it only where a note actually fits the ticket.** The note is the human's own vocabulary for what that model is good at ("UI/UX taste", "mechanical refactors"); assign it when this ticket's work is plainly that, and leave the field unset when nothing in the list speaks to it. Unset is the good default — it falls through to the model the project already burns on.
+- **Never invent an id**, never copy one from these docs or from memory, and never write a model that is not in `annotatedModels` — the store rejects it and the whole batch fails to emit.
+
+The human sees the assignment on the ticket card and can change or clear it before Burn, so a wrong-but-reasonable choice is cheap; a fabricated id is not.
 
 ## 3. Self-check, then emit
 
@@ -79,4 +90,4 @@ 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.
 - `mcp__runcastle__complete_phase({ phase: "tickets" })`. If the gate returns `ok: false`, fix what it names and retry.
 
-Return to `/runcastle:ideate` to close out the session.
+Return control to **the session skill that invoked you** — `/runcastle:ideate` for a linear feature, `/runcastle:converge` for a mapped one — and let it close out the session. Do **not** invoke a session skill yourself to hand back: you are already inside one, and loading another session's entry skill would drop a whole procedure this session is not running (a converge session in particular is forbidden to grill) into the window.

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

@@ -1,7 +1,7 @@
 ---
 name: waypoint
 description: The runcastle waypoint session. Work ONE waypoint on a feature's map — grill, prototype, or run a task checklist for its assigned question — write the decision prose to the docs, then resolve the waypoint. Entry skill for kind=waypoint sessions.
-disable-model-invocation: false
+disable-model-invocation: true
 ---
 <!-- runcastle mapped-ideation waypoint session (ADR-0001 §13.5) -->
 
@@ -11,20 +11,25 @@ This is a **mapped-ideation** feature: too big for one context window, so it was
 
 ## 0. Orient
 
-1. Call `mcp__runcastle__get_feature_context`. For a mapped feature it returns, besides the usual feature/phase/docs, the full `map` state: `waypoints`, the `frontier`, and — the one that matters here — `assignedWaypoint`: **your** waypoint (the one this session claimed). Read its `title`, `type`, and `question`. The injected system prompt carries the same question; trust `get_feature_context` for the live state.
-2. Read `docs/features/<slug>/map.md` (Destination, Notes, Not-yet-specified, Out-of-scope) so your answer fits the north star, and skim `decisions.md` for what is already locked — **do not re-litigate settled decisions.**
-3. `mcp__runcastle__record_event({ type: "waypoint.started", message: "<waypoint title>" })`.
+1. Call `mcp__runcastle__get_feature_context`. The injected system prompt carries the slug, the paths and your question; trust `get_feature_context` for the live state. For a mapped feature it returns, besides the usual feature/phase/docs:
+   - `waypoints` — every waypoint on the map, with its `title`, `type`, `question`, status and (once terminal) `summary`.
+   - `frontierIds` — the ids currently open, unclaimed and unblocked.
+   - `assignedWaypointId` — **your** waypoint's id, the one this session claimed. Find that id in `waypoints` and read its `title`, `type` and `question`. That is your whole assignment.
+2. `docs[]` inlines the canonical docs in full — `brief.md`, `map.md`, `decisions.md`, `spec.md` if it exists. Read `map.md` (Destination, Notes, Not-yet-specified, Out-of-scope) so your answer fits the north star, and `decisions.md` for what is already locked — **do not re-litigate settled decisions.**
+3. **Read the research already done for this feature.** Earlier `research` waypoints wrote deliverables to `docs/features/<slug>/research/<seq>-<slug>.md`. They are *not* inlined — they appear in the `moreDocs` index with their `relPath` and `bytes`, and each resolved research waypoint's `summary` in `waypoints` names its file (`researched: <title> — see <path>`). Fetch the ones your question depends on with `mcp__runcastle__read_feature_doc({ relPath })`, or read them off disk in this worktree. A waypoint that re-derives a finding an earlier waypoint already paid an AFK run for is a wasted session.
 
 ## 1. Work it — mode by type
 
-Your `assignedWaypoint.type` picks the mode:
+Your waypoint's `type` picks the mode:
 
-- **`grilling`** → grill the human on the question exactly as `/runcastle:ideate` does: one question at a time, always recommend an answer, look up facts in the code, model the domain, don't move on until you share understanding. Scope the grill to THIS waypoint's question — resist wandering into the whole feature.
-- **`prototype`** → build the smallest throwaway spike that answers the question (a fork to compare approaches, a spike to prove feasibility). The prototype exists to produce a decision, not to ship — capture what it proved, then let it go.
+- **`grilling`** → grill the human on the question exactly as `/runcastle:ideate` does (`/runcastle:ideate` §1 is the procedure — one question at a time, always recommend an answer, look up facts in the code, model the domain, don't move on until you share understanding). Scope the grill to THIS waypoint's question — resist wandering into the whole feature.
+- **`prototype`** → build the smallest throwaway spike that answers the question (a fork to compare two approaches, a spike to prove feasibility). **Write it under `docs/features/<slug>/prototypes/` and nowhere else.** That directory is the only place a talk session may put code: everything outside `docs/features/<slug>/` is denied by the edit guard, and the deny is real, not advisory. The spike is *evidence for the decision prose*, not shipped code — nothing under `prototypes/` is ever built on, and the working version rides a ticket like any other code. So do not try to write into `src/`, do not conclude the prototype is impossible and emit a ticket instead, and do not ask the human to run it for you: spike it in `prototypes/`, read what it proves, write the decision (§2), and let the spike go.
 - **`task`** → run the concrete checklist the question describes (gather the facts, enumerate the cases, fill the table). Produce the artifact the waypoint asked for.
 
 If, while working, you discover the question really splits into new sub-questions or uncovers whole new branches, chart them: `mcp__runcastle__emit_waypoints({ waypoints: [...] })` — each with `title`, `type`, `question`, `blockedBy` (1-based positions in this batch and/or existing waypoint ids), and `originWaypointId: "<your waypoint id>"` so the lineage ("surfaced by …") is recorded. Any mapped session may branch the map; that is the recursion. Emitting a waypoint does **not** relieve you of answering your own.
 
+If something surfaces that is plainly its own **feature** rather than another waypoint, park it instead of swallowing it: `mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true })` creates a parked draft — no branch, nothing written — with the `brief` carrying why you deferred it. Drafts are the only feature you may create here; a full create belongs to the project session.
+
 ## 2. Write the decision prose — directly, to the docs
 
 The answer is **prose in the docs**, not a tool argument. Serial HITL makes these writes race-free, so edit the files directly in this talk worktree:
@@ -39,13 +44,13 @@ The answer is **prose in the docs**, not a tool argument. Serial HITL makes thes
 
 - **Dropping** (no longer worth answering): record a one-line gist under `## Out of scope` in `docs/features/<slug>/map.md`, so the map remembers why it was cut.
 
-Write the prose **before** you resolve — the resolve tool flips machinery only and does not carry your answer.
+Write the prose **before** you resolve — the resolve tool flips machinery only and does not carry your answer. If a prototype produced the answer, the decision entry must stand on its own: the reader of `decisions.md` is a converge session that will never open your spike.
 
 ## 3. Resolve — end the session
 
 `mcp__runcastle__resolve_waypoint({ id: "<your waypoint id>", disposition: "resolved" | "dropped", summary: "<one-line gist>" })`.
 
-This marks your waypoint terminal and frees any waypoint that was blocked only on yours — they appear on the frontier for the next session to Work. The `summary` is the one line shown on the map card.
+This marks your waypoint terminal and frees any waypoint that was blocked only on yours — they appear on the frontier for the next session to Work. The `summary` is the one line shown on the map card, and it is what a later session sees first; if your work left a file behind (a prototype, a table), name its path there.
 
 Then tell the human plainly: