cclaw-cli 0.5.4 → 0.5.6

package/dist/content/learnings.js

@@ -1,10 +1,9 @@
 // ---------------------------------------------------------------------------
-// Learnings — markdown for /cc-learn skill, command contract, and AGENTS.md
-// Cclaw emits instructions only; agents use shell tools against JSONL on disk.
+// Knowledge store content for /cc-learn and stage self-improvement prompts.
 // ---------------------------------------------------------------------------
-const LEARNINGS_PATH = ".cclaw/learnings.jsonl";
+const KNOWLEDGE_PATH = ".cclaw/knowledge.md";
 const LEARN_SKILL_NAME = "learnings";
-const LEARN_SKILL_DESCRIPTION = "Project-scoped learnings store: read, search, add, prune, export, and stats for .cclaw/learnings.jsonl via shell tools (never edits application code).";
+const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: review and append rule/pattern/lesson entries in .cclaw/knowledge.md.";
 export function learnSkillMarkdown() {
     return `---
 name: ${LEARN_SKILL_NAME}
@@ -15,251 +14,104 @@ description: "${LEARN_SKILL_DESCRIPTION}"
 
 ## Overview
 
-This skill governs **${LEARNINGS_PATH}** — a project-scoped knowledge base that compounds over time. Each line is one JSON object (JSONL). Cclaw generates these instructions; **you** (the agent) perform reads and writes using shell tools (\`cat\`, \`tail\`, \`grep\`, \`jq\`, etc.) in the user's workspace.
+This skill manages the append-only project knowledge file at \`${KNOWLEDGE_PATH}\`.
 
-Treat learnings as durable project memory: patterns, pitfalls, preferences, architecture notes, tool quirks, and operational shortcuts that save real time on future sessions.
+Use it to keep durable knowledge that should survive sessions:
+- **rule**: hard constraint to follow every time
+- **pattern**: repeatable way that works well in this project
+- **lesson**: non-obvious outcome from a failure or trade-off
 
 ## HARD-GATE
 
-**Never modify production or application source code from this skill.** Commands under \`/cc-learn\` manage the **knowledge store only** (\`${LEARNINGS_PATH}\`, optional exports). Do not refactor, fix bugs, or change configs "while you are here" unless the user explicitly asked for that work outside \`/cc-learn\`.
+Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or an explicitly user-approved summary file. Do not modify application code here.
 
-- Allowed: read/write **${LEARNINGS_PATH}**, generate markdown summaries for the user, optional append to \`AGENTS.md\` when the user approves.
-- Forbidden: using learnings maintenance as a pretext to touch unrelated code paths.
+## Entry format (append-only)
 
-## Learning Entry Schema
-
-| Field | Required | Description |
-|---|---|---|
-| \`ts\` | yes (on write) | ISO-8601 UTC timestamp. **Auto-inject** on every append; never rely on the model to invent wall-clock time — use the shell (\`date -u +%Y-%m-%dT%H:%M:%SZ\`) or equivalent and embed in JSON. |
-| \`skill\` | yes | Originating Cclaw stage or context (e.g. \`brainstorm\`, \`scope\`, \`learnings\`). |
-| \`type\` | yes | One of: \`pattern\`, \`pitfall\`, \`preference\`, \`architecture\`, \`tool\`, \`operational\`. |
-| \`key\` | yes | Stable **kebab-case** identifier for dedup and search (e.g. \`avoid-barrel-reexports-in-tests\`). |
-| \`insight\` | yes | Single human-readable sentence (no multi-paragraph essays). |
-| \`confidence\` | yes | Integer **1–10** (see scale in “Operational Self-Improvement” on stage skills). |
-| \`source\` | yes | \`observed\` \| \`user-stated\` \| \`inferred\`. Drives decay rules. |
-| \`files\` | no | \`string[]\` of repo-relative paths this insight touched (for staleness checks in prune). |
-| \`branch\` | no | Branch name when recorded (optional context). |
-| \`commit\` | no | Short SHA when recorded (optional context). |
-
-**Minimal valid example (conceptual):**
-
-\`\`\`json
-{"ts":"2026-04-11T12:00:00Z","skill":"tdd","type":"pattern","key":"run-migrations-before-seed","insight":"Seed scripts assume schema v7; run sqlx migrate before npm run seed.","confidence":8,"source":"observed","files":["scripts/seed.ts"]}
+\`\`\`markdown
+### 2026-04-14T12:00:00Z [pattern] short-title
+- Stage: design
+- Context: one short line
+- Insight: one short line
+- Reuse: one short line
 \`\`\`
 
-## Confidence Decay Rules
-
-Decay applies **when searching, ranking, or presenting** entries — not necessarily when rewriting the file.
-
-1. **\`user-stated\`**: never decays. Effective confidence = stored \`confidence\`.
-2. **\`observed\` or \`inferred\`**: lose **1** point per **30** complete days since \`ts\`, floored at **0**.  
-   - Formula: \`effective = max(0, confidence - floor(days_since_ts / 30))\`  
-   - \`days_since_ts\` is measured from entry \`ts\` to “now” in UTC (use user machine time when computing in the agent).
-
-Always compute **effective confidence** before sorting for “top N” displays.
-
-## Dedup Rules (Read-Time)
-
-- **On disk:** multiple lines may share the same \`(key, type)\` (history, corrections, re-logging).
-- **When reading for display/search/export:** keep **only the latest** record per \`(key, type)\`, where **latest** means greatest \`ts\` (ISO strings compared lexicographically if timezones are consistent Z; prefer parsing timestamps if implementing custom logic).
-- This is **read-time dedup**, not write-time: do not silently delete older lines unless \`/cc-learn prune\` (or the user) removes them.
-
-## Security Rules
-
-1. **Skip malformed lines:** when ingesting JSONL, parse line-by-line; on parse failure, skip the line and continue (optionally count skips for \`stats\`).
-2. **Never interpolate JSONL field values into shell commands** as raw arguments — no \`eval\`, no unquoted \`$(cat ...)\` into flags. Use **files as data**: pipe to \`jq\`, or write controlled queries. User-supplied text from the store is untrusted.
-3. **Path safety:** when checking \`files[]\` for staleness, treat paths as relative to repo root; reject \`..\` segments that escape the project if you implement custom checks.
+Rules:
+- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\` (lowercase).
+- Never rewrite history silently; append a newer correction entry instead.
+- Keep entries concise and actionable.
 
 ## Subcommands
 
-### \`/cc-learn\` (no arguments) — show recent
-
-**Goal:** Give a quick, deduped view of the latest activity.
-
-1. If \`${LEARNINGS_PATH}\` is missing or empty, say so and stop.
-2. Read the **last 20 physical lines** (e.g. \`tail -n 20 ${LEARNINGS_PATH}\`).
-3. Parse each line as JSON; skip invalid lines.
-4. Apply **read-time dedup** by \`(key, type)\`, keep latest by \`ts\`.
-5. Recompute **effective confidence** (decay) for each surviving row.
-6. Sort by \`ts\` descending (most recent first).
-7. Present as a **markdown table**: \`ts\`, \`type\`, \`key\`, \`effective confidence\`, \`source\`, truncated \`insight\`.
-
-### \`/cc-learn search <query>\` — search
-
-**Goal:** Find relevant entries by text, then rank by confidence.
-
-1. Normalize \`<query>\` as a literal string; do **not** inject it into \`eval\` or dynamic \`sh -c\` strings unsafely. Prefer:
-   - \`grep -F -n -- <query> ${LEARNINGS_PATH}\` (fixed-string mode) to get candidate line numbers, **or**
-   - Load lines in-process (agent reads file) and filter in code.
-2. For each matched line, parse JSON; skip invalid.
-3. Apply read-time dedup (\`(key, type)\` → latest \`ts\`).
-4. Filter where **case-insensitive** match hits any of: \`insight\`, \`key\`, \`type\` (and optionally \`skill\`).
-5. Compute **effective confidence**; sort **descending** by effective confidence, then by \`ts\` desc as tiebreaker.
-6. Show **top 20** as a table (same columns as “show recent”).
-
-### \`/cc-learn add\` — manual add
-
-**Goal:** Interactive append with explicit user input.
-
-1. Ask the user (one prompt at a time is fine): \`type\`, \`key\` (enforce kebab-case), \`insight\` (one sentence), \`confidence\` (1–10).
-2. Set \`source\` to **\`"user-stated"\`** always for this path.
-3. Set \`skill\` to \`learnings\` (or the user’s stated originating context if they insist).
-4. Obtain \`ts\` from shell UTC timestamp.
-5. Build one JSON object on a **single line** (no pretty-printed multi-line JSON inside JSONL).
-6. Append: e.g. \`printf '%s\\n' '<json-line>' >> ${LEARNINGS_PATH}\` from a **heredoc or file** the agent controls — avoid breaking quoting.
-7. **Verification (required):** after append, read back the **last line** of the file, parse as JSON, confirm \`key\` and \`ts\` match what you wrote.
-
-### \`/cc-learn prune\` — staleness & conflicts
-
-**Goal:** Curate quality; never delete without user confirmation.
-
-1. Load up to **100** recent lines (prefer tail-first read, then widen if needed).
-2. Parse; skip malformed; apply read-time dedup to get canonical latest per \`(key, type)\`.
-3. **Staleness:** if \`files\` is a non-empty array, check each path exists relative to repo root. If **any** path is missing, flag the entry **STALE** (file targets gone).
-4. **Conflicts:** if the same \`key\` appears with **different** \`insight\` strings across retained history (or between latest and visible duplicates), flag **CONFLICT** and show the competing insights with their \`ts\` / \`source\`.
-5. For each flagged item, ask the user: **Remove** / **Keep** / **Update** (update = rewrite insight or files list after confirmation).
-6. If removing: prefer rewriting the file without those lines **only** when the user confirms; use a safe write pattern (write temp → replace) if the environment allows.
-
-### \`/cc-learn export\` — high-signal markdown rollup
-
-**Goal:** Summarize the best current knowledge for humans and \`AGENTS.md\`.
+### \`/cc-learn\` (default)
+- Show the last 30 lines from \`${KNOWLEDGE_PATH}\`.
+- If file is missing or empty, report that clearly.
 
-1. Parse full file or a bounded read if huge; skip malformed.
-2. Read-time dedup by \`(key, type)\`.
-3. Compute effective confidence; take **top 50** by effective confidence (tiebreak: newer \`ts\`).
-4. Emit markdown grouped under:
-   - \`## Patterns\` (\`type === "pattern"\`)
-   - \`## Pitfalls\` (\`pitfall\`)
-   - \`## Preferences\` (\`preference\`)
-   - \`## Architecture\` (\`architecture\`)
-   - \`## Tools\` (\`tool\` and optionally \`operational\` — put \`operational\` here if you want a single “tools & ops” bucket, or add \`## Operational\` if the user prefers separation)
-5. Under each section, bullet format: **\`key\` (conf X):** insight.
-6. Ask the user: **append to \`AGENTS.md\`** vs **save as a separate file** (e.g. \`.cclaw/learnings-summary.md\`). Do nothing destructive without explicit choice.
+### \`/cc-learn search <query>\`
+- Perform case-insensitive text search in \`${KNOWLEDGE_PATH}\`.
+- Return matched headings and nearby lines.
 
-### \`/cc-learn stats\` — inventory
-
-1. Parse all lines; count **skipped malformed** separately.
-2. After read-time dedup (canonical latest per \`(key, type)\`):
-   - **total** canonical entries
-   - **unique keys** count
-   - Breakdown counts by \`type\` and by \`source\`
-   - **Average confidence** (raw stored values) **and** optionally average **effective** confidence
-3. Present as compact markdown (table + short narrative).
-
-## Handoff
-
-This skill **does not** hand off to any \`/cc-<stage>\` command. Return control to the user or the prior task context when finished.
-
-## Verification (Writes)
-
-After **any** write operation (\`add\`, \`prune\` removal, export append):
-
-1. Read back the **last line** of \`${LEARNINGS_PATH}\` (or the written artifact if appending elsewhere).
-2. Parse as JSON; if parse fails, treat the write as **failed** and report immediately.
-3. For append, confirm the final object’s \`ts\` / \`key\` match the intended mutation.
-
----
-
-**Primary location on disk (generated by Cclaw installer):** \`.cclaw/skills/${LEARN_SKILL_NAME}/SKILL.md\` (this content).
+### \`/cc-learn add\`
+- Ask for: \`type\`, \`short title\`, \`context\`, \`insight\`, \`reuse\`.
+- Append one entry using current UTC timestamp.
+- Re-read the file tail and confirm the entry was written.
 `;
 }
 export function learnCommandContract() {
-    const skillMdPath = `.cclaw/skills/${LEARN_SKILL_NAME}/SKILL.md`;
     return `# /cc-learn
 
 ## Purpose
 
-Manage the project learnings JSONL store at \`${LEARNINGS_PATH}\`: inspect recent entries, search, manually append, prune stale or conflicting records, export a high-confidence markdown digest, and print aggregate stats. This command is **knowledge-store only** — it is not an excuse to edit application code.
+Manage the project knowledge store at \`${KNOWLEDGE_PATH}\` (append-only markdown).
 
 ## HARD-GATE
 
-Never modify production or application source code while executing \`/cc-learn\`. Only touch \`${LEARNINGS_PATH}\` (and user-approved summary targets like \`AGENTS.md\` or \`.cclaw/learnings-summary.md\`).
+Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\` (or user-approved summary output).
 
 ## Subcommands
 
 | subcommand | args | description |
 |---|---|---|
-| (default) | — | Show recent: tail 20 lines, dedup by \`(key,type)\` latest \`ts\`, apply decay for display, table output. |
-| \`search\` | \`<query>\` | \`grep -F\` or in-agent scan for \`<query>\` across \`insight\` / \`key\` / \`type\`; dedup; decay; top 20 by effective confidence. |
-| \`add\` | — | Prompt user for \`type\`, \`key\`, \`insight\`, \`confidence\`; set \`source: "user-stated"\`; inject \`ts\`; append one JSON line; verify by reading last line. |
-| \`prune\` | — | Load ≤100 entries; flag **STALE** if \`files\` paths missing; flag **CONFLICT** if same \`key\` diverges in \`insight\`; user chooses Remove / Keep / Update per flag. |
-| \`export\` | — | Dedup; top 50 by effective confidence; markdown sections (Patterns, Pitfalls, Preferences, Architecture, Tools); user picks append to \`AGENTS.md\` vs separate file. |
-| \`stats\` | — | Totals, unique keys, breakdown by \`type\` and \`source\`, average confidence (+ optional effective average); report malformed line count. |
-
-## Learning Entry Schema
-
-| Field | Required | Description |
-|---|---|---|
-| \`ts\` | yes | ISO timestamp; auto on write. |
-| \`skill\` | yes | Originating stage or context. |
-| \`type\` | yes | \`pattern\` \| \`pitfall\` \| \`preference\` \| \`architecture\` \| \`tool\` \| \`operational\` |
-| \`key\` | yes | Kebab-case stable id. |
-| \`insight\` | yes | One-sentence insight. |
-| \`confidence\` | yes | 1–10 |
-| \`source\` | yes | \`observed\` \| \`user-stated\` \| \`inferred\` |
-| \`files\` | no | \`string[]\` relative paths (optional). |
-| \`branch\` / \`commit\` | no | Optional provenance. |
-
-## Confidence Decay
-
-- \`user-stated\`: **no decay**.
-- \`observed\` / \`inferred\`: **−1** effective confidence per **30** days since \`ts\`, floor at **0**.
-- Always apply decay **before sorting** for search / show / export rankings.
-
-## Dedup Rules
-
-Multiple JSONL lines may share the same \`(key, type)\`. When reading, keep **only the line with the latest \`ts\`** per pair. **Do not** assume uniqueness on disk.
-
-## Security Rules
-
-- Skip malformed JSONL lines; continue processing.
-- **Never** splice stored field values into shell control flow; treat file contents as data (\`jq\`, controlled greps, agent-side parsing).
-
-## Primary Skill (${skillMdPath})
-
-Canonical instructions live at \`${skillMdPath}\` (generated by Cclaw).
+| (default) | — | Show recent knowledge entries (tail view). |
+| \`search\` | \`<query>\` | Search knowledge text for relevant prior rules/patterns/lessons. |
+| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\`. |
 `;
 }
 export function selfImprovementBlock(stageName) {
-    const skill = JSON.stringify(stageName);
     return `## Operational Self-Improvement
 
-After completing this stage, reflect briefly:
-- Did any command fail unexpectedly?
-- Did you backtrack or retry something that a hint would have prevented?
-- Did you discover a project quirk (unusual config, naming convention, gotcha)?
+After this stage, ask:
+- Did I discover a non-obvious reusable **rule** or **pattern**?
+- Did a failure reveal a reusable **lesson**?
 
-If an insight would save **5+ minutes next time**, log it:
+If yes, append one concise entry to \`${KNOWLEDGE_PATH}\`:
 
 \`\`\`bash
-echo '{"skill":${skill},"type":"operational","key":"[kebab-case-key]","insight":"[one sentence]","confidence":7,"source":"observed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> .cclaw/learnings.jsonl
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+cat >> ${KNOWLEDGE_PATH} <<EOF
+### $TS [pattern] short-title
+- Stage: ${stageName}
+- Context: what situation triggered this
+- Insight: what should be remembered
+- Reuse: how to apply this next time
+EOF
 \`\`\`
 
-Guidelines:
-- Skip transient errors (network blips, typos). Log structural insights only.
-- Use consistent keys so future entries dedup correctly.
-- **\`ts\` is required** on every line — the example uses \`date -u +%Y-%m-%dT%H:%M:%SZ\` (UTC). If nested quoting is awkward, build JSON in the agent and \`printf '%s\\n' '<one-line-json>'\` instead.
-- Confidence 1-3: uncertain pattern. 4-6: likely pattern. 7-9: confirmed pattern. 10: absolute rule.
+Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`.
 `;
 }
 export function learningsSearchPreamble(stage) {
-    return `## Prior Learnings (load at stage start)
-
-Before beginning this stage, search the project learnings store for relevant prior knowledge:
-
-\`\`\`bash
-grep -i "${stage}" ${LEARNINGS_PATH} 2>/dev/null | tail -n 5
-\`\`\`
+    return `## Prior Knowledge (load at stage start)
 
-If learnings are found, incorporate them into your analysis. When a finding matches a past learning, note: **"Prior learning applied: [key] (confidence N/10)"**.
+Before stage work, search \`${KNOWLEDGE_PATH}\` for relevant entries (for example: \`${stage}\`, affected systems, key constraints) and apply them explicitly.
 
-If the store is empty or the file does not exist, skip this step silently.
+If the file is empty, continue normally.
 `;
 }
 export function learningsAgentsMdBlock() {
-    return `### Learnings Store
+    return `### Knowledge Store
 
-\`${LEARNINGS_PATH}\` — JSONL knowledge base. At session start: \`tail -n 20 ${LEARNINGS_PATH}\` → parse → dedup by \`(key,type)\` → decay → show top 3.
-After each stage: follow "Operational Self-Improvement" block. Manage: \`/cc-learn\` (show | search | add | prune | export | stats).
+\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`.
+At session start and stage transitions, load recent entries and apply relevant ones.
+If a non-obvious reusable rule/pattern/lesson is discovered, append a new entry.
 `;
 }

package/dist/content/meta-skill.js

@@ -26,7 +26,7 @@ Task arrives
     |
     +-- New idea / starting fresh?  --> /cc <idea>  (starts brainstorm)
     +-- Resuming / continuing?  --> /cc  or  /cc-next
-    +-- Want to check/add project learnings?  --> /cc-learn
+    +-- Want to check/add project knowledge?  --> /cc-learn
     +-- No cclaw stage applies?  --> Respond normally
 \`\`\`
 
@@ -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/\`; cclaw sync/runtime keeps run snapshots in \`.cclaw/runs/<activeRunId>/artifacts/\` aligned as the evidence trail.
+5. **Artifacts are mandatory.** Each stage writes to \`.cclaw/artifacts/\`; completed features are archived later with \`cclaw archive\`.
 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
@@ -108,7 +108,7 @@ Use this loading order to keep context lean while preserving depth:
 
 ### 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/learnings/SKILL.md\` for durable knowledge capture and reuse
 ## Decision Protocol
 
 When a stage requires user input (approval, choice, direction), use this structured pattern:
@@ -138,15 +138,12 @@ Watch for these anti-patterns:
 - **Hollow reviews** — "looks good" without checking spec compliance
 - **Cargo-cult artifacts** — filling templates without real thought
 
-## Learnings Integration
+## Knowledge Integration
 
-At session start, check \`.cclaw/learnings.jsonl\` for project-specific knowledge:
-- Run \`tail -n 20 .cclaw/learnings.jsonl\` and surface the top 3 highest-confidence entries
-- Apply relevant learnings to the current task
-- After each stage, reflect: did anything happen that would save 5+ minutes next time? If so, log it.
+At session start and stage transitions, check \`.cclaw/knowledge.md\` for project-specific knowledge:
+- Review recent entries and apply relevant rules/patterns to the current task
+- If you discover a non-obvious reusable rule or pattern, append a new entry with type \`rule\`, \`pattern\`, or \`lesson\`
 
-## Observation Hooks
-
-If tool observation is enabled, cclaw captures tool usage patterns (PreToolUse/PostToolUse) to \`.cclaw/observations.jsonl\`. At session stop, observations are analyzed and valuable patterns are promoted to learnings. This is automatic — you do not need to manage it.
+Knowledge capture is append-only and should preserve historical context rather than rewriting prior entries.
 `;
 }

