cclaw-cli 0.10.1 → 0.12.0

package/dist/content/core-agents.js

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ */
+function yamlScalarString(value) {
+    // JSON double-quoted strings are valid YAML scalars and escape reliably.
+    return JSON.stringify(value);
+}
+function yamlFlowSequence(values) {
+    return JSON.stringify(values);
+}
+/**
+ * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ */
+export const CCLAW_AGENTS = [
+    {
+        name: "planner",
+        description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "mandatory",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        body: [
+            "You are an **implementation planning specialist** (staff engineer mindset).",
+            "",
+            "When invoked:",
+            "1. Analyze scope and break it into concrete sub-problems.",
+            "2. Map each sub-problem to existing modules and reusable code.",
+            "3. Produce an ordered execution plan with dependencies and checks.",
+            "4. Highlight risks and unknowns that need user decisions.",
+            "",
+            "**Role boundary:** planning only. Do NOT write production code."
+        ].join("\n")
+    },
+    {
+        name: "reviewer",
+        description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["spec", "review", "ship"],
+        body: [
+            "You are a **combined spec + code reviewer**.",
+            "",
+            "Run two explicit passes:",
+            "",
+            "1. **Spec pass**",
+            "   - For each acceptance criterion: PASS / PARTIAL / FAIL.",
+            "   - Cite evidence as `file:line`.",
+            "",
+            "2. **Code-quality pass**",
+            "   - Correctness: logic, boundaries, state transitions.",
+            "   - Maintainability: naming, structure, complexity, debt risks.",
+            "   - Performance: avoid obvious hot-path regressions.",
+            "   - Architecture fit: layering and contract stability.",
+            "",
+            "For each finding include:",
+            "- Severity: `Critical` | `Important` | `Suggestion`",
+            "- Location: `file:line`",
+            "- Problem and concrete recommendation",
+            "",
+            "**Trust model:** never rely on implementer claims; verify by reading code."
+        ].join("\n")
+    },
+    {
+        name: "security-reviewer",
+        description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["design", "review", "ship"],
+        body: [
+            "You are a **security vulnerability specialist** focused on exploitability.",
+            "",
+            "Check for (non-exhaustive):",
+            "- validation gaps and injection vectors",
+            "- authz/authn boundary violations",
+            "- secret leakage in code/logging",
+            "- unsafe file/system/network operations",
+            "- privilege escalation and trust-boundary misuse",
+            "",
+            "For each finding include:",
+            "- severity aligned to ship risk",
+            "- CWE ID when possible (or UNKNOWN)",
+            "- short proof-of-concept vector",
+            "- concrete control-oriented fix"
+        ].join("\n")
+    },
+    {
+        name: "test-author",
+        description: "MANDATORY in TDD stage. MUST BE USED for RED -> GREEN -> REFACTOR with evidence-first discipline.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["tdd"],
+        body: [
+            "You are a **test-driven development** specialist.",
+            "",
+            "**Iron law:** no production code without a failing test first.",
+            "",
+            "Process:",
+            "1. RED: write a failing test for the desired behavior.",
+            "2. Verify RED fails for the right reason.",
+            "3. GREEN: implement minimal code to pass.",
+            "4. Verify GREEN on relevant suite/full suite.",
+            "5. REFACTOR with behavior preserved."
+        ].join("\n")
+    },
+    {
+        name: "doc-updater",
+        description: "MANDATORY at ship and PROACTIVE when behavior/config/public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob"],
+        model: "fast",
+        activation: "mandatory",
+        relatedStages: ["tdd", "ship"],
+        body: [
+            "You are a **documentation maintenance specialist**.",
+            "",
+            "After code changes, verify and update only stale sections in:",
+            "- README / setup / usage",
+            "- API docs and examples",
+            "- migration and operational notes",
+            "",
+            "Preserve existing tone and structure; avoid rewrites for style alone."
+        ].join("\n")
+    }
+];
+import { enhancedAgentBody } from "./subagents.js";
+/**
+ * Render a complete cclaw agent markdown file (YAML frontmatter + body).
+ */
+export function agentMarkdown(agent) {
+    const frontmatter = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${yamlScalarString(agent.description)}`,
+        `tools: ${yamlFlowSequence(agent.tools)}`,
+        `model: ${agent.model}`,
+        "---"
+    ].join("\n");
+    const relatedStages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "(none)";
+    const taskDelegation = enhancedAgentBody(agent.name);
+    return `${frontmatter}
+
+# ${agent.name}
+
+${agent.body}
+
+## Activation
+
+- Mode: ${agent.activation}
+- Related stages: ${relatedStages}
+
+## Rules
+
+- Cite file:line for every finding
+- Do not make changes outside your specialist domain
+- Report findings with severity classification
+- If uncertain, say "UNKNOWN" - never guess
+
+${taskDelegation}
+`;
+}
+/**
+ * Markdown table mapping cclaw stage entry points to specialist agents.
+ */
+export function agentRoutingTable() {
+    return `| Stage Entry | Primary Agent(s) | Supporting guidance |
+|---|---|---|
+| Brainstorm (start with \`/cc <idea>\`) | planner | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
+| Scope / Design / Plan (via \`/cc-next\`) | planner | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
+| Spec (via \`/cc-next\`) | reviewer | planner (if ambiguity or conflicts remain) |
+| TDD (via \`/cc-next\`) | test-author | doc-updater on public behavior/config changes |
+| Review (via \`/cc-next\`) | reviewer, security-reviewer | conditional second reviewer for high blast-radius diffs |
+| Ship (via \`/cc-next\`) | doc-updater | security-reviewer when release risk is elevated |
+`;
+}
+/**
+ * Cost tier routing for the core-5 agent roster.
+ */
+export function agentCostTierTable() {
+    return `| Tier | Use for | Example agents |
+|---|---|---|
+| \`deep\` | one heavy planning pass per stage | planner |
+| \`balanced\` | review and TDD specialists with stronger reasoning depth | reviewer, security-reviewer, test-author |
+| \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
+`;
+}
+/**
+ * AGENTS.md-ready section describing cclaw’s specialist delegation model.
+ */
+export function agentsAgentsMdBlock() {
+    return `### Agent Specialists
+
+cclaw materializes **5 core specialist agents** under \`.cclaw/agents/\`.
+
+${agentRoutingTable()}
+
+### Research Playbooks (in-thread)
+
+Research work is no longer modeled as standalone personas. Use in-thread playbooks under \`.cclaw/skills/research/\`:
+
+- \`repo-scan.md\`
+- \`learnings-lookup.md\`
+- \`framework-docs-lookup.md\`
+- \`best-practices-lookup.md\`
+- \`git-history.md\`
+
+### Activation modes
+
+- **Mandatory:** planner (scope/design/plan), reviewer + security-reviewer (review), test-author (tdd), doc-updater (ship).
+- **Proactive:** planner on ambiguity, security-reviewer on trust-boundary movement outside review, doc-updater on behavior/config drift.
+- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.
+
+### Cost-aware routing
+
+${agentCostTierTable()}
+
+**Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.
+`;
+}

package/dist/content/doctor-references.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCTOR_REFERENCE_DIR = ".cclaw/references/doctor";
+export declare const DOCTOR_REFERENCE_MARKDOWN: Record<string, string>;

package/dist/content/doctor-references.js

@@ -0,0 +1,144 @@
+import { RUNTIME_ROOT } from "../constants.js";
+export const DOCTOR_REFERENCE_DIR = `${RUNTIME_ROOT}/references/doctor`;
+export const DOCTOR_REFERENCE_MARKDOWN = {
+    "README.md": `# Doctor Reference Index
+
+Reference docs for \`cclaw doctor\` checks.
+
+## Categories
+
+- \`runtime-layout.md\` - runtime directories, generated commands, and skill files
+- \`hooks-and-lifecycle.md\` - hook wiring and harness lifecycle integration
+- \`harness-and-routing.md\` - harness shims, AGENTS/CLAUDE routing blocks, cursor rule
+- \`state-and-gates.md\` - flow-state integrity and gate evidence contracts
+- \`delegation-and-preamble.md\` - mandatory delegations and preamble budget controls
+- \`traceability.md\` - spec/plan/tdd trace matrix expectations
+- \`tooling-capabilities.md\` - local runtime prerequisites (bash/node/python/jq)
+- \`config-and-policy.md\` - config schema, rules policy, and validation references
+`,
+    "runtime-layout.md": `# Runtime Layout
+
+## Expected surfaces
+
+- \`.cclaw/\` root and generated subdirectories
+- stage command contracts under \`.cclaw/commands/\`
+- stage skills under \`.cclaw/skills/\`
+- utility command contracts (\`start\`, \`next\`, \`learn\`, \`status\`)
+- state files under \`.cclaw/state/\`
+
+## Typical fixes
+
+1. Run \`cclaw sync\` to re-materialize generated assets.
+2. If runtime is severely drifted, run \`cclaw upgrade\`.
+3. Avoid manual edits under generated runtime paths unless explicitly supported.
+`,
+    "hooks-and-lifecycle.md": `# Hooks And Lifecycle
+
+## Expected behavior
+
+- session start rehydrates flow + knowledge digest
+- pre-tool hooks run prompt/workflow guards
+- post-tool hooks run context monitor
+- stop hooks checkpoint progress
+- OpenCode uses plugin-based lifecycle integration
+
+## Typical fixes
+
+1. Re-run \`cclaw sync\` after harness config changes.
+2. Ensure harness is enabled in \`.cclaw/config.yaml\`.
+3. Validate hook JSON shape and remove malformed manual edits.
+`,
+    "harness-and-routing.md": `# Harness And Routing
+
+## Expected behavior
+
+- command shims exist for every enabled harness
+- managed routing block is present in \`AGENTS.md\` (and \`CLAUDE.md\` when applicable)
+- cursor rule mirrors workflow activation guidance
+- opencode plugin path is registered in opencode config
+
+## Typical fixes
+
+1. Confirm \`harnesses\` list in \`.cclaw/config.yaml\`.
+2. Run \`cclaw sync\` to re-generate shims/routing files.
+3. Remove stale harness artifacts for disabled harnesses via \`cclaw sync\`.
+`,
+    "state-and-gates.md": `# State And Gates
+
+## Expected behavior
+
+- \`flow-state.json\` has activeRunId, current stage, and consistent track/skippedStages
+- current-stage gate evidence is internally consistent
+- completed stages only include passed required gates
+
+## Typical fixes
+
+1. Run \`cclaw doctor --reconcile-gates\` to refresh current-stage gate catalog.
+2. Repair inconsistent stage artifacts, then re-run doctor.
+3. Do not manually mutate gate arrays without matching artifact evidence.
+`,
+    "delegation-and-preamble.md": `# Delegation And Preamble
+
+## Delegation contract
+
+- mandatory delegations for the current stage must be completed or waived
+- waivers should include an explicit reason
+- stale entries from previous runs are ignored by current-run checks
+
+## Preamble budget contract
+
+- preamble events are logged to \`.cclaw/state/preamble-log.jsonl\`
+- repeated entries inside cooldown windows indicate noisy preamble behavior
+- in TDD wave mode, emit once per wave unless plan materially changes
+
+## Typical fixes
+
+1. Append missing delegation records with \`completed\` or \`waived\` status.
+2. Record harness-limitation waivers when native delegation is unavailable.
+3. Reduce repeated preamble emissions and keep logs structured (\`ts/stage/trigger/hash\`).
+`,
+    "traceability.md": `# Traceability
+
+## Expected behavior
+
+- spec criteria map to plan tasks
+- plan tasks map to tdd slices/tests
+- no orphaned criteria/tasks/tests when downstream artifacts exist
+
+## Typical fixes
+
+1. Add stable IDs to spec/plan/tdd sections.
+2. Ensure mapping tables include every active criterion/task/slice.
+3. Re-run \`cclaw doctor\` after artifact updates.
+`,
+    "tooling-capabilities.md": `# Tooling Capabilities
+
+## Required
+
+- \`bash\` for runtime hook scripts
+- \`node\` for generated runtime scripts/plugins
+
+## Optional fallback
+
+- at least one of \`python3\` or \`jq\` for JSON parsing fallback paths
+
+## Typical fixes
+
+1. Install missing runtime tools.
+2. Keep at least one JSON fallback parser available (\`python3\` or \`jq\`).
+`,
+    "config-and-policy.md": `# Config And Policy
+
+## Expected behavior
+
+- \`.cclaw/config.yaml\` parses and uses supported keys/values
+- \`.cclaw/rules/rules.json\` matches generated policy schema
+- policy needles and required sections remain present in generated contracts
+
+## Typical fixes
+
+1. Repair invalid config values and run \`cclaw sync\`.
+2. Re-generate policy files via \`cclaw sync\` if drift is detected.
+3. Keep generated contracts aligned with stage schemas and policy needles.
+`
+};

package/dist/content/examples.js

@@ -379,7 +379,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 ## Review Army Contract
 
 - See \`07-review-army.json\`
-- Reconciliation summary: 1 duplicate collapsed (R-1 reported by spec-reviewer and code-reviewer), 0 conflicts
+- Reconciliation summary: 1 duplicate collapsed (R-1 reported by reviewer and security-reviewer), 0 conflicts
 
 ## Review Readiness Dashboard
 

package/dist/content/harnesses-doc.d.ts

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

package/dist/content/harnesses-doc.js

@@ -0,0 +1,95 @@
+import { HARNESS_ADAPTERS, harnessTier } from "../harness-adapters.js";
+import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./hook-events.js";
+function harnessTitle(harness) {
+    switch (harness) {
+        case "claude":
+            return "Claude Code";
+        case "cursor":
+            return "Cursor";
+        case "opencode":
+            return "OpenCode";
+        case "codex":
+            return "OpenAI Codex";
+    }
+}
+function tierDescription(tier) {
+    if (tier === "tier1")
+        return "full native automation";
+    if (tier === "tier2")
+        return "partial automation with waivers";
+    return "manual fallback only";
+}
+export function harnessIntegrationDocMarkdown() {
+    const harnesses = Object.keys(HARNESS_ADAPTERS);
+    const capabilityRows = harnesses
+        .map((harness) => {
+        const adapter = HARNESS_ADAPTERS[harness];
+        const tier = harnessTier(harness);
+        return `| ${harnessTitle(harness)} | \`${harness}\` | \`${tier}\` (${tierDescription(tier)}) | ${adapter.capabilities.nativeSubagentDispatch} | ${adapter.capabilities.hookSurface} | ${adapter.capabilities.structuredAsk} |`;
+    })
+        .join("\n");
+    const hookRows = HOOK_SEMANTIC_EVENTS.map((eventName) => {
+        const columns = harnesses
+            .map((harness) => {
+            const mapping = HOOK_EVENTS_BY_HARNESS[harness][eventName];
+            return mapping ?? "missing";
+        })
+            .join(" | ");
+        return `| \`${eventName}\` | ${columns} |`;
+    }).join("\n");
+    return `# Harness Integration Matrix
+
+Generated from \`src/harness-adapters.ts\` capabilities and hook event mappings.
+
+## Capability tiers
+
+| Harness | ID | Tier | Native subagent dispatch | Hook surface | Structured ask |
+|---|---|---|---|---|---|
+${capabilityRows}
+
+## Semantic hook event coverage
+
+| Event | Claude | Cursor | OpenCode | Codex |
+|---|---|---|---|---|
+${hookRows}
+
+## Interpretation
+
+- \`tier1\`: full native delegation + structured asks + full hook surface.
+- \`tier2\`: usable flow with capability gaps; mandatory delegation can require waivers.
+- \`tier3\`: manual-only fallback; no native automation guarantees.
+
+## Shared command contract
+
+All harnesses receive the same utility commands:
+
+- \`/cc\` - flow entry and resume
+- \`/cc-next\` - stage progression
+- \`/cc-learn\` - knowledge capture/lookup
+
+Stage order remains canonical:
+\`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\`
+
+## Install surfaces
+
+Always generated:
+
+- \`.cclaw/commands/*.md\`
+- \`.cclaw/skills/*/SKILL.md\`
+- \`.cclaw/references/**\`
+- \`.cclaw/state/*.json|*.jsonl\`
+- \`AGENTS.md\` managed block
+
+Harness-specific additions:
+
+- \`claude\`: \`.claude/commands/cc*.md\`, \`.claude/hooks/hooks.json\`
+- \`cursor\`: \`.cursor/commands/cc*.md\`, \`.cursor/hooks.json\`, \`.cursor/rules/cclaw-workflow.mdc\`
+- \`opencode\`: \`.opencode/commands/cc*.md\`, \`.opencode/plugins/cclaw-plugin.mjs\`, opencode plugin registration
+- \`codex\`: \`.codex/commands/cc*.md\`, \`.codex/hooks.json\`
+
+## Runtime observability
+
+- \`.cclaw/state/harness-gaps.json\` captures per-harness capability gaps for the active config.
+- \`cclaw doctor\` validates shim, hook, and lifecycle surfaces against this capability model.
+`;
+}

package/dist/content/hook-events.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessId } from "../types.js";
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+export declare const HOOK_EVENTS_BY_HARNESS: Record<HarnessId, Partial<Record<HookSemanticEvent, string>>>;

package/dist/content/hook-events.js

@@ -0,0 +1,42 @@
+export const HOOK_SEMANTIC_EVENTS = [
+    "session_rehydrate",
+    "pre_tool_prompt_guard",
+    "pre_tool_workflow_guard",
+    "post_tool_context_monitor",
+    "stop_checkpoint",
+    "precompact_digest"
+];
+export const HOOK_EVENTS_BY_HARNESS = {
+    claude: {
+        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
+        pre_tool_prompt_guard: "PreToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "PreToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "PostToolUse -> context-monitor.sh",
+        stop_checkpoint: "Stop -> stop-checkpoint.sh",
+        precompact_digest: "PreCompact -> pre-compact.sh"
+    },
+    cursor: {
+        session_rehydrate: "sessionStart/sessionResume/sessionClear/sessionCompact",
+        pre_tool_prompt_guard: "preToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "preToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "postToolUse -> context-monitor.sh",
+        stop_checkpoint: "stop -> stop-checkpoint.sh",
+        precompact_digest: "sessionCompact -> pre-compact.sh"
+    },
+    opencode: {
+        session_rehydrate: "plugin event handlers + transform rehydration",
+        pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard.sh",
+        pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard.sh",
+        post_tool_context_monitor: "plugin tool.execute.after -> context-monitor.sh",
+        stop_checkpoint: "plugin session.idle -> stop-checkpoint.sh",
+        precompact_digest: "plugin session.cleared/session.resumed hooks"
+    },
+    codex: {
+        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
+        pre_tool_prompt_guard: "PreToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "PreToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "PostToolUse -> context-monitor.sh",
+        stop_checkpoint: "Stop -> stop-checkpoint.sh",
+        precompact_digest: "PreCompact -> pre-compact.sh"
+    }
+};

package/dist/content/hooks.js

@@ -39,7 +39,7 @@ export const RUNTIME_SHELL_DETECT_ROOT = DETECT_ROOT;
 export function sessionStartScript(_options = {}) {
     return `#!/usr/bin/env bash
 # cclaw session-start hook — generated by cclaw sync
-# Injects using-cclaw + flow status + active artifacts + knowledge snapshot + checkpoint/activity summary.
+# Injects using-cclaw + flow status + active artifacts + compact knowledge digest + checkpoint/activity summary.
 set -euo pipefail
 
 ${DETECT_ROOT}
@@ -52,6 +52,7 @@ 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"
 KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.jsonl"
+KNOWLEDGE_DIGEST_FILE="$ROOT/${RUNTIME_ROOT}/state/knowledge-digest.md"
 META_SKILL="$ROOT/${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"
 
 # --- Read flow state ---
@@ -309,12 +310,72 @@ if [ -f "$META_SKILL" ]; then
   META_CONTENT=$(cat "$META_SKILL" 2>/dev/null || echo "")
 fi
 
-# --- Load knowledge snapshot (canonical JSONL tail + total count) ---
-KNOWLEDGE_SUMMARY=""
+# --- Build compact knowledge digest (stage-biased, top entries only) ---
+KNOWLEDGE_DIGEST=""
 LEARNINGS_COUNT=0
 if [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
-  KNOWLEDGE_SUMMARY=$(tail -n 30 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
   LEARNINGS_COUNT=$(grep -c '^{' "$KNOWLEDGE_FILE" 2>/dev/null || echo "0")
+  if command -v jq >/dev/null 2>&1; then
+    KNOWLEDGE_DIGEST=$(tail -n 200 "$KNOWLEDGE_FILE" 2>/dev/null | jq -Rsc --arg stage "$STAGE" '
+      split("\\n")
+      | map(select(length > 0))
+      | map(try fromjson catch null)
+      | map(select(type == "object"))
+      | map(select((.stage // null) == $stage or (.stage // null) == null))
+      | reverse
+      | .[0:8]
+      | map("- [" + ((.confidence // "unknown")|tostring) + " • " + ((.stage // "global")|tostring) + " • " + ((.domain // "general")|tostring) + "] " + ((.trigger // "trigger")|tostring) + " -> " + ((.action // "action")|tostring))
+      | join("\\n")
+    ' 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    KNOWLEDGE_DIGEST=$(python3 - "$KNOWLEDGE_FILE" "$STAGE" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+stage = sys.argv[2]
+entries = []
+try:
+    with open(path, "r", encoding="utf-8") as fh:
+        lines = fh.readlines()[-200:]
+    for raw in lines:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            obj = json.loads(raw)
+        except Exception:
+            continue
+        if not isinstance(obj, dict):
+            continue
+        row_stage = obj.get("stage")
+        if row_stage not in (stage, None):
+            continue
+        entries.append(obj)
+except Exception:
+    entries = []
+
+entries = list(reversed(entries))[:8]
+out = []
+for obj in entries:
+    conf = str(obj.get("confidence", "unknown"))
+    row_stage = str(obj.get("stage", "global"))
+    domain = str(obj.get("domain", "general"))
+    trigger = str(obj.get("trigger", "trigger"))
+    action = str(obj.get("action", "action"))
+    out.append(f"- [{conf} • {row_stage} • {domain}] {trigger} -> {action}")
+print("\\n".join(out))
+PY
+)
+  else
+    KNOWLEDGE_DIGEST=$(tail -n 8 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
+  fi
+fi
+
+if [ -n "$KNOWLEDGE_DIGEST" ]; then
+  printf '# Knowledge digest (auto-generated)\\n\\n%s\\n' "$KNOWLEDGE_DIGEST" > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
+elif [ -f "$KNOWLEDGE_DIGEST_FILE" ]; then
+  printf '# Knowledge digest (auto-generated)\\n\\n(no matching entries for current stage)\\n' > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
 fi
 
 # --- Installed cclaw-cli version vs. project's recorded version (one-block
@@ -391,10 +452,10 @@ if [ -n "$STAGE_SUGGESTION" ]; then
 $STAGE_SUGGESTION
 To disable suggestions persistently set ${RUNTIME_ROOT}/state/suggestion-memory.json -> enabled=false."
 fi
-if [ -n "$KNOWLEDGE_SUMMARY" ]; then
+if [ -n "$KNOWLEDGE_DIGEST" ]; then
   CTX="$CTX
-Knowledge snapshot (latest entries):
-$KNOWLEDGE_SUMMARY"
+Knowledge digest (top relevant entries):
+$KNOWLEDGE_DIGEST"
 fi
 if [ -n "$META_CONTENT" ]; then
   CTX="$CTX
@@ -833,6 +894,7 @@ export default function cclawPlugin(ctx) {
   const contextsDir = join(runtimeDir, "contexts");
   const sessionDigestPath = join(stateDir, "session-digest.md");
   const knowledgePath = join(runtimeDir, "knowledge.jsonl");
+  const knowledgeDigestPath = join(stateDir, "knowledge-digest.md");
   const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
 
   function ensureRuntimeDirs() {
@@ -937,8 +999,16 @@ export default function cclawPlugin(ctx) {
     }
   }
 
-  function readKnowledgeSnapshot() {
-    return readTailLines(knowledgePath, 30);
+  function readKnowledgeDigest() {
+    const digest = readFileText(knowledgeDigestPath).trim();
+    if (!digest) {
+      return readTailLines(knowledgePath, 12);
+    }
+    return digest
+      .split(/\\r?\\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .filter((line) => !line.startsWith("#"));
   }
 
   function buildBootstrap() {
@@ -965,8 +1035,8 @@ export default function cclawPlugin(ctx) {
     const warning = readLatestContextWarning();
     if (warning) parts.push("Latest context warning:", warning);
 
-    const knowledge = readKnowledgeSnapshot();
-    if (knowledge.length > 0) parts.push("Knowledge snapshot (latest entries):", ...knowledge);
+    const knowledge = readKnowledgeDigest();
+    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."