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

package/src/runtime/evidence-fields.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/** The names a retrieval score arrives under, in camelCase (`--relevance-score` normalises here).
+ *  Exported because `bin/doflow.js` refuses the same names on the command line, and because
+ *  `retrieval-plan.ts` and `outcome.ts` refuse them on the option object a declared plan and a
+ *  terminal record are built from: one definition, three input surfaces (argv, a `--batch` JSON
+ *  file, and a verb's own options), each with exactly one enforcement point. A second copy of
+ *  this list is how one of them drifts. */
+const EVIDENCE_SCORE_FIELDS                      = new Set([
+  'confidence', 'score', 'relevance', 'relevanceScore', 'similarity',
+  'certainty', 'probability', 'rank', 'distance', 'weight',
+]);
+
+/** The one refusal message for a score offered as a property of a fact. */
+function scoreFieldRefusal(name        )         {
+  return `'${name}' is a retrieval score and this boundary records none (FR-007). Relevance is a `
+    + 'property of a search, not of a fact: stored beside the fact it is read as confidence by the '
+    + 'next worker, which is the specific interpretation the requirement forbids. Record the '
+    + 'locator and the content instead — a reader who can see where a fact came from does not need '
+    + 'to be told how sure to be.';
+}
+
+/** Refuses a score-shaped key anywhere in an item, including nested under source or locator. */
+function assertNoScoreFields(value         , prefix        )       {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+  for (const [key, inner] of Object.entries(value                           )) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    if (EVIDENCE_SCORE_FIELDS.has(key)) throw new Error(scoreFieldRefusal(dotted));
+    assertNoScoreFields(inner, dotted);
+  }
+}
+
+module.exports = {
+  EVIDENCE_SCORE_FIELDS,
+  scoreFieldRefusal,
+  assertNoScoreFields,
+};

package/src/runtime/evidence-ledger.js

@@ -8,6 +8,7 @@ const crypto = require('node:crypto');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 const { updateTaskState, readTaskState, mergeRecords } = require('./task-state.js');
 const { taskStoreDir } = require('./task-scope.js');
+const { assertNoScoreFields } = require('./evidence-fields.js');
 
 const VALID_EVIDENCE_KINDS = new Set([
   'exact-search',
@@ -129,6 +130,7 @@ class EvidenceLedger {
     if (!item || typeof item !== 'object') {
       throw new Error('Evidence item must be an object');
     }
+    assertNoScoreFields(item, '');
 
     if (!item.kind || !VALID_EVIDENCE_KINDS.has(item.kind)) {
       throw new Error(`Invalid evidence kind '${item.kind}'. Allowed: ${[...VALID_EVIDENCE_KINDS].join(', ')}`);
@@ -152,6 +154,8 @@ class EvidenceLedger {
       fileHash: item.freshness?.fileHash || null,
       observedAt: item.freshness?.observedAt || new Date().toISOString(),
       status: item.freshness?.status || 'FRESH',
+      isDirty: item.freshness?.isDirty !== undefined ? item.freshness.isDirty : null,
+      ...(item.freshness?.treeFingerprint ? { treeFingerprint: item.freshness.treeFingerprint } : {}),
     };
 
     const evidenceRecord = {
@@ -163,6 +167,7 @@ class EvidenceLedger {
       provenance,
       content: item.content || null,
       freshness,
+      ...(item.result !== undefined ? { result: item.result } : {}),
       // Which template requirements this item claims to establish. Readiness counts an item toward
       // a requirement only when the writer named it here — kind-matching alone let an item saying
       // "tests failed" satisfy a passing-baseline requirement (architecture review R1, P1).
@@ -208,6 +213,8 @@ class EvidenceLedger {
       if (filter.capability && item.source.capability !== filter.capability) continue;
       if (filter.file && item.locator.file !== filter.file) continue;
       if (filter.status && item.freshness.status !== filter.status) continue;
+      if (filter.queryRef && item.source?.queryRef !== filter.queryRef) continue;
+      if (filter.attemptRef && item.source?.attemptRef !== filter.attemptRef) continue;
       results.push(item);
     }
     return results;

package/src/runtime/freshness.js

@@ -7,6 +7,8 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFileSync } = require('node:child_process');
 const { REPO_ROOT } = require('../helper/repo-root.js');
+const { measureTreeState } = require('./source-version.js');
+
 
 // Freshness is measured against the bytes observed, not whether the file was clean at HEAD.
 // Git identity remains provenance and a conservative fallback for older records without hashes.
@@ -25,17 +27,23 @@ function measureFreshness(root        , locator     , gitCommit     )      {
 
 class FreshnessValidator {
   repoRoot        ;
+  treeRoot        ;
   gitRunner                                                 ;
                                                
+                                          
+  validatingLedger         ;
 
   /**
    * @param {Object} [options]
    * @param {string} [options.repoRoot]
+   * @param {string} [options.treeRoot]
    * @param {Function} [options.gitRunner]
    */
   constructor(options      = {}) {
     this.repoRoot = options.repoRoot || REPO_ROOT;
+    this.treeRoot = options.treeRoot || this.repoRoot;
     this.gitRunner = options.gitRunner || this.defaultGitRunner.bind(this);
+    this.validatingLedger = false;
   }
 
   defaultGitRunner(args          , cwd         = this.repoRoot)                {
@@ -121,6 +129,28 @@ class FreshnessValidator {
       return { status: 'STALE', reason: 'Already marked stale' };
     }
 
+    if (item.result === 'EMPTY' && item.freshness?.status === 'FRESH') {
+      let currentFingerprint;
+      if (this.validatingLedger) {
+        if (this.treeFingerprint === undefined) {
+          this.treeFingerprint = measureTreeState(this.treeRoot, this.gitRunner).fingerprint;
+        }
+        currentFingerprint = this.treeFingerprint;
+      } else {
+        currentFingerprint = measureTreeState(this.treeRoot, this.gitRunner).fingerprint;
+      }
+
+      if (!item.freshness?.treeFingerprint || !currentFingerprint) {
+        return { status: 'STALE', reason: 'tree-unverifiable' };
+      }
+
+      if (item.freshness.treeFingerprint !== currentFingerprint) {
+        return { status: 'STALE', reason: 'tree-changed-since-recorded' };
+      }
+
+      return { status: 'FRESH' };
+    }
+
     const targetFile = item.locator?.file;
     if (!targetFile) {
       // Evidence without a file locator (e.g. general documentation) remains fresh
@@ -157,15 +187,22 @@ class FreshnessValidator {
     
     let count = 0;
     const allEvidence = ledger.getAllEvidence();
-
-    for (const item of allEvidence) {
-      if (item.freshness?.status === 'FRESH') {
-        const check = this.checkEvidenceFreshness(item);
-        if (check.status === 'STALE') {
-          item.freshness.status = 'STALE';
-          count += 1;
+    this.treeFingerprint = undefined;
+    this.validatingLedger = true;
+    try {
+      for (const item of allEvidence) {
+        if (item.freshness?.status === 'FRESH') {
+          const check = this.checkEvidenceFreshness(item);
+          if (check.status === 'STALE') {
+            item.freshness.status = 'STALE';
+            item.freshness.staleReason = check.reason;
+            count += 1;
+          }
         }
       }
+    } finally {
+      this.treeFingerprint = undefined;
+      this.validatingLedger = false;
     }
     return count;
   }

package/src/runtime/outcome.js

@@ -55,7 +55,7 @@ const { planPath, UNREACHED } = require('./retrieval-plan.js');
 // One definition of the score refusal, applied at a further boundary. See the note on
 // EVIDENCE_SCORE_FIELDS in cli.js: a terminal state that carried a confidence would be exactly the
 // number NFR-001 exists to keep out of the one record the next worker reads first.
-const { assertNoScoreFields } = require('./cli.js');
+const { assertNoScoreFields } = require('./evidence-fields.js');
 const { finishRuntime, usageError } = require('./cli-result.js');
 const { REPO_ROOT } = require('../helper/repo-root.js');
 

package/src/runtime/readiness.js

@@ -6,6 +6,7 @@ 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 { REPO_ROOT } = require('../helper/repo-root.js');
 
 const READINESS_STATES = new Set([
@@ -211,7 +212,20 @@ 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) : []);
+    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,7 +239,8 @@ 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 = [];
@@ -242,9 +257,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
@@ -286,18 +322,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 +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,
@@ -399,6 +466,9 @@ class ReadinessEngine {
       evidenceCount: taskEvidence.length,
       unresolvableEvidence,
       staleEvidence,
+      staleAbsence,
+      ...(unreadablePlan ? { retrievalPlan: unreadablePlan } : {}),
+      ...(unboundEvidence ? { unboundEvidence } : {}),
     };
   }
 }
@@ -406,7 +476,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, 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,7 +487,7 @@ 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 }).validateLedgerFreshness(ledger);
   const claims = new ClaimsManager({ evidenceLedger: ledger, repoRoot: projectRoot });
   claims.load(taskProfile.taskId);
   claims.evaluateAll();