package/dist/content/next-command.js

@@ -7,7 +7,7 @@ function flowStatePath() {
     return `${RUNTIME_ROOT}/state/flow-state.json`;
 }
 function delegationLogPathLine() {
-    return `${RUNTIME_ROOT}/runs/<activeRunId>/delegation-log.json`;
+    return `${RUNTIME_ROOT}/state/delegation-log.json`;
 }
 /**
  * Command contract for /cc-next — the primary progression command.
@@ -38,7 +38,7 @@ This is the only progression command the user needs to drive the entire flow. St
 ## Algorithm (mandatory)
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
-2. Parse JSON. Capture \`currentStage\`, \`activeRunId\`, and \`stageGateCatalog[currentStage]\`.
+2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
 3. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
 4. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
 5. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
@@ -110,7 +110,7 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 ### Step 1: Read state
 
 1. Open **\`${flowPath}\`**.
-2. Record \`currentStage\`, \`activeRunId\`, \`stageGateCatalog[currentStage]\`.
+2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
 3. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 
 ### Step 2: Evaluate gates

package/dist/content/observe.d.ts

@@ -1,12 +1,9 @@
 /**
- * Tool observation system — captures PreToolUse/PostToolUse events
- * to .cclaw/observations.jsonl for continuous learning.
+ * Hook helper scripts and harness hook JSON generators.
  *
- * observe.sh: reads hook JSON from stdin, extracts tool name + truncated I/O,
- * appends a JSONL line to .cclaw/observations.jsonl.
- *
- * summarize-observations.sh: run at session stop, reads recent observations,
- * identifies patterns, and appends new learnings to .cclaw/learnings.jsonl.
+ * This module still provides prompt/workflow/context guard scripts and
+ * cross-harness hook wiring. Observation pipeline scripts are retained only
+ * for backward compatibility and are not wired by default runtime generation.
  */
 export interface PromptGuardOptions {
     strictMode?: boolean;

package/dist/content/observe.js

@@ -1,12 +1,9 @@
 /**
- * Tool observation system — captures PreToolUse/PostToolUse events
- * to .cclaw/observations.jsonl for continuous learning.
+ * Hook helper scripts and harness hook JSON generators.
  *
- * observe.sh: reads hook JSON from stdin, extracts tool name + truncated I/O,
- * appends a JSONL line to .cclaw/observations.jsonl.
- *
- * summarize-observations.sh: run at session stop, reads recent observations,
- * identifies patterns, and appends new learnings to .cclaw/learnings.jsonl.
+ * This module still provides prompt/workflow/context guard scripts and
+ * cross-harness hook wiring. Observation pipeline scripts are retained only
+ * for backward compatibility and are not wired by default runtime generation.
  */
 import { RUNTIME_ROOT } from "../constants.js";
 import { RUNTIME_SHELL_DETECT_ROOT } from "./hooks.js";
@@ -102,7 +99,7 @@ REASONS=""
 
 case "$TOOL_LOWER" in
   write|edit|multiedit|delete|applypatch|runcommand|shell|terminal|execcommand)
