shift-ax 0.3.0

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

@@ -0,0 +1,156 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { topicArtifactPath } from '../topics/topic-artifacts.js';
+async function readArtifact(path) {
+    return readFile(path, 'utf8');
+}
+async function assertResolvedContextReady(topicDir) {
+    const raw = await readArtifact(topicArtifactPath(topicDir, 'resolved_context')).catch(() => '');
+    if (!raw) {
+        throw new Error('resolved context artifact is missing');
+    }
+    const parsed = JSON.parse(raw);
+    if ((parsed.unresolved_paths ?? []).length > 0) {
+        throw new Error('resolved context still has unresolved base-context paths');
+    }
+}
+export async function readExecutionHandoff(topicDir) {
+    const raw = await readArtifact(topicArtifactPath(topicDir, 'execution_handoff'));
+    return JSON.parse(raw);
+}
+export async function readExecutionWorktreePath(topicDir) {
+    const raw = await readArtifact(topicArtifactPath(topicDir, 'worktree_state'));
+    const parsed = JSON.parse(raw);
+    if (!parsed.worktree_path) {
+        throw new Error('worktree-state.json does not contain worktree_path');
+    }
+    return parsed.worktree_path;
+}
+function parseMarkdownSections(markdown) {
+    const sections = new Map();
+    const lines = String(markdown || '').split(/\r?\n/);
+    let currentSection = null;
+    let buffer = [];
+    const flush = () => {
+        if (!currentSection)
+            return;
+        sections.set(currentSection, buffer.join('\n').trim());
+    };
+    for (const line of lines) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading) {
+            flush();
+            currentSection = heading[1].trim();
+            buffer = [];
+            continue;
+        }
+        if (currentSection) {
+            buffer.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+function bulletizeSection(content, fallback) {
+    const items = String(content || '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.replace(/^[-*]\s+/, '').trim())
+        .filter(Boolean)
+        .map((line) => (line.startsWith('- ') ? line : `- ${line}`));
+    if (items.length > 0)
+        return items;
+    return fallback ? [`- ${fallback}`] : [];
+}
+function buildExecutionPromptContent(input) {
+    const brainstormSections = parseMarkdownSections(input.brainstorm);
+    const specSections = parseMarkdownSections(input.spec);
+    const relevantDocs = (input.resolvedContext.matches ?? [])
+        .map((match) => {
+        const label = match.label?.trim();
+        const path = match.path?.trim();
+        if (!label || !path)
+            return null;
+        return `- ${label} -> ${path}`;
+    })
+        .filter((item) => Boolean(item));
+    const constraints = bulletizeSection(specSections.get('Constraints') || brainstormSections.get('Constraints'), 'No extra constraints were recorded.');
+    const outOfScope = bulletizeSection(specSections.get('Out of Scope') || brainstormSections.get('Out of Scope'), 'No out-of-scope items were recorded.');
+    const verification = bulletizeSection(specSections.get('Verification Expectations') || brainstormSections.get('Verification Expectations'), 'No explicit verification expectations were recorded.');
+    return [
+        `You are executing Shift AX task ${input.task.id} inside this worktree: ${input.worktreePath}`,
+        '',
+        `Request summary: ${input.summary.trim() || input.request.trim()}`,
+        '',
+        `Do this task now: ${input.task.source_text.trim()}`,
+        '',
+        'Relevant base-context docs to consult first if they apply:',
+        ...(relevantDocs.length > 0 ? relevantDocs : ['- No directly matched base-context docs were recorded.']),
+        '',
+        'Constraints:',
+        ...constraints,
+        '',
+        'Out of scope:',
+        ...outOfScope,
+        '',
+        'Verification expectations:',
+        ...verification,
+        '',
+        'Execution rules:',
+        '- Read any listed base-context docs before editing when they are relevant.',
+        '- Make the file edits now; do not stop at an explanation or plan.',
+        '- Keep changes inside the assigned worktree only.',
+        '- Do not widen scope beyond the assigned task.',
+        '- If you cannot complete the edit, say exactly why.',
+        '',
+        `Routing reason: ${input.task.reason.trim()}`,
+        '',
+        'In your final response, briefly list changed files and tests run.',
+        '',
+    ].join('\n');
+}
+export async function materializeExecutionPrompts(topicDir, taskId) {
+    await assertResolvedContextReady(topicDir);
+    const [handoff, worktreePath, request, summary, brainstorm, spec, plan, resolvedContextRaw] = await Promise.all([
+        readExecutionHandoff(topicDir),
+        readExecutionWorktreePath(topicDir),
+        readArtifact(topicArtifactPath(topicDir, 'request')),
+        readArtifact(topicArtifactPath(topicDir, 'request_summary')),
+        readArtifact(topicArtifactPath(topicDir, 'brainstorm')),
+        readArtifact(topicArtifactPath(topicDir, 'spec')),
+        readArtifact(topicArtifactPath(topicDir, 'implementation_plan')),
+        readArtifact(topicArtifactPath(topicDir, 'resolved_context')),
+    ]);
+    const resolvedContext = JSON.parse(resolvedContextRaw);
+    const tasks = taskId
+        ? handoff.tasks.filter((task) => task.id === taskId)
+        : handoff.tasks;
+    if (tasks.length === 0) {
+        throw new Error(taskId ? `No execution task found for ${taskId}` : 'No execution tasks found');
+    }
+    const artifacts = [];
+    for (const task of tasks) {
+        const promptPath = join(topicDir, 'execution-prompts', `${task.id}.md`);
+        const outputPath = join(topicDir, 'execution-results', `${task.id}.json`);
+        await mkdir(dirname(promptPath), { recursive: true });
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(promptPath, `${buildExecutionPromptContent({
+            request,
+            summary,
+            brainstorm,
+            spec,
+            plan,
+            resolvedContext,
+            task,
+            worktreePath,
+        }).trimEnd()}\n`, 'utf8');
+        artifacts.push({
+            task,
+            worktreePath,
+            promptPath,
+            outputPath,
+        });
+    }
+    return artifacts;
+}

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

@@ -0,0 +1,87 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { topicArtifactPath } from '../topics/topic-artifacts.js';
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasUsableOutput(path) {
+    try {
+        const details = await stat(path);
+        return details.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForOutput(path, pollIntervalMs, timeoutMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= timeoutMs) {
+        if (await pathExists(path))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error(`Timed out waiting for execution output: ${path}`);
+}
+async function writeExecutionState(topicDir, state) {
+    await writeFile(topicArtifactPath(topicDir, 'execution_state'), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export async function orchestrateExecutionTasks({ topicDir, tasks, runTask, pollIntervalMs = 50, timeoutMs = 60_000, }) {
+    const startedAt = new Date().toISOString();
+    const taskStates = [];
+    for (const task of tasks) {
+        const taskStartedAt = new Date().toISOString();
+        try {
+            await mkdir(dirname(task.output_path), { recursive: true });
+            if (!(await hasUsableOutput(task.output_path))) {
+                await runTask(task);
+                await waitForOutput(task.output_path, pollIntervalMs, timeoutMs);
+            }
+            taskStates.push({
+                task_id: task.task_id,
+                execution_mode: task.execution_mode,
+                status: 'completed',
+                output_path: task.output_path,
+                ...(task.session_name ? { session_name: task.session_name } : {}),
+                started_at: taskStartedAt,
+                completed_at: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            taskStates.push({
+                task_id: task.task_id,
+                execution_mode: task.execution_mode,
+                status: /timed out/i.test(message) ? 'timed_out' : 'failed',
+                output_path: task.output_path,
+                ...(task.session_name ? { session_name: task.session_name } : {}),
+                started_at: taskStartedAt,
+                completed_at: new Date().toISOString(),
+                error: message,
+            });
+            const failedState = {
+                version: 1,
+                overall_status: 'failed',
+                started_at: startedAt,
+                completed_at: new Date().toISOString(),
+                tasks: taskStates,
+            };
+            await writeExecutionState(topicDir, failedState);
+            return failedState;
+        }
+    }
+    const state = {
+        version: 1,
+        overall_status: 'completed',
+        started_at: startedAt,
+        completed_at: new Date().toISOString(),
+        tasks: taskStates,
+    };
+    await writeExecutionState(topicDir, state);
+    return state;
+}

package/dist/core/planning/feedback-reactions.js

@@ -0,0 +1,75 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { renderReviewSummaryMarkdown } from '../review/aggregate-reviews.js';
+import { readWorkflowState, writeWorkflowState } from './workflow-state.js';
+import { recordLifecycleEvent } from './lifecycle-events.js';
+function buildFeedbackVerdict({ kind, summary, now, }) {
+    return {
+        version: 1,
+        lane: 'downstream-feedback',
+        status: kind === 'ci-failed' ? 'blocked' : 'changes_requested',
+        checked_at: now.toISOString(),
+        summary,
+    };
+}
+function buildFeedbackAggregate(verdict) {
+    return {
+        version: 1,
+        overall_status: verdict.status,
+        commit_allowed: false,
+        next_stage: 'implementation',
+        required_lanes: [],
+        approved_lanes: [],
+        changes_requested_lanes: verdict.status === 'changes_requested' ? ['downstream-feedback'] : [],
+        blocked_lanes: verdict.status === 'blocked' ? ['downstream-feedback'] : [],
+        missing_lanes: [],
+        verdicts: [verdict],
+    };
+}
+async function writeFeedbackArtifacts(topicDir, verdict, aggregate) {
+    const reviewDir = join(topicDir, 'review');
+    await Promise.all([
+        writeFile(join(reviewDir, 'downstream-feedback.json'), `${JSON.stringify(verdict, null, 2)}\n`, 'utf8'),
+        writeFile(join(reviewDir, 'aggregate.json'), `${JSON.stringify(aggregate, null, 2)}\n`, 'utf8'),
+        writeFile(join(reviewDir, 'summary.md'), renderReviewSummaryMarkdown(aggregate), 'utf8'),
+    ]);
+}
+export async function applyFeedbackReaction({ topicDir, kind, summary, now = new Date(), }) {
+    if (!summary.trim()) {
+        throw new Error('feedback summary is required');
+    }
+    const workflow = await readWorkflowState(topicDir);
+    workflow.phase = 'implementation_running';
+    workflow.updated_at = now.toISOString();
+    workflow.review = {
+        overall_status: kind === 'ci-failed' ? 'blocked' : 'changes_requested',
+        commit_allowed: false,
+        next_stage: 'implementation',
+    };
+    delete workflow.verification;
+    await writeWorkflowState(topicDir, workflow);
+    const verdict = buildFeedbackVerdict({
+        kind,
+        summary: summary.trim(),
+        now,
+    });
+    const aggregate = buildFeedbackAggregate(verdict);
+    await writeFeedbackArtifacts(topicDir, verdict, aggregate);
+    await recordLifecycleEvent({
+        topicDir,
+        phase: workflow.phase,
+        event: 'feedback.received',
+        summary: summary.trim(),
+        reaction: {
+            key: kind,
+            action: 'reopen_execution',
+            outcome: verdict.status,
+        },
+        now,
+    });
+    return {
+        workflow,
+        aggregate,
+        feedback_verdict: verdict,
+    };
+}

package/dist/core/planning/lifecycle-events.js

@@ -0,0 +1,45 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+function lifecycleLogPath(topicDir) {
+    return join(topicDir, 'lifecycle-log.json');
+}
+function reactionLogPath(topicDir) {
+    return join(topicDir, 'reaction-log.json');
+}
+async function readJsonArray(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+async function writeJsonArray(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+export async function recordLifecycleEvent({ topicDir, phase, event, summary, reaction, now = new Date(), }) {
+    const events = await readJsonArray(lifecycleLogPath(topicDir));
+    events.push({
+        phase,
+        event,
+        summary,
+        recorded_at: now.toISOString(),
+    });
+    await writeJsonArray(lifecycleLogPath(topicDir), events);
+    if (reaction) {
+        const reactions = await readJsonArray(reactionLogPath(topicDir));
+        reactions.push({
+            ...reaction,
+            recorded_at: now.toISOString(),
+        });
+        await writeJsonArray(reactionLogPath(topicDir), reactions);
+    }
+}
+export async function readLifecycleEvents(topicDir) {
+    return readJsonArray(lifecycleLogPath(topicDir));
+}
+export async function readReactionRecords(topicDir) {
+    return readJsonArray(reactionLogPath(topicDir));
+}

package/dist/core/planning/plan-review.js

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { topicArtifactPath } from '../topics/topic-artifacts.js';
+import { recordLifecycleEvent } from './lifecycle-events.js';
+import { readPolicyContextSyncArtifact } from './policy-context-sync.js';
+import { readWorkflowState, writeWorkflowState, } from './workflow-state.js';
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+async function readPlanFile(topicDir) {
+    return readFile(topicArtifactPath(topicDir, 'implementation_plan'), 'utf8');
+}
+export async function readPlanReviewArtifact(topicDir) {
+    const raw = await readFile(topicArtifactPath(topicDir, 'plan_review'), 'utf8');
+    return JSON.parse(raw);
+}
+export async function writePlanReviewArtifact(topicDir, artifact) {
+    await writeFile(topicArtifactPath(topicDir, 'plan_review'), `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+}
+export async function recordPlanReviewDecision({ topicDir, reviewer, status, notes, now = new Date(), }) {
+    const planContent = await readPlanFile(topicDir);
+    const fingerprint = status === 'approved'
+        ? {
+            plan_path: 'implementation-plan.md',
+            sha256: sha256(planContent),
+        }
+        : undefined;
+    const artifact = {
+        version: 1,
+        status,
+        reviewer,
+        reviewed_at: now.toISOString(),
+        ...(notes ? { notes } : {}),
+        ...(fingerprint ? { approved_plan_fingerprint: fingerprint } : {}),
+    };
+    await writePlanReviewArtifact(topicDir, artifact);
+    const workflow = await readWorkflowState(topicDir);
+    workflow.plan_review_status = status;
+    const policyContextSync = await readPolicyContextSyncArtifact(topicDir);
+    workflow.phase =
+        status === 'approved'
+            ? policyContextSync.status === 'required'
+                ? 'awaiting_policy_sync'
+                : 'approved'
+            : 'awaiting_plan_review';
+    workflow.updated_at = now.toISOString();
+    await writeWorkflowState(topicDir, workflow);
+    if (status === 'approved' && policyContextSync.status === 'required') {
+        await recordLifecycleEvent({
+            topicDir,
+            phase: workflow.phase,
+            event: 'policy.sync_required',
+            summary: 'Plan approval requires shared base-context policy updates before implementation can start.',
+            now,
+        });
+    }
+    return artifact;
+}
+export async function verifyApprovedPlanFingerprint({ topicDir, }) {
+    const review = await readPlanReviewArtifact(topicDir);
+    if (review.status !== 'approved' || !review.approved_plan_fingerprint) {
+        return {
+            matches: false,
+            reason: 'plan review is not approved',
+        };
+    }
+    const currentSha = sha256(await readPlanFile(topicDir));
+    return {
+        matches: currentSha === review.approved_plan_fingerprint.sha256,
+        expected: review.approved_plan_fingerprint,
+        actual_sha256: currentSha,
+        ...(currentSha === review.approved_plan_fingerprint.sha256
+            ? {}
+            : { reason: 'approved plan fingerprint does not match current plan' }),
+    };
+}

package/dist/core/planning/policy-context-sync.js

@@ -0,0 +1,154 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { authorBaseContextIndex } from '../context/index-authoring.js';
+import { readProjectProfile, writeProjectProfile, } from '../policies/project-profile.js';
+import { getRootDirFromTopicDir, topicArtifactPath } from '../topics/topic-artifacts.js';
+import { recordLifecycleEvent } from './lifecycle-events.js';
+import { readWorkflowState, writeWorkflowState } from './workflow-state.js';
+const POLICY_UPDATE_HEADING = /^#{2,}\s+(?:base-context\s+policy\s+updates?|base-context\s+updates?|policy\s+updates?)\s*$/i;
+const POLICY_UPDATE_NONE = /^\s*-\s*(none(?:\s+yet)?|no(?:\s+updates?)?|n\/a|not needed|없음|해당 없음)\s*\.?\s*$/i;
+function dedupeStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function dedupeEntries(entries) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        const normalized = {
+            label: entry.label.trim(),
+            path: entry.path.trim(),
+        };
+        if (!normalized.label || !normalized.path)
+            continue;
+        const key = `${normalized.label}::${normalized.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(normalized);
+    }
+    return result;
+}
+export function extractPolicyContextUpdates(markdown) {
+    const lines = String(markdown || '').split(/\r?\n/);
+    const items = [];
+    let capturing = false;
+    for (const line of lines) {
+        if (POLICY_UPDATE_HEADING.test(line.trim())) {
+            capturing = true;
+            continue;
+        }
+        if (capturing && /^#{1,6}\s+/.test(line.trim())) {
+            capturing = false;
+            continue;
+        }
+        if (!capturing)
+            continue;
+        if (POLICY_UPDATE_NONE.test(line)) {
+            continue;
+        }
+        const match = line.match(/^\s*-\s+(.+?)\s*$/);
+        if (match?.[1]) {
+            items.push(match[1].trim());
+        }
+    }
+    return dedupeStrings(items);
+}
+export function inferPolicyContextSyncArtifact({ brainstormContent, specContent, implementationPlanContent, now = new Date(), }) {
+    const requiredUpdates = dedupeStrings([
+        ...extractPolicyContextUpdates(brainstormContent),
+        ...extractPolicyContextUpdates(specContent),
+        ...extractPolicyContextUpdates(implementationPlanContent),
+    ]);
+    return {
+        version: 1,
+        status: requiredUpdates.length > 0 ? 'required' : 'not_needed',
+        required_updates: requiredUpdates,
+        created_at: now.toISOString(),
+        updated_at: now.toISOString(),
+    };
+}
+export async function writePolicyContextSyncArtifact(topicDir, artifact) {
+    await writeFile(topicArtifactPath(topicDir, 'policy_context_sync'), `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+}
+export async function readPolicyContextSyncArtifact(topicDir) {
+    try {
+        const raw = await readFile(topicArtifactPath(topicDir, 'policy_context_sync'), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {
+            version: 1,
+            status: 'not_needed',
+            required_updates: [],
+            created_at: new Date(0).toISOString(),
+            updated_at: new Date(0).toISOString(),
+        };
+    }
+}
+async function mergeContextDocs(rootDir, entries) {
+    const mergedEntries = dedupeEntries(entries);
+    if (mergedEntries.length === 0)
+        return undefined;
+    const index = await authorBaseContextIndex({
+        rootDir,
+        entries: mergedEntries,
+    });
+    const profile = await readProjectProfile(rootDir);
+    if (profile) {
+        const byKey = new Map();
+        for (const doc of [...profile.context_docs, ...mergedEntries]) {
+            byKey.set(`${doc.label}::${doc.path}`, doc);
+        }
+        profile.context_docs = [...byKey.values()];
+        profile.updated_at = new Date().toISOString();
+        await writeProjectProfile(rootDir, profile);
+    }
+    return index;
+}
+export async function completePolicyContextSync({ topicDir, summary, syncedPaths = [], syncedEntries = [], now = new Date(), }) {
+    if (!summary.trim()) {
+        throw new Error('policy context sync summary is required');
+    }
+    const artifact = await readPolicyContextSyncArtifact(topicDir);
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    const normalizedPaths = dedupeStrings(syncedPaths);
+    const normalizedEntries = dedupeEntries(syncedEntries);
+    if (artifact.status === 'required' && normalizedPaths.length === 0 && normalizedEntries.length === 0) {
+        throw new Error('policy context sync requires at least one updated path or index entry');
+    }
+    for (const path of normalizedPaths) {
+        if (!existsSync(join(rootDir, path))) {
+            throw new Error(`policy context path does not exist: ${path}`);
+        }
+    }
+    for (const entry of normalizedEntries) {
+        if (!existsSync(join(rootDir, entry.path))) {
+            throw new Error(`policy context entry path does not exist: ${entry.path}`);
+        }
+    }
+    await mergeContextDocs(rootDir, normalizedEntries);
+    const completed = {
+        ...artifact,
+        status: artifact.status === 'not_needed' ? 'not_needed' : 'completed',
+        updated_at: now.toISOString(),
+        summary: summary.trim(),
+        synced_paths: normalizedPaths,
+        ...(normalizedEntries.length > 0 ? { synced_entries: normalizedEntries } : {}),
+    };
+    await writePolicyContextSyncArtifact(topicDir, completed);
+    const workflow = await readWorkflowState(topicDir);
+    if (workflow.plan_review_status === 'approved') {
+        workflow.phase = 'approved';
+        workflow.updated_at = now.toISOString();
+        await writeWorkflowState(topicDir, workflow);
+    }
+    await recordLifecycleEvent({
+        topicDir,
+        phase: workflow.plan_review_status === 'approved' ? 'approved' : workflow.phase,
+        event: 'policy.sync_completed',
+        summary: summary.trim(),
+        now,
+    });
+    return completed;
+}