cclaw-cli 7.5.0 → 7.6.0

package/dist/artifact-linter/plan.js

@@ -5,6 +5,11 @@ import { FORBIDDEN_PLACEHOLDER_TOKENS, CONFIDENCE_FINDING_REGEX_SOURCE } from ".
 import fs from "node:fs/promises";
 import path from "node:path";
 import { PLAN_SPLIT_SMALL_PLAN_THRESHOLD, parseImplementationUnits, parseImplementationUnitParallelFields } from "../internal/plan-split-waves.js";
+import { compareSliceIds, parseSliceId } from "../util/slice-id.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { loadStackAdapter } from "../stack-detection.js";
+const execFileAsync = promisify(execFile);
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 const TASK_ID_PATTERN = /\bT-\d{3}[a-z]?(?:\.\d{1,3})?\b/giu;
@@ -120,13 +125,15 @@ function parseParallelWaveTableMetadata(planMarkdown) {
             continue;
         }
         const sliceCell = cells[0];
-        if (!/^S-\d+$/iu.test(sliceCell))
+        const parsedSlice = parseSliceId(sliceCell);
+        if (!parsedSlice)
             continue;
         const idx = headerIdx ?? new Map();
         const unitIdx = idx.get("unit") ?? idx.get("taskid") ?? 1;
         const pathsIdx = idx.get("claimedpaths");
         const parallelizableIdx = idx.get("parallelizable");
         const laneIdx = idx.get("lane");
+        const dependsOnIdx = idx.get("dependson");
         const rawPaths = pathsIdx !== undefined ? (cells[pathsIdx] ?? "") : "";
         const claimedPaths = rawPaths.length === 0
             ? []
@@ -141,12 +148,22 @@ function parseParallelWaveTableMetadata(planMarkdown) {
         if (rawParallel === "false" || rawParallel === "no")
             parallelizable = false;
         const laneRaw = laneIdx !== undefined ? (cells[laneIdx] ?? "").trim().toLowerCase() : "";
+        const rawDeps = dependsOnIdx !== undefined ? (cells[dependsOnIdx] ?? "") : "";
+        const dependsOn = rawDeps.length === 0
+            ? []
+            : rawDeps
+                .replace(/^\[|\]$/gu, "")
+                .split(/[,\s]+/u)
+                .map((token) => token.trim().replace(/^`|`$/gu, ""))
+                .map((token) => parseSliceId(token)?.id ?? "")
+                .filter((id) => id.length > 0);
         current.rows.push({
-            sliceId: sliceCell.toUpperCase(),
+            sliceId: parsedSlice.id,
             unit: (cells[unitIdx] ?? "").trim(),
             claimedPaths,
             parallelizable,
-            lane: laneRaw.length > 0 ? laneRaw : null
+            lane: laneRaw.length > 0 ? laneRaw : null,
+            dependsOn
         });
     }
     flush();
@@ -156,6 +173,65 @@ function waveHasSequentialModeHint(wave) {
     const noteText = wave.notes.join("\n").toLowerCase();
     return /mode\s*:\s*sequential/iu.test(noteText) || /\bsequential\b/iu.test(noteText) || /\bserial\b/iu.test(noteText);
 }
+/**
+ * Capture the set of repo-relative paths tracked at HEAD. Returns an
+ * empty set when the project root is not a git repo or `git ls-files`
+ * fails — the wiring linter degrades to "no aggregator required" in
+ * that case rather than crashing the whole stage check.
+ */
+async function readHeadFiles(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["ls-files", "-z"], { cwd: projectRoot, maxBuffer: 64 * 1024 * 1024 });
+        const out = new Set();
+        for (const segment of stdout.split("\u0000")) {
+            const trimmed = segment.trim();
+            if (trimmed.length === 0)
+                continue;
+            out.add(trimmed.replace(/\\/gu, "/"));
+        }
+        return out;
+    }
+    catch {
+        return new Set();
+    }
+}
+function buildSliceClaimGraph(waves) {
+    const bySliceId = new Map();
+    for (const wave of waves) {
+        for (const row of wave.rows) {
+            bySliceId.set(row.sliceId, row);
+        }
+    }
+    return { bySliceId };
+}
+/**
+ * Walk the dependsOn graph from `sliceId` and return the set of
+ * predecessor slice ids (transitive). Skips ids that aren't in the
+ * graph and handles cycles via a `visiting` set so a malformed plan
+ * doesn't lock the linter.
+ */
+function transitivePredecessors(sliceId, graph) {
+    const out = new Set();
+    const stack = [sliceId];
+    const visiting = new Set();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (visiting.has(current))
+            continue;
+        visiting.add(current);
+        const row = graph.bySliceId.get(current);
+        if (!row)
+            continue;
+        for (const predecessor of row.dependsOn) {
+            const normalized = parseSliceId(predecessor)?.id ?? predecessor;
+            if (out.has(normalized))
+                continue;
+            out.add(normalized);
+            stack.push(normalized);
+        }
+    }
+    return out;
+}
 export async function lintPlanStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
     evaluateInvestigationTrace(ctx, "Implementation Units");
