cclaw-cli 7.4.0 → 7.6.0

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);
 }

package/dist/internal/plan-split-waves.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { resolveArtifactPath } from "../artifact-paths.js";
 import { exists, writeFileSafe } from "../fs-utils.js";
 import { readFlowState } from "../runs.js";
+import { compareSliceIds, parseSliceId } from "../util/slice-id.js";
 export const PLAN_SPLIT_DEFAULT_WAVE_SIZE = 5;
 export const PLAN_SPLIT_SMALL_PLAN_THRESHOLD = 50;
 const WAVE_PLANS_DIR = "wave-plans";
@@ -34,15 +35,17 @@ export function extractParallelExecutionManagedBody(planMarkdown) {
 }
 function tokenToSliceAndUnit(token) {
     const t = token.trim().replace(/^[`"'[\]()]+|[`"'[\]()]+$/gu, "");
-    const u = /^U-(\d+)$/u.exec(t);
+    const u = /^U-(\d+)([a-z][a-z0-9]*)?$/iu.exec(t);
     if (u) {
-        const n = u[1];
-        return { unitId: `U-${n}`, sliceId: `S-${n}` };
+        const num = u[1];
+        const suffix = (u[2] ?? "").toLowerCase();
+        const tail = suffix.length > 0 ? `${num}${suffix}` : num;
+        return { unitId: `U-${tail}`, sliceId: `S-${tail}` };
     }
-    const s = /^S-(\d+)$/u.exec(t);
-    if (s) {
-        const n = s[1];
-        return { unitId: `U-${n}`, sliceId: `S-${n}` };
+    const parsed = parseSliceId(t);
+    if (parsed) {
+        const tail = parsed.suffix.length > 0 ? `${parsed.numeric}${parsed.suffix}` : `${parsed.numeric}`;
+        return { unitId: `U-${tail}`, sliceId: parsed.id };
     }
     return null;
 }
@@ -90,12 +93,14 @@ export function parseTableRowMember(trimmedLine) {
         return null;
     const stripDecorations = (raw) => raw.replace(/^[`"'[\]()]+|[`"'[\]()]+$/gu, "").trim();
     const col1 = stripDecorations(cells[0]);
-    const sliceMatch = /^S-(\d+)$/u.exec(col1);
-    if (!sliceMatch)
+    const parsedSlice = parseSliceId(col1);
+    if (!parsedSlice)
         return null;
-    const sliceNum = sliceMatch[1];
-    const sliceId = `S-${sliceNum}`;
-    let unitId = `U-${sliceNum}`;
+    const sliceTail = parsedSlice.suffix.length > 0
+        ? `${parsedSlice.numeric}${parsedSlice.suffix}`
+        : `${parsedSlice.numeric}`;
+    const sliceId = parsedSlice.id;
+    let unitId = `U-${sliceTail}`;
     if (cells.length >= 2) {
         const col2 = stripDecorations(cells[1]);
         if (col2.length > 0) {
@@ -235,7 +240,7 @@ export function parseWavePlanFileBody(body, waveId) {
         }
     }
     if (members.length === 0) {
-        const regex = /\b(S-\d+)\b/gu;
+        const regex = /\b(S-\d+(?:[a-z][a-z0-9]*)?)\b/giu;
         let match;
         while ((match = regex.exec(body)) !== null) {
             const ids = tokenToSliceAndUnit(match[1]);
@@ -307,7 +312,7 @@ export function mergeParallelWaveDefinitions(primary, secondary) {
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([wid, memMap]) => ({
         waveId: wid,
-        members: [...memMap.values()].sort((p, q) => p.sliceId.localeCompare(q.sliceId))
+        members: [...memMap.values()].sort((p, q) => compareSliceIds(p.sliceId, q.sliceId))
     }));
 }
 /**

package/dist/internal/slice-commit.js

@@ -1,9 +1,10 @@
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
-import { readConfig, resolveTddCommitMode, resolveTddIsolationMode, resolveTddWorktreeRoot } from "../config.js";
+import { readConfig, resolveLockfileTwinPolicy, resolveTddCommitMode, resolveTddIsolationMode, resolveTddWorktreeRoot } from "../config.js";
 import { readDelegationLedger } from "../delegation.js";
 import { exists } from "../fs-utils.js";
+import { loadStackAdapter } from "../stack-detection.js";
 import { cleanupWorktree, commitAndMergeBack, createSliceWorktree, WorktreeMergeConflictError, WorktreeUnsupportedError } from "../worktree-manager.js";
 const execFileAsync = promisify(execFile);
 function parseCsv(raw) {
@@ -165,6 +166,71 @@ function matchesClaimedPath(changedPath, claimedPaths) {
         return changed.startsWith(`${claimed}/`);
     });
 }
+/**
+ * 7.6.0 — match a candidate path against a stack-adapter glob pattern.
+ *
+ * Adapter globs are intentionally simple: literal paths (`Cargo.toml`),
+ * recursive prefix (`**\/Cargo.toml`), or single-level wildcard
+ * (`*.csproj`). We translate those shapes here without pulling in a
+ * full glob library so the slice-commit hook stays dependency-light.
+ */
+function matchesAdapterGlob(candidate, glob) {
+    const normalizedCandidate = normalizePathLike(candidate);
+    const normalizedGlob = normalizePathLike(glob);
+    if (normalizedGlob.length === 0)
+        return false;
+    if (normalizedGlob.includes("**")) {
+        // `**/foo` → match either `foo` at root or any nested `foo`.
+        if (normalizedGlob.startsWith("**/")) {
+            const tail = normalizedGlob.slice(3);
+            if (tail === normalizedCandidate)
+                return true;
+            return normalizedCandidate.endsWith(`/${tail}`);
+        }
+        // Generic ** in the middle: collapse to suffix match for simplicity.
+        const tail = normalizedGlob.split("**/").pop() ?? "";
+        return tail.length > 0 && normalizedCandidate.endsWith(tail);
+    }
+    if (normalizedGlob.includes("*")) {
+        // Single-segment wildcard like `*.csproj`. Convert to a basic regex.
+        const regexSrc = normalizedGlob
+            .split("/")
+            .map((segment) => segment
+            .replace(/[.+?^${}()|[\]\\]/gu, "\\$&")
+            .replace(/\*/gu, "[^/]*"))
+            .join("/");
+        return new RegExp(`^${regexSrc}$`, "u").test(normalizedCandidate);
+    }
+    return normalizedGlob === normalizedCandidate;
+}
+/**
+ * Find lockfile twins whose manifestGlob matches at least one claimed
+ * path. The returned twins are the candidates whose lockfileGlob we
+ * should auto-include / auto-revert when they drift.
+ */
+function activeLockfileTwins(adapter, claimedPaths) {
+    if (adapter.lockfileTwins.length === 0)
+        return [];
+    const active = [];
+    for (const twin of adapter.lockfileTwins) {
+        const claimedManifest = claimedPaths.some((claimed) => matchesAdapterGlob(claimed, twin.manifestGlob));
+        if (claimedManifest)
+            active.push(twin);
+    }
+    return active;
+}
+/**
+ * Partition a candidate path: `is it a lockfile twin we should
+ * auto-handle?`. Returns the twin entry that matches, or null.
+ */
+function findMatchingLockfileTwin(changedPath, twins) {
+    for (const twin of twins) {
+        if (matchesAdapterGlob(changedPath, twin.lockfileGlob)) {
+            return twin;
+        }
+    }
+    return null;
+}
 async function resolveClaimedPathsFromLedger(projectRoot, args) {
     const ledger = await readDelegationLedger(projectRoot);
     const matches = ledger.entries.filter((entry) => entry.stage === "tdd" &&
@@ -195,6 +261,8 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
     const commitMode = resolveTddCommitMode(config);
     const isolationMode = resolveTddIsolationMode(config);
     const worktreeRoot = resolveTddWorktreeRoot(config);
+    const lockfileTwinPolicy = resolveLockfileTwinPolicy(config);
+    const stackAdapter = await loadStackAdapter(projectRoot);
     const gitPresent = await exists(path.join(projectRoot, ".git"));
     if (args.prepareWorktree) {
         if (!gitPresent) {
@@ -354,8 +422,41 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         });
         return 0;
     }
-    const pathDrift = changedPaths.filter((p) => !matchesClaimedPath(p, claimedPaths));
-    if (pathDrift.length > 0) {
+    const initialDrift = changedPaths.filter((p) => !matchesClaimedPath(p, claimedPaths));
+    const twinsForCommit = activeLockfileTwins(stackAdapter, claimedPaths);
+    // 7.6.0 — split drift into "lockfile twin drift" (handle per policy)
+    // vs "true drift" (always rejected).
+    const lockfileTwinDrift = [];
+    const trueDrift = [];
+    for (const driftPath of initialDrift) {
+        const twin = findMatchingLockfileTwin(driftPath, twinsForCommit);
+        if (twin) {
+            lockfileTwinDrift.push({ path: driftPath, twin });
+        }
+        else {
+            trueDrift.push(driftPath);
+        }
+    }
+    // Report a separate true-drift error when there is actual non-twin
+    // drift, regardless of policy: the operator's claim should still
+    // cover everything they changed.
+    if (trueDrift.length > 0) {
+        output(io, args, {
+            ok: false,
+            errorCode: "slice_commit_path_drift",
+            details: {
+                sliceId: args.sliceId,
+                spanId: args.spanId,
+                claimedPaths,
+                driftPaths: trueDrift
+            },
+            message: `slice_commit_path_drift: ${trueDrift.join(", ")}`
+        }, "stderr");
+        return 2;
+    }
+    // strict-fence: lockfile twins still count as drift.
+    if (lockfileTwinDrift.length > 0 && lockfileTwinPolicy === "strict-fence") {
+        const driftPaths = lockfileTwinDrift.map((entry) => entry.path);
         output(io, args, {
             ok: false,
             errorCode: "slice_commit_path_drift",
@@ -363,13 +464,62 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
                 sliceId: args.sliceId,
                 spanId: args.spanId,
                 claimedPaths,
-                driftPaths: pathDrift
+                driftPaths,
+                lockfileTwinPolicy,
+                stackAdapterId: stackAdapter.id
             },
-            message: `slice_commit_path_drift: ${pathDrift.join(", ")}`
+            message: `slice_commit_path_drift: ${driftPaths.join(", ")} (lockfileTwinPolicy=strict-fence)`
         }, "stderr");
         return 2;
     }
-    const changedInClaim = changedPaths.filter((p) => matchesClaimedPath(p, claimedPaths));
+    // auto-revert: restore the lockfile, then exclude from changed set.
+    const revertedTwinPaths = [];
+    if (lockfileTwinDrift.length > 0 && lockfileTwinPolicy === "auto-revert") {
+        for (const entry of lockfileTwinDrift) {
+            try {
+                await execFileAsync("git", ["restore", "--", entry.path], { cwd: activeCwd });
+                revertedTwinPaths.push(entry.path);
+            }
+            catch {
+                // Fall through; if restore fails the drift will reappear in the
+                // recomputed status and we'll reject as drift.
+            }
+        }
+        changedPaths = await gitChangedPaths(activeCwd);
+        const remainingDrift = changedPaths.filter((p) => !matchesClaimedPath(p, claimedPaths));
+        if (remainingDrift.length > 0) {
+            output(io, args, {
+                ok: false,
+                errorCode: "slice_commit_path_drift",
+                details: {
+                    sliceId: args.sliceId,
+                    spanId: args.spanId,
+                    claimedPaths,
+                    driftPaths: remainingDrift,
+                    lockfileTwinPolicy,
+                    stackAdapterId: stackAdapter.id
+                },
+                message: `slice_commit_path_drift: ${remainingDrift.join(", ")}`
+            }, "stderr");
+            return 2;
+        }
+    }
+    // auto-include: add the twin path(s) to the effective claim so the
+    // commit picks them up. We don't mutate the persisted claim — only
+    // the in-memory list used for the upcoming `git add`.
+    const effectiveCommitPaths = [...claimedPaths];
+    const includedTwinPaths = [];
+    if (lockfileTwinDrift.length > 0 && lockfileTwinPolicy === "auto-include") {
+        for (const entry of lockfileTwinDrift) {
+            if (!effectiveCommitPaths.includes(entry.path)) {
+                effectiveCommitPaths.push(entry.path);
+            }
+            includedTwinPaths.push(entry.path);
+        }
+    }
+    const changedInClaim = changedPaths.filter((p) => matchesClaimedPath(p, claimedPaths) ||
+        (lockfileTwinPolicy === "auto-include" &&
+            findMatchingLockfileTwin(p, twinsForCommit) !== null));
     if (changedInClaim.length === 0) {
         await cleanupManagedWorktree();
         output(io, args, {
@@ -381,7 +531,7 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         return 0;
     }
     try {
-        await execFileAsync("git", ["add", "--", ...claimedPaths], {
+        await execFileAsync("git", ["add", "--", ...effectiveCommitPaths], {
             cwd: activeCwd
         });
         const taskPart = args.taskId && args.taskId.length > 0 ? args.taskId : "task";
@@ -459,6 +609,10 @@ export async function runSliceCommitCommand(projectRoot, tokens, io) {
         changedPaths: changedInClaim,
         worktreePath: managedWorktreePath ?? undefined,
         degradedToInPlace: degradedToInPlace || undefined,
+        lockfileTwinPolicy,
+        lockfileTwinsIncluded: includedTwinPaths.length > 0 ? includedTwinPaths : undefined,
+        lockfileTwinsReverted: revertedTwinPaths.length > 0 ? revertedTwinPaths : undefined,
+        stackAdapterId: stackAdapter.id,
         message: `slice commit created for ${args.sliceId}: ${commitSha}`
     });
     return 0;

package/dist/internal/wave-status.js

@@ -5,6 +5,7 @@ import { readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { readFlowState } from "../runs.js";
 import { DEFAULT_SLICE_STREAM_REL_PATH, readEventStreamFile } from "../streaming/event-stream.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./plan-split-waves.js";
+import { compareSliceIds, parseSliceId } from "../util/slice-id.js";
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 function parseArgs(tokens) {
@@ -94,9 +95,10 @@ function parseManagedWaveClaimedPaths(planMarkdown) {
         if (cells.every((cell) => /^:?-{3,}:?$/u.test(cell))) {
             continue;
         }
-        const sliceId = cells[0].trim().toUpperCase();
-        if (!/^S-\d+$/u.test(sliceId))
+        const parsedSlice = parseSliceId(cells[0]);
+        if (!parsedSlice)
             continue;
+        const sliceId = parsedSlice.id;
         const pathsIdx = headerIdx.get("claimedpaths");
         const rawPaths = pathsIdx !== undefined ? (cells[pathsIdx] ?? "") : "";
         const claimedPaths = rawPaths.length === 0
@@ -111,7 +113,7 @@ function parseManagedWaveClaimedPaths(planMarkdown) {
 }
 function detectPathConflicts(readySlices, bySlice) {
     const conflicts = new Set();
-    const ordered = [...readySlices].sort();
+    const ordered = [...readySlices].sort(compareSliceIds);
     for (let i = 0; i < ordered.length; i += 1) {
         const leftSlice = ordered[i];
         const leftPaths = bySlice.get(leftSlice) ?? [];
@@ -338,7 +340,7 @@ export async function runWaveStatus(projectRoot, options = {}) {
         };
     }
     else {
-        const readyToDispatch = [...firstOpenWave.readyMembers].sort();
+        const readyToDispatch = [...firstOpenWave.readyMembers].sort(compareSliceIds);
         const claimedPathsByWave = parseManagedWaveClaimedPaths(planRaw);
         const conflicts = detectPathConflicts(readyToDispatch, claimedPathsByWave.get(firstOpenWave.waveId) ?? new Map());
         const mode = conflicts.length > 0

package/dist/stack-detection.d.ts

@@ -20,3 +20,97 @@ export declare const STACK_DISCOVERY_MARKERS: readonly string[];
  * Directory markers (checked with pathExists) for stack discovery.
  */
 export declare const STACK_DISCOVERY_DIR_MARKERS: readonly string[];
+export type StackAdapterId = "rust" | "node" | "python" | "go" | "ruby" | "php" | "swift" | "dotnet" | "elixir" | "java" | "unknown";
+/** Twin describing manifest → lockfile coupling for a stack. */
+export interface ManifestLockfileTwin {
+    /** Manifest glob (path relative to repo root). */
+    manifestGlob: string;
+    /** Lockfile glob that the manifest's package manager regenerates. */
+    lockfileGlob: string;
+}
+/**
+ * Wiring-aggregator contract — describes whether a new file in a stack
+ * needs an explicit aggregator/parent module update for the new module to
+ * be reachable from the rest of the project.
+ *
+ * - `aggregatorPattern` is a human-facing description; consumers should
+ *   call `resolveAggregatorFor(filePath, repoState?)` to compute the
+ *   concrete aggregator path.
+ * - `resolveAggregatorFor` returns the concrete repo-relative path of
+ *   the aggregator file required to wire `filePath`, or `null` when no
+ *   aggregator is required (e.g. file IS the aggregator, or the stack
+ *   layout makes wiring implicit).
+ * - `repoState.headFiles` lets the resolver check whether sibling
+ *   aggregators already exist (so e.g. node-ts only requires
+ *   `index.ts` updates when an `index.ts` already exists in that
+ *   directory).
+ */
+export interface WiringAggregatorContract {
+    aggregatorPattern: string;
+    /**
+     * Resolve the aggregator path required to wire `filePath` into its
+     * parent module, given a snapshot of repo state. Return `null` when
+     * no aggregator update is required.
+     */
+    resolveAggregatorFor(filePath: string, repoState?: {
+        headFiles?: ReadonlySet<string>;
+    }): string | null;
+}
+/**
+ * Universal stack-adapter contract used by hooks (slice-commit lockfile
+ * twins), linters (`plan_module_introducing_slice_wires_root`), and
+ * future stack-specific evidence validators.
+ *
+ * Each stack returns:
+ * - `id` — short stable identifier; routes used elsewhere should match.
+ * - `displayName` — used in user-facing prose so error messages stay
+ *   stack-agnostic at the surface ("Rust workspace" vs "Node project"
+ *   are forbidden in generic code; use `adapter.displayName` instead).
+ * - `manifestGlobs` — repo-relative manifest paths the stack uses.
+ * - `lockfileTwins` — manifest→lockfile twin entries; auto-detected
+ *   from disk at adapter init so node projects with yarn.lock get
+ *   `yarn.lock`, pnpm gets `pnpm-lock.yaml`, etc.
+ * - `testCommandHints` — example test command lines for prompts and
+ *   evidence validators (advisory; not authoritative).
+ * - `wiringAggregator` — see contract above. `undefined` when the
+ *   stack has no aggregator pattern (Go, Java, Ruby, Swift, .NET,
+ *   Elixir use implicit/automatic wiring).
+ */
+export interface StackAdapter {
+    id: StackAdapterId;
+    displayName: string;
+    manifestGlobs: string[];
+    lockfileTwins: ManifestLockfileTwin[];
+    testCommandHints: string[];
+    wiringAggregator?: WiringAggregatorContract;
+}
+interface LoadStackAdapterOptions {
+    /**
+     * Override the project root for tests. Defaults to the supplied
+     * argument; primarily here so callers can inject a synthesized
+     * directory in fixtures.
+     */
+    projectRoot?: string;
+}
+/**
+ * Load the stack-adapter for a project. Walks the registered factories
+ * in order; the first detector that returns true wins. Returns the
+ * `unknown` adapter (no-op) when no detector matches.
+ *
+ * Adapter init reads the filesystem to auto-detect lockfile twins
+ * (e.g. yarn.lock vs package-lock.json). Callers should cache the
+ * adapter for the lifetime of the operation rather than calling this
+ * per-row.
+ */
+export declare function loadStackAdapter(projectRoot: string, options?: LoadStackAdapterOptions): Promise<StackAdapter>;
+/**
+ * Synthesize a stack adapter from explicit lockfile-twin overrides.
+ * Useful in tests that want to pin twins without a real filesystem
+ * scan, and for the linter test suite.
+ */
+export declare function buildStackAdapterForTests(partial: Partial<StackAdapter> & {
+    id: StackAdapterId;
+    displayName: string;
+}): StackAdapter;
+export declare const UNKNOWN_STACK: StackAdapter;
+export {};