@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/recovery.js

@@ -0,0 +1,282 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Failure classifier and bounded recovery planner — the JavaScript port of
+ * `core/shared/scripts/doflow/recovery/recovery_manager.py` (plan task B.3, component C8).
+ *
+ * All **eleven** failure classes are kept, against the specification's seven (design R4, plan
+ * decision D3 and risk RK6): TOOL_FAILURE, AGENT_FAILURE, BUDGET_EXCEEDED and UNKNOWN_FAILURE are
+ * real discriminations the Python already made, and narrowing to match a document would throw away
+ * working behaviour. The classification order, every keyword, the strategy table, the
+ * agent-switch rule and the three-iteration bound are reproduced exactly.
+ *
+ * Two defects are fixed rather than reproduced, each explained at its site:
+ *   1. `plan_recovery` returned two incompatible record shapes — the abort path omitted `canRetry`
+ *      and `failureClass`, so the natural caller check `result["canRetry"]` raised on exactly the
+ *      path that must stop the loop.
+ *   2. `classify_failure` assumed its arguments' types; a `None` message or a bare string of check
+ *      names either raised or silently iterated characters.
+ */
+
+const { finishRuntime, usageError } = require('./cli-result.js');
+
+/** The eleven classes, in the order the Python declared them. */
+const FAILURE_CLASSES                    = Object.freeze([
+  'CONTEXT_MISSING',
+  'WRONG_IMPLEMENTATION',
+  'TEST_FAILURE',
+  'BUILD_FAILURE',
+  'ARCHITECTURE_FAILURE',
+  'REQUIREMENT_FAILURE',
+  'ENVIRONMENT_FAILURE',
+  'TOOL_FAILURE',
+  'AGENT_FAILURE',
+  'BUDGET_EXCEEDED',
+  'UNKNOWN_FAILURE',
+]);
+
+const DEFAULT_MAX_ITERATIONS = 3;
+
+/** Check-name fragments that identify a build-stage failure regardless of the error text. */
+const BUILD_CHECK_MARKERS                    = Object.freeze(['syntax', 'compile', 'build']);
+/** Check-name fragments that identify a test-stage failure. */
+const TEST_CHECK_MARKERS                    = Object.freeze(['test', 'unit']);
+
+/**
+ * Per-class recovery strategy — **one entry per class, all eleven** (plan task C.2).
+ *
+ * The B.3 port preserved the Python's six-entry table, under which WRONG_IMPLEMENTATION,
+ * TOOL_FAILURE, AGENT_FAILURE, BUDGET_EXCEEDED and UNKNOWN_FAILURE all fell through to
+ * `GENERIC_DEBUGGER_FIX`. C.2 completes the table, because that fallthrough directly contradicts
+ * FR-010 — "the response MUST be the targeted action for that class" — and in two cases the generic
+ * action is not merely untargeted but wrong:
+ *
+ *   - BUDGET_EXCEEDED: handing the task back to a debugger spends more of the budget that is
+ *     already gone. It is the one class where the targeted action is to stop, so it is `terminal`.
+ *   - TOOL_FAILURE: an unreachable MCP server or a missing provider is not fixed by rewriting code,
+ *     and swapping the agent changes nothing about the tool. The action routes to a fallback
+ *     provider instead (the capability router already declares those fallbacks).
+ *
+ * Classifying eleven ways and then acting six ways discarded most of what the classifier
+ * established. `GENERIC_STRATEGY` is retained and still reachable — a caller may pass a class
+ * string that is not one of the eleven — but no declared class relies on it any more.
+ *
+ * `switchAtIteration` encodes the Python's three agent-switch behaviours: `null` never switches,
+ * `0` always switches (its unconditional `True`), and `2` switches only once two attempts have
+ * already been spent (its `current_iteration >= 2`). `terminal` is new and means the class is not
+ * retryable at any iteration.
+ */
+const STRATEGY_MAP                                = Object.freeze({
+  CONTEXT_MISSING: { action: 'RETRIEVE_MORE_CONTEXT', targetRole: 'SCOUT', switchAtIteration: null },
+  WRONG_IMPLEMENTATION: { action: 'REVISE_IMPLEMENTATION', targetRole: 'IMPLEMENTER', switchAtIteration: 2 },
+  TEST_FAILURE: { action: 'TARGETED_DEBUGGER_FIX', targetRole: 'DEBUGGER', switchAtIteration: 2 },
+  BUILD_FAILURE: { action: 'TARGETED_COMPILER_FIX', targetRole: 'DEBUGGER', switchAtIteration: 2 },
+  ARCHITECTURE_FAILURE: { action: 'GRAPH_RE_EVALUATION', targetRole: 'PLANNER', switchAtIteration: 0 },
+  REQUIREMENT_FAILURE: { action: 'SPEC_RECONCILIATION', targetRole: 'PLANNER', switchAtIteration: 0 },
+  ENVIRONMENT_FAILURE: { action: 'ENVIRONMENT_DIAGNOSTIC', targetRole: 'VERIFIER', switchAtIteration: null },
+  TOOL_FAILURE: { action: 'ROUTE_TO_FALLBACK_PROVIDER', targetRole: 'VERIFIER', switchAtIteration: null },
+  // The agent itself is the failure, so the switch is the action rather than a later escalation.
+  AGENT_FAILURE: { action: 'SWITCH_AGENT_AND_RESTATE_TASK', targetRole: 'IMPLEMENTER', switchAtIteration: 0 },
+  BUDGET_EXCEEDED: { action: 'ESCALATE_TO_USER', targetRole: null, switchAtIteration: null, terminal: true },
+  // Diagnose before acting: an unclassified failure is the one case where a targeted fix cannot be
+  // chosen, and guessing one is how a recovery loop burns its whole bound on the wrong repair.
+  UNKNOWN_FAILURE: { action: 'DIAGNOSTIC_TRIAGE', targetRole: 'VERIFIER', switchAtIteration: null },
+});
+
+/** Reachable only for a class string outside the eleven — see the note on STRATEGY_MAP. */
+const GENERIC_STRATEGY                                = Object.freeze({
+  action: 'GENERIC_DEBUGGER_FIX',
+  targetRole: 'DEBUGGER',
+  switchAtIteration: 2,
+});
+
+/**
+ * @param {*} value
+ * @returns {Array<string>} only the string members, lowercased
+ */
+function normalizeCheckNames(value     )           {
+  // Defect fix (2a): the Python accepted `failed_checks` unvalidated. Handed a plain string it
+  // iterated characters, so every single-letter "check" was tested for "syntax" and none matched —
+  // a build failure silently classified as WRONG_IMPLEMENTATION.
+  if (!Array.isArray(value)) return [];
+  return value.filter((v     ) => typeof v === 'string').map((v        ) => v.toLowerCase());
+}
+
+class RecoveryManager {
+  maxIterations        ;
+
+  /**
+   * @param {Object|number} [options] a number is accepted for parity with the Python's positional
+   *   `max_iterations` argument
+   * @param {number} [options.maxIterations=3]
+   */
+  constructor(options      = {}) {
+    const opts = typeof options === 'number' ? { maxIterations: options } : options;
+    this.maxIterations = opts.maxIterations || DEFAULT_MAX_ITERATIONS;
+  }
+
+  /**
+   * Classifies a failure into one of the eleven classes.
+   *
+   * Order matters and is preserved: the names of the checks that failed outrank the wording of the
+   * error message, because a check name is structural evidence and an error string is prose.
+   * @param {string} errorMessage
+   * @param {Array<string>} [failedChecks=[]]
+   * @returns {string} one of FAILURE_CLASSES
+   */
+  classifyFailure(errorMessage     , failedChecks      = [])         {
+    const checks = normalizeCheckNames(failedChecks);
+    // Defect fix (2b): `None.lower()` raised. A classifier handed no message should return
+    // UNKNOWN_FAILURE, not abort the recovery path that exists to handle failures.
+    const msg = typeof errorMessage === 'string' ? errorMessage.toLowerCase() : '';
+
+    const anyCheck = (markers                   ) => checks.some((chk) => markers.some((m) => chk.includes(m)));
+
+    if (anyCheck(BUILD_CHECK_MARKERS) || msg.includes('build error')) {
+      return 'BUILD_FAILURE';
+    }
+    if (anyCheck(TEST_CHECK_MARKERS) || msg.includes('test failed') || msg.includes('assertionerror')) {
+      return 'TEST_FAILURE';
+    }
+    if (msg.includes('budget') || msg.includes('token limit')) {
+      return 'BUDGET_EXCEEDED';
+    }
+    if (msg.includes('missing file') || msg.includes('cannot find module') || msg.includes('not found')) {
+      return 'CONTEXT_MISSING';
+    }
+    if (msg.includes('timeout') || msg.includes('connection refused') || msg.includes('econnrefused')) {
+      return 'ENVIRONMENT_FAILURE';
+    }
+    if (msg.includes('tool error') || msg.includes('mcp error')) {
+      return 'TOOL_FAILURE';
+    }
+    if (msg.includes('architecture') || msg.includes('boundary')) {
+      return 'ARCHITECTURE_FAILURE';
+    }
+    if (msg.includes('requirement') || msg.includes('acceptance criterion')) {
+      return 'REQUIREMENT_FAILURE';
+    }
+    if (msg.includes('agent') || msg.includes('hallucination')) {
+      return 'AGENT_FAILURE';
+    }
+    if (checks.length > 0) {
+      return 'WRONG_IMPLEMENTATION';
+    }
+    return 'UNKNOWN_FAILURE';
+  }
+
+  /**
+   * Determines the next recovery action and whether to hand the task to a different agent.
+   * @param {string} failureClass
+   * @param {number} currentIteration zero-based count of retries already spent
+   * @param {string} [lastAgent='codex']
+   * @returns {{ iteration: number, failureClass: string, action: string, targetRole: string|null, agent: string, canRetry: boolean, reason?: string }}
+   */
+  planRecovery(failureClass        , currentIteration        , lastAgent         = 'codex')                                                                                                                                            {
+    // A negative or non-numeric iteration is caller nonsense; clamping keeps it from reading as
+    // "before the first attempt" and skipping the agent switch that iteration 0 is supposed to get.
+    const iteration = Number.isFinite(currentIteration) ? Math.max(0, Math.trunc(currentIteration)) : 0;
+    const agent = lastAgent || 'codex';
+
+    if (iteration >= this.maxIterations) {
+      // Defect fix (1): the Python's abort record carried only `action`, `reason` and
+      // `switchAgent`, while its retry record carried `iteration`, `failureClass`, `targetRole`,
+      // `agent` and `canRetry`. A caller written against either shape broke on the other, and the
+      // key it most needed — `canRetry` — was the one missing from the stop path. One shape now,
+      // with `canRetry: false` stating the bound explicitly.
+      return {
+        iteration,
+        failureClass,
+        action: 'ABORT',
+        targetRole: null,
+        agent,
+        canRetry: false,
+        reason: `Maximum retry iterations (${this.maxIterations}) exceeded.`,
+      };
+    }
+
+    const strategy = STRATEGY_MAP[failureClass] || GENERIC_STRATEGY;
+
+    // A terminal class stops the loop regardless of how much of the bound is left. Today that is
+    // BUDGET_EXCEEDED only: retrying is the one response guaranteed to make the failure worse.
+    if (strategy.terminal) {
+      return {
+        iteration,
+        failureClass,
+        action: strategy.action,
+        targetRole: strategy.targetRole,
+        agent,
+        canRetry: false,
+        reason: `Failure class '${failureClass}' is not retryable; a retry would repeat the condition that caused it.`,
+      };
+    }
+
+    const switchAgent =
+      strategy.switchAtIteration !== null && iteration >= strategy.switchAtIteration;
+
+    // Preserved verbatim: the swap is a two-way toggle between codex and claude, so any other
+    // agent name switches to codex.
+    const recommendedAgent = switchAgent ? (agent === 'codex' ? 'claude' : 'codex') : agent;
+
+    return {
+      iteration: iteration + 1,
+      failureClass,
+      action: strategy.action,
+      targetRole: strategy.targetRole,
+      agent: recommendedAgent,
+      canRetry: true,
+    };
+  }
+}
+
+/**
+ * Handles `doflow recover` — classify a verification failure and return the targeted action for
+ * that class (FR-010).
+ *
+ * Exit 0 means a bounded retry is available and the plan says what to change; exit 1 means the
+ * loop must stop — the retry budget is spent, or the class is one where retrying is guaranteed to
+ * reproduce the failure. That is the distinction a caller has to branch on, so it is the one the
+ * exit code carries.
+ *
+ * @param {Object} options
+ * @param {string} options.errorMessage
+ * @param {Array<string>} [options.failedChecks]
+ * @param {number} [options.iteration=0] retries already spent
+ * @param {string} [options.agent]
+ * @param {boolean} [options.json=false]
+ * @returns {number} exit code
+ */
+function handleRecoverCommand({ errorMessage, failedChecks = [], iteration = 0, agent, json = false }      = {})         {
+  // Handed nothing, the classifier answers UNKNOWN_FAILURE — a confident-looking verdict about a
+  // failure it never saw. Refuse instead.
+  if ((typeof errorMessage !== 'string' || errorMessage.trim() === '') && failedChecks.length === 0) {
+    return usageError('recover', '--error (and/or one or more --failed-check) is required — classifying a failure nobody described would name a class over no evidence.', json);
+  }
+  const manager = new RecoveryManager();
+  const failureClass = manager.classifyFailure(errorMessage, failedChecks);
+  const plan = manager.planRecovery(failureClass, iteration, agent || undefined);
+
+  if (json) console.log(JSON.stringify({ failureClass, failedChecks, ...(plan       ) }, null, 2));
+  else {
+    console.log(`\nDoFlow Recovery [${plan.failureClass}]:`);
+    console.log('═'.repeat(78));
+    console.log(`Action:     ${plan.action}`);
+    console.log(`Target:     ${plan.targetRole || 'unchanged'}`);
+    console.log(`Agent:      ${plan.agent}`);
+    console.log(`Retry:      ${plan.canRetry ? `yes — iteration ${plan.iteration}` : 'no'}`);
+    if (plan.reason) console.log(`Reason:     ${plan.reason}`);
+    console.log('═'.repeat(78) + '\n');
+  }
+  return finishRuntime(plan.canRetry ? 0 : 1);
+}
+
+module.exports = {
+  RecoveryManager,
+  FAILURE_CLASSES,
+  STRATEGY_MAP,
+  GENERIC_STRATEGY,
+  DEFAULT_MAX_ITERATIONS,
+  handleRecoverCommand,
+};

package/src/runtime/research-request.js

@@ -0,0 +1,231 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { acquireLock, updateTaskState, readTaskState } = require('./task-state.js');
+const { EvidenceLedger, assertSafeTaskId } = require('./evidence-ledger.js');
+const { ClaimsManager } = require('./claims.js');
+const { taskStoreDir } = require('./task-scope.js');
+const { FreshnessValidator } = require('./freshness.js');
+const { resolveLocator } = require('./locator-resolve.js');
+const { finishRuntime, usageError } = require('./cli-result.js');
+
+const STATES = new Set(['OPEN', 'ANSWERED', 'UNRESOLVED']);
+const REASONS = new Set(['detected-gap', 'user-request']);
+const safeId = (value     , label     ) => {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`${label} must be a safe non-empty identifier`);
+  }
+  return value;
+};
+
+function hasLocatedSource(item     , projectRoot     ) {
+  const locator = item.locator || {};
+  if (locator.uri !== undefined) {
+    if (typeof locator.uri !== 'string') return false;
+    try {
+      const url = new URL(locator.uri);
+      if (!['https:', 'http:'].includes(url.protocol) || !url.hostname || url.username || url.password) return false;
+    } catch { return false; }
+  }
+  return Boolean((locator.uri && typeof locator.uri === 'string')
+    || (locator.file && resolveLocator({ locator, repoRoot: projectRoot }).resolved));
+}
+
+class ResearchRequestStore {
+                           
+                      
+                    
+                        
+  constructor({ projectRoot = process.cwd(), fsImpl = fs, slug = null }      = {}) {
+    this.projectRoot = projectRoot;
+    this.fsImpl = fsImpl;
+    this.slug = slug;
+    this.stateDir = path.join(projectRoot, '.doflow', 'state', 'research');
+  }
+
+  /** The feature's namespace directory when the task has one (task-scope.js), else the flat store. */
+  file(taskId     ) {
+    const dir = taskStoreDir({ projectRoot: this.projectRoot, store: 'research', taskId: assertSafeTaskId(taskId), slug: this.slug });
+    return path.join(dir, `${taskId}.json`);
+  }
+
+  runFile(taskId     ) {
+    return path.join(this.projectRoot, '.doflow', 'state', 'orchestration', `${assertSafeTaskId(taskId)}.json`);
+  }
+
+  read(taskId     ) {
+    const data = readTaskState(this.fsImpl, this.file(taskId));
+    if (!data) return { taskId, revision: 0, requests: [] };
+    if (data.taskId !== taskId || !Array.isArray(data.requests)
+      || data.requests.some((r     ) => !STATES.has(r.status))) {
+      throw new Error(`Invalid research state for task '${taskId}'`);
+    }
+    return data;
+  }
+
+  // Re-read inside updateTaskState's lock: overlapping writers cannot lose a request.
+  change(taskId     , update     ) {
+    let result;
+    updateTaskState({ fsImpl: this.fsImpl, file: this.file(taskId), build: (disk     ) => {
+      if (disk && (disk.taskId !== taskId || !Array.isArray(disk.requests))) {
+        throw new Error(`Invalid research state for task '${taskId}'`);
+      }
+      const requests = disk?.requests || [];
+      result = update(requests);
+      return { taskId, requests };
+    } });
+    return result;
+  }
+
+  stageFor(taskId     , stageId     ) {
+    const run = readTaskState(this.fsImpl, this.runFile(taskId));
+    if (!run || run.taskClass !== 'feature' || run.state !== 'RUNNING') {
+      throw new Error(`Task '${taskId}' has no active feature stage`);
+    }
+    const current = run.program[run.cursor];
+    if (current?.type !== 'stage' || current.id !== stageId) {
+      throw new Error(`Current feature stage is '${current?.type === 'stage' ? current.id : 'none'}', not '${stageId}'`);
+    }
+  }
+
+  open({ taskId, stageId, question, reason, blocking }      = {}) {
+    safeId(taskId, 'taskId'); safeId(stageId, 'stageId');
+    if (typeof question !== 'string' || !question.trim()) throw new Error('question is required');
+    if (!REASONS.has(reason)) throw new Error(`reason must be one of: ${[...REASONS].join(', ')}`);
+    if (blocking !== undefined && typeof blocking !== 'boolean') throw new Error('blocking must be true or false');
+    // Lock order is run -> research for both open and completion. The stage check and request
+    // write must be indivisible with the orchestrator's final completion check.
+    const runFile = this.runFile(taskId);
+    if (!this.fsImpl.existsSync(runFile)) throw new Error(`Task '${taskId}' has no active feature stage`);
+    const release = acquireLock(this.fsImpl, runFile);
+    try {
+      this.stageFor(taskId, stageId);
+      return this.change(taskId, (requests     ) => {
+        const existing = requests.find((r     ) => r.stageId === stageId && r.question === question.trim() && r.status === 'OPEN');
+        if (existing) {
+          if ((blocking ?? reason === 'detected-gap') && !existing.blocking) {
+            existing.blocking = true;
+            existing.reason = reason;
+            existing.updatedAt = new Date().toISOString();
+          }
+          return existing;
+        }
+        const at = new Date().toISOString();
+        const record = { id: `req_${crypto.randomBytes(12).toString('hex')}`, taskId, stageId,
+          question: question.trim(), reason, blocking: blocking ?? reason === 'detected-gap',
+          status: 'OPEN', claimId: null, evidenceIds: [], gap: null, createdAt: at, updatedAt: at };
+        requests.push(record);
+        return record;
+      });
+    } finally { release(); }
+  }
+
+  list(taskId     ) {
+    safeId(taskId, 'taskId');
+    return this.read(taskId).requests;
+  }
+
+  // Validate references before taking the write lock; only the status transition itself mutates state.
+  resolve({ taskId, requestId, outcome, claimId, evidenceIds = [], gap }      = {}) {
+    safeId(taskId, 'taskId'); safeId(requestId, 'requestId');
+    if (!['answered', 'unresolved'].includes(outcome)) throw new Error('outcome must be answered or unresolved');
+    if (!Array.isArray(evidenceIds)) throw new Error('evidenceIds must be an array');
+    if (outcome === 'unresolved') {
+      if (!gap || !String(gap).trim()) throw new Error('unresolved requires a gap');
+      if (claimId) throw new Error('unresolved cannot carry a claim');
+    } else {
+      if (gap) throw new Error('answered cannot carry a gap');
+      if (!claimId || evidenceIds.length === 0) throw new Error('answered requires a claim and evidence IDs');
+      const ledger = new EvidenceLedger({ repoRoot: this.projectRoot, slug: this.slug });
+      ledger.load(taskId);
+      new FreshnessValidator({ repoRoot: this.projectRoot }).validateLedgerFreshness(ledger);
+      const claims = new ClaimsManager({ repoRoot: this.projectRoot, evidenceLedger: ledger, slug: this.slug });
+      claims.load(taskId); claims.evaluateAll();
+      const claim = claims.getClaim(claimId);
+      if (!claim || claim.taskId !== taskId || claim.status !== 'supported') {
+        throw new Error('answered requires a supported claim in the same task');
+      }
+      for (const id of evidenceIds) {
+        const item = ledger.getEvidence(id);
+        if (!item || item.taskId !== taskId || item.provenance !== 'extracted'
+          || item.status === 'superseded' || item.freshness?.status !== 'FRESH'
+          || !hasLocatedSource(item, this.projectRoot)
+          || !claim.supportingEvidence.includes(id)) {
+          throw new Error(`Evidence '${id}' is not fresh, located support for this claim and task`);
+        }
+      }
+    }
+    return this.change(taskId, (requests     ) => {
+      const request = requests.find((r     ) => r.id === requestId);
+      if (!request) throw new Error(`Unknown research request '${requestId}' for task '${taskId}'`);
+      if (request.status !== 'OPEN') throw new Error(`Request '${requestId}' is ${request.status}, not OPEN`);
+      Object.assign(request, { status: outcome === 'answered' ? 'ANSWERED' : 'UNRESOLVED',
+        claimId: claimId || null, evidenceIds: [...evidenceIds], gap: gap || null,
+        updatedAt: new Date().toISOString() });
+      return request;
+    });
+  }
+
+  blockingGap(taskId     , stageId     ) {
+    const requests = this.list(taskId).filter((r     ) => r.stageId === stageId && r.blocking);
+    for (const request of requests) {
+      if (request.status !== 'ANSWERED') return request;
+      try {
+        this.validateAnswer(taskId, request);
+      } catch (error     ) {
+        return { ...request, failureReason: error.message };
+      }
+    }
+    return null;
+  }
+
+  validateAnswer(taskId     , request     ) {
+    const ledger = new EvidenceLedger({ repoRoot: this.projectRoot, slug: this.slug });
+    ledger.load(taskId);
+    new FreshnessValidator({ repoRoot: this.projectRoot }).validateLedgerFreshness(ledger);
+    const claims = new ClaimsManager({ repoRoot: this.projectRoot, evidenceLedger: ledger, slug: this.slug });
+    claims.load(taskId); claims.evaluateAll();
+    const claim = claims.getClaim(request.claimId);
+    if (!claim || claim.taskId !== taskId) {
+      throw new Error(`Research claim '${request.claimId}' is missing from this task`);
+    }
+    if (claim.status !== 'supported') {
+      throw new Error(`Research claim '${request.claimId}' is ${claim.status}, not supported`);
+    }
+    if (!request.evidenceIds?.length) throw new Error('Research answer has no linked evidence');
+    for (const id of request.evidenceIds) {
+      const item = ledger.getEvidence(id);
+      if (!item || item.taskId !== taskId || item.provenance !== 'extracted'
+        || item.status === 'superseded' || item.freshness?.status !== 'FRESH'
+        || !hasLocatedSource(item, this.projectRoot)
+        || !claim.supportingEvidence.includes(id)) {
+        throw new Error(`Research evidence '${id}' is no longer fresh, located support`);
+      }
+    }
+  }
+}
+
+function handleResearchRequestCommand({ action = 'list', taskId, stageId, question, reason,
+  blocking, requestId, outcome, claimId, evidenceIds, gap, json = false, projectRoot, slug }      = {}) {
+  try {
+    const store = new ResearchRequestStore({ projectRoot, slug });
+    let result;
+    switch (action) {
+      case 'open': result = store.open({ taskId, stageId, question, reason, blocking }); break;
+      case 'list': result = { taskId, requests: store.list(taskId) }; break;
+      case 'resolve': result = store.resolve({ taskId, requestId, outcome, claimId, evidenceIds, gap }); break;
+      default: return usageError('research-request', `unknown action '${action}'; valid: open, list, resolve`, json);
+    }
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(JSON.stringify(result));
+    return finishRuntime(0);
+  } catch (error     ) {
+    return usageError('research-request', error.message, json, error);
+  }
+}
+
+module.exports = { ResearchRequestStore, handleResearchRequestCommand };