@@ -600,7 +676,7 @@ export async function lintPlanStage(ctx) {
                 : `Serial slice(s) found without sequential wave mode hints in: ${inconsistentParallelizable.join(", ")}. Add a wave mode/note indicating sequential execution.`
         });
         const mermaidBlocks = raw.match(/```mermaid[\s\S]*?```/giu) ?? [];
-        const hasParallelExecMermaid = mermaidBlocks.some((block) => /(flowchart|gantt)/iu.test(block) && /\bW-\d+\b/iu.test(block) && /\bS-\d+\b/iu.test(block));
+        const hasParallelExecMermaid = mermaidBlocks.some((block) => /(flowchart|gantt)/iu.test(block) && /\bW-\d+\b/iu.test(block) && /\bS-\d+(?:[a-z][a-z0-9]*)?\b/iu.test(block));
         findings.push({
             section: "plan_parallel_exec_mermaid_present",
             required: false,
@@ -610,5 +686,68 @@ export async function lintPlanStage(ctx) {
                 ? "Mermaid visualization for parallel execution waves is present."
                 : "No mermaid parallel-execution visualization found (advisory). Add a ` ```mermaid ` flowchart or gantt with W-* and S-* nodes."
         });
+        // 7.6.0 — plan_module_introducing_slice_wires_root.
+        // Stack-aware: stack-adapter exposes a `wiringAggregator` contract
+        // for stacks where introducing a new module file requires a
+        // sibling aggregator update (Rust lib.rs, Python __init__.py,
+        // optional Node-TS index.ts). For each NEW path in a slice's
+        // claim, if the adapter says an aggregator is required, the
+        // aggregator path must appear in the slice's own claim or in any
+        // transitive predecessor's claim within the same flow.
+        //
+        // For unknown stacks (Go, Java, Ruby, Swift, .NET, Elixir, …)
+        // the adapter returns `wiringAggregator: undefined`, so this
+        // gate is a no-op and `found: true`.
+        const stackAdapter = await loadStackAdapter(projectRoot);
+        const headFiles = await readHeadFiles(projectRoot);
+        const wiringIssues = [];
+        if (stackAdapter.wiringAggregator) {
+            const claimGraph = buildSliceClaimGraph(waveMeta);
+            for (const wave of waveMeta) {
+                for (const row of [...wave.rows].sort((a, b) => compareSliceIds(a.sliceId, b.sliceId))) {
+                    const predecessors = transitivePredecessors(row.sliceId, claimGraph);
+                    const predecessorClaims = new Set();
+                    for (const predId of predecessors) {
+                        const predRow = claimGraph.bySliceId.get(predId);
+                        if (!predRow)
+                            continue;
+                        for (const claim of predRow.claimedPaths) {
+                            predecessorClaims.add(normalizePathToken(claim));
+                        }
+                    }
+                    const ownClaims = new Set(row.claimedPaths.map(normalizePathToken));
+                    for (const rawClaim of row.claimedPaths) {
+                        const claim = normalizePathToken(rawClaim);
+                        if (claim.length === 0)
+                            continue;
+                        // Only NEW paths (not present at HEAD) require an
+                        // aggregator update — existing modules are already wired.
+                        if (headFiles.size > 0 && headFiles.has(claim))
+                            continue;
+                        const required = stackAdapter.wiringAggregator.resolveAggregatorFor(claim, { headFiles });
+                        if (!required)
+                            continue;
+                        const aggregatorPath = normalizePathToken(required);
+                        if (ownClaims.has(aggregatorPath))
+                            continue;
+                        if (predecessorClaims.has(aggregatorPath))
+                            continue;
+                        wiringIssues.push(`${wave.waveId}/${row.sliceId} introduces ${claim} but wiring aggregator ${aggregatorPath} is not in its claim or any predecessor's claim`);
+                    }
+                }
+            }
+        }
+        const wiringApplies = stackAdapter.wiringAggregator !== undefined;
+        findings.push({
+            section: "plan_module_introducing_slice_wires_root",
+            required: taskListPresent && wiringApplies,
+            rule: "When a slice introduces a new module file, the stack-adapter's wiring aggregator (e.g. Rust `lib.rs`, Python `__init__.py`, Node-TS barrel `index.*` when present) must be in the same slice's claim or in a transitive predecessor's claim, otherwise the new module is dead code and RED can't be expressed.",
+            found: !wiringApplies || wiringIssues.length === 0,
+            details: !wiringApplies
+                ? `Stack adapter (id=${stackAdapter.id}) does not declare a wiring aggregator; gate is a no-op for this stack.`
+                : wiringIssues.length === 0
+                    ? `Stack adapter (id=${stackAdapter.id}) wiring aggregator coverage verified across all wave slices.`
+                    : `Wiring aggregator coverage gaps: ${wiringIssues.slice(0, 12).join(" | ")}${wiringIssues.length > 12 ? ` | … (${wiringIssues.length - 12} more)` : ""}.`
+        });
     }
 }

