shift-ax 0.3.0

package/dist/core/diagnostics/doctor.js

@@ -0,0 +1,154 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseIndexDocument } from '../context/index-resolver.js';
+import { summarizeTopicStatus } from '../observability/topic-status.js';
+import { getProjectProfilePath, readProjectProfile } from '../policies/project-profile.js';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+function combineStatuses(statuses) {
+    if (statuses.includes('fail'))
+        return 'fail';
+    if (statuses.includes('warn'))
+        return 'warn';
+    return 'ok';
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function defaultCommandExists(command) {
+    try {
+        execFileSync('/bin/sh', ['-lc', `command -v ${shellQuote(command)} >/dev/null 2>&1`], {
+            stdio: 'pipe',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function checkGitRoot(rootDir) {
+    try {
+        const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: rootDir,
+            encoding: 'utf8',
+            stdio: 'pipe',
+        }).trim();
+        return {
+            status: 'ok',
+            message: 'Git repository is available.',
+            repo_root: repoRoot,
+        };
+    }
+    catch {
+        return {
+            status: 'fail',
+            message: 'Git repository root could not be resolved.',
+        };
+    }
+}
+async function checkBaseContext(rootDir) {
+    const home = getGlobalContextHome();
+    const indexPath = home.indexPath;
+    if (!existsSync(indexPath)) {
+        return {
+            status: 'fail',
+            message: 'Global Shift AX index is missing.',
+            index_path: indexPath,
+            entry_count: 0,
+            missing_paths: [],
+        };
+    }
+    const rawIndex = await readFile(indexPath, 'utf8');
+    const entries = parseIndexDocument(rawIndex);
+    const missingPaths = entries
+        .map((entry) => entry.path)
+        .filter((path) => !existsSync(resolve(home.root, path)));
+    return {
+        status: missingPaths.length > 0 ? 'fail' : 'ok',
+        message: missingPaths.length > 0
+            ? 'Global index includes unresolved or missing document paths.'
+            : 'Global index and linked documents are present.',
+        index_path: indexPath,
+        entry_count: entries.length,
+        missing_paths: missingPaths,
+    };
+}
+async function checkProfile(rootDir) {
+    const path = getProjectProfilePath(rootDir);
+    const profile = await readProjectProfile(rootDir);
+    return {
+        status: profile ? 'ok' : 'fail',
+        message: profile
+            ? 'Global Shift AX profile is available.'
+            : 'Global Shift AX profile is missing. Run `/onboarding` or `shift-ax onboard-context` first.',
+        path,
+    };
+}
+async function checkTopic(topicDir) {
+    if (!existsSync(topicDir)) {
+        return {
+            topic_dir: topicDir,
+            topic_slug: topicDir.split('/').pop() || 'unknown-topic',
+            phase: 'missing',
+            review_status: 'unknown',
+            execution_status: 'unknown',
+            status: 'fail',
+            message: 'Topic directory does not exist.',
+        };
+    }
+    const summary = await summarizeTopicStatus(topicDir);
+    const status = summary.phase === 'awaiting_policy_sync' ||
+        summary.review_status === 'changes_requested' ||
+        !!summary.last_failure_reason
+        ? 'warn'
+        : 'ok';
+    return {
+        ...summary,
+        topic_dir: topicDir,
+        status,
+        message: status === 'warn'
+            ? summary.last_failure_reason || 'Topic needs operator attention before it can continue.'
+            : 'Topic artifacts look healthy.',
+    };
+}
+function checkLaunchers({ platform, commandExists = defaultCommandExists, }) {
+    const checkedCommands = platform === 'codex' ? ['codex', 'tmux'] : ['claude', 'tmux'];
+    const missingCommands = checkedCommands.filter((command) => !commandExists(command));
+    return {
+        platform,
+        checked_commands: checkedCommands,
+        missing_commands: missingCommands,
+        status: missingCommands.length > 0 ? 'warn' : 'ok',
+        message: missingCommands.length > 0
+            ? `Missing launcher commands for ${platform}: ${missingCommands.join(', ')}`
+            : `Required launcher commands for ${platform} are available.`,
+    };
+}
+export async function runDoctor({ rootDir, topicDir, platform, commandExists, }) {
+    const git = checkGitRoot(rootDir);
+    const [baseContext, profile, topic] = await Promise.all([
+        checkBaseContext(rootDir),
+        checkProfile(rootDir),
+        topicDir ? checkTopic(topicDir) : Promise.resolve(undefined),
+    ]);
+    const launchers = platform
+        ? checkLaunchers({ platform, commandExists })
+        : undefined;
+    const overallStatus = combineStatuses([
+        git.status,
+        baseContext.status,
+        profile.status,
+        ...(topic ? [topic.status] : []),
+        ...(launchers ? [launchers.status] : []),
+    ]);
+    return {
+        root_dir: rootDir,
+        overall_status: overallStatus,
+        git,
+        base_context: baseContext,
+        profile,
+        ...(topic ? { topic } : {}),
+        ...(launchers ? { launchers } : {}),
+    };
+}

package/dist/core/finalization/commit-message.js

@@ -0,0 +1,76 @@
+const REQUIRED_TRAILERS = [
+    'Constraint:',
+    'Confidence:',
+    'Scope-risk:',
+    'Tested:',
+    'Not-tested:',
+];
+export function validateLoreCommitMessage(message) {
+    const issues = [];
+    const trimmed = String(message || '').trim();
+    const lines = trimmed.split(/\r?\n/).filter((line) => line.trim() !== '');
+    if (trimmed === '') {
+        issues.push('Commit message is empty.');
+    }
+    if (lines.length === 0 || lines[0].trim() === '') {
+        issues.push('Intent line is required.');
+    }
+    for (const trailer of REQUIRED_TRAILERS) {
+        if (!new RegExp(`^${trailer.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s+.+$`, 'm').test(trimmed)) {
+            issues.push(`Missing required lore trailer: ${trailer}`);
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}
+export function buildLoreCommitMessage({ intent, body, constraint, confidence, scopeRisk, directive, tested, notTested, rejected, related, reversibility, }) {
+    const lines = [intent.trim(), '', body.trim(), '', `Constraint: ${constraint}`];
+    if (rejected)
+        lines.push(`Rejected: ${rejected}`);
+    lines.push(`Confidence: ${confidence}`);
+    lines.push(`Scope-risk: ${scopeRisk}`);
+    if (reversibility)
+        lines.push(`Reversibility: ${reversibility}`);
+    if (directive)
+        lines.push(`Directive: ${directive}`);
+    lines.push(`Tested: ${tested}`);
+    lines.push(`Not-tested: ${notTested}`);
+    if (related)
+        lines.push(`Related: ${related}`);
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function normalizeOneLine(value) {
+    return String(value || '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+export function buildTopicLoreCommitMessage({ request, requestSummary, topicSlug, verificationCommands = [], }) {
+    const normalizedSummary = normalizeOneLine(requestSummary) || normalizeOneLine(request);
+    const normalizedRequest = normalizeOneLine(request) || normalizedSummary;
+    const intentSource = normalizedSummary || 'reviewed request update';
+    const tested = ['Shift AX review lanes', ...verificationCommands]
+        .map((command) => normalizeOneLine(command))
+        .filter(Boolean)
+        .join('; ');
+    return buildLoreCommitMessage({
+        intent: truncate(`Deliver reviewed change: ${intentSource}`, 72),
+        body: [
+            `This commit captures the reviewed Shift AX work for "${normalizedRequest || intentSource}".`,
+            'The request passed context resolution, human plan review, and review gates before local finalization.',
+        ].join(' '),
+        constraint: 'v1 finalization stops at a meaningful local git commit',
+        confidence: 'high',
+        scopeRisk: 'moderate',
+        directive: 'Re-run plan-review, escalation, and review gates before changing finalization semantics',
+        tested: tested || 'Shift AX review lanes',
+        notTested: 'GitHub push or PR automation beyond the v1 local-commit boundary',
+        ...(topicSlug ? { related: `topic:${topicSlug}` } : {}),
+    });
+}

package/dist/core/finalization/commit-workflow.js

@@ -0,0 +1,131 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildTopicLoreCommitMessage, validateLoreCommitMessage, } from './commit-message.js';
+import { readWorkflowState, writeWorkflowState, } from '../planning/workflow-state.js';
+import { getRootDirFromTopicDir, topicArtifactPath, } from '../topics/topic-artifacts.js';
+function runGit(cwd, args) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+async function resolveGitCwd(topicDir) {
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    try {
+        const raw = await readFile(topicArtifactPath(topicDir, 'worktree_state'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.worktree_path &&
+            ['created', 'reused'].includes(String(parsed.status || '')) &&
+            existsSync(parsed.worktree_path)) {
+            return parsed.worktree_path;
+        }
+    }
+    catch {
+        // ignore and fall back
+    }
+    return rootDir;
+}
+async function readAggregateReview(topicDir) {
+    const raw = await readFile(join(topicDir, 'review', 'aggregate.json'), 'utf8');
+    return JSON.parse(raw);
+}
+async function readCommitMessage(topicDir, message) {
+    if (message && message.trim() !== '') {
+        return message;
+    }
+    return readFile(topicArtifactPath(topicDir, 'commit_message'), 'utf8');
+}
+async function readTopicRequest(topicDir) {
+    const [request, requestSummary] = await Promise.all([
+        readFile(topicArtifactPath(topicDir, 'request'), 'utf8').catch(() => ''),
+        readFile(topicArtifactPath(topicDir, 'request_summary'), 'utf8').catch(() => ''),
+    ]);
+    try {
+        const workflow = await readWorkflowState(topicDir);
+        return {
+            request,
+            requestSummary,
+            topicSlug: workflow.topic_slug,
+            verification: workflow.verification ?? [],
+        };
+    }
+    catch {
+        return {
+            request,
+            requestSummary,
+            verification: [],
+        };
+    }
+}
+export async function ensureTopicCommitMessageArtifact({ topicDir, verification, }) {
+    const artifactPath = topicArtifactPath(topicDir, 'commit_message');
+    const existing = await readFile(artifactPath, 'utf8').catch(() => '');
+    if (validateLoreCommitMessage(existing).valid) {
+        return existing;
+    }
+    const topic = await readTopicRequest(topicDir);
+    const message = buildTopicLoreCommitMessage({
+        request: topic.request,
+        requestSummary: topic.requestSummary,
+        topicSlug: topic.topicSlug,
+        verificationCommands: (verification ?? topic.verification)
+            .filter((item) => item.exit_code === 0)
+            .map((item) => item.command),
+    });
+    await writeFile(artifactPath, message, 'utf8');
+    return message;
+}
+export async function finalizeTopicCommit({ topicDir, message, now = new Date(), }) {
+    const aggregate = await readAggregateReview(topicDir);
+    if (!aggregate.commit_allowed) {
+        throw new Error('aggregate review commit_allowed=false; commit cannot proceed');
+    }
+    const artifactPath = topicArtifactPath(topicDir, 'commit_message');
+    const commitMessage = message && message.trim() !== ''
+        ? message
+        : await ensureTopicCommitMessageArtifact({ topicDir });
+    const validation = validateLoreCommitMessage(commitMessage);
+    if (!validation.valid) {
+        throw new Error(validation.issues.join('\n'));
+    }
+    if (message && message.trim() !== '') {
+        await writeFile(artifactPath, `${commitMessage.trimEnd()}\n`, 'utf8');
+    }
+    else {
+        const storedMessage = await readCommitMessage(topicDir).catch(() => '');
+        if (storedMessage !== commitMessage) {
+            await writeFile(artifactPath, `${commitMessage.trimEnd()}\n`, 'utf8');
+        }
+    }
+    const gitCwd = await resolveGitCwd(topicDir);
+    const status = runGit(gitCwd, ['status', '--porcelain']);
+    if (status.trim() === '') {
+        throw new Error('No git changes are available to commit.');
+    }
+    runGit(gitCwd, ['add', '-A']);
+    runGit(gitCwd, ['commit', '-F', artifactPath]);
+    const commitSha = runGit(gitCwd, ['rev-parse', 'HEAD']);
+    const result = {
+        version: 1,
+        status: 'committed',
+        commit_sha: commitSha,
+        committed_at: now.toISOString(),
+        git_cwd: gitCwd,
+        message_path: artifactPath,
+        review_summary_path: join(topicDir, 'review', 'summary.md'),
+    };
+    await writeFile(topicArtifactPath(topicDir, 'commit_state'), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+    try {
+        const workflow = await readWorkflowState(topicDir);
+        workflow.phase = 'committed';
+        workflow.updated_at = now.toISOString();
+        await writeWorkflowState(topicDir, workflow);
+    }
+    catch {
+        // ignore missing workflow state in fixture tests
+    }
+    return result;
+}

package/dist/core/memory/consolidation.js

@@ -0,0 +1,99 @@
+import { listDecisionRecords } from './decision-register.js';
+import { listThreads } from './threads.js';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const GLOSSARY_STOPWORDS = new Set([
+    'about',
+    'above',
+    'after',
+    'always',
+    'below',
+    'carry',
+    'entry',
+    'issue',
+    'migration',
+    'needs',
+    'notes',
+    'shared',
+    'should',
+    'summary',
+    'thread',
+    'track',
+]);
+async function readMaybe(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function collectGlossaryTokens(content) {
+    const counts = new Map();
+    const relevantLines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .filter((line) => !line.startsWith('#'))
+        .filter((line) => !line.startsWith('- updated_at:'));
+    for (const line of relevantLines) {
+        const normalized = line.replace(/^-\s*\d{4}-\d{2}-\d{2}T[^:]+:\s*/, '');
+        for (const token of normalized.match(/\b[a-zA-Z][a-zA-Z-]{5,}\b/g) ?? []) {
+            const lower = token.toLowerCase();
+            if (GLOSSARY_STOPWORDS.has(lower))
+                continue;
+            counts.set(lower, (counts.get(lower) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()]
+        .sort((left, right) => {
+        const countDiff = right[1] - left[1];
+        if (countDiff !== 0)
+            return countDiff;
+        return left[0].localeCompare(right[0]);
+    })
+        .map(([token]) => token)
+        .slice(0, 10);
+}
+export async function consolidateMemory({ rootDir, }) {
+    const decisions = await listDecisionRecords({ rootDir });
+    const decisionCounts = new Map();
+    for (const decision of decisions) {
+        const key = decision.title.trim().toLowerCase();
+        decisionCounts.set(key, (decisionCounts.get(key) ?? 0) + 1);
+    }
+    const duplicateDecisions = [...decisionCounts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([title, count]) => ({ title, count }));
+    const topicsRoot = join(rootDir, '.ax', 'topics');
+    const topicEntries = await readdir(topicsRoot, { withFileTypes: true }).catch(() => []);
+    const summaryCounts = new Map();
+    for (const entry of topicEntries) {
+        if (!entry.isDirectory())
+            continue;
+        const summary = (await readMaybe(join(topicsRoot, entry.name, 'request-summary.md')))
+            .trim()
+            .toLowerCase();
+        if (!summary)
+            continue;
+        summaryCounts.set(summary, (summaryCounts.get(summary) ?? 0) + 1);
+    }
+    const repeatedTopics = [...summaryCounts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([summary, count]) => ({ summary, count }));
+    const threads = await listThreads({ rootDir });
+    const glossaryCandidates = new Set();
+    for (const thread of threads) {
+        const content = await readMaybe(thread.path);
+        for (const token of collectGlossaryTokens(content)) {
+            glossaryCandidates.add(token);
+            if (glossaryCandidates.size >= 10)
+                break;
+        }
+    }
+    return {
+        duplicate_decisions: duplicateDecisions,
+        repeated_topics: repeatedTopics,
+        glossary_candidates: [...glossaryCandidates].slice(0, 10),
+    };
+}

package/dist/core/memory/decision-register.js

@@ -0,0 +1,141 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function getDecisionRegisterPath(rootDir) {
+    return join(rootDir, '.ax', 'memory', 'decision-register.json');
+}
+async function readDecisionRegister(rootDir) {
+    try {
+        const raw = await readFile(getDecisionRegisterPath(rootDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+async function writeDecisionRegister(rootDir, records) {
+    const path = getDecisionRegisterPath(rootDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(records, null, 2)}\n`, 'utf8');
+}
+export async function recordDecision({ rootDir, title, summary, category, validFrom, sourceTopic, sourceDoc, now = new Date(), }) {
+    const records = await readDecisionRegister(rootDir);
+    const record = {
+        id: randomUUID(),
+        title,
+        summary,
+        category,
+        valid_from: validFrom,
+        status: 'active',
+        ...(sourceTopic ? { source_topic: sourceTopic } : {}),
+        ...(sourceDoc ? { source_doc: sourceDoc } : {}),
+        created_at: now.toISOString(),
+    };
+    records.push(record);
+    await writeDecisionRegister(rootDir, records);
+    return record;
+}
+export async function replaceDecision({ rootDir, replacedDecisionId, title, summary, category, validFrom, sourceTopic, sourceDoc, now = new Date(), }) {
+    const records = await readDecisionRegister(rootDir);
+    const replaced = records.find((record) => record.id === replacedDecisionId);
+    if (!replaced) {
+        throw new Error(`Decision not found: ${replacedDecisionId}`);
+    }
+    const replacement = {
+        id: randomUUID(),
+        title,
+        summary,
+        category,
+        valid_from: validFrom,
+        status: 'active',
+        ...(sourceTopic ? { source_topic: sourceTopic } : {}),
+        ...(sourceDoc ? { source_doc: sourceDoc } : {}),
+        created_at: now.toISOString(),
+    };
+    replaced.status = 'superseded';
+    replaced.valid_to = validFrom;
+    replaced.replaced_by = replacement.id;
+    records.push(replacement);
+    await writeDecisionRegister(rootDir, records);
+    return replacement;
+}
+function matchesActiveAt(record, activeAt) {
+    if (!activeAt)
+        return true;
+    if (record.valid_from > activeAt)
+        return false;
+    if (record.valid_to && record.valid_to <= activeAt)
+        return false;
+    return true;
+}
+function matchesQuery(record, query) {
+    if (!query)
+        return true;
+    const haystack = `${record.title}\n${record.summary}`.toLowerCase();
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3)
+        .every((token) => haystack.includes(token));
+}
+function tokenize(value) {
+    return String(value || '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+}
+function scoreDecision(query, content) {
+    const haystack = new Set(tokenize(content));
+    return tokenize(query).reduce((score, token) => score + (haystack.has(token) ? 1 : 0), 0);
+}
+export async function listDecisionRecords({ rootDir, activeAt, query, }) {
+    const records = await readDecisionRegister(rootDir);
+    return records
+        .filter((record) => matchesActiveAt(record, activeAt))
+        .filter((record) => matchesQuery(record, query));
+}
+export async function searchDecisionMemory({ rootDir, query, activeAt, limit = 5, }) {
+    const records = await listDecisionRecords({
+        rootDir,
+        activeAt,
+    });
+    const matches = [];
+    for (const record of records) {
+        const topicSummary = record.source_topic
+            ? await readFile(join(rootDir, '.ax', 'topics', record.source_topic, 'request-summary.md'), 'utf8').catch(() => '')
+            : '';
+        const topicRequest = record.source_topic
+            ? await readFile(join(rootDir, '.ax', 'topics', record.source_topic, 'request.md'), 'utf8').catch(() => '')
+            : '';
+        const topicSpec = record.source_topic
+            ? await readFile(join(rootDir, '.ax', 'topics', record.source_topic, 'spec.md'), 'utf8').catch(() => '')
+            : '';
+        const score = scoreDecision(query, [
+            record.title,
+            record.summary,
+            record.category,
+            record.source_doc ?? '',
+            record.source_topic ?? '',
+            topicSummary,
+            topicRequest,
+            topicSpec,
+        ].join('\n'));
+        if (score <= 0)
+            continue;
+        matches.push({
+            ...record,
+            score,
+            ...(topicSummary.trim() ? { source_topic_summary: topicSummary.trim() } : {}),
+        });
+    }
+    return matches
+        .sort((left, right) => {
+        const scoreDiff = right.score - left.score;
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        return String(right.valid_from).localeCompare(String(left.valid_from));
+    })
+        .slice(0, limit);
+}

package/dist/core/memory/entity-memory.js

@@ -0,0 +1,25 @@
+import { searchDecisionMemory } from './decision-register.js';
+import { listThreads } from './threads.js';
+import { searchPastTopics } from './topic-recall.js';
+import { readFile } from 'node:fs/promises';
+export async function buildEntityMemoryView({ rootDir, entity, }) {
+    const [decisions, threads, topics] = await Promise.all([
+        searchDecisionMemory({ rootDir, query: entity, limit: 5 }),
+        listThreads({ rootDir }),
+        searchPastTopics({ rootDir, query: entity, limit: 5 }),
+    ]);
+    const normalizedEntity = entity.toLowerCase();
+    const matchingThreads = (await Promise.all(threads.map(async (thread) => {
+        const content = await readFile(thread.path, 'utf8').catch(() => '');
+        if (!content.toLowerCase().includes(normalizedEntity)) {
+            return null;
+        }
+        return { name: thread.name, path: thread.path };
+    }))).filter((thread) => Boolean(thread));
+    return {
+        entity,
+        decisions,
+        threads: matchingThreads,
+        topics,
+    };
+}

package/dist/core/memory/learned-debug.js

@@ -0,0 +1,52 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function storePath(rootDir) {
+    return join(rootDir, '.ax', 'memory', 'learned-debug.json');
+}
+async function readStore(rootDir) {
+    try {
+        return JSON.parse(await readFile(storePath(rootDir), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+async function writeStore(rootDir, notes) {
+    const path = storePath(rootDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(notes, null, 2)}\n`, 'utf8');
+}
+function matchesQuery(note, query) {
+    if (!query)
+        return true;
+    const haystack = `${note.summary}\n${note.resolution}`.toLowerCase();
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3)
+        .every((token) => haystack.includes(token));
+}
+export async function recordLearnedDebugNote({ rootDir, summary, resolution, occurrences = 1, approved = false, fixCommit, now = new Date(), }) {
+    if (occurrences < 2 && !approved && !fixCommit) {
+        throw new Error('learned-debug notes require approval, repeated occurrences, or a fix commit');
+    }
+    const notes = await readStore(rootDir);
+    const note = {
+        id: randomUUID(),
+        summary,
+        resolution,
+        occurrences,
+        approved,
+        ...(fixCommit ? { fix_commit: fixCommit } : {}),
+        created_at: now.toISOString(),
+    };
+    notes.push(note);
+    await writeStore(rootDir, notes);
+    return note;
+}
+export async function listLearnedDebugNotes({ rootDir, query, }) {
+    const notes = await readStore(rootDir);
+    return notes.filter((note) => matchesQuery(note, query));
+}

package/dist/core/memory/summary-checkpoints.js

@@ -0,0 +1,9 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export async function writeTopicSummaryCheckpoint({ topicDir, summary, now = new Date(), }) {
+    const stamp = now.toISOString().replace(/[:.]/g, '-');
+    const outputPath = join(topicDir, 'checkpoints', `${stamp}-summary.md`);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, `# Context Checkpoint\n\n- recorded_at: ${now.toISOString()}\n\n## Summary\n\n${summary.trim()}\n`, 'utf8');
+    return { output_path: outputPath };
+}