gsd-pi 2.33.1-dev.29a8268 → 2.33.1-dev.9bafd68

package/dist/resources/extensions/gsd/mechanical-completion.js

@@ -0,0 +1,351 @@
+/**
+ * Mechanical Completion — deterministic post-verification artifact generation.
+ *
+ * Pure functions that aggregate task-level outputs into slice/milestone summaries,
+ * UAT stubs, roadmap checkbox updates, and validation reports. Zero orchestration
+ * dependencies — operates on filesystem paths and parsed structures only.
+ *
+ * ADR-003: replaces LLM-driven complete-slice and validate-milestone units with
+ * mechanical aggregation when the data is sufficient.
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { loadFile, parseSummary } from "./files.js";
+import { extractMarkdownSection } from "./auto-prompts.js";
+import { resolveTaskFiles, resolveTaskJsonFiles, resolveTasksDir, resolveSliceFile, resolveSlicePath, resolveMilestoneFile, resolveMilestonePath, resolveGsdRootFile, } from "./paths.js";
+// ─── Slice Completion ────────────────────────────────────────────────────────
+/**
+ * Mechanically complete a slice by aggregating task summaries into:
+ * - S##-SUMMARY.md (aggregated frontmatter + task one-liners)
+ * - S##-UAT.md (extracted from plan Verification section)
+ * - Roadmap checkbox [x] update
+ *
+ * Returns true if completion succeeded, false if data is insufficient
+ * (serves as quality gate — caller falls back to LLM completion).
+ */
+export async function mechanicalSliceCompletion(base, mid, sid) {
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (!tDir)
+        return false;
+    // Read all task summaries
+    const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+    if (summaryFiles.length === 0)
+        return false;
+    const taskSummaries = [];
+    for (const file of summaryFiles) {
+        const content = readFileSync(join(tDir, file), "utf-8");
+        if (!content.trim())
+            continue;
+        const summary = parseSummary(content);
+        const taskId = file.match(/^(T\d+)/)?.[1] ?? file;
+        taskSummaries.push({ taskId, summary });
+    }
+    if (taskSummaries.length === 0)
+        return false;
+    // Quality gate: multi-task slices need substantive summaries
+    if (taskSummaries.length > 1) {
+        const totalContent = taskSummaries
+            .map(ts => ts.summary.whatHappened || ts.summary.oneLiner || "")
+            .join("");
+        if (totalContent.length < 200)
+            return false;
+    }
+    // Aggregate frontmatter
+    const aggregated = aggregateFrontmatter(taskSummaries.map(ts => ts.summary.frontmatter));
+    // Build SUMMARY.md
+    const summaryLines = [
+        "---",
+        `id: ${sid}`,
+        `parent: ${mid}`,
+        `milestone: ${mid}`,
+    ];
+    if (aggregated.provides.length > 0)
+        summaryLines.push(`provides:\n${aggregated.provides.map(p => `  - ${p}`).join("\n")}`);
+    if (aggregated.key_files.length > 0)
+        summaryLines.push(`key_files:\n${aggregated.key_files.map(f => `  - ${f}`).join("\n")}`);
+    if (aggregated.key_decisions.length > 0)
+        summaryLines.push(`key_decisions:\n${aggregated.key_decisions.map(d => `  - ${d}`).join("\n")}`);
+    if (aggregated.patterns_established.length > 0)
+        summaryLines.push(`patterns_established:\n${aggregated.patterns_established.map(p => `  - ${p}`).join("\n")}`);
+    if (aggregated.affects.length > 0)
+        summaryLines.push(`affects:\n${aggregated.affects.map(a => `  - ${a}`).join("\n")}`);
+    if (aggregated.observability_surfaces.length > 0)
+        summaryLines.push(`observability_surfaces:\n${aggregated.observability_surfaces.map(o => `  - ${o}`).join("\n")}`);
+    const allPassed = taskSummaries.every(ts => ts.summary.frontmatter.verification_result === "passed");
+    summaryLines.push(`verification_result: ${allPassed ? "passed" : "mixed"}`);
+    summaryLines.push(`completed_at: ${new Date().toISOString()}`);
+    summaryLines.push("---");
+    summaryLines.push("");
+    summaryLines.push(`# ${sid}: Slice Summary`);
+    summaryLines.push("");
+    // Task one-liners
+    for (const { taskId, summary } of taskSummaries) {
+        const line = summary.oneLiner || summary.title || taskId;
+        summaryLines.push(`- **${taskId}**: ${line}`);
+    }
+    summaryLines.push("");
+    const sDir = resolveSlicePath(base, mid, sid);
+    if (!sDir)
+        return false;
+    const summaryPath = join(sDir, `${sid}-SUMMARY.md`);
+    atomicWriteSync(summaryPath, summaryLines.join("\n"));
+    process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+    // Build UAT.md from plan's Verification section
+    const planPath = resolveSliceFile(base, mid, sid, "PLAN");
+    if (planPath) {
+        const planContent = readFileSync(planPath, "utf-8");
+        const verification = extractMarkdownSection(planContent, "Verification");
+        if (verification) {
+            const uatContent = [
+                "---",
+                `id: ${sid}`,
+                `parent: ${mid}`,
+                "type: artifact-driven",
+                "---",
+                "",
+                `# ${sid}: UAT`,
+                "",
+                verification,
+                "",
+            ].join("\n");
+            const uatPath = join(sDir, `${sid}-UAT.md`);
+            atomicWriteSync(uatPath, uatContent);
+            process.stderr.write(`gsd-mechanical: wrote ${uatPath}\n`);
+        }
+    }
+    // Mark slice [x] in ROADMAP
+    await markSliceInRoadmap(base, mid, sid);
+    // Append new decisions if any
+    await appendNewDecisions(base, taskSummaries.map(ts => ts.summary));
+    // Update requirements if all passed
+    if (allPassed) {
+        await mechanicalRequirementsUpdate(base, mid, sid, taskSummaries.map(ts => ts.summary));
+    }
+    return true;
+}
+// ─── Requirements Update ─────────────────────────────────────────────────────
+/**
+ * Conservative requirements update: mark requirements Validated only if
+ * all tasks' verification passed.
+ */
+export async function mechanicalRequirementsUpdate(_base, _mid, _sid, _taskSummaries) {
+    // Conservative: requirements validation requires human or LLM judgment
+    // about whether the requirement is truly met. Mechanical completion only
+    // marks the slice done — requirement status updates are left to the
+    // existing validation pipeline.
+}
+// ─── Decision Aggregation ────────────────────────────────────────────────────
+/**
+ * Collect key_decisions from task summaries, deduplicate against existing
+ * DECISIONS.md, and append new ones.
+ */
+export async function appendNewDecisions(base, taskSummaries) {
+    const allDecisions = taskSummaries.flatMap(s => s.frontmatter.key_decisions);
+    if (allDecisions.length === 0)
+        return;
+    const decisionsPath = resolveGsdRootFile(base, "DECISIONS");
+    const existing = existsSync(decisionsPath)
+        ? readFileSync(decisionsPath, "utf-8")
+        : "";
+    // Deduplicate — skip decisions whose text already appears in the file
+    const newDecisions = allDecisions.filter(d => d.trim() && !existing.includes(d.trim()));
+    if (newDecisions.length === 0)
+        return;
+    const entries = newDecisions
+        .map(d => `- ${d} _(auto-aggregated from task summaries)_`)
+        .join("\n");
+    const updated = existing.trimEnd() + "\n\n### Auto-aggregated Decisions\n\n" + entries + "\n";
+    atomicWriteSync(decisionsPath, updated);
+    process.stderr.write(`gsd-mechanical: appended ${newDecisions.length} decision(s) to DECISIONS.md\n`);
+}
+/**
+ * Aggregate T##-VERIFY.json files and S##-UAT-RESULT.md files across all
+ * slices in a milestone to produce VALIDATION.md.
+ */
+export async function aggregateMilestoneVerification(base, mid) {
+    const mDir = resolveMilestonePath(base, mid);
+    if (!mDir)
+        return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+    const allChecks = [];
+    const allUatResults = [];
+    // Scan all slices
+    const slicesDir = join(mDir, "slices");
+    if (!existsSync(slicesDir))
+        return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+    const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+    for (const sliceName of sliceDirs) {
+        const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+        const tDir = resolveTasksDir(base, mid, sid);
+        if (tDir) {
+            const verifyFiles = resolveTaskJsonFiles(tDir, "VERIFY");
+            for (const vf of verifyFiles) {
+                try {
+                    const content = readFileSync(join(tDir, vf), "utf-8");
+                    const evidence = JSON.parse(content);
+                    allChecks.push(evidence);
+                }
+                catch {
+                    // Skip malformed JSON
+                }
+            }
+        }
+        // Check for UAT result
+        const uatResultPath = resolveSliceFile(base, mid, sid, "UAT-RESULT");
+        if (uatResultPath) {
+            try {
+                const uatContent = readFileSync(uatResultPath, "utf-8");
+                allUatResults.push(`### ${sid}\n\n${uatContent}`);
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+    }
+    // Determine verdict
+    const allPassed = allChecks.length > 0 && allChecks.every(c => c.passed);
+    const anyFailed = allChecks.some(c => !c.passed);
+    const verdict = allPassed
+        ? "passed"
+        : anyFailed
+            ? (allChecks.some(c => c.passed) ? "mixed" : "failed")
+            : "passed"; // No checks = vacuously passed
+    // Build VALIDATION.md
+    const mdLines = [
+        "---",
+        `milestone: ${mid}`,
+        `verdict: ${verdict}`,
+        "remediation_round: 0",
+        `validated_at: ${new Date().toISOString()}`,
+        "---",
+        "",
+        `# ${mid}: Milestone Validation`,
+        "",
+        `**Verdict:** ${verdict}`,
+        "",
+        "## Verification Results",
+        "",
+    ];
+    if (allChecks.length === 0) {
+        mdLines.push("_No verification evidence found._");
+    }
+    else {
+        mdLines.push("| Task | Passed | Checks | Failed |");
+        mdLines.push("|------|--------|--------|--------|");
+        for (const check of allChecks) {
+            const failedCount = check.checks.filter(c => c.verdict === "fail").length;
+            mdLines.push(`| ${check.taskId} | ${check.passed ? "yes" : "no"} | ${check.checks.length} | ${failedCount} |`);
+        }
+    }
+    if (allUatResults.length > 0) {
+        mdLines.push("");
+        mdLines.push("## UAT Results");
+        mdLines.push("");
+        mdLines.push(...allUatResults);
+    }
+    mdLines.push("");
+    const markdown = mdLines.join("\n");
+    // Write VALIDATION.md
+    const validationPath = join(mDir, `${mid}-VALIDATION.md`);
+    atomicWriteSync(validationPath, markdown);
+    process.stderr.write(`gsd-mechanical: wrote ${validationPath}\n`);
+    return { verdict, checks: allChecks, uatResults: allUatResults, markdown };
+}
+// ─── Milestone Summary ──────────────────────────────────────────────────────
+/**
+ * Read all S##-SUMMARY.md files and produce M##-SUMMARY.md.
+ */
+export async function generateMilestoneSummary(base, mid) {
+    const mDir = resolveMilestonePath(base, mid);
+    if (!mDir)
+        return "";
+    const slicesDir = join(mDir, "slices");
+    if (!existsSync(slicesDir))
+        return "";
+    const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+    const aggregatedProvides = [];
+    const aggregatedKeyFiles = [];
+    const aggregatedKeyDecisions = [];
+    const aggregatedPatterns = [];
+    const sliceOneLinerList = [];
+    for (const sliceName of sliceDirs) {
+        const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+        const summaryPath = resolveSliceFile(base, mid, sid, "SUMMARY");
+        if (!summaryPath)
+            continue;
+        try {
+            const content = readFileSync(summaryPath, "utf-8");
+            const summary = parseSummary(content);
+            aggregatedProvides.push(...summary.frontmatter.provides);
+            aggregatedKeyFiles.push(...summary.frontmatter.key_files);
+            aggregatedKeyDecisions.push(...summary.frontmatter.key_decisions);
+            aggregatedPatterns.push(...summary.frontmatter.patterns_established);
+            sliceOneLinerList.push(`- **${sid}**: ${summary.oneLiner || summary.title || sid}`);
+        }
+        catch {
+            sliceOneLinerList.push(`- **${sid}**: _(summary unavailable)_`);
+        }
+    }
+    const mdLines = [
+        "---",
+        `id: ${mid}`,
+    ];
+    if (dedup(aggregatedProvides).length > 0)
+        mdLines.push(`provides:\n${dedup(aggregatedProvides).map(p => `  - ${p}`).join("\n")}`);
+    if (dedup(aggregatedKeyFiles).length > 0)
+        mdLines.push(`key_files:\n${dedup(aggregatedKeyFiles).map(f => `  - ${f}`).join("\n")}`);
+    if (dedup(aggregatedKeyDecisions).length > 0)
+        mdLines.push(`key_decisions:\n${dedup(aggregatedKeyDecisions).map(d => `  - ${d}`).join("\n")}`);
+    if (dedup(aggregatedPatterns).length > 0)
+        mdLines.push(`patterns_established:\n${dedup(aggregatedPatterns).map(p => `  - ${p}`).join("\n")}`);
+    mdLines.push(`completed_at: ${new Date().toISOString()}`);
+    mdLines.push("---");
+    mdLines.push("");
+    mdLines.push(`# ${mid}: Milestone Summary`);
+    mdLines.push("");
+    mdLines.push("## Slices");
+    mdLines.push("");
+    mdLines.push(...sliceOneLinerList);
+    mdLines.push("");
+    const content = mdLines.join("\n");
+    // Write M##-SUMMARY.md
+    const summaryPath = join(mDir, `${mid}-SUMMARY.md`);
+    atomicWriteSync(summaryPath, content);
+    process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+    return content;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function aggregateFrontmatter(fms) {
+    return {
+        provides: dedup(fms.flatMap(f => f.provides)),
+        key_files: dedup(fms.flatMap(f => f.key_files)),
+        key_decisions: dedup(fms.flatMap(f => f.key_decisions)),
+        patterns_established: dedup(fms.flatMap(f => f.patterns_established)),
+        affects: dedup(fms.flatMap(f => f.affects)),
+        observability_surfaces: dedup(fms.flatMap(f => f.observability_surfaces)),
+    };
+}
+function dedup(arr) {
+    return [...new Set(arr.filter(s => s.trim()))];
+}
+async function markSliceInRoadmap(base, mid, sid) {
+    const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+    if (!roadmapPath)
+        return;
+    const content = await loadFile(roadmapPath);
+    if (!content)
+        return;
+    const updated = content.replace(new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"), `$1[x] **${sid}:`);
+    if (updated !== content) {
+        atomicWriteSync(roadmapPath, updated);
+        process.stderr.write(`gsd-mechanical: marked ${sid} done in ROADMAP\n`);
+    }
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/resources/extensions/gsd/memory-extractor.js

@@ -0,0 +1,295 @@
+// GSD Memory Extractor — Background LLM extraction from activity logs
+//
+// After each unit completes, extracts durable knowledge from the session
+// transcript and stores it as memory entries. One extraction at a time
+// (mutex guard). Fire-and-forget — never blocks auto-mode.
+import { readFileSync, statSync } from 'node:fs';
+import { getActiveMemories, isUnitProcessed, markUnitProcessed, applyMemoryActions, decayStaleMemories, } from './memory-store.js';
+// ─── Concurrency Guard ──────────────────────────────────────────────────────
+let _extracting = false;
+let _lastExtractionTime = 0;
+const MIN_EXTRACTION_INTERVAL_MS = 30_000;
+// ─── Skip Conditions ────────────────────────────────────────────────────────
+const SKIP_TYPES = new Set([
+    'complete-slice',
+    'rewrite-docs',
+    'triage-captures',
+]);
+const MIN_ACTIVITY_SIZE = 1024; // 1KB
+// ─── Secret Redaction ───────────────────────────────────────────────────────
+const SECRET_PATTERNS = [
+    /(?:sk|pk|api[_-]?key|token|secret|password|credential|auth)[_-]?\w*[\s:=]+['"]?[\w\-./+=]{20,}['"]?/gi,
+    /AKIA[0-9A-Z]{16}/g,
+    /gh[pousr]_[A-Za-z0-9_]{36,}/g,
+    /[rsp]k_(?:live|test)_[A-Za-z0-9]{20,}/g,
+    /eyJ[A-Za-z0-9_-]{20,}\.eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/g,
+    /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/g,
+    /(?:Bearer\s+)[A-Za-z0-9\-._~+/]+=*/gi,
+    /npm_[A-Za-z0-9]{36,}/g,
+    /sk-ant-[A-Za-z0-9\-_]{20,}/g,
+    /sk-[A-Za-z0-9]{40,}/g,
+];
+function redactSecrets(text) {
+    let result = text;
+    for (const pattern of SECRET_PATTERNS) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, '[REDACTED]');
+    }
+    return result;
+}
+// ─── Model Selection ────────────────────────────────────────────────────────
+/**
+ * Build an LLM call function using the cheapest available model (preferring Haiku).
+ * Returns null if no models available.
+ */
+export function buildMemoryLLMCall(ctx) {
+    try {
+        const available = ctx.modelRegistry.getAvailable();
+        if (!available || available.length === 0)
+            return null;
+        // Prefer Haiku by ID substring match
+        let model = available.find(m => m.id.toLowerCase().includes('haiku'));
+        // Fallback: cheapest by input cost
+        if (!model) {
+            model = [...available].sort((a, b) => a.cost.input - b.cost.input)[0];
+        }
+        if (!model)
+            return null;
+        const selectedModel = model;
+        return async (system, user) => {
+            const { completeSimple } = await import('@gsd/pi-ai');
+            const result = await completeSimple(selectedModel, {
+                systemPrompt: system,
+                messages: [{ role: 'user', content: [{ type: 'text', text: user }], timestamp: Date.now() }],
+            }, {
+                maxTokens: 2048,
+                temperature: 0,
+            });
+            // Extract text from response
+            const textParts = result.content
+                .filter((c) => c.type === 'text')
+                .map(c => c.text);
+            return textParts.join('');
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Extraction Prompts ─────────────────────────────────────────────────────
+const EXTRACTION_SYSTEM = `You are a memory extraction agent for a software project. Analyze the session
+transcript and identify durable knowledge worth remembering for future sessions.
+
+Categories: architecture, convention, gotcha, preference, environment, pattern
+
+Actions (return JSON array):
+- CREATE: {"action": "CREATE", "category": "<cat>", "content": "<text>", "confidence": <0.6-0.95>}
+- UPDATE: {"action": "UPDATE", "id": "<MEM###>", "content": "<revised text>"}
+- REINFORCE: {"action": "REINFORCE", "id": "<MEM###>"}
+- SUPERSEDE: {"action": "SUPERSEDE", "id": "<MEM###>", "superseded_by": "<MEM###>"}
+
+Rules:
+- Don't create memories for one-off bug fixes or temporary state
+- Don't duplicate existing memories — use REINFORCE or UPDATE
+- Keep content to 1-3 sentences
+- Confidence: 0.6 tentative, 0.8 solid, 0.95 well-confirmed
+- Prefer fewer high-quality memories over many low-quality ones
+- Return empty array [] if nothing worth remembering
+- NEVER include secrets, API keys, or passwords
+
+Return ONLY a valid JSON array.`;
+function buildExtractionUserPrompt(unitType, unitId, existingMemories, transcript) {
+    let memoriesSection;
+    if (existingMemories.length === 0) {
+        memoriesSection = '(none yet)';
+    }
+    else {
+        memoriesSection = existingMemories
+            .map((m, i) => `${i + 1}. [${m.id}] (${m.category}) ${m.content}`)
+            .join('\n');
+    }
+    return `## Current Active Memories\n${memoriesSection}\n\n## Session Transcript (${unitType}: ${unitId})\n${transcript}`;
+}
+// ─── Activity JSONL Parsing ─────────────────────────────────────────────────
+/**
+ * Extract assistant message text from activity JSONL.
+ * Returns concatenated text content from assistant role entries.
+ */
+function extractTranscriptFromActivity(raw, maxChars = 30_000) {
+    const lines = raw.split('\n');
+    const parts = [];
+    let totalChars = 0;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (entry.role !== 'assistant')
+                continue;
+            // Handle content array or direct text
+            if (Array.isArray(entry.content)) {
+                for (const block of entry.content) {
+                    if (block.type === 'text' && block.text) {
+                        const text = block.text;
+                        if (totalChars + text.length > maxChars) {
+                            parts.push(text.substring(0, maxChars - totalChars));
+                            return parts.join('\n\n');
+                        }
+                        parts.push(text);
+                        totalChars += text.length;
+                    }
+                }
+            }
+            else if (typeof entry.content === 'string') {
+                const text = entry.content;
+                if (totalChars + text.length > maxChars) {
+                    parts.push(text.substring(0, maxChars - totalChars));
+                    return parts.join('\n\n');
+                }
+                parts.push(text);
+                totalChars += text.length;
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return parts.join('\n\n');
+}
+// ─── Response Parsing ───────────────────────────────────────────────────────
+/**
+ * Parse the LLM response into memory actions.
+ * Strips markdown fences, validates required fields.
+ * Returns [] on any parse failure.
+ */
+export function parseMemoryResponse(raw) {
+    try {
+        // Strip markdown code fences
+        let cleaned = raw.trim();
+        if (cleaned.startsWith('```')) {
+            cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, '');
+        }
+        const parsed = JSON.parse(cleaned);
+        if (!Array.isArray(parsed))
+            return [];
+        const actions = [];
+        for (const item of parsed) {
+            if (!item || typeof item !== 'object' || !item.action)
+                continue;
+            switch (item.action) {
+                case 'CREATE':
+                    if (typeof item.category === 'string' && typeof item.content === 'string') {
+                        actions.push({
+                            action: 'CREATE',
+                            category: item.category,
+                            content: item.content,
+                            confidence: typeof item.confidence === 'number' ? item.confidence : undefined,
+                        });
+                    }
+                    break;
+                case 'UPDATE':
+                    if (typeof item.id === 'string' && typeof item.content === 'string') {
+                        actions.push({
+                            action: 'UPDATE',
+                            id: item.id,
+                            content: item.content,
+                            confidence: typeof item.confidence === 'number' ? item.confidence : undefined,
+                        });
+                    }
+                    break;
+                case 'REINFORCE':
+                    if (typeof item.id === 'string') {
+                        actions.push({ action: 'REINFORCE', id: item.id });
+                    }
+                    break;
+                case 'SUPERSEDE':
+                    if (typeof item.id === 'string' && typeof item.superseded_by === 'string') {
+                        actions.push({
+                            action: 'SUPERSEDE',
+                            id: item.id,
+                            superseded_by: item.superseded_by,
+                        });
+                    }
+                    break;
+            }
+        }
+        return actions;
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Main Extraction Function ───────────────────────────────────────────────
+/**
+ * Extract memories from a completed unit's activity log.
+ * Fire-and-forget — never throws, mutex-guarded, respects rate limiting.
+ */
+export async function extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn) {
+    // Mutex guard
+    if (_extracting)
+        return;
+    // Rate limit
+    const now = Date.now();
+    if (now - _lastExtractionTime < MIN_EXTRACTION_INTERVAL_MS)
+        return;
+    // Skip certain unit types
+    if (SKIP_TYPES.has(unitType))
+        return;
+    const unitKey = `${unitType}/${unitId}`;
+    // Already processed
+    if (isUnitProcessed(unitKey))
+        return;
+    // Check file size
+    try {
+        const stat = statSync(activityFile);
+        if (stat.size < MIN_ACTIVITY_SIZE)
+            return;
+    }
+    catch {
+        return;
+    }
+    _extracting = true;
+    _lastExtractionTime = now;
+    try {
+        // Read and parse activity file
+        const raw = readFileSync(activityFile, 'utf-8');
+        const transcript = extractTranscriptFromActivity(raw);
+        if (!transcript.trim())
+            return;
+        // Redact secrets
+        const safeTranscript = redactSecrets(transcript);
+        // Get current memories for context
+        const activeMemories = getActiveMemories().map(m => ({
+            id: m.id,
+            category: m.category,
+            content: m.content,
+        }));
+        // Build prompts
+        const userPrompt = buildExtractionUserPrompt(unitType, unitId, activeMemories, safeTranscript);
+        // Call LLM
+        const response = await llmCallFn(EXTRACTION_SYSTEM, userPrompt);
+        // Parse response
+        const actions = parseMemoryResponse(response);
+        // Apply actions
+        if (actions.length > 0) {
+            applyMemoryActions(actions, unitType, unitId);
+        }
+        // Decay stale memories periodically
+        decayStaleMemories(20);
+        // Mark unit as processed
+        markUnitProcessed(unitKey, activityFile);
+    }
+    catch {
+        // Non-fatal — memory extraction failure should never affect auto-mode
+    }
+    finally {
+        _extracting = false;
+    }
+}
+// ─── Testing Helpers ────────────────────────────────────────────────────────
+/** Reset extraction state (testing only). */
+export function _resetExtractionState() {
+    _extracting = false;
+    _lastExtractionTime = 0;
+}