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

package/src/runtime/{decision-register.ts → decision-register.js}

@@ -17,10 +17,10 @@
 
 const nodeFs = require('node:fs');
 const path = require('node:path');
-const { acquireLock } = require('./task-state.ts');
-const { resolveActiveFeature } = require('./feature-resolve.ts');
-const { compactHistory } = require('./history-compactor.ts');
-const { finishRuntime, usageError } = require('./cli-result.ts');
+const { acquireLock } = require('./task-state.js');
+const { resolveActiveFeature } = require('./feature-resolve.js');
+const { compactHistory } = require('./history-compactor.js');
+const { finishRuntime, usageError } = require('./cli-result.js');
 
 const REGISTER_VERSION = 1;
 const TOPIC_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -30,7 +30,7 @@ const REF_RE = /^[A-Za-z]+-?[0-9]+$/;
 const DEC_RE = /^DEC-[0-9]{3,}$/;
 const STAGES = ['discovery', 'design', 'planning', 'implementation', 'verification', 'review'];
 /** Channel -> who decided. The caller names the channel; `decidedBy` follows from it. */
-const CHANNEL_DECIDED_BY: Record<string, string> = { question: 'user', gate: 'user', prompt: 'user', default: 'agent', resolution: 'agent' };
+const CHANNEL_DECIDED_BY                         = { question: 'user', gate: 'user', prompt: 'user', default: 'agent', resolution: 'agent' };
 const ITEM_KEYS = ['topic', 'statement', 'channel', 'stage', 'rationale', 'supersedes', 'refs', 'source'];
 const REQUIRED_KEYS = ['topic', 'statement', 'channel', 'stage', 'rationale'];
 
@@ -44,9 +44,9 @@ class DecisionUsageError extends Error {}
 
 /** A finding the caller must act on (exit 1). */
 class DecisionFinding extends Error {
-  finding: string;
+  finding        ;
 
-  constructor(finding: string, message: string) {
+  constructor(finding        , message        ) {
     super(message);
     this.finding = finding;
   }
@@ -54,19 +54,19 @@ class DecisionFinding extends Error {
 
 // ── paths ──────────────────────────────────────────────────────────────────────────────────────
 
-function registerFile(featureDir: string): string { return path.join(featureDir, 'decisions', 'register.json'); }
-function liveViewFile(featureDir: string): string { return path.join(featureDir, 'decisions.md'); }
-function archiveFile(featureDir: string): string { return path.join(featureDir, 'decisions', 'archive.md'); }
+function registerFile(featureDir        )         { return path.join(featureDir, 'decisions', 'register.json'); }
+function liveViewFile(featureDir        )         { return path.join(featureDir, 'decisions.md'); }
+function archiveFile(featureDir        )         { return path.join(featureDir, 'decisions', 'archive.md'); }
 
 // ── register io ────────────────────────────────────────────────────────────────────────────────
 
-function readRegister(featureDir: string, fsImpl: any = nodeFs): any {
+function readRegister(featureDir        , fsImpl      = nodeFs)      {
   const file = registerFile(featureDir);
   if (!fsImpl.existsSync(file)) return null;
-  let data: any;
+  let data     ;
   try {
     data = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
-  } catch (error: any) {
+  } catch (error     ) {
     throw new DecisionUsageError(`${file} is not valid JSON (${error.message}). The register is written atomically, so a torn file means outside interference; restore it from version control.`);
   }
   if (!data || data.version !== REGISTER_VERSION || !Array.isArray(data.decisions) || !Number.isInteger(data.nextId)) {
@@ -75,62 +75,62 @@ function readRegister(featureDir: string, fsImpl: any = nodeFs): any {
   return data;
 }
 
-function writeAtomic(fsImpl: any, file: string, content: string): void {
+function writeAtomic(fsImpl     , file        , content        )       {
   fsImpl.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.tmp`;
   try {
     fsImpl.writeFileSync(tmp, content, 'utf8');
     fsImpl.renameSync(tmp, file);
-  } catch (error: any) {
+  } catch (error     ) {
     try { fsImpl.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
     throw error;
   }
 }
 
 /** Writes only when the content differs, so re-rendering an unchanged view is a no-op. */
-function writeIfChanged(fsImpl: any, file: string, content: string): void {
+function writeIfChanged(fsImpl     , file        , content        )       {
   if (fsImpl.existsSync(file) && fsImpl.readFileSync(file, 'utf8') === content) return;
   writeAtomic(fsImpl, file, content);
 }
 
-function writeRegister(fsImpl: any, featureDir: string, register: any): void {
+function writeRegister(fsImpl     , featureDir        , register     )       {
   writeAtomic(fsImpl, registerFile(featureDir), `${JSON.stringify(register, null, 2)}\n`);
 }
 
-function renderViews(fsImpl: any, featureDir: string, register: any): void {
+function renderViews(fsImpl     , featureDir        , register     )       {
   writeIfChanged(fsImpl, liveViewFile(featureDir), renderLiveView(register));
   writeIfChanged(fsImpl, archiveFile(featureDir), renderArchive(register));
 }
 
 // ── ordering and ids ───────────────────────────────────────────────────────────────────────────
 
-function idNumber(id: string): number { return Number(id.slice(4)); }
-function formatId(n: number): string { return `DEC-${String(n).padStart(3, '0')}`; }
-function byId(a: any, b: any): number { return idNumber(a.id) - idNumber(b.id); }
-function byTopic(a: any, b: any): number { return a.topic < b.topic ? -1 : a.topic > b.topic ? 1 : idNumber(a.id) - idNumber(b.id); }
-function liveOf(register: any): any[] { return register.decisions.filter((d: any) => d.status === 'live'); }
+function idNumber(id        )         { return Number(id.slice(4)); }
+function formatId(n        )         { return `DEC-${String(n).padStart(3, '0')}`; }
+function byId(a     , b     )         { return idNumber(a.id) - idNumber(b.id); }
+function byTopic(a     , b     )         { return a.topic < b.topic ? -1 : a.topic > b.topic ? 1 : idNumber(a.id) - idNumber(b.id); }
+function liveOf(register     )        { return register.decisions.filter((d     ) => d.status === 'live'); }
 
 // ── renderers ──────────────────────────────────────────────────────────────────────────────────
 
 /** `\` is escaped first, so a statement ending in one cannot escape the pipe that closes the cell
  * (IC-007); `|` would end the cell; `<` could open an HTML comment that hides every later row. */
-function cell(text: any): string { return String(text).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/</g, '\\<'); }
+function cell(text     )         { return String(text).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/</g, '\\<'); }
 
 /** Archive text is read by people and agents, never as HTML: `<` is escaped so `<!--` cannot hide later entries. */
-function plain(text: any): string { return String(text).replace(/</g, '\\<'); }
+function plain(text     )         { return String(text).replace(/</g, '\\<'); }
 
 /**
  * A one-line rationale reads inline. A longer one goes in a blockquote under the bullet, every line
  * prefixed, so no line of it can start a heading or pose as one of the entry's own bullets.
  */
-function rationaleLines(rationale: any): string[] {
+function rationaleLines(rationale     )           {
   const parts = plain(rationale).split(/\r\n|[\n\r\u2028\u2029\u0085]/);
   if (parts.length === 1) return [`- **Rationale:** ${parts[0]}`];
-  return ['- **Rationale:**', ...parts.map((l: string) => (l === '' ? '  >' : `  > ${l}`))];
+  return ['- **Rationale:**', ...parts.map((l        ) => (l === '' ? '  >' : `  > ${l}`))];
 }
 
 /** IC-007. Size depends on the number of live topics, never on how many decisions were made. */
-function renderLiveView(register: any): string {
+function renderLiveView(register     )         {
   const live = liveOf(register).sort(byTopic);
   const out = [
     `# Decisions: ${register.slug}`,
@@ -150,7 +150,7 @@ function renderLiveView(register: any): string {
 }
 
 /** IC-008. One entry per decision, by id; superseded entries stay with their rationale. */
-function renderArchive(register: any): string {
+function renderArchive(register     )         {
   const out = [`# Decision archive: ${register.slug}`, '', `> ${GENERATED_NOTE}`];
   for (const d of [...register.decisions].sort(byId)) {
     out.push('', `### ${d.id}: ${d.topic}`, '');
@@ -167,13 +167,13 @@ function renderArchive(register: any): string {
 
 // ── item validation ────────────────────────────────────────────────────────────────────────────
 
-function toList(value: any, what: string, label: string): string[] {
+function toList(value     , what        , label        )           {
   if (value === undefined || value === null || value === '') return [];
-  let list: any[];
+  let list       ;
   if (Array.isArray(value)) list = value;
   else if (typeof value === 'string') list = value.split(',');
   else throw new DecisionUsageError(`${label}: ${what} must be an array of strings`);
-  const out: string[] = [];
+  const out           = [];
   for (const entry of list) {
     if (typeof entry !== 'string') throw new DecisionUsageError(`${label}: ${what} must be an array of strings`);
     const trimmed = entry.trim();
@@ -183,11 +183,11 @@ function toList(value: any, what: string, label: string): string[] {
 }
 
 /** Validates one add item against IC-003's field rules. Throws DecisionUsageError. */
-function normalizeItem(raw: any, label: string): any {
+function normalizeItem(raw     , label        )      {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new DecisionUsageError(`${label}: must be an object`);
-  const extra = Object.keys(raw).filter((k: string) => !ITEM_KEYS.includes(k));
+  const extra = Object.keys(raw).filter((k        ) => !ITEM_KEYS.includes(k));
   if (extra.length) {
-    throw new DecisionUsageError(`${label}: unknown key${extra.length > 1 ? 's' : ''} ${extra.map((k: string) => `'${k}'`).join(', ')}. Allowed: ${ITEM_KEYS.join(', ')} (decidedBy is set by the runtime from the channel)`);
+    throw new DecisionUsageError(`${label}: unknown key${extra.length > 1 ? 's' : ''} ${extra.map((k        ) => `'${k}'`).join(', ')}. Allowed: ${ITEM_KEYS.join(', ')} (decidedBy is set by the runtime from the channel)`);
   }
   for (const key of REQUIRED_KEYS) {
     if (typeof raw[key] !== 'string' || raw[key].trim() === '') throw new DecisionUsageError(`${label}: '${key}' is required`);
@@ -226,9 +226,9 @@ function normalizeItem(raw: any, label: string): any {
 }
 
 /** Normalizes the batch (`--batch` contents) or the single item, refusing everything on one fault. */
-function normalizeItems(items: any): any[] {
+function normalizeItems(items     )        {
   if (!Array.isArray(items)) throw new DecisionUsageError('a batch must be a JSON array of decision objects');
-  const normalized = items.map((raw: any, i: number) => normalizeItem(raw, `item ${i + 1}`));
+  const normalized = items.map((raw     , i        ) => normalizeItem(raw, `item ${i + 1}`));
   const seen = new Set();
   for (const item of normalized) {
     if (seen.has(item.topic)) throw new DecisionUsageError(`topic '${item.topic}' appears more than once in the batch; a topic takes one decision per batch`);
@@ -239,15 +239,15 @@ function normalizeItems(items: any): any[] {
 
 // ── actions ────────────────────────────────────────────────────────────────────────────────────
 
-function summary({ action, slug, featureDir }: { action: string; slug: string; featureDir: string }): { action: string; slug: string; featureDir: string } { return { action, slug, featureDir }; }
+function summary({ action, slug, featureDir }                                                      )                                                       { return { action, slug, featureDir }; }
 
 const FOLDER_ARTIFACTS = ['intention/requirement.md', 'requirement.md', 'design/design.md', 'design.md', 'plan.md'];
 
 /** IC-002. */
-function initRegister({ featureDir, slug, fsImpl = nodeFs }: any): any {
+function initRegister({ featureDir, slug, fsImpl = nodeFs }     )      {
   const base = summary({ action: 'init', slug, featureDir });
   if (fsImpl.existsSync(registerFile(featureDir))) return { ...base, created: false };
-  const present = FOLDER_ARTIFACTS.filter((rel: string) => fsImpl.existsSync(path.join(featureDir, rel)));
+  const present = FOLDER_ARTIFACTS.filter((rel        ) => fsImpl.existsSync(path.join(featureDir, rel)));
   if (present.length) {
     return {
       ...base,
@@ -273,7 +273,7 @@ function initRegister({ featureDir, slug, fsImpl = nodeFs }: any): any {
  * IC-003. All-or-nothing: the whole batch is validated and simulated against the register first,
  * and nothing is written unless every item passes.
  */
-function addDecisions({ featureDir, slug, items, now = new Date(), fsImpl = nodeFs }: any): any {
+function addDecisions({ featureDir, slug, items, now = new Date(), fsImpl = nodeFs }     )      {
   const normalized = normalizeItems(items);
   const base = summary({ action: 'add', slug, featureDir });
   if (!fsImpl.existsSync(registerFile(featureDir))) {
@@ -285,24 +285,24 @@ function addDecisions({ featureDir, slug, items, now = new Date(), fsImpl = node
   try {
     const register = readRegister(featureDir, fsImpl);
     const iso = now.toISOString();
-    const added: any[] = [];
-    const superseded: any[] = [];
-    let conflict: any = null;
+    const added        = [];
+    const superseded        = [];
+    let conflict      = null;
     let nextId = register.nextId;
     for (const item of normalized) {
       for (const id of item.supersedes) {
-        const target = register.decisions.find((d: any) => d.id === id);
+        const target = register.decisions.find((d     ) => d.id === id);
         if (!target) throw new DecisionUsageError(`topic '${item.topic}': supersedes ${id}, which is not a decision in this register`);
         if (target.status !== 'live') throw new DecisionUsageError(`topic '${item.topic}': supersedes ${id}, which is not live (it was superseded by ${target.supersededBy})`);
       }
-      const unnamed = register.decisions.find((d: any) => d.status === 'live' && d.topic === item.topic && !item.supersedes.includes(d.id));
+      const unnamed = register.decisions.find((d     ) => d.status === 'live' && d.topic === item.topic && !item.supersedes.includes(d.id));
       if (unnamed && !conflict) {
         conflict = { finding: 'topic-conflict', message: `topic '${item.topic}' already has live decision ${unnamed.id}; name it in supersedes to replace it. Nothing was written` };
       }
       const id = formatId(nextId);
       nextId += 1;
       for (const old of item.supersedes) {
-        const target = register.decisions.find((d: any) => d.id === old);
+        const target = register.decisions.find((d     ) => d.id === old);
         target.status = 'superseded';
         target.supersededBy = id;
         superseded.push({ id: old, by: id });
@@ -336,7 +336,7 @@ function addDecisions({ featureDir, slug, items, now = new Date(), fsImpl = node
 }
 
 /** IC-004. */
-function listDecisions({ featureDir, slug, all = false, fsImpl = nodeFs }: any): any {
+function listDecisions({ featureDir, slug, all = false, fsImpl = nodeFs }     )      {
   const base = summary({ action: 'list', slug, featureDir });
   const register = readRegister(featureDir, fsImpl);
   if (!register) return { ...base, finding: 'no-register', message: `${featureDir} has no decisions/register.json` };
@@ -345,7 +345,7 @@ function listDecisions({ featureDir, slug, all = false, fsImpl = nodeFs }: any):
 }
 
 /** IC-005: compaction plus the view re-render, under the register lock `compactHistory` itself lacks. */
-function compactDecisions({ featureDir, slug, repoRoot, paths, now = new Date(), fsImpl = nodeFs }: any): any {
+function compactDecisions({ featureDir, slug, repoRoot, paths, now = new Date(), fsImpl = nodeFs }     )      {
   const base = summary({ action: 'compact', slug, featureDir });
   if (!fsImpl.existsSync(registerFile(featureDir))) {
     return { ...base, finding: 'no-register', message: `${featureDir} has no decisions/register.json; nothing was touched` };
@@ -360,7 +360,7 @@ function compactDecisions({ featureDir, slug, repoRoot, paths, now = new Date(),
     if (result.failed.length) {
       return {
         ...base, status: result.status, finding: 'compaction-failed',
-        message: result.failed.map((f: any) => f.message).join('; '),
+        message: result.failed.map((f     ) => f.message).join('; '),
         artifact: result.failed[0].path, moved: result.moved, failed: result.failed,
       };
     }
@@ -374,17 +374,17 @@ function compactDecisions({ featureDir, slug, repoRoot, paths, now = new Date(),
 
 const VALID_ACTIONS = ['init', 'add', 'list', 'compact'];
 
-function readBatchFile(batchPath: string, fsImpl: any): any {
-  let text: string;
+function readBatchFile(batchPath        , fsImpl     )      {
+  let text        ;
   try {
     // `-` is stdin, as for the evidence verb.
     text = batchPath === '-' ? fsImpl.readFileSync(0, 'utf8') : fsImpl.readFileSync(path.resolve(batchPath), 'utf8');
-  } catch (error: any) {
+  } catch (error     ) {
     throw new DecisionUsageError(`cannot read --batch ${batchPath}: ${error.message}`);
   }
   try {
     return JSON.parse(text);
-  } catch (error: any) {
+  } catch (error     ) {
     throw new DecisionUsageError(`--batch ${batchPath} is not valid JSON: ${error.message}`);
   }
 }
@@ -401,15 +401,15 @@ function readBatchFile(batchPath: string, fsImpl: any): any {
  *   refs, source, batch (path); list: all
  * @returns {{exitCode:number, result?:Object, usage?:string}}
  */
-function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, now = new Date(), fsImpl = nodeFs }: any): { exitCode: number; result?: any; usage?: string } {
+function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, now = new Date(), fsImpl = nodeFs }     )                                                     {
   const act = action === 'status' ? 'list' : action;
-  let resolved: any = null;
+  let resolved      = null;
   try {
     if (!VALID_ACTIONS.includes(act)) throw new DecisionUsageError(`unknown --action '${action}'. Valid: ${VALID_ACTIONS.join(', ')}`);
     const feature = resolveActiveFeature({ projectRoot, slug });
     if (feature.error) throw new DecisionUsageError(feature.message);
     resolved = { featureDir: feature.featureDir, slug: feature.paths.feature_slug };
-    let result: any;
+    let result     ;
     if (act === 'init') {
       result = initRegister({ ...resolved, fsImpl });
     } else if (act === 'list') {
@@ -417,13 +417,13 @@ function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, no
     } else if (act === 'compact') {
       result = compactDecisions({ ...resolved, repoRoot: feature.repoRoot, paths: feature.paths, now, fsImpl });
     } else {
-      let items: any;
+      let items     ;
       if (flags.batch) {
         const named = ITEM_KEYS.filter((k) => flags[k] !== undefined);
         if (named.length) throw new DecisionUsageError(`--batch cannot be combined with --${named[0]}`);
         items = readBatchFile(flags.batch, fsImpl);
       } else {
-        const single: Record<string, any> = {};
+        const single                      = {};
         for (const key of ITEM_KEYS) if (flags[key] !== undefined) single[key] = flags[key];
         for (const key of REQUIRED_KEYS) {
           if (single[key] === undefined) throw new DecisionUsageError(`--${key} is required for --action add (or pass --batch <file.json>)`);
@@ -433,7 +433,7 @@ function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, no
       result = addDecisions({ ...resolved, items, now, fsImpl });
     }
     return { exitCode: result.finding ? 1 : 0, result };
-  } catch (error: any) {
+  } catch (error     ) {
     if (error instanceof DecisionUsageError) return { exitCode: 2, usage: error.message };
     // Another writer holds the register lock: a condition to retry, not a mistake in the call.
     if (resolved && error && /^Could not lock/.test(error.message || '')) {
@@ -443,21 +443,21 @@ function runDecision({ action = 'list', projectRoot, slug = null, flags = {}, no
   }
 }
 
-function humanLines(result: any): string[] {
-  const lines: string[] = [];
+function humanLines(result     )           {
+  const lines           = [];
   if (result.finding) lines.push(`${result.finding}: ${result.message}`);
   if (result.action === 'init' && !result.finding) {
     lines.push(result.created ? `created ${path.join(result.featureDir, 'decisions', 'register.json')}` : 'register already exists; nothing written');
   }
-  for (const a of (result.added || []) as any[]) lines.push(`added ${a.id} (${a.topic})`);
-  for (const s of (result.superseded || []) as any[]) lines.push(`superseded ${s.id} by ${s.by}`);
+  for (const a of (result.added || [])         ) lines.push(`added ${a.id} (${a.topic})`);
+  for (const s of (result.superseded || [])         ) lines.push(`superseded ${s.id} by ${s.by}`);
   if (result.action === 'list' && !result.finding) {
     if (result.decisions.length === 0) lines.push('No decisions.');
-    for (const d of result.decisions as any[]) lines.push(`${d.id}  ${d.topic}  ${d.statement}  [${d.decidedBy}, ${d.stage}${d.status === 'live' ? '' : `, superseded by ${d.supersededBy}`}]`);
+    for (const d of result.decisions         ) lines.push(`${d.id}  ${d.topic}  ${d.statement}  [${d.decidedBy}, ${d.stage}${d.status === 'live' ? '' : `, superseded by ${d.supersededBy}`}]`);
   }
   if (result.action === 'compact') {
     if (result.status === 'unchanged') lines.push('nothing to compact');
-    for (const m of (result.moved || []) as any[]) lines.push(`moved ${m.lines} line${m.lines === 1 ? '' : 's'} from ${m.path} to ${m.archive}`);
+    for (const m of (result.moved || [])         ) lines.push(`moved ${m.lines} line${m.lines === 1 ? '' : 's'} from ${m.path} to ${m.archive}`);
   }
   return lines;
 }
@@ -466,7 +466,7 @@ function humanLines(result: any): string[] {
  * `decision` verb. Exit 0 = answered, 1 = a finding the caller must act on, 2 = usage.
  * `--json` prints the result object unmodified.
  */
-function handleDecisionCommand({ action = 'list', projectRoot, slug = null, flags = {}, json = false }: any = {}): number {
+function handleDecisionCommand({ action = 'list', projectRoot, slug = null, flags = {}, json = false }      = {})         {
   const run = runDecision({ action, projectRoot: projectRoot || process.cwd(), slug, flags });
   if (run.usage !== undefined) return usageError('decision', run.usage, json);
   if (json) console.log(JSON.stringify(run.result, null, 2));

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.ts → evidence-ledger.js}

@@ -5,9 +5,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { REPO_ROOT } = require('../helper/repo-root.ts');
-const { updateTaskState, readTaskState, mergeRecords } = require('./task-state.ts');
-const { taskStoreDir } = require('./task-scope.ts');
+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',
@@ -47,7 +48,7 @@ const EVIDENCE_STATUSES = new Set(['active', 'superseded']);
  * @param {string} file the ledger path, so the message says which file to look at
  * @returns {object} the same item, once its status is one of the two
  */
-function assertKnownStatus(item: any, file: string) {
+function assertKnownStatus(item     , file        ) {
   const status = item?.status;
   if (!EVIDENCE_STATUSES.has(status)) {
     throw new Error(
@@ -66,7 +67,7 @@ function assertKnownStatus(item: any, file: string) {
  * @param {string} taskId
  * @returns {string} the validated id, for use in an expression
  */
-function assertSafeTaskId(taskId: string): string {
+function assertSafeTaskId(taskId        )         {
   if (typeof taskId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || taskId.includes('..')) {
     throw new Error(`Invalid task id '${taskId}': expected letters, digits, dot, dash or underscore, and no path separators`);
   }
@@ -74,14 +75,14 @@ function assertSafeTaskId(taskId: string): string {
 }
 
 class EvidenceLedger {
-  declare fsImpl: any;
-  declare repoRoot: any;
-  declare fixedStateDir: any;
-  declare slug: any;
-  declare stateDir: any;
-  declare evidenceMap: Map<any, any>;
-  declare baseline: Map<any, any>;
-  declare seq: number;
+                      
+                        
+                             
+                    
+                        
+                                     
+                                  
+                      
   /**
    * @param {Object} [options]
    * @param {string} [options.repoRoot]
@@ -89,7 +90,7 @@ class EvidenceLedger {
    * @param {string} [options.slug] feature whose namespace the records live under (see task-scope.js)
    * @param {Object} [options.fsImpl]
    */
-  constructor(options: any = {}) {
+  constructor(options      = {}) {
     this.fsImpl = options.fsImpl || fs;
     this.repoRoot = options.repoRoot || REPO_ROOT;
     this.fixedStateDir = options.stateDir || null;
@@ -101,7 +102,7 @@ class EvidenceLedger {
   }
 
   /** Where this task's evidence file lives: the feature's namespace when it has one (IC-002). */
-  fileFor(taskId: any) {
+  fileFor(taskId     ) {
     const dir = this.fixedStateDir
       || taskStoreDir({ projectRoot: this.repoRoot, store: 'evidence', taskId, slug: this.slug });
     return path.join(dir, `${assertSafeTaskId(taskId)}.json`);
@@ -115,7 +116,7 @@ class EvidenceLedger {
    * scheme. The random component carries that burden; timestamp and sequence stay for readability.
    * @returns {string}
    */
-  generateId(): string {
+  generateId()         {
     this.seq += 1;
     return `ev_${Date.now().toString(36)}_${crypto.randomBytes(4).toString('hex')}_${this.seq.toString(36)}`;
   }
@@ -125,10 +126,11 @@ class EvidenceLedger {
    * @param {Object} item
    * @returns {string} evidenceId
    */
-  addEvidence(item: any): string {
+  addEvidence(item     )         {
     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).
@@ -190,7 +195,7 @@ class EvidenceLedger {
    * @param {string} id
    * @returns {Object|null}
    */
-  getEvidence(id: string) {
+  getEvidence(id        ) {
     return this.evidenceMap.get(id) || null;
   }
 
@@ -199,7 +204,7 @@ class EvidenceLedger {
    * @param {Object} [filter={}]
    * @returns {Array<Object>}
    */
-  queryEvidence(filter: any = {}) {
+  queryEvidence(filter      = {}) {
     const results = [];
     for (const item of this.evidenceMap.values()) {
       if (filter.taskId && item.taskId !== filter.taskId) continue;
@@ -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;
@@ -225,7 +232,7 @@ class EvidenceLedger {
    * @param {string} replacedBy the id of the item that supersedes it; must already exist
    * @returns {string} the new status
    */
-  supersedeEvidence(evidenceId: string, replacedBy: string): string {
+  supersedeEvidence(evidenceId        , replacedBy        )         {
     if (!replacedBy) {
       throw new Error('supersede requires the id of the evidence item that replaces this one');
     }
@@ -254,7 +261,7 @@ class EvidenceLedger {
    * @param {Array<string>} modifiedFiles
    * @returns {number} count of invalidated items
    */
-  invalidateFiles(modifiedFiles: any): number {
+  invalidateFiles(modifiedFiles     )         {
     if (!Array.isArray(modifiedFiles) || modifiedFiles.length === 0) return 0;
     const fileSet = new Set(modifiedFiles);
     let count = 0;
@@ -283,12 +290,12 @@ class EvidenceLedger {
    * @param {string} [taskId='default']
    * @returns {string} filePath
    */
-  save(taskId = 'default'): string {
+  save(taskId = 'default')         {
     const targetFile = this.fileFor(taskId);
-    let merged: any;
+    let merged     ;
     const file = updateTaskState({
       fsImpl: this.fsImpl, file: targetFile,
-      build: (disk: any) => {
+      build: (disk     ) => {
         merged = mergeRecords(this.queryEvidence({ taskId }), disk?.evidence || [], this.baseline);
         return { taskId, updatedAt: new Date().toISOString(), evidenceCount: merged.length, evidence: merged };
       },
@@ -305,7 +312,7 @@ class EvidenceLedger {
    * @param {string} [taskId='default']
    * @returns {number} count of loaded items
    */
-  load(taskId = 'default'): number {
+  load(taskId = 'default')         {
     const targetFile = this.fileFor(taskId);
     const data = readTaskState(this.fsImpl, targetFile);
     if (data && Array.isArray(data.evidence)) {