cclaw-cli 0.5.1 → 0.5.3

package/README.md

@@ -119,7 +119,7 @@ Required repository secret:
 │   └── <activeRunId>/
 │       ├── artifacts/        # canonical run artifacts
 │       ├── run.json
-│       └── 00-handoff.md
+│       └── handoff.md
 └── learnings.jsonl
 ```
 

package/dist/content/contracts.js

@@ -26,7 +26,7 @@ ${schema.hardGate}
 
 ## In / Out
 - **Reads:** ${readsLine}
-- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
+- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot under \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\` is synchronized by cclaw runtime)
 - **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
@@ -35,7 +35,7 @@ ${schema.hardGate}
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
 4. If a canonical run artifact is missing, fallback to the matching file under \`.cclaw/artifacts/\` and record that fallback in the stage artifact.
-5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\` and keep canonical run copy aligned at \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`.
+5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps run snapshots aligned.
 
 ## Gates
 ${gateIds}

package/dist/content/examples.js

@@ -1,5 +1,22 @@
 const STAGE_EXAMPLES = {
-    brainstorm: `### Alternatives comparison
+    brainstorm: `### Clarification sequence (Socratic)
+
+**Q1 (PURPOSE):** "What decision will this demo help your audience make, and who exactly is that audience?"  
+**A1:** "Internal platform team; they should see whether our release flow can be trusted."
+
+**Q2 (SCOPE):** "Which outcomes are explicitly OUT of scope for this demo so we avoid accidental expansion?"  
+**A2:** "No production rollout automation; only release metadata validation + publish safety checks."
+
+**Q3 (BOUNDARIES):** "When release metadata is missing or invalid, what should happen and what should NEVER happen?"  
+**A3:** "Must block release with a clear reason; must never auto-publish anyway."
+
+**Q4 (ENVIRONMENT):** "Where will this run in practice: local only, CI only, or both? How is it installed and invoked?"  
+**A4:** "CI-first in GitHub Actions, but reproducible locally with npm scripts."
+
+**Q5 (CONSTRAINTS):** "What constraints are non-negotiable (runtime deps, latency, compatibility, policy)?"  
+**A5:** "No new runtime dependencies; checks should stay under 2 minutes; compatible with current workflow."
+
+### Alternatives comparison
 
 | Approach | Pros | Cons | Effort | Recommendation |
 | --- | --- | --- | --- | --- |

package/dist/content/hooks.js

@@ -1078,6 +1078,14 @@ export default function cclawPlugin(ctx) {
       payload?.command,
       payload?.tool?.name,
       payload?.tool?.id,
+      payload?.input?.tool,
+      payload?.input?.toolName,
+      payload?.input?.tool_name,
+      payload?.input?.name,
+      payload?.input?.id,
+      payload?.input?.command,
+      payload?.input?.tool?.name,
+      payload?.input?.tool?.id
     ];
     for (const value of candidates) {
       if (typeof value === "string" && value.trim()) return value.trim();
@@ -1085,6 +1093,36 @@ export default function cclawPlugin(ctx) {
     return "unknown";
   }
 
+  function normalizeToolPayload(input, output) {
+    if (typeof output === "undefined") {
+      return input ?? {};
+    }
+    return {
+      input: input ?? {},
+      output: output ?? {}
+    };
+  }
+
+  function resolveEventType(payload) {
+    if (typeof payload === "string") return payload;
+    if (payload && typeof payload === "object") {
+      if (typeof payload.type === "string") return payload.type;
+      if (typeof payload.name === "string") return payload.name;
+      if (payload.event && typeof payload.event === "object") {
+        if (typeof payload.event.type === "string") return payload.event.type;
+        if (typeof payload.event.name === "string") return payload.event.name;
+      }
+    }
+    return "";
+  }
+
+  function resolveEventData(payload) {
+    if (payload && typeof payload === "object" && payload.event && typeof payload.event === "object") {
+      return payload.event;
+    }
+    return payload;
+  }
+
   function appendJsonLine(filePath, value) {
     try {
       appendFileSync(filePath, JSON.stringify(value) + "\\n", "utf8");
@@ -1120,28 +1158,43 @@ export default function cclawPlugin(ctx) {
   }
 
   return {
-    event: async (name, data) => {
-      if (name === "session.created" || name === "session.resumed" || name === "session.compacted" || name === "session.cleared") {
+    event: async (payload) => {
+      const eventType = resolveEventType(payload);
+      const eventData = resolveEventData(payload);
+      if (eventType === "session.created" || eventType === "session.resumed" || eventType === "session.compacted" || eventType === "session.cleared") {
         emitBootstrap();
       }
-      if (name === "session.updated") {
+      if (eventType === "session.updated") {
         // no-op: tracked via activity log
       }
-      if (name === "session.idle") {
+      if (eventType === "session.idle") {
         if (!observationEnabled()) return;
         await runHookScript("summarize-observations.sh");
         await runHookScript("stop-checkpoint.sh", { loop_count: 0 });
       }
-      if (name === "tool.execute.before") {
-        await runHookScript("prompt-guard.sh", data ?? {});
-        await runHookScript("workflow-guard.sh", data ?? {});
-        recordToolEvent("pre", data);
+      if (eventType === "tool.execute.before") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        await runHookScript("prompt-guard.sh", toolPayload);
+        await runHookScript("workflow-guard.sh", toolPayload);
+        recordToolEvent("pre", toolPayload);
       }
-      if (name === "tool.execute.after") {
-        await runHookScript("context-monitor.sh", data ?? {});
-        recordToolEvent("post", data);
+      if (eventType === "tool.execute.after") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        await runHookScript("context-monitor.sh", toolPayload);
+        recordToolEvent("post", toolPayload);
       }
     },
+    "tool.execute.before": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      await runHookScript("prompt-guard.sh", payload);
+      await runHookScript("workflow-guard.sh", payload);
+      recordToolEvent("pre", payload);
+    },
+    "tool.execute.after": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      await runHookScript("context-monitor.sh", payload);
+      recordToolEvent("post", payload);
+    },
     "experimental.chat.system.transform": (payload) => {
       const bootstrap = buildBootstrap();
       if (typeof payload === "string") {

package/dist/content/meta-skill.js

@@ -47,7 +47,7 @@ Before starting work, ALWAYS:
 2. **Stages are workflows, not suggestions.** Follow the skill steps in order. Do not skip verification steps.
 3. **One stage at a time.** Complete the current stage before advancing to the next.
 4. **Gates must pass.** Every stage has required gates — the agent cannot claim completion without satisfying them.
-5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\` and keeps the active run copy in \`.cclaw/runs/<activeRunId>/artifacts/\` — this is the evidence trail.
+5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\`; cclaw sync/runtime keeps run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` aligned as the evidence trail.
 6. **When in doubt, use \`/cc\`.** If the task is non-trivial and there's no prior artifact, run \`/cc <idea>\` to start brainstorming.
 
 ## Stage Quick Reference

package/dist/content/skills.js

@@ -173,10 +173,18 @@ When all required gates are satisfied and the artifact is written:
 
 1. **Update \`${RUNTIME_ROOT}/state/flow-state.json\`:**
 ${stateUpdate}
-2. **Sync artifact** to \`${RUNTIME_ROOT}/runs/<activeRunId>/artifacts/${schema.artifactFile}\`
+   - For each passed gate, add an entry to \`guardEvidence\`: \`"<gate_id>": "<artifact path or excerpt proving the gate>"\`. Do NOT leave \`guardEvidence\` empty.
+2. **Persist artifact** at \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`. Do NOT manually copy into run directories; cclaw sync/runtime keeps \`${RUNTIME_ROOT}/runs/<activeRunId>/artifacts/\` aligned.
 ${nextAction}
 
 **STOP.** Do not load the next stage skill yourself. The user will run \`/cc-next\` when ready (same session or new session).
+
+## Resume Protocol
+
+When resuming a stage in a NEW session (artifact exists but gates are not all passed in flow-state):
+1. Read the existing artifact and check which gates can be verified from artifact evidence.
+2. For each unverified gate, ask the user to confirm ONE gate at a time. Do NOT batch multiple gate confirmations in a single message.
+3. Update \`guardEvidence\` for each confirmed gate before proceeding.
 `;
 }
 function stageTransitionAutoAdvanceBlock(schema) {
@@ -279,7 +287,7 @@ function quickStartBlock(stage) {
 
 > **Even if you read nothing else, do these 3 things:**
 > 1. Obey the HARD-GATE below — violating it invalidates the entire stage.
-> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\` (canonical run copy: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`).
+> 2. Complete every checklist step in order and write the artifact to \`.cclaw/artifacts/${schema.artifactFile}\`. Run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` are synchronized by cclaw runtime.
 > 3. Do not claim completion without satisfying gates: ${topGates}${schema.requiredGates.length > 3 ? ` (+${schema.requiredGates.length - 3} more)` : ""}.
 >
 > **After this stage:** update \`flow-state.json\` and tell the user to run \`/cc-next\`.
@@ -377,7 +385,7 @@ ${progressiveDisclosureBlock(stage)}
 ${selfImprovementBlock(stage)}
 ## Handoff
 - Next command: \`/cc-next\` (loads whatever stage is current in flow-state)
-- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (canonical: \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`)
+- Required artifact: \`.cclaw/artifacts/${schema.artifactFile}\` (run snapshot at \`.cclaw/runs/<activeRunId>/artifacts/${schema.artifactFile}\`, synchronized by cclaw runtime)
 - Stage stays blocked if any required gate is unsatisfied
 `;
 }

package/dist/content/stage-schema.js

@@ -38,8 +38,8 @@ const BRAINSTORM = {
     checklist: [
         "Explore project context — check files, docs, recent commits, existing behavior. Summarize what you found (even for seemingly simple projects).",
         "Assess scope — if the request describes multiple independent subsystems, flag for decomposition before detailed questions.",
-        "Restate the problem — before any questions, summarize what you understood the user wants and why. Ask the user to confirm or correct your understanding.",
-        "Ask clarifying questions — one at a time, understand purpose, constraints, success criteria, target users, and edge cases. Continue until you can confidently describe the solution space. Minimum: understand the WHY, WHO, WHAT, and boundary conditions.",
+        "Restate the problem — in a SEPARATE message (no questions in this message), summarize what you understood the user wants and why. **STOP and wait** for user to confirm or correct before asking any clarifying questions.",
+        "Ask clarifying questions — one at a time, one per message. You MUST cover these categories before proposing approaches: (a) PURPOSE — why this project exists, who it serves; (b) SCOPE — what it must do, what it must NOT do; (c) BOUNDARIES — error handling, edge cases, failure modes; (d) ENVIRONMENT — how it runs, deploys, installs; (e) CONSTRAINTS — performance, compatibility, dependencies. Skip a category only if the user already provided that info. Do NOT rush — 3 generic questions are never enough for a non-trivial project.",
         "Propose 2-3 approaches — with real trade-offs (not cosmetic differences) and your explicit recommendation with reasoning. Explain WHY you recommend this option over others.",
         "Present design — in sections. After each section, explicitly state what you are asking the user to approve: 'Do you approve [specific thing]?' Never ask a bare 'одобряете?/approve?' without context.",
         "Write design doc — save to `.cclaw/artifacts/01-brainstorm.md`.",
@@ -49,8 +49,8 @@ const BRAINSTORM = {
     ],
     interactionProtocol: [
         "Explore context first (files, docs, existing behavior). Share a brief summary of what you found.",
-        "Restate the problem in your own words. Ask user to confirm before proceeding to questions.",
-        "Ask one clarifying question per message. Do NOT combine questions. Continue until you understand purpose, constraints, users, success criteria, and edge cases.",
+        "Restate the problem in your own words in a SEPARATE message. Do NOT add any questions to this message. Wait for user to confirm or correct.",
+        "Ask clarifying questions — one per message. Cover mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do NOT combine questions. Do NOT propose approaches until all categories are addressed.",
         "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with REAL trade-offs (not cosmetic) and mark one as (recommended) with clear reasoning. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Every approval question MUST state what exactly is being approved: 'Do you approve [the architecture / the API shape / the dependency choice]?' Never ask a bare 'approve?' or 'looks good?'.",
         "Get section-by-section approval before finalizing the design direction.",
@@ -59,8 +59,8 @@ const BRAINSTORM = {
     ],
     process: [
         "Explore project context — files, docs, behavior, recent changes. Share findings.",
-        "Restate the problem — summarize what the user wants and why. Get confirmation.",
-        "Clarify iteratively — ask questions one at a time until you understand WHY, WHO, WHAT, success criteria, and boundaries.",
+        "Restate the problem — summarize what the user wants and why in a SEPARATE message. Wait for confirmation before questions.",
+        "Clarify iteratively — ask questions one at a time covering mandatory categories: PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS. Do not skip to approaches early.",
         "Identify whether request should be decomposed into smaller sub-problems.",
         "Offer 2-3 alternatives with real trade-offs and recommendation with rationale.",
         "Present design in sections. After each section explicitly name what you ask the user to approve.",
@@ -70,7 +70,11 @@ const BRAINSTORM = {
         "Handoff to scope stage only after approval is explicit."
     ],
     requiredGates: [
-        { id: "brainstorm_context_explored", description: "Project context and constraints have been reviewed and summarized." },
+        { id: "brainstorm_discovery_purpose", description: "Discovery captured WHY this project exists and WHO it serves, with explicit user confirmation." },
+        { id: "brainstorm_discovery_scope", description: "Discovery captured explicit in-scope and out-of-scope boundaries before approach selection." },
+        { id: "brainstorm_discovery_boundaries", description: "Discovery captured failure modes, edge cases, and error-handling boundaries." },
+        { id: "brainstorm_discovery_environment", description: "Discovery captured runtime/install/deployment environment assumptions." },
+        { id: "brainstorm_discovery_constraints", description: "Discovery captured constraints (performance, compatibility, dependency limits) before deciding architecture." },
         { id: "brainstorm_problem_restated", description: "Problem was restated in agent's words and user confirmed the understanding." },
         { id: "brainstorm_options_compared", description: "At least two alternatives were compared with real trade-offs." },
         { id: "brainstorm_design_approved", description: "User approved a concrete design direction (with explicit statement of what was approved)." },
@@ -79,6 +83,8 @@ const BRAINSTORM = {
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Clarification log explicitly records PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, and CONSTRAINTS coverage.",
+        "Discovery sections include explicit in-scope/out-of-scope boundaries and failure handling boundaries.",
         "Approved direction captured in artifact.",
         "Open questions explicitly listed (if any).",
         "Self-review pass completed with no unresolved issues."
@@ -113,7 +119,8 @@ const BRAINSTORM = {
         "Invoking implementation skills before writing plans",
         "Asking bare 'approve?' or 'одобряете?' without stating WHAT is being approved",
         "Presenting a single summary and asking for blanket approval instead of section-by-section review",
-        "Rushing through clarification — asking 1-2 generic questions then jumping to design"
+        "Rushing through clarification — asking 1-2 generic questions then jumping to design",
+        "Batching multiple gate confirmations in one message when resuming a session"
     ],
     rationalizations: [
         { claim: "This is too simple for design.", reality: "Simple tasks fail fast when assumptions are wrong; a short design pass prevents rework." },
@@ -154,8 +161,14 @@ const BRAINSTORM = {
         traceabilityRule: "Every approved direction must be traceable forward through scope and design. Downstream stages must reference brainstorm decisions."
     },
     artifactValidation: [
-        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY." },
+        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution. Include WHO and WHY and success signal." },
         { section: "Known Context", required: true, validationRule: "Files, patterns, constraints discovered during exploration. Evidence that context was actually explored." },
+        { section: "Clarification Log", required: true, validationRule: "At least 5 rows covering PURPOSE, SCOPE, BOUNDARIES, ENVIRONMENT, CONSTRAINTS." },
+        { section: "Purpose & Beneficiaries", required: true, validationRule: "At least 3 meaningful lines describing why this exists and who benefits." },
+        { section: "Scope Boundaries", required: true, validationRule: "At least 2 scope items including explicit out-of-scope boundaries." },
+        { section: "Failure Boundaries", required: true, validationRule: "At least 2 failure/edge-case expectations and error visibility behavior." },
+        { section: "Runtime Environment", required: true, validationRule: "At least 2 lines describing runtime, install/distribution, and execution environment." },
+        { section: "Constraints", required: true, validationRule: "At least 2 concrete constraints (performance, compatibility, dependency, or policy)." },
         { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with real trade-offs (not cosmetic) and recommendation with reasoning." },
         { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user. State what was approved." },
         { section: "Assumptions & Risks", required: true, validationRule: "Explicit assumptions made during design. Known risks. If none, state 'None'." },

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- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/` and canonical run copies in `.cclaw/runs/<activeRunId>/artifacts/`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\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- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/`; cclaw sync/runtime maintains run snapshots in `.cclaw/runs/<activeRunId>/artifacts/`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -8,13 +8,48 @@ export const ARTIFACT_TEMPLATES = {
 - **Who benefits:**
 - **Why now:**
 - **Success signal:**
-- **Constraints:**
 
 ## Known Context
 - **Explored files/patterns:**
 - **Existing behavior:**
 - **Relevant dependencies:**
 
+## Clarification Log
+| Category | Question asked | User answer | Evidence note |
+|---|---|---|---|
+| PURPOSE |  |  |  |
+| SCOPE |  |  |  |
+| BOUNDARIES |  |  |  |
+| ENVIRONMENT |  |  |  |
+| CONSTRAINTS |  |  |  |
+
+## Purpose & Beneficiaries
+- **Project purpose:**
+- **Primary users:**
+- **Value outcome:**
+
+## Scope Boundaries
+### In Scope
+- 
+
+### Out of Scope
+- 
+
+## Failure Boundaries
+- **Edge cases to handle:**
+- **Expected failures and behavior:**
+- **Error visibility expectations:**
+
+## Runtime Environment
+- **Runtime/platform:**
+- **Install/distribution model:**
+- **Execution context (local/CI/deploy):**
+
+## Constraints
+- **Performance constraints:**
+- **Compatibility constraints:**
+- **Dependency constraints:**
+
 ## Alternatives Table
 | Option | Summary | Trade-offs | Recommendation |
 |---|---|---|---|
@@ -347,7 +382,7 @@ alwaysApply: true
 - Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.
 - Read \`.cclaw/state/flow-state.json\` before acting; continue from current stage when active.
 - Use \`/cc-next\` only after required gates pass; never bypass explicit pause/approval rules.
-- Keep evidence in \`.cclaw/artifacts/\` and canonical run copies in \`.cclaw/runs/<activeRunId>/artifacts/\`.
+- Keep evidence in \`.cclaw/artifacts/\`; cclaw sync/runtime maintains run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\`.
 - For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.
 - Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).
 - Treat \`.cclaw/skills/using-cclaw/SKILL.md\` as routing source of truth; load contextual utility skills only when their triggers apply.

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execFile } from "node:child_process";
+import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/agents.js";
@@ -186,6 +187,47 @@ async function opencodeRegistrationCheck(projectRoot) {
     }
     return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
 }
+async function opencodePluginRuntimeShapeCheck(projectRoot) {
+    const pluginPath = path.join(projectRoot, ".opencode/plugins/cclaw-plugin.mjs");
+    if (!(await exists(pluginPath))) {
+        return { ok: false, details: `${path.relative(projectRoot, pluginPath)} not found` };
+    }
+    try {
+        const moduleUrl = `${pathToFileURL(pluginPath).href}?doctor=${Date.now()}`;
+        const imported = await import(moduleUrl);
+        if (typeof imported.default !== "function") {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} must export a default plugin factory function`
+            };
+        }
+        const plugin = imported.default({ directory: projectRoot });
+        const requiredHandlers = [
+            "event",
+            "tool.execute.before",
+            "tool.execute.after",
+            "experimental.chat.system.transform"
+        ];
+        const missing = requiredHandlers.filter((name) => typeof plugin?.[name] !== "function");
+        if (missing.length > 0) {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} missing runtime handlers: ${missing.join(", ")}`
+            };
+        }
+        await plugin.event({ event: { type: "session.updated", data: {} } });
+        return {
+            ok: true,
+            details: `${path.relative(projectRoot, pluginPath)} exports compatible runtime handler shape`
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            details: `runtime load failed for .opencode/plugins/cclaw-plugin.mjs: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
 export async function doctorChecks(projectRoot, options = {}) {
     const checks = [];
     for (const dir of REQUIRED_DIRS) {
@@ -595,6 +637,12 @@ export async function doctorChecks(projectRoot, options = {}) {
             ok,
             details: `${file} must include event lifecycle handler, tool.execute.before/after with prompt/workflow/context hooks, session.idle summarization, and transform rehydration`
         });
+        const runtimeShape = await opencodePluginRuntimeShapeCheck(projectRoot);
+        checks.push({
+            name: "hook:opencode:runtime_shape",
+            ok: runtimeShape.ok,
+            details: runtimeShape.details
+        });
         const registration = await opencodeRegistrationCheck(projectRoot);
         checks.push({
             name: "hook:opencode:config_registration",
@@ -719,8 +767,8 @@ export async function doctorChecks(projectRoot, options = {}) {
     });
     checks.push({
         name: "run:active_handoff",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "00-handoff.md")),
-        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/00-handoff.md must exist`
+        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "handoff.md")),
+        details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/handoff.md must exist`
     });
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
     checks.push({

package/dist/runs.js

@@ -7,7 +7,7 @@ const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const RUN_META_FILE = "run.json";
-const RUN_HANDOFF_FILE = "00-handoff.md";
+const RUN_HANDOFF_FILE = "handoff.md";
 const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
 function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);

package/package.json

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