cclaw-cli 7.7.0 → 7.7.1

package/dist/content/core-agents.js

@@ -153,6 +153,8 @@ export function sliceBuilderProtocol() {
         "",
         "**slice-builder** is the canonical worker for **one feature-atomic implementation unit/slice** end-to-end: **RED → GREEN → REFACTOR → inline DOC** in **one** delegated span. The unit may contain internal 2-5 minute TDD steps; do not split those into separate agents unless the parent selected `strict-micro`. Multiple slice-builder spans run in parallel only when topology is `parallel-builders` and the wave plan declares disjoint `claimedPaths`.",
         "",
+        "**Multi-slice batch under `single-builder`:** the controller may dispatch ONE slice-builder span that owns MORE than one ready slice (e.g. when the router collapses a wave into single-builder mode). Treat each slice in the batch as its own RED → GREEN → REFACTOR → DOC mini-cycle: emit a separate `phase=red|green|refactor|doc` row per `--slice` value (use the same `spanId`/`dispatchId` for the whole batch), keep `claimedPaths` disjoint per-slice within the batch, and author one `tdd-slices/S-<id>.md` per slice. Phase-status rules from the table below stay unchanged — never collapse multiple slices into one phase row.",
+        "",
         "### Invariants",
         "- Produce failing RED evidence (or cite the delegated RED artifact) **before** production edits.",
         "- Stay inside the slice contract: `claimedPaths`, acceptance mapping, and forbidden-change lists from the parent.",

package/dist/content/meta-skill.js

@@ -57,15 +57,17 @@ If you think any of these, stop and follow the routing flow:
 - "I can answer from memory without loading the active stage skill." -> No. Load the skill first.
 - "Hook guard warned, but I can ignore it." -> No. Resolve the warning before continuing.
 - "I'll edit \`.cclaw/state\` directly to move faster." -> No. Use managed commands only.
-- "I'll just do the worker's job inline so we move faster." -> Only if the active TDD topology is explicitly \`inline\`; otherwise see the Controller dispatch discipline below.
+- "I'll just do the worker's job inline so we move faster." -> Only if the active TDD topology is explicitly \`inline\` (\`nextDispatch.mode = controller-inline\` from \`wave-status\`); otherwise see the Controller dispatch discipline below.
 
 ## Controller dispatch discipline (applies to every stage)
 
-cclaw stages have **mandatory delegations** (TDD normally routes through \`slice-builder\`; review: \`reviewer\` + \`security-reviewer\`; design: \`architect\`; scope: \`planner\`; etc.). The controller is the **orchestrator**, not the worker, except when TDD topology is explicitly \`inline\` for a low-risk unit. When a stage declares a mandatory delegation:
+cclaw stages have **mandatory delegations** (TDD normally routes through \`slice-builder\`; review: \`reviewer\` + \`security-reviewer\`; design: \`architect\`; scope: \`planner\`; etc.). The controller is the **orchestrator**, not the worker, except when the TDD router selects \`inline\` (a non-high-risk discovery/scaffold/docs ready set with no path conflicts). When a stage declares a mandatory delegation:
 
-- **Dispatch via the harness Task tool unless topology says inline.** Do NOT write the worker's output (slice code, review findings, architect notes) into the artifact yourself as a substitute for delegating. For TDD \`inline\`, record the routing reason and satisfy the same RED/GREEN/REFACTOR, AC traceability, path containment, managed commit/worktree, lockfile twin, and orphan-change gates.
-- **Parallel only when topology says parallel-builders.** TDD fan-out requires genuinely independent substantial units with disjoint \`claimedPaths\`; review-army (independent reviewer lenses) MUST emit all parallel \`Task\` calls in a SINGLE controller message — not sequentially over multiple turns. The controller waits for all spans to return before reconciling.
+- **Dispatch via the harness Task tool unless topology says inline.** Do NOT write the worker's output (slice code, review findings, architect notes) into the artifact yourself as a substitute for delegating. For TDD \`inline\`, record \`delegation-record\` lifecycle rows with \`--dispatch-surface=role-switch\` and \`--agent-definition-path=.cclaw/skills/tdd/SKILL.md\` (scheduled → completed with \`--evidence-ref\`) and satisfy the same RED/GREEN/REFACTOR, AC traceability, path containment, managed commit/worktree, lockfile twin, and orphan-change gates.
+- **\`single-builder\`: one Task covers the wave.** When the router chooses \`single-builder\` and the ready set has more than one slice, issue exactly ONE \`Task\` dispatch and let that single \`slice-builder\` span own multi-slice TDD for every currently ready member. Do not split the ready set into multiple Task calls when the router chose single-builder.
+- **Parallel only when topology says parallel-builders.** TDD fan-out requires genuinely independent substantial units with disjoint \`claimedPaths\` and at least one non-discovery ready unit (pure discovery-only sets are collapsed by the router); review-army (independent reviewer lenses) MUST emit all parallel \`Task\` calls in a SINGLE controller message — not sequentially over multiple turns. The controller waits for all spans to return before reconciling.
 - **Record lifecycle on the same span** via \`delegation-record --status=scheduled|launched|acknowledged|completed\`; the worker emits its own \`--phase=…\` and evidence rows. A \`completed\` row without a matching ACK or dispatch surface is a forgery.
+- **Trust the router; skip routing AskQuestions.** \`wave-status\` already returns \`nextDispatch.topology\`, \`nextDispatch.mode\`, and (when present) \`nextDispatch.controllerHint\`. Act on them; do not wrap an extra "launch wave or single builder?" confirmation around routing.
 - **Auto-advance when stage-complete returns ok.** When the helper reports a new \`currentStage\`, immediately load the next stage skill and continue. Announce \`Stage <prev> complete → entering <next>. Continuing.\` Do NOT pause for the user to retype \`/cc\` or say \"продолжай\" — that pause is the failure mode 7.0.2 explicitly removed. The only legitimate stop is a real blocker (missing user input, ambiguous decision, hook fail).
 
 ## Routing flow

package/dist/content/stages/tdd.js

@@ -37,21 +37,21 @@ export const TDD = {
     },
     executionModel: {
         checklist: [
-            "**Wave discovery:** Entering TDD, first call `node .cclaw/cli.mjs internal wave-status --json`. It parses the managed `<!-- parallel-exec-managed-start -->` block and reports the adaptive `topology`; read `05-plan.md`/`wave-plans/` only once `wave-status` names work. Restore partial waves by resuming remaining units.",
-            "**Topology routing:** Default `auto` + `balanced` means cheapest safe route: inline for one low-risk inline-safe unit, single-builder for one feature-atomic unit or conflicts, parallel-builders only for genuinely independent substantial units, strict-micro for high-risk/configured micro-slice work.",
-            "**Routing AskQuestion:** Two or more ready units with `topology=parallel-builders` ⇒ exactly one AskQuestion (“launch wave …” vs “single builder …”, default wave). Otherwise do not ask “which slice next?” when the plan already resolves it.",
+            "**Wave discovery:** Entering TDD, first call `node .cclaw/cli.mjs internal wave-status --json`. It parses the managed `<!-- parallel-exec-managed-start -->` block and reports `nextDispatch.topology`, `nextDispatch.mode`, and (when present) `nextDispatch.controllerHint`; read `05-plan.md`/`wave-plans/` only once `wave-status` names work. Restore partial waves by resuming remaining units.",
+            "**Topology routing:** Default `auto` + `balanced` means cheapest safe route: lane-aware inline collapse for non-high-risk discovery/scaffold/docs ready sets, single-builder for one feature-atomic unit or large discovery-only batches, parallel-builders only when at least one ready unit is non-discovery and the wave is genuinely independent + substantial, strict-micro for high-risk/configured micro-slice work. The router decides; the controller acts on its output without re-asking the user which slice to take next.",
             "**Record before dispatch:** For every `Task`, write `delegation-record` `--status=scheduled` then `--status=launched` before the tool call. Workers self-record `acknowledged` and `completed`; back-fill is `--repair` only.",
-            "**One worker per feature-atomic unit when delegated:** Dispatch `slice-builder` with `--slice S-<id>` and explicit `--paths` from the plan. The worker owns the unit's internal 2-5 minute RED/GREEN/REFACTOR steps. Parallel builders are allowed only when topology says `parallel-builders` and paths are disjoint; honor any lane/lease flags the hook requires today.",
-            "**Inline topology:** When the router/guidance chooses `inline`, the controller may execute the unit without a builder dispatch, but must still keep RED-before-GREEN, AC traceability, path containment, verification-before-completion, lockfile twin handling, managed commit/worktree policy, and orphan-change gates intact.",
-            "**Single span owns the delegated unit:** `slice-builder` runs RED → GREEN → REFACTOR (separate phase rows or `--refactor-outcome` on GREEN) and authors `<artifacts-dir>/tdd-slices/S-<id>.md`. Follow the agent body and `delegation-record` snippets it embeds.",
+            "**Honor `topology=inline` (controller-inline):** Do NOT use `Task` to dispatch `slice-builder` for inline slices. Write each ready slice's `claimedPaths` and any small file edits yourself, then record lifecycle rows with `--dispatch-surface=role-switch --agent-definition-path=.cclaw/skills/tdd/SKILL.md` (scheduled → completed, with `--evidence-ref` on completion). RED-before-GREEN, AC traceability, path containment, verification-before-completion, lockfile twin handling, managed commit/worktree policy, and orphan-change gates remain intact — the router only changes who does the work, not what evidence is required.",
+            "**Honor `topology=single-builder`:** Issue exactly ONE `Task` dispatch that covers ALL currently ready members of the wave. The single `slice-builder` span owns multi-slice TDD: RED → GREEN → REFACTOR (and inline DOC card) for every slice it received. Do not split that ready set into multiple separate Task calls when the router chose `single-builder`.",
+            "**Honor `topology=parallel-builders`:** Fan out only when at least one ready unit is non-discovery (router collapses pure discovery-only sets into inline/single-builder per the previous bullets) and `claimedPaths` are disjoint. Emit all parallel `Task` calls in a single controller message and wait for all spans before reconciling.",
+            "**Single span owns the delegated unit:** Dispatched `slice-builder` runs RED → GREEN → REFACTOR (separate phase rows or `--refactor-outcome` on GREEN) and authors `<artifacts-dir>/tdd-slices/S-<id>.md`. Follow the agent body and `delegation-record` snippets it embeds.",
             "**Wave closure:** When every slice/unit in the wave has GREEN + REFACTOR coverage, call `integrationCheckRequired`. Dispatch `integration-overseer` when required; otherwise emit `cclaw_integration_overseer_skipped` via `delegation-record --audit-kind=...`.",
             "**Plan triggers:** If the unit row demands extra scrutiny (`touchCount >= filesChangedThreshold`, matching `touchPaths`, or `highRisk`), capture that review posture in `tdd-slices/S-<id>.md` or via a reviewer dispatch before closing the slice.",
             "**Auto-render tables:** Do not hand-edit content between `auto-start: tdd-slice-summary` markers; the linter overwrites them from `delegation-events.jsonl`.",
             "**Active-span collisions:** If scheduling fails with `dispatch_duplicate` / `dispatch_active_span_collision`, identify the live span; use `--allow-parallel` or `--supersede` deliberately. Do not silence errors blindly.",
         ],
         interactionProtocol: [
-            "Parallel `slice-builder` tasks are allowed only when topology is `parallel-builders` and `claimedPaths` are disjoint; remain serial for dependencies, conflicts, high-risk units, or strict-micro chains.",
-            "Controller normally orchestrates delegated builders. In `inline` topology it may execute directly, but must record the routing decision and satisfy the same RED/GREEN/REFACTOR evidence gates before completion.",
+            "Parallel `slice-builder` tasks are allowed only when topology is `parallel-builders` and `claimedPaths` are disjoint; remain serial for dependencies, conflicts, high-risk units, or strict-micro chains. Pure discovery/scaffold/docs ready sets collapse to inline (or single-builder for large batches) — never one worker per markdown spike.",
+            "Controller normally orchestrates delegated builders. When topology is `inline` (mode `controller-inline`) it executes the wave's ready slices itself with `--dispatch-surface=role-switch` lifecycle rows, but must satisfy the same RED/GREEN/REFACTOR evidence gates before completion.",
             "Discover existing tests and commands before RED; run a system-wide impact check (callbacks, state, interfaces, contracts) before GREEN.",
             "RED must fail for the right reason; capture logs. GREEN must run the full relevant suite, not a narrow subset.",
             "Before calling a slice done, run verification-before-completion (command + PASS/FAIL + durable commit evidence: managed-per-slice git commits when `.git` is present, or explicit no-VCS attestation + hash).",
@@ -61,7 +61,7 @@ export const TDD = {
         process: [
             "Map the slice to acceptance criteria; read `ralph-loop.json` for open RED cycles before starting new work.",
             "Discover tests, fixtures, helpers, and commands; record impact on public surfaces.",
-            "Route the active unit via topology (`inline`, `single-builder`, `parallel-builders`, or `strict-micro`) before RED.",
+            "Read the topology + mode + controllerHint reported by `wave-status --json` and act on them (inline = controller fulfils ready set; single-builder = one Task covers all ready members; parallel-builders = one Task per disjoint ready unit; strict-micro = micro-slice fan-out).",
             "For delegated units, dispatch `slice-builder` for RED (failing tests, no production edits beyond test files).",
             "For delegated units, dispatch the same builder for GREEN with minimal production changes and full-suite evidence.",
             "Close REFACTOR inline, via deferred phase, or `--refactor-outcome` on GREEN — match what `delegation-record` expects.",

package/dist/execution-topology.d.ts

@@ -14,6 +14,14 @@ export interface ExecutionTopologyShape {
     requiresStrictMicro?: boolean;
     /** True when the controller can safely execute the unit inline in the current harness. */
     inlineSafe?: boolean;
+    /**
+     * 7.7.1 — count of ready units classified as discovery-only/scaffold/docs
+     * lanes that are not high-risk and have no path conflicts. When this equals
+     * `unitCount`, the auto router collapses the wave into `inline` (small
+     * batch) or `single-builder` (large batch) so trivial markdown spikes never
+     * fan out into one slice-builder span per file.
+     */
+    discoveryOnlyUnits?: number;
 }
 export interface ExecutionTopologyDecision {
     topology: Exclude<ExecutionTopology, "auto">;

package/dist/execution-topology.js

@@ -47,6 +47,28 @@ export function routeExecutionTopology(options) {
             reason: "path conflicts require serialized execution"
         };
     }
+    // 7.7.1 — lane-aware short-circuit. When every ready unit is a non-high-risk
+    // discovery/scaffold/docs lane with no path conflicts, never fan out: the
+    // controller should fulfil a small batch inline, or hand the whole wave to a
+    // single builder when the batch is large enough that one inline turn would
+    // bloat the controller transcript.
+    const discoveryOnly = shape.discoveryOnlyUnits ?? 0;
+    if (!shape.highRisk &&
+        discoveryOnly === unitCount &&
+        unitCount >= 1) {
+        if (unitCount <= 3) {
+            return {
+                topology: "inline",
+                maxBuilders,
+                reason: "discovery-only ready set; controller can fulfill inline"
+            };
+        }
+        return {
+            topology: "single-builder",
+            maxBuilders,
+            reason: "discovery-only ready set is large; one builder owns the wave"
+        };
+    }
     const independent = shape.independentUnitCount ?? unitCount;
     const substantial = shape.substantialUnitCount ?? unitCount;
     if (maxBuilders > 1 && independent >= 2 && substantial >= 2) {

package/dist/internal/wave-status.d.ts

@@ -13,14 +13,25 @@ export interface WaveStatusWaveSummary {
     blockedMembers: string[];
     status: "closed" | "open" | "partial" | "empty";
 }
+/**
+ * 7.7.1 — `controller-inline` is added so the controller knows it must
+ * fulfil the ready slices in this turn (no slice-builder dispatch). The
+ * remaining values (`single-slice`, `wave-fanout`, `blocked`, `none`) keep
+ * their pre-7.7.1 contract.
+ */
 export interface WaveStatusNextDispatch {
     waveId: string | null;
     readyToDispatch: string[];
     pathConflicts: string[];
-    mode: "single-slice" | "wave-fanout" | "blocked" | "none";
+    mode: "single-slice" | "wave-fanout" | "blocked" | "none" | "controller-inline";
     topology: Exclude<ExecutionTopology, "auto"> | "none";
     topologyReason: string;
     maxBuilders: number;
+    /**
+     * Optional natural-language hint for the controller, populated when the
+     * router selects a non-default mode (currently only `inline`).
+     */
+    controllerHint?: string;
 }
 export interface WaveStatusReport {
     activeRunId: string;

package/dist/internal/wave-status.js

@@ -57,7 +57,7 @@ function parsePipeRow(trimmedLine) {
 function normalizePathToken(raw) {
     return raw.trim().replace(/^`|`$/gu, "").replace(/^\.\/+/u, "");
 }
-function parseManagedWaveClaimedPaths(planMarkdown) {
+function parseManagedWaveSliceMeta(planMarkdown) {
     const out = new Map();
     const startIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_START);
     const endIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_END);
@@ -115,10 +115,52 @@ function parseManagedWaveClaimedPaths(planMarkdown) {
                 .split(",")
                 .map((p) => normalizePathToken(p))
                 .filter((p) => p.length > 0);
-        out.get(currentWaveId).set(sliceId, claimedPaths);
+        const laneIdx = headerIdx.get("lane");
+        const rawLane = laneIdx !== undefined ? (cells[laneIdx] ?? "") : "";
+        const lane = rawLane.replace(/^`|`$/gu, "").trim().toLowerCase();
+        const riskIdx = headerIdx.get("risktier");
+        const rawRisk = riskIdx !== undefined ? (cells[riskIdx] ?? "") : "";
+        const riskTier = rawRisk.replace(/^`|`$/gu, "").trim().toLowerCase();
+        out.get(currentWaveId).set(sliceId, {
+            claimedPaths,
+            lane: lane.length > 0 ? lane : undefined,
+            riskTier: riskTier.length > 0 ? riskTier : undefined
+        });
     }
     return out;
 }
+/**
+ * Backward-compatible projection: callers that only need claimed paths
+ * keep getting `Map<sliceId, paths[]>` shapes.
+ */
+function projectClaimedPaths(meta) {
+    const out = new Map();
+    for (const [sliceId, info] of meta) {
+        out.set(sliceId, info.claimedPaths);
+    }
+    return out;
+}
+const DISCOVERY_LANES = new Set(["scaffold", "docs"]);
+/**
+ * 7.7.1 — count ready members whose lane is `scaffold` or `docs` and whose
+ * `riskTier` is not `high`. Members with no recorded lane fall back to
+ * non-discovery (so the controller never collapses substantive work into
+ * inline by accident).
+ */
+function countDiscoveryOnlyUnits(readySlices, meta) {
+    let count = 0;
+    for (const sliceId of readySlices) {
+        const info = meta.get(sliceId);
+        if (!info)
+            continue;
+        if (!info.lane || !DISCOVERY_LANES.has(info.lane))
+            continue;
+        if (info.riskTier === "high")
+            continue;
+        count += 1;
+    }
+    return count;
+}
 function detectPathConflicts(readySlices, bySlice) {
     const conflicts = new Set();
     const ordered = [...readySlices].sort(compareSliceIds);
@@ -362,16 +404,18 @@ export async function runWaveStatus(projectRoot, options = {}) {
     }
     else {
         const readyToDispatch = [...firstOpenWave.readyMembers].sort(compareSliceIds);
-        const claimedPathsByWave = parseManagedWaveClaimedPaths(planRaw);
-        const conflicts = detectPathConflicts(readyToDispatch, claimedPathsByWave.get(firstOpenWave.waveId) ?? new Map());
-        const mode = conflicts.length > 0
+        const sliceMetaByWave = parseManagedWaveSliceMeta(planRaw);
+        const sliceMeta = sliceMetaByWave.get(firstOpenWave.waveId) ?? new Map();
+        const conflicts = detectPathConflicts(readyToDispatch, projectClaimedPaths(sliceMeta));
+        const discoveryOnlyUnits = countDiscoveryOnlyUnits(readyToDispatch, sliceMeta);
+        const baseMode = conflicts.length > 0
             ? "blocked"
             : readyToDispatch.length > 1
                 ? "wave-fanout"
                 : readyToDispatch.length === 1
                     ? "single-slice"
                     : "none";
-        const topologyDecision = mode === "none"
+        const topologyDecision = baseMode === "none"
             ? null
             : routeExecutionTopology({
                 configuredTopology,
@@ -382,9 +426,20 @@ export async function runWaveStatus(projectRoot, options = {}) {
                     independentUnitCount: conflicts.length > 0 ? 0 : readyToDispatch.length,
                     substantialUnitCount: readyToDispatch.length,
                     hasPathConflicts: conflicts.length > 0,
-                    inlineSafe: false
+                    inlineSafe: false,
+                    discoveryOnlyUnits
                 }
             });
+        // 7.7.1 — when the router collapses a discovery-only ready set into
+        // `inline`, surface `controller-inline` mode + a controllerHint so the
+        // controller knows it must fulfil the slices this turn instead of
+        // dispatching slice-builder per file.
+        const mode = topologyDecision?.topology === "inline"
+            ? "controller-inline"
+            : baseMode;
+        const controllerHint = topologyDecision?.topology === "inline"
+            ? "Fulfill ready slices in this turn without dispatching slice-builder. Record delegation rows with role=controller (scheduled→completed) per slice."
+            : undefined;
         nextDispatch = {
             waveId: firstOpenWave.waveId,
             readyToDispatch,
@@ -392,7 +447,8 @@ export async function runWaveStatus(projectRoot, options = {}) {
             mode,
             topology: topologyDecision?.topology ?? "none",
             topologyReason: topologyDecision?.reason ?? "no ready units",
-            maxBuilders: topologyDecision?.maxBuilders ?? maxBuilders
+            maxBuilders: topologyDecision?.maxBuilders ?? maxBuilders,
+            ...(controllerHint ? { controllerHint } : {})
         };
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "7.7.0",
+  "version": "7.7.1",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {