@renzrollon/interlock 1.1.0 → 1.2.0

package/lib/waves.mjs

@@ -8,9 +8,13 @@
 // Two rules exist specifically to stop the classifier from harming the run:
 //
 //   1. Model clamp. Classifiers reliably over-assign `opus` to anything that
-//      touches several files. Sonnet handles tiers 1-4; opus survives only on a
-//      true tier-5 task. The clamp is applied after classification so the model
-//      cannot escalate itself, and every clamp is reported.
+//      touches several files. The clamp keeps a task's recorded model at haiku
+//      or sonnet below tier 5, and opus only on a true tier-5 task, so the
+//      model cannot escalate itself. That clamped model is what a single-task
+//      lane dispatches on. A lane of two or more tasks dispatches on opus only
+//      when its hardest tier clears `LANE_CAPS.opusMinTier` (or every task
+//      already carries opus, as in solo); otherwise it runs on sonnet. Every
+//      clamp is reported.
 //
 //   2. Fan-out cap. A wave is a set of independent tasks, so the temptation is
 //      to spawn all of them at once. The original implementation did exactly
@@ -44,6 +48,8 @@
 //      colliding tasks become one lane. Lanes in a batch are path-disjoint and
 //      run in parallel; `LANE_CAPS.byTier` bounds how much one interruption can
 //      discard, and a uniform override of 1 reproduces one agent per task.
+//      Inside a layer a lane is a collision or a cohesion fold. A chain (rule 8)
+//      is formed later, from batches, and does not change how those two are built.
 //
 //   6. Cohesion. Collision alone made every path-disjoint task its own agent,
 //      however small: seven tasks each writing one `evals/*/case.yaml` were
@@ -53,6 +59,7 @@
 //      hardest component first, bounded by that lane's per-tier cap. Tier 4 and
 //      5 work is excluded on purpose: cross-file pattern-following is where a
 //      fresh context per task still pays for itself. Every fold is reported.
+//      Cohesion stays inside one dependency layer of one section.
 //
 //   7. Solo. A small change may be planned as ONE lane — every implementation
 //      task in section, layer and id order, then every test task — run by one
@@ -61,6 +68,17 @@
 //      classifier's recommendation if the change fits, then waves. The mode,
 //      its source and its reason are on the plan, because a run that silently
 //      changed its own shape is the failure the plan preview exists to remove.
+//      A solo plan is not chain-fused. One agent for the whole change is already
+//      what solo is.
+//
+//   8. Chain fusion. After the singleton fold, and inside the trailing test
+//      wave, every run of consecutive batches that each hold exactly one lane
+//      becomes one chain lane, packed next-fit under the same per-tier cap. A
+//      batch of two or more lanes is left alone, so work that was going to run
+//      concurrently still does. Fusion never crosses a wave. A chain runs in
+//      the batch order it was fused from, never re-sorted by task id. Its model
+//      follows `laneModel` — opus only when the hardest tier clears the
+//      published floor, otherwise sonnet.
 //
 // The second half of this file *executes* that plan — as a state machine, not a
 // runner. The orchestration is moving into a dynamic-workflow script, which can
@@ -111,6 +129,8 @@ export const LANE_COLLISION = 'collision'
 export const LANE_COHESION = 'cohesion'
 /** The single lane of a solo plan: the whole change, in order, on one agent. */
 export const LANE_SOLO = 'solo'
+/** A lane fused from consecutive single-lane batches of one wave. */
+export const LANE_CHAIN = 'chain'
 
 /** The two plan shapes. `auto` is not one — it is the absence of an override. */
 export const MODE_WAVES = 'waves'
@@ -487,13 +507,6 @@ function capForTier(caps, tier) {
   return Number.isInteger(cap) && cap > 0 ? cap : 1
 }
 
