@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/commands/integrate.js

@@ -7,9 +7,9 @@ const { resolveTaskFile, getTaskStatus, setTaskStatus, completeTask, getTaskAssi
 const { toVirtual, toActual } = require('../core/state-map');
 const { getPrStatus, getLatestReviewDecision, syncMerged, readToken, resolveTokenFile, resolveForgejoUser, resolveForgejoHome, isForgejoPath, listOpenPrsForSlug } = require('../tools/forgejo');
 const fmt = require('../core/fmt');
-const { KNOWN_AGENT_NAMES } = require('../agents/agents');
+
 const { buildAutonomousReviewMatrix, formatMatrixSummary } = require('../core/runtime-matrix');
-const { findMissionDir, resolveWorktree, findMissionArea, missionTitle, parseConflictFilesFromMergeOutput, getConflictFiles, inferSlug, updateGraphifyKnowledgeGraph, resolveMainRepo, getPrimaryWorktree, getPrimaryBranch, conventionalWorktreePath, getMissionYear, softResetTrailingBacklogNoise, findMissionDocInBranches, missionBranchName, missionBaseDir, missionDirForSlug, isMissionArtifact, resolveMissionBaseBranch, resolveBaseWorktree } = require('../core/mission-utils');
+const { findMissionDir, resolveWorktree, findMissionArea, missionTitle, parseConflictFilesFromMergeOutput, getConflictFiles, inferSlug, updateGraphifyKnowledgeGraph, getPrimaryWorktree, getPrimaryBranch, conventionalWorktreePath, softResetTrailingBacklogNoise, findMissionDocInBranches, missionBranchName, missionDirForSlug, isMissionArtifact, resolveMissionBaseBranch, resolveBaseWorktree } = require('../core/mission-utils');
 const stats = require('./stats');
 const verification = require('../core/verification');
 const { formatVerificationCommand } = verification;
@@ -18,6 +18,7 @@ const { readReviewState } = require('../review/review-state');
 
 const VARIANT_B_AUTOMATION_SUMMARY = 'Variant B automation: Backlog task closeout, worktree-path rewrite, squash commit with hook-enforced validation, Forgejo sync-merged, and mission worktree cleanup.';
 
+/** @type{{symptom: string, cause: string, fix: string}[]} */
 const SYNC_MERGED_DIAGNOSTICS = [
   { symptom: 'sync-merged reports generic failure; PR still open', cause: 'allow_manual_merge disabled or drifted off in Forgejo settings', fix: 'Enable "Allow manual merge" in Forgejo PR settings and retry.' },
   { symptom: 'POST /pulls/N/merge returns 405 or 500', cause: 'Forgejo API conflict or stale PR state', fix: 'px review <slug> to check if actually merged.' },
@@ -26,28 +27,34 @@ const SYNC_MERGED_DIAGNOSTICS = [
   { symptom: 'PR marked merged but remote branch still exists', cause: 'Remote branch deletion failed (permissions or network)', fix: 'px review <slug> --close (to trigger cleanup; identity resolves from review-state).' }
 ];
 
+/** @extends{Error} */
 class IntegrationAbort extends Error {}
 
+/** @param {{mission: string, implementer: string, pr_fix_rounds: string, classification: string, date: string}} row */
 function formatRecordedStatsRow(row) {
   return `${row.mission}: implementer=${row.implementer}, pr_fix_rounds=${row.pr_fix_rounds}, classification=${row.classification}, date=${row.date}`;
 }
 
+/** @param {string} value */
 function shellQuote(value) {
   return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
 }
 
-function maybeUpdateGraphifyOnPrimary(rootDir = getPrimaryWorktree(), { commandRunner = null, log = fmt.log.plain } = {}) {
+/** @param {string} rootDir @param {{commandRunner?: Function, log?: Function}} opts */
+function maybeUpdateGraphifyOnPrimary(rootDir = getPrimaryWorktree(), opts = {}) {
   return updateGraphifyKnowledgeGraph({
     rootDir,
-    commandRunner: commandRunner || ((command, args, options) => require('../core/git').run(command, args, options)),
-    log,
+    commandRunner: opts.commandRunner || ((/** @type{string} */ command, /** @type{string[]} */ args, /** @type{object} */ options) => require('../core/git').run(command, args, options)),
+    log: opts.log,
     startMessage: `Updating graphify knowledge graph on ${getPrimaryBranch()}...`,
     failureHint: 'Continuing without blocking integration.'
   });
 }
 
-function prepareNoisePatchForSquash(rootDir, { gitRunner = git } = {}) {
-  const diffResult = gitRunner(['-C', rootDir, 'diff', '--cached', '--binary']);
+/** @param {string} rootDir @param {{gitRunner?: Function}} opts */
+function prepareNoisePatchForSquash(rootDir, opts = {}) {
+  const runner = opts.gitRunner || git;
+  const diffResult = runner(['-C', rootDir, 'diff', '--cached', '--binary']);
   if (diffResult.status !== 0) {
     return {
       ok: false,
@@ -64,7 +71,7 @@ function prepareNoisePatchForSquash(rootDir, { gitRunner = git } = {}) {
   const patchPath = path.join(patchDir, 'backlog-noise.patch');
   fs.writeFileSync(patchPath, patch, 'utf8');
 
-  const resetResult = gitRunner(['-C', rootDir, 'reset', '--hard', 'HEAD']);
+  const resetResult = runner(['-C', rootDir, 'reset', '--hard', 'HEAD']);
   if (resetResult.status !== 0) {
     return {
       ok: false,
@@ -80,9 +87,11 @@ function prepareNoisePatchForSquash(rootDir, { gitRunner = git } = {}) {
   };
 }
 
-function restoreNoisePatchAfterSquash(rootDir, patchPath, { gitRunner = git } = {}) {
-  if (!patchPath) return { ok: true };
-  const applyResult = gitRunner(['-C', rootDir, 'apply', '--index', patchPath]);
+/** @param {string} rootDir @param {string|null} patchPath @param {{gitRunner?: Function}} opts */
+function restoreNoisePatchAfterSquash(rootDir, patchPath, opts = {}) {
+  if (!patchPath) {return { ok: true };}
+  const runner = opts.gitRunner || git;
+  const applyResult = runner(['-C', rootDir, 'apply', '--index', patchPath]);
   if (applyResult.status !== 0) {
     return {
       ok: false,
@@ -92,6 +101,7 @@ function restoreNoisePatchAfterSquash(rootDir, patchPath, { gitRunner = git } =
   return { ok: true };
 }
 
+/** @param {string|null} taskAssignee */
 function resolveForgejoUserForIntegration(taskAssignee) {
   // If taskAssignee is set, use it directly as the Forgejo user identity.
   // This ensures that even non-agent assignees (e.g., human users) have their
@@ -105,13 +115,15 @@ function resolveForgejoUserForIntegration(taskAssignee) {
 
   // Fall back to environment variable or default only when no assignee is available
   return {
-    forgejoUser: resolveForgejoUser(),
+    forgejoUser: resolveForgejoUser(""),
     warning: null
   };
 }
 
-function getUnresolvedIndexConflicts(rootDir = getPrimaryWorktree(), { gitRunner = git } = {}) {
-  const result = gitRunner(['-C', rootDir, 'ls-files', '-u']);
+/** @param {string} rootDir @param {{gitRunner?: Function}} opts */
+function getUnresolvedIndexConflicts(rootDir = getPrimaryWorktree(), opts = {}) {
+  const runner = opts.gitRunner || git;
+  const result = runner(['-C', rootDir, 'ls-files', '-u']);
   if (result.status !== 0) {
     return {
       ok: false,
@@ -123,9 +135,9 @@ function getUnresolvedIndexConflicts(rootDir = getPrimaryWorktree(), { gitRunner
   const files = Array.from(new Set(
     result.stdout
       .split('\n')
-      .map(line => line.trim())
+      .map((/** @type{string} */ line) => line.trim())
       .filter(Boolean)
-      .map(line => line.split('\t')[1])
+      .map((/** @type{string} */ line) => line.split('\t')[1])
       .filter(Boolean)
   ));
 
@@ -143,20 +155,19 @@ function parseStashPopCollisionFiles(output = '') {
     .map(line => line.replace(/\s+already exists, no checkout$/i, ''));
 }
 
-function reportStashPopFailure(
-  slug,
-  restoreResult,
-  {
-    rootDir = getPrimaryWorktree(),
-    gitRunner = git,
-    getUnresolvedIndexConflictsFn = targetRootDir => getUnresolvedIndexConflicts(targetRootDir, { gitRunner })
-  } = {}
-) {
+/**
+ * @param {string} slug
+ * @param {{stdout: string, stderr: string, status: number}} restoreResult
+ * @param {{rootDir?: string, gitRunner?: Function, getUnresolvedIndexConflictsFn?: Function}} opts
+ */
+function reportStashPopFailure(slug, restoreResult, opts = {}) {
   const output = [restoreResult.stdout, restoreResult.stderr].filter(Boolean).join('\n').trim();
-  const headResult = gitRunner(['-C', rootDir, 'log', '-1', '--oneline']);
+  const runner = opts.gitRunner || git;
+  const rootDir = opts.rootDir || getPrimaryWorktree();
+  const headResult = runner(['-C', rootDir, 'log', '-1', '--oneline']);
   const headLine = headResult.status === 0 ? headResult.stdout.trim() : '(unavailable)';
   const integrationLanded = headLine.includes(`${missionBranchName(slug, rootDir)}:`);
-  const indexConflicts = getUnresolvedIndexConflictsFn(rootDir);
+  const indexConflicts = (opts.getUnresolvedIndexConflictsFn || getUnresolvedIndexConflicts)(rootDir);
   const collisionFiles = parseStashPopCollisionFiles(output);
 
   fmt.log.fail('Could not restore the temporarily stashed local integration checkout changes.');
@@ -168,10 +179,10 @@ function reportStashPopFailure(
 
   if (indexConflicts.ok && indexConflicts.files.length > 0) {
     fmt.log.fail('Stash restore failure type: merge-conflict');
-    indexConflicts.files.forEach(file => fmt.log.fail(`  - ${file}`));
+    indexConflicts.files.forEach((/** @type{string} */ file) => fmt.log.fail(`  - ${file}`));
     fmt.log.fail('Recovery steps:');
     fmt.log.fail(`  1. cd ${rootDir}`);
-    indexConflicts.files.forEach(file => {
+    indexConflicts.files.forEach((/** @type{string} */ file) => {
       fmt.log.fail(`  2. Resolve ${file}, then run git add "${file}" or git rm "${file}"`);
     });
     fmt.log.fail('  3. git status --short');
@@ -179,12 +190,12 @@ function reportStashPopFailure(
   } else {
     fmt.log.fail('Stash restore failure type: file-collision');
     if (collisionFiles.length > 0) {
-      collisionFiles.forEach(file => fmt.log.fail(`  - ${file}`));
+      collisionFiles.forEach((/** @type{string} */ file) => fmt.log.fail(`  - ${file}`));
     }
     fmt.log.fail('Recovery steps:');
     fmt.log.fail(`  1. git -C ${rootDir} stash show --name-only stash@{0}`);
     if (collisionFiles.length > 0) {
-      collisionFiles.forEach(file => {
+      collisionFiles.forEach((/** @type{string} */ file) => {
         fmt.log.fail(`  2. mv ${path.join(rootDir, file)} ${path.join(rootDir, `${file}.pre-stash-pop`)}`);
       });
       fmt.log.fail(`  3. git -C ${rootDir} stash pop`);
@@ -210,6 +221,7 @@ function printDiagnosticTable() {
   fmt.log.info('------------------------------------\n');
 }
 
+/** @param {{statusCode?: number, error: string, raw?: string}} syncResult */
 function reportSyncMergedFailure(syncResult) {
   const detail = syncResult.statusCode ? ` (${syncResult.error}: ${syncResult.statusCode})` : ` (${syncResult.error})`;
   fmt.log.fail(`Forgejo sync-merged failed${detail}.`);
@@ -227,18 +239,20 @@ const INTEGRATION_CONFIG_PATH = path.join(getPrimaryWorktree(), 'config', 'integ
  * Detect which top-level areas have been modified in the mission branch vs primary branch
  * Returns an array of area names (e.g., ['server', 'auth-server', 'web-client'])
  */
-function detectChangedAreas(slug, { gitRunner = git, rootDir = getPrimaryWorktree(), baseBranch = null } = {}) {
-  const primaryBranch = baseBranch || getPrimaryBranch();
+/** @param {string} slug @param {{gitRunner?: Function, rootDir?: string, baseBranch?: string|null}} opts */
+function detectChangedAreas(slug, opts = {}) {
+  const primaryBranch = opts.baseBranch || getPrimaryBranch();
   const branch = `mission/${slug}`;
+  const runner = opts.gitRunner || git;
   
   // Get changed files between primary branch and mission branch
-  const diffResult = gitRunner(['-C', rootDir, 'diff', '--name-only', primaryBranch, branch, '--']);
+  const diffResult = runner(['-C', opts.rootDir || getPrimaryWorktree(), 'diff', '--name-only', primaryBranch, branch, '--']);
   
   if (diffResult.status !== 0 && !diffResult.stdout.trim()) {
     // No changes or error - fall back to checking against HEAD in the worktree
-    const worktree = resolveWorktree(slug) || conventionalWorktreePath(slug, rootDir);
+    const worktree = resolveWorktree(slug) || conventionalWorktreePath(slug, opts.rootDir);
     if (fs.existsSync(worktree)) {
-      const worktreeDiff = gitRunner(['-C', worktree, 'diff', '--name-only', primaryBranch, 'HEAD', '--']);
+      const worktreeDiff = runner(['-C', worktree, 'diff', '--name-only', primaryBranch, 'HEAD', '--']);
       if (worktreeDiff.status === 0 && worktreeDiff.stdout.trim()) {
         return parseFilesToAreas(worktreeDiff.stdout);
       }
@@ -252,13 +266,14 @@ function detectChangedAreas(slug, { gitRunner = git, rootDir = getPrimaryWorktre
 /**
  * Parse a list of files (one per line) and extract the top-level area directories
  */
+/** @param {string} filesOutput */
 function parseFilesToAreas(filesOutput) {
   const areas = new Set();
-  const knownAreas = ['server', 'auth-server', 'web-client', 'docs', 'workflow', 'android', 'kubernetes'];
+  const knownAreas = ['lib', 'server', 'auth-server', 'web-client', 'docs', 'workflow', 'android', 'kubernetes'];
   
-  filesOutput.split('\n').forEach(file => {
+  filesOutput.split('\n').forEach((/** @type{string} */ file) => {
     file = file.trim();
-    if (!file) return;
+    if (!file) {return;}
     const topDir = file.split('/')[0];
     if (knownAreas.includes(topDir)) {
       areas.add(topDir);
@@ -271,7 +286,9 @@ function parseFilesToAreas(filesOutput) {
 /**
  * Load integration pipelines config from repo-side file
  */
-function loadIntegrationConfig({ configPath = INTEGRATION_CONFIG_PATH } = {}) {
+/** @param {{configPath?: string}} opts */
+function loadIntegrationConfig(opts = {}) {
+  const configPath = opts.configPath || INTEGRATION_CONFIG_PATH;
   if (!fs.existsSync(configPath) || !fs.statSync(configPath).size) {
     return { ok: false, error: 'no config present' };
   }
@@ -280,7 +297,7 @@ function loadIntegrationConfig({ configPath = INTEGRATION_CONFIG_PATH } = {}) {
     const content = fs.readFileSync(configPath, 'utf8');
     const config = JSON.parse(content);
     return { ok: true, config };
-  } catch (error) {
+  } catch (/** @type{any} */ error) {
     return { ok: false, error: `invalid JSON: ${error.message}` };
   }
 }
@@ -289,11 +306,12 @@ function loadIntegrationConfig({ configPath = INTEGRATION_CONFIG_PATH } = {}) {
  * Get the integration gate plan for changed areas
  * Returns { gates: [{key, command, run_last}], changedAreas: [...] }
  */
-function getIntegrationGatePlan(slug, { runIntegrationGates = true, gitRunner = git, dryRun = false, configPath = INTEGRATION_CONFIG_PATH } = {}) {
+/** @param {string} slug @param {{runIntegrationGates?: boolean, gitRunner?: Function, dryRun?: boolean, configPath?: string}} opts */
+function getIntegrationGatePlan(slug, opts = {}) {
   // Check config
-  const configResult = loadIntegrationConfig({ configPath });
+  const configResult = loadIntegrationConfig(opts);
   if (!configResult.ok) {
-    if (runIntegrationGates) {
+    if (opts.runIntegrationGates) {
       fmt.log.info(`integration-gates: ${configResult.error}, skipping`);
     }
     return { gates: [], changedAreas: [], configError: configResult.error };
@@ -301,16 +319,16 @@ function getIntegrationGatePlan(slug, { runIntegrationGates = true, gitRunner =
   
   const config = configResult.config;
   if (!config.gates || Object.keys(config.gates).length === 0) {
-    if (runIntegrationGates) {
+    if (opts.runIntegrationGates) {
       fmt.log.info('integration-gates: no gates defined in config, skipping');
     }
     return { gates: [], changedAreas: [], configError: 'no gates defined' };
   }
   
   // Detect changed areas (always detect for dry-run; for real run, detect only if runIntegrationGates)
-  const changedAreas = (runIntegrationGates || dryRun) ? detectChangedAreas(slug, { gitRunner }) : [];
+  const changedAreas = (opts.runIntegrationGates || opts.dryRun) ? detectChangedAreas(slug, opts) : [];
   
-  if (runIntegrationGates && !dryRun && changedAreas.length === 0) {
+  if (opts.runIntegrationGates && !opts.dryRun && changedAreas.length === 0) {
     fmt.log.info('integration-gates: no area changes detected, skipping');
     return { gates: [], changedAreas: [], configError: null };
   }
@@ -351,6 +369,7 @@ function getIntegrationGatePlan(slug, { runIntegrationGates = true, gitRunner =
 /**
  * Print the integration gate plan (for --dry-run)
  */
+/** @param{{key: string, command: string, order: number, run_last: boolean}[]} gates */
 function printIntegrationGatePlan(gates) {
   fmt.log.info('Integration gate plan:');
   for (const gate of gates) {
@@ -358,22 +377,21 @@ function printIntegrationGatePlan(gates) {
   }
 }
 
-function buildIntegrationGateEnv(slug, {
-  dryRun = false,
-  processEnv = process.env,
-  gitRunner = git,
-  baseBranch = null,
-  baseWorktree = null
-} = {}) {
-  const env = {
-    ...processEnv,
-    INTEGRATE_DRY_RUN: dryRun ? 'true' : 'false',
+/**
+ * @param {string} slug
+ * @param {{dryRun?: boolean, processEnv?: NodeJS.ProcessEnv, gitRunner?: Function, baseBranch?: string|null, baseWorktree?: string|null}} opts
+ */
+function buildIntegrationGateEnv(slug, opts = {}) {
+  /** @type {{[key: string]: string | undefined}} */
+  const env = /** @type {{[key: string]: string | undefined}} */ ({
+    ...opts.processEnv,
+    INTEGRATE_DRY_RUN: opts.dryRun ? 'true' : 'false',
     INTEGRATE_CHANGED_AREAS: detectChangedAreas(slug, {
-      gitRunner,
-      baseBranch,
-      ...(baseWorktree ? { rootDir: baseWorktree } : {})
+      gitRunner: opts.gitRunner,
+      baseBranch: opts.baseBranch,
+      ...(opts.baseWorktree ? { rootDir: opts.baseWorktree } : {})
     }).join(' ')
-  };
+  });
 
   // Integration must always use the repo-side config, but the changed-area set
   // should be the one resolved for this mission branch, not rediscovered later.
@@ -381,28 +399,26 @@ function buildIntegrationGateEnv(slug, {
   return env;
 }
 
-function resolveIntegrationVerificationWorktree(slug, {
-  baseWorktree = getPrimaryWorktree(),
-  resolveWorktreeFn = resolveWorktree,
-  conventionalWorktreePathFn = conventionalWorktreePath
-} = {}) {
-  return resolveWorktreeFn(slug, { cwd: baseWorktree })
-    || conventionalWorktreePathFn(slug, baseWorktree);
+/**
+ * @param {string} slug
+ * @param {{baseWorktree?: string, resolveWorktreeFn?: Function, conventionalWorktreePathFn?: Function}} opts
+ */
+function resolveIntegrationVerificationWorktree(slug, opts = {}) {
+  const resolveFn = opts.resolveWorktreeFn || resolveWorktree;
+  const convFn = opts.conventionalWorktreePathFn || conventionalWorktreePath;
+  return resolveFn(slug, { cwd: opts.baseWorktree })
+    || convFn(slug, opts.baseWorktree);
 }
 
-function buildIntegrationVerificationInvocation(slug, {
-  baseWorktree = getPrimaryWorktree(),
-  resolveWorktreeFn = resolveWorktree,
-  conventionalWorktreePathFn = conventionalWorktreePath,
-  formatVerificationCommandFn = formatVerificationCommand
-} = {}) {
-  const cwd = resolveIntegrationVerificationWorktree(slug, {
-    baseWorktree,
-    resolveWorktreeFn,
-    conventionalWorktreePathFn
-  });
+/**
+ * @param {string} slug
+ * @param {{baseWorktree?: string, resolveWorktreeFn?: Function, conventionalWorktreePathFn?: Function, formatVerificationCommandFn?: Function}} opts
+ */
+function buildIntegrationVerificationInvocation(slug, opts = {}) {
+  const cwd = resolveIntegrationVerificationWorktree(slug, opts);
+  const fmtFn = opts.formatVerificationCommandFn || formatVerificationCommand;
   return {
-    command: formatVerificationCommandFn('integrate', cwd),
+    command: fmtFn('integrate', cwd),
     cwd
   };
 }
@@ -411,10 +427,14 @@ function buildIntegrationVerificationInvocation(slug, {
  * Execute integration gates, aborting on first failure
  * Returns { ok: boolean, failedGate: string|null, error: string|null }
  */
-async function executeIntegrationGates(gates, { commandRunner = null, rootDir = getPrimaryWorktree() } = {}) {
-  const runner = commandRunner || ((cmd, args, options) => require('child_process').spawnSync(cmd, {
+/**
+ * @param {{key: string, command: string, order: number, run_last: boolean}[]} gates
+ * @param {{commandRunner?: Function, rootDir?: string}} opts
+ */
+async function executeIntegrationGates(gates, opts = {}) {
+  const runner = opts.commandRunner || ((/** @type{string} */ cmd) => require('child_process').spawnSync(cmd, {
       shell: true,
-      cwd: rootDir,
+      cwd: opts.rootDir || getPrimaryWorktree(),
       stdio: 'inherit'
     }));
   
@@ -423,7 +443,7 @@ async function executeIntegrationGates(gates, { commandRunner = null, rootDir =
     fmt.log.info(`  Command: ${gate.command}`);
     
     // Execute the command using the injected runner
-    const result = runner(gate.command, [], { cwd: rootDir, stdio: 'inherit' });
+    const result = runner(gate.command, [], { cwd: opts.rootDir, stdio: 'inherit' });
     
     if (result.status !== 0) {
       fmt.log.fail(`Integration gate failed: ${gate.key}`);
@@ -438,17 +458,22 @@ async function executeIntegrationGates(gates, { commandRunner = null, rootDir =
   return { ok: true, failedGate: null, error: null };
 }
 
+/** @param {string[]} args */
 async function integrate(args) {
   let exitCode = 0;
+  /** @type{{created?: boolean, message?: string, rootDir?: string}|null} */
   let temporaryStash = null;
   let nextActionMessage = null;
-  const flags = args.filter(arg => arg.startsWith('--'));
-  const params = args.filter(arg => !arg.startsWith('--'));
+  const flags = args.filter((/** @type{string} */ arg) => arg.startsWith('--'));
+  const params = args.filter((/** @type{string} */ arg) => !arg.startsWith('--'));
   const explicitSlug = params[0];
   const slug = inferSlug(explicitSlug);
   const dryRun = flags.includes('--dry-run');
   const noIntegrationGates = flags.includes('--no-integration-gates');
 
+  /** @type {{slug: string, branch: string, currentBranch: string, missionDir?: string, area: string, task: {ok: boolean, taskFile?: string, reason?: string, matches?: string[]}, taskStatus?: string, taskAssignee?: string|null, forgejoUser?: string|null, forgejoToken?: string|null, taskAssigneeWarning?: string|null, pr: {exists?: boolean, state?: string, number?: number, merged?: boolean, raw?: string}, siblingPrs: any[], approval: {ok?: boolean, error?: string, reviewState?: string, defaultUserApproved?: boolean, source?: string}, baseBranch?: string, baseWorktree?: string, mainBranch: string, mainDirtyEntries: string[], mainDirty: boolean}} */
+  let context;
+
   if (process.env.FORGEJO_USER === 'gemini' || process.env.WORKFLOW_AGENT === 'gemini') {
     fmt.log.fail('Gemini is not authorized to run integrate. Post a handoff comment on the PR and stop.');
     process.exit(1);
@@ -459,55 +484,70 @@ async function integrate(args) {
     process.exit(1);
   }
 
-  if (flags.includes('--no-gate')) {
-    fmt.log.warn('integrate ignores --no-gate. The landed squash commit relies on the local git hooks for validation.');
-  }
-
-  try {
-    const executionDir = process.cwd();
-    const context = buildIntegrationContext(slug);
-    // The integration target is the mission's recorded base worktree/branch.
-    // For legacy missions these resolve to the primary worktree/branch, keeping
-    // the merge/commit/sync path byte-identical to today.
-    const baseWorktree = context.baseWorktree;
-    const baseBranch = context.baseBranch;
-    const { failures } = printIntegrationPreflight(context);
-
-    if (failures.length > 0) {
-      fmt.log.fail('\nIntegration preflight failed. Resolve the blockers above before running integrate.');
-      throw new IntegrationAbort();
+    if (flags.includes('--no-gate')) {
+      fmt.log.warn('integrate ignores --no-gate. The landed squash commit relies on the local git hooks for validation.');
     }
 
-    if (!noIntegrationGates) {
-      const verification = buildIntegrationVerificationInvocation(slug, { baseWorktree });
-      const env = buildIntegrationGateEnv(slug, { dryRun, baseBranch, baseWorktree });
-      
-      if (dryRun) {
-        fmt.log.info('Running integration gates (dry-run)...');
-      } else {
-        fmt.log.info('Running integration gates...');
-      }
-      
-      const result = child_process.spawnSync('bash', ['-lc', verification.command], {
-        cwd: verification.cwd,
-        env,
-        stdio: 'inherit'
-      });
-      
-      if (result.status !== 0) {
-        fmt.log.fail(`\nIntegration gates failed with exit code ${result.status}`);
-        fmt.log.fail('Aborting before merge.');
+    try {
+      const executionDir = process.cwd();
+      // @ts-expect-error buildIntegrationContext return type mismatch
+      context = buildIntegrationContext(slug);
+      // The integration target is the mission's recorded base worktree/branch.
+      // For legacy missions these resolve to the primary worktree/branch, keeping
+      // the merge/commit/sync path byte-identical to today.
+      const baseWorktree = context.baseWorktree;
+      const baseBranch = context.baseBranch;
+      const { failures } = printIntegrationPreflight(context);
+
+      if (failures.length > 0) {
+        fmt.log.fail('\nIntegration preflight failed. Resolve the blockers above before running integrate.');
         throw new IntegrationAbort();
       }
-      
-      if (!dryRun) {
-        fmt.log.pass('All integration gates passed.');
+
+      if (!noIntegrationGates) {
+        const verification = buildIntegrationVerificationInvocation(slug, { baseWorktree });
+        const env = buildIntegrationGateEnv(slug, { dryRun, baseBranch, baseWorktree });
+        
+        if (dryRun) {
+          fmt.log.info('Running integration gates (dry-run)...');
+        } else {
+          fmt.log.info('Running integration gates...');
+        }
+        
+        const result = child_process.spawnSync('bash', ['-lc', verification.command], {
+          cwd: verification.cwd,
+          env,
+          stdio: 'inherit'
+        });
+        
+        if (result.status !== 0) {
+          fmt.log.fail(`\nIntegration gates failed with exit code ${result.status}`);
+          fmt.log.fail('Aborting before merge.');
+          throw new IntegrationAbort();
+        }
+        
+        if (!dryRun) {
+          fmt.log.pass('All integration gates passed.');
+        }
+      } else {
+        fmt.log.info('Integration gates skipped via --no-integration-gates flag');
       }
-    } else {
-      fmt.log.info('Integration gates skipped via --no-integration-gates flag');
-    }
 
-    if (dryRun) {
+      if (dryRun) {
+        promoteTaskForIntegrationIfNeeded(context, { dryRun: true });
+        fmt.log.pass('\nDry run complete. Integration preflight passed.');
+        return;
+      }
+
+      promoteTaskForIntegrationIfNeeded(context);
+
+      temporaryStash = stashMainCheckoutIfNeeded({
+        slug,
+        dirtyEntries: context.mainDirtyEntries,
+        rootDir: /** @type{string} */(baseWorktree)
+      });
+
+      if (dryRun) {
       promoteTaskForIntegrationIfNeeded(context, { dryRun: true });
       fmt.log.pass('\nDry run complete. Integration preflight passed.');
       return;
@@ -526,6 +566,7 @@ async function integrate(args) {
     const missionWorktree = conventionalWorktreePath(slug);
     if (process.cwd() === missionWorktree || process.cwd().startsWith(missionWorktree + '/')) {
       fmt.log.info(`Moving process directory to ${baseWorktree} before mission worktree deletion.`);
+      // @ts-expect-error baseWorktree may be undefined
       process.chdir(baseWorktree);
     }
 
@@ -533,6 +574,7 @@ async function integrate(args) {
     const branch = missionBranchName(slug, baseWorktree);
     const mainTitle = missionTitle(slug) || slug;
     const summary = mainTitle.replace(/\s+/g, ' ').trim();
+    // @ts-expect-error context.task.taskFile may be undefined
     const mainTaskFile = context.task.taskFile.replace(executionDir, baseWorktree);
     const useVariantA = context.pr.merged;
     fmt.log.info(`Selecting integration variant: ${useVariantA ? 'Variant A (fast-path)' : 'Variant B (full squash-merge)'}`);
@@ -569,8 +611,11 @@ async function integrate(args) {
       fmt.log.info(`\nStep 1: Using base worktree ${baseWorktree} on ${baseBranch} as the squash-merge target...`);
 
       fmt.log.info(`Step 2: Checking merge conflicts against local ${baseBranch} in the base worktree...`);
+      // @ts-expect-error baseWorktree may be undefined
       const dryMerge = git(['-C', baseWorktree, 'merge', '--no-commit', '--no-ff', branch]);
+      // @ts-expect-error baseWorktree may be undefined
       const abortResult = git(['-C', baseWorktree, 'merge', '--abort']);
+      // @ts-expect-error dryMerge/abortResult type mismatch
       if (abortResult.status !== 0 && !isNoMergeToAbortResult(abortResult)) {
         fmt.log.fail('Dry-run merge could not be aborted cleanly. Inspect the local integration checkout before retrying integrate.');
         throw new IntegrationAbort();
@@ -578,6 +623,7 @@ async function integrate(args) {
       if (dryMerge.status !== 0) {
         // Before failing, check if a squash commit for this mission already landed on the primary branch
         // from a previous partial integration run (e.g. sync-merged failed after the commit was created).
+        // @ts-expect-error baseWorktree may be undefined
         const existingSquash = findExistingSquashCommit(baseWorktree, slug);
         if (existingSquash) {
           fmt.log.warn(`Squash commit already exists on local ${baseBranch} from a previous partial integration (${existingSquash.slice(0, 12)}). Resuming from sync-merged step.`);
@@ -591,6 +637,7 @@ async function integrate(args) {
               baseBranch: context.baseBranch
             });
             if (!syncResult.ok) {
+              // @ts-expect-error reportSyncMergedFailure expects {statusCode, error}
               reportSyncMergedFailure(syncResult);
               throw new IntegrationAbort();
             }
@@ -608,7 +655,7 @@ async function integrate(args) {
           fmt.log.pass('Integration completed successfully (resumed from partial state).');
         } else {
           fmt.log.fail('Merge conflicts detected. Rebase the mission branch before integrating.');
-          const conflictOutput = [dryMerge.stdout, dryMerge.stderr].filter(Boolean).join('\n');
+          const conflictOutput = [/** @type {any} */ (dryMerge).stdout, /** @type {any} */ (dryMerge).stderr].filter(Boolean).join('\n');
           const conflictFiles = parseConflictFilesFromMergeOutput(conflictOutput);
           if (conflictFiles.length > 0) {
             fmt.log.info(`Conflicting files (${conflictFiles.length}):`);
@@ -618,7 +665,7 @@ async function integrate(args) {
           for (const line of formatMatrixSummary(buildAutonomousReviewMatrix())) {
             fmt.log.info(line);
           }
-          for (const line of buildConflictResolutionPrompt(slug, context.area, { baseBranch: context.baseBranch })) {
+          for (const line of buildConflictResolutionPrompt(slug, context.area, { baseBranch: context.baseBranch || '' })) {
             fmt.log.info(line);
           }
           throw new IntegrationAbort();
@@ -626,7 +673,9 @@ async function integrate(args) {
       } else {
         fmt.log.info('Step 3: Squash-merging the mission branch...');
         let noisePatchState = null;
+        // @ts-expect-error baseWorktree may be undefined
         if (softResetTrailingBacklogNoise(baseWorktree, git)) {
+          // @ts-expect-error baseWorktree may be undefined
           noisePatchState = prepareNoisePatchForSquash(baseWorktree, { gitRunner: git });
           if (!noisePatchState.ok) {
             fmt.log.fail('Could not preserve trailing backlog noise before squash merge.');
@@ -636,6 +685,7 @@ async function integrate(args) {
             throw new IntegrationAbort();
           }
         }
+        // @ts-expect-error baseWorktree may be undefined
         const squashResult = git(['-C', baseWorktree, 'merge', '--squash', branch]);
         if (squashResult.status !== 0) {
           noisePatchState?.cleanup?.();
@@ -643,8 +693,8 @@ async function integrate(args) {
           throw new IntegrationAbort();
         }
         if (noisePatchState?.patchPath) {
-          const restoreNoiseResult = restoreNoisePatchAfterSquash(baseWorktree, noisePatchState.patchPath, { gitRunner: git });
-          noisePatchState.cleanup();
+          const restoreNoiseResult = restoreNoisePatchAfterSquash(/** @type {string} */ (baseWorktree), noisePatchState.patchPath, { gitRunner: git });
+          /** @type {Function} */ (noisePatchState.cleanup)();
           if (!restoreNoiseResult.ok) {
             fmt.log.fail('Could not restore trailing backlog noise after squash merge.');
             if (restoreNoiseResult.error) {
@@ -660,15 +710,17 @@ async function integrate(args) {
           // Re-resolve because it moved
           const updatedResolution = resolveTaskFile(slug, baseWorktree);
           if (updatedResolution.ok) {
+            // @ts-expect-error baseWorktree may be undefined
             rewriteWorktreePaths(updatedResolution.taskFile, slug, { rootDir: baseWorktree });
           }
         }
 
+        // @ts-expect-error baseWorktree may be undefined
         git(['-C', baseWorktree, 'add', '-A']);
         fmt.log.info('Step 5: Creating the landed squash commit in the local integration checkout...');
         const commitResult = git([
           '-C',
-          baseWorktree,
+          /** @type {string} */ (baseWorktree),
           'commit',
           '-m',
           `${branch}: ${summary}`
@@ -685,17 +737,18 @@ async function integrate(args) {
         }
         const proofResult = verification.captureVerifiedTreeProof(context.area, baseWorktree, {
           gitRunner: git,
-          runFn: child_process.spawnSync
+          runFn: /** @type {Function} */ (child_process.spawnSync)
         });
-        if (!proofResult.ok) {
-          fmt.log.fail(`Could not verify the exact tree being published: ${proofResult.error}`);
+        if (!/** @type {any} */ (proofResult).ok) {
+          fmt.log.fail(`Could not verify the exact tree being published: ${/** @type {any} */ (proofResult).error}`);
           throw new IntegrationAbort();
         }
-        const proof = proofResult.proof;
+        const proof = /** @type {any} */ (proofResult).proof;
+        // @ts-expect-error baseWorktree may be undefined
         const mergedCommit = git(['-C', baseWorktree, 'rev-parse', 'HEAD']).stdout.trim();
         const proofCheck = verification.assertVerifiedTreeProof(proof, baseWorktree, { gitRunner: git });
         if (!proofCheck.ok) {
-          fmt.log.fail(`Verification proof is stale for the publish tree: ${proofCheck.error}`);
+          fmt.log.fail(`Verification proof is stale for the publish tree: ${/** @type {any} */ (proofCheck).error}`);
           throw new IntegrationAbort();
         }
 
@@ -708,6 +761,7 @@ async function integrate(args) {
             baseBranch: context.baseBranch
           });
           if (!syncResult.ok) {
+            // @ts-expect-error reportSyncMergedFailure expects {statusCode, error}
             reportSyncMergedFailure(syncResult);
             throw new IntegrationAbort();
           }
@@ -731,13 +785,13 @@ async function integrate(args) {
     if (error instanceof IntegrationAbort) {
       exitCode = 1;
     } else {
-      throw error;
+      throw /** @type {any} */ (error);
     }
   } finally {
     if (temporaryStash?.created) {
-      const restoreResult = restoreMainCheckoutStash(temporaryStash);
+        const restoreResult = restoreMainCheckoutStash(/** @type {any} */ (temporaryStash));
       if (restoreResult.status !== 0) {
-        reportStashPopFailure(slug, restoreResult, { rootDir: temporaryStash.rootDir });
+        reportStashPopFailure(slug, restoreResult, { rootDir: /** @type {any} */ (temporaryStash).rootDir });
         exitCode = 1;
       }
     }
@@ -749,6 +803,7 @@ async function integrate(args) {
   }
 }
 
+/** @param {string} slug @param{{baseBranch?: string|null, baseWorktree?: string|null, isForgejoReviewEnabledFn?: Function}} opts */
 function buildIntegrationContext(slug, {
   baseBranch = null,
   baseWorktree = null,
@@ -773,15 +828,15 @@ function buildIntegrationContext(slug, {
   let task = resolveTaskFile(slug);
   if (!task.ok) {
     const worktree = resolveWorktree(slug);
-    if (worktree) task = resolveTaskFile(slug, worktree);
+    if (worktree) {task = resolveTaskFile(slug, worktree);}
   }
-  let taskStatus = task.ok ? getTaskStatus(task.taskFile) : null;
+  let taskStatus = task.ok ? getTaskStatus(/** @type {string} */ (task.taskFile)) : null;
   if (task.ok && taskStatus === 'backlog') {
     const worktree = resolveWorktree(slug);
     if (worktree) {
       const wtTask = resolveTaskFile(slug, worktree);
       if (wtTask.ok) {
-        const wtStatus = getTaskStatus(wtTask.taskFile);
+        const wtStatus = getTaskStatus(/** @type {string} */ (wtTask.taskFile));
         if (wtStatus && wtStatus !== 'backlog') {
           task = wtTask;
           taskStatus = wtStatus;
@@ -789,22 +844,24 @@ function buildIntegrationContext(slug, {
       }
     }
   }
-  const taskAssignee = task.ok ? getTaskAssignee(task.taskFile) : null;
-  const forgejoEnabled = isForgejoReviewEnabledFn(resolvedBaseWorktree);
+  const taskAssignee = task.ok ? getTaskAssignee(/** @type {string} */ (task.taskFile)) : null;
+  const forgejoEnabled = isForgejoReviewEnabledFn(/** @type {string} */ (resolvedBaseWorktree));
   
   let forgejoIdentity = { forgejoUser: null, warning: null };
   let forgejoToken = null;
   let pr = { exists: false };
-  let siblingPrs = [];
+  /** @type{any[]} */ let siblingPrs = [];
   let approval = { ok: false, error: 'forgejo-off', reviewState: null };
 
   if (forgejoEnabled) {
+    // @ts-expect-error forgejoIdentity.forgejoUser type mismatch
     forgejoIdentity = resolveForgejoUserForIntegration(taskAssignee);
-    forgejoToken = readToken(forgejoIdentity.forgejoUser);
-    pr = getPrStatus(branch, process.cwd(), {
-      forgejoUser: forgejoIdentity.forgejoUser,
+    forgejoToken = readToken(/** @type {any} */ (forgejoIdentity.forgejoUser));
+    pr = /** @type {any} */ (getPrStatus(branch, process.cwd(), {
+      forgejoUser: /** @type {any} */ (forgejoIdentity.forgejoUser),
+      // @ts-expect-error forgejoToken may be null
       token: forgejoToken
-    });
+    }));
     
     if (pr.exists && slug) {
       const baseSlugMatch = slug.match(/^(task-\d+)/i);
@@ -815,10 +872,10 @@ function buildIntegrationContext(slug, {
       }
     }
 
-    approval = pr.exists ? getLatestReviewDecision(branch, {
-      forgejoUser: forgejoIdentity.forgejoUser,
-      token: forgejoToken
-    }) : { ok: false, error: 'pr-missing', reviewState: null };
+    approval = pr.exists ? /** @type {any} */ (getLatestReviewDecision(branch, {
+      forgejoUser: /** @type {any} */ (forgejoIdentity.forgejoUser),
+      token: /** @type {any} */ (forgejoToken)
+    })) : /** @type {any} */ ({ ok: false, error: 'pr-missing', reviewState: undefined });
   }
 
   // Local review-state fallback: when forgejo token/API is unavailable but the
@@ -826,15 +883,15 @@ function buildIntegrationContext(slug, {
   // so that integrate can proceed without a live Forgejo connection.
   // Only applies when Forgejo was enabled but approval could not be obtained.
   if (forgejoEnabled && !approval.ok) {
-    const localStateFallback = readReviewState(slug, resolvedBaseWorktree);
+    const localStateFallback = readReviewState(slug, /** @type {string} */ (resolvedBaseWorktree));
     if (localStateFallback && localStateFallback.phase === 'approved' && localStateFallback.disposition === 'APPROVED') {
-      approval = { ok: true, reviewState: 'APPROVED', source: 'local-review-state' };
+      approval = /** @type {any} */ ({ ok: true, reviewState: 'APPROVED', source: 'local-review-state' });
     }
   }
   
-  const mainBranchResult = git(['-C', resolvedBaseWorktree, 'branch', '--show-current']);
+  const mainBranchResult = git(['-C', /** @type {string} */ (resolvedBaseWorktree), 'branch', '--show-current']);
   const mainBranch = mainBranchResult.stdout.trim();
-  const mainStatus = git(['-C', resolvedBaseWorktree, 'status', '--short']);
+  const mainStatus = git(['-C', /** @type {string} */ (resolvedBaseWorktree), 'status', '--short']);
 
   return {
     slug,
@@ -861,9 +918,11 @@ function buildIntegrationContext(slug, {
   };
 }
 
+/** @param {{slug: string, branch: string, currentBranch: string, missionDir?: string, area: string, task: {ok: boolean, taskFile?: string, reason?: string, matches?: string[]}, taskStatus?: string, taskAssignee?: string|null, forgejoUser?: string|null, forgejoToken?: string|null, taskAssigneeWarning?: string|null, pr: {exists?: boolean, state?: string, number?: number, merged?: boolean, raw?: string}, siblingPrs: any[], approval: {ok?: boolean, error?: string, reviewState?: string, defaultUserApproved?: boolean, source?: string}, baseBranch?: string, baseWorktree?: string, mainBranch: string, mainDirtyEntries: string[], mainDirty: boolean}} context */
 function evaluateTaskStatusForIntegration(context) {
-  const stateMapOptions = { rootDir: context.baseWorktree };
-  if (toVirtual(context.taskStatus, stateMapOptions) === 'approved') {
+  const stateMapOptions = { rootDir: /** @type {string} */ (context.baseWorktree) };
+  // @ts-expect-error context.taskStatus may be undefined
+  if (toVirtual(context.taskStatus, /** @type {any} */ (stateMapOptions)) === 'approved') {
     return {
       ok: true,
       level: 'pass',
@@ -904,10 +963,12 @@ function evaluateTaskStatusForIntegration(context) {
   return {
     ok: false,
     level: 'fail',
+    // @ts-expect-error stateMapOptions type mismatch
     message: `Backlog status: expected approved, or review with an approved/merged Forgejo PR; found ${toVirtual(context.taskStatus, stateMapOptions)}`
   };
 }
 
+/** @param {{slug: string, branch: string, currentBranch: string, missionDir?: string, area: string, task: {ok: boolean, taskFile?: string, reason?: string, matches?: string[]}, taskStatus?: string, taskAssignee?: string|null, forgejoUser?: string|null, forgejoToken?: string|null, taskAssigneeWarning?: string|null, pr: {exists?: boolean, state?: string, number?: number, merged?: boolean, raw?: string}, siblingPrs: any[], approval: {ok?: boolean, error?: string, reviewState?: string, defaultUserApproved?: boolean, source?: string}, baseBranch?: string, baseWorktree?: string, mainBranch: string, mainDirtyEntries: string[], mainDirty: boolean}} context */
 function promoteTaskForIntegrationIfNeeded(context, { dryRun = false } = {}) {
   const taskStatusCheck = evaluateTaskStatusForIntegration(context);
   const needsPromotion = context.task?.ok && context.taskStatus === 'review' && taskStatusCheck.ok;
@@ -921,8 +982,8 @@ function promoteTaskForIntegrationIfNeeded(context, { dryRun = false } = {}) {
     return { changed: false, dryRun: true };
   }
 
-  const stateMapOptions = { rootDir: context.baseWorktree };
-  if (!setTaskStatus(context.task.taskFile, toActual('approved', stateMapOptions))) {
+  const stateMapOptions = { rootDir: /** @type {string} */ (context.baseWorktree) };
+  if (!setTaskStatus(/** @type {string} */ (context.task.taskFile), toActual('approved', stateMapOptions))) {
     fmt.log.fail('Could not promote the Backlog task to approved before integration.');
     throw new IntegrationAbort();
   }
@@ -932,6 +993,9 @@ function promoteTaskForIntegrationIfNeeded(context, { dryRun = false } = {}) {
   return { changed: true, dryRun: false };
 }
 
+/**
+ * @param{{slug: string, branch: string, missionDir?: string, area: string, task: {ok: boolean, taskFile?: string, reason?: string, matches?: string[]}, taskStatus?: string, taskAssignee?: string|null, forgejoUser?: string|null, forgejoToken?: string|null, taskAssigneeWarning?: string|null, pr: {exists?: boolean, state?: string, number?: number, merged?: boolean, raw?: string}, siblingPrs: any[], approval: {ok?: boolean, error?: string, reviewState?: string, defaultUserApproved?: boolean, source?: string}, baseBranch?: string, baseWorktree?: string, mainBranch: string, mainDirtyEntries: string[], mainDirty: boolean}} context
+ */
 function printIntegrationPreflight(
   context,
   {
@@ -956,11 +1020,14 @@ function printIntegrationPreflight(
   log(fmt.status('INFO', `Integration preflight for ${context.slug}`));
 
   const branchPrefix = missionBranchName(context.slug, baseWorktree);
-  if (context.currentBranch === context.branch || context.currentBranch.startsWith(`${branchPrefix}-`)) {
-    log(fmt.status('PASS', `Mission branch: ${context.currentBranch}`));
+  // @ts-expect-error context.currentBranch doesn't exist on type
+  if ((/** @type {any} */ context).currentBranch === context.branch || (/** @type {any} */ context).currentBranch.startsWith(`${branchPrefix}-`)) {
+    // @ts-expect-error context.currentBranch doesn't exist on type
+    log(fmt.status('PASS', `Mission branch: ${(/** @type {any} */ context).currentBranch}`));
   } else {
     failures.push('branch');
-    log(fmt.status('FAIL', `Mission branch: current branch is ${context.currentBranch}, expected ${context.branch} (or a branch with a suffix)`));
+    // @ts-expect-error context.currentBranch doesn't exist on type
+    log(fmt.status('FAIL', `Mission branch: current branch is ${(/** @type {any} */ context).currentBranch}, expected ${context.branch} (or a branch with a suffix)`));
   }
 
   if (context.missionDir) {
@@ -987,7 +1054,7 @@ function printIntegrationPreflight(
   }
 
   if (context.task.ok) {
-    log(fmt.status('PASS', `Backlog task: ${path.basename(context.task.taskFile)} (${context.taskStatus})`));
+    log(fmt.status('PASS', `Backlog task: ${path.basename(/** @type {string} */ (context.task.taskFile))} (${context.taskStatus})`));
     
     try {
       const { classification, error: classificationError } = stats.resolveMissionClassification(context.slug);
@@ -997,11 +1064,12 @@ function printIntegrationPreflight(
       } else {
         log(fmt.status('PASS', `Backlog classification: ${classification}`));
       }
-    } catch (error) {
+    } catch (/** @type{any} */ error) {
       failures.push('classification');
       log(fmt.status('FAIL', `Backlog classification: ${error.message}`));
     }
 
+    // @ts-expect-error context type mismatch (missing currentBranch)
     const taskStatusCheck = evaluateTaskStatusForIntegration(context);
     if (!taskStatusCheck.ok) {
       failures.push('task-status');
@@ -1015,7 +1083,8 @@ function printIntegrationPreflight(
   } else if (context.task.reason === 'ambiguous') {
     failures.push('task-ambiguity');
     log(fmt.status('FAIL', `Backlog task: ambiguous slug ${context.slug}`));
-    context.task.matches.forEach(match => log(`  - ${match}`));
+    // @ts-expect-error context.task.matches may be undefined
+    context.task.matches.forEach((/** @type{string} */ match) => log(`  - ${match}`));
   } else {
     log(fmt.status('WARN', `Backlog task: no task file found for ${context.slug}; continuing with synthetic/unknown task metadata.`));
     log(fmt.status('PASS', 'Backlog classification: unknown'));
@@ -1057,13 +1126,13 @@ function printIntegrationPreflight(
       const baseSlugMatch = context.slug.match(/^(task-\d+)/i);
       const baseSlug = baseSlugMatch ? baseSlugMatch[1].toLowerCase() : context.slug;
       log(fmt.status('WARN', `Multiple open PRs detected for ${baseSlug}. Close stale PRs before integrating:`));
-      context.siblingPrs.forEach(p => {
+      context.siblingPrs.forEach((/** @type{{number: number, head: string, html_url: string}} */ p) => {
         log(fmt.status('INFO', `  - PR #${p.number} (${p.head}): ${p.html_url}`));
       });
     }
 
-    const tokenPath = resolveTokenFileFn(context.forgejoUser);
-    const token = readTokenFn(context.forgejoUser);
+    const tokenPath = resolveTokenFileFn(/** @type {string} */ (context.forgejoUser));
+    const token = readTokenFn(/** @type {string} */ (context.forgejoUser));
     if (token) {
       log(fmt.status('PASS', `Forgejo token: resolved for ${context.forgejoUser} (${tokenPath || 'env:FORGEJO_TOKEN'})`));
     } else if (localApprovalFallback) {
@@ -1130,7 +1199,7 @@ function printIntegrationPreflight(
   if (context.mainDirty) {
     warnings.push('main-dirty');
     log(fmt.status('WARN', `Integration checkout dirty: ${baseWorktree} has uncommitted changes that will be stashed temporarily`));
-    context.mainDirtyEntries.forEach(entry => log(fmt.status('INFO', `  - ${entry}`)));
+    context.mainDirtyEntries.forEach((/** @type{string} */ entry) => log(fmt.status('INFO', `  - ${entry}`)));
   } else {
     log(fmt.status('PASS', 'Integration checkout dirty state: clean'));
   }
@@ -1156,6 +1225,7 @@ function printIntegrationPreflight(
   return { failures, warnings };
 }
 
+/** @param {string} taskFilePath @param {string} slug @param{{rootDir?: string}} options */
 function rewriteWorktreePaths(taskFilePath, slug, options = {}) {
   const rootDir = options.rootDir || getPrimaryWorktree();
   const before = fs.readFileSync(taskFilePath, 'utf8');
@@ -1169,6 +1239,7 @@ function rewriteWorktreePaths(taskFilePath, slug, options = {}) {
   }
 }
 
+/** @param{{slug: string, dirtyEntries?: string[], rootDir?: string, gitRunner?: Function}} params */
 function stashMainCheckoutIfNeeded({
   slug,
   dirtyEntries = [],
@@ -1203,6 +1274,7 @@ function stashMainCheckoutIfNeeded({
   };
 }
 
+/** @param{{message: string, rootDir?: string, gitRunner?: Function}} params */
 function restoreMainCheckoutStash({ message, rootDir = getPrimaryWorktree(), gitRunner = git }) {
   fmt.log.info(`Restoring temporarily stashed local integration checkout changes: ${message}`);
   // Pass cwd explicitly so spawnSync does not inherit the process cwd, which may have been
@@ -1210,11 +1282,16 @@ function restoreMainCheckoutStash({ message, rootDir = getPrimaryWorktree(), git
   return gitRunner(['-C', rootDir, 'stash', 'pop'], { cwd: rootDir });
 }
 
+/** @param{{stdout: string, stderr: string, status: number}} result */
 function isNoMergeToAbortResult(result) {
   const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
   return /MERGE_HEAD missing|There is no merge to abort/i.test(output);
 }
 
+/**
+ * @param {string} slug
+ * @param{{rootDir?: string, gitRunner?: Function, recordIntegrationStatsFn?: Function}} options
+ */
 function recordPostIntegrationStats(
   slug,
   {
@@ -1240,19 +1317,28 @@ function recordPostIntegrationStats(
   fmt.log.info(`Workflow stats recorded: ${formatRecordedStatsRow(outcome.row)}`);
   fmt.log.info('Workflow stats updated:');
   fmt.log.plain(outcome.report);
+
+  const missionRows = outcome.data?.rows || [];
+  const missionReport = stats.renderMissionPhaseReport(missionRows, slug);
+  const firstLine = missionReport.split('\n')[0];
+  fmt.log.info(firstLine);
+  fmt.log.plain(missionReport.split('\n').slice(1).join('\n'));
+
   return outcome;
 }
 
+/** @param {string} slug @param{{rootDir?: string}} options */
 function recordPostIntegrationStatsOrAbort(slug, options = {}) {
   try {
     return recordPostIntegrationStats(slug, options);
-  } catch (error) {
+  } catch (/** @type{any} */ error) {
     const detail = error && error.message ? error.message : String(error);
     fmt.log.fail(`Post-integration workflow stats failed for ${slug}: ${detail}`);
     throw new IntegrationAbort();
   }
 }
 
+/** @param{{slug: string, summary: string, mainTaskFile?: string, rootDir?: string, gitRunner?: Function, baseBranch?: string|null, verificationArea?: string|null, captureVerifiedTreeProofFn?: Function, assertVerifiedTreeProofFn?: Function}} params */
 function finalizeVariantACloseout({
   slug,
   summary,
@@ -1271,7 +1357,7 @@ function finalizeVariantACloseout({
     // Re-resolve because it moved
     const updatedResolution = resolveTaskFile(slug, rootDir);
     if (updatedResolution.ok) {
-      rewriteWorktreePaths(updatedResolution.taskFile, slug, { rootDir });
+      rewriteWorktreePaths(/** @type {string} */ (updatedResolution.taskFile), slug, { rootDir });
     }
   }
 
@@ -1332,12 +1418,16 @@ function finalizeVariantACloseout({
   return { ok: true, changed: true };
 }
 
+/**
+ * @param {string} slug
+ * @param{{rootDir?: string, gitRunner?: Function, removeDir?: Function, existsSync?: Function}} options
+ */
 function cleanupMissionWorktree(
   slug,
   {
     rootDir = getPrimaryWorktree(),
     gitRunner = git,
-    removeDir = target => {
+    removeDir = (/** @type{string} */ target) => {
       if (isForgejoPath(target, { forgejoHome: resolveForgejoHome() })) {
         throw new Error(`CRITICAL SAFETY VIOLATION: cleanupMissionWorktree attempted to delete Forgejo home: ${target}`);
       }
@@ -1359,6 +1449,7 @@ function cleanupMissionWorktree(
   }
 
   const worktreeList = gitRunner(['-C', rootDir, 'worktree', 'list', '--porcelain']).stdout;
+  // @ts-expect-error line implicitly any
   const isRegistered = worktreeList.split('\n').some(line => line.trim() === `worktree ${worktreePath}`);
 
   if (existsSync(worktreePath) && isRegistered) {
@@ -1389,16 +1480,17 @@ function cleanupMissionWorktree(
   return !existsSync(worktreePath);
 }
 
+/** @param {string} rootDir @param {string} slug */
 function findExistingSquashCommit(rootDir, slug) {
   const result = git(['-C', rootDir, 'log', '--format=%H %s', '-50']);
-  if (result.status !== 0) return null;
+  if (result.status !== 0) {return null;}
   const prefix = `${missionBranchName(slug, rootDir)}:`;
   for (const line of result.stdout.trim().split('\n')) {
     const spaceIdx = line.indexOf(' ');
-    if (spaceIdx === -1) continue;
+    if (spaceIdx === -1) {continue;}
     const hash = line.slice(0, spaceIdx);
     const subject = line.slice(spaceIdx + 1);
-    if (subject.startsWith(prefix)) return hash;
+    if (subject.startsWith(prefix)) {return hash;}
   }
   return null;
 }
@@ -1414,8 +1506,14 @@ function findExistingSquashCommit(rootDir, slug) {
  * @param {string} slug - Backlog task key (e.g. "task-108")
  * @param {string} area - Mission gate area passed to the configured verification command
  * @param {{ getConflictFilesFn?: Function }} [options] - Overrides for testing
- * @returns {{ ok: boolean, conflictFiles: string[], sharedFiles: string[], missionSpecificFiles: string[] }}
+ * @returns {{ ok: boolean, conflictFiles: string[], sharedFiles: string[], missionSpecificFiles: string[], error?: string, worktreePath?: string }}
+ */
+/**
+ * @param {string} slug
+ * @param {string} area
+ * @param{{getConflictFilesFn: Function, resolveWorktreeFn?: Function, worktreePathOverride?: string|null, rootDir?: string, baseBranch?: string|null}} options
  */
+// @ts-expect-error resolveConflictsForMission options missing getConflictFilesFn
 function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWorktreeFn = resolveWorktree, worktreePathOverride = null, rootDir = getPrimaryWorktree(), baseBranch = null } = {}) {
   // Resolve the actual attached worktree dynamically; fall back to the conventional
   // path only when git worktree list has no entry for this mission branch.
@@ -1434,7 +1532,8 @@ function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWor
     try { targetBranch = resolveMissionBaseBranch(slug, rootDir); } catch (_) { targetBranch = getPrimaryBranch(); }
   }
 
-  const detectFn = getConflictFilesFn || ((_rootDir, _branch) => getConflictFiles(worktreePath, targetBranch));
+  // @ts-expect-error getConflictFilesFn may be undefined
+  const detectFn = getConflictFilesFn || (() => getConflictFiles(worktreePath, targetBranch));
 
   if (!fs.existsSync(worktreePath)) {
     fmt.log.fail(`Mission worktree not found: ${worktreePath}`);
@@ -1446,7 +1545,7 @@ function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWor
   let conflictFiles;
   try {
     conflictFiles = detectFn(worktreePath, targetBranch);
-  } catch (err) {
+  } catch (/** @type{any} */ err) {
     fmt.log.fail('Merge check failed with a non-conflict error:');
     fmt.log.fail(err.message);
     return { ok: false, error: 'merge-failed', conflictFiles: [], sharedFiles: [], missionSpecificFiles: [], worktreePath };
@@ -1459,20 +1558,20 @@ function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWor
   }
 
   fmt.log.info(`Conflicting files (${conflictFiles.length}):`);
-  conflictFiles.forEach(f => fmt.log.info(`  - ${f}`));
+  conflictFiles.forEach((/** @type{string} */ f) => fmt.log.info(`  - ${f}`));
 
   // Derive the mission-doc directory prefix from the actual located mission dir
   // so the classification works for non-standard doc paths (e.g. renamed year dir).
   const taskPattern = new RegExp(`backlog/(?:tasks|completed)/[^/]*${slug}`);
-  const missionSpecificFiles = conflictFiles.filter(f =>
+  const missionSpecificFiles = conflictFiles.filter((/** @type{string} */ f) =>
     isMissionArtifact(f, slug, worktreePath) || taskPattern.test(f)
   );
-  const sharedFiles = conflictFiles.filter(f => !missionSpecificFiles.includes(f));
+  const sharedFiles = conflictFiles.filter((/** @type{string} */ f) => !missionSpecificFiles.includes(f));
   const quotedWorktreePath = shellQuote(worktreePath);
 
   if (sharedFiles.length > 0) {
     fmt.log.warn(`Conflicts in ${sharedFiles.length} shared file(s) require manual resolution:`);
-    sharedFiles.forEach(f => fmt.log.plain(`  - ${f}`));
+    sharedFiles.forEach((/** @type{string} */ f) => fmt.log.plain(`  - ${f}`));
     fmt.log.info('Manual resolution path:');
     fmt.log.info(`  cd ${quotedWorktreePath}`);
     fmt.log.info(`  git rebase ${targetBranch}`);
@@ -1489,7 +1588,7 @@ function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWor
   fmt.log.info(`  cd ${quotedWorktreePath}`);
   fmt.log.info(`  git rebase ${targetBranch}`);
   fmt.log.info('  # after the rebase pauses on conflicts:');
-  missionSpecificFiles.forEach(f => fmt.log.info(`  git checkout --theirs "${f}" && git add "${f}"`));
+  missionSpecificFiles.forEach((/** @type{string} */ f) => fmt.log.info(`  git checkout --theirs "${f}" && git add "${f}"`));
   fmt.log.info('  git rebase --continue');
   fmt.log.info(`  ${formatVerificationCommand(area, worktreePath)}`);
   fmt.log.info(`  px integrate ${slug} --dry-run`);
@@ -1497,6 +1596,7 @@ function resolveConflictsForMission(slug, area, { getConflictFilesFn, resolveWor
   return { ok: true, conflictFiles, sharedFiles: [], missionSpecificFiles, worktreePath };
 }
 
+/** @param{string} slug @param{string} area @param{{rootDir?: string, worktreePath?: string, baseBranch?: string|null}} options */
 function buildConflictResolutionPrompt(slug = '<slug>', area = '<area>', options = {}) {
   const rootDir = options.rootDir || getPrimaryWorktree();
   const worktreePath = options.worktreePath || resolveWorktree(slug) || conventionalWorktreePath(slug, rootDir);