cclaw-cli 0.6.0 → 0.7.1

package/dist/cli.d.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import type { FlowTrack, HarnessId } from "./types.js";
+import type { FlowTrack, HarnessId, InitProfile } from "./types.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
     track?: FlowTrack;
+    profile?: InitProfile;
     reconcileGates?: boolean;
     archiveName?: string;
     showHelp?: boolean;
@@ -13,5 +14,6 @@ interface ParsedArgs {
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseTrack(raw: string): FlowTrack;
+declare function parseProfile(raw: string): InitProfile;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseHarnesses, parseTrack, parseProfile };

package/dist/cli.js

@@ -3,11 +3,12 @@ import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS, INIT_PROFILES } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
+import { RUNTIME_ROOT } from "./constants.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
 export function usage() {
     return `cclaw - installer-first flow toolkit
@@ -19,8 +20,9 @@ Usage:
 
 Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
-             Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
-                    --track=<id>        Flow track for new runs (standard | quick). Default: standard.
+             Flags: --profile=<id>      Pre-fill defaults. One of: minimal | standard | full. Default: standard.
+                    --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex). Overrides the profile default.
+                    --track=<id>        Flow track for new runs (standard | quick). Overrides the profile default.
   sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
   doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
              Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
@@ -85,6 +87,13 @@ function parseTrack(raw) {
     }
     return trimmed;
 }
+function parseProfile(raw) {
+    const trimmed = raw.trim();
+    if (!INIT_PROFILES.includes(trimmed)) {
+        throw new Error(`Unknown profile: ${trimmed}. Supported: ${INIT_PROFILES.join(", ")}`);
+    }
+    return trimmed;
+}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -108,6 +117,10 @@ function parseArgs(argv) {
             parsed.track = parseTrack(flag.replace("--track=", ""));
             continue;
         }
+        if (flag.startsWith("--profile=")) {
+            parsed.profile = parseProfile(flag.replace("--profile=", ""));
+            continue;
+        }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
             continue;
@@ -136,10 +149,13 @@ async function runCommand(parsed, ctx) {
         await initCclaw({
             projectRoot: ctx.cwd,
             harnesses: parsed.harnesses,
-            track: parsed.track
+            track: parsed.track,
+            profile: parsed.profile
         });
-        const trackNote = parsed.track ? ` (track: ${parsed.track})` : "";
-        info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
+        const profileNote = parsed.profile ? ` profile=${parsed.profile}` : "";
+        const trackNote = parsed.track ? ` track=${parsed.track}` : "";
+        const suffix = profileNote || trackNote ? ` (${(profileNote + trackNote).trim()})` : "";
+        info(ctx, `Initialized .cclaw runtime and generated harness shims${suffix}`);
         return 0;
     }
     if (command === "sync") {
@@ -167,6 +183,16 @@ async function runCommand(parsed, ctx) {
             ? ` Snapshotted ${archived.snapshottedStateFiles.length} state file(s) under ${archived.archivePath}/state and wrote archive-manifest.json.`
             : "";
         info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
+        const k = archived.knowledge;
+        if (k.overThreshold) {
+            info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Run \`/cc-learn curate\` to plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.md.`);
+        }
+        else if (k.activeEntryCount > 0) {
+            info(ctx, `Knowledge: ${k.activeEntryCount}/${k.softThreshold} active entries. Run \`/cc-learn curate\` if you want a sweep before the next run.`);
+        }
+        else {
+            info(ctx, `Knowledge: 0 active entries in ${k.knowledgePath}. Capture lessons from this run with \`/cc-learn add\` before they fade.`);
+        }
         return 0;
     }
     await uninstallCclaw(ctx.cwd);
@@ -204,4 +230,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseHarnesses, parseTrack, parseProfile };

package/dist/config.d.ts

@@ -1,5 +1,15 @@
-import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, InitProfile, LanguageRulePack, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
 export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
+/**
+ * Build a VibyConfig for a named init profile. Profile defaults are applied
+ * first, then any explicit overrides (CLI flags) win. This keeps the profile
+ * contract deterministic and testable.
+ */
+export declare function createProfileConfig(profile: InitProfile, overrides?: {
+    harnesses?: HarnessId[];
+    defaultTrack?: FlowTrack;
+    languageRulePacks?: LanguageRulePack[];
+}): VibyConfig;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
 export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;

package/dist/config.js

@@ -3,12 +3,14 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { CCLAW_VERSION, DEFAULT_HARNESSES, FLOW_VERSION, RUNTIME_ROOT } from "./constants.js";
 import { exists, writeFileSafe } from "./fs-utils.js";
-import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS, LANGUAGE_RULE_PACKS } from "./types.js";
 const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
 const HARNESS_ID_SET = new Set(HARNESS_IDS);
 const FLOW_TRACK_SET = new Set(FLOW_TRACKS);
+const LANGUAGE_RULE_PACK_SET = new Set(LANGUAGE_RULE_PACKS);
 const SUPPORTED_HARNESSES_TEXT = HARNESS_IDS.join(", ");
 const SUPPORTED_TRACKS_TEXT = FLOW_TRACKS.join(", ");
+const SUPPORTED_LANGUAGE_RULE_PACKS_TEXT = LANGUAGE_RULE_PACKS.join(", ");
 const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
@@ -16,7 +18,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "autoAdvance",
     "promptGuardMode",
     "gitHookGuards",
