@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/readiness.js

@@ -7,6 +7,7 @@ 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([
@@ -64,6 +65,7 @@ class ReadinessEngine {
                       
                         
                            
+                          
                             
                          
   /**
@@ -72,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]
@@ -80,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) {
@@ -134,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',
@@ -224,7 +245,10 @@ class ReadinessEngine {
     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
@@ -246,7 +270,7 @@ class ReadinessEngine {
     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,
@@ -296,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) {
@@ -309,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}'` : ''}.`;
@@ -476,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(), treeRoot = projectRoot, 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)) {
@@ -487,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, treeRoot }).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 };

package/src/runtime/retrieval-plan.js

@@ -42,7 +42,7 @@ const { CapabilityRouter } = require('./capability-router.js');
 const { EvidenceLedger, assertSafeTaskId } = require('./evidence-ledger.js');
 const { FreshnessValidator } = require('./freshness.js');
 const { probeFreshness } = require('./health.js');
-const { planPath, readPlan, updatePlan, moveCorruptPlanAside, mintPlanId, activeAttemptRef, resolveNeed, bindEvidence, deriveOutcome } = require('./retrieval-record.js');
+const { planPath, readPlan, updatePlan, moveCorruptPlanAside, mintPlanId, activeAttemptRef, resolveNeed, appendRetrievalAttempt, bindEvidence, deriveOutcome } = require('./retrieval-record.js');
 // One definition of the score refusal, applied at a second boundary. See the note on
 // EVIDENCE_SCORE_FIELDS in src/runtime/evidence-fields.js: relevance is a property of a search, not of a fact, and a plan
 // that recorded one would hand the next worker a confidence dressed as a measurement.
@@ -387,7 +387,7 @@ function reportPlan({ projectRoot, sourceRoot, taskId, reached, json, slug, repo
   } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }
-  new FreshnessValidator({ repoRoot: projectRoot, treeRoot: sourceRoot }).validateLedgerFreshness(ledger);
+  new FreshnessValidator({ repoRoot: projectRoot, treeRoot: sourceRoot, sourceRoot }).validateLedgerFreshness(ledger);
   const items = ledger.queryEvidence({ taskId });
 
   const isQueryBound = Boolean(record.planId);
@@ -730,35 +730,15 @@ function attemptPlan({
   let savedAttempt      = null;
   let file        ;
   try {
-    file = updatePlan(projectRoot, taskId, slug, (disk     ) => {
-      const current = requirePlanForUpdate(disk, taskId);
-      const targetNeed = current.needs ? current.needs.find((n     ) => n.intent === intent) : null;
-      if (!targetNeed) {
-        throw new Error(`need '${intent}' missing from disk plan during update`);
-      }
-      if (!Array.isArray(targetNeed.attempts)) {
-        targetNeed.attempts = [];
-      }
-      const n = targetNeed.attempts.length + 1;
-      const role = provider === targetNeed.provider ? 'primary' : 'fallback';
-      const attempt = {
-        n,
-        provider,
-        capability: targetNeed.capability,
-        role,
-        status: finalStatus,
-        reason: finalReason,
-        note: note !== undefined && note !== null ? String(note) : null,
-        indexState,
-        attemptRef: activeRef,
-        evidenceIds: [],
-        recordedAt: new Date().toISOString(),
-        recordedBy: 'caller',
-      };
-      targetNeed.attempts.push(attempt);
-      savedAttempt = attempt;
-      return current;
+    const appended = appendRetrievalAttempt({
+      projectRoot, taskId, intent, provider, status: finalStatus, reason: finalReason,
+      note, indexState, slug, attemptRef: activeRef,
+      expectedCapability: declaredNeed.capability,
+      expectedPrimaryProvider: declaredNeed.provider,
+      registeredProviders,
     });
+    file = appended.file;
+    savedAttempt = appended.attempt;
   } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }

package/src/runtime/retrieval-record.js

@@ -5,7 +5,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { taskStoreDir, resolveTaskScope } = require('./task-scope.js');
+const { taskStoreDir, taskRecord, resolveTaskScope } = require('./task-scope.js');
 const { assertSafeTaskId } = require('./evidence-ledger.js');
 const { readTaskState, updateTaskState } = require('./task-state.js');
 const { storeFile, activeAttempt } = require('./task-attempts.js');
@@ -36,8 +36,7 @@ function planPath(projectRoot     , taskId     , slug      = null)         {
  * @returns {any|null}
  */
 function readPlan(projectRoot     , taskId     , slug      = null, fsImpl      = fs)             {
-  const file = planPath(projectRoot, taskId, slug);
-  return readTaskState(fsImpl, file);
+  return readTaskState(fsImpl, taskRecord({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug, fsImpl }).read);
 }
 
 /**
@@ -50,8 +49,8 @@ function readPlan(projectRoot     , taskId     , slug      = null, fsImpl      =
  * @returns {string} the written file path
  */
 function updatePlan(projectRoot     , taskId     , slug     , build     , fsImpl      = fs, prepare      )         {
-  const file = planPath(projectRoot, taskId, slug);
-  return updateTaskState({ fsImpl, file, build, prepare });
+  const { file, seed } = taskRecord({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug, fsImpl });
+  return updateTaskState({ fsImpl, file, build, prepare: () => { seed(); if (prepare) prepare(); } });
 }
 
 /** Move a syntactically unreadable plan aside before its replacement is written under the lock. */
@@ -128,6 +127,75 @@ function resolveNeed(plan     , intent        , taskId        )      {
   };
 }
 
+/** Resolve the plan's query binding and the task's active attempt in one reusable operation. */
+function resolveRetrievalBinding({ projectRoot, taskId, intent, slug = null, fsImpl = fs, attemptRoot = null }     )      {
+  const plan = readPlan(projectRoot, taskId, slug, fsImpl);
+  const resolved = resolveNeed(plan, intent, taskId);
+  if (!resolved.ok) return resolved;
+  return {
+    ok: true,
+    plan,
+    queryRef: resolved.queryRef,
+    need: resolved.need,
+    attemptRef: activeAttemptRef(projectRoot, taskId, slug, fsImpl, attemptRoot),
+  };
+}
+
+/** Append one validated provider attempt under the retrieval-plan state lock. */
+function appendRetrievalAttempt({
+  projectRoot, taskId, intent, provider, status, reason, note = null, indexState,
+  slug = null, attemptRef = undefined, fsImpl = fs, expectedCapability = undefined,
+  expectedPrimaryProvider = undefined, registeredProviders = undefined,
+}     )      {
+  const allowedIndexStates = ['FRESH', 'STALE', 'UNKNOWN', 'NOT_APPLICABLE'];
+  if (!allowedIndexStates.includes(indexState)) {
+    throw new Error(`attempt indexState '${indexState}' is invalid; expected one of ${allowedIndexStates.join(', ')}`);
+  }
+  const allowedReasons                           = {
+    EMPTY: ['empty-answer', 'index-stale', 'index-unverifiable'],
+    UNREACHED: ['provider-unavailable', 'policy-bypass', 'provider-error', 'timeout'],
+    UNVERIFIED: ['index-unverifiable'],
+  };
+  if (status === 'RETRIEVED') throw new Error('RETRIEVED is derived from evidence and cannot be appended as a provider attempt');
+  if (!Object.prototype.hasOwnProperty.call(allowedReasons, status) || !allowedReasons[status].includes(reason)) {
+    throw new Error(`attempt reason '${reason}' is not valid for status '${status}'`);
+  }
+  if (!Array.isArray(registeredProviders) || !registeredProviders.includes(provider)) {
+    throw new Error(`provider '${provider}' is not registered for this capability`);
+  }
+  if (note !== null && String(note).length > 160) throw new Error('attempt note is longer than 160 characters');
+
+  let savedAttempt      = null;
+  const file = updatePlan(projectRoot, taskId, slug, (disk     ) => {
+    if (disk === null) throw new Error(`the retrieval plan for task ${taskId} was removed during the update; re-declare it`);
+    const current = disk;
+    const targetNeed = Array.isArray(current.needs) ? current.needs.find((need     ) => need.intent === intent) : null;
+    if (!targetNeed) throw new Error(`need '${intent}' missing from disk plan during update`);
+    if (expectedCapability !== undefined && targetNeed.capability !== expectedCapability) {
+      throw new Error(`need '${intent}' capability changed during update`);
+    }
+    if (expectedPrimaryProvider !== undefined && targetNeed.provider !== expectedPrimaryProvider) {
+      throw new Error(`need '${intent}' provider changed during update`);
+    }
+    if (provider === undefined || provider === null || String(provider).trim() === '') throw new Error('attempt provider is required');
+    if (!Array.isArray(targetNeed.attempts)) targetNeed.attempts = [];
+    const n = targetNeed.attempts.reduce((max        , prior     ) => Math.max(max, Number.isInteger(prior?.n) ? prior.n : 0), 0) + 1;
+    const role = provider === targetNeed.provider ? 'primary' : 'fallback';
+    savedAttempt = {
+      n, provider, capability: targetNeed.capability, role, status, reason,
+      note: note !== undefined && note !== null ? String(note) : null,
+      indexState,
+      attemptRef: attemptRef === undefined ? activeAttemptRef(projectRoot, taskId, slug, fsImpl) : attemptRef,
+      evidenceIds: [],
+      recordedAt: new Date().toISOString(),
+      recordedBy: 'caller',
+    };
+    targetNeed.attempts.push(savedAttempt);
+    return current;
+  }, fsImpl);
+  return { file, attempt: savedAttempt };
+}
+
 /**
  * Reads the 070 active attempt ref for a task, returning `${taskId}#${token}` or null.
  *
@@ -216,6 +284,8 @@ module.exports = {
   moveCorruptPlanAside,
   mintPlanId,
   resolveNeed,
+  resolveRetrievalBinding,
+  appendRetrievalAttempt,
   activeAttemptRef,
   declaredIntentList,
   bindEvidence,