-/**
- * The model a lane dispatches on — the one assigned to its hardest task.
- *
- * A lane is one agent, and that agent has to be capable of everything in it.
- * Taking the first task's model would run a tier-5 task on whatever tier 1 was
- * given, which is the one direction of this trade that is not survivable.
- */
 /**
  * The label a lane runs under — the name its agent, its trajectory line and its
  * briefing file all carry.
@@ -507,10 +520,53 @@ export function laneLabel(lane) {
   return lane.length === 1 ? lane[0].id : `${lane[0].id}+${lane.length - 1}`
 }
 
+/** Separates a spawn's label from the words its title adds. */
+export const TITLE_SEPARATOR = ' · '
+
+/** The longest title a lane displays under, ellipsis included. */
+const TITLE_MAX = 48
+
+/**
+ * The name a lane is SHOWN under — its label, then the first words of its first
+ * task's description: `1.1+5 · Add the relaunch guard to…`.
+ *
+ * Display only. Everything that joins on a lane — its briefing file, worktree,
+ * trajectory line, record-batch fold — keys on `laneLabel`, because a key built
+ * from prose would change whenever a task was reworded. It is still a pure
+ * function of the lane, so a replay displays, and cache-hits, the same agent.
+ */
+export function laneTitle(lane) {
+  const label = laneLabel(lane)
+  const first = lane[0] && typeof lane[0].description === 'string' ? lane[0].description : ''
+  const words = first.replace(/[`*_]/g, '').replace(/\s+/g, ' ').trim().split(' ').slice(0, 6).join(' ')
+  const gist = words.replace(/[\s.,;:—-]+$/, '')
+  if (!gist) return label
+  const full = `${label}${TITLE_SEPARATOR}${gist}`
+  return full.length <= TITLE_MAX ? full : `${full.slice(0, TITLE_MAX - 1).trimEnd()}…`
+}
+
+/**
+ * The model a lane dispatches on, derived from the lane's shape and hardest tier.
+ *
+ * A lane of one task dispatches on that task's clamped model — haiku or sonnet,
+ * or opus for a tier-5 task or a solo promotion. A lane of two or more tasks is
+ * the work agent the planner chose not to split: it dispatches on opus when its
+ * hardest tier is at or above `LANE_CAPS.opusMinTier`, or when every task already
+ * carries opus (solo promotion of the whole change). Otherwise it runs on
+ * sonnet — routine multi-task work no longer pays the flagship model by default.
+ * Nothing here rewrites `task.model`: a narrowed lane of one returns to the
+ * task's model.
+ */
 export function laneModel(lane) {
-  const tier = laneTier(lane)
-  const hardest = lane.find(t => t.tier === tier)
-  return (hardest && hardest.model) || (lane[0] && lane[0].model) || 'sonnet'
+  if (!Array.isArray(lane) || lane.length === 0) return 'sonnet'
+  if (lane.length === 1) {
+    const only = lane[0]
+    return (only && only.model) || 'sonnet'
+  }
+  // Solo promotions rewrite every task to opus after the clamp; an all-opus
+  // multi-task lane is that decision (or a pure tier-5 pack), not the floor.
+  if (lane.every(t => t && t.model === 'opus')) return 'opus'
+  return laneTier(lane) >= LANE_CAPS.opusMinTier ? 'opus' : 'sonnet'
 }
 
 /**
@@ -522,8 +578,9 @@ export function laneModel(lane) {
  *
  * Returns `null` (inherit the session default — do not force) for tiers 3–4 by
  * policy and for an untiered lane (`laneTier` → 0) by fallback; the plan's
- * effort report distinguishes the two. Effort is orthogonal to the model clamp:
- * both are derived from tier so a future model tweak never silently moves effort.
+ * effort report distinguishes the two. Effort is derived from tier alone. The
+ * model a lane dispatches on follows shape and the opus floor, so a multi-task
+ * lane of tier-1 or tier-2 tasks runs on sonnet at `low`.
  */
 export function laneEffort(lane) {
   const tier = laneTier(lane)
@@ -817,6 +874,67 @@ function foldSingletonWaves(planned) {
   return { waves, folded }
 }
 
+/**
+ * Fuse consecutive single-lane batches of one wave into chain lanes.
+ *
+ * A batch of one lane buys no parallelism, so next-fit appends it to the open
+ * chain while the chain stays within the cap for the hardest tier across the
+ * chain and the lane being appended. A batch of two or more lanes closes the
+ * open chain and is emitted untouched. A chain drawn from a single batch keeps
+ * that batch's array identity; a chain drawn from two or more is one new lane,
+ * in batch order, never re-sorted by task id.
+ *
+ * @param {Array<Array<Array>>} batches
+ * @param {Record<number, number>} laneCaps
+ * @returns {{batches: Array, chains: Array}}
+ */
+function fuseSerialBatches(batches, laneCaps) {
+  const out = []
+  const chains = []
+  let open = null
+
+  const emitOpen = () => {
+    if (!open) return
+    if (open.sources === 1) {
+      out.push(open.batch)
+    } else {
+      const lane = open.tasks
+      out.push([lane])
+      chains.push({
+        tasks: lane,
+        ids: lane.map(t => t.id),
+        fusedBatches: open.sources,
+        tier: open.tier,
+        cap: capForTier(laneCaps, open.tier)
+      })
+    }
+    open = null
+  }
+
+  for (const batch of batches) {
+    if (!Array.isArray(batch) || batch.length !== 1) {
+      emitOpen()
+      out.push(batch)
+      continue
+    }
+    const lane = batch[0]
+    const tier = laneTier(lane)
+    if (open) {
+      const hardest = Math.max(open.tier, tier)
+      if (open.tasks.length + lane.length <= capForTier(laneCaps, hardest)) {
+        open.tasks.push(...lane)
+        open.tier = hardest
+        open.sources += 1
+        continue
+      }
+      emitOpen()
+    }
+    open = { tasks: lane.slice(), tier, sources: 1, batch }
+  }
+  emitOpen()
+  return { batches: out, chains }
+}
+
 /**
  * Every claimed path on every task is documentation.
  *
@@ -1067,11 +1185,15 @@ export function planWaves(input, opts = {}) {
   const deferred = []
   const laneEntries = []
   const promoted = []
+  const chains = []
   let planned = []
   let waves = []
   let folded = []
   let testWave = null
   let widest = 0
+  // Post-fold, pre-fusion. Solo never fuses, and its lane count is 1, so the
+  // serial warning's threshold is the same either way.
+  let preFusionLaneCount = 0
 
   if (solo) {
     // Every task on one agent, so there is nothing to pack: `foldSingletonWaves`,
@@ -1183,31 +1305,78 @@ export function planWaves(input, opts = {}) {
       }
       testWave = { taskCount: testTasks.length, batches }
     }
+
+    // Measured before fusion. A chain the planner is about to fuse is not a
+    // shape the operator still has to fix, so the serial warning keeps the
+    // post-fold count it had before this step existed.
+    preFusionLaneCount = waves.reduce((n, w) => n + waveLanes(w).length, 0)
+    const fusedWaves = []
+    for (const wave of waves) {
+      const fused = fuseSerialBatches(wave.batches, laneCaps)
+      for (const chain of fused.chains) chains.push({ group: wave.group, ...chain })
+      fusedWaves.push({ ...wave, batches: fused.batches })
+    }
+    waves = fusedWaves
+    if (testWave) {
+      const fused = fuseSerialBatches(testWave.batches, laneCaps)
+      for (const chain of fused.chains) chains.push({ group: null, ...chain })
+      testWave = { ...testWave, batches: fused.batches }
+    }
   }
 
   const implCount = implTasks.length
 
-  // Every lane holding more than one task, so a fold is visible rather than
-  // inferred from a smaller agent bill. A lane of one is not a fold and is not
-  // listed — the plan would otherwise report a "fold" for every task it has.
+  // Every dispatched lane holding more than one task, so a fold is visible
+  // rather than inferred from a smaller agent bill. A lane of one is not a fold
+  // and is not listed.
   //
-  // Read off the entries the packer produced rather than re-walked from the
-  // waves, because `kind` is a fact about how the lane was BUILT and cannot be
-  // recovered from the lane's contents afterwards. The test wave's lanes are
-  // listed too (with a null group): a cohesion fold there is exactly as much a
-  // fold as one in an implementation wave.
+  // Solo reads the build-time entries: there is one lane and its kind is a fact
+  // about how it was built. Waves mode reads the lanes that will dispatch, after
+  // fusion. A chain's kind cannot be recovered from its tasks, so it is taken
+  // from the fusion record; a lane fusion left untouched keeps the array the
+  // packer built, and its kind comes from that entry. The test wave's lanes are
+  // listed too (with a null group).
+  const listedLane = (group, tasks, kind, cap, extra) => ({
+    group,
+    kind,
+    ids: tasks.map(t => t.id),
+    tier: laneTier(tasks),
+    cap,
+    model: laneModel(tasks),
+    effort: laneEffort(tasks),
+    ...extra
+  })
   const lanes = []
-  for (const { group, entry } of laneEntries) {
-    if (entry.tasks.length < 2) continue
-    lanes.push({
-      group,
-      kind: entry.kind,
-      ids: entry.tasks.map(t => t.id),
-      tier: laneTier(entry.tasks),
-      cap: entry.cap,
-      model: laneModel(entry.tasks),
-      effort: laneEffort(entry.tasks)
-    })
+  if (solo) {
+    for (const { group, entry } of laneEntries) {
+      if (entry.tasks.length < 2) continue
+      lanes.push(listedLane(group, entry.tasks, entry.kind, entry.cap))
+    }
+  } else {
+    const chainByTasks = new Map(chains.map(c => [c.tasks, c]))
+    const entryByTasks = new Map(laneEntries.map(({ entry }) => [entry.tasks, entry]))
+    const consider = (group, wave) => {
+      if (!wave) return
+      for (const lane of waveLanes(wave)) {
+        if (lane.length < 2) continue
+        const chain = chainByTasks.get(lane)
+        if (chain) {
+          lanes.push(listedLane(group, lane, LANE_CHAIN, chain.cap, { fusedBatches: chain.fusedBatches }))
+          continue
+        }
+        const entry = entryByTasks.get(lane)
+        lanes.push(
+          listedLane(
+            group,
+            lane,
+            entry ? entry.kind : LANE_COLLISION,
+            entry ? entry.cap : capForTier(laneCaps, laneTier(lane))
+          )
+        )
+      }
+    }
+    for (const wave of waves) consider(wave.group, wave)
+    if (testWave) consider(null, testWave)
   }
   const laneCount = waves.reduce((n, w) => n + waveLanes(w).length, 0)
 
@@ -1243,36 +1412,47 @@ export function planWaves(input, opts = {}) {
       `widest wave has ${widest} tasks; splitting into batches of ${maxParallel}`
     )
   }
-  // Measured on the collapsed list and in lanes, because a lane is one agent:
-  // a staircase the fold already removed, or a chain the lanes already folded,
-  // is not a shape the operator still has to fix.
-  if (laneCount >= 2 && waves.length > laneCount * 0.5) {
+  // Measured on the post-fold, pre-fusion lane count. A chain the planner has
+  // already fused is not a shape the operator still has to fix, and neither is
+  // a staircase the singleton fold already removed.
+  if (preFusionLaneCount >= 2 && waves.length > preFusionLaneCount * 0.5) {
     warnings.push(
-      `effectively serial: ${waves.length} waves for ${laneCount} implementation lane(s)`
+      `effectively serial: ${waves.length} waves for ${preFusionLaneCount} implementation lane(s)`
     )
   }
-  // One warning per fold, phrased by KIND. A cohesion fold is not a collision:
-  // an operator reading "share a file" about seven path-disjoint tasks would go
-  // looking for a file they do not share.
-  for (const lane of lanes) {
-    if (lane.kind === LANE_SOLO) {
+  // Build-time warnings, phrased by KIND, from the entries the packer produced.
+  // A cohesion fold that later became part of a chain is still named here. A
+  // cohesion fold is not a collision: an operator reading "share a file" about
+  // seven path-disjoint tasks would go looking for a file they do not share.
+  for (const { group, entry } of laneEntries) {
+    if (entry.tasks.length < 2) continue
+    const ids = entry.tasks.map(t => t.id)
+    const tier = laneTier(entry.tasks)
+    if (entry.kind === LANE_SOLO) {
       warnings.push(
-        `solo lane: tasks ${lane.ids.join(', ')} run in that order on one opus agent — ` +
+        `solo lane: tasks ${ids.join(', ')} run in that order on one opus agent — ` +
           `every section barrier and dependency edge is honoured by position in the lane`
       )
-    } else if (lane.kind === LANE_COHESION) {
+    } else if (entry.kind === LANE_COHESION) {
       warnings.push(
-        `tasks ${lane.ids.join(', ')} are path-disjoint tier-${lane.tier} work in ` +
-          `${laneWhere(lane.group)}; packed into one cohesion lane run by a single agent in that ` +
-          `order (tier-${lane.tier} lane cap ${lane.cap})`
+        `tasks ${ids.join(', ')} are path-disjoint tier-${tier} work in ` +
+          `${laneWhere(group)}; packed into one cohesion lane run by a single agent in that ` +
+          `order (tier-${tier} lane cap ${entry.cap})`
       )
     } else {
       warnings.push(
-        `tasks ${lane.ids.join(', ')} share a file in ${laneWhere(lane.group)}; folded into one ` +
-          `lane run by a single tier-${lane.tier} agent in that order`
+        `tasks ${ids.join(', ')} share a file in ${laneWhere(group)}; folded into one ` +
+          `lane run by a single tier-${tier} agent in that order`
       )
     }
   }
+  for (const chain of chains) {
+    warnings.push(
+      `tasks ${chain.ids.join(', ')} were ${chain.fusedBatches} consecutive single-lane batches in ` +
+        `${laneWhere(chain.group)}; fused into one chain lane run by one ${laneModel(chain.tasks)} agent in that order ` +
+        `(tier-${chain.tier} lane cap ${chain.cap})`
+    )
+  }
   for (const f of folded) {
     warnings.push(
       `task ${f.id} was a 1-task wave in group ${f.from}; folded into wave ${f.to} as a later ` +
@@ -1311,7 +1491,7 @@ export function planWaves(input, opts = {}) {
         ? `task ${d.id} declares dependsOn ${d.after.join(', ')}; it runs after them inside the ` +
           `solo lane rather than beside them`
         : `task ${d.id} declares dependsOn ${d.after.join(', ')}; it runs after them in ` +
-          `${laneWhere(d.group)}, in a later batch or wave rather than beside them`
+          `${laneWhere(d.group)}, in a later batch, wave or lane position rather than beside them`
     )
   }
 
@@ -1434,6 +1614,12 @@ export function formatPlan(plan) {
         `  cohesion ${lane.ids.join(' → ')}: ${lane.ids.length} path-disjoint tasks in ` +
           `${laneWhere(lane.group)} on one ${lane.model}/T${lane.tier} agent (cap ${lane.cap})`
       )
+    } else if (lane.kind === LANE_CHAIN) {
+      lines.push(
+        `  chain ${lane.ids.join(' → ')}: ${lane.ids.length} tasks in ` +
+          `${laneWhere(lane.group)} on one ${lane.model}/T${lane.tier} agent ` +
+          `(${lane.fusedBatches} batches, cap ${lane.cap})`
+      )
     } else {
       lines.push(
         `  lane ${lane.ids.join(' → ')}: ${lane.ids.length} tasks in ${laneWhere(lane.group)} on ` +
@@ -1782,30 +1968,38 @@ function makeWave(kind, group, tasks, maxParallel, laneCaps, opts = {}) {
   // outcome-audit fields already make: a run resumed across an upgrade must
   // still be able to replan.
   const caps = laneCaps && typeof laneCaps === 'object' ? laneCaps : LANE_CAPS.byTier
+  // Cloned, then clamped, so a replanned task obeys the same model clamp the
+  // planner applied at plan time. The caller's objects are left untouched.
+  const clamped = []
+  const cloned = tasks.map(t => {
+    const copy = { ...t }
+    const record = clampModel(copy)
+    if (record) clamped.push(record)
+    return copy
+  })
+  // Layered by `dependsOn` the way initial planning is, so a revision that
+  // carries edges keeps their order. The layers become later BATCHES here
+  // rather than separate waves, because a replan revises one group into one
+  // wave — and those single-lane batches then fuse under the caps the run was
+  // planned with, the same way planWaves fuses after the fold.
+  const built = layerByDependencies(cloned).flatMap(
+    layer => collisionAwareChunk(layer, maxParallel, serialized, group, caps).batches
+  )
+  const fused = fuseSerialBatches(built, caps)
   return {
-    kind,
-    group,
-    // Preserved across a replan. The marker is what stops the red wave's
-    // failing suite being treated as a defect, so a revision that rebuilt the
-    // group without it would restore exactly the halt this wave exists to
-    // avoid — and would do it only on replanned runs, which is the hardest
-    // version of that bug to find.
-    ...(opts.red === true ? { red: true } : {}),
-    taskCount: tasks.length,
-    // A replanned group is laned under the SAME caps the rest of the run was
-    // planned with, read off the state. Falling back to the current published
-    // table would let a replan mid-run produce lanes of a different length than
-    // the plan the run started from — including under a uniform override, which
-    // is already folded into the table the state carries.
-    //
-    // And it is layered by `dependsOn` the way initial planning is, so a
-    // revision that carries edges keeps their order. The layers become later
-    // BATCHES here rather than separate waves, because a replan revises one
-    // group into one wave — a later batch expresses the same ordering, which is
-    // what the singleton fold would have collapsed the extra wave into anyway.
-    batches: layerByDependencies(tasks).flatMap(
-      layer => collisionAwareChunk(layer, maxParallel, serialized, group, caps).batches
-    )
+    clamped,
+    wave: {
+      kind,
+      group,
+      // Preserved across a replan. The marker is what stops the red wave's
+      // failing suite being treated as a defect, so a revision that rebuilt the
+      // group without it would restore exactly the halt this wave exists to
+      // avoid — and would do it only on replanned runs, which is the hardest
+      // version of that bug to find.
+      ...(opts.red === true ? { red: true } : {}),
+      taskCount: cloned.length,
+      batches: fused.batches
+    }
   }
 }
 
@@ -2525,13 +2719,15 @@ export function applyReplan(state, revisedGroups) {
       const wasRed = next.waves[at] && next.waves[at].red === true
       if (!revision.tasks.length) next.waves.splice(at, spans)
       else {
-        next.waves.splice(
-          at,
-          spans,
-          makeWave('impl', revision.group, revision.tasks, next.maxParallel, next.laneCaps, {
-            red: wasRed
-          })
-        )
+        const made = makeWave('impl', revision.group, revision.tasks, next.maxParallel, next.laneCaps, {
+          red: wasRed
+        })
+        next.waves.splice(at, spans, made.wave)
+        for (const c of made.clamped) {
+          next.warnings.push(
+            `task ${c.id} clamped ${c.from} → ${c.to} (tier ${c.tier}) on replan of group ${revision.group}`
+          )
+        }
       }
       continue
     }
@@ -2550,7 +2746,13 @@ export function applyReplan(state, revisedGroups) {
         break
       }
     }
-    next.waves.splice(insertAt, 0, makeWave('impl', revision.group, revision.tasks, next.maxParallel, next.laneCaps))
+    const made = makeWave('impl', revision.group, revision.tasks, next.maxParallel, next.laneCaps)
+    next.waves.splice(insertAt, 0, made.wave)
+    for (const c of made.clamped) {
+      next.warnings.push(
+        `task ${c.id} clamped ${c.from} → ${c.to} (tier ${c.tier}) on replan of group ${revision.group}`
+      )
+    }
   }
 
   next.replansUsed += 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renzrollon/interlock",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
   "type": "module",
   "engines": {
@@ -18,6 +18,7 @@
     "workflows",
     "skills",
     "hooks",
+    "types",
     "agents",
     "shared",
     ".claude-plugin",

package/shared/TEST-PROFILE.md

@@ -5,8 +5,9 @@ Durable, machine-readable record of how a project's tests run. Owned by
 re-sniff `package.json` on every run.
 
 **Path:** `.claude/testing/profile.json`  
-**Human mirror:** idempotent `## Testing` block in `CLAUDE.md` (or `AGENTS.md`
-on Cursor-only projects) between HTML comment markers (see below).
+**Human mirror:** idempotent `## Testing` block in the project's instruction
+file — `CLAUDE.md`, `.claude/CLAUDE.md`, or `AGENTS.md` on Cursor-only
+projects — between HTML comment markers (see below).
 
 Learned gotchas discovered mid-fix go to
 `.claude/memory/failure-modes/<slug>.md` (max 3 per session) — **not** into
@@ -153,9 +154,13 @@ reuse as-is.
 
 ## Human mirror (`## Testing` block)
 
-Write (or replace) content **between** these markers inside `CLAUDE.md`
-(prefer) or `AGENTS.md` (if that is the project's agent doc and `CLAUDE.md`
-is absent):
+Write (or replace) content **between** these markers inside the first of
+these that exists: `CLAUDE.md` at the root, then `.claude/CLAUDE.md`, then
+`AGENTS.md` (if that is the project's agent doc). Create a root `CLAUDE.md`
+only when none of the three exists. A repository that is also a Claude Code
+plugin keeps its instructions in `.claude/CLAUDE.md`, because
+`claude plugin validate --strict` rejects a `CLAUDE.md` at the plugin root; a
+mirror that recreated one there would turn that repository's CI red.
 
 ```markdown
 ## Testing

package/skills/fix-tests/SKILL.md

@@ -34,7 +34,7 @@ Resolve `typecheck.command` and `lint.command` on the same pass, the way `covera
 
 This is the only skill permitted to interview the user about tests. Every later run is zero-question.
 
-Persist the profile and mirror it into the `## Testing` block in `CLAUDE.md` (or `AGENTS.md`), between the managed markers, idempotently.
+Persist the profile and mirror it into the `## Testing` block of the first instruction file that exists — `CLAUDE.md`, then `.claude/CLAUDE.md`, then `AGENTS.md` — between the managed markers, idempotently.
 
 ---
 

package/types/index.d.ts

@@ -0,0 +1,28 @@
+// Interlock's type contract: the session state its hooks module keeps
+// (guard-ship-relaunch-in-process design D2). `.claude-plugin/plugin.json`
+// names this file as `types`; `claude plugin validate` holds every `$.state`
+// key `hooks/mod.mjs` reads or writes to the keys declared here.
+//
+// One key, the launch guard's record, in the shape `lib/launch-rule.mjs`
+// reads and the settings form's file ledger holds: times are ISO strings.
+
+/** One ship launch the runtime accepted, as its result named it. */
+export type Launch = {
+  at: string
+  runId: string | null
+  workflowName: string | null
+  scriptPath: string | null
+}
+
+/** The session's launches and the time of its last human prompt. */
+export type LaunchRecord = {
+  schema: 'interlock.launch-ledger/1'
+  launches: Launch[]
+  lastHumanPromptAt: string | null
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    interlock: { ledger: LaunchRecord }
+  }
+}