-    if printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/(state|artifacts|hooks|skills|commands|agents|runs|learnings)'; then
+    if printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/(state|artifacts|hooks|skills|commands|agents|runs|knowledge)'; then
       REASONS="write_to_cclaw_runtime"
     fi
     ;;
@@ -1595,9 +1592,6 @@ export function claudeHooksJsonWithObservation() {
                         }, {
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
-                        }, {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh pre`
                         }]
                 }],
             PostToolUse: [{
@@ -1605,24 +1599,14 @@ export function claudeHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
-                        }, {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh post`
                         }]
                 }],
             Stop: [{
-                    hooks: [
-                        {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/summarize-observations.sh`,
-                            timeout: 15
-                        },
-                        {
+                    hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
-                        }
-                    ]
+                        }]
                 }]
         }
     }, null, 2);
@@ -1650,21 +1634,12 @@ export function cursorHooksJsonWithObservation() {
                 }, {
                     matcher: "*",
                     command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
-                }, {
-                    matcher: "*",
-                    command: `bash ${RUNTIME_ROOT}/hooks/observe.sh pre`
                 }],
             postToolUse: [{
                     matcher: "*",
                     command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
-                }, {
-                    matcher: "*",
-                    command: `bash ${RUNTIME_ROOT}/hooks/observe.sh post`
                 }],
-            stop: [
-                { command: `bash ${RUNTIME_ROOT}/hooks/summarize-observations.sh`, timeout: 15 },
-                { command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`, timeout: 10 }
-            ]
+            stop: [{ command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`, timeout: 10 }]
         }
     }, null, 2);
 }
@@ -1688,9 +1663,6 @@ export function codexHooksJsonWithObservation() {
                         }, {
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
-                        }, {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh pre`
                         }]
                 }],
             PostToolUse: [{
@@ -1698,24 +1670,14 @@ export function codexHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
-                        }, {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh post`
                         }]
                 }],
             Stop: [{
-                    hooks: [
-                        {
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/summarize-observations.sh`,
-                            timeout: 15
-                        },
-                        {
+                    hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
-                        }
-                    ]
+                        }]
                 }]
         }
     }, null, 2);

package/dist/content/session-hooks.js

@@ -26,7 +26,7 @@ These are prompt-discipline guidelines that complement the real hooks cclaw gene
 When a new session begins in any harness:
 
 1. **Read flow state:** Load \`.cclaw/state/flow-state.json\` to find the current stage and completed stages.
-2. **Load learnings:** Run \`tail -n 20 .cclaw/learnings.jsonl 2>/dev/null\` and surface the top 3 highest-confidence entries (see learnings skill for dedup/decay).
+2. **Load knowledge:** Review recent entries from \`.cclaw/knowledge.md\` and surface the most relevant rules/patterns.
 3. **Check for in-progress work:** If the last stage is incomplete, remind the user and offer to resume.
 4. **Load suggestion memory:** Read \`.cclaw/state/suggestion-memory.json\` and honor \`enabled=false\` opt-out.
 5. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
@@ -35,7 +35,7 @@ When a new session begins in any harness:
 
 \`\`\`
 Cclaw flow state: [current stage] ([N] of 9 stages completed)
-Top learnings: [key1] (confidence N), [key2] (confidence N), [key3] (confidence N)
+Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
 Next action: /cc-[stage] to continue, or describe what you'd like to do.
 \`\`\`
 
@@ -45,7 +45,7 @@ Before ending a session or when context is full:
 
 1. **Verify no pending changes:** All modified files must be either committed or explicitly reverted.
 2. **Update flow state:** Mark the current stage as its actual status (DONE / DONE_WITH_CONCERNS / BLOCKED).
-3. **Write learnings:** If any insight from this session would save 5+ minutes next time, append to \`.cclaw/learnings.jsonl\`.
+3. **Write knowledge:** If any non-obvious reusable insight appears, append to \`.cclaw/knowledge.md\` with type \`rule\`, \`pattern\`, or \`lesson\`.
 4. **Create checkpoint:** Write a brief status note to the current artifact or as a comment in flow-state.json.
 
 ### Stop conditions (agent must halt and report)
@@ -61,7 +61,7 @@ When resuming work after a break:
 
 1. Re-read \`.cclaw/state/flow-state.json\` (may have changed externally).
 2. Re-read the current stage's artifact to verify it matches your last checkpoint.
-3. Re-load top learnings.
+3. Re-load recent knowledge entries.
 4. Continue from the last incomplete step — do not restart the stage.
 
 ## Proactive Suggestion Memory
@@ -121,16 +121,16 @@ When approaching context limits:
 - Ending a session with modified but uncommitted files
 - No flow state update after completing work
 - Restarting a stage from scratch instead of resuming from checkpoint
-- Ignoring learnings from prior sessions
+- Ignoring knowledge from prior sessions
 `;
 }
 export function sessionHooksAgentsMdBlock() {
     return `### Session Guidelines
 
 Session boundary behavior (real hooks inject context automatically; guidelines cover manual steps):
-- **Start:** Hooks inject flow state + top learnings. Check for in-progress work, show status.
-- **Stop:** Hooks remind about checkpoint. Verify no pending changes, update flow state, write learnings.
-- **Resume:** Re-read state, verify artifact, re-load learnings, continue from last step.
+- **Start:** Hooks inject flow state + knowledge snapshot. Check for in-progress work, show status.
+- **Stop:** Hooks remind about checkpoint. Verify no pending changes, update flow state, append useful knowledge.
+- **Resume:** Re-read state, verify artifact, re-load knowledge, continue from last step.
 
 Skill: \`.cclaw/skills/session/SKILL.md\`
 `;