@magnusekdahl/parallix 1.0.0

package/lib/commands/handoff.js

@@ -0,0 +1,501 @@
+const fs = require('fs');
+const path = require('path');
+const git = require('../core/git');
+const missionUtils = require('../core/mission-utils');
+const backlog = require('../tools/backlog');
+const forgejo = require('../tools/forgejo');
+const { resolveReviewIdentity } = require('../review/review-state');
+const setupReview = require('../tools/setup-review');
+const gatekeeper = require('../tools/gatekeeper');
+const fmt = require('../core/fmt');
+const { runVerificationGate } = require('../core/verification');
+const { isForgejoReviewEnabled } = require('../core/product-config');
+const { rebaseBeforeReviewRound } = require('../review/rebase');
+
+/**
+ * Verifies that the current environment is ready for handoff.
+ *
+ * @param {string} slug - Mission slug
+ * @param {object} [options]
+ * @returns {{ ok: boolean, error?: string, missionDir?: string, area?: string, branch?: string, rootDir?: string }}
+ */
+function verifyHandoff(slug, options = {}) {
+  const rootDir = options.worktree || process.cwd();
+  const missionDir = missionUtils.findMissionDir(slug, rootDir);
+  if (!missionDir) {
+    return { ok: false, error: `Mission directory not found for slug: ${slug}` };
+  }
+
+  const area = missionUtils.findMissionArea(missionDir);
+  const branch = missionUtils.missionBranchName(slug, rootDir);
+  const current = git.getCurrentBranch(rootDir);
+
+  if (current !== branch) {
+    return { ok: false, error: `Not on mission branch. Current: ${current}, Expected: ${branch}` };
+  }
+
+  const missionMdPath = path.join(missionDir, 'MISSION.md');
+  if (!fs.existsSync(missionMdPath)) {
+    return { ok: false, error: `MISSION.md not found at ${missionMdPath}. The mission contract must exist before handoff.` };
+  }
+
+  return { ok: true, missionDir, area, branch, rootDir };
+}
+
+/**
+ * Performs the handoff process for a mission:
+ * 1. Runs the verification gate.
+ * 2. Syncs primary branch and pushes the mission branch to Forgejo, creating or updating the PR.
+ * 3. Transitions Backlog task to 'review'.
+ * 4. Commits and pushes the Backlog state change to Forgejo.
+ *
+ * @param {string} slug - Mission slug
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+async function performHandoff(slug, options = {}) {
+  const {
+    skipGate = false,
+    worktree = null,
+    force = false,
+    forceWithLease = true,
+    log = fmt.log.info,
+    error = fmt.log.fail,
+    rebaseFn = rebaseBeforeReviewRound
+  } = options;
+
+  const verification = verifyHandoff(slug, { worktree });
+  if (!verification.ok) {
+    error(verification.error);
+    return { ok: false, error: verification.error };
+  }
+
+  const { area, branch, rootDir } = verification;
+
+  // Step 0: Resolve Backlog task for identity derivation
+  const taskResolution = backlog.resolveTaskFile(slug, rootDir);
+  if (!taskResolution.ok) {
+    const msg = `Backlog task file for ${fmt.slug(slug)} not found or ambiguous: ${taskResolution.reason}.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Pre-handoff Content Integrity Check
+  const relativeMissionPath = path.relative(rootDir, path.join(verification.missionDir, 'MISSION.md'));
+  const dirtyFiles = git.getWorktreeStatus(rootDir);
+  let checkpoints = missionUtils.findCheckpoints(verification.missionDir);
+
+  if (dirtyFiles.some(line => line.endsWith(relativeMissionPath))) {
+    const msg = `${fmt.path('MISSION.md')} is modified but uncommitted at ${fmt.path(relativeMissionPath)}. Commit the mission contract before handoff.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  if (checkpoints.length === 0) {
+    // Auto-remediation (task-1228): rather than hard-failing when no checkpoint
+    // document exists, generate a minimal default CP-1.md with a valid Goal Check
+    // table so the handoff can proceed without manual intervention. The generated
+    // file is clearly marked as auto-generated for reviewer awareness, then we
+    // re-scan to confirm it is discoverable via findCheckpoints().
+    const autoCheckpointPath = path.join(verification.missionDir, 'CP-1.md');
+    fs.writeFileSync(autoCheckpointPath, buildAutoCheckpointContent(slug), 'utf8');
+    log(fmt.status('WARN', `No checkpoint documents found — auto-generated ${fmt.path('CP-1.md')} in ${fmt.path(verification.missionDir)}.`));
+
+    checkpoints = missionUtils.findCheckpoints(verification.missionDir);
+    if (checkpoints.length === 0) {
+      const msg = `No checkpoint documents found in ${fmt.path(verification.missionDir)} even after auto-remediation. Implementation evidence is mandatory for review.`;
+      error(msg);
+      return { ok: false, error: msg };
+    }
+
+    // Commit the auto-generated checkpoint so it is included in the handoff push
+    // and does not trip the uncommitted-checkpoint check below.
+    git.git(['-C', rootDir, 'add', autoCheckpointPath]);
+    const commitRes = git.git(['-C', rootDir, 'commit', '-m', `docs(${slug}): auto-generate CP-1.md checkpoint (handoff remediation)`]);
+    if (commitRes.status !== 0) {
+      log(fmt.status('WARN', `Could not commit auto-generated CP-1.md for ${fmt.slug(slug)}; continuing handoff.`));
+    }
+  }
+
+  const finalCheckpoint = checkpoints[checkpoints.length - 1];
+  const relativeCheckpointPath = path.relative(rootDir, finalCheckpoint);
+  if (dirtyFiles.some(line => line.endsWith(relativeCheckpointPath))) {
+    const msg = `The latest checkpoint document is modified but uncommitted at ${fmt.path(relativeCheckpointPath)}. Commit the implementation evidence before handoff.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Pre-handoff Content Integrity Check: final checkpoint must contain a Goal Check table
+  // with real evidence. Per review.md step 5, a missing or empty goal-check table
+  // means the checkpoint has not satisfied the mission's evidence requirement.
+  // Accept both `## Goal Check` and `## Goal Check Table` heading variants used across repo artifacts.
+  const checkpointContent = fs.readFileSync(finalCheckpoint, 'utf8');
+  const goalCheckMatch = checkpointContent.match(/^## Goal Check(?: Table)?\s*$/m);
+  if (!goalCheckMatch) {
+    const msg = `The final checkpoint at ${fmt.path(relativeCheckpointPath)} is missing a "## Goal Check" section. Review requires a goal-check table with real evidence before handoff.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Verify the goal-check table has at least one row of evidence (table row after header).
+  // Must exclude table separator rows (|---|---|---|) and the header row itself —
+  // only real evidence rows (with pipe-separated content that is not all dashes) count.
+  const afterHeader = checkpointContent.slice(goalCheckMatch.index + goalCheckMatch[0].length);
+  const separatorPattern = /^\|\s*:?-+:?\s*\|/;
+  const headerPattern = /^\| .+\| .+\| .+\|$/;
+  const evidenceLinePattern = /^\| .+\| .+\| .+\|$/;
+  const linesAfterHeader = afterHeader.split('\n');
+  let foundEvidence = false;
+  let pastHeader = false;
+  for (const line of linesAfterHeader) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    if (!pastHeader && headerPattern.test(trimmed)) {
+      pastHeader = true;
+      continue;
+    }
+    if (separatorPattern.test(trimmed)) continue;
+    if (pastHeader && evidenceLinePattern.test(trimmed)) {
+      foundEvidence = true;
+      break;
+    }
+    // Non-empty, non-separator, non-evidence row after header = no valid table
+    break;
+  }
+  if (!foundEvidence) {
+    const msg = `The final checkpoint at ${fmt.path(relativeCheckpointPath)} has a "## Goal Check" section but no evidence rows. A goal-check table with real evidence is required before handoff.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const isForgejoReviewEnabledFn = options.isForgejoReviewEnabledFn || isForgejoReviewEnabled;
+  const forgejoEnabled = isForgejoReviewEnabledFn(rootDir);
+
+  const { forgejoUser: reviewStateUser } = resolveReviewIdentity(slug, rootDir, {
+  });
+  const forgejoUser = reviewStateUser || backlog.getTaskImplementer(taskResolution.taskFile);
+
+  if (!forgejoUser) {
+    error('forgejoUser is required for performHandoff. Ensure review-state.json or the Backlog task has an agent family assigned.');
+    return { ok: false, error: 'forgejoUser is required' };
+  }
+
+  log(`Starting handoff for mission ${fmt.slug(slug)}...`);
+
+  // Step 1: Final Gate Run
+  if (skipGate) {
+    fmt.log.warn('Step 1: Skipping final verification gate (--no-gate)');
+  } else {
+    log(`Step 1: Running final verification gate for area: ${fmt.bold(area)}...`);
+    const verifyResult = runVerificationGate(area, {
+      rootDir,
+      stdio: 'inherit',
+      runFn: git.run
+    });
+    if (verifyResult.status !== 0) {
+      const msg = 'Final verification gate failed. Fix errors before submitting or use --no-gate if appropriate.';
+      error(msg);
+      return { ok: false, error: msg };
+    }
+  }
+
+  // Step 1.5: Rebase mission branch onto latest primary before PR creation
+  log('Step 1.5: Rebasing onto primary branch before handoff...');
+  const rebaseResult = await rebaseFn(slug, {
+    worktree,
+    log,
+    error,
+    isForgejoReviewEnabledFn: isForgejoReviewEnabledFn,
+  });
+  if (!rebaseResult.ok) {
+    if (rebaseResult.sharedFileConflicts) {
+      const msg = 'Rebase encountered shared-file conflicts. Resolve the conflicts in the worktree, then re-run handoff.';
+      error(msg);
+      return { ok: false, error: msg };
+    } else {
+      const msg = 'Rebase failed before handoff. Ensure the mission branch can be rebased onto the latest primary branch.';
+      error(msg);
+      return { ok: false, error: msg };
+    }
+  }
+
+  // Step 2: Forgejo PR Update/Create (optional mirror when Forgejo is enabled)
+  let token = null;
+  let bootstrapUsed = false;
+  let fallbackUser = null;
+  let bootstrapFailureReason = null;
+  if (forgejoEnabled) {
+    log(`Step 2: Updating/Creating Forgejo PR as user ${fmt.agent(forgejoUser)}...`);
+    token = forgejo.readToken(forgejoUser);
+    if (!token) {
+      // Token missing for the agent user — attempt non-interactive bootstrap
+      error(`Token not found for ${fmt.agent(forgejoUser)}. Attempting non-interactive bootstrap...`);
+
+      const reviewSettings = forgejo.resolveForgejoSettings(rootDir);
+      const bootstrapSetup = {
+        baseUrl: reviewSettings.url,
+        repo: reviewSettings.repo,
+        ownerLogin: 'human',
+        ownerPassword: '',
+        agentPasswords: [{ user: forgejoUser, password: '' }],
+      };
+      const bootstrapResult = await setupReview.bootstrapReviewSurface(rootDir, bootstrapSetup, {
+        interactive: false,
+        requestFn: setupReview.apiRequest,
+        log,
+      });
+
+      if (bootstrapResult.ok) {
+        log(fmt.status('PASS', `Bootstrap succeeded for ${fmt.agent(forgejoUser)}.`));
+        bootstrapUsed = true;
+        token = forgejo.readToken(forgejoUser);
+        if (!token) {
+          bootstrapFailureReason = 'bootstrap completed but token file for the agent user was not found';
+          error('Bootstrap completed but token file for the agent user was not found. Falling back to default user.');
+        }
+      } else {
+        bootstrapFailureReason = bootstrapResult.error || 'unknown';
+        error(`Bootstrap for ${fmt.agent(forgejoUser)} failed: ${bootstrapFailureReason}. Falling back to default user.`);
+      }
+
+      // Magnus fallback if bootstrap didn't produce a token
+      if (!token) {
+        token = forgejo.readToken('human');
+        if (token) {
+          fallbackUser = 'human';
+          log(`Token not found for ${fmt.agent(forgejoUser)} and bootstrap did not succeed. Falling back to PR creation as ${fmt.agent(fallbackUser)}.`);
+        } else {
+          const msg = `No Forgejo token found for user "${fmt.agent(forgejoUser)}", bootstrap failed (${bootstrapResult.error || 'unknown'}), and no fallback token available for "${fmt.agent('human')}". Manual action required: create a token manually or run \`node parallix setup-review\` first.`;
+          error(msg);
+          return { ok: false, error: msg };
+        }
+      }
+    }
+
+    // Persist durable fallback summary when we fell back to the default user
+    if (fallbackUser === 'human') {
+      const reason = bootstrapFailureReason || 'agent token was missing and bootstrap did not provide a replacement token';
+      const fallbackSummary = `## Fallback: PR submitted as ${fmt.agent(fallbackUser)}\n\nOriginal user: ${fmt.agent(forgejoUser)}\nBootstrap failure reason: ${reason}`;
+      if (!writeFallbackSummary(slug, fallbackSummary, { rootDir, log })) {
+        log(fmt.status('WARN', `Could not persist fallback summary for ${fmt.slug(slug)}`));
+      }
+    }
+
+    const prResult = forgejo.createPr(branch, fallbackUser || forgejoUser, token, {
+      rootDir,
+      log,
+      forceWithLease
+    });
+    if (!prResult.ok) {
+      const msg = `Forgejo PR creation/update failed: ${prResult.error}`;
+      error(msg);
+      return { ok: false, error: msg };
+    }
+  } else {
+    log('Step 2: Skipping Forgejo PR (review provider is not forgejo).');
+  }
+
+ // Step 2.5: Gatekeeper pre-review validation
+  // Run before transitioning Backlog to 'review' so missing artifacts are
+  // flagged as a request-changes review instead of consuming a reviewer cycle.
+  log('Step 2.5: Running gatekeeper pre-review validation...');
+  const gatekeeperResult = gatekeeper.runGatekeeper(slug, { rootDir, log });
+  let gatekeeperPushedBack = false;
+  if (!gatekeeperResult.ok && gatekeeperResult.posted) {
+    fmt.log.warn(`Gatekeeper posted pushback for ${fmt.slug(slug)}: missing ${gatekeeperResult.missing.join(', ')}.`);
+    gatekeeperPushedBack = true;
+    log(`Keeping task ${fmt.slug(slug)} in active — not transitioning to review while artifacts are missing.`);
+  } else if (!gatekeeperResult.ok && (gatekeeperResult.skipped || !gatekeeperResult.posted)) {
+    fmt.log.fail(`Gatekeeper detected missing artifacts for ${fmt.slug(slug)} but could not post pushback: skipped=${gatekeeperResult.skipped}, posted=${gatekeeperResult.posted}. Blocking handoff — task remains in active until artifacts are present.`);
+    error(`Missing mandatory artifacts: ${gatekeeperResult.missing.join(', ')}.`);
+    return { ok: false, error: `Gatekeeper detected missing artifacts but could not post pushback (skipped=${gatekeeperResult.skipped}, posted=${gatekeeperResult.posted}). Fix missing artifacts before handoff: ${gatekeeperResult.missing.join(', ')}.` };
+  } else {
+    log('Gatekeeper: all mandatory artifacts present.');
+  }
+
+  if (gatekeeperPushedBack) {
+    log(`Gatekeeper pushback posted for ${fmt.slug(slug)} — skipping Backlog transition to review.`);
+    return { ok: true, gatekeeperPushedBack: true };
+  }
+
+  // Step 3 & 4: Backlog Transition and Commit
+  log('Step 3 & 4: Transitioning and committing Backlog task to review...');
+
+  const taskImplementer = forgejoUser;
+  if (!backlog.transitionTask(slug, 'review', { implementer: taskImplementer, rootDir, log })) {
+    const msg = `Could not transition task ${fmt.slug(slug)} to review.`;
+    error(msg);
+    return { ok: false, error: msg };
+  }
+
+  if (forgejoEnabled && token) {
+    log('Pushing state change to Forgejo...');
+    const reviewSettings = forgejo.resolveForgejoSettings(rootDir);
+    const repoOwner = (reviewSettings.repo && reviewSettings.repo.split('/')[0]) || null;
+    const ownerToken = repoOwner ? forgejo.readToken(repoOwner) : null;
+    const pushUser = ownerToken && repoOwner ? repoOwner : (fallbackUser || forgejoUser);
+    const pushToken = ownerToken || token;
+    const remoteUrl = forgejo.authenticatedReviewUrl(pushUser, pushToken, rootDir);
+    let pushLeaseArg = null;
+    if (force) {
+      const fetchArgs = ['-C', rootDir, 'fetch', remoteUrl, `+refs/heads/${branch}:refs/remotes/review/${branch}`];
+      const fetchResult = git.git(fetchArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
+      if (fetchResult.status !== 0) {
+        const fetchError = (fetchResult.stderr || fetchResult.stdout || '').trim();
+        const msg = `Failed to refresh Backlog transition lease for ${fmt.slug(slug)} before Forgejo push.`;
+        error(`${msg}${fetchError ? ` ${fetchError}` : ''}`);
+        return { ok: false, error: msg };
+      }
+      const tracking = forgejo.resolveTrackingBranchSha(branch, rootDir);
+      if (!tracking.ok) {
+        const msg = `Failed to resolve Backlog transition lease for ${fmt.slug(slug)} before Forgejo push.`;
+        error(msg);
+        return { ok: false, error: `${msg} ${tracking.error || ''}`.trim() };
+      }
+      pushLeaseArg = `--force-with-lease=refs/heads/${branch}:${tracking.sha}`;
+    }
+    const pushArgs = ['-C', rootDir, 'push'];
+    if (pushLeaseArg) {
+      pushArgs.push(pushLeaseArg);
+    }
+    pushArgs.push(remoteUrl, branch);
+    const pushBacklogForgejo = git.git(pushArgs);
+    if (pushBacklogForgejo.status !== 0) {
+      const pushError = [pushBacklogForgejo.stderr, pushBacklogForgejo.stdout].filter(Boolean).join('\n');
+      if (force && /non-fast-forward|stale info|fetch first/i.test(pushError || '')) {
+        const forceArgs = ['-C', rootDir, 'push', '--force', remoteUrl, branch];
+        const forceResult = git.git(forceArgs);
+        if (forceResult.status === 0) {
+          fmt.log.info(`Backlog transition for ${fmt.slug(slug)} required plain force after stale lease.`);
+        } else {
+          const forceError = (forceResult.stderr || forceResult.stdout || '').trim();
+          const msg = `Failed to push Backlog transition for ${fmt.slug(slug)} to Forgejo.`;
+          error(msg);
+          return { ok: false, error: forceError ? `${msg} ${forceError}` : msg };
+        }
+        return { ok: true, gatekeeperPushedBack };
+      }
+      const msg = `Failed to push Backlog transition for ${fmt.slug(slug)} to Forgejo.`;
+      error(msg);
+      return { ok: false, error: msg };
+    }
+  }
+
+  fmt.log.pass(`Mission ${fmt.slug(slug)} handed off successfully.`);
+  return { ok: true, gatekeeperPushedBack };
+}
+
+/**
+ * Build the content for an auto-generated CP-1.md checkpoint (task-1228).
+ *
+ * The generated file satisfies the minimum checkpoint integrity requirements
+ * enforced in performHandoff: an `# CP-1:` h1 heading, a `## Goal Check`
+ * section (matching the regex `^## Goal Check(?: Table)?\s*$`), and a 3-column
+ * pipe table with at least one evidence row. It is explicitly marked as
+ * auto-generated so a reviewer knows to replace it with real evidence.
+ *
+ * @param {string} slug - Mission slug, used for human-readable context.
+ * @returns {string}
+ */
+function buildAutoCheckpointContent(slug) {
+  return [
+    `# CP-1: Auto-generated checkpoint (handoff remediation for ${slug})`,
+    '',
+    '> **Auto-generated by `node parallix handoff`** because no checkpoint document',
+    '> was present in the mission directory at handoff time. This file provides the',
+    '> minimum required structure so the handoff can proceed. A reviewer should',
+    '> replace it with real implementation evidence.',
+    '',
+    '## Goal Check',
+    '',
+    '| Criterion | Evidence | Status |',
+    '|-----------|----------|--------|',
+    '| Auto-generated checkpoint CP-1.md present | handoff.js auto-remediation creates CP-1.md when checkpoints.length === 0 | PASS |',
+    '| Mission contract exists for review | MISSION.md present in the mission directory | PASS |',
+    '',
+    'Next action: Reviewer to replace this placeholder with real implementation evidence before approval.',
+    ''
+  ].join('\n');
+}
+
+/**
+ * Write a fallback summary (`## Fallback:` heading) into the backlog task file.
+ * This is the in-scope equivalent of backlog.setTaskFinalSummary, implemented
+ * inline here since modifying backlog.js is out of scope for this mission.
+ * @param {string} slug - Mission slug
+ * @param {string} summary - The fallback summary text (must contain ## Fallback)
+ * @param {object} options
+ * @returns {boolean}
+ */
+function writeFallbackSummary(slug, summary, options = {}) {
+  const { rootDir = process.cwd(), log = fmt.log.plain } = options;
+  const resolution = backlog.resolveTaskFile(slug, rootDir);
+  if (!resolution.ok) {
+    log(fmt.status('WARN', `Could not write fallback summary for ${fmt.slug(slug)}: ${resolution.reason}`));
+    return false;
+  }
+
+  const taskFile = resolution.taskFile;
+  let content = fs.readFileSync(taskFile, 'utf8');
+
+  // Already present — no-op
+  if (content.includes('## Fallback:')) {
+    return true;
+  }
+
+  // Insert after frontmatter block (first occurrence of "---" closing)
+  const firstDash = content.indexOf('---');
+  if (firstDash === -1) {
+    content = summary + '\n\n' + content;
+  } else {
+    // Find the closing --- of frontmatter
+    const closingDash = content.indexOf('---', firstDash + 3);
+    if (closingDash === -1) {
+      content = summary + '\n\n' + content;
+    } else {
+      const insertPos = closingDash + 3;
+      content = content.slice(0, insertPos) + '\n\n' + summary + content.slice(insertPos);
+    }
+  }
+
+  // Write the file
+  fs.writeFileSync(taskFile, content, 'utf8');
+
+  // Commit via the git module
+  const gitResult = git.git(['add', taskFile]);
+  if (gitResult.status !== 0) {
+    log(fmt.status('WARN', `Failed to stage fallback summary for ${fmt.slug(slug)}`));
+    return false;
+  }
+
+  const commitResult = git.git(['commit', '-m', `backlog(${slug}): set fallback summary`]);
+  if (commitResult.status !== 0) {
+    log(fmt.status('WARN', `Failed to commit fallback summary for ${fmt.slug(slug)}`));
+    return false;
+  }
+
+  log(fmt.status('PASS', `Set fallback summary on ${fmt.slug(slug)}.`));
+  return true;
+}
+
+async function handoffCommand(args) {
+  const explicitSlug = args[0];
+  const slug = missionUtils.inferSlug(explicitSlug);
+  const skipGate = args.includes('--no-gate');
+  const force = args.includes('--force');
+
+  if (!slug) {
+    fmt.log.fail('Usage: node parallix handoff [<slug>] [--no-gate] [--force]');
+    process.exit(1);
+  }
+
+  const result = await module.exports.performHandoff(slug, { skipGate, force });
+  if (!result.ok) {
+    process.exit(1);
+  }
+}
+
+module.exports = handoffCommand;
+module.exports.verifyHandoff = verifyHandoff;
+module.exports.performHandoff = performHandoff;
+module.exports.gatekeeper = gatekeeper;