runcastle 1.0.26 → 1.0.27

package/drizzle/meta/_journal.json

@@ -99,6 +99,13 @@
       "when": 1785243983378,
       "tag": "0013_sudden_naoko",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1785260479530,
+      "tag": "0014_ordinary_mystique",
+      "breakpoints": true
     }
   ]
 }

package/index.js

@@ -271,6 +271,7 @@ var init_schemas = __esm(() => {
     featureId: z2.string(),
     seq: z2.number(),
     status: TicketStatus,
+    lap: z2.number(),
     commits: z2.array(z2.string()),
     error: z2.string().optional(),
     attemptBranch: z2.string().optional(),
@@ -348,6 +349,7 @@ var init_schemas = __esm(() => {
     title: z2.string(),
     oneLiner: z2.string(),
     mapped: z2.boolean(),
+    lap: z2.number(),
     phase: Phase,
     branch: z2.string(),
     baseBranch: z2.string().optional(),
@@ -484,7 +486,7 @@ function nextGate(feature) {
     return MAPPED_G1;
   return gate;
 }
-var PIPELINE, ORDER, REVIEW_LOOP_BACK, MAPPED_G1;
+var PIPELINE, ORDER, REVIEW_LOOP_BACK, RETHINK_LOOP_BACK, MAPPED_G1;
 var init_pipeline = __esm(() => {
   PIPELINE = [
     { phase: "ideation" },
@@ -531,6 +533,7 @@ var init_pipeline = __esm(() => {
   ];
   ORDER = PIPELINE.map((p) => p.phase);
   REVIEW_LOOP_BACK = { from: "review", to: "implementation" };
+  RETHINK_LOOP_BACK = { from: "review", to: "ideation" };
   MAPPED_G1 = {
     id: "G1",
     description: "Every waypoint resolved or dropped before converging",
@@ -583,6 +586,7 @@ var init_db_schema = __esm(() => {
     title: text("title").notNull(),
     oneLiner: text("one_liner").notNull(),
     mapped: integer("mapped", { mode: "boolean" }).notNull().default(false),
+    lap: integer("lap").notNull().default(1),
     phase: text("phase").notNull().$type(),
     branch: text("branch").notNull(),
     baseBranch: text("base_branch"),
@@ -593,6 +597,7 @@ var init_db_schema = __esm(() => {
     id: text("id").primaryKey(),
     featureId: text("feature_id"),
     projectId: text("project_id"),
+    lap: integer("lap").notNull().default(1),
     kind: text("kind").notNull().$type(),
     ccSessionId: text("cc_session_id"),
     transcriptPath: text("transcript_path"),
@@ -609,6 +614,7 @@ var init_db_schema = __esm(() => {
     acceptanceCriteria: text("acceptance_criteria", { mode: "json" }).notNull().$type(),
     seams: text("seams", { mode: "json" }).notNull().$type(),
     blockedBy: text("blocked_by", { mode: "json" }).notNull().$type(),
+    lap: integer("lap").notNull().default(1),
     status: text("status").notNull().$type(),
     commits: text("commits", { mode: "json" }).notNull().$type(),
     error: text("error"),
@@ -644,6 +650,7 @@ var init_db_schema = __esm(() => {
     featureId: text("feature_id"),
     runId: text("run_id"),
     ticketId: text("ticket_id"),
+    lap: integer("lap").notNull().default(1),
     ts: integer("ts").notNull(),
     type: text("type").notNull(),
     message: text("message").notNull(),
@@ -1382,6 +1389,10 @@ function projectIdForFeature(ctx, featureId) {
     throw new NotFoundError(`feature ${featureId} not found`);
   return row.projectId;
 }
+function lapForFeature(ctx, featureId) {
+  const row = ctx.db.select({ lap: features.lap }).from(features).where(eq(features.id, featureId)).get();
+  return row?.lap ?? 1;
+}
 function emit(ctx, featureId, e) {
   return insertEvent(ctx, projectIdForFeature(ctx, featureId), featureId, e);
 }
@@ -1399,6 +1410,7 @@ function insertEvent(ctx, projectId, featureId, e) {
   const row = ctx.db.insert(events).values({
     projectId,
     featureId,
+    lap: featureId ? lapForFeature(ctx, featureId) : 1,
     runId: e.runId ?? null,
     ticketId: e.ticketId ?? null,
     ts: Date.now(),
@@ -1439,6 +1451,7 @@ function rowToFeature(row) {
     title: row.title,
     oneLiner: row.oneLiner,
     mapped: row.mapped,
+    lap: row.lap,
     phase: row.phase,
     branch: row.branch,
     baseBranch: row.baseBranch ?? undefined,
@@ -1740,6 +1753,7 @@ function createSessionRow(ctx, input) {
     id: newId("sess"),
     featureId: input.featureId ?? null,
     projectId: input.projectId ?? null,
+    lap: input.featureId ? getFeatureRow(ctx, input.featureId).lap : 1,
     kind: input.kind,
     ccSessionId: null,
     transcriptPath: null,
@@ -1771,6 +1785,9 @@ function markSessionLive(ctx, id, input = {}) {
   }
   return getSessionRow(ctx, id);
 }
+function lapKickoff(lap) {
+  return `Proceed with your task: invoke the /runcastle:revisit skill for LAP ${lap} REVIEW ITERATION. ` + `Call get_feature_context, then read this feature's test-notes.md (the "## Lap ${lap - 1}" ` + 'section \u2014 what the last drive surfaced) and the "## Later laps" section of its spec.md. ' + "EITHER MAY NOT EXIST YET; that is normal, not an error \u2014 say so and carry on from what I " + "tell you. Interview me about what the test drive taught: what was wrong, what was missing, " + "what I want next. Write what we settle on into decisions.md and amend spec.md for this lap " + '(pruning anything you promote out of "## Later laps"), then call emit_tickets for this ' + `lap's work. Finish in THIS session: complete_phase through ideation \u2192 spec \u2192 tickets, then ` + "tell me to review the cards and click Burn.";
+}
 function kickoffLineFor(kind, override) {
   return override ?? KICKOFF_LINES[kind];
 }
@@ -4904,6 +4921,7 @@ function rowToTicket(row) {
     acceptanceCriteria: row.acceptanceCriteria,
     seams: row.seams,
     blockedBy: row.blockedBy,
+    lap: row.lap,
     status: row.status,
     commits: row.commits,
     error: row.error ?? undefined,
@@ -4926,6 +4944,7 @@ function listByFeature2(ctx, featureId) {
 function storeTickets(ctx, featureId, inputs) {
   if (inputs.length === 0)
     return [];
+  const { lap } = getFeatureRow(ctx, featureId);
   const existing = ctx.db.select({ seq: tickets.seq }).from(tickets).where(eq7(tickets.featureId, featureId)).all();
   const startSeq = existing.reduce((max, r) => Math.max(max, r.seq), 0) + 1;
   const resolved = resolveBlocking(inputs, startSeq);
@@ -4939,6 +4958,7 @@ function storeTickets(ctx, featureId, inputs) {
     acceptanceCriteria: t.acceptanceCriteria,
     seams: t.seams,
     blockedBy: resolved[i].blockedBy,
+    lap,
     status: "pending",
     commits: [],
     error: null,
@@ -5046,6 +5066,7 @@ var init_tickets = __esm(() => {
   init_schema();
   init_errors();
   init_events();
+  init_repo();
   MUTABLE_STATUSES = new Set(["pending", "failed"]);
 });
 
@@ -5069,7 +5090,7 @@ function checkGate(ctx, check, feature) {
     case "spec-file-exists":
       return fileGate(ctx, feature, "spec.md", "write the spec (spec.md) before breaking into tickets");
     case "tickets-approved": {
-      const count = listByFeature2(ctx, feature.id).filter((t) => t.status !== "cancelled").length;
+      const count = listByFeature2(ctx, feature.id).filter((t) => t.lap === feature.lap && t.status !== "cancelled").length;
       return count >= 1 ? { satisfied: true } : { satisfied: false, reason: "no tickets to burn" };
     }
     case "all-tickets-terminal": {
@@ -5604,6 +5625,7 @@ async function createFeature(ctx, input) {
     title: input.title,
     oneLiner: input.oneLiner,
     mapped: false,
+    lap: 1,
     phase: "ideation",
     branch,
     baseBranch,
@@ -5688,7 +5710,8 @@ async function burn(ctx, featureId, opts = {}) {
   const feature = getFeatureRow(ctx, featureId);
   const running = hasActiveRun(ctx, featureId);
   let tickets2 = listByFeature2(ctx, featureId);
-  const pending = tickets2.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
+  const lapTickets = tickets2.filter((t) => t.lap === feature.lap);
+  const pending = lapTickets.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
   const restarting = feature.phase === "implementation" && !running;
   const iterating = feature.phase === "review" && !running && pending.length >= 1;
   if (feature.phase !== "tickets" && !restarting && !iterating) {
@@ -5701,8 +5724,8 @@ async function burn(ctx, featureId, opts = {}) {
       why = `feature must be in the tickets phase to burn (currently ${feature.phase})`;
     throw new GateError(why);
   }
-  if (tickets2.filter((t) => t.status !== "cancelled").length < 1) {
-    throw new GateError(tickets2.length > 0 ? "no burnable tickets \u2014 every ticket is cancelled" : "no tickets to burn");
+  if (lapTickets.filter((t) => t.status !== "cancelled").length < 1) {
+    throw new GateError(lapTickets.length > 0 ? "no burnable tickets \u2014 every ticket is cancelled" : "no tickets to burn");
   }
   if (restarting) {
     sweepOrphanedBurning(ctx, featureId, "orphaned \u2014 the previous run died while it was burning");
@@ -5726,6 +5749,22 @@ async function burn(ctx, featureId, opts = {}) {
   });
   return { runId };
 }
+function rethink(ctx, featureId) {
+  const feature = getFeatureRow(ctx, featureId);
+  if (feature.phase !== RETHINK_LOOP_BACK.from) {
+    throw new GateError(`feature must be in the review phase to rethink (currently ${feature.phase})`);
+  }
+  if (hasActiveRun(ctx, featureId)) {
+    throw new GateError("a run is burning this feature \u2014 cancel or wait for it before rethinking");
+  }
+  const live = activeSessionsForFeature(ctx, featureId);
+  if (live.length > 0) {
+    throw new GateError(`a ${live[0].kind} session is already live for ${feature.slug} \u2014 only one terminal per feature; end or resume it first`);
+  }
+  const lap = feature.lap + 1;
+  ctx.db.update(features).set({ lap }).where(eq9(features.id, featureId)).run();
+  return setPhase(ctx, featureId, RETHINK_LOOP_BACK.to, "lap.started", `rethink \u2014 lap ${lap}`);
+}
 async function retryTicket(ctx, ticketId, opts = {}) {
   const ticket = getTicket(ctx, ticketId);
   const feature = getFeatureRow(ctx, ticket.featureId);
@@ -5907,6 +5946,7 @@ var init_features = __esm(() => {
   init_git();
   init_knowledge();
   init_repo();
+  init_sessions();
   init_end_session();
   init_tickets();
   init_waypoints();
@@ -5952,6 +5992,7 @@ function toolGetFeatureContext(ctx, session) {
   const context = {
     feature,
     phase: feature.phase,
+    lap: feature.lap,
     docs,
     tickets: listByFeature2(ctx, feature.id)
   };
@@ -7460,6 +7501,7 @@ var gateId, featureRouter;
 var init_feature = __esm(() => {
   init_src();
   init_launcher();
+  init_sessions();
   init_events();
   init_features();
   init_gates();
@@ -7483,6 +7525,14 @@ var init_feature = __esm(() => {
     })).mutation(({ ctx, input }) => launchSession(ctx, input)),
     workWaypoint: publicProcedure.input(z7.object({ featureId: z7.string(), waypointId: z7.string(), endLive: z7.boolean().optional() })).mutation(({ ctx, input }) => workWaypoint(ctx, input)),
     converge: publicProcedure.input(z7.object({ featureId: z7.string(), overrideReason: z7.string().min(1).optional() })).mutation(({ ctx, input }) => converge(ctx, { featureId: input.featureId, overrideReason: input.overrideReason })),
+    rethink: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => {
+      const feature = rethink(ctx, input.featureId);
+      return launchSession(ctx, {
+        featureId: input.featureId,
+        kind: "revisit",
+        kickoffLine: lapKickoff(feature.lap)
+      });
+    }),
     resendKickoff: publicProcedure.input(z7.object({ sessionId: z7.string() })).mutation(({ ctx, input }) => resendKickoff(ctx, input.sessionId)),
     endSession: publicProcedure.input(z7.object({ sessionId: z7.string() })).mutation(({ ctx, input }) => endSession(ctx, input.sessionId)),
     advance: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => advance(ctx, input.featureId)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "MIT",
   "type": "module",

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

@@ -28,6 +28,8 @@ Interview the human about every aspect of the feature until you reach a genuinel
 - **Look up facts; ask only for decisions.** If a fact is discoverable in the codebase — how something currently works, what a type looks like, whether a pattern already exists — read/grep the repo and find it. Never make the human be your grep. *Decisions* are theirs: put each one to them and wait.
 - **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.
+- **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/revisit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: revisit
-description: Fold late-arriving information into a feature whose sessions are finished — amend the docs, then reconcile tickets (update/cancel/emit). Never advances phases. Entry skill for kind=revisit sessions.
+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
 ---
 
@@ -8,6 +8,8 @@ disable-model-invocation: false
 
 The human came back: they remembered a constraint, changed their mind, or learned something that the grilling/spec didn't capture. This session's job is to make the **record** and the **ticket queue** match the new reality — nothing more. The pipeline does not move; whatever phase the feature is in, it stays in.
 
+That is the ordinary revisit, and it is what the moves below describe. The one exception is a **lap**: a Rethink from review opens this same session with a lap kickoff and a bigger job — see **Lap mode** below, and work that section instead.
+
 ## 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.
@@ -23,18 +25,26 @@ The human came back: they remembered a constraint, changed their mind, or learne
    - `done` work now wrong → emit a NEW ticket that corrects it. Never touch done/burning tickets.
 5. **Close.** `mcp__runcastle__record_event({ type: "feature.revisited", message: "<one-line gist of what changed>" })`, then tell the human what state you left things in — especially whether a re-Burn is needed (pending tickets exist and the feature is at `implementation`).
 
-## Review iteration ("Iterate")
+## Lap mode (a Rethink)
+
+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.
+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`.
+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.
+8. **Hand to Burn.** Tell the human in a line or two what this lap does, then:
 
-At the **review** phase this same session is surfaced as **Iterate**: the tickets were burned, the human test-drove the branch, and now they want to fix what they found. The moves are the same — docs, then ticket surgery — with a review flavour:
+   > Lap `<n>` is specced and carded. Review the ticket cards and click **Burn** — I'll stop here.
 
-1. **Read the outcome first.** `get_feature_context` carries the latest run outcome and every ticket's final state (done / failed / cancelled). Skim it before the interview so you know what already shipped and what failed.
-2. **Interview about the test drive.** Ask what they hit — bugs, rough edges, missing polish, follow-on tweaks. One concrete change per fix ticket.
-3. **Emit fix tickets.** New work → `emit_tickets`. If a just-burned ticket was wrong, emit a NEW fix ticket (never reopen `done` work). Reconcile stale pending tickets with `update_ticket` / `cancel_ticket`.
-4. **Hand back to Burn.** Do NOT advance the phase. When the cards are ready, tell the human to review them and click **Burn** — burning from review loops the feature back through implementation, and the run returns it to review when it finishes. The loop repeats until they click Merge & ship.
+If the rethink turns out to be genuinely big — whole branches of design reopened, decisions hanging on material nobody has read — say so and escalate the way ideation would (`/runcastle:ideate` §3, the map), rather than grinding it out here.
 
 ## Do NOT
 
-- **Never call `complete_phase`.** A revisit has no gates to cross; the human drives the pipeline from the UI.
+- **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.