cclaw-cli 7.5.0 → 7.7.0

package/dist/stack-detection.js

@@ -1,3 +1,5 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 export const STACK_REVIEW_ROUTE_PROFILES = [
     {
         stack: "TypeScript/JavaScript",
@@ -56,3 +58,432 @@ export const STACK_DISCOVERY_MARKERS = [
 export const STACK_DISCOVERY_DIR_MARKERS = [
     ".github/workflows"
 ];
+const STACK_ADAPTER_FACTORIES = [
+    {
+        id: "rust",
+        displayName: "Rust",
+        async detect({ fileExists }) {
+            return await fileExists("Cargo.toml");
+        },
+        async build() {
+            return {
+                id: "rust",
+                displayName: "Rust",
+                manifestGlobs: ["Cargo.toml", "**/Cargo.toml"],
+                lockfileTwins: [
+                    { manifestGlob: "Cargo.toml", lockfileGlob: "Cargo.lock" }
+                ],
+                testCommandHints: ["cargo test", "cargo nextest run"],
+                wiringAggregator: rustWiringAggregator()
+            };
+        }
+    },
+    {
+        id: "node",
+        displayName: "Node/TypeScript",
+        async detect({ fileExists }) {
+            return await fileExists("package.json");
+        },
+        async build({ fileExists }) {
+            const lockfileTwins = [];
+            const candidates = [
+                { manifestGlob: "package.json", lockfileGlob: "package-lock.json" },
+                { manifestGlob: "package.json", lockfileGlob: "yarn.lock" },
+                { manifestGlob: "package.json", lockfileGlob: "pnpm-lock.yaml" }
+            ];
+            let detectedAny = false;
+            for (const candidate of candidates) {
+                if (await fileExists(candidate.lockfileGlob)) {
+                    lockfileTwins.push(candidate);
+                    detectedAny = true;
+                }
+            }
+            // Conservative default when no lockfile is on disk: assume npm.
+            // Slice-commit uses lockfileTwins to know which file to auto-include
+            // when the manifest is in claim and the lockfile drifted; a stale
+            // npm-style guess is harmless on a yarn project because we only
+            // act on actual on-disk drift.
+            if (!detectedAny) {
+                lockfileTwins.push({
+                    manifestGlob: "package.json",
+                    lockfileGlob: "package-lock.json"
+                });
+            }
+            return {
+                id: "node",
+                displayName: "Node/TypeScript",
+                manifestGlobs: ["package.json", "**/package.json"],
+                lockfileTwins,
+                testCommandHints: [
+                    "npm test",
+                    "pnpm test",
+                    "yarn test",
+                    "npx vitest run",
+                    "npx jest"
+                ],
+                wiringAggregator: nodeTsWiringAggregator()
+            };
+        }
+    },
+    {
+        id: "python",
+        displayName: "Python",
+        async detect({ fileExists }) {
+            return ((await fileExists("pyproject.toml")) ||
+                (await fileExists("requirements.txt")) ||
+                (await fileExists("Pipfile")) ||
+                (await fileExists("setup.py")));
+        },
+        async build({ fileExists }) {
+            const lockfileTwins = [];
+            const pyprojectCandidates = [
+                { manifestGlob: "pyproject.toml", lockfileGlob: "poetry.lock" },
+                { manifestGlob: "pyproject.toml", lockfileGlob: "uv.lock" },
+                { manifestGlob: "pyproject.toml", lockfileGlob: "pdm.lock" }
+            ];
+            let pyprojectAny = false;
+            if (await fileExists("pyproject.toml")) {
+                for (const candidate of pyprojectCandidates) {
+                    if (await fileExists(candidate.lockfileGlob)) {
+                        lockfileTwins.push(candidate);
+                        pyprojectAny = true;
+                    }
+                }
+                if (!pyprojectAny) {
+                    // Default guess for projects that don't yet have a lockfile.
+                    lockfileTwins.push({
+                        manifestGlob: "pyproject.toml",
+                        lockfileGlob: "poetry.lock"
+                    });
+                }
+            }
+            if (await fileExists("Pipfile")) {
+                lockfileTwins.push({ manifestGlob: "Pipfile", lockfileGlob: "Pipfile.lock" });
+            }
+            return {
+                id: "python",
+                displayName: "Python",
+                manifestGlobs: [
+                    "pyproject.toml",
+                    "Pipfile",
+                    "requirements.txt",
+                    "requirements-dev.txt",
+                    "setup.py",
+                    "setup.cfg"
+                ],
+                lockfileTwins,
+                testCommandHints: ["pytest", "python -m pytest", "python -m unittest"],
+                wiringAggregator: pythonWiringAggregator()
+            };
+        }
+    },
+    {
+        id: "go",
+        displayName: "Go",
+        async detect({ fileExists }) {
+            return await fileExists("go.mod");
+        },
+        async build() {
+            return {
+                id: "go",
+                displayName: "Go",
+                manifestGlobs: ["go.mod", "**/go.mod"],
+                lockfileTwins: [
+                    { manifestGlob: "go.mod", lockfileGlob: "go.sum" }
+                ],
+                testCommandHints: ["go test ./...", "go test"]
+            };
+        }
+    },
+    {
+        id: "ruby",
+        displayName: "Ruby",
+        async detect({ fileExists }) {
+            return await fileExists("Gemfile");
+        },
+        async build() {
+            return {
+                id: "ruby",
+                displayName: "Ruby",
+                manifestGlobs: ["Gemfile", "**/Gemfile"],
+                lockfileTwins: [
+                    { manifestGlob: "Gemfile", lockfileGlob: "Gemfile.lock" }
+                ],
+                testCommandHints: ["bundle exec rspec", "bundle exec rake test"]
+            };
+        }
+    },
+    {
+        id: "php",
+        displayName: "PHP",
+        async detect({ fileExists }) {
+            return await fileExists("composer.json");
+        },
+        async build() {
+            return {
+                id: "php",
+                displayName: "PHP",
+                manifestGlobs: ["composer.json", "**/composer.json"],
+                lockfileTwins: [
+                    { manifestGlob: "composer.json", lockfileGlob: "composer.lock" }
+                ],
+                testCommandHints: ["composer test", "vendor/bin/phpunit"]
+            };
+        }
+    },
+    {
+        id: "swift",
+        displayName: "Swift",
+        async detect({ fileExists }) {
+            return await fileExists("Package.swift");
+        },
+        async build() {
+            return {
+                id: "swift",
+                displayName: "Swift",
+                manifestGlobs: ["Package.swift", "**/Package.swift"],
+                lockfileTwins: [
+                    { manifestGlob: "Package.swift", lockfileGlob: "Package.resolved" }
+                ],
+                testCommandHints: ["swift test"]
+            };
+        }
+    },
+    {
+        id: "dotnet",
+        displayName: ".NET",
+        async detect({ fileExists }) {
+            return ((await fileExists("global.json")) ||
+                (await fileExists("Directory.Build.props")));
+        },
+        async build() {
+            return {
+                id: "dotnet",
+                displayName: ".NET",
+                manifestGlobs: ["**/*.csproj", "**/*.fsproj", "**/*.vbproj"],
+                lockfileTwins: [
+                    { manifestGlob: "**/*.csproj", lockfileGlob: "**/packages.lock.json" }
+                ],
+                testCommandHints: ["dotnet test"]
+            };
+        }
+    },
+    {
+        id: "elixir",
+        displayName: "Elixir",
+        async detect({ fileExists }) {
+            return await fileExists("mix.exs");
+        },
+        async build() {
+            return {
+                id: "elixir",
+                displayName: "Elixir",
+                manifestGlobs: ["mix.exs", "**/mix.exs"],
+                lockfileTwins: [
+                    { manifestGlob: "mix.exs", lockfileGlob: "mix.lock" }
+                ],
+                testCommandHints: ["mix test"]
+            };
+        }
+    },
+    {
+        id: "java",
+        displayName: "Java/JVM",
+        async detect({ fileExists }) {
+            return ((await fileExists("pom.xml")) ||
+                (await fileExists("build.gradle")) ||
+                (await fileExists("build.gradle.kts")));
+        },
+        async build({ fileExists }) {
+            const manifestGlobs = [];
+            if (await fileExists("pom.xml"))
+                manifestGlobs.push("pom.xml");
+            if (await fileExists("build.gradle"))
+                manifestGlobs.push("build.gradle");
+            if (await fileExists("build.gradle.kts"))
+                manifestGlobs.push("build.gradle.kts");
+            // Java/Gradle/Maven do not have a single canonical lockfile in
+            // common usage. Leave lockfileTwins empty (no-op for slice-commit
+            // auto-include). Projects that want lockfiles wire them via the
+            // local config or wrapper rather than at the adapter layer.
+            return {
+                id: "java",
+                displayName: "Java/JVM",
+                manifestGlobs: manifestGlobs.length > 0 ? manifestGlobs : ["pom.xml"],
+                lockfileTwins: [],
+                testCommandHints: ["mvn test", "gradle test", "./gradlew test"]
+            };
+        }
+    }
+];
+const UNKNOWN_STACK_ADAPTER = {
+    id: "unknown",
+    displayName: "current stack",
+    manifestGlobs: [],
+    lockfileTwins: [],
+    testCommandHints: []
+};
+/**
+ * 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 async function loadStackAdapter(projectRoot, options = {}) {
+    const root = options.projectRoot ?? projectRoot;
+    const fileExists = async (relPath) => {
+        if (relPath.includes("*")) {
+            // We never glob in the detection path; concrete probes only.
+            return false;
+        }
+        try {
+            await fs.access(path.join(root, relPath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const factoryInput = { fileExists };
+    for (const factory of STACK_ADAPTER_FACTORIES) {
+        if (await factory.detect(factoryInput)) {
+            return factory.build(factoryInput);
+        }
+    }
+    return UNKNOWN_STACK_ADAPTER;
+}
+/**
+ * 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 function buildStackAdapterForTests(partial) {
+    return {
+        manifestGlobs: [],
+        lockfileTwins: [],
+        testCommandHints: [],
+        ...partial
+    };
+}
+export const UNKNOWN_STACK = UNKNOWN_STACK_ADAPTER;
+// ---------------------------------------------------------------------------
+// Wiring aggregator helpers (per stack).
+// ---------------------------------------------------------------------------
+function rustWiringAggregator() {
+    return {
+        aggregatorPattern: "src/lib.rs | src/main.rs | mod.rs (parent module)",
+        resolveAggregatorFor(filePath) {
+            const normalized = normalizeRel(filePath);
+            if (!/\.rs$/u.test(normalized))
+                return null;
+            // The file IS itself an aggregator: nothing to do.
+            const basename = baseName(normalized);
+            if (basename === "lib.rs" || basename === "main.rs" || basename === "mod.rs") {
+                return null;
+            }
+            // Find the nearest `src/` ancestor and target its `lib.rs` (or main).
+            // We default to lib.rs because most workspaces expose a library
+            // crate; binaries can override by carrying main.rs in the claim
+            // alongside lib.rs.
+            const segments = normalized.split("/");
+            const srcIdx = segments.lastIndexOf("src");
+            if (srcIdx < 0) {
+                // No conventional layout — fall back to parent dir mod.rs.
+                const parent = segments.slice(0, -1).join("/");
+                if (parent.length === 0)
+                    return null;
+                return `${parent}/mod.rs`;
+            }
+            const srcRoot = segments.slice(0, srcIdx + 1).join("/");
+            // If file lives directly under src/ (e.g. src/foo.rs), it must be
+            // declared in src/lib.rs (or src/main.rs).
+            if (srcIdx === segments.length - 2) {
+                return `${srcRoot}/lib.rs`;
+            }
+            // Otherwise, the parent module's mod.rs is the wiring point.
+            const parentSegments = segments.slice(0, -1);
+            return `${parentSegments.join("/")}/mod.rs`;
+        }
+    };
+}
+function nodeTsWiringAggregator() {
+    const candidateBasenames = ["index.ts", "index.tsx", "index.js", "index.jsx"];
+    return {
+        aggregatorPattern: "parent-dir index.{ts,tsx,js,jsx} (only when an index.* already exists in the parent dir)",
+        resolveAggregatorFor(filePath, repoState) {
+            const normalized = normalizeRel(filePath);
+            if (!/\.(ts|tsx|js|jsx|mjs|cjs)$/u.test(normalized))
+                return null;
+            const basename = baseName(normalized);
+            if (candidateBasenames.includes(basename))
+                return null;
+            const segments = normalized.split("/");
+            if (segments.length < 2)
+                return null;
+            const parentDir = segments.slice(0, -1).join("/");
+            const headFiles = repoState?.headFiles;
+            // node-ts wiring is opt-in: if the parent dir already has an
+            // index.* file at HEAD, the project uses barrel exports and the
+            // new file must be added to the barrel. Without an index.* file,
+            // we treat the project as not using barrels and emit no
+            // requirement.
+            if (!headFiles)
+                return null;
+            for (const candidate of candidateBasenames) {
+                const indexPath = `${parentDir}/${candidate}`;
+                if (headFiles.has(indexPath)) {
+                    return indexPath;
+                }
+            }
+            return null;
+        }
+    };
+}
+function pythonWiringAggregator() {
+    return {
+        aggregatorPattern: "parent-dir __init__.py (skipped when sibling __init__.py absent — PEP 420 namespace package)",
+        resolveAggregatorFor(filePath, repoState) {
+            const normalized = normalizeRel(filePath);
+            if (!/\.py$/u.test(normalized))
+                return null;
+            const basename = baseName(normalized);
+            if (basename === "__init__.py")
+                return null;
+            const segments = normalized.split("/");
+            if (segments.length < 2)
+                return null;
+            const parentDir = segments.slice(0, -1).join("/");
+            const candidate = `${parentDir}/__init__.py`;
+            // PEP 420 namespace packages skip __init__.py entirely. We detect
+            // the layout by checking whether the parent dir already has an
+            // __init__.py at HEAD; if it doesn't, treat the dir as namespace
+            // and skip the requirement.
+            const headFiles = repoState?.headFiles;
+            if (!headFiles) {
+                // No state: be conservative and emit the requirement so authors
+                // either include the aggregator or migrate to PEP 420 with a
+                // claimedPaths note.
+                return candidate;
+            }
+            if (headFiles.has(candidate)) {
+                return candidate;
+            }
+            // Sibling __init__.py absent — namespace package layout. No-op.
+            return null;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Path helpers shared by aggregator resolvers.
+// ---------------------------------------------------------------------------
+function normalizeRel(value) {
+    return value.trim().replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+}
+function baseName(rel) {
+    const idx = rel.lastIndexOf("/");
+    return idx >= 0 ? rel.slice(idx + 1) : rel;
+}

package/dist/tdd-cycle.js

@@ -1,3 +1,4 @@
+import { isSliceId } from "./util/slice-id.js";
 export function parseTddCycleLog(text, options = {}) {
     const issues = options.issues;
     const strict = options.strict === true;
@@ -75,7 +76,6 @@ export function parseTddCycleLog(text, options = {}) {
     }
     return out;
 }
-const SLICE_ID_PATTERN = /^S-\d+$/u;
 export function validateTddCycleOrder(entries, options = {}) {
     const targetRun = options.runId;
     const filtered = targetRun
@@ -89,13 +89,15 @@ export function validateTddCycleOrder(entries, options = {}) {
     }
     const issues = [];
     const openRedSlices = [];
-    // Reject slices whose ID does not match the stable `S-<number>` contract.
+    // Reject slices whose ID does not match the stable slice-id contract.
     // Entries that drop the slice field entirely were previously coerced to
     // `S-unknown` and silently bucketed together, which means multiple distinct
-    // cycles could appear to share a RED/GREEN pair.
+    // cycles could appear to share a RED/GREEN pair. 7.6.0 relaxed the shape
+    // to allow lettered sub-slice ids (e.g. `S-36a`) so plan amendments can
+    // insert work between numeric slices without renumbering.
     for (const slice of bySlice.keys()) {
-        if (!SLICE_ID_PATTERN.test(slice)) {
-            issues.push(`slice "${slice}": id must match /^S-\\d+$/ (e.g. S-1); repair by re-logging RED/GREEN/REFACTOR with a stable slice id.`);
+        if (!isSliceId(slice)) {
+            issues.push(`slice "${slice}": id must match S-<number>(<letter><suffix>)? (e.g. S-1, S-36a); repair by re-logging RED/GREEN/REFACTOR with a stable slice id.`);
         }
     }
     for (const [slice, sliceEntries] of bySlice.entries()) {

package/dist/types.d.ts

@@ -163,6 +163,25 @@ export interface ReviewLoopConfig {
 export type VcsMode = "git-with-remote" | "git-local-only" | "none";
 export type TddCommitMode = "managed-per-slice" | "agent-required" | "checkpoint-only" | "off";
 export type TddIsolationMode = "worktree" | "in-place" | "auto";
+export type ExecutionTopology = "auto" | "inline" | "single-builder" | "parallel-builders" | "strict-micro";
+export type ExecutionStrictnessProfile = "fast" | "balanced" | "strict";
+export type PlanSliceGranularity = "feature-atomic" | "strict-micro";
+export type PlanMicroTaskPolicy = "advisory" | "strict";
+/**
+ * 7.6.0 — what slice-commit does when a manifest in the slice's
+ * claim drifts its corresponding lockfile twin (e.g. Cargo.toml +
+ * Cargo.lock; package.json + package-lock.json; pyproject.toml +
+ * poetry.lock; etc).
+ *
+ * - `auto-include` (default) — fold the lockfile drift into the slice
+ *   commit so the manifest + lockfile land atomically.
+ * - `auto-revert` — revert the lockfile drift before commit so the
+ *   slice ships only the manifest change; the next CI/test run will
+ *   regenerate the lockfile.
+ * - `strict-fence` — reject the lockfile drift as
+ *   `slice_commit_path_drift` (pre-7.6.0 behavior).
+ */
+export type LockfileTwinPolicy = "auto-include" | "auto-revert" | "strict-fence";
 export interface TddConfig {
     /**
      * Commit ownership model for closed TDD slices.
@@ -183,12 +202,60 @@ export interface TddConfig {
      * Repo-relative root used for managed slice worktrees.
      */
     worktreeRoot?: string;
+    /**
+     * 7.6.0 — slice-commit policy when a manifest claim drifts its lockfile
+     * twin (Cargo.toml/Cargo.lock, package.json/package-lock.json, etc).
+     * Defaults to `auto-include` so the manifest + regenerated lockfile
+     * land in the same managed commit instead of failing on drift.
+     */
+    lockfileTwinPolicy?: LockfileTwinPolicy;
+}
+export interface ExecutionConfig {
+    /**
+     * 7.7.0 — adaptive execution topology for implementation units.
+     *
+     * - `auto` (default): choose the cheapest safe route from plan shape.
+     * - `inline`: controller may execute a low-risk unit inline while still
+     *   recording RED/GREEN/REFACTOR evidence.
+     * - `single-builder`: one slice-builder owns a feature-atomic unit.
+     * - `parallel-builders`: fan out independent substantial units only.
+     * - `strict-micro`: preserve the pre-7.7 posture where each tiny task is
+     *   its own schedulable slice.
+     */
+    topology?: ExecutionTopology;
+    /**
+     * 7.7.0 — default calibration for topology and plan-shape advisories.
+     * `balanced` is the default: prefer feature-atomic units with internal
+     * 2-5 minute TDD steps, warning on microtask-only plans without blocking.
+     */
+    strictness?: ExecutionStrictnessProfile;
+    /**
+     * 7.7.0 — upper bound for simultaneous slice-builder workers when the
+     * router selects `parallel-builders`.
+     */
+    maxBuilders?: number;
+}
+export interface PlanConfig {
+    /**
+     * 7.7.0 — default schedulable surface for plan authoring.
+     * - feature-atomic: U-* slices contain internal 2-5 minute TDD steps.
+     * - strict-micro: one tiny task can remain one schedulable slice.
+     */
+    sliceGranularity?: PlanSliceGranularity;
+    /**
+     * 7.7.0 — how strongly the plan linter reacts to microtask-only plans.
+     * `advisory` warns in fast/balanced execution; `strict` treats strict
+     * microtask planning as intentional.
+     */
+    microTaskPolicy?: PlanMicroTaskPolicy;
 }
 export interface CclawConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
     tdd?: TddConfig;
+    execution?: ExecutionConfig;
+    plan?: PlanConfig;
 }
 export interface TransitionRule {
     from: FlowStage;

package/dist/util/slice-id.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Slice-ID helpers.
+ *
+ * 7.6.0 — relaxed strict `/^S-\d+$/` to allow lettered sub-slices
+ * (`S-36a`, `S-36b`, …) so plan amendments can insert work between
+ * existing numeric slices without renumbering.
+ *
+ * Canonical shape: `S-<integer>(<lowercase-letter>[<lowercase-or-digit>...])?`
+ *
+ * Sort order (used everywhere we list slice ids):
+ *   1. numeric chunk ascending
+ *   2. lexical suffix ascending (no suffix sorts before any suffix)
+ *
+ * So: `S-1 < S-2 < S-10 < S-36 < S-36a < S-36b < S-37`.
+ *
+ * Surface:
+ *   - `SLICE_ID_PATTERN`   — anchored regex source string for embedding
+ *   - `SLICE_ID_REGEX`     — anchored RegExp for tests
+ *   - `parseSliceId`       — strict parse → `{ numeric, suffix }` or null
+ *   - `isSliceId`          — boolean shape check
+ *   - `compareSliceIds`    — sort comparator
+ *   - `sortSliceIds`       — convenience wrapper around `compareSliceIds`
+ */
+/** Anchored, case-insensitive regex source for slice ids. */
+export declare const SLICE_ID_PATTERN = "^S-(\\d+)([a-z][a-z0-9]*)?$";
+/** Anchored, case-insensitive RegExp instance for slice ids. */
+export declare const SLICE_ID_REGEX: RegExp;
+export interface ParsedSliceId {
+    /** Canonical normalized form, e.g. `S-36a`. */
+    id: string;
+    /** Numeric chunk as a number (e.g. `S-36a` → `36`). */
+    numeric: number;
+    /** Lowercase suffix (e.g. `S-36a` → `"a"`). Empty string when absent. */
+    suffix: string;
+}
+/**
+ * Strict parse of a slice id token.
+ *
+ * Returns `null` when the input is not a slice id. Whitespace and
+ * surrounding markdown decorations (backticks, brackets, quotes) are
+ * stripped before parsing so callers can pass cells from markdown
+ * tables verbatim.
+ */
+export declare function parseSliceId(raw: unknown): ParsedSliceId | null;
+/**
+ * Boolean shape check. Lowercase-or-uppercase `S-` prefix accepted; the
+ * canonical form is uppercase.
+ */
+export declare function isSliceId(raw: unknown): boolean;
+/**
+ * Comparator that orders slice ids by numeric chunk first, then by
+ * suffix (no-suffix sorts before any suffix). Non-slice tokens fall
+ * back to a stable lexical comparison so callers can pass mixed input
+ * without crashing.
+ */
+export declare function compareSliceIds(a: string, b: string): number;
+/** Convenience wrapper: returns a new sorted array using `compareSliceIds`. */
+export declare function sortSliceIds(ids: readonly string[]): string[];