cclaw-cli 0.5.16 → 0.6.0

package/dist/flow-state.js

@@ -1,7 +1,28 @@
 import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageGateIds } from "./content/stage-schema.js";
+import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
-export function createInitialFlowState(activeRunId = "active") {
+export function isFlowTrack(value) {
+    return typeof value === "string" && FLOW_TRACKS.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));
+}
+export function firstStageForTrack(track) {
+    const stages = TRACK_STAGES[track];
+    return stages[0] ?? "brainstorm";
+}
+export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTrack) {
+    const options = typeof activeRunIdOrOptions === "string"
+        ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
+        : activeRunIdOrOptions;
+    const activeRunId = options.activeRunId ?? "active";
+    const track = options.track ?? "standard";
+    const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
     for (const schema of orderedStageSchemas()) {
         stageGateCatalog[schema.stage] = {
@@ -12,10 +33,12 @@ export function createInitialFlowState(activeRunId = "active") {
     }
     return {
         activeRunId,
-        currentStage: "brainstorm",
+        currentStage: firstStageForTrack(track),
         completedStages: [],
         guardEvidence: {},
-        stageGateCatalog
+        stageGateCatalog,
+        track,
+        skippedStages
     };
 }
 export function canTransition(from, to) {
@@ -25,17 +48,33 @@ export function getTransitionGuards(from, to) {
     const match = TRANSITION_RULES.find((rule) => rule.from === from && rule.to === to);
     return match ? [...match.guards] : [];
 }
-export function nextStage(stage) {
-    const index = COMMAND_FILE_ORDER.indexOf(stage);
-    if (index < 0 || index === COMMAND_FILE_ORDER.length - 1) {
+export function nextStage(stage, track = "standard") {
+    const ordered = TRACK_STAGES[track];
+    const index = ordered.indexOf(stage);
+    if (index < 0) {
+        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        if (fallback < 0 || fallback === COMMAND_FILE_ORDER.length - 1) {
+            return null;
+        }
+        return COMMAND_FILE_ORDER[fallback + 1];
+    }
+    if (index === ordered.length - 1) {
         return null;
     }
-    return COMMAND_FILE_ORDER[index + 1];
+    return ordered[index + 1];
 }
-export function previousStage(stage) {
-    const index = COMMAND_FILE_ORDER.indexOf(stage);
-    if (index <= 0) {
+export function previousStage(stage, track = "standard") {
+    const ordered = TRACK_STAGES[track];
+    const index = ordered.indexOf(stage);
+    if (index === 0) {
         return null;
     }
-    return COMMAND_FILE_ORDER[index - 1];
+    if (index < 0) {
+        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        if (fallback <= 0) {
+            return null;
+        }
+        return COMMAND_FILE_ORDER[fallback - 1];
+    }
+    return ordered[index - 1];
 }

package/dist/gate-evidence.d.ts

@@ -7,8 +7,22 @@ export interface GateEvidenceCheckResult {
     requiredCount: number;
     passedCount: number;
     blockedCount: number;
+    /** True only when every required gate for the stage is in `passed` and none are `blocked`. */
+    complete: boolean;
+    /** Required gate ids that are neither passed nor blocked. */
+    missingRequired: string[];
+}
+export interface CompletedStagesClosureResult {
+    ok: boolean;
+    issues: string[];
+    openStages: Array<{
+        stage: FlowStage;
+        missingRequired: string[];
+        blocked: string[];
+    }>;
 }
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
+export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
     stage: FlowStage;
     changed: boolean;

package/dist/gate-evidence.js

@@ -1,6 +1,29 @@
-import { lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { checkReviewVerdictConsistency, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
+import { exists } from "./fs-utils.js";
 import { readFlowState, writeFlowState } from "./runs.js";
+async function currentStageArtifactExists(projectRoot, stage) {
+    const artifactFile = stageSchema(stage).artifactFile;
+    const candidates = [
+        path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile),
+        path.join(projectRoot, artifactFile)
+    ];
+    for (const candidate of candidates) {
+        if (await exists(candidate))
+            return true;
+    }
+    // Artifact-linter also accepts the file under current working directory fallback; stat once more.
+    try {
+        await fs.access(path.join(projectRoot, artifactFile));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -44,7 +67,8 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             issues.push(`blocked gate "${gateId}" is not defined for stage "${stage}".`);
         }
     }
-    const shouldValidateArtifact = catalog.passed.length > 0 || flowState.completedStages.includes(stage);
+    const artifactPresent = await currentStageArtifactExists(projectRoot, stage);
+    const shouldValidateArtifact = artifactPresent || catalog.passed.length > 0 || flowState.completedStages.includes(stage);
     if (shouldValidateArtifact) {
         const lint = await lintArtifact(projectRoot, stage);
         if (!lint.passed) {
@@ -60,6 +84,21 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             if (!reviewArmy.valid) {
                 issues.push(`review-army validation failed: ${reviewArmy.errors.join("; ")}`);
             }
+            const verdictConsistency = await checkReviewVerdictConsistency(projectRoot);
+            if (!verdictConsistency.ok) {
+                issues.push(`review verdict inconsistency: ${verdictConsistency.errors.join("; ")}`);
+            }
+        }
+    }
+    const passedSet = new Set(catalog.passed);
+    const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
+    const complete = missingRequired.length === 0 && catalog.blocked.length === 0;
+    if (flowState.completedStages.includes(stage) && !complete) {
+        if (missingRequired.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but required gates are not passed: ${missingRequired.join(", ")}.`);
+        }
+        if (catalog.blocked.length > 0) {
+            issues.push(`stage "${stage}" is marked completed but has blocked gates: ${catalog.blocked.join(", ")}.`);
         }
     }
     return {
@@ -68,9 +107,32 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         issues,
         requiredCount: required.length,
         passedCount: catalog.passed.length,
-        blockedCount: catalog.blocked.length
+        blockedCount: catalog.blocked.length,
+        complete,
+        missingRequired
     };
 }
+export function verifyCompletedStagesGateClosure(flowState) {
+    const issues = [];
+    const openStages = [];
+    for (const stage of flowState.completedStages) {
+        const schema = stageSchema(stage);
+        const catalog = flowState.stageGateCatalog[stage];
+        const required = schema.requiredGates.map((gate) => gate.id);
+        const passedSet = new Set(catalog.passed);
+        const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
+        if (missingRequired.length > 0 || catalog.blocked.length > 0) {
+            openStages.push({ stage, missingRequired, blocked: [...catalog.blocked] });
+            if (missingRequired.length > 0) {
+                issues.push(`completed stage "${stage}" has unpassed required gates: ${missingRequired.join(", ")}.`);
+            }
+            if (catalog.blocked.length > 0) {
+                issues.push(`completed stage "${stage}" still has blocked gates: ${catalog.blocked.join(", ")}.`);
+            }
+        }
+    }
+    return { ok: openStages.length === 0, issues, openStages };
+}
 export function reconcileCurrentStageGateCatalog(flowState) {
     const stage = flowState.currentStage;
     const required = stageSchema(stage).requiredGates.map((gate) => gate.id);

package/dist/harness-adapters.js

@@ -124,6 +124,7 @@ export async function syncHarnessShims(projectRoot, harnesses) {
         await writeFileSafe(path.join(commandDir, "cc.md"), utilityShimContent(harness, "cc", "flow-start", "start.md"));
         await writeFileSafe(path.join(commandDir, "cc-next.md"), utilityShimContent(harness, "next", "flow-next-step", "next.md"));
         await writeFileSafe(path.join(commandDir, "cc-learn.md"), utilityShimContent(harness, "learn", "learnings", "learn.md"));
+        await writeFileSafe(path.join(commandDir, "cc-status.md"), utilityShimContent(harness, "status", "flow-status", "status.md"));
     }
     await syncAgentFiles(projectRoot);
     await syncAgentsMd(projectRoot);

package/dist/install.d.ts

@@ -1,7 +1,8 @@
-import type { HarnessId } from "./types.js";
+import type { FlowTrack, HarnessId } from "./types.js";
 export interface InitOptions {
     projectRoot: string;
     harnesses?: HarnessId[];
+    track?: FlowTrack;
 }
 export declare function initCclaw(options: InitOptions): Promise<void>;
 export declare function syncCclaw(projectRoot: string): Promise<void>;

package/dist/install.js

@@ -9,9 +9,10 @@ import { contextModeFiles, createInitialContextModeState } from "./content/conte
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
+import { statusCommandContract, statusCommandSkillMarkdown } from "./content/status-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -173,6 +174,7 @@ async function writeSkills(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "learnings", "SKILL.md"), learnSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-next-step", "SKILL.md"), nextCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-status", "SKILL.md"), statusCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
@@ -186,6 +188,7 @@ async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "start.md"), startCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "status.md"), statusCommandContract());
 }
 function toObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -482,6 +485,7 @@ async function writeHooks(projectRoot, config) {
     await ensureDir(hooksDir);
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
+    await writeFileSafe(path.join(hooksDir, "pre-compact.sh"), preCompactScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
@@ -493,6 +497,7 @@ async function writeHooks(projectRoot, config) {
         for (const script of [
             "session-start.sh",
             "stop-checkpoint.sh",
+            "pre-compact.sh",
             "prompt-guard.sh",
             "workflow-guard.sh",
             "context-monitor.sh",
@@ -542,6 +547,101 @@ async function ensureKnowledgeStore(projectRoot) {
         await writeFileSafe(storePath, "# Project Knowledge\n\n");
     }
 }
+async function ensureCustomSkillsScaffold(projectRoot) {
+    const customDir = runtimePath(projectRoot, "custom-skills");
+    await ensureDir(customDir);
+    const readmePath = path.join(customDir, "README.md");
+    if (!(await exists(readmePath))) {
+        await writeFileSafe(readmePath, CUSTOM_SKILLS_README);
+    }
+    const examplePath = path.join(customDir, "example", "SKILL.md");
+    if (!(await exists(examplePath))) {
+        await writeFileSafe(examplePath, CUSTOM_SKILLS_EXAMPLE);
+    }
+}
+const CUSTOM_SKILLS_README = `# Custom Skills (sync-safe)
+
+This directory is **never overwritten** by \`cclaw sync\` or \`cclaw upgrade\`. Use it
+to add project-specific skills that complement the managed skills under
+\`.cclaw/skills/\`.
+
+## When to add a custom skill
+
+- A repeatable lens specific to **this project** (e.g. "billing-domain", "kafka-message-contracts").
+- A team convention you want every agent session to load.
+- A domain checklist that does not generalize to other projects.
+
+If the skill is general (security, performance, accessibility, etc.) prefer
+contributing it upstream instead — the managed skills receive maintenance.
+
+## File format
+
+Each skill lives at \`.cclaw/custom-skills/<folder>/SKILL.md\` with frontmatter:
+
+\`\`\`markdown
+---
+name: <kebab-case-skill-name>
+description: "One sentence describing when this skill applies. Triggers semantic routing."
+---
+
+# <Skill title>
+
+## When to use
+- ...
+
+## HARD-GATE (optional)
+A non-skippable rule, if any. Phrase it as a refusal, not a recommendation.
+
+## Algorithm / checklist
+1. ...
+2. ...
+
+## Anti-patterns
+- ...
+\`\`\`
+
+## Routing
+
+Custom skills are surfaced via the \`using-cclaw\` meta-skill at session start.
+Mention the skill name in your prompt or let the agent semantic-route to it
+based on the description.
+
+## Removing or replacing
+
+Custom skills are user-owned. Delete or edit them at any time — \`cclaw sync\`
+will not touch them.
+`;
+const CUSTOM_SKILLS_EXAMPLE = `---
+name: example-custom-skill
+description: "Replace this with a one-sentence description that triggers when the skill should be used. Delete or rename this folder when you add a real skill."
+---
+
+# Example Custom Skill
+
+This is a placeholder. Use it as a starting template, then delete or rename
+the \`example/\` folder.
+
+## When to use
+
+- A real, repeatable situation in **this** project that needs a consistent lens.
+
+## HARD-GATE (optional)
+
+Drop this section if no hard rule applies. Keep it crisp:
+
+> Do not <X> while <Y>.
+
+## Algorithm
+
+1. Step one — observable, file:line evidence required.
+2. Step two — produce a named artifact, not a vibe.
+3. Step three — escalate / hand off / record knowledge entry.
+
+## Anti-patterns
+
+- Treating this skill as advisory when the situation matches the trigger.
+- Loading this skill when the situation clearly does not match (context bloat).
+`;
 async function ensureSessionStateFiles(projectRoot) {
     const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(stateDir);
@@ -623,12 +723,12 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
         await removeManagedOpenCodePluginConfig(projectRoot, OPENCODE_PLUGIN_REL_PATH);
     }
 }
-async function writeState(projectRoot, forceReset = false) {
+async function writeState(projectRoot, config, forceReset = false) {
     const statePath = runtimePath(projectRoot, "state", "flow-state.json");
     if (!forceReset && (await exists(statePath))) {
         return;
     }
-    const state = createInitialFlowState();
+    const state = createInitialFlowState("active", config.defaultTrack ?? "standard");
     await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 async function writeAdapterManifest(projectRoot, harnesses) {
@@ -740,11 +840,12 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await writeContextModes(projectRoot);
     await writeArtifactTemplates(projectRoot);
     await writeRulebook(projectRoot);
-    await writeState(projectRoot, forceStateReset);
+    await writeState(projectRoot, config, forceStateReset);
     await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);
     await writeAdapterManifest(projectRoot, harnesses);
     await ensureKnowledgeStore(projectRoot);
+    await ensureCustomSkillsScaffold(projectRoot);
     await writeHooks(projectRoot, config);
     await syncDisabledHarnessArtifacts(projectRoot, harnesses);
     await syncManagedGitHooks(projectRoot, config);
@@ -753,7 +854,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureGitignore(projectRoot);
 }
 export async function initCclaw(options) {
-    const config = createDefaultConfig(options.harnesses);
+    const config = createDefaultConfig(options.harnesses, options.track);
     await writeConfig(options.projectRoot, config);
     await materializeRuntime(options.projectRoot, config, true);
 }
@@ -828,7 +929,7 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
+    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
 }
 async function removeManagedHookEntries(hookFilePath) {
     if (!(await exists(hookFilePath)))

package/dist/runs.d.ts

@@ -1,5 +1,17 @@
 import { type FlowState } from "./flow-state.js";
 import type { FlowStage } from "./types.js";
+export declare class InvalidStageTransitionError extends Error {
+    readonly from: FlowStage;
+    readonly to: FlowStage;
+    constructor(from: FlowStage, to: FlowStage, message: string);
+}
+export interface WriteFlowStateOptions {
+    /**
+     * When true, skip prior-state validation. Used for run archival, initial
+     * bootstrap, or explicit recovery; never set from normal stage handlers.
+     */
+    allowReset?: boolean;
+}
 export interface CclawRunMeta {
     id: string;
     title: string;
@@ -32,7 +44,7 @@ export declare class CorruptFlowStateError extends Error {
     constructor(statePath: string, quarantinedPath: string, cause: unknown);
 }
 export declare function readFlowState(projectRoot: string): Promise<FlowState>;
-export declare function writeFlowState(projectRoot: string, state: FlowState): Promise<void>;
+export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
 export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
 export declare function archiveRun(projectRoot: string, featureName?: string): Promise<ArchiveRunResult>;

package/dist/runs.js

@@ -1,8 +1,35 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { createInitialFlowState } from "./flow-state.js";
+import { canTransition, createInitialFlowState, isFlowTrack, skippedStagesForTrack } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+export class InvalidStageTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to, message) {
+        super(message);
+        this.from = from;
+        this.to = to;
+        this.name = "InvalidStageTransitionError";
+    }
+}
+function validateFlowTransition(prev, next) {
+    if (prev.activeRunId !== next.activeRunId) {
+        // New run — only reset paths may change the runId, but those set allowReset.
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change activeRunId from "${prev.activeRunId}" to "${next.activeRunId}" without allowReset.`);
+    }
+    for (const completed of prev.completedStages) {
+        if (!next.completedStages.includes(completed)) {
+            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
+        }
+    }
+    if (prev.currentStage === next.currentStage) {
+        return;
+    }
+    if (!canTransition(prev.currentStage, next.currentStage)) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}". Use /cc-next to advance stages or archive the run to reset.`);
+    }
+}
 const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
@@ -129,8 +156,27 @@ function sanitizeStageGateCatalog(value, fallback) {
     }
     return next;
 }
+function coerceTrack(value) {
+    return isFlowTrack(value) ? value : "standard";
+}
+function sanitizeSkippedStages(value, track) {
+    const trackDefault = skippedStagesForTrack(track);
+    if (!Array.isArray(value)) {
+        return trackDefault;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of value) {
+        if (isFlowStage(raw) && !seen.has(raw)) {
+            seen.add(raw);
+            out.push(raw);
+        }
+    }
+    return out.length > 0 ? out : trackDefault;
+}
 function coerceFlowState(parsed) {
-    const next = createInitialFlowState();
+    const track = coerceTrack(parsed.track);
+    const next = createInitialFlowState("active", track);
     const activeRunIdRaw = parsed.activeRunId;
     const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
         ? activeRunIdRaw.trim()
@@ -140,7 +186,9 @@ function coerceFlowState(parsed) {
         currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
         completedStages: sanitizeCompletedStages(parsed.completedStages),
         guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
-        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog)
+        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
+        track,
+        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track)
     };
 }
 function toArchiveDate(date = new Date()) {
@@ -251,10 +299,28 @@ export async function readFlowState(projectRoot) {
     }
     return coerceFlowState(parsed);
 }
-export async function writeFlowState(projectRoot, state) {
+export async function writeFlowState(projectRoot, state, options = {}) {
     await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
+        const statePath = flowStatePath(projectRoot);
+        if (!options.allowReset && (await exists(statePath))) {
+            try {
+                const raw = await fs.readFile(statePath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    const prev = coerceFlowState(parsed);
+                    validateFlowTransition(prev, state);
+                }
+            }
+            catch (err) {
+                if (err instanceof InvalidStageTransitionError) {
+                    throw err;
+                }
+                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
+                // block a legitimate write attempt on parse errors here.
+            }
+        }
         const safe = coerceFlowState({ ...state });
-        await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(safe, null, 2)}\n`);
+        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
     });
 }
 export async function ensureRunSystem(projectRoot, _options = {}) {
@@ -263,7 +329,7 @@ export async function ensureRunSystem(projectRoot, _options = {}) {
     const statePath = flowStatePath(projectRoot);
     const state = await readFlowState(projectRoot);
     if (!(await exists(statePath))) {
-        await writeFlowState(projectRoot, state);
+        await writeFlowState(projectRoot, state, { allowReset: true });
     }
     return state;
 }
@@ -315,7 +381,7 @@ export async function archiveRun(projectRoot, featureName) {
     const archiveStatePath = path.join(archivePath, "state");
     const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
     const resetState = createInitialFlowState();
-    await writeFlowState(projectRoot, resetState);
+    await writeFlowState(projectRoot, resetState, { allowReset: true });
     const archivedAt = new Date().toISOString();
     const manifest = {
         version: 1,

package/dist/types.d.ts

@@ -1,5 +1,16 @@
 export declare const FLOW_STAGES: readonly ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
 export type FlowStage = (typeof FLOW_STAGES)[number];
+export declare const FLOW_TRACKS: readonly ["quick", "standard"];
+export type FlowTrack = (typeof FLOW_TRACKS)[number];
+/**
+ * Ordered stages that make up each flow track.
+ *
+ * - `standard` runs the full 8-stage pipeline (default — same as before tracks existed).
+ * - `quick` skips the upstream product stages (brainstorm/scope/design/plan) for
+ *   small bug fixes or single-purpose changes where the spec is already known.
+ *   It still keeps the non-negotiable safety gates: spec → tdd → review → ship.
+ */
+export declare const TRACK_STAGES: Record<FlowTrack, readonly FlowStage[]>;
 export declare const HARNESS_IDS: readonly ["claude", "cursor", "opencode", "codex"];
 export type HarnessId = (typeof HARNESS_IDS)[number];
 export interface VibyConfig {
@@ -12,6 +23,8 @@ export interface VibyConfig {
     promptGuardMode?: "advisory" | "strict";
     /** When true, cclaw installs managed git pre-commit/pre-push wrappers. */
     gitHookGuards?: boolean;
+    /** Default flow track for new runs (quick = shortened path, standard = full pipeline). */
+    defaultTrack?: FlowTrack;
 }
 export interface TransitionRule {
     from: FlowStage;

package/dist/types.js

@@ -8,4 +8,17 @@ export const FLOW_STAGES = [
     "review",
     "ship"
 ];
+export const FLOW_TRACKS = ["quick", "standard"];
+/**
+ * Ordered stages that make up each flow track.
+ *
+ * - `standard` runs the full 8-stage pipeline (default — same as before tracks existed).
+ * - `quick` skips the upstream product stages (brainstorm/scope/design/plan) for
+ *   small bug fixes or single-purpose changes where the spec is already known.
+ *   It still keeps the non-negotiable safety gates: spec → tdd → review → ship.
+ */
+export const TRACK_STAGES = {
+    standard: FLOW_STAGES,
+    quick: ["spec", "tdd", "review", "ship"]
+};
 export const HARNESS_IDS = ["claude", "cursor", "opencode", "codex"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.5.16",
+  "version": "0.6.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {