shift-ax 0.3.0

package/dist/core/planning/request-pipeline.js

@@ -0,0 +1,386 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { promisify } from 'node:util';
+import { resolveContextFromIndex } from '../context/index-resolver.js';
+import { applyGlobalKnowledgeUpdatesFromArtifacts } from '../context/global-knowledge-updates.js';
+import { ensureTopicCommitMessageArtifact } from '../finalization/commit-workflow.js';
+import { finalizeTopicCommit } from '../finalization/commit-workflow.js';
+import { readProjectProfile } from '../policies/project-profile.js';
+import { aggregateReviewVerdicts, writeAggregateReviewArtifacts, } from '../review/aggregate-reviews.js';
+import { runReviewLanes } from '../review/run-lanes.js';
+import { bootstrapTopic, } from '../topics/bootstrap.js';
+import { topicArtifactPath, getRootDirFromTopicDir, } from '../topics/topic-artifacts.js';
+import { createTopicWorktree, } from '../topics/worktree-runtime.js';
+import { verifyApprovedPlanFingerprint } from './plan-review.js';
+import { clearWorkflowEscalations, recordWorkflowEscalations, } from './escalation.js';
+import { writeExecutionHandoff } from './execution-handoff.js';
+import { recordLifecycleEvent } from './lifecycle-events.js';
+import { inferPolicyContextSyncArtifact, readPolicyContextSyncArtifact, writePolicyContextSyncArtifact, } from './policy-context-sync.js';
+import { hasActiveWorkflowEscalations, readWorkflowState, writeWorkflowState, } from './workflow-state.js';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+const execFileAsync = promisify(execFile);
+async function resolveRequestContext({ rootDir, request, contextQuery, indexPath = getGlobalContextHome().indexPath, maxMatches = 5, }) {
+    const effectiveQuery = contextQuery?.trim() || request.trim();
+    if (existsSync(indexPath)) {
+        return resolveContextFromIndex({
+            rootDir,
+            indexPath,
+            indexRootDir: getGlobalContextHome().root,
+            query: effectiveQuery,
+            maxMatches,
+        });
+    }
+    return {
+        version: 1,
+        index_path: indexPath,
+        query: effectiveQuery,
+        matches: [],
+        unresolved_paths: [relative(rootDir, indexPath) || indexPath],
+    };
+}
+function buildDefaultBrainstorm(request, matchedLabels) {
+    return [
+        '# Brainstorm',
+        '',
+        '## Request',
+        '',
+        request.trim(),
+        '',
+        '## Relevant Context',
+        '',
+        ...(matchedLabels.length > 0 ? matchedLabels.map((label) => `- ${label}`) : ['- No matched context documents yet.']),
+        '',
+        '## Global Knowledge Updates',
+        '',
+        '- None yet.',
+        '',
+    ].join('\n');
+}
+function buildDefaultSpec(request, matchedLabels) {
+    return [
+        '# Topic Spec',
+        '',
+        '## Goal',
+        '',
+        request.trim(),
+        '',
+        '## Relevant Context',
+        '',
+        ...(matchedLabels.length > 0 ? matchedLabels.map((label) => `- ${label}`) : ['- No matched context documents yet.']),
+        '',
+        '## Global Knowledge Updates',
+        '',
+        '- None yet.',
+        '',
+    ].join('\n');
+}
+function buildDefaultImplementationPlan(testStrategy, architecture) {
+    return [
+        '# Implementation Plan',
+        '',
+        `Use ${testStrategy.toUpperCase()} first.`,
+        `Respect ${architecture.replace(/-/g, ' ')}.`,
+        'Add focused verification steps before commit finalization.',
+        '',
+        '## Global Knowledge Updates',
+        '',
+        '- None yet.',
+        '',
+    ].join('\n');
+}
+async function writeVerificationReport(topicDir, verification) {
+    const lines = ['# Final Verification', ''];
+    if (verification.length === 0) {
+        lines.push('No verification commands were provided.');
+    }
+    else {
+        for (const item of verification) {
+            lines.push(`## ${item.command}`);
+            lines.push('');
+            lines.push(`- exit_code: ${item.exit_code}`);
+            lines.push('');
+            lines.push('```text');
+            lines.push(item.stdout.trim() || item.stderr.trim() || '(no output)');
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    await writeFile(topicArtifactPath(topicDir, 'verification'), `${lines.join('\n')}\n`, 'utf8');
+}
+async function runVerificationCommands(cwd, commands) {
+    const results = [];
+    for (const command of commands) {
+        try {
+            const { stdout, stderr } = await execFileAsync('/bin/sh', ['-lc', command], { cwd });
+            results.push({
+                command,
+                exit_code: 0,
+                stdout,
+                stderr,
+            });
+        }
+        catch (error) {
+            const failed = error;
+            results.push({
+                command,
+                exit_code: typeof failed.code === 'number' ? failed.code : 1,
+                stdout: failed.stdout ?? '',
+                stderr: failed.stderr ?? '',
+            });
+            break;
+        }
+    }
+    return results;
+}
+async function resolveExecutionCwd(topicDir) {
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    try {
+        const raw = await readFile(topicArtifactPath(topicDir, 'worktree_state'), 'utf8');
+        const state = JSON.parse(raw);
+        if (state.worktree_path &&
+            ['created', 'reused'].includes(String(state.status || '')) &&
+            existsSync(state.worktree_path)) {
+            return state.worktree_path;
+        }
+    }
+    catch {
+        // fall back to rootDir
+    }
+    return rootDir;
+}
+async function assertResolvedContextReady(topicDir) {
+    const raw = await readFile(topicArtifactPath(topicDir, 'resolved_context'), 'utf8').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 startRequestPipeline({ rootDir, request, summary, indexPath, contextQuery, maxMatches, brainstormContent, specContent, implementationPlanContent, baseBranch = 'main', allowMissingGlobalIndex = false, now = new Date(), }) {
+    const topic = await bootstrapTopic({
+        rootDir,
+        request,
+        summary,
+        now,
+    });
+    const profile = await readProjectProfile(rootDir);
+    const resolvedContext = await resolveRequestContext({
+        rootDir,
+        request,
+        contextQuery,
+        indexPath,
+        maxMatches,
+    });
+    const matchedLabels = resolvedContext.matches.map((match) => match.label);
+    if (!existsSync(indexPath ?? getGlobalContextHome().indexPath) && !allowMissingGlobalIndex) {
+        throw new Error('global context index is missing. Run /onboarding first, or pass --allow-missing-global-context to continue with reduced accuracy.');
+    }
+    if (resolvedContext.unresolved_paths.length > 0) {
+        throw new Error('resolved context still has unresolved base-context paths');
+    }
+    await writeFile(topicArtifactPath(topic.topicDir, 'resolved_context'), `${JSON.stringify(resolvedContext, null, 2)}\n`, 'utf8');
+    await writeFile(topicArtifactPath(topic.topicDir, 'brainstorm'), `${brainstormContent ?? buildDefaultBrainstorm(request, matchedLabels)}\n`, 'utf8');
+    await writeFile(topicArtifactPath(topic.topicDir, 'spec'), `${specContent ?? buildDefaultSpec(request, matchedLabels)}\n`, 'utf8');
+    await writeFile(topicArtifactPath(topic.topicDir, 'implementation_plan'), `${implementationPlanContent ?? buildDefaultImplementationPlan(profile?.engineering_defaults.test_strategy ?? 'tdd', profile?.engineering_defaults.architecture ?? 'clean-boundaries')}\n`, 'utf8');
+    await applyGlobalKnowledgeUpdatesFromArtifacts({
+        brainstormContent: brainstormContent ?? buildDefaultBrainstorm(request, matchedLabels),
+        specContent: specContent ?? buildDefaultSpec(request, matchedLabels),
+        implementationPlanContent: implementationPlanContent ??
+            buildDefaultImplementationPlan(profile?.engineering_defaults.test_strategy ?? 'tdd', profile?.engineering_defaults.architecture ?? 'clean-boundaries'),
+    });
+    await writePolicyContextSyncArtifact(topic.topicDir, inferPolicyContextSyncArtifact({
+        brainstormContent: brainstormContent ?? buildDefaultBrainstorm(request, matchedLabels),
+        specContent: specContent ?? buildDefaultSpec(request, matchedLabels),
+        implementationPlanContent: implementationPlanContent ??
+            buildDefaultImplementationPlan(profile?.engineering_defaults.test_strategy ?? 'tdd', profile?.engineering_defaults.architecture ?? 'clean-boundaries'),
+        now,
+    }));
+    await writeExecutionHandoff(topic.topicDir, now);
+    const worktree = await createTopicWorktree({
+        topicDir: topic.topicDir,
+        baseBranch,
+    });
+    const workflow = {
+        ...(await readWorkflowState(topic.topicDir)),
+        updated_at: now.toISOString(),
+        phase: 'awaiting_plan_review',
+        plan_review_status: 'pending',
+        worktree: {
+            branch_name: worktree.branch_name,
+            worktree_path: worktree.worktree_path,
+            base_branch: worktree.base_branch,
+        },
+        resolved_context: {
+            index_path: resolvedContext.index_path,
+            query: resolvedContext.query,
+            matches: resolvedContext.matches.length,
+            unresolved_paths: resolvedContext.unresolved_paths,
+        },
+        escalation: {
+            status: 'clear',
+            triggers: [],
+        },
+    };
+    await writeWorkflowState(topic.topicDir, workflow);
+    await recordLifecycleEvent({
+        topicDir: topic.topicDir,
+        phase: workflow.phase,
+        event: 'plan.review_required',
+        summary: 'Waiting for the human plan review.',
+        now,
+    });
+    return {
+        ...topic,
+        resolvedContext,
+        worktree,
+        workflow,
+    };
+}
+export async function resumeRequestPipeline({ topicDir, verificationCommands = [], escalationTriggers = [], clearEscalations = false, escalationResolution, autoCommit = false, executionRunner, now = new Date(), }) {
+    if (clearEscalations) {
+        await clearWorkflowEscalations({
+            topicDir,
+            resolution: escalationResolution,
+            now,
+        });
+    }
+    if (escalationTriggers.length > 0) {
+        await recordWorkflowEscalations({
+            topicDir,
+            triggers: escalationTriggers,
+            now,
+        });
+        await recordLifecycleEvent({
+            topicDir,
+            phase: 'awaiting_human_escalation',
+            event: 'execution.blocked',
+            summary: 'Execution stopped because a mandatory escalation trigger was raised.',
+            reaction: {
+                key: escalationTriggers[0].kind,
+                action: 'await_human_escalation',
+                outcome: 'blocked',
+            },
+            now,
+        });
+        throw new Error('workflow requires human escalation review before automation can continue');
+    }
+    const fingerprint = await verifyApprovedPlanFingerprint({ topicDir });
+    if (!fingerprint.matches) {
+        throw new Error(fingerprint.reason ?? 'approved plan fingerprint check failed');
+    }
+    await assertResolvedContextReady(topicDir);
+    const workflow = await readWorkflowState(topicDir);
+    if (hasActiveWorkflowEscalations(workflow)) {
+        throw new Error('workflow has active escalation triggers; resolve them before resuming automation');
+    }
+    const policyContextSync = await readPolicyContextSyncArtifact(topicDir);
+    if (policyContextSync.status === 'required') {
+        workflow.phase = 'awaiting_policy_sync';
+        workflow.updated_at = now.toISOString();
+        await writeWorkflowState(topicDir, workflow);
+        throw new Error('policy context sync is required before implementation can start');
+    }
+    workflow.phase = 'implementation_running';
+    workflow.plan_review_status = 'approved';
+    workflow.updated_at = now.toISOString();
+    await writeWorkflowState(topicDir, workflow);
+    await recordLifecycleEvent({
+        topicDir,
+        phase: workflow.phase,
+        event: 'execution.started',
+        summary: 'Execution resumed after human plan approval.',
+        now,
+    });
+    const executionCwd = await resolveExecutionCwd(topicDir);
+    if (executionRunner) {
+        const executionState = await executionRunner({
+            topicDir,
+            worktreePath: executionCwd,
+        });
+        await writeFile(topicArtifactPath(topicDir, 'execution_state'), `${JSON.stringify(executionState, null, 2)}\n`, 'utf8');
+        if (executionState.overall_status !== 'completed') {
+            throw new Error('execution orchestration failed');
+        }
+    }
+    const verification = await runVerificationCommands(executionCwd, verificationCommands);
+    await writeVerificationReport(topicDir, verification);
+    workflow.verification = verification;
+    if (verification.some((item) => item.exit_code !== 0)) {
+        workflow.updated_at = now.toISOString();
+        await writeWorkflowState(topicDir, workflow);
+        throw new Error('verification commands failed');
+    }
+    workflow.phase = 'review_pending';
+    workflow.updated_at = now.toISOString();
+    await writeWorkflowState(topicDir, workflow);
+    await recordLifecycleEvent({
+        topicDir,
+        phase: workflow.phase,
+        event: 'review.started',
+        summary: 'Structured review lanes are running.',
+        now,
+    });
+    await runReviewLanes({ topicDir });
+    const aggregate = await aggregateReviewVerdicts({ topicDir });
+    await writeAggregateReviewArtifacts(topicDir, aggregate);
+    workflow.review = {
+        overall_status: aggregate.overall_status,
+        commit_allowed: aggregate.commit_allowed,
+        next_stage: aggregate.next_stage,
+    };
+    if (aggregate.commit_allowed) {
+        await ensureTopicCommitMessageArtifact({
+            topicDir,
+            verification,
+        });
+    }
+    workflow.phase = aggregate.commit_allowed ? 'commit_ready' : 'implementation_running';
+    workflow.updated_at = now.toISOString();
+    await writeWorkflowState(topicDir, workflow);
+    await recordLifecycleEvent({
+        topicDir,
+        phase: workflow.phase,
+        event: 'review.completed',
+        summary: aggregate.commit_allowed
+            ? 'Review passed and the topic is commit-ready.'
+            : 'Review requested more implementation work.',
+        ...(aggregate.commit_allowed
+            ? {}
+            : {
+                reaction: {
+                    key: 'review-changes-requested',
+                    action: 'return_to_implementation',
+                    outcome: 'changes_requested',
+                },
+            }),
+        now,
+    });
+    let finalization;
+    if (aggregate.commit_allowed && autoCommit) {
+        finalization = await finalizeTopicCommit({
+            topicDir,
+            now,
+        });
+        workflow.phase = 'committed';
+        workflow.updated_at = now.toISOString();
+        await writeWorkflowState(topicDir, workflow);
+        await recordLifecycleEvent({
+            topicDir,
+            phase: workflow.phase,
+            event: 'finalization.committed',
+            summary: 'Automatic finalization created the local commit.',
+            now,
+        });
+    }
+    return {
+        workflow,
+        aggregate,
+        verification,
+        ...(finalization ? { finalization } : {}),
+    };
+}
+export { readWorkflowState } from './workflow-state.js';

package/dist/core/planning/workflow-state.js

@@ -0,0 +1,18 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { topicArtifactPath } from '../topics/topic-artifacts.js';
+export const SHIFT_AX_ESCALATION_KINDS = [
+    'new-user-flow',
+    'policy-conflict',
+    'risky-data-or-permission-change',
+];
+export function hasActiveWorkflowEscalations(state) {
+    return (state.escalation?.status === 'required' &&
+        state.escalation.triggers.some((trigger) => !trigger.resolved_at));
+}
+export async function readWorkflowState(topicDir) {
+    const raw = await readFile(topicArtifactPath(topicDir, 'workflow_state'), 'utf8');
+    return JSON.parse(raw);
+}
+export async function writeWorkflowState(topicDir, state) {
+    await writeFile(topicArtifactPath(topicDir, 'workflow_state'), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}

package/dist/core/policies/project-profile.js

@@ -0,0 +1,28 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { getGlobalContextHome } from '../settings/global-context-home.js';
+export function defaultEngineeringDefaults() {
+    return {
+        test_strategy: 'tdd',
+        architecture: 'clean-boundaries',
+        short_task_execution: 'subagent',
+        long_task_execution: 'tmux',
+        verification_commands: ['npm test', 'npm run build'],
+    };
+}
+export function getProjectProfilePath(rootDir) {
+    return getGlobalContextHome().profilePath;
+}
+export async function readProjectProfile(rootDir) {
+    try {
+        const raw = await readFile(getProjectProfilePath(rootDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeProjectProfile(rootDir, profile) {
+    const path = getProjectProfilePath(rootDir);
+    await mkdir(getGlobalContextHome().root, { recursive: true });
+    await writeFile(path, `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+}

package/dist/core/policies/team-preferences.js

@@ -0,0 +1,17 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+function path(rootDir) {
+    return join(rootDir, '.ax', 'team-preferences.json');
+}
+export async function readTeamPreferences(rootDir) {
+    try {
+        return JSON.parse(await readFile(path(rootDir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeTeamPreferences({ rootDir, preferences, }) {
+    await mkdir(join(rootDir, '.ax'), { recursive: true });
+    await writeFile(path(rootDir), `${JSON.stringify(preferences, null, 2)}\n`, 'utf8');
+}

package/dist/core/review/aggregate-reviews.js

@@ -0,0 +1,129 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const REQUIRED_REVIEW_LANES = [
+    'domain-policy',
+    'spec-conformance',
+    'test-adequacy',
+    'engineering-discipline',
+    'conversation-trace',
+];
+async function readVerdictFile(path) {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+}
+export async function aggregateReviewVerdicts({ topicDir, requiredLanes = [...REQUIRED_REVIEW_LANES], }) {
+    if (!topicDir)
+        throw new Error('topicDir is required');
+    const reviewDir = join(topicDir, 'review');
+    let files = [];
+    try {
+        files = (await readdir(reviewDir))
+            .filter((entry) => entry.endsWith('.json'))
+            .sort();
+    }
+    catch {
+        files = [];
+    }
+    const verdicts = [];
+    for (const file of files) {
+        try {
+            const verdict = await readVerdictFile(join(reviewDir, file));
+            verdicts.push(verdict);
+        }
+        catch {
+            // Ignore malformed verdicts in aggregation.
+        }
+    }
+    const byLane = new Map();
+    for (const verdict of verdicts) {
+        if (!verdict?.lane)
+            continue;
+        byLane.set(verdict.lane, verdict);
+    }
+    const approvedLanes = [];
+    const changesRequestedLanes = [];
+    const blockedLanes = [];
+    const missingLanes = [];
+    for (const lane of requiredLanes) {
+        const verdict = byLane.get(lane);
+        if (!verdict) {
+            missingLanes.push(lane);
+            continue;
+        }
+        if (verdict.status === 'approved')
+            approvedLanes.push(lane);
+        else if (verdict.status === 'changes_requested') {
+            changesRequestedLanes.push(lane);
+        }
+        else {
+            blockedLanes.push(lane);
+        }
+    }
+    let overallStatus = 'approved';
+    if (missingLanes.length > 0 || blockedLanes.length > 0) {
+        overallStatus = 'blocked';
+    }
+    else if (changesRequestedLanes.length > 0) {
+        overallStatus = 'changes_requested';
+    }
+    const commitAllowed = overallStatus === 'approved';
+    const nextStage = commitAllowed ? 'finalization' : 'implementation';
+    return {
+        version: 1,
+        overall_status: overallStatus,
+        commit_allowed: commitAllowed,
+        next_stage: nextStage,
+        required_lanes: [...requiredLanes],
+        approved_lanes: approvedLanes,
+        changes_requested_lanes: changesRequestedLanes,
+        blocked_lanes: blockedLanes,
+        missing_lanes: missingLanes,
+        verdicts: requiredLanes
+            .map((lane) => byLane.get(lane))
+            .filter((verdict) => Boolean(verdict)),
+    };
+}
+export function renderReviewSummaryMarkdown(result) {
+    const lines = [
+        '# Review Summary',
+        '',
+        `- Overall Status: ${result.overall_status}`,
+        `- Commit Allowed: ${result.commit_allowed ? 'yes' : 'no'}`,
+        `- Next Stage: ${result.next_stage}`,
+        '',
+        '## Lane Status',
+        '',
+        `- Approved: ${result.approved_lanes.join(', ') || '(none)'}`,
+        `- Changes Requested: ${result.changes_requested_lanes.join(', ') || '(none)'}`,
+        `- Blocked: ${result.blocked_lanes.join(', ') || '(none)'}`,
+        `- Missing Lanes: ${result.missing_lanes.join(', ') || '(none)'}`,
+        '',
+        '## Lane Summaries',
+        '',
+    ];
+    if (result.verdicts.length === 0) {
+        lines.push('- No lane verdicts were recorded.');
+    }
+    else {
+        for (const verdict of result.verdicts) {
+            lines.push(`### ${verdict.lane}`);
+            lines.push(`- Status: ${verdict.status}`);
+            lines.push(`- Summary: ${verdict.summary}`);
+            if (verdict.issues && verdict.issues.length > 0) {
+                lines.push('- Issues:');
+                for (const issue of verdict.issues) {
+                    lines.push(`  - [${issue.severity}] ${issue.message}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+export async function writeAggregateReviewArtifacts(topicDir, result) {
+    const reviewDir = join(topicDir, 'review');
+    await Promise.all([
+        writeFile(join(reviewDir, 'aggregate.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8'),
+        writeFile(join(reviewDir, 'summary.md'), renderReviewSummaryMarkdown(result), 'utf8'),
+    ]);
+}