@khoavu882/doflow 2.0.0-beta.3 → 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.ts → artifacts.js}

@@ -13,7 +13,7 @@
  */
 
 /** Returns the body of the first `## …<title>…` section, or null when there is none. */
-function section(text: string, titlePattern: RegExp): string | null {
+function section(text        , titlePattern        )                {
   const lines = text.split('\n');
   let start = -1;
   for (let i = 0; i < lines.length; i += 1) {
@@ -28,7 +28,7 @@ function section(text: string, titlePattern: RegExp): string | null {
 }
 
 /** Splits a markdown table row into trimmed cells, or null when the line is not a row. */
-function row(line: string): string[] | null {
+function row(line        )                  {
   if (!/^\s*\|/.test(line)) return null;
   const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
   if (cells.every((c) => /^:?-{3,}:?$/.test(c))) return null;   // the header separator
@@ -36,8 +36,8 @@ function row(line: string): string[] | null {
 }
 
 /** Markdown wraps long list items; a criterion or task split over three lines is still one item. */
-function joinWrapped(body: string): string[] {
-  const out: string[] = [];
+function joinWrapped(body        )           {
+  const out           = [];
   for (const line of body.split('\n')) {
     if (/^\s+\S/.test(line) && out.length && out[out.length - 1].trim() !== '') {
       out[out.length - 1] += ` ${line.trim()}`;
@@ -52,9 +52,9 @@ function joinWrapped(body: string): string[] {
  * `requirement.md` → requirement summaries (for traceability headers) and acceptance criteria
  * (for test stubs).
  */
-function parseRequirement(text: string): any {
-  const gaps: any[] = [];
-  const requirements = new Map<string, any>();
+function parseRequirement(text        )      {
+  const gaps        = [];
+  const requirements = new Map             ();
 
   const frBody = section(text, /Functional Requirements/i) ?? '';
   const nfrBody = section(text, /Non-Functional Requirements/i) ?? '';
@@ -72,7 +72,7 @@ function parseRequirement(text: string): any {
     gaps.push({ artifact: 'requirement.md', what: 'requirement index', why: 'no `| FR-nnn | … |` table row found under a Functional Requirements heading' });
   }
 
-  const criteria: any[] = [];
+  const criteria        = [];
   const acceptanceBody = section(text, /Acceptance Criteria/i);
   if (acceptanceBody === null) {
     gaps.push({ artifact: 'requirement.md', what: 'acceptance criteria', why: 'no "Acceptance Criteria" section — no test stubs can be derived' });
@@ -96,9 +96,9 @@ function parseRequirement(text: string): any {
  * `design.md` → the component index (traceability) and whatever §4 declares as an interface
  * (carried through verbatim rather than paraphrased).
  */
-function parseDesign(text: string): any {
-  const gaps: any[] = [];
-  const components = new Map<string, any>();
+function parseDesign(text        )      {
+  const gaps        = [];
+  const components = new Map             ();
 
   const body = section(text, /Components\s*(&|and)\s*Boundaries/i) ?? '';
   for (const line of body.split('\n')) {
@@ -121,9 +121,9 @@ function parseDesign(text: string): any {
     gaps.push({ artifact: 'design.md', what: 'interface contracts', why: 'no "API / Interface Contracts" section — every emitted file falls back to a placeholder signature' });
   } else {
     const lines = contractBody.split('\n');
-    let heading: string | null = null;
-    let fence: string | null = null;
-    let buffer: string[] = [];
+    let heading                = null;
+    let fence                = null;
+    let buffer           = [];
     for (const line of lines) {
       const headingMatch = line.match(/^###\s+(.*)$/);
       if (headingMatch && fence === null) { heading = headingMatch[1].trim(); continue; }
@@ -155,9 +155,9 @@ function parseDesign(text: string): any {
 const TASK_KEYS = ['owner', 'files', 'depends-on', 'external-contract'];
 
 /** `plan.md` → the task list, which is where the intended file layout actually comes from. */
-function parsePlan(text: string): any {
-  const gaps: any[] = [];
-  const tasks: any[] = [];
+function parsePlan(text        )      {
+  const gaps        = [];
+  const tasks        = [];
 
   // Anchored on the whole heading: `### Task Summary` is orientation, not the task list, and a
   // loose match would read the summary table's rows as tasks.
@@ -182,14 +182,14 @@ function parsePlan(text: string): any {
     const stories = [...new Set(head.match(/US\d+/g) || [])].sort();
     const description = head.replace(/\[P\]/g, '').replace(/\[US\d+\]/g, '').replace(/\s{2,}/g, ' ').trim();
 
-    const fields: Record<string, string> = {};
+    const fields                         = {};
     for (const chunk of meta.split(';')) {
       const fieldMatch = chunk.match(/^\s*([a-z-]+):\s*(.*)$/);
       if (!fieldMatch || !TASK_KEYS.includes(fieldMatch[1])) continue;
       fields[fieldMatch[1]] = fieldMatch[2].trim();
     }
 
-    const list = (value: string | undefined) => (value ? value.split(',').map((v) => v.replace(/`/g, '').trim()).filter(Boolean) : []);
+    const list = (value                    ) => (value ? value.split(',').map((v) => v.replace(/`/g, '').trim()).filter(Boolean) : []);
 
     tasks.push({
       id,
@@ -211,6 +211,9 @@ function parsePlan(text: string): any {
 }
 
 module.exports = {
+  section,
+  row,
+  joinWrapped,
   parseRequirement,
   parseDesign,
   parsePlan,

package/src/runtime/scaffold/{fingerprint.ts → fingerprint.js}

@@ -17,7 +17,7 @@ const crypto = require('node:crypto');
 const FINGERPRINT_MARKER = 'doflow-scaffold-fingerprint';
 const FINGERPRINT_RE = new RegExp(`${FINGERPRINT_MARKER} sha256:([0-9a-f]{64})`);
 
-function sha256(text: string): string {
+function sha256(text        )         {
   return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
 }
 
@@ -28,7 +28,7 @@ function sha256(text: string): string {
  * reading as human-edited; and it lives in the file rather than in a side ledger, so a scaffold
  * copied, moved or committed on its own still carries the evidence needed to protect it.
  */
-function compose(emitter: any, headerLines: string[], body: string): string {
+function compose(emitter     , headerLines          , body        )         {
   const fingerprint = sha256(body);
   const header = [
     ...headerLines.map((l) => emitter.line(l)),
@@ -38,7 +38,7 @@ function compose(emitter: any, headerLines: string[], body: string): string {
 }
 
 /** The hash a file claims for its own body, and the body it actually has. */
-function inspectExisting(text: string): { claimed: string | null; actual: string | null; body: string | null } {
+function inspectExisting(text        )                                                                         {
   const match = text.match(FINGERPRINT_RE);
   if (!match) return { claimed: null, actual: null, body: null };
   const cut = text.indexOf('\n', text.indexOf(match[0]));