codehere 0.3.4 → 0.5.0-alpha.2

package/dist/presentation/cli/commands/memory-command.js

@@ -0,0 +1,1017 @@
+/**
+ * Memory Command — F3 v0.5 memory operations.
+ *
+ * `codehere memory init` migrates the v0.4.1 .codehere/CONTEXT.md /
+ * HANDOVER.md / PROMPTS.md into the four-layer F3 layout per
+ * docs/design/f3_memory_spec.md:
+ *
+ *   CONTEXT.md  → AGENTS.md                          (top-level rename;
+ *                                                     standard cross-tool
+ *                                                     project briefing path)
+ *   HANDOVER.md → memory/working/session.md          (move + path change)
+ *   PROMPTS.md  → skills/<slug>/SKILL.md per ^## section
+ *                                                    (split on level-2 markdown
+ *                                                     headers; intro before
+ *                                                     first ## is dropped — it
+ *                                                     belongs in skills/_index.md
+ *                                                     which `codehere init` already
+ *                                                     wrote)
+ *
+ * Back-compat default: leave a SYMLINK at each old path pointing at the new
+ * location, so any tool / muscle memory that still reads `.codehere/CONTEXT.md`
+ * continues to work transparently.
+ *
+ * For PROMPTS.md the symlink target is `skills/_index.md` because the source
+ * was split into multiple files — there's no single new file to point at.
+ *
+ * Future tasks (v0.5):
+ *   - `codehere memory show [layer]`   (Task 6)
+ *   - `codehere memory graduate`       (Task 5)
+ *
+ * This file currently implements only `init`. The action dispatch is built so
+ * future actions slot in without touching index.ts.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, lstatSync, symlinkSync, statSync, readdirSync, readlinkSync, openSync, writeSync, fsyncSync, closeSync, } from 'fs';
+import { createHash } from 'crypto';
+import { join, dirname } from 'path';
+import { colors, success, info, warning, error, newline } from '../../../ui.js';
+import { findCodebaseRoot } from '../../../domain/services/codebase-detector.js';
+import { homedir } from 'os';
+import { F3_TEMPLATES, ensureEpisodicSymlink } from './init-command.js';
+import { writeRepoMap } from './repo-map-builder.js';
+import { buildMemoryPrefix } from '../../../infrastructure/orchestration/memory-injector.js';
+/**
+ * Lookup table: relative-path-under-.codehere → default seed body.
+ * If a target file matches its default seed byte-for-byte, the user hasn't
+ * edited it and migration is free to overwrite without --force.
+ *
+ * Built lazily from init-command.ts's F3_TEMPLATES so the seed bodies stay
+ * in one place — no duplication, no drift.
+ */
+const DEFAULT_SEED_BODIES = new Map(F3_TEMPLATES.map(t => [t.filename, t.body]));
+function lessonIdForText(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+function readLessonsFile(path) {
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf8')
+        .trim()
+        .split('\n')
+        .filter(l => l.length > 0)
+        .map(l => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            // Skip malformed lines rather than crash.
+            return null;
+        }
+    })
+        .filter((l) => l !== null);
+}
+/**
+ * Append a lesson to lessons.jsonl, deduped by id (content-derived).
+ * Returns 'added' on first write, 'duplicate' if the same id already exists.
+ *
+ * Single-user CLI write — no concurrent-writer atomicity is required. We
+ * open with `O_APPEND` (Node's `'a'` mode), `writeSync`, then `fsyncSync`
+ * to flush the kernel write buffer to stable storage so a power loss
+ * between the call returning and the next sync doesn't lose the lesson
+ * (K2 Round 1 crash-safety nit).
+ */
+function appendLessonIfNew(path, text, source) {
+    const id = lessonIdForText(text);
+    const existing = readLessonsFile(path);
+    const dup = existing.find(l => l.id === id);
+    if (dup)
+        return { result: 'duplicate', lesson: dup };
+    const lesson = {
+        id,
+        text,
+        graduatedAt: new Date().toISOString(),
+        source,
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    // O_APPEND open + write + fsync. fsync is the K2 crash-safety guarantee.
+    const fd = openSync(path, 'a');
+    try {
+        writeSync(fd, JSON.stringify(lesson) + '\n');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { result: 'added', lesson };
+}
+/**
+ * Validate that a parsed candidate has the required fields.
+ * Returns null for any malformed shape — caller surfaces a clean error
+ * instead of crashing in `createHash().update(undefined)` (codex Round 1
+ * fix: candidate files are user-droppable + auto-dream-written, neither
+ * is fully trusted; v0.5 needs explicit validation).
+ *
+ * The candidate's identity is its FILENAME (passed as `filenameId`), never
+ * the JSON `id` field — that field is informational metadata only. Real-repo
+ * dogfood Apr 29 caught Bug 3: when JSON `id` differed from filename, the
+ * list view showed the JSON id but `--accept <id>` lookups by filename failed
+ * with "no candidate found." Filename is now the single source of truth so
+ * what the user sees in the list is exactly what `--accept` expects.
+ */
+function validateCandidate(parsed, filenameId) {
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    const text = obj.text;
+    if (typeof text !== 'string' || text.trim().length === 0)
+        return null;
+    const out = { id: filenameId, text };
+    if (typeof obj.createdAt === 'string')
+        out.createdAt = obj.createdAt;
+    if (typeof obj.source === 'string')
+        out.source = obj.source;
+    if (Array.isArray(obj.supportingEvents)) {
+        out.supportingEvents = obj.supportingEvents.filter((e) => typeof e === 'string');
+    }
+    return out;
+}
+function readCandidate(candidatesDir, id) {
+    const path = join(candidatesDir, id + '.json');
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    return validateCandidate(parsed, id);
+}
+function listCandidates(candidatesDir) {
+    if (!existsSync(candidatesDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(candidatesDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const id = entry.name.slice(0, -'.json'.length);
+        const c = readCandidate(candidatesDir, id);
+        if (c)
+            out.push(c);
+        // Malformed candidates silently skipped from the LIST view — but
+        // --accept on a malformed file by id will surface a clean error
+        // (readCandidate returns null → the same not-found message fires).
+    }
+    return out;
+}
+/**
+ * F3 Task 5 — `codehere memory graduate`.
+ *
+ * Promotes patterns into project-wide lessons. Three explicit paths:
+ *
+ *   --add "<text>"       direct free-text lesson (most common in v0.5
+ *                        before auto-dream populates candidates)
+ *   --accept <id>        graduate a candidate file
+ *   --reject <id>        delete a candidate without graduating
+ *
+ * No flags: list any candidates (or print "no candidates" + --add hint).
+ *
+ * Lesson ids are content-derived (16-hex sha256 of text) so the same text
+ * graduated twice is a no-op. Candidate files are deleted on accept/reject
+ * regardless of dedup outcome — the user made a decision, the candidate
+ * shouldn't keep nagging.
+ *
+ * The auto-dream pipeline that POPULATES candidates/ ships in v0.6
+ * (`auto_dream.py` analog from agentic-stack, see ADR-006). v0.5 ships
+ * the graduation primitives so the eventual auto-dream output is
+ * actionable on day one.
+ */
+function executeMemoryGraduate(options) {
+    const codeInfo = findCodebaseRoot();
+    const root = codeInfo?.rootPath ?? process.cwd();
+    const codehereDir = join(root, '.codehere');
+    if (!existsSync(codehereDir)) {
+        newline();
+        console.log(`  ${error('refused')} .codehere/ not found at this root.`);
+        console.log(`  ${colors.dim('Run')} ${colors.cyan('codehere init')} ${colors.dim('first.')}`);
+        newline();
+        process.exitCode = 1;
+        return;
+    }
+    const lessonsPath = join(codehereDir, 'memory/semantic/lessons.jsonl');
+    const candidatesDir = join(codehereDir, 'memory/candidates');
+    newline();
+    console.log(colors.bold('codehere memory graduate'));
+    newline();
+    // ── --add: direct free-text lesson ──────────────────────────────────────
+    if (options.add !== undefined) {
+        const text = options.add.trim();
+        if (text.length === 0) {
+            console.log(`  ${error('failed ')} --add requires a non-empty lesson text`);
+            newline();
+            process.exitCode = 1;
+            return;
+        }
+        const r = appendLessonIfNew(lessonsPath, text, 'manual');
+        if (r.result === 'added') {
+            console.log(`  ${success('added  ')} lesson ${colors.dim(r.lesson.id)} → ${lessonsPath}`);
+            console.log(`           ${colors.dim('"' + r.lesson.text + '"')}`);
+        }
+        else {
+            console.log(`  ${info('skipped')} duplicate of existing lesson ${colors.dim(r.lesson.id)}`);
+            console.log(`           ${colors.dim('(already in lessons.jsonl — graduate is a no-op)')}`);
+        }
+        newline();
+        return;
+    }
+    // ── --accept <id>: graduate a candidate ─────────────────────────────────
+    if (options.accept !== undefined) {
+        const candidateId = options.accept;
+        const c = readCandidate(candidatesDir, candidateId);
+        if (c === null) {
+            console.log(`  ${error('failed ')} no candidate found with id "${candidateId}"`);
+            console.log(`  ${colors.dim('Inspect ')} ${colors.cyan('codehere memory show')} ${colors.dim('to see what candidates exist.')}`);
+            newline();
+            process.exitCode = 1;
+            return;
+        }
+        const r = appendLessonIfNew(lessonsPath, c.text, `candidate:${candidateId}`);
+        // Either way, the user decided — delete the candidate.
+        rmSync(join(candidatesDir, candidateId + '.json'));
+        if (r.result === 'added') {
+            console.log(`  ${success('graduated')} candidate ${candidateId} → lesson ${colors.dim(r.lesson.id)}`);
+        }
+        else {
+            console.log(`  ${info('skipped ')} candidate ${candidateId} text already in lessons (lesson ${colors.dim(r.lesson.id)})`);
+            console.log(`           ${colors.dim('(candidate file deleted; decision recorded)')}`);
+        }
+        newline();
+        return;
+    }
+    // ── --reject <id>: delete a candidate ──────────────────────────────────
+    if (options.reject !== undefined) {
+        const candidateId = options.reject;
+        const candidatePath = join(candidatesDir, candidateId + '.json');
+        if (!existsSync(candidatePath)) {
+            console.log(`  ${error('failed ')} no candidate found with id "${candidateId}"`);
+            newline();
+            process.exitCode = 1;
+            return;
+        }
+        rmSync(candidatePath);
+        console.log(`  ${success('rejected')} candidate ${candidateId} (deleted, not graduated)`);
+        newline();
+        return;
+    }
+    // ── no flags: list candidates ──────────────────────────────────────────
+    const candidates = listCandidates(candidatesDir);
+    if (candidates.length === 0) {
+        console.log(`  ${info('empty  ')} no candidates to review`);
+        newline();
+        console.log(colors.dim(`  Auto-clustering of episodic patterns into candidates ships in v0.6.`));
+        console.log(colors.dim(`  For now, add lessons directly:`));
+        console.log(`    ${colors.cyan('codehere memory graduate --add "your lesson text"')}`);
+        newline();
+        return;
+    }
+    console.log(`  ${success('present')} ${candidates.length} candidate${candidates.length === 1 ? '' : 's'} pending review:`);
+    newline();
+    for (const c of candidates) {
+        console.log(`  ${colors.bold(c.id)}`);
+        console.log(`    ${c.text}`);
+        if (c.source)
+            console.log(`    ${colors.dim('source: ' + c.source)}`);
+        newline();
+    }
+    console.log(colors.dim('  Act on each:'));
+    console.log(`    ${colors.cyan('codehere memory graduate --accept <id>')}`);
+    console.log(`    ${colors.cyan('codehere memory graduate --reject <id>')}`);
+    newline();
+}
+const SHOW_LAYERS = ['working', 'episodic', 'semantic', 'personal', 'skills', 'protocols', 'injection'];
+/**
+ * Render bytes as a human-friendly size: "0", "412 B", "3.2 KB", "1.8 MB".
+ */
+function fmtSize(bytes) {
+    if (bytes === 0)
+        return '0';
+    if (bytes < 1024)
+        return bytes + ' B';
+    if (bytes < 1024 * 1024)
+        return (bytes / 1024).toFixed(1) + ' KB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}
+/**
+ * Collect a one-line presence/size summary per layer for the overview view.
+ * Pure: only reads filesystem stats; no formatting yet.
+ *
+ * Takes BOTH `codehereDir` and `projectRoot` because the `injection` layer
+ * needs the project root (not just .codehere/) — buildMemoryPrefix walks
+ * upward from there. (codex Round 1 fix — the original signature only had
+ * codehereDir, so the injection summary line was missing from the overview.)
+ */
+function gatherLayerSummary(codehereDir, projectRoot) {
+    const out = [];
+    // working/session.md
+    const sessionPath = join(codehereDir, 'memory/working/session.md');
+    if (existsSync(sessionPath)) {
+        const sz = statSync(sessionPath).size;
+        out.push({ layer: 'working', line: `working    · session.md (${fmtSize(sz)})` });
+    }
+    else {
+        out.push({ layer: 'working', line: `working    · (empty — no session.md)` });
+    }
+    // episodic — symlink + repo_map
+    const episodicLearnings = join(codehereDir, 'memory/episodic/AGENT_LEARNINGS.jsonl');
+    const repoMapPath = join(codehereDir, 'memory/episodic/repo_map.json');
+    const learningsLine = existsSync(episodicLearnings) || isSymlink(episodicLearnings)
+        ? (isSymlink(episodicLearnings) ? `AGENT_LEARNINGS.jsonl → ${readlinkSync(episodicLearnings)}` : 'AGENT_LEARNINGS.jsonl (real file)')
+        : '(no AGENT_LEARNINGS.jsonl)';
+    const repoMapLine = existsSync(repoMapPath)
+        ? `repo_map.json (${fmtSize(statSync(repoMapPath).size)})`
+        : 'no repo_map.json — run `codehere memory repo-map`';
+    out.push({ layer: 'episodic', line: `episodic   · ${learningsLine} · ${repoMapLine}` });
+    // semantic/lessons.jsonl
+    const lessonsPath = join(codehereDir, 'memory/semantic/lessons.jsonl');
+    if (existsSync(lessonsPath)) {
+        const body = readFileSync(lessonsPath, 'utf8');
+        const count = body.trim().length === 0 ? 0 : body.trim().split('\n').length;
+        out.push({ layer: 'semantic', line: `semantic   · lessons.jsonl (${count} lesson${count === 1 ? '' : 's'})` });
+    }
+    else {
+        out.push({ layer: 'semantic', line: `semantic   · (no lessons.jsonl)` });
+    }
+    // personal/preferences.json
+    const prefsPath = join(codehereDir, 'memory/personal/preferences.json');
+    if (existsSync(prefsPath)) {
+        out.push({ layer: 'personal', line: `personal   · preferences.json (${fmtSize(statSync(prefsPath).size)})` });
+    }
+    else {
+        out.push({ layer: 'personal', line: `personal   · (no preferences.json)` });
+    }
+    // skills/<name>/SKILL.md
+    const skillsDir = join(codehereDir, 'skills');
+    if (existsSync(skillsDir)) {
+        const subdirs = readdirSync(skillsDir, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .filter(e => existsSync(join(skillsDir, e.name, 'SKILL.md')));
+        out.push({ layer: 'skills', line: `skills     · ${subdirs.length} skill folder${subdirs.length === 1 ? '' : 's'}` });
+    }
+    else {
+        out.push({ layer: 'skills', line: `skills     · (no skills/ dir)` });
+    }
+    // protocols/hook_patterns.json
+    const patternsPath = join(codehereDir, 'protocols/hook_patterns.json');
+    if (existsSync(patternsPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(patternsPath, 'utf8'));
+            const builtin = Array.isArray(parsed.patterns_builtin) ? parsed.patterns_builtin.length : 0;
+            const project = Array.isArray(parsed.patterns_project) ? parsed.patterns_project.length : 0;
+            out.push({ layer: 'protocols', line: `protocols  · hook_patterns.json (${builtin} built-in + ${project} project)` });
+        }
+        catch {
+            out.push({ layer: 'protocols', line: `protocols  · hook_patterns.json (parse error)` });
+        }
+    }
+    else {
+        out.push({ layer: 'protocols', line: `protocols  · (no hook_patterns.json — run \`codehere protocols export\`)` });
+    }
+    // injection — codex Round 1 fix: every entry in SHOW_LAYERS must appear
+    // in the overview, including the special-case `injection` layer.
+    // buildMemoryPrefix is cheap (it reads the same files we already read above)
+    // and gives the user a single-line answer to "what would actually inject?"
+    // — the most useful thing on the overview for someone debugging their
+    // setup.
+    const inj = buildMemoryPrefix(projectRoot);
+    if (inj.prefix === '') {
+        out.push({ layer: 'injection', line: `injection  · (nothing — empty / placeholder layers)` });
+    }
+    else {
+        const truncNote = inj.truncated ? ' TRUNCATED' : '';
+        out.push({ layer: 'injection', line: `injection  · ${inj.tokens} tokens · ${inj.included.join(', ')}${truncNote}` });
+    }
+    return out;
+}
+/**
+ * `codehere memory show [layer]` — read-only inspector for the F3 layers.
+ * Renders the layer's content (no edits, no spawn).
+ *
+ * Special layer `injection` previews the prefix that WOULD be injected for
+ * a spawn from cwd. Addresses the K2 Round 1 UX concern from F3 Task 8 —
+ * until now the user had no CLI surface to see the auto-injected memory.
+ */
+function executeMemoryShow(layerArg) {
+    const codeInfo = findCodebaseRoot();
+    const root = codeInfo?.rootPath ?? process.cwd();
+    const codehereDir = join(root, '.codehere');
+    // Special case: `memory show injection` is meaningful even outside a
+    // codehere project — the honest answer is "nothing would inject from
+    // here." The buildMemoryPrefix() helper handles the no-ancestor case
+    // by returning an empty prefix, so we let it run and report "empty".
+    if (layerArg === 'injection') {
+        newline();
+        console.log(colors.bold('codehere memory show injection'));
+        newline();
+        const r = buildMemoryPrefix(root);
+        if (r.prefix === '') {
+            console.log(`  ${info('empty  ')} nothing to inject from this cwd`);
+            console.log(`           ${colors.dim('(no .codehere/ ancestor, or no AGENTS.md content / lessons / repo_map symbols / edited session)')}`);
+        }
+        else {
+            console.log(`  ${success('would inject')} ${r.included.join(', ')} · ${r.tokens} tokens${r.truncated ? ' (TRUNCATED)' : ''}`);
+            newline();
+            console.log(colors.dim('─── prefix preview ────────────────────────────────────────────────'));
+            console.log(r.prefix.trimEnd());
+            console.log(colors.dim('─── end of prefix · user prompt would follow ──────────────────────'));
+        }
+        newline();
+        return;
+    }
+    if (!existsSync(codehereDir)) {
+        newline();
+        console.log(`  ${error('refused')} .codehere/ not found at this root.`);
+        console.log(`  ${colors.dim('Run')} ${colors.cyan('codehere init')} ${colors.dim('first.')}`);
+        newline();
+        process.exitCode = 1;
+        return;
+    }
+    // No-arg: overview of every layer.
+    if (!layerArg) {
+        newline();
+        console.log(colors.bold('codehere memory'));
+        console.log(colors.dim(`  inspecting ${codehereDir}`));
+        newline();
+        const summary = gatherLayerSummary(codehereDir, root);
+        for (const s of summary) {
+            console.log(`  ${s.line}`);
+        }
+        newline();
+        console.log(colors.dim(`  Use 'codehere memory show <layer>' for details. Layers: ${SHOW_LAYERS.join(', ')}.`));
+        newline();
+        return;
+    }
+    // Per-layer detail.
+    const layer = layerArg;
+    if (!SHOW_LAYERS.includes(layer)) {
+        console.error(`\n  ${error('failed')} unknown layer: ${layerArg}\n  Valid layers: ${SHOW_LAYERS.join(', ')}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    newline();
+    console.log(colors.bold(`codehere memory show ${layer}`));
+    newline();
+    switch (layer) {
+        case 'working': {
+            const path = join(codehereDir, 'memory/working/session.md');
+            if (!existsSync(path)) {
+                console.log(`  ${info('empty  ')} no session.md yet`);
+            }
+            else {
+                console.log(readFileSync(path, 'utf8').trimEnd());
+            }
+            break;
+        }
+        case 'episodic': {
+            const learnings = join(codehereDir, 'memory/episodic/AGENT_LEARNINGS.jsonl');
+            const repoMap = join(codehereDir, 'memory/episodic/repo_map.json');
+            if (isSymlink(learnings)) {
+                const target = readlinkSync(learnings);
+                console.log(`  ${success('linked ')} AGENT_LEARNINGS.jsonl → ${target}`);
+                try {
+                    const body = readFileSync(learnings, 'utf8');
+                    const count = body.trim().length === 0 ? 0 : body.trim().split('\n').length;
+                    console.log(`           ${colors.dim(`(${count} session record${count === 1 ? '' : 's'})`)}`);
+                }
+                catch {
+                    console.log(`           ${colors.dim('(unreadable)')}`);
+                }
+            }
+            else if (existsSync(learnings)) {
+                console.log(`  ${warning('real-file')} AGENT_LEARNINGS.jsonl is a regular file, not a symlink to ~/.codehere/sessions.jsonl.`);
+            }
+            else {
+                console.log(`  ${info('empty  ')} no AGENT_LEARNINGS.jsonl yet`);
+            }
+            newline();
+            if (existsSync(repoMap)) {
+                try {
+                    const m = JSON.parse(readFileSync(repoMap, 'utf8'));
+                    const fileCount = Object.keys(m.files ?? {}).length;
+                    const symbolCount = Object.values(m.files ?? {}).reduce((acc, f) => {
+                        const symbols = f?.symbols;
+                        return acc + (Array.isArray(symbols) ? symbols.length : 0);
+                    }, 0);
+                    const topCount = Array.isArray(m.topSymbols) ? m.topSymbols.length : 0;
+                    console.log(`  ${success('present')} repo_map.json — ${fileCount} files, ${symbolCount} symbols, top ${topCount} ranked`);
+                    if (Array.isArray(m.topSymbols) && m.topSymbols.length > 0) {
+                        console.log(`           ${colors.dim('top 5:')}`);
+                        for (const s of m.topSymbols.slice(0, 5)) {
+                            console.log(`             ${s.references}× ${s.name}  ${colors.dim(`(${s.file}:${s.line})`)}`);
+                        }
+                    }
+                }
+                catch {
+                    console.log(`  ${error('failed ')} repo_map.json present but unparseable`);
+                }
+            }
+            else {
+                console.log(`  ${info('absent ')} no repo_map.json — run ${colors.cyan('codehere memory repo-map')}`);
+            }
+            break;
+        }
+        case 'semantic': {
+            const path = join(codehereDir, 'memory/semantic/lessons.jsonl');
+            if (!existsSync(path)) {
+                console.log(`  ${info('empty  ')} no lessons.jsonl yet`);
+                break;
+            }
+            const lines = readFileSync(path, 'utf8').trim().split('\n').filter(l => l.length > 0);
+            if (lines.length === 0) {
+                console.log(`  ${info('empty  ')} lessons.jsonl is empty — run ${colors.cyan('codehere memory graduate')} (coming in v0.5)`);
+                break;
+            }
+            console.log(`  ${success('present')} ${lines.length} lesson${lines.length === 1 ? '' : 's'}:`);
+            newline();
+            for (let i = 0; i < lines.length; i++) {
+                try {
+                    const obj = JSON.parse(lines[i]);
+                    const text = obj.text ?? obj.lesson ?? JSON.stringify(obj);
+                    console.log(`  ${(i + 1).toString().padStart(3)}. ${text}`);
+                }
+                catch {
+                    console.log(`  ${(i + 1).toString().padStart(3)}. ${colors.dim('(unparseable JSON)')} ${lines[i].slice(0, 100)}`);
+                }
+            }
+            break;
+        }
+        case 'personal': {
+            const path = join(codehereDir, 'memory/personal/preferences.json');
+            if (!existsSync(path)) {
+                console.log(`  ${info('empty  ')} no preferences.json yet`);
+                break;
+            }
+            console.log(readFileSync(path, 'utf8').trimEnd());
+            break;
+        }
+        case 'skills': {
+            const skillsDir = join(codehereDir, 'skills');
+            if (!existsSync(skillsDir)) {
+                console.log(`  ${info('empty  ')} no skills/ dir`);
+                break;
+            }
+            const subdirs = readdirSync(skillsDir, { withFileTypes: true })
+                .filter(e => e.isDirectory())
+                .filter(e => existsSync(join(skillsDir, e.name, 'SKILL.md')));
+            if (subdirs.length === 0) {
+                console.log(`  ${info('empty  ')} no skill folders yet (skills/<name>/SKILL.md)`);
+                break;
+            }
+            console.log(`  ${success('present')} ${subdirs.length} skill folder${subdirs.length === 1 ? '' : 's'}:`);
+            for (const d of subdirs) {
+                console.log(`    - ${d.name}`);
+            }
+            break;
+        }
+        case 'protocols': {
+            const path = join(codehereDir, 'protocols/hook_patterns.json');
+            if (!existsSync(path)) {
+                console.log(`  ${info('empty  ')} no hook_patterns.json — run ${colors.cyan('codehere protocols export')}`);
+                break;
+            }
+            try {
+                const parsed = JSON.parse(readFileSync(path, 'utf8'));
+                const builtin = Array.isArray(parsed.patterns_builtin) ? parsed.patterns_builtin.length : 0;
+                const project = Array.isArray(parsed.patterns_project) ? parsed.patterns_project.length : 0;
+                console.log(`  ${success('present')} ${builtin} built-in patterns + ${project} project patterns`);
+                if (parsed.patterns_builtin && parsed.patterns_builtin.length > 0) {
+                    // Group by category
+                    const byCategory = new Map();
+                    for (const p of parsed.patterns_builtin) {
+                        byCategory.set(p.category, (byCategory.get(p.category) ?? 0) + 1);
+                    }
+                    newline();
+                    console.log(`  ${colors.dim('by category:')}`);
+                    for (const [cat, n] of [...byCategory.entries()].sort((a, b) => b[1] - a[1])) {
+                        console.log(`    ${n}× ${cat}`);
+                    }
+                }
+            }
+            catch {
+                console.log(`  ${error('failed ')} hook_patterns.json present but unparseable`);
+            }
+            break;
+        }
+        case 'injection': {
+            // Already handled in the early-return branch above (no .codehere/
+            // required for this layer). This case is unreachable but kept so the
+            // exhaustive-switch pattern doesn't drift.
+            break;
+        }
+    }
+    newline();
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert a section title to a filesystem-safe slug.
+ *
+ *   "Implement a change"             → "implement-a-change"
+ *   "Refactor (old style) — careful" → "refactor-old-style-careful"
+ *   "  Trim spaces  "                → "trim-spaces"
+ */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-') // any non-alphanumeric run → single hyphen
+        .replace(/^-+|-+$/g, ''); // trim leading/trailing hyphens
+}
+function parsePromptsSections(content) {
+    // CRLF-tolerant split (K2 review nit).
+    const lines = content.split(/\r?\n/);
+    const sections = [];
+    let current = null;
+    // Fence awareness — CommonMark-correct (codex Round 2 fix).
+    //
+    // Open: 3+ identical fence chars (` or ~), up to 3 leading spaces, optional
+    //       info string after.
+    // Close: SAME fence char, >= opening length, up to 3 leading spaces, ONLY
+    //       trailing whitespace allowed (no info string on closer).
+    //
+    // Without the length+whitespace constraint a line like `````oops``` would
+    // falsely close an opening ```` fence, and the parser would re-enable header
+    // matching mid-block — corrupting the migration.
+    let inFence = false;
+    let fenceChar = ''; // ` or ~
+    let fenceLength = 0; // number of fence chars on the opening line
+    for (const line of lines) {
+        // Try open: 3+ chars, then anything (info string allowed).
+        const openMatch = !inFence ? line.match(/^ {0,3}(`{3,}|~{3,})/) : null;
+        // Try close: SAME char, >= opening length, ONLY trailing whitespace.
+        const closeRegex = inFence
+            ? new RegExp(`^ {0,3}(${fenceChar === '`' ? '`' : '~'}{${fenceLength},})[ \\t]*$`)
+            : null;
+        const closeMatch = inFence && closeRegex ? line.match(closeRegex) : null;
+        if (openMatch) {
+            inFence = true;
+            fenceChar = openMatch[1][0];
+            fenceLength = openMatch[1].length;
+            if (current)
+                current.body += line + '\n';
+            continue;
+        }
+        if (closeMatch) {
+            inFence = false;
+            fenceChar = '';
+            fenceLength = 0;
+            if (current)
+                current.body += line + '\n';
+            continue;
+        }
+        if (!inFence) {
+            const headerMatch = line.match(/^##\s+(.+?)\s*$/);
+            if (headerMatch) {
+                // Push the previous section before starting a new one.
+                if (current)
+                    sections.push(current);
+                const title = headerMatch[1];
+                const slug = slugify(title);
+                // Skip sections whose title slugifies to empty (defensive — shouldn't
+                // happen with reasonable headers, but covers edge inputs).
+                if (slug.length > 0) {
+                    current = { slug, title, body: '' };
+                }
+                else {
+                    current = null;
+                }
+                continue;
+            }
+        }
+        if (current) {
+            current.body += line + '\n';
+        }
+        // Lines before the first ## (intro) are dropped — that text belongs in
+        // skills/_index.md, which init already wrote.
+    }
+    if (current)
+        sections.push(current);
+    // Trim trailing blank lines from each section body.
+    for (const s of sections) {
+        s.body = s.body.replace(/\n+$/, '\n');
+    }
+    return sections;
+}
+/**
+ * Migrate a single source file to a new target path. Returns outcome string.
+ * Behavior:
+ *   - source missing                → 'missing'
+ *   - source is already a symlink   → 'already-migrated' (don't double-migrate)
+ *   - target exists & not --force   → 'skipped'
+ *   - else                          → write target with source body, then
+ *                                     delete source (or leave symlink)
+ */
+/**
+ * "Is this target file just the default F3 seed?" — true if its body is
+ * byte-identical to the seed init writes. Lets migration overwrite the
+ * placeholder without --force, while still respecting user edits.
+ *
+ * targetRelative is the path under .codehere (e.g. 'memory/working/session.md').
+ */
+function isDefaultSeed(targetRelative, targetAbsPath) {
+    const seed = DEFAULT_SEED_BODIES.get(targetRelative);
+    if (seed === undefined)
+        return false;
+    try {
+        return readFileSync(targetAbsPath, 'utf8') === seed;
+    }
+    catch {
+        return false;
+    }
+}
+function migrateFile(codehereDir, sourcePath, targetRelative, symlinkRel, force, dryRun) {
+    const targetPath = join(codehereDir, targetRelative);
+    if (!existsSync(sourcePath) && !isSymlink(sourcePath))
+        return 'missing';
+    if (isSymlink(sourcePath))
+        return 'already-migrated';
+    // Target exists AND user has edited it AND not --force → skip.
+    // Target exists but is the default seed → safe to overwrite (placeholder).
+    if (existsSync(targetPath) && !force && !isDefaultSeed(targetRelative, targetPath)) {
+        return 'skipped';
+    }
+    // Dry-run: report what WOULD happen, touch nothing.
+    if (dryRun)
+        return 'migrated';
+    const body = readFileSync(sourcePath, 'utf8');
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, body);
+    rmSync(sourcePath);
+    if (symlinkRel !== null) {
+        symlinkSync(symlinkRel, sourcePath);
+    }
+    return 'migrated';
+}
+/**
+ * Migrate PROMPTS.md → skills/<slug>/SKILL.md per section.
+ * Returns outcome + count of skill folders created.
+ */
+function migratePrompts(codehereDir, force, noSymlinks, dryRun) {
+    const sourcePath = join(codehereDir, 'PROMPTS.md');
+    if (!existsSync(sourcePath) && !isSymlink(sourcePath)) {
+        return { outcome: 'missing', skillsCreated: 0, legacyFallback: false };
+    }
+    if (isSymlink(sourcePath)) {
+        return { outcome: 'already-migrated', skillsCreated: 0, legacyFallback: false };
+    }
+    const body = readFileSync(sourcePath, 'utf8');
+    const sections = parsePromptsSections(body);
+    // Fallback: if no ## sections, preserve the whole file as skills/_legacy.md.
+    if (sections.length === 0) {
+        const legacyTarget = join(codehereDir, 'skills/_legacy.md');
+        if (existsSync(legacyTarget) && !force) {
+            return { outcome: 'skipped', skillsCreated: 0, legacyFallback: true };
+        }
+        if (dryRun)
+            return { outcome: 'migrated', skillsCreated: 0, legacyFallback: true };
+        mkdirSync(dirname(legacyTarget), { recursive: true });
+        writeFileSync(legacyTarget, body);
+        rmSync(sourcePath);
+        if (!noSymlinks)
+            symlinkSync('skills/_legacy.md', sourcePath);
+        return { outcome: 'migrated', skillsCreated: 0, legacyFallback: true };
+    }
+    // Split path: write each section into skills/<slug>/SKILL.md.
+    // Conflict policy: if ANY target SKILL.md exists and not --force, abort the
+    // PROMPTS migration entirely (don't half-write). This preserves user state.
+    for (const s of sections) {
+        const target = join(codehereDir, 'skills', s.slug, 'SKILL.md');
+        if (existsSync(target) && !force) {
+            return { outcome: 'skipped', skillsCreated: 0, legacyFallback: false };
+        }
+    }
+    if (dryRun) {
+        return { outcome: 'migrated', skillsCreated: sections.length, legacyFallback: false };
+    }
+    let count = 0;
+    for (const s of sections) {
+        const target = join(codehereDir, 'skills', s.slug, 'SKILL.md');
+        mkdirSync(dirname(target), { recursive: true });
+        // Body is the raw section content. Don't re-add a `# Title` because the
+        // SKILL.md convention is to be focused-content; the slug folder itself
+        // names the skill.
+        writeFileSync(target, s.body);
+        count++;
+    }
+    rmSync(sourcePath);
+    if (!noSymlinks) {
+        // Symlink old path → skills/_index.md (the navigable entry point that
+        // codehere init already wrote, explaining where skills now live).
+        symlinkSync('skills/_index.md', sourcePath);
+    }
+    return { outcome: 'migrated', skillsCreated: count, legacyFallback: false };
+}
+function executeMemoryInit(options) {
+    const info_ = findCodebaseRoot();
+    const root = info_?.rootPath ?? process.cwd();
+    const codehereDir = join(root, '.codehere');
+    newline();
+    console.log(colors.bold('codehere memory init'));
+    console.log(colors.dim(`  migrating .codehere/ at ${root}`));
+    newline();
+    if (!existsSync(codehereDir)) {
+        console.log(`  ${error('refused')} .codehere/ not found at this root.`);
+        console.log(`  ${colors.dim('Run')} ${colors.cyan('codehere init')} ${colors.dim('first to scaffold the layout, then re-run.')}`);
+        newline();
+        process.exitCode = 1;
+        return;
+    }
+    const force = !!options.force;
+    const noSymlinks = !!options.noSymlinks;
+    const dryRun = !!options.dryRun;
+    if (dryRun) {
+        console.log(`  ${colors.dim('[--dry-run]')} no files will be touched · planned moves only`);
+        newline();
+    }
+    // ── CONTEXT.md → AGENTS.md ──────────────────────────────────────────────
+    const contextOutcome = migrateFile(codehereDir, join(codehereDir, 'CONTEXT.md'), 'AGENTS.md', noSymlinks ? null : 'AGENTS.md', force, dryRun);
+    // ── HANDOVER.md → memory/working/session.md ─────────────────────────────
+    const handoverOutcome = migrateFile(codehereDir, join(codehereDir, 'HANDOVER.md'), 'memory/working/session.md', noSymlinks ? null : 'memory/working/session.md', force, dryRun);
+    // ── PROMPTS.md → skills/<slug>/SKILL.md ─────────────────────────────────
+    const promptsResult = migratePrompts(codehereDir, force, noSymlinks, dryRun);
+    // ── F3 Task 3 — episodic AGENT_LEARNINGS.jsonl bridge ───────────────────
+    // Even v0.4.1 users who skipped re-running `codehere init` get the bridge
+    // wired so any future agent spawn can read their full session history.
+    // (--dry-run inhibits the actual symlink write but we still report it.)
+    const homePath = process.env.CODEHERE_HOME || homedir();
+    let episodicResult = null;
+    if (!dryRun) {
+        episodicResult = ensureEpisodicSymlink(codehereDir, homePath);
+    }
+    // ── report ──────────────────────────────────────────────────────────────
+    const report = (label, outcome, extra = '') => {
+        switch (outcome) {
+            case 'migrated':
+                console.log(`  ${success('migrated')} ${label}${extra ? '  ' + colors.dim(extra) : ''}`);
+                break;
+            case 'skipped':
+                console.log(`  ${warning('skipped ')} ${label}  ${colors.dim('(target already exists — use --force)')}`);
+                break;
+            case 'missing':
+                console.log(`  ${info('skipped ')} ${label}  ${colors.dim('(source not found)')}`);
+                break;
+            case 'already-migrated':
+                console.log(`  ${info('exists  ')} ${label}  ${colors.dim('(already migrated — symlink in place)')}`);
+                break;
+        }
+    };
+    report('CONTEXT.md → AGENTS.md', contextOutcome);
+    report('HANDOVER.md → memory/working/session.md', handoverOutcome);
+    // PROMPTS.md gets a richer report because of the split semantics.
+    if (promptsResult.outcome === 'migrated') {
+        if (promptsResult.legacyFallback) {
+            console.log(`  ${success('migrated')} PROMPTS.md → skills/_legacy.md  ${colors.dim('(no ^## sections found — preserved as-is for manual split)')}`);
+        }
+        else {
+            console.log(`  ${success('migrated')} PROMPTS.md → ${promptsResult.skillsCreated} skill folder${promptsResult.skillsCreated === 1 ? '' : 's'}  ${colors.dim('(skills/<slug>/SKILL.md per ^## section)')}`);
+        }
+    }
+    else {
+        report('PROMPTS.md → skills/', promptsResult.outcome);
+    }
+    // F3 Task 3 — episodic symlink result.
+    if (episodicResult) {
+        switch (episodicResult.result) {
+            case 'created':
+                console.log(`  ${success('linked  ')} memory/episodic/AGENT_LEARNINGS.jsonl → ${episodicResult.targetPath}`);
+                break;
+            case 're-linked':
+                console.log(`  ${success('re-linked')} memory/episodic/AGENT_LEARNINGS.jsonl → ${episodicResult.targetPath}`);
+                break;
+            case 'refused':
+                console.log(`  ${error('refused ')} memory/episodic/AGENT_LEARNINGS.jsonl  ${colors.dim('(real file or symlinked ancestor — remove first)')}`);
+                break;
+            case 'root-skipped':
+                console.log(`  ${warning('skipped ')} episodic symlink  ${colors.dim('(running as root — re-run as your normal user)')}`);
+                break;
+            case 'failed':
+                console.log(`  ${warning('skipped ')} episodic symlink  ${colors.dim('(HOME read-only?)')}`);
+                break;
+            // 'exists' is intentionally silent on memory init too.
+        }
+    }
+    // Idempotency hint when nothing was actually migrated.
+    const allOutcomes = [contextOutcome, handoverOutcome, promptsResult.outcome];
+    const anyMigrated = allOutcomes.some(o => o === 'migrated');
+    const allAlreadyOrMissing = allOutcomes.every(o => o === 'already-migrated' || o === 'missing');
+    if (!anyMigrated && allAlreadyOrMissing) {
+        newline();
+        console.log(`  ${info('no-op')} everything already migrated or no source files to migrate.`);
+    }
+    newline();
+    console.log(colors.bold('Next:'));
+    console.log(`  1. Open ${colors.cyan('.codehere/AGENTS.md')} — your project briefing (renamed from CONTEXT.md)`);
+    console.log(`  2. Edit ${colors.cyan('.codehere/memory/working/session.md')} as you work — supersedes HANDOVER.md`);
+    console.log(`  3. Each ${colors.cyan('.codehere/skills/<name>/SKILL.md')} is a task-shape template — copy and adapt`);
+    if (!noSymlinks && anyMigrated) {
+        console.log(`  ${colors.dim('(Old paths kept as symlinks for back-compat; safe to delete once teammates have pulled.)')}`);
+    }
+    newline();
+}
+/**
+ * F3 Task 4 — build the project's repo_map.json.
+ *
+ * Emits .codehere/memory/episodic/repo_map.json — a top-level symbol map
+ * (functions, classes, etc.) with reference counts, ranked. Spawned agents
+ * can read this once on entry instead of cold-grepping the codebase.
+ *
+ * v0.5 ships TS-native regex extraction (TS/JS/Python). v0.6 swaps in
+ * proper tree-sitter parsing. The schema is forward-compatible.
+ */
+function executeMemoryRepoMap(options) {
+    const codeInfo = findCodebaseRoot();
+    const root = codeInfo?.rootPath ?? process.cwd();
+    const codehereDir = join(root, '.codehere');
+    newline();
+    console.log(colors.bold('codehere memory repo-map'));
+    console.log(colors.dim(`  scanning ${root}`));
+    newline();
+    if (!existsSync(codehereDir)) {
+        console.log(`  ${error('refused')} .codehere/ not found at this root.`);
+        console.log(`  ${colors.dim('Run')} ${colors.cyan('codehere init')} ${colors.dim('first.')}`);
+        newline();
+        process.exitCode = 1;
+        return;
+    }
+    const result = writeRepoMap(root, codehereDir, { rebuild: !!options.rebuild });
+    switch (result.result) {
+        case 'written': {
+            const skipNote = result.skippedLargeFiles && result.skippedLargeFiles > 0
+                ? ` · ${result.skippedLargeFiles} file${result.skippedLargeFiles === 1 ? '' : 's'} skipped (>1MB)`
+                : '';
+            console.log(`  ${success('written ')} ${result.path}  ${colors.dim(`(${result.fileCount} files · ${result.symbolCount} symbols${skipNote})`)}`);
+            break;
+        }
+        case 'exists':
+            console.log(`  ${info('exists  ')} ${result.path}  ${colors.dim('(use --rebuild to overwrite)')}`);
+            break;
+        case 'failed':
+            console.log(`  ${error('failed  ')} ${result.path}  ${colors.dim(`(${result.error})`)}`);
+            process.exitCode = 1;
+            break;
+    }
+    newline();
+    console.log(colors.bold('Next:'));
+    console.log(`  - Spawned agents now read this file as part of project context`);
+    console.log(`  - Re-run ${colors.cyan('codehere memory repo-map --rebuild')} after large refactors`);
+    console.log(`  ${colors.dim('(v0.6 will refresh incrementally on file change via the per-file hash.)')}`);
+    newline();
+}
+export function executeMemoryCommand(action, options = {}) {
+    try {
+        switch (action) {
+            case 'init':
+                executeMemoryInit(options);
+                return;
+            case 'repo-map':
+                executeMemoryRepoMap(options);
+                return;
+            case 'show':
+                executeMemoryShow(options.layer);
+                return;
+            case 'graduate':
+                executeMemoryGraduate(options);
+                return;
+            case undefined:
+            case 'help':
+                console.log(`
+codehere memory <action> — F3 project memory operations
+
+  init           Migrate v0.4.1 CONTEXT/HANDOVER/PROMPTS into the F3 layout
+  repo-map       Build .codehere/memory/episodic/repo_map.json (symbol map)
+  show [layer]   Render any memory layer (working / episodic / semantic /
+                 personal / skills / protocols / injection)
+  graduate       Promote patterns into project-wide lessons:
+                   --add "<text>"      add free-text lesson directly
+                   --accept <id>       graduate a candidate
+                   --reject <id>       delete a candidate without graduating
+                   (no flag)           list any candidates pending review
+`);
+                return;
+            default:
+                console.error(`\n  ${error('failed')} unknown memory action: ${action}\n  Try: codehere memory help\n`);
+                process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`\n  ${error('failed')} codehere memory ${action ?? ''} — ${msg}\n`);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=memory-command.js.map