cclaw-cli 7.7.1 → 8.1.0

package/dist/flow-state.d.ts

@@ -1,179 +1,22 @@
-import type { DiscoveryMode, FlowStage, FlowTrack, TransitionRule } from "./types.js";
-export declare const TRANSITION_RULES: TransitionRule[];
-export declare const FLOW_STATE_SCHEMA_VERSION = 1;
-/** Snapshot from `collectRepoSignals` at last successful `start-flow` (optional on older states). */
-export interface RepoSignals {
-    fileCount: number;
-    hasReadme: boolean;
-    hasPackageManifest: boolean;
-    capturedAt: string;
-}
-export interface StageGateState {
-    required: string[];
-    recommended: string[];
-    conditional: string[];
-    /** Conditional gates currently considered active for blocking checks. */
-    triggered: string[];
-    passed: string[];
-    blocked: string[];
-}
-export interface RewindRecord {
-    id: string;
-    fromStage: FlowStage;
-    toStage: FlowStage;
-    reason: string;
-    timestamp: string;
-    invalidatedStages: FlowStage[];
-}
-export interface StaleStageMarker {
-    rewindId: string;
-    reason: string;
-    markedAt: string;
-    acknowledgedAt?: string;
-}
-export interface RetroState {
-    required: boolean;
-    completedAt?: string;
-    compoundEntries: number;
-}
-/**
- * Ship closeout substate machine.
- *
- * After ship completes, cclaw auto-chains post-ship review → archive.
- * Each step is interruptible: `/cc` reads `shipSubstate` and resumes
- * from the correct step even across sessions.
- *
- * - `idle` — ship not complete, or closeout not yet started.
- * - `post_ship_review` — unified closeout leg: retro acceptance/edit/no changes
- *   plus compound pass execution (or explicit no-additional-changes path).
- * - `ready_to_archive` — retro + compound done; archive is the next
- *   automatic step.
- * - `archived` — archive completed in this session (transient — archive
- *   resets flow-state so this value does not persist between runs).
- *
- * Layer separation (intentional):
- * - `next: "done"` in stage schema means "the flow stage chain ended".
- * - `shipSubstate: "archived"` is closeout-machine progress after ship.
- * - `shipSubstate: "idle"` is the default closeout value before ship.
- *
- * These are not duplicates: `done` lives in stage transitions; `archived` /
- * `idle` live in closeout lifecycle state.
- */
-export declare const SHIP_SUBSTATES: readonly ["idle", "post_ship_review", "ready_to_archive", "archived"];
-export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];
-export interface CloseoutState {
-    shipSubstate: ShipSubstate;
-    retroDraftedAt?: string;
-    retroAcceptedAt?: string;
-    retroSkipped?: boolean;
-    retroSkipReason?: string;
-    compoundCompletedAt?: string;
-    compoundSkipped?: boolean;
-    compoundSkipReason?: string;
-    compoundPromoted: number;
-}
-export declare function createInitialCloseoutState(): CloseoutState;
-export interface FlowState {
-    /** Schema marker for forward compatibility. */
+import { type AcceptanceCriterionState, type BuildProfile, type DiscoverySpecialistId, type FlowStage } from "./types.js";
+export declare const FLOW_STATE_SCHEMA_VERSION = 2;
+export interface FlowStateV8 {
     schemaVersion: typeof FLOW_STATE_SCHEMA_VERSION;
-    /** Workspace marker stamped during sync/upgrade (semver string). */
-    packageVersion?: string;
-    activeRunId: string;
-    currentStage: FlowStage;
-    completedStages: FlowStage[];
-    guardEvidence: Record<string, string>;
-    stageGateCatalog: Record<FlowStage, StageGateState>;
-    /** Active flow track (determines which stages are in the critical path for this run). */
-    track: FlowTrack;
-    /** Run-level upstream shaping mode chosen once at start (`lean` / `guided` / `deep`). */
-    discoveryMode: DiscoveryMode;
-    /**
-     * Optional task class for the active run.
-     *
-     * Mirrors the `MandatoryDelegationTaskClass` union used by
-     * `mandatoryAgentsFor`. When set to `"software-bugfix"`, the
-     * artifact-validation escape (`shouldDemoteArtifactValidationByTrack`)
-     * collapses lite-tier-only checks (Architecture Diagram async/failure
-     * edges, Interaction Edge Case mandatory rows, Stale Diagram Drift,
-     * Expansion Strategist) from required → advisory.
-     */
-    taskClass?: "software-standard" | "software-trivial" | "software-bugfix" | null;
-    /** Stages explicitly skipped for this track (empty for standard; populated for quick). */
-    skippedStages: FlowStage[];
-    /** Stages invalidated by rewind operations and awaiting explicit acknowledgement. */
-    staleStages: Partial<Record<FlowStage, StaleStageMarker>>;
-    /** Chronological rewind operations for the active run. */
-    rewinds: RewindRecord[];
-    /** Optional per-stage interaction hints carried from prior stage transitions. */
-    interactionHints?: Partial<Record<FlowStage, StageInteractionHint>>;
-    /** Mandatory retrospective gate status before archive. */
-    retro: RetroState;
-    /** Ship → post_ship_review → archive substate for resumable closeout. */
-    closeout: CloseoutState;
-    /** Repo shape signals captured at last successful start-flow (omit on legacy files). */
-    repoSignals?: RepoSignals;
-    /**
-     * Best-effort stage completion timestamps (ISO strings) captured as stages
-     * enter `completedStages`. Missing keys behave like older flows with no
-     * audit clock for post-closure mutation hints.
-     */
-    completedStageMeta?: Partial<Record<FlowStage, {
-        completedAt: string;
-    }>>;
-    /**
-     * Minimum elapsed milliseconds between `acknowledged` and `completed`
-     * for a `slice-builder --phase green` row. The hook helper rejects
-     * fast-greens (`completedTs - ackTs < this`) with `green_evidence_too_fresh`
-     * unless the dispatch carries `--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 `0` to disable the check entirely while keeping the
-     * other freshness contracts (RED test name match, passing assertion line)
-     * active.
-     */
-    tddGreenMinElapsedMs?: number;
-}
-export declare const DEFAULT_TDD_GREEN_MIN_ELAPSED_MS = 4000;
-/**
- * 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;
-    recordedAt?: string;
-    /**
-     * `/cc-ideate` handoff carry-forward. When a brainstorm run is started
-     * from a `/cc-ideate` recommendation, `start-flow` records the originating
-     * idea artifact so brainstorm can reuse the divergent + critique + rank
-     * work instead of re-generating it.
-     *
-     * `fromIdeaArtifact` is a workspace-relative POSIX path to
-     * `.cclaw/ideas/idea-YYYY-MM-DD-<slug>.md` (or wherever `/cc-ideate`
-     * wrote its artifact). `fromIdeaCandidateId` is the chosen `I-#` row.
-     */
-    fromIdeaArtifact?: string;
-    fromIdeaCandidateId?: string;
-}
-export interface InitialFlowStateOptions {
-    activeRunId?: string;
-    track?: FlowTrack;
-    discoveryMode?: DiscoveryMode;
-}
-export declare function isFlowTrack(value: unknown): value is FlowTrack;
-export declare function isDiscoveryMode(value: unknown): value is DiscoveryMode;
-export declare function trackStages(track: FlowTrack): FlowStage[];
-export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
-export declare function firstStageForTrack(track: FlowTrack): FlowStage;
-export declare function createRunId(date?: Date): string;
-export declare function createInitialFlowState(activeRunIdOrOptions?: string | InitialFlowStateOptions, maybeTrack?: FlowTrack): FlowState;
-export declare function canTransition(from: FlowStage, to: FlowStage): boolean;
-export declare function getAvailableTransitions(from: FlowStage, track?: FlowTrack): TransitionRule[];
-export declare function getTransitionGuards(from: FlowStage, to: FlowStage, track?: FlowTrack): string[];
-export declare function nextStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;
-export declare function previousStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;
+    currentSlug: string | null;
+    currentStage: FlowStage | null;
+    ac: AcceptanceCriterionState[];
+    lastSpecialist: DiscoverySpecialistId | null;
+    startedAt: string;
+    reviewIterations: number;
+    securityFlag: boolean;
+    buildProfile?: BuildProfile;
+}
+export type FlowState = FlowStateV8;
+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 isDiscoverySpecialist(value: unknown): value is DiscoverySpecialistId;
+export declare function createInitialFlowStateV8(nowIso?: string): FlowStateV8;
+export declare function assertFlowStateV8(value: unknown): asserts value is FlowStateV8;

