cclaw-cli 7.5.0 → 7.7.0

package/dist/config.js

@@ -6,7 +6,14 @@ import { exists, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_IDS } from "./types.js";
 const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
 const HARNESS_ID_SET = new Set(HARNESS_IDS);
-const ALLOWED_CONFIG_KEYS = new Set(["version", "flowVersion", "harnesses", "tdd"]);
+const ALLOWED_CONFIG_KEYS = new Set([
+    "version",
+    "flowVersion",
+    "harnesses",
+    "tdd",
+    "execution",
+    "plan"
+]);
 const SUPPORTED_HARNESSES_TEXT = HARNESS_IDS.join(", ");
 export const TDD_COMMIT_MODES = [
     "managed-per-slice",
@@ -20,6 +27,28 @@ export const TDD_ISOLATION_MODES = ["worktree", "in-place", "auto"];
 const TDD_ISOLATION_MODE_SET = new Set(TDD_ISOLATION_MODES);
 export const DEFAULT_TDD_ISOLATION_MODE = "worktree";
 export const DEFAULT_TDD_WORKTREE_ROOT = `${RUNTIME_ROOT}/worktrees`;
+export const LOCKFILE_TWIN_POLICIES = ["auto-include", "auto-revert", "strict-fence"];
+const LOCKFILE_TWIN_POLICY_SET = new Set(LOCKFILE_TWIN_POLICIES);
+export const DEFAULT_LOCKFILE_TWIN_POLICY = "auto-include";
+export const EXECUTION_TOPOLOGIES = [
+    "auto",
+    "inline",
+    "single-builder",
+    "parallel-builders",
+    "strict-micro"
+];
+const EXECUTION_TOPOLOGY_SET = new Set(EXECUTION_TOPOLOGIES);
+export const DEFAULT_EXECUTION_TOPOLOGY = "auto";
+export const EXECUTION_STRICTNESS_PROFILES = ["fast", "balanced", "strict"];
+const EXECUTION_STRICTNESS_PROFILE_SET = new Set(EXECUTION_STRICTNESS_PROFILES);
+export const DEFAULT_EXECUTION_STRICTNESS = "balanced";
+export const DEFAULT_MAX_BUILDERS = 5;
+export const PLAN_SLICE_GRANULARITIES = ["feature-atomic", "strict-micro"];
+const PLAN_SLICE_GRANULARITY_SET = new Set(PLAN_SLICE_GRANULARITIES);
+export const DEFAULT_PLAN_SLICE_GRANULARITY = "feature-atomic";
+export const PLAN_MICRO_TASK_POLICIES = ["advisory", "strict"];
+const PLAN_MICRO_TASK_POLICY_SET = new Set(PLAN_MICRO_TASK_POLICIES);
+export const DEFAULT_PLAN_MICRO_TASK_POLICY = "advisory";
 // Kept for runtime modules that use these defaults directly.
 export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
     "**/*.test.*",
@@ -46,7 +75,14 @@ function configFixExample() {
 tdd:
   commitMode: managed-per-slice
   isolationMode: worktree
-  worktreeRoot: .cclaw/worktrees`;
+  worktreeRoot: .cclaw/worktrees
+execution:
+  topology: auto
+  strictness: balanced
+  maxBuilders: 5
+plan:
+  sliceGranularity: feature-atomic
+  microTaskPolicy: advisory`;
 }
 function configValidationError(configFilePath, reason) {
     return new InvalidConfigError(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
@@ -68,7 +104,17 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, _defaultTrack
         tdd: {
             commitMode: DEFAULT_TDD_COMMIT_MODE,
             isolationMode: DEFAULT_TDD_ISOLATION_MODE,
-            worktreeRoot: DEFAULT_TDD_WORKTREE_ROOT
+            worktreeRoot: DEFAULT_TDD_WORKTREE_ROOT,
+            lockfileTwinPolicy: DEFAULT_LOCKFILE_TWIN_POLICY
+        },
+        execution: {
+            topology: DEFAULT_EXECUTION_TOPOLOGY,
+            strictness: DEFAULT_EXECUTION_STRICTNESS,
+            maxBuilders: DEFAULT_MAX_BUILDERS
+        },
+        plan: {
+            sliceGranularity: DEFAULT_PLAN_SLICE_GRANULARITY,
+            microTaskPolicy: DEFAULT_PLAN_MICRO_TASK_POLICY
         }
     };
 }
@@ -93,6 +139,48 @@ export function resolveTddWorktreeRoot(config) {
     }
     return DEFAULT_TDD_WORKTREE_ROOT;
 }
