akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/commands/improve/distill.js

@@ -52,22 +52,31 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import distillKnowledgeSystemPrompt from "../../assets/prompts/distill-knowledge-system.md" with { type: "text" };
+import distillLessonSystemPrompt from "../../assets/prompts/distill-lesson-system.md" with { type: "text" };
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
-import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseFrontmatter, writeSalienceToFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
 import { resolveStashDir, timestampForFilename } from "../../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
+import { getDbPath } from "../../core/paths.js";
+import { openStateDatabase } from "../../core/state-db.js";
 import { warnVerbose } from "../../core/warn.js";
+import { closeDatabase, getAllEntries, openDatabase } from "../../indexer/db/db.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
 import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { akmSearch } from "../read/search.js";
+import { stripFrontmatterBody as stripBodyForFidelity } from "./dedup.js";
 import { assessMemoryKnowledgePromotionCandidate, deriveKnowledgeRef } from "./distill-promotion-policy.js";
+import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.js";
+import { buildClsContext, checkDistillFidelity } from "./homeostatic.js";
+import { computeSalience, upsertAssetSalience } from "./salience.js";
 /**
  * Asset-ref types that `akm distill` structurally refuses as inputs.
  *
@@ -122,68 +131,8 @@ import { repairTruncatedDescription } from "../../core/text-truncation.js";
 import { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse, } from "../proposal/validators/proposal-quality-validators.js";
 export { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse };
 // ── Prompt assembly ─────────────────────────────────────────────────────────
-const LESSON_SYSTEM_PROMPT = [
-    "You are the akm `distill` distiller.",
-    "Given an asset and recent feedback events about it, produce a single",
-    "concise *lesson* an agent should remember next time it works on this",
-    "asset's domain.",
-    "",
-    "YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.",
-    "DO NOT output any prose, explanation, or code fences before or after.",
-    "",
-    "Required output format — copy this structure exactly:",
-    "---",
-    "description: <one complete sentence (ending with `.`) summarising what the lesson teaches>",
-    "when_to_use: <one complete sentence describing the concrete trigger condition>",
-    "---",
-    "",
-    "<lesson body — plain markdown, 1–3 short paragraphs of practical guidance>",
-    "",
-    "## description field (MANDATORY)",
-    "- A single complete sentence in present tense, 80-200 chars, NO markdown.",
-    "- Self-contained: a reviewer must understand the lesson from this field alone.",
-    '- DO NOT start with "When ", "If ", or a connector word — that belongs in when_to_use.',
-    '- DO NOT copy a section heading ("Key takeaways", "For example", "Key pitfalls").',
-    "- DO NOT begin with a numbered list marker, code fence, or markdown heading.",
-    "",
-    'GOOD: "Always validate ref existence before promoting a memory to knowledge; missing refs surface as silent 404s during accept."',
-    'BAD:  "Key pitfalls"',
-    'BAD:  "When working with the akm CLI"',
-    'BAD:  "For example, you might..."',
-    'BAD:  "1. Check the file"',
-    "",
-    "RULES:",
-    "- `when_to_use` MUST be a complete sentence describing a concrete trigger. Never write `When working with <asset-name>` — that is circular and useless.",
-    "- `description` and `when_to_use` MUST differ from each other.",
-    "- The lesson body MUST be non-empty markdown prose. Do NOT restate `description:` or `when_to_use:` inside the body (no `**description:** ...` or `**when_to_use:** ...` lines — the frontmatter is the only place those keys belong).",
-    "- Do NOT emit a second `---` fence after the opening frontmatter — there are exactly two `---` lines in the output, both belonging to the single frontmatter block at the top.",
-    "- Do NOT reproduce the source asset verbatim — distil what a caller needs to know.",
-    "- Output ONLY the lesson file. No preamble, no code fences, no trailing prose.",
-].join("\n");
-const KNOWLEDGE_SYSTEM_PROMPT = [
-    "You are the akm `distill` distiller.",
-    "Given an asset and recent feedback events about it, produce a concise",
-    "*knowledge* markdown document capturing the durable, reusable facts.",
-    "Prefer stable guidance over narrative recap.",
-    "",
-    "YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.",
-    "DO NOT output any prose, explanation, or code fences before or after.",
-    "",
-    "Required output format:",
-    "---",
-    "description: <one-line summary of the knowledge asset>",
-    "tags: [<tag1>, <tag2>]",
-    "---",
-    "",
-    "# <Title>",
-    "",
-    "<body — structured markdown, durable facts only>",
-    "",
-    "RULES:",
-    "- `description` MUST be a non-empty single-line string.",
-    "- Include a meaningful markdown body with a `# Title` heading.",
-    "- Output ONLY the knowledge file. No preamble, no code fences, no trailing prose.",
-].join("\n");
+const LESSON_SYSTEM_PROMPT = distillLessonSystemPrompt;
+const KNOWLEDGE_SYSTEM_PROMPT = distillKnowledgeSystemPrompt;
 // ── Structured-output schemas (responseSchema lift) ─────────────────────────
 //
 // PR 1 of the asset-writers decision (see knowledge:projects/akm/
@@ -681,15 +630,78 @@ export async function akmDistill(options) {
     // Best-effort load: when the asset is not yet indexed we still proceed —
     // the LLM is asked to distil from "available signal" (feedback alone).
     let assetContent = null;
+    let assetFilePath = null;
     try {
         const filePath = await lookup(inputRef);
         if (filePath && fs.existsSync(filePath)) {
+            assetFilePath = filePath;
             assetContent = fs.readFileSync(filePath, "utf8");
         }
     }
     catch {
         assetContent = null;
     }
+    // ── #608: Encoding-time salience scoring ────────────────────────────────
+    // Score the source asset with the three-signal model (novelty × 0.40 +
+    // magnitude × 0.35 + predictionError × 0.25) and persist the result to:
+    //   1. The asset's frontmatter (human-readable mirror; idempotent delta gate).
+    //   2. state.db :: asset_salience (canonical; feeds improve's high-salience gate).
+    // Both writes are best-effort — a DB error never blocks distillation.
+    if (assetContent && assetFilePath) {
+        try {
+            const parsedRef = parseAssetRef(inputRef);
+            // Build bigram vocabulary from currently-indexed refs for novelty signal.
+            let existingRefVocabulary = new Set();
+            try {
+                const embCfg = config?.embedding;
+                const indexDb = openDatabase(getDbPath(), embCfg?.dimension ? { embeddingDim: embCfg.dimension } : undefined);
+                try {
+                    const allRefs = getAllEntries(indexDb).map((e) => e.entryKey);
+                    existingRefVocabulary = buildRefVocabulary(allRefs);
+                }
+                finally {
+                    closeDatabase(indexDb);
+                }
+            }
+            catch {
+                // Index not available — novelty defaults to type-floor.
+            }
+            const salienceResult = scoreEncodingSalience({
+                body: assetContent,
+                type: parsedRef.type,
+                existingRefVocabulary,
+                revisionCount: 0,
+            });
+            // 1. Write salience to the source asset frontmatter (idempotent).
+            const updatedContent = writeSalienceToFrontmatter(assetContent, salienceResult.score, salienceResult);
+            if (updatedContent !== assetContent) {
+                fs.writeFileSync(assetFilePath, updatedContent, "utf8");
+                assetContent = updatedContent;
+            }
+            // 2. Persist encoding_salience to state.db.
+            try {
+                const stateDb = openStateDatabase();
+                try {
+                    const vector = computeSalience({
+                        ref: inputRef,
+                        type: parsedRef.type,
+                        retrievalFreq: 0,
+                        encodingSalience: salienceResult.score,
+                    });
+                    upsertAssetSalience(stateDb, inputRef, vector);
+                }
+                finally {
+                    stateDb.close();
+                }
+            }
+            catch {
+                // State DB unavailable — frontmatter mirror is the only persistence.
+            }
+        }
+        catch {
+            // Scoring errors never block distillation.
+        }
+    }
     const { events } = readEventsImpl({
         ref: inputRef,
         type: "feedback",
@@ -909,13 +921,32 @@ export async function akmDistill(options) {
         reason: p.review?.reason ?? "no reason given",
         contentPreview: p.payload.content.slice(0, 500),
     }));
-    const userPrompt = buildDistillPrompt({
+    // WS-3b CLS interleaving (step 9).
+    // When cls.enabled, inject embedding-retrieved adjacent lessons/knowledge
+    // into the distill prompt so the LLM avoids overwriting prior generalizations
+    // (catastrophic interference). DEFAULT OFF.
+    const clsConfig = config.profiles?.improve?.default?.processes?.distill?.cls ?? {};
+    let clsContext = "";
+    if (clsConfig.enabled) {
+        try {
+            const adjacentCount = clsConfig.adjacentCount ?? 3;
+            // Use the asset content or input ref as the query for adjacent retrieval.
+            const clsQuery = assetContent ? assetContent.slice(0, 500) : inputRef;
+            const adjacentItems = await fetchSimilarLessonsFn(clsQuery, adjacentCount);
+            clsContext = buildClsContext(adjacentItems, clsConfig);
+        }
+        catch {
+            // Fail open — CLS is supplemental, never required.
+        }
+    }
+    const baseUserPrompt = buildDistillPrompt({
         inputRef,
         assetContent,
         feedback,
         proposalKind: effectiveProposalKind,
         ...(rejectedForRef.length > 0 ? { rejectedProposals: rejectedForRef } : {}),
     });
+    const userPrompt = clsContext ? `${baseUserPrompt}${clsContext}` : baseUserPrompt;
     const messages = [
         { role: "system", content: effectiveProposalKind === "knowledge" ? KNOWLEDGE_SYSTEM_PROMPT : LESSON_SYSTEM_PROMPT },
         { role: "user", content: userPrompt },
@@ -1251,6 +1282,30 @@ export async function akmDistill(options) {
         if (judgeResult.score > 0)
             lessonJudgeConfidence = judgeResult.score / 5;
     }
+    // WS-3b: Distill→source fidelity check (step 10).
+    // When fidelityCheck.enabled, check the distill proposal against its cited
+    // source memories. A contradiction flag routes to human review (not auto-accept).
+    // DEFAULT OFF. Fail-open: any error is treated as no-contradiction.
+    const fidelityConfig = config.profiles?.improve?.default?.processes?.distill?.fidelityCheck ?? {};
+    if (fidelityConfig.enabled && assetContent) {
+        try {
+            const proposalBody = stripBodyForFidelity(content);
+            const sourceBodies = [stripBodyForFidelity(assetContent)];
+            const fidelityResult = checkDistillFidelity(proposalBody, sourceBodies, fidelityConfig);
+            if (fidelityResult.contradictionDetected) {
+                // Route to human review by writing a quality rejection with reviewNeeded=true.
+                return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, 2.0, // below auto-accept threshold, signals review needed
+                fidelityResult.reason ?? "Proposal may contradict cited source memories.", {
+                    reviewNeeded: true,
+                    fidelityContradiction: true,
+                    ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+                }, options.eligibilitySource);
+            }
+        }
+        catch {
+            // Fail open — fidelity check is supplemental.
+        }
+    }
     // Round-trip the parsed frontmatter so the proposal carries it as a
     // structured payload alongside the raw content (matches the shape used by
     // other proposal sources).

package/dist/commands/improve/encoding-salience.js

@@ -0,0 +1,205 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Encoding-time salience scoring for issue #608.
+ *
+ * Pure module — no I/O. All inputs are pre-fetched by the caller.
+ * Implements the three-signal model: novelty × 0.40 + magnitude × 0.35 +
+ * predictionError × 0.25, clamped to [0, 1].
+ */
+// ── Weights ────────────────────────────────────────────────────────────────────
+const W_NOVELTY = 0.4;
+const W_MAGNITUDE = 0.35;
+const W_PREDICTION_ERROR = 0.25;
+// Guard: weights must sum to 1.0 (consistent with the pattern in salience.ts).
+// This check fires at module load and catches any future re-tuning mistakes.
+if (Math.abs(W_NOVELTY + W_MAGNITUDE + W_PREDICTION_ERROR - 1.0) > 1e-9) {
+    throw new Error(`encoding-salience.ts: sub-signal weights must sum to 1.0 (got ${W_NOVELTY + W_MAGNITUDE + W_PREDICTION_ERROR})`);
+}
+// ── Novelty type floors ────────────────────────────────────────────────────────
+const TYPE_NOVELTY_FLOOR = Object.freeze({
+    skill: 0.8,
+    agent: 0.8,
+    memory: 0.4,
+});
+const DEFAULT_NOVELTY_FLOOR = 0.5;
+// ── Magnitude keyword sets ──────────────────────────────────────────────────────
+const SEVERITY_BUCKET = new Set(["error", "critical", "warning", "incident", "regression"]);
+// Note: "fails" and "urgent" are from the spec's initial keyword list and are included
+// here as strong constraint signals, even though the spec's final bucket table omits them.
+const CONSTRAINT_BUCKET = new Set(["must", "never", "always", "blocked", "breaking", "deprecated", "fails", "urgent"]);
+const ALL_MAGNITUDE_KEYWORDS = new Set([...SEVERITY_BUCKET, ...CONSTRAINT_BUCKET]);
+// Number of distinct keyword matches to reach full magnitude score.
+const MAGNITUDE_FULL_SCORE_THRESHOLD = 4;
+// Single-bucket magnitude cap: when only one semantic bucket matches.
+const MAGNITUDE_SINGLE_BUCKET_CAP = 0.5;
+// ── Stop-words (excluded from bigram tokenization) ────────────────────────────
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "and",
+    "or",
+    "but",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "of",
+    "with",
+    "by",
+    "from",
+    "as",
+    "is",
+    "it",
+    "its",
+    "be",
+    "are",
+    "was",
+    "were",
+    "has",
+    "have",
+    "had",
+    "do",
+    "does",
+    "did",
+    "not",
+    "this",
+    "that",
+    "these",
+    "those",
+    "i",
+    "we",
+    "you",
+    "he",
+    "she",
+    "they",
+    "my",
+    "our",
+    "your",
+    "his",
+    "her",
+    "their",
+    "can",
+    "will",
+    "would",
+    "should",
+    "could",
+    "may",
+    "might",
+    "shall",
+    "so",
+    "if",
+    "then",
+    "than",
+    "when",
+    "while",
+    "what",
+    "which",
+    "who",
+    "how",
+    "no",
+    "any",
+    "all",
+    "more",
+    "also",
+]);
+// ── Tokenization helpers ──────────────────────────────────────────────────────
+/**
+ * Tokenize text into lowercase words, splitting on whitespace and punctuation,
+ * dropping stop-words. Used for body bigram extraction (novelty signal).
+ */
+function tokenizeBody(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s\p{P}\p{S}\-_/]+/u)
+        .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+/**
+ * Tokenize a ref name or tag into lowercase words without stop-word filtering.
+ * Ref names are identifiers, not prose — all tokens are significant.
+ */
+function tokenizeRef(ref) {
+    return ref
+        .toLowerCase()
+        .split(/[\s\p{P}\p{S}\-_/]+/u)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Generate all consecutive bigrams from an array of tokens.
+ * Returns them as "token1 token2" strings.
+ */
+function bigrams(tokens) {
+    const result = [];
+    for (let i = 0; i < tokens.length - 1; i++) {
+        result.push(`${tokens[i]} ${tokens[i + 1]}`);
+    }
+    return result;
+}
+/**
+ * Build the existing-ref vocabulary: a Set of bigrams derived from tokenizing
+ * the provided ref names (and tags). Pass this to `scoreEncodingSalience` as
+ * `existingRefVocabulary` so the novelty signal can measure how much of the
+ * asset body is already represented in the stash vocabulary.
+ */
+export function buildRefVocabulary(refs) {
+    const vocab = new Set();
+    for (const ref of refs) {
+        const tokens = tokenizeRef(ref);
+        for (const bg of bigrams(tokens)) {
+            vocab.add(bg);
+        }
+    }
+    return vocab;
+}
+// ── Sub-signal computations ────────────────────────────────────────────────────
+function computeNovelty(body, type, vocab) {
+    const tokens = tokenizeBody(body);
+    const bgs = bigrams(tokens);
+    const floor = TYPE_NOVELTY_FLOOR[type] ?? DEFAULT_NOVELTY_FLOOR;
+    if (bgs.length === 0)
+        return floor;
+    const novelCount = bgs.filter((bg) => !vocab.has(bg)).length;
+    const bigramNoveltyFraction = novelCount / bgs.length;
+    return Math.max(floor, bigramNoveltyFraction);
+}
+function computeMagnitude(body) {
+    const lowerBody = body.toLowerCase();
+    // Split on word boundaries to avoid partial matches (e.g. "errors" matching "error").
+    const words = new Set(lowerBody.split(/\W+/).filter((w) => w.length > 0));
+    const matched = [...ALL_MAGNITUDE_KEYWORDS].filter((kw) => words.has(kw));
+    if (matched.length === 0)
+        return 0;
+    const distinctCount = matched.length;
+    const rawMagnitude = Math.min(1.0, distinctCount / MAGNITUDE_FULL_SCORE_THRESHOLD);
+    // Require at least one match from each bucket to lift the single-bucket cap.
+    const hasSeverity = matched.some((kw) => SEVERITY_BUCKET.has(kw));
+    const hasConstraint = matched.some((kw) => CONSTRAINT_BUCKET.has(kw));
+    if (hasSeverity && hasConstraint)
+        return rawMagnitude;
+    return Math.min(rawMagnitude, MAGNITUDE_SINGLE_BUCKET_CAP);
+}
+function computePredictionError(revisionCount) {
+    if (revisionCount === 0)
+        return 1.0;
+    return 1 / (1 + Math.log(1 + revisionCount));
+}
+// ── Main export ────────────────────────────────────────────────────────────────
+/**
+ * Compute the encoding-time salience score for an asset.
+ *
+ * Three sub-signals:
+ *   novelty (0.40) — how much of the body is absent from the stash vocabulary.
+ *   magnitude (0.35) — presence of severity/constraint keywords.
+ *   predictionError (0.25) — surprise: high for new assets, decays with revisions.
+ */
+export function scoreEncodingSalience(inputs) {
+    const novelty = computeNovelty(inputs.body, inputs.type, inputs.existingRefVocabulary);
+    const magnitude = computeMagnitude(inputs.body);
+    const predictionError = computePredictionError(inputs.revisionCount);
+    const raw = W_NOVELTY * novelty + W_MAGNITUDE * magnitude + W_PREDICTION_ERROR * predictionError;
+    const score = Math.min(1, Math.max(0, raw));
+    return { score, novelty, magnitude, predictionError };
+}

package/dist/commands/improve/extract-cli.js

@@ -14,11 +14,14 @@
  * Output is the AkmExtractResult JSON envelope (or an aggregated one when
  * `--auto` runs multiple harnesses).
  */
+import fs from "node:fs";
+import path from "node:path";
 import { defineCommand } from "citty";
 import { output, runWithJsonErrors } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
-import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
+import { getAvailableHarnesses, getWatchTargets } from "../../integrations/session-logs/index.js";
 import { akmExtract } from "./extract.js";
+import { akmExtractWatch } from "./extract-watch.js";
 export const extractCommand = defineCommand({
     meta: {
         name: "extract",
@@ -60,6 +63,15 @@ export const extractCommand = defineCommand({
             type: "string",
             description: "Per-session LLM timeout in ms (default 60000).",
         },
+        watch: {
+            type: "boolean",
+            description: "Watch harness session-log directories and run extract on change (debounced). Stays alive until SIGINT/SIGTERM. Falls back to the */30 cron when off.",
+            default: false,
+        },
+        "debounce-ms": {
+            type: "string",
+            description: "Debounce window in ms for --watch (default 2000).",
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -76,6 +88,17 @@ export const extractCommand = defineCommand({
             if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
                 throw new UsageError(`--timeout-ms must be a positive integer (got "${args["timeout-ms"]}").`, "INVALID_FLAG_VALUE");
             }
+            const watch = args.watch === true;
+            const debounceMs = typeof args["debounce-ms"] === "string" && args["debounce-ms"] !== ""
+                ? Number.parseInt(args["debounce-ms"], 10)
+                : 2000;
+            if (watch && (!Number.isFinite(debounceMs) || debounceMs <= 0)) {
+                throw new UsageError(`--debounce-ms must be a positive integer (got "${args["debounce-ms"]}").`, "INVALID_FLAG_VALUE");
+            }
+            if (watch) {
+                await runWatchMode({ debounceMs, dryRun, force, ...(since ? { since } : {}) });
+                return;
+            }
             if (auto && type) {
                 throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
             }
@@ -125,3 +148,94 @@ export const extractCommand = defineCommand({
         });
     },
 });
+/**
+ * A thin {@link WatchEventSource} over `fs.watch` for each configured root.
+ * This adapter is the ONLY place a real `fs.watch` is created (the core stays
+ * injectable + fully unit-tested); it is intentionally not unit-covered.
+ *
+ * `fs.watch(dir, { recursive: true })` is unreliable for recursive mode on some
+ * Node/Bun/Linux combinations — that is acceptable here: missed events degrade
+ * to the unchanged scheduled cron fallback, never worse than today.
+ */
+function createFsWatchEventSource(roots) {
+    return {
+        subscribe(listener) {
+            const watchers = [];
+            for (const root of roots) {
+                try {
+                    const watcher = fs.watch(root, { recursive: true }, (_event, filename) => {
+                        if (!filename)
+                            return;
+                        const filePath = path.isAbsolute(filename.toString())
+                            ? filename.toString()
+                            : path.join(root, filename.toString());
+                        listener({ path: filePath });
+                    });
+                    watchers.push(watcher);
+                }
+                catch {
+                    // A root that can't be watched is skipped; the cron fallback covers it.
+                }
+            }
+            return () => {
+                for (const w of watchers) {
+                    try {
+                        w.close();
+                    }
+                    catch {
+                        // best-effort teardown
+                    }
+                }
+            };
+        },
+    };
+}
+/**
+ * Run `akm extract --watch`: watch every available harness's session-log
+ * roots and run extract (debounced, per-harness) on change. Stays alive until
+ * SIGINT/SIGTERM, then stops cleanly. PROCESS-HYGIENE: stop() removes every
+ * watcher + pending timer before the process exits.
+ */
+async function runWatchMode(opts) {
+    const targets = getWatchTargets();
+    if (targets.length === 0) {
+        output("extract", {
+            schemaVersion: 1,
+            ok: false,
+            shape: "extract-watch-started",
+            warnings: ["no watchable harness session-log directories found on this machine"],
+            watching: [],
+        });
+        return;
+    }
+    const allRoots = targets.flatMap((t) => t.roots);
+    const eventSource = createFsWatchEventSource(allRoots);
+    const handle = akmExtractWatch({
+        roots: targets,
+        eventSource,
+        debounceMs: opts.debounceMs,
+        onTrigger: async (harnessName) => {
+            await akmExtract({
+                type: harnessName,
+                dryRun: opts.dryRun,
+                force: opts.force,
+                ...(opts.since ? { since: opts.since } : {}),
+            });
+        },
+    });
+    output("extract", {
+        schemaVersion: 1,
+        ok: true,
+        shape: "extract-watch-started",
+        debounceMs: opts.debounceMs,
+        watching: allRoots,
+    });
+    await new Promise((resolve) => {
+        const shutdown = () => {
+            handle.stop();
+            resolve();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}

package/dist/commands/improve/extract-prompt.js

@@ -21,12 +21,18 @@ import promptTemplate from "../../assets/prompts/extract-session.md" with { type
  *
  * Shape:
  *   {
- *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
+ *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence,
+ *                     orderedActions?, outcomeData?}, ...],
  *     "rationale_if_empty"?: string
  *   }
  *
  * `additionalProperties: false` at each level so any hallucinated keys are
  * dropped before parsing.
+ *
+ * `orderedActions` and `outcomeData` are additive fields for #615 procedural
+ * compilation (WS-0 data-capture hook). Source transcripts are external logs
+ * not guaranteed re-extractable; we capture the ordered-action sequence and
+ * outcome now even though the detection/compilation feature is deferred to 0.10+.
  */
 export const EXTRACT_JSON_SCHEMA = {
     type: "object",
@@ -79,6 +85,17 @@ export const EXTRACT_JSON_SCHEMA = {
                         minLength: 5,
                         description: "One-line pointer to the moment in the session that supports this candidate.",
                     },
+                    orderedActions: {
+                        type: "array",
+                        description: "OPTIONAL. Ordered list of discrete actions taken during this episode, as brief imperative phrases (e.g. 'run deploy.sh', 'check VPN status', 'retry with --force'). Capture only when the candidate represents a recurring action sequence that could become a skill or workflow. Omit when the candidate is a standalone fact or observation.",
+                        items: { type: "string", minLength: 3 },
+                        maxItems: 20,
+                    },
+                    outcomeData: {
+                        type: "string",
+                        description: "OPTIONAL. One-sentence description of the outcome when the ordered action sequence completed (e.g. 'deploy succeeded after VPN reconnect', 'build failed with error X'). Required when orderedActions is present; omit otherwise.",
+                        maxLength: 400,
+                    },
                 },
             },
         },
@@ -207,6 +224,20 @@ export function parseExtractPayload(stdout) {
         };
         if (typeof c.when_to_use === "string")
             candidate.when_to_use = c.when_to_use.trim();
+        // #615 WS-0: parse optional ordered-action + outcome fields.
+        // Defensive: silently drop malformed entries rather than rejecting the whole candidate.
+        if (Array.isArray(c.orderedActions) && c.orderedActions.length > 0) {
+            const actions = c.orderedActions
+                .filter((a) => typeof a === "string" && a.trim().length >= 3)
+                .map((a) => a.trim())
+                .slice(0, 20);
+            if (actions.length > 0) {
+                candidate.orderedActions = actions;
+                if (typeof c.outcomeData === "string" && c.outcomeData.trim().length > 0) {
+                    candidate.outcomeData = c.outcomeData.trim().slice(0, 400);
+                }
+            }
+        }
         candidates.push(candidate);
     }
     const result = { candidates };