cclaw-cli 0.55.2 → 2.0.0

package/dist/content/observe.js

@@ -56,20 +56,20 @@ function buildCursorEvents() {
 }
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         hooks: buildClaudeLikeEvents("claude")
     }, null, 2);
 }
 export function cursorHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         version: 1,
         hooks: buildCursorEvents()
     }, null, 2);
 }
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
-        cclawHookSchemaVersion: 1,
+        cclawHookSchemaVersion: 2,
         hooks: buildClaudeLikeEvents("codex")
     }, null, 2);
 }

package/dist/content/opencode-plugin.js

@@ -1,5 +1,6 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
+import { SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS, SHARED_STAGE_SUPPORT_SNIPPETS } from "./runtime-shared-snippets.js";
 export function opencodePluginJs(_options = {}) {
     return `// cclaw OpenCode plugin — generated by npx cclaw-cli sync
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
@@ -16,13 +17,8 @@ export default function cclawPlugin(ctx) {
   const flowStatePath = join(stateDir, "flow-state.json");
   const knowledgePath = join(runtimeDir, "knowledge.jsonl");
   const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
-  const STAGE_IDS = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
-  const REVIEW_PROMPT_BY_STAGE = {
-    brainstorm: "brainstorm-self-review.md",
-    scope: "scope-ceo-review.md",
-    design: "design-eng-review.md"
-  };
-  const REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);
+  ${SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS}
+  ${SHARED_STAGE_SUPPORT_SNIPPETS}
 
   function ensureRuntimeDirs() {
     try {
@@ -61,14 +57,9 @@ export default function cclawPlugin(ctx) {
   async function readFlowState() {
     try {
       const raw = await readFile(flowStatePath, "utf8");
-      const state = JSON.parse(raw);
-      return {
-        stage: typeof state.currentStage === "string" ? state.currentStage : "none",
-        completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
-        activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
-      };
+      return summarizeFlowState(JSON.parse(raw));
     } catch {
-      return { stage: "none", completed: 0, activeRunId: "none" };
+      return summarizeFlowState({});
     }
   }
 
@@ -80,18 +71,13 @@ export default function cclawPlugin(ctx) {
     }
   }
 
-  async function readTailLines(filePath, maxLines) {
-    const text = (await readFileText(filePath)).trim();
-    if (!text) return [];
-    return text.split(/\\r?\\n/).slice(-maxLines);
-  }
-
-  async function readKnowledgeDigest() {
-    return readTailLines(knowledgePath, 12);
+  async function readKnowledgeDigest(stage) {
+    const raw = await readFileText(knowledgePath);
+    return parseKnowledgeDigest(raw, stage, 6).lines;
   }
 
   async function readStageSupportContext(stage) {
-    if (typeof stage !== "string" || !STAGE_IDS.includes(stage)) return [];
+    if (!isKnownStageId(stage)) return [];
     const parts = [];
     const contract = (await readFileText(join(runtimeDir, "templates/state-contracts", stage + ".json"))).trim();
     if (contract.length > 0) {
@@ -100,7 +86,7 @@ export default function cclawPlugin(ctx) {
           contract
       );
     }
-    const reviewPromptName = REVIEW_PROMPT_BY_STAGE[stage];
+    const reviewPromptName = reviewPromptFileName(stage);
     if (reviewPromptName) {
       const prompt = (await readFileText(join(runtimeDir, "skills/review-prompts", reviewPromptName))).trim();
       if (prompt.length > 0) {
@@ -119,12 +105,12 @@ export default function cclawPlugin(ctx) {
     const flow = await readFlowState();
     const parts = [
       BOOTSTRAP_MARKER,
-      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: ${RUNTIME_ROOT}/artifacts/\`
+      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: \${activeArtifactsPathLabel("${RUNTIME_ROOT}")}\`
     ];
 
 
 
-    const knowledge = await readKnowledgeDigest();
+    const knowledge = await readKnowledgeDigest(flow.stage);
     if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
 
     const stageSupport = await readStageSupportContext(flow.stage);
@@ -621,12 +607,6 @@ export default function cclawPlugin(ctx) {
         eventType === "session.compacted" ||
         eventType === "session.cleared" ||
         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

package/dist/content/reference-patterns.js

@@ -201,7 +201,7 @@ export const REFERENCE_PATTERNS = [
                     "Review source-item coverage by vertical slice, not by file count alone.",
                     "A slice is review-ready only when RED, GREEN, REFACTOR, and verification evidence all line up."
                 ],
-                artifactSections: ["Completeness Snapshot", "Trace Matrix Check"]
+                artifactSections: ["Completeness Snapshot", "Coverage Check"]
             }
         ]
     },
@@ -348,7 +348,7 @@ export const REFERENCE_PATTERNS = [
             {
                 stage: "review",
                 guidance: [
-                    "Victory Detector: Layer 1, Layer 2, security sweep, structured findings, and trace evidence are complete with no unresolved criticals unless verdict is BLOCKED.",
+                    "Victory Detector: Layer 1, Layer 2, security sweep, structured findings, and acceptance/reproduction coverage evidence are complete with no unresolved criticals unless verdict is BLOCKED.",
                     "If the detector fails, iterate findings or route back to TDD; do not say LGTM."
                 ],
                 artifactSections: ["Review Readiness Snapshot", "Final Verdict"]

package/dist/content/runtime-shared-snippets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared runtime snippets interpolated into generated hook/plugin scripts.
+ *
+ * Keep these string helpers minimal and dependency-free so both runtimes
+ * (node hooks and OpenCode plugin) stay in sync without duplicating constants.
+ */
+export declare const SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS = "\nfunction summarizeFlowState(rawState) {\n  const state =\n    rawState && typeof rawState === \"object\" && !Array.isArray(rawState)\n      ? rawState\n      : {};\n  return {\n    stage: typeof state.currentStage === \"string\" ? state.currentStage : \"none\",\n    completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,\n    activeRunId: typeof state.activeRunId === \"string\" ? state.activeRunId : \"none\"\n  };\n}\n\nfunction parseKnowledgeDigest(rawKnowledge, currentStage, maxRows = 6) {\n  const text = typeof rawKnowledge === \"string\" ? rawKnowledge : \"\";\n  if (text.trim().length === 0) {\n    return { learningsCount: 0, lines: [] };\n  }\n  const rows = text\n    .split(/\\r?\\n/gu)\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n  let learningsCount = 0;\n  const parsedRows = [];\n  for (const line of rows) {\n    if (line.startsWith(\"{\")) learningsCount += 1;\n    try {\n      const parsed = JSON.parse(line);\n      if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n      parsedRows.push(parsed);\n    } catch {\n      // ignore malformed knowledge line in digest\n    }\n  }\n  const lines = parsedRows\n    .filter((row) => {\n      const stage = typeof row.stage === \"string\" ? row.stage : null;\n      return stage === null || stage === currentStage;\n    })\n    .slice(-maxRows)\n    .reverse()\n    .map((row) => {\n      const confidence = typeof row.confidence === \"string\" ? row.confidence : \"unknown\";\n      const stage = typeof row.stage === \"string\" ? row.stage : \"global\";\n      const trigger = typeof row.trigger === \"string\" ? row.trigger : \"trigger\";\n      const action = typeof row.action === \"string\" ? row.action : \"action\";\n      return \"- [\" + confidence + \" \u2022 \" + stage + \"] \" + trigger + \" -> \" + action;\n    });\n  return { learningsCount, lines };\n}\n\nfunction activeArtifactsPathLabel(runtimeRoot) {\n  return String(runtimeRoot || \".cclaw\") + \"/artifacts/\";\n}\n";
+export declare const SHARED_STAGE_SUPPORT_SNIPPETS = "\nconst STAGE_IDS = [\"brainstorm\", \"scope\", \"design\", \"spec\", \"plan\", \"tdd\", \"review\", \"ship\"];\nconst REVIEW_PROMPT_BY_STAGE = {\n  brainstorm: \"brainstorm-self-review.md\",\n  scope: \"scope-ceo-review.md\",\n  design: \"design-eng-review.md\"\n};\nconst REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);\n\nfunction isKnownStageId(stage) {\n  return typeof stage === \"string\" && STAGE_IDS.includes(stage);\n}\n\nfunction reviewPromptFileName(stage) {\n  if (!isKnownStageId(stage)) return null;\n  const name = REVIEW_PROMPT_BY_STAGE[stage];\n  return typeof name === \"string\" ? name : null;\n}\n";

package/dist/content/runtime-shared-snippets.js

@@ -0,0 +1,80 @@
+/**
+ * Shared runtime snippets interpolated into generated hook/plugin scripts.
+ *
+ * Keep these string helpers minimal and dependency-free so both runtimes
+ * (node hooks and OpenCode plugin) stay in sync without duplicating constants.
+ */
+export const SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS = `
+function summarizeFlowState(rawState) {
+  const state =
+    rawState && typeof rawState === "object" && !Array.isArray(rawState)
+      ? rawState
+      : {};
+  return {
+    stage: typeof state.currentStage === "string" ? state.currentStage : "none",
+    completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
+    activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
+  };
+}
+
+function parseKnowledgeDigest(rawKnowledge, currentStage, maxRows = 6) {
+  const text = typeof rawKnowledge === "string" ? rawKnowledge : "";
+  if (text.trim().length === 0) {
+    return { learningsCount: 0, lines: [] };
+  }
+  const rows = text
+    .split(/\\r?\\n/gu)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  let learningsCount = 0;
+  const parsedRows = [];
+  for (const line of rows) {
+    if (line.startsWith("{")) learningsCount += 1;
+    try {
+      const parsed = JSON.parse(line);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      parsedRows.push(parsed);
+    } catch {
+      // ignore malformed knowledge line in digest
+    }
+  }
+  const lines = parsedRows
+    .filter((row) => {
+      const stage = typeof row.stage === "string" ? row.stage : null;
+      return stage === null || stage === currentStage;
+    })
+    .slice(-maxRows)
+    .reverse()
+    .map((row) => {
+      const confidence = typeof row.confidence === "string" ? row.confidence : "unknown";
+      const stage = typeof row.stage === "string" ? row.stage : "global";
+      const trigger = typeof row.trigger === "string" ? row.trigger : "trigger";
+      const action = typeof row.action === "string" ? row.action : "action";
+      return "- [" + confidence + " • " + stage + "] " + trigger + " -> " + action;
+    });
+  return { learningsCount, lines };
+}
+
+function activeArtifactsPathLabel(runtimeRoot) {
+  return String(runtimeRoot || ".cclaw") + "/artifacts/";
+}
+`;
+export const SHARED_STAGE_SUPPORT_SNIPPETS = `
+const STAGE_IDS = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
+const REVIEW_PROMPT_BY_STAGE = {
+  brainstorm: "brainstorm-self-review.md",
+  scope: "scope-ceo-review.md",
+  design: "design-eng-review.md"
+};
+const REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);
+
+function isKnownStageId(stage) {
+  return typeof stage === "string" && STAGE_IDS.includes(stage);
+}
+
+function reviewPromptFileName(stage) {
+  if (!isKnownStageId(stage)) return null;
+  const name = REVIEW_PROMPT_BY_STAGE[stage];
+  return typeof name === "string" ? name : null;
+}
+`;

package/dist/content/session-hooks.js

@@ -66,7 +66,7 @@ When resuming work after a break:
 
 ### Optional session-history scan for compound
 
-During post-ship \`compound_review\`, ask before scanning external session history. If the user opts in, inspect only relevant Cursor/Claude/Codex transcripts for repeated failures or process lessons, summarize matches, and then apply the same overlap/refresh/supersede rules before touching \`.cclaw/knowledge.jsonl\`.
+During post-ship \`post_ship_review\`, ask before scanning external session history. If the user opts in, inspect only relevant Cursor/Claude/Codex transcripts for repeated failures or process lessons, summarize matches, and then apply the same overlap/refresh/supersede rules before touching \`.cclaw/knowledge.jsonl\`.
 
 ## Context Management
 

package/dist/content/skills-elicitation.d.ts

@@ -0,0 +1 @@
+export declare function adaptiveElicitationSkillMarkdown(): string;

package/dist/content/skills-elicitation.js

@@ -0,0 +1,123 @@
+import { RUNTIME_ROOT } from "../constants.js";
+import { questionBudgetHint } from "../track-heuristics.js";
+import { FLOW_TRACKS } from "../types.js";
+const ELICITATION_STAGES = ["brainstorm", "scope", "design"];
+function renderQuestionBudgetHintTable() {
+    const rows = [];
+    for (const track of FLOW_TRACKS) {
+        for (const stage of ELICITATION_STAGES) {
+            const hint = questionBudgetHint(track, stage);
+            rows.push(`| \`${track}\` | \`${stage}\` | ${hint.min} | ${hint.recommended} | ${hint.hardCapWarning} |`);
+        }
+    }
+    return `| Track | Stage | Min | Recommended | Hard cap warning |
+|---|---|---|---|---|
+${rows.join("\n")}`;
+}
+export function adaptiveElicitationSkillMarkdown() {
+    const budgetTable = renderQuestionBudgetHintTable();
+    return `---
+name: adaptive-elicitation
+description: "Harness-native one-question-at-a-time dialogue for brainstorm/scope/design with stop signals, smart-skip, and append-only Q&A logging."
+---
+
+# Adaptive Elicitation
+
+Pinned anchor: "Don't tell it what to do, give it success criteria and watch it go."
+
+## HARD-GATE
+- User does not run cclaw manually. Do not tell the user to run CLI commands for answers.
+- Ask exactly one question per turn and wait for the answer before asking the next one.
+- Use harness-native question tools first; prose fallback is allowed only when the tool is unavailable.
+- Keep a running Q&A trace in the active artifact under \`## Q&A Log\` in \`${RUNTIME_ROOT}/artifacts/\` as append-only rows.
+
+## Harness Question Surface
+
+Preferred native tool names:
+- Claude Code: \`AskUserQuestion\`
+- Codex: \`request_user_input\`
+- Gemini: \`ask_user\`
+- Cursor: \`AskQuestion\`
+
+If unavailable, ask one concise prose question and explicitly wait for chat answer.
+
+## Core Protocol
+
+1. Ask one decision-changing question.
+2. Wait for the answer.
+3. Append one row to \`## Q&A Log\`: \`Turn | Question | User answer (1-line) | Decision impact\`.
+4. Self-evaluate:
+   - What did I learn?
+   - Is context enough to draft now? (yes/no + reason)
+   - If no, what is the next most decision-changing question?
+5. Repeat until context is clear OR user asks to proceed.
+
+## Question Shape Rules
+
+- Prefer single-select multiple choice when one direction/priority/next step must be chosen.
+- Use multi-select only for compatible sets (goals, constraints, non-goals).
+- Smart-skip questions already answered earlier (directly or implicitly) and log "skipped (already covered)" when relevant.
+
+## Stop Signals (Natural Language)
+
+Treat these as stop-and-draft signals:
+- RU: "достаточно", "хватит", "давай драфт"
+- EN: "enough", "skip", "just draft it", "stop asking", "move on"
+- UA: "досить", "вистачить", "давай драфт", "рухаємось далі"
+
+When detected:
+- Do not ask another question in this stage loop.
+- Move to drafting with available context.
+- For internal agent calls only, pass \`--skip-questions\` on the next advance helper call.
+
+## Conditional Grilling (Only On Risk Triggers)
+
+Ask an extra 3-5 sharp questions only when one of these triggers appears:
+- Irreversibility (data deletion, schema migration, breaking API/contract)
+- Security/auth boundary changes
+- Domain-model ambiguity with multiple plausible invariants
+
+Do not ask extra questions "for theater" on simple low-risk work.
+
+## Question Budget Hint (Soft Guidance)
+
+Use as orientation, never as a hard stop. Source of truth is \`questionBudgetHint(track, stage)\`:
+
+${budgetTable}
+
+Track mapping note: \`quick\` ~= lightweight, \`medium\` ~= standard, \`standard\` ~= deep.
+Stop based on clarity/user signal, not raw count.
+
+## Stage Forcing Questions
+
+Always keep at least one unresolved forcing question in play until answered or explicitly waived:
+
+- Brainstorm:
+  - What pain are we solving?
+  - What is the most direct path?
+  - What happens if we do nothing?
+  - Who is the operator/user impacted first?
+  - What are non-negotiable no-go boundaries?
+- Scope:
+  - What is definitely in and definitely out?
+  - Which decisions are already locked upstream?
+  - What is the rollback path if this fails?
+  - What are the top failure modes we must design for?
+- Design:
+  - What is the data flow end-to-end?
+  - Where are the seams/interfaces and ownership boundaries?
+  - Which invariants must always hold?
+  - What will we explicitly NOT refactor now?
+
+## One-Way Override (Irreversible Decisions)
+
+For irreversible moves (deletion, schema migration, breaking API):
+- Ask for explicit confirmation even if user asked to stop questions.
+- Proceed only after explicit override ("I understand the irreversible risk; proceed").
+- Record the override in \`## Q&A Log\` and in the stage artifact decision section.
+
+## Completion Rule
+
+"Continue until clear OR user wants to proceed."
+Never force a fixed N-question script.`;
+}

