cclaw-cli 0.36.0 → 0.38.0

package/README.md

@@ -229,27 +229,30 @@ Each critical-path stage produces a dated artifact under
 bundle into `.cclaw/runs/<YYYY-MM-DD-slug>/` and resets the active flow
 for the next feature.
 
-### Track heuristics are configurable
+### Track heuristics are configurable (advisory)
 
 Every team has its own vocabulary. Override the built-in trigger lists in
 `.cclaw/config.yaml`:
 
 ```yaml
 trackHeuristics:
-  priority: [standard, medium, quick]
   fallback: standard
   tracks:
     quick:
       triggers: [hotfix, rollback, prod-incident]
-      veto: [schema, migration]   # never route quick even if one trigger hits
+      veto: [schema, migration]   # never route quick even if a trigger hits
     standard:
-      patterns:
-        - "^epic:"
-        - "platform-team|core-infra"
+      triggers: [epic, platform-team, core-infra]
 ```
 
-`priority` + `veto` + regex `patterns` give you deterministic routing
-without touching any code.
+Honest caveat: this config is **advisory**. cclaw surfaces these lists in
+the `/cc` skill and contract prose so the LLM applies them during
+classification — there is no Node-level router that mechanically enforces
+the outcome. That is why the knobs are deliberately minimal: per-track
+`triggers` + `veto` on top of defaults, plus `fallback`. Evaluation order is
+fixed (`standard -> medium -> quick`, narrow-to-broad); regex `patterns`
+and a `priority` override were removed in v0.38.0 because nothing in
+runtime consumed them.
 
 ### Mid-flow reclassification
 

package/dist/config.js

@@ -160,17 +160,8 @@ export async function readConfig(projectRoot) {
         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)];
+        if (Object.prototype.hasOwnProperty.call(trackHeuristicsRaw, "priority")) {
+            throw configValidationError(fullPath, `"trackHeuristics.priority" is no longer supported (removed in v0.38.0). Track evaluation order is always standard -> medium -> quick. Remove the field to upgrade.`);
         }
         const tracksRaw = trackHeuristicsRaw.tracks;
         let tracks = undefined;
@@ -186,30 +177,19 @@ export async function readConfig(projectRoot) {
                 if (!isRecord(ruleRaw)) {
                     throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}" must be an object`);
                 }
+                if (Object.prototype.hasOwnProperty.call(ruleRaw, "patterns")) {
+                    throw configValidationError(fullPath, `"trackHeuristics.tracks.${trackName}.patterns" is no longer supported (removed in v0.38.0). Regex patterns were never wired into runtime routing. Move the intent into "triggers" (substrings) or "veto".`);
+                }
                 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
         };
     }

package/dist/content/compound-command.js

