cclaw-cli 6.14.0 → 6.14.2

package/dist/internal/advance-stage.js

@@ -17,6 +17,10 @@ import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persis
 import { DelegationTimestampError, DispatchCapError, DispatchClaimInvalidError, DispatchDuplicateError, DispatchOverlapError } from "../delegation.js";
 import { parsePlanSplitWavesArgs, runPlanSplitWaves } from "./plan-split-waves.js";
 import { runSetWorktreeMode } from "./set-worktree-mode.js";
+import { runSetCheckpointMode } from "./set-checkpoint-mode.js";
+import { runSetIntegrationOverseerMode } from "./set-integration-overseer-mode.js";
+import { runWaveStatusCommand } from "./wave-status.js";
+import { runCohesionContractCommand } from "./cohesion-contract-stub.js";
 /**
  * Subcommands that mutate or consult flow-state.json via the CLI runtime.
  * They all require the sha256 sidecar to match before continuing so a
@@ -30,12 +34,14 @@ const GUARD_ENFORCED_SUBCOMMANDS = new Set([
     "rewind",
     "verify-flow-state-diff",
     "verify-current-state",
-    "set-worktree-mode"
+    "set-worktree-mode",
+    "set-checkpoint-mode",
+    "set-integration-overseer-mode"
 ]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode | set-checkpoint-mode | set-integration-overseer-mode | wave-status | cohesion-contract\n");
         return 1;
     }
     try {
@@ -93,7 +99,19 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "set-worktree-mode") {
             return await runSetWorktreeMode(projectRoot, tokens, io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode\n`);
+        if (subcommand === "set-checkpoint-mode") {
+            return await runSetCheckpointMode(projectRoot, tokens, io);
+        }
+        if (subcommand === "set-integration-overseer-mode") {
+            return await runSetIntegrationOverseerMode(projectRoot, tokens, io);
+        }
+        if (subcommand === "wave-status") {
+            return await runWaveStatusCommand(projectRoot, tokens, io);
+        }
+        if (subcommand === "cohesion-contract") {
+            return await runCohesionContractCommand(projectRoot, tokens, io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant | plan-split-waves | set-worktree-mode | set-checkpoint-mode | set-integration-overseer-mode | wave-status | cohesion-contract\n`);
         return 1;
     }
     catch (err) {

package/dist/internal/cohesion-contract-stub.d.ts

@@ -0,0 +1,29 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface CohesionContractArgs {
+    stub: boolean;
+    force: boolean;
+    reason: string | null;
+}
+export declare function parseCohesionContractArgs(tokens: string[]): CohesionContractArgs | null;
+/**
+ * v6.14.2 — emit a minimal advisory cohesion contract that satisfies
+ * the linter shape check (`cohesion-contract.{md,json}`) so projects
+ * with `legacyContinuation: true` and ≥ 2 completed slice-implementer
+ * rows can clear the soft `tdd.cohesion_contract_missing` finding
+ * without hand-authoring the document.
+ *
+ * The stub is intentionally bare — `sharedTypes`, `touchpoints`, and
+ * `slices` are populated from the active run delegation ledger so
+ * downstream tooling can see which slices the contract acknowledges,
+ * but the contract carries `status.verdict: "advisory_legacy"` so
+ * reviewers know not to treat it as authoritative.
+ *
+ * Refuses to overwrite an existing contract unless `--force` is
+ * passed; the existing file is treated as authored work.
+ */
+export declare function runCohesionContractCommand(projectRoot: string, tokens: string[], io: InternalIo): Promise<number>;
+export {};

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

@@ -0,0 +1,166 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { writeFileSafe } from "../fs-utils.js";
+import { readDelegationLedger } from "../delegation.js";
+export function parseCohesionContractArgs(tokens) {
+    const args = { stub: false, force: false, reason: null };
+    for (const token of tokens) {
+        if (token === "--stub") {
+            args.stub = true;
+            continue;
+        }
+        if (token === "--force") {
+            args.force = true;
+            continue;
+        }
+        if (token.startsWith("--reason=")) {
+            const raw = token.slice("--reason=".length).trim();
+            if (raw.length > 0)
+                args.reason = raw;
+            continue;
+        }
+        return null;
+    }
+    if (!args.stub)
+        return null;
+    return args;
+}
+/**
+ * v6.14.2 — emit a minimal advisory cohesion contract that satisfies
+ * the linter shape check (`cohesion-contract.{md,json}`) so projects
+ * with `legacyContinuation: true` and ≥ 2 completed slice-implementer
+ * rows can clear the soft `tdd.cohesion_contract_missing` finding
+ * without hand-authoring the document.
+ *
+ * The stub is intentionally bare — `sharedTypes`, `touchpoints`, and
+ * `slices` are populated from the active run delegation ledger so
+ * downstream tooling can see which slices the contract acknowledges,
+ * but the contract carries `status.verdict: "advisory_legacy"` so
+ * reviewers know not to treat it as authoritative.
+ *
+ * Refuses to overwrite an existing contract unless `--force` is
+ * passed; the existing file is treated as authored work.
+ */
+export async function runCohesionContractCommand(projectRoot, tokens, io) {
+    const parsed = parseCohesionContractArgs(tokens);
+    if (!parsed) {
+        io.stderr.write("cclaw internal cohesion-contract: usage: --stub [--force] [--reason=\"<short>\"]\n");
+        return 1;
+    }
+    const artifactsDir = path.join(projectRoot, RUNTIME_ROOT, "artifacts");
+    const mdPath = path.join(artifactsDir, "cohesion-contract.md");
+    const jsonPath = path.join(artifactsDir, "cohesion-contract.json");
+    if (!parsed.force) {
+        const mdExists = await fileExists(mdPath);
+        const jsonExists = await fileExists(jsonPath);
+        if (mdExists || jsonExists) {
+            io.stderr.write("cclaw internal cohesion-contract: existing cohesion-contract.{md,json} present; pass --force to overwrite.\n");
+            return 1;
+        }
+    }
+    const ledger = await readDelegationLedger(projectRoot).catch(() => null);
+    const sliceIds = collectSliceIds(ledger?.entries ?? []);
+    const reasonNote = parsed.reason
+        ? `Reason: ${parsed.reason}`
+        : "Reason: legacyContinuation auto-stub.";
+    const md = [
+        "# Cohesion Contract",
+        "",
+        "_Advisory stub generated by `cclaw-cli internal cohesion-contract --stub`._",
+        "_Status: `advisory_legacy` — populated for legacyContinuation projects so the_",
+        "_TDD linter does not block stage-complete on `tdd.cohesion_contract_missing`._",
+        "",
+        `${reasonNote}`,
+        "",
+        "## Shared Types & Interfaces",
+        "| Symbol | Path | Signature | Owner slice |",
+        "|---|---|---|---|",
+        "| (none recorded) | (none) | (none) | (n/a) |",
+        "",
+        "## Naming Conventions",
+        "- Stub: per-slice modules continue to follow the existing repo conventions.",
+        "",
+        "## Invariants",
+        "- Stub: no cross-slice invariants asserted; treat each slice as independent until upgraded.",
+        "",
+        "## Integration Touchpoints",
+        "| From slice | To slice | Surface | Integration test name |",
+        "|---|---|---|---|",
+        "| (none recorded) | (n/a) | (n/a) | (n/a) |",
+        "",
+        "## Behavior Specifications per Slice",
+        sliceIds.length === 0
+            ? "- (none recorded)"
+            : sliceIds
+                .map((sid) => `### Slice ${sid}\n- Behavior: see \`tdd-slices/${sid}.md\` (if present).`)
+                .join("\n\n"),
+        "",
+        "## Status",
+        "| Slice | Implemented | Tests pass | Cohesion verified |",
+        "|---|---|---|---|",
+        sliceIds.length === 0
+            ? "| (none) | n/a | n/a | n/a |"
+            : sliceIds.map((sid) => `| ${sid} | yes | yes | advisory |`).join("\n"),
+        ""
+    ].join("\n");
+    const jsonStub = {
+        version: 1,
+        sharedTypes: [],
+        touchpoints: [],
+        slices: sliceIds.map((sid) => ({
+            sliceId: sid,
+            description: `Stub entry for ${sid}; advisory under legacyContinuation.`,
+            implemented: true,
+            testsPass: true,
+            cohesionVerified: false
+        })),
+        status: {
+            verdict: "advisory_legacy",
+            generatedBy: "cclaw-cli internal cohesion-contract --stub",
+            reason: parsed.reason ?? "legacyContinuation auto-stub"
+        }
+    };
+    await writeFileSafe(mdPath, md);
+    await writeFileSafe(jsonPath, `${JSON.stringify(jsonStub, null, 2)}\n`);
+    io.stdout.write(`cclaw: cohesion-contract stub written (${sliceIds.length} slice(s) referenced). ` +
+        "Status: advisory_legacy — review and replace once cross-slice cohesion data is real.\n");
+    return 0;
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function collectSliceIds(entries) {
+    const set = new Set();
+    for (const entry of entries) {
+        if (entry.agent !== "slice-implementer")
+            continue;
+        if (entry.status !== "completed")
+            continue;
+        if (typeof entry.sliceId !== "string")
+            continue;
+        if (entry.sliceId.length === 0)
+            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;
+}

package/dist/internal/set-checkpoint-mode.d.ts

@@ -0,0 +1,16 @@
+import type { Writable } from "node:stream";
+export interface SetCheckpointModeArgs {
+    mode: "per-slice" | "global-red";
+    reason: string | null;
+}
+export declare function parseSetCheckpointModeArgs(tokens: string[]): SetCheckpointModeArgs | null;
+/**
+ * v6.14.2 — set `flow-state.json::tddCheckpointMode` without advancing
+ * the stage DAG. Mirrors `set-worktree-mode`. The `--reason` flag is
+ * optional but recommended for the audit trail; it is currently passed
+ * through to the writer subsystem string so operators can grep the
+ * `.flow-state.guard.json` sidecar.
+ */
+export declare function runSetCheckpointMode(projectRoot: string, tokens: string[], io: {
+    stderr: Writable;
+}): Promise<number>;

package/dist/internal/set-checkpoint-mode.js

@@ -0,0 +1,72 @@
+import { readFlowState, writeFlowState } from "../runs.js";
+export function parseSetCheckpointModeArgs(tokens) {
+    let mode = null;
+    let reason = null;
+    let positional = null;
+    for (const token of tokens) {
+        if (token.startsWith("--mode=")) {
+            const raw = token.slice("--mode=".length).trim();
+            if (raw === "per-slice" || raw === "global-red") {
+                mode = raw;
+            }
+            else {
+                return null;
+            }
+            continue;
+        }
+        if (token.startsWith("--reason=")) {
+            const raw = token.slice("--reason=".length).trim();
+            if (raw.length > 0)
+                reason = raw;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            // unknown flag — let the caller surface usage.
+            return null;
+        }
+        if (positional === null) {
+            positional = token.trim();
+            continue;
+        }
+        return null;
+    }
+    if (mode === null && positional !== null) {
+        if (positional === "per-slice" || positional === "global-red") {
+            mode = positional;
+        }
+        else {
+            return null;
+        }
+    }
+    if (mode === null)
+        return null;
+    return { mode, reason };
+}
+/**
+ * v6.14.2 — set `flow-state.json::tddCheckpointMode` without advancing
+ * the stage DAG. Mirrors `set-worktree-mode`. The `--reason` flag is
+ * optional but recommended for the audit trail; it is currently passed
+ * through to the writer subsystem string so operators can grep the
+ * `.flow-state.guard.json` sidecar.
+ */
+export async function runSetCheckpointMode(projectRoot, tokens, io) {
+    const parsed = parseSetCheckpointModeArgs(tokens);
+    if (!parsed) {
+        io.stderr.write("cclaw internal set-checkpoint-mode: usage: <per-slice|global-red> [--reason=\"<short>\"] " +
+            "(or --mode=<per-slice|global-red>)\n");
+        return 1;
+    }
+    const state = await readFlowState(projectRoot);
+    const writerSubsystem = parsed.reason
+        ? `set-checkpoint-mode:${slugifyReason(parsed.reason)}`
+        : "set-checkpoint-mode";
+    await writeFlowState(projectRoot, { ...state, tddCheckpointMode: parsed.mode }, { writerSubsystem });
+    return 0;
+}
+function slugifyReason(reason) {
+    return (reason
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, 60) || "unspecified");
+}

package/dist/internal/set-integration-overseer-mode.d.ts

@@ -0,0 +1,14 @@
+import type { Writable } from "node:stream";
+export interface SetIntegrationOverseerModeArgs {
+    mode: "conditional" | "always";
+    reason: string | null;
+}
+export declare function parseSetIntegrationOverseerModeArgs(tokens: string[]): SetIntegrationOverseerModeArgs | null;
+/**
+ * v6.14.2 — set `flow-state.json::integrationOverseerMode` without
+ * advancing the stage DAG. Mirrors `set-worktree-mode` and
+ * `set-checkpoint-mode`.
+ */
+export declare function runSetIntegrationOverseerMode(projectRoot: string, tokens: string[], io: {
+    stderr: Writable;
+}): Promise<number>;

package/dist/internal/set-integration-overseer-mode.js

@@ -0,0 +1,69 @@
+import { readFlowState, writeFlowState } from "../runs.js";
+export function parseSetIntegrationOverseerModeArgs(tokens) {
+    let mode = null;
+    let reason = null;
+    let positional = null;
+    for (const token of tokens) {
+        if (token.startsWith("--mode=")) {
+            const raw = token.slice("--mode=".length).trim();
+            if (raw === "conditional" || raw === "always") {
+                mode = raw;
+            }
+            else {
+                return null;
+            }
+            continue;
+        }
+        if (token.startsWith("--reason=")) {
+            const raw = token.slice("--reason=".length).trim();
+            if (raw.length > 0)
+                reason = raw;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            return null;
+        }
+        if (positional === null) {
+            positional = token.trim();
+            continue;
+        }
+        return null;
+    }
+    if (mode === null && positional !== null) {
+        if (positional === "conditional" || positional === "always") {
+            mode = positional;
+        }
+        else {
+            return null;
+        }
+    }
+    if (mode === null)
+        return null;
+    return { mode, reason };
+}
+/**
+ * v6.14.2 — set `flow-state.json::integrationOverseerMode` without
+ * advancing the stage DAG. Mirrors `set-worktree-mode` and
+ * `set-checkpoint-mode`.
+ */
+export async function runSetIntegrationOverseerMode(projectRoot, tokens, io) {
+    const parsed = parseSetIntegrationOverseerModeArgs(tokens);
+    if (!parsed) {
+        io.stderr.write("cclaw internal set-integration-overseer-mode: usage: <conditional|always> [--reason=\"<short>\"] " +
+            "(or --mode=<conditional|always>)\n");
+        return 1;
+    }
+    const state = await readFlowState(projectRoot);
+    const writerSubsystem = parsed.reason
+        ? `set-integration-overseer-mode:${slugifyReason(parsed.reason)}`
+        : "set-integration-overseer-mode";
+    await writeFlowState(projectRoot, { ...state, integrationOverseerMode: parsed.mode }, { writerSubsystem });
+    return 0;
+}
+function slugifyReason(reason) {
+    return (reason
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, 60) || "unspecified");
+}

