cclaw-cli 0.51.0 → 0.51.2

package/README.md

@@ -443,8 +443,7 @@ Derived diagnostics are produced on demand by `cclaw doctor`.
 
 ## CLI reference
 
-The CLI is deliberately small. Everything operational happens inside
-your harness.
+`cclaw-cli` is deliberately small: it installs, syncs, upgrades, diagnoses, and removes the generated harness runtime. Day-to-day flow work happens inside your harness via `/cc*` commands and Node hooks.
 
 ```bash
 npx cclaw-cli                   # launches interactive setup (or prints
@@ -456,6 +455,8 @@ npx cclaw-cli uninstall         # remove .cclaw + generated harness shims
 npx cclaw-cli --version
 ```
 
+The generated `node .cclaw/hooks/stage-complete.mjs <stage>` helper is the canonical stage-closeout path and must not require a runtime `cclaw` binary in `PATH`.
+
 For CI or scripted installs, `cclaw-cli init --harnesses=<list>
 --no-interactive` is the non-interactive form. All other tunables
 (prompt-guard strictness, TDD enforcement, language rule packs, track

package/dist/content/closeout-guidance.js

@@ -31,7 +31,7 @@ export function closeoutSubstateProtocolBullets() {
     session transcripts for matching historical learnings; only do it after opt-in.
     Ask **one** structured question (apply / skip) per candidate cluster or a
     single accept-all / skip choice, then advance substate.
-  - \`"ready_to_archive"\` -> run \`cclaw archive\` (or \`cclaw archive --name=<slug>\`) and reset state.
+  - \`"ready_to_archive"\` -> run \`npx cclaw-cli archive\` (or \`npx cclaw-cli archive --name=<slug>\`) and reset state.
   - \`"archived"\` (transient) -> report "run archived" and stop.`;
 }
 export function closeoutFlowMapSentence() {

package/dist/content/core-agents.js

@@ -1,11 +1,4 @@
-/**
- * Agent persona content for cclaw.
- *
- * cclaw materializes markdown agent definitions (`.md` with YAML frontmatter)
- * under `.cclaw/agents/` for harness delegation. Research work that does not
- * need isolated subagent context lives in `.cclaw/skills/research/*.md`
- * playbooks and is executed in-thread by the primary agent.
- */
+import { conversationLanguagePolicyBullets } from "./language-policy.js";
 function yamlScalarString(value) {
     // JSON double-quoted strings are valid YAML scalars and escape reliably.
     return JSON.stringify(value);
@@ -196,6 +189,9 @@ ${agent.body}
 
 ## Rules
 
+## Conversation Language Policy
+
+${conversationLanguagePolicyBullets()}
 - Cite file:line for every finding
 - Do not make changes outside your specialist domain
 - Report findings with severity classification

package/dist/content/hooks.js

@@ -1,12 +1,31 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { RUNTIME_ROOT } from "../constants.js";
+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.
+        // The generated hook receives a concrete path and does not need a global bin.
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
 export function stageCompleteScript() {
+    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, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
 
 async function detectRoot() {
   const candidates = [
@@ -58,27 +77,29 @@ async function main() {
     return;
   }
 
-  if (process.platform === "win32") {
-    const probe = spawnSync("where", ["cclaw"], {
-      cwd: root,
-      env: process.env,
-      stdio: "ignore"
-    });
-    if ((probe.status ?? 1) !== 0) {
-      process.stderr.write(
-        "[cclaw] stage-complete: cclaw binary not found in PATH. Install cclaw CLI and rerun stage completion.\\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] stage-complete: 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] stage-complete: 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 isWindows = process.platform === "win32";
   const child = spawn(
-    isWindows ? "cmd.exe" : "cclaw",
-    isWindows
-      ? ["/d", "/s", "/c", "cclaw", "internal", "advance-stage", stage, ...flags]
-      : ["internal", "advance-stage", stage, ...flags],
+    process.execPath,
+    [cliEntrypoint, "internal", "advance-stage", stage, ...flags],
     {
     cwd: root,
     env: process.env,
@@ -92,11 +113,11 @@ async function main() {
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
     if (code === "ENOENT") {
       process.stderr.write(
-        "[cclaw] stage-complete: cclaw binary not found in PATH. Install cclaw CLI and rerun stage completion.\\n"
+        "[cclaw] stage-complete: node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
       );
     } else {
       process.stderr.write(
-        "[cclaw] stage-complete: failed to invoke cclaw internal advance-stage (" +
+        "[cclaw] stage-complete: failed to invoke local Node advance-stage runtime (" +
           (error instanceof Error ? error.message : String(error)) +
           ").\\n"
       );
@@ -134,7 +155,7 @@ set "RUNTIME=%HOOK_DIR%run-hook.mjs"
 where node >nul 2>nul
 if %ERRORLEVEL% neq 0 (
   REM Best-effort: missing node should not block harness execution loops.
-  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run cclaw doctor. >&2
+  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor. >&2
   exit /b 0
 )
 node "%RUNTIME%" %*
@@ -146,7 +167,7 @@ if [ "$#" -lt 1 ]; then
   exit 1
 fi
 if ! command -v node >/dev/null 2>&1; then
-  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run cclaw doctor." >&2
+  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor." >&2
   exit 0
 fi
 exec node "\${SCRIPT_DIR}/run-hook.mjs" "$@"

package/dist/content/ideate-command.js

@@ -1,6 +1,7 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { resolveIdeateFrames } from "./ideate-frames.js";
 import { ideateStructuredAskToolsWithFallback } from "./decision-protocol.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
 /**
@@ -43,6 +44,7 @@ same session, or save/discard the backlog.
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 - Ideate mode only. Never mutate \`.cclaw/state/flow-state.json\`.
 - Every recommendation cites evidence from the current repository
   (file path, command output, or knowledge-store entry id).
@@ -125,6 +127,7 @@ repository. Will persist a ranked backlog to
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 - Do not start coding in ideate mode.
 - Do not mutate \`.cclaw/state/flow-state.json\` — ideate mode sits outside
   the critical-path flow.

package/dist/content/language-policy.d.ts

@@ -0,0 +1,2 @@
+export declare function conversationLanguagePolicyMarkdown(): string;
+export declare function conversationLanguagePolicyBullets(): string;

package/dist/content/language-policy.js

@@ -0,0 +1,13 @@
+export function conversationLanguagePolicyMarkdown() {
+    return `## Conversation Language Policy
+
+- Infer the user-facing language from the latest substantive user message.
+- Write user-facing prose, summaries, recommendations, and structured question text/options in that language unless the user asks otherwise.
+- Do not translate stable machine surfaces: commands, file paths, stage ids, gate ids, JSON keys, enum/status values, artifact headings/frontmatter, logs, code identifiers, and quoted source text.
+- If the request mixes languages, use the language of the actual ask sentence for narrative output.
+`;
+}
+export function conversationLanguagePolicyBullets() {
+    return `- User-facing narrative follows the latest substantive user message language.
+- Do not translate commands, paths, ids, JSON keys/enums, artifact headings, logs, code identifiers, or quoted source.`;
+}

package/dist/content/learnings.js

@@ -64,7 +64,9 @@ Knowledge capture is now stage-native:
   3. writes a harvest marker into the artifact.
 
 Manual/query operations (search, backfill, curation) use this skill when the
-user asks for knowledge work.
+user asks for knowledge work. If a stage artifact contains JSON learnings but
+\`${KNOWLEDGE_PATH}\` did not change, the missing step is almost always running
+\`node .cclaw/hooks/stage-complete.mjs <stage>\` successfully.
 
 ## HARD-GATE
 

package/dist/content/meta-skill.js

@@ -1,3 +1,4 @@
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { CLOSEOUT_CHAIN, closeoutChainInline, closeoutFlowMapSentence, closeoutProtocolBehaviorSentence } from "./closeout-guidance.js";
 export const META_SKILL_NAME = "using-cclaw";
 export function usingCclawSkillMarkdown() {
@@ -18,6 +19,7 @@ description: "Routing brain for cclaw. Decide whether to start/resume a stage, a
 
 If the user explicitly overrides a stage rule, record it in the artifact.
 
+${conversationLanguagePolicyMarkdown()}
 ## Skill-before-response gate
 
 If \`.cclaw/state/flow-state.json\` exists and \`currentStage\` is set,
@@ -60,7 +62,7 @@ Task arrives
   ├─ Knowledge operation? -> load the learnings skill
   ├─ Read-only workspace view? -> /cc-view [status|tree|diff]
   ├─ Normal post-ship closeout? -> /cc-next drives ${closeoutChainInline()}
-  └─ Explicit early archival/reset? -> cclaw archive [--name=<slug>]
+  └─ Explicit early archival/reset? -> npx cclaw-cli archive [--name=<slug>]
 \`\`\`
 
 ## Task classification
@@ -84,7 +86,7 @@ Before stage work:
 ## Platform reliability notes
 
 - Managed hook dispatch uses \`.cclaw/hooks/run-hook.cmd\` (cross-platform wrapper).
-- If hooks fail due missing runtime deps (for example \`node\` not on \`PATH\`), run \`cclaw doctor\` before continuing.
+- If hooks fail due missing runtime deps (for example \`node\` not on \`PATH\`), run \`npx cclaw-cli doctor\` before continuing.
 - Prefer cross-platform commands in artifacts/examples (\`npm test\`, \`pnpm test\`, \`python -m pytest\`, etc.) over shell-specific aliases whenever possible.
 
 ## Stage quick map
@@ -93,11 +95,10 @@ Use \`/cc <idea>\` for new work, \`/cc-next\` for progression and closeout, \`/c
 
 ## Main vs Operator Surfaces
 
-- **Main workflow:** \`/cc\`, \`/cc-next\`, \`/cc-ideate\`, \`/cc-view status\`.
-- **Operator/support:** \`cclaw doctor\`, \`cclaw sync\`, \`cclaw archive\`,
-  \`/cc-view tree\`, and \`/cc-view diff\`.
-- Use operator/support surfaces only for install/runtime diagnosis, explicit
-  archival, or deeper inspection. Do not make them part of the happy path.
+- **Main workflow:** \`/cc\`, \`/cc-next\`, \`/cc-ideate\`, \`/cc-view status\`, and \`node .cclaw/hooks/stage-complete.mjs <stage>\` inside the installed harness runtime.
+- **Installer/support surface:** \`npx cclaw-cli init\`, \`npx cclaw-cli sync\`, \`npx cclaw-cli upgrade\`, \`npx cclaw-cli doctor\`, and explicit support/archive actions. Do not ask users to install or run a \`cclaw\` binary during normal stage flow.
+- **Read-only support:** \`/cc-view tree\` and \`/cc-view diff\`.
+- Use operator/support surfaces only for install/runtime diagnosis, explicit archival, or deeper inspection. Do not make them part of the happy path.
 
 ## Whole flow map
 

package/dist/content/next-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { stageSchema } from "./stage-schema.js";
 import { closeoutChainInline, closeoutNextCommandGuidance, closeoutSubstateInline, closeoutSubstateProtocolBullets } from "./closeout-guidance.js";
 import { stageSkillFolder } from "./skills.js";
@@ -65,6 +66,7 @@ This is the only progression command the user needs to drive the entire flow. St
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 - **Do not** invent gate completion: use only \`${flowPath}\` plus observable evidence in repo artifacts.
 - **Do not** skip stages: advance only from \`currentStage\` to its configured successor.
 - ${closeoutNextCommandGuidance()}
@@ -170,6 +172,7 @@ description: "The primary progression command. Reads flow state, starts/resumes
 
 ## Operator Output Contract
 
+${conversationLanguagePolicyMarkdown()}
 Default output should be compact, like OMC/OMX operator surfaces:
 
 \`\`\`
@@ -243,7 +246,7 @@ by inspecting ${closeoutSubstateInline()}:
 | \`idle\` / missing      | Flip to \`retro_review\` and start retro protocol     |
 | \`retro_review\`        | Draft/update \`09-retro.md\`, ask accept/edit/skip  |
 | \`compound_review\`     | Compound closeout: overlap scan, refresh/supersede, ask approve/skip |
-| \`ready_to_archive\`    | Run \`cclaw archive\`; reset flow-state on success |
+| \`ready_to_archive\`    | Run \`npx cclaw-cli archive\`; reset flow-state on success |
 | \`archived\`            | Report "run archived"; stop                         |
 
 Each step owns its own state transition. \`/cc-next\` keeps retro and compound

package/dist/content/node-hooks.js

@@ -1066,9 +1066,7 @@ async function handleStopHandoff(runtime) {
     state.activeRunId +
     "). Active artifacts stay in " +
     RUNTIME_ROOT +
-    "/artifacts until cclaw archive. Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match current intent, (3) if you discovered a non-obvious rule/pattern, append one strict-schema JSON line to " +
-    RUNTIME_ROOT +
-    "/knowledge.jsonl, (4) commit or revert pending changes.";
+    "/artifacts until archive. Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match current intent, (3) if you discovered a non-obvious rule/pattern during stage work, add it to the current artifact ## Learnings section so stage-complete can harvest it, (4) commit or revert pending changes.";
 
   if (runtime.harness === "cursor") {
     if (loopCount === 0) {

package/dist/content/opencode-plugin.js

@@ -1,7 +1,7 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
 export function opencodePluginJs(_options = {}) {
-    return `// cclaw OpenCode plugin — generated by cclaw sync
+    return `// cclaw OpenCode plugin — generated by npx cclaw-cli sync
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
@@ -98,7 +98,7 @@ export default function cclawPlugin(ctx) {
     if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
 
     parts.push(
-      "If you discover a non-obvious rule or pattern, append one strict-schema JSON line to .cclaw/knowledge.jsonl using type: rule, pattern, lesson, or compound."
+      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. Direct JSONL append is only for explicit manual learnings operations."
     );
 
     const meta = (await readFileText(metaSkillPath)).trim();
@@ -646,7 +646,7 @@ export default function cclawPlugin(ctx) {
         throw new Error(
           "cclaw " + failed + " blocked tool.execute.before.\\n" +
           "Reason: " + detail + "\\n" +
-          "Diagnose: run \`cclaw doctor\` in project root.\\n" +
+          "Diagnose: run \`npx cclaw-cli doctor\` in project root.\\n" +
           "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode,\\n" +
           "or set \`strictness: advisory\` in .cclaw/config.yaml."
         );

package/dist/content/session-hooks.js

@@ -45,7 +45,7 @@ Before ending a session or when context is full:
 
 1. **Verify no pending changes:** All modified files must be either committed or explicitly reverted.
 2. **Update flow state:** Mark the current stage as its actual status (DONE / DONE_WITH_CONCERNS / BLOCKED).
-3. **Write knowledge:** If any non-obvious reusable insight appears, append one strict-schema JSON line to \`.cclaw/knowledge.jsonl\` with type \`rule\`, \`pattern\`, \`lesson\`, or \`compound\`.
+3. **Capture knowledge:** If any non-obvious reusable insight appears during stage work, add a strict JSON bullet to the current artifact \`## Learnings\`; stage completion harvests it into \`.cclaw/knowledge.jsonl\`.
 4. **Leave handoff context:** Put blockers and remaining work in the current stage artifact, not a separate state file.
 
 ### Stop conditions (agent must halt and report)
@@ -98,7 +98,7 @@ export function sessionHooksAgentsMdBlock() {
 
 Session boundary behavior (real hooks inject context automatically; guidelines cover manual steps):
 - **Start:** Hooks inject flow state + knowledge snapshot. Check for in-progress work, show status.
-- **Stop:** Hooks remind about handoff. Verify no pending changes, update flow state, append useful knowledge after overlap check.
+- **Stop:** Hooks remind about handoff. Verify no pending changes, update the current artifact handoff, and capture reusable knowledge in \`## Learnings\`; stage completion harvests it.
 - **Resume:** Re-read state, verify artifact, re-load knowledge, continue from last step. For compound closeout, optional session-history scans require user opt-in.
 
 Skill: \`.cclaw/skills/session/SKILL.md\`

package/dist/content/skills.js

@@ -1,6 +1,7 @@
 import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { stageExamples } from "./examples.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
 function whenNotToUseBlock(items) {
     if (items.length === 0) {
@@ -215,10 +216,11 @@ function completionParametersBlock(schema, track) {
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
 - \`completion helper\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage}\`
+- \`completion helper with evidence\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage} --evidence-json '{"<gate_id>":"<evidence note>"}' --passed=<gate_id>[,<gate_id>]\`
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
-- Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
-- Completion protocol: verify required gates, update the artifact, then use the completion helper.
+- Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
+- Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
 function quickStartBlock(stage, track) {
@@ -357,6 +359,7 @@ If you are about to violate the Iron Law, STOP. No amount of urgency, partial pr
 
 ${quickStartBlock(stage, track)}
 
+${conversationLanguagePolicyMarkdown()}
 ## Philosophy
 ${philosophy.purpose}
 

package/dist/content/stage-common-guidance.js

@@ -1,9 +1,11 @@
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 export function stageCommonGuidanceMarkdown() {
     return `# Common Stage Guidance
 
 Shared guidance loaded by every stage skill. Keep this file concise and stable so
 per-stage skills can stay focused on stage-specific work.
 
+${conversationLanguagePolicyMarkdown()}
 ## Shared completion protocol
 
 - Stage-specific skills expose **Completion Parameters** plus the gates that
@@ -26,8 +28,8 @@ Use this same closeout menu for every stage:
 - **A) Advance** — run \`/cc-next\` and continue the critical path; after \`ship\`, the same command drives \`retro -> compound -> archive\`.
 - **B) Revise this stage** — stay on current stage and apply feedback.
 - **C) Pause / park** — run \`/cc-view status\`, then stop and resume later.
-- **D) Rewind** — run \`cclaw internal rewind <target-stage> "<reason>"\`.
-- **E) Abandon** — only when the user explicitly wants to end a non-ship active run early, archive with \`cclaw archive --skip-retro --retro-reason="<reason>"\`. Once in post-ship closeout, continue \`/cc-next\` through retro/compound/archive instead.
+- **D) Rewind** — run \`npx cclaw-cli internal rewind <target-stage> "<reason>"\` as a support/runtime repair action.
+- **E) Abandon** — only when the user explicitly wants to end a non-ship active run early, archive with \`npx cclaw-cli archive --skip-retro --retro-reason="<reason>"\`. Once in post-ship closeout, continue \`/cc-next\` through retro/compound/archive instead.
 
 Recommendation defaults:
 

package/dist/content/start-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 const START_SKILL_FOLDER = "flow-start";
 const START_SKILL_NAME = "flow-start";
 function flowStatePath() {
@@ -25,6 +26,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 - **Do not** skip reading \`${flowPath}\` — always check current state before acting.
 - **Do not** start implementation stages directly from \`/cc <prompt>\` — always begin at the first stage of the resolved track (brainstorm for medium/standard, spec for quick).
 - **Do not** start a stage pipeline for a task that is not a software change (pure question, non-software task, conversation).
@@ -150,6 +152,7 @@ description: "Unified entry point for the cclaw flow. No args = resume/next. Wit
 
 Do **not** silently discard an existing flow when the user provides a prompt. If completed stages exist, inform and confirm before resetting.
 
+${conversationLanguagePolicyMarkdown()}
 ## Protocol
 
 ### Path A: \`/cc <prompt>\`

package/dist/content/subagents.js

@@ -1,4 +1,5 @@
 import { stageDelegationSummary } from "./stage-schema.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 /**
  * Markdown content generators for Cclaw’s subagent orchestration skills and enhanced
  * specialist payloads. Cclaw materializes static instructions — this module does not
@@ -80,10 +81,10 @@ can enforce phase-appropriate write boundaries. Use separate workers only when t
 
 | Harness | Fallback | Delegation tool | Structured ask | Capability source |
 |---|---|---|---|---|
-| Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`cclaw doctor\` |
-| Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`cclaw doctor\` |
-| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`cclaw doctor\` |
-| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`cclaw doctor\` |
+| Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`npx cclaw-cli doctor\` |
+| Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`npx cclaw-cli doctor\` |
+| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`npx cclaw-cli doctor\` |
+| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`npx cclaw-cli doctor\` |
 
 **Dispatch rules driven by \`subagentFallback\`:**
 
@@ -136,6 +137,7 @@ Concrete per-stage rules so the controller does not have to guess which tier fit
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 **Never dispatch a subagent without a concrete, self-contained task description pasted into the prompt. Do not pass file references the subagent must read to understand its task.**
 
 If you catch yourself writing “read PLAN.md Task 3” or “implement the next unchecked item,” stop: expand the work into explicit text in the Task body before dispatching.
@@ -194,6 +196,7 @@ CONTEXT: {paste relevant file paths, types, patterns}
 CONSTRAINTS: {paste from spec — what NOT to do}
 
 After implementation:
+0. Write user-facing narrative in the parent/user language; keep status tokens unchanged.
 1. Run the full test suite
 2. Report your status: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
 3. If DONE_WITH_CONCERNS, list each concern
@@ -335,6 +338,7 @@ This document bridges **Superpowers-style task isolation** with the **gstack “
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 **Never dispatch parallel IMPLEMENTATION agents that write to the same codebase. Parallel agents are for investigation, analysis, and review ONLY.**
 
 Implementation that touches shared source trees must remain **sequential** unless you have proven disjoint filesystem ownership (rare) and an explicit merge protocol.

package/dist/content/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc-next`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick or medium track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc-next` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive via `cclaw archive`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc-next`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick or medium track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc-next` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive via `npx cclaw-cli archive`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -915,7 +915,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 
 - No completion claim without fresh command evidence in this turn.
 - Do not mark gates passed from memory.
-- Keep evidence in \`.cclaw/artifacts/\`; archive via \`cclaw archive\`.
+- Keep evidence in \`.cclaw/artifacts/\`; archive via \`npx cclaw-cli archive\`.
 
 ## Delegation And Approvals
 

package/dist/content/tree-command.js

@@ -25,7 +25,7 @@ Do not modify state in this command. It is a pure read/render operation.
    \`fulfillmentMode\` / \`evidenceRefs\`.
 3. Inspect \`${artifactsPath()}\` for per-stage artifact presence and stale copies,
    and for the retro artifact \`09-retro.md\`.
-4. Use \`cclaw doctor --explain\` for harness capability status when needed.
+4. Use \`npx cclaw-cli doctor --explain\` for harness capability status when needed.
 5. Render one compact tree:
    - stage marker: passed/current/pending/skipped/stale,
    - gates summary,
@@ -41,7 +41,7 @@ Do not modify state in this command. It is a pure read/render operation.
      then \`next\`; the transient \`archived\` substate surfaces only if the
      archive step failed mid-run.
 7. Append a \`harnesses:\` branch. For each installed harness derive the tier
-   and fallback from cclaw capability metadata; use \`cclaw doctor --explain\`
+   and fallback from cclaw capability metadata; use \`npx cclaw-cli doctor --explain\`
    for remediation details when needed.
 8. If rewind records exist in \`${rewindLogPath()}\`, include latest rewind note in footer.
 

package/dist/content/view-command.js

@@ -2,6 +2,7 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { diffSubcommandMarkdown } from "./diff-command.js";
 import { statusSubcommandMarkdown } from "./status-command.js";
 import { treeSubcommandMarkdown } from "./tree-command.js";
+import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 const VIEW_SKILL_FOLDER = "flow-view";
 const VIEW_SKILL_NAME = "flow-view";
 export function viewCommandContract() {
@@ -18,6 +19,7 @@ Subcommands:
 
 ## HARD-GATE
 
+${conversationLanguagePolicyMarkdown()}
 - \`/cc-view\` is strictly read-only at wrapper level.
 - Do not mutate flow-state or derived state from any subcommand.
 

package/dist/harness-adapters.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
+import { conversationLanguagePolicyMarkdown } from "./content/language-policy.js";
 import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
 import { ironLawsAgentsMdBlock } from "./content/iron-laws.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
@@ -159,6 +160,7 @@ function agentsMdBlock() {
 > Auto-generated by \`cclaw sync\`. Do not edit this managed block manually.
 > Existing project rules in this repository take precedence over cclaw defaults.
 
+${conversationLanguagePolicyMarkdown()}
 ## Anti-Slop Guard
 
 Treat quality as a hard requirement, not style preference:
@@ -377,7 +379,7 @@ Codex CLI v0.89 (Jan 2026). cclaw ships its entry points as skills
 under \`.agents/skills/${skillSlug}/\` so the user can either:
 
 - Type \`/use ${skillSlug}\` at the Codex prompt, or
-- Type \`${slashToken} …\` (or describe the intent in English) — Codex's
+- Type \`${slashToken} …\` (or describe the intent in natural language) — Codex's
   skill matcher picks this skill up via the description frontmatter.
 
 Lifecycle hooks **are** available in Codex CLI v0.114+ (behind the

package/dist/internal/advance-stage.js

@@ -309,6 +309,19 @@ function coerceCandidateFlowState(raw, fallback) {
         stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
     };
 }
+function stringifyGateEvidenceValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value ? "passed" : "failed";
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 function parseEvidenceByGate(raw) {
     if (!raw || raw.trim().length === 0) {
         return {};
@@ -325,12 +338,10 @@ function parseEvidenceByGate(raw) {
     }
     const next = {};
     for (const [key, value] of Object.entries(parsed)) {
-        if (typeof value !== "string")
-            continue;
-        const trimmed = value.trim();
-        if (trimmed.length === 0)
+        const normalized = stringifyGateEvidenceValue(value).trim();
+        if (normalized.length === 0)
             continue;
-        next[key] = trimmed;
+        next[key] = normalized;
     }
     return next;
 }
@@ -381,28 +392,62 @@ function parseAdvanceStageArgs(tokens) {
     let waiveDelegations = [];
     let waiverReason;
     let quiet = false;
-    for (const token of flagTokens) {
+    for (let i = 0; i < flagTokens.length; i += 1) {
+        const token = flagTokens[i];
+        const nextToken = flagTokens[i + 1];
         if (token === "--quiet") {
             quiet = true;
             continue;
         }
+        if (token === "--evidence-json") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--evidence-json requires a JSON object value.");
+            }
+            evidenceJson = nextToken;
+            i += 1;
+            continue;
+        }
         if (token.startsWith("--evidence-json=")) {
-            evidenceJson = token.replace("--evidence-json=", "");
+            evidenceJson = token.slice("--evidence-json=".length);
+            continue;
+        }
+        if (token === "--passed") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--passed requires a comma-separated gate list.");
+            }
+            passed = [...passed, ...parseCsv(nextToken)];
+            i += 1;
             continue;
         }
         if (token.startsWith("--passed=")) {
-            passed = [...passed, ...parseCsv(token.replace("--passed=", ""))];
+            passed = [...passed, ...parseCsv(token.slice("--passed=".length))];
+            continue;
+        }
+        if (token === "--waive-delegation") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waive-delegation requires a comma-separated agent list.");
+            }
+            waiveDelegations = [...waiveDelegations, ...parseCsv(nextToken)];
+            i += 1;
             continue;
         }
         if (token.startsWith("--waive-delegation=")) {
             waiveDelegations = [
                 ...waiveDelegations,
-                ...parseCsv(token.replace("--waive-delegation=", ""))
+                ...parseCsv(token.slice("--waive-delegation=".length))
             ];
             continue;
         }
+        if (token === "--waiver-reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--waiver-reason requires a text value.");
+            }
+            waiverReason = nextToken.trim();
+            i += 1;
+            continue;
+        }
         if (token.startsWith("--waiver-reason=")) {
-            waiverReason = token.replace("--waiver-reason=", "").trim();
+            waiverReason = token.slice("--waiver-reason=".length).trim();
             continue;
         }
         throw new Error(`Unknown flag for internal advance-stage: ${token}`);

package/package.json

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