@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

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.
@@ -19,23 +21,58 @@ function fileHash(root        , locator     )                {
   } catch { return null; }
 }
 
-function measureFreshness(root        , locator     , gitCommit     )      {
-  return { gitCommit, fileHash: fileHash(root, locator), observedAt: new Date().toISOString(), status: 'FRESH' };
+/**
+ * IC-007: the root a relative locator.file is read in: sourceRoot, except for a locator under
+ * `agent-docs/doflow/<slug>/` whose folder is absent in sourceRoot and present in the state root
+ * (the IC-005 `feature_root` case), which resolves in the state root. Any other missing file stays
+ * missing in sourceRoot (=> STALE/missing as today for a non-redirected file).
+ */
+function fileRootFor(sourceRoot        , stateRoot        , locator     )         {
+  const file = locator?.file;
+  if (typeof file !== 'string' || file === '' || path.isAbsolute(file) || path.resolve(sourceRoot) === path.resolve(stateRoot)) return sourceRoot;
+  const normalized = path.normalize(file).replace(/\\/g, '/');
+  const match = normalized.match(/^agent-docs\/doflow\/([^/]+)\/.+/);
+  if (match) {
+    const slug = match[1];
+    const folder = path.join('agent-docs', 'doflow', slug);
+    const isDir = (root        ) => {
+      try { return fs.statSync(path.resolve(root, folder)).isDirectory(); } catch { return false; }
+    };
+    if (!isDir(sourceRoot) && isDir(stateRoot)) {
+      return stateRoot;
+    }
+  }
+  return sourceRoot;
+}
+
+// IC-007: a relative locator.file is hashed in sourceRoot, the checkout the verb runs in; `root`
+// (the record store) is only the default. An absolute locator.file is hashed as is.
+function measureFreshness(root        , locator     , gitCommit     , sourceRoot         = root)      {
+  return { gitCommit, fileHash: fileHash(fileRootFor(sourceRoot, root, locator), locator), observedAt: new Date().toISOString(), status: 'FRESH' };
 }
 
 class FreshnessValidator {
   repoRoot        ;
+  treeRoot        ;
+  sourceRoot        ;
   gitRunner                                                 ;
                                                
+                                          
+  validatingLedger         ;
 
   /**
    * @param {Object} [options]
    * @param {string} [options.repoRoot]
+   * @param {string} [options.treeRoot]
+   * @param {string} [options.sourceRoot] checkout a relative locator.file is hashed in (default repoRoot)
    * @param {Function} [options.gitRunner]
    */
   constructor(options      = {}) {
     this.repoRoot = options.repoRoot || REPO_ROOT;
+    this.treeRoot = options.treeRoot || this.repoRoot;
+    this.sourceRoot = options.sourceRoot || this.repoRoot;
     this.gitRunner = options.gitRunner || this.defaultGitRunner.bind(this);
+    this.validatingLedger = false;
   }
 
   defaultGitRunner(args          , cwd         = this.repoRoot)                {
@@ -121,6 +158,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
@@ -128,7 +187,7 @@ class FreshnessValidator {
     }
 
     if (item.freshness?.fileHash) {
-      const currentHash = fileHash(this.repoRoot, item.locator);
+      const currentHash = fileHash(fileRootFor(this.sourceRoot, this.repoRoot, item.locator), item.locator);
       return currentHash === item.freshness.fileHash
         ? { status: 'FRESH' }
         : { status: 'STALE', reason: currentHash ? 'Observed file contents changed' : 'Observed file is missing or unreadable' };
@@ -157,15 +216,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;
   }
@@ -173,5 +239,6 @@ class FreshnessValidator {
 
 module.exports = {
   measureFreshness,
+  fileRootFor,
   FreshnessValidator,
 };

package/src/runtime/git-memo.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * A call-scoped memo for git answers that cannot change while one runtime call runs (the project root
+ * of a path, a repository's common directory). One `git` child costs a process spawn, and a roadmap
+ * tick or a dispatch call asks the same question many times.
+ *
+ * The scope is the call, never the process: `withGitMemo(fn)` opens a fresh Map for `fn` (and for
+ * everything `fn` awaits), and the Map is dropped when `fn` settles. Outside a scope `memoGit` just
+ * computes, so a long-lived process, a test calling a helper directly and a nested call that opened
+ * no scope all see the answer git gives now. A scope opened inside another is the outer one.
+ *
+ * Only an answer that cannot move belongs here. A ref (HEAD, a branch tip, an index path in a
+ * worktree the call may remove and add again) is not cached: the code that moves it is not
+ * the memo's to track.
+ */
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const scope = new AsyncLocalStorage();
+
+/** Runs `fn` inside a call scope (the current one when already inside one) and returns what `fn` returns. */
+function withGitMemo   (fn         )    {
+  if (scope.getStore()) return fn();
+  return scope.run(new Map(), fn);
+}
+
+/**
+ * `compute()` once per `key` inside the current scope. A throw is not remembered, and a `compute`
+ * that returns `undefined` is not either, so a failed or inconclusive read is asked again.
+ */
+function memoGit   (key        , compute         )    {
+  const memo = scope.getStore();
+  if (!memo) return compute();
+  if (memo.has(key)) return memo.get(key);
+  const value = compute();
+  if (value !== undefined) memo.set(key, value);
+  return value;
+}
+
+/** Whether a call scope is open (for tests). */
+function inGitMemo()          { return scope.getStore() !== undefined; }
+
+module.exports = { withGitMemo, memoGit, inGitMemo };

package/src/runtime/guidance/ablation.js

@@ -0,0 +1,427 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+                                                                                          
+                                                        
+
+                            
+             
+              
+                    
+                     
+                         
+                               
+                                
+                       
+                             
+                       
+ 
+
+                             
+             
+                      
+                     
+ 
+
+                                      
+                       
+                           
+                      
+ 
+
+                                       
+                             
+                    
+                      
+                        
+                      
+                                       
+                                        
+    
+                      
+                    
+ 
+
+                                      
+                             
+                                    
+                                                       
+                                                                                    
+                                                     
+                             
+                                
+ 
+
+/**
+ * Permanent immutable set of protected safety invariant rule IDs (IC-002).
+ */
+const PERMANENT_NEVER_ABLATE_RULE_IDS = Object.freeze(new Set        ([
+  'rule-safety-conflict-order',
+  'rule-safety-temporal-awareness',
+  'rule-principles-retrieved-content-data',
+  'rule-quality-no-invented-sources',
+  'rule-quality-admit-unknowns',
+  'rule-questions-noninteractive-fallback',
+  'rule-questions-noninteractive-halt-on-blocker',
+]));
+
+/**
+ * Error thrown when an ablation attempt violates the never-ablate safety invariant (IC-002).
+ */
+class NeverAblateViolationError extends Error {
+           code = 'ERR_NEVER_ABLATE';
+           violatedRuleIds          ;
+
+  constructor(violatedRuleIds          ) {
+    super(`Cannot ablate protected rules [${violatedRuleIds.join(', ')}]: neverAblate safety invariant is violated.`);
+    this.name = 'NeverAblateViolationError';
+    this.violatedRuleIds = violatedRuleIds;
+  }
+}
+
+/**
+ * Loads and validates core/registry/rules.json (IC-001 / IC-003).
+ */
+function loadRuleLedger(options                                      )             {
+  const fsImpl = options?.fsImpl || fs;
+  const root = options?.repoRoot || REPO_ROOT;
+  const ledgerPath = path.join(root, 'core', 'registry', 'rules.json');
+
+  if (!fsImpl.existsSync(ledgerPath)) {
+    const err      = new Error(`ERR_RULE_LEDGER_INVALID: rules registry not found at ${ledgerPath}`);
+    err.code = 'ERR_RULE_LEDGER_INVALID';
+    throw err;
+  }
+
+  let text        ;
+  try {
+    text = fsImpl.readFileSync(ledgerPath, 'utf8');
+  } catch (cause     ) {
+    const err      = new Error(`ERR_RULE_LEDGER_INVALID: failed to read ${ledgerPath}: ${cause?.message || cause}`);
+    err.code = 'ERR_RULE_LEDGER_INVALID';
+    throw err;
+  }
+
+  let parsed     ;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause     ) {
+    const err      = new Error(`ERR_RULE_LEDGER_INVALID: rules.json is not valid JSON: ${cause?.message || cause}`);
+    err.code = 'ERR_RULE_LEDGER_INVALID';
+    throw err;
+  }
+
+  if (!parsed || typeof parsed !== 'object' || parsed.version !== 1 || !Array.isArray(parsed.rules)) {
+    const err      = new Error('ERR_RULE_LEDGER_INVALID: schema must have version: 1 and rules: array');
+    err.code = 'ERR_RULE_LEDGER_INVALID';
+    throw err;
+  }
+
+  const seenIds = new Set        ();
+  for (const rule of parsed.rules) {
+    if (!rule || typeof rule !== 'object') {
+      const err      = new Error('ERR_RULE_LEDGER_INVALID: rule entry must be an object');
+      err.code = 'ERR_RULE_LEDGER_INVALID';
+      throw err;
+    }
+    if (!rule.id || typeof rule.id !== 'string') {
+      const err      = new Error('ERR_RULE_LEDGER_INVALID: rule id must be a non-empty string');
+      err.code = 'ERR_RULE_LEDGER_INVALID';
+      throw err;
+    }
+    if (seenIds.has(rule.id)) {
+      const err      = new Error(`ERR_RULE_LEDGER_INVALID: duplicate rule id: ${rule.id}`);
+      err.code = 'ERR_RULE_LEDGER_INVALID';
+      throw err;
+    }
+    seenIds.add(rule.id);
+
+    // Mutual exclusion invariant
+    if (rule.neverAblate === true && rule.ablationCandidate === true) {
+      const err      = new Error(`ERR_RULE_LEDGER_INVALID: rule ${rule.id} cannot have both neverAblate: true and ablationCandidate: true`);
+      err.code = 'ERR_RULE_LEDGER_INVALID';
+      throw err;
+    }
+  }
+
+  return parsed              ;
+}
+
+/**
+ * Retrieves all rules eligible for ablation trials (neverAblate === false && ablationCandidate === true).
+ */
+function getAblationCandidates(ledger            )              {
+  if (!ledger || !Array.isArray(ledger.rules)) return [];
+  return ledger.rules.filter((rule) => !rule.neverAblate && rule.ablationCandidate === true);
+}
+
+/**
+ * Verifies that none of the target rule IDs violate the never-ablate invariant (IC-002).
+ * Throws NeverAblateViolationError (ERR_NEVER_ABLATE) if violated.
+ */
+function assertAblatable(ruleIds          , ledger            )       {
+  if (!Array.isArray(ruleIds) || ruleIds.length === 0) return;
+
+  const ruleMap = new Map                   ();
+  if (ledger && Array.isArray(ledger.rules)) {
+    for (const rule of ledger.rules) {
+      ruleMap.set(rule.id, rule);
+    }
+  }
+
+  const violated           = [];
+  for (const id of ruleIds) {
+    if (PERMANENT_NEVER_ABLATE_RULE_IDS.has(id)) {
+      violated.push(id);
+      continue;
+    }
+    const rule = ruleMap.get(id);
+    if (!rule) {
+      const err      = new Error(`ERR_RULE_NOT_FOUND: Rule '${id}' not found in rule ledger.`);
+      err.code = 'ERR_RULE_NOT_FOUND';
+      throw err;
+    }
+    if (rule.neverAblate) {
+      violated.push(id);
+    }
+  }
+
+  if (violated.length > 0) {
+    throw new NeverAblateViolationError(violated);
+  }
+}
+
+/**
+ * Masks designated rules from the guidance string without altering disk files (IC-003).
+ */
+function maskGuidance(options                     )         {
+  const { guidanceText, ablatedRuleIds } = options;
+  if (!ablatedRuleIds || ablatedRuleIds.length === 0) {
+    return guidanceText;
+  }
+
+  const ledger = options.ledger || loadRuleLedger();
+  assertAblatable(ablatedRuleIds, ledger);
+
+  const ruleMap = new Map                   ();
+  for (const rule of ledger.rules) {
+    ruleMap.set(rule.id, rule);
+  }
+
+  const targets = ablatedRuleIds.map((id) => ruleMap.get(id) ).filter(Boolean);
+  if (targets.length === 0) return guidanceText;
+
+  const targetSignatures = targets.map((target) => {
+    const rawStatement = target.statement.replace(/\.\.\./g, ' ').trim();
+    const cleanStatement = rawStatement.replace(/[`*#_]/g, '').trim();
+    const prefix = cleanStatement.slice(0, 36).toLowerCase();
+
+    // Support section-headed rules (e.g. "Trade-offs: Classify a decision...")
+    const colonIdx = cleanStatement.indexOf(':');
+    let headingPrefix = '';
+    let bodyPrefix = '';
+    if (colonIdx > 0) {
+      headingPrefix = cleanStatement.slice(0, colonIdx).trim().toLowerCase();
+      bodyPrefix = cleanStatement.slice(colonIdx + 1).trim().slice(0, 36).toLowerCase();
+    }
+
+    return {
+      id: target.id,
+      tag: target.tag,
+      cleanStatement,
+      prefix,
+      headingPrefix,
+      bodyPrefix,
+    };
+  });
+
+  const lines = guidanceText.split('\n');
+  const filteredLines           = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const cleanLine = line.replace(/[`*#_]/g, '').toLowerCase().trim();
+
+    let matchesTarget = false;
+    for (const sig of targetSignatures) {
+      if (line.includes(sig.id)) {
+        matchesTarget = true;
+        break;
+      }
+      if (sig.prefix && cleanLine.includes(sig.prefix)) {
+        matchesTarget = true;
+        break;
+      }
+      if (sig.bodyPrefix && cleanLine.includes(sig.bodyPrefix)) {
+        matchesTarget = true;
+        break;
+      }
+      if (sig.headingPrefix && (cleanLine === sig.headingPrefix || cleanLine.startsWith(sig.headingPrefix))) {
+        matchesTarget = true;
+        break;
+      }
+      if (sig.cleanStatement && cleanLine.length > 10 && sig.cleanStatement.toLowerCase().includes(cleanLine)) {
+        matchesTarget = true;
+        break;
+      }
+    }
+
+    if (!matchesTarget) {
+      filteredLines.push(line);
+    }
+  }
+
+  return filteredLines.join('\n');
+}
+
+/**
+ * Helper to count total test runs across cases for infraShare computation.
+ */
+function countRuns(scores                          )         {
+  if (!scores || typeof scores !== 'object') return 0;
+  return Object.values(scores).reduce((acc, curr) => acc + (Array.isArray(curr) ? curr.length : 0), 0);
+}
+
+/**
+ * Noise-floor decision bridge evaluating statistical ablation success via bench/noise.ts decide() (IC-004).
+ */
+function evaluateAblationNoiseDecision({
+  baselineScores,
+  candidateScores,
+  noiseArtifact,
+  noiseConfig,
+  scope = 'heldout',
+}   
+                                           
+                                            
+                      
+                    
+                                         
+ ) {
+  let decide     ;
+  try {
+    const noiseMod = require('../../../bench/noise.ts');
+    decide = noiseMod.decide;
+  } catch (err     ) {
+    const error      = new Error(`ERR_BENCH_NOT_FOUND: bench/noise.ts is only available in developer checkouts: ${err?.message || err}`);
+    error.code = 'ERR_BENCH_NOT_FOUND';
+    throw error;
+  }
+
+  const noise = noiseArtifact?.scopes?.[scope]?.noise ?? null;
+  const cfg = noiseConfig || {};
+  const mde = typeof cfg.mde === 'number' ? cfg.mde : 0.05;
+  const maxInfraShare = typeof cfg.maxInfraShare === 'number' ? cfg.maxInfraShare : 0.10;
+  const seed = Number.isInteger(cfg.seed) ? cfg.seed : 96;
+
+  const decision = decide({
+    scope,
+    baseline: baselineScores,
+    candidate: candidateScores,
+    excluded: {
+      baseline: { runs: countRuns(baselineScores), excluded: 0 },
+      candidate: { runs: countRuns(candidateScores), excluded: 0 },
+    },
+    noise,
+    mde,
+    maxInfraShare,
+    seed,
+  });
+
+  const rawVerdict = decision.verdict;
+  const recommendation = (rawVerdict === 'gain-above-noise' || rawVerdict === 'within-noise')
+    ? 'merge-candidate'
+    : 'do-not-merge';
+
+  return {
+    verdict: rawVerdict,
+    recommendation,
+    gain: decision.gain,
+    ci95: decision.ci95,
+    band: decision.band,
+    detail: decision.detail,
+  };
+}
+
+/**
+ * Loads baseline core guidance from filesystem for trial evaluation.
+ */
+function loadCanonicalGuidance(repoRoot        , fsImpl     )         {
+  const guidanceDir = path.join(repoRoot, 'core', 'shared', 'guidance');
+  const files = [
+    path.join(guidanceDir, 'PRINCIPLES.md'),
+    path.join(guidanceDir, 'rules', 'RULES.md'),
+  ];
+  const parts           = [];
+  for (const f of files) {
+    if (fsImpl.existsSync(f)) {
+      parts.push(fsImpl.readFileSync(f, 'utf8'));
+    }
+  }
+  return parts.join('\n\n');
+}
+
+/**
+ * Runs an ablation trial evaluating behavioral impact against baseline repeats (IC-003).
+ */
+function runAblationTrial(options                      )                      {
+  const repoRoot = options?.repoRoot || REPO_ROOT;
+  const fsImpl = (options       )?.fsImpl || fs;
+  const ledger = options.ledger || loadRuleLedger({ repoRoot, fsImpl });
+
+  assertAblatable(options.candidateRuleIds, ledger);
+
+  const baseText = options.guidanceText || loadCanonicalGuidance(repoRoot, fsImpl);
+  const maskedText = maskGuidance({
+    guidanceText: baseText,
+    ablatedRuleIds: options.candidateRuleIds,
+    ledger,
+  });
+
+  const originalLength = Buffer.byteLength(baseText, 'utf8');
+  const maskedLength = Buffer.byteLength(maskedText, 'utf8');
+  const byteDelta = originalLength - maskedLength;
+
+  let trialVerdict                                                                      = 'inconclusive';
+  let recommendation                                     = 'do-not-merge';
+  let heldoutGain                = null;
+  let ci95                          = null;
+
+  if (options.simulationScores) {
+    const decision = evaluateAblationNoiseDecision({
+      baselineScores: options.simulationScores.baseline,
+      candidateScores: options.simulationScores.candidate,
+      noiseArtifact: options.noiseArtifact,
+      noiseConfig: options.noiseConfig,
+      scope: 'heldout',
+    });
+    trialVerdict = decision.verdict                                                                       ;
+    recommendation = decision.recommendation                                      ;
+    heldoutGain = decision.gain;
+    ci95 = decision.ci95;
+  }
+
+  return {
+    candidateRuleIds: options.candidateRuleIds,
+    maskedGuidanceLengthBytes: maskedLength,
+    byteDelta,
+    trialVerdict,
+    recommendation,
+    heldoutGain,
+    ci95,
+  };
+}
+
+module.exports = {
+  PERMANENT_NEVER_ABLATE_RULE_IDS,
+  NeverAblateViolationError,
+  loadRuleLedger,
+  getAblationCandidates,
+  assertAblatable,
+  maskGuidance,
+  evaluateAblationNoiseDecision,
+  runAblationTrial,
+};