@magnusekdahl/parallix 1.0.0

package/lib/review/review-polling.js

@@ -0,0 +1,141 @@
+/**
+ * Review Polling Module
+ * Extracted from parallix/lib/review.js for task-1201
+ * Handles polling for review outcomes and disposition comments.
+ */
+
+const fmt = require('../core/fmt');
+const { getLatestReviewForPr, getLatestDispositionForPr } = require('./review-adapter');
+
+const DEFAULT_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_POLL_MAX_WAIT_MS = 600_000;
+const POLL_PROGRESS_EVERY_MS = 30_000;
+
+const POLL_TIMEOUT = Object.freeze({ __isPollTimeout: true });
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function resolvePollIntervalMs() {
+  const raw = process.env.AUTONOMOUS_REVIEW_POLL_INTERVAL_MS;
+  const parsed = raw ? parseInt(raw, 10) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_POLL_INTERVAL_MS;
+  return parsed;
+}
+
+function resolvePollTimeoutMs(explicitSeconds) {
+  if (Number.isFinite(explicitSeconds) && explicitSeconds > 0) {
+    return explicitSeconds * 1000;
+  }
+  const raw = process.env.AUTONOMOUS_REVIEW_POLL_TIMEOUT_MS;
+  const parsed = raw ? parseInt(raw, 10) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_POLL_MAX_WAIT_MS;
+  return parsed;
+}
+
+function formatElapsed(startMs) {
+  const secs = Math.round((Date.now() - startMs) / 1000);
+  return `${secs}s`;
+}
+
+function isPollTimeout(result) {
+  return result === POLL_TIMEOUT;
+}
+
+async function pollForReview(prNumber, reviewerUser, sinceIso, token, options = {}) {
+  const {
+    getLatestReviewForPrFn = getLatestReviewForPr,
+    sleepFn = delay,
+    intervalMs = resolvePollIntervalMs(),
+    timeoutMs = resolvePollTimeoutMs(),
+    verbose = false,
+    label = 'review',
+    retryCount = 0,
+    log = fmt.log.plain
+  } = options;
+  if (!token) {
+    log(fmt.status('WARN', 'No Forgejo token — skipping review-outcome poll (manual handoff required).'));
+    return null;
+  }
+
+  const start = Date.now();
+  const deadline = start + timeoutMs;
+  let lastProgressAt = start;
+  log(fmt.status('INFO', `Polling Forgejo for ${label} by ${reviewerUser} on PR #${prNumber} (timeout ${Math.round(timeoutMs / 1000)}s)...`));
+
+  while (Date.now() < deadline) {
+    const review = await getLatestReviewForPrFn(prNumber, reviewerUser, sinceIso, token);
+    if (review) {
+      if (verbose) log(fmt.status('INFO', `${label}: reviewer state=${review.state} after ${formatElapsed(start)}.`));
+      return review.state;
+    }
+
+    const now = Date.now();
+    if (verbose || now - lastProgressAt >= POLL_PROGRESS_EVERY_MS) {
+      log(fmt.status('INFO', `${label}: still waiting for ${reviewerUser}'s review... (${formatElapsed(start)} elapsed)`));
+      lastProgressAt = now;
+    }
+
+    await sleepFn(intervalMs);
+  }
+
+  const isRetry = retryCount > 0;
+  const logLevel = isRetry ? 'INFO' : 'WARN';
+  log(fmt.status(logLevel, `${label}: no review posted by ${reviewerUser} within ${Math.round(timeoutMs / 1000)}s.`));
+  return POLL_TIMEOUT;
+}
+
+async function pollForDisposition(prNumber, implementerUser, sinceIso, token, options = {}) {
+  const {
+    getLatestDispositionForPrFn = getLatestDispositionForPr,
+    sleepFn = delay,
+    intervalMs = resolvePollIntervalMs(),
+    timeoutMs = resolvePollTimeoutMs(),
+    verbose = false,
+    label = 'disposition',
+    retryCount = 0,
+    log = fmt.log.plain
+  } = options;
+  if (!token) {
+    log(fmt.status('WARN', 'No Forgejo token — skipping disposition poll (manual handoff required).'));
+    return null;
+  }
+
+  const start = Date.now();
+  const deadline = start + timeoutMs;
+  let lastProgressAt = start;
+  log(fmt.status('INFO', `Polling Forgejo for ${label} by ${implementerUser} on PR #${prNumber} (timeout ${Math.round(timeoutMs / 1000)}s)...`));
+
+  while (Date.now() < deadline) {
+    const disposition = await getLatestDispositionForPrFn(prNumber, implementerUser, sinceIso, token);
+    if (disposition) {
+      if (verbose) log(fmt.status('INFO', `${label}: disposition=${disposition} after ${formatElapsed(start)}.`));
+      return disposition;
+    }
+
+    const now = Date.now();
+    if (verbose || now - lastProgressAt >= POLL_PROGRESS_EVERY_MS) {
+      log(fmt.status('INFO', `${label}: still waiting for ${implementerUser}'s disposition comment... (${formatElapsed(start)} elapsed)`));
+      lastProgressAt = now;
+    }
+
+    await sleepFn(intervalMs);
+  }
+
+  const isRetry = retryCount > 0;
+  const logLevel = isRetry ? 'INFO' : 'WARN';
+  log(fmt.status(logLevel, `${label}: no disposition comment posted by ${implementerUser} within ${Math.round(timeoutMs / 1000)}s.`));
+  return POLL_TIMEOUT;
+}
+
+module.exports = {
+  POLL_TIMEOUT,
+  delay,
+  resolvePollIntervalMs,
+  resolvePollTimeoutMs,
+  formatElapsed,
+  isPollTimeout,
+  pollForReview,
+  pollForDisposition
+};

package/lib/review/review-prompts.js

@@ -0,0 +1,212 @@
+/**
+ * Assemble review and act-on-review prompts for the autonomous review loop.
+ * Owned by the Node workflow harness (ADR 0037 / task-089).
+ *
+ * Node-invoked agent prompts read from parallix/prompts/*.md templates
+ * (same pattern as active.js / draft.js). Full verbose prompts are kept
+ * for --dry-run diagnostics and human/manual invocation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getMissionYear, getPrimaryBranch, missionPathForSlug } = require('../core/mission-utils');
+const { resolveArtifactDir } = require('./review-artifacts');
+
+const REVIEW_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'review.md');
+const ACT_ON_REVIEW_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'act-on-review.md');
+const REVIEW_VERBOSE_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'review-verbose.md');
+const ACT_ON_REVIEW_VERBOSE_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'act-on-review-verbose.md');
+
+/**
+ * Slash-command / entrypoint used to invoke the review skill for each agent family.
+ * Moved from scripts/autonomous-review.sh prompt_entrypoint_for() into Node.
+ */
+const PROMPT_ENTRYPOINTS = {
+  codex:  { review: '$review all',                           actOnReview: '$act-on-review' },
+  claude: { review: '/review all',                           actOnReview: '/act-on-review' },
+  mistral: { review: '$review all',                           actOnReview: '$act-on-review' },
+  qwen:   { review: '$review all',                           actOnReview: '$act-on-review' },
+  autonomous: { review: '$review all',                       actOnReview: '$act-on-review' }
+};
+
+function reviewEntrypoint(agent) {
+  const entry = PROMPT_ENTRYPOINTS[agent];
+  if (!entry) throw new Error(`Unknown agent family for review entrypoint: ${agent}`);
+  return entry.review;
+}
+
+function actOnReviewEntrypoint(agent) {
+  const entry = PROMPT_ENTRYPOINTS[agent];
+  if (!entry) throw new Error(`Unknown agent family for act-on-review entrypoint: ${agent}`);
+  return entry.actOnReview;
+}
+
+/**
+ * Build the prompt sent to the reviewer agent for a given round.
+ *
+ * @param {object} opts
+ * @param {string} opts.reviewer      - Reviewer agent family (codex|claude)
+ * @param {string} opts.branch        - Mission branch name (e.g. 'mission/task-089')
+ * @param {string} opts.implementer   - Implementer agent family
+ * @param {string} opts.focus         - Review focus (default: 'all')
+ * @param {number} opts.attempt       - Round number (1-based)
+ * @param {string} [opts.repoRoot]    - Absolute repo root path
+ * @returns {string}
+ */
+function resolveMissionPath(slug, repoRoot, missionPathOverride) {
+  // `--mission <path>` override: when the caller points the review loop at a
+  // mission contract in a non-standard location, agents must read that file
+  // instead of the slug-derived standard path (task-1272 SC7).
+  if (missionPathOverride) return missionPathOverride;
+  const root = repoRoot || process.cwd();
+  try {
+    return missionPathForSlug(root, slug);
+  } catch (_) {
+    const year = getMissionYear(slug, root);
+    return path.join(root, 'docs', 'missions', String(year), slug, 'MISSION.md');
+  }
+}
+
+function resolvePrimaryBranch(repoRoot) {
+  try {
+    return getPrimaryBranch(repoRoot || process.cwd());
+  } catch (_) {
+    return 'main';
+  }
+}
+
+function buildReviewPrompt({ reviewer, branch, implementer, focus = 'all', attempt, repoRoot = '', missionPath: missionPathOverride }) {
+  const entrypoint = reviewEntrypoint(reviewer);
+  const repoLine = repoRoot ? `\noperate from repo root: ${repoRoot}` : '';
+  const slug = branch.replace(/^mission\//, '');
+  const year = getMissionYear(slug, repoRoot || process.cwd());
+  const missionPath = resolveMissionPath(slug, repoRoot, missionPathOverride);
+  const artifactDir = resolveArtifactDir(repoRoot || process.cwd());
+
+  const template = fs.readFileSync(REVIEW_VERBOSE_PROMPT_PATH, 'utf8');
+  return template
+    .replaceAll('{{branch}}',           branch)
+    .replaceAll('{{reviewer}}',         reviewer)
+    .replaceAll('{{implementer}}',      implementer)
+    .replaceAll('{{focus}}',            focus)
+    .replaceAll('{{attempt}}',          String(attempt))
+    .replaceAll('{{slug}}',             slug)
+    .replaceAll('{{missionPath}}',      missionPath)
+    .replaceAll('{{artifactDir}}',      artifactDir)
+    .replaceAll('{{primaryBranch}}',    resolvePrimaryBranch(repoRoot))
+    .replaceAll('{{review_entrypoint}}', entrypoint)
+    .replaceAll('YYYY',                year)
+    .replaceAll('{{repo_line}}',        repoLine ? repoLine.trim() + '\n- ' : '');
+}
+
+/**
+ * Build the prompt sent back to the implementer agent after a review round.
+ *
+ * @param {object} opts
+ * @param {string} opts.implementer   - Implementer agent family
+ * @param {string} opts.branch        - Mission branch name
+ * @param {number} opts.attempt       - Round number (1-based)
+ * @param {string} [opts.repoRoot]    - Absolute repo root path
+ * @returns {string}
+ */
+function buildActOnReviewPrompt({ implementer, branch, attempt, repoRoot = '', missionPath: missionPathOverride }) {
+  const entrypoint = actOnReviewEntrypoint(implementer);
+  const repoLine = repoRoot ? `\noperate from repo root: ${repoRoot}` : '';
+  const slug = branch.replace(/^mission\//, '');
+  const year = getMissionYear(slug, repoRoot || process.cwd());
+  const missionPath = resolveMissionPath(slug, repoRoot, missionPathOverride);
+  const artifactDir = resolveArtifactDir(repoRoot || process.cwd());
+
+  const template = fs.readFileSync(ACT_ON_REVIEW_VERBOSE_PROMPT_PATH, 'utf8');
+  return template
+    .replaceAll('{{branch}}',                  branch)
+    .replaceAll('{{implementer}}',             implementer)
+    .replaceAll('{{attempt}}',                 String(attempt))
+    .replaceAll('{{slug}}',                    slug)
+    .replaceAll('{{missionPath}}',             missionPath)
+    .replaceAll('{{artifactDir}}',             artifactDir)
+    .replaceAll('{{primaryBranch}}',           resolvePrimaryBranch(repoRoot))
+    .replaceAll('{{act_on_review_entrypoint}}', entrypoint)
+    .replaceAll('YYYY',                       year)
+    .replaceAll('{{repo_line}}',               repoLine ? repoLine.trim() + '\n- ' : '');
+}
+
+
+/**
+ * Node-invoked reviewer prompt built from parallix/prompts/review.md template.
+ * Uses the same template-substitution pattern as active.js (execute.md).
+ *
+ * @param {object} opts
+ * @param {string} opts.reviewer      - Reviewer agent family
+ * @param {string} opts.branch        - Mission branch name
+ * @param {string} opts.implementer   - Implementer agent family
+ * @param {string} opts.focus         - Review focus (default: 'all')
+ * @param {number} opts.attempt       - Round number (1-based)
+ * @param {string} [opts.repoRoot]    - Absolute repo root path (unused but kept for API symmetry)
+ * @param {string} [opts.actualReviewer] - The actual agent family launched (overrides reviewer for identity text, TASK-1051)
+ * @returns {string}
+ */
+function buildCompactReviewPrompt({ reviewer, branch, implementer, focus = 'all', attempt, actualReviewer, repoRoot = '', missionPath: missionPathOverride }) {
+  const slug = branch.replace(/^mission\//, '');
+  const finalReviewer = actualReviewer || reviewer;
+  const year = getMissionYear(slug, repoRoot || process.cwd());
+  const missionPath = resolveMissionPath(slug, repoRoot, missionPathOverride);
+  const primaryBranch = resolvePrimaryBranch(repoRoot);
+  const artifactDir = resolveArtifactDir(repoRoot || process.cwd());
+  const template = fs.readFileSync(REVIEW_PROMPT_PATH, 'utf8');
+  return template
+    .replaceAll('{{branch}}',           branch)
+    .replaceAll('{{reviewer}}',         finalReviewer)
+    .replaceAll('{{implementer}}',      implementer)
+    .replaceAll('{{focus}}',            focus)
+    .replaceAll('{{attempt}}',          String(attempt))
+    .replaceAll('{{slug}}',             slug)
+    .replaceAll('{{missionPath}}',      missionPath)
+    .replaceAll('{{artifactDir}}',      artifactDir)
+    .replaceAll('{{primaryBranch}}',    primaryBranch)
+    .replaceAll('YYYY',                year)
+    .replaceAll('{{review_entrypoint}}', reviewEntrypoint(finalReviewer));
+}
+
+/**
+ * Node-invoked act-on-review prompt built from parallix/prompts/act-on-review.md template.
+ *
+ * @param {object} opts
+ * @param {string} opts.implementer   - Implementer agent family
+ * @param {string} opts.branch        - Mission branch name
+ * @param {number} opts.attempt       - Round number (1-based)
+ * @param {string} [opts.reviewOutcome] - Outcome of latest review (e.g. 'REQUEST_CHANGES')
+ * @param {string} [opts.repoRoot]    - Absolute repo root path
+ * @param {string} [opts.actualImplementer] - The actual agent family launched (overrides implementer for identity text, TASK-1051)
+ * @returns {string}
+ */
+function buildCompactActOnReviewPrompt({ implementer, branch, attempt, reviewOutcome = '?', actualImplementer, repoRoot = '', missionPath: missionPathOverride }) {
+  const slug = branch.replace(/^mission\//, '');
+  const finalImplementer = actualImplementer || implementer;
+  const year = getMissionYear(slug, repoRoot || process.cwd());
+  const missionPath = resolveMissionPath(slug, repoRoot, missionPathOverride);
+  const primaryBranch = resolvePrimaryBranch(repoRoot);
+  const artifactDir = resolveArtifactDir(repoRoot || process.cwd());
+  const template = fs.readFileSync(ACT_ON_REVIEW_PROMPT_PATH, 'utf8');
+  return template
+    .replaceAll('{{branch}}',                  branch)
+    .replaceAll('{{implementer}}',             finalImplementer)
+    .replaceAll('{{attempt}}',                 String(attempt))
+    .replaceAll('{{slug}}',                    slug)
+    .replaceAll('{{missionPath}}',             missionPath)
+    .replaceAll('{{artifactDir}}',             artifactDir)
+    .replaceAll('{{primaryBranch}}',           primaryBranch)
+    .replaceAll('{{review_outcome}}',          reviewOutcome)
+    .replaceAll('YYYY',                       year)
+    .replaceAll('{{act_on_review_entrypoint}}', actOnReviewEntrypoint(finalImplementer));
+}
+
+module.exports = {
+  PROMPT_ENTRYPOINTS,
+  reviewEntrypoint,
+  actOnReviewEntrypoint,
+  buildReviewPrompt,
+  buildActOnReviewPrompt,
+  buildCompactReviewPrompt,
+  buildCompactActOnReviewPrompt
+};

package/lib/review/review-state.js

@@ -0,0 +1,280 @@
+/**
+ * Reviewer-family persistence for the autonomous review loop.
+ *
+ * State is stored under the adapter-resolved mission directory on the mission branch.
+ * Writing and committing state before each round ensures session-restart safety.
+ *
+ * Owned by the Node workflow harness (ADR 0037 / task-089).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { git } = require('../core/git');
+const { findMissionDir, resolveWorktree } = require('../core/mission-utils');
+const fmt = require('../core/fmt');
+
+/**
+ * Return the path to the review-state file for a given slug.
+ * Resolves using the same mission-dir discovery as other workflow commands.
+ *
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {string|null}  Absolute path, or null if mission dir not found
+ */
+function reviewStateFile(slug, rootDir = process.cwd()) {
+  const missionDir = findMissionDir(slug, rootDir);
+  if (!missionDir) return null;
+  return path.join(missionDir, 'review-state.json');
+}
+
+/**
+ * Read the persisted review state for a mission.
+ *
+ * @param {string} slug
+ * @param {string} [rootDir]  Directory to resolve the mission from (defaults to process.cwd())
+ * @returns {ReviewState|null}
+ */
+function readReviewState(slug, rootDir = process.cwd()) {
+  const statePath = reviewStateFile(slug, rootDir);
+  if (!statePath || !fs.existsSync(statePath)) return null;
+
+  try {
+    const raw = fs.readFileSync(statePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.reviewer && parsed.implementer) {
+      return new ReviewState(slug, parsed);
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Resolve the review-provider identity for a review workflow path.
+ *
+ * The normal contract is review-state-backed so standard review/handoff/rebase
+ * paths do not require a provider identity env var to be exported.
+ *
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @param {object} [options]
+ * @returns {{ identityUser: string|null, commentIdentityUser: string|null, forgejoUser: string|null, commentForgejoUser: string|null, reviewState: ReviewState|null, source: 'review-state'|null }}
+ */
+function resolveReviewIdentity(slug, rootDir = process.cwd(), options = {}) {
+  const readReviewStateFn = options.readReviewStateFn || readReviewState;
+  const reviewState = readReviewStateFn(slug, rootDir);
+  const reviewerUser = reviewState ? (reviewState.reviewer || reviewState.implementer || null) : null;
+  const implementerUser = reviewState ? (reviewState.implementer || reviewState.reviewer || null) : null;
+
+  return {
+    identityUser: reviewerUser || null,
+    commentIdentityUser: implementerUser || null,
+    // Legacy aliases kept for compatibility while generic review orchestration
+    // moves to provider-neutral option names.
+    forgejoUser: reviewerUser || null,
+    commentForgejoUser: implementerUser || null,
+    reviewState,
+    source: reviewerUser ? 'review-state' : null
+  };
+}
+
+/**
+ * Manager class for mission review state.
+ * Expanded to include phase, disposition, and metadata for canonical state ownership.
+ */
+const VALID_PHASES = ['reviewing', 'fixing', 'pending-approval', 'approved'];
+const PHASE_ALIASES = new Map([
+  ['review', 'reviewing'],
+  ['rewiewing', 'reviewing'],
+  ['fix', 'fixing'],
+  ['pending_approval', 'pending-approval'],
+  ['pending approval', 'pending-approval']
+]);
+
+const PHASE_TRANSITIONS = {
+  'reviewing': ['fixing', 'approved'],
+  'fixing': ['reviewing', 'pending-approval'],
+  'pending-approval': ['reviewing'],
+  'approved': []
+};
+
+function inferPhaseFromDisposition(disposition) {
+  switch (String(disposition || '').trim().toUpperCase()) {
+  case 'APPROVED':
+    return 'approved';
+  case 'REQUEST_CHANGES':
+  case 'COMMENT':
+  case 'PUSHBACK_ALL':
+  case 'BLOCKED':
+  case 'PARKED':
+    return 'fixing';
+  case 'CHANGES_MADE':
+    return 'reviewing';
+  default:
+    return 'reviewing';
+  }
+}
+
+function normalizeReviewPhase(phase, disposition) {
+  if (!phase) {
+    return { phase: 'reviewing', original: null, normalized: false };
+  }
+
+  const raw = String(phase).trim();
+  const canonical = raw.toLowerCase().replace(/[_\s]+/g, '-');
+  if (VALID_PHASES.includes(canonical)) {
+    return { phase: canonical, original: raw, normalized: canonical !== raw };
+  }
+
+  const alias = PHASE_ALIASES.get(raw.toLowerCase()) || PHASE_ALIASES.get(canonical);
+  if (alias) {
+    return { phase: alias, original: raw, normalized: true };
+  }
+
+  return {
+    phase: inferPhaseFromDisposition(disposition),
+    original: raw,
+    normalized: true
+  };
+}
+
+class ReviewState {
+  constructor(slug, data = {}) {
+    const phaseInfo = normalizeReviewPhase(data.phase, data.disposition);
+    this.slug = slug;
+    this.reviewer = data.reviewer;
+    this.implementer = data.implementer;
+    this.round = data.round || 1;
+    this.startedAt = data.startedAt || new Date().toISOString();
+    this.phase = phaseInfo.phase;
+    this.disposition = data.disposition || null;
+    this.reviewerRetryCount = data.reviewerRetryCount || 0;
+    this.implementerRetryCount = data.implementerRetryCount || 0;
+    this.metadata = data.metadata || {};
+    this.phaseOriginal = phaseInfo.normalized ? phaseInfo.original : null;
+  }
+
+  static from(slug, dataOrInstance) {
+    if (dataOrInstance instanceof ReviewState) {
+      if (dataOrInstance.slug !== slug) {
+        throw new Error(`ReviewState slug mismatch: expected "${slug}", got "${dataOrInstance.slug}"`);
+      }
+      return dataOrInstance;
+    }
+    return new ReviewState(slug, dataOrInstance || {});
+  }
+
+  transitionTo(nextPhase) {
+    if (!VALID_PHASES.includes(nextPhase)) {
+      throw new Error(`Invalid phase: "${nextPhase}". Valid: ${VALID_PHASES.join(', ')}`);
+    }
+    const allowed = PHASE_TRANSITIONS[this.phase];
+    if (!allowed || !allowed.includes(nextPhase)) {
+      throw new Error(`Cannot transition from "${this.phase}" to "${nextPhase}". Allowed: ${(allowed || []).join(', ') || 'none'}`);
+    }
+    this.phase = nextPhase;
+    return this;
+  }
+
+  advanceRound() {
+    this.round += 1;
+    this.phase = 'reviewing';
+    this.disposition = null;
+    this.reviewerRetryCount = 0;
+    this.implementerRetryCount = 0;
+    this.startedAt = new Date().toISOString();
+    return this;
+  }
+
+  toJSON() {
+    const payload = {
+      reviewer: this.reviewer,
+      implementer: this.implementer,
+      round: this.round,
+      startedAt: this.startedAt,
+      phase: this.phase,
+      disposition: this.disposition
+    };
+
+    if (this.reviewerRetryCount > 0) payload.reviewerRetryCount = this.reviewerRetryCount;
+    if (this.implementerRetryCount > 0) payload.implementerRetryCount = this.implementerRetryCount;
+    if (Object.keys(this.metadata).length > 0) payload.metadata = this.metadata;
+
+    return payload;
+  }
+
+  save(worktree = resolveWorktree(this.slug) || process.cwd(), gitFn = git) {
+    const statePath = reviewStateFile(this.slug, worktree);
+    if (!statePath) return false;
+
+    const payload = this.toJSON();
+    fs.writeFileSync(statePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+
+    const relPath = path.relative(worktree, statePath);
+    gitFn(['-C', worktree, 'add', relPath]);
+    const msg = `review-state(${this.slug}): round ${this.round} (${this.phase}) [${this.reviewer} -> ${this.implementer}]${this.disposition ? ` disposition=${this.disposition}` : ''}`;
+    const result = gitFn(['-C', worktree, 'commit', '-m', msg]);
+
+    if (result.status !== 0) {
+      const statusResult = gitFn(['-C', worktree, 'status', '--porcelain', relPath]);
+      if (statusResult.stdout.trim() === '') {
+        return true;
+      }
+      fmt.log.warn(`Failed to commit review state update: ${result.stderr}`);
+    }
+
+    return true;
+  }
+}
+
+/**
+ * Write and commit the review state for a mission.
+ * Commits to the current branch so the state is visible after session restarts.
+ *
+ * @param {string} slug
+ * @param {ReviewState|object} state
+ * @returns {boolean}  true if written successfully
+ */
+function writeReviewState(slug, state, worktree = resolveWorktree(slug) || process.cwd(), gitFn = git) {
+  const instance = state instanceof ReviewState ? state : new ReviewState(slug, state);
+  return instance.save(worktree, gitFn);
+}
+
+/**
+ * Delete the review state file for a mission (used by --reset).
+ * Commits the deletion if the file was tracked.
+ *
+ * @param {string} slug
+ * @returns {boolean}  true if a file was deleted
+ */
+function resetReviewState(slug, worktree = resolveWorktree(slug) || process.cwd(), gitFn = git) {
+  const statePath = reviewStateFile(slug, worktree);
+  if (!statePath || !fs.existsSync(statePath)) return false;
+
+  fs.unlinkSync(statePath);
+
+  const relPath = path.relative(worktree, statePath);
+  try {
+    gitFn(['-C', worktree, 'rm', '--cached', relPath]);
+    const result = gitFn(['-C', worktree, 'commit', '-m', `review-state(${slug}): reset (--reset flag)`]);
+    if (result.status !== 0) {
+      fmt.log.warn(`Failed to commit review state reset: ${result.stderr}`);
+    }
+  } catch (_) {
+    // file may not have been tracked yet
+  }
+
+  return true;
+}
+
+module.exports = {
+  ReviewState,
+  VALID_PHASES,
+  normalizeReviewPhase,
+  reviewStateFile,
+  readReviewState,
+  resolveReviewIdentity,
+  writeReviewState,
+  resetReviewState
+};