cclaw-cli 0.51.3 → 0.51.5

package/dist/artifact-linter.js

@@ -1633,25 +1633,34 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
         // IDs all fail the lint; absence of the section remains advisory so
         // scope stays optional for small/quick tracks.
         if (headingPresent(sections, "Locked Decisions (D-XX)")) {
-            const decisionIds = extractDecisionIds(lockedDecisionsBody);
-            const bulletLines = lockedDecisionsBody
+            const listDecisionLines = lockedDecisionsBody
                 .split(/\r?\n/u)
                 .map((line) => line.trim())
-                .filter((line) => /^(?:[-*]|\|)\s+\S/u.test(line));
-            const orphanBullets = bulletLines.filter((line) => !/\bD-\d+\b/u.test(line));
+                .filter((line) => /^[-*]\s+\S/u.test(line));
+            const tableDecisionRows = getMarkdownTableRows(lockedDecisionsBody);
+            const tableDecisionLines = tableDecisionRows.map((row) => row.join(" | "));
+            const decisionLines = [...listDecisionLines, ...tableDecisionLines];
+            const orphanDecisionLines = decisionLines.filter((line) => !/\bD-\d+\b/u.test(line));
+            const rowDecisionIds = [
+                ...listDecisionLines.map((line) => /\bD-\d+\b/u.exec(line)?.[0]),
+                ...tableDecisionRows.map((row) => /\bD-\d+\b/u.exec(row[0] ?? "")?.[0])
+            ].filter((id) => typeof id === "string");
             const duplicateIds = (() => {
-                const all = lockedDecisionsBody.match(/\bD-\d+\b/gu) ?? [];
                 const counts = new Map();
-                for (const id of all)
+                for (const id of rowDecisionIds)
                     counts.set(id, (counts.get(id) ?? 0) + 1);
                 return [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
             })();
             const issues = [];
-            if (decisionIds.length === 0 && bulletLines.length === 0) {
+            if (rowDecisionIds.length === 0 && decisionLines.length === 0) {
                 issues.push("section is empty");
             }
-            if (orphanBullets.length > 0) {
-                issues.push(`${orphanBullets.length} bullet(s) missing a D-XX ID`);
+            if (orphanDecisionLines.length > 0) {
+                const examples = orphanDecisionLines
+                    .slice(0, 3)
+                    .map((line) => `\`${line.slice(0, 120)}\``)
+                    .join(", ");
+                issues.push(`${orphanDecisionLines.length} decision row(s) missing a D-XX ID${examples.length > 0 ? `: ${examples}` : ""}`);
             }
             if (duplicateIds.length > 0) {
                 issues.push(`duplicate IDs: ${duplicateIds.join(", ")}`);
@@ -1662,7 +1671,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                 rule: "Locked Decisions section must list each decision with a unique stable D-XX ID.",
                 found: issues.length === 0,
                 details: issues.length === 0
-                    ? `${decisionIds.length} decision ID(s) recorded with no duplicates.`
+                    ? `${rowDecisionIds.length} decision ID(s) recorded with no duplicates.`
                     : issues.join("; ")
             });
         }

package/dist/content/node-hooks.js

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "../config.js";
 import { RUNTIME_ROOT } from "../constants.js";
 import { SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD, SMALL_PROJECT_RECURRENCE_THRESHOLD } from "../knowledge-store.js";
@@ -7,6 +10,19 @@ function normalizePatterns(patterns, fallback) {
         return [...fallback];
     return patterns.map((value) => value.trim()).filter((value) => value.length > 0);
 }
+function resolveCliEntrypointForGeneratedHook() {
+    const here = fileURLToPath(import.meta.url);
+    const candidates = [
+        path.resolve(path.dirname(here), "..", "cli.js"),
+        path.resolve(path.dirname(here), "..", "..", "dist", "cli.js")
+    ];
+    for (const candidate of candidates) {
+        // Synchronous probe runs only during cclaw-cli init/sync generation.
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
 /**
  * Node-only hook runtime (single entrypoint).
  *
@@ -26,6 +42,7 @@ export function nodeHookRuntimeScript(options = {}) {
         options.compoundRecurrenceThreshold >= 1
         ? options.compoundRecurrenceThreshold
         : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -47,6 +64,7 @@ const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = ${JSON.stringify(tddProductionPathP
 const COMPOUND_RECURRENCE_THRESHOLD = ${JSON.stringify(compoundRecurrenceThreshold)};
 const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD)};
 const SMALL_PROJECT_RECURRENCE_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_RECURRENCE_THRESHOLD)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
 
 function resolveStrictness() {
   return process.env.CCLAW_STRICTNESS === "strict" ? "strict" : DEFAULT_STRICTNESS;
@@ -303,8 +321,28 @@ async function readStdin() {
 }
 
 async function runCclawInternal(root, args, options = {}) {
+  const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  if (!cliEntrypoint || String(cliEntrypoint).trim().length === 0) {
+    return {
+      code: 1,
+      stdout: "",
+      stderr: "[cclaw] hook: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync or npx cclaw-cli upgrade.\\n",
+      missingBinary: true
+    };
+  }
+  try {
+    const stat = await fs.stat(cliEntrypoint);
+    if (!stat.isFile()) throw new Error("not-file");
+  } catch {
+    return {
+      code: 1,
+      stdout: "",
+      stderr: "[cclaw] hook: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync or npx cclaw-cli upgrade.\\n",
+      missingBinary: true
+    };
+  }
+
   return await new Promise((resolve) => {
-    const isWindows = process.platform === "win32";
     const captureStdout = options && options.captureStdout === true;
     let settled = false;
     let stdout = "";
@@ -316,22 +354,18 @@ async function runCclawInternal(root, args, options = {}) {
     };
     let child;
     try {
-      child = spawn(
-        isWindows ? "cmd.exe" : "cclaw",
-        isWindows ? ["/d", "/s", "/c", "cclaw", "internal", ...args] : ["internal", ...args],
-        {
+      child = spawn(process.execPath, [cliEntrypoint, "internal", ...args], {
         cwd: root,
         env: process.env,
         stdio: ["ignore", captureStdout ? "pipe" : "ignore", "pipe"]
-      }
-      );
+      });
     } catch (error) {
       const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
       finalize({
         code: 1,
         stdout,
         stderr,
-        missingBinary: code === "ENOENT" || (isWindows && code === "EINVAL")
+        missingBinary: code === "ENOENT"
       });
       return;
     }
@@ -355,7 +389,7 @@ async function runCclawInternal(root, args, options = {}) {
         code: 1,
         stdout,
         stderr,
-        missingBinary: code === "ENOENT" || (isWindows && code === "EINVAL")
+        missingBinary: code === "ENOENT"
       });
     });
     child.on("close", (code, signal) => {
@@ -368,15 +402,11 @@ async function runCclawInternal(root, args, options = {}) {
         });
         return;
       }
-      const stderrLower = stderr.toLowerCase();
-      const missingBinary = isWindows
-        ? stderrLower.includes("is not recognized as an internal or external command")
-        : false;
       finalize({
         code: typeof code === "number" ? code : 1,
         stdout,
         stderr,
-        missingBinary
+        missingBinary: false
       });
     });
   });
@@ -1562,12 +1592,13 @@ async function handleVerifyCurrentState(runtime) {
   const mode = resolveStrictness();
   const result = await runCclawInternal(runtime.root, ["verify-current-state", "--quiet"]);
   if (result.missingBinary) {
-    emitAdvisoryContext(
-      runtime,
-      "verify-current-state",
-      "Cclaw verify-current-state requires cclaw binary on PATH."
-    );
-    process.stderr.write("[cclaw] hook: cclaw binary is required for verify-current-state\\n");
+    const message = result.stderr.trim().length > 0
+      ? result.stderr.trim()
+      : "Cclaw verify-current-state requires a local Node runtime entrypoint.";
+    emitAdvisoryContext(runtime, "verify-current-state", message);
+    process.stderr.write(result.stderr.trim().length > 0
+      ? result.stderr
+      : "[cclaw] hook: local Node runtime entrypoint is required for verify-current-state\\n");
     return 1;
   }
   if (mode === "strict") {

package/dist/content/opencode-plugin.js

@@ -564,25 +564,25 @@ export default function cclawPlugin(ctx) {
             : typeof payload;
         logToFile("unknown event payload keys: " + keys);
       }
-      // session.compacted must run pre-compact BEFORE refreshing the bootstrap
-      // cache, otherwise the injected system prompt still shows the pre-compact
-      // digest/state until the next lifecycle event.
-      if (eventType === "session.compacted") {
-        await runHookScript("pre-compact", eventData ?? {});
-      }
-      if (
+      const isSessionLifecycle =
         eventType === "session.created" ||
         eventType === "session.resumed" ||
         eventType === "session.compacted" ||
         eventType === "session.cleared" ||
-        eventType === "session.updated"
-      ) {
-        // Avoid writing directly to stdout in lifecycle hooks because it can
-        // interfere with OpenCode TUI rendering. Bootstrap is injected via
-        // the system transform hook instead.
-        // session.updated covers config reloads and artifact/rules edits
-        // that happen mid-session; without it the cache would stay stale
-        // until the next compaction or restart.
+        eventType === "session.updated";
+      // session.compacted must run pre-compact BEFORE canonical rehydration,
+      // otherwise the injected system prompt can show the pre-compact
+      // digest/state until the next lifecycle event.
+      if (eventType === "session.compacted") {
+        await runHookScript("pre-compact", eventData ?? {});
+      }
+      if (isSessionLifecycle) {
+        // Keep OpenCode aligned with Claude/Cursor/Codex: session-start is
+        // the canonical rehydrate path that refreshes derived state such as
+        // Ralph Loop, compound readiness, and hook-error breadcrumbs. The
+        // plugin refreshes its local bootstrap cache afterwards so the system
+        // transform sees the side effects from the hook runtime.
+        await runHookScript("session-start", eventData ?? {});
         await refreshBootstrapCache(true);
       }
       if (eventType === "session.idle") {

package/dist/content/start-command.js

@@ -85,8 +85,10 @@ ${conversationLanguagePolicyMarkdown()}
    > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
    > Override? (A) keep \`<recommended>\`  (B) switch track  (C) cancel.
    If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
-10. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, medium/standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
-11. Write the prompt to \`.cclaw/artifacts/00-idea.md\` with the following header lines: \`Class:\` (from Phase 0), \`Track:\` (chosen track + matched heuristic), \`Stack:\` (from Phase 2 detection, or \`unknown\`), and a \`Discovered context\` section if Phase 1/seed recall found references.
+10. Start the tracked flow only through the managed helper:
+   \`cclaw internal start-flow --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
+   If this helper fails, STOP and report the exact command/output. Do **not** manually edit \`${flowPath}\`.
+11. The helper persists \`${flowPath}\`, computes \`skippedStages\`, sets the first stage for the track, resets the gate catalog, and writes \`.cclaw/artifacts/00-idea.md\`.
 12. Load the **first-stage skill for the chosen track** and its command file:
     - quick → \`.cclaw/skills/specification-authoring/SKILL.md\`
     - medium/standard → \`.cclaw/skills/brainstorming/SKILL.md\`
@@ -100,7 +102,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 1. Surface the new evidence in plain text.
 2. Propose the updated \`Class\` + \`Track\` with a one-line reason.
 3. Use the Decision Protocol to let the user accept, override, or cancel.
-4. On acceptance: update \`00-idea.md\` with a \`Reclassification:\` entry (old → new, reason, ISO timestamp) and update \`flow-state.json\` accordingly — do NOT rewrite prior artifacts, they stay as history.
+4. On acceptance: run \`cclaw internal start-flow --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report the exact output; do NOT manually edit \`flow-state.json\`.
 
 ### Without prompt (\`/cc\`)
 
@@ -179,13 +181,12 @@ ${conversationLanguagePolicyMarkdown()}
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers.
-8. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`medium\`/ \`standard\` → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\`). Reset gate catalog.
-9. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt plus header lines: \`Class:\`, \`Track:\`, \`Stack:\`, and a \`Discovered context\` section from Phase 0.5/1.
-10. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
+8. Run the managed start helper: \`cclaw internal start-flow --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP and report the exact command/output; do not manually edit flow state.
+9. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for medium/standard, \`specification-authoring\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 
-If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. Record \`Reclassification:\` in \`00-idea.md\` with old/new class and a one-line reason. Do NOT rewrite prior artifacts — they stay as history.
+If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`cclaw internal start-flow --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. Do NOT rewrite prior artifacts or manually edit flow-state.
 
 ### Path B: \`/cc\` (no arguments)
 

package/dist/doctor.js

@@ -73,6 +73,61 @@ function collectHookCommands(value) {
     const nested = collectHookCommands(obj.hooks);
     return [...direct, ...nested];
 }
+function extractGeneratedCliEntrypoints(scriptContent) {
+    const paths = [];
+    for (const match of scriptContent.matchAll(/const\s+CCLAW_CLI_ENTRYPOINT\s*=\s*("(?:\\.|[^"\\])*"|null);/gu)) {
+        const raw = match[1];
+        if (!raw || raw === "null")
+            continue;
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === "string" && parsed.trim().length > 0) {
+                paths.push(parsed);
+            }
+        }
+        catch {
+            // malformed generated constant; treat below as missing/unusable
+        }
+    }
+    return paths;
+}
+async function generatedCliEntrypointsOk(projectRoot) {
+    const hookScripts = ["stage-complete.mjs", "run-hook.mjs"];
+    const problems = [];
+    const checked = [];
+    for (const script of hookScripts) {
+        const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);
+        if (!(await exists(scriptPath)))
+            continue;
+        const content = await fs.readFile(scriptPath, "utf8");
+        const entrypoints = extractGeneratedCliEntrypoints(content);
+        if (entrypoints.length === 0) {
+            problems.push(`${RUNTIME_ROOT}/hooks/${script} has no local CLI entrypoint`);
+            continue;
+        }
+        for (const entrypoint of entrypoints) {
+            checked.push(`${RUNTIME_ROOT}/hooks/${script} -> ${entrypoint}`);
+            try {
+                const stat = await fs.stat(entrypoint);
+                if (!stat.isFile()) {
+                    problems.push(`${RUNTIME_ROOT}/hooks/${script} points to non-file ${entrypoint}`);
+                }
+            }
+            catch {
+                problems.push(`${RUNTIME_ROOT}/hooks/${script} points to missing ${entrypoint}`);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        return { ok: false, details: problems.join("; ") };
+    }
+    return {
+        ok: true,
+        details: checked.length > 0
+            ? `local CLI entrypoints valid: ${checked.join("; ")}`
+            : "local CLI entrypoint check skipped because generated hook scripts are absent"
+    };
+}
 function extractUserPromptFromIdeaArtifact(markdown) {
     const normalized = markdown.replace(/\r\n?/gu, "\n");
     const heading = /^##\s+User prompt\s*$/imu.exec(normalized);
@@ -617,6 +672,12 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
         }
     }
+    const localCliEntrypoints = await generatedCliEntrypointsOk(projectRoot);
+    checks.push({
+        name: "hook:script:local_cli_entrypoint",
+        ok: localCliEntrypoints.ok,
+        details: localCliEntrypoints.details
+    });
     // Hook JSON files per harness. OpenCode ships hooks through its plugin
     // system (covered below). Codex joined the managed list in v0.40.0 — Codex
     // CLI ≥ v0.114 consumes `.codex/hooks.json` behind the `codex_hooks`
@@ -934,7 +995,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     for (const candidate of windowsHookConfigCandidates) {
         if (!(await exists(candidate)))
             continue;
-        const content = await fs.readFile(candidate, "utf8");
+        const content = (await fs.readFile(candidate, "utf8")).replace(/\\/gu, "/");
         if (/bash\s+\.cclaw\/hooks\/|\.cclaw\/hooks\/(?:session-start|stop-handoff|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh/u.test(content)) {
             legacyDispatchFiles.push(path.relative(projectRoot, candidate));
         }

package/dist/install.js

@@ -128,7 +128,6 @@ const DEPRECATED_HOOK_FILES = [
     "_lib.sh",
     "session-start.sh",
     "stop-checkpoint.sh",
-    "run-hook.cmd",
     "stage-complete.sh",
     "pre-compact.sh",
     "prompt-guard.sh",

package/dist/internal/advance-stage.js

@@ -8,10 +8,10 @@ import { stageSchema } from "../content/stage-schema.js";
 import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
 import { extractMarkdownSectionBody, parseLearningsSection } from "../artifact-linter.js";
-import { getAvailableTransitions, getTransitionGuards, isFlowTrack } from "../flow-state.js";
+import { getAvailableTransitions, getTransitionGuards, isFlowTrack, createInitialFlowState } from "../flow-state.js";
 import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
-import { FLOW_STAGES } from "../types.js";
+import { FLOW_STAGES, TRACK_STAGES } from "../types.js";
 import { runCompoundReadinessCommand } from "./compound-readiness.js";
 import { runHookManifestCommand } from "./hook-manifest.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
@@ -507,6 +507,70 @@ function parseHookArgs(tokens) {
     }
     return { hookName: normalizedHook };
 }
+function parseStartFlowArgs(tokens) {
+    let track;
+    let className;
+    let prompt;
+    let reason;
+    let stack;
+    let forceReset = false;
+    let reclassify = false;
+    let quiet = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        const readValue = (flag) => {
+            if (token.startsWith(`${flag}=`))
+                return token.slice(flag.length + 1);
+            if (token === flag && nextToken && !nextToken.startsWith("--")) {
+                i += 1;
+                return nextToken;
+            }
+            throw new Error(`${flag} requires a value.`);
+        };
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--force-reset") {
+            forceReset = true;
+            continue;
+        }
+        if (token === "--reclassify") {
+            reclassify = true;
+            continue;
+        }
+        if (token === "--track" || token.startsWith("--track=")) {
+            const raw = readValue("--track").trim();
+            if (!isFlowTrack(raw)) {
+                throw new Error(`--track must be one of: standard, medium, quick.`);
+            }
+            track = raw;
+            continue;
+        }
+        if (token === "--class" || token.startsWith("--class=")) {
+            className = readValue("--class").trim();
+            continue;
+        }
+        if (token === "--prompt" || token.startsWith("--prompt=")) {
+            prompt = readValue("--prompt").trim();
+            continue;
+        }
+        if (token === "--reason" || token.startsWith("--reason=")) {
+            reason = readValue("--reason").trim();
+            continue;
+        }
+        if (token === "--stack" || token.startsWith("--stack=")) {
+            stack = readValue("--stack").trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal start-flow: ${token}`);
+    }
+    if (!track) {
+        throw new Error("internal start-flow requires --track=<standard|medium|quick>.");
+    }
+    return { track, className, prompt, reason, stack, forceReset, reclassify, quiet };
+}
 async function buildValidationReport(projectRoot, flowState) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
     const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
@@ -827,6 +891,78 @@ async function runVerifyCurrentState(projectRoot, args, io) {
     }
     return validation.ok ? 0 : 1;
 }
+function firstIncompleteStageForTrack(track, completedStages) {
+    const completed = new Set(completedStages);
+    const stages = TRACK_STAGES[track];
+    return stages.find((stage) => !completed.has(stage)) ?? stages[stages.length - 1] ?? "brainstorm";
+}
+async function appendIdeaArtifact(projectRoot, args, previous) {
+    const artifactPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "00-idea.md");
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    const now = new Date().toISOString();
+    if (args.reclassify) {
+        const entry = [
+            "",
+            `Reclassification: ${now}`,
+            `- From: ${previous?.track ?? "unknown"}`,
+            `- To: ${args.track}`,
+            `- Class: ${args.className || "unspecified"}`,
+            `- Reason: ${args.reason || "unspecified"}`
+        ].join("\n") + "\n";
+        await fs.appendFile(artifactPath, entry, "utf8");
+        return;
+    }
+    const body = [
+        "# Idea",
+        `Class: ${args.className || "unspecified"}`,
+        `Track: ${args.track}${args.reason ? ` (${args.reason})` : ""}`,
+        `Stack: ${args.stack || "unknown"}`,
+        "",
+        "## User prompt",
+        args.prompt || "(not provided)",
+        "",
+        "## Discovered context",
+        "- None recorded by managed start-flow."
+    ].join("\n") + "\n";
+    await fs.writeFile(artifactPath, body, "utf8");
+}
+async function runStartFlow(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const hasProgress = current.completedStages.length > 0;
+    if (!args.reclassify && hasProgress && !args.forceReset) {
+        io.stderr.write("cclaw internal start-flow: refusing to reset an active flow with completed stages without --force-reset. Ask the user before resetting.\n");
+        return 1;
+    }
+    let nextState;
+    if (args.reclassify) {
+        const completedInNewTrack = current.completedStages.filter((stage) => TRACK_STAGES[args.track].includes(stage));
+        const fresh = createInitialFlowState({ activeRunId: current.activeRunId, track: args.track });
+        nextState = {
+            ...fresh,
+            completedStages: completedInNewTrack,
+            currentStage: firstIncompleteStageForTrack(args.track, completedInNewTrack),
+            rewinds: current.rewinds,
+            staleStages: current.staleStages
+        };
+    }
+    else {
+        nextState = createInitialFlowState({ track: args.track });
+    }
+    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    await appendIdeaArtifact(projectRoot, args, current);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "start-flow",
+            reclassify: args.reclassify,
+            track: nextState.track,
+            currentStage: nextState.currentStage,
+            skippedStages: nextState.skippedStages,
+            activeRunId: nextState.activeRunId
+        }, null, 2)}\n`);
+    }
+    return 0;
+}
 async function runHookCommand(projectRoot, args, io) {
     const runHookPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "run-hook.mjs");
     try {
@@ -865,13 +1001,16 @@ async function runHookCommand(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
         return 1;
     }
     try {
         if (subcommand === "advance-stage") {
             return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
         }
+        if (subcommand === "start-flow") {
+            return await runStartFlow(projectRoot, parseStartFlowArgs(tokens), io);
+        }
         if (subcommand === "verify-flow-state-diff") {
             return await runVerifyFlowStateDiff(projectRoot, parseVerifyFlowStateDiffArgs(tokens), io);
         }
@@ -896,7 +1035,7 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
         return 1;
     }
     catch (err) {

package/package.json

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