@khoavu882/doflow 2.0.0-beta.3 → 2.0.0-beta.5

package/src/runtime/{readiness.ts → readiness.js}

@@ -4,9 +4,10 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { parseYamlFile } = require('./capability-router.ts');
-const { resolveLocator, describeResolution } = require('./locator-resolve.ts');
-const { REPO_ROOT } = require('../helper/repo-root.ts');
+const { parseYamlFile } = require('./capability-router.js');
+const { resolveLocator, describeResolution } = require('./locator-resolve.js');
+const { readPlan, bindEvidence, declaredIntentList } = require('./retrieval-record.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
 
 const READINESS_STATES = new Set([
   'READY',
@@ -37,7 +38,7 @@ const STAGE_ENTRY_DECISIONS = new Set(['ENTER', 'GATHER_FIRST', 'ASK_USER', 'STO
  * @param {string} [mode='workflow'] 'workflow' | 'standalone'
  * @returns {{decision: string, reason: string}}
  */
-function stageEntryFor(state: any, mode = 'workflow') {
+function stageEntryFor(state     , mode = 'workflow') {
   if (!EXECUTION_MODES.has(mode)) {
     throw new Error(`Unknown execution mode '${mode}'. Valid: ${[...EXECUTION_MODES].join(', ')} — the standalone exemption is declared, never inferred.`);
   }
@@ -60,11 +61,11 @@ function stageEntryFor(state: any, mode = 'workflow') {
 }
 
 class ReadinessEngine {
-  declare fsImpl: any;
-  declare repoRoot: any;
-  declare projectRoot: any;
-  declare templatePath: any;
-  declare templates: any;
+                      
+                        
+                           
+                            
+                         
   /**
    * @param {Object} [options]
    * @param {string} [options.repoRoot] the DoFlow install, where readiness-templates.json lives
@@ -75,7 +76,7 @@ class ReadinessEngine {
    * @param {Object} [options.templates]
    * @param {Object} [options.fsImpl]
    */
-  constructor(options: any = {}) {
+  constructor(options      = {}) {
     this.fsImpl = options.fsImpl || fs;
     this.repoRoot = options.repoRoot || REPO_ROOT;
     this.projectRoot = options.projectRoot || process.cwd();
@@ -92,7 +93,7 @@ class ReadinessEngine {
     try {
       const data = parseYamlFile(this.templatePath, this.fsImpl);
       this.templates = data.templates || {};
-    } catch (error: any) {
+    } catch (error     ) {
       throw new Error(`Failed to load readiness templates from '${this.templatePath}': ${error.message}`);
     }
   }
@@ -104,7 +105,7 @@ class ReadinessEngine {
    * @param {Object} taskProfile
    * @returns {Object}
    */
-  suggestAction(reqId: any, reqDef: any, taskProfile: any) {
+  suggestAction(reqId     , reqDef     , taskProfile     ) {
     if (reqId === 'root_cause') {
       return {
         intent: 'trace-dependency',
@@ -152,7 +153,7 @@ class ReadinessEngine {
    * @param {Object} claimsManager
    * @returns {Object} ReadinessReport
    */
-  evaluateReadiness(taskProfile: any, evidenceLedger: any, claimsManager: any) {
+  evaluateReadiness(taskProfile     , evidenceLedger     , claimsManager     ) {
     if (!taskProfile || typeof taskProfile !== 'object') {
       throw new Error('taskProfile must be an object');
     }
@@ -206,12 +207,25 @@ class ReadinessEngine {
 
     // Inspect claims
     const taskClaims = claimsManager ? claimsManager.getClaims(taskId) : [];
-    const conflictedClaims = taskClaims.filter((c: any) => c.status === 'conflicted');
+    const conflictedClaims = taskClaims.filter((c     ) => c.status === 'conflicted');
     if (conflictedClaims.length > 0) {
       hasBlocked = true;
     }
 
-    const taskEvidence = evidenceLedger ? evidenceLedger.queryEvidence({ taskId, status: 'FRESH' }) : [];
+    const allTaskEvidence = evidenceLedger ? evidenceLedger.queryEvidence({ taskId }) : [];
+    let plan = null;
+    let unreadablePlan = null;
+    try {
+      plan = readPlan(this.projectRoot, taskId);
+    } catch (error     ) {
+      if (error.code !== 'store-unreadable') throw error;
+      unreadablePlan = { unreadable: true, reason: error.message };
+    }
+    const queryBound = Boolean(plan?.planId);
+    const binding = queryBound ? bindEvidence(plan, allTaskEvidence) : null;
+    const unboundIds = new Set(binding ? binding.unbound.map((item     ) => item.id) : []);
+    const taskEvidence = allTaskEvidence.filter((item     ) => item.freshness?.status === 'FRESH'
+      && (!queryBound || !unboundIds.has(item.id)));
 
     // An item accepted before FR-004 existed, or one whose target file has since shrunk, can be
     // FRESH and still point at nothing. *Stale* (the file changed at all) and *unresolvable* (the
@@ -225,8 +239,9 @@ class ReadinessEngine {
     // in evaluateClaim — it is not a claim that the file never changed. An item that genuinely went
     // stale and was never superseded still forces NEEDS_EVIDENCE exactly as before.
     const staleEvidence = (evidenceLedger ? evidenceLedger.getAllEvidence() : [])
-      .filter((item: any) => item.taskId === taskId && item.freshness?.status === 'STALE' && item.status !== 'superseded')
-      .map((item: any) => ({ evidenceId: item.id, locator: item.locator, reason: 'file-modified-since-recorded' }));
+      .filter((item     ) => item.taskId === taskId && item.result !== 'EMPTY'
+        && item.freshness?.status === 'STALE' && item.status !== 'superseded')
+      .map((item     ) => ({ evidenceId: item.id, locator: item.locator, reason: 'file-modified-since-recorded' }));
 
     const unresolvableEvidence = [];
     for (const item of taskEvidence) {
@@ -242,9 +257,30 @@ class ReadinessEngine {
       }
     }
 
-    for (const [reqId, reqDef] of Object.entries<any>(requirements)) {
+    const staleAbsence = [];
+    const staleAbsenceByRequirement = new Map               ();
+    for (const item of allTaskEvidence) {
+      if (item.result !== 'EMPTY' || item.status !== 'active'
+          || !['STALE', 'UNKNOWN'].includes(item.freshness?.status)
+          || (queryBound && unboundIds.has(item.id))) continue;
+      for (const requirement of Array.isArray(item.establishes) ? item.establishes : []) {
+        const entry = { evidenceId: item.id, requirement, provider: item.source?.provider || null,
+          freshness: item.freshness.status, refresh: plan?.providers?.[item.source?.provider]?.refresh || null };
+        staleAbsence.push(entry);
+        const entries = staleAbsenceByRequirement.get(requirement) || [];
+        entries.push({ item, entry });
+        staleAbsenceByRequirement.set(requirement, entries);
+      }
+    }
+
+    const unboundEvidence = queryBound
+      ? { count: binding.unbound.length, ids: binding.unbound.slice(0, 5).map((item     ) => item.id) }
+      : undefined;
+
+    for (const [reqId, reqDef] of Object.entries     (requirements)) {
       let isSatisfied = false;
       let reason = null;
+      let reasonCode = null;
       let matchedEvidenceIds = [];
 
       // Check verification plan requirement
@@ -260,9 +296,9 @@ class ReadinessEngine {
       // not by any supported claim the task happens to hold (review R1 — a supported claim about an
       // unrelated invariant satisfied the bug template's root-cause requirement).
       else if (reqDef.requiresClaimStatus) {
-        let matchingClaims = taskClaims.filter((c: any) => c.status === reqDef.requiresClaimStatus);
+        let matchingClaims = taskClaims.filter((c     ) => c.status === reqDef.requiresClaimStatus);
         if (reqDef.requiresClaimRole) {
-          const withRole = matchingClaims.filter((c: any) => c.role === reqDef.requiresClaimRole);
+          const withRole = matchingClaims.filter((c     ) => c.role === reqDef.requiresClaimRole);
           if (withRole.length === 0 && matchingClaims.length > 0) {
             reason = `${matchingClaims.length} claim(s) have status '${reqDef.requiresClaimStatus}' but none `
               + `declares role '${reqDef.requiresClaimRole}' — add the claim with --role ${reqDef.requiresClaimRole}, `
@@ -272,7 +308,7 @@ class ReadinessEngine {
         }
         if (matchingClaims.length > 0) {
           isSatisfied = true;
-          matchedEvidenceIds = matchingClaims.flatMap((c: any) => c.supportingEvidence);
+          matchedEvidenceIds = matchingClaims.flatMap((c     ) => c.supportingEvidence);
         } else if (!reason) {
           reason = `Requires at least one claim with status '${reqDef.requiresClaimStatus}'`
             + `${reqDef.requiresClaimRole ? ` and role '${reqDef.requiresClaimRole}'` : ''}.`;
@@ -286,21 +322,21 @@ class ReadinessEngine {
       // (review R1, P1 — reproduced through the public CLI).
       else if (Array.isArray(reqDef.evidenceKinds) && reqDef.evidenceKinds.length > 0) {
         const allowedKinds = new Set(reqDef.evidenceKinds);
-        const kindMatched = taskEvidence.filter((ev: any) => allowedKinds.has(ev.kind));
-        const extracted = kindMatched.filter((ev: any) => ev.provenance === 'extracted');
-        const bound = extracted.filter((ev: any) => Array.isArray(ev.establishes) && ev.establishes.includes(reqId));
-        let qualifying = bound;
-        if (reqDef.requiresObservation) {
-          qualifying = qualifying.filter((ev: any) => ev.observation && Number.isInteger(ev.observation.exitCode));
-          if (reqDef.expectedExit === 'zero') {
-            qualifying = qualifying.filter((ev: any) => ev.observation.exitCode === 0);
-          } else if (reqDef.expectedExit === 'nonzero') {
-            qualifying = qualifying.filter((ev: any) => ev.observation.exitCode !== 0);
-          }
-        }
+        const rawKindMatched = allTaskEvidence.filter((ev     ) => allowedKinds.has(ev.kind));
+        const kindMatched = taskEvidence.filter((ev     ) => allowedKinds.has(ev.kind));
+        const extracted = kindMatched.filter((ev     ) => ev.provenance === 'extracted');
+        const bound = extracted.filter((ev     ) => Array.isArray(ev.establishes) && ev.establishes.includes(reqId));
+        const observationOk = (ev     ) => !reqDef.requiresObservation || (ev.observation
+          && Number.isInteger(ev.observation.exitCode)
+          && (reqDef.expectedExit !== 'zero' || ev.observation.exitCode === 0)
+          && (reqDef.expectedExit !== 'nonzero' || ev.observation.exitCode !== 0));
+        const qualifies = (ev     ) => ev.provenance === 'extracted'
+          && Array.isArray(ev.establishes) && ev.establishes.includes(reqId)
+          && observationOk(ev);
+        const qualifying = taskEvidence.filter((ev     ) => allowedKinds.has(ev.kind) && qualifies(ev));
         if (qualifying.length > 0) {
           isSatisfied = true;
-          matchedEvidenceIds = qualifying.map((ev: any) => ev.id);
+          matchedEvidenceIds = qualifying.map((ev     ) => ev.id);
         } else if (kindMatched.length === 0) {
           reason = `Missing fresh evidence of kind: ${reqDef.evidenceKinds.join(', ')}.`;
         } else if (extracted.length === 0) {
@@ -310,8 +346,8 @@ class ReadinessEngine {
           reason = `${extracted.length} extracted item(s) of the right kind exist but none declares it `
             + `establishes '${reqId}' — record evidence with establishes: ['${reqId}'] so the gate grades `
             + 'what the item was actually gathered to prove.';
-        } else if (reqDef.expectedExit === 'zero' && bound.some((ev: any) => ev.observation && ev.observation.exitCode !== 0)) {
-          const failed = bound.find((ev: any) => ev.observation && ev.observation.exitCode !== 0);
+        } else if (reqDef.expectedExit === 'zero' && bound.some((ev     ) => ev.observation && ev.observation.exitCode !== 0)) {
+          const failed = bound.find((ev     ) => ev.observation && ev.observation.exitCode !== 0);
           reason = `The bound observation ran '${failed.observation.command}' and exited ${failed.observation.exitCode}; `
             + 'this requirement needs an exit status of 0. A failed run does not establish a passing baseline.';
         } else {
@@ -319,6 +355,32 @@ class ReadinessEngine {
             + `${reqDef.expectedExit ? ` with a${reqDef.expectedExit === 'zero' ? ' passing (0)' : ' non-zero'} exit status` : ''} — `
             + 'record the execution itself, not a description of one.';
         }
+        if (!isSatisfied && reqDef.required) {
+          const staleAbsences = staleAbsenceByRequirement.get(reqId) || [];
+          if (staleAbsences.length > 0) {
+            const { item, entry } = staleAbsences[0];
+            const refresh = entry.refresh || 'none declared';
+            reasonCode = 'stale-absence-unverified';
+            const prefix = `'${reqId}' rests only on an empty answer from ${entry.provider || 'unknown provider'}, whose index was ${entry.freshness} when it was recorded (${item.id}). An empty answer from that index cannot establish absence. `;
+            if (item.freshness?.staleReason === 'tree-changed-since-recorded'
+                || item.freshness?.staleReason === 'tree-unverifiable') {
+              reason = `${prefix}the working tree changed since it was recorded; re-run the lookup and record the absence again.`;
+            } else if (item.freshness?.gitCommit === null) {
+              reason = `${prefix}absence cannot be established outside a git work tree; record a positive item.`;
+            } else {
+              reason = `${prefix}Run the declared refresh command (${refresh}) and record the absence again, or re-run the lookup with a live provider such as native.rg: doflow evidence --task-id ${taskId} --action add --absence --need <intent> --provider native.rg ...`;
+            }
+          } else if (queryBound) {
+            const unboundKind = rawKindMatched.filter((ev     ) => unboundIds.has(ev.id));
+            const unboundQualifying = unboundKind.filter((ev     ) =>
+              ev.freshness?.status === 'FRESH' && qualifies(ev));
+            if (unboundQualifying.length > 0) {
+              const ids = unboundQualifying.slice(0, 5).map((item     ) => item.id).join(', ');
+              reasonCode = 'unbound-retrieval-evidence';
+              reason = `${unboundQualifying.length} item(s) of the right kind are not bound to a declared need of plan ${plan.planId} (${ids}), so they do not count. Re-record them with --need <intent>; declared: ${declaredIntentList(plan)}.`;
+            }
+          }
+        }
       }
       // Scope verified / scope clear
       else if (reqId === 'scope_clear' || reqId === 'scope_verified' || reqId === 'invariants_captured') {
@@ -347,6 +409,7 @@ class ReadinessEngine {
         required: Boolean(reqDef.required),
         satisfied: isSatisfied,
         reason,
+        reasonCode,
         evidenceIds: matchedEvidenceIds,
         recommendedAction: isSatisfied ? null : this.suggestAction(reqId, reqDef, taskProfile),
       });
@@ -383,6 +446,10 @@ class ReadinessEngine {
         + 'Re-record them against the tree as it stands.';
     }
 
+    if (unreadablePlan) {
+      summary += ` Warning: retrieval plan is unreadable and was treated as absent: ${unreadablePlan.reason}`;
+    }
+
     return {
       taskId,
       taskClass,
@@ -392,13 +459,16 @@ class ReadinessEngine {
       requirements: requirementResults,
       claimsSummary: {
         total: taskClaims.length,
-        supported: taskClaims.filter((c: any) => c.status === 'supported').length,
-        hypotheses: taskClaims.filter((c: any) => c.status === 'hypothesis').length,
+        supported: taskClaims.filter((c     ) => c.status === 'supported').length,
+        hypotheses: taskClaims.filter((c     ) => c.status === 'hypothesis').length,
         conflicts: conflictedClaims.length,
       },
       evidenceCount: taskEvidence.length,
       unresolvableEvidence,
       staleEvidence,
+      staleAbsence,
+      ...(unreadablePlan ? { retrievalPlan: unreadablePlan } : {}),
+      ...(unboundEvidence ? { unboundEvidence } : {}),
     };
   }
 }
@@ -406,18 +476,18 @@ class ReadinessEngine {
 /** One live snapshot for readiness inspection and orchestration transitions. Reads never persist
  * derived freshness or claim status; every invocation evaluates the current project again.
  * `mode` defaults to 'workflow' — fail closed: the standalone exemption must be declared. */
-function evaluateTaskReadiness({ taskProfile, repoRoot = REPO_ROOT, projectRoot = process.cwd(), mode = 'workflow' }: any) {
+function evaluateTaskReadiness({ taskProfile, repoRoot = REPO_ROOT, projectRoot = process.cwd(), treeRoot = projectRoot, mode = 'workflow' }     ) {
   // Validated before any ledger work, not just inside stageEntryFor at the end — an invalid mode
   // used to pay a full freshness/claims evaluation before erroring (review suggestion, 026).
   if (!EXECUTION_MODES.has(mode)) {
     throw new Error(`Unknown execution mode '${mode}'. Valid: ${[...EXECUTION_MODES].join(', ')} — the standalone exemption is declared, never inferred.`);
   }
-  const { EvidenceLedger } = require('./evidence-ledger.ts');
-  const { ClaimsManager } = require('./claims.ts');
-  const { FreshnessValidator } = require('./freshness.ts');
+  const { EvidenceLedger } = require('./evidence-ledger.js');
+  const { ClaimsManager } = require('./claims.js');
+  const { FreshnessValidator } = require('./freshness.js');
   const ledger = new EvidenceLedger({ repoRoot: projectRoot });
   ledger.load(taskProfile.taskId);
-  new FreshnessValidator({ repoRoot: projectRoot }).validateLedgerFreshness(ledger);
+  new FreshnessValidator({ repoRoot: projectRoot, treeRoot }).validateLedgerFreshness(ledger);
   const claims = new ClaimsManager({ evidenceLedger: ledger, repoRoot: projectRoot });
   claims.load(taskProfile.taskId);
   claims.evaluateAll();

package/src/runtime/{recovery.ts → recovery.js}

@@ -20,10 +20,10 @@
  *      names either raised or silently iterated characters.
  */
 
-const { finishRuntime, usageError } = require('./cli-result.ts');
+const { finishRuntime, usageError } = require('./cli-result.js');
 
 /** The eleven classes, in the order the Python declared them. */
-const FAILURE_CLASSES: readonly string[] = Object.freeze([
+const FAILURE_CLASSES                    = Object.freeze([
   'CONTEXT_MISSING',
   'WRONG_IMPLEMENTATION',
   'TEST_FAILURE',
@@ -40,9 +40,9 @@ const FAILURE_CLASSES: readonly string[] = Object.freeze([
 const DEFAULT_MAX_ITERATIONS = 3;
 
 /** Check-name fragments that identify a build-stage failure regardless of the error text. */
-const BUILD_CHECK_MARKERS: readonly string[] = Object.freeze(['syntax', 'compile', 'build']);
+const BUILD_CHECK_MARKERS                    = Object.freeze(['syntax', 'compile', 'build']);
 /** Check-name fragments that identify a test-stage failure. */
-const TEST_CHECK_MARKERS: readonly string[] = Object.freeze(['test', 'unit']);
+const TEST_CHECK_MARKERS                    = Object.freeze(['test', 'unit']);
 
 /**
  * Per-class recovery strategy — **one entry per class, all eleven** (plan task C.2).
@@ -68,7 +68,7 @@ const TEST_CHECK_MARKERS: readonly string[] = Object.freeze(['test', 'unit']);
  * already been spent (its `current_iteration >= 2`). `terminal` is new and means the class is not
  * retryable at any iteration.
  */
-const STRATEGY_MAP: Readonly<Record<string, any>> = Object.freeze({
+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 },
@@ -86,7 +86,7 @@ const STRATEGY_MAP: Readonly<Record<string, any>> = Object.freeze({
 });
 
 /** Reachable only for a class string outside the eleven — see the note on STRATEGY_MAP. */
-const GENERIC_STRATEGY: Readonly<Record<string, any>> = Object.freeze({
+const GENERIC_STRATEGY                                = Object.freeze({
   action: 'GENERIC_DEBUGGER_FIX',
   targetRole: 'DEBUGGER',
   switchAtIteration: 2,
@@ -96,23 +96,23 @@ const GENERIC_STRATEGY: Readonly<Record<string, any>> = Object.freeze({
  * @param {*} value
  * @returns {Array<string>} only the string members, lowercased
  */
-function normalizeCheckNames(value: any): string[] {
+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: any) => typeof v === 'string').map((v: string) => v.toLowerCase());
+  return value.filter((v     ) => typeof v === 'string').map((v        ) => v.toLowerCase());
 }
 
 class RecoveryManager {
-  maxIterations: number;
+  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: any = {}) {
+  constructor(options      = {}) {
     const opts = typeof options === 'number' ? { maxIterations: options } : options;
     this.maxIterations = opts.maxIterations || DEFAULT_MAX_ITERATIONS;
   }
@@ -126,13 +126,13 @@ class RecoveryManager {
    * @param {Array<string>} [failedChecks=[]]
    * @returns {string} one of FAILURE_CLASSES
    */
-  classifyFailure(errorMessage: any, failedChecks: any = []): string {
+  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: readonly string[]) => checks.some((chk) => markers.some((m) => chk.includes(m)));
+    const anyCheck = (markers                   ) => checks.some((chk) => markers.some((m) => chk.includes(m)));
 
     if (anyCheck(BUILD_CHECK_MARKERS) || msg.includes('build error')) {
       return 'BUILD_FAILURE';
@@ -174,7 +174,7 @@ class RecoveryManager {
    * @param {string} [lastAgent='codex']
    * @returns {{ iteration: number, failureClass: string, action: string, targetRole: string|null, agent: string, canRetry: boolean, reason?: string }}
    */
-  planRecovery(failureClass: string, currentIteration: number, lastAgent: string = 'codex'): { 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;
@@ -248,7 +248,7 @@ class RecoveryManager {
  * @param {boolean} [options.json=false]
  * @returns {number} exit code
  */
-function handleRecoverCommand({ errorMessage, failedChecks = [], iteration = 0, agent, json = false }: any = {}): number {
+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) {
@@ -258,7 +258,7 @@ function handleRecoverCommand({ errorMessage, failedChecks = [], iteration = 0,
   const failureClass = manager.classifyFailure(errorMessage, failedChecks);
   const plan = manager.planRecovery(failureClass, iteration, agent || undefined);
 
-  if (json) console.log(JSON.stringify({ failureClass, failedChecks, ...(plan as any) }, null, 2));
+  if (json) console.log(JSON.stringify({ failureClass, failedChecks, ...(plan       ) }, null, 2));
   else {
     console.log(`\nDoFlow Recovery [${plan.failureClass}]:`);
     console.log('═'.repeat(78));

package/src/runtime/{research-request.ts → research-request.js}

@@ -5,24 +5,24 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { acquireLock, updateTaskState, readTaskState } = require('./task-state.ts');
-const { EvidenceLedger, assertSafeTaskId } = require('./evidence-ledger.ts');
-const { ClaimsManager } = require('./claims.ts');
-const { taskStoreDir } = require('./task-scope.ts');
-const { FreshnessValidator } = require('./freshness.ts');
-const { resolveLocator } = require('./locator-resolve.ts');
-const { finishRuntime, usageError } = require('./cli-result.ts');
+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: any, label: any) => {
+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: any, projectRoot: any) {
+function hasLocatedSource(item     , projectRoot     ) {
   const locator = item.locator || {};
   if (locator.uri !== undefined) {
     if (typeof locator.uri !== 'string') return false;
@@ -36,11 +36,11 @@ function hasLocatedSource(item: any, projectRoot: any) {
 }
 
 class ResearchRequestStore {
-  declare projectRoot: any;
-  declare fsImpl: any;
-  declare slug: any;
-  declare stateDir: any;
-  constructor({ projectRoot = process.cwd(), fsImpl = fs, slug = null }: any = {}) {
+                           
+                      
+                    
+                        
+  constructor({ projectRoot = process.cwd(), fsImpl = fs, slug = null }      = {}) {
     this.projectRoot = projectRoot;
     this.fsImpl = fsImpl;
     this.slug = slug;
@@ -48,29 +48,29 @@ class ResearchRequestStore {
   }
 
   /** The feature's namespace directory when the task has one (task-scope.js), else the flat store. */
-  file(taskId: any) {
+  file(taskId     ) {
     const dir = taskStoreDir({ projectRoot: this.projectRoot, store: 'research', taskId: assertSafeTaskId(taskId), slug: this.slug });
     return path.join(dir, `${taskId}.json`);
   }
 
-  runFile(taskId: any) {
+  runFile(taskId     ) {
     return path.join(this.projectRoot, '.doflow', 'state', 'orchestration', `${assertSafeTaskId(taskId)}.json`);
   }
 
-  read(taskId: any) {
+  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: any) => !STATES.has(r.status))) {
+      || 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: any, update: any) {
+  change(taskId     , update     ) {
     let result;
-    updateTaskState({ fsImpl: this.fsImpl, file: this.file(taskId), build: (disk: any) => {
+    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}'`);
       }
@@ -81,7 +81,7 @@ class ResearchRequestStore {
     return result;
   }
 
-  stageFor(taskId: any, stageId: any) {
+  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`);
@@ -92,7 +92,7 @@ class ResearchRequestStore {
     }
   }
 
-  open({ taskId, stageId, question, reason, blocking }: any = {}) {
+  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(', ')}`);
@@ -104,8 +104,8 @@ class ResearchRequestStore {
     const release = acquireLock(this.fsImpl, runFile);
     try {
       this.stageFor(taskId, stageId);
-      return this.change(taskId, (requests: any) => {
-        const existing = requests.find((r: any) => r.stageId === stageId && r.question === question.trim() && r.status === 'OPEN');
+      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;
@@ -124,13 +124,13 @@ class ResearchRequestStore {
     } finally { release(); }
   }
 
-  list(taskId: any) {
+  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 }: any = {}) {
+  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');
@@ -159,8 +159,8 @@ class ResearchRequestStore {
         }
       }
     }
-    return this.change(taskId, (requests: any) => {
-      const request = requests.find((r: any) => r.id === requestId);
+    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',
@@ -170,20 +170,20 @@ class ResearchRequestStore {
     });
   }
 
-  blockingGap(taskId: any, stageId: any) {
-    const requests = this.list(taskId).filter((r: any) => r.stageId === stageId && r.blocking);
+  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: any) {
+      } catch (error     ) {
         return { ...request, failureReason: error.message };
       }
     }
     return null;
   }
 
-  validateAnswer(taskId: any, request: any) {
+  validateAnswer(taskId     , request     ) {
     const ledger = new EvidenceLedger({ repoRoot: this.projectRoot, slug: this.slug });
     ledger.load(taskId);
     new FreshnessValidator({ repoRoot: this.projectRoot }).validateLedgerFreshness(ledger);
@@ -210,7 +210,7 @@ class ResearchRequestStore {
 }
 
 function handleResearchRequestCommand({ action = 'list', taskId, stageId, question, reason,
-  blocking, requestId, outcome, claimId, evidenceIds, gap, json = false, projectRoot, slug }: any = {}) {
+  blocking, requestId, outcome, claimId, evidenceIds, gap, json = false, projectRoot, slug }      = {}) {
   try {
     const store = new ResearchRequestStore({ projectRoot, slug });
     let result;
@@ -223,7 +223,7 @@ function handleResearchRequestCommand({ action = 'list', taskId, stageId, questi
     if (json) console.log(JSON.stringify(result, null, 2));
     else console.log(JSON.stringify(result));
     return finishRuntime(0);
-  } catch (error: any) {
+  } catch (error     ) {
     return usageError('research-request', error.message, json, error);
   }
 }