cclaw-cli 8.1.2 → 8.2.0

package/dist/flow-state.d.ts

@@ -1,6 +1,8 @@
-import { type AcceptanceCriterionState, type BuildProfile, type DiscoverySpecialistId, type FlowStage } from "./types.js";
-export declare const FLOW_STATE_SCHEMA_VERSION = 2;
-export interface FlowStateV8 {
+import { type AcMode, type AcceptanceCriterionState, type BuildProfile, type DiscoverySpecialistId, type FlowStage, type RoutingClass, type TriageDecision } from "./types.js";
+export declare const FLOW_STATE_SCHEMA_VERSION = 3;
+/** v8.0–v8.1 schema. Auto-migrated to v3 on read. */
+export declare const LEGACY_V8_FLOW_STATE_SCHEMA_VERSION = 2;
+export interface FlowStateV82 {
     schemaVersion: typeof FLOW_STATE_SCHEMA_VERSION;
     currentSlug: string | null;
     currentStage: FlowStage | null;
@@ -10,13 +12,43 @@ export interface FlowStateV8 {
     reviewIterations: number;
     securityFlag: boolean;
     buildProfile?: BuildProfile;
+    /**
+     * Triage decision for the active flow. Null while no flow is running.
+     * Persisted so resume never re-prompts the user.
+     */
+    triage: TriageDecision | null;
 }
-export type FlowState = FlowStateV8;
+export type FlowState = FlowStateV82;
+/** @deprecated alias preserved for v8.1 import sites. Use {@link FlowStateV82}. */
+export type FlowStateV8 = FlowStateV82;
 export declare class LegacyFlowStateError extends Error {
     readonly observedSchemaVersion: unknown;
     constructor(message: string, observedSchemaVersion: unknown);
 }
 export declare function isFlowStage(value: unknown): value is FlowStage;
+export declare function isRoutingClass(value: unknown): value is RoutingClass;
+export declare function isAcMode(value: unknown): value is AcMode;
 export declare function isDiscoverySpecialist(value: unknown): value is DiscoverySpecialistId;
-export declare function createInitialFlowStateV8(nowIso?: string): FlowStateV8;
-export declare function assertFlowStateV8(value: unknown): asserts value is FlowStateV8;
+export declare function createInitialFlowState(nowIso?: string): FlowStateV82;
+/** @deprecated kept for source-level compatibility with v8.1 imports. */
+export declare const createInitialFlowStateV8: typeof createInitialFlowState;
+/**
+ * Validate a flow-state object. Throws on hard schema errors.
+ *
+ * v8.2 (schemaVersion=3) is the current shape. v8.0–v8.1 (schemaVersion=2)
+ * states are auto-migrated forward in {@link readMigratedFlowState}; this
+ * assertion expects the migrated shape.
+ */
+export declare function assertFlowStateV82(value: unknown): asserts value is FlowStateV82;
+/** @deprecated alias preserved for v8.1 import sites. Use {@link assertFlowStateV82}. */
+export declare const assertFlowStateV8: typeof assertFlowStateV82;
+/** Older v7.x schema marker — used only for the hard-stop migration error. */
+export declare const PRE_V8_LEGACY_SCHEMA_VERSIONS: Set<string | number | undefined>;
+/**
+ * Migrate any in-memory flow-state value to the current schemaVersion.
+ *
+ * Returns the migrated object. The caller is expected to write it back to
+ * disk before any further mutation. Throws {@link LegacyFlowStateError} if
+ * the input is from a pre-v8 release (schemaVersion 1 or unset).
+ */
+export declare function migrateFlowState(value: unknown): FlowStateV82;

package/dist/flow-state.js

@@ -1,5 +1,7 @@
-import { FLOW_STAGES } from "./types.js";
-export const FLOW_STATE_SCHEMA_VERSION = 2;
+import { AC_MODES, FLOW_STAGES, ROUTING_CLASSES } from "./types.js";
+export const FLOW_STATE_SCHEMA_VERSION = 3;
+/** v8.0–v8.1 schema. Auto-migrated to v3 on read. */
+export const LEGACY_V8_FLOW_STATE_SCHEMA_VERSION = 2;
 export class LegacyFlowStateError extends Error {
     observedSchemaVersion;
     constructor(message, observedSchemaVersion) {
@@ -11,10 +13,16 @@ export class LegacyFlowStateError extends Error {
 export function isFlowStage(value) {
     return typeof value === "string" && FLOW_STAGES.includes(value);
 }
+export function isRoutingClass(value) {
+    return typeof value === "string" && ROUTING_CLASSES.includes(value);
+}
+export function isAcMode(value) {
+    return typeof value === "string" && AC_MODES.includes(value);
+}
 export function isDiscoverySpecialist(value) {
     return value === "brainstormer" || value === "architect" || value === "planner";
 }
-export function createInitialFlowStateV8(nowIso = new Date().toISOString()) {
+export function createInitialFlowState(nowIso = new Date().toISOString()) {
     return {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         currentSlug: null,
@@ -23,7 +31,38 @@ export function createInitialFlowStateV8(nowIso = new Date().toISOString()) {
         lastSpecialist: null,
         startedAt: nowIso,
         reviewIterations: 0,
-        securityFlag: false
+        securityFlag: false,
+        triage: null
+    };
+}
+/** @deprecated kept for source-level compatibility with v8.1 imports. */
+export const createInitialFlowStateV8 = createInitialFlowState;
+/**
+ * Infer a TriageDecision for a v2 (pre-8.2) state being migrated forward.
+ *
+ * v2 states never recorded a triage. To preserve their behaviour we map
+ * them to `strict` AC mode (they relied on per-AC TDD), with complexity
+ * inferred from the AC count and security flag.
+ */
+function inferTriageFromLegacy(state) {
+    const acCount = state.ac.length;
+    let complexity;
+    if (state.securityFlag || acCount > 5) {
+        complexity = "large-risky";
+    }
+    else if (acCount > 0) {
+        complexity = "small-medium";
+    }
+    else {
+        complexity = "small-medium";
+    }
+    return {
+        complexity,
+        acMode: "strict",
+        path: ["plan", "build", "review", "ship"],
+        rationale: "Auto-migrated from cclaw 8.0/8.1 flow-state (no triage recorded; preserved as strict).",
+        decidedAt: state.startedAt,
+        userOverrode: false
     };
 }
 function assertAcArray(value) {
@@ -51,12 +90,46 @@ function assertAcArray(value) {
         }
     }
 }
-export function assertFlowStateV8(value) {
+function assertTriageOrNull(value) {
+    if (value === null)
+        return;
+    if (typeof value !== "object")
+        throw new Error("flow-state.triage must be an object or null");
+    const triage = value;
+    if (!isRoutingClass(triage.complexity)) {
+        throw new Error(`Invalid triage.complexity: ${String(triage.complexity)}`);
+    }
+    if (!isAcMode(triage.acMode)) {
+        throw new Error(`Invalid triage.acMode: ${String(triage.acMode)}`);
+    }
+    if (!Array.isArray(triage.path)) {
+        throw new Error("triage.path must be an array of stage names");
+    }
+    for (const stage of triage.path) {
+        if (!isFlowStage(stage))
+            throw new Error(`Invalid triage.path stage: ${String(stage)}`);
+    }
+    if (typeof triage.rationale !== "string")
+        throw new Error("triage.rationale must be a string");
+    if (typeof triage.decidedAt !== "string")
+        throw new Error("triage.decidedAt must be a string");
+    if (typeof triage.userOverrode !== "boolean") {
+        throw new Error("triage.userOverrode must be a boolean");
+    }
+}
+/**
+ * Validate a flow-state object. Throws on hard schema errors.
+ *
+ * v8.2 (schemaVersion=3) is the current shape. v8.0–v8.1 (schemaVersion=2)
+ * states are auto-migrated forward in {@link readMigratedFlowState}; this
+ * assertion expects the migrated shape.
+ */
+export function assertFlowStateV82(value) {
     if (typeof value !== "object" || value === null)
         throw new Error("flow-state must be an object");
     const state = value;
     if (state.schemaVersion !== FLOW_STATE_SCHEMA_VERSION) {
-        throw new LegacyFlowStateError("Unsupported flow-state schema. cclaw v8 cannot resume 7.x runs. Finish or abandon the old run, then delete .cclaw/state/flow-state.json.", state.schemaVersion);
+        throw new LegacyFlowStateError(`Unsupported flow-state schema (saw ${String(state.schemaVersion)}, expected ${FLOW_STATE_SCHEMA_VERSION}). Run cclaw upgrade or delete .cclaw/state/flow-state.json to start fresh.`, state.schemaVersion);
     }
     if (state.currentSlug !== null && state.currentSlug !== undefined && typeof state.currentSlug !== "string") {
         throw new Error("flow-state.currentSlug must be a string or null");
@@ -79,4 +152,50 @@ export function assertFlowStateV8(value) {
     if (state.buildProfile !== undefined && state.buildProfile !== "default" && state.buildProfile !== "bootstrap") {
         throw new Error(`Invalid buildProfile: ${String(state.buildProfile)}`);
     }
+    assertTriageOrNull(state.triage);
+}
+/** @deprecated alias preserved for v8.1 import sites. Use {@link assertFlowStateV82}. */
+export const assertFlowStateV8 = assertFlowStateV82;
+/** Older v7.x schema marker — used only for the hard-stop migration error. */
+export const PRE_V8_LEGACY_SCHEMA_VERSIONS = new Set([1, "1", "1.0", undefined]);
+/**
+ * Migrate any in-memory flow-state value to the current schemaVersion.
+ *
+ * Returns the migrated object. The caller is expected to write it back to
+ * disk before any further mutation. Throws {@link LegacyFlowStateError} if
+ * the input is from a pre-v8 release (schemaVersion 1 or unset).
+ */
+export function migrateFlowState(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error("flow-state must be an object");
+    }
+    const raw = value;
+    if (raw.schemaVersion === FLOW_STATE_SCHEMA_VERSION) {
+        assertFlowStateV82(raw);
+        return raw;
+    }
+    if (raw.schemaVersion === LEGACY_V8_FLOW_STATE_SCHEMA_VERSION) {
+        const migrated = migrateFromV2(raw);
+        assertFlowStateV82(migrated);
+        return migrated;
+    }
+    throw new LegacyFlowStateError(`Unsupported flow-state schema. cclaw v8.2 only migrates from schemaVersion 2 (v8.0/v8.1). Saw ${String(raw.schemaVersion)}. Delete .cclaw/state/flow-state.json to start fresh.`, raw.schemaVersion);
+}
+function migrateFromV2(raw) {
+    const ac = raw.ac ?? [];
+    const securityFlag = Boolean(raw.securityFlag);
+    const startedAt = typeof raw.startedAt === "string" ? raw.startedAt : new Date().toISOString();
+    const triage = raw.currentSlug ? inferTriageFromLegacy({ ac, securityFlag, startedAt }) : null;
+    return {
+        schemaVersion: FLOW_STATE_SCHEMA_VERSION,
+        currentSlug: raw.currentSlug ?? null,
+        currentStage: raw.currentStage ?? null,
+        ac,
+        lastSpecialist: raw.lastSpecialist ?? null,
+        startedAt,
+        reviewIterations: typeof raw.reviewIterations === "number" ? raw.reviewIterations : 0,
+        securityFlag,
+        buildProfile: raw.buildProfile,
+        triage
+    };
 }

package/dist/run-persistence.d.ts

@@ -1,7 +1,14 @@
-import { type FlowStateV8 } from "./flow-state.js";
+import { type FlowStateV82 } from "./flow-state.js";
 export declare function flowStatePath(projectRoot: string): string;
 export declare function ensureRunSystem(projectRoot: string): Promise<void>;
-export declare function readFlowState(projectRoot: string): Promise<FlowStateV8>;
-export declare function writeFlowState(projectRoot: string, state: FlowStateV8): Promise<void>;
+/**
+ * Read and validate flow-state.json.
+ *
+ * v8.0/v8.1 (schemaVersion=2) states are silently auto-migrated to v8.2
+ * (schemaVersion=3) and rewritten to disk so subsequent reads are O(1).
+ * v7.x states throw `LegacyFlowStateError` exactly as before.
+ */
+export declare function readFlowState(projectRoot: string): Promise<FlowStateV82>;
+export declare function writeFlowState(projectRoot: string, state: FlowStateV82): Promise<void>;
 export declare function resetFlowState(projectRoot: string): Promise<void>;
-export declare function patchFlowState(projectRoot: string, patch: Partial<FlowStateV8>): Promise<FlowStateV8>;
+export declare function patchFlowState(projectRoot: string, patch: Partial<FlowStateV82>): Promise<FlowStateV82>;

package/dist/run-persistence.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { FLOW_STATE_REL_PATH, RUNTIME_ROOT } from "./constants.js";
-import { assertFlowStateV8, createInitialFlowStateV8 } from "./flow-state.js";
+import { assertFlowStateV82, createInitialFlowState, migrateFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);
@@ -10,27 +10,38 @@ export async function ensureRunSystem(projectRoot) {
     await ensureDir(path.join(projectRoot, RUNTIME_ROOT, "state"));
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
-        await writeFlowState(projectRoot, createInitialFlowStateV8());
+        await writeFlowState(projectRoot, createInitialFlowState());
     }
 }
+/**
+ * Read and validate flow-state.json.
+ *
+ * v8.0/v8.1 (schemaVersion=2) states are silently auto-migrated to v8.2
+ * (schemaVersion=3) and rewritten to disk so subsequent reads are O(1).
+ * v7.x states throw `LegacyFlowStateError` exactly as before.
+ */
 export async function readFlowState(projectRoot) {
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
-        const initial = createInitialFlowStateV8();
+        const initial = createInitialFlowState();
         await writeFlowState(projectRoot, initial);
         return initial;
     }
     const raw = await fs.readFile(statePath, "utf8");
     const parsed = JSON.parse(raw);
-    assertFlowStateV8(parsed);
-    return parsed;
+    const migrated = migrateFlowState(parsed);
+    // If migration reshaped the on-disk file, persist the upgrade.
+    if (parsed.schemaVersion !== migrated.schemaVersion) {
+        await writeFlowState(projectRoot, migrated);
+    }
+    return migrated;
 }
 export async function writeFlowState(projectRoot, state) {
-    assertFlowStateV8(state);
+    assertFlowStateV82(state);
     await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(state, null, 2)}\n`);
 }
 export async function resetFlowState(projectRoot) {
-    await writeFlowState(projectRoot, createInitialFlowStateV8());
+    await writeFlowState(projectRoot, createInitialFlowState());
 }
 export async function patchFlowState(projectRoot, patch) {
     const current = await readFlowState(projectRoot);

package/dist/types.d.ts

@@ -25,7 +25,38 @@ export interface AcceptanceCriterionState {
     phases?: Partial<Record<TddPhase, TddPhaseRecord>>;
 }
 export type BuildProfile = "default" | "bootstrap";
-export type RoutingClass = "trivial" | "small-medium" | "large-risky";
+export declare const ROUTING_CLASSES: readonly ["trivial", "small-medium", "large-risky"];
+export type RoutingClass = (typeof ROUTING_CLASSES)[number];
+/**
+ * AC traceability and TDD enforcement modes (v8.2+).
+ *
+ * - `inline`: trivial change. No AC table, no commit hook, optional tests.
+ * - `soft`: small/medium feature work. Bullet-list testable conditions in
+ *   `plan.md` (no AC IDs); commit-helper does not block; one TDD cycle per
+ *   feature is enough. Default for small/medium routing.
+ * - `strict`: large/risky / security-flagged. AC IDs with commit trace,
+ *   ship gate, RED → GREEN → REFACTOR per AC. Same as v8.1 behaviour.
+ *
+ * Selected at the triage gate; user can override.
+ */
+export declare const AC_MODES: readonly ["inline", "soft", "strict"];
+export type AcMode = (typeof AC_MODES)[number];
+/**
+ * Decision recorded at the triage gate that opens every new flow.
+ * Persisted in flow-state.json so resumes never re-trigger triage.
+ */
+export interface TriageDecision {
+    complexity: RoutingClass;
+    acMode: AcMode;
+    /** Stages the orchestrator promised to run, in order. Empty for trivial. */
+    path: FlowStage[];
+    /** Why this complexity was chosen. One short sentence. */
+    rationale: string;
+    /** ISO timestamp when triage was recorded. */
+    decidedAt: string;
+    /** Did the user override the orchestrator's recommendation? */
+    userOverrode: boolean;
+}
 export interface CliContext {
     cwd: string;
     stdout: NodeJS.WriteStream;

package/dist/types.js

@@ -7,3 +7,17 @@ export const SPECIALISTS = [
     "security-reviewer",
     "slice-builder"
 ];
+export const ROUTING_CLASSES = ["trivial", "small-medium", "large-risky"];
+/**
+ * AC traceability and TDD enforcement modes (v8.2+).
+ *
+ * - `inline`: trivial change. No AC table, no commit hook, optional tests.
+ * - `soft`: small/medium feature work. Bullet-list testable conditions in
+ *   `plan.md` (no AC IDs); commit-helper does not block; one TDD cycle per
+ *   feature is enough. Default for small/medium routing.
+ * - `strict`: large/risky / security-flagged. AC IDs with commit trace,
+ *   ship gate, RED → GREEN → REFACTOR per AC. Same as v8.1 behaviour.
+ *
+ * Selected at the triage gate; user can override.
+ */
+export const AC_MODES = ["inline", "soft", "strict"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "8.1.2",
+  "version": "8.2.0",
   "description": "Lightweight harness-first flow toolkit for coding agents",
   "type": "module",
   "bin": {