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

package/src/runtime/retrieval-record.js

@@ -0,0 +1,223 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { taskStoreDir, 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');
+const { projectRoot: lifecycleProjectRoot } = require('./lifecycle/root.js');
+
+/**
+ * Path of a task's retrieval-plan store.
+ *
+ * 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]
+ * @returns {string}
+ */
+function planPath(projectRoot     , taskId     , slug      = null)         {
+  const dir = taskStoreDir({ projectRoot, store: 'retrieval', taskId: assertSafeTaskId(taskId), slug });
+  return path.join(dir, `${taskId}.json`);
+}
+
+/**
+ * Reads and validates one task's retrieval plan via readTaskState.
+ * Returns null when the plan file does not exist.
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} [slug]
+ * @param {any} [fsImpl]
+ * @returns {any|null}
+ */
+function readPlan(projectRoot     , taskId     , slug      = null, fsImpl      = fs)             {
+  const file = planPath(projectRoot, taskId, slug);
+  return readTaskState(fsImpl, file);
+}
+
+/**
+ * Updates a task's retrieval plan under the task-state lock.
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} slug
+ * @param {(disk: any|null) => any} build
+ * @param {any} [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 });
+}
+
+/** Move a syntactically unreadable plan aside before its replacement is written under the lock. */
+function moveCorruptPlanAside(projectRoot     , taskId     , slug      = null, fsImpl      = fs)                {
+  const file = planPath(projectRoot, taskId, slug);
+  if (!fsImpl.existsSync(file)) return null;
+  try {
+    JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    return null;
+  } catch (error     ) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const corruptFile = `${file}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fsImpl.renameSync(file, corruptFile);
+    return corruptFile;
+  }
+}
+
+/**
+ * Mints a new plan id: rp_<base36 ms>_<4 hex>.
+ * @returns {string}
+ */
+function mintPlanId()         {
+  return `rp_${Date.now().toString(36)}_${crypto.randomBytes(2).toString('hex')}`;
+}
+
+/**
+ * Formats declared intents from a plan: sorted, comma-joined, or 'none declared'.
+ *
+ * @param {any} plan
+ * @returns {string}
+ */
+function declaredIntentList(plan     , sep = ', ')         {
+  const declaredIntents = Array.isArray(plan?.needs)
+    ? plan.needs.map((n     ) => n.intent).filter(Boolean).sort()
+    : [];
+  return declaredIntents.length > 0 ? declaredIntents.join(sep) : 'none declared';
+}
+
+/**
+ * Resolves a declared need from a plan for a given intent.
+ *
+ * @param {any} plan
+ * @param {string} intent
+ * @param {string} taskId
+ * @returns {{ ok: true, queryRef: string, need: any } | { ok: false, message: string }}
+ */
+function resolveNeed(plan     , intent        , taskId        )      {
+  if (!plan) {
+    const message = `no retrieval plan is declared for task '${taskId}', so --need '${intent}' names nothing. Declare one first: doflow retrieval-plan --task-id ${taskId} --action declare --need ${intent}, then re-run.`;
+    return { ok: false, message };
+  }
+  const list = declaredIntentList(plan);
+
+  if (!plan.planId) {
+    const message = `the retrieval plan for task '${taskId}' was declared before query binding and has no plan id. Re-declare it: doflow retrieval-plan --task-id ${taskId} --action declare --need ${declaredIntentList(plan, ',')}, then re-run.`;
+    return { ok: false, message };
+  }
+
+  const need = Array.isArray(plan.needs) ? plan.needs.find((n     ) => n.intent === intent) : null;
+  if (!need) {
+    const message = `'${intent}' is not a declared need of task '${taskId}' (plan ${plan.planId}). Declared: ${list}. Re-run with one of them, or re-declare the plan with this need.`;
+    return { ok: false, message };
+  }
+
+  if (!need.queryRef) {
+    const message = `the retrieval plan for task '${taskId}' was declared before query binding and has no plan id. Re-declare it: doflow retrieval-plan --task-id ${taskId} --action declare --need ${declaredIntentList(plan, ',')}, then re-run.`;
+    return { ok: false, message };
+  }
+
+  return {
+    ok: true,
+    queryRef: need.queryRef,
+    need,
+  };
+}
+
+/**
+ * Reads the 070 active attempt ref for a task, returning `${taskId}#${token}` or null.
+ *
+ * Resolves the feature slug via resolveTaskScope, reads storeFile(lifecycleProjectRoot(projectRoot), featureSlug),
+ * and finds the active attempt for the task. If no slug, no store, no entry or no active attempt exists,
+ * or if any failure occurs finding or reading the store, returns null (IC-005: "no attempt" never fails the write).
+ *
+ * @param {string} projectRoot
+ * @param {string} taskId
+ * @param {string|null} [slug]
+ * @param {any} [fsImpl]
+ * @returns {string|null}
+ */
+function activeAttemptRef(projectRoot     , taskId     , slug      = null, fsImpl      = fs, attemptRoot      = null)                {
+  try {
+    const featureSlug = resolveTaskScope({ projectRoot, taskId, slug }).slug;
+    if (!featureSlug) return null;
+
+    const file = storeFile(attemptRoot || lifecycleProjectRoot(projectRoot), featureSlug);
+    if (!fsImpl.existsSync(file)) return null;
+
+    const data = readTaskState(fsImpl, file);
+    if (!data || !data.tasks || !data.tasks[taskId]) return null;
+
+    const active = activeAttempt(data.tasks[taskId]);
+    if (!active || active.token === undefined || active.token === null) return null;
+
+    return `${taskId}#${active.token}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Binds active evidence to declared query refs and explains evidence that could have matched. */
+function bindEvidence(plan     , items       ) {
+  const byNeed = new Map               ();
+  const unbound        = [];
+  const needs = Array.isArray(plan?.needs) ? plan.needs : [];
+  for (const need of needs) byNeed.set(need.intent, []);
+  for (const item of items) {
+    if (item.status !== 'active') continue;
+    const source = item.source || {};
+    const exact = needs.find((need     ) => need.queryRef && need.queryRef === source.queryRef);
+    if (exact) {
+      if (plan.attemptRef && source.attemptRef && plan.attemptRef !== source.attemptRef) {
+        unbound.push({ id: item.id, cause: 'other-attempt' });
+      } else {
+        const matches = byNeed.get(exact.intent);
+        if (matches) matches.push(item);
+      }
+      continue;
+    }
+    if (source.queryRef) {
+      unbound.push({ id: item.id, cause: 'replaced-plan' });
+    } else if (needs.some((need     ) => need.capability && need.capability === source.capability)) {
+      unbound.push({ id: item.id, cause: 'no-query-ref' });
+    }
+  }
+  return { byNeed, unbound };
+}
+
+/** Selects the highest-precedence recorded attempt, with the earliest attempt winning ties. */
+function deriveOutcome(need     ) {
+  const precedence                         = { RETRIEVED: 0, EMPTY: 1, UNVERIFIED: 3, UNREACHED: 4 };
+  const attempts = (Array.isArray(need?.attempts) ? need.attempts : []).filter((attempt     ) =>
+    !(attempt.recordedBy === 'derived' && attempt.basis !== 'report-need'
+      && (!Array.isArray(attempt.evidenceIds) || attempt.evidenceIds.length === 0)));
+  const ranked = [...attempts].sort((a, b) => {
+    const rank = (attempt     ) => attempt.status === 'EMPTY' && ['STALE', 'UNKNOWN'].includes(attempt.indexState)
+      ? (attempt.indexState === 'STALE' ? 2 : 3)
+      : (precedence[attempt.status] ?? 4);
+    return rank(a) - rank(b) || a.n - b.n;
+  });
+  const winner = ranked[0];
+  return {
+    result: winner ? winner.status : 'UNREACHED',
+    resolvedBy: winner ? winner.n : null,
+    viaFallback: Boolean(winner && winner.role === 'fallback'),
+  };
+}
+
+module.exports = {
+  planPath,
+  readPlan,
+  updatePlan,
+  moveCorruptPlanAside,
+  mintPlanId,
+  resolveNeed,
+  activeAttemptRef,
+  declaredIntentList,
+  bindEvidence,
+  deriveOutcome,
+};

package/src/runtime/scaffold/artifacts.js

@@ -211,6 +211,9 @@ function parsePlan(text        )      {
 }
 
 module.exports = {
+  section,
+  row,
+  joinWrapped,
   parseRequirement,
   parseDesign,
   parsePlan,

package/src/runtime/source-version.js

@@ -0,0 +1,289 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+                     
+                           
+                            
+                        
+                             
+ 
+
+                                                                 
+
+                         
+                           
+                          
+                          
+ 
+
+const treeStateMemo = new Map                   ();
+
+function clearTreeStateCache()       {
+  treeStateMemo.clear();
+}
+
+/**
+ * Finds the top of the git work tree and root's relative prefix below it using filesystem reads only.
+ */
+function findWorkTreeTop(root        )                                                {
+  let current = path.resolve(root);
+  while (true) {
+    try {
+      if (fs.existsSync(path.join(current, '.git'))) {
+        const rel = path.relative(current, path.resolve(root));
+        const prefix = rel && rel !== '.' ? (rel.split(path.sep).join('/') + '/') : '';
+        return { top: current, prefix };
+      }
+    } catch {
+      break;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return { top: null, prefix: null };
+}
+
+function defaultGitRunner(args          , cwd        )                {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      timeout: 2000,
+      maxBuffer: 256 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Measures the repository's HEAD commit, dirty paths and tree fingerprint with one git status call.
+ */
+function measureTreeState(root        , runner            )            {
+  const absRoot = path.resolve(root);
+  if (!runner && treeStateMemo.has(absRoot)) {
+    return treeStateMemo.get(absRoot) ;
+  }
+
+  const { top: workTreeTop, prefix } = findWorkTreeTop(absRoot);
+  if (!workTreeTop) {
+    const unmeasured            = {
+      gitCommit: null,
+      dirty: null,
+      prefix: null,
+      fingerprint: null,
+    };
+    if (!runner) treeStateMemo.set(absRoot, unmeasured);
+    return unmeasured;
+  }
+
+  const args = ['-C', absRoot, 'status', '--porcelain=v2', '--branch', '-z', '--untracked-files=all', '--ignored=matching'];
+  const raw = runner ? runner(args, absRoot) : defaultGitRunner(args, absRoot);
+
+  if (raw === null || raw === undefined) {
+    const commit = runner
+      ? runner(['-C', absRoot, 'rev-parse', 'HEAD'], absRoot)
+      : defaultGitRunner(['-C', absRoot, 'rev-parse', 'HEAD'], absRoot);
+    const failed            = {
+      gitCommit: commit?.trim() || null,
+      dirty: null,
+      prefix,
+      fingerprint: null,
+    };
+    if (!runner) treeStateMemo.set(absRoot, failed);
+    return failed;
+  }
+
+  const tokens = raw.split('\0');
+  let gitCommit                = null;
+  const dirty = new Set        ();
+  const entryRecords           = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token) continue;
+
+    if (token.startsWith('# branch.oid ')) {
+      const oid = token.slice('# branch.oid '.length).trim();
+      if (oid && oid !== '(initial)') {
+        gitCommit = oid;
+      }
+      continue;
+    }
+    if (token.startsWith('# ')) {
+      continue;
+    }
+
+    if (token.startsWith('! ')) {
+      const ignoredPath = token.slice(2);
+      if (prefix && (ignoredPath === prefix.slice(0, -1) || ignoredPath === `${prefix.slice(0, -1)}/`)) {
+        const ignored            = { gitCommit, dirty: null, prefix, fingerprint: null };
+        if (!runner) treeStateMemo.set(absRoot, ignored);
+        return ignored;
+      }
+      continue;
+    }
+
+    let dirtyPath                = null;
+    let entryText = token;
+
+    if (token.startsWith('1 ')) {
+      const parts = token.split(' ');
+      dirtyPath = parts.slice(8).join(' ');
+      dirty.add(dirtyPath);
+    } else if (token.startsWith('2 ')) {
+      const parts = token.split(' ');
+      dirtyPath = parts.slice(9).join(' ');
+      dirty.add(dirtyPath);
+      if (i + 1 < tokens.length && tokens[i + 1]) {
+        const origPath = tokens[i + 1];
+        dirty.add(origPath);
+        entryText = `${token}\0${origPath}`;
+        i++;
+      }
+    } else if (token.startsWith('u ')) {
+      const parts = token.split(' ');
+      dirtyPath = parts.slice(10).join(' ');
+      dirty.add(dirtyPath);
+    } else if (token.startsWith('? ')) {
+      dirtyPath = token.slice(2);
+      dirty.add(dirtyPath);
+    }
+
+    if (dirtyPath !== null) {
+      const statePath = `${prefix}.doflow/state/`;
+      const normalizedDirtyPath = dirtyPath.split(path.sep).join('/');
+      const shouldFingerprint = !normalizedDirtyPath.startsWith(statePath);
+      if (shouldFingerprint && /^(?:1|2|u) \S+ S\.M /.test(token)) {
+        const nestedRoot = path.resolve(workTreeTop, dirtyPath);
+        const nested = measureNestedRepository(nestedRoot);
+        if (nested === null) {
+          const unknown            = { gitCommit, dirty: null, prefix, fingerprint: null };
+          if (!runner) treeStateMemo.set(absRoot, unknown);
+          return unknown;
+        }
+        entryRecords.push(`${entryText}:nested:${nested}`);
+        continue;
+      }
+      if (shouldFingerprint && token.startsWith('? ')) {
+        const nestedRoot = path.resolve(workTreeTop, dirtyPath.replace(/\/$/, ''));
+        if (fs.existsSync(path.join(nestedRoot, '.git'))) {
+          const nested = measureNestedRepository(nestedRoot);
+          if (nested === null) {
+            const unknown            = { gitCommit, dirty: null, prefix, fingerprint: null };
+            if (!runner) treeStateMemo.set(absRoot, unknown);
+            return unknown;
+          }
+          entryRecords.push(`${entryText}:nested:${nested}`);
+          continue;
+        }
+      }
+      if (!shouldFingerprint) continue;
+      let statTerm = 'absent';
+      try {
+        const absPath = path.resolve(workTreeTop, dirtyPath);
+        const st = fs.statSync(absPath);
+        statTerm = `${st.size}:${st.mtimeMs}`;
+      } catch {
+        statTerm = 'absent';
+      }
+      entryRecords.push(`${entryText}:${statTerm}`);
+    }
+  }
+
+  if (!gitCommit) {
+    const uncommitted            = {
+      gitCommit: null,
+      dirty: null,
+      prefix,
+      fingerprint: null,
+    };
+    if (!runner) treeStateMemo.set(absRoot, uncommitted);
+    return uncommitted;
+  }
+
+  const hash = crypto.createHash('sha256');
+  hash.update(gitCommit);
+  hash.update('\0');
+  hash.update(entryRecords.sort().join('\0'));
+  const fingerprint = `sha256:${hash.digest('hex')}`;
+
+  const state            = {
+    gitCommit,
+    dirty,
+    prefix,
+    fingerprint,
+  };
+  if (!runner) treeStateMemo.set(absRoot, state);
+  return state;
+}
+
+function measureNestedRepository(root        )                {
+  try {
+    const gitEntry = path.join(root, '.git');
+    const gitStat = fs.statSync(gitEntry);
+    const gitDir = gitStat.isFile()
+      ? path.resolve(root, fs.readFileSync(gitEntry, 'utf8').trim().replace(/^gitdir:\s*/, ''))
+      : gitEntry;
+    const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+    const headRef = head.startsWith('ref: ')
+      ? fs.readFileSync(path.join(gitDir, head.slice('ref: '.length)), 'utf8').trim()
+      : head;
+    const index = fs.statSync(path.join(gitDir, 'index'));
+    return `${head}:${headRef}:${index.mtimeMs}:${index.size}`;
+  } catch {
+    return null;
+  }
+}
+
+function fileHash(root        , locator     )                {
+  if (!locator?.file) return null;
+  try {
+    const absolute = path.resolve(root, locator.file);
+    if (!fs.statSync(absolute).isFile()) return null;
+    return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(absolute)).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derives source version { gitCommit, fileHash, isDirty } for a given locator and tree state.
+ */
+function sourceVersionFor(root        , locator     , state           )                {
+  const hash = fileHash(root, locator);
+  if (!locator?.file || !state || !state.dirty) {
+    return {
+      gitCommit: state?.gitCommit ?? null,
+      fileHash: hash,
+      isDirty: null,
+    };
+  }
+
+  const prefix = state.prefix || '';
+  if (path.isAbsolute(locator.file)) {
+    return { gitCommit: state.gitCommit ?? null, fileHash: hash, isDirty: null };
+  }
+  const candidate = path.posix.normalize(`${prefix}${locator.file.split(path.sep).join('/')}`).replace(/^\.\//, '');
+  const isDirty = state.dirty.has(candidate);
+
+  return {
+    gitCommit: state.gitCommit ?? null,
+    fileHash: hash,
+    isDirty,
+  };
+}
+
+module.exports = {
+  measureTreeState,
+  sourceVersionFor,
+  clearTreeStateCache,
+};

package/src/runtime/task-attempts.js

@@ -411,5 +411,5 @@ function handleTaskAttemptCommand({
 
 module.exports = {
   handleTaskAttemptCommand, checkCompletion, claim, finish, release, status, loadPlan, taskLineHash,
-  storeFile, TaskAttemptError, MODES, RESULTS, ACTIONS,
+  storeFile, TaskAttemptError, MODES, RESULTS, ACTIONS, activeAttempt,
 };

package/src/runtime/task-scope.js

@@ -4,7 +4,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { resolveActiveFeature } = require('./feature-resolve.js');
+const featureResolve = require('./feature-resolve.js');
 
 // Which feature a task record belongs to (feature 045, IC-001/IC-002).
 //
@@ -37,6 +37,9 @@ function invalidSlugRefusal(slug     )
 /** (projectRoot, slug) -> { slug, hasRegister } | { reason }. One resolver spawn per key per process. */
 const featureCache = new Map             ();
 
+/** The resolver's raw answer, including thrown failures, shared by every consumer in this process. */
+const resolvedFeatureCache = new Map                                             ();
+
 /** A slug the CLI named explicitly (`--slug`), applied to every store call in this process that was
  * not given its own. The dispatcher sets it once so the verbs whose handlers build their ledger
  * internally (readiness, evidence) route the same way as the ones that take `slug` directly. */
@@ -48,6 +51,28 @@ function setDefaultSlug(slug     )       {
 
 function clearTaskScopeCache()       {
   featureCache.clear();
+  resolvedFeatureCache.clear();
+}
+
+/**
+ * Resolve once per process per (root, slug). The resolver spawns do-paths.sh, and every store and
+ * the decisions lookup must see the same answer.
+ */
+function resolveFeature({ projectRoot, slug = null }                                               )      {
+  const key = `${path.resolve(projectRoot)}\0${slug || ''}`;
+  if (resolvedFeatureCache.has(key)) {
+    const cached = resolvedFeatureCache.get(key) ;
+    if ('error' in cached) throw cached.error;
+    return cached.value;
+  }
+  try {
+    const value = featureResolve.resolveActiveFeature({ projectRoot, slug: slug || null });
+    resolvedFeatureCache.set(key, { value });
+    return value;
+  } catch (error) {
+    resolvedFeatureCache.set(key, { error });
+    throw error;
+  }
 }
 
 /** The resolver reports the git top level, which is the project root or one of its ancestors, and
@@ -71,7 +96,7 @@ function featureFor(projectRoot        , slug                           )      {
   let value      = { reason: 'no-feature' };
   try {
     if (hasFeatureFolderAbove(projectRoot)) {
-      const found = resolveActiveFeature({ projectRoot, slug: slug || null });
+      const found = resolveFeature({ projectRoot, slug: slug || null });
       if (!found.error && found.paths && isSafeSlug(found.paths.feature_slug)) {
         value = { slug: found.paths.feature_slug, hasRegister: found.paths.has_decisions === true, exists: fs.existsSync(found.featureDir) };
       }
@@ -127,4 +152,4 @@ function taskStoreDir({ projectRoot, store, taskId, slug = null }
   return namespace ? path.join(base, namespace) : base;
 }
 
-module.exports = { resolveTaskScope, taskStoreDir, setDefaultSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };
+module.exports = { resolveFeature, resolveTaskScope, taskStoreDir, setDefaultSlug, clearTaskScopeCache, isSafeSlug, invalidSlugRefusal, slugNamesNoFeature };