runcastle 1.2.3 → 1.2.5

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "runcastle",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Burn tickets into shipped features with Claude Code.",
-  "license": "MIT",
+  "license": "FSL-1.1-ALv2",
   "type": "module",
   "bin": {
     "runcastle": "./bin/runcastle.js"

package/pty-host.cjs

@@ -138,6 +138,13 @@ function handle(msg) {
       }
       break
     case 'kill':
+      // Deliberately NOT a tree kill. Teardown never relies on this: the server
+      // tree-kills the pid it owns — THIS host process — and `taskkill /T` sweeps
+      // host → cmd shim → dev server from the outside (pty-sidecar.ts's
+      // `killTree`), so by the time a `kill` frame could matter the host is
+      // already gone. This is the backstop for the paths that are not teardown
+      // (an explicit kill with the tree walk unavailable or failed), where
+      // killing node-pty's own child is the most this process can do.
       if (proc) {
         try {
           proc.kill()
@@ -173,6 +180,9 @@ process.stdin.on('data', (chunk) => {
 })
 
 // When the server closes our stdin (it detached / crashed), tear down the child.
+// This is the orphan path, not the teardown path — an orderly stop tree-kills
+// this host from the outside and we never get here — so the same "kill what we
+// own, no tree walk" rule as the `kill` frame applies.
 process.stdin.on('end', () => {
   if (proc) {
     try {

package/skills/burner/implement-ticket.md

@@ -2,7 +2,7 @@
 
 # Implement this ticket — unattended
 
-You are a single agent in a sandbox on branch `feature/<slug>`. You have **one ticket**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt and in the repo. Work carefully, commit only green work, and stop when the ticket is done.
+You are a single agent in a sandbox on **your ticket's own temp branch**, `runcastle/ticket/<slug>/<seq>-<unique>`, forked from the feature branch `feature/<slug>`. Commit there and only there — the run merges your branch back into the feature branch once you land, so never check out or commit to `feature/<slug>` yourself. You have **one ticket**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt and in the repo. Work carefully, commit only green work, and stop when the ticket is done.
 
 ## How you run
 
@@ -74,6 +74,13 @@ Whatever the commands are, spend them well — a full suite on a monorepo is min
    - **Spec = this ticket** — is every acceptance criterion actually met, and is there **nothing in the diff the ticket did not ask for**? Missing and extra both count.
    Commit the fixes.
 
+6. **Write your digest — the last thing you do.** Once every acceptance criterion passes and the self-review fixes are committed, write `DIGEST.md` (see "Where to work" for exactly where) as your final act before printing `<promise>COMPLETE</promise>`. Roughly 10–15 lines, three parts:
+   - **What was done** — past tense, what you actually built, *including where it deviated* from the approach the ticket described.
+   - **Surprises** — what the ticket or the spec did not anticipate: the coupling nobody mentioned, the test that was already red, the API that did not behave as documented.
+   - **Left undone** — adjacent work you noticed and deliberately did not do, so the next agent inherits the observation instead of re-finding it.
+
+   Write it in plain prose, for a reader who does not have your context. **Never commit `DIGEST.md`** — it is harvested from the workspace, not from the repo, and a committed one is diff noise. It is a **success artifact only**: if you are blocked and writing `BLOCKED.md`, write no digest — `BLOCKED.md` is your record.
+
 ## Hard rules
 
 A few of these are enforced by a tool hook, not just stated here: `git stash`, test-runner concurrency flags, and rewriting files through interpreter heredocs are **denied** before they run. A denial is policy, not a broken environment — read its reason, take the alternative it names, and carry on. Do not try to route around it.

package/skills/burner/research-waypoint.md

@@ -2,7 +2,7 @@
 
 # Research this waypoint — unattended
 
-You are a single agent in a sandbox on branch `feature/<slug>`. You have **one research question**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt, on the web, and in the repo. Research carefully, write one focused summary, commit it, and stop.
+You are a single agent in a sandbox on **this run's own temp branch**, `runcastle/research/<slug>/<seq>-<unique>`, forked from the feature branch `feature/<slug>`. Commit there and only there — the run merges your branch back into the feature branch when it lands, and the feature branch stays checked out elsewhere for the whole run, so never check it out or commit to it yourself. You have **one research question**. There is **no human to ask** — no follow-up questions are possible. Everything you need is in this prompt, on the web, and in the repo. Research carefully, write one focused summary, commit it, and stop.
 
 ## The waypoint
 
@@ -36,7 +36,7 @@ You are a single agent in a sandbox on branch `feature/<slug>`. You have **one r
 
    Keep it tight and honest. If the question cannot be answered from available material, say so plainly in the doc and record what would be needed.
 
-4. **Commit the doc to the feature branch.** Stage only your new/changed doc under `docs/features/<slug>/` and commit with a clear message, e.g. `research(<seq>): <summary>`. The run reads your exit state from the commit — **a doc with no commit is read as no research landed.**
+4. **Commit the doc to the branch you are on.** Stage only your new/changed doc under `docs/features/<slug>/` and commit with a clear message, e.g. `research(<seq>): <summary>`. The run reads your exit state from the commit — **a doc with no commit is read as no research landed** — and merges the commit onto the feature branch for you.
 
 ## Hard rules
 

package/skills/packs/README.md

@@ -1,6 +1,6 @@
 # Skill packs
 
-**Packs** are runcastle-owned Claude Code *plugin directories* — vendored, adapted forks of Matt Pocock's methodology skills, 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's skills can never break us. (Every fork keeps a provenance header crediting the original.)
+**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.
 
 ## The `runcastle` pack
 
@@ -13,6 +13,9 @@ Scope-specific skills, each namespaced `/runcastle:<skill>`:
 | `/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: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 |
 
 Layout (the verified plugin format — only `plugin.json` lives inside `.claude-plugin/`; `skills/` is a sibling at the plugin root):
 
@@ -26,7 +29,11 @@ packs/
         ├── ideate/SKILL.md
         ├── spec/SKILL.md
         ├── tickets/SKILL.md
-        └── qa/SKILL.md
+        ├── qa/SKILL.md
+        ├── project/SKILL.md
+        ├── waypoint/SKILL.md
+        ├── converge/SKILL.md
+        └── revisit/SKILL.md
 ```
 
 ## How the launcher consumes a pack
@@ -37,7 +44,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 four 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 eight skills carry `disable-model-invocation: false`, so the model may also reach for them by description.
 
 ## Adding a pack
 

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

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "description": "Runcastle phase-scoped skills — forks of Matt Pocock's grilling, to-spec, and to-tickets adapted to runcastle's MCP feature pipeline (ideate, spec, tickets, qa).",
+  "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).",
   "version": "0.1.0",
   "author": { "name": "runcastle" }
 }

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

@@ -29,6 +29,7 @@ Interview the human about every aspect of the feature until you reach a genuinel
 - **Model the domain as you go** (forked from domain-modeling): challenge terms that conflict with existing usage, sharpen fuzzy words to one canonical meaning ("you said 'account' — Customer or User?"), invent concrete edge-case scenarios that force precision, and cross-check claims against the actual code ("your code cancels whole Orders, but you just said partial — which is right?").
 - **Probe the size early.** Within your first few questions, ask enough about scope to judge whether this is one-session-sized or map-sized — how many independent areas it touches, what has to be researched or prototyped before decisions can lock, how wide the design tree looks. Make that call up front, not thirty questions deep into one corner. If it smells map-sized, go to §3 *now* rather than rabbit-holing first.
 - **Ask the slicing question: how sure are you this is what you want?** Put it to them early, plainly, with your recommendation attached. **Sure, and small** → spec the whole thing; it is one lap and will likely merge on lap 1 — the old linear flow, verbatim. **Unsure, or large** → recommend a thin **lap 1**: a walking skeleton of the uncertain part, or one sub-feature slice they can actually test-drive, with the consciously deferred scope parked in the spec's `## Later laps` section (from there it seeds the next lap's session alongside the test notes). **Say the recommendation out loud and let them answer** — this is a judgment you offer, not a rule you enforce, and the human decides. There is no mode and no flag: how many laps a feature takes is a description of how it went.
+- **Park scope creep instead of swallowing it.** When something surfaces that is plainly its own feature, say so and offer to park 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 and what it must not swallow. Then get back to this feature. Drafts are the only thing you may create here; a full create belongs to the project session.
 - **Size and certainty are orthogonal.** Mapping (§3) is for ideation too big to *think* through in one session; laps are for a feature too uncertain to *spec whole*. A feature can need both, one, or neither — a small but fuzzy feature gets a thin lap 1 and no map; a big but settled one gets a map and still merges on lap 1.
 
 Do not move on until the human confirms you have reached shared understanding.

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

@@ -18,8 +18,8 @@ Everything else you do — portfolio Q&A, routing, curation, the charter — is
 Four, and deliberately none of the feature pipeline's. A session with no feature has no business advancing one through a gate.
 
 - `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. Facts, never intent.
-- `mcp__runcastle__create_feature({ title, oneLiner, baseBranch?, brief?, ticket? })` — the end of intake.
+- `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__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.
@@ -48,6 +48,8 @@ This is a grilling, run the way `/runcastle:ideate` grills, at one level up: you
 
 When it resolves: **one `create_feature` call per feature.**
 
+**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.
+
 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.
@@ -117,7 +119,7 @@ always describes the present, never the history.>
 - Delete the line when the thread is done — this section is pruned, not appended to forever.
 ```
 
-**`## Deferred / open threads` is runcastle's only home for a parked idea.** There is no backlog table, no `docs/backlog.md`, no draft feature status, 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.
+**`## 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.
 
 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.
 

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

@@ -35,7 +35,7 @@ Your kickoff line reads `LAP <n> REVIEW ITERATION`. The human burned the last la
 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`.
 6. **Emit this lap's tickets.** `mcp__runcastle__emit_tickets({ tickets })` — only the work this lap will burn; the rest stays in `## Later laps`. Reconcile stale pending tickets with `update_ticket` / `cancel_ticket`; `done` work that is now wrong gets a NEW ticket, as always.
-7. **Advance the pipeline.** `mcp__runcastle__complete_phase` through `ideation` → `spec` → `tickets`, here, without opening another session. It will refuse to cross into implementation — that gate is the human's Burn click, which is the point.
+7. **Advance the pipeline.** `mcp__runcastle__complete_phase` through `ideation` → `spec` → `tickets`, here, without opening another session. It will not cross into implementation: the `tickets` call comes back `ok: true` with `waitingOn: "human burn"` and the feature parks at `tickets` instead of advancing — that gate (G3) is the human's Burn click, which is the point.
 8. **Hand to Burn.** Tell the human in a line or two what this lap does, then:
 
    > Lap `<n>` is specced and carded. Review the ticket cards and click **Burn** — I'll stop here.

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

@@ -34,6 +34,10 @@ Turn the ideation conversation plus `docs/features/<slug>/decisions.md` into a s
 
    ## Open questions
    Anything still unresolved or deliberately deferred.
+
+   ## Later laps
+   Optional — include it when this is a thin lap 1. Scope consciously deferred
+   to a later lap; it seeds the next lap's session alongside the test notes.
    ```
 
    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.

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

@@ -35,7 +35,7 @@ Expect a **handful of substantial tickets** for a feature — roughly 4–8, eac
 - **Parallelism pays when the halves are file-disjoint.** Tickets with no blocking edge burn concurrently, each on its own temp branch, landing one at a time (ADR-0002) — so two substantial slices touching *different* files buy real wall-clock for one container. Two touching the *same* files race to land, and the loser fails on a merge conflict: that width costs a re-burn, which is worse than the container it bought. Overlapping files → merge.
 </vertical-slice-rules>
 
-Give each ticket its **blocking edges** — the tickets that must finish before it can start. No blockers → it can start immediately.
+Give each ticket its **blocking edges** — the tickets that must finish before it can start. Every ticket carries them: the field is required, so a ticket with no blockers gets an empty array and can start immediately.
 
 <wide-refactor-exception>
 A **wide refactor** — one mechanical change (rename a column, retype a shared symbol) whose blast radius breaks thousands of call sites at once — cannot land green as a vertical slice. Sequence it **expand → migrate → contract** instead. Expand: add the new form beside the old so nothing breaks (one ticket). Migrate: move call sites over in batches sized by blast radius (per package/dir), each batch a ticket blocked by the expand, CI green throughout because the old form still exists. Contract: delete the old form once no caller remains, blocked by every migrate batch. If even the batches cannot stay green alone, let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
@@ -51,7 +51,7 @@ Each ticket:
 - **context** — everything the sandboxed agent needs and cannot ask for: file paths to touch, existing patterns/modules to follow, type/schema shapes, gotchas, how to run and verify. Be concrete (see above).
 - **acceptanceCriteria** — `string[]`, each independently *verifiable* (a behaviour you can observe, a command that passes). These are what the burner works red-green against, one at a time, committing each green one — so this is where the fine granularity lives. A substantial ticket having four to eight criteria is right, not a smell; a list running well past that is a ticket that will not land in one pass.
 - **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[]`, the seq numbers (from your 1..N ordering) of the tickets that *genuinely* gate this one. Only true gates.
+- **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.
 
 ## 3. Self-check, then emit
 
@@ -64,8 +64,7 @@ There is no in-session quiz — the human's review is the **Burn** gate in the r
 5. Is every `context` self-sufficient for an agent that cannot ask — covering every file and pattern the ticket touches?
 
 Then:
-- `mcp__runcastle__emit_tickets({ tickets: [...] })` — **emit the array; do NOT write ticket files.** It returns `{ stored, ids }`.
-- `mcp__runcastle__record_event({ type: "tickets.emitted", message: "<n> tickets" })`.
+- `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.