@@ -35,20 +35,24 @@ the user can approve individual lifts, accept-all, or skip.
    - set \`closeout.compoundPromoted = 0\`,
    - set \`closeout.shipSubstate = "ready_to_archive"\`,
    - emit \`compound: no candidates | next: /cc-next\` and stop.
-5. Otherwise, present **one** structured ask (AskUserQuestion / AskQuestion /
+5. **Drift check** each surviving candidate before presenting it (see
+   "Drift check" section in the skill): confirm the lift target file is
+   current, spot-check the repo for contradictions, demote stale clusters
+   into a new superseding entry instead of a lift.
+6. Otherwise, present **one** structured ask (AskUserQuestion / AskQuestion /
    plain text) summarising all candidates at once:
    - \`apply-all\` (default) — apply every listed lift,
    - \`apply-selected\` — prompt per-candidate,
    - \`skip\` — record a skip reason and advance without changes.
-6. Apply approved lifts to the target file(s). Each lift also appends a
+7. Apply approved lifts to the target file(s). Each lift also appends a
    \`type: "compound"\` entry back to \`${RUNTIME_ROOT}/knowledge.jsonl\`
    summarising what was lifted.
-7. Update flow-state:
+8. Update flow-state:
    - \`closeout.compoundCompletedAt = <ISO>\`,
    - \`closeout.compoundPromoted = <count>\`,
    - \`closeout.compoundSkipped = true\` if user picked skip,
    - \`closeout.shipSubstate = "ready_to_archive"\`.
-8. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
+9. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
 
 ## Primary skill
 
@@ -83,27 +87,53 @@ empty pass is allowed and must advance \`closeout.shipSubstate\` to
    - \`closeout.compoundPromoted = 0\`,
    - \`closeout.shipSubstate = "ready_to_archive"\`,
    - announce \`compound: no candidates\` and stop.
-4. Otherwise, render each candidate as:
+4. **Drift check — run before presenting any candidate.** Knowledge lines
+   are append-only, so textual repetition alone does not prove the rule is
+   still true. For every cluster that survives the recurrence filter:
+
+   - **Read the lift target.** Open the rule/protocol/skill file you would
+     edit. If the current contents already encode a stronger version of
+     the cluster's \`action\`, drop the candidate (nothing to lift).
+   - **Grep for contradictions.** Run a quick repo search on the cluster's
+     \`trigger\` keywords. If recent code or docs contradict the cluster,
+     treat the cluster as stale.
+   - **Check age.** Inspect \`last_seen_ts\` across the cluster's lines. If
+     every contributing line is older than ~90 days with no fresh
+     observation, treat the cluster as stale.
+   - **Handle stale clusters correctly.** Do **not** silently skip them.
+     Append a new superseding \`type: "lesson"\` line to
+     \`.cclaw/knowledge.jsonl\` whose \`trigger\` explicitly references the
+     old pattern (e.g. \`"when previous rule about X no longer holds: ..."\`)
+     and whose \`action\` documents the replacement or archive reason.
+     Then drop the candidate from the lift list.
+   - **Cite line IDs.** Every surviving candidate must list the concrete
+     knowledge line indices (1-based) that back it, not just a
+     summary string. This is what makes the lift auditable.
+   - Optionally invoke the \`knowledge-curation\` utility skill's
+     stale/duplicate/supersede heuristics if you want a second pass.
+
+5. Otherwise, render each candidate as:
 
 \`\`\`
 Candidate: <short title>
-Evidence: <knowledge refs>
+Evidence: <knowledge line-ids>
+Freshness: <newest last_seen_ts among evidence lines>
 Lift target: <rule/protocol/skill file>
 Change type: <add/update/remove>
 Expected benefit: <what regressions this prevents>
 \`\`\`
 
-5. Present **one** structured question with three options:
+6. Present **one** structured question with three options:
    - \`apply-all\` (default) — apply every candidate,
    - \`apply-selected\` — prompt per-candidate approval next,
    - \`skip\` — record a skip reason and advance.
 
-6. For approved candidates:
+7. For approved candidates:
    - edit the target file(s) with the lift,
    - append a \`type: "compound"\` entry to \`.cclaw/knowledge.jsonl\`
-     describing what was promoted.
+     describing what was promoted, including the source line IDs.
 
-7. Update flow-state \`closeout\`:
+8. Update flow-state \`closeout\`:
    - \`compoundCompletedAt\`,
    - \`compoundPromoted\` (count),
    - \`compoundSkipped\` (boolean) + \`compoundSkipReason\` when applicable,
@@ -122,6 +152,9 @@ closeout chain's perspective.
 - \`closeout.compoundCompletedAt\` is set.
 - \`closeout.shipSubstate === "ready_to_archive"\`.
 - If lifts were applied, the target files show the edit and at least one
-  new \`compound\` line exists in \`.cclaw/knowledge.jsonl\`.
+  new \`compound\` line exists in \`.cclaw/knowledge.jsonl\`, and the new
+  line references the source knowledge line IDs.
+- If drift check demoted any cluster, a new superseding \`lesson\` line
+  exists on the same run documenting the replacement.
 `;
 }

package/dist/content/start-command.js

@@ -65,7 +65,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 4. Read \`${flowPath}\`.
 5. If flow already has completed stages beyond brainstorm, warn the user that starting a new brainstorm will reset progress. Ask for confirmation before proceeding.
 6. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
-   - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track rules (\`priority\`, \`fallback\`, \`tracks.<id>.{triggers,patterns,veto}\`) before built-in defaults.
+   - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
      Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
    - **medium** (\`brainstorm → spec → plan → tdd → review → ship\`) — additive work that fits existing architecture and still needs product framing.
@@ -141,7 +141,7 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
 6. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
-   - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply that override first (priority/fallback/rules), then use built-in defaults only as fallback.
+   - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply those vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of built-in defaults. Evaluation order is fixed: \`standard -> medium -> quick\`. (Honest note: this is advisory prose; the LLM applies it, not a Node-level router.)
 
    **Track heuristic** (lowercase substring match against the user prompt):
 

package/dist/doctor.js

@@ -873,7 +873,13 @@ export async function doctorChecks(projectRoot, options = {}) {
         let missingSchemaV2Fields = 0;
         let parsedKnowledgeLines = 0;
         let lowConfidenceLines = 0;
+        let staleRawEntries = 0;
         const triggerActionCounts = new Map();
+        // Stale threshold for raw entries: ~90 days with no re-observation.
+        // Chosen to match the compound drift checklist language; anything newer is
+        // recent enough to trust, anything older deserves a curate/supersede pass.
+        const STALE_RAW_THRESHOLD_MS = 90 * 24 * 60 * 60 * 1000;
+        const now = Date.now();
         const requiredV2Fields = [
             "type",
             "trigger",
@@ -919,6 +925,14 @@ export async function doctorChecks(projectRoot, options = {}) {
                     if (missing) {
                         missingSchemaV2Fields += 1;
                     }
+                    const maturity = typeof parsed.maturity === "string" ? parsed.maturity.toLowerCase() : "";
+                    const lastSeenRaw = typeof parsed.last_seen_ts === "string" ? parsed.last_seen_ts : "";
+                    if (maturity === "raw" && lastSeenRaw.length > 0) {
+                        const lastSeenMs = Date.parse(lastSeenRaw);
+                        if (Number.isFinite(lastSeenMs) && now - lastSeenMs > STALE_RAW_THRESHOLD_MS) {
+                            staleRawEntries += 1;
+                        }
+                    }
                 }
                 catch {
                     malformedKnowledgeLines += 1;
@@ -962,6 +976,15 @@ export async function doctorChecks(projectRoot, options = {}) {
                 ? "no high-frequency repeated trigger/action clusters detected"
                 : `warning: ${repeatedClusters.length} repeated learning cluster(s) detected (>=3 repeats). Consider /cc-ops compound to lift them into rules/skills.`
         });
+        checks.push({
+            name: "warning:knowledge:stale_raw_entries",
+            ok: true,
+            details: parsedKnowledgeLines === 0
+                ? "knowledge.jsonl is empty"
+                : staleRawEntries === 0
+                    ? `no raw knowledge entries older than 90 days`
+                    : `warning: ${staleRawEntries} raw knowledge entry(ies) have last_seen_ts older than 90 days. Run /cc-learn curate or append a superseding entry before the next /cc-ops compound pass.`
+        });
     }
     checks.push({
         name: "state:checkpoint_exists",

package/dist/track-heuristics.d.ts

@@ -4,9 +4,16 @@ export interface TrackResolution {
     reason: string;
     matchedTokens: string[];
 }
+/**
+ * Reference implementation of the track classifier the /cc skill prose
+ * describes. Tests pin its behavior so the built-in defaults stay honest.
+ * This function is not called from cclaw runtime — `/cc` routing happens in
+ * the LLM. If you wire this in later, update README to drop the
+ * "advisory" language.
+ */
 export declare function resolveTrackFromPrompt(prompt: string, config: TrackHeuristicsConfig | undefined): TrackResolution;
 export declare const TRACK_HEURISTICS_DEFAULTS: {
     readonly fallback: "standard";
-    readonly priority: ("quick" | "medium" | "standard")[];
+    readonly evaluationOrder: readonly ("quick" | "medium" | "standard")[];
     readonly tracks: Record<"quick" | "medium" | "standard", TrackHeuristicRule>;
 };

package/dist/track-heuristics.js

@@ -1,4 +1,6 @@
 import { FLOW_TRACKS } from "./types.js";
+// Built-in vocabulary per track. Kept in one place so tests, docs, and the
+// /cc skill prose can snapshot the exact same strings.
 const DEFAULT_RULES = {
     quick: {
         triggers: [
@@ -48,7 +50,9 @@ const DEFAULT_RULES = {
         ]
     }
 };
-const DEFAULT_PRIORITY = ["standard", "medium", "quick"];
+// Fixed evaluation order: narrow-to-broad. Overriding this was never wired
+// into runtime, so cclaw stopped offering the knob in v0.38.0.
+const EVALUATION_ORDER = ["standard", "medium", "quick"];
 const DEFAULT_FALLBACK = "standard";
 function hasToken(promptLower, token) {
     return promptLower.includes(token.toLowerCase());
@@ -62,17 +66,6 @@ function matchRule(promptLower, rule) {
             matches.push(trigger);
         }
     }
-    for (const pattern of rule.patterns ?? []) {
-        try {
-            const regex = new RegExp(pattern, "iu");
-            if (regex.test(promptLower)) {
-                matches.push(`/${pattern}/`);
-            }
-        }
-        catch {
-            // Ignore invalid custom regex entries; config validation should catch these.
-        }
-    }
     return [...new Set(matches)];
 }
 function isValidTrack(value) {
@@ -89,34 +82,26 @@ function mergeRules(base, overrides) {
             continue;
         merged[track] = {
             triggers: rule.triggers ?? merged[track].triggers,
-            patterns: rule.patterns ?? merged[track].patterns,
             veto: rule.veto ?? merged[track].veto
         };
     }
     return merged;
 }
-function resolvePriority(config) {
-    const configured = config?.priority ?? [];
-    const filtered = configured.filter((track) => isValidTrack(track));
-    const unique = [...new Set(filtered)];
-    if (unique.length === 0)
-        return [...DEFAULT_PRIORITY];
-    // Ensure all tracks are still represented in deterministic order.
-    for (const track of FLOW_TRACKS) {
-        if (!unique.includes(track))
-            unique.push(track);
-    }
-    return unique;
-}
 function resolveFallback(config) {
     return config?.fallback && isValidTrack(config.fallback) ? config.fallback : DEFAULT_FALLBACK;
 }
+/**
+ * Reference implementation of the track classifier the /cc skill prose
+ * describes. Tests pin its behavior so the built-in defaults stay honest.
+ * This function is not called from cclaw runtime — `/cc` routing happens in
+ * the LLM. If you wire this in later, update README to drop the
+ * "advisory" language.
+ */
 export function resolveTrackFromPrompt(prompt, config) {
     const promptLower = prompt.toLowerCase();
     const rules = mergeRules(DEFAULT_RULES, config);
-    const priority = resolvePriority(config);
     const fallback = resolveFallback(config);
-    for (const track of priority) {
+    for (const track of EVALUATION_ORDER) {
         const rule = rules[track];
         const vetoes = rule.veto ?? [];
         if (vetoes.some((token) => hasToken(promptLower, token))) {
@@ -139,6 +124,6 @@ export function resolveTrackFromPrompt(prompt, config) {
 }
 export const TRACK_HEURISTICS_DEFAULTS = {
     fallback: DEFAULT_FALLBACK,
-    priority: DEFAULT_PRIORITY,
+    evaluationOrder: EVALUATION_ORDER,
     tracks: DEFAULT_RULES
 };

package/dist/types.d.ts

@@ -25,20 +25,38 @@ export type HarnessId = (typeof HARNESS_IDS)[number];
  */
 export declare const LANGUAGE_RULE_PACKS: readonly ["typescript", "python", "go"];
 export type LanguageRulePack = (typeof LANGUAGE_RULE_PACKS)[number];
+/**
+ * Per-track vocabulary hints the LLM applies when classifying a /cc prompt.
+ *
+ * Intentionally minimal:
+ * - `triggers`: additional substrings that push a prompt toward this track.
+ * - `veto`:     substrings that forbid this track even if a trigger matches.
+ *
+ * Removed in v0.38.0:
+ * - `patterns` (regex): no runtime ever consumed them; kept authors honest
+ *   about what cclaw actually enforces.
+ */
 export interface TrackHeuristicRule {
     triggers?: string[];
-    patterns?: string[];
     veto?: string[];
 }
+/**
+ * Optional prompt-to-track overrides for /cc classification.
+ *
+ * Honesty note: this config is **advisory**. cclaw surfaces these lists in
+ * the /cc skill and contract prose so the LLM can apply them when picking a
+ * track. There is no Node-level routing layer that mechanically enforces the
+ * result — which is why we only ship `triggers`, `veto`, and `fallback`, not
+ * regex patterns or priority overrides.
+ *
+ * Removed in v0.38.0:
+ * - `priority`: track evaluation order is always `standard -> medium -> quick`
+ *   (narrow-to-broad matching). Overriding it was never wired.
+ */
 export interface TrackHeuristicsConfig {
-    /** Track used when no trigger/pattern matches. */
+    /** Track used when no trigger matches. Defaults to `standard`. */
     fallback?: FlowTrack;
-    /**
-     * Track evaluation order. First matching track wins.
-     * Example: ["standard", "medium", "quick"].
-     */
-    priority?: FlowTrack[];
-    /** Per-track matching rules. */
+    /** Per-track vocabulary hints. */
     tracks?: Partial<Record<FlowTrack, TrackHeuristicRule>>;
 }
 /**
@@ -92,7 +110,8 @@ export interface VibyConfig {
      */
     languageRulePacks?: LanguageRulePack[];
     /**
-     * Optional prompt-to-track mapping overrides for /cc classification.
+     * Optional prompt-to-track vocabulary overrides for /cc classification.
+     * Advisory (surfaced in the /cc skill prose), not machine-enforced.
      * If omitted, cclaw uses built-in defaults.
      */
     trackHeuristics?: TrackHeuristicsConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {