@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/readiness.js

@@ -6,6 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { parseYamlFile } = require('./capability-router.js');
 const { resolveLocator, describeResolution } = require('./locator-resolve.js');
+const { readPlan, bindEvidence, declaredIntentList } = require('./retrieval-record.js');
+const { fileRootFor } = require('./freshness.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 
 const READINESS_STATES = new Set([
@@ -63,6 +65,7 @@ class ReadinessEngine {
                       
                         
                            
+                          
                             
                          
   /**
@@ -71,6 +74,8 @@ class ReadinessEngine {
    * @param {string} [options.projectRoot] the repository under work, which evidence locators name.
    *   Distinct from repoRoot on purpose: when the CLI runs inside another project, the templates
    *   come from the install and the locators must be resolved against that project, not the install.
+   * @param {string} [options.sourceRoot] the checkout the verb runs in, where a relative locator's file
+   *   is read (IC-007, `fileRootFor`); differs from projectRoot in a linked worktree. Defaults to projectRoot.
    * @param {string} [options.templatePath]
    * @param {Object} [options.templates]
    * @param {Object} [options.fsImpl]
@@ -79,6 +84,7 @@ class ReadinessEngine {
     this.fsImpl = options.fsImpl || fs;
     this.repoRoot = options.repoRoot || REPO_ROOT;
     this.projectRoot = options.projectRoot || process.cwd();
+    this.sourceRoot = options.sourceRoot || this.projectRoot;
     this.templatePath = options.templatePath || path.join(this.repoRoot, 'core', 'registry', 'readiness-templates.json');
 
     if (options.templates) {
@@ -133,6 +139,22 @@ class ReadinessEngine {
         action: 'Execute automated tests or record runtime observation reproducing the behavior.',
       };
     }
+    // These are satisfied by what the caller states, not by retrieved evidence (evaluateReadiness),
+    // so the action names the flag that states it (--scope / --invariants, cli/index.ts).
+    if (reqId === 'scope_clear' || reqId === 'scope_verified') {
+      return {
+        intent: 'locate-concept',
+        capability: 'code.semantic-search',
+        action: `State the scope boundary for requirement '${reqId}' (${reqDef.description}): pass --scope "<boundary>" when evaluating readiness.`,
+      };
+    }
+    if (reqId === 'invariants_captured') {
+      return {
+        intent: 'locate-concept',
+        capability: 'code.semantic-search',
+        action: `State the invariants the change must preserve for requirement '${reqId}' (${reqDef.description}): pass --invariants "<invariants>" when evaluating readiness.`,
+      };
+    }
     return {
       intent: 'locate-concept',
       capability: 'code.semantic-search',
@@ -211,7 +233,23 @@ class ReadinessEngine {
       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) : []);
+    // A superseded item is retired: it neither satisfies a requirement nor can it be unresolvable
+    // (the stale check below already skips it), so nothing else can be left that clears it.
+    const taskEvidence = allTaskEvidence.filter((item     ) => item.freshness?.status === 'FRESH'
+      && item.status !== 'superseded'
+      && (!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,13 +263,14 @@ 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     ) => item.taskId === taskId && item.freshness?.status === 'STALE' && item.status !== 'superseded')
+      .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) {
       if (item.provenance !== 'extracted' || !item.locator || !item.locator.file) continue;
-      const resolution = resolveLocator({ locator: item.locator, repoRoot: this.projectRoot });
+      const resolution = resolveLocator({ locator: item.locator, repoRoot: fileRootFor(this.sourceRoot, this.projectRoot, item.locator) });
       if (!resolution.resolved) {
         unresolvableEvidence.push({
           evidenceId: item.id,
@@ -242,9 +281,30 @@ class ReadinessEngine {
       }
     }
 
+    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,7 +320,18 @@ 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     ) => c.status === reqDef.requiresClaimStatus);
+        // A `supported` claim counts only while at least one of its supporting items is live
+        // (active, FRESH, bound) in `taskEvidence`: support that was superseded, went stale or is
+        // unbound no longer backs it (107-B review C-1). Other statuses are not evidence-backed.
+        const liveEvidenceIds = new Set(taskEvidence.map((item     ) => item.id));
+        const statusMatched = taskClaims.filter((c     ) => c.status === reqDef.requiresClaimStatus);
+        const hasLiveSupport = (c     ) => reqDef.requiresClaimStatus !== 'supported'
+          || (c.supportingEvidence || []).some((id        ) => liveEvidenceIds.has(id));
+        // A claim whose stored status still reads `supported` but whose support was retired is
+        // named as such, so the user is not told to add a supported claim they can already see.
+        const retired = statusMatched.filter((c     ) => !hasLiveSupport(c)
+          && (!reqDef.requiresClaimRole || c.role === reqDef.requiresClaimRole));
+        let matchingClaims = statusMatched.filter(hasLiveSupport);
         if (reqDef.requiresClaimRole) {
           const withRole = matchingClaims.filter((c     ) => c.role === reqDef.requiresClaimRole);
           if (withRole.length === 0 && matchingClaims.length > 0) {
@@ -273,6 +344,12 @@ class ReadinessEngine {
         if (matchingClaims.length > 0) {
           isSatisfied = true;
           matchedEvidenceIds = matchingClaims.flatMap((c     ) => c.supportingEvidence);
+        } else if (!reason && retired.length > 0) {
+          reasonCode = 'claim-support-retired';
+          reason = `${retired.length} claim(s) with status '${reqDef.requiresClaimStatus}'`
+            + `${reqDef.requiresClaimRole ? ` and role '${reqDef.requiresClaimRole}'` : ''} have no live supporting `
+            + `evidence (${retired.slice(0, 5).map((c     ) => c.id).join(', ')}): each supporting item was superseded, `
+            + 'went stale or is not bound to the task plan. Link a fresh item with `claim --action link` and re-evaluate.';
         } else if (!reason) {
           reason = `Requires at least one claim with status '${reqDef.requiresClaimStatus}'`
             + `${reqDef.requiresClaimRole ? ` and role '${reqDef.requiresClaimRole}'` : ''}.`;
@@ -286,18 +363,18 @@ 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 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));
-        let qualifying = bound;
-        if (reqDef.requiresObservation) {
-          qualifying = qualifying.filter((ev     ) => ev.observation && Number.isInteger(ev.observation.exitCode));
-          if (reqDef.expectedExit === 'zero') {
-            qualifying = qualifying.filter((ev     ) => ev.observation.exitCode === 0);
-          } else if (reqDef.expectedExit === 'nonzero') {
-            qualifying = qualifying.filter((ev     ) => ev.observation.exitCode !== 0);
-          }
-        }
+        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     ) => ev.id);
@@ -319,6 +396,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 +450,7 @@ class ReadinessEngine {
         required: Boolean(reqDef.required),
         satisfied: isSatisfied,
         reason,
+        reasonCode,
         evidenceIds: matchedEvidenceIds,
         recommendedAction: isSatisfied ? null : this.suggestAction(reqId, reqDef, taskProfile),
       });
@@ -383,6 +487,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,
@@ -399,6 +507,9 @@ class ReadinessEngine {
       evidenceCount: taskEvidence.length,
       unresolvableEvidence,
       staleEvidence,
+      staleAbsence,
+      ...(unreadablePlan ? { retrievalPlan: unreadablePlan } : {}),
+      ...(unboundEvidence ? { unboundEvidence } : {}),
     };
   }
 }
@@ -406,7 +517,7 @@ 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' }     ) {
+function evaluateTaskReadiness({ taskProfile, repoRoot = REPO_ROOT, projectRoot = process.cwd(), treeRoot = projectRoot, sourceRoot = 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)) {
@@ -417,11 +528,11 @@ function evaluateTaskReadiness({ taskProfile, repoRoot = REPO_ROOT, projectRoot
   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, sourceRoot }).validateLedgerFreshness(ledger);
   const claims = new ClaimsManager({ evidenceLedger: ledger, repoRoot: projectRoot });
   claims.load(taskProfile.taskId);
   claims.evaluateAll();
-  const report = new ReadinessEngine({ repoRoot, projectRoot }).evaluateReadiness(taskProfile, ledger, claims);
+  const report = new ReadinessEngine({ repoRoot, projectRoot, sourceRoot }).evaluateReadiness(taskProfile, ledger, claims);
   return { ...report, executionMode: mode, stageEntry: stageEntryFor(report.state, mode) };
 }
 

package/src/runtime/research-request.js

@@ -8,13 +8,15 @@ 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 { taskRecord } = require('./task-scope.js');
+const { FreshnessValidator, fileRootFor } = 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 REASONS = new Set(['detected-gap', 'user-request', 'ideation']);
+// Stage kinds an ideation request may attach to (IC-001): the feature's discovery and design stages.
+const IDEATION_KINDS = new Set(['discovery', 'design']);
 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`);
@@ -22,7 +24,7 @@ const safeId = (value     , label     ) => {
   return value;
 };
 
-function hasLocatedSource(item     , projectRoot     ) {
+function hasLocatedSource(item     , projectRoot     , stateRoot      = projectRoot) {
   const locator = item.locator || {};
   if (locator.uri !== undefined) {
     if (typeof locator.uri !== 'string') return false;
@@ -32,33 +34,43 @@ function hasLocatedSource(item     , projectRoot     ) {
     } catch { return false; }
   }
   return Boolean((locator.uri && typeof locator.uri === 'string')
-    || (locator.file && resolveLocator({ locator, repoRoot: projectRoot }).resolved));
+    || (locator.file && resolveLocator({ locator, repoRoot: fileRootFor(projectRoot, stateRoot, locator) }).resolved));
 }
 
+// The run, the requests, the evidence and the claims are all read and written under `projectRoot`,
+// the task's state root (115 IC-004); `sourceRoot` is the checkout the verb runs in, where a relative
+// evidence locator resolves and is hashed (IC-007). Both default to the same directory.
 class ResearchRequestStore {
                            
+                          
                       
                     
                         
-  constructor({ projectRoot = process.cwd(), fsImpl = fs, slug = null }      = {}) {
+  constructor({ projectRoot = process.cwd(), sourceRoot, fsImpl = fs, slug = null }      = {}) {
     this.projectRoot = projectRoot;
+    this.sourceRoot = sourceRoot || 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. */
+  /** The task's request file in the feature's namespace when it has one (task-scope.ts), else the flat store. */
+  record(taskId     ) {
+    return taskRecord({ projectRoot: this.projectRoot, store: 'research', taskId: assertSafeTaskId(taskId), slug: this.slug, fsImpl: this.fsImpl });
+  }
+
+  /** Where the task's requests are written. */
   file(taskId     ) {
-    const dir = taskStoreDir({ projectRoot: this.projectRoot, store: 'research', taskId: assertSafeTaskId(taskId), slug: this.slug });
-    return path.join(dir, `${taskId}.json`);
+    return this.record(taskId).file;
   }
 
+  /** The task's run, read where the orchestrator keeps it (115 IC-004). */
   runFile(taskId     ) {
-    return path.join(this.projectRoot, '.doflow', 'state', 'orchestration', `${assertSafeTaskId(taskId)}.json`);
+    return taskRecord({ projectRoot: this.projectRoot, store: 'orchestration', taskId: assertSafeTaskId(taskId), slug: this.slug, fsImpl: this.fsImpl }).read;
   }
 
   read(taskId     ) {
-    const data = readTaskState(this.fsImpl, this.file(taskId));
+    const data = readTaskState(this.fsImpl, this.record(taskId).read);
     if (!data) return { taskId, revision: 0, requests: [] };
     if (data.taskId !== taskId || !Array.isArray(data.requests)
       || data.requests.some((r     ) => !STATES.has(r.status))) {
@@ -70,7 +82,8 @@ class ResearchRequestStore {
   // 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     ) => {
+    const { file, seed } = this.record(taskId);
+    updateTaskState({ fsImpl: this.fsImpl, file, prepare: seed, build: (disk     ) => {
       if (disk && (disk.taskId !== taskId || !Array.isArray(disk.requests))) {
         throw new Error(`Invalid research state for task '${taskId}'`);
       }
@@ -90,6 +103,7 @@ class ResearchRequestStore {
     if (current?.type !== 'stage' || current.id !== stageId) {
       throw new Error(`Current feature stage is '${current?.type === 'stage' ? current.id : 'none'}', not '${stageId}'`);
     }
+    return current;
   }
 
   open({ taskId, stageId, question, reason, blocking }      = {}) {
@@ -103,13 +117,20 @@ class ResearchRequestStore {
     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);
+      const stage = this.stageFor(taskId, stageId);
+      if (reason === 'ideation' && !IDEATION_KINDS.has(stage.kind)) {
+        throw new Error(`reason ideation is only valid on a feature discovery or design stage, not '${stage.kind ?? 'none'}'`);
+      }
       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;
+          const upgradeBlocking = (blocking ?? reason === 'detected-gap') && !existing.blocking;
+          // A re-open as ideation makes the request ideation (so an OPEN one holds the stage); no
+          // re-open weakens it: an ideation request keeps its reason.
+          const nextReason = existing.reason === 'ideation' ? 'ideation' : reason === 'ideation' || upgradeBlocking ? reason : existing.reason;
+          if (upgradeBlocking || nextReason !== existing.reason) {
+            if (upgradeBlocking) existing.blocking = true;
+            existing.reason = nextReason;
             existing.updatedAt = new Date().toISOString();
           }
           return existing;
@@ -142,7 +163,7 @@ class ResearchRequestStore {
       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);
+      new FreshnessValidator({ repoRoot: this.projectRoot, treeRoot: this.sourceRoot, sourceRoot: this.sourceRoot }).validateLedgerFreshness(ledger);
       const claims = new ClaimsManager({ repoRoot: this.projectRoot, evidenceLedger: ledger, slug: this.slug });
       claims.load(taskId); claims.evaluateAll();
       const claim = claims.getClaim(claimId);
@@ -153,7 +174,7 @@ class ResearchRequestStore {
         const item = ledger.getEvidence(id);
         if (!item || item.taskId !== taskId || item.provenance !== 'extracted'
           || item.status === 'superseded' || item.freshness?.status !== 'FRESH'
-          || !hasLocatedSource(item, this.projectRoot)
+          || !hasLocatedSource(item, this.sourceRoot, this.projectRoot)
           || !claim.supportingEvidence.includes(id)) {
           throw new Error(`Evidence '${id}' is not fresh, located support for this claim and task`);
         }
@@ -171,8 +192,12 @@ class ResearchRequestStore {
   }
 
   blockingGap(taskId     , stageId     ) {
-    const requests = this.list(taskId).filter((r     ) => r.stageId === stageId && r.blocking);
-    for (const request of requests) {
+    const onStage = this.list(taskId).filter((r     ) => r.stageId === stageId);
+    // An OPEN ideation request holds the stage whatever its blocking flag (IC-002): the research
+    // is either answered or recorded UNRESOLVED before the stage completes.
+    const openIdeation = onStage.find((r     ) => r.reason === 'ideation' && r.status === 'OPEN');
+    if (openIdeation) return openIdeation;
+    for (const request of onStage.filter((r     ) => r.blocking)) {
       if (request.status !== 'ANSWERED') return request;
       try {
         this.validateAnswer(taskId, request);
@@ -186,7 +211,7 @@ class ResearchRequestStore {
   validateAnswer(taskId     , request     ) {
     const ledger = new EvidenceLedger({ repoRoot: this.projectRoot, slug: this.slug });
     ledger.load(taskId);
-    new FreshnessValidator({ repoRoot: this.projectRoot }).validateLedgerFreshness(ledger);
+    new FreshnessValidator({ repoRoot: this.projectRoot, treeRoot: this.sourceRoot, sourceRoot: this.sourceRoot }).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);
@@ -201,7 +226,7 @@ class ResearchRequestStore {
       const item = ledger.getEvidence(id);
       if (!item || item.taskId !== taskId || item.provenance !== 'extracted'
         || item.status === 'superseded' || item.freshness?.status !== 'FRESH'
-        || !hasLocatedSource(item, this.projectRoot)
+        || !hasLocatedSource(item, this.sourceRoot, this.projectRoot)
         || !claim.supportingEvidence.includes(id)) {
         throw new Error(`Research evidence '${id}' is no longer fresh, located support`);
       }
@@ -210,9 +235,9 @@ class ResearchRequestStore {
 }
 
 function handleResearchRequestCommand({ action = 'list', taskId, stageId, question, reason,
-  blocking, requestId, outcome, claimId, evidenceIds, gap, json = false, projectRoot, slug }      = {}) {
+  blocking, requestId, outcome, claimId, evidenceIds, gap, json = false, projectRoot, sourceRoot, slug }      = {}) {
   try {
-    const store = new ResearchRequestStore({ projectRoot, slug });
+    const store = new ResearchRequestStore({ projectRoot, sourceRoot, slug });
     let result;
     switch (action) {
       case 'open': result = store.open({ taskId, stageId, question, reason, blocking }); break;
@@ -228,4 +253,4 @@ function handleResearchRequestCommand({ action = 'list', taskId, stageId, questi
   }
 }
 
-module.exports = { ResearchRequestStore, handleResearchRequestCommand };
+module.exports = { ResearchRequestStore, handleResearchRequestCommand, REASONS };