cclaw-cli 7.5.0 → 7.7.0

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.d.ts

@@ -64,8 +64,11 @@ export declare function extractMembersListFromLine(trimmedLine: string): string
  *
  * Rules:
  * - The line must start with `|` (after trimming).
- * - Column 1 (after stripping markdown noise) must match `^S-(\d+)$` —
- *   header rows (`| sliceId | …`) and separator rows (`|---|---|…`) are
+ * - Column 1 (after stripping markdown noise) may be either a slice id
+ *   (`S-N`) or an implementation-unit id (`U-N`). Unit ids derive their
+ *   execution slice as `S-N`, which lets 7.7+ plans schedule feature-atomic
+ *   units without inventing a tiny `T-NNN` row per dispatch lane. Header rows
+ *   (`| sliceId | …`, `| unit | …`) and separator rows (`|---|---|…`) are
  *   silently skipped.
  * - Column 2, when present and non-empty, becomes the `unitId`
  *   verbatim (after stripping whitespace + backticks/quotes/brackets).

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;
 }
@@ -68,8 +71,11 @@ export function extractMembersListFromLine(trimmedLine) {
  *
  * Rules:
  * - The line must start with `|` (after trimming).
- * - Column 1 (after stripping markdown noise) must match `^S-(\d+)$` —
- *   header rows (`| sliceId | …`) and separator rows (`|---|---|…`) are
+ * - Column 1 (after stripping markdown noise) may be either a slice id
+ *   (`S-N`) or an implementation-unit id (`U-N`). Unit ids derive their
+ *   execution slice as `S-N`, which lets 7.7+ plans schedule feature-atomic
+ *   units without inventing a tiny `T-NNN` row per dispatch lane. Header rows
+ *   (`| sliceId | …`, `| unit | …`) and separator rows (`|---|---|…`) are
  *   silently skipped.
  * - Column 2, when present and non-empty, becomes the `unitId`
  *   verbatim (after stripping whitespace + backticks/quotes/brackets).
@@ -90,12 +96,17 @@ 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);
+    const parsedUnit = tokenToSliceAndUnit(col1);
+    if (!parsedSlice && !parsedUnit)
         return null;
-    const sliceNum = sliceMatch[1];
-    const sliceId = `S-${sliceNum}`;
-    let unitId = `U-${sliceNum}`;
+    const sliceTail = parsedSlice
+        ? parsedSlice.suffix.length > 0
+            ? `${parsedSlice.numeric}${parsedSlice.suffix}`
+            : `${parsedSlice.numeric}`
+        : "";
+    const sliceId = parsedSlice ? parsedSlice.id : parsedUnit.sliceId;
+    let unitId = parsedSlice ? `U-${sliceTail}` : parsedUnit.unitId;
     if (cells.length >= 2) {
         const col2 = stripDecorations(cells[1]);
         if (col2.length > 0) {
@@ -235,7 +246,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 +318,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.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from "node:stream";
+import type { ExecutionTopology } from "../types.js";
 interface InternalIo {
     stdout: Writable;
     stderr: Writable;
@@ -17,6 +18,9 @@ export interface WaveStatusNextDispatch {
     readyToDispatch: string[];
     pathConflicts: string[];
     mode: "single-slice" | "wave-fanout" | "blocked" | "none";
+    topology: Exclude<ExecutionTopology, "auto"> | "none";
+    topologyReason: string;
+    maxBuilders: number;
 }
 export interface WaveStatusReport {
     activeRunId: string;

package/dist/internal/wave-status.js

@@ -4,7 +4,10 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { readFlowState } from "../runs.js";
 import { DEFAULT_SLICE_STREAM_REL_PATH, readEventStreamFile } from "../streaming/event-stream.js";
+import { readConfig, resolveExecutionStrictness, resolveExecutionTopology, resolveMaxBuilders } from "../config.js";
+import { routeExecutionTopology } from "../execution-topology.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) {
@@ -81,7 +84,11 @@ function parseManagedWaveClaimedPaths(planMarkdown) {
         if (cells.length === 0)
             continue;
         const first = cells[0].toLowerCase();
-        if (first === "sliceid" || first === "slice id") {
+        if (first === "sliceid" ||
+            first === "slice id" ||
+            first === "unitid" ||
+            first === "unit id" ||
+            first === "unit") {
             headerIdx = new Map();
             for (let i = 0; i < cells.length; i += 1) {
                 const key = cells[i].toLowerCase().replace(/[^a-z0-9]/gu, "");
@@ -94,9 +101,12 @@ 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 firstCell = (cells[0] ?? "").replace(/^`|`$/gu, "").trim();
+        const parsedSlice = parseSliceId(firstCell);
+        const parsedUnit = /^U-(\d+(?:[a-z][a-z0-9]*)?)$/iu.exec(firstCell);
+        if (!parsedSlice && !parsedUnit)
             continue;
+        const sliceId = parsedSlice?.id ?? `S-${parsedUnit[1].toLowerCase()}`;
         const pathsIdx = headerIdx.get("claimedpaths");
         const rawPaths = pathsIdx !== undefined ? (cells[pathsIdx] ?? "") : "";
         const claimedPaths = rawPaths.length === 0
@@ -111,7 +121,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) ?? [];
@@ -173,7 +183,10 @@ export async function runWaveStatus(projectRoot, options = {}) {
                 waveId: null,
                 readyToDispatch: [],
                 pathConflicts: [],
-                mode: "none"
+                mode: "none",
+                topology: "none",
+                topologyReason: "wave plan could not be parsed",
+                maxBuilders: 0
             },
             warnings: [
                 `wave_plan_parse_error: ${err instanceof Error ? err.message : String(err)}`
@@ -201,7 +214,10 @@ export async function runWaveStatus(projectRoot, options = {}) {
                 waveId: null,
                 readyToDispatch: [],
                 pathConflicts: [],
-                mode: "none"
+                mode: "none",
+                topology: "none",
+                topologyReason: "wave plan sources conflict",
+                maxBuilders: 0
             },
             warnings: [
                 `wave_plan_merge_conflict: ${err instanceof Error ? err.message : String(err)}`
@@ -329,16 +345,23 @@ export async function runWaveStatus(projectRoot, options = {}) {
         warnings.push("wave_plan_managed_block_missing: <!-- parallel-exec-managed-start --> block not found in 05-plan.md and wave-plans/ has no parseable wave files.");
     }
     let nextDispatch;
+    const config = await readConfig(projectRoot).catch(() => null);
+    const configuredTopology = resolveExecutionTopology(config);
+    const strictness = resolveExecutionStrictness(config);
+    const maxBuilders = resolveMaxBuilders(config);
     if (firstOpenWave === null) {
         nextDispatch = {
             waveId: null,
             readyToDispatch: [],
             pathConflicts: [],
-            mode: "none"
+            mode: "none",
+            topology: "none",
+            topologyReason: "no open wave has ready units",
+            maxBuilders
         };
     }
     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
@@ -348,11 +371,28 @@ export async function runWaveStatus(projectRoot, options = {}) {
                 : readyToDispatch.length === 1
                     ? "single-slice"
                     : "none";
+        const topologyDecision = mode === "none"
+            ? null
+            : routeExecutionTopology({
+                configuredTopology,
+                strictness,
+                maxBuilders,
+                shape: {
+                    unitCount: readyToDispatch.length,
+                    independentUnitCount: conflicts.length > 0 ? 0 : readyToDispatch.length,
+                    substantialUnitCount: readyToDispatch.length,
+                    hasPathConflicts: conflicts.length > 0,
+                    inlineSafe: false
+                }
+            });
         nextDispatch = {
             waveId: firstOpenWave.waveId,
             readyToDispatch,
             pathConflicts: conflicts,
-            mode
+            mode,
+            topology: topologyDecision?.topology ?? "none",
+            topologyReason: topologyDecision?.reason ?? "no ready units",
+            maxBuilders: topologyDecision?.maxBuilders ?? maxBuilders
         };
     }
     return {
@@ -380,6 +420,7 @@ function formatHumanReport(report) {
     }
     lines.push(`nextDispatch: wave=${report.nextDispatch.waveId ?? "(none)"} ` +
         `mode=${report.nextDispatch.mode} ` +
+        `topology=${report.nextDispatch.topology} ` +
         `ready=[${report.nextDispatch.readyToDispatch.join(",")}]`);
     if (report.warnings.length > 0) {
         lines.push("warnings:");

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