-    "defaultTrack"
+    "defaultTrack",
+    "languageRulePacks"
 ]);
 function configFixExample() {
     return `harnesses:
@@ -27,6 +30,7 @@ function configValidationError(configFilePath, reason) {
     return new Error(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
         `Supported harnesses: ${SUPPORTED_HARNESSES_TEXT}\n` +
         `Supported tracks: ${SUPPORTED_TRACKS_TEXT}\n` +
+        `Supported languageRulePacks: ${SUPPORTED_LANGUAGE_RULE_PACKS_TEXT}\n` +
         `Example config:\n${configFixExample()}\n` +
         `After fixing, run: cclaw sync`);
 }
@@ -41,9 +45,50 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         autoAdvance: false,
         promptGuardMode: "advisory",
         gitHookGuards: false,
-        defaultTrack
+        defaultTrack,
+        languageRulePacks: []
     };
 }
+/**
+ * Build a VibyConfig for a named init profile. Profile defaults are applied
+ * first, then any explicit overrides (CLI flags) win. This keeps the profile
+ * contract deterministic and testable.
+ */
+export function createProfileConfig(profile, overrides = {}) {
+    const base = createDefaultConfig();
+    switch (profile) {
+        case "minimal":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? ["claude"],
+                autoAdvance: false,
+                promptGuardMode: "advisory",
+                gitHookGuards: false,
+                defaultTrack: overrides.defaultTrack ?? "quick",
+                languageRulePacks: overrides.languageRulePacks ?? []
+            };
+        case "standard":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
+                autoAdvance: false,
+                promptGuardMode: "advisory",
+                gitHookGuards: false,
+                defaultTrack: overrides.defaultTrack ?? "standard",
+                languageRulePacks: overrides.languageRulePacks ?? []
+            };
+        case "full":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
+                autoAdvance: false,
+                promptGuardMode: "strict",
+                gitHookGuards: true,
+                defaultTrack: overrides.defaultTrack ?? "standard",
+                languageRulePacks: overrides.languageRulePacks ?? [...LANGUAGE_RULE_PACKS]
+            };
+    }
+}
 export async function readConfig(projectRoot) {
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {
@@ -102,6 +147,20 @@ export async function readConfig(projectRoot) {
     const defaultTrack = typeof defaultTrackRaw === "string" && FLOW_TRACK_SET.has(defaultTrackRaw)
         ? defaultTrackRaw
         : "standard";
+    const languageRulePacksRaw = parsed.languageRulePacks;
+    const hasLanguageRulePacksField = Object.prototype.hasOwnProperty.call(parsed, "languageRulePacks");
+    if (hasLanguageRulePacksField && !Array.isArray(languageRulePacksRaw)) {
+        throw configValidationError(fullPath, `"languageRulePacks" must be an array`);
+    }
+    const rawPacks = (languageRulePacksRaw ?? []);
+    const invalidPacks = rawPacks.filter((pack) => typeof pack !== "string" || !LANGUAGE_RULE_PACK_SET.has(pack));
+    if (invalidPacks.length > 0) {
+        const formatted = invalidPacks
+            .map((item) => (typeof item === "string" ? item : JSON.stringify(item)))
+            .join(", ");
+        throw configValidationError(fullPath, `unknown languageRulePacks id(s): ${formatted}`);
+    }
+    const languageRulePacks = [...new Set(rawPacks)];
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -109,7 +168,8 @@ export async function readConfig(projectRoot) {
         autoAdvance,
         promptGuardMode,
         gitHookGuards,
-        defaultTrack
+        defaultTrack,
+        languageRulePacks
     };
 }
 export async function writeConfig(projectRoot, config) {

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/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;

package/dist/content/learnings.js

@@ -1,9 +1,28 @@
 // ---------------------------------------------------------------------------
 // Knowledge store content for /cc-learn and stage self-improvement prompts.
+//
+// The knowledge store is a single canonical JSONL file. Each line is one
+// self-contained JSON object matching the strict schema in this module.
+// There is no markdown mirror — cclaw is JSONL-native.
 // ---------------------------------------------------------------------------
-const KNOWLEDGE_PATH = ".cclaw/knowledge.md";
+const KNOWLEDGE_PATH = ".cclaw/knowledge.jsonl";
+const KNOWLEDGE_ARCHIVE_PATH = ".cclaw/knowledge.archive.jsonl";
 const LEARN_SKILL_NAME = "learnings";
-const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: review and append rule/pattern/lesson entries in .cclaw/knowledge.md.";
+const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: append and query rule/pattern/lesson/compound entries in the canonical JSONL file at .cclaw/knowledge.jsonl. Strict schema, append-only, machine-queryable.";
+/**
+ * Canonical JSONL field order (matches the reference spec).
+ * Exported for tests and any programmatic writer that wants the exact shape.
+ */
+export const KNOWLEDGE_JSONL_FIELDS = [
+    "type",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "stage",
+    "created",
+    "project"
+];
 export function learnSkillMarkdown() {
     return `---
 name: ${LEARN_SKILL_NAME}
@@ -14,65 +33,81 @@ description: "${LEARN_SKILL_DESCRIPTION}"
 
 ## Overview
 
-This skill manages the append-only project knowledge file at \`${KNOWLEDGE_PATH}\`.
+The project knowledge store is **one canonical JSONL file**: \`${KNOWLEDGE_PATH}\`.
+Each line is one self-contained JSON object. Append-only. Machine-queryable.
 
-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
-- **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule)
+Use the store 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.
+- **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule).
 
 ## HARD-GATE
 
-Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or an explicitly user-approved summary file. Do not modify application code here.
+Under \`/cc-learn\`, only modify \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_ARCHIVE_PATH}\`,
+or an explicitly user-approved summary file. Do not modify application code here.
+Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage files).
 
-## Entry format (append-only)
+## Entry format — strict JSONL schema
 
-\`\`\`markdown
-### 2026-04-14T12:00:00Z [pattern] short-title
-- Stage: design
-- Context: one short line
-- Insight: one short line
-- Reuse: one short line
-- Confidence: high | medium | low      (optional)
-- Domain: api | infra | ui | testing | …  (optional)
-- Project: <repo or scope name>        (optional)
+Exactly one JSON object per line. Fields must appear in the order:
+\`type, trigger, action, confidence, domain, stage, created, project\`.
+
+\`\`\`json
+{"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","created":"2026-04-14T12:00:00Z","project":"cclaw"}
 \`\`\`
 
+| field | type | required | notes |
+|---|---|---|---|
+| \`type\` | \`"rule" \\| "pattern" \\| "lesson" \\| "compound"\` | yes | Lowercase. |
+| \`trigger\` | string | yes | The concrete situation that must be recognized. Start with a verb or \`when …\`. |
+| \`action\` | string | yes | The concrete move to take when the trigger fires. One sentence. |
+| \`confidence\` | \`"high" \\| "medium" \\| "low"\` | yes | Write \`medium\` when unsure; do not omit. |
+| \`domain\` | string \\| null | yes | Free-form taxonomy (\`api\`, \`infra\`, \`ui\`, \`security\`, \`testing\`, …). Use \`null\` when cross-cutting. |
+| \`stage\` | \`FlowStage\` \\| null | yes | One of brainstorm / scope / design / spec / plan / tdd / review / ship, or \`null\` when cross-stage. |
+| \`created\` | ISO 8601 UTC string | yes | \`date -u +%Y-%m-%dT%H:%M:%SZ\`. |
+| \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
+
 Rules:
-- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\`, \`compound\` (lowercase).
-- Never rewrite history silently; append a newer correction entry instead. To replace, prefix the new entry with \`Supersedes: <old-title>\`.
-- Keep entries concise and actionable.
-- Optional fields (\`Confidence\`, \`Domain\`, \`Project\`) are forward-compatible and used by the **knowledge-curation** skill — fill them when known.
+- No other fields. Extra keys are forbidden and MUST be rejected by any writer.
+- Every required-null field must be emitted explicitly as \`null\` (not omitted). This keeps the file grep-friendly.
+- Append-only: never rewrite or delete a historical line. Corrections are new
+  entries whose \`trigger\` clearly supersedes the earlier one.
+- Keep each entry one line. No pretty-printing. No trailing commas.
 
 ## Curation policy (target: ≤ 50 active entries)
 
-The knowledge file is append-only, but entries can be **superseded** rather than deleted:
-
-- When you discover a more correct rule, append a new entry with \`Supersedes: <old-title>\`.
-- During \`/cc-learn curate\`, the assistant surfaces candidates for soft-archive (move to \`.cclaw/knowledge.archive.md\`) when the active file exceeds 50 entries or contains stale/duplicate entries.
-
-See the **knowledge-curation** utility skill for the full curation protocol.
+- The file is append-only — entries are never physically deleted.
+- When the canonical file exceeds 50 lines, \`/cc-learn curate\` proposes
+  soft-archiving: the approved lines are **moved** to \`${KNOWLEDGE_ARCHIVE_PATH}\`
+  verbatim (same JSONL shape). The working file stays lean.
+- See the **knowledge-curation** utility skill for the full curation protocol.
 
 ## Subcommands
 
 ### \`/cc-learn\` (default)
-- Show the last 30 lines from \`${KNOWLEDGE_PATH}\`.
-- If file is missing or empty, report that clearly.
+- Read \`${KNOWLEDGE_PATH}\`. Stream the last 30 lines; pretty-print each
+  line's \`type\` / \`trigger\` / \`action\` for human review.
+- If file is missing or empty, report that clearly and suggest \`/cc-learn add\`.
 
 ### \`/cc-learn search <query>\`
-- Perform case-insensitive text search in \`${KNOWLEDGE_PATH}\`.
-- Return matched headings and nearby lines.
+- Stream \`${KNOWLEDGE_PATH}\`, JSON.parse each line, filter where any of
+  \`trigger\`, \`action\`, \`domain\`, \`project\` contains \`<query>\` (case-insensitive).
+- Return the matched lines pretty-printed (do not mutate the file).
 
 ### \`/cc-learn add\`
-- Ask for: \`type\`, \`short title\`, \`context\`, \`insight\`, \`reuse\`.
-- Optionally ask for: \`confidence\`, \`domain\`, \`project\`.
-- Append one entry using current UTC timestamp.
-- Re-read the file tail and confirm the entry was written.
+- Ask for required fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`project\`.
+- \`confidence\` must be one of \`high\`, \`medium\`, \`low\`. Default to \`medium\` if the user declines to set it.
+- \`domain\`, \`stage\`, and \`project\` may be explicitly \`null\`.
+- \`created\` is set automatically to the current UTC ISO timestamp.
+- Append exactly one JSON line to \`${KNOWLEDGE_PATH}\` with the field order from the schema table above.
+- Re-read the file tail to confirm the new line is valid JSON and parses back to the same object.
 
 ### \`/cc-learn curate\`
 - Hand off to the **knowledge-curation** skill (read-only audit + soft-archive plan).
-- Never deletes from \`${KNOWLEDGE_PATH}\` without an explicit user-approved archive plan.
+- Never deletes. Soft-archive means **moving** full JSON lines from
+  \`${KNOWLEDGE_PATH}\` to \`${KNOWLEDGE_ARCHIVE_PATH}\` as part of a
+  user-approved curation pass.
 `;
 }
 export function learnCommandContract() {
@@ -80,20 +115,23 @@ export function learnCommandContract() {
 
 ## Purpose
 
-Manage the project knowledge store at \`${KNOWLEDGE_PATH}\` (append-only markdown).
+Manage the project knowledge store. One canonical file, strict JSONL:
+- \`${KNOWLEDGE_PATH}\` — append-only JSONL, one entry per line.
+- \`${KNOWLEDGE_ARCHIVE_PATH}\` — soft-archive target written only by curate.
 
 ## HARD-GATE
 
-Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\` (or user-approved summary output).
+Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`,
+\`${KNOWLEDGE_ARCHIVE_PATH}\`, or user-approved summary output.
 
 ## Subcommands
 
 | subcommand | args | description |
 |---|---|---|
-| (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\` / \`compound\`. |
-| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the active file exceeds the curation threshold. |
+| (default) | — | Show recent knowledge entries (tail of JSONL, pretty-printed). |
+| \`search\` | \`<query>\` | Stream-filter the JSONL for matching \`trigger\`, \`action\`, \`domain\`, \`project\`. |
+| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict 8-field schema. |
+| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the file exceeds the curation threshold. |
 `;
 }
 export function selfImprovementBlock(stageName) {
@@ -103,35 +141,34 @@ After this stage, ask:
 - Did I discover a non-obvious reusable **rule** or **pattern**?
 - Did a failure reveal a reusable **lesson**?
 
-If yes, append one concise entry to \`${KNOWLEDGE_PATH}\`:
+If yes, append one concise JSON line to the canonical knowledge store
+(\`${KNOWLEDGE_PATH}\`) using the strict 8-field schema:
 
 \`\`\`bash
 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
+printf '%s\\n' '{"type":"pattern","trigger":"when <situation>","action":"<concrete move>","confidence":"medium","domain":null,"stage":"${stageName}","created":"'"$TS"'","project":null}' >> ${KNOWLEDGE_PATH}
 \`\`\`
 
 Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
+Fields must appear in the order: \`type, trigger, action, confidence, domain, stage, created, project\`.
+Missing optional values must be emitted as \`null\`, never omitted.
 `;
 }
 export function learningsSearchPreamble(stage) {
     return `## Prior Knowledge (load at stage start)
 
-Before stage work, search \`${KNOWLEDGE_PATH}\` for relevant entries (for example: \`${stage}\`, affected systems, key constraints) and apply them explicitly.
-
-If the file is empty, continue normally.
+Before stage work, stream \`${KNOWLEDGE_PATH}\` and filter for entries relevant to
+this stage (\`${stage}\`), affected domains, and key constraints. Apply matching
+entries explicitly. If the file is empty, continue normally.
 `;
 }
 export function learningsAgentsMdBlock() {
     return `### Knowledge Store
 
-\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
-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.
+\`${KNOWLEDGE_PATH}\` — append-only JSONL memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
+Strict 8-field schema: \`type, trigger, action, confidence, domain, stage, created, project\`.
+At session start and stage transitions, tail the file and apply relevant entries.
+If a non-obvious reusable rule/pattern/lesson is discovered, append a new line
+through \`/cc-learn add\` (never hand-edit).
 `;
 }