cclaw-cli 7.5.0 → 7.7.0

package/dist/content/stages/tdd.js

@@ -8,7 +8,7 @@ export const TDD = {
     complexityTier: "standard",
     skillFolder: "tdd",
     skillName: "tdd",
-    skillDescription: "Full vertical-slice TDD cycle: discover existing tests and system impact, then RED (failing tests), GREEN (minimal implementation), REFACTOR (cleanup). One source item at a time with strict traceability.",
+    skillDescription: "Adaptive vertical-slice TDD cycle: route each feature-atomic implementation unit through inline, single-builder, parallel-builder, or strict-micro execution while preserving RED-first traceability.",
     philosophy: {
         hardGate: "Do NOT merge, ship, or skip review. Follow RED → GREEN → REFACTOR strictly for each plan slice. Do NOT write implementation code before RED tests exist. Do NOT write RED tests before discovering relevant existing tests and impacted contracts. Do NOT skip the REFACTOR step.",
         ironLaw: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST — THE RED FAILURE IS THE SPEC.",
@@ -37,19 +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; read `05-plan.md`/`wave-plans/` only once `wave-status` names work. Restore partial waves by parallelizing remaining members.",
-            "**Routing AskQuestion:** Two or more ready slices ⇒ exactly one AskQuestion (“launch wave …” vs “single slice …”, 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 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.",
             "**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 slice:** Dispatch `slice-builder` with `--slice S-<id>` and explicit `--paths` from the plan. Parallel builders are allowed when paths are disjoint; honor any lane/lease flags the hook requires today.",
-            "**Single span owns the slice:** `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 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=...`.",
+            "**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.",
+            "**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 when `claimedPaths` are disjoint; remain serial when the plan orders dependencies.",
-            "Controller never writes production code or per-slice prose — the delegated worker does. Record routing decisions; cite `wave-status` before redundant slice questions.",
+            "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.",
             "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).",
@@ -59,8 +61,9 @@ 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.",
-            "Dispatch `slice-builder` for RED (failing tests, no production edits beyond test files).",
-            "Dispatch the same builder for GREEN with minimal production changes and full-suite evidence.",
+            "Route the active unit via topology (`inline`, `single-builder`, `parallel-builders`, or `strict-micro`) before RED.",
+            "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.",
             "Keep `tdd-slices/S-<id>.md` aligned with evidence as the builder finishes.",
             "Run fresh verification and attach traceability (plan task + spec criterion).",

package/dist/content/start-command.js

@@ -117,9 +117,9 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 4. Otherwise check current stage gates, resume if incomplete, and advance if complete.
 5. **TDD wave dispatch:** When \`currentStage\` is \`tdd\`, run \`node .cclaw/cli.mjs internal wave-status --json\` first, then read the managed **Parallel Execution Plan** block inside \`${RUNTIME_ROOT}/artifacts/05-plan.md\` plus \`${RUNTIME_ROOT}/artifacts/wave-plans/\` for detail. Resume partial waves on remaining members only.
 
-   **The controller never edits production code in TDD.** When \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out the entire wave in a SINGLE controller message: one harness \`Task(subagent_type=…, description="slice-builder S-<id>", prompt=<full slice context>)\` call per ready slice, **side by side in the same tool batch**. Each \`slice-builder\` span owns the full RED → GREEN → REFACTOR → DOC cycle for its slice and emits its own \`delegation-record --phase=red|green|refactor|refactor-deferred|doc\` rows. RED-before-GREEN is enforced per-slice by the linter.
+   **The controller preserves TDD evidence.** When \`topology: parallel-builders\` and \`pathConflicts: []\`, fan out the ready independent units in a SINGLE controller message: one harness \`Task(subagent_type=…, description="slice-builder S-<id>", prompt=<full slice context>)\` call per routed builder, **side by side in the same tool batch**. Each \`slice-builder\` span owns the full RED → GREEN → REFACTOR → DOC cycle for its feature-atomic unit and emits its own \`delegation-record --phase=red|green|refactor|refactor-deferred|doc\` rows. RED-before-GREEN is enforced per-slice by the linter.
 
-   When \`mode: blocked\` with \`pathConflicts\`, surface exactly one AskQuestion that lets the user resolve the overlap (drop / split / serialize). When \`mode: single-slice\`, dispatch one \`Task\` for the next ready slice.
+   When \`mode: blocked\` with \`pathConflicts\`, surface exactly one AskQuestion that lets the user resolve the overlap (drop / split / serialize). When \`topology: single-builder\`, dispatch one \`Task\` for the next ready unit. When \`topology: inline\`, execute inline only if the same RED/GREEN/REFACTOR evidence and path/commit gates can be satisfied.
 
 6. **Auto-advance after stage-complete:** when \`stage-complete\` returns \`ok\` with a new \`currentStage\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`. Announce \`Stage <prev> complete → entering <next>. Continuing.\` and proceed.
 
@@ -214,7 +214,7 @@ Progress the tracked flow only when one exists:
 2. If missing, guide the user to run \`npx cclaw-cli init\` and stop.
 3. If it is only a fresh init placeholder (\`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\`), stop and ask for \`/cc <prompt>\` to start a tracked run. Do not silently create a brainstorm run.
 4. Check gates for \`currentStage\`.
-5. **TDD:** When \`currentStage\` is \`tdd\`, run \`wave-status --json\`, then reconcile the managed **Parallel Execution Plan** in \`05-plan.md\` with \`wave-plans/wave-NN.md\`. **The controller never edits production code in TDD.** When \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out the wave in a SINGLE controller message — one \`Task\` per ready slice, side by side. If \`mode: blocked\`, resolve overlaps first. Each \`slice-builder\` span owns its full RED → GREEN → REFACTOR → DOC cycle. Mirror plan \`dependsOn\` ordering between waves.
+5. **TDD:** When \`currentStage\` is \`tdd\`, run \`wave-status --json\`, then reconcile the managed **Parallel Execution Plan** in \`05-plan.md\` with \`wave-plans/wave-NN.md\`. Route by \`nextDispatch.topology\`: \`parallel-builders\` fans out independent units in one controller message, \`single-builder\` dispatches one builder, \`inline\` executes directly only with equivalent evidence, and \`strict-micro\` preserves tiny-slice sequencing. If \`mode: blocked\`, resolve overlaps first. Each delegated \`slice-builder\` span owns its full RED → GREEN → REFACTOR → DOC cycle. Mirror plan \`dependsOn\` ordering between waves.
 6. **Wave resume:** Parallelize unfinished members; never restart completed lanes. Integration-overseer follows \`integrationCheckRequired\`; when skipped, emit \`cclaw_integration_overseer_skipped\` per the hook contract.
 7. If incomplete → load current stage skill and execute.
 8. If complete → advance to next stage and execute. **Auto-advance:** when \`stage-complete\` returns \`ok\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`.

package/dist/content/subagent-context-skills.js

@@ -10,7 +10,7 @@ function skillFrontmatter(name, description) {
 function tddCycleEvidenceSkill() {
     return `${skillFrontmatter("tdd-cycle-evidence", "Evidence contract for the mandatory slice-builder delegation across RED/GREEN/REFACTOR/DOC.")}# TDD Cycle Evidence
 
-Use with the \`slice-builder\` delegation in the \`tdd\` stage. One \`slice-builder\` span owns the full cycle for a single vertical slice.
+Use with the \`slice-builder\` delegation in the \`tdd\` stage. One \`slice-builder\` span owns the full cycle for a feature-atomic implementation unit/slice, including its internal 2-5 minute TDD steps.
 
 ## Required Output
 
@@ -25,7 +25,7 @@ Use with the \`slice-builder\` delegation in the \`tdd\` stage. One \`slice-buil
 - No production code before RED evidence exists.
 - If a RED test cannot be expressed, stop and route back to design/spec with the blocker.
 - Record command output summaries, not just "tests passed".
-- Multiple \`slice-builder\` spans run in parallel inside one wave only when their \`claimedPaths\` are disjoint.
+- Multiple \`slice-builder\` spans run in parallel inside one wave only when topology is \`parallel-builders\` and their \`claimedPaths\` are disjoint. \`strict-micro\` keeps tiny tasks separate; \`inline\` skips delegation but not RED/GREEN/REFACTOR evidence.
 `;
 }
 function reviewSpecPassSkill() {

package/dist/content/subagents.js

@@ -37,7 +37,7 @@ description: "Orchestrate implementation via isolated subagents — one fresh ag
 Use a **controller -> coder -> overseer** loop when building multi-step software work.
 
 - **Controller (parent agent):** owns the plan, gating, sequencing, and dispatch decisions; never mixes deep implementation context with review evidence.
-- **Coder / slice-builder (subagent):** receives a **single self-contained task** and edits code only within that scope; exits with a structured status contract.
+- **Coder / slice-builder (subagent):** receives a **single feature-atomic implementation unit/slice** and edits code only within that scope; exits with a structured status contract.
 - **Overseer / reviewer (subagent):** validates outputs against the specification **by reading code** and never edits during the overseer pass.
 
 This pattern is intentionally **Superpowers-style**: cheap parallelism where it doesn’t corrupt state, strict serialization where it would.
@@ -62,7 +62,7 @@ Reconcile findings into \`.cclaw/artifacts/07-review-army.json\` with explicit s
 
 ### TDD evidence protocol
 
-Each parallel slice runs end-to-end inside one \`slice-builder\` delegation, with RED, GREEN, REFACTOR, and per-slice DOC as phase intents on a single span:
+Each delegated feature-atomic slice runs end-to-end inside one \`slice-builder\` delegation, with RED, GREEN, REFACTOR, and per-slice DOC as phase intents on a single span. The slice may contain internal 2-5 minute TDD steps; \`strict-micro\` is the explicit mode for one tiny task per slice:
 
 - \`--phase red\`: failing tests only, no production writes
 - \`--phase green\`: minimal production implementation that passes the matching RED
@@ -70,7 +70,7 @@ Each parallel slice runs end-to-end inside one \`slice-builder\` delegation, wit
 - \`--phase doc\`: write \`<artifacts-dir>/tdd-slices/S-<id>.md\` for the slice
 
 Set \`CCLAW_ACTIVE_AGENT\` to the active phase name when possible so workflow-guard
-can enforce phase-appropriate write boundaries. The mandatory gate is the evidence-backed \`slice-builder\` row, not multiple default subagents.
+can enforce phase-appropriate write boundaries. The mandatory gate is the evidence-backed \`slice-builder\` row for delegated topologies, not multiple default subagents. When TDD topology is \`inline\`, the controller may skip the builder but must preserve the same RED-before-GREEN, AC traceability, path containment, verification, managed commit/worktree, lockfile twin, and orphan-change gates.
 
 ## Model & Harness Routing Notes
 
@@ -154,7 +154,7 @@ If you catch yourself writing “read PLAN.md Task 3” or “implement the next
 Borrow the good part of Team/Ruflo-style orchestration without adding a swarm runtime:
 
 - **One controller owns alignment.** The parent keeps the task list, gate state, and final synthesis.
-- **Small fan-out by default.** Run at most 3-5 parallel agents, and only for independent read-only research or non-overlapping files.
+- **Small fan-out by topology.** Run at most configured \`maxBuilders\` parallel builders, and only for independent substantial units or independent read-only research/review lenses.
 - **No parallel writes to adjacent surfaces.** If tasks may touch the same module, serialize them.
 - **Checkpoint before synthesis.** Each agent returns status, files inspected/changed, evidence, and blockers before the parent acts.
 - **Consensus is for hard calls only.** Use two reviewers when severity or architecture is disputed; otherwise one evidence-backed reviewer is enough.
@@ -177,7 +177,7 @@ Before parallel dispatch, answer yes to all gates: tasks are independent, write
    - Copy each task verbatim into a working queue (checklist is fine).
    - Normalize each task so it includes: goal, acceptance criteria, constraints, and explicit “out of scope.”
 
-2. **For each task — sequential by default; parallel only with cohesion controls:**
+2. **For each unit — cheapest safe topology first; parallel only with cohesion controls:**
    - Implementation subagents are sequential by default. Parallel implementers
      are allowed only when ALL three conditions hold:
      - (a) the lanes touch non-overlapping files (verify via the plan's task
@@ -397,7 +397,7 @@ This document bridges **Superpowers-style task isolation** with the **gstack “
 ${conversationLanguagePolicyMarkdown()}
 **Default rule:** parallel implementation agents are SAFE for investigation, analysis, review, and the **TDD wave-fanout** path; otherwise keep implementation sequential.
 
-**TDD wave-fanout is the supported parallel-implementation path.** When \`cclaw-cli internal wave-status --json\` reports \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out one \`slice-builder\` span per ready slice in a single controller message. Each span owns its disjoint \`claimedPaths\`; the dispatcher rejects overlapping spans with \`DispatchOverlapError\` inline, so the disjoint-paths invariant is enforced for you.
+**TDD wave-fanout is the supported parallel-implementation path.** When \`cclaw-cli internal wave-status --json\` reports \`topology: parallel-builders\` and \`pathConflicts: []\`, fan out one \`slice-builder\` span per ready feature-atomic unit/slice in a single controller message, capped by \`maxBuilders\`. Each span owns its disjoint \`claimedPaths\`; the dispatcher rejects overlapping spans with \`DispatchOverlapError\` inline, so the disjoint-paths invariant is enforced for you.
 
 **Outside wave-fanout** — for ad-hoc parallel implementation that touches shared source trees — keep work **sequential** unless you have proven disjoint filesystem ownership and an explicit merge protocol.
 

package/dist/content/templates.js

@@ -868,7 +868,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 ## Task List
 
 **Rules (apply before writing rows):**
-- Every task fits the **2-5 minute budget**. If \`[~Nm]\` is >5, split the task.
+- Task rows are internal TDD steps unless \`Execution Topology\` is \`strict-micro\`. Keep each step in the **2-5 minute budget**; group related steps into feature-atomic \`U-*\` Implementation Units.
 - **No placeholders.** Forbidden tokens anywhere in this table: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis. Every file path, test, and verification command must be copy-pasteable as written.
 - **No silent scope reduction.** Forbidden phrasing when locked decisions exist: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
 - If an estimate is genuinely uncertain (new library, unfamiliar subsystem), add a **spike task in batch 0** to de-risk — do NOT hide the uncertainty inside a large estimate.
@@ -883,7 +883,12 @@ Execution rule: complete and verify each batch before starting the next batch.
 | AC-1 | T-1 |
 
 ## Execution Posture
-- Posture: sequential | dependency-batched | parallel-safe | blocked
+- execution.topology: auto | inline | single-builder | parallel-builders | strict-micro
+- execution.strictness: fast | balanced | strict
+- execution.maxBuilders: 5
+- plan.sliceGranularity: feature-atomic | strict-micro
+- plan.microTaskPolicy: advisory | strict
+- Posture rationale: (why this is the cheapest safe topology)
 - Stop conditions:
 - Risk triggers:
 - TDD checkpoint plan: RED commit/checkpoint -> GREEN commit/checkpoint -> REFACTOR commit/checkpoint (or deferred because: )
@@ -904,7 +909,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 |  |  |  |
 
 ## Implementation Units
-> Required structural form per implementation unit. Use ≥1 unit; bite-sized 2-5 minute steps inside each. The linter validates shape, not topic.
+> Required structural form per implementation unit. Default is feature-atomic units with bite-sized 2-5 minute TDD steps inside each. Use strict micro-slices only for high-risk work or when explicitly configured.
 
 ### Implementation Unit U-1
 - **id:** U-1
@@ -947,10 +952,10 @@ Execution rule: complete and verify each batch before starting the next batch.
 - Required pre-merge proof:
 
 ## Execution Handoff
-- **Posture chosen:** Subagent-Driven (recommended) | Inline executor
-- **Why this posture:** (one line tying choice to plan size, parallelism, novelty)
-- **Subagent recipe (if Subagent-Driven):** \`<harness>\` -> \`<dispatch surface>\` -> \`<agent-definition path>\` (substitute neutral placeholders; full recipes in \`docs/harnesses.md\`)
-- **Inline recipe (if Inline executor):** TDD loop unit-by-unit with batch checkpoints
+- **Topology chosen:** execution.topology = auto | inline | single-builder | parallel-builders | strict-micro
+- **Why this topology:** (one line tying choice to unit count, path independence, risk, and maxBuilders)
+- **Subagent recipe (if single/parallel builder):** \`<harness>\` -> \`<dispatch surface>\` -> \`<agent-definition path>\` (substitute neutral placeholders; full recipes in \`docs/harnesses.md\`)
+- **Inline recipe (if inline):** TDD loop unit-by-unit with the same RED-before-GREEN, AC traceability, path containment, verification, and managed commit/worktree gates
 
 ## Plan Quality Scan
 <!-- linter-meta -->

package/dist/delegation.d.ts

@@ -330,8 +330,9 @@ export declare class DispatchOverlapError extends Error {
 /**
  * Thrown when the count of active `slice-builder` spans reaches
  * `MAX_PARALLEL_SLICE_BUILDERS` and a new scheduled row would push it past
- * the cap. Cap can be overridden once via `--override-cap=N` on the hook
- * flag or globally via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<N>` env.
+ * the cap. Cap can be configured via `.cclaw/config.yaml::execution.maxBuilders`,
+ * overridden once via `--override-cap=N` on the hook flag, or globally via
+ * `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<N>` env.
  */
 export declare class DispatchCapError extends Error {
     readonly cap: number;
@@ -381,6 +382,45 @@ export declare class DispatchClaimedPathProtectedError extends Error {
  * offending path so the operator can fix the dispatch in one pass.
  */
 export declare function validateClaimedPathsNotProtected(stamped: DelegationEntry): void;
+/**
+ * Thrown by `appendDelegation` (and the inline `delegation-record.mjs`
+ * helper) when an event with a non-null `phase` is recorded with
+ * `status="acknowledged"`. Phase-level granularity only makes sense on
+ * terminal outcomes (`completed` or `failed`); the dispatch-level ACK
+ * (no phase) is the controller saying "I see the dispatch surface back".
+ *
+ * Motivated by hox W-08/S-41: the slice-builder agent recorded all four
+ * phase events with `--status=acknowledged`, which the helper silently
+ * accepted but `slice-commit.mjs` only fires on `phase=doc status=completed`.
+ * `wave-status` then saw the slice as phantom-open even though the
+ * worker had finished. Recovery required raw backfill commands.
+ *
+ * 7.6.0 makes the constraint explicit: pair `--phase=<phase>` with
+ * `--status=completed` (or `--status=failed`) and use
+ * `--status=acknowledged` only for the dispatch-level ack (no phase).
+ */
+export declare class PhaseEventRequiresTerminalStatusError extends Error {
+    readonly phase: string;
+    readonly status: DelegationStatus;
+    readonly spanId: string;
+    readonly correctedCommandHint: string;
+    constructor(params: {
+        phase: string;
+        status: DelegationStatus;
+        spanId: string;
+        correctedCommandHint: string;
+    });
+}
+/**
+ * Reject delegation rows where `phase` is set but `status` is not
+ * `completed` or `failed`. Acknowledged/launched/scheduled/waived/stale
+ * rows must NOT carry a phase — the phase-level lifecycle exists only
+ * to record terminal outcomes per phase (RED/GREEN/REFACTOR/DOC).
+ *
+ * Throws `PhaseEventRequiresTerminalStatusError`; the message includes
+ * an actionable corrected-command hint that the controller can paste.
+ */
+export declare function validatePhaseEventStatus(stamped: DelegationEntry): void;
 /**
  * Thrown by `appendDelegation` when a new `scheduled` span would open a
  * second TDD cycle for a slice that already has at least one closed span
@@ -497,7 +537,7 @@ export declare function validateFileOverlap(stamped: DelegationEntry, activeEntr
 };
 /**
  * Enforce the slice-builder fan-out cap. The new scheduled row pushes the
- * active count from N to N+1; if that would exceed the cap (default 5,
+ * active count from N to N+1; if that would exceed the cap (default/config 5,
  * env-overridable via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS`), throw
  * `DispatchCapError`.
  *

package/dist/delegation.js

@@ -3,12 +3,13 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { RUNTIME_ROOT } from "./constants.js";
-import { readConfig } from "./config.js";
+import { readConfig, resolveMaxBuilders } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
 import { compareCanonicalUnitIds, mergeParallelWaveDefinitions, parseImplementationUnitParallelFields, parseImplementationUnits, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./internal/plan-split-waves.js";
+import { compareSliceIds } from "./util/slice-id.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -615,8 +616,9 @@ export class DispatchOverlapError extends Error {
 /**
  * Thrown when the count of active `slice-builder` spans reaches
  * `MAX_PARALLEL_SLICE_BUILDERS` and a new scheduled row would push it past
- * the cap. Cap can be overridden once via `--override-cap=N` on the hook
- * flag or globally via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<N>` env.
+ * the cap. Cap can be configured via `.cclaw/config.yaml::execution.maxBuilders`,
+ * overridden once via `--override-cap=N` on the hook flag, or globally via
+ * `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<N>` env.
  */
 export class DispatchCapError extends Error {
     cap;
@@ -700,6 +702,69 @@ export function validateClaimedPathsNotProtected(stamped) {
         spanId: stamped.spanId ?? "unknown"
     });
 }
+/**
+ * Thrown by `appendDelegation` (and the inline `delegation-record.mjs`
+ * helper) when an event with a non-null `phase` is recorded with
+ * `status="acknowledged"`. Phase-level granularity only makes sense on
+ * terminal outcomes (`completed` or `failed`); the dispatch-level ACK
+ * (no phase) is the controller saying "I see the dispatch surface back".
+ *
+ * Motivated by hox W-08/S-41: the slice-builder agent recorded all four
+ * phase events with `--status=acknowledged`, which the helper silently
+ * accepted but `slice-commit.mjs` only fires on `phase=doc status=completed`.
+ * `wave-status` then saw the slice as phantom-open even though the
+ * worker had finished. Recovery required raw backfill commands.
+ *
+ * 7.6.0 makes the constraint explicit: pair `--phase=<phase>` with
+ * `--status=completed` (or `--status=failed`) and use
+ * `--status=acknowledged` only for the dispatch-level ack (no phase).
+ */
+export class PhaseEventRequiresTerminalStatusError extends Error {
+    phase;
+    status;
+    spanId;
+    correctedCommandHint;
+    constructor(params) {
+        super(`phase_event_requires_completed_or_failed_status — span ${params.spanId} recorded --phase=${params.phase} with --status=${params.status}; ` +
+            `phase-level events are only valid on terminal outcomes (--status=completed or --status=failed). ` +
+            `The dispatch-level ack (no --phase) can still use --status=acknowledged. ` +
+            `Corrected command: ${params.correctedCommandHint}`);
+        this.name = "PhaseEventRequiresTerminalStatusError";
+        this.phase = params.phase;
+        this.status = params.status;
+        this.spanId = params.spanId;
+        this.correctedCommandHint = params.correctedCommandHint;
+    }
+}
+/**
+ * Reject delegation rows where `phase` is set but `status` is not
+ * `completed` or `failed`. Acknowledged/launched/scheduled/waived/stale
+ * rows must NOT carry a phase — the phase-level lifecycle exists only
+ * to record terminal outcomes per phase (RED/GREEN/REFACTOR/DOC).
+ *
+ * Throws `PhaseEventRequiresTerminalStatusError`; the message includes
+ * an actionable corrected-command hint that the controller can paste.
+ */
+export function validatePhaseEventStatus(stamped) {
+    if (typeof stamped.phase !== "string" || stamped.phase.length === 0)
+        return;
+    if (stamped.status === "completed" || stamped.status === "failed")
+        return;
+    const phase = stamped.phase;
+    const sliceFlag = typeof stamped.sliceId === "string" && stamped.sliceId.length > 0
+        ? `--slice=${stamped.sliceId} `
+        : "";
+    const spanFlag = typeof stamped.spanId === "string" && stamped.spanId.length > 0
+        ? `--span-id=${stamped.spanId} `
+        : "";
+    const correctedCommandHint = `node .cclaw/hooks/delegation-record.mjs --stage=${stamped.stage} --agent=${stamped.agent} --mode=${stamped.mode} --status=completed --phase=${phase} ${sliceFlag}${spanFlag}--evidence-ref="<phase outcome>"`;
+    throw new PhaseEventRequiresTerminalStatusError({
+        phase,
+        status: stamped.status,
+        spanId: stamped.spanId ?? "unknown",
+        correctedCommandHint
+    });
+}
 /**
  * Thrown by `appendDelegation` when a new `scheduled` span would open a
  * second TDD cycle for a slice that already has at least one closed span
@@ -845,7 +910,7 @@ export function readySliceUnitsFromMergedWaves(mergedWaves, planMarkdown, option
         }
     }
     const out = [];
-    for (const sliceId of [...sliceSet].sort((a, b) => a.localeCompare(b))) {
+    for (const sliceId of [...sliceSet].sort(compareSliceIds)) {
         const member = mergedWaves.flatMap((w) => w.members).find((x) => x.sliceId === sliceId);
         if (!member)
             continue;
@@ -1047,7 +1112,7 @@ export function validateFileOverlap(stamped, activeEntries) {
 }
 /**
  * Enforce the slice-builder fan-out cap. The new scheduled row pushes the
- * active count from N to N+1; if that would exceed the cap (default 5,
+ * active count from N to N+1; if that would exceed the cap (default/config 5,
  * env-overridable via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS`), throw
  * `DispatchCapError`.
  *
@@ -1062,9 +1127,13 @@ export function validateFanOutCap(stamped, activeEntries, override) {
         return;
     if (stamped.status !== "scheduled")
         return;
-    const cap = (override !== null && override !== undefined && Number.isInteger(override) && override >= 1)
-        ? override
-        : (readMaxParallelOverrideFromEnv() ?? MAX_PARALLEL_SLICE_BUILDERS);
+    const cap = readMaxParallelOverrideFromEnv() ??
+        (override !== null &&
+            override !== undefined &&
+            Number.isInteger(override) &&
+            override >= 1
+            ? override
+            : MAX_PARALLEL_SLICE_BUILDERS);
     const sameLaneActive = activeEntries.filter((entry) => entry.stage === stamped.stage &&
         entry.agent === stamped.agent &&
         entry.spanId !== stamped.spanId);
@@ -1183,6 +1252,7 @@ export async function appendDelegation(projectRoot, entry) {
             return;
         }
         validateMonotonicTimestamps(stamped, prior.entries);
+        validatePhaseEventStatus(stamped);
         if (stamped.status === "scheduled" &&
             typeof stamped.sliceId === "string" &&
             stamped.sliceId.length > 0 &&
@@ -1206,7 +1276,8 @@ export async function appendDelegation(projectRoot, entry) {
             if (overlap.autoParallel && stamped.allowParallel !== true) {
                 stamped.allowParallel = true;
             }
-            validateFanOutCap(stamped, activeForRun);
+            const config = await readConfig(projectRoot).catch(() => null);
+            validateFanOutCap(stamped, activeForRun, resolveMaxBuilders(config));
             if (stamped.allowParallel !== true) {
                 const existing = findActiveSpanForPair(stamped.stage, stamped.agent, activeRunId, prior);
                 if (existing && existing.spanId && existing.spanId !== stamped.spanId) {

package/dist/execution-topology.d.ts

@@ -0,0 +1,36 @@
+import type { ExecutionStrictnessProfile, ExecutionTopology } from "./types.js";
+export interface ExecutionTopologyShape {
+    /** Ready implementation units/slices the controller could execute now. */
+    unitCount: number;
+    /** Ready units with no declared dependency/path conflict against each other. */
+    independentUnitCount?: number;
+    /** Ready units large enough to justify isolated builder overhead. */
+    substantialUnitCount?: number;
+    /** True when same-wave path ownership overlaps or is unknown-dangerous. */
+    hasPathConflicts?: boolean;
+    /** True for migrations, public contracts, security, data loss, or broad API changes. */
+    highRisk?: boolean;
+    /** True when a plan or controller explicitly requests micro-slice discipline. */
+    requiresStrictMicro?: boolean;
+    /** True when the controller can safely execute the unit inline in the current harness. */
+    inlineSafe?: boolean;
+}
+export interface ExecutionTopologyDecision {
+    topology: Exclude<ExecutionTopology, "auto">;
+    maxBuilders: number;
+    reason: string;
+}
+export interface RouteExecutionTopologyOptions {
+    configuredTopology?: ExecutionTopology;
+    strictness?: ExecutionStrictnessProfile;
+    maxBuilders?: number;
+    shape: ExecutionTopologyShape;
+}
+/**
+ * Choose the cheapest safe execution topology for a ready TDD surface.
+ *
+ * Safety invariants are intentionally conservative: explicit strict-micro wins,
+ * path conflicts prevent fan-out, and parallel builders require multiple
+ * independent substantial units plus a builder cap above one.
+ */
+export declare function routeExecutionTopology(options: RouteExecutionTopologyOptions): ExecutionTopologyDecision;

package/dist/execution-topology.js

@@ -0,0 +1,73 @@
+const DEFAULT_MAX_BUILDERS = 5;
+function normalizeMaxBuilders(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1
+        ? value
+        : DEFAULT_MAX_BUILDERS;
+}
+/**
+ * Choose the cheapest safe execution topology for a ready TDD surface.
+ *
+ * Safety invariants are intentionally conservative: explicit strict-micro wins,
+ * path conflicts prevent fan-out, and parallel builders require multiple
+ * independent substantial units plus a builder cap above one.
+ */
+export function routeExecutionTopology(options) {
+    const configured = options.configuredTopology ?? "auto";
+    const strictness = options.strictness ?? "balanced";
+    const maxBuilders = normalizeMaxBuilders(options.maxBuilders);
+    const shape = options.shape;
+    if (configured !== "auto") {
+        return {
+            topology: configured,
+            maxBuilders,
+            reason: `configured execution.topology=${configured}`
+        };
+    }
+    if (shape.requiresStrictMicro || strictness === "strict") {
+        return {
+            topology: "strict-micro",
+            maxBuilders,
+            reason: shape.requiresStrictMicro
+                ? "plan requested strict micro-slice execution"
+                : "strict execution profile selected"
+        };
+    }
+    const unitCount = Math.max(0, shape.unitCount);
+    if (unitCount === 0) {
+        return {
+            topology: "inline",
+            maxBuilders,
+            reason: "no ready units; controller can reconcile inline"
+        };
+    }
+    if (shape.hasPathConflicts) {
+        return {
+            topology: "single-builder",
+            maxBuilders,
+            reason: "path conflicts require serialized execution"
+        };
+    }
+    const independent = shape.independentUnitCount ?? unitCount;
+    const substantial = shape.substantialUnitCount ?? unitCount;
+    if (maxBuilders > 1 && independent >= 2 && substantial >= 2) {
+        return {
+            topology: "parallel-builders",
+            maxBuilders,
+            reason: "multiple independent substantial units are ready"
+        };
+    }
+    if (unitCount === 1 && shape.inlineSafe && !shape.highRisk) {
+        return {
+            topology: "inline",
+            maxBuilders,
+            reason: "single low-risk inline-safe unit"
+        };
+    }
+    return {
+        topology: "single-builder",
+        maxBuilders,
+        reason: unitCount === 1
+            ? "single ready unit keeps builder evidence isolated"
+            : "ready units are not safely parallelizable"
+    };
+}

package/dist/gate-evidence.js

@@ -11,6 +11,7 @@ import { computeEarlyLoopStatus, isEarlyLoopStage, normalizeEarlyLoopMaxIteratio
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { detectSupplyChainChanges } from "./internal/detect-supply-chain-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
+import { loadStackAdapter } from "./stack-detection.js";
 import { validateTddVerificationEvidence } from "./tdd-verification-evidence.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
     const resolved = await resolveArtifactPath(stage, {
@@ -88,20 +89,17 @@ async function discoverRealTestCommands(projectRoot) {
             commands.push(name === "test" ? "bun test" : `bun run ${name}`);
         }
     }
-    if (await exists(path.join(projectRoot, "pyproject.toml")))
-        commands.push("pytest");
+    // 7.6.0 — pull additional commands from the stack-adapter's
+    // testCommandHints rather than hardcoding pytest/go test/cargo
+    // test/mvn/gradle here. Adapters that don't apply to the project
+    // contribute no commands; pytest.ini support is kept as an
+    // explicit fallback because pyproject.toml-less projects exist.
+    const stackAdapter = await loadStackAdapter(projectRoot);
+    for (const hint of stackAdapter.testCommandHints) {
+        commands.push(hint);
+    }
     if (await exists(path.join(projectRoot, "pytest.ini")))
         commands.push("pytest");
-    if (await exists(path.join(projectRoot, "go.mod")))
-        commands.push("go test ./...");
-    if (await exists(path.join(projectRoot, "Cargo.toml")))
-        commands.push("cargo test");
-    if (await exists(path.join(projectRoot, "pom.xml")))
-        commands.push("mvn test");
-    if (await exists(path.join(projectRoot, "build.gradle")) ||
-        await exists(path.join(projectRoot, "build.gradle.kts"))) {
-        commands.push("gradle test", "./gradlew test");
-    }
     return unique(commands);
 }
 async function verifyDiscoveredCommandEvidence(projectRoot, stage, gateId, flowState) {

package/dist/internal/advance-stage/start-flow.js

@@ -4,7 +4,7 @@ import { RUNTIME_ROOT } from "../../constants.js";
 import { createInitialFlowState } from "../../flow-state.js";
 import { readFlowState, writeFlowState } from "../../runs.js";
 import { listExistingFiles, listFilesUnder, pathExists } from "./helpers.js";
-import { STACK_DISCOVERY_DIR_MARKERS, STACK_DISCOVERY_MARKERS } from "../../stack-detection.js";
+import { STACK_DISCOVERY_DIR_MARKERS, STACK_DISCOVERY_MARKERS, loadStackAdapter } from "../../stack-detection.js";
 import { TRACK_STAGES } from "../../types.js";
 import { buildValidationReport } from "./advance.js";
 import { carriedCompletedStageCatalog, completedStageClosureEvidenceIssues, firstIncompleteStageForTrack } from "./verify.js";
@@ -58,11 +58,20 @@ export async function collectRepoSignals(projectRoot) {
             // ignore
         }
     }
-    for (const manifest of ["package.json", "pyproject.toml", "Cargo.toml"]) {
+    // 7.6.0 — manifest detection now routes through the stack-adapter
+    // contract instead of hardcoding `package.json` / `pyproject.toml` /
+    // `Cargo.toml`. Adapters that declare manifestGlobs probe their
+    // declared paths; the unknown adapter is a no-op.
+    const stackAdapter = await loadStackAdapter(projectRoot);
+    for (const manifestGlob of stackAdapter.manifestGlobs) {
+        if (manifestGlob.includes("*"))
+            continue;
         try {
-            const st = await fs.stat(path.join(projectRoot, manifest));
-            if (st.isFile())
+            const st = await fs.stat(path.join(projectRoot, manifestGlob));
+            if (st.isFile()) {
                 hasPackageManifest = true;
+                break;
+            }
         }
         catch {
             // ignore