@jbarket/loomai 0.5.0

package/dist/tools/append-maintenance-log.d.ts

@@ -0,0 +1,52 @@
+export interface Tier2Entry {
+    /** Defaults to "Art-Consolidate autopilot". */
+    runName?: string;
+    memoriesAudited: number;
+    staleCount: number;
+    duplicateCount: number;
+    expiredCount: number;
+    mergeCount: number;
+    contradictions: number;
+    pruned: number;
+    notes?: string;
+}
+export interface Tier3Entry {
+    /** Defaults to "Art-Identity-Review routine". */
+    runName?: string;
+    /** Section names updated in preferences.md (empty/omitted = no changes). */
+    preferencesUpdated?: string[];
+    /** Section names updated in self-model.md (empty/omitted = no changes). */
+    selfModelUpdated?: string[];
+    /** Whether IDENTITY.md itself changed. */
+    identityChanged?: boolean;
+    projectBriefsAccessed: number;
+    projectBriefsStale: number;
+    /** Free-form harness-manifest status, e.g. "4/4 present and current". */
+    harnessManifests?: string;
+    notes?: string;
+}
+export type MaintenanceLogEntry = {
+    type: 'tier-2';
+    timestamp?: Date;
+    tier2: Tier2Entry;
+    tier3?: never;
+} | {
+    type: 'tier-3';
+    timestamp?: Date;
+    tier3: Tier3Entry;
+    tier2?: never;
+};
+export interface AppendResult {
+    success: boolean;
+    filePath: string;
+    /** ISO date (YYYY-MM-DD) of the entry that was written. */
+    timestamp: string;
+}
+export declare function formatEntry(entry: MaintenanceLogEntry): string;
+export declare const FILE_HEADER: string;
+/**
+ * Append a maintenance entry to `logFilePath`. Creates the file (with header) and
+ * any missing parent directories on first write. Each entry is separated from the
+ * previous content by a `---` thematic break.
+ */
+export declare function appendMaintenanceLog(entry: MaintenanceLogEntry, logFilePath: string): Promise<AppendResult>;

package/dist/tools/append-maintenance-log.js

@@ -0,0 +1,103 @@
+/**
+ * append-maintenance-log — appends a dated Markdown entry to a repo-tracked
+ * changelog file for memory-maintenance operations.
+ *
+ * Blessed decision 3 (SLE-89 / SLE-71): the consolidation digest goes to a file
+ * in the repo — not a `reference` memory, not an issue comment. This helper is the
+ * canonical formatter for that file, shared by both maintenance tracks:
+ *   - Tier 2: weekly consolidation  (Art-Consolidate)
+ *   - Tier 3: monthly identity review (Art-Identity-Review)
+ *
+ * It is a plain filesystem append — NO git operations. Entries are append-only;
+ * the maintainer batches commits (agents do not commit). See docs/memory-maintenance.md.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+// ─── Formatting ───────────────────────────────────────────────────────────────
+/** ISO date (YYYY-MM-DD) in UTC. Stable regardless of the host time zone. */
+function isoDate(ts) {
+    return ts.toISOString().slice(0, 10);
+}
+function formatTier2(date, data) {
+    const lines = [
+        `## [${date}] Weekly Consolidation (Tier 2)`,
+        '',
+        `- **Run:** ${data.runName ?? 'Art-Consolidate autopilot'}`,
+        `- **Memories audited:** ${data.memoriesAudited} ` +
+            `(${data.staleCount} stale, ${data.duplicateCount} duplicates, ${data.expiredCount} expired)`,
+        `- **Operations:**`,
+        `  - Merges: ${data.mergeCount}`,
+        `  - Contradictions: ${data.contradictions}`,
+        `  - Pruned: ${data.pruned}`,
+    ];
+    if (data.notes)
+        lines.push(`- **Notes:** ${data.notes}`);
+    return lines.join('\n');
+}
+function formatTier3(date, data) {
+    const prefs = data.preferencesUpdated ?? [];
+    const self = data.selfModelUpdated ?? [];
+    const lines = [
+        `## [${date}] Monthly Identity Review (Tier 3)`,
+        '',
+        `- **Run:** ${data.runName ?? 'Art-Identity-Review routine'}`,
+        `- **Manifest changes:**`,
+        prefs.length > 0
+            ? `  - preferences.md: ${prefs.length} section(s) updated (${prefs.join(', ')})`
+            : `  - preferences.md: No changes`,
+        self.length > 0
+            ? `  - self-model.md: ${self.length} section(s) updated (${self.join(', ')})`
+            : `  - self-model.md: No changes`,
+        `  - IDENTITY.md: ${data.identityChanged ? 'Changes made' : 'No changes'}`,
+        `- **Project briefs:** ${data.projectBriefsAccessed} accessed, ${data.projectBriefsStale} stale`,
+    ];
+    if (data.harnessManifests)
+        lines.push(`- **Harness manifests:** ${data.harnessManifests}`);
+    if (data.notes)
+        lines.push(`- **Notes:** ${data.notes}`);
+    return lines.join('\n');
+}
+export function formatEntry(entry) {
+    const date = isoDate(entry.timestamp ?? new Date());
+    return entry.type === 'tier-2'
+        ? formatTier2(date, entry.tier2)
+        : formatTier3(date, entry.tier3);
+}
+// ─── File header ──────────────────────────────────────────────────────────────
+export const FILE_HEADER = [
+    '# Memory Maintenance Log',
+    '',
+    'Changelog of memory-maintenance operations. Tier 2 (weekly consolidation,',
+    'Art-Consolidate) and Tier 3 (monthly identity review, Art-Identity-Review)',
+    'agents append a dated summary after each run.',
+    '',
+    'Append-only: entries are never edited or removed. Agents do **not** commit —',
+    'the maintainer batches commits. See `docs/memory-maintenance.md` for the format',
+    'and procedure.',
+    '',
+].join('\n');
+// ─── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Append a maintenance entry to `logFilePath`. Creates the file (with header) and
+ * any missing parent directories on first write. Each entry is separated from the
+ * previous content by a `---` thematic break.
+ */
+export async function appendMaintenanceLog(entry, logFilePath) {
+    const date = isoDate(entry.timestamp ?? new Date());
+    await mkdir(dirname(logFilePath), { recursive: true });
+    let existing;
+    try {
+        existing = await readFile(logFilePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        existing = FILE_HEADER;
+    }
+    // Normalize trailing whitespace so the separator spacing is consistent
+    // regardless of how a prior write/edit left the file.
+    const base = existing.replace(/\s*$/, '');
+    const block = `${base}\n\n---\n\n${formatEntry(entry)}\n`;
+    await writeFile(logFilePath, block);
+    return { success: true, filePath: logFilePath, timestamp: date };
+}

package/dist/tools/archive.d.ts

@@ -0,0 +1,2 @@
+import type { ArchiveInput } from '../backends/types.js';
+export declare function archive(contextDir: string, input: ArchiveInput): Promise<string>;

package/dist/tools/archive.js

@@ -0,0 +1,21 @@
+/**
+ * Archive tool — soft-retire a memory with a tombstone instead of hard delete.
+ *
+ * Archived memories are excluded from recall, list, audit, and findSimilar
+ * but remain recoverable via restore. The tombstone preserves the original
+ * body plus a caller-provided note (who/why retired) and a timestamp.
+ */
+import { createBackend } from '../backends/index.js';
+export async function archive(contextDir, input) {
+    const isSingle = input.ref || (input.category && input.title);
+    if (!isSingle) {
+        return 'Nothing to archive. Provide a ref or category+title.';
+    }
+    const backend = createBackend(contextDir);
+    const result = await backend.archive(input);
+    if (result.archived.length === 0) {
+        const identifier = input.ref ?? `${input.category}/${input.title}`;
+        return `Memory not found (or already archived): "${identifier}". Use recall to find the correct reference.`;
+    }
+    return `Memory archived: ${result.archived[0]}`;
+}

package/dist/tools/bootstrap.d.ts

@@ -0,0 +1,11 @@
+export interface BootstrapParams {
+    /** The human this agent works with — their name, not the agent's. */
+    user?: string;
+    name: string;
+    purpose: string;
+    voice: string;
+    preferences?: string;
+    clients?: string[];
+    force?: boolean;
+}
+export declare function bootstrap(contextDir: string, params: BootstrapParams): Promise<string>;

package/dist/tools/bootstrap.js

@@ -0,0 +1,161 @@
+/**
+ * Bootstrap tool — initialize a new loom identity from scratch.
+ *
+ * Runs an onboarding interview (user, name, purpose, voice) and
+ * generates the three core identity files:
+ *   - IDENTITY.md  — the terminal creed (who this agent is)
+ *   - preferences.md — working style with the user
+ *   - self-model.md  — capability tracking skeleton
+ *
+ * Also returns setup snippets for the requested runtimes so the user
+ * knows exactly what to add to their MCP host's config, CLAUDE.md, etc.
+ *
+ * Will not overwrite existing files unless force: true.
+ */
+import { readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWriteWithBackup } from '../path-safety.js';
+import { buildIdentityMd } from './identity-scaffold.js';
+// ─── Identity file templates ──────────────────────────────────────────────────
+function buildPreferencesMd(name, preferences, user) {
+    const who = user?.trim();
+    const body = preferences?.trim()
+        ? preferences.trim()
+        : '*No initial preferences set. Update this file as you learn what works.*';
+    if (!who) {
+        return `# ${name} — Preferences
+
+${body}
+`;
+    }
+    const seeded = preferences?.trim()
+        ? preferences.trim()
+        : `*What you learn about how ${who} works belongs here: communication style, what to
+decide alone, what to bring to them, decisions already made. Write it as you go —
+this file is read into your identity on every wake.*`;
+    return `# ${name} — Preferences
+
+You work with **${who}**.
+
+${seeded}
+`;
+}
+function buildSelfModelMd() {
+    return `# Self-Model
+
+## Strengths
+*(Add your strengths as you discover them)*
+
+## Learning
+*(Add lessons learned here)*
+
+## Current Focus
+*(Track what you're actively working on)*
+`;
+}
+// ─── Setup snippets ───────────────────────────────────────────────────────────
+function setupSnippet(client, contextDir) {
+    switch (client) {
+        case 'claude-code':
+            return `### Claude Code
+
+Add to \`.mcp.json\` (or \`~/.claude/.mcp.json\` for global):
+\`\`\`json
+{
+  "mcpServers": {
+    "loom": {
+      "command": "npx",
+      "args": ["-y", "@jbarket/loomai"],
+      "env": {
+        "LOOM_CONTEXT_DIR": "${contextDir}"
+      }
+    }
+  }
+}
+\`\`\`
+
+Add to \`~/.claude/CLAUDE.md\`:
+\`\`\`
+# Identity Loading
+Before doing any other work, call the \`identity\` MCP tool from the \`loom\` server.
+If the loom MCP server is not available, proceed as a standard Claude Code session.
+\`\`\``;
+        case 'gemini-cli':
+            return `### Gemini CLI
+
+Add to \`GEMINI.md\` (project or global):
+\`\`\`
+# Identity Loading
+At session start, call the \`identity\` tool from the loom MCP server before doing any work.
+\`\`\`
+
+Configure loom in your Gemini CLI MCP settings with:
+- Command: \`npx\`
+- Args: \`-y @jbarket/loomai\`
+- Env: \`LOOM_CONTEXT_DIR=${contextDir}\``;
+        default:
+            return `### ${client}
+
+Add loom as an MCP server:
+- Command: \`npx\`
+- Args: \`-y @jbarket/loomai\`
+- Env: \`LOOM_CONTEXT_DIR=${contextDir}\`
+
+At session start, call \`identity\` (or the runtime-prefixed equivalent) before doing anything else.`;
+    }
+}
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function fileExists(path) {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function bootstrap(contextDir, params) {
+    const { user, name, purpose, voice, preferences, clients = [], force = false } = params;
+    const identityPath = join(contextDir, 'IDENTITY.md');
+    const prefsPath = join(contextDir, 'preferences.md');
+    const selfModelPath = join(contextDir, 'self-model.md');
+    // Guard against overwriting unless forced
+    if (!force) {
+        const existing = [];
+        if (await fileExists(identityPath))
+            existing.push('IDENTITY.md');
+        if (await fileExists(prefsPath))
+            existing.push('preferences.md');
+        if (await fileExists(selfModelPath))
+            existing.push('self-model.md');
+        if (existing.length > 0) {
+            return (`Identity already exists: ${existing.join(', ')}.\n\n` +
+                `Call bootstrap with \`force: true\` to overwrite, or edit the files directly.`);
+        }
+    }
+    // Ensure context dir exists
+    await mkdir(contextDir, { recursive: true });
+    // Write identity files — atomic, with a .bak of any prior version
+    // (only relevant under force: true, when existing files are overwritten)
+    await atomicWriteWithBackup(identityPath, buildIdentityMd({ name, purpose, voice, user }));
+    await atomicWriteWithBackup(prefsPath, buildPreferencesMd(name, preferences, user));
+    await atomicWriteWithBackup(selfModelPath, buildSelfModelMd());
+    const parts = [
+        `## Identity initialized for **${name}**`,
+        `Written to \`${contextDir}\`:`,
+        `- \`IDENTITY.md\` — terminal creed`,
+        `- \`preferences.md\` — working style`,
+        `- \`self-model.md\` — capability skeleton`,
+    ];
+    if (clients.length > 0) {
+        parts.push('\n## Setup Instructions');
+        for (const client of clients) {
+            parts.push(setupSnippet(client, contextDir));
+        }
+    }
+    else {
+        parts.push('\nTo get setup instructions for a specific runtime, call bootstrap again with ' +
+            '`clients: ["claude-code"]` (or "gemini-cli", or any custom runtime name).');
+    }
+    return parts.join('\n');
+}

package/dist/tools/dossier.d.ts

@@ -0,0 +1 @@
+export declare function loadDossier(contextDir: string, project?: string, client?: string, model?: string, role?: string): Promise<string>;

package/dist/tools/dossier.js

@@ -0,0 +1,102 @@
+/**
+ * Dossier tool — brief worker bodies on Art without telling them they ARE Art.
+ *
+ * A worker body (Code, Review, Architect, etc.) is NOT Art. It executes tasks
+ * on Art's behalf. The dossier gives it Art's standards, taste, operating
+ * constraints, and how Art wants work done — framed in the third person.
+ *
+ * Key difference from identity: identity says "you are Art."
+ * Dossier says "you serve Art — here is Art's brief."
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadClientAdapter } from '../clients.js';
+import * as harnessBlock from '../blocks/harness.js';
+import * as modelBlock from '../blocks/model.js';
+import { pathSegmentError } from '../path-safety.js';
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+const PREAMBLE = `# Worker Dossier: Art E Fish
+
+You are a **worker agent** — not Art. You execute tasks on Art E Fish's behalf.
+This dossier gives you Art's standards, taste, operating constraints, and how
+Art wants work done. Read it and apply it.
+
+**Push-back mandate.** Art explicitly expects you to push back on bad work and
+explain why — *including work Art or Jonathan requests*. You serve the standard,
+not the person. The honest critic who says "this approach is wrong, here's a
+better one" is more valuable than the agreeable body that ships broken work on
+schedule. Disagreement is not insubordination; silence about a real problem is.`;
+export async function loadDossier(contextDir, project, client, model, role) {
+    const parts = [PREAMBLE];
+    const effectiveClient = client ?? process.env.LOOM_CLIENT;
+    const effectiveModel = model ?? process.env.LOOM_MODEL;
+    // Boundary discipline: every param that becomes a path segment validates
+    // here, before any file read. Empty/unset values are simply "not provided"
+    // (all readers below are guarded), so only truthy values are checked.
+    for (const [name, value] of [
+        ['project', project],
+        ['client', effectiveClient],
+        ['model', effectiveModel],
+        ['role', role],
+    ]) {
+        if (value) {
+            const error = pathSegmentError(value, name);
+            if (error)
+                return error;
+        }
+    }
+    // Art's working standards — preferences framed as what Art expects from workers
+    const preferences = await readOptional(join(contextDir, 'preferences.md'));
+    if (preferences) {
+        parts.push("# Art's Standards & Working Style\n\n" + preferences.trim());
+    }
+    // Art's capabilities and current focus — context for the work you're doing for him
+    const selfModel = await readOptional(join(contextDir, 'self-model.md'));
+    if (selfModel) {
+        parts.push("# Art's Capabilities & Focus\n\n" + selfModel.trim());
+    }
+    // Role addendum — the specific job this worker body does for Art. Lives in
+    // roles/<role>.md; the SAME mechanism identity() uses for reflection modes.
+    if (role) {
+        const roleBrief = await readOptional(join(contextDir, 'roles', `${role}.md`));
+        if (roleBrief) {
+            parts.push(`# Your Role: ${role}\n\n` + roleBrief.trim());
+        }
+    }
+    // Project-specific context
+    if (project) {
+        const projectBrief = await readOptional(join(contextDir, 'projects', `${project}.md`));
+        if (projectBrief) {
+            parts.push(`# Project: ${project}\n\n` + projectBrief.trim());
+        }
+    }
+    // Harness manifest — tool prefix awareness for workers that call loom tools
+    if (effectiveClient) {
+        const block = await harnessBlock.read(contextDir, effectiveClient);
+        if (block) {
+            parts.push(`# Harness: ${effectiveClient}\n\n${block.body}`);
+        }
+    }
+    // Model manifest
+    if (effectiveModel) {
+        const block = await modelBlock.read(contextDir, effectiveModel);
+        if (block) {
+            parts.push(`# Model: ${effectiveModel}\n\n${block.body}`);
+        }
+    }
+    // Client adapter — tool names for this runtime (e.g. mcp__loom__ prefix)
+    if (effectiveClient) {
+        const adapter = await loadClientAdapter(contextDir, effectiveClient);
+        if (adapter) {
+            parts.push(adapter);
+        }
+    }
+    return parts.join('\n\n---\n\n');
+}

package/dist/tools/eurorack-import.d.ts

@@ -0,0 +1,47 @@
+export declare function resolveContextDir(explicit?: string): string;
+/**
+ * Map a eurorack-repo-relative file path to a domain tag string.
+ * Mirrors the folder→domain map from the Phase 3a inventory report.
+ */
+export declare function mapDomain(relPath: string): string;
+/**
+ * Derive a stable slug from the repo-relative file path.
+ * e.g. "cases/palette-4u/spec.md" → "eurorack-cases-palette-4u-spec"
+ */
+export declare function pathToSlug(relPath: string): string;
+/**
+ * Extract the H1 title from markdown content, falling back to filename.
+ */
+export declare function extractTitle(content: string, filePath: string): string;
+/**
+ * Walk the eurorack repo directory, returning relative paths of markdown files
+ * to import. Skips .git/, CLAUDE.md, and non-.md files.
+ */
+export declare function discoverFiles(repoPath: string): string[];
+export interface ImportRecord {
+    relPath: string;
+    slug: string;
+    title: string;
+    domain: string;
+    status: 'created' | 'skipped' | 'error';
+    error?: string;
+}
+export interface ImportReport {
+    repoPath: string;
+    sha: string;
+    dryRun: boolean;
+    records: ImportRecord[];
+    pagesCreated: number;
+    pagesSkipped: number;
+    pagesFailed: number;
+}
+export interface ImportOptions {
+    /** Absolute path to the eurorack repo checkout */
+    repoPath: string;
+    /** Loom context dir (knowledge.db lives here) */
+    contextDir: string;
+    /** When true, plan the import but write nothing */
+    dryRun?: boolean;
+}
+export declare function importEurorack(options: ImportOptions): Promise<ImportReport>;
+export declare function renderImportReport(report: ImportReport): string;