+export function resolveLockfileTwinPolicy(config) {
+    const raw = config?.tdd?.lockfileTwinPolicy;
+    if (typeof raw === "string" && LOCKFILE_TWIN_POLICY_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_LOCKFILE_TWIN_POLICY;
+}
+export function resolveExecutionTopology(config) {
+    const raw = config?.execution?.topology;
+    if (typeof raw === "string" && EXECUTION_TOPOLOGY_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_EXECUTION_TOPOLOGY;
+}
+export function resolveExecutionStrictness(config) {
+    const raw = config?.execution?.strictness;
+    if (typeof raw === "string" && EXECUTION_STRICTNESS_PROFILE_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_EXECUTION_STRICTNESS;
+}
+export function resolveMaxBuilders(config) {
+    const raw = config?.execution?.maxBuilders;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1) {
+        return raw;
+    }
+    return DEFAULT_MAX_BUILDERS;
+}
+export function resolvePlanSliceGranularity(config) {
+    const raw = config?.plan?.sliceGranularity;
+    if (typeof raw === "string" && PLAN_SLICE_GRANULARITY_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_PLAN_SLICE_GRANULARITY;
+}
+export function resolvePlanMicroTaskPolicy(config) {
+    const raw = config?.plan?.microTaskPolicy;
+    if (typeof raw === "string" && PLAN_MICRO_TASK_POLICY_SET.has(raw)) {
+        return raw;
+    }
+    return DEFAULT_PLAN_MICRO_TASK_POLICY;
+}
 function assertOnlySupportedKeys(parsed, fullPath) {
     const unknownKeys = Object.keys(parsed).filter((key) => !ALLOWED_CONFIG_KEYS.has(key));
     if (unknownKeys.length === 0)
@@ -130,6 +218,14 @@ export async function readConfig(projectRoot, _options = {}) {
         !isRecord(parsed.tdd)) {
         throw configValidationError(fullPath, `"tdd" must be an object when provided`);
     }
+    if (Object.prototype.hasOwnProperty.call(parsed, "execution") &&
+        !isRecord(parsed.execution)) {
+        throw configValidationError(fullPath, `"execution" must be an object when provided`);
+    }
+    if (Object.prototype.hasOwnProperty.call(parsed, "plan") &&
+        !isRecord(parsed.plan)) {
+        throw configValidationError(fullPath, `"plan" must be an object when provided`);
+    }
     const rawHarnesses = Array.isArray(parsed.harnesses) ? parsed.harnesses : DEFAULT_HARNESSES;
     const normalizedHarnesses = [];
     for (const harness of rawHarnesses) {
@@ -153,6 +249,14 @@ export async function readConfig(projectRoot, _options = {}) {
     const rawCommitMode = parsedTdd.commitMode;
     const rawIsolationMode = parsedTdd.isolationMode;
     const rawWorktreeRoot = parsedTdd.worktreeRoot;
+    const rawLockfileTwinPolicy = parsedTdd.lockfileTwinPolicy;
+    const parsedExecution = isRecord(parsed.execution) ? parsed.execution : {};
+    const rawExecutionTopology = parsedExecution.topology;
+    const rawExecutionStrictness = parsedExecution.strictness;
+    const rawMaxBuilders = parsedExecution.maxBuilders;
+    const parsedPlan = isRecord(parsed.plan) ? parsed.plan : {};
+    const rawPlanSliceGranularity = parsedPlan.sliceGranularity;
+    const rawPlanMicroTaskPolicy = parsedPlan.microTaskPolicy;
     if (rawCommitMode !== undefined &&
         (typeof rawCommitMode !== "string" || !TDD_COMMIT_MODE_SET.has(rawCommitMode))) {
         throw configValidationError(fullPath, `"tdd.commitMode" must be one of: ${TDD_COMMIT_MODES.join(", ")}`);
@@ -165,6 +269,33 @@ export async function readConfig(projectRoot, _options = {}) {
         (typeof rawWorktreeRoot !== "string" || rawWorktreeRoot.trim().length === 0)) {
         throw configValidationError(fullPath, `"tdd.worktreeRoot" must be a non-empty string when provided`);
     }
+    if (rawLockfileTwinPolicy !== undefined &&
+        (typeof rawLockfileTwinPolicy !== "string" || !LOCKFILE_TWIN_POLICY_SET.has(rawLockfileTwinPolicy))) {
+        throw configValidationError(fullPath, `"tdd.lockfileTwinPolicy" must be one of: ${LOCKFILE_TWIN_POLICIES.join(", ")}`);
+    }
+    if (rawExecutionTopology !== undefined &&
+        (typeof rawExecutionTopology !== "string" || !EXECUTION_TOPOLOGY_SET.has(rawExecutionTopology))) {
+        throw configValidationError(fullPath, `"execution.topology" must be one of: ${EXECUTION_TOPOLOGIES.join(", ")}`);
+    }
+    if (rawExecutionStrictness !== undefined &&
+        (typeof rawExecutionStrictness !== "string" ||
+            !EXECUTION_STRICTNESS_PROFILE_SET.has(rawExecutionStrictness))) {
+        throw configValidationError(fullPath, `"execution.strictness" must be one of: ${EXECUTION_STRICTNESS_PROFILES.join(", ")}`);
+    }
+    if (rawMaxBuilders !== undefined &&
+        (!Number.isInteger(rawMaxBuilders) || rawMaxBuilders < 1)) {
+        throw configValidationError(fullPath, `"execution.maxBuilders" must be an integer >= 1 when provided`);
+    }
+    if (rawPlanSliceGranularity !== undefined &&
+        (typeof rawPlanSliceGranularity !== "string" ||
+            !PLAN_SLICE_GRANULARITY_SET.has(rawPlanSliceGranularity))) {
+        throw configValidationError(fullPath, `"plan.sliceGranularity" must be one of: ${PLAN_SLICE_GRANULARITIES.join(", ")}`);
+    }
+    if (rawPlanMicroTaskPolicy !== undefined &&
+        (typeof rawPlanMicroTaskPolicy !== "string" ||
+            !PLAN_MICRO_TASK_POLICY_SET.has(rawPlanMicroTaskPolicy))) {
+        throw configValidationError(fullPath, `"plan.microTaskPolicy" must be one of: ${PLAN_MICRO_TASK_POLICIES.join(", ")}`);
+    }
     const commitMode = typeof rawCommitMode === "string"
         ? rawCommitMode
         : DEFAULT_TDD_COMMIT_MODE;
@@ -174,6 +305,26 @@ export async function readConfig(projectRoot, _options = {}) {
     const worktreeRoot = typeof rawWorktreeRoot === "string" && rawWorktreeRoot.trim().length > 0
         ? rawWorktreeRoot.trim()
         : DEFAULT_TDD_WORKTREE_ROOT;
+    const lockfileTwinPolicy = typeof rawLockfileTwinPolicy === "string"
+        ? rawLockfileTwinPolicy
+        : DEFAULT_LOCKFILE_TWIN_POLICY;
+    const executionTopology = typeof rawExecutionTopology === "string"
+        ? rawExecutionTopology
+        : DEFAULT_EXECUTION_TOPOLOGY;
+    const executionStrictness = typeof rawExecutionStrictness === "string"
+        ? rawExecutionStrictness
+        : DEFAULT_EXECUTION_STRICTNESS;
+    const maxBuilders = typeof rawMaxBuilders === "number" &&
+        Number.isInteger(rawMaxBuilders) &&
+        rawMaxBuilders >= 1
+        ? rawMaxBuilders
+        : DEFAULT_MAX_BUILDERS;
+    const planSliceGranularity = typeof rawPlanSliceGranularity === "string"
+        ? rawPlanSliceGranularity
+        : DEFAULT_PLAN_SLICE_GRANULARITY;
+    const planMicroTaskPolicy = typeof rawPlanMicroTaskPolicy === "string"
+        ? rawPlanMicroTaskPolicy
+        : DEFAULT_PLAN_MICRO_TASK_POLICY;
     return {
         version,
         flowVersion,
@@ -181,7 +332,17 @@ export async function readConfig(projectRoot, _options = {}) {
         tdd: {
             commitMode,
             isolationMode,
-            worktreeRoot
+            worktreeRoot,
+            lockfileTwinPolicy
+        },
+        execution: {
+            topology: executionTopology,
+            strictness: executionStrictness,
+            maxBuilders
+        },
+        plan: {
+            sliceGranularity: planSliceGranularity,
+            microTaskPolicy: planMicroTaskPolicy
         }
     };
 }
@@ -193,7 +354,17 @@ export async function writeConfig(projectRoot, config, _options = {}) {
         tdd: {
             commitMode: resolveTddCommitMode(config),
             isolationMode: resolveTddIsolationMode(config),
-            worktreeRoot: resolveTddWorktreeRoot(config)
+            worktreeRoot: resolveTddWorktreeRoot(config),
+            lockfileTwinPolicy: resolveLockfileTwinPolicy(config)
+        },
+        execution: {
+            topology: resolveExecutionTopology(config),
+            strictness: resolveExecutionStrictness(config),
+            maxBuilders: resolveMaxBuilders(config)
+        },
+        plan: {
+            sliceGranularity: resolvePlanSliceGranularity(config),
+            microTaskPolicy: resolvePlanMicroTaskPolicy(config)
         }
     };
     await writeFileSafe(configPath(projectRoot), stringify(serialisable));

package/dist/content/core-agents.d.ts

@@ -196,7 +196,7 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly body: string;
 }, {
     readonly name: "slice-builder";
-    readonly description: "MANDATORY for every TDD slice. Owns RED → GREEN → REFACTOR → per-slice DOC for one bounded vertical slice in a single delegated span. Multiple slice-builder spans run in parallel inside one wave when their `claimedPaths` are disjoint.";
+    readonly description: "MANDATORY for delegated TDD slices. Owns RED → GREEN → REFACTOR → per-slice DOC for one feature-atomic implementation unit/slice in a single delegated span. Multiple slice-builder spans run in parallel only under `parallel-builders` topology with disjoint `claimedPaths`; `strict-micro` keeps tiny tasks separate.";
     readonly tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"];
     readonly model: "balanced";
     readonly activation: "mandatory";

package/dist/content/core-agents.js

@@ -151,7 +151,7 @@ export function sliceBuilderProtocol() {
     return [
         "## slice-builder protocol",
         "",
-        "**slice-builder** is the canonical worker for **one bounded vertical slice** end-to-end: **RED → GREEN → REFACTOR → inline DOC** in **one** delegated span. Multiple slice-builder spans run in parallel under a single wave when the wave plan declares disjoint `claimedPaths`.",
+        "**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`.",
         "",
         "### Invariants",
         "- Produce failing RED evidence (or cite the delegated RED artifact) **before** production edits.",
@@ -165,6 +165,21 @@ export function sliceBuilderProtocol() {
         "- Honor every `delegation-record`/`delegation-record.mjs` row shape the controller requests so artifact linters keep passing.",
         "- The umbrella `slice-completed` row ties RED/GREEN/REFACTOR/DOC timestamps to your builder span.",
         "",
+        "### Event → status flag table (7.6.0 — phase-event status validation)",
+        "",
+        "Phase-level granularity is only meaningful on terminal outcomes. The dispatch-level ack (no `--phase`) is the controller saying \"I see the dispatch surface back\" — it stays on `--status=acknowledged`. Phase events MUST use `--status=completed` or `--status=failed`. The hook rejects mismatches with `phase_event_requires_completed_or_failed_status` (exit 2) and prints a corrected-command hint.",
+        "",
+        "| event | --phase | --status |",
+        "|---|---|---|",
+        "| dispatch ack (controller-side) | (none) | `acknowledged` |",
+        "| RED watched-fail captured | `red` | `completed` |",
+        "| GREEN test passes | `green` | `completed` (with `--refactor-outcome=inline\\|deferred\\|...`) |",
+        "| REFACTOR landed | `refactor` | `completed` |",
+        "| DOC card landed (triggers slice-commit) | `doc` | `completed` |",
+        "| BLOCKED / unrecoverable | (any phase reached) | `failed` |",
+        "",
+        "Common slip: recording every phase event with `--status=acknowledged` (e.g. `--phase=doc --status=acknowledged`). The event row is silently dropped from terminal-phase aggregations, `slice-commit.mjs` never fires (it only triggers on `phase=doc status=completed`), and `wave-status` reports the slice as phantom-open. Recovery requires raw backfill commands. The 7.6.0 hook validator forbids this configuration up front.",
+        "",
         "### Streaming output contract",
         "- Emit one JSON line to stdout per completed phase: `{\"event\":\"phase-completed\",\"stage\":\"tdd\",\"sliceId\":\"S-<n>\",\"phase\":\"<red|green|refactor|refactor-deferred|doc>\",\"spanId\":\"<span>\",\"runId\":\"<run>\",\"ts\":\"<iso>\"}`.",
         "- For `phase=green` with inline/deferred refactor folding, include `refactorOutcome.mode` in the same JSON line so live controllers can close the slice without waiting for file sync.",
@@ -574,7 +589,7 @@ export const CCLAW_AGENTS = [
     },
     {
         name: "slice-builder",
-        description: "MANDATORY for every TDD slice. Owns RED → GREEN → REFACTOR → per-slice DOC for one bounded vertical slice in a single delegated span. Multiple slice-builder spans run in parallel inside one wave when their `claimedPaths` are disjoint.",
+        description: "MANDATORY for delegated TDD slices. Owns RED → GREEN → REFACTOR → per-slice DOC for one feature-atomic implementation unit/slice in a single delegated span. Multiple slice-builder spans run in parallel only under `parallel-builders` topology with disjoint `claimedPaths`; `strict-micro` keeps tiny tasks separate.",
         tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
         model: "balanced",
         activation: "mandatory",

package/dist/content/hooks.js

@@ -1489,6 +1489,43 @@ async function main() {
     emitProblems(problems, json, 2);
     return;
   }
+  // 7.6.0 — phase-event status validation.
+  // \`--phase=<phase>\` carries phase-level granularity (RED/GREEN/REFACTOR/DOC
+  // outcomes). It is only meaningful on terminal statuses
+  // (\`completed\` or \`failed\`). The dispatch-level ack (no phase) keeps
+  // \`--status=acknowledged\`. Refuse acknowledged/launched/scheduled/waived/stale
+  // rows that carry a phase so phantom-open slices cannot be recorded.
+  if (
+    typeof args.phase === "string" &&
+    args.phase.length > 0 &&
+    args.status !== "completed" &&
+    args.status !== "failed"
+  ) {
+    const sliceFlag = typeof args.slice === "string" && args.slice.length > 0
+      ? "--slice=" + args.slice + " "
+      : "";
+    const spanFlag = typeof args["span-id"] === "string" && args["span-id"].length > 0
+      ? "--span-id=" + args["span-id"] + " "
+      : "";
+    const correctedCommandHint =
+      "node .cclaw/hooks/delegation-record.mjs --stage=" + (args.stage || "<stage>") +
+      " --agent=" + (args.agent || "<agent>") +
+      " --mode=" + (args.mode || "mandatory") +
+      " --status=completed --phase=" + args.phase +
+      " " + sliceFlag + spanFlag +
+      '--evidence-ref="<phase outcome>"';
+    emitErrorJson(
+      "phase_event_requires_completed_or_failed_status",
+      {
+        phase: args.phase,
+        status: args.status,
+        spanId: args["span-id"] || "unknown",
+        correctedCommandHint
+      },
+      json
+    );
+    return;
+  }
   if (args.phase === "refactor-deferred") {
     const rationaleQuality = validateDeferredRationaleInline(args["refactor-rationale"], args);
     if (rationaleQuality !== "ok") {

package/dist/content/meta-skill.js

@@ -57,14 +57,14 @@ 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." -> No. 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\`; otherwise see the Controller dispatch discipline below.
 
 ## Controller dispatch discipline (applies to every stage)
 
-cclaw stages have **mandatory delegations** (TDD: \`slice-builder\`; review: \`reviewer\` + \`security-reviewer\`; design: \`architect\`; scope: \`planner\`; etc.). The controller is the **orchestrator**, not the worker. 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 TDD topology is explicitly \`inline\` for a low-risk unit. When a stage declares a mandatory delegation:
 
-- **Dispatch via the harness Task tool.** Do NOT write the worker's output (slice code, review findings, architect notes) into the artifact yourself as a substitute for delegating. Editing \`06-tdd.md\` slice cards, \`07-review.md\` findings, or any other "result of mandatory worker" content inline in the controller chat is a protocol violation.
-- **Parallel by default when paths/lenses are independent.** TDD wave-fanout (disjoint \`claimedPaths\`) and 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 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.
 - **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.
 - **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).
 

package/dist/content/skills.js

@@ -183,22 +183,24 @@ export function tddTopOfSkillBlock(stage) {
         return "";
     return `## TDD orchestration primer
 
-**MANDATE — controller never implements.** In TDD the controller plans, dispatches, and reconciles. **NEVER edit production code, tests, or run cargo/npm/pytest yourself in the controller chat.** Every slice's RED → GREEN → REFACTOR → DOC cycle MUST happen inside an isolated \`slice-builder\` span dispatched via the harness Task tool. Inline code edits in the controller chat are a protocol violation that defeats parallelism, evidence isolation, and the audit ledger.
+**MANDATE — controller preserves TDD evidence.** In TDD the controller routes, dispatches when needed, and reconciles. Default topology is \`auto\` + \`balanced\`: feature-atomic units contain internal 2-5 minute RED/GREEN/REFACTOR steps. Inline execution is allowed only when \`wave-status\`/the plan selects \`inline\`; it still must satisfy RED-before-GREEN, AC traceability, path containment, verification, managed commit/worktree, lockfile twin, and orphan-change gates. \`single-builder\` and \`parallel-builders\` use \`slice-builder\`; \`strict-micro\` preserves one tiny task per schedulable slice for high-risk work.
 
 **Step 1 — Wave status (always first):**
 \`node .cclaw/cli.mjs internal wave-status --json\`
 
-The output names: \`waves[]\` (closed/open), \`nextDispatch.waveId\`, \`nextDispatch.mode\` (\`wave-fanout\`, \`single-slice\`, or \`blocked\`), \`nextDispatch.readyToDispatch\` (slice ids), and \`nextDispatch.pathConflicts\` (overlapping \`claimedPaths\` between members).
+The output names: \`waves[]\` (closed/open), \`nextDispatch.waveId\`, \`nextDispatch.mode\` (\`wave-fanout\`, \`single-slice\`, or \`blocked\`), \`nextDispatch.topology\` (\`inline\`, \`single-builder\`, \`parallel-builders\`, or \`strict-micro\`), \`nextDispatch.readyToDispatch\` (slice ids), and \`nextDispatch.pathConflicts\` (overlapping \`claimedPaths\` between members).
 
 **Step 2 — Decide automatically (no user question when paths disjoint):**
 
-| \`mode\`         | \`pathConflicts\` | Action                                                                                                                                  |
-|------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
-| \`wave-fanout\`  | \`[]\`            | **Fan out the entire wave in one tool batch.** Emit one \`Task\` per ready slice in a single controller message. Do NOT ask the user.   |
-| \`blocked\`      | non-empty         | Issue exactly one AskQuestion (resolve overlap, split/serialize, or adjust claimedPaths), then re-run \`wave-status\`.                    |
-| \`single-slice\` | —                 | One \`Task\` for the next ready slice.                                                                                                  |
+| \`topology\`              | \`pathConflicts\` | Action                                                                                                                                     |
+|---------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| \`parallel-builders\`     | \`[]\`            | **Fan out independent substantial units in one tool batch.** Emit one \`Task\` per routed ready builder in a single controller message. Do NOT ask. |
+| \`single-builder\`        | any/none          | Dispatch one \`slice-builder\` for the next feature-atomic unit; serialize remaining ready units.                                          |
+| \`inline\`                | \`[]\`            | Execute inline only for low-risk inline-safe units; record equivalent RED/GREEN/REFACTOR evidence before completion.                       |
+| \`strict-micro\`          | any/none          | Preserve micro-slice sequencing: one tiny task/slice at a time unless the strict plan explicitly proves safe fan-out.                      |
+| \`blocked\`/mode blocked  | non-empty         | Issue exactly one AskQuestion (resolve overlap, split/serialize, or adjust claimedPaths), then re-run \`wave-status\`.                     |
 
-**Step 3 — Dispatch protocol per slice:** in the SAME controller message that issues the \`Task\` call:
+**Step 3 — Dispatch protocol per delegated slice:** for \`single-builder\`, \`parallel-builders\`, and delegated \`strict-micro\`, in the SAME controller message that issues the \`Task\` call:
 
 1. Append \`delegation-record --status=scheduled\` for the \`slice-builder\` span (one row per slice; reuse the same \`spanId\` across the entire RED → GREEN → REFACTOR → DOC lifecycle).
 2. Append \`delegation-record --status=launched\` immediately after.
@@ -206,6 +208,8 @@ The output names: \`waves[]\` (closed/open), \`nextDispatch.waveId\`, \`nextDisp
 4. The slice-builder span ACKs locally (\`delegation-record --status=acknowledged\`) and runs the **complete** RED → GREEN → REFACTOR → DOC cycle inside the span — including writing \`tdd-slices/S-<id>.md\` and emitting \`--phase=red\`, \`--phase=green\`, \`--phase=refactor\` (or \`--phase=refactor-deferred\` with rationale), and \`--phase=doc\` rows on its own.
 5. The controller waits for ALL parallel spans to terminate before reconciling. Do not page back into the controller chat between spans.
 
+For \`inline\`, skip the Task call but do not skip evidence: write the same per-slice card/evidence refs, run RED before GREEN, verify before completion, and keep all path/commit/worktree gates satisfied.
+
 **Step 4 — Wave closeout:** after all in-flight slices report \`completed\`:
 
 1. Re-run \`wave-status --json\`. Confirm the wave is \`closed\` and the next dispatch is the following wave (or \`closeout\`).

package/dist/content/stage-schema.js

@@ -272,6 +272,7 @@ const REQUIRED_GATE_IDS = {
         "plan_execution_posture_recorded",
         "plan_parallel_exec_full_coverage",
         "plan_wave_paths_disjoint",
+        "plan_module_introducing_slice_wires_root",
         "plan_wait_for_confirm"
     ],
     tdd: (track) => [
@@ -677,8 +678,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "slice-builder",
             mode: "mandatory",
             requiredAtTier: "lightweight",
-            when: "Always during the TDD cycle. Controller MUST NOT write tests or production code itself.",
-            purpose: "Own one bounded vertical slice end-to-end: RED → GREEN → REFACTOR → per-slice DOC in a single delegated span. Multiple slice-builder spans run in parallel inside one wave when their `claimedPaths` are disjoint. Linter rules `tdd_slice_builder_missing` and `tdd_slice_doc_missing` block unauthorized GREEN authors and missing per-slice prose.",
+            when: "During delegated TDD topologies (`single-builder`, `parallel-builders`, `strict-micro`). Inline topology may skip the dispatch only when the same RED/GREEN/REFACTOR evidence gates are preserved.",
+            purpose: "Own one feature-atomic implementation unit/slice end-to-end: RED → GREEN → REFACTOR → per-slice DOC in a single delegated span. Multiple slice-builder spans run in parallel only under `parallel-builders` topology with disjoint `claimedPaths`. Linter rules `tdd_slice_builder_missing` and `tdd_slice_doc_missing` block unauthorized GREEN authors and missing per-slice prose unless inline topology is explicitly recorded.",
             requiresUserGate: false,
             skill: "tdd-cycle-evidence"
         },

package/dist/content/stages/plan.js

@@ -10,8 +10,8 @@ export const PLAN = {
     skillDescription: "Execution planning stage with strict confirmation gate before implementation.",
     philosophy: {
         hardGate: "Do NOT write code or tests. Planning only. This stage produces a task graph and execution order. WAIT_FOR_CONFIRM before any handoff to implementation.",
-        ironLaw: "EVERY TASK IS 2–5 MINUTES, FULLY SPELLED OUT, AND CARRIES A STABLE ID — NO PLACEHOLDERS, NO ‘ETC.’.",
-        purpose: "Create small executable tasks with dependencies and pause for explicit user confirmation.",
+        ironLaw: "EVERY IMPLEMENTATION UNIT IS FEATURE-ATOMIC, WITH INTERNAL 2–5 MINUTE TDD STEPS — STRICT MICRO-SLICES ARE RESERVED FOR HIGH-RISK WORK.",
+        purpose: "Create feature-atomic implementation units with dependencies, internal TDD steps, and explicit confirmation before execution.",
         whenToUse: [
             "After spec approval",
             "Before writing tests or implementation",
@@ -43,21 +43,21 @@ export const PLAN = {
             "Read upstream — load spec, design, and scope artifacts. Cross-reference acceptance criteria.",
             "Build dependency graph — identify task ordering, parallel opportunities, and blocking dependencies.",
             "Group tasks into dependency batches — batch N+1 cannot start until batch N has verification evidence.",
-            "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
-            "Task Contract — every task has one coherent outcome, AC mapping, exact verification command/manual step, and expected evidence snippet or pass condition. Avoid vague `run tests` wording.",
+            "Slice into implementation units — each unit is feature-atomic and testable end-to-end, with internal 2-5 minute RED/GREEN/REFACTOR steps. Use `strict-micro` only for high-risk or explicitly requested micro-slice execution.",
+            "Task Contract — every unit has one coherent outcome, AC mapping, exact verification command/manual step, and expected evidence snippet or pass condition. Internal steps may be `T-NNN` rows, but they are not automatically separate schedulable agents in balanced/fast mode.",
             "Annotate slice-review metadata — task rows may carry `touchCount` (rough number of files expected to change), `touchPaths` (glob hints, e.g. `migrations/**`, `src/auth/**`), and optional `highRisk: true` to force a review pass. These fields feed the TDD stage's Per-Slice Review point.",
             "For every `### Implementation Unit U-<n>`, declare parallel metadata bullets: `id`, `dependsOn` (unit ids or `none`), `claimedPaths` (repo-relative), `parallelizable` (true|false), `riskTier` (low|standard|high), optional `lane` — used for conflict-aware wave plans and schedulers.",
             "Map scope Locked Decisions — every D-XX ID from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
             "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
             "Define validation points — mark where progress must be checked before continuing, with concrete command and expected evidence.",
-            "Define execution posture — record whether execution should be sequential, dependency-batched, parallel-safe, or blocked; include risk triggers and RED/GREEN/REFACTOR checkpoint/commit expectations when the repo workflow supports them. This fulfills the `plan_execution_posture_recorded` gate.",
-            "**Author the FULL Parallel Execution Plan.** Inside the `<!-- parallel-exec-managed-start -->` block, enumerate ALL waves W-02..W-N covering EVERY T-NNN task in `## Task List` — no `we'll author waves later`, `next batch only`, or open-ended Backlog handwave is acceptable. Each task gets a slice with `sliceId | taskId | dependsOn | claimedPaths | parallelizable | riskTier | lane`. Spike rows (`S-N`) and tasks marked `deferred` in an explicit `Deferred:` column may be omitted, but every other T-NNN must be claimed. This fulfills the `plan_parallel_exec_full_coverage` gate. The TDD stage downstream is a pure consumer of these waves — if the plan does not author them, TDD cannot fan out that work.",
-            "After authoring/refreshing the managed parallel-exec block, render a Mermaid `flowchart` or `gantt` covering waves (`W-*`) and slice dependencies (`S-*`) so parallelism and fan-in boundaries are visually auditable.",
+            "Define execution topology — record `execution.topology` (`auto|inline|single-builder|parallel-builders|strict-micro`), `execution.strictness` (`fast|balanced|strict`), `execution.maxBuilders`, `plan.sliceGranularity`, `plan.microTaskPolicy`, stop conditions, and RED/GREEN/REFACTOR checkpoint/commit expectations. Default posture is `auto` + `balanced`: choose the cheapest safe route, not the most parallel one.",
+            "**Author the FULL Parallel Execution Plan.** Inside the `<!-- parallel-exec-managed-start -->` block, enumerate all waves W-01..W-N covering every feature-atomic `U-*` implementation unit/slice. Legacy strict-micro plans may cover each non-deferred `T-NNN` task instead. Each row carries `unit|sliceId | dependsOn | claimedPaths | parallelizable | riskTier | lane`. Do not leave `we'll author waves later`, `next batch only`, or open-ended Backlog handwaves. This fulfills the `plan_parallel_exec_full_coverage` gate. The TDD stage downstream is a pure consumer of these waves — if the plan does not author them, TDD cannot fan out that work.",
+            "After authoring/refreshing the managed parallel-exec block, render a Mermaid `flowchart` or `gantt` covering waves (`W-*`) and unit/slice dependencies (`U-*`/`S-*`) so topology and fan-in boundaries are visually auditable.",
             "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then close the stage with `node .cclaw/hooks/stage-complete.mjs plan` and tell user to run `/cc`."
         ],
         interactionProtocol: [
             "Plan in read-only mode relative to implementation.",
-            "Split work into small vertical slices (target 2-5 minute tasks).",
+            "Split work into feature-atomic vertical units; place 2-5 minute TDD steps inside each unit.",
             "Publish explicit dependency batches with entry and exit checks for each batch.",
             "Expose execution posture: sequential vs batch/parallel, stop conditions, and checkpoint cadence for the TDD handoff.",
             "Keep same-wave `claimedPaths` disjoint; if overlap exists, split waves or serialize explicitly before handoff.",
@@ -79,17 +79,18 @@ export const PLAN = {
             "Write plan artifact and pause at WAIT_FOR_CONFIRM."
         ],
         requiredGates: [
-            { id: "plan_tasks_sliced_2_5_min", description: "Tasks are small, executable slices." },
+            { id: "plan_tasks_sliced_2_5_min", description: "Implementation units are feature-atomic and contain internal 2-5 minute TDD steps; strict micro-slices are explicit." },
             { id: "plan_dependency_batches_defined", description: "Tasks are grouped into executable batches with gate checks and execution posture." },
             { id: "plan_acceptance_mapped", description: "Each task maps to a spec acceptance criterion." },
-            { id: "plan_execution_posture_recorded", description: "Execution posture is recorded before implementation handoff." },
-            { id: "plan_parallel_exec_full_coverage", description: "Every T-NNN task in `## Task List` (other than spikes/explicitly-deferred) is assigned to at least one slice inside the `<!-- parallel-exec-managed-start -->` block; TDD cannot fan out work that the plan never authored as waves." },
+            { id: "plan_execution_posture_recorded", description: "Execution topology/posture is recorded before implementation handoff." },
+            { id: "plan_parallel_exec_full_coverage", description: "Every U-* implementation unit/slice (or every T-NNN task in explicit strict-micro plans) is assigned inside the `<!-- parallel-exec-managed-start -->` block; TDD cannot fan out work that the plan never authored as waves." },
             { id: "plan_wave_paths_disjoint", description: "Within each authored wave, slice `claimedPaths` remain disjoint so `wave-fanout` can dispatch safely without overlap conflicts." },
+            { id: "plan_module_introducing_slice_wires_root", description: "When a slice introduces a new module file, the stack-adapter's wiring aggregator (Rust `lib.rs`, Python `__init__.py`, Node-TS barrel when present) must appear in the same slice's claim or a transitive predecessor's claim so RED can be expressed." },
             { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
         ],
         requiredEvidence: [
             "Artifact written to `.cclaw/artifacts/05-plan.md`.",
-            "Task list includes acceptance mapping, exact verification command/manual step, and expected evidence/pass condition.",
+            "Implementation units include acceptance mapping, internal 2-5 minute TDD steps, exact verification command/manual step, and expected evidence/pass condition.",
             "Locked decision coverage table present with D-XX trace links.",
             "Dependency graph documented.",
             "Dependency batches documented with batch-by-batch verification gates.",
@@ -135,13 +136,13 @@ export const PLAN = {
             { section: "Upstream Handoff", required: false, validationRule: "Summarizes spec/design/scope decisions, constraints, open questions, and explicit drift before task breakdown." },
             { section: "Dependency Graph", required: false, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
             { section: "Dependency Batches", required: true, validationRule: "Every task belongs to a batch. Each batch has an exit gate and dependency statement." },
-            { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, exact verification command/manual step, expected evidence/pass condition, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget. When present, touchCount/touchPaths/highRisk metadata drives Per-Slice Review escalation in TDD." },
+            { section: "Task List", required: true, validationRule: "Task rows may describe internal 2-5 minute TDD steps. In balanced/fast mode, the schedulable unit is the feature-atomic Implementation Unit, not every T-NNN row. Strict-micro plans may still use one T-NNN per slice." },
             { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
-            { section: "Execution Posture", required: true, validationRule: "States sequential/batch/parallel posture, stop conditions, risk triggers, and RED/GREEN/REFACTOR checkpoint or commit expectations for TDD when consistent with the repo workflow." },
+            { section: "Execution Posture", required: true, validationRule: "States `execution.topology` (`auto|inline|single-builder|parallel-builders|strict-micro`), `execution.strictness`, `execution.maxBuilders`, `plan.sliceGranularity`, `plan.microTaskPolicy`, stop conditions, risk triggers, and RED/GREEN/REFACTOR checkpoint or commit expectations for TDD when consistent with the repo workflow." },
             { section: "Locked Decision Coverage", required: false, validationRule: "Every locked decision ID (D-XX) from scope is listed with linked task IDs or explicit defer rationale." },
             { section: "Risk Assessment", required: false, validationRule: "If present: per-task or per-batch risk identification with likelihood, impact, and mitigation strategy." },
             { section: "Boundary Map", required: false, validationRule: "If present: per-batch or per-task interface contracts listing what each task produces (exports) and consumes (imports) from other tasks." },
-            { section: "Implementation Units", required: false, validationRule: "If present: each `### Implementation Unit U-<n>` includes Goal, Files, Approach, Test scenarios, Verification fields, plus bullets (`id`, `dependsOn`, `claimedPaths`, `parallelizable`, `riskTier`, optional `lane`)." },
+            { section: "Implementation Units", required: false, validationRule: "Each `### Implementation Unit U-<n>` includes Goal, Files, Approach, Test scenarios, Verification, internal 2-5 minute TDD steps, plus bullets (`id`, `dependsOn`, `claimedPaths`, `parallelizable`, `riskTier`, optional `lane`)." },
             { section: "Calibrated Findings", required: false, validationRule: "If present: either `None this stage` or one or more lines in `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>` format." },
             { section: "Regression Iron Rule", required: false, validationRule: "If present: includes `Iron rule acknowledged: yes`." },
             { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." },
@@ -155,7 +156,7 @@ export const PLAN = {
                 title: "Task Decomposition Audit",
                 evaluationPoints: [
                     "Does every task target a single coherent area (vertical slice)?",
-                    "Can each task be completed in 2-5 minutes?",
+                    "Is each implementation unit feature-atomic, with internal steps that fit 2-5 minutes each?",
                     "Does every task have an acceptance criterion link, exact verification command/manual step, and expected evidence/pass condition?",
                     "Are there tasks that touch multiple unrelated areas?",
                     "Would a new engineer understand and start each task within two minutes?"
@@ -177,7 +178,7 @@ export const PLAN = {
             {
                 title: "Five-Minute Budget + No-Placeholders Audit",
                 evaluationPoints: [
-                    "Does every task carry an explicit minutes estimate (e.g. `[~3m]`) and does every estimate fit the 2-to-5-minute budget? Estimates >5 minutes must be split.",
+                    "Does every internal TDD step carry a bounded 2-to-5-minute estimate or checkbox-level step? Whole units may be larger when feature-atomic.",
                     "Are all file paths, test commands, verification commands, and expected evidence copy-pasteable/specific as written — no `TODO`, `TBD`, `FIXME`, `<fill-in>`, `<your-*-here>`, `xxx`, bare `run tests`, or ellipsis standing in for omitted args?",
                     "Does every acceptance-criterion reference resolve to a real R# / AC-### in the spec (not a blank link)?",
                     "If an estimate is genuinely uncertain (first-time integration, unfamiliar library), is the uncertainty named explicitly and scheduled as a spike task in batch 0, rather than hidden behind a large estimate?"