@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/commands/active.js

@@ -7,7 +7,7 @@ const agents = require('../agents/agents');
 const { findMissionDir, findCheckpoints, getFirstLine, resolveWorktree, inferSlug, getMissionYear, missionDirForSlug, isWorkflowGeneratedArtifact } = require('../core/mission-utils');
 const handoff = require('./handoff');
 const { resolveTaskFile, transitionTask, getTaskStatus, getTaskImplementer } = require('../tools/backlog');
-const { loadAdapterConfig, resolveAgentModel } = require('../core/product-config');
+const { resolveAgentModel } = require('../core/product-config');
 const review = require('../review/review');
 const repairHandoff = require('./repair-handoff');
 const stats = require('./stats');
@@ -15,21 +15,26 @@ const { resolveStageTelemetry } = require('../agents/stage-telemetry');
 
 const EXECUTE_PROMPT_PATH = path.join(__dirname, '..', '..', 'prompts', 'execute.md');
 
-async function active(args, {
-  inferSlugFn = inferSlug,
-  missionStartFn = missionStart,
-  resolveWorktreeFn = resolveWorktree,
-  readAgentConfigOrExitFn = agents.readAgentConfigOrExit,
-  resolveTaskFileFn = resolveTaskFile,
-  buildCheckpointContextFn = buildCheckpointContext,
-  buildExecutePromptFn = buildExecutePrompt,
-  selectLaunchAndRecordFn = selectLaunchAndRecord,
-  enforceExecuteCommitSafetyFn = enforceExecuteCommitSafety,
-  runHandoffAndReviewFn = runHandoffAndReview,
-  exitFn = process.exit,
-  logFn = fmt.log.info,
-  errorFn = fmt.log.fail
-} = {}) {
+/**
+ * @param {string[]} args
+ * @param {{inferSlugFn?: Function, missionStartFn?: Function, resolveWorktreeFn?: Function, readAgentConfigOrExitFn?: Function, resolveTaskFileFn?: Function, buildCheckpointContextFn?: Function, buildExecutePromptFn?: Function, selectLaunchAndRecordFn?: Function, enforceExecuteCommitSafetyFn?: Function, runHandoffAndReviewFn?: Function, exitFn?: Function, logFn?: Function, errorFn?: Function}} [options]
+ */
+async function active(args, options = {}) {
+  const {
+    inferSlugFn = inferSlug,
+    missionStartFn = missionStart,
+    resolveWorktreeFn = resolveWorktree,
+    readAgentConfigOrExitFn = agents.readAgentConfigOrExit,
+    resolveTaskFileFn = resolveTaskFile,
+    buildCheckpointContextFn = buildCheckpointContext,
+    buildExecutePromptFn = buildExecutePrompt,
+    selectLaunchAndRecordFn = selectLaunchAndRecord,
+    enforceExecuteCommitSafetyFn = enforceExecuteCommitSafety,
+    runHandoffAndReviewFn = runHandoffAndReview,
+    exitFn = process.exit,
+    logFn = fmt.log.info,
+    errorFn = fmt.log.fail
+  } = options;
   const explicitSlug = args[0];
   const slug = inferSlugFn(explicitSlug);
   if (!slug) {
@@ -41,9 +46,10 @@ async function active(args, {
   const normalizedSlug = slug.toLowerCase();
 
   // Allow operators to pin the implementer agent family via CLI flag instead of WORKFLOW_AGENT env var.
+  /** @param {string[]} arr @param {string} flag @param {string} name */
   function flagValue(arr, flag, name) {
     const i = arr.indexOf(flag);
-    if (i === -1) return null;
+    if (i === -1) {return null;}
     const v = arr[i + 1];
     if (!v || v.startsWith('--')) {
       errorFn(fmt.status('FAIL', `Missing value for --${name}. Usage: px active <slug> --${name} <family>`));
@@ -89,7 +95,7 @@ async function active(args, {
       prompt
     });
   } catch (err) {
-    errorFn(`Could not launch execute agent: ${err.message}`);
+    errorFn(`Could not launch execute agent: ${/** @type{Error} */(err).message}`);
     exitFn(1);
     return;
   }
@@ -111,7 +117,7 @@ async function active(args, {
   try {
     enforceExecuteCommitSafetyFn({ slug: normalizedSlug, worktree });
   } catch (error) {
-    errorFn(fmt.status('FAIL', error.message));
+    errorFn(fmt.status('FAIL', /** @type{Error} */(error).message));
     exitFn(1);
     return;
   }
@@ -121,7 +127,8 @@ async function active(args, {
   try {
     const result = launchResult.result;
     const sinceMs = result && result.startedAt ? Date.parse(result.startedAt) : 0;
-    stats.recordActiveStats({
+    stats.recordActiveStats(
+      /** @type{Parameters<typeof stats.recordActiveStats>[0]} */({
       slug: normalizedSlug,
       rootDir: worktree,
       implementer: agent,
@@ -133,9 +140,10 @@ async function active(args, {
       durationMinutes: result && result.startedAt && result.endedAt
         ? (Date.parse(result.endedAt) - Date.parse(result.startedAt)) / 60000
         : 0,
-    });
+    })
+    );
   } catch (err) {
-    logFn(fmt.status('WARN', `Could not record execute stats for ${fmt.slug(normalizedSlug)}: ${err.message}`));
+    logFn(fmt.status('WARN', `Could not record execute stats for ${fmt.slug(normalizedSlug)}: ${/** @type{Error} */(err).message}`));
   }
   logFn(`\nExecute agent (${fmt.agent(agent)}) completed successfully. Starting automated handoff...`);
   const ok = await runHandoffAndReviewFn(normalizedSlug, worktree, agent, {
@@ -156,23 +164,28 @@ async function active(args, {
 // Backlog status is moved to 'active' from the onLaunch hook, which fires
 // immediately after the launcher successfully spawns the process. If the final
 // launch result later fails, we roll the task status back to the prior status.
-async function selectLaunchAndRecord({
-  slug,
-  worktree,
-  preselectedAgent = null,
-  agentConfig,
-  taskResolution,
-  prompt,
-  startAgentFn = (step, opts) => agents.startAgent(step, opts),
-  transitionTaskFn = transitionTask,
-  getTaskStatusFn = getTaskStatus,
-  getTaskImplementerFn = getTaskImplementer,
-  selectAgentFn = agents.selectAgent,
-  log = fmt.log.plain
-}) {
+/**
+ * @param {{slug: string, worktree: string, preselectedAgent?: string | null, agentConfig: object, taskResolution: object, prompt: string, startAgentFn?: Function, transitionTaskFn?: Function, getTaskStatusFn?: Function, getTaskImplementerFn?: Function, selectAgentFn?: Function, log?: Function}} opts
+ */
+async function selectLaunchAndRecord(opts) {
+  const {
+    slug,
+    worktree,
+    preselectedAgent = null,
+    agentConfig,
+    taskResolution,
+    prompt,
+    startAgentFn = (/** @type{string} */ step, /** @type{any} */ opts) => agents.startAgent(step, opts),
+    transitionTaskFn = transitionTask,
+    getTaskStatusFn = getTaskStatus,
+    getTaskImplementerFn = getTaskImplementer,
+    selectAgentFn = agents.selectAgent,
+    log = fmt.log.plain
+  } = opts;
   const preselected = preselectedAgent || selectAgentFn('active', { config: agentConfig });
-  const taskFile = taskResolution && taskResolution.ok && taskResolution.taskFile
-    ? taskResolution.taskFile
+  const taskResolutionTyped = /** @type{{ok: boolean, taskFile?: string} | undefined} */(taskResolution);
+  const taskFile = taskResolutionTyped && taskResolutionTyped.ok && taskResolutionTyped.taskFile
+    ? taskResolutionTyped.taskFile
     : null;
   const priorStatus = taskFile ? getTaskStatusFn(taskFile) : null;
   const priorImplementer = taskFile ? getTaskImplementerFn(taskFile) : null;
@@ -185,6 +198,7 @@ async function selectLaunchAndRecord({
     }
 
     log(fmt.status('WARN', `Execute launch for ${fmt.slug(slug)} did not complete cleanly; rolling task state back to ${priorStatus} / ${priorImplementer || 'none'}.`));
+    /** @type{{rootDir: string, log: Function, implementer?: string, clearAssignee?: boolean}} */
     const rollbackOpts = { rootDir: worktree, log };
     if (priorImplementer) {
       rollbackOpts.implementer = priorImplementer;
@@ -193,7 +207,7 @@ async function selectLaunchAndRecord({
     }
     if (!transitionTaskFn(slug, priorStatus, rollbackOpts)) {
       const msg = `Failed to roll back task ${fmt.slug(slug)} to ${priorStatus} after execute launch failure.`;
-      if (throwOnFailure) throw new Error(msg);
+      if (throwOnFailure) {throw new Error(msg);}
       log(fmt.status('WARN', msg));
     }
     launchRecorded = false;
@@ -208,9 +222,9 @@ async function selectLaunchAndRecord({
       agent: preselected,
       slug: slug,
       role: 'implementer',
-      onLaunch: ({ agent }) => {
+      onLaunch: (/** @type{{agent: string}} */ { agent }) => {
         launchedAgent = agent;
-        if (!(taskResolution && taskResolution.ok)) {
+        if (!(taskResolutionTyped && taskResolutionTyped.ok)) {
           return;
         }
 
@@ -253,19 +267,22 @@ async function selectLaunchAndRecord({
 // implementer that actually ran is `actual`, not the originally `preselected`
 // one. Re-record the resolved agent in the Backlog task so the post-active
 // handoff and the autonomous review loop poll the correct Forgejo identity.
-function applyExecuteFallback({
-  slug,
-  preselected,
-  actual,
-  taskResolution,
-  worktree,
-  log = fmt.log.plain,
-  transitionTaskFn = transitionTask
-}) {
+/** @param {{slug: string, preselected: string, actual: string, taskResolution: object, worktree: string, log?: Function, transitionTaskFn?: Function}} opts */
+function applyExecuteFallback(opts) {
+  const {
+    slug,
+    preselected,
+    actual,
+    taskResolution,
+    worktree,
+    log = fmt.log.plain,
+    transitionTaskFn = transitionTask
+  } = opts;
   if (!actual || actual === preselected) {
     return preselected;
   }
-  if (taskResolution && taskResolution.ok) {
+  const taskResolutionTyped2 = /** @type{{ok: boolean, taskFile?: string} | undefined} */(taskResolution);
+  if (taskResolutionTyped2 && taskResolutionTyped2.ok) {
     log(fmt.status('INFO', `Execute agent fell back from ${fmt.agent(preselected)} to ${fmt.agent(actual)}; enforcing backlog assignee.`));
     transitionTaskFn(slug, 'active', { implementer: actual, rootDir: worktree, log });
   }
@@ -283,14 +300,22 @@ function applyExecuteFallback({
  * @param {object} [options]
  * @returns {Promise<{relaunched: boolean, error?: string}>} Result of relaunch attempt
  */
-async function attemptAgentRelaunch(slug, worktree, errorMsg, agent, {
-  isRelaunchableErrorFn = repairHandoff.isRelaunchableError,
-  buildRelaunchPromptFn = repairHandoff.buildRelaunchPrompt,
-  workflowLauncherStatusFn = agents.workflowLauncherStatus,
-  startAgentFn = agents.startAgent,
-  log = fmt.log.plain,
-  error = fmt.log.plainError
-} = {}) {
+/**
+ * @param {string} slug
+ * @param {string} worktree
+ * @param {string} errorMsg
+ * @param {string} agent
+ * @param {{isRelaunchableErrorFn?: Function, buildRelaunchPromptFn?: Function, workflowLauncherStatusFn?: Function, startAgentFn?: Function, log?: Function, error?: Function}} [options]
+ */
+async function attemptAgentRelaunch(slug, worktree, errorMsg, agent, options = {}) {
+  const {
+    isRelaunchableErrorFn = repairHandoff.isRelaunchableError,
+    buildRelaunchPromptFn = repairHandoff.buildRelaunchPrompt,
+    workflowLauncherStatusFn = agents.workflowLauncherStatus,
+    startAgentFn = agents.startAgent,
+    log = fmt.log.plain,
+    error = fmt.log.plainError
+  } = options;
   // Check if this is a relaunchable error
   if (!isRelaunchableErrorFn(errorMsg)) {
     log(`Error is not relaunchable: ${errorMsg}`);
@@ -318,7 +343,7 @@ async function attemptAgentRelaunch(slug, worktree, errorMsg, agent, {
       slug,
       role: 'implementer',
       // startAgent will use RESUME_CAPABLE set and session markers to decide resume
-      onLaunch: ({ agent: launchedAgent }) => {
+      onLaunch: (/** @type{{agent: string}} */ { agent: launchedAgent }) => {
         log(`Relaunched ${fmt.agent(launchedAgent)} for repair. Session persistence will be used if available.`);
       }
     });
@@ -336,18 +361,20 @@ async function attemptAgentRelaunch(slug, worktree, errorMsg, agent, {
     log(`Relaunch successful. ${fmt.agent(agent)} is now running to fix the handoff error.`);
     return { relaunched: true };
   } catch (err) {
-    error(`Relaunch failed with exception: ${err.message}`);
-    return { relaunched: false, error: err.message };
+    error(`Relaunch failed with exception: ${/** @type{Error} */(err).message}`);
+    return { relaunched: false, error: /** @type{Error} */(err).message };
   }
 }
 
-function validateCheckpointsBeforeHandoff(slug, worktree, {
-  findMissionDirFn = findMissionDir,
-  findCheckpointsFn = findCheckpoints,
-  runFn = git,
-  log = fmt.log.plain,
-  error = fmt.log.plainError
-} = {}) {
+/** @param {string} slug @param {string} worktree @param {{findMissionDirFn?: Function, findCheckpointsFn?: Function, runFn?: Function, log?: Function, error?: Function}} [options] */
+function validateCheckpointsBeforeHandoff(slug, worktree, options = {}) {
+  const {
+    findMissionDirFn = findMissionDir,
+    findCheckpointsFn = findCheckpoints,
+    runFn = git,
+    log = fmt.log.plain,
+    error = fmt.log.plainError
+  } = options;
   const rootDir = worktree || process.cwd();
   const missionDir = findMissionDirFn(slug, rootDir);
   if (!missionDir) {
@@ -363,7 +390,7 @@ function validateCheckpointsBeforeHandoff(slug, worktree, {
     return { ok: false, error: msg };
   }
 
-  const checkpointArgs = checkpoints.map(checkpoint => path.relative(rootDir, checkpoint) || checkpoint);
+  const checkpointArgs = checkpoints.map((/** @type{string} */ checkpoint) => path.relative(rootDir, checkpoint) || checkpoint);
   const statusResult = runFn(['status', '--porcelain', '--', ...checkpointArgs], { cwd: rootDir });
   if (statusResult.status !== 0) {
     const statusError = (statusResult.stderr || statusResult.stdout || '').trim() || 'git status failed';
@@ -374,14 +401,14 @@ function validateCheckpointsBeforeHandoff(slug, worktree, {
 
   const dirtyCheckpointLines = (statusResult.stdout || '')
     .split('\n')
-    .map(line => line.trimEnd())
+    .map((/** @type{string} */ line) => line.trimEnd())
     .filter(Boolean);
 
   if (dirtyCheckpointLines.length > 0) {
     const dirtyPaths = dirtyCheckpointLines
-      .map(line => line.slice(3).trim())
+      .map((/** @type{string} */ line) => line.slice(3).trim())
       .filter(Boolean);
-    const msg = `Checkpoint documents must be committed before handoff. Uncommitted checkpoint files: ${dirtyPaths.map(p => fmt.path(p)).join(', ')}. Commit the checkpoint update and re-run the handoff.`;
+    const msg = `Checkpoint documents must be committed before handoff. Uncommitted checkpoint files: ${dirtyPaths.map((/** @type{string} */ p) => fmt.path(p)).join(', ')}. Commit the checkpoint update and re-run the handoff.`;
     error(msg);
     return { ok: false, error: msg };
   }
@@ -390,16 +417,23 @@ function validateCheckpointsBeforeHandoff(slug, worktree, {
   return { ok: true };
 }
 
-async function runHandoffAndReview(slug, worktree, agent, {
-  taskFile = null,
-  validateCheckpointsBeforeHandoffFn = validateCheckpointsBeforeHandoff,
-  performHandoff: _performHandoff = (s, o) => handoff.performHandoff(s, o),
-  startReviewLoop: _startReviewLoop = (s, o) => review.startReviewLoop(s, o),
-  repairHandoffFn = repairHandoff,
-  attemptAgentRelaunchFn = attemptAgentRelaunch,
-  log = fmt.log.plain,
-  error = fmt.log.plainError
-} = {}) {
+/**
+ * @param {string} slug
+ * @param {string} worktree
+ * @param {string} agent
+  * @param {{taskFile?: string | null, validateCheckpointsBeforeHandoffFn?: Function, performHandoff?: Function, startReviewLoop?: Function, repairHandoffFn?: {isRelaunchableError: Function, buildRelaunchPrompt: Function}, attemptAgentRelaunchFn?: Function, log?: Function, error?: Function}} [options]
+ */
+async function runHandoffAndReview(slug, worktree, agent, options = {}) {
+  const {
+    taskFile = null,
+    validateCheckpointsBeforeHandoffFn = validateCheckpointsBeforeHandoff,
+    performHandoff: _performHandoff = (/** @type{string} */ s, /** @type{object} */ o) => handoff.performHandoff(s, o),
+    startReviewLoop: _startReviewLoop = (/** @type{string} */ s, /** @type{object} */ o) => review.startReviewLoop(s, o),
+    repairHandoffFn = /** @type{(s: string, w: string, e: string, o: object) => Promise<{repaired: boolean, blocker?: string}>} */(repairHandoff),
+    attemptAgentRelaunchFn = attemptAgentRelaunch,
+    log = fmt.log.plain,
+    error = fmt.log.plainError
+  } = options;
   // Pre-handoff checkpoint enforcement: validate checkpoints exist before calling performHandoff()
   // This catches missing checkpoints immediately after the execute agent exits,
   // before the repair flow runs, and provides an explicit instruction to create them.
@@ -417,7 +451,7 @@ async function runHandoffAndReview(slug, worktree, agent, {
     // Attempt single repair for routine hygiene issues (dirty artifacts, rebase needed)
     log(`\nAutomated handoff failed: ${handoffResult.error}`);
     log(`Attempting post-execute repair...`);
-    const { repaired, blocker } = await repairHandoffFn(slug, worktree, handoffResult.error, { taskFile, log, error });
+    const { repaired, blocker } = await /** @type{Function} */(repairHandoffFn)(slug, worktree, /** @type{string} */(handoffResult.error), { taskFile, log, error });
     if (repaired) {
       log(`Repair successful. Retrying automated handoff...`);
       handoffResult = await _performHandoff(slug, { forgejoUser: agent, worktree, force: true });
@@ -429,7 +463,7 @@ async function runHandoffAndReview(slug, worktree, agent, {
       // Attempt agent relaunch for repairable content errors (missing goal-check table)
       log(`Content error detected. Attempting agent relaunch to fix...`);
       const { relaunched, error: relaunchError } = await attemptAgentRelaunchFn(
-        slug, worktree, handoffResult.error, agent, { log, error }
+        slug, worktree, /** @type{string} */(handoffResult.error), agent, { log, error }
       );
       if (relaunched) {
         // Agent was relaunched successfully; re-invoke performHandoff to verify
@@ -456,7 +490,9 @@ async function runHandoffAndReview(slug, worktree, agent, {
     return false;
   }
 
-  if (handoffResult.gatekeeperPushedBack) {
+  /** @type{{ok: boolean, error?: string, gatekeeperPushedBack?: boolean}} */
+  const hr = handoffResult;
+  if (hr.gatekeeperPushedBack) {
     log(`\nGatekeeper posted pushback for ${fmt.slug(slug)}; skipping autonomous review loop until artifacts are fixed.`);
     return true;
   }
@@ -466,18 +502,20 @@ async function runHandoffAndReview(slug, worktree, agent, {
   return true;
 }
 
+/** @param {string} slug */
 function buildCheckpointContext(slug) {
   const missionDir = findMissionDir(slug);
-  if (!missionDir) return 'No checkpoint documents found. Start from CP-1.';
+  if (!missionDir) {return 'No checkpoint documents found. Start from CP-1.';}
 
   const checkpoints = findCheckpoints(missionDir);
-  if (checkpoints.length === 0) return 'No checkpoint documents found. Start from CP-1.';
+  if (checkpoints.length === 0) {return 'No checkpoint documents found. Start from CP-1.';}
 
   const latest = checkpoints[checkpoints.length - 1];
   const firstLine = getFirstLine(latest);
   return `Most recent checkpoint: ${path.basename(latest)} — ${firstLine}\nResume from there, or start the next checkpoint if that one is complete.`;
 }
 
+/** @param {string} slug @param {string} rootDir */
 function resolveExecuteTaskPath(slug, rootDir) {
   const resolution = resolveTaskFile(slug, rootDir);
   if (resolution && resolution.ok && resolution.taskFile) {
@@ -486,7 +524,9 @@ function resolveExecuteTaskPath(slug, rootDir) {
   return path.join(rootDir, 'backlog', 'tasks', `<${slug}>.md`);
 }
 
-function buildExecutePrompt(slug, checkpointContext, { rootDir = process.cwd() } = {}) {
+/** @param {string} slug @param {string} checkpointContext @param {{rootDir?: string}} [options] */
+function buildExecutePrompt(slug, checkpointContext, options = {}) {
+  const { rootDir = process.cwd() } = options;
   const template = fs.readFileSync(EXECUTE_PROMPT_PATH, 'utf8');
   const year = getMissionYear(slug, rootDir) || String(new Date().getFullYear());
   const missionPath = path.join(missionDirForSlug(rootDir, slug), 'MISSION.md');
@@ -507,6 +547,7 @@ function buildExecutePrompt(slug, checkpointContext, { rootDir = process.cwd() }
 // and escapes are display syntax, not part of the on-disk path, so they must be
 // decoded before the value is handed to `git add --` — otherwise git treats the
 // quote-wrapped string as a pathspec that matches no file and aborts staging.
+/** @param {string} rawPath */
 function unquoteGitStatusPath(rawPath) {
   if (rawPath.length < 2 || rawPath[0] !== '"' || rawPath[rawPath.length - 1] !== '"') {
     return rawPath;
@@ -542,18 +583,19 @@ function unquoteGitStatusPath(rawPath) {
     }
     if (Object.prototype.hasOwnProperty.call(simple, next)) {
       flush();
-      chunks.push(Buffer.from([simple[next]]));
+      chunks.push(Buffer.from([/** @type{number} */(simple[/** @type{keyof typeof simple} */(next)])]));
       i++;
     } else {
       // Unknown or trailing escape: keep the following character literally.
       literal += next === undefined ? '\\' : next;
-      if (next !== undefined) i++;
+      if (next !== undefined) {i++;}
     }
   }
   flush();
   return Buffer.concat(chunks).toString('utf8');
 }
 
+/** @param {string} entry */
 function parseDirtyEntry(entry) {
   const match = entry.match(/^(.{1,2})\s+(.*)$/);
   const status = (match ? match[1] : entry.slice(0, 2)).padEnd(2, ' ');
@@ -561,17 +603,20 @@ function parseDirtyEntry(entry) {
   // For renames git reports `<old> -> <new>`; each side is independently quoted
   // and the ` -> ` separator is always literal, so split before unquoting and
   // keep staging the destination path.
-  const renamed = rawPath.includes(' -> ') ? rawPath.split(' -> ').pop() : rawPath;
+  const renamed = rawPath.includes(' -> ') ? (rawPath.split(' -> ').pop() || rawPath) : rawPath;
   const filePath = unquoteGitStatusPath(renamed.trim());
   return { status, filePath };
 }
 
+/** @param {string} filePath */
 function isExecuteIgnoredPath(filePath) {
   return isWorkflowGeneratedArtifact(filePath);
 }
 
-function enforceExecuteCommitSafety({ slug, worktree, dirtyEntries = getWorktreeStatus(worktree), gitImpl = git }) {
-  const parsedEntries = dirtyEntries.map(parseDirtyEntry);
+/** @param {{slug: string, worktree: string, dirtyEntries?: Array<{status: string, filePath: string}>, gitImpl?: Function}} opts */
+function enforceExecuteCommitSafety(opts) {
+  const { slug, worktree, dirtyEntries = getWorktreeStatus(worktree), gitImpl = git } = opts;
+  const parsedEntries = /** @type{Array<{status: string, filePath: string}>} */(/** @type{Array<string>} */(dirtyEntries).map(parseDirtyEntry));
   const relevantEntries = parsedEntries.filter(entry => !isExecuteIgnoredPath(entry.filePath));
   const conflictEntries = relevantEntries.filter(entry =>
     ['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'].includes(entry.status.trim())

package/lib/commands/checkpoint.js

@@ -1,11 +1,13 @@
 const { git, run, getCurrentBranch } = require('../core/git');
 const { findMissionDir, findMissionArea, inferSlug } = require('../core/mission-utils');
-const path = require('path');
 const fmt = require('../core/fmt');
 const { formatVerificationCommand, runVerificationGate } = require('../core/verification');
 
+/** @param {string[]} args */
 function checkpoint(args) {
+  /** @param {string} a */
   const flags = args.filter(a => a.startsWith('--'));
+  /** @param {string} a */
   const params = args.filter(a => !a.startsWith('--'));
   
   let [explicitSlug, cpName, nextAction] = params;

package/lib/commands/config.js

@@ -8,17 +8,19 @@ const { loadEffectiveConfig, loadWorkflowConfig, validateWorkflowConfig } = requ
 // This replaces the deleted workflow.config.json.example as the way to discover
 // the configurable surface, with no copy-paste footgun and no second source of
 // truth to drift from (task-1233 Scope Amendment).
-async function config(args = [], opts = {}) {
+/** @param {string[]} _args @param {{logFn?: Function, errorFn?: Function, exitFn?: Function, rootDir?: string}} opts */
+async function config(_args = [], opts = {}) {
+  void _args; // intentionally unused — part of public API signature
   const logFn = opts.logFn || fmt.log.plain;
   const errorFn = opts.errorFn || fmt.log.plainError;
-  const exitFn = opts.exitFn || (code => { process.exitCode = code; });
+  const exitFn = opts.exitFn || /** @type{(code: number) => void} */ ((code) => { process.exitCode = code; });
   const rootDir = opts.rootDir || process.cwd();
 
   const loaded = loadWorkflowConfig(rootDir);
   if (!loaded.found) {
     logFn(fmt.status('INFO', 'No workflow.config.json found — showing built-in defaults.'));
   } else if (loaded.parseError) {
-    errorFn(fmt.status('FAIL', `workflow.config.json is invalid JSON (${loaded.parseError.message}); showing fallback built-in defaults.`));
+    errorFn(fmt.status('FAIL', `workflow.config.json is invalid JSON (${/** @type{Error} */(loaded.parseError).message}); showing fallback built-in defaults.`));
     logFn(JSON.stringify(loadEffectiveConfig(rootDir), null, 2));
     exitFn(1);
     return;

package/lib/commands/coverage-gate.js

@@ -89,6 +89,7 @@ const COVERAGE_EXCLUDES = [
 // under cold caches. Keep the gate generous so it can finish without a manual
 // override while still failing on real hangs.
 const DEFAULT_TEST_TIMEOUT_MS = 3_600_000;
+/** @type {string[]} */
 const PER_RUN_SCRATCH = [];
 let threshold = 90;
 let dryRun = false;
@@ -108,7 +109,7 @@ for (let i = 2; i < process.argv.length; i++) {
 
 function discoverTestFiles() {
   const testDir = path.join(REPO_ROOT, 'test');
-  if (!fs.existsSync(testDir)) return [];
+  if (!fs.existsSync(testDir)) {return [];}
   return fs.readdirSync(testDir)
     .filter(file => file.endsWith('.test.js'))
     .filter(file => file !== SELF_TEST_FILE)
@@ -117,18 +118,20 @@ function discoverTestFiles() {
 }
 
 function listTempEntries(tmpRoot = os.tmpdir()) {
-  if (!fs.existsSync(tmpRoot)) return new Set();
+  if (!fs.existsSync(tmpRoot)) {return new Set();}
   return new Set(fs.readdirSync(tmpRoot));
 }
 
+/** @param {string} name */
 function shouldCleanTempDir(name) {
   return TEMP_DIR_PREFIXES.some(prefix => name.startsWith(prefix));
 }
 
+/** @param {Set<string>} beforeEntries @param {string} tmpRoot */
 function cleanupNewTempDirs(beforeEntries, tmpRoot = os.tmpdir()) {
-  if (!fs.existsSync(tmpRoot)) return;
+  if (!fs.existsSync(tmpRoot)) {return;}
   for (const name of fs.readdirSync(tmpRoot)) {
-    if (beforeEntries.has(name) || !shouldCleanTempDir(name)) continue;
+    if (beforeEntries.has(name) || !shouldCleanTempDir(name)) {continue;}
     const fullPath = path.join(tmpRoot, name);
     let stat = null;
     try {
@@ -136,7 +139,7 @@ function cleanupNewTempDirs(beforeEntries, tmpRoot = os.tmpdir()) {
     } catch (_) {
       continue;
     }
-    if (!stat.isDirectory()) continue;
+    if (!stat.isDirectory()) {continue;}
     try {
       fs.rmSync(fullPath, { recursive: true, force: true });
     } catch (_) {}
@@ -179,7 +182,7 @@ exit 1
 }
 
 function cleanupPerRunScratch() {
-  if (cleanupDone) return;
+  if (cleanupDone) {return;}
   cleanupDone = true;
   for (const dir of PER_RUN_SCRATCH) {
     try {
@@ -208,6 +211,7 @@ function resetPerRunScratchState() {
   cleanupDone = false;
 }
 
+/** @param {string[]} testFiles @param {number} coverageThreshold @param {boolean} useLcov */
 function buildCoverageArgs(testFiles, coverageThreshold = threshold, useLcov = lcov) {
   const args = [
     '--test',
@@ -234,11 +238,12 @@ function buildCoverageArgs(testFiles, coverageThreshold = threshold, useLcov = l
 
 function resolveTestTimeoutMs(env = process.env) {
   const raw = env.WORKFLOW_COVERAGE_GATE_TIMEOUT_MS;
-  if (raw === undefined || raw === '') return DEFAULT_TEST_TIMEOUT_MS;
+  if (raw === undefined || raw === '') {return DEFAULT_TEST_TIMEOUT_MS;}
   const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TEST_TIMEOUT_MS;
 }
 
+/** @param {string[]} testFiles @param {number} coverageThreshold @param {Function} _spawnSync */
 function runTests(testFiles, coverageThreshold = threshold, _spawnSync = spawnSync) {
   const tmpRoot = createPerRunTmpRoot();
   const tmpEntriesBefore = listTempEntries(tmpRoot);
@@ -300,7 +305,9 @@ if (require.main === module) {
   main();
 }
 
+/** @param {string[]} args @param {{exitFn?: Function}} options */
 function run(args, options = {}) {
+  /** @type{Function} */
   const exitFn = options.exitFn || process.exit;
   let threshold_ = 90;
   let dryRun_ = false;
@@ -320,7 +327,7 @@ function run(args, options = {}) {
     if (dryRun_) {
       const testFiles = discoverTestFiles();
       if (testFiles.length === 0) {
-        if (typeof exitFn === 'function') exitFn(1);
+        if (typeof exitFn === 'function') {exitFn(1);}
       } else {
         fmt.log.info(`Found ${testFiles.length} test file(s)`);
         fmt.log.info(`DRY-RUN mode — threshold=${threshold}%`);
@@ -328,8 +335,8 @@ function run(args, options = {}) {
         fmt.log.info(`Include globs: ${COVERAGE_INCLUDES.join(', ')}`);
         fmt.log.info(`Exclude globs: ${COVERAGE_EXCLUDES.join(', ')}`);
         fmt.log.info(`Would run: ${fmt.command(`${process.execPath} ${buildCoverageArgs(testFiles, threshold).join(' ')}`)}`);
-        if (typeof exitFn === 'function') exitFn(0);
-        else process.exit(0);
+        if (typeof exitFn === 'function') {exitFn(0);}
+        else {process.exit(0);}
       }
     } else {
       registerExitHandlers();