cclaw-cli 0.1.1 → 0.2.1

package/dist/content/hooks.js

@@ -7,6 +7,13 @@
  */
 import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
+function shellLiteral(value) {
+    return value
+        .replace(/\\/gu, "\\\\")
+        .replace(/"/gu, '\\"')
+        .replace(/\$/gu, "\\$")
+        .replace(/`/gu, "\\`");
+}
 const ESCAPE_FN = `escape_json() {
   local str="$1"
   str=\${str//\\\\/\\\\\\\\}
@@ -36,7 +43,11 @@ if [ -z "$ROOT" ]; then
 fi`;
 /** Shared bash preamble for generated hook scripts. */
 export const RUNTIME_SHELL_DETECT_ROOT = DETECT_ROOT;
-export function sessionStartScript() {
+export function sessionStartScript(options = {}) {
+    const globalLearningsEnabled = options.globalLearningsEnabled === true;
+    const globalLearningsPath = options.globalLearningsPath?.trim() ?? "";
+    const globalLearningsPathLiteral = shellLiteral(globalLearningsPath);
+    const globalLearningsEnabledLiteral = globalLearningsEnabled ? "true" : "false";
     return `#!/usr/bin/env bash
 # cclaw session-start hook — generated by cclaw sync
 # Injects using-cclaw + flow status + run pointer + top learnings + checkpoint/activity summary.
@@ -49,13 +60,22 @@ CHECKPOINT_FILE="$ROOT/${RUNTIME_ROOT}/state/checkpoint.json"
 ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
 SUGGESTION_MEMORY_FILE="$ROOT/${RUNTIME_ROOT}/state/suggestion-memory.json"
 CONTEXT_WARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/state/context-warnings.jsonl"
+CONTEXT_MODE_FILE="$ROOT/${RUNTIME_ROOT}/state/context-mode.json"
+CONTEXTS_DIR="$ROOT/${RUNTIME_ROOT}/contexts"
 LEARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/learnings.jsonl"
+GLOBAL_LEARNINGS_ENABLED="${globalLearningsEnabledLiteral}"
+GLOBAL_LEARNINGS_FILE="${globalLearningsPathLiteral}"
+if [ "$GLOBAL_LEARNINGS_ENABLED" = "true" ] && [ -z "$GLOBAL_LEARNINGS_FILE" ]; then
+  GLOBAL_LEARNINGS_FILE="$HOME/.cclaw-global-learnings.jsonl"
+fi
 META_SKILL="$ROOT/${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"
 
 # --- Read flow state ---
 STAGE="none"
 COMPLETED="0"
 ACTIVE_RUN="none"
+ACTIVE_CONTEXT_MODE="default"
+CONTEXT_MODE_NOTE=""
 if [ -f "$STATE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
     STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
@@ -124,6 +144,34 @@ PY
   fi
 fi
 
+if [ -f "$CONTEXT_MODE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    ACTIVE_CONTEXT_MODE=$(jq -r '.activeMode // "default"' "$CONTEXT_MODE_FILE" 2>/dev/null || echo "default")
+  elif command -v python3 >/dev/null 2>&1; then
+    ACTIVE_CONTEXT_MODE=$(python3 - "$CONTEXT_MODE_FILE" <<'PY'
+import json
+import sys
+mode = "default"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("activeMode")
+    if isinstance(value, str) and value:
+        mode = value
+except Exception:
+    pass
+print(mode)
+PY
+)
+  fi
+fi
+
+if [ -f "$CONTEXTS_DIR/$ACTIVE_CONTEXT_MODE.md" ]; then
+  CONTEXT_MODE_NOTE="Context mode: $ACTIVE_CONTEXT_MODE (guide: ${RUNTIME_ROOT}/contexts/$ACTIVE_CONTEXT_MODE.md)"
+else
+  CONTEXT_MODE_NOTE="Context mode: $ACTIVE_CONTEXT_MODE"
+fi
+
 # --- Checkpoint summary ---
 CHECKPOINT_SUMMARY=""
 if [ -f "$CHECKPOINT_FILE" ]; then
@@ -149,6 +197,12 @@ PY
   fi
 fi
 
+SESSION_DIGEST=""
+DIGEST_PATH="$ROOT/${RUNTIME_ROOT}/state/session-digest.md"
+if [ -f "$DIGEST_PATH" ]; then
+  SESSION_DIGEST=$(cat "$DIGEST_PATH" 2>/dev/null || echo "")
+fi
+
 # --- Recent stage activity summary ---
 ACTIVITY_SUMMARY=""
 if [ -f "$ACTIVITY_FILE" ] && [ -s "$ACTIVITY_FILE" ]; then
@@ -274,10 +328,28 @@ fi
 
 # --- Read top learnings with decay ---
 LEARNINGS_SUMMARY=""
-if [ -f "$LEARNINGS_FILE" ] && [ -s "$LEARNINGS_FILE" ]; then
+LEARNING_LINES=""
+for source_file in "$LEARNINGS_FILE" "$GLOBAL_LEARNINGS_FILE"; do
+  [ -n "$source_file" ] || continue
+  if [ "$source_file" = "$GLOBAL_LEARNINGS_FILE" ] && [ "$GLOBAL_LEARNINGS_ENABLED" != "true" ]; then
+    continue
+  fi
+  [ -f "$source_file" ] || continue
+  [ -s "$source_file" ] || continue
+  CHUNK=$(tail -n 30 "$source_file" 2>/dev/null || echo "")
+  [ -n "$CHUNK" ] || continue
+  if [ -n "$LEARNING_LINES" ]; then
+    LEARNING_LINES="$LEARNING_LINES
+$CHUNK"
+  else
+    LEARNING_LINES="$CHUNK"
+  fi
+done
+
+if [ -n "$LEARNING_LINES" ]; then
   if command -v jq >/dev/null 2>&1; then
     NOW_EPOCH=$(date +%s 2>/dev/null || echo "0")
-    LEARNINGS_SUMMARY=$(tail -n 30 "$LEARNINGS_FILE" 2>/dev/null | jq -r -s --arg now "$NOW_EPOCH" '
+    LEARNINGS_SUMMARY=$(printf '%s\n' "$LEARNING_LINES" | jq -r -s --arg now "$NOW_EPOCH" '
       [.[] | select(.key != null)]
       | group_by([.key, .type])
       | map(sort_by(.ts) | last)
@@ -295,16 +367,54 @@ if [ -f "$LEARNINGS_FILE" ] && [ -s "$LEARNINGS_FILE" ]; then
       | join("\\n")
     ' 2>/dev/null || echo "")
   else
-    LEARNINGS_SUMMARY=$(tail -n 3 "$LEARNINGS_FILE" 2>/dev/null || echo "")
+    LEARNINGS_SUMMARY=$(printf '%s\n' "$LEARNING_LINES" | tail -n 3 2>/dev/null || echo "")
   fi
 fi
 
+STAGE_LEARNINGS=""
+STAGE_LEARNING_LINES=""
+for source_file in "$LEARNINGS_FILE" "$GLOBAL_LEARNINGS_FILE"; do
+  [ -n "$source_file" ] || continue
+  if [ "$source_file" = "$GLOBAL_LEARNINGS_FILE" ] && [ "$GLOBAL_LEARNINGS_ENABLED" != "true" ]; then
+    continue
+  fi
+  [ -f "$source_file" ] || continue
+  [ -s "$source_file" ] || continue
+  CHUNK=$(tail -n 50 "$source_file" 2>/dev/null || echo "")
+  [ -n "$CHUNK" ] || continue
+  if [ -n "$STAGE_LEARNING_LINES" ]; then
+    STAGE_LEARNING_LINES="$STAGE_LEARNING_LINES
+$CHUNK"
+  else
+    STAGE_LEARNING_LINES="$CHUNK"
+  fi
+done
+
+if [ "$STAGE" != "none" ] && [ -n "$STAGE_LEARNING_LINES" ] && command -v jq >/dev/null 2>&1; then
+  STAGE_LEARNINGS=$(printf '%s\n' "$STAGE_LEARNING_LINES" | jq -r -s --arg stage "$STAGE" '
+    [.[] | select(.key != null and (.key | contains($stage)))]
+    | sort_by(-.confidence)
+    | .[0:2]
+    | map("- [stage] " + .key + ": " + .insight)
+    | join("\\n")
+  ' 2>/dev/null || echo "")
+fi
+
 # --- Build context message ---
 CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/9 completed, run=$ACTIVE_RUN). Active run artifacts: ${RUNTIME_ROOT}/runs/$ACTIVE_RUN/artifacts/"
+if [ -n "$CONTEXT_MODE_NOTE" ]; then
+  CTX="$CTX
+$CONTEXT_MODE_NOTE"
+fi
 if [ -n "$CHECKPOINT_SUMMARY" ]; then
   CTX="$CTX
 $CHECKPOINT_SUMMARY"
 fi
+if [ -n "$SESSION_DIGEST" ]; then
+  CTX="$CTX
+Last session:
+$SESSION_DIGEST"
+fi
 if [ -n "$ACTIVITY_SUMMARY" ]; then
   CTX="$CTX
 Recent stage activity:
@@ -325,6 +435,11 @@ if [ -n "$LEARNINGS_SUMMARY" ]; then
 Top learnings:
 $LEARNINGS_SUMMARY"
 fi
+if [ -n "$STAGE_LEARNINGS" ]; then
+  CTX="$CTX
+Stage learnings ($STAGE):
+$STAGE_LEARNINGS"
+fi
 if [ -n "$META_CONTENT" ]; then
   CTX="$CTX
 
@@ -366,6 +481,7 @@ STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 STATE_FILE="$STATE_DIR/flow-state.json"
 CHECKPOINT_FILE="$STATE_DIR/checkpoint.json"
 CHECKPOINT_TMP="$STATE_DIR/checkpoint.json.tmp.$$"
+CHECKPOINT_LOCK_DIR="$STATE_DIR/.checkpoint.lock"
 STAGE="none"
 ACTIVE_RUN="none"
 LOOP_COUNT=""
@@ -445,7 +561,30 @@ CHECKPOINT_WRITTEN=0
 cleanup_checkpoint_tmp() {
   rm -f "$CHECKPOINT_TMP" 2>/dev/null || true
 }
-trap cleanup_checkpoint_tmp EXIT INT TERM
+
+acquire_checkpoint_lock() {
+  local attempt=0
+  while ! mkdir "$CHECKPOINT_LOCK_DIR" 2>/dev/null; do
+    attempt=$((attempt + 1))
+    if [ "$attempt" -ge 200 ]; then
+      return 1
+    fi
+    sleep 0.02
+  done
+  return 0
+}
+
+release_checkpoint_lock() {
+  rmdir "$CHECKPOINT_LOCK_DIR" 2>/dev/null || true
+}
+
+cleanup_checkpoint_state() {
+  cleanup_checkpoint_tmp
+  release_checkpoint_lock
+}
+trap cleanup_checkpoint_state EXIT INT TERM
+
+acquire_checkpoint_lock || exit 0
 
 if command -v jq >/dev/null 2>&1; then
   EXISTING_JSON="{}"
@@ -532,7 +671,7 @@ if [ "$CHECKPOINT_WRITTEN" -eq 0 ]; then
   fi
 fi
 
-cleanup_checkpoint_tmp
+cleanup_checkpoint_state
 trap - EXIT INT TERM
 
 CHECKPOINT_NOTE="Checkpoint updated at ${RUNTIME_ROOT}/state/checkpoint.json."
@@ -575,15 +714,39 @@ export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
 // ---------------------------------------------------------------------------
 // OpenCode plugin — JS module
 // ---------------------------------------------------------------------------
-export function opencodePluginJs() {
+export function opencodePluginJs(options = {}) {
+    const globalLearningsEnabledLiteral = options.globalLearningsEnabled === true ? "true" : "false";
+    const globalLearningsPathLiteral = JSON.stringify(options.globalLearningsPath?.trim() ?? "");
     return `// cclaw OpenCode plugin — generated by cclaw sync
-import { closeSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
-import { join } from "node:path";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
 
 export default function cclawPlugin(ctx) {
   const root = ctx.directory || process.cwd();
+  const runtimeDir = join(root, "${RUNTIME_ROOT}");
+  const stateDir = join(root, "${RUNTIME_ROOT}/state");
+  const observationsPath = join(root, "${RUNTIME_ROOT}/observations.jsonl");
+  const learningsPath = join(root, "${RUNTIME_ROOT}/learnings.jsonl");
   const checkpointPath = join(root, "${RUNTIME_ROOT}/state/checkpoint.json");
   const activityPath = join(root, "${RUNTIME_ROOT}/state/stage-activity.jsonl");
+  const suggestionMemoryPath = join(root, "${RUNTIME_ROOT}/state/suggestion-memory.json");
+  const contextWarningsPath = join(root, "${RUNTIME_ROOT}/state/context-warnings.jsonl");
+  const contextModePath = join(root, "${RUNTIME_ROOT}/state/context-mode.json");
+  const contextsDir = join(root, "${RUNTIME_ROOT}/contexts");
+  const sessionDigestPath = join(root, "${RUNTIME_ROOT}/state/session-digest.md");
+  const observeDisabledPath = join(root, "${RUNTIME_ROOT}/.observe-disabled");
+  const globalLearningsEnabled = ${globalLearningsEnabledLiteral};
+  const globalLearningsPathRaw = ${globalLearningsPathLiteral};
 
   function readFlowState() {
     try {
@@ -636,9 +799,42 @@ export default function cclawPlugin(ctx) {
     return raw.split(/\\r?\\n/).slice(-maxLines);
   }
 
+  function resolveGlobalLearningsPath(rawPath) {
+    if (!rawPath || typeof rawPath !== "string" || rawPath.trim().length === 0) {
+      return join(homedir(), ".cclaw-global-learnings.jsonl");
+    }
+    const trimmed = rawPath.trim();
+    if (trimmed.startsWith("~/")) {
+      return join(homedir(), trimmed.slice(2));
+    }
+    if (isAbsolute(trimmed)) {
+      return trimmed;
+    }
+    return join(root, trimmed);
+  }
+
+  function learningFiles() {
+    const files = [learningsPath];
+    if (globalLearningsEnabled) {
+      const globalPath = resolveGlobalLearningsPath(globalLearningsPathRaw);
+      if (globalPath !== learningsPath) {
+        files.push(globalPath);
+      }
+    }
+    return files;
+  }
+
+  function readLearningLines(maxLines, maxBytes) {
+    const combined = [];
+    for (const filePath of learningFiles()) {
+      combined.push(...readTailLines(filePath, maxLines, maxBytes));
+    }
+    return combined;
+  }
+
   function readTopLearnings() {
     try {
-      const lines = readTailLines(join(root, "${RUNTIME_ROOT}/learnings.jsonl"), 30, 65536);
+      const lines = readLearningLines(30, 65536);
       if (lines.length === 0) return [];
       const entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
       const deduped = new Map();
@@ -670,6 +866,22 @@ export default function cclawPlugin(ctx) {
     }
   }
 
+  function readContextMode() {
+    let mode = "default";
+    try {
+      const raw = readFileSync(contextModePath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.activeMode === "string" && parsed.activeMode.trim().length > 0) {
+        mode = parsed.activeMode.trim();
+      }
+    } catch {
+      // use default mode
+    }
+    const guidePath = join(contextsDir, mode + ".md");
+    const guide = existsSync(guidePath) ? "${RUNTIME_ROOT}/contexts/" + mode + ".md" : "";
+    return { mode, guide };
+  }
+
   function readRecentActivity() {
     try {
       const lines = readTailLines(activityPath, 5, 32768);
@@ -686,19 +898,123 @@ export default function cclawPlugin(ctx) {
     }
   }
 
+  function readSessionDigest() {
+    try {
+      const digest = readFileSync(sessionDigestPath, "utf8").trim();
+      return digest;
+    } catch {
+      return "";
+    }
+  }
+
+  function readLatestContextWarning() {
+    try {
+      const line = readTailLines(contextWarningsPath, 1, 8192)[0];
+      if (!line) return "";
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed.note === "string") {
+          return parsed.note;
+        }
+      } catch {
+        // non-json line fallback
+      }
+      return line;
+    } catch {
+      return "";
+    }
+  }
+
+  function stageSuggestionFor(stage) {
+    const map = {
+      brainstorm: "Suggestion: list 2-3 alternatives and ask a single focused clarifying question before direction lock.",
+      scope: "Suggestion: lock explicit in-scope/out-of-scope boundaries and choose one scope mode.",
+      design: "Suggestion: map failure modes per new codepath and confirm architecture boundaries before moving forward.",
+      spec: "Suggestion: ensure every acceptance criterion is measurable and mapped to a concrete test.",
+      plan: "Suggestion: group tasks into dependency waves and keep WAIT_FOR_CONFIRM pending until approval.",
+      test: "Suggestion: RED only in this stage — capture failing output for each selected slice.",
+      build: "Suggestion: apply minimal GREEN change, run full suite, then document REFACTOR notes.",
+      review: "Suggestion: run Layer 1 before Layer 2 and reconcile findings into 07-review-army.json.",
+      ship: "Suggestion: verify preflight + rollback plan before selecting exactly one finalization mode."
+    };
+    return map[stage] || "";
+  }
+
+  function readStageSuggestion(stage) {
+    let memory = { enabled: true, mutedStages: [] };
+    try {
+      const parsed = JSON.parse(readFileSync(suggestionMemoryPath, "utf8"));
+      if (parsed && typeof parsed === "object") {
+        memory = {
+          enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : true,
+          mutedStages: Array.isArray(parsed.mutedStages)
+            ? parsed.mutedStages.filter((item) => typeof item === "string")
+            : []
+        };
+      }
+    } catch {
+      // use defaults
+    }
+    if (!memory.enabled || memory.mutedStages.includes(stage)) {
+      return "";
+    }
+    return stageSuggestionFor(stage);
+  }
+
+  function readStageLearnings(stage) {
+    try {
+      const lines = readLearningLines(60, 131072);
+      const entries = lines
+        .map((line) => {
+          try {
+            return JSON.parse(line);
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean);
+      if (entries.length === 0) return [];
+      return entries
+        .filter((entry) => typeof entry.key === "string" && entry.key.toLowerCase().includes(stage.toLowerCase()))
+        .sort((a, b) => (Number(b.confidence) || 0) - (Number(a.confidence) || 0))
+        .slice(0, 2)
+        .map((entry) => "- [stage] " + entry.key + ": " + entry.insight);
+    } catch {
+      return [];
+    }
+  }
+
   function buildBootstrap() {
     const { stage, completed, activeRunId } = readFlowState();
     const meta = readMetaSkill();
     const learnings = readTopLearnings();
     const checkpoint = readCheckpointSummary();
     const activity = readRecentActivity();
+    const digest = readSessionDigest();
+    const warning = readLatestContextWarning();
+    const contextMode = readContextMode();
+    const stageSuggestion = readStageSuggestion(stage);
+    const stageLearnings = readStageLearnings(stage);
     const parts = [\`cclaw loaded. Flow: stage=\${stage} (\${completed}/9 completed, run=\${activeRunId}). Active run artifacts: ${RUNTIME_ROOT}/runs/\${activeRunId}/artifacts/\`];
+    parts.push(
+      contextMode.guide
+        ? \`Context mode: \${contextMode.mode} (guide: \${contextMode.guide})\`
+        : \`Context mode: \${contextMode.mode}\`
+    );
     if (checkpoint) parts.push(checkpoint);
+    if (digest) parts.push("Last session:", digest);
     if (activity.length > 0) parts.push("Recent stage activity:", ...activity);
+    if (warning) parts.push("Latest context warning:", warning);
+    if (stageSuggestion) {
+      parts.push(stageSuggestion, "To disable suggestions persistently set .cclaw/state/suggestion-memory.json -> enabled=false.");
+    }
     if (learnings.length > 0) {
       parts.push("Top learnings:");
       for (const l of learnings) parts.push(\`- \${l.key} (conf \${l.effective_confidence}): \${l.insight}\`);
     }
+    if (stageLearnings.length > 0) {
+      parts.push(\`Stage learnings (\${stage}):\`, ...stageLearnings);
+    }
     if (meta) parts.push("", meta);
     return parts.join("\\n");
   }
@@ -707,11 +1023,127 @@ export default function cclawPlugin(ctx) {
     console.log(buildBootstrap());
   }
 
+  function observationEnabled() {
+    return !existsSync(observeDisabledPath);
+  }
+
+  function ensureRuntimeDirs() {
+    try {
+      mkdirSync(runtimeDir, { recursive: true });
+    } catch {
+      // ignore
+    }
+    try {
+      mkdirSync(stateDir, { recursive: true });
+    } catch {
+      // ignore
+    }
+  }
+
+  async function runHookScript(scriptFileName, payload = {}) {
+    const { spawnSync } = await import("node:child_process");
+    const scriptPath = join(root, "${RUNTIME_ROOT}/hooks/" + scriptFileName);
+    const input = typeof payload === "string" ? payload : JSON.stringify(payload ?? {});
+    try {
+      spawnSync("bash", [scriptPath], {
+        cwd: root,
+        timeout: 20000,
+        stdio: ["pipe", "ignore", "ignore"],
+        input
+      });
+    } catch {
+      // advisory-only runtime path
+    }
+  }
+
+  function toText(value) {
+    if (typeof value === "string") return value;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return value == null ? "" : String(value);
+    }
+  }
+
+  function truncateText(value, maxLen = 2000) {
+    const text = toText(value);
+    return text.length > maxLen ? text.slice(0, maxLen) : text;
+  }
+
+  function extractToolName(payload) {
+    const candidates = [
+      payload?.tool,
+      payload?.toolName,
+      payload?.tool_name,
+      payload?.name,
+      payload?.id,
+      payload?.command,
+      payload?.tool?.name,
+      payload?.tool?.id,
+    ];
+    for (const value of candidates) {
+      if (typeof value === "string" && value.trim()) return value.trim();
+    }
+    return "unknown";
+  }
+
+  function appendJsonLine(filePath, value) {
+    try {
+      appendFileSync(filePath, JSON.stringify(value) + "\\n", "utf8");
+    } catch {
+      // ignore
+    }
+  }
+
+  function recordToolEvent(phase, payload) {
+    if (!observationEnabled()) return;
+    const flow = readFlowState();
+    const ts = new Date().toISOString();
+    const tool = extractToolName(payload);
+    const event = phase === "pre" ? "tool_start" : "tool_complete";
+    ensureRuntimeDirs();
+    appendJsonLine(observationsPath, {
+      ts,
+      event,
+      tool,
+      phase,
+      stage: flow.stage,
+      runId: flow.activeRunId,
+      data: truncateText(payload)
+    });
+    appendJsonLine(activityPath, {
+      ts,
+      event,
+      tool,
+      phase,
+      stage: flow.stage,
+      runId: flow.activeRunId
+    });
+  }
+
   return {
-    "session.created": emitBootstrap,
-    "session.resumed": emitBootstrap,
-    "session.compacted": emitBootstrap,
-    "session.cleared": emitBootstrap,
+    event: async (name, data) => {
+      if (name === "session.created" || name === "session.resumed" || name === "session.compacted" || name === "session.cleared") {
+        emitBootstrap();
+      }
+      if (name === "session.updated") {
+        // no-op: tracked via activity log
+      }
+      if (name === "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 (name === "tool.execute.after") {
+        await runHookScript("context-monitor.sh", data ?? {});
+        recordToolEvent("post", data);
+      }
+    },
     "experimental.chat.system.transform": (payload) => {
       const bootstrap = buildBootstrap();
       if (typeof payload === "string") {
@@ -735,14 +1167,14 @@ export function hooksAgentsMdBlock() {
 
 Cclaw generates real hook integrations across harnesses:
 - **Claude/Cursor/Codex:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
-- **OpenCode:** session lifecycle + system transform rehydration in plugin
+- **OpenCode:** session lifecycle + system transform rehydration + bootstrap parity (digest/warnings/suggestions/stage learnings)
 
 | Harness | Hook file | Events |
 |---------|-----------|--------|
 | Claude Code | \`.claude/hooks/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
 | Cursor | \`.cursor/hooks.json\` | sessionStart/sessionResume/sessionClear/sessionCompact, preToolUse, postToolUse, stop |
 | Codex | \`.codex/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
-| OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/resumed/compacted/cleared + system transform |
+| OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/updated/resumed/cleared/compacted/idle, tool.execute.before/after, system transform |
 
 Hook state files:
 - \`${RUNTIME_ROOT}/state/stage-activity.jsonl\`

package/dist/content/meta-skill.js

@@ -91,9 +91,35 @@ These skills live in \`.cclaw/skills/\` but have no slash commands. They activat
 | Performance | \`performance/\` | During review; when code is perf-sensitive (DB queries, rendering, bundle size) |
 | CI/CD | \`ci-cd/\` | During ship; when pipeline config or deployment is involved |
 | Documentation | \`docs/\` | During ship; when adding public APIs, architecture changes, or breaking changes |
+| Executing Plans | \`executing-plans/\` | After plan approval during sustained task execution waves |
+| Context Engineering | \`context-engineering/\` | When work mode changes (execution, review, incident) or context pressure rises |
+| Source-Driven Development | \`source-driven-development/\` | Before introducing new patterns/helpers; when deciding reuse vs net-new structure |
+| Frontend Accessibility | \`frontend-accessibility/\` | For user-facing UI changes and accessibility quality gates |
 
 **Activation rule:** When a contextual skill applies, read its SKILL.md and follow it as a supplementary lens alongside the current stage. Do not skip the stage workflow — the contextual skill adds depth, not a detour.
 
+## Progressive Disclosure (Depth / See Also)
+
+Use this loading order to keep context lean while preserving depth:
+
+1. Start with the active stage skill in \`.cclaw/skills/<stage>/SKILL.md\`.
+2. Load exactly one contextual utility skill only if its trigger appears.
+3. Open command contract (\`.cclaw/commands/<stage>.md\`) only for gate/handoff wording.
+4. Expand to adjacent stage skills only when transition ambiguity exists.
+
+### Depth triggers
+- **Flaky/failing tests:** \`.cclaw/skills/debugging/SKILL.md\`
+- **Security-sensitive change:** \`.cclaw/skills/security/SKILL.md\`
+- **Performance risk:** \`.cclaw/skills/performance/SKILL.md\`
+- **Release/deploy concerns:** \`.cclaw/skills/ci-cd/SKILL.md\`
+- **Public API/docs impact:** \`.cclaw/skills/docs/SKILL.md\`
+- **Specialist delegation needed:** \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`
+
+### See also
+- \`.cclaw/skills/session/SKILL.md\` for session start/stop/resume behavior
+- \`.cclaw/skills/learnings/SKILL.md\` for durable memory capture and reuse
+- \`.cclaw/skills/autoplan/SKILL.md\` when user requests multi-stage orchestration
+
 ## Decision Protocol
 
 When a stage requires user input (approval, choice, direction), use this structured pattern:

package/dist/content/next-command.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command contract for /cc-next - agent reads flow state, evaluates gates, advances or reports blockers.
+ * Wire into install (write to `.cclaw/commands/next.md` + harness shim `cc-next.md`) in a follow-up; not invoked by CLI.
+ */
+export declare function nextCommandContract(): string;
+/**
+ * Skill body for /cc-next - flow logic and continue semantics.
+ */
+export declare function nextCommandSkillMarkdown(): string;