package/dist/artifact-linter/tdd.js

@@ -6,6 +6,7 @@ import { loadTddReadySlicePool, readDelegationLedger, readDelegationEvents, sele
 import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
 import { exists } from "../fs-utils.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "../internal/plan-split-waves.js";
+import { compareSliceIds } from "../util/slice-id.js";
 import { extractAcceptanceCriterionIdsFromMarkdown, extractH2Sections, evaluateInvestigationTrace, sectionBodyByName } from "./shared.js";
 const SLICE_SUMMARY_START = "<!-- auto-start: tdd-slice-summary -->";
 const SLICE_SUMMARY_END = "<!-- auto-end: tdd-slice-summary -->";
@@ -509,7 +510,7 @@ async function listSliceFiles(slicesDir) {
             continue;
         files.push({ sliceId: match[1], absPath: path.join(slicesDir, name) });
     }
-    files.sort((a, b) => (a.sliceId < b.sliceId ? -1 : a.sliceId > b.sliceId ? 1 : 0));
+    files.sort((a, b) => compareSliceIds(a.sliceId, b.sliceId));
     return files;
 }
 function escapeForRegex(value) {

package/dist/config.d.ts

@@ -1,9 +1,11 @@
-import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, TddCommitMode, TddIsolationMode } from "./types.js";
+import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack, LockfileTwinPolicy, TddCommitMode, TddIsolationMode } from "./types.js";
 export declare const TDD_COMMIT_MODES: readonly ["managed-per-slice", "agent-required", "checkpoint-only", "off"];
 export declare const DEFAULT_TDD_COMMIT_MODE: TddCommitMode;
 export declare const TDD_ISOLATION_MODES: readonly ["worktree", "in-place", "auto"];
 export declare const DEFAULT_TDD_ISOLATION_MODE: TddIsolationMode;
 export declare const DEFAULT_TDD_WORKTREE_ROOT = ".cclaw/worktrees";
+export declare const LOCKFILE_TWIN_POLICIES: readonly ["auto-include", "auto-revert", "strict-fence"];
+export declare const DEFAULT_LOCKFILE_TWIN_POLICY: LockfileTwinPolicy;
 export declare const DEFAULT_TDD_TEST_PATH_PATTERNS: readonly string[];
 export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
 export declare const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS: readonly string[];
@@ -24,6 +26,7 @@ export declare function createDefaultConfig(harnesses?: HarnessId[], _defaultTra
 export declare function resolveTddCommitMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddCommitMode;
 export declare function resolveTddIsolationMode(config: Pick<CclawConfig, "tdd"> | null | undefined): TddIsolationMode;
 export declare function resolveTddWorktreeRoot(config: Pick<CclawConfig, "tdd"> | null | undefined): string;
+export declare function resolveLockfileTwinPolicy(config: Pick<CclawConfig, "tdd"> | null | undefined): LockfileTwinPolicy;
 export declare function detectLanguageRulePacks(_projectRoot: string): Promise<LanguageRulePack[]>;
 export declare function readConfig(projectRoot: string, _options?: ReadConfigOptions): Promise<CclawConfig>;
 export interface WriteConfigOptions {

package/dist/config.js

@@ -20,6 +20,9 @@ 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";
 // Kept for runtime modules that use these defaults directly.
 export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
     "**/*.test.*",
@@ -68,7 +71,8 @@ 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
         }
     };
 }
@@ -93,6 +97,13 @@ 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;
+}
 function assertOnlySupportedKeys(parsed, fullPath) {
     const unknownKeys = Object.keys(parsed).filter((key) => !ALLOWED_CONFIG_KEYS.has(key));
     if (unknownKeys.length === 0)
@@ -153,6 +164,7 @@ export async function readConfig(projectRoot, _options = {}) {
     const rawCommitMode = parsedTdd.commitMode;
     const rawIsolationMode = parsedTdd.isolationMode;
     const rawWorktreeRoot = parsedTdd.worktreeRoot;
+    const rawLockfileTwinPolicy = parsedTdd.lockfileTwinPolicy;
     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 +177,10 @@ 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(", ")}`);
+    }
     const commitMode = typeof rawCommitMode === "string"
         ? rawCommitMode
         : DEFAULT_TDD_COMMIT_MODE;
@@ -174,6 +190,9 @@ 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;
     return {
         version,
         flowVersion,
@@ -181,7 +200,8 @@ export async function readConfig(projectRoot, _options = {}) {
         tdd: {
             commitMode,
             isolationMode,
-            worktreeRoot
+            worktreeRoot,
+            lockfileTwinPolicy
         }
     };
 }
@@ -193,7 +213,8 @@ export async function writeConfig(projectRoot, config, _options = {}) {
         tdd: {
             commitMode: resolveTddCommitMode(config),
             isolationMode: resolveTddIsolationMode(config),
-            worktreeRoot: resolveTddWorktreeRoot(config)
+            worktreeRoot: resolveTddWorktreeRoot(config),
+            lockfileTwinPolicy: resolveLockfileTwinPolicy(config)
         }
     };
     await writeFileSafe(configPath(projectRoot), stringify(serialisable));

package/dist/content/core-agents.js

@@ -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.",

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/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) => [

package/dist/content/stages/plan.js

@@ -85,6 +85,7 @@ export const PLAN = {
             { 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_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: [

package/dist/delegation.d.ts

@@ -381,6 +381,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

package/dist/delegation.js

@@ -9,6 +9,7 @@ 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 = [
@@ -700,6 +701,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 +909,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;
@@ -1183,6 +1247,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 &&

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

package/dist/internal/cohesion-contract-stub.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
 import { writeFileSafe } from "../fs-utils.js";
 import { readDelegationLedger, isParallelTddSliceWorker } from "../delegation.js";
+import { compareSliceIds } from "../util/slice-id.js";
 export function parseCohesionContractArgs(tokens) {
     const args = { stub: false, force: false, reason: null };
     for (const token of tokens) {
@@ -143,18 +144,5 @@ function collectSliceIds(entries) {
             continue;
         set.add(entry.sliceId);
     }
-    return [...set].sort((a, b) => {
-        const an = parseSliceNum(a);
-        const bn = parseSliceNum(b);
-        if (an !== null && bn !== null)
-            return an - bn;
-        return a.localeCompare(b);
-    });
-}
-function parseSliceNum(sliceId) {
-    const m = /^S-(\d+)$/u.exec(sliceId);
-    if (!m)
-        return null;
-    const n = Number.parseInt(m[1], 10);
-    return Number.isFinite(n) ? n : null;
+    return [...set].sort(compareSliceIds);
 }