akm-opencode 0.8.0-rc.8 → 0.8.0

package/shared/redaction.ts

@@ -0,0 +1,292 @@
+import { inspect } from "node:util"
+
+export type RedactionResult = {
+  text: string
+  redacted: boolean
+  categories: string[]
+}
+
+export type RedactedObjectResult<T> = {
+  value: T
+  redacted: boolean
+  categories: string[]
+}
+
+const SENSITIVE_KEY_RE = /(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|GITHUB_TOKEN|GH_TOKEN|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|AZURE_[A-Z0-9_]*KEY|SLACK_BOT_TOKEN|SLACK_TOKEN|PASSWORD|PASSWD|SECRET|CONNECTION_STRING|DATABASE_URL|AKM_[A-Z0-9_]*TOKEN)/i
+const SIMPLE_REPLACEMENTS: Array<{ category: string; pattern: RegExp; replacement: string }> = [
+  {
+    category: "private_key",
+    pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    replacement: "[REDACTED:PRIVATE_KEY]",
+  },
+  {
+    category: "bearer_token",
+    pattern: /Bearer\s+[A-Za-z0-9._~+/=-]+/gi,
+    replacement: "[REDACTED:BEARER_TOKEN]",
+  },
+  {
+    category: "github_token",
+    pattern: /\bgh[pousr]_[A-Za-z0-9_]+\b/g,
+    replacement: "[REDACTED:GITHUB_TOKEN]",
+  },
+  {
+    category: "github_pat",
+    pattern: /\bgithub_pat_[A-Za-z0-9_]+\b/g,
+    replacement: "[REDACTED:GITHUB_PAT]",
+  },
+  {
+    category: "openai_key",
+    pattern: /\bsk-[A-Za-z0-9_-]+\b/g,
+    replacement: "[REDACTED:OPENAI_API_KEY]",
+  },
+  {
+    category: "slack_token",
+    pattern: /\bxox[baprs]-[A-Za-z0-9-]+\b/g,
+    replacement: "[REDACTED:SLACK_TOKEN]",
+  },
+  // 0.8.0 release-hardening: AWS access key (AKIA prefix, 16 alphanumerics).
+  // IAM user access keys are 20 chars total starting with AKIA; STS temporary
+  // creds use ASIA but those are paired with a session token and short-lived,
+  // so the AKIA prefix is the high-value leak.
+  {
+    category: "aws_access_key",
+    pattern: /\bAKIA[0-9A-Z]{16}\b/g,
+    replacement: "[REDACTED:AWS_ACCESS_KEY_ID]",
+  },
+  // Google Cloud API key (AIza prefix, 35 base64url-safe chars). Pattern is
+  // documented at cloud.google.com/docs/authentication/api-keys.
+  {
+    category: "google_api_key",
+    pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    replacement: "[REDACTED:GOOGLE_API_KEY]",
+  },
+  // Stripe live-mode secret/publishable keys (sk_live_, pk_live_). Stripe
+  // documents these as the high-severity leak surface in their API docs.
+  {
+    category: "stripe_live_key",
+    pattern: /\b(?:sk|pk)_live_[0-9a-zA-Z]+\b/g,
+    replacement: "[REDACTED:STRIPE_LIVE_KEY]",
+  },
+  // Stripe test-mode keys (sk_test_, pk_test_). Lower severity but still
+  // sensitive — test keys often grant access to test webhooks and dashboards
+  // that mirror production object shapes.
+  {
+    category: "stripe_test_key",
+    pattern: /\b(?:sk|pk)_test_[0-9a-zA-Z]+\b/g,
+    replacement: "[REDACTED:STRIPE_TEST_KEY]",
+  },
+  // Raw `Authorization: <token>` header without the `Bearer` keyword. Some
+  // services (legacy AWS, internal APIs, OAuth1 signed requests) send the
+  // token directly. The Bearer-form pattern above handles the common case.
+  // We require at least 12 chars of token to avoid matching `Authorization: ?`
+  // or other very short placeholder values.
+  {
+    category: "authorization_header",
+    pattern: /(Authorization:\s+)(?!Bearer\b)([A-Za-z0-9._~+/=-]{12,})/gi,
+    replacement: "$1[REDACTED:AUTHORIZATION]",
+  },
+  // WS-7b: Database connection strings — redact credentials portion.
+  // Matches postgres://, mysql://, mongodb+srv://, mongodb://, redis:// with user:pass@ form.
+  {
+    category: "connection_string",
+    pattern: /((?:postgres|postgresql|mysql|mongodb(?:\+srv)?|redis):\/\/)([^@\s]+@)([^\s"'`,]+)/gi,
+    replacement: "$1[REDACTED:CREDENTIALS]@$3",
+  },
+  // WS-7b: AWS ARN structures with embedded account IDs (12-digit).
+  // Matches arn:aws:...:123456789012:... patterns.
+  {
+    category: "aws_arn",
+    pattern: /arn:aws:[a-z0-9_-]+:[a-z0-9-]*:(\d{12}):[^\s"'`,]*/gi,
+    replacement: "arn:aws:...[REDACTED:ACCOUNT_ID]:...",
+  },
+  // WS-7b: JWT-shaped tokens — three base64url segments separated by dots (eyJ prefix).
+  {
+    category: "jwt_token",
+    pattern: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+    replacement: "[REDACTED:JWT_TOKEN]",
+  },
+]
+
+/**
+ * High-entropy string redaction (WS-7b).
+ *
+ * Generic strings >= 32 chars matching [A-Za-z0-9+/=_-]+ that look like
+ * base64/hex secrets. Disabled by default to avoid false positives (e.g.
+ * long identifiers, file paths, etc.). Opt in by setting the env var:
+ *
+ *   AKM_REDACT_HIGH_ENTROPY=1
+ *
+ * The threshold is 32 chars, configurable via AKM_REDACT_ENTROPY_MIN_LEN.
+ */
+const HIGH_ENTROPY_ENABLED = process.env.AKM_REDACT_HIGH_ENTROPY === "1"
+const HIGH_ENTROPY_MIN_LEN = Number.parseInt(process.env.AKM_REDACT_ENTROPY_MIN_LEN ?? "32", 10)
+const HIGH_ENTROPY_RE = HIGH_ENTROPY_ENABLED
+  ? new RegExp(`\\b[A-Za-z0-9+/=_-]{${Math.max(32, HIGH_ENTROPY_MIN_LEN)},}\\b`, "g")
+  : null
+
+/**
+ * Opt-in PII redaction patterns. Off by default because financial / phone
+ * shapes appear in legitimate logs (timestamps, counters, identifiers) and
+ * over-redaction makes session logs unreadable. Enable for hosts that
+ * legitimately process PII through the agent loop:
+ *
+ *   AKM_REDACT_PII=1
+ *
+ * Patterns covered:
+ *   - Credit-card-shaped 13–19 digit sequences with optional `[- ]` delimiters
+ *     (Luhn is intentionally NOT verified — we redact aggressively when opt-in)
+ *   - US Social Security Numbers in `\d{3}-\d{2}-\d{4}` form (delimited only;
+ *     bare 9-digit numbers are too noisy)
+ *   - US/international phone numbers in `[\+]?\d{1,3}[- .]?\d{3}[- .]?\d{3}[- .]?\d{4}` form
+ */
+const PII_REDACTION_ENABLED = process.env.AKM_REDACT_PII === "1"
+const PII_PATTERNS: Array<{ category: string; pattern: RegExp; replacement: string }> = PII_REDACTION_ENABLED
+  ? [
+      {
+        category: "credit_card",
+        pattern: /\b(?:\d[ -]?){12,18}\d\b/g,
+        replacement: "[REDACTED:CREDIT_CARD]",
+      },
+      {
+        category: "ssn",
+        pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+        replacement: "[REDACTED:SSN]",
+      },
+      {
+        category: "phone",
+        pattern: /(?<![\w./-])\+?\d{1,3}[- .]?\(?\d{3}\)?[- .]?\d{3}[- .]?\d{4}(?![\w./-])/g,
+        replacement: "[REDACTED:PHONE]",
+      },
+    ]
+  : []
+
+function uniq(values: string[]): string[] {
+  return [...new Set(values)]
+}
+
+function redactAssignments(text: string, categories: string[]): string {
+  const envLineRe = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/gm
+  let next = text.replace(envLineRe, (match, rawKey: string) => {
+    const key = String(rawKey)
+    if (!SENSITIVE_KEY_RE.test(key)) return match
+    categories.push(key.toLowerCase().includes("password") || key.toLowerCase().includes("passwd") ? "password" : "env_secret")
+    categories.push("env_output")
+    return `${key}: [REDACTED:${key}]`
+  })
+  const inlineAssignmentRe = /\b([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^\s"'`,;]+)/g
+  next = next.replace(inlineAssignmentRe, (match, rawKey: string) => {
+    const key = String(rawKey)
+    if (!SENSITIVE_KEY_RE.test(key)) return match
+    categories.push(key.toLowerCase().includes("password") || key.toLowerCase().includes("passwd") ? "password" : "env_secret")
+    categories.push("env_output")
+    return `${key}: [REDACTED:${key}]`
+  })
+  return next
+}
+
+function redactJsonLikePairs(text: string, categories: string[]): string {
+  const pairRe = /(["']?)(password|passwd|secret|connectionString|apiKey|token|accessKey|secretKey)(\1\s*[:=]\s*)(["']?)([^\n,}"']+)(["']?)/gi
+  return text.replace(pairRe, (_match, q1: string, key: string, sep: string) => {
+    const upper = key.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()
+    const category = /connection/i.test(key)
+      ? "connection_string"
+      : /pass/i.test(key)
+        ? "password"
+        : /secret/i.test(key)
+          ? "secret"
+          : "token"
+    categories.push(category)
+    return `${q1}${key}${q1}${sep}[REDACTED:${upper}]`
+  })
+}
+
+// Redact `--flag value` / `-f value` CLI argv shapes where the flag name
+// contains a sensitive substring (password, token, secret, api-key, etc.).
+// This catches a class of leaks that the env-assignment and JSON-pair
+// regexes miss because CLI args use a space separator rather than `=` / `:`.
+function redactCliArgPairs(text: string, categories: string[]): string {
+  const pairRe = /(--?[A-Za-z0-9_-]*?(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|auth)[A-Za-z0-9_-]*)(\s+)(\S+)/gi
+  return text.replace(pairRe, (_match, flag: string, sep: string) => {
+    categories.push("cli_arg_secret")
+    return `${flag}${sep}[REDACTED:CLI_ARG]`
+  })
+}
+
+export function redactSecrets(input: string): RedactionResult {
+  let text = input
+  const categories: string[] = []
+
+  for (const entry of SIMPLE_REPLACEMENTS) {
+    if (!entry.pattern.test(text)) continue
+    categories.push(entry.category)
+    text = text.replace(entry.pattern, entry.replacement)
+  }
+
+  text = redactAssignments(text, categories)
+  text = redactJsonLikePairs(text, categories)
+  text = redactCliArgPairs(text, categories)
+
+  // WS-7b: Optional high-entropy string redaction (opt-in via AKM_REDACT_HIGH_ENTROPY=1).
+  if (HIGH_ENTROPY_RE && HIGH_ENTROPY_RE.test(text)) {
+    categories.push("high_entropy")
+    HIGH_ENTROPY_RE.lastIndex = 0 // reset after .test()
+    text = text.replace(HIGH_ENTROPY_RE, "[REDACTED:HIGH_ENTROPY]")
+  }
+
+  // Opt-in PII redaction (AKM_REDACT_PII=1).
+  for (const entry of PII_PATTERNS) {
+    if (!entry.pattern.test(text)) continue
+    categories.push(entry.category)
+    entry.pattern.lastIndex = 0
+    text = text.replace(entry.pattern, entry.replacement)
+  }
+
+  return {
+    text,
+    redacted: categories.length > 0,
+    categories: uniq(categories),
+  }
+}
+
+function normalizeObjectInput(value: unknown): unknown {
+  if (typeof value === "string") return value
+  if (value == null) return value
+  if (typeof value === "number" || typeof value === "boolean") return value
+  if (Array.isArray(value)) return value.map(normalizeObjectInput)
+  if (typeof value === "object") {
+    const record: Record<string, unknown> = {}
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      record[key] = normalizeObjectInput(entry)
+    }
+    return record
+  }
+  return inspect(value, { depth: 4, breakLength: 120 })
+}
+
+function redactUnknown(value: unknown, categories: string[]): unknown {
+  if (typeof value === "string") {
+    const redacted = redactSecrets(value)
+    categories.push(...redacted.categories)
+    return redacted.text
+  }
+  if (Array.isArray(value)) return value.map((entry) => redactUnknown(entry, categories))
+  if (value && typeof value === "object") {
+    const output: Record<string, unknown> = {}
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      output[key] = redactUnknown(entry, categories)
+    }
+    return output
+  }
+  return value
+}
+
+export function redactObject<T>(input: T): RedactedObjectResult<T> {
+  const categories: string[] = []
+  const normalized = normalizeObjectInput(input)
+  const value = redactUnknown(normalized, categories) as T
+  return {
+    value,
+    redacted: categories.length > 0,
+    categories: uniq(categories),
+  }
+}

package/shared/ref-extraction.ts

@@ -0,0 +1,261 @@
+/**
+ * AKM ref extraction & live-stash validation.
+ *
+ * Background: session-checkpoint memories captured by the hook embed Bash
+ * command bodies verbatim — heredocs, grep patterns, jq queries, JSON
+ * payloads. Naive ref extraction (`text.match(REF_PATTERN)`) treats every
+ * `<type>:<slug>` token as a real reference, which causes `akm lint` to
+ * flag string-literal tokens as `missing-ref`. The next session capture
+ * regenerates the same flags — a permanent lint treadmill.
+ *
+ * The fix (this module): we drop the "guess from context" heuristic and
+ * instead **validate every candidate against the live local stash**. A
+ * token only graduates from "candidate" to "ref" when the referenced asset
+ * actually exists on disk. Anything that doesn't resolve is silently
+ * dropped — including all the literal-string false positives.
+ *
+ * The validation logic mirrors the consumer-side lint walker
+ * (`src/commands/lint/base-linter.ts#refExistsInAnyStash`). We deliberately
+ * inline a small copy here (rather than spawn a subprocess) so the hook's
+ * post-tool path stays cheap (zero subprocess, zero JSON parse). The two
+ * resolvers must stay in sync; any new asset type added to lint's
+ * `refToRelPath` must be added here too.
+ */
+
+// CONTRACT: ref-resolver
+// ----------------------------------------------------------------------------
+// The `refExistsInAnyStash` and `refToRelPath` helpers below are
+// contract-locked: a sister copy lives in the akm-core repo at
+// `src/commands/lint/base-linter.ts`. Both implementations resolve the same
+// `<type>:<slug>` -> on-disk-asset question and MUST agree on the set of
+// reachable refs for any given stash layout.
+//
+// The lock is enforced by `tests/ref-resolver-contract.test.ts`, which drives
+// `validateRefCandidates` (the only public entry to this resolver) through a
+// canonical fixture set. The akm-core repo ships an equivalent test at
+// `tests/contracts/ref-resolver-contract.test.ts` that drives ITS copy
+// through the SAME inputs. Any change to the resolver behavior on either
+// side MUST update both contract tests in lockstep, or one will fail.
+//
+// NOTE: this file is the SECOND copy of the resolver. The runtime-shipped
+// copy lives at `claude/shared/ref-extraction.ts` and is imported by the
+// post-tool hook. Both copies must agree with each other AND with the
+// akm-core resolver. The contract test runs against `../shared/ref-extraction`
+// (this file) — the divergence between this file and the runtime copy is
+// tracked separately (regex tightness only, see top-level repo notes).
+// ----------------------------------------------------------------------------
+
+import { existsSync, statSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Permissive ref regex. Matches `[origin//]type:slug` for the known asset
+ * types. Origins (e.g. `local//`, `npm:foo//`) are tolerated but stripped
+ * before validation — only `local//` refs are resolvable against the local
+ * stash; anything else is dropped because we cannot validate it offline.
+ *
+ * Kept in sync with the lint walker pattern in
+ * `src/commands/lint/base-linter.ts`.
+ */
+// Slug body allows the same charset as the lint walker, but the closing
+// character must be alphanumeric, `_`, or `-` — so a trailing `.` or `/`
+// from natural prose (`see memory:rollout-notes.`) does not leak into
+// the captured ref string. Mirrors the consumer-side
+// `src/commands/lint/base-linter.ts` REF_RE, which terminates on a
+// punctuation set including `.` via lookahead. We allow `.` mid-slug
+// (e.g. `env:.env`-style names) by requiring the slug to be at least
+// one character and to *end* on `[A-Za-z0-9_-]`.
+const REF_PATTERN =
+  /(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|lesson|script|workflow|task|env|secret|wiki):(?:[A-Za-z0-9._/-]*[A-Za-z0-9_-]|[A-Za-z0-9_-])/g;
+
+/**
+ * Return every `<type>:<slug>` token in `text` regardless of context.
+ * Order matches first-occurrence; duplicates are removed.
+ */
+export function extractAllRefs(text: string): string[] {
+  if (!text) return [];
+  return [...new Set(text.match(REF_PATTERN) ?? [])];
+}
+
+// Tokenized whitespace-split fallback used by callers that need a strict
+// "this token, in isolation, is a ref" answer (e.g. PreToolUse non-Bash
+// observation, which inspects a single tool input field rather than a
+// transcript-style body). Kept for backward compatibility with existing
+// callers in `claude/hooks/akm-hook.ts` and the opencode plugin.
+const AKM_REF_STRICT =
+  /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|task|env|secret|wiki|lesson):[A-Za-z0-9._/\-]+$/;
+const EDGE_PUNCTUATION = new Set([".", ",", ";", ":", "!", "?", "(", ")", "[", "]", "{", "}", "'", "\"", "`"]);
+
+function normalizeToken(token: string): string {
+  let start = 0;
+  let end = token.length;
+  while (start < end && EDGE_PUNCTUATION.has(token[start] ?? "")) start += 1;
+  while (end > start && EDGE_PUNCTUATION.has(token[end - 1] ?? "")) end -= 1;
+  return token.slice(start, end);
+}
+
+export function extractAkmRefsFromString(text: string): string[] {
+  const refs = new Set<string>();
+  for (const token of text.split(/\s+/)) {
+    const normalized = normalizeToken(token);
+    if (normalized && AKM_REF_STRICT.test(normalized)) refs.add(normalized);
+  }
+  return [...refs];
+}
+
+/**
+ * Map ref type → relative path within a stash root.
+ * Returns `null` for types that cannot be resolved by direct path
+ * (scripts live in nested dirs; remote-only types).
+ */
+function refToRelPath(refType: string, refName: string): string | null {
+  switch (refType) {
+    case "agent":
+      return path.join("agents", `${refName}.md`);
+    case "command":
+      return path.join("commands", `${refName}.md`);
+    case "knowledge":
+      return path.join("knowledge", `${refName}.md`);
+    case "memory":
+      return path.join("memories", `${refName}.md`);
+    case "script":
+      return null; // scripts live in nested dirs — skip
+    case "skill":
+      return path.join("skills", refName, "SKILL.md");
+    case "workflow":
+      return path.join("workflows", `${refName}.md`);
+    case "lesson":
+      return path.join("lessons", `${refName}.md`);
+    case "task":
+      return path.join("tasks", `${refName}.md`);
+    case "wiki":
+      return path.join("wikis", `${refName}.md`);
+    case "env":
+      if (!refName || refName === "default") return path.join("env", ".env");
+      return path.join("env", `${refName}.env`);
+    case "secret":
+      return path.join("secrets", refName);
+    default:
+      return null;
+  }
+}
+
+/**
+ * True if `<type>:<refName>` resolves to a real file under any provided
+ * stash root. Mirrors `refExistsInAnyStash` in `src/commands/lint/base-linter.ts`.
+ */
+function refExistsInAnyStash(refType: string, refName: string, stashRoots: readonly string[]): boolean {
+  const relPath = refToRelPath(refType, refName);
+  if (!relPath) return false;
+  for (const root of stashRoots) {
+    if (!root) continue;
+    const absPath = path.join(root, relPath);
+    if (existsSync(absPath)) return true;
+    // Multi-file skill layout: directory containing SKILL.md
+    const bareDir = absPath.replace(/\.md$/, "");
+    try {
+      if (existsSync(bareDir) && existsSync(path.join(bareDir, "SKILL.md"))) return true;
+    } catch {
+      // ignore
+    }
+    // .derived.md variant for memory refs
+    if (refType === "memory") {
+      const derivedPath = path.join(root, "memories", `${refName}.derived.md`);
+      if (existsSync(derivedPath)) return true;
+    }
+    // Knowledge subdirectory layout (knowledge/projects/foo/...)
+    if (refType === "knowledge") {
+      try {
+        const knowledgeDir = path.join(root, "knowledge");
+        if (existsSync(knowledgeDir) && statSync(knowledgeDir).isDirectory()) {
+          for (const entry of readdirSync(knowledgeDir)) {
+            const subPath = path.join(knowledgeDir, entry, `${refName}.md`);
+            if (existsSync(subPath)) return true;
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+    // Fallback: refName already encodes the stash-relative path
+    const directPath = path.join(root, `${refName}.md`);
+    if (existsSync(directPath)) return true;
+    const directDir = path.join(root, refName);
+    try {
+      if (existsSync(directDir) && existsSync(path.join(directDir, "SKILL.md"))) return true;
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
+/**
+ * Drop candidate tokens that obviously cannot resolve:
+ * - Embedded shell expansion: `memory:$(cmd)`, `knowledge:${VAR}`
+ * - ACP type notation: `agent::Type`
+ * - Empty / placeholder slugs: single char, `**`, leading `/`, `~`, `http*`
+ * - Remote origins other than `local//` (cannot be validated offline)
+ */
+function normalizeCandidate(fullRef: string): { type: string; name: string } | null {
+  if (fullRef.includes("$(") || fullRef.includes("${")) return null;
+  if (fullRef.includes("::")) return null;
+
+  let ref = fullRef;
+  if (ref.startsWith("local//")) {
+    ref = ref.slice("local//".length);
+  } else if (ref.includes("//")) {
+    return null; // remote origin — cannot validate locally
+  }
+
+  const colonIdx = ref.indexOf(":");
+  if (colonIdx === -1) return null;
+  const type = ref.slice(0, colonIdx);
+  const name = ref.slice(colonIdx + 1);
+  if (!name || name.startsWith("/") || name.startsWith("~") || name.startsWith("http")) return null;
+  if (name.length <= 1 || name === "**") return null;
+  // Slug must not contain shell metacharacters — pipe etc. would be a
+  // pasted regex like `memory:foo|knowledge:bar`.
+  if (/[|&;<>(){}\[\]"`'\\?*]/.test(name)) return null;
+  return { type, name };
+}
+
+/**
+ * Given an arbitrary block of text and one or more stash roots, return the
+ * subset of `<type>:<slug>` tokens that actually resolve to a real asset
+ * on disk. String literals (heredocs, grep patterns, jq queries) are
+ * silently dropped — they don't exist in the stash and therefore cannot
+ * generate `missing-ref` lint flags after the body is captured.
+ *
+ * The returned list is sorted alphabetically and deduplicated.
+ */
+export function validateLiveRefs(text: string, stashRoots: readonly string[]): string[] {
+  return validateRefCandidates(extractAllRefs(text), stashRoots);
+}
+
+/**
+ * Validate a pre-extracted list of candidate refs against one or more
+ * stash roots. Returns the subset that resolve to a real on-disk asset,
+ * sorted alphabetically and deduplicated. The input is typically produced
+ * by `extractAllRefs(...)` on raw command/output text — the producer-side
+ * collection step is permissive so candidates can be accumulated across
+ * tool invocations and validated once at memory-capture time.
+ */
+export function validateRefCandidates(candidates: readonly string[], stashRoots: readonly string[]): string[] {
+  if (!candidates || candidates.length === 0) return [];
+  const roots = stashRoots.filter(Boolean);
+  if (roots.length === 0) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const candidate of candidates) {
+    const norm = normalizeCandidate(candidate);
+    if (!norm) continue;
+    if (!refExistsInAnyStash(norm.type, norm.name, roots)) continue;
+    const canonical = `${norm.type}:${norm.name}`;
+    if (seen.has(canonical)) continue;
+    seen.add(canonical);
+    out.push(canonical);
+  }
+  out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return out;
+}

package/commands/akm-distill-lesson.md

@@ -1,7 +0,0 @@
-Distill repeated evidence into a proposed lesson.
-
-1. Search or curate for candidate refs.
-2. Show the strongest evidence refs.
-3. Call `akm_help` with `topic: "distill"`.
-4. Run `akm distill <ref>` only after the evidence is clear.
-5. Report the resulting proposal and remind the user that proposed assets are not curated until accepted.

package/commands/akm-reflect-on-failure.md

@@ -1,7 +0,0 @@
-Reflect on an existing AKM asset after failure or drift.
-
-1. Identify the failure evidence and touched refs.
-2. Record negative feedback when justified.
-3. Call `akm_help` with `topic: "reflect"`.
-4. Run `akm reflect <ref> --task "..."`.
-5. List resulting pending proposals and do not accept or reject them without explicit user approval.