shift-ax 0.3.0

package/dist/core/memory/thread-promotion.js

@@ -0,0 +1,22 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { bootstrapTopic } from '../topics/bootstrap.js';
+import { findThread } from './threads.js';
+export async function promoteThreadToTopic({ rootDir, name, request, }) {
+    const threadSummary = await findThread({ rootDir, name });
+    if (!threadSummary) {
+        throw new Error(`Thread not found: ${name}`);
+    }
+    const thread = await readFile(threadSummary.path, 'utf8');
+    const topic = await bootstrapTopic({
+        rootDir,
+        request,
+    });
+    const supportPath = join(topic.topicDir, 'support-thread.md');
+    await writeFile(supportPath, `# Imported Support Thread\n\n- source_thread: ${threadSummary.name}\n- source_slug: ${threadSummary.slug}\n\n${thread.trim()}\n`, 'utf8');
+    return {
+        topicDir: topic.topicDir,
+        topicSlug: topic.topicSlug,
+        supportPath,
+    };
+}

package/dist/core/memory/threads.js

@@ -0,0 +1,66 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export function slugifyThreadName(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') || 'thread';
+}
+export function threadPath(rootDir, name) {
+    return join(rootDir, '.ax', 'threads', `${slugifyThreadName(name)}.md`);
+}
+export async function saveThreadNote({ rootDir, name, summary, note, now = new Date(), }) {
+    const path = threadPath(rootDir, name);
+    const existing = await readFile(path, 'utf8').catch(() => '');
+    const lines = existing.trim().length > 0
+        ? existing
+            .replace(/- updated_at:\s*.+$/m, `- updated_at: ${now.toISOString()}`)
+            .trimEnd()
+            .concat(`\n\n- ${now.toISOString()}: ${note.trim()}`)
+        : [
+            `# Thread: ${name}`,
+            '',
+            `- updated_at: ${now.toISOString()}`,
+            '',
+            '## Summary',
+            '',
+            (summary || `Thread for ${name}`).trim(),
+            '',
+            '## Notes',
+            '',
+            `- ${now.toISOString()}: ${note.trim()}`,
+        ].join('\n');
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${lines}\n`, 'utf8');
+    return { path };
+}
+export async function listThreads({ rootDir, }) {
+    const dir = join(rootDir, '.ax', 'threads');
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const result = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const path = join(dir, entry.name);
+        const content = await readFile(path, 'utf8').catch(() => '');
+        const updatedAt = content.match(/- updated_at:\s*(.+)\s*$/m)?.[1]?.trim() ||
+            content.match(/- (\d{4}-\d{2}-\d{2}T[^:]+:[^\n]+)/)?.[1]?.trim() ||
+            '';
+        result.push({
+            name: content.match(/^# Thread:\s*(.+)\s*$/m)?.[1]?.trim() || entry.name.replace(/\.md$/, ''),
+            slug: entry.name.replace(/\.md$/, ''),
+            path,
+            updated_at: updatedAt,
+        });
+    }
+    return result.sort((left, right) => right.updated_at.localeCompare(left.updated_at));
+}
+export async function findThread({ rootDir, name, }) {
+    const slug = slugifyThreadName(name);
+    const threads = await listThreads({ rootDir });
+    return (threads.find((thread) => thread.slug === slug) ??
+        threads.find((thread) => thread.name.toLowerCase() === name.toLowerCase()) ??
+        null);
+}

package/dist/core/memory/topic-recall.js

@@ -0,0 +1,52 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+function tokenize(value) {
+    return String(value || '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+}
+function scoreTopic(query, content) {
+    const haystack = new Set(tokenize(content));
+    return tokenize(query).reduce((score, token) => score + (haystack.has(token) ? 1 : 0), 0);
+}
+export async function searchPastTopics({ rootDir, query, limit = 5, }) {
+    const topicsRoot = join(rootDir, '.ax', 'topics');
+    const topicEntries = await readdir(topicsRoot, { withFileTypes: true }).catch(() => []);
+    const matches = [];
+    for (const entry of topicEntries) {
+        if (!entry.isDirectory())
+            continue;
+        const topicDir = join(topicsRoot, entry.name);
+        const [request, summary, spec, workflowRaw] = await Promise.all([
+            readFile(join(topicDir, 'request.md'), 'utf8').catch(() => ''),
+            readFile(join(topicDir, 'request-summary.md'), 'utf8').catch(() => ''),
+            readFile(join(topicDir, 'spec.md'), 'utf8').catch(() => ''),
+            readFile(join(topicDir, 'workflow-state.json'), 'utf8').catch(() => ''),
+        ]);
+        if (!workflowRaw)
+            continue;
+        const workflow = JSON.parse(workflowRaw);
+        if (workflow.phase !== 'committed')
+            continue;
+        const score = scoreTopic(query, [request, summary, spec].join('\n'));
+        if (score <= 0)
+            continue;
+        matches.push({
+            topic_slug: entry.name,
+            summary: summary.trim(),
+            request: request.trim(),
+            score,
+            updated_at: workflow.updated_at,
+        });
+    }
+    return matches
+        .sort((a, b) => {
+        const scoreDiff = b.score - a.score;
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        return String(b.updated_at ?? '').localeCompare(String(a.updated_at ?? ''));
+    })
+        .slice(0, limit);
+}

package/dist/core/observability/context-health.js

@@ -0,0 +1,15 @@
+import { buildContextBundle, classifyContextBundle, } from '../context/context-bundle.js';
+export async function assessContextHealth({ rootDir, topicDir, query, maxChars = 6000, }) {
+    const bundle = await buildContextBundle({
+        ...(rootDir ? { rootDir } : {}),
+        ...(topicDir ? { topicDir } : {}),
+        query,
+        maxChars,
+    });
+    const classification = classifyContextBundle(bundle);
+    return {
+        status: classification.status,
+        recommendation: classification.recommendation,
+        bundle,
+    };
+}

package/dist/core/observability/context-monitor.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { assessContextHealth } from './context-health.js';
+import { getRootDirFromTopicDir } from '../topics/topic-artifacts.js';
+export async function writeContextMonitorSnapshot({ rootDir, topicDir, query, maxChars = 6000, outputPath, }) {
+    const report = await assessContextHealth({
+        ...(rootDir ? { rootDir } : {}),
+        ...(topicDir ? { topicDir } : {}),
+        query,
+        maxChars,
+    });
+    const effectiveRoot = rootDir || (topicDir ? getRootDirFromTopicDir(topicDir) : '');
+    const targetPath = outputPath || join(effectiveRoot, '.ax', 'context-monitor.json');
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, `${JSON.stringify({
+        status: report.status,
+        should_pause: report.status === 'critical',
+        recommendation: report.recommendation,
+        query,
+        max_chars: report.bundle.max_chars,
+        total_source_chars: report.bundle.total_source_chars,
+        truncated: report.bundle.truncated,
+        issues: report.bundle.issues,
+    }, null, 2)}\n`, 'utf8');
+    return {
+        output_path: targetPath,
+        status: report.status,
+    };
+}

package/dist/core/observability/state-handoff.js

@@ -0,0 +1,78 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { listTopicsStatus } from './topics-status.js';
+import { summarizeTopicStatus } from './topic-status.js';
+import { getRootDirFromTopicDir, topicArtifactPath } from '../topics/topic-artifacts.js';
+export async function writeRootStateSummary({ rootDir, limit = 10, }) {
+    const topics = await listTopicsStatus({ rootDir, limit });
+    const lines = [
+        '# Shift AX State',
+        '',
+        '## Active Topics',
+        '',
+    ];
+    if (topics.length === 0) {
+        lines.push('- No tracked topics yet.');
+    }
+    else {
+        for (const topic of topics) {
+            lines.push(`- ${topic.topic_slug}`);
+            lines.push(`  - phase: ${topic.phase}`);
+            lines.push(`  - review: ${topic.review_status}`);
+            lines.push(`  - execution: ${topic.execution_status}`);
+            if (topic.last_failure_reason) {
+                lines.push(`  - latest issue: ${topic.last_failure_reason}`);
+            }
+        }
+    }
+    const outputPath = join(rootDir, '.ax', 'STATE.md');
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, `${lines.join('\n')}\n`, 'utf8');
+    return { output_path: outputPath };
+}
+export async function writeTopicHandoff({ topicDir, summary, nextStep, commands = [], }) {
+    const status = await summarizeTopicStatus(topicDir);
+    const lines = [
+        '# Topic Handoff',
+        '',
+        `- topic: ${status.topic_slug}`,
+        `- phase: ${status.phase}`,
+        `- review: ${status.review_status}`,
+        `- execution: ${status.execution_status}`,
+        '',
+        '## Summary',
+        '',
+        summary.trim(),
+        '',
+    ];
+    if (nextStep?.trim()) {
+        lines.push('## Next Step', '', nextStep.trim(), '');
+    }
+    if (commands.length > 0) {
+        lines.push('## Suggested Commands', '');
+        for (const command of commands) {
+            lines.push(`- \`${command}\``);
+        }
+        lines.push('');
+    }
+    if (status.last_failure_reason) {
+        lines.push('## Latest Failure Reason', '', status.last_failure_reason, '');
+    }
+    const outputPath = topicArtifactPath(topicDir, 'handoff');
+    await writeFile(outputPath, `${lines.join('\n')}\n`, 'utf8');
+    return { output_path: outputPath };
+}
+export async function pauseTopicWork({ topicDir, summary, nextStep, commands = [], }) {
+    const handoff = await writeTopicHandoff({
+        topicDir,
+        summary,
+        nextStep,
+        commands,
+    });
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    const state = await writeRootStateSummary({ rootDir });
+    return {
+        handoff_path: handoff.output_path,
+        state_path: state.output_path,
+    };
+}

package/dist/core/observability/topic-status.js

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+async function readJson(path, fallback) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function summarizeTopicStatus(topicDir) {
+    const [workflow, executionState, aggregate, policyContextSync, lifecycle, reactions] = await Promise.all([
+        readJson(join(topicDir, 'workflow-state.json'), {}),
+        readJson(join(topicDir, 'execution-state.json'), {}),
+        readJson(join(topicDir, 'review', 'aggregate.json'), {}),
+        readJson(join(topicDir, 'policy-context-sync.json'), {}),
+        readJson(join(topicDir, 'lifecycle-log.json'), []),
+        readJson(join(topicDir, 'reaction-log.json'), []),
+    ]);
+    const lastEvent = lifecycle.length > 0 ? lifecycle[lifecycle.length - 1] : undefined;
+    const lastReaction = reactions.length > 0 ? reactions[reactions.length - 1] : undefined;
+    return {
+        topic_slug: workflow.topic_slug ?? topicDir.split('/').pop() ?? 'unknown-topic',
+        phase: workflow.phase ?? 'unknown',
+        review_status: workflow.review?.overall_status ?? aggregate.overall_status ?? 'unknown',
+        execution_status: executionState.overall_status ?? 'unknown',
+        ...(policyContextSync.status ? { policy_context_status: policyContextSync.status } : {}),
+        ...(lastEvent ? { last_event: lastEvent } : {}),
+        ...(lastReaction ? { last_reaction: lastReaction } : {}),
+        ...(policyContextSync.status === 'required'
+            ? { last_failure_reason: 'policy context sync is required before implementation can start' }
+            : {}),
+        ...(lastEvent && /fail|blocked|changes|requested/i.test(lastEvent.summary)
+            ? { last_failure_reason: lastEvent.summary }
+            : lastReaction?.outcome && lastReaction.outcome !== 'approved'
+                ? { last_failure_reason: `${lastReaction.key}: ${lastReaction.outcome}` }
+                : {}),
+    };
+}

package/dist/core/observability/topics-status.js

@@ -0,0 +1,26 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { summarizeTopicStatus } from './topic-status.js';
+export async function listTopicsStatus({ rootDir, limit = 10, }) {
+    const topicsRoot = join(rootDir, '.ax', 'topics');
+    const entries = await readdir(topicsRoot, { withFileTypes: true }).catch(() => []);
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const topicDir = join(topicsRoot, entry.name);
+        const workflowRaw = await readFile(join(topicDir, 'workflow-state.json'), 'utf8').catch(() => '');
+        if (!workflowRaw)
+            continue;
+        const workflow = JSON.parse(workflowRaw);
+        const summary = await summarizeTopicStatus(topicDir);
+        results.push({
+            ...summary,
+            topic_dir: topicDir,
+            updated_at: workflow.updated_at ?? '',
+        });
+    }
+    return results
+        .sort((left, right) => String(right.updated_at).localeCompare(String(left.updated_at)))
+        .slice(0, limit);
+}

package/dist/core/observability/verification-debt.js

@@ -0,0 +1,82 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+async function readMaybe(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function readTopicDebt(topicDir) {
+    const workflowRaw = await readMaybe(join(topicDir, 'workflow-state.json'));
+    if (!workflowRaw)
+        return [];
+    const workflow = JSON.parse(workflowRaw);
+    const topicSlug = workflow.topic_slug || topicDir.split('/').pop() || 'unknown-topic';
+    const debt = [];
+    if ((workflow.verification ?? []).length === 0) {
+        debt.push({
+            topic_slug: topicSlug,
+            kind: 'verification_command',
+            message: 'Verification was skipped or not recorded.',
+        });
+    }
+    for (const item of workflow.verification ?? []) {
+        if ((item.exit_code ?? 0) !== 0) {
+            debt.push({
+                topic_slug: topicSlug,
+                kind: 'verification_command',
+                message: `Verification command failed: ${item.command ?? 'unknown command'}`,
+            });
+        }
+    }
+    const reviewDir = join(topicDir, 'review');
+    const reviewFiles = await readdir(reviewDir).catch(() => []);
+    for (const file of reviewFiles) {
+        if (!file.endsWith('.json') || file === 'aggregate.json')
+            continue;
+        const raw = await readMaybe(join(reviewDir, file));
+        if (!raw)
+            continue;
+        const parsed = JSON.parse(raw);
+        if (parsed.status === 'approved')
+            continue;
+        if ((parsed.issues ?? []).length > 0) {
+            for (const issue of parsed.issues ?? []) {
+                debt.push({
+                    topic_slug: topicSlug,
+                    kind: 'review_issue',
+                    message: `${parsed.lane ?? 'review'}: ${issue.message ?? parsed.summary ?? 'review issue'}`,
+                });
+            }
+        }
+        else if (parsed.summary) {
+            debt.push({
+                topic_slug: topicSlug,
+                kind: 'review_issue',
+                message: `${parsed.lane ?? 'review'}: ${parsed.summary}`,
+            });
+        }
+        for (const item of parsed.deferred_items ?? []) {
+            debt.push({
+                topic_slug: topicSlug,
+                kind: 'review_issue',
+                message: `${parsed.lane ?? 'review'} deferred verification: ${item}`,
+            });
+        }
+    }
+    return debt;
+}
+export async function listVerificationDebt({ rootDir, topicDir, }) {
+    if (topicDir) {
+        return readTopicDebt(topicDir);
+    }
+    if (!rootDir) {
+        throw new Error('rootDir or topicDir is required');
+    }
+    const topicsRoot = join(rootDir, '.ax', 'topics');
+    const entries = await readdir(topicsRoot, { withFileTypes: true }).catch(() => []);
+    const all = await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => readTopicDebt(join(topicsRoot, entry.name))));
+    return all.flat();
+}

package/dist/core/planning/brainstorm.js

@@ -0,0 +1,120 @@
+function bulletize(value) {
+    return String(value || '')
+        .split(/\r?\n|;/)
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => (item.startsWith('-') ? item : `- ${item}`));
+}
+function sentenceOrFallback(value, fallback) {
+    const trimmed = String(value || '').trim();
+    return trimmed === '' ? fallback : trimmed;
+}
+export function buildPlanningArtifactsFromInterview({ request, matchedContextLabels, answers, engineeringDefaults, }) {
+    const relevantContext = matchedContextLabels.length > 0
+        ? matchedContextLabels.map((label) => `- ${label}`)
+        : ['- No matched context documents yet.'];
+    const constraints = bulletize(answers.constraints);
+    const outOfScope = bulletize(answers.outOfScope);
+    const verification = bulletize(answers.verification);
+    const implementationAreas = bulletize(answers.implementationAreas);
+    const longRunningWork = bulletize(answers.longRunningWork);
+    const policyUpdates = bulletize(answers.policyUpdates);
+    const brainstormContent = [
+        '# Brainstorm',
+        '',
+        '## Request',
+        '',
+        request.trim(),
+        '',
+        '## Relevant Context',
+        '',
+        ...relevantContext,
+        '',
+        '## Clarified Outcome',
+        '',
+        ...bulletize(answers.outcome),
+        '',
+        '## Constraints',
+        '',
+        ...constraints,
+        '',
+        '## Out of Scope',
+        '',
+        ...outOfScope,
+        '',
+        '## Verification Expectations',
+        '',
+        ...verification,
+        '',
+        '## Global Knowledge Updates',
+        '',
+        ...(policyUpdates.length > 0 ? policyUpdates : ['- None yet.']),
+        '',
+        '## Implementation Areas',
+        '',
+        ...implementationAreas,
+        '',
+        '## Long-running Work',
+        '',
+        ...longRunningWork,
+        '',
+    ].join('\n');
+    const specContent = [
+        '# Topic Spec',
+        '',
+        '## Goal',
+        '',
+        sentenceOrFallback(answers.outcome, request.trim()),
+        '',
+        '## Relevant Context',
+        '',
+        ...relevantContext,
+        '',
+        '## Constraints',
+        '',
+        ...constraints,
+        '',
+        '## Out of Scope',
+        '',
+        ...outOfScope,
+        '',
+        '## Verification Expectations',
+        '',
+        ...verification,
+        '',
+        '## Global Knowledge Updates',
+        '',
+        ...(policyUpdates.length > 0 ? policyUpdates : ['- None yet.']),
+        '',
+    ].join('\n');
+    const implementationPlanContent = [
+        '# Implementation Plan',
+        '',
+        '## Delivery Tasks',
+        '',
+        `1. Add or update tests first using ${engineeringDefaults.test_strategy.toUpperCase()} for: ${sentenceOrFallback(answers.verification, 'the clarified outcome')}`,
+        `2. Implement ${sentenceOrFallback(answers.outcome, request.trim())} inside: ${sentenceOrFallback(answers.implementationAreas, 'the affected service boundary')}.`,
+        `3. Respect ${engineeringDefaults.architecture.replace(/-/g, ' ')} and keep these constraints visible: ${sentenceOrFallback(answers.constraints, 'No extra constraints recorded.')}`,
+        `4. Keep these items out of scope: ${sentenceOrFallback(answers.outOfScope, 'No out-of-scope items recorded.')}`,
+        `5. Capture verification evidence for: ${sentenceOrFallback(answers.verification, 'the agreed happy path and regressions')}`,
+        '',
+        '## Execution Routing',
+        '',
+        `- Short slices should use ${engineeringDefaults.short_task_execution}.`,
+        `- Long-running or cross-cutting work should use ${engineeringDefaults.long_task_execution}.`,
+        ...longRunningWork.map((item) => `${item} -> ${engineeringDefaults.long_task_execution}`),
+        ...implementationAreas
+            .filter((item) => !longRunningWork.some((longItem) => longItem.includes(item.replace(/^-\s*/, ''))))
+            .map((item) => `${item} -> ${engineeringDefaults.short_task_execution}`),
+        '',
+        '## Global Knowledge Updates',
+        '',
+        ...(policyUpdates.length > 0 ? policyUpdates : ['- None yet.']),
+        '',
+    ].join('\n');
+    return {
+        brainstormContent: `${brainstormContent.trimEnd()}\n`,
+        specContent: `${specContent.trimEnd()}\n`,
+        implementationPlanContent: `${implementationPlanContent.trimEnd()}\n`,
+    };
+}

package/dist/core/planning/escalation.js

@@ -0,0 +1,69 @@
+import { SHIFT_AX_ESCALATION_KINDS, readWorkflowState, writeWorkflowState, } from './workflow-state.js';
+export function defaultEscalationSummary(kind) {
+    switch (kind) {
+        case 'new-user-flow':
+            return 'Implementation requires a new user flow that is not in the reviewed plan.';
+        case 'policy-conflict':
+            return 'A domain or policy document conflicts with the implementation approach.';
+        case 'risky-data-or-permission-change':
+            return 'A risky data or permission change needs human review before continuing.';
+    }
+}
+export function parseEscalationArgument(raw) {
+    const [kindPart, ...summaryParts] = String(raw || '').split(':');
+    const kind = kindPart?.trim();
+    if (!kind || !SHIFT_AX_ESCALATION_KINDS.includes(kind)) {
+        throw new Error(`Invalid escalation trigger "${raw}". Expected one of: ${SHIFT_AX_ESCALATION_KINDS.join(', ')}`);
+    }
+    const summary = summaryParts.join(':').trim() || defaultEscalationSummary(kind);
+    return {
+        kind,
+        summary,
+    };
+}
+function nextPhaseAfterEscalationClear(workflow) {
+    if (workflow.phase !== 'awaiting_human_escalation') {
+        return workflow.phase;
+    }
+    return workflow.plan_review_status === 'approved'
+        ? 'approved'
+        : 'awaiting_plan_review';
+}
+export async function recordWorkflowEscalations({ topicDir, triggers, now = new Date(), }) {
+    if (!triggers || triggers.length === 0) {
+        throw new Error('At least one escalation trigger is required.');
+    }
+    const workflow = await readWorkflowState(topicDir);
+    const resolvedHistory = workflow.escalation?.triggers.filter((trigger) => trigger.resolved_at) ?? [];
+    const activeTriggers = triggers.map((trigger) => ({
+        kind: trigger.kind,
+        summary: trigger.summary.trim(),
+        detected_at: now.toISOString(),
+    }));
+    workflow.phase = 'awaiting_human_escalation';
+    workflow.updated_at = now.toISOString();
+    workflow.escalation = {
+        status: 'required',
+        triggers: [...resolvedHistory, ...activeTriggers],
+    };
+    await writeWorkflowState(topicDir, workflow);
+    return workflow;
+}
+export async function clearWorkflowEscalations({ topicDir, resolution, now = new Date(), }) {
+    const workflow = await readWorkflowState(topicDir);
+    const updatedTriggers = (workflow.escalation?.triggers ?? []).map((trigger) => trigger.resolved_at
+        ? trigger
+        : {
+            ...trigger,
+            resolved_at: now.toISOString(),
+            ...(resolution?.trim() ? { resolution: resolution.trim() } : {}),
+        });
+    workflow.updated_at = now.toISOString();
+    workflow.phase = nextPhaseAfterEscalationClear(workflow);
+    workflow.escalation = {
+        status: 'clear',
+        triggers: updatedTriggers,
+    };
+    await writeWorkflowState(topicDir, workflow);
+    return workflow;
+}

package/dist/core/planning/execution-handoff.js

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { readProjectProfile } from '../policies/project-profile.js';
+import { getRootDirFromTopicDir, topicArtifactPath } from '../topics/topic-artifacts.js';
+function extractPlanTasks(plan) {
+    const lines = String(plan || '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => !line.startsWith('#'));
+    const taskLines = lines.filter((line) => /^[-*]\s+|^\d+\.\s+/.test(line));
+    if (taskLines.length > 0) {
+        return taskLines.map((line) => line.replace(/^[-*]\s+|^\d+\.\s+/, '').trim());
+    }
+    return lines;
+}
+function pickExecutionMode(task, shortExecution, longExecution) {
+    const normalized = task.toLowerCase();
+    const longSignals = ['migration', 'long-running', 'cross-cutting', 'multi-service', 'analysis', 'tmux'];
+    const isLong = longSignals.some((signal) => normalized.includes(signal));
+    return isLong
+        ? {
+            executionMode: 'tmux',
+            reason: `Matched long-running signal; route through ${longExecution}.`,
+        }
+        : {
+            executionMode: 'subagent',
+            reason: `Fits a shorter bounded slice; route through ${shortExecution}.`,
+        };
+}
+export async function buildExecutionHandoff(topicDir, now = new Date()) {
+    const [plan, workflow, profile] = await Promise.all([
+        readFile(topicArtifactPath(topicDir, 'implementation_plan'), 'utf8'),
+        readFile(topicArtifactPath(topicDir, 'workflow_state'), 'utf8'),
+        readProjectProfile(getRootDirFromTopicDir(topicDir)),
+    ]);
+    const parsedWorkflow = JSON.parse(workflow);
+    const shortExecution = profile?.engineering_defaults.short_task_execution ?? 'subagent';
+    const longExecution = profile?.engineering_defaults.long_task_execution ?? 'tmux';
+    const tasks = extractPlanTasks(plan).map((task, index) => {
+        const routing = pickExecutionMode(task, shortExecution, longExecution);
+        return {
+            id: `task-${index + 1}`,
+            source_text: task,
+            execution_mode: routing.executionMode,
+            reason: routing.reason,
+        };
+    });
+    return {
+        version: 1,
+        generated_at: now.toISOString(),
+        topic_slug: parsedWorkflow.topic_slug,
+        default_short_execution: shortExecution,
+        default_long_execution: longExecution,
+        tasks,
+    };
+}
+export async function writeExecutionHandoff(topicDir, now = new Date()) {
+    const handoff = await buildExecutionHandoff(topicDir, now);
+    await writeFile(topicArtifactPath(topicDir, 'execution_handoff'), `${JSON.stringify(handoff, null, 2)}\n`, 'utf8');
+    return handoff;
+}