cclaw-cli 0.51.4 → 0.51.6

package/dist/content/hooks.d.ts

@@ -1,3 +1,4 @@
+export declare function startFlowScript(): string;
 export declare function stageCompleteScript(): string;
 export declare function runHookCmdScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -16,6 +16,128 @@ function resolveCliEntrypointForGeneratedHook() {
     }
     return null;
 }
+function internalHelperScript(helperName, internalSubcommand, usage) {
+    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    return `#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+
+const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const HELPER_NAME = ${JSON.stringify(helperName)};
+const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
+const USAGE = ${JSON.stringify(usage)};
+
+async function detectRoot() {
+  const candidates = [
+    process.env.CCLAW_PROJECT_ROOT,
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_DIR,
+    process.env.CURSOR_PROJECT_ROOT,
+    process.env.OPENCODE_PROJECT_DIR,
+    process.env.OPENCODE_PROJECT_ROOT,
+    process.cwd()
+  ].filter((value) => typeof value === "string" && value.length > 0);
+
+  for (const candidate of candidates) {
+    try {
+      const runtimePath = path.join(candidate, RUNTIME_ROOT);
+      const stat = await fs.stat(runtimePath);
+      if (stat.isDirectory()) return candidate;
+    } catch {
+      // continue
+    }
+  }
+  return candidates[0] || process.cwd();
+}
+
+function printUsage() {
+  process.stderr.write(USAGE + "\\n");
+}
+
+async function main() {
+  const [, , ...flags] = process.argv;
+  if (flags.includes("--help") || flags.includes("-h")) {
+    printUsage();
+    return;
+  }
+
+  const root = await detectRoot();
+  const runtimePath = path.join(root, RUNTIME_ROOT);
+  try {
+    const stat = await fs.stat(runtimePath);
+    if (!stat.isDirectory()) throw new Error("not-dir");
+  } catch {
+    process.stderr.write("[cclaw] " + HELPER_NAME + ": runtime root not found at " + runtimePath + "\\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
+    process.stderr.write(
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const stat = await fs.stat(cliEntrypoint);
+    if (!stat.isFile()) throw new Error("not-file");
+  } catch {
+    process.stderr.write(
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const child = spawn(process.execPath, [cliEntrypoint, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+    cwd: root,
+    env: process.env,
+    stdio: "inherit"
+  });
+  let spawnErrored = false;
+
+  child.on("error", (error) => {
+    spawnErrored = true;
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT") {
+      process.stderr.write(
+        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
+      );
+    } else {
+      process.stderr.write(
+        "[cclaw] " + HELPER_NAME + ": failed to invoke local Node runtime (" +
+          (error instanceof Error ? error.message : String(error)) +
+          ").\\n"
+      );
+    }
+    process.exitCode = 1;
+  });
+
+  child.on("close", (code, signal) => {
+    if (spawnErrored) {
+      process.exitCode = 1;
+      return;
+    }
+    if (signal) {
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = typeof code === "number" && code >= 0 ? code : 1;
+  });
+}
+
+void main();
+`;
+}
+export function startFlowScript() {
+    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
+}
 export function stageCompleteScript() {
     const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
     return `#!/usr/bin/env node

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:
+   \`node .cclaw/hooks/start-flow.mjs --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 \`node .cclaw/hooks/start-flow.mjs --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: \`node .cclaw/hooks/start-flow.mjs --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 \`node .cclaw/hooks/start-flow.mjs --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", "start-flow.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);
@@ -589,6 +644,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         "run-hook.mjs",
         "run-hook.cmd",
         "stage-complete.mjs",
+        "start-flow.mjs",
         "opencode-plugin.mjs"
     ]) {
         const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);
@@ -617,6 +673,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 +996,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

@@ -12,7 +12,7 @@ import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-co
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.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";
@@ -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",
@@ -706,6 +705,7 @@ async function writeHooks(projectRoot, config) {
         strictLaws: config.ironLaws?.strictLaws
     }), null, 2)}\n`);
     await writeFileSafe(path.join(hooksDir, "stage-complete.mjs"), stageCompleteScript());
+    await writeFileSafe(path.join(hooksDir, "start-flow.mjs"), startFlowScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.mjs"), nodeHookRuntimeScript({
         strictness: effectiveStrictness,
         tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
@@ -718,6 +718,7 @@ async function writeHooks(projectRoot, config) {
     try {
         for (const script of [
             "stage-complete.mjs",
+            "start-flow.mjs",
             "run-hook.mjs",
             "run-hook.cmd",
             "opencode-plugin.mjs"

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.4",
+  "version": "0.51.6",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {