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

package/src/runtime/{retrieval-plan.ts → retrieval-plan.js}

@@ -38,18 +38,17 @@
  * emits are counts of records.
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { CapabilityRouter } = require('./capability-router.ts');
-const { EvidenceLedger, assertSafeTaskId } = require('./evidence-ledger.ts');
-const { taskStoreDir } = require('./task-scope.ts');
-const { probeFreshness } = require('./health.ts');
+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');
 // One definition of the score refusal, applied at a second boundary. See the note on
-// EVIDENCE_SCORE_FIELDS in cli.js: relevance is a property of a search, not of a fact, and a plan
+// 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.
-const { assertNoScoreFields } = require('./cli.ts');
-const { finishRuntime, usageError } = require('./cli-result.ts');
-const { REPO_ROOT } = require('../helper/repo-root.ts');
+const { assertNoScoreFields } = require('./evidence-fields.js');
+const { finishRuntime, usageError } = require('./cli-result.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
 
 // ── the closed result vocabulary (design §4) ─────────────────────────────────────────────────
 
@@ -73,6 +72,18 @@ const RESULTS = Object.freeze([RETRIEVED, EMPTY, UNREACHED, UNVERIFIED]);
 const NOT_APPLICABLE = 'NOT_APPLICABLE';
 const FRESHNESS_STATES = Object.freeze(['FRESH', 'STALE', 'UNKNOWN', NOT_APPLICABLE]);
 
+// ── attempt reason codes (IC-013) ─────────────────────────────────────────────────────────────
+
+const ATTEMPT_REASON_CODES = Object.freeze([
+  'provider-unavailable',
+  'policy-bypass',
+  'provider-error',
+  'timeout',
+  'empty-answer',
+  'index-stale',
+  'index-unverifiable',
+]);
+
 /**
  * Design §4's mapping table, as data. It maps only the *empty* answer: a provider that returned
  * something is RETRIEVED whatever the age of its index, because the thing it returned is a
@@ -84,19 +95,26 @@ const FRESHNESS_STATES = Object.freeze(['FRESH', 'STALE', 'UNKNOWN', NOT_APPLICA
  * this module exists to prevent — so staleness travels as a marker beside `EMPTY`, and the
  * provider's `refresh` command travels with it so the remedy is one step away.
  */
-const EMPTY_ANSWER_BY_FRESHNESS: Record<string, any> = Object.freeze({
+const EMPTY_ANSWER_BY_FRESHNESS                      = Object.freeze({
   UNKNOWN: UNVERIFIED,
   STALE: EMPTY,
   FRESH: EMPTY,
   [NOT_APPLICABLE]: EMPTY,
 });
 
+function requirePlanForUpdate(disk     , taskId        ) {
+  if (disk === null) {
+    throw new Error(`the retrieval plan for task ${taskId} was removed during the update; re-declare it`);
+  }
+  return disk;
+}
+
 /**
  * What an empty answer becomes, given the freshness of the index behind it.
  * @param {string} freshnessState one of FRESHNESS_STATES
  * @returns {string} one of RESULTS
  */
-function resultForEmptyAnswer(freshnessState: any) {
+function resultForEmptyAnswer(freshnessState     ) {
   const mapped = EMPTY_ANSWER_BY_FRESHNESS[freshnessState];
   if (!mapped) {
     // Fail closed rather than pick a default: an unrecognised freshness token means the record was
@@ -107,50 +125,6 @@ function resultForEmptyAnswer(freshnessState: any) {
   return mapped;
 }
 
-// ── the record ────────────────────────────────────────────────────────────────────────────────
-
-/**
- * Where a task's plan lives, under the invoking project's state root.
- *
- * The task id is validated by the evidence ledger's own rule, unchanged: it becomes a filename, so
- * it must never be able to name a path.
- * @param {string} projectRoot
- * @param {string} taskId
- * @param {string|null} [slug] the feature the task belongs to, when not the branch's (task-scope.js)
- * @returns {string}
- */
-function planPath(projectRoot: any, taskId: any, slug: any = null) {
-  const dir = taskStoreDir({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug });
-  return path.join(dir, `${taskId}.json`);
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} taskId
- * @returns {Object|null} the record, or null when no plan was declared
- */
-function readPlan(projectRoot: any, taskId: any, slug: any = null) {
-  const file = planPath(projectRoot, taskId, slug);
-  if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch (error: any) {
-    throw new Error(`the retrieval plan at '${file}' is not readable: ${error.message}`);
-  }
-}
-
-/**
- * @param {string} projectRoot
- * @param {string} taskId
- * @param {Object} record
- * @returns {string} the file written
- */
-function writePlan(projectRoot: any, taskId: any, record: any, slug: any = null) {
-  const file = planPath(projectRoot, taskId, slug);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
-  return file;
-}
 
 /**
  * The `sourceMode` each provider id declares, as a lookup the plan builds once per declare.
@@ -161,16 +135,16 @@ function writePlan(projectRoot: any, taskId: any, record: any, slug: any = null)
  * @param {Object} capabilities the router's `capabilities` map
  * @returns {(providerId: string) => string|null} the declared mode, or null for an unknown id
  */
-function sourceModeLookup(capabilities: any) {
+function sourceModeLookup(capabilities     ) {
   const modes = new Map();
-  for (const capability of Object.values<any>(capabilities || {})) {
+  for (const capability of Object.values     (capabilities || {})) {
     for (const provider of (capability && capability.providers) || []) {
       if (!provider || !provider.id) continue;
       if (modes.get(provider.id) === 'index') continue;
       modes.set(provider.id, provider.sourceMode || null);
     }
   }
-  return (providerId: any) => (modes.has(providerId) ? modes.get(providerId) : null);
+  return (providerId     ) => (modes.has(providerId) ? modes.get(providerId) : null);
 }
 
 /**
@@ -186,8 +160,8 @@ function sourceModeLookup(capabilities: any) {
  *   absent, every provider without an artifact layout is treated as unknown (fail closed)
  * @returns {{state: string, artifact: string|null, refresh: string|null, label: string|null, reason: string|null}}
  */
-function freshnessEntry(providerId: any, projectRoot: any, sourceModeOf: any = () => null) {
-  const probe = probeFreshness(providerId, { root: projectRoot });
+function freshnessEntry(providerId     , sourceRoot     , sourceModeOf      = () => null) {
+  const probe = probeFreshness(providerId, { root: sourceRoot });
   if (!probe) {
     // `probeFreshness` returns null for a provider it has no artifact layout for. What that means
     // depends on how the provider answers: a `live` provider reads current files or commands, so
@@ -230,9 +204,9 @@ function freshnessEntry(providerId: any, projectRoot: any, sourceModeOf: any = (
  * @param {Object} need
  * @returns {string} one of FRESHNESS_STATES
  */
-function freshnessOf(record: any, need: any) {
+function freshnessOf(record     , need     ) {
   if (!need.provider) return NOT_APPLICABLE;
-  const entry: any = record.providers && record.providers[need.provider];
+  const entry      = record.providers && record.providers[need.provider];
   return entry && entry.state ? entry.state : NOT_APPLICABLE;
 }
 
@@ -248,14 +222,14 @@ function freshnessOf(record: any, need: any) {
  * @param {Array<Object>} items
  * @returns {Array<string>} evidence ids
  */
-function evidenceIdsFor(need: any, items: any) {
+function evidenceIdsFor(need     , items     ) {
   return items
-    .filter((item: any) => {
+    .filter((item     ) => {
       const source = item.source || {};
       if (need.provider && source.provider === need.provider) return true;
       return Boolean(need.capability) && source.capability === need.capability;
     })
-    .map((item: any) => item.id);
+    .map((item     ) => item.id);
 }
 
 // ── actions ───────────────────────────────────────────────────────────────────────────────────
@@ -274,13 +248,13 @@ function evidenceIdsFor(need: any, items: any) {
  *
  * @returns {number} exit code
  */
-function declarePlan({ router, projectRoot, taskId, stage, intents, json, slug }: any) {
-  const needs = [];
+function declarePlan({ router, projectRoot, sourceRoot, taskId, stage, intents, json, slug }     ) {
+  const needs        = [];
   for (const intent of intents) {
     let resolution;
     try {
       resolution = router.resolveIntent(intent);
-    } catch (error: any) {
+    } catch (error     ) {
       // A misspelled intent is a caller error, not an unresolvable need. Recording it as
       // declared-unresolvable would file a typo as a machine limitation and hide it until report.
       return usageError('retrieval-plan',
@@ -299,22 +273,39 @@ function declarePlan({ router, projectRoot, taskId, stage, intents, json, slug }
 
   // R8, in one loop: the probe set is the set of DISTINCT providers, so cost is bounded by
   // provider count and not by need count. Six needs across two providers pay two scans.
-  const providers: Record<string, any> = {};
-  const sourceModeOf: any = sourceModeLookup(router.capabilities);
+  const providers                      = {};
+  const sourceModeOf      = sourceModeLookup(router.capabilities);
   for (const need of needs) {
     if (!need.provider || providers[need.provider]) continue;
-    providers[need.provider] = freshnessEntry(need.provider, projectRoot, sourceModeOf);
+    providers[need.provider] = freshnessEntry(need.provider, sourceRoot, sourceModeOf);
   }
 
-  const record = {
+  const planId = mintPlanId();
+  const attemptRef = activeAttemptRef(projectRoot, taskId, slug);
+  for (const need of needs) {
+    need.queryRef = `${planId}#${need.intent}`;
+  }
+
+  const record      = {
     version: 1,
+    planId,
+    binding: 'query',
     taskId,
     stage: stage || null,
     declaredAt: new Date().toISOString(),
+    attemptRef,
     providers,
     needs,
   };
-  const file = writePlan(projectRoot, taskId, record, slug);
+  let file        ;
+  try {
+    file = updatePlan(projectRoot, taskId, slug, () => record, undefined, () => {
+      const corruptFile = moveCorruptPlanAside(projectRoot, taskId, slug);
+      if (corruptFile) console.log(`Moved unreadable retrieval plan to ${corruptFile}; declaring a new plan.`);
+    });
+  } catch (error     ) {
+    return usageError('retrieval-plan', error.message, json, error);
+  }
 
   const unresolvable = needs.filter((need) => !need.provider).map((need) => need.intent);
   if (json) {
@@ -326,12 +317,13 @@ function declarePlan({ router, projectRoot, taskId, stage, intents, json, slug }
   console.log('═'.repeat(78));
   console.log(`Stage: ${record.stage || 'not stated'}`);
   console.log('─'.repeat(78));
-  console.log('Intent'.padEnd(26) + 'Provider'.padEnd(22) + 'Index');
+  console.log('Intent'.padEnd(26) + 'Provider'.padEnd(22) + 'Index'.padEnd(16) + 'QueryRef');
   for (const need of needs) {
     console.log(
       need.intent.padEnd(26)
       + (need.provider || 'none — unresolvable').padEnd(22)
-      + freshnessOf(record, need),
+      + freshnessOf(record, need).padEnd(16)
+      + (need.queryRef || ''),
     );
   }
   printProviderIndexes(record);
@@ -367,11 +359,11 @@ function declarePlan({ router, projectRoot, taskId, stage, intents, json, slug }
  *
  * @returns {number} exit code
  */
-function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
-  let record;
+function reportPlan({ projectRoot, sourceRoot, taskId, reached, json, slug, repoRoot }     ) {
+  let record     ;
   try {
     record = readPlan(projectRoot, taskId, slug);
-  } catch (error: any) {
+  } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }
   if (!record) {
@@ -381,7 +373,7 @@ function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
       + 'plan would state that nothing was missed, which is not something an absent plan can establish', json);
   }
 
-  const declared = new Set(record.needs.map((need: any) => need.intent));
+  const declared = new Set(record.needs.map((need     ) => need.intent));
   const undeclared = [...reached].filter((intent) => !declared.has(intent)).sort();
   if (undeclared.length > 0) {
     return usageError('retrieval-plan',
@@ -392,25 +384,129 @@ function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
   const ledger = new EvidenceLedger({ repoRoot: projectRoot, slug });
   try {
     ledger.load(taskId);
-  } catch (error: any) {
+  } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }
+  new FreshnessValidator({ repoRoot: projectRoot, treeRoot: sourceRoot }).validateLedgerFreshness(ledger);
   const items = ledger.queryEvidence({ taskId });
 
-  for (const need of record.needs) {
-    need.evidenceIds = evidenceIdsFor(need, items);
-    if (need.evidenceIds.length > 0) need.result = RETRIEVED;
-    else if (reached.has(need.intent)) need.result = resultForEmptyAnswer(freshnessOf(record, need));
-    else need.result = UNREACHED;
+  const isQueryBound = Boolean(record.planId);
+  let binding = isQueryBound ? bindEvidence(record, items) : null;
+  let reportSourceModeOf      = null;
+  const probeByProvider = new Map             ();
+  if (record.planId) {
+    const initialBinding = bindEvidence(record, items);
+    const missingProviders = new Set        ();
+    for (const need of record.needs) {
+      for (const item of initialBinding.byNeed.get(need.intent) || []) {
+        if (item.result !== 'EMPTY' && !record.providers?.[item.source?.provider]) {
+          if (item.source?.provider) missingProviders.add(item.source.provider);
+        }
+      }
+    }
+    if (missingProviders.size > 0) {
+      const reportRouter = new CapabilityRouter({ repoRoot: repoRoot || REPO_ROOT });
+      reportSourceModeOf = sourceModeLookup(reportRouter.capabilities);
+      for (const providerId of missingProviders) {
+        probeByProvider.set(providerId, module.exports._probe(providerId, sourceRoot, reportSourceModeOf));
+      }
+    }
   }
 
-  record.reportedAt = new Date().toISOString();
-  const file = writePlan(projectRoot, taskId, record, slug);
+  let file        ;
+  try {
+    file = updatePlan(projectRoot, taskId, slug, (disk     ) => {
+      const current = requirePlanForUpdate(disk, taskId);
+      if (current.planId) {
+        const currentBinding = bindEvidence(current, items);
+        binding = currentBinding;
+        for (const need of current.needs) {
+          const bound = currentBinding.byNeed.get(need.intent) || [];
+          if (!Array.isArray(need.attempts)) need.attempts = [];
+          for (const attempt of need.attempts) {
+            if (attempt.recordedBy === 'derived') attempt.evidenceIds = [];
+          }
+          const groups = new Map               ();
+          for (const item of bound) {
+            const absent = item.result === 'EMPTY';
+            const status = absent
+              ? (item.freshness?.status === 'UNKNOWN' ? UNVERIFIED : EMPTY)
+              : RETRIEVED;
+            const providerKey = item.source?.provider ?? '__no_provider__';
+            const freshness = item.freshness?.status || 'UNKNOWN';
+            const key = `${providerKey}\u0000${status}\u0000${freshness}`;
+            if (!groups.has(key)) groups.set(key, []);
+            const group = groups.get(key);
+            if (group) group.push(item);
+          }
+          const countedAttempts = need.attempts.filter((attempt     ) =>
+            !(attempt.recordedBy === 'derived' && attempt.basis !== 'report-need'
+              && (!Array.isArray(attempt.evidenceIds) || attempt.evidenceIds.length === 0)));
+          if (reached.has(need.intent) && countedAttempts.length === 0 && bound.length === 0) {
+            const provider = need.provider;
+            const indexState = provider ? (current.providers?.[provider]?.state || 'UNKNOWN') : NOT_APPLICABLE;
+            groups.set(`${provider ?? '__no_provider__'}\u0000${resultForEmptyAnswer(indexState)}\u0000${indexState}`, []);
+          }
+          for (const [key, group] of groups) {
+            const [providerKey, status, freshness] = key.split('\u0000');
+            const provider = providerKey === '__no_provider__' ? null : providerKey;
+            let attempt = need.attempts.find((entry     ) => entry.recordedBy === 'derived'
+              && entry.provider === provider && entry.status === status && entry.indexState === freshness);
+            if (attempt) {
+              attempt.evidenceIds = group.map((item     ) => item.id);
+              continue;
+            }
+            if (status === RETRIEVED && provider && !current.providers?.[provider] && probeByProvider.has(provider)) {
+              current.providers ||= {};
+              current.providers[provider] = probeByProvider.get(provider);
+            }
+            const providerState = provider ? current.providers?.[provider]?.state : null;
+            const indexState = status === RETRIEVED
+              ? (providerState || 'UNKNOWN')
+              : (freshness || providerState || 'UNKNOWN');
+            const reason = status === RETRIEVED ? null
+              : indexState === 'STALE' ? 'index-stale'
+                : indexState === 'UNKNOWN' ? 'index-unverifiable' : 'empty-answer';
+            const n = need.attempts.reduce((max        , entry     ) => Math.max(max, entry.n || 0), 0) + 1;
+            need.attempts.push({
+              n, provider, capability: need.capability,
+              role: provider === null || provider === need.provider ? 'primary' : 'fallback',
+              status, reason, note: null, indexState,
+              attemptRef: current.attemptRef || null,
+              evidenceIds: group.map((item     ) => item.id),
+              recordedAt: new Date().toISOString(), recordedBy: 'derived',
+              ...(reached.has(need.intent) && group.length === 0 ? { basis: 'report-need' } : {}),
+            });
+          }
+          const outcome = deriveOutcome(need);
+          need.result = outcome.result;
+          need.resolvedBy = outcome.resolvedBy;
+          need.viaFallback = outcome.viaFallback;
+          need.evidenceIds = need.attempts.filter((entry     ) => entry.status === RETRIEVED
+            && !(entry.recordedBy === 'derived' && (!Array.isArray(entry.evidenceIds) || entry.evidenceIds.length === 0)))
+            .flatMap((entry     ) => entry.evidenceIds || []);
+        }
+        record = current;
+      } else {
+        for (const need of current.needs) {
+          need.evidenceIds = evidenceIdsFor(need, items);
+          if (need.evidenceIds.length > 0) need.result = RETRIEVED;
+          else if (reached.has(need.intent)) need.result = resultForEmptyAnswer(freshnessOf(current, need));
+          else need.result = UNREACHED;
+        }
+      }
+      current.reportedAt = new Date().toISOString();
+      record = current;
+      return current;
+    });
+  } catch (error     ) {
+    return usageError('retrieval-plan', error.message, json, error);
+  }
 
   // Derived views, computed at emit and never stored on a need — a need holds a provider id and
   // nothing about that provider's index (plan D7).
-  const byResult = (result: any) => record.needs.filter((need: any) => need.result === result).map((need: any) => need.intent);
-  const stale = record.needs.filter((need: any) => freshnessOf(record, need) === 'STALE').map((need: any) => need.intent);
+  const byResult = (result     ) => record.needs.filter((need     ) => need.result === result).map((need     ) => need.intent);
+  const stale = record.needs.filter((need     ) => freshnessOf(record, need) === 'STALE').map((need     ) => need.intent);
   const unreached = byResult(UNREACHED);
   const unverified = byResult(UNVERIFIED);
   const incomplete = unreached.length > 0 || unverified.length > 0;
@@ -430,6 +526,18 @@ function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
       unreached,
       unverified,
       stale,
+      ...(record.planId ? {
+        planId: record.planId,
+        binding: record.binding,
+        unbound: {
+          count: binding.unbound.length,
+          ids: binding.unbound.slice(0, 5).map((item     ) => item.id),
+          causes: binding.unbound.reduce((counts     , item     ) => {
+            counts[item.cause] = (counts[item.cause] || 0) + 1;
+            return counts;
+          }, {}),
+        },
+      } : {}),
     }, null, 2));
     return finishRuntime(incomplete ? 1 : 0);
   }
@@ -447,8 +555,21 @@ function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
       + freshness.padEnd(16)
       + need.result + (freshness === 'STALE' ? ' (stale index)' : ''),
     );
+    if (record.planId) {
+      const attempts = need.attempts || [];
+      if (attempts.length > 1 || (attempts.length === 1 && attempts[0].status !== RETRIEVED)) {
+        for (const attempt of attempts) {
+          console.log(`  Attempt #${attempt.n} ${attempt.role} ${attempt.provider} — ${attempt.status}`
+            + (attempt.reason ? ` (${attempt.reason})` : '')
+            + (attempt.evidenceIds?.length ? ` [${attempt.evidenceIds.join(', ')}]` : ''));
+        }
+      }
+    }
   }
   printProviderIndexes(record);
+  if (record.planId && binding.unbound.length > 0) {
+    console.log(`${binding.unbound.length} item(s) not bound to a declared need are not counted; re-record them with --need <intent>.`);
+  }
   console.log('─'.repeat(78));
   // NFR-004: the skip is stated as prominently as the failure, on its own line and named.
   if (unreached.length > 0) {
@@ -464,9 +585,209 @@ function reportPlan({ projectRoot, taskId, reached, json, slug }: any) {
   return finishRuntime(incomplete ? 1 : 0);
 }
 
+/**
+ * `--action attempt` — record an attempt against a declared need (IC-012, IC-013).
+ *
+ * Rules:
+ *   - The action appends one attempt to the need, under the plan lock (IC-020).
+ *   - `indexState` is re-probed for `--provider` with `freshnessEntry` at record time.
+ *   - `--status EMPTY` is mapped through `resultForEmptyAnswer(indexState)`, so an EMPTY
+ *     from an UNKNOWN index is stored as UNVERIFIED with reason `index-unverifiable`.
+ *   - The action writes no evidence and never changes declared fields.
+ *   - Exits 0 when written, 2 on any refusal.
+ *
+ * @returns {number} exit code
+ */
+function attemptPlan({
+  router,
+  projectRoot,
+  taskId,
+  intents,
+  provider,
+  attemptStatus,
+  reason,
+  note,
+  json,
+  slug,
+  sourceRoot,
+}     ) {
+  if (intents.length !== 1) {
+    return usageError(
+      'retrieval-plan',
+      `--need takes one intent on retrieval-plan --action attempt, got ${intents.length}. Record one write per need.`,
+      json,
+    );
+  }
+  const intent = intents[0];
+
+  let record     ;
+  try {
+    record = readPlan(projectRoot, taskId, slug);
+  } catch (error     ) {
+    return usageError('retrieval-plan', error.message, json, error);
+  }
+
+  const resolved = resolveNeed(record, intent, taskId);
+  if (!resolved.ok) {
+    return usageError('retrieval-plan', resolved.message, json);
+  }
+  const declaredNeed = resolved.need;
+
+  if (attemptStatus === undefined || attemptStatus === null || attemptStatus === '') {
+    return usageError('retrieval-plan', '--status is required: EMPTY, UNREACHED or UNVERIFIED', json);
+  }
+
+  if (attemptStatus === 'RETRIEVED') {
+    return usageError(
+      'retrieval-plan',
+      `RETRIEVED is never recorded by hand: it is derived from evidence bound to the need. Record what was found with: doflow evidence --task-id ${taskId} --action add --need ${intent} ...`,
+      json,
+    );
+  }
+
+  if (attemptStatus !== 'EMPTY' && attemptStatus !== 'UNREACHED' && attemptStatus !== 'UNVERIFIED') {
+    return usageError(
+      'retrieval-plan',
+      `unknown --status '${attemptStatus}'. Valid here: EMPTY, UNREACHED, UNVERIFIED. A provider that could not be asked is UNREACHED with --reason provider-unavailable or policy-bypass.`,
+      json,
+    );
+  }
+
+  const REASON_CODES_LIST = ATTEMPT_REASON_CODES.join(', ');
+
+  if (reason === undefined || reason === null || reason === '') {
+    return usageError(
+      'retrieval-plan',
+      `--status ${attemptStatus} needs --reason <code>: a lookup that returned no locator must say why. Codes: ${REASON_CODES_LIST}.`,
+      json,
+    );
+  }
+
+  if (!ATTEMPT_REASON_CODES.includes(reason)) {
+    return usageError(
+      'retrieval-plan',
+      `unknown --reason '${reason}'. Codes: ${REASON_CODES_LIST}.`,
+      json,
+    );
+  }
+
+  const allowedReasons                           = {
+    EMPTY: ['empty-answer', 'index-stale', 'index-unverifiable'],
+    UNREACHED: ['provider-unavailable', 'policy-bypass', 'provider-error', 'timeout'],
+    UNVERIFIED: ['index-unverifiable'],
+  };
+  if (!allowedReasons[attemptStatus].includes(reason)) {
+    return usageError('retrieval-plan', `--reason '${reason}' is not allowed for --status ${attemptStatus}. Allowed: ${allowedReasons[attemptStatus].join(', ')}.`, json);
+  }
+
+  const capEntry = router.capabilities ? router.capabilities[declaredNeed.capability] : null;
+  const registeredProviders = capEntry && Array.isArray(capEntry.providers)
+    ? capEntry.providers.map((p     ) => p.id).filter(Boolean)
+    : [];
+  const regList = registeredProviders.join(', ');
+
+  if (provider === undefined || provider === null || String(provider).trim() === '') {
+    return usageError(
+      'retrieval-plan',
+      `--provider is required: an attempt is one provider's try at one need. Providers registered under ${declaredNeed.capability}: ${regList}.`,
+      json,
+    );
+  }
+
+  if (!registeredProviders.includes(provider)) {
+    return usageError(
+      'retrieval-plan',
+      `provider '${provider}' is not registered under capability '${declaredNeed.capability}' (need '${intent}'). Registered: ${regList}. A fallback is another provider of the same capability, for example native.rg.`,
+      json,
+    );
+  }
+
+  if (note !== undefined && note !== null && String(note).length > 160) {
+    return usageError(
+      'retrieval-plan',
+      `--note is at most 160 characters (got ${String(note).length}): it is a hint for a reader, and the runtime never reads it.`,
+      json,
+    );
+  }
+
+  const sourceModeOf = sourceModeLookup(router.capabilities);
+  const probe = freshnessEntry(provider, sourceRoot, sourceModeOf);
+  const indexState = probe.state;
+
+  let finalStatus = attemptStatus;
+  let finalReason = reason;
+
+  if (attemptStatus === 'EMPTY') {
+    finalStatus = resultForEmptyAnswer(indexState);
+    if (finalStatus === 'UNVERIFIED') {
+      finalReason = 'index-unverifiable';
+    } else if (indexState === 'STALE') {
+      finalReason = 'index-stale';
+    }
+  }
+
+  const activeRef = activeAttemptRef(projectRoot, taskId, slug);
+  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;
+    });
+  } catch (error     ) {
+    return usageError('retrieval-plan', error.message, json, error);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({
+      action: 'attempt',
+      taskId,
+      intent,
+      stateFile: file,
+      attempt: savedAttempt,
+    }, null, 2));
+    return finishRuntime(0);
+  }
+
+  console.log(`\nDoFlow Retrieval Attempt recorded [Task: ${taskId}]:`);
+  console.log('═'.repeat(78));
+  console.log(`Need: ${intent}   Attempt: #${savedAttempt.n}   Role: ${savedAttempt.role}`);
+  console.log(`Provider: ${savedAttempt.provider}   Status: ${savedAttempt.status}   Reason: ${savedAttempt.reason}`);
+  if (savedAttempt.note) console.log(`Note: ${savedAttempt.note}`);
+  console.log('─'.repeat(78));
+  console.log(`Recorded attempt #${savedAttempt.n} to ${file}`);
+  console.log('═'.repeat(78) + '\n');
+  return finishRuntime(0);
+}
+
 /** The provider index block both actions print: state, what was located, and the remedy. */
-function printProviderIndexes(record: any) {
-  const entries = Object.entries<any>(record.providers || {});
+function printProviderIndexes(record     ) {
+  const entries = Object.entries     (record.providers || {});
   if (entries.length === 0) return;
   console.log('─'.repeat(78));
   console.log('Provider indexes (probed once each, at declare time):');
@@ -481,9 +802,9 @@ function printProviderIndexes(record: any) {
 // ── the verb ──────────────────────────────────────────────────────────────────────────────────
 
 /** `--need a,b --need c` and `--need a --need b` are the same list. */
-function parseIntents(raw: any) {
+function parseIntents(raw     ) {
   const list = Array.isArray(raw) ? raw : (raw === undefined || raw === null ? [] : [raw]);
-  const out: any = [];
+  const out      = [];
   for (const entry of list) {
     for (const token of String(entry).split(',')) {
       const trimmed = token.trim();
@@ -504,18 +825,19 @@ function parseIntents(raw: any) {
  * @param {string} [options.stage] the stage id declaring the plan
  * @param {boolean} [options.json=false]
  * @param {string} [options.repoRoot] the DoFlow package root, holding the capability registries
- * @param {string} [options.stateRoot] the project the task belongs to; its state and its index
+ * @param {string} [options.stateRoot] the project the task belongs to; its state
+ * @param {string} [options.sourceRoot] the checkout whose source and index freshness are measured
  * @returns {number} exit code
  */
-function handleRetrievalPlanCommand(options: any = {}) {
-  const { taskId, action = 'report', need, stage, json = false, repoRoot, stateRoot, slug } = options;
+function handleRetrievalPlanCommand(options      = {}) {
+  const { taskId, action = 'report', need, stage, provider, attemptStatus, reason, note, json = false, repoRoot, stateRoot, sourceRoot: requestedSourceRoot, slug } = options;
 
   // NFR-001, at the boundary where a caller's input first becomes a record. `bin/doflow.js` already
   // refuses every score-shaped flag name on the command line; this is the same rule applied to the
   // option object, so a second input surface cannot arrive later without inheriting the refusal.
   try {
     assertNoScoreFields(options, '');
-  } catch (error: any) {
+  } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }
 
@@ -523,18 +845,19 @@ function handleRetrievalPlanCommand(options: any = {}) {
   // accepts it as an alias for its own default rather than reporting a usage error on an argument
   // the caller never typed — `verify` and `claim` already do exactly this.
   const resolvedAction = action === 'status' ? 'report' : action;
-  if (resolvedAction !== 'declare' && resolvedAction !== 'report') {
-    return usageError('retrieval-plan', `unknown --action '${action}'. Valid: declare, report (default)`, json);
+  if (resolvedAction !== 'declare' && resolvedAction !== 'report' && resolvedAction !== 'attempt') {
+    return usageError('retrieval-plan', `unknown --action '${action}'. Valid: declare, report (default), attempt`, json);
   }
 
   // The project the task belongs to owns both the state and the index whose age is being measured.
   // The package root owns the capability registries, and is a different directory in every install.
   const projectRoot = stateRoot || process.cwd();
+  const sourceRoot = requestedSourceRoot || projectRoot;
   const packageRoot = repoRoot || REPO_ROOT;
 
   try {
     assertSafeTaskId(taskId);
-  } catch (error: any) {
+  } catch (error     ) {
     return usageError('retrieval-plan', error.message, json, error);
   }
 
@@ -552,13 +875,35 @@ function handleRetrievalPlanCommand(options: any = {}) {
     let router;
     try {
       router = new CapabilityRouter({ repoRoot: packageRoot });
-    } catch (error: any) {
+    } catch (error     ) {
+      return usageError('retrieval-plan', error.message, json, error);
+    }
+    return declarePlan({ router, projectRoot, sourceRoot, taskId, stage, intents, json, slug });
+  }
+
+  if (resolvedAction === 'attempt') {
+    let router;
+    try {
+      router = new CapabilityRouter({ repoRoot: packageRoot });
+    } catch (error     ) {
       return usageError('retrieval-plan', error.message, json, error);
     }
-    return declarePlan({ router, projectRoot, taskId, stage, intents, json, slug });
+    return attemptPlan({
+      router,
+      projectRoot,
+      sourceRoot,
+      taskId,
+      intents,
+      provider,
+      attemptStatus,
+      reason,
+      note,
+      json,
+      slug,
+    });
   }
 
-  return reportPlan({ projectRoot, taskId, reached: new Set(intents), json, slug });
+  return reportPlan({ projectRoot, sourceRoot, taskId, reached: new Set(intents), json, slug, repoRoot: packageRoot });
 }
 
 module.exports = {
@@ -575,4 +920,8 @@ module.exports = {
   NOT_APPLICABLE,
   FRESHNESS_STATES,
   EMPTY_ANSWER_BY_FRESHNESS,
+  ATTEMPT_REASON_CODES,
+  applyReport: (disk     , taskId        ) => requirePlanForUpdate(disk, taskId),
+  applyAttempt: (disk     , taskId        ) => requirePlanForUpdate(disk, taskId),
+  _probe: (providerId        , root        , sourceModeOf     ) => freshnessEntry(providerId, root, sourceModeOf),
 };