@magnusekdahl/parallix 1.3.2 → 1.3.4

package/lib/commands/handoff.ts

@@ -58,18 +58,19 @@ import * as nels from '../core/nels.js';
   * @param {{skipGate?: boolean, worktree?: string|null, force?: boolean, forceWithLease?: boolean, log?: Function, error?: Function, rebaseFn?: Function, isForgejoReviewEnabledFn?: Function}} [options]
   * @returns {Promise<{ ok: boolean, error?: string, gatekeeperPushedBack?: boolean }>}
   */
- async function performHandoff(slug, options = {}) {
-   /** @type{{skipGate?: boolean, worktree?: string|null, force?: boolean, forceWithLease?: boolean, log?: Function, error?: Function, rebaseFn?: Function, isForgejoReviewEnabledFn?: Function}} */
-   const opts = options;
-   const {
-     skipGate = false,
-     worktree = null,
-     force = false,
-     forceWithLease = true,
-     log = fmt.log.info,
-     error = fmt.log.fail,
-     rebaseFn = rebaseBeforeReviewRound
-   } = opts;
+async function performHandoff(slug, options = {}) {
+   /** @type{{skipGate?: boolean, worktree?: string|null, force?: boolean, forceWithLease?: boolean, log?: Function, error?: Function, rebaseFn?: Function, isForgejoReviewEnabledFn?: Function, runVerificationGateFn?: Function}} */
+    const opts = options;
+    const {
+      skipGate = false,
+      worktree = null,
+      force = false,
+      forceWithLease = true,
+      log = fmt.log.info,
+      error = fmt.log.fail,
+      rebaseFn = rebaseBeforeReviewRound,
+      runVerificationGateFn = runVerificationGate
+    } = opts;
 
    const verification = verifyHandoff(slug, { worktree: worktree || undefined });
   if (!verification.ok) {
@@ -198,15 +199,17 @@ import * as nels from '../core/nels.js';
     fmt.log.warn('Step 1: Skipping final verification gate (--no-gate)');
   } else {
     log(`Step 1: Running final verification gate for area: ${fmt.bold(area || 'docs')}...`);
-    const verifyResult = runVerificationGate(area || 'docs', {
+    const verifyResult = runVerificationGateFn(area || 'docs', {
       rootDir,
-      stdio: 'inherit',
+      stdio: 'pipe',
       runFn: git.run
     });
     if (verifyResult.status !== 0) {
+      const stdout = (verifyResult.stdout || '').trim();
+      const stderr = (verifyResult.stderr || '').trim();
       const msg = 'Final verification gate failed. Fix errors before submitting or use --no-gate if appropriate.';
       error(msg);
-      return { ok: false, error: msg };
+      return { ok: false, error: msg, gateOutput: { stdout, stderr } };
     }
   }
 
@@ -346,7 +349,7 @@ import * as nels from '../core/nels.js';
   if (!gatesResult.ok) {
     const msg = `Declared gate "${gatesResult.gate}" failed for ${fmt.slug(slug)}: ${gatesResult.error || gatesResult.reason}. Blocking handoff — task remains in active.`;
     error(msg);
-    return { ok: false, error: msg };
+    return { ok: false, error: msg, gateOutput: { stdout: (gatesResult.stdout || ''), stderr: (gatesResult.stderr || '') } };
   }
   if (gatesResult.skipped) {
     log(`No declared gates for ${fmt.slug(slug)} (${gatesResult.reason}).`);
@@ -463,16 +466,19 @@ function runDeclaredGates(missionDir, rootDir, options = {}) {
     const result = spawnSync('bash', ['-c', cmd], {
       cwd: rootDir,
       encoding: 'utf8',
-      stdio: ['inherit', 'pipe', 'pipe']
+      stdio: 'pipe'
     });
 
     if (result.status !== 0) {
+      const stdout = (result.stdout || '').trim();
       const stderr = (result.stderr || '').trim();
       return {
         ok: false,
         gate: cmd,
         reason: 'gate-failed',
-        error: stderr || `Gate exited with status ${result.status}`
+        error: stderr || `Gate exited with status ${result.status}`,
+        stdout,
+        stderr
       };
     }
   }

package/lib/commands/rebase.js

@@ -58,7 +58,7 @@ const verification_js_1 = require("../core/verification.js");
  * Usage: px rebase [<slug>] [--push]
  */
 /** @param {string[]} args @param {{inferSlugFn?: Function, findMissionDirFn?: Function, findMissionAreaFn?: Function, getCurrentBranchFn?: Function, resolveConflictsFn?: Function, startAgentFn?: Function, createPrFn?: Function, readTokenFn?: Function, resolveForgejoUserFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, detectRebaseStateFn?: Function, resolveMissionBaseBranchFn?: Function, gitFn?: Function, exitFn?: Function, isForgejoReviewEnabledFn?: Function, fetchReviewBranchFn?: Function}} opts */
-async function rebase(args, { inferSlugFn = mission_utils_js_1.inferSlug, findMissionDirFn = mission_utils_js_1.findMissionDir, findMissionAreaFn = mission_utils_js_1.findMissionArea, getCurrentBranchFn = git_js_1.getCurrentBranch, resolveConflictsFn = integrate_js_1.default.resolveConflictsForMission, startAgentFn = agents_js_1.startAgent, createPrFn = forgejo_js_1.createPr, readTokenFn = forgejo_js_1.readToken, resolveForgejoUserFn = forgejo_js_1.resolveForgejoUser, resolveTaskFileFn = backlog_js_1.resolveTaskFile, getTaskImplementerFn = backlog_js_1.getTaskImplementer, detectRebaseStateFn = git_js_1.detectRebaseState, resolveMissionBaseBranchFn = mission_utils_js_1.resolveMissionBaseBranch, gitFn = git_js_1.git, exitFn = ((code) => process.exit(code)), isForgejoReviewEnabledFn = product_config_js_1.isForgejoReviewEnabled, fetchReviewBranchFn = forgejo_js_1.fetchReviewBranch, } = {}) {
+async function rebase(args, { inferSlugFn = mission_utils_js_1.inferSlug, findMissionDirFn = mission_utils_js_1.findMissionDir, findMissionAreaFn = mission_utils_js_1.findMissionArea, getCurrentBranchFn = git_js_1.getCurrentBranch, resolveConflictsFn = integrate_js_1.default.resolveConflictsForMission, startAgentFn = agents_js_1.startAgent, createPrFn = forgejo_js_1.createPr, readTokenFn = forgejo_js_1.readToken, resolveForgejoUserFn = forgejo_js_1.resolveForgejoUser, resolveTaskFileFn = backlog_js_1.resolveTaskFile, getTaskImplementerFn = backlog_js_1.getTaskImplementer, detectRebaseStateFn = git_js_1.detectRebaseState, resolveMissionBaseBranchFn = mission_utils_js_1.resolveMissionBaseBranch, gitFn = git_js_1.git, exitFn = ((_code) => process.exit(_code)), isForgejoReviewEnabledFn = product_config_js_1.isForgejoReviewEnabled, fetchReviewBranchFn = forgejo_js_1.fetchReviewBranch, } = {}) {
     const flags = args.filter(a => a.startsWith('--'));
     const params = args.filter(a => !a.startsWith('--'));
     const isPush = flags.includes('--push');

package/lib/commands/rebase.ts

@@ -32,10 +32,10 @@ async function rebase(args: string[], {
   detectRebaseStateFn = detectRebaseState,
   resolveMissionBaseBranchFn = resolveMissionBaseBranch,
   gitFn = git,
-  exitFn = ((code: number) => process.exit(code)) as (code: number) => void,
+  exitFn = ((_code: number) => process.exit(_code)) as (_code: number) => void,
   isForgejoReviewEnabledFn = isForgejoReviewEnabled,
   fetchReviewBranchFn = fetchReviewBranch,
-}: {inferSlugFn?: Function, findMissionDirFn?: Function, findMissionAreaFn?: Function, getCurrentBranchFn?: Function, resolveConflictsFn?: Function, startAgentFn?: Function, createPrFn?: Function, readTokenFn?: Function, resolveForgejoUserFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, detectRebaseStateFn?: Function, resolveMissionBaseBranchFn?: Function, gitFn?: Function, exitFn?: (code: number) => void, isForgejoReviewEnabledFn?: Function, fetchReviewBranchFn?: Function} = {}) {
+}: {inferSlugFn?: Function, findMissionDirFn?: Function, findMissionAreaFn?: Function, getCurrentBranchFn?: Function, resolveConflictsFn?: Function, startAgentFn?: Function, createPrFn?: Function, readTokenFn?: Function, resolveForgejoUserFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, detectRebaseStateFn?: Function, resolveMissionBaseBranchFn?: Function, gitFn?: Function, exitFn?: (_code: number) => void, isForgejoReviewEnabledFn?: Function, fetchReviewBranchFn?: Function} = {}) {
   const flags = args.filter(a => a.startsWith('--'));
   const params = args.filter(a => !a.startsWith('--'));
   const isPush = flags.includes('--push');

package/lib/commands/repair-handoff.js

@@ -36,6 +36,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DispatchAction = exports.FailureClass = void 0;
+exports.getDispatchAction = getDispatchAction;
+exports.classifyError = classifyError;
 exports.repairHandoff = repairHandoff;
 exports.isRelaunchableError = isRelaunchableError;
 exports.buildRelaunchPrompt = buildRelaunchPrompt;
@@ -43,19 +46,129 @@ const git_js_1 = require("../core/git.js");
 const missionUtils = __importStar(require("../core/mission-utils.js"));
 const rebase_js_1 = __importDefault(require("./rebase.js"));
 const fmt = __importStar(require("../core/fmt.js"));
+// ── FailureClass: 8 classes from ADR 0048 ────────────────────────────────────
+const FailureClass = {
+    UnverifiableClaims: 'UnverifiableClaims',
+    MalformedGates: 'MalformedGates',
+    MissingArtifacts: 'MissingArtifacts',
+    IncompleteEvidence: 'IncompleteEvidence',
+    GitBlockers: 'GitBlockers',
+    GateFailure: 'GateFailure',
+    InfraBlocker: 'InfraBlocker',
+    StateMachineViolation: 'StateMachineViolation',
+};
+exports.FailureClass = FailureClass;
+// ── DispatchAction: 3 actions from ADR 0048 ──────────────────────────────────
+const DispatchAction = {
+    AutoRepair: 'AutoRepair',
+    AutoSendBack: 'AutoSendBack',
+    HumanOnly: 'HumanOnly',
+};
+exports.DispatchAction = DispatchAction;
+// ── Dispatch table: maps each failure class to its prescribed action (ADR 0048) ─
+const DISPATCH_TABLE = {
+    [FailureClass.UnverifiableClaims]: DispatchAction.AutoSendBack,
+    [FailureClass.MalformedGates]: DispatchAction.AutoRepair,
+    [FailureClass.MissingArtifacts]: DispatchAction.AutoSendBack,
+    [FailureClass.IncompleteEvidence]: DispatchAction.AutoSendBack,
+    [FailureClass.GitBlockers]: DispatchAction.AutoRepair,
+    [FailureClass.GateFailure]: DispatchAction.AutoSendBack,
+    [FailureClass.InfraBlocker]: DispatchAction.HumanOnly,
+    [FailureClass.StateMachineViolation]: DispatchAction.HumanOnly,
+};
+/**
+ * Look up the dispatch action for a given failure class.
+ *
+ * @param failureClass - One of the 8 failure class values from ADR 0048
+ * @returns The prescribed dispatch action, or null if unknown
+ */
+function getDispatchAction(failureClass) {
+    return DISPATCH_TABLE[failureClass] ?? null;
+}
+/**
+ * Classify an error message into one of the 8 failure classes from ADR 0048
+ * and return the associated dispatch action.
+ *
+ * Patterns are checked in order of specificity to avoid collisions.
+ * Returns a `reason` field for GitBlockers to distinguish dirty-artifact from behind-branch errors,
+ * allowing callers to derive repair-strategy flags without duplicating pattern matching.
+ *
+ * @param errorMsg - The error message to classify
+ * @returns Object with failureClass, dispatchAction, and (for GitBlockers) reason
+ */
+function classifyError(errorMsg) {
+    if (!errorMsg || typeof errorMsg !== 'string') {
+        return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+    }
+    // 1. IncompleteEvidence: goal-check table missing evidence rows (most specific — checked before generic gate patterns)
+    if (errorMsg.includes('has a "## Goal Check" section but no evidence rows') &&
+        errorMsg.includes('A goal-check table with real evidence is required before handoff')) {
+        return { failureClass: FailureClass.IncompleteEvidence, dispatchAction: DispatchAction.AutoSendBack };
+    }
+    // 2. GitBlockers: dirty/uncommitted mission artifacts (mechanical git blocker — auto-repairable)
+    if (errorMsg.includes('is modified but uncommitted') ||
+        errorMsg.includes('Commit the mission contract before handoff') ||
+        errorMsg.includes('Commit the implementation evidence before handoff')) {
+        return { failureClass: FailureClass.GitBlockers, dispatchAction: DispatchAction.AutoRepair, reason: 'dirty' };
+    }
+    // 3. GitBlockers: branch behind primary / push rejected (mechanical git blocker — auto-repairable via rebase)
+    if (errorMsg.includes('Updates were rejected') ||
+        errorMsg.includes('fetch first') ||
+        errorMsg.includes('non-fast-forward') ||
+        errorMsg.includes('behind its remote') ||
+        (errorMsg.includes('git push failed') && (errorMsg.includes('rejected') ||
+            errorMsg.includes('remote contains work')))) {
+        return { failureClass: FailureClass.GitBlockers, dispatchAction: DispatchAction.AutoRepair, reason: 'behind' };
+    }
+    // 4. GateFailure: verification gate failed
+    if (/verification gate failed/i.test(errorMsg)) {
+        return { failureClass: FailureClass.GateFailure, dispatchAction: DispatchAction.AutoSendBack };
+    }
+    // 5. GateFailure: declared gate failed
+    if (/\bdeclared gate\b/i.test(errorMsg) && /\bfailed\b/i.test(errorMsg)) {
+        return { failureClass: FailureClass.GateFailure, dispatchAction: DispatchAction.AutoSendBack };
+    }
+    // 6. UnverifiableClaims: test claims that cannot be verified
+    if (/test(s?\s+)?passed/i.test(errorMsg) && /cannot\s+verify|unverifiable|proof\s+(not\s+)?found|stale\s+proof/i.test(errorMsg)) {
+        return { failureClass: FailureClass.UnverifiableClaims, dispatchAction: DispatchAction.AutoSendBack };
+    }
+    // 7. MalformedGates: malformed or non-runnable declared gates
+    if (/malformed\s+gate|invalid\s+gate\s+config|gate\s+command\s+(not\s+found|syntax\s+error|not\s+runnable)/i.test(errorMsg) ||
+        (/gate/i.test(errorMsg) && /syntax\s+error|not\s+found|missing\s+(file|command)/i.test(errorMsg))) {
+        return { failureClass: FailureClass.MalformedGates, dispatchAction: DispatchAction.AutoRepair };
+    }
+    // 8. MissingArtifacts: mandatory mission artifacts missing
+    if (/mandatory\s+(artifact|file|document)|missing\s+(mission\s+)?(artifact|file|document)|required\s+(artifact|file|document)\s+(not\s+)?found/i.test(errorMsg) ||
+        (/gatekeeper/i.test(errorMsg) && /missing\s+(artifact|file|document)/i.test(errorMsg))) {
+        return { failureClass: FailureClass.MissingArtifacts, dispatchAction: DispatchAction.AutoSendBack };
+    }
+    // 9. StateMachineViolation: task state machine violations
+    if (/state\s+violation|invalid\s+state|transition\s+not\s+allowed|cannot\s+(move|transition)\s+(from|to)\s+\w+\s+(to|from)/i.test(errorMsg) ||
+        (/task\s+state/i.test(errorMsg) && /invalid|violation|incorrect/i.test(errorMsg))) {
+        return { failureClass: FailureClass.StateMachineViolation, dispatchAction: DispatchAction.HumanOnly };
+    }
+    // 10. InfraBlocker: forgejo/infrastructure blockers
+    if (/forgejo|infrastructure|authentication\s+failed|token\s+(expired|invalid|missing)|forbidden|unauthorized\s+(access|request)|rate\s+limit|connection\s+(refused|timed?\s*out)|network\s+error/i.test(errorMsg)) {
+        return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+    }
+    // Default: human-only for unrecognized errors
+    return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+}
 /**
  * Check if an error message indicates a relaunchable content error (missing/empty goal-check table).
+ * Delegates to classifyError for backward-compatible classification.
  *
- * @param {string} errorMsg - The error message to check
- * @returns {boolean} True if the error is relaunchable
+ * @param errorMsg - The error message to check
+ * @returns True if the error is relaunchable (IncompleteEvidence or GateFailure)
  */
 function isRelaunchableError(errorMsg) {
     if (!errorMsg || typeof errorMsg !== 'string') {
         return false;
     }
-    // Match the exact error message from handoff.js when final checkpoint has no evidence rows
-    return errorMsg.includes('has a "## Goal Check" section but no evidence rows') &&
-        errorMsg.includes('A goal-check table with real evidence is required before handoff');
+    const { failureClass } = classifyError(errorMsg);
+    // IncompleteEvidence and GateFailure are the only classes that were relaunchable under the old logic
+    return failureClass === FailureClass.IncompleteEvidence
+        || failureClass === FailureClass.GateFailure;
 }
 /**
  * Build a relaunch prompt for an agent to fix a relaunchable error.
@@ -65,10 +178,10 @@ function isRelaunchableError(errorMsg) {
  * @param {string} worktree - Path to the mission worktree
  * @returns {string} The relaunch prompt
   */
-function buildRelaunchPrompt(errorMsg, slug, worktree) {
+function buildRelaunchPrompt(errorMsg, slug, worktree, gateOutput) {
     const year = missionUtils.getMissionYear(slug, worktree);
     const missionDir = missionUtils.findMissionDir(slug, worktree) || missionUtils.missionDirForSlug(worktree, slug);
-    return `Automated handoff failed for mission ${slug} with a repairable error: ${errorMsg}
+    let prompt = `Automated handoff failed for mission ${slug} with a repairable error: ${errorMsg}
 
 ` +
         `Please fix the final checkpoint document in ${missionDir} by adding a Goal Check table ` +
@@ -103,6 +216,16 @@ function buildRelaunchPrompt(errorMsg, slug, worktree) {
 
 ` +
         `Do NOT add placeholder or generic evidence. Each row must cite real, verifiable artifacts.`;
+    // Append captured gate output if available (task-1387)
+    if (gateOutput && (gateOutput.stdout || gateOutput.stderr)) {
+        const totalOutput = (gateOutput.stdout || '') + (gateOutput.stderr || '');
+        // Truncate if total output exceeds 16000 chars; keep last 8000 chars
+        const truncated = totalOutput.length > 16000
+            ? `[truncated — total ${totalOutput.length} chars, showing last 8000]\n` + totalOutput.slice(-8000)
+            : totalOutput;
+        prompt += `\n\n--- Captured Gate Output ---\n${truncated}`;
+    }
+    return prompt;
 }
 /**
  * Attempt to repair a failed automated handoff by auto-committing mission
@@ -129,23 +252,17 @@ async function repairHandoff(slug, worktree, errorMsg, options = {}) {
         const cleanPath = (pathPart.startsWith('"') && pathPart.endsWith('"')) ? pathPart.slice(1, -1) : pathPart;
         return { xy, file: cleanPath };
     }
-    // 0. Check if error is repairable
-    const isDirtyError = errorMsg && (errorMsg.includes('is modified but uncommitted') ||
-        errorMsg.includes('Commit the mission contract before handoff') ||
-        errorMsg.includes('Commit the implementation evidence before handoff'));
-    const isBehind = errorMsg && (errorMsg.includes('Updates were rejected') ||
-        errorMsg.includes('fetch first') ||
-        errorMsg.includes('non-fast-forward') ||
-        errorMsg.includes('behind its remote') ||
-        // Ensure we don't match generic git push failed unless it has non-fast-forward hints
-        (errorMsg.includes('git push failed') && (errorMsg.includes('rejected') ||
-            errorMsg.includes('remote contains work'))));
-    if (!isDirtyError && !isBehind) {
+    // 0. Check if error is repairable via classifyError
+    const classification = classifyError(errorMsg);
+    const isGitBlocker = classification.failureClass === FailureClass.GitBlockers;
+    // Derive isBehind from classification result (avoids duplicating classifyError's behind-branch patterns)
+    const isBehind = classification.reason === 'behind';
+    if (!isGitBlocker) {
         log(`Handoff error is not automatically repairable: ${errorMsg}`);
         return { repaired: false, blocker: null };
     }
     // 1. Auto-commit mission artifacts if uncommitted
-    if (isDirtyError || isBehind) {
+    if (isGitBlocker) {
         const statusResult = gitFn(['-C', rootDir, 'status', '--porcelain']);
         if (statusResult.status === 0 && statusResult.stdout) {
             const dirtyLines = statusResult.stdout.split('\n')
@@ -236,6 +353,10 @@ async function repairHandoff(slug, worktree, errorMsg, options = {}) {
 }
 repairHandoff.isRelaunchableError = isRelaunchableError;
 repairHandoff.buildRelaunchPrompt = buildRelaunchPrompt;
+repairHandoff.classifyError = classifyError;
+repairHandoff.getDispatchAction = getDispatchAction;
+repairHandoff.FailureClass = FailureClass;
+repairHandoff.DispatchAction = DispatchAction;
 exports.default = repairHandoff;
 if (typeof module !== 'undefined') {
     module.exports = repairHandoff;

package/lib/commands/repair-handoff.ts

@@ -3,19 +3,155 @@ import * as missionUtils from '../core/mission-utils.js';
 import rebase from './rebase.js';
 import * as fmt from '../core/fmt.js';
 
+// ── FailureClass: 8 classes from ADR 0048 ────────────────────────────────────
+const FailureClass = {
+  UnverifiableClaims: 'UnverifiableClaims',
+  MalformedGates: 'MalformedGates',
+  MissingArtifacts: 'MissingArtifacts',
+  IncompleteEvidence: 'IncompleteEvidence',
+  GitBlockers: 'GitBlockers',
+  GateFailure: 'GateFailure',
+  InfraBlocker: 'InfraBlocker',
+  StateMachineViolation: 'StateMachineViolation',
+} as const;
+
+type FailureClassType = (typeof FailureClass)[keyof typeof FailureClass];
+
+// ── DispatchAction: 3 actions from ADR 0048 ──────────────────────────────────
+const DispatchAction = {
+  AutoRepair: 'AutoRepair',
+  AutoSendBack: 'AutoSendBack',
+  HumanOnly: 'HumanOnly',
+} as const;
+
+type DispatchActionType = (typeof DispatchAction)[keyof typeof DispatchAction];
+
+// ── Dispatch table: maps each failure class to its prescribed action (ADR 0048) ─
+const DISPATCH_TABLE: Record<FailureClassType, DispatchActionType> = {
+  [FailureClass.UnverifiableClaims]: DispatchAction.AutoSendBack,
+  [FailureClass.MalformedGates]: DispatchAction.AutoRepair,
+  [FailureClass.MissingArtifacts]: DispatchAction.AutoSendBack,
+  [FailureClass.IncompleteEvidence]: DispatchAction.AutoSendBack,
+  [FailureClass.GitBlockers]: DispatchAction.AutoRepair,
+  [FailureClass.GateFailure]: DispatchAction.AutoSendBack,
+  [FailureClass.InfraBlocker]: DispatchAction.HumanOnly,
+  [FailureClass.StateMachineViolation]: DispatchAction.HumanOnly,
+};
+
+/**
+ * Look up the dispatch action for a given failure class.
+ *
+ * @param failureClass - One of the 8 failure class values from ADR 0048
+ * @returns The prescribed dispatch action, or null if unknown
+ */
+export function getDispatchAction(failureClass: FailureClassType): DispatchActionType | null {
+  return DISPATCH_TABLE[failureClass] ?? null;
+}
+
+/**
+ * Sub-reason for GitBlockers classification: distinguishes dirty-artifact from behind-branch errors.
+ * Used by repairHandoff() to decide whether to auto-rebase (behind) vs auto-commit only (dirty).
+ */
+type GitBlockerReason = 'dirty' | 'behind' | 'other';
+
+/**
+ * Classify an error message into one of the 8 failure classes from ADR 0048
+ * and return the associated dispatch action.
+ *
+ * Patterns are checked in order of specificity to avoid collisions.
+ * Returns a `reason` field for GitBlockers to distinguish dirty-artifact from behind-branch errors,
+ * allowing callers to derive repair-strategy flags without duplicating pattern matching.
+ *
+ * @param errorMsg - The error message to classify
+ * @returns Object with failureClass, dispatchAction, and (for GitBlockers) reason
+ */
+export function classifyError(errorMsg: string): { failureClass: FailureClassType; dispatchAction: DispatchActionType; reason?: GitBlockerReason } {
+  if (!errorMsg || typeof errorMsg !== 'string') {
+    return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+  }
+
+  // 1. IncompleteEvidence: goal-check table missing evidence rows (most specific — checked before generic gate patterns)
+  if (errorMsg.includes('has a "## Goal Check" section but no evidence rows') &&
+      errorMsg.includes('A goal-check table with real evidence is required before handoff')) {
+    return { failureClass: FailureClass.IncompleteEvidence, dispatchAction: DispatchAction.AutoSendBack };
+  }
+
+  // 2. GitBlockers: dirty/uncommitted mission artifacts (mechanical git blocker — auto-repairable)
+  if (errorMsg.includes('is modified but uncommitted') ||
+      errorMsg.includes('Commit the mission contract before handoff') ||
+      errorMsg.includes('Commit the implementation evidence before handoff')) {
+    return { failureClass: FailureClass.GitBlockers, dispatchAction: DispatchAction.AutoRepair, reason: 'dirty' };
+  }
+
+  // 3. GitBlockers: branch behind primary / push rejected (mechanical git blocker — auto-repairable via rebase)
+  if (errorMsg.includes('Updates were rejected') ||
+      errorMsg.includes('fetch first') ||
+      errorMsg.includes('non-fast-forward') ||
+      errorMsg.includes('behind its remote') ||
+      (errorMsg.includes('git push failed') && (
+        errorMsg.includes('rejected') ||
+        errorMsg.includes('remote contains work')
+      ))) {
+    return { failureClass: FailureClass.GitBlockers, dispatchAction: DispatchAction.AutoRepair, reason: 'behind' };
+  }
+
+  // 4. GateFailure: verification gate failed
+  if (/verification gate failed/i.test(errorMsg)) {
+    return { failureClass: FailureClass.GateFailure, dispatchAction: DispatchAction.AutoSendBack };
+  }
+
+  // 5. GateFailure: declared gate failed
+  if (/\bdeclared gate\b/i.test(errorMsg) && /\bfailed\b/i.test(errorMsg)) {
+    return { failureClass: FailureClass.GateFailure, dispatchAction: DispatchAction.AutoSendBack };
+  }
+
+  // 6. UnverifiableClaims: test claims that cannot be verified
+  if (/test(s?\s+)?passed/i.test(errorMsg) && /cannot\s+verify|unverifiable|proof\s+(not\s+)?found|stale\s+proof/i.test(errorMsg)) {
+    return { failureClass: FailureClass.UnverifiableClaims, dispatchAction: DispatchAction.AutoSendBack };
+  }
+
+  // 7. MalformedGates: malformed or non-runnable declared gates
+  if (/malformed\s+gate|invalid\s+gate\s+config|gate\s+command\s+(not\s+found|syntax\s+error|not\s+runnable)/i.test(errorMsg) ||
+      (/gate/i.test(errorMsg) && /syntax\s+error|not\s+found|missing\s+(file|command)/i.test(errorMsg))) {
+    return { failureClass: FailureClass.MalformedGates, dispatchAction: DispatchAction.AutoRepair };
+  }
+
+  // 8. MissingArtifacts: mandatory mission artifacts missing
+  if (/mandatory\s+(artifact|file|document)|missing\s+(mission\s+)?(artifact|file|document)|required\s+(artifact|file|document)\s+(not\s+)?found/i.test(errorMsg) ||
+      (/gatekeeper/i.test(errorMsg) && /missing\s+(artifact|file|document)/i.test(errorMsg))) {
+    return { failureClass: FailureClass.MissingArtifacts, dispatchAction: DispatchAction.AutoSendBack };
+  }
+
+  // 9. StateMachineViolation: task state machine violations
+  if (/state\s+violation|invalid\s+state|transition\s+not\s+allowed|cannot\s+(move|transition)\s+(from|to)\s+\w+\s+(to|from)/i.test(errorMsg) ||
+      (/task\s+state/i.test(errorMsg) && /invalid|violation|incorrect/i.test(errorMsg))) {
+    return { failureClass: FailureClass.StateMachineViolation, dispatchAction: DispatchAction.HumanOnly };
+  }
+
+  // 10. InfraBlocker: forgejo/infrastructure blockers
+  if (/forgejo|infrastructure|authentication\s+failed|token\s+(expired|invalid|missing)|forbidden|unauthorized\s+(access|request)|rate\s+limit|connection\s+(refused|timed?\s*out)|network\s+error/i.test(errorMsg)) {
+    return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+  }
+
+  // Default: human-only for unrecognized errors
+  return { failureClass: FailureClass.InfraBlocker, dispatchAction: DispatchAction.HumanOnly };
+}
+
 /**
  * Check if an error message indicates a relaunchable content error (missing/empty goal-check table).
+ * Delegates to classifyError for backward-compatible classification.
  *
- * @param {string} errorMsg - The error message to check
- * @returns {boolean} True if the error is relaunchable
+ * @param errorMsg - The error message to check
+ * @returns True if the error is relaunchable (IncompleteEvidence or GateFailure)
  */
-function isRelaunchableError(errorMsg: string) {
+function isRelaunchableError(errorMsg: string): boolean {
   if (!errorMsg || typeof errorMsg !== 'string') {
     return false;
   }
-  // Match the exact error message from handoff.js when final checkpoint has no evidence rows
-  return errorMsg.includes('has a "## Goal Check" section but no evidence rows') &&
-         errorMsg.includes('A goal-check table with real evidence is required before handoff');
+  const { failureClass } = classifyError(errorMsg);
+  // IncompleteEvidence and GateFailure are the only classes that were relaunchable under the old logic
+  return failureClass === FailureClass.IncompleteEvidence
+    || failureClass === FailureClass.GateFailure;
 }
 
 /**
@@ -26,45 +162,57 @@ function isRelaunchableError(errorMsg: string) {
  * @param {string} worktree - Path to the mission worktree
  * @returns {string} The relaunch prompt
   */
-function buildRelaunchPrompt(errorMsg: string, slug: string, worktree: string) {
+function buildRelaunchPrompt(errorMsg: string, slug: string, worktree: string, gateOutput?: { stdout: string; stderr: string }) {
   const year = missionUtils.getMissionYear(slug, worktree);
   const missionDir = missionUtils.findMissionDir(slug, worktree) || missionUtils.missionDirForSlug(worktree, slug);
   
-  return `Automated handoff failed for mission ${slug} with a repairable error: ${errorMsg}
+  let prompt = `Automated handoff failed for mission ${slug} with a repairable error: ${errorMsg}
 
 ` +
-         `Please fix the final checkpoint document in ${missionDir} by adding a Goal Check table ` +
-         `with real evidence rows (file:line references, test names). The Goal Check table must have ` +
-         `a header row and at least one evidence row using pipe syntax (|).
+          `Please fix the final checkpoint document in ${missionDir} by adding a Goal Check table ` +
+          `with real evidence rows (file:line references, test names). The Goal Check table must have ` +
+          `a header row and at least one evidence row using pipe syntax (|).
 
 ` +
-         `Steps:
+          `Steps:
 ` +
-         `1. Open the final checkpoint document (CP-N.md) in ${missionDir}
+          `1. Open the final checkpoint document (CP-N.md) in ${missionDir}
 ` +
-         `2. Add or update the "## Goal Check" section
+          `2. Add or update the "## Goal Check" section
 ` +
-         `3. Create a markdown table with columns for: Goal Check description | Evidence | Status
+          `3. Create a markdown table with columns for: Goal Check description | Evidence | Status
 ` +
-         `4. Add at least one evidence row with real file:line or test name references
+          `4. Add at least one evidence row with real file:line or test name references
 ` +
-         `5. Commit the updated checkpoint with a descriptive commit message
+          `5. Commit the updated checkpoint with a descriptive commit message
 ` +
-         `6. Re-run: node parallix review ${slug} --submit
+          `6. Re-run: node parallix review ${slug} --submit
 
 ` +
-         `Example Goal Check table:
+          `Example Goal Check table:
 ` +
-         `| Goal Check | Evidence | Status |
+          `| Goal Check | Evidence | Status |
 ` +
-         `|---|---|---|
+          `|---|---|---|
 ` +
-         `| Final checkpoint has Goal Check section | docs/missions/${year}/${slug}/CP-1.md:15 | PASS |
+          `| Final checkpoint has Goal Check section | docs/missions/${year}/${slug}/CP-1.md:15 | PASS |
 ` +
-         `| Tests pass | npm test -- parallix/test/repair-handoff.test.js | PASS |
+          `| Tests pass | npm test -- parallix/test/repair-handoff.test.js | PASS |
 
 ` +
-         `Do NOT add placeholder or generic evidence. Each row must cite real, verifiable artifacts.`;
+          `Do NOT add placeholder or generic evidence. Each row must cite real, verifiable artifacts.`;
+
+  // Append captured gate output if available (task-1387)
+  if (gateOutput && (gateOutput.stdout || gateOutput.stderr)) {
+    const totalOutput = (gateOutput.stdout || '') + (gateOutput.stderr || '');
+    // Truncate if total output exceeds 16000 chars; keep last 8000 chars
+    const truncated = totalOutput.length > 16000
+      ? `[truncated — total ${totalOutput.length} chars, showing last 8000]\n` + totalOutput.slice(-8000)
+      : totalOutput;
+    prompt += `\n\n--- Captured Gate Output ---\n${truncated}`;
+  }
+
+  return prompt;
 }
 
 /**
@@ -100,32 +248,19 @@ async function repairHandoff(slug: string, worktree: string, errorMsg: string, o
     return { xy, file: cleanPath };
   }
 
-  // 0. Check if error is repairable
-  const isDirtyError = errorMsg && (
-    errorMsg.includes('is modified but uncommitted') ||
-    errorMsg.includes('Commit the mission contract before handoff') ||
-    errorMsg.includes('Commit the implementation evidence before handoff')
-  );
-
-  const isBehind = errorMsg && (
-    errorMsg.includes('Updates were rejected') || 
-    errorMsg.includes('fetch first') || 
-    errorMsg.includes('non-fast-forward') ||
-    errorMsg.includes('behind its remote') ||
-    // Ensure we don't match generic git push failed unless it has non-fast-forward hints
-    (errorMsg.includes('git push failed') && (
-      errorMsg.includes('rejected') || 
-      errorMsg.includes('remote contains work')
-    ))
-  );
-
-  if (!isDirtyError && !isBehind) {
+  // 0. Check if error is repairable via classifyError
+  const classification = classifyError(errorMsg);
+  const isGitBlocker = classification.failureClass === FailureClass.GitBlockers;
+  // Derive isBehind from classification result (avoids duplicating classifyError's behind-branch patterns)
+  const isBehind = classification.reason === 'behind';
+
+  if (!isGitBlocker) {
     log(`Handoff error is not automatically repairable: ${errorMsg}`);
     return { repaired: false, blocker: null };
   }
 
   // 1. Auto-commit mission artifacts if uncommitted
-  if (isDirtyError || isBehind) {
+  if (isGitBlocker) {
     const statusResult = gitFn(['-C', rootDir, 'status', '--porcelain']);
     if (statusResult.status === 0 && statusResult.stdout) {
       const dirtyLines = statusResult.stdout.split('\n')
@@ -224,9 +359,14 @@ async function repairHandoff(slug: string, worktree: string, errorMsg: string, o
 
 (repairHandoff as any).isRelaunchableError = isRelaunchableError;
 (repairHandoff as any).buildRelaunchPrompt = buildRelaunchPrompt;
+(repairHandoff as any).classifyError = classifyError;
+(repairHandoff as any).getDispatchAction = getDispatchAction;
+(repairHandoff as any).FailureClass = FailureClass;
+(repairHandoff as any).DispatchAction = DispatchAction;
 
 export default repairHandoff;
 export { repairHandoff, isRelaunchableError, buildRelaunchPrompt };
+export { FailureClass, DispatchAction };
 
 // CJS compat: ensure require() returns the function directly
 declare const module: { exports: any } | undefined;

package/lib/commands/resolve-conflict.js

@@ -80,7 +80,7 @@ function buildAgentResolutionPrompt({ slug, area, worktreePath, missionSpecificF
     ].join('\n');
 }
 /** @param {string[]} args @param {{resolveConflictsFn?: Function, startAgentFn?: Function, exitFn?: Function}} opts */
-async function resolveConflict(args, { resolveConflictsFn = integrate_js_1.default.resolveConflictsForMission, startAgentFn = agents_js_1.startAgent, exitFn = ((code) => process.exit(code)), } = {}) {
+async function resolveConflict(args, { resolveConflictsFn = integrate_js_1.default.resolveConflictsForMission, startAgentFn = agents_js_1.startAgent, exitFn = ((_code) => process.exit(_code)), } = {}) {
     const explicitSlug = args[0];
     const slug = (0, mission_utils_js_1.inferSlug)(explicitSlug);
     if (!slug) {

package/lib/commands/resolve-conflict.ts

@@ -47,8 +47,8 @@ function buildAgentResolutionPrompt({ slug, area, worktreePath, missionSpecificF
 async function resolveConflict(args: string[], {
   resolveConflictsFn = (integrate as any).resolveConflictsForMission,
   startAgentFn = startAgent,
-  exitFn = ((code: number) => process.exit(code)) as (code: number) => void,
-}: {resolveConflictsFn?: Function, startAgentFn?: Function, exitFn?: (code: number) => void} = {}) {
+  exitFn = ((_code: number) => process.exit(_code)) as (_code: number) => void,
+}: {resolveConflictsFn?: Function, startAgentFn?: Function, exitFn?: (_code: number) => void} = {}) {
   const explicitSlug = args[0];
   const slug = inferSlug(explicitSlug);
   if (!slug) {