cclaw-cli 6.14.1 → 6.14.2

package/dist/content/stages/tdd.js

@@ -37,7 +37,8 @@ export const TDD = {
     },
     executionModel: {
         checklist: [
-            "**Stream-style wave dispatch (v6.14.0):** Before routing, read the Parallel Execution Plan (managed block in the track planning artifact) and `<artifacts-dir>/wave-plans/`. Per-lane stream: each lane runs RED→GREEN→REFACTOR independently as soon as its `dependsOn` closes — no global RED checkpoint between Phase A and Phase B. The linter enforces RED-before-GREEN per slice via `tdd_slice_red_completed_before_green`; cross-lane interleaving is allowed. **Legacy `global-red` mode** is preserved for projects with `legacyContinuation: true` and any project that explicitly sets `flow-state.json::tddCheckpointMode: \"global-red\"` (rule `tdd_red_checkpoint_violation` still fires there). Multi-ready waves still get one AskQuestion (launch wave vs single-slice); then per-lane GREEN+DOC dispatch with worktree-first flags. Integration-overseer fires only on cross-slice trigger (see `integrationCheckRequired()` heuristic). Resume partial waves by parallelizing remaining members only (see top-of-skill `## Wave Batch Mode`).",
+            "**Wave dispatch — discovery hardened (v6.14.2):** Before routing, your FIRST tool call after entering TDD MUST be `node .cclaw/cli.mjs internal wave-status --json` (or the harness equivalent `npx cclaw-cli internal wave-status --json`). Do NOT page through `05-plan.md` to find the managed block — the helper reads the managed `<!-- parallel-exec-managed-start -->` block deterministically and prints `{ waves, nextDispatch.readyToDispatch, warnings }`. Open `05-plan.md` only AFTER `wave-status` names a slice that needs context. Multi-ready waves: one AskQuestion (launch wave vs single-slice); then RED checkpoint (when `tddCheckpointMode: \"global-red\"`) or per-lane stream (when `tddCheckpointMode: \"per-slice\"`, the v6.14+ default), parallel GREEN+DOC with worktree-first flags, per-lane REFACTOR. Resume partial waves by parallelizing remaining members only (see top-of-skill `## Wave Batch Mode`).",
+            "**Stream-style wave dispatch (v6.14.0):** After `wave-status` resolves the next dispatch, route accordingly. Per-lane stream: each lane runs RED→GREEN→REFACTOR independently as soon as its `dependsOn` closes — no global RED checkpoint between Phase A and Phase B. The linter enforces RED-before-GREEN per slice via `tdd_slice_red_completed_before_green`; cross-lane interleaving is allowed. **Legacy `global-red` mode** is preserved for projects with `legacyContinuation: true` and any project that explicitly sets `flow-state.json::tddCheckpointMode: \"global-red\"` (rule `tdd_red_checkpoint_violation` still fires there). Multi-ready waves still get one AskQuestion (launch wave vs single-slice); then per-lane GREEN+DOC dispatch with worktree-first flags. Integration-overseer fires only on cross-slice trigger (see `integrationCheckRequired()` heuristic).",
             "**Controller dispatch ordering (v6.14.1 — record BEFORE dispatch).** For every `Task` subagent the controller spawns, record `scheduled` then `launched` ledger events via `node .cclaw/hooks/delegation-record.mjs --status=scheduled ...` and `--status=launched ...` **BEFORE** the `Task(...)` call (one message: ledger writes first, then the matching `Task` calls). Workers self-record `acknowledged` and `completed`; controller back-fill is reserved for `--repair` recovery only. Pass `--span-id`, `--lane-id`, `--claim-token`, `--lease-until` through to the worker so its own helper invocations reuse them.",
             "**Wave closure — integration-overseer decision (v6.14.1).** When every dispatched lane has a `phase=green status=completed` event AND per-lane REFACTOR coverage is satisfied (separate phase event OR `refactorOutcome` folded into GREEN), call `integrationCheckRequired(events, fanInAudits)` from `src/delegation.ts`. (1) `required: true` → dispatch `integration-overseer` as before. (2) `required: false` → emit the audit row via `node .cclaw/hooks/delegation-record.mjs --audit-kind=cclaw_integration_overseer_skipped --audit-reason=\"<reasons>\" --slice-ids=\"S-1,S-2\" --json` and SKIP the dispatch. Linter advisory `tdd_integration_overseer_skipped_audit_missing` flags a wave that closes without either an overseer dispatch or this audit row.",
             "**Inline DOC opt-in (v6.14.1 — single-slice non-deep waves).** Default remains parallel `slice-documenter --phase doc` dispatched alongside `slice-implementer --phase green`. For single-slice waves where `flow-state.json::discoveryMode != \"deep\"`, the controller MAY skip the parallel documenter and instead invoke `slice-implementer --finalize-doc --slice S-<id> --paths <artifacts-dir>/tdd-slices/S-<id>.md` synchronously after GREEN. Multi-slice waves and any `discoveryMode=deep` run keep parallel slice-documenter mandatory.",
@@ -114,7 +115,7 @@ export const TDD = {
             "Relevant existing test files, helpers, fixtures, and exact commands identified before RED.",
             "Callbacks, state transitions, interfaces, schemas, and contracts checked for impact before implementation.",
             "Execution posture and vertical-slice RED/GREEN/REFACTOR checkpoint plan recorded, including commit boundaries when the repo workflow supports them.",
-            "RED observability: a `phase=red` event in `delegation-events.jsonl` for each slice with non-empty evidenceRefs (test path, span ref, or pasted-output pointer). Slices created **before the v6.12.0 cutover marker** in `flow-state.json::tddCutoverSliceId` may retain legacy `## Watched-RED Proof` / `## RED Evidence` markdown tables; slices created **after the cutover marker** MUST use phase events + slice-documenter doc, and legacy table writes are surfaced by the advisory `tdd_legacy_section_writes_after_cutover` rule.",
+            "RED observability: a `phase=red` event in `delegation-events.jsonl` for each slice with non-empty evidenceRefs (test path, span ref, or pasted-output pointer). **`flow-state.json::tddCutoverSliceId` is a HISTORICAL boundary set by `cclaw-cli sync` at upgrade time; it is NOT a pointer to the active slice and the controller MUST NOT dispatch new work for that slice id on its basis.** Slices created at or before the cutover marker may retain legacy `## Watched-RED Proof` / `## RED Evidence` markdown tables; slices created after the cutover marker MUST use phase events + slice-documenter doc, and legacy table writes are surfaced by the advisory `tdd_legacy_section_writes_after_cutover` rule. To find the ACTIVE slice, run `cclaw-cli internal wave-status --json` (Fix 1, v6.14.2) — never derive it from `tddCutoverSliceId`.",
             "GREEN observability: a `phase=green` event in `delegation-events.jsonl` per slice whose `completedTs` >= the matching `phase=red` `completedTs`, authored by `slice-implementer` (linter rule `tdd_slice_implementer_missing` blocks the gate otherwise), and whose evidenceRefs name the failing-now-passing test. Pre-cutover slices may keep legacy `## GREEN Evidence` markdown.",
             "REFACTOR observability: per slice, a `phase=refactor` event OR a `phase=refactor-deferred` event whose evidenceRefs / refactor rationale captures why refactor was deferred.",
             "Per slice, a `phase=doc` event from `slice-documenter` whose evidenceRefs name `<artifacts-dir>/tdd-slices/S-<id>.md`. Mandatory regardless of `discoveryMode` (v6.12.0 Phase R). Linter rule `tdd_slice_documenter_missing` blocks the gate when missing.",

package/dist/flow-state.d.ts

@@ -136,6 +136,29 @@ export interface FlowState {
      * sync hasn't visited yet.
      */
     tddCutoverSliceId?: string;
+    /**
+     * v6.14.2 — boundary slice id at which worktree-first protocol began
+     * applying. `cclaw-cli sync` auto-stamps this when
+     * `legacyContinuation: true` AND `worktreeExecutionMode: "worktree-first"`
+     * AND the value is not already set.
+     *
+     * Detection rule (v6.14.2): the highest `S-N` among slices with at
+     * least one completed `slice-implementer` row in the active run that
+     * carries NONE of the worktree-first metadata fields (`claimToken`,
+     * `ownerLaneId`, `leasedUntil`). When no such slice exists, sync
+     * falls back to `tddCutoverSliceId` so legacy v6.12 cutover marks
+     * still confer the exemption.
+     *
+     * Effect: closed slices whose numeric id is `<= tddWorktreeCutoverSliceId`
+     * AND whose `slice-implementer` rows in the active run lack ALL
+     * three worktree fields are exempt from `tdd_slice_lane_metadata_missing`,
+     * `tdd_slice_claim_token_missing`, and `tdd_lease_expired_unreclaimed`.
+     *
+     * One-shot: subsequent sync runs leave the value untouched. Operators
+     * may pin it earlier/later by direct edit + `cclaw-cli internal
+     * flow-state-repair --reason=<slug>`.
+     */
+    tddWorktreeCutoverSliceId?: string;
     /**
      * v6.13.0 — when `worktree-first` (default for newly initialized runs),
      * slice-implementer work happens in isolated git worktrees with explicit
@@ -185,6 +208,20 @@ export interface FlowState {
      * Omitted on legacy state files (treated as `"always"`).
      */
     integrationOverseerMode?: "conditional" | "always";
+    /**
+     * v6.14.2 — minimum elapsed milliseconds between `acknowledged` and
+     * `completed` for a `slice-implementer --phase green` row. The hook
+     * helper rejects fast-greens (`completedTs - ackTs < this`) with
+     * `green_evidence_too_fresh` unless the dispatch carries
+     * `--allow-fast-green --green-mode=observational`.
+     *
+     * Default 4000ms when omitted (see `effectiveTddGreenMinElapsedMs`).
+     * Operators tuning the floor for very fast suites may set it lower
+     * (e.g. `1500`) or set it to `0` to disable the check entirely while
+     * keeping the other Fix 4 contracts (RED test name match, passing
+     * assertion line) active.
+     */
+    tddGreenMinElapsedMs?: number;
 }
 /**
  * Effective worktree mode: legacy state files without the field keep
@@ -202,6 +239,15 @@ export declare function effectiveTddCheckpointMode(state: FlowState): "per-slice
  * the field default to `always` (matches v6.13 behavior).
  */
 export declare function effectiveIntegrationOverseerMode(state: FlowState): "conditional" | "always";
+export declare const DEFAULT_TDD_GREEN_MIN_ELAPSED_MS = 4000;
+/**
+ * v6.14.2 — effective minimum GREEN elapsed window in milliseconds.
+ * Returns the per-project override when present and finite; otherwise
+ * the documented 4000ms default. Negative values or NaN fall through
+ * to the default so a hand-edited `flow-state.json` cannot accidentally
+ * disable the check via `-1` or `"oops"`.
+ */
+export declare function effectiveTddGreenMinElapsedMs(state: FlowState): number;
 export interface StageInteractionHint {
     skipQuestions?: boolean;
     sourceStage?: FlowStage;

package/dist/flow-state.js

@@ -69,6 +69,24 @@ export function effectiveTddCheckpointMode(state) {
 export function effectiveIntegrationOverseerMode(state) {
     return state.integrationOverseerMode === "conditional" ? "conditional" : "always";
 }
+export const DEFAULT_TDD_GREEN_MIN_ELAPSED_MS = 4000;
+/**
+ * v6.14.2 — effective minimum GREEN elapsed window in milliseconds.
+ * Returns the per-project override when present and finite; otherwise
+ * the documented 4000ms default. Negative values or NaN fall through
+ * to the default so a hand-edited `flow-state.json` cannot accidentally
+ * disable the check via `-1` or `"oops"`.
+ */
+export function effectiveTddGreenMinElapsedMs(state) {
+    const raw = state.tddGreenMinElapsedMs;
+    if (typeof raw !== "number")
+        return DEFAULT_TDD_GREEN_MIN_ELAPSED_MS;
+    if (!Number.isFinite(raw))
+        return DEFAULT_TDD_GREEN_MIN_ELAPSED_MS;
+    if (raw < 0)
+        return DEFAULT_TDD_GREEN_MIN_ELAPSED_MS;
+    return Math.floor(raw);
+}
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }

package/dist/install.js

@@ -1005,12 +1005,25 @@ async function applyPlanLegacyContinuationIfNeeded(projectRoot) {
 }
 /**
  * v6.14.0 — set stream-style defaults on `cclaw-cli sync` and print a
- * one-line hint when defaults change. Strategy:
+ * one-line hint when defaults change.
  *
- * - When `legacyContinuation: true` and `tddCheckpointMode` is unset, force
- *   `tddCheckpointMode: "global-red"` (preserves hox wave protocol).
- * - When `legacyContinuation: true` and `integrationOverseerMode` is unset,
- *   force `integrationOverseerMode: "always"` (preserves v6.13 behavior).
+ * v6.14.2 update — flip the legacyContinuation defaults from
+ * `global-red`/`always` to `per-slice`/`conditional`. Rationale: hox-shape
+ * projects ran into S-17 misroutes precisely because the default
+ * preserved the v6.12 wave barrier even after the project itself had
+ * moved to stream-mode. Existing flow-state values are NEVER overwritten
+ * — operators who want to pin `global-red`/`always` may set them
+ * explicitly via `cclaw-cli internal set-checkpoint-mode global-red` and
+ * `set-integration-overseer-mode always`.
+ *
+ * Strategy:
+ *
+ * - When `legacyContinuation: true` and `tddCheckpointMode` is unset,
+ *   default to `tddCheckpointMode: "per-slice"` (v6.14.2 — was
+ *   `global-red` in v6.14.0/v6.14.1).
+ * - When `legacyContinuation: true` and `integrationOverseerMode` is
+ *   unset, default to `integrationOverseerMode: "conditional"` (v6.14.2
+ *   — was `always` in v6.14.0/v6.14.1).
  * - When `legacyContinuation` is NOT true (new / standard projects) and
  *   neither field is set, default to `tddCheckpointMode: "per-slice"`,
  *   `integrationOverseerMode: "conditional"`. Also default
@@ -1053,12 +1066,12 @@ async function applyV614DefaultsIfNeeded(projectRoot) {
     const legacyContinuation = obj.legacyContinuation === true;
     if (legacyContinuation) {
         if (!tddCheckpointModeSet) {
-            updates.tddCheckpointMode = "global-red";
-            summary.push("tddCheckpointMode=global-red (legacyContinuation)");
+            updates.tddCheckpointMode = "per-slice";
+            summary.push("tddCheckpointMode=per-slice (legacyContinuation, v6.14.2 default flip)");
         }
         if (!integrationOverseerModeSet) {
-            updates.integrationOverseerMode = "always";
-            summary.push("integrationOverseerMode=always (legacyContinuation)");
+            updates.integrationOverseerMode = "conditional";
+            summary.push("integrationOverseerMode=conditional (legacyContinuation, v6.14.2 default flip)");
         }
     }
     else {
@@ -1085,7 +1098,124 @@ async function applyV614DefaultsIfNeeded(projectRoot) {
     catch {
         return null;
     }
-    return `v6.14.0 stream-style defaults applied: ${summary.join(", ")}. To opt out, edit .cclaw/state/flow-state.json directly or pin the legacy mode (tddCheckpointMode="global-red", integrationOverseerMode="always").`;
+    return `v6.14.2 stream-style defaults applied: ${summary.join(", ")}. To opt out, run cclaw-cli internal set-checkpoint-mode global-red --reason="..." and/or cclaw-cli internal set-integration-overseer-mode always --reason="...".`;
+}
+/**
+ * v6.14.2 — auto-stamp `tddWorktreeCutoverSliceId` for legacyContinuation
+ * projects in worktree-first mode that haven't yet recorded a boundary.
+ *
+ * Detection ("any-metadata" rule): scan the active run's
+ * `slice-implementer` rows. The boundary is the highest `S-N` whose
+ * rows for the active run lack ALL of `claimToken`, `ownerLaneId`, and
+ * `leasedUntil`. When no such slice exists (every slice carries at
+ * least one worktree field), fall back to `tddCutoverSliceId` so the
+ * v6.12 cutover marker still confers exemption.
+ *
+ * Idempotent: when the field is already set, returns null without
+ * writing. Best-effort: read failures, missing ledger, or unparseable
+ * rows all short-circuit silently — the existing flow-state.json is
+ * never corrupted.
+ *
+ * Returns a one-line hint string (or `null` if nothing changed).
+ */
+async function applyV6142WorktreeCutoverIfNeeded(projectRoot) {
+    const flowStatePath = runtimePath(projectRoot, "state", "flow-state.json");
+    let flowStateRaw;
+    try {
+        flowStateRaw = await fs.readFile(flowStatePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(flowStateRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    if (obj.legacyContinuation !== true)
+        return null;
+    if (obj.worktreeExecutionMode !== "worktree-first")
+        return null;
+    if (typeof obj.tddWorktreeCutoverSliceId === "string" &&
+        obj.tddWorktreeCutoverSliceId.trim().length > 0) {
+        return null;
+    }
+    const ledgerPath = runtimePath(projectRoot, "state", "delegation-log.json");
+    const activeRunId = typeof obj.activeRunId === "string" ? obj.activeRunId : "";
+    let ledgerRaw;
+    try {
+        ledgerRaw = await fs.readFile(ledgerPath, "utf8");
+    }
+    catch {
+        ledgerRaw = "";
+    }
+    let ledgerParsed = null;
+    if (ledgerRaw.length > 0) {
+        try {
+            ledgerParsed = JSON.parse(ledgerRaw);
+        }
+        catch {
+            ledgerParsed = null;
+        }
+    }
+    const entries = ledgerParsed &&
+        typeof ledgerParsed === "object" &&
+        !Array.isArray(ledgerParsed) &&
+        Array.isArray(ledgerParsed.entries)
+        ? ledgerParsed.entries
+        : [];
+    let boundary = -1;
+    for (const entry of entries) {
+        if (entry.agent !== "slice-implementer")
+            continue;
+        if (entry.status !== "completed")
+            continue;
+        if (typeof entry.sliceId !== "string")
+            continue;
+        if (activeRunId && entry.runId && entry.runId !== activeRunId)
+            continue;
+        const tok = typeof entry.claimToken === "string" ? entry.claimToken.trim() : "";
+        const lane = typeof entry.ownerLaneId === "string" ? entry.ownerLaneId.trim() : "";
+        const lease = typeof entry.leasedUntil === "string" ? entry.leasedUntil.trim() : "";
+        if (tok.length > 0 || lane.length > 0 || lease.length > 0)
+            continue;
+        const m = /^S-(\d+)$/u.exec(entry.sliceId);
+        if (!m)
+            continue;
+        const n = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(n))
+            continue;
+        if (n > boundary)
+            boundary = n;
+    }
+    let stamped = null;
+    if (boundary >= 0) {
+        stamped = `S-${boundary}`;
+    }
+    else if (typeof obj.tddCutoverSliceId === "string" &&
+        /^S-\d+$/u.test(obj.tddCutoverSliceId)) {
+        stamped = obj.tddCutoverSliceId;
+    }
+    if (!stamped)
+        return null;
+    const merged = { ...obj, tddWorktreeCutoverSliceId: stamped };
+    try {
+        await writeFileSafe(flowStatePath, `${JSON.stringify(merged, null, 2)}\n`, {
+            mode: 0o600
+        });
+    }
+    catch {
+        return null;
+    }
+    return (`v6.14.2 stamped tddWorktreeCutoverSliceId=${stamped}; closed slices ≤ ${stamped} ` +
+        "are exempt from worktree-first findings under legacyContinuation. " +
+        "Edit .cclaw/state/flow-state.json to override (advisory).");
 }
 async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
@@ -1266,6 +1396,10 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
             if (v614Hint) {
                 process.stdout.write(`cclaw: ${v614Hint}\n`);
             }
+            const v6142Hint = await applyV6142WorktreeCutoverIfNeeded(projectRoot);
+            if (v6142Hint) {
+                process.stdout.write(`cclaw: ${v6142Hint}\n`);
+            }
         }
         try {
             await ensureRunSystem(projectRoot, { createIfMissing: false });

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