@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/library/types.ts

@@ -0,0 +1,181 @@
+/**
+ * scripts/library/types.ts
+ * R2.3 (+D2) — class-memory library record types.
+ * Type A — Pure Script (type + schema definitions only).
+ *
+ * entity.json is the machine record per diagnosed entity. journal.md is the
+ * append-only human log. patterns/<id>.json are regex detectors promoted from
+ * operator-APPROVED findings (the only write trigger).
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { Static } from "@sinclair/typebox";
+
+/**
+ * D2: a single run record stored in the library. operatorInvocation is the
+ * VERBATIM brief preserved even when parsing succeeded (re-parse later + library
+ * authenticity, plan §5 D2).
+ */
+export const LibraryRunRecordSchema = Type.Object({
+  runId: Type.String(),
+  diagnosedAt: Type.String(),
+  /** D2 — verbatim operator brief that initiated this run (may be empty). */
+  operatorInvocation: Type.Optional(Type.String()),
+  /** How many approved findings this run contributed to the library. */
+  approvedFindingCount: Type.Number(),
+});
+export type LibraryRunRecord = Static<typeof LibraryRunRecordSchema>;
+
+/**
+ * A regex pattern detector promoted from an approved finding. Plain regex (no LLM)
+ * so Tier-0 can match it deterministically + cheaply.
+ */
+export const LibraryPatternSchema = Type.Object({
+  patternId: Type.String(),
+  /** Signal/failure-mode this pattern detects (e.g. "loop", "hallucination"). */
+  signal: Type.String(),
+  /** Plain regex source string (matched against trace text/tags in Tier-0). */
+  regex: Type.String(),
+  /** Regex flags (e.g. "i"). */
+  flags: Type.Optional(Type.String()),
+  /** The finding id this pattern was promoted from (provenance). */
+  sourceFindingId: Type.String(),
+  /** ISO8601 when it was approved into the library. */
+  approvedAt: Type.String(),
+});
+export type LibraryPattern = Static<typeof LibraryPatternSchema>;
+
+/**
+ * BLOCK G (deep-read LEDGER) — one cross-run record per (entity, trace) the deep-read
+ * analyzer has already digested. The ledger lets the next run SKIP re-reading a trace
+ * whose digest is still VALID, while remaining honest about staleness: an entry is
+ * INVALIDATED (and excluded from a fold) when the analyzer version changed, the entity
+ * fingerprint changed, or the entry aged past its TTL. Blocks B (deep-read planning)
+ * and C (promotion) consume this — but the ledger itself NEVER decides promotion: it
+ * carries version-stamped digests + validity only (R2 boundary; Block C re-applies the
+ * evidence floor to folded digests).
+ */
+export const DeepReadLedgerEntrySchema = Type.Object({
+  /** Trace this digest was produced from (the dedupe key within an entity ledger). */
+  traceId: Type.String(),
+  /** Failure-mode / signal the deep-read attributed to this trace (e.g. "loop"). */
+  signal: Type.String(),
+  /** Short deterministic digest of what happened — NO client identity, synthetic-safe. */
+  whatHappenedDigest: Type.String(),
+  /** Pointer back to the evidence the digest was derived from (e.g. journal/report ref). */
+  evidenceRef: Type.String(),
+  /** Analyzer version that produced the digest — bump invalidates prior entries. */
+  analyzerVersion: Type.String(),
+  /** Entity fingerprint at digest time — a change (e.g. prompt edit) invalidates priors. */
+  entityFingerprint: Type.String(),
+  /** INJECTED ISO8601 timestamp the entry was recorded (drives TTL invalidation). */
+  ts: Type.String(),
+});
+export type DeepReadLedgerEntry = Static<typeof DeepReadLedgerEntrySchema>;
+
+export const LibraryEntitySchema = Type.Object({
+  name: Type.String(),
+  entityType: Type.Union([
+    Type.Literal("agent"),
+    Type.Literal("tool"),
+    Type.Literal("skill"),
+    Type.Literal("model"),
+  ]),
+  slug: Type.String(),
+  /** D2 — append-only run history (latest last). */
+  runs: Type.Array(LibraryRunRecordSchema),
+  /** Promoted regex detectors (matched FIRST in Tier-0). */
+  patterns: Type.Array(LibraryPatternSchema),
+  /**
+   * BLOCK G — cross-run deep-read ledger (append-only, deduped by traceId). Persisted
+   * in its OWN file (deep-read-ledger.json) so the approved-only entity.json write gate
+   * stays clean; carried on the record type for typed composition by Blocks B/C.
+   */
+  deepReadLedger: Type.Array(DeepReadLedgerEntrySchema),
+  createdAt: Type.String(),
+  updatedAt: Type.String(),
+});
+export type LibraryEntity = Static<typeof LibraryEntitySchema>;
+
+/**
+ * R2.3 — prior-signal weight multiplier. A signal backed by a library prior counts
+ * 3× in the R2.2 awareness/selection step (plan §4 R2.3).
+ */
+export const PRIOR_SIGNAL_WEIGHT = 3;
+
+/**
+ * BLOCK G — default ledger TTL: 30 days in milliseconds. A deep-read digest older than
+ * this is treated as stale and excluded from foldValidDigests(). Callers may override
+ * per-fold; this is the sane default so a year-old digest never silently re-admits.
+ */
+export const DEEP_READ_LEDGER_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+// ── UNIFIED VERDICT LEDGER (finding-verdict MEMORY — both polarities) ─────────
+//
+// The verdict ledger is the diagnostics finding-verdict MEMORY: "what I found (and
+// the operator APPROVED) vs what the operator DISMISSED". It is the SYMMETRIC twin of
+// the approve→pattern loop — ONE per-entity store recording BOTH polarities:
+//   - "approved"  — the operator accepted the finding / its remedy (valid).
+//   - "dismissed" — the operator ruled the finding not-an-issue (invalid → suppress).
+//
+// It lives in its OWN file (verdict-ledger.json) alongside entity.json — the approve→
+// pattern PROMOTE behaviour (entity.json + patterns/ + journal + INDEX) is byte-unchanged;
+// the approve path ADDITIVELY mirrors an "approved" verdict here (see store.ts).
+//
+// NEVER-EXPIRE (operator decision): a dismissal has NO TTL. It stays suppressed
+// indefinitely and un-hides ONLY on (a) severity-escalation (handled at the enrich
+// partition — the finding's current severity materially exceeds severityAtDismissal)
+// or (b) entity-fingerprint invalidation (the agent's prompt/config changed — reuse
+// the foldValidDigests entityFingerprint mechanism, WITHOUT the TTL branch).
+
+/** The two polarities a finding verdict can carry. */
+export const VERDICT_POLARITIES = ["approved", "dismissed"] as const;
+export type VerdictPolarity = (typeof VERDICT_POLARITIES)[number];
+
+/**
+ * Severity grade a finding carries (mirrors Finding.severity in normalize/trace.ts).
+ * Duplicated here so the library layer stays free of a render/normalize import.
+ */
+export const VerdictSeveritySchema = Type.Union([
+  Type.Literal("crit"),
+  Type.Literal("high"),
+  Type.Literal("med"),
+  Type.Literal("info"),
+]);
+export type VerdictSeverity = Static<typeof VerdictSeveritySchema>;
+
+/**
+ * One entry in the unified verdict ledger. The (what, why, where) failure-mode triple
+ * is stored for provenance AND as the basis of the SEMANTIC final-check (the triple is
+ * NOT string-matched run-to-run — a pinned host-runtime reasoning check compares it;
+ * see enrich/dismissal-match.ts). Chesterton's-Fence provenance travels on every entry
+ * (reason · ts · operatorInvocation · runId · severityAtDismissal · entityFingerprint)
+ * so no verdict is a blind suppression.
+ */
+export const VerdictLedgerEntrySchema = Type.Object({
+  /** POLARITY — "approved" (valid) or "dismissed" (not-an-issue → suppress). */
+  verdict: Type.Union([Type.Literal("approved"), Type.Literal("dismissed")]),
+  /** The finding this verdict was cast on (provenance; NOT a run-to-run match key). */
+  findingId: Type.String(),
+  /** Entity slug — the EXACT-match half of the final-check (entity must match). */
+  entitySlug: Type.String(),
+  /** Failure-mode triple (from failureOrigin) — provenance + semantic-match basis. */
+  what: Type.String(),
+  why: Type.String(),
+  where: Type.String(),
+  /** OPTIONAL richer narration (failureOrigin.whatHappened) for the semantic check. */
+  whatHappened: Type.Optional(Type.String()),
+  /** Severity when the verdict was cast — the §escalation guard baseline. */
+  severityAtDismissal: VerdictSeveritySchema,
+  /** Entity fingerprint at verdict time — a change invalidates the verdict (config-change). */
+  entityFingerprint: Type.String(),
+  /** Operator's "why not an issue" / approval note (Chesterton's-Fence provenance). */
+  reason: Type.Optional(Type.String()),
+  /** D2 — verbatim operator invocation that cast this verdict. */
+  operatorInvocation: Type.Optional(Type.String()),
+  /** The run that produced the finding this verdict was cast on. */
+  runId: Type.String(),
+  /** INJECTED ISO8601 timestamp the verdict was recorded (provenance; NOT a TTL basis). */
+  ts: Type.String(),
+});
+export type VerdictLedgerEntry = Static<typeof VerdictLedgerEntrySchema>;

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/lint/template-inline-js.ts

@@ -0,0 +1,267 @@
+/**
+ * scripts/lint/template-inline-js.ts
+ * R-007-B: Template inline-JS TypeScript lint.
+ *
+ * Walks assets/templates/*.html and *.html.tpl and extracts every <script> block whose
+ * type attribute is empty or "text/javascript" (i.e. executable scripts,
+ * NOT type="application/ld+json" or similar data blocks).
+ *
+ * Rejects TypeScript-specific patterns:
+ *   - Type annotations:      `: string`, `: number`, `: boolean`, `: HTMLElement`,
+ *                            `: HTMLInputElement`, `: any`, `: void`
+ *   - Type assertions:       `as SomeType` (capital-letter identifiers)
+ *   - Interfaces:            `interface Foo {`
+ *   - Type aliases:          `type Foo =`
+ *   - Generic functions:     `function f<T>(`
+ *
+ * Exit 0 = all templates pass.
+ * Exit 1 = at least one pattern found — prints actionable error with file + line.
+ *
+ * Usage: bun scripts/lint/template-inline-js.ts [--templates-dir <path>]
+ *        Defaults to assets/templates/ relative to this script's location.
+ *        Scans *.html and *.html.tpl files (R-015-A: added .html.tpl support).
+ *
+ * Type A — Pure Script (no LLM, no agent ops, deterministic lint only).
+ */
+
+import { readFileSync, readdirSync } from "fs";
+import { resolve, dirname as pathDirname, join, basename } from "path";
+
+// ── Forbidden TypeScript patterns in inline executable <script> blocks ─────────
+
+const FORBIDDEN_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  // Type annotations: `: string`, `: number`, `: boolean`, `: any`, `: void`
+  {
+    pattern: /:\s*(string|number|boolean|any|void)\b/,
+    label: "TypeScript type annotation (: string|number|boolean|any|void)",
+  },
+  // HTML element type annotations: `: HTMLElement`, `: HTMLInputElement`
+  {
+    pattern: /:\s*(HTMLElement|HTMLInputElement)\b/,
+    label: "TypeScript DOM type annotation (: HTMLElement | HTMLInputElement)",
+  },
+  // Type assertions: `as HTMLElement`, `as SomeUpperCaseIdentifier`
+  {
+    pattern: /\bas\s+[A-Z][a-zA-Z]+\b/,
+    label: "TypeScript type assertion (as SomeType)",
+  },
+  // Interface declarations: `interface Foo {`
+  {
+    pattern: /\binterface\s+\w+\s*\{/,
+    label: "TypeScript interface declaration",
+  },
+  // Type alias declarations: `type Foo =`
+  {
+    pattern: /\btype\s+\w+\s*=/,
+    label: "TypeScript type alias",
+  },
+  // Generic function syntax: `function f<T>(`
+  {
+    pattern: /\bfunction\s+\w+\s*<[A-Za-z][\w,\s]*>\s*\(/,
+    label: "TypeScript generic function",
+  },
+];
+
+// ── Script block extraction ────────────────────────────────────────────────────
+
+interface ScriptBlock {
+  content: string;
+  startLine: number;  // 1-indexed, line of the opening <script> tag
+}
+
+/**
+ * Extract all executable <script> blocks from an HTML string.
+ * Executable = type attribute is absent, empty, or "text/javascript".
+ * Explicitly EXCLUDES type="application/ld+json" and other non-executable types.
+ */
+function extractExecutableScriptBlocks(html: string): ScriptBlock[] {
+  const blocks: ScriptBlock[] = [];
+  // Match <script ...> ... </script> (non-greedy, handles multiline)
+  const scriptTagRe = /<script([^>]*)>([\s\S]*?)<\/script>/gi;
+
+  let match: RegExpExecArray | null;
+  while ((match = scriptTagRe.exec(html)) !== null) {
+    const attrs = match[1] ?? "";
+    const content = match[2] ?? "";
+
+    // Extract type attribute value
+    const typeMatch = attrs.match(/\btype\s*=\s*["']?([^"'\s>]*)["']?/i);
+    const typeValue = typeMatch ? typeMatch[1].toLowerCase() : "";
+
+    // Skip non-executable script blocks
+    if (typeValue && typeValue !== "text/javascript") {
+      continue;
+    }
+
+    // Calculate starting line number
+    const before = html.slice(0, match.index);
+    const startLine = (before.match(/\n/g)?.length ?? 0) + 1;
+
+    blocks.push({ content, startLine });
+  }
+  return blocks;
+}
+
+// ── R-015-A: Literal newline inside JS string literal ─────────────────────────
+
+/**
+ * Detect lines where a JS string literal (single- or double-quoted) contains a
+ * raw LF — i.e., the quote is opened but not closed before end-of-line.
+ * Such strings cause `SyntaxError: Unexpected token ILLEGAL` in all browsers.
+ *
+ * Algorithm per line:
+ *  1. Strip properly-closed string literals (handles \' and \\ escapes inside)
+ *     so their closing quotes don't produce false positives.
+ *  2. After stripping, any remaining quote at end-of-line = unclosed string
+ *     spanning a literal newline.
+ *
+ * Limitation: does not handle template literals (`\`...\``) or regex literals —
+ * acceptable for a regression guard on simple browser-executable template JS.
+ */
+function detectLiteralNewlinesInBlock(
+  block: ScriptBlock,
+  filePath: string
+): LintError[] {
+  const errors: LintError[] = [];
+  const lines = block.content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Strip complete single-quoted strings (including internal \'  and \\ escapes)
+    let stripped = line.replace(/'(?:[^'\\]|\\.)*'/g, "__STR__");
+    // Strip complete double-quoted strings
+    stripped = stripped.replace(/"(?:[^"\\]|\\.)*"/g, "__STR__");
+
+    // After stripping matched pairs, an unclosed quote at EOL = literal newline in string
+    const singleUnclosed = /'[^']*$/.test(stripped);
+    const doubleUnclosed = /"[^"]*$/.test(stripped);
+
+    if (singleUnclosed || doubleUnclosed) {
+      errors.push({
+        file: filePath,
+        scriptStartLine: block.startLine,
+        contentLine: i + 1,
+        absoluteLine: block.startLine + i,
+        pattern:
+          "Literal newline inside JS string literal (use '\\n' escape instead — R-015-A)",
+        match: line.trim().slice(0, 120),
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ── Main lint runner ───────────────────────────────────────────────────────────
+
+interface LintError {
+  file: string;
+  scriptStartLine: number;
+  contentLine: number;    // line within the script block content (1-indexed)
+  absoluteLine: number;   // approximate line in the HTML file
+  pattern: string;
+  match: string;
+}
+
+function lintTemplateFile(filePath: string): LintError[] {
+  const html = readFileSync(filePath, "utf8");
+  const blocks = extractExecutableScriptBlocks(html);
+  const errors: LintError[] = [];
+
+  for (const block of blocks) {
+    // Check TypeScript-specific forbidden patterns (line by line)
+    const lines = block.content.split("\n");
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      const line = lines[lineIdx];
+      for (const { pattern, label } of FORBIDDEN_PATTERNS) {
+        if (pattern.test(line)) {
+          errors.push({
+            file: filePath,
+            scriptStartLine: block.startLine,
+            contentLine: lineIdx + 1,
+            absoluteLine: block.startLine + lineIdx,
+            pattern: label,
+            match: line.trim().slice(0, 120),
+          });
+        }
+      }
+    }
+    // R-015-A: check for literal newlines inside single/double-quoted string literals
+    errors.push(...detectLiteralNewlinesInBlock(block, filePath));
+  }
+  return errors;
+}
+
+function resolveTemplatesDir(args: string[]): string {
+  const flagIdx = args.indexOf("--templates-dir");
+  if (flagIdx !== -1 && args[flagIdx + 1]) {
+    return resolve(args[flagIdx + 1]);
+  }
+  // Default: assets/templates/ relative to this script (scripts/lint/ → ../.. → skill root)
+  const scriptDir = import.meta.dirname ?? pathDirname(import.meta.url.replace("file://", ""));
+  return join(scriptDir, "..", "..", "assets", "templates");
+}
+
+// ── Entrypoint ─────────────────────────────────────────────────────────────────
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const templatesDir = resolveTemplatesDir(args);
+
+  let htmlFiles: string[];
+  try {
+    htmlFiles = readdirSync(templatesDir)
+      .filter((f) => f.endsWith(".html") || f.endsWith(".html.tpl"))
+      .map((f) => join(templatesDir, f));
+  } catch (err) {
+    process.stderr.write(`[template-inline-js] ERROR: Could not read templates directory: ${templatesDir}\n  ${err}\n`);
+    process.exit(1);
+  }
+
+  if (htmlFiles.length === 0) {
+    process.stdout.write(`[template-inline-js] No .html files found in ${templatesDir} — nothing to lint.\n`);
+    process.exit(0);
+  }
+
+  const allErrors: LintError[] = [];
+
+  for (const file of htmlFiles) {
+    const errors = lintTemplateFile(file);
+    allErrors.push(...errors);
+  }
+
+  if (allErrors.length === 0) {
+    process.stdout.write(
+      `[template-inline-js] PASS — ${htmlFiles.length} template(s) checked, 0 TypeScript patterns found.\n`
+    );
+    process.exit(0);
+  }
+
+  // Report errors
+  process.stderr.write(
+    `[template-inline-js] FAIL — TypeScript patterns found in inline <script> blocks.\n` +
+    `Templates must use plain JavaScript only (no TypeScript syntax in browser-executed script tags).\n\n`
+  );
+
+  for (const err of allErrors) {
+    process.stderr.write(
+      `  ${basename(err.file)}:${err.absoluteLine} — ${err.pattern}\n` +
+      `    Line: ${err.match}\n`
+    );
+  }
+
+  process.stderr.write(
+    "\n" + allErrors.length + " error(s) found in " + new Set(allErrors.map((e) => e.file)).size + " file(s).\n" +
+    "FIX: Remove TypeScript syntax and literal newlines from inline <script type=\"text/javascript\"> blocks.\n" +
+    "  Type annotations: remove ': Type' suffixes\n" +
+    "  Type assertions: replace 'x as HTMLElement' with plain 'x'\n" +
+    "  Interfaces/types: move to a separate .ts compilation step\n" +
+    "  Literal newlines: replace join('\\n') spanning two lines with join('\\\\n') on one line (R-015-A)\n"
+  );
+  process.exit(1);
+}
+
+// Export for testing
+export { extractExecutableScriptBlocks, lintTemplateFile, detectLiteralNewlinesInBlock, FORBIDDEN_PATTERNS };
+export type { ScriptBlock, LintError };

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/memory/append.ts

@@ -0,0 +1,188 @@
+/**
+ * scripts/memory/append.ts
+ * PHASE 3 (PR-D) — project-level AutoMemory APPENDER.
+ *
+ * Appends a NEW (or UPDATES an existing) memory entry to `.mutagent/memory/` on
+ * operator feedback, and refreshes the `MEMORY.md` index. Called at run FINALIZE
+ * (finalize-gate / Step 9.9) when the operator gives feedback about the TOOL or a
+ * standing preference — see the classification rubric in references/memory-format.md.
+ *
+ * Reuses the store.ts APPEND DISCIPLINE (deterministic writes; INJECTED clock; a
+ * regenerated, sorted index) but NOT its per-entity keying — AutoMemory is keyed by
+ * a content SLUG, one FACT per file, not per diagnosed-entity.
+ *
+ * DETERMINISM: `created` is INJECTED (`now`, a YYYY-MM-DD string) so tests are
+ * byte-stable. Dedupe on append: an existing slug is UPDATED in place and its
+ * `created` date REFRESHED (the plan's "dedupe on append: update + refresh date").
+ *
+ * Type A — Pure Script (file I/O; clock INJECTED; base dir INJECTABLE for tests).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "fs";
+import { join } from "path";
+import {
+  memoryRoot,
+  memoryIndexPath,
+  memoryEntryPath,
+  parseMemoryEntry,
+  type MemoryEntry,
+  type MemoryType,
+  type MemoryLifecycle,
+} from "./read.ts";
+
+export interface AppendMemoryInput {
+  /** Kebab-case slug (also the entry filename). */
+  slug: string;
+  /** Frontmatter `name`. */
+  name: string;
+  /** Frontmatter `description` — the one-line relevance hint used at recall. */
+  description: string;
+  /** Classified type (rubric in references/memory-format.md; first-match wins). */
+  type: MemoryType;
+  /** ADL lifecycle tag. Defaults to "diagnose" for a diagnostics-run feedback. */
+  lifecycle: MemoryLifecycle;
+  /** The fact body (for feedback/project include **Why:** + **How to apply:** lines). */
+  body: string;
+  /** INJECTED absolute date (YYYY-MM-DD) — keeps writes deterministic in tests. */
+  now: string;
+}
+
+export interface AppendResult {
+  written: boolean;
+  /** "created" a new entry or "updated" an existing slug (dedupe). */
+  action: "created" | "updated";
+  slug: string;
+  entryPath: string;
+  indexPath: string;
+}
+
+/** Deterministic kebab-case slug: lowercase, non-alphanumerics → "-", collapse, trim. */
+export function memorySlug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") || "untitled"
+  );
+}
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** Render an entry to its committed markdown file shape (frontmatter + body). */
+function renderEntry(input: AppendMemoryInput): string {
+  return (
+    `---\n` +
+    `name: ${input.name}\n` +
+    `description: ${input.description}\n` +
+    `metadata:\n` +
+    `  type: ${input.type}\n` +
+    `  lifecycle: ${input.lifecycle}\n` +
+    `  created: ${input.now}\n` +
+    `---\n\n` +
+    `${input.body.trim()}\n`
+  );
+}
+
+/**
+ * Append (or dedupe-update) an AutoMemory entry + refresh the index. Returns the
+ * write outcome. Idempotent on the slug: a second append with the same slug UPDATES
+ * the file and refreshes its `created` date rather than creating a duplicate.
+ */
+export function appendMemory(input: AppendMemoryInput, base?: string): AppendResult {
+  const root = memoryRoot(base);
+  ensureDir(root);
+
+  const entryPath = memoryEntryPath(input.slug, base);
+  const action: "created" | "updated" = existsSync(entryPath)
+    ? "updated"
+    : "created";
+
+  writeFileSync(entryPath, renderEntry(input), "utf8");
+  regenerateMemoryIndex(base);
+
+  return {
+    written: true,
+    action,
+    slug: input.slug,
+    entryPath,
+    indexPath: memoryIndexPath(base),
+  };
+}
+
+/**
+ * Regenerate `MEMORY.md` DETERMINISTICALLY from the on-disk entries: one
+ * `- [Title](<slug>.md) — <hook>` line per entry, sorted by slug. Pure given disk
+ * state (mirrors store.ts regenerateIndex). The hook is the entry's description.
+ */
+export function regenerateMemoryIndex(base?: string): void {
+  const root = memoryRoot(base);
+  ensureDir(root);
+
+  const slugs = existsSync(root)
+    ? readdirSync(root)
+        .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
+        .map((f) => f.slice(0, -3))
+        .sort()
+    : [];
+
+  const lines: string[] = [
+    "# mutagent — project AutoMemory",
+    "",
+    "> Project-level, COMMITTED. Subject = the TOOL + operator preferences (NOT the",
+    "> diagnosed agent). Claude-Code AutoMemory format; every entry DATED + classified",
+    "> + lifecycle-tagged. See references/memory-format.md.",
+    "",
+  ];
+  for (const slug of slugs) {
+    const entry = loadEntry(slug, base);
+    if (!entry) continue;
+    lines.push(`- [${entry.name}](${slug}.md) — ${entry.description}`);
+  }
+  lines.push("");
+  writeFileSync(memoryIndexPath(base), lines.join("\n"), "utf8");
+}
+
+/** Load + parse a single entry from disk, or null when absent/corrupt. */
+function loadEntry(slug: string, base?: string): MemoryEntry | null {
+  const p = join(memoryRoot(base), `${slug}.md`);
+  if (!existsSync(p)) return null;
+  try {
+    return parseMemoryEntry(slug, readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// CLI usage: bun scripts/memory/append.ts <slug> <name> <description> <type> <lifecycle> <now> <body...> [--root <dir>]
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  const rootIdx = argv.indexOf("--root");
+  const base = rootIdx !== -1 ? argv[rootIdx + 1] : process.cwd();
+  const positional = rootIdx !== -1 ? argv.slice(0, rootIdx) : argv;
+  const [slug, name, description, type, lifecycle, now, ...bodyParts] = positional;
+
+  if (!slug || !name || !description || !type || !lifecycle || !now) {
+    process.stderr.write(
+      "Usage: bun scripts/memory/append.ts <slug> <name> <description> <type> <lifecycle> <YYYY-MM-DD> <body...> [--root <dir>]\n",
+    );
+    process.exit(1);
+  }
+
+  const result = appendMemory(
+    {
+      slug,
+      name,
+      description,
+      type: type as MemoryType,
+      lifecycle: lifecycle as MemoryLifecycle,
+      body: bodyParts.join(" "),
+      now,
+    },
+    base,
+  );
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(0);
+}