package/dist/content/skills.d.ts

@@ -10,3 +10,4 @@ export declare function noPlaceholdersBlock(): string;
 export declare function watchedFailProofBlock(): string;
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;
+export declare function executingWavesSkillMarkdown(): string;

package/dist/content/skills.js

@@ -148,11 +148,12 @@ function contextLoadingBlock(stage, trace, executionModel) {
 
 Before execution:
 1. Read \`.cclaw/state/flow-state.json\`.
+   - If the file is missing, do **not** invent an active run — this is normal for fresh init. Route to \`/cc <idea>\` first.
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
 4. Read the state contract from \`.cclaw/templates/state-contracts/<stage>.json\` for required fields, taxonomies, and derived markdown path.
-5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its exact section layout — per-row tables with stable column order, calibrated review block; do not invent layouts.
+5. Read the canonical artifact template at \`${artifactTemplatePath}\` to preserve heading/per-row tables contracts (stable section names and column order) plus calibrated review block scaffolding. Preserve existing substantive bullets/rows already in the artifact; never overwrite the artifact wholesale from the template — patch only sections you author this turn.
 6. Extract upstream decisions, constraints, and open questions into the current artifact's \`Upstream Handoff\` section when present.
 7. Confirm context readiness: upstream artifact freshness, required context, canonical template shape, relevant in-repo/reference patterns, and unresolved blockers are known. If any item is missing, load it or stop before drafting.
 8. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
@@ -376,7 +377,7 @@ function completionParametersBlock(schema, track) {
 - \`delegation lifecycle proof\`: use the delegation helper recipe in this section with explicit lifecycle rows: \`--status=scheduled\` -> \`--status=launched\` -> \`--status=acknowledged\` -> \`--status=completed\` (completed isolated/generic requires prior ACK for the same span or \`--ack-ts=<iso>\`).
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
-- 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.
+- Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If a helper fails, report a one-line human-readable failure plus fenced JSON diagnostics; never echo the invoking command line or apply 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.
 `;
 }
@@ -607,3 +608,54 @@ ${reviewSectionsBlock(reviewLens.reviewSections)}
 - Keep decisions explicit: context, options, chosen option, rationale, risk, and rollback.
 `;
 }
+export function executingWavesSkillMarkdown() {
+    return `---
+name: executing-waves
+description: "Execute multi-wave work using existing cclaw run resume + verify-current-state — no new CLI needed."
+---
+
+# Executing Waves (Persistent Multi-Wave Work)
+
+## Overview
+
+Long-form work (large refactors, multi-stage uplifts) often spans many waves.
+This skill documents how the controller persists work across waves WITHOUT new
+CLI commands, using existing \`cclaw run resume\` and \`internal verify-current-state\`.
+
+## When to Use
+
+- Work spans 2+ commits / waves with cohesion concerns between waves.
+- Each wave has its own stage cycle (brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship).
+- User wants explicit per-wave verification before the next wave starts.
+- Risk of cross-wave drift exists.
+
+## Anti-Pattern
+
+- Running many waves linearly without verification between them, accumulating drift.
+- Treating a wave as only a commit boundary without re-verifying upstream decisions.
+
+## Process
+
+1. **Wave Start**: author wave plan as \`.cclaw/wave-plans/<wave-n>.md\` referencing previous wave's ship artifact.
+2. **Carry-forward Audit**: at brainstorm of the next wave, re-read previous wave ship artifact and explicitly record in the existing \`## Wave Carry-forward\` section:
+   - Carrying forward: <scope LD# hash references still valid>
+   - Drift detected: <decisions no longer valid + reason>
+   - Re-scope needed: <yes/no>
+   - Never create a second \`## Locked Decisions\` heading in brainstorm; reference prior LD# hashes inline.
+3. **Resume Path**: if a wave was interrupted mid-stage, \`cclaw run resume\` restores state. Run \`internal verify-current-state\` before continuing.
+4. **Wave End**: at ship, architect cross-stage verification runs from dispatch matrix. If \`DRIFT_DETECTED\`, fix before ship.
+5. **Next Wave Trigger**: launch new \`/cc <topic>\` for next wave and reference previous wave ship artifact in upstream handoff.
+
+## Status Markers
+
+- \`wave-status: in-progress\` — current stage incomplete.
+- \`wave-status: blocked-by-prev\` — waiting on previous wave verification.
+- \`wave-status: shipped\` — wave shipped, next wave can start.
+- \`wave-status: rolled-back\` — previous wave invalidated, current wave needs rebase.
+
+## Linter Hooks
+
+- If multi-wave work is detected (>1 wave-plan files in \`.cclaw/wave-plans/\`), current brainstorm artifact MUST contain \`## Wave Carry-forward\` section with drift audit.
+- If carry-forward drift is missing in multi-wave context, emit \`[P1] wave.drift_unaddressed\`.
+`;
+}