@slope-dev/slope 1.57.2 → 1.58.0

package/dist/cli/commands/sprint.js

@@ -1,5 +1,5 @@
 import { loadSprintState, saveSprintState, createSprintState, mutateSprintState, updateGate, updateSprintPhase, clearSprintState, isSprintComplete, pendingGates, isSprintPhase, SPRINT_PHASES, } from '../sprint-state.js';
-import { WorkflowEngine, loadWorkflow, resolveVariables, validateWorkflow, loadConfig, loadScorecards, parseRoadmap, castRoadmapStructure, formatSprintLabel, formatSprintNumber, parseSprintNumber } from '../../core/index.js';
+import { WorkflowEngine, loadWorkflow, resolveVariables, validateWorkflow, loadConfig, parseRoadmap, castRoadmapStructure, formatSprintLabel, formatSprintNumber, parseSprintNumber } from '../../core/index.js';
 import { createHash } from 'node:crypto';
 /** Get workflow definition from execution snapshot (preferred) or disk (fallback for old executions) */
 function getDefinition(exec, cwd) {
@@ -20,9 +20,12 @@ function getDefinition(exec, cwd) {
     return { def: loadWorkflow(exec.workflow_name, cwd), drifted: false };
 }
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { join, dirname, basename, isAbsolute } from 'node:path';
 import { createStore } from '../../store/index.js';
+import { formatCliError } from '../error-reporter.js';
+import { buildSprintResumePointer, planPortableSprintResume, writeSprintResumePointer, } from '../sprint-resume.js';
 import { blockingRoadmapIssuesForSprint, collectSiblingWorktreeReality, findWorktreeOverlaps, formatWorktreeRealitySection, loadRoadmapReality, parseTouchedPaths, } from '../pre-sprint-reality.js';
+import { findStaleWorkflowExecutions, reconcileWorkflowExecutions } from '../workflow-resync.js';
 /**
  * Check completion_conditions for a step before allowing completion/skip.
  * Returns null if all conditions met, or an error message string.
@@ -385,6 +388,59 @@ function getStore(cwd) {
     const config = loadConfig(cwd);
     return createStore({ storePath: config.store_path ?? '.slope/slope.db', cwd });
 }
+function roadmapTicketKeysForSprint(cwd, sprintId) {
+    if (!sprintId)
+        return [];
+    const sprintNumber = parseSprintNumber(sprintId);
+    if (sprintNumber === null)
+        return [];
+    const config = loadConfig(cwd);
+    if (!config.roadmapPath)
+        return [];
+    const roadmapPath = join(cwd, config.roadmapPath);
+    if (!existsSync(roadmapPath))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(roadmapPath, 'utf8'));
+        const parsed = parseRoadmap(raw);
+        const roadmap = parsed.roadmap ?? castRoadmapStructure(raw);
+        const sprint = roadmap?.sprints.find(s => s.id === sprintNumber);
+        return sprint?.tickets.map(t => t.key).filter(Boolean) ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function applyWorkflowVariableDefaults(def, vars, cwd, sprintId) {
+    if (sprintId && !('sprint_id' in vars)) {
+        vars.sprint_id = sprintId;
+    }
+    const ticketsSpec = def.variables?.tickets;
+    if (ticketsSpec?.required && !('tickets' in vars)) {
+        const tickets = roadmapTicketKeysForSprint(cwd, sprintId);
+        if (tickets.length > 0) {
+            vars.tickets = tickets.join(',');
+        }
+    }
+}
+function positionalSprintArg(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--var') {
+            i++;
+            continue;
+        }
+        if (!arg.startsWith('--'))
+            return arg;
+    }
+    return undefined;
+}
+function sprintIdFromRunArgs(args) {
+    const sprintFlag = args.find(a => a.startsWith('--sprint='));
+    if (sprintFlag)
+        return sprintFlag.slice('--sprint='.length);
+    return positionalSprintArg(args);
+}
 const SPRINT_PHASE_ORDER = {
     planning: 0,
     reviewing: 1,
@@ -437,7 +493,7 @@ function syncSprintStateWithWorkflow(cwd, sprintId, workflowPhase) {
     });
 }
 async function runWorkflowCommand(args, cwd) {
-    const sprintArg = args.find(a => a.startsWith('--sprint=') || !a.startsWith('--'));
+    const explicitSprintId = sprintIdFromRunArgs(args);
     const workflowArg = args.find(a => a.startsWith('--workflow='));
     const varArgs = [];
     for (let i = 0; i < args.length; i++) {
@@ -453,12 +509,11 @@ async function runWorkflowCommand(args, cwd) {
         console.error('Usage: slope sprint run <sprint_id> --workflow=<name> [--var key=value ...]');
         process.exit(1);
     }
-    const sprintId = sprintArg?.startsWith('--') ? undefined : sprintArg;
     const workflowName = workflowArg.slice('--workflow='.length);
     // Parse variables
     const vars = {};
-    if (sprintId)
-        vars.sprint_id = sprintId;
+    if (explicitSprintId)
+        vars.sprint_id = explicitSprintId;
     for (const v of varArgs) {
         const kv = v.slice('--var='.length);
         const eq = kv.indexOf('=');
@@ -466,6 +521,7 @@ async function runWorkflowCommand(args, cwd) {
             vars[kv.slice(0, eq)] = kv.slice(eq + 1);
         }
     }
+    const sprintId = explicitSprintId ?? vars.sprint_id;
     // Load and validate workflow
     const def = loadWorkflow(workflowName, cwd);
     const validation = validateWorkflow(def);
@@ -476,6 +532,7 @@ async function runWorkflowCommand(args, cwd) {
         }
         process.exit(1);
     }
+    applyWorkflowVariableDefaults(def, vars, cwd, sprintId);
     // Resolve variables
     const resolved = resolveVariables(def, vars);
     // Start execution
@@ -513,8 +570,9 @@ async function runWorkflowCommand(args, cwd) {
 }
 async function workflowStatusCommand(args, cwd) {
     const sprintArg = args.find(a => !a.startsWith('--'));
-    const store = getStore(cwd);
+    let store = null;
     try {
+        store = getStore(cwd);
         if (sprintArg) {
             const exec = await store.getExecutionBySprint(sprintArg);
             if (!exec) {
@@ -536,60 +594,45 @@ async function workflowStatusCommand(args, cwd) {
             }
         }
     }
-    finally {
-        store.close();
-    }
-}
-function completedRoadmapSprintIds(cwd, config) {
-    if (!config.roadmapPath)
-        return new Set();
-    const roadmapPath = join(cwd, config.roadmapPath);
-    if (!existsSync(roadmapPath))
-        return new Set();
-    try {
-        const raw = JSON.parse(readFileSync(roadmapPath, 'utf8'));
-        const parsed = parseRoadmap(raw);
-        const roadmap = parsed.roadmap ?? castRoadmapStructure(raw);
-        if (!roadmap)
-            return new Set();
-        return new Set(roadmap.sprints
-            .filter(sprint => {
-            const status = sprint.status;
-            return status === 'complete' || status === 'superseded';
-        })
-            .map(sprint => sprint.id));
-    }
-    catch {
-        return new Set();
-    }
-}
-async function findStaleWorkflowExecutions(cwd, store) {
-    const config = loadConfig(cwd);
-    const scorecardSprintIds = new Set(loadScorecards(config, cwd).map(card => card.sprint_number));
-    const roadmapDoneIds = completedRoadmapSprintIds(cwd, config);
-    const running = await store.listExecutions({ status: 'running' });
-    const stale = [];
-    for (const exec of running) {
-        const sprint = sprintNumberFromId(exec.sprint_id);
-        if (sprint === null)
-            continue;
-        const reasons = [];
-        if (scorecardSprintIds.has(sprint))
-            reasons.push('scorecard exists');
-        if (roadmapDoneIds.has(sprint))
-            reasons.push('roadmap complete/superseded');
-        if (reasons.length > 0) {
-            stale.push({ exec, reason: reasons.join(', ') });
+    catch (err) {
+        for (const line of formatCliError(err, cwd)) {
+            console.error(line);
         }
+        process.exitCode = 1;
+    }
+    finally {
+        store?.close();
     }
-    return stale;
 }
 async function workflowCleanupCommand(args, cwd) {
     const action = args[0];
     const dryRun = args.includes('--dry-run');
     const staleOnly = args.includes('--stale');
+    const resync = action === 'resync';
+    if (resync) {
+        const store = getStore(cwd);
+        try {
+            const result = await reconcileWorkflowExecutions(cwd, store);
+            for (const { exec, reason } of result.paused) {
+                console.log(`Paused ${exec.sprint_id ?? exec.id} (${exec.workflow_name}) at ${exec.current_phase}/${exec.current_step} — ${reason}`);
+            }
+            for (const item of result.fastForwarded) {
+                console.log(`Fast-forwarded ${item.exec.sprint_id ?? item.exec.id} (${item.exec.workflow_name}) to ${item.phase}/${item.step} — ${item.reason}`);
+            }
+            if (result.paused.length === 0 && result.fastForwarded.length === 0) {
+                console.log('Workflow state already matches git/roadmap reality.');
+            }
+            else {
+                console.log(`\nResynced workflow state: ${result.paused.length} paused, ${result.fastForwarded.length} fast-forwarded.`);
+            }
+        }
+        finally {
+            store.close();
+        }
+        return;
+    }
     if (action !== 'cleanup' || !staleOnly) {
-        console.error('Usage: slope sprint workflow cleanup --stale [--dry-run]');
+        console.error('Usage: slope sprint workflow cleanup --stale [--dry-run]\n       slope sprint workflow resync');
         process.exit(1);
     }
     const store = getStore(cwd);
@@ -629,7 +672,184 @@ function printExecution(exec) {
     console.log(`  Started:   ${exec.started_at}`);
     console.log('');
 }
+function shouldUsePortableResume(args) {
+    return args.includes('--portable')
+        || args.includes('--write-pointer')
+        || args.includes('--dry-run')
+        || args.some(a => a.startsWith('--from=') || a.startsWith('--sprint=') || a.startsWith('--phase=') || a.startsWith('--output='));
+}
+function parsePortableResumeFlags(args) {
+    const flags = {
+        portable: args.includes('--portable'),
+        writePointer: args.includes('--write-pointer'),
+        force: args.includes('--force'),
+        dryRun: args.includes('--dry-run'),
+    };
+    for (const arg of args) {
+        if (arg.startsWith('--sprint=')) {
+            const raw = arg.slice('--sprint='.length);
+            const sprint = parseSprintNumber(raw);
+            if (sprint)
+                flags.sprint = sprint;
+            else
+                flags.invalidSprint = raw;
+        }
+        else if (arg.startsWith('--phase=')) {
+            const phase = arg.slice('--phase='.length);
+            if (isSprintPhase(phase))
+                flags.phase = phase;
+            else
+                flags.invalidPhase = phase;
+        }
+        else if (arg.startsWith('--from=')) {
+            flags.from = arg.slice('--from='.length);
+        }
+        else if (arg.startsWith('--output=')) {
+            flags.output = arg.slice('--output='.length);
+        }
+    }
+    return flags;
+}
+async function portableResumeCommand(args, cwd) {
+    const flags = parsePortableResumeFlags(args);
+    const config = loadConfig(cwd);
+    if (flags.invalidSprint) {
+        console.error(`Error: invalid sprint "${flags.invalidSprint}". Use --sprint=N, e.g. --sprint=177.`);
+        process.exit(1);
+        return;
+    }
+    if (flags.invalidPhase) {
+        console.error(`Error: invalid phase "${flags.invalidPhase}". Valid phases: ${SPRINT_PHASES.join(', ')}`);
+        process.exit(1);
+        return;
+    }
+    if (flags.writePointer) {
+        const current = loadSprintState(cwd);
+        const sprint = flags.sprint ?? current?.sprint;
+        if (!sprint) {
+            console.error('Usage: slope sprint resume --write-pointer --sprint=N [--phase=<phase>] [--output=path]');
+            process.exit(1);
+            return;
+        }
+        const phase = flags.phase ?? current?.phase ?? 'implementing';
+        const resumeClaims = await collectResumeClaimPointers(cwd, sprint);
+        const pointer = buildSprintResumePointer(cwd, config, { sprint, phase, resumeClaims });
+        const outputPath = flags.output ? (isAbsolute(flags.output) ? flags.output : join(cwd, flags.output)) : undefined;
+        const written = writeSprintResumePointer(cwd, pointer, outputPath);
+        console.log(`Sprint resume pointer written: ${written}`);
+        console.log(`  Sprint: ${formatSprintLabel(sprint)} (${phase})`);
+        console.log(`  Resume claims: ${resumeClaims.length}`);
+        console.log('  Local runtime state excluded: slope.db, session locks, guard metrics, baselines');
+        return;
+    }
+    const plan = planPortableSprintResume(cwd, config, {
+        sprint: flags.sprint,
+        phase: flags.phase,
+        from: flags.from,
+        force: flags.force,
+    });
+    printPortableResumePlan(plan);
+    if (plan.unsafe.length > 0 && !flags.force) {
+        console.error('\nPortable resume refused. Rerun with --force after reviewing the unsafe condition(s).');
+        process.exit(1);
+        return;
+    }
+    const existing = loadSprintState(cwd);
+    if (existing && existing.sprint !== plan.sprint && !flags.force) {
+        console.error(`\nPortable resume refused. Local sprint-state is ${formatSprintLabel(existing.sprint)}, but resume target is ${formatSprintLabel(plan.sprint)}.`);
+        console.error('Run `slope sprint reset` or rerun with --force if replacing local state is intentional.');
+        process.exit(1);
+        return;
+    }
+    if (flags.dryRun) {
+        console.log('\nDry run: local sprint-state and claims were not changed.');
+        return;
+    }
+    saveSprintState(cwd, createSprintState(plan.sprint, plan.phase));
+    const restoredClaims = await restoreResumeClaims(cwd, plan);
+    console.log(`\nPortable sprint resume complete: ${formatSprintLabel(plan.sprint)} (${plan.phase}).`);
+    console.log(`  Fresh local sprint-state written to .slope/sprint-state.json`);
+    console.log(`  Resume claims restored: ${restoredClaims}`);
+    console.log('  Local DB/locks/metrics were not imported from another machine.');
+}
+function printPortableResumePlan(plan) {
+    console.log('\nPortable sprint resume plan');
+    console.log('='.repeat(32));
+    console.log(`  Sprint: ${formatSprintLabel(plan.sprint)}`);
+    console.log(`  Phase:  ${plan.phase}`);
+    console.log(`  Source: ${plan.source}${plan.pointerPath ? ` (${plan.pointerPath})` : ''}`);
+    if (plan.currentBranch)
+        console.log(`  Branch: ${plan.currentBranch}`);
+    if (plan.headCommit)
+        console.log(`  HEAD:   ${plan.headCommit.slice(0, 12)}`);
+    const evidence = Object.entries(plan.evidence);
+    if (evidence.length > 0) {
+        console.log('  Evidence:');
+        for (const [label, value] of evidence) {
+            console.log(`    - ${label}: ${value}`);
+        }
+    }
+    if (plan.resumeClaims.length > 0) {
+        console.log('  Resume claims:');
+        for (const claim of plan.resumeClaims) {
+            console.log(`    - ${claim.id} (${claim.scope ?? 'ticket'}, ${claim.state})${claim.last_evidence ? ` via ${claim.last_evidence}` : ''}`);
+        }
+    }
+    if (plan.unsafe.length > 0) {
+        console.log('  Unsafe conditions:');
+        for (const item of plan.unsafe)
+            console.log(`    - ${item}`);
+    }
+}
+async function collectResumeClaimPointers(cwd, sprint) {
+    const { resolveStore } = await import('../store.js');
+    const store = await resolveStore(cwd);
+    try {
+        const claims = await store.list(sprint);
+        return claims.map(claim => ({
+            id: claim.target,
+            state: 'in_progress',
+            scope: claim.scope,
+            last_evidence: claim.notes,
+        }));
+    }
+    finally {
+        store.close();
+    }
+}
+async function restoreResumeClaims(cwd, plan) {
+    const claims = plan.resumeClaims.filter(claim => claim.state !== 'done');
+    if (claims.length === 0)
+        return 0;
+    const { resolveStore } = await import('../store.js');
+    const store = await resolveStore(cwd);
+    const player = process.env.USER || 'unknown';
+    let restored = 0;
+    try {
+        const existing = await store.list(plan.sprint);
+        for (const claim of claims) {
+            if (existing.some(c => c.target === claim.id && c.player === player))
+                continue;
+            await store.claim({
+                sprint_number: plan.sprint,
+                player,
+                target: claim.id,
+                scope: claim.scope ?? 'ticket',
+                notes: claim.last_evidence ? `portable resume: ${claim.last_evidence}` : 'portable resume',
+            });
+            restored++;
+        }
+    }
+    finally {
+        store.close();
+    }
+    return restored;
+}
 async function resumeCommand(args, cwd) {
+    if (shouldUsePortableResume(args)) {
+        await portableResumeCommand(args, cwd);
+        return;
+    }
     const sprintArg = args.find(a => !a.startsWith('--'));
     if (!sprintArg) {
         console.error('Usage: slope sprint resume <sprint_id>');
@@ -875,6 +1095,10 @@ async function validateSprintCommand(args, cwd) {
 export async function sprintCommand(args) {
     const cwd = process.cwd();
     const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        printSprintUsage();
+        return;
+    }
     switch (sub) {
         case 'start':
             await startCommand(args.slice(1), cwd);
@@ -896,9 +1120,19 @@ export async function sprintCommand(args) {
         case 'status':
             await workflowStatusCommand(args.slice(1), cwd);
             break;
-        case 'reset':
+        case 'reset': {
+            const resetArgs = args.slice(1);
+            if (resetArgs.includes('--help') || resetArgs.includes('-h')) {
+                printSprintUsage();
+                break;
+            }
+            if (resetArgs.length > 0) {
+                printSprintUsage();
+                process.exit(1);
+            }
             resetCommand(cwd);
             break;
+        }
         case 'run':
             await runWorkflowCommand(args.slice(1), cwd);
             break;
@@ -921,7 +1155,13 @@ export async function sprintCommand(args) {
             await validateSprintCommand(args.slice(1), cwd);
             break;
         default:
-            console.log(`
+            printSprintUsage();
+            process.exit(1);
+            break;
+    }
+}
+function printSprintUsage() {
+    console.log(`
 slope sprint — Sprint lifecycle management
 
 Legacy commands:
@@ -932,6 +1172,10 @@ Legacy commands:
   slope sprint phase <phase>       Update current sprint phase
   slope sprint gate <name>           Mark a gate as complete
   slope sprint status                Show sprint state and gates
+  slope sprint resume --portable [--from=path] [--force] [--dry-run]
+                                      Reconstruct local sprint state from tracked artifacts
+  slope sprint resume --write-pointer [--output=path]
+                                      Write tracked resume pointer without syncing DB/locks
   slope sprint reset                 Clear sprint state
 
 Workflow commands:
@@ -939,12 +1183,11 @@ Workflow commands:
   slope sprint status [sprint_id]    Show workflow execution progress
   slope sprint resume <sprint_id>    Resume a paused workflow execution
   slope sprint pause <sprint_id>     Pause a running workflow execution
+  slope sprint context <sprint_id>   Show current workflow step and remaining work
+  slope sprint validate <sprint_id>  Validate workflow, plan, scorecard, and tests
   slope sprint workflow cleanup --stale [--dry-run]         Pause stale completed/superseded executions
+  slope sprint workflow resync       Reconcile workflow executions with git/roadmap reality
   slope sprint skip <id> --step=<s> --reason="..."          Skip a blocking step
 `);
-            if (sub)
-                process.exit(1);
-            break;
-    }
 }
 //# sourceMappingURL=sprint.js.map