cclaw-cli 0.7.0 → 0.8.0

package/dist/content/agents.d.ts

@@ -33,6 +33,15 @@ export declare function agentMarkdown(agent: AgentDefinition): string;
  * Markdown table mapping Cclaw stage entry points to specialist agents.
  */
 export declare function agentRoutingTable(): string;
+/**
+ * Cost tier routing: keep heavy reasoning on the \`deep\` tier (planner, a
+ * single post-review reconciliation), push read-only research and narrow
+ * machine-only checks to the \`fast\` tier, and default review to \`balanced\`.
+ * This table is emitted into AGENTS.md so harness users understand why
+ * certain specialists are automatically fan-out-able without blowing the
+ * context budget.
+ */
+export declare function agentCostTierTable(): string;
 /**
  * AGENTS.md-ready section describing Cclaw’s specialist delegation model.
  */

package/dist/content/agents.js

@@ -170,6 +170,157 @@ export const CCLAW_AGENTS = [
             "**Scope control:** only update what needs updating — **do not rewrite** docs that remain correct.",
         ].join("\n"),
     },
+    {
+        name: "repo-research-analyst",
+        description: "PROACTIVE at the start of brainstorm/scope/design: delegates deep codebase exploration — existing modules, ownership boundaries, duplication, and reuse candidates — so the primary agent can plan from a grounded map instead of guesses.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "fast",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design"],
+        body: [
+            "You are a **repo research analyst**.",
+            "",
+            "Scan the codebase for existing modules, helpers, patterns, and ownership boundaries relevant to the current task. Deliver a grounded map the primary agent can plan against.",
+            "",
+            "**Process:**",
+            "",
+            "1. Identify the task domain keywords (nouns, verbs, known file/module names).",
+            "2. Glob for obvious homes (by convention: `src/**`, `packages/**`, `apps/**`, etc.).",
+            "3. Grep for existing implementations of the same capability.",
+            "4. Enumerate adjacent tests/fixtures that already cover the area.",
+            "5. Flag duplication, near-duplicates, and reuse candidates with file:line.",
+            "",
+            "**Output schema:**",
+            "",
+            "- `Relevant modules:` bulleted list with `path — 1-line purpose`.",
+            "- `Reuse candidates:` bulleted list with `file:line — why this could absorb the change`.",
+            "- `Ownership hints:` any CODEOWNERS / README / comment signals.",
+            "- `Gaps:` what does NOT yet exist that the task would need.",
+            "",
+            "**Role boundary:** read-only. Do NOT edit files. Cite `file:line` for every claim; never guess paths.",
+        ].join("\n"),
+    },
+    {
+        name: "learnings-researcher",
+        description: "PROACTIVE before every non-trivial stage: streams `.cclaw/knowledge.jsonl` and surfaces the entries (rules, patterns, lessons, compounds) most relevant to the current task before the primary agent commits to a direction.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "fast",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"],
+        body: [
+            "You are a **project learnings researcher**.",
+            "",
+            "Stream `.cclaw/knowledge.jsonl` and surface the entries most relevant to the current task. The goal is to prevent the primary agent from re-learning things the project already wrote down.",
+            "",
+            "**Process:**",
+            "",
+            "1. Parse `.cclaw/knowledge.jsonl` (one JSON object per line, strict schema).",
+            "2. Match entries by `domain`, `stage`, and substring overlap with the current task description.",
+            "3. Rank by `confidence` then recency (`created`).",
+            "4. Group by `type` (rule, pattern, lesson, compound).",
+            "5. Return the top 10 entries verbatim with a one-line reason each.",
+            "",
+            "**Output schema:**",
+            "",
+            "- `Matched rules:` list of `trigger → action (confidence)`.",
+            "- `Matched patterns:` list of `trigger → action (confidence)`.",
+            "- `Matched lessons:` list of `trigger → action (confidence)`.",
+            "- `Matched compounds:` list of `trigger → action (confidence)`.",
+            "- `No-match note:` if nothing relevant exists, say so explicitly.",
+            "",
+            "**Role boundary:** read-only. Never rewrite or delete entries — corrections are appended by the primary agent via `/cc-learn add`.",
+        ].join("\n"),
+    },
+    {
+        name: "framework-docs-researcher",
+        description: "PROACTIVE during design/spec/tdd for tasks that touch a specific framework, library, or SDK: fetches authoritative, version-aware documentation (via context7 when available) so implementation matches the live API, not training priors.",
+        tools: ["Read", "Grep", "Glob", "WebSearch", "WebFetch"],
+        model: "fast",
+        activation: "on-demand",
+        relatedStages: ["design", "spec", "tdd", "review"],
+        body: [
+            "You are a **framework documentation researcher**.",
+            "",
+            "Fetch authoritative, version-aware docs for any library/framework/SDK/CLI the current task depends on. The goal is to replace model priors with live API references.",
+            "",
+            "**Process:**",
+            "",
+            "1. Identify the exact library + version from the repo (package.json, pyproject, go.mod, etc.).",
+            "2. If context7 MCP is available, use it first — it returns docs keyed to the installed version.",
+            "3. Otherwise WebSearch / WebFetch for the official docs site or the tagged release changelog.",
+            "4. Capture: public API signatures, breaking changes since a major version back, migration notes, and any deprecated paths relevant to the task.",
+            "",
+            "**Output schema:**",
+            "",
+            "- `Library + version:` name and resolved version.",
+            "- `Key APIs:` bullet list of signatures the task will touch.",
+            "- `Breaking changes:` notable deltas relevant to the task.",
+            "- `Gotchas:` footguns, deprecated paths, version-gated flags.",
+            "- `Source:` URL(s) or MCP reference used.",
+            "",
+            "**Role boundary:** never invent APIs. If docs are unclear, say `UNKNOWN` and surface the gap instead of guessing.",
+        ].join("\n"),
+    },
+    {
+        name: "best-practices-researcher",
+        description: "PROACTIVE during design/spec when the task touches a well-known domain (auth, caching, rate limiting, observability, accessibility, etc.): delivers a short, opinionated best-practice summary grounded in citable sources.",
+        tools: ["Read", "Grep", "Glob", "WebSearch", "WebFetch"],
+        model: "fast",
+        activation: "on-demand",
+        relatedStages: ["brainstorm", "scope", "design", "spec", "review"],
+        body: [
+            "You are a **best-practices researcher**.",
+            "",
+            "For a named domain (auth, caching, rate limiting, observability, accessibility, etc.), deliver a short, opinionated best-practice summary that is citable and current.",
+            "",
+            "**Process:**",
+            "",
+            "1. Restate the domain + narrow it to the sub-problem the task is solving.",
+            "2. Gather 3–5 authoritative sources (official docs, IETF / W3C / OWASP references, well-known community standards).",
+            "3. Surface the 5–8 practices most relevant to the task, each with one-line rationale + source.",
+            "4. Flag practices that look common but are anti-patterns today.",
+            "",
+            "**Output schema:**",
+            "",
+            "- `Domain + sub-problem:` one sentence.",
+            "- `Recommended practices:` list of `practice — rationale — source`.",
+            "- `Common traps:` list of `trap — why it fails — source`.",
+            "- `Decision hooks:` 1–3 explicit questions the primary agent must answer before moving on.",
+            "",
+            "**Role boundary:** never prescribe a choice without citing a source. If the domain has no authoritative answer, say so.",
+        ].join("\n"),
+    },
+    {
+        name: "git-history-analyzer",
+        description: "PROACTIVE when a task touches an existing module: reads git log/blame/diff to surface prior changes, failed attempts, revert patterns, and code owners that bias the current plan.",
+        tools: ["Read", "Grep", "Glob", "Bash"],
+        model: "fast",
+        activation: "on-demand",
+        relatedStages: ["scope", "design", "plan", "review"],
+        body: [
+            "You are a **git history analyzer**.",
+            "",
+            "Read commit history, blame, and recent diffs for files the current task touches. The goal is to expose prior context (attempts, reverts, owners, flaky surfaces) the primary agent would otherwise miss.",
+            "",
+            "**Process:**",
+            "",
+            "1. For each impacted path: `git log --follow -n 20 -- <path>` and note the themes.",
+            "2. `git blame` the hot lines to surface current owners.",
+            "3. Look for `Revert ...`, `Reopen ...`, or repeated regressions in the last 90 days.",
+            "4. Check CODEOWNERS / committer frequency for ownership signal.",
+            "5. Flag any recent refactors or migrations in-flight that this task might collide with.",
+            "",
+            "**Output schema:**",
+            "",
+            "- `Impacted paths:` list.",
+            "- `Recent themes:` 3–5 bullets summarizing what changed lately in those paths.",
+            "- `Revert/regression signals:` list with commit SHAs.",
+            "- `Owners:` best-guess owners with supporting evidence.",
+            "- `Collision risks:` in-flight branches/migrations that overlap.",
+            "",
+            "**Role boundary:** read-only; never amend history, never `git push`. Use `git` commands only.",
+        ].join("\n"),
+    },
 ];
 import { enhancedAgentBody } from "./subagents.js";
 /**
@@ -213,13 +364,29 @@ ${taskDelegation}
 export function agentRoutingTable() {
     return `| Stage Entry | Primary Agent | Supporting Agents |
 |---|---|---|
-| Brainstorm (start with \`/cc <idea>\`) | planner | — |
-| Scope / Design / Spec / Plan (advance via \`/cc-next\`) | planner | security-reviewer on design, spec-reviewer on spec |
-| TDD (via \`/cc-next\`) | test-author | doc-updater |
-| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer, security-reviewer | — |
+| Brainstorm (start with \`/cc <idea>\`) | planner | repo-research-analyst, learnings-researcher, best-practices-researcher |
+| Scope / Design / Spec / Plan (advance via \`/cc-next\`) | planner | security-reviewer on design, spec-reviewer on spec, framework-docs-researcher + git-history-analyzer on design/plan |
+| TDD (via \`/cc-next\`) | test-author | doc-updater, framework-docs-researcher |
+| Review (via \`/cc-next\`) | spec-reviewer, code-reviewer, security-reviewer | best-practices-researcher, git-history-analyzer |
 | Ship (via \`/cc-next\`) | — | doc-updater |
 `;
 }
+/**
+ * Cost tier routing: keep heavy reasoning on the \`deep\` tier (planner, a
+ * single post-review reconciliation), push read-only research and narrow
+ * machine-only checks to the \`fast\` tier, and default review to \`balanced\`.
+ * This table is emitted into AGENTS.md so harness users understand why
+ * certain specialists are automatically fan-out-able without blowing the
+ * context budget.
+ */
+export function agentCostTierTable() {
+    return `| Tier | Use for | Example agents |
+|---|---|---|
+| \`deep\` | one heavy plan or one final reconciliation per stage | planner |
+| \`balanced\` | spec compliance and code/security review with enough context | spec-reviewer, code-reviewer, security-reviewer, test-author |
+| \`fast\` | read-only research / narrow machine checks / docs updates; safe to fan out 3-5× in parallel | repo-research-analyst, learnings-researcher, framework-docs-researcher, best-practices-researcher, git-history-analyzer, doc-updater |
+`;
+}
 /**
  * AGENTS.md-ready section describing Cclaw’s specialist delegation model.
  */
@@ -232,8 +399,12 @@ ${agentRoutingTable()}
 
 **Activation modes:**
 - **Mandatory:** MUST be used when the related stage runs (spec-reviewer, code-reviewer, and security-reviewer during review; planner during scope and design; test-author during tdd; doc-updater during ship). Even if a change has no trust-boundary impact, security-reviewer produces an explicit no-change attestation.
-- **Proactive:** Should be used automatically when context matches (planner for complex features, security-reviewer escalations outside review, doc-updater on behavior changes)
-- **On-demand:** Invoked only when explicitly requested
+- **Proactive:** Should be used automatically when context matches (planner for complex features, repo-research-analyst / learnings-researcher at the start of brainstorm/scope/design, security-reviewer escalations outside review, doc-updater on behavior changes).
+- **On-demand:** Invoked only when explicitly requested, but strongly suggested in the matching contexts (framework-docs-researcher when the task touches a specific library/SDK, best-practices-researcher when the task touches a well-known domain, git-history-analyzer when the task touches existing code).
+
+### Cost-aware routing
+
+${agentCostTierTable()}
 
 **Agent files:** \`.cclaw/agents/{name}.md\` — each contains YAML frontmatter with tools and model tier.
 `;

package/dist/content/contracts.js

@@ -34,7 +34,7 @@ ${schema.hardGate}
 2. Resolve active artifact root: \`.cclaw/artifacts/\`.
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
-4. Load \`.cclaw/knowledge.md\` and apply relevant entries.
+4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, created, project).
 5. Write stage output to ${writeStepPaths}.
 6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled only by \`cclaw archive\`.
 

package/dist/content/examples.d.ts

@@ -1,2 +1,3 @@
 import type { FlowStage } from "../types.js";
+export declare function stageGoodBadExamples(stage: FlowStage): string;
 export declare function stageExamples(stage: FlowStage): string;

package/dist/content/examples.js

@@ -432,6 +432,69 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Execution result: PR #42 created via \`gh pr create\`; CI passed; squash-merged to main.
 - PR URL: https://github.com/example/repo/pull/42`,
 };
+const GOOD_BAD_EXAMPLES = {
+    brainstorm: {
+        good: "Problem: release checks are fragile and inconsistent between CI and local runs; invalid metadata sometimes reaches npm publish. Success: invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows. Constraints: no new runtime dependencies.",
+        bad: "Problem: releases are broken. Success: make them better. Constraints: be careful.",
+        lesson: "\"Make it better\" is not a success criterion — an agent cannot know when it is done. State the observable condition that proves success."
+    },
+    scope: {
+        good: "In scope: in-app notification feed, SSE delivery path, read/unread state, retry on transient failures. Out of scope: email/SMS/push providers, per-user preferences. Deferred: WebSocket channel, rich media, full-text search.",
+        bad: "In scope: notifications. Out of scope: stuff we are not doing. Deferred: v2.",
+        lesson: "Vague boundaries get relitigated in every subsequent stage. Enumerate concrete capabilities on each side — \"stuff we are not doing\" is not a decision."
+    },
+    design: {
+        good: "Failure: SSE connection drop. Trigger: network interruption. Detection: client heartbeat timeout (30s). Mitigation: auto-reconnect with exponential backoff + REST snapshot fallback. User impact: ≤10s delay, no data loss.",
+        bad: "Failure: network errors. Mitigation: retry and log. User impact: users may see issues sometimes.",
+        lesson: "A failure row without a detection signal and a bounded user impact is aspirational, not a design. Name the trigger, the detector, and the recovery behavior."
+    },
+    spec: {
+        good: "AC-1: Given a signed-in user with an active session, when the server publishes a new notification event for that user, the client feed shows the new item within 5 seconds without a full page reload.",
+        bad: "AC-1: Users should see their notifications quickly and reliably, with a good user experience.",
+        lesson: "Spec criteria must be observable, measurable, and falsifiable. \"Quickly\" is a feeling; \"within 5 seconds without a full page reload\" is a test."
+    },
+    plan: {
+        good: "T-2: Implement publisher + outbox write path. Acceptance: AC-1. Verification: `pnpm vitest run tests/integration/publisher.test.ts`. Depends on: T-1. Effort: M.",
+        bad: "T-2: Build the backend. Verify: manual testing. Effort: a few days.",
+        lesson: "A task without a single acceptance criterion and a reproducible verification command is a wish. If you cannot say how you will know it is done, you cannot ship it."
+    },
+    tdd: {
+        good: "RED: `pnpm vitest run tests/unit/dedupe-feed.test.ts` → `publishToOutbox is not a function`. GREEN (after minimal impl): same command, 47/47 pass, full suite. REFACTOR: extracted `mergeLatestByDedupeKey`; suite still 47/47.",
+        bad: "Wrote the publisher code. Tests pass now. Will add unit tests later when I have time.",
+        lesson: "Code written before a failing test is guessing validated after the fact. The RED failure IS the specification — without it, the GREEN pass proves nothing about the intended behavior."
+    },
+    review: {
+        good: "R-1 Critical: snapshot endpoint returns newest N rows but does not guarantee consistency with stream cursor — users can miss items between snapshot and subscribe. Evidence: integration test `notification-consistency.test.ts:22-58`. Status: open.",
+        bad: "Looks good overall. A few small things could be polished, maybe refactor the merge logic. LGTM.",
+        lesson: "\"LGTM\" is not a review — it is a signature on whatever the author shipped. Every finding needs a severity, a falsifiable description, evidence, and a status."
+    },
+    ship: {
+        good: "Rollback trigger: error rate on `/notifications/stream` >5% for 5 minutes, or p95 publish-to-visible lag >10s. Steps: `git revert <merge-sha> && git push origin main` then redeploy; run `2026_04_12_notifications_cursor_down.sql` before traffic. Verification: error rate returns to baseline within 10 minutes.",
+        bad: "Rollback plan: revert the commit if anything goes wrong.",
+        lesson: "\"Revert if anything goes wrong\" leaves the on-call engineer to invent the plan at 2 a.m. The rollback trigger is an operational contract: state the signal, the command, and the verification."
+    }
+};
+export function stageGoodBadExamples(stage) {
+    const sample = GOOD_BAD_EXAMPLES[stage];
+    if (!sample)
+        return "";
+    return [
+        "## Good vs Bad (at-a-glance)",
+        "",
+        "Contrasting samples to calibrate the quality bar for this stage. Read before writing the artifact — mirror the **Good** shape, avoid the **Bad** shape.",
+        "",
+        "**Good**",
+        "",
+        "> " + sample.good,
+        "",
+        "**Bad**",
+        "",
+        "> " + sample.bad,
+        "",
+        "**Why it matters:** " + sample.lesson,
+        ""
+    ].join("\n");
+}
 export function stageExamples(stage) {
     const examples = STAGE_EXAMPLES[stage];
     if (!examples)

package/dist/content/hooks.js

@@ -51,7 +51,7 @@ 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"
-KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.md"
+KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.jsonl"
 META_SKILL="$ROOT/${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"
 
 # --- Read flow state ---
@@ -309,7 +309,7 @@ if [ -f "$META_SKILL" ]; then
   META_CONTENT=$(cat "$META_SKILL" 2>/dev/null || echo "")
 fi
 
-# --- Load knowledge snapshot (append-only markdown) ---
+# --- Load knowledge snapshot (canonical JSONL tail) ---
 KNOWLEDGE_SUMMARY=""
 if [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
   KNOWLEDGE_SUMMARY=$(tail -n 30 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
@@ -593,7 +593,7 @@ RUN_SYNC_NOTE="Run metadata sync removed; active artifacts stay in ${RUNTIME_ROO
 
 # --- Escape for JSON ---
 ${ESCAPE_FN}
-MSG=$(escape_json "Cclaw: session ending (stage=$STAGE, run=$ACTIVE_RUN). $CHECKPOINT_NOTE $RUN_SYNC_NOTE Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match current feature intent, (3) if you discovered a non-obvious rule/pattern, append it to ${RUNTIME_ROOT}/knowledge.md, (4) commit or revert pending changes.")
+MSG=$(escape_json "Cclaw: session ending (stage=$STAGE, run=$ACTIVE_RUN). $CHECKPOINT_NOTE $RUN_SYNC_NOTE Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match current feature intent, (3) if you discovered a non-obvious rule/pattern, append one strict-schema JSON line to ${RUNTIME_ROOT}/knowledge.jsonl, (4) commit or revert pending changes.")
 
 # --- Output harness-specific JSON ---
 case "$HARNESS" in
@@ -631,7 +631,7 @@ INPUT=$(cat 2>/dev/null || echo '{}')
 STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 STATE_FILE="$STATE_DIR/flow-state.json"
 DELEGATION_FILE="$STATE_DIR/delegation-log.json"
-KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.md"
+KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.jsonl"
 DIGEST_FILE="$STATE_DIR/session-digest.md"
 DIGEST_TMP="$STATE_DIR/session-digest.md.tmp.$$"
 
@@ -786,7 +786,7 @@ export default function cclawPlugin(ctx) {
   const contextModePath = join(stateDir, "context-mode.json");
   const contextsDir = join(runtimeDir, "contexts");
   const sessionDigestPath = join(stateDir, "session-digest.md");
-  const knowledgePath = join(runtimeDir, "knowledge.md");
+  const knowledgePath = join(runtimeDir, "knowledge.jsonl");
   const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
 
   function ensureRuntimeDirs() {
@@ -923,7 +923,7 @@ export default function cclawPlugin(ctx) {
     if (knowledge.length > 0) parts.push("Knowledge snapshot (latest entries):", ...knowledge);
 
     parts.push(
-      "If you discover a non-obvious rule or pattern, append it to .cclaw/knowledge.md using type: rule, pattern, or lesson."
+      "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."
     );
 
     const meta = readFileText(metaSkillPath).trim();

package/dist/content/learnings.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Canonical JSONL field order (matches the reference spec).
+ * Exported for tests and any programmatic writer that wants the exact shape.
+ */
+export declare const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "created", "project"];
 export declare function learnSkillMarkdown(): string;
 export declare function learnCommandContract(): string;
 export declare function selfImprovementBlock(stageName: string): string;