package/dist/internal/wave-status.d.ts

@@ -0,0 +1,51 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface WaveStatusWaveSummary {
+    waveId: string;
+    members: string[];
+    closedMembers: string[];
+    openMembers: string[];
+    readyMembers: string[];
+    blockedMembers: string[];
+    status: "closed" | "open" | "partial" | "empty";
+}
+export interface WaveStatusNextDispatch {
+    waveId: string | null;
+    readyToDispatch: string[];
+    pathConflicts: string[];
+    mode: "single-slice" | "wave-fanout" | "none";
+}
+export interface WaveStatusReport {
+    activeRunId: string;
+    currentStage: string;
+    tddCutoverSliceId: string | null;
+    tddWorktreeCutoverSliceId: string | null;
+    legacyContinuation: boolean;
+    waves: WaveStatusWaveSummary[];
+    nextDispatch: WaveStatusNextDispatch;
+    warnings: string[];
+}
+export interface RunWaveStatusOptions {
+    /**
+     * Override the artifacts directory; useful for fixture tests that
+     * place an `05-plan.md` outside `.cclaw/artifacts`. Defaults to
+     * `<projectRoot>/.cclaw/artifacts`.
+     */
+    artifactsDir?: string;
+}
+/**
+ * v6.14.2 — deterministic helper for the TDD controller. Reads the
+ * managed `<!-- parallel-exec-managed-start -->` block from
+ * `<artifacts-dir>/05-plan.md` plus the `wave-plans/` directory and
+ * reports waves + the next dispatchable members so the controller does
+ * NOT have to page through a 1400-line plan to find the active wave.
+ *
+ * Always exits 0 unless the plan is malformed (no managed block AND no
+ * wave-plans directory), in which case exit 2 with a structured error.
+ */
+export declare function runWaveStatus(projectRoot: string, options?: RunWaveStatusOptions): Promise<WaveStatusReport>;
+export declare function runWaveStatusCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};