cclaw-cli 0.10.0 → 0.11.0

package/dist/config.js

@@ -19,7 +19,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "promptGuardMode",
     "gitHookGuards",
     "defaultTrack",
-    "languageRulePacks"
+    "languageRulePacks",
+    "trackHeuristics"
 ]);
 function configFixExample() {
     return `harnesses:
@@ -34,6 +35,21 @@ function configValidationError(configFilePath, reason) {
         `Example config:\n${configFixExample()}\n` +
         `After fixing, run: cclaw sync`);
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateStringArray(value, fieldName, configFilePath) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw configValidationError(configFilePath, `"${fieldName}" must be an array of strings`);
+    }
+    const invalid = value.filter((item) => typeof item !== "string");
+    if (invalid.length > 0) {
+        throw configValidationError(configFilePath, `"${fieldName}" must contain only strings`);
+    }
+    return value;
+}
 export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
@@ -64,7 +80,7 @@ export function createProfileConfig(profile, overrides = {}) {
                 autoAdvance: false,
                 promptGuardMode: "advisory",
                 gitHookGuards: false,
-                defaultTrack: overrides.defaultTrack ?? "quick",
+                defaultTrack: overrides.defaultTrack ?? "medium",
                 languageRulePacks: overrides.languageRulePacks ?? []
             };
         case "standard":
@@ -161,6 +177,69 @@ export async function readConfig(projectRoot) {
         throw configValidationError(fullPath, `unknown languageRulePacks id(s): ${formatted}`);
     }
     const languageRulePacks = [...new Set(rawPacks)];
+    const trackHeuristicsRaw = parsed.trackHeuristics;
+    let trackHeuristics = undefined;
+    if (Object.prototype.hasOwnProperty.call(parsed, "trackHeuristics")) {
+        if (!isRecord(trackHeuristicsRaw)) {
+            throw configValidationError(fullPath, `"trackHeuristics" must be an object`);
+        }
+        const fallbackRaw = trackHeuristicsRaw.fallback;
+        if (fallbackRaw !== undefined && (typeof fallbackRaw !== "string" || !FLOW_TRACK_SET.has(fallbackRaw))) {
+            throw configValidationError(fullPath, `"trackHeuristics.fallback" must be one of: ${SUPPORTED_TRACKS_TEXT}`);
+        }
+        const priorityRaw = trackHeuristicsRaw.priority;
+        let priority;
+        if (priorityRaw !== undefined) {
+            if (!Array.isArray(priorityRaw)) {
+                throw configValidationError(fullPath, `"trackHeuristics.priority" must be an array`);
+            }
+            const invalidPriority = priorityRaw.filter((value) => typeof value !== "string" || !FLOW_TRACK_SET.has(value));
+            if (invalidPriority.length > 0) {
+                throw configValidationError(fullPath, `"trackHeuristics.priority" must contain only: ${SUPPORTED_TRACKS_TEXT}`);
+            }
+            priority = [...new Set(priorityRaw)];
+        }
+        const tracksRaw = trackHeuristicsRaw.tracks;
+        let tracks = undefined;
+        if (tracksRaw !== undefined) {
+            if (!isRecord(tracksRaw)) {
+                throw configValidationError(fullPath, `"trackHeuristics.tracks" must be an object`);
+            }
+            tracks = {};
+            for (const [trackName, ruleRaw] of Object.entries(tracksRaw)) {
+                if (!FLOW_TRACK_SET.has(trackName)) {
+                    throw configValidationError(fullPath, `"trackHeuristics.tracks" contains unknown track "${trackName}". Supported: ${SUPPORTED_TRACKS_TEXT}`);
+                }
+                if (!isRecord(ruleRaw)) {
+                    throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}" must be an object`);
+                }
+                const triggers = validateStringArray(ruleRaw.triggers, `trackHeuristics.tracks.${trackName}.triggers`, fullPath);
+                const patterns = validateStringArray(ruleRaw.patterns, `trackHeuristics.tracks.${trackName}.patterns`, fullPath);
+                const veto = validateStringArray(ruleRaw.veto, `trackHeuristics.tracks.${trackName}.veto`, fullPath);
+                if (patterns) {
+                    for (const pattern of patterns) {
+                        try {
+                            // eslint-disable-next-line no-new
+                            new RegExp(pattern, "iu");
+                        }
+                        catch {
+                            throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}.patterns" contains invalid regex "${pattern}"`);
+                        }
+                    }
+                }
+                tracks[trackName] = {
+                    triggers,
+                    patterns,
+                    veto
+                };
+            }
+        }
+        trackHeuristics = {
+            fallback: fallbackRaw,
+            priority,
+            tracks
+        };
+    }
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -169,7 +248,8 @@ export async function readConfig(projectRoot) {
         promptGuardMode,
         gitHookGuards,
         defaultTrack,
-        languageRulePacks
+        languageRulePacks,
+        trackHeuristics
     };
 }
 export async function writeConfig(projectRoot, config) {

package/dist/content/examples.js

@@ -714,6 +714,72 @@ const DOMAIN_LABELS = {
     "data-pipeline": "Data pipeline / ETL"
 };
 const STAGE_DOMAIN_SAMPLES = {
+    brainstorm: [
+        {
+            domain: "web",
+            label: "Direction",
+            body: "Problem: admin dashboard orders table requires manual refresh to see new orders. Success: admins see new rows within 2s of server-side status change, no full navigation. Anti-success: WebSocket rewrite of the whole table stack when only one view needs live updates."
+        },
+        {
+            domain: "cli",
+            label: "Direction",
+            body: "Problem: `cclaw archive` silently deletes 30+ day runs with no preview. Success: a `--dry-run` flag prints would-be-archived run IDs to stdout and exits 0; current behavior is unchanged without the flag. Anti-success: adding an interactive confirmation prompt that breaks CI scripts."
+        },
+        {
+            domain: "library",
+            label: "Direction",
+            body: "Problem: consumers cannot validate hook JSON without importing internal modules. Success: `validateHookDocument(obj)` exported from the package root with typed result `{ ok, errors? }`. Anti-success: exposing the full Zod schema and forcing consumers to depend on Zod."
+        },
+        {
+            domain: "data-pipeline",
+            label: "Direction",
+            body: "Problem: reruns of the orders job create duplicate `fact_orders` rows. Success: running the job twice on the same input leaves row count unchanged and `dbt test --select fact_orders` green. Anti-success: introducing a nightly dedup job that hides the underlying non-idempotency."
+        }
+    ],
+    scope: [
+        {
+            domain: "web",
+            label: "Scope line",
+            body: "In: live-update `/dashboard/orders` table via SSE; out: notification drawer, mobile PWA, dashboards other than `orders`. Discretion: choice of SSE vs long-polling for legacy Safari. NOT in scope: rewriting the auth layer or the existing REST endpoints."
+        },
+        {
+            domain: "cli",
+            label: "Scope line",
+            body: "In: add `--dry-run` to `cclaw archive`; out: redesigning archive formats, adding retention flags, or changing the default. Discretion: exact wording of stdout lines. NOT in scope: touching `init` / `sync` / `doctor` subcommands."
+        },
+        {
+            domain: "library",
+            label: "Scope line",
+            body: "In: expose `validateHookDocument` + types from package root; out: rewriting hook schema, adding new hook kinds, dropping old ones. Discretion: whether to re-export `HookDocument` as type-only. NOT in scope: migrating consumers."
+        },
+        {
+            domain: "data-pipeline",
+            label: "Scope line",
+            body: "In: dedup step between `raw.orders` and `fact_orders` keyed on `(order_id, event_ts)`; out: redesigning ingestion, adding new partitions, or touching downstream marts. Discretion: `row_number()` vs `qualify`-style dedup. NOT in scope: backfilling historical partitions."
+        }
+    ],
+    design: [
+        {
+            domain: "web",
+            label: "Architecture note",
+            body: "Data flow: server-side order update → publish to `orders-updates` channel → SSE endpoint `/api/orders/stream` → `useOrderFeed` hook merges into React state → row rerenders. Failure mode: SSE connection drop → exponential-backoff reconnect + on-reconnect REST snapshot fallback. Trade-off accepted: no client→server channel (SSE one-way); existing REST mutations cover it."
+        },
+        {
+            domain: "cli",
+            label: "Architecture note",
+            body: "Flag is parsed by the existing Zod CLI parser; `--dry-run` short-circuits before any filesystem mutation, shares formatter `src/cli/format.ts` with `status`. Failure mode: formatter output differs between `status` and `archive --dry-run` → centralize format. Trade-off: we print run IDs unsorted to keep the code path identical to the real archive path."
+        },
+        {
+            domain: "library",
+            label: "Architecture note",
+            body: "Re-export `validateHookDocument` from package root; rename internal `__validate` to match the exported name so callsites and the export converge. Failure mode: consumers importing from `/dist/internal` break on the rename → add a deprecation re-export shim for one minor. Trade-off: slightly wider public surface today buys us a smaller public surface tomorrow."
+        },
+        {
+            domain: "data-pipeline",
+            label: "Architecture note",
+            body: "Insert `int_orders_deduped` CTE between staging and fact, keyed on `(order_id, event_ts)` with `row_number() = 1` per key; `fact_orders` reads from the deduped model only. Failure mode: late-arriving events with an earlier `event_ts` would flap the chosen row → tiebreak on `ingest_ts DESC`. Trade-off: the job now does one extra pass; measured +8% runtime, within budget."
+        }
+    ],
     spec: [
         {
             domain: "web",
@@ -780,6 +846,28 @@ const STAGE_DOMAIN_SAMPLES = {
             body: "RED: `dbt test --select fact_orders` → `unique test on (order_id, event_ts)` fails on re-run. GREEN: added `row_number()` dedup in the staging model. REFACTOR: extracted the dedup CTE into `int_orders_deduped` for reuse by `fact_returns`."
         }
     ],
+    review: [
+        {
+            domain: "web",
+            label: "Finding",
+            body: "R-W-1 (Critical, correctness): `useOrderFeed` does not unsubscribe from the SSE channel on unmount — two mounts on the same page double-count rows. Evidence: `tests/unit/order-feed-hook.test.ts > unmount` fails. Fix owner: frontend; blocks ship."
+        },
+        {
+            domain: "cli",
+            label: "Finding",
+            body: "R-C-2 (Suggestion, UX): `cclaw archive --dry-run` prints run IDs without a trailing newline, breaking downstream `xargs` pipelines. Evidence: `echo '' | xargs -I{} printf '%s\\n' {}` contrast. Fix owner: CLI; non-blocking."
+        },
+        {
+            domain: "library",
+            label: "Finding",
+            body: "R-L-1 (Important, surface-area): the new `validateHookDocument` export is documented in README but missing from `src/index.ts` — `import { validateHookDocument } from 'cclaw'` fails despite the docs. Evidence: `pnpm build && node -e \"require('./dist').validateHookDocument\"` prints `undefined`. Fix owner: library; blocks ship."
+        },
+        {
+            domain: "data-pipeline",
+            label: "Finding",
+            body: "R-D-1 (Critical, correctness): dedup CTE orders by `event_ts ASC` instead of `event_ts DESC` — on duplicate events we keep the older row. Evidence: `dbt test --select fact_orders` green but fixture `tests/fixtures/orders-dupes.csv` shows wrong survivor. Fix owner: analytics-eng; blocks ship."
+        }
+    ],
     ship: [
         {
             domain: "web",

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."

package/dist/content/meta-skill.d.ts

@@ -1,10 +1,2 @@
-/**
- * using-cclaw meta-skill — injected at SessionStart via hooks.
- *
- * Like agent-skills' using-agent-skills, this teaches the agent HOW to use
- * cclaw: skill discovery flowchart, activation rules, skill behaviors.
- * The full text is injected by session-start.sh so the agent always has
- * routing context without needing to read files first.
- */
 export declare const META_SKILL_NAME = "using-cclaw";
 export declare function usingCclawSkillMarkdown(): string;