@slope-dev/slope 1.59.2 → 1.61.0

package/dist/cli/commands/sprint.js

@@ -1,6 +1,8 @@
-import { loadSprintState, saveSprintState, createSprintState, mutateSprintState, updateGate, updateSprintPhase, clearSprintState, isSprintComplete, pendingGates, isSprintPhase, SPRINT_PHASES, } from '../sprint-state.js';
+import { loadSprintState, loadSprintStateResult, createSprintState, initializeSprintState, mutateSprintState, updateGate, updateSprintPhase, updateSprintPhaseForSprint, clearSprintState, isSprintComplete, isReviewGateSatisfied, isRequiredReviewGate, waivedReviewGateNames, pendingGateNames, pendingGates, isSprintPhase, isReviewGateName, validateReviewGateCompletion, SPRINT_PHASES, } from '../sprint-state.js';
 import { WorkflowEngine, loadWorkflow, resolveVariables, validateWorkflow, loadConfig, parseRoadmap, castRoadmapStructure, formatSprintLabel, formatSprintNumber, parseSprintNumber } from '../../core/index.js';
 import { createHash } from 'node:crypto';
+import { formatActorName, formatActorSource, formatConflictSummary, resolveActor } from '../actor.js';
+import { inspectSprintRollover, performSprintRollover, SprintRolloverError, verifySprintRolloverLineage, } from '../sprint-rollover.js';
 /** Get workflow definition from execution snapshot (preferred) or disk (fallback for old executions) */
 function getDefinition(exec, cwd) {
     // Prefer snapshot from execution
@@ -20,12 +22,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, isAbsolute } from 'node:path';
+import { join, dirname, basename, isAbsolute, relative } 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';
+import { findStaleWorkflowExecutions, reconcileWorkflowExecutions, sprintLabelForExecution } 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.
@@ -67,6 +69,358 @@ function checkCompletionConditions(stepId, def, currentPhase, cwd) {
     return null;
 }
 const VALID_GATES = ['tests', 'code_review', 'architect_review', 'scorecard', 'review_md'];
+function optionValue(args, index, flag) {
+    const arg = args[index];
+    if (arg.startsWith(`${flag}=`))
+        return { value: arg.slice(flag.length + 1), next: index };
+    if (arg === flag)
+        return { value: args[index + 1] ?? null, next: index + 1 };
+    return null;
+}
+function findOptionValue(args, flag) {
+    for (let i = 0; i < args.length; i++) {
+        const value = optionValue(args, i, flag);
+        if (value)
+            return value.value ?? undefined;
+    }
+    return undefined;
+}
+function actorOverride(args) {
+    for (const flag of ['--actor', '--player']) {
+        const value = findOptionValue(args, flag);
+        if (value && !value.startsWith('--'))
+            return value;
+    }
+    return undefined;
+}
+function parseGateOptions(args) {
+    const errors = [];
+    const evidence = [];
+    let reviewer;
+    let prReview;
+    let selfReview = false;
+    let waiveIndependentReview = false;
+    let notes;
+    let reason;
+    let overrideReason;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        const evidenceValue = optionValue(args, i, '--evidence');
+        if (evidenceValue) {
+            if (!evidenceValue.value || evidenceValue.value.startsWith('--'))
+                errors.push('--evidence requires a value');
+            else
+                evidence.push(evidenceValue.value);
+            i = evidenceValue.next;
+            continue;
+        }
+        const reviewerValue = optionValue(args, i, '--reviewer');
+        if (reviewerValue) {
+            if (!reviewerValue.value || reviewerValue.value.startsWith('--'))
+                errors.push('--reviewer requires a value');
+            else
+                reviewer = reviewerValue.value;
+            i = reviewerValue.next;
+            continue;
+        }
+        const prReviewValue = optionValue(args, i, '--pr-review');
+        if (prReviewValue) {
+            if (!prReviewValue.value || prReviewValue.value.startsWith('--'))
+                errors.push('--pr-review requires a value');
+            else
+                prReview = prReviewValue.value;
+            i = prReviewValue.next;
+            continue;
+        }
+        if (arg === '--self-review') {
+            selfReview = true;
+            continue;
+        }
+        if (arg === '--waive-independent-review') {
+            waiveIndependentReview = true;
+            continue;
+        }
+        const reasonValue = optionValue(args, i, '--reason');
+        if (reasonValue) {
+            if (!reasonValue.value || reasonValue.value.startsWith('--'))
+                errors.push('--reason requires a value');
+            else
+                reason = reasonValue.value;
+            i = reasonValue.next;
+            continue;
+        }
+        const notesValue = optionValue(args, i, '--notes');
+        if (notesValue) {
+            if (!notesValue.value || notesValue.value.startsWith('--'))
+                errors.push('--notes requires a value');
+            else
+                notes = notesValue.value;
+            i = notesValue.next;
+            continue;
+        }
+        const overrideValue = optionValue(args, i, '--override') ?? optionValue(args, i, '--manual-override');
+        if (overrideValue) {
+            if (!overrideValue.value || overrideValue.value.startsWith('--'))
+                errors.push('--override requires a value');
+            else
+                overrideReason = overrideValue.value;
+            i = overrideValue.next;
+            continue;
+        }
+        errors.push(`Unknown gate option: ${arg}`);
+    }
+    const hasPrReview = Boolean(prReview);
+    const hasSelfReview = selfReview;
+    const hasWaiver = waiveIndependentReview;
+    const hasOverride = Boolean(overrideReason);
+    const hasIndependent = !hasPrReview && !hasSelfReview && !hasWaiver && !hasOverride && (Boolean(reviewer) || evidence.length > 0);
+    const modeCount = [hasPrReview, hasSelfReview, hasWaiver, hasOverride, hasIndependent].filter(Boolean).length;
+    if (modeCount > 1) {
+        errors.push('Use only one review provenance mode: --reviewer/--evidence, --pr-review, --self-review, --waive-independent-review, or --override.');
+    }
+    let review;
+    if (modeCount === 1) {
+        if (hasPrReview) {
+            review = { provenance: 'pr_review', evidence: [prReview, ...evidence], reviewer, notes: notes ?? reason };
+        }
+        else if (hasSelfReview) {
+            review = { provenance: 'self_review', evidence, reviewer, notes: reason ?? notes };
+        }
+        else if (hasWaiver) {
+            review = { provenance: 'independent_review_waived', evidence, reviewer, notes: reason ?? notes };
+        }
+        else if (hasOverride) {
+            review = { provenance: 'manual_override', evidence, reviewer, notes: overrideReason };
+        }
+        else {
+            review = { provenance: 'independent_review', evidence, reviewer, notes: notes ?? reason };
+        }
+    }
+    return { review, errors, help };
+}
+function printGateUsage(gateName) {
+    const gate = gateName && isReviewGateName(gateName) ? gateName : 'code_review';
+    console.error('');
+    console.error('Usage:');
+    console.error('  slope sprint gate <name>');
+    console.error(`  slope sprint gate ${gate} --reviewer=<agent-or-person> --evidence=<transcript-or-output>`);
+    console.error(`  slope sprint gate ${gate} --pr-review=<url-or-id>`);
+    console.error(`  slope sprint gate ${gate} --self-review --reason="why self-review is acceptable"`);
+    console.error(`  slope sprint gate ${gate} --waive-independent-review --reason="why the required independent review is being waived"`);
+    console.error(`  slope sprint gate ${gate} --override="manual override reason"`);
+    console.error('');
+    console.error('Review provenance modes:');
+    console.error('  independent_review: requires --reviewer and --evidence');
+    console.error('  pr_review: records external PR review evidence from --pr-review');
+    console.error('  self_review (weaker): requires --self-review and --reason');
+    console.error('  independent_review_waived: explicit waiver for a required review; requires --waive-independent-review and --reason');
+    console.error('  manual_override (weaker): requires --override');
+    console.error('');
+}
+function commandValue(value) {
+    if (/^[A-Za-z0-9._:/-]+$/.test(value))
+        return value;
+    return process.platform === 'win32'
+        ? `'${value.replaceAll("'", "''")}'`
+        : `'${value.replaceAll("'", `'"'"'`)}`;
+}
+function actorRetryOption(args) {
+    for (const flag of ['--actor', '--player']) {
+        const value = findOptionValue(args, flag);
+        if (value)
+            return `${flag}=${commandValue(value)}`;
+    }
+    return null;
+}
+function commandOptionErrors(args, valueFlags, booleanFlags = []) {
+    const errors = [];
+    const seen = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        let matched = false;
+        for (const flag of valueFlags) {
+            const value = optionValue(args, index, flag);
+            if (!value)
+                continue;
+            matched = true;
+            if (seen.has(flag))
+                errors.push(`${flag} may only be provided once`);
+            seen.add(flag);
+            if (!value.value || value.value.startsWith('--'))
+                errors.push(`${flag} requires a value`);
+            index = value.next;
+            break;
+        }
+        if (matched)
+            continue;
+        if (booleanFlags.includes(arg)) {
+            if (seen.has(arg))
+                errors.push(`${arg} may only be provided once`);
+            seen.add(arg);
+            continue;
+        }
+        errors.push(`Unknown option: ${arg}`);
+    }
+    if (seen.has('--actor') && seen.has('--player')) {
+        errors.push('Use only one actor identity flag: --actor or --player');
+    }
+    return errors;
+}
+function rolloverFlagValue(label) {
+    return label.startsWith('S') ? label.slice(1) : label;
+}
+function rolloverBaseCommand(assessment) {
+    return `slope sprint rollover --from=${rolloverFlagValue(assessment.from_label)} --to=${rolloverFlagValue(assessment.to_label)}`;
+}
+/**
+ * Return true when the requested sprint is the existing sprint, including a
+ * roadmap-aware legacy alias. Otherwise print bounded recovery guidance and
+ * terminate without mutating local state.
+ */
+function requireMatchingSprintOrRollover(cwd, state, requestedSprint, action, retryCommand) {
+    try {
+        verifySprintRolloverLineage(cwd, state);
+    }
+    catch (error) {
+        console.error(`Refusing to ${action}: ${error.message}`);
+        console.error(`After restoring the tracked rollover audit, retry: ${retryCommand}`);
+        process.exit(1);
+    }
+    if (state.sprint === requestedSprint)
+        return true;
+    let assessment;
+    try {
+        assessment = inspectSprintRollover(cwd, { from: state.sprint, to: requestedSprint });
+    }
+    catch (error) {
+        console.error(`Refusing to ${action}: ${error.message}`);
+        console.error(`After resolving the sprint state, retry: ${retryCommand}`);
+        process.exit(1);
+    }
+    if (assessment.from_sprint && assessment.to_sprint && assessment.from === assessment.to)
+        return true;
+    console.error(`Refusing to ${action} — sprint-state.json is for ${assessment.from_label}, not ${assessment.to_label}.`);
+    const eligibilityIssues = assessment.issues.filter(issue => issue.code !== 'from_not_terminal');
+    if (eligibilityIssues.length === 0) {
+        const command = assessment.from_terminal
+            ? rolloverBaseCommand(assessment)
+            : `${rolloverBaseCommand(assessment)} --force --reason="<why>"`;
+        console.error(`Record the prior state with: ${command}`);
+    }
+    else {
+        console.error('Rollover is not currently eligible:');
+        for (const issue of eligibilityIssues)
+            console.error(`  - ${issue.message}`);
+    }
+    console.error(`After resolving the rollover, retry: ${retryCommand}`);
+    process.exit(1);
+}
+function failOnCorruptSprintState(cwd) {
+    const loaded = loadSprintStateResult(cwd);
+    if (loaded.status !== 'corrupt')
+        return;
+    console.error(`Refusing to change sprint state: corrupt evidence was preserved at ${relative(cwd, loaded.path)}.`);
+    process.exit(1);
+}
+function printRolloverUsage() {
+    console.error('');
+    console.error('Usage: slope sprint rollover --from=N --to=N [--force --reason="<why>"]');
+    console.error('Safely archives the prior local state in a tracked audit before creating the next planning state.');
+    console.error('');
+}
+function rolloverCommand(args, cwd) {
+    if (args.includes('--help') || args.includes('-h')) {
+        printRolloverUsage();
+        return;
+    }
+    let fromValue;
+    let toValue;
+    let reason;
+    let force = false;
+    const errors = [];
+    const seen = new Set();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        const from = optionValue(args, index, '--from');
+        if (from) {
+            if (seen.has('--from'))
+                errors.push('--from may only be provided once');
+            seen.add('--from');
+            if (!from.value || from.value.startsWith('--'))
+                errors.push('--from requires a sprint id');
+            else
+                fromValue = from.value;
+            index = from.next;
+            continue;
+        }
+        const to = optionValue(args, index, '--to');
+        if (to) {
+            if (seen.has('--to'))
+                errors.push('--to may only be provided once');
+            seen.add('--to');
+            if (!to.value || to.value.startsWith('--'))
+                errors.push('--to requires a sprint id');
+            else
+                toValue = to.value;
+            index = to.next;
+            continue;
+        }
+        const parsedReason = optionValue(args, index, '--reason');
+        if (parsedReason) {
+            if (seen.has('--reason'))
+                errors.push('--reason may only be provided once');
+            seen.add('--reason');
+            if (!parsedReason.value || parsedReason.value.startsWith('--'))
+                errors.push('--reason requires a non-empty value');
+            else
+                reason = parsedReason.value;
+            index = parsedReason.next;
+            continue;
+        }
+        if (arg === '--force') {
+            if (seen.has('--force'))
+                errors.push('--force may only be provided once');
+            seen.add('--force');
+            force = true;
+            continue;
+        }
+        errors.push(`Unknown rollover option: ${arg}`);
+    }
+    const from = fromValue ? parseSprintNumber(fromValue) : null;
+    const to = toValue ? parseSprintNumber(toValue) : null;
+    if (from == null)
+        errors.push('--from must be a positive sprint id');
+    if (to == null)
+        errors.push('--to must be a positive sprint id');
+    if (reason && !force)
+        errors.push('--reason is only valid with --force');
+    if (errors.length > 0) {
+        for (const error of errors)
+            console.error(`Error: ${error}`);
+        printRolloverUsage();
+        process.exit(1);
+    }
+    try {
+        const result = performSprintRollover(cwd, { from: from, to: to, force, reason }, resolveActor(cwd));
+        console.log(`${result.already_applied ? 'Rollover already recorded' : 'Rollover recorded'}: ${result.record.from_label} -> ${result.record.to_label}.`);
+        console.log(`Audit: ${result.audit_path}`);
+        console.log(`Sprint ${rolloverFlagValue(result.record.to_label)} state is ready (phase: ${result.state.phase}).`);
+        console.log('Prior state archived; claims and sessions unchanged.');
+        console.log(`Next: slope sprint begin --sprint=${rolloverFlagValue(result.record.to_label)} --ticket=<key>`);
+    }
+    catch (error) {
+        if (error instanceof SprintRolloverError) {
+            console.error(`Rollover refused: ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+}
 /**
  * `slope sprint begin --sprint=N --ticket=T` — bundled start-of-work flow.
  *
@@ -79,44 +433,48 @@ const VALID_GATES = ['tests', 'code_review', 'architect_review', 'scorecard', 'r
  *   6. Print recommended next implementation step
  */
 async function beginCommand(args, cwd) {
-    const sprintArg = args.find(a => a.startsWith('--sprint='));
-    const ticketArg = args.find(a => a.startsWith('--ticket='));
-    if (!sprintArg || !ticketArg) {
-        console.error('\nUsage: slope sprint begin --sprint=N --ticket=KEY');
+    const optionErrors = commandOptionErrors(args, ['--sprint', '--ticket', '--actor', '--player']);
+    const sprintValue = findOptionValue(args, '--sprint');
+    const ticketValue = findOptionValue(args, '--ticket');
+    if (optionErrors.length > 0 || !sprintValue || !ticketValue) {
+        for (const error of optionErrors)
+            console.error(`Error: ${error}`);
+        console.error('\nUsage: slope sprint begin --sprint=N --ticket=KEY [--actor=<name>]');
         console.error('Bundles: sprint start + claim + briefing + prep --lite\n');
         process.exit(1);
     }
-    const sprint = parseSprintNumber(sprintArg.split('=')[1]);
-    const ticket = ticketArg.split('=')[1];
+    const sprint = parseSprintNumber(sprintValue);
+    const ticket = ticketValue;
     if (!sprint || !ticket) {
         console.error('Error: --sprint must be a positive sprint id; --ticket must be a non-empty key');
         process.exit(1);
     }
-    // Step 1: sprint state
-    let state = loadSprintState(cwd);
-    if (state && state.sprint === sprint) {
-        console.log(`Sprint ${formatSprintNumber(sprint)}: already started (phase: ${state.phase}).`);
-    }
-    else if (state && state.sprint !== sprint) {
-        console.error(`Refusing to begin S${formatSprintNumber(sprint)} — sprint-state.json is for S${formatSprintNumber(state.sprint)}.`);
-        console.error('Run `slope sprint reset` first if the previous sprint is done.');
+    // Step 1: initialize without overwriting existing or corrupt local state.
+    const initialized = initializeSprintState(cwd, createSprintState(sprint, 'planning'));
+    if (initialized.status === 'corrupt') {
+        console.error(`Refusing to begin: corrupt sprint evidence was preserved at ${relative(cwd, initialized.path)}.`);
         process.exit(1);
     }
+    let state = initialized.state;
+    const retryActor = actorRetryOption(args);
+    if (initialized.status === 'existing' && requireMatchingSprintOrRollover(cwd, state, sprint, `begin ${formatSprintLabel(sprint)}`, `slope sprint begin --sprint=${formatSprintNumber(sprint)} --ticket=${commandValue(ticket)}${retryActor ? ` ${retryActor}` : ''}`)) {
+        console.log(`Sprint ${formatSprintNumber(sprint)}: already started (phase: ${state.phase}).`);
+    }
     else {
-        state = createSprintState(sprint, 'planning');
-        saveSprintState(cwd, state);
         console.log(`Sprint ${formatSprintNumber(sprint)}: started (phase: planning).`);
     }
     // Step 2: claim
     const { resolveStore } = await import('../store.js');
     const { checkConflicts } = await import('../../core/index.js');
-    const player = process.env.USER || 'unknown';
+    const actor = resolveActor(cwd, { explicitActor: actorOverride(args) });
+    const player = actor.name;
+    const playerDisplay = formatActorName(actor);
     const store = await resolveStore(cwd);
     try {
         const existing = await store.list(sprint);
         const ownClaim = existing.find(c => c.target === ticket && c.player === player);
         if (ownClaim) {
-            console.log(`Ticket ${ticket}: already claimed by ${player}.`);
+            console.log(`Ticket ${ticket}: already claimed by ${playerDisplay} (actor source: ${formatActorSource(actor)}).`);
         }
         else {
             // Detect overlap conflicts via core check
@@ -132,12 +490,12 @@ async function beginCommand(args, cwd) {
             if (overlaps.length > 0) {
                 console.error(`\nClaim blocked — overlap conflict(s) detected:`);
                 for (const c of overlaps)
-                    console.error(`  [!!] ${c.reason}`);
+                    console.error(`  [!!] ${formatConflictSummary(c)}`);
                 console.error(`\nResolve conflicts or run \`slope claim --target=${ticket} --sprint=${formatSprintNumber(sprint)} --force\` to override.`);
                 process.exit(1);
             }
             const claim = await store.claim({ sprint_number: sprint, player, target: ticket, scope: 'ticket' });
-            console.log(`Ticket ${ticket}: claimed (id ${claim.id.slice(0, 8)}, player ${player}).`);
+            console.log(`Ticket ${ticket}: claimed (id ${claim.id.slice(0, 8)}, player ${playerDisplay}, actor source: ${formatActorSource(actor)}).`);
         }
     }
     finally {
@@ -195,30 +553,47 @@ async function beginCommand(args, cwd) {
     console.log('');
 }
 async function startCommand(args, cwd) {
-    const numberArg = args.find(a => a.startsWith('--number='));
-    if (!numberArg) {
+    const optionErrors = commandOptionErrors(args, ['--number', '--phase', '--touches', '--actor', '--player'], ['--force']);
+    const numberValue = findOptionValue(args, '--number');
+    if (optionErrors.length > 0 || !numberValue) {
+        for (const error of optionErrors)
+            console.error(`Error: ${error}`);
         console.error('Error: --number=N is required. Usage: slope sprint start --number=22');
         process.exit(1);
     }
-    const sprint = parseSprintNumber(numberArg.slice('--number='.length));
+    const sprint = parseSprintNumber(numberValue);
     if (!sprint) {
         console.error('Error: --number must be a positive sprint id, e.g. 114 or 114.5.');
         process.exit(1);
     }
-    const phaseArg = args.find(a => a.startsWith('--phase='));
-    const phaseInput = phaseArg?.slice('--phase='.length) ?? 'planning';
+    const phaseValue = findOptionValue(args, '--phase');
+    const phaseInput = phaseValue ?? 'planning';
     if (!isSprintPhase(phaseInput)) {
         console.error(`Error: invalid phase "${phaseInput}". Valid phases: ${SPRINT_PHASES.join(', ')}`);
         process.exit(1);
     }
     const phase = phaseInput;
     const force = args.includes('--force');
-    const touchesArg = args.find(a => a.startsWith('--touches='));
-    const touchedPaths = parseTouchedPaths(touchesArg?.slice('--touches='.length));
-    const existing = loadSprintState(cwd);
-    if (existing && existing.sprint === sprint) {
-        if (phaseArg && existing.phase !== phase) {
-            updateSprintPhase(cwd, phase);
+    const touchedPaths = parseTouchedPaths(findOptionValue(args, '--touches'));
+    const retryActor = actorRetryOption(args);
+    const retryTouches = findOptionValue(args, '--touches');
+    const retryExtras = [
+        ...(retryTouches ? [`--touches=${commandValue(retryTouches)}`] : []),
+        ...(retryActor ? [retryActor] : []),
+        ...(force ? ['--force'] : []),
+    ];
+    const retryStart = `slope sprint start --number=${formatSprintNumber(sprint)} --phase=${phase}${retryExtras.length > 0 ? ` ${retryExtras.join(' ')}` : ''}`;
+    failOnCorruptSprintState(cwd);
+    const existingResult = loadSprintStateResult(cwd);
+    const existing = existingResult.status === 'valid' ? existingResult.state : null;
+    if (existing) {
+        requireMatchingSprintOrRollover(cwd, existing, sprint, `start ${formatSprintLabel(sprint)}`, retryStart);
+        if (phaseValue && existing.phase !== phase) {
+            const updated = updateSprintPhaseForSprint(cwd, existing.sprint, phase);
+            if (!updated.matched) {
+                console.error('Refusing to update phase because sprint state changed concurrently; retry the start command.');
+                process.exit(1);
+            }
             console.log(`Sprint ${formatSprintNumber(sprint)} phase updated: ${phase}.`);
             return;
         }
@@ -248,23 +623,33 @@ async function startCommand(args, cwd) {
         console.error('Resolve the overlap, choose a non-overlapping sprint, or rerun with --force if this is intentional.');
         process.exit(1);
     }
-    const state = createSprintState(sprint, phase);
-    saveSprintState(cwd, state);
-    const autoClaim = await autoClaimSprint(cwd, sprint);
-    console.log(`Sprint ${formatSprintNumber(sprint)} started (phase: ${phase}). Use 'slope sprint gate <name>' to mark gates.`);
+    const initialized = initializeSprintState(cwd, createSprintState(sprint, phase));
+    if (initialized.status === 'corrupt') {
+        console.error(`Refusing to start: corrupt sprint evidence was preserved at ${relative(cwd, initialized.path)}.`);
+        process.exit(1);
+    }
+    if (initialized.status === 'existing') {
+        requireMatchingSprintOrRollover(cwd, initialized.state, sprint, `start ${formatSprintLabel(sprint)}`, retryStart);
+        console.log(`Sprint ${formatSprintNumber(sprint)} state already exists (phase: ${initialized.state.phase}).`);
+        return;
+    }
+    const autoClaim = await autoClaimSprint(cwd, sprint, actorOverride(args));
+    console.log(`Sprint ${formatSprintNumber(sprint)} started (phase: ${phase}). Use 'slope sprint gate <name>' to mark gates; review gates require evidence options.`);
     if (autoClaim)
         console.log(autoClaim);
 }
-async function autoClaimSprint(cwd, sprint) {
+async function autoClaimSprint(cwd, sprint, explicitActor) {
     const { resolveStore } = await import('../store.js');
-    const player = process.env.USER || 'unknown';
+    const actor = resolveActor(cwd, { explicitActor });
+    const player = actor.name;
+    const playerDisplay = formatActorName(actor);
     const target = `sprint:${formatSprintLabel(sprint)}`;
     try {
         const store = await resolveStore(cwd);
         try {
             const existing = await store.list(sprint);
             if (existing.some(c => c.player === player && c.target === target)) {
-                return `Claim: ${target} already held by ${player}.`;
+                return `Claim: ${target} already held by ${playerDisplay} (actor source: ${formatActorSource(actor)}).`;
             }
             const claim = await store.claim({
                 sprint_number: sprint,
@@ -273,7 +658,7 @@ async function autoClaimSprint(cwd, sprint) {
                 scope: 'area',
                 notes: 'auto-claimed by slope sprint start',
             });
-            return `Claim: ${claim.target} (${claim.scope}) auto-claimed for ${player}.`;
+            return `Claim: ${claim.target} (${claim.scope}) auto-claimed for ${playerDisplay} (actor source: ${formatActorSource(actor)}).`;
         }
         finally {
             store.close();
@@ -306,6 +691,22 @@ function gateCommand(args, cwd) {
     const gateName = args[0];
     if (!gateName || !VALID_GATES.includes(gateName)) {
         console.error(`Error: gate name required. Valid gates: ${VALID_GATES.join(', ')}`);
+        printGateUsage();
+        process.exit(1);
+    }
+    const options = parseGateOptions(args.slice(1));
+    if (options.help) {
+        printGateUsage(gateName);
+        return;
+    }
+    if (options.errors.length > 0) {
+        for (const error of options.errors)
+            console.error(`Error: ${error}`);
+        printGateUsage(gateName);
+        process.exit(1);
+    }
+    if (!isReviewGateName(gateName) && options.review) {
+        console.error('Error: review evidence options only apply to code_review and architect_review gates.');
         process.exit(1);
     }
     const state = loadSprintState(cwd);
@@ -313,18 +714,78 @@ function gateCommand(args, cwd) {
         console.error("No active sprint. Run 'slope sprint start --number=N' first.");
         process.exit(1);
     }
-    if (state.gates[gateName]) {
+    if (isReviewGateName(gateName)) {
+        const required = isRequiredReviewGate(state, gateName);
+        const provenance = options.review?.provenance;
+        if (required && (provenance === 'self_review' || provenance === 'manual_override')) {
+            console.error(`Error: ${gateName} is a required independent review; --self-review/--override cannot silently satisfy it.`);
+            console.error(`Choose independent evidence, PR review evidence, or --waive-independent-review --reason="...".`);
+            printGateUsage(gateName);
+            process.exit(1);
+        }
+        if (!required && provenance === 'independent_review_waived') {
+            console.error(`Error: ${gateName} is not recorded as required; use --self-review --reason="..." for a weaker optional/recommended review.`);
+            printGateUsage(gateName);
+            process.exit(1);
+        }
+        const validation = validateReviewGateCompletion(options.review);
+        if (validation) {
+            console.error(`Error: ${validation}.`);
+            printGateUsage(gateName);
+            process.exit(1);
+        }
+    }
+    if (state.gates[gateName] && (!isReviewGateName(gateName) || !options.review)) {
         console.log(`Gate '${gateName}' is already complete.`);
         return;
     }
-    updateGate(cwd, gateName, true);
+    const changed = updateGate(cwd, gateName, true, { review: options.review });
+    if (!changed) {
+        console.error(`Error: could not update gate '${gateName}'.`);
+        process.exit(1);
+    }
     const updated = loadSprintState(cwd);
     const remaining = pendingGates(updated);
+    const provenance = isReviewGateName(gateName) ? ` (${updated.review_gates[gateName].provenance})` : '';
     if (remaining.length === 0) {
-        console.log(`Gate '${gateName}' marked complete. All gates done — ready for PR!`);
+        console.log(`Gate '${gateName}' marked complete${provenance}. All gates done - ready for PR!`);
     }
     else {
-        console.log(`Gate '${gateName}' marked complete. Remaining: ${remaining.join(', ')}`);
+        console.log(`Gate '${gateName}' marked complete${provenance}. Remaining: ${remaining.join(', ')}`);
+    }
+}
+function formatReviewEvidence(review) {
+    return review.evidence.length > 0 ? review.evidence.join(', ') : '(missing)';
+}
+function formatReviewGateStatus(state, gate) {
+    const review = state.review_gates[gate];
+    const requirement = state.review_requirements?.[gate];
+    const requiredLabel = requirement?.priority === 'required' ? 'required independent review' : null;
+    if (!state.gates[gate] || review.provenance === 'pending') {
+        return requiredLabel
+            ? `${requiredLabel} pending; choose reviewer evidence, PR review evidence, or an explicit waiver`
+            : 'pending review evidence';
+    }
+    const validation = validateReviewGateCompletion({
+        provenance: review.provenance,
+        evidence: review.evidence,
+        reviewer: review.reviewer,
+        notes: review.notes,
+    });
+    if (validation) {
+        return `invalid ${review.provenance}: ${validation}`;
+    }
+    switch (review.provenance) {
+        case 'independent_review':
+            return `independent_review; reviewer=${review.reviewer}; evidence=${formatReviewEvidence(review)}`;
+        case 'pr_review':
+            return `pr_review; evidence=${formatReviewEvidence(review)}`;
+        case 'self_review':
+            return `self_review (weaker); reason=${review.notes}`;
+        case 'independent_review_waived':
+            return `required independent review WAIVED; reason=${review.notes}`;
+        case 'manual_override':
+            return `manual_override (weaker); reason=${review.notes}`;
     }
 }
 function statusCommand(cwd) {
@@ -334,19 +795,49 @@ function statusCommand(cwd) {
         return;
     }
     const complete = isSprintComplete(state);
-    console.log(`Sprint ${formatSprintNumber(state.sprint)} — phase: ${state.phase}${complete ? ' (all gates complete)' : ''}`);
+    const waivedReviews = waivedReviewGateNames(state);
+    const derivedStatus = complete
+        ? waivedReviews.length > 0 ? 'ready_for_pr_with_review_waiver' : 'ready_for_pr'
+        : state.phase;
+    const phaseContext = complete ? ` (phase: ${state.phase}, all gates complete)` : ` (phase: ${state.phase})`;
+    console.log(`Sprint ${formatSprintNumber(state.sprint)} - status: ${derivedStatus}${phaseContext}`);
     console.log(`Started: ${state.started_at}`);
     console.log(`Updated: ${state.updated_at}`);
     console.log('');
     console.log('Gates:');
     for (const [gate, done] of Object.entries(state.gates)) {
-        const marker = done ? '[x]' : '[ ]';
-        console.log(`  ${marker} ${gate}`);
+        if (isReviewGateName(gate)) {
+            const satisfied = isReviewGateSatisfied(state, gate);
+            const marker = satisfied
+                ? state.review_gates[gate].provenance === 'independent_review_waived' ? '[~]' : '[x]'
+                : done ? '[!]' : '[ ]';
+            console.log(`  ${marker} ${gate} (${formatReviewGateStatus(state, gate)})`);
+        }
+        else {
+            const marker = done ? '[x]' : '[ ]';
+            console.log(`  ${marker} ${gate}`);
+        }
     }
     if (!complete) {
-        const pending = pendingGates(state);
+        const pendingNames = pendingGateNames(state);
+        const pendingLabels = pendingGates(state);
+        const pending = pendingNames.map((gate, index) => {
+            if (isReviewGateName(gate) && state.gates[gate]) {
+                return `${gate} (review evidence incomplete)`;
+            }
+            return pendingLabels[index] ?? gate;
+        });
         console.log(`\nRemaining: ${pending.join(', ')}`);
     }
+    else {
+        if (waivedReviews.length > 0) {
+            console.log(`\nNext: ${waivedReviews.join(', ')} has an explicit independent-review waiver.`);
+            console.log('Attach independent reviewer/PR evidence to replace the waiver, or proceed only with the recorded downgrade visible in PR guidance.');
+        }
+        else {
+            console.log('\nNext: create PR for this branch; after merge, run post-merge retro.');
+        }
+    }
 }
 function resetCommand(cwd) {
     clearSprintState(cwd);
@@ -421,6 +912,11 @@ function applyWorkflowVariableDefaults(def, vars, cwd, sprintId) {
         if (tickets.length > 0) {
             vars.tickets = tickets.join(',');
         }
+        else {
+            const sprintHint = sprintId ? ` for ${sprintId}` : '';
+            throw new Error(`Required variable "tickets" not provided and no roadmap tickets were found${sprintHint}. ` +
+                'Provide a comma-separated/JSON ticket list or a count, for example `--var tickets=T1,T2` or `--var tickets=3`.');
+        }
     }
 }
 function positionalSprintArg(args) {
@@ -476,7 +972,7 @@ function syncSprintStateWithWorkflow(cwd, sprintId, workflowPhase) {
         return;
     const existing = loadSprintState(cwd);
     if (!existing) {
-        saveSprintState(cwd, createSprintState(sprint, nextPhase));
+        initializeSprintState(cwd, createSprintState(sprint, nextPhase));
         return;
     }
     if (existing.sprint !== sprint || existing.phase === 'complete')
@@ -614,10 +1110,10 @@ async function workflowCleanupCommand(args, 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}`);
+                console.log(`Paused ${sprintLabelForExecution(exec)} (${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}`);
+                console.log(`Fast-forwarded ${sprintLabelForExecution(item.exec)} (${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.');
@@ -644,7 +1140,7 @@ async function workflowCleanupCommand(args, cwd) {
         }
         const engine = new WorkflowEngine();
         for (const { exec, reason } of stale) {
-            const label = exec.sprint_id ?? exec.id;
+            const label = sprintLabelForExecution(exec);
             if (dryRun) {
                 console.log(`[dry-run] Would pause ${label} (${exec.workflow_name}) at ${exec.current_phase}/${exec.current_step} — ${reason}`);
             }
@@ -713,6 +1209,12 @@ function parsePortableResumeFlags(args) {
 async function portableResumeCommand(args, cwd) {
     const flags = parsePortableResumeFlags(args);
     const config = loadConfig(cwd);
+    const loadedState = loadSprintStateResult(cwd);
+    if (loadedState.status === 'corrupt') {
+        console.error(`Portable resume refused: corrupt sprint evidence was preserved at ${relative(cwd, loadedState.path)}.`);
+        process.exit(1);
+        return;
+    }
     if (flags.invalidSprint) {
         console.error(`Error: invalid sprint "${flags.invalidSprint}". Use --sprint=N, e.g. --sprint=177.`);
         process.exit(1);
@@ -724,7 +1226,7 @@ async function portableResumeCommand(args, cwd) {
         return;
     }
     if (flags.writePointer) {
-        const current = loadSprintState(cwd);
+        const current = loadedState.status === 'valid' ? loadedState.state : null;
         const sprint = flags.sprint ?? current?.sprint;
         if (!sprint) {
             console.error('Usage: slope sprint resume --write-pointer --sprint=N [--phase=<phase>] [--output=path]');
@@ -754,21 +1256,34 @@ async function portableResumeCommand(args, cwd) {
         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;
+    const existing = loadedState.status === 'valid' ? loadedState.state : null;
+    if (existing) {
+        const retryResume = [
+            'slope sprint resume --portable',
+            ...(flags.sprint ? [`--sprint=${formatSprintNumber(flags.sprint)}`] : []),
+            ...(flags.phase ? [`--phase=${flags.phase}`] : []),
+            ...(flags.from ? [`--from=${commandValue(flags.from)}`] : []),
+            ...(flags.force ? ['--force'] : []),
+        ].join(' ');
+        requireMatchingSprintOrRollover(cwd, existing, plan.sprint, `resume ${formatSprintLabel(plan.sprint)}`, retryResume);
     }
     if (flags.dryRun) {
         console.log('\nDry run: local sprint-state and claims were not changed.');
         return;
     }
-    saveSprintState(cwd, createSprintState(plan.sprint, plan.phase));
+    if (!existing) {
+        const initialized = initializeSprintState(cwd, createSprintState(plan.sprint, plan.phase));
+        if (initialized.status !== 'created') {
+            console.error('Portable resume refused because sprint state changed concurrently; retry the command.');
+            process.exit(1);
+            return;
+        }
+    }
     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(`\nPortable sprint resume complete: ${formatSprintLabel(plan.sprint)} (${existing?.phase ?? plan.phase}).`);
+    console.log(existing
+        ? '  Existing local sprint-state and rollover lineage preserved'
+        : '  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.');
 }
@@ -823,7 +1338,8 @@ async function restoreResumeClaims(cwd, plan) {
         return 0;
     const { resolveStore } = await import('../store.js');
     const store = await resolveStore(cwd);
-    const player = process.env.USER || 'unknown';
+    const actor = resolveActor(cwd);
+    const player = actor.name;
     let restored = 0;
     try {
         const existing = await store.list(plan.sprint);
@@ -1106,6 +1622,9 @@ export async function sprintCommand(args) {
         case 'begin':
             await beginCommand(args.slice(1), cwd);
             break;
+        case 'rollover':
+            rolloverCommand(args.slice(1), cwd);
+            break;
         case 'plan': {
             const { sprintPlanCommand } = await import('./sprint-plan.js');
             await sprintPlanCommand(args.slice(1));
@@ -1165,12 +1684,18 @@ function printSprintUsage() {
 slope sprint — Sprint lifecycle management
 
 Legacy commands:
-  slope sprint start --number=N [--phase=<phase>] [--touches=<paths>] [--force]
+  slope sprint start --number=N [--phase=<phase>] [--touches=<paths>] [--actor=<name>] [--force]
                                       Start sprint state tracking with pre-sprint reality checks
-  slope sprint begin --sprint=N --ticket=T  Bundled start + claim + briefing + prep (#311)
+  slope sprint begin --sprint=N --ticket=T [--actor=<name>]  Bundled start + claim + briefing + prep (#311)
+  slope sprint rollover --from=N --to=N [--force --reason="<why>"]
+                                      Archive prior state and create the next planning state
   slope sprint plan --sprint=N [--output=path]  Generate markdown sprint plan (#312)
   slope sprint phase <phase>       Update current sprint phase
-  slope sprint gate <name>           Mark a gate as complete
+  slope sprint gate <name> [review evidence options]
+                                      Mark a gate as complete
+                                      Review gates require independent evidence, PR review evidence,
+                                      required reviews need independent evidence or an explicit
+                                      --waive-independent-review downgrade; optional reviews may use self_review
   slope sprint status                Show sprint state and gates
   slope sprint resume --portable [--from=path] [--force] [--dry-run]
                                       Reconstruct local sprint state from tracked artifacts
@@ -1180,6 +1705,7 @@ Legacy commands:
 
 Workflow commands:
   slope sprint run <id> --workflow=<name> [--var k=v ...]   Start workflow execution
+                                      tickets accepts a list/JSON array or count (tickets=3)
   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