package/dist/flow-state.js

@@ -1,185 +1,82 @@
-import { buildTransitionRules, orderedStageSchemas, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
-import { DISCOVERY_MODES, FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
-export const TRANSITION_RULES = buildTransitionRules();
-export const FLOW_STATE_SCHEMA_VERSION = 1;
-/**
- * Ship closeout substate machine.
- *
- * After ship completes, cclaw auto-chains post-ship review → archive.
- * Each step is interruptible: `/cc` reads `shipSubstate` and resumes
- * from the correct step even across sessions.
- *
- * - `idle` — ship not complete, or closeout not yet started.
- * - `post_ship_review` — unified closeout leg: retro acceptance/edit/no changes
- *   plus compound pass execution (or explicit no-additional-changes path).
- * - `ready_to_archive` — retro + compound done; archive is the next
- *   automatic step.
- * - `archived` — archive completed in this session (transient — archive
- *   resets flow-state so this value does not persist between runs).
- *
- * Layer separation (intentional):
- * - `next: "done"` in stage schema means "the flow stage chain ended".
- * - `shipSubstate: "archived"` is closeout-machine progress after ship.
- * - `shipSubstate: "idle"` is the default closeout value before ship.
- *
- * These are not duplicates: `done` lives in stage transitions; `archived` /
- * `idle` live in closeout lifecycle state.
- */
-export const SHIP_SUBSTATES = [
-    "idle",
-    "post_ship_review",
-    "ready_to_archive",
-    "archived"
-];
-export function createInitialCloseoutState() {
-    return {
-        shipSubstate: "idle",
-        retroDraftedAt: undefined,
-        retroAcceptedAt: undefined,
-        retroSkipped: undefined,
-        retroSkipReason: undefined,
-        compoundCompletedAt: undefined,
-        compoundSkipped: undefined,
-        compoundSkipReason: undefined,
-        compoundPromoted: 0
-    };
-}
-export const DEFAULT_TDD_GREEN_MIN_ELAPSED_MS = 4000;
-/**
- * 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);
-}
-export function isDiscoveryMode(value) {
-    return typeof value === "string" && DISCOVERY_MODES.includes(value);
-}
-export function trackStages(track) {
-    return [...TRACK_STAGES[track]];
-}
-export function skippedStagesForTrack(track) {
-    const inTrack = new Set(TRACK_STAGES[track]);
-    return FLOW_STAGES.filter((stage) => !inTrack.has(stage));
+import { FLOW_STAGES } from "./types.js";
+export const FLOW_STATE_SCHEMA_VERSION = 2;
+export class LegacyFlowStateError extends Error {
+    observedSchemaVersion;
+    constructor(message, observedSchemaVersion) {
+        super(message);
+        this.observedSchemaVersion = observedSchemaVersion;
+        this.name = "LegacyFlowStateError";
+    }
 }
-export function firstStageForTrack(track) {
-    const stages = TRACK_STAGES[track];
-    return stages[0] ?? "brainstorm";
+export function isFlowStage(value) {
+    return typeof value === "string" && FLOW_STAGES.includes(value);
 }
-export function createRunId(date = new Date()) {
-    return `run-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+export function isDiscoverySpecialist(value) {
+    return value === "brainstormer" || value === "architect" || value === "planner";
 }
-export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
-    const options = typeof activeRunIdOrOptions === "string"
-        ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
-        : activeRunIdOrOptions;
-    const activeRunId = options.activeRunId ?? createRunId();
-    const track = options.track ?? "standard";
-    const discoveryMode = options.discoveryMode ?? "guided";
-    const skippedStages = skippedStagesForTrack(track);
-    const stageGateCatalog = {};
-    for (const schema of orderedStageSchemas(track)) {
-        stageGateCatalog[schema.stage] = {
-            required: stageGateIds(schema.stage, track),
-            recommended: stageRecommendedGateIds(schema.stage, track),
-            conditional: [],
-            triggered: [],
-            passed: [],
-            blocked: []
-        };
-    }
+export function createInitialFlowStateV8(nowIso = new Date().toISOString()) {
     return {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
-        activeRunId,
-        currentStage: firstStageForTrack(track),
-        completedStages: [],
-        guardEvidence: {},
-        stageGateCatalog,
-        track,
-        discoveryMode,
-        skippedStages,
-        staleStages: {},
-        rewinds: [],
-        interactionHints: {},
-        retro: {
-            required: false,
-            completedAt: undefined,
-            compoundEntries: 0
-        },
-        closeout: createInitialCloseoutState()
+        currentSlug: null,
+        currentStage: null,
+        ac: [],
+        lastSpecialist: null,
+        startedAt: nowIso,
+        reviewIterations: 0,
+        securityFlag: false
     };
 }
-export function canTransition(from, to) {
-    return TRANSITION_RULES.some((rule) => rule.from === from && rule.to === to);
-}
-export function getAvailableTransitions(from, track = "standard") {
-    const natural = nextStage(from, track);
-    const fromRules = TRANSITION_RULES.filter((rule) => rule.from === from);
-    if (!natural) {
-        return fromRules;
+function assertAcArray(value) {
+    if (!Array.isArray(value))
+        throw new Error("flow-state.ac must be an array");
+    for (const item of value) {
+        if (typeof item !== "object" || item === null)
+            throw new Error("flow-state.ac entries must be objects");
+        const ac = item;
+        if (typeof ac.id !== "string" || typeof ac.text !== "string") {
+            throw new Error("flow-state.ac entries require string id and text");
+        }
+        if (ac.status !== "pending" && ac.status !== "committed") {
+            throw new Error(`Invalid AC status: ${String(ac.status)}`);
+        }
+        if (ac.phases !== undefined) {
+            if (typeof ac.phases !== "object" || ac.phases === null) {
+                throw new Error("flow-state.ac.phases must be an object when present");
+            }
+            for (const phaseKey of Object.keys(ac.phases)) {
+                if (phaseKey !== "red" && phaseKey !== "green" && phaseKey !== "refactor") {
+                    throw new Error(`Invalid TDD phase key: ${phaseKey}`);
+                }
+            }
+        }
     }
-    return fromRules.sort((a, b) => {
-        if (a.to === natural && b.to !== natural)
-            return -1;
-        if (b.to === natural && a.to !== natural)
-            return 1;
-        return a.to.localeCompare(b.to);
-    });
 }
-export function getTransitionGuards(from, to, track = "standard") {
-    // Natural forward edge on this track: derive guards fresh from the
-    // track-specific gate schema. `TRANSITION_RULES` collapses shared edges
-    // across tracks (first-registered wins), so reading guards directly
-    // from the track-aware schema avoids silently dropping gates that only
-    // the current track requires (e.g. `tdd_traceable_to_plan` on standard
-    // gets lost if quick was registered first).
-    const ordered = TRACK_STAGES[track];
-    const fromIdx = ordered.indexOf(from);
-    if (fromIdx >= 0 && ordered[fromIdx + 1] === to) {
-        return stageGateIds(from, track);
+export function assertFlowStateV8(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);
     }
-    // Non-neighbour edges (e.g. `review -> tdd` with `review_verdict_blocked`)
-    // carry special guards not derivable from a stage's gate catalog; fall
-    // back to the pre-computed rule table.
-    const match = TRANSITION_RULES.find((rule) => rule.from === from && rule.to === to);
-    return match ? [...match.guards] : [];
-}
-export function nextStage(stage, track = "standard") {
-    const ordered = TRACK_STAGES[track];
-    const index = ordered.indexOf(stage);
-    if (index < 0) {
-        return null;
+    if (state.currentSlug !== null && state.currentSlug !== undefined && typeof state.currentSlug !== "string") {
+        throw new Error("flow-state.currentSlug must be a string or null");
     }
-    if (index === ordered.length - 1) {
-        return null;
+    if (state.currentStage !== null && state.currentStage !== undefined && !isFlowStage(state.currentStage)) {
+        throw new Error(`Invalid currentStage: ${String(state.currentStage)}`);
     }
-    return ordered[index + 1];
-}
-export function previousStage(stage, track = "standard") {
-    const ordered = TRACK_STAGES[track];
-    const index = ordered.indexOf(stage);
-    if (index === 0) {
-        return null;
+    assertAcArray(state.ac);
+    if (state.lastSpecialist !== null && state.lastSpecialist !== undefined && !isDiscoverySpecialist(state.lastSpecialist)) {
+        throw new Error(`Invalid lastSpecialist: ${String(state.lastSpecialist)}`);
     }
-    if (index < 0) {
-        const fallback = FLOW_STAGES.indexOf(stage);
-        if (fallback <= 0) {
-            return null;
-        }
-        return FLOW_STAGES[fallback - 1];
+    if (typeof state.startedAt !== "string")
+        throw new Error("flow-state.startedAt must be a string");
+    if (typeof state.reviewIterations !== "number" || state.reviewIterations < 0) {
+        throw new Error("flow-state.reviewIterations must be a non-negative number");
+    }
+    if (typeof state.securityFlag !== "boolean") {
+        throw new Error("flow-state.securityFlag must be a boolean");
+    }
+    if (state.buildProfile !== undefined && state.buildProfile !== "default" && state.buildProfile !== "bootstrap") {
+        throw new Error(`Invalid buildProfile: ${String(state.buildProfile)}`);
     }
-    return ordered[index - 1];
 }

package/dist/fs-utils.d.ts

@@ -1,27 +1,7 @@
-export declare function ensureDir(dirPath: string): Promise<void>;
-/**
- * Strip a leading UTF-8 BOM (U+FEFF) if present. Many editors (VS Code on
- * Windows, Notepad, some CI tools) silently prepend a BOM when saving
- * UTF-8; when the file is then split on `\n` the first line keeps the
- * invisible BOM and `JSON.parse` rejects it, which caused the first
- * knowledge.jsonl entry to be silently dropped on load. Treat BOM as a
- * no-op at read time so the rest of the pipeline sees clean UTF-8.
- */
-export declare function stripBom(text: string): string;
-export interface DirectoryLockOptions {
-    retries?: number;
-    retryDelayMs?: number;
-    staleAfterMs?: number;
-}
-/**
- * Acquire a lightweight lock by creating a directory.
- * The lock is removed in a finally block.
- */
-export declare function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>, options?: DirectoryLockOptions): Promise<T>;
-export interface WriteFileSafeOptions {
-    mode?: number;
-}
-export declare function writeFileSafe(filePath: string, content: string, options?: WriteFileSafeOptions): Promise<void>;
 export declare function exists(filePath: string): Promise<boolean>;
-export declare function removeIfExists(targetPath: string): Promise<void>;
-export declare function resolveProjectPath(cwd: string, relativePath: string): string;
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function writeFileSafe(filePath: string, content: string): Promise<void>;
+export declare function readJsonIfExists<T>(filePath: string): Promise<T | null>;
+export declare function removePath(filePath: string): Promise<void>;
+export declare function listMarkdownFiles(dir: string): Promise<string[]>;
+export declare function listSubdirs(dir: string): Promise<string[]>;