@renzrollon/interlock 1.0.2 → 1.1.1

package/lib/waves.mjs

@@ -8,9 +8,12 @@
 // 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
+//      (rule 8) without rewriting any task's recorded model. 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 +47,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 +58,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 +67,16 @@
 //      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, and it
+//      dispatches on opus because it holds more than one task.
 //
 // 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 +127,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 +505,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 +518,18 @@ export function laneLabel(lane) {
   return lane.length === 1 ? lane[0].id : `${lane[0].id}+${lane.length - 1}`
 }
 
+/**
+ * The model a lane dispatches on, derived from the lane's shape.
+ *
+ * A lane of two or more tasks is the work agent the planner chose not to split,
+ * so it dispatches on opus. 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. 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 (lane.length >= 2) return 'opus'
+  const only = lane[0]
+  return (only && only.model) || 'sonnet'
 }
 
 /**
@@ -522,8 +541,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 the lane's shape, so an opus lane of
+ * tier-1 or tier-2 tasks still runs at `low`.
  */
 export function laneEffort(lane) {
   const tier = laneTier(lane)
@@ -817,6 +837,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 +1148,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 +1268,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 +1375,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 opus 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 +1454,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 +1577,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 +1931,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 +2682,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 +2709,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.0.2",
+  "version": "1.1.1",
   "description": "Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec",
   "type": "module",
   "engines": {

package/shared/TOOL-ECONOMY.md

@@ -110,10 +110,17 @@ one you need. When Rule 0 applies, graph query/consumers counts as “locate.”
 
 At session start, current-task context comes from a few cheap, authoritative
 sources — `git log --oneline`, `git status --short`, `openspec status --json`,
-an open-task grep over `openspec/changes/*/tasks.md`, and the latest handoff.
+an open-task grep over `openspec/changes/*/tasks.md`, and the latest explore
+brief (`.claude/handoff/explore-*.md`).
 Front-load these in one pass. Read them,
 then act. Do not re-traverse the tree to reconstruct what they already tell you.
 
+The glob is load-bearing, not tidiness. `.claude/handoff/` also holds
+`ship-*.md` halt resume cards, which are records of runs that already stopped —
+nothing reads them, and finding one is not permission to start anything. Reading
+"the latest handoff" unqualified after a halt would hand you one as if it were
+session context.
+
 **Explore brief as Rule-3 state:** when `/interlock:spec` runs after explore
 (especially after `/clear` or prompt-cache expiry), read the latest matching
 `.claude/handoff/explore-*.md` first (see `EXPLORE-BRIEF.md`).