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

package/src/runtime/cli.js

@@ -5,12 +5,12 @@
 const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
 const { CapabilityRouter } = require('./capability-router.js');
-const { EvidenceLedger, VALID_EVIDENCE_KINDS, VALID_PROVENANCE } = require('./evidence-ledger.js');
-const { resolveLocator, describeResolution } = require('./locator-resolve.js');
+const { EvidenceLedger } = require('./evidence-ledger.js');
 const { ClaimsManager } = require('./claims.js');
-const { measureFreshness } = require('./freshness.js');
+const { measureTreeState } = require('./source-version.js');
+const { toEvidence, validateEvidenceItem, EVIDENCE_REFUSED_FIELDS } = require('./candidate.js');
+const { sourceModeLookup } = require('./retrieval-plan.js');
 const { evaluateTaskReadiness } = require('./readiness.js');
 const { writeReadinessRecord } = require('./readiness-record.js');
 const { parseDeclaredScope } = require('./verification/scope-bound.js');
@@ -90,7 +90,7 @@ function handleCapabilitiesCommand({ json = false, check = false, repoRoot }
  * @returns {number} exit code: 0 once the evaluation is recorded, whatever its state
  */
 function handleReadinessCommand({
-  taskClass = 'feature', taskId = 'default', json = false, repoRoot, stateRoot,
+  taskClass = 'feature', taskId = 'default', json = false, repoRoot, stateRoot, sourceRoot,
   verificationPlan, scopeClear, invariants, userDecisionPending = false, mode = 'workflow', now, slug = null,
 }      = {}) {
   // Two different roots, previously conflated into one. `root` locates the *registry* (the
@@ -111,7 +111,7 @@ function handleReadinessCommand({
 
   let report;
   try {
-    report = evaluateTaskReadiness({ taskProfile: profile, repoRoot: root, projectRoot: state, mode });
+    report = evaluateTaskReadiness({ taskProfile: profile, repoRoot: root, projectRoot: state, treeRoot: sourceRoot || state, mode });
   } catch (error     ) {
     return usageError('readiness', error.message, json, error);
   }
@@ -196,263 +196,23 @@ function handleReadinessCommand({
 // every key it does not recognise, so a field this boundary forwards blindly is a field the caller
 // watches vanish while the command reports success. Nothing reaches the ledger unnamed.
 
-/** Every field an evidence item may carry here. Anything else is refused, never dropped. */
-const EVIDENCE_ITEM_FIELDS = ['kind', 'provenance', 'source', 'locator', 'content', 'taskId', 'establishes', 'observation'];
-const EVIDENCE_SOURCE_FIELDS = ['provider', 'capability'];
-const EVIDENCE_LOCATOR_FIELDS = ['file', 'line', 'symbol', 'uri'];
-const EVIDENCE_OBSERVATION_FIELDS = ['command', 'exitCode'];
-
-/** Kinds that record an execution and may carry a typed observation. */
-const OBSERVATION_KINDS = new Set(['test-result', 'runtime-observation']);
-
-/** Kinds that are by definition not a direct read of the repository. FR-007's second sentence. */
-const NON_REPOSITORY_KINDS = new Set(['generated-analysis', 'user-statement']);
-
-/** Fields a caller might plausibly send that this boundary refuses by name, with the reason.
- *  A named refusal beats the generic unknown-field error: each of these would otherwise be
- *  silently discarded by `addEvidence`, and a silent discard reads as a successful write. */
-const EVIDENCE_REFUSED_FIELDS = new Map([
-  ['id', 'evidence ids are minted by the ledger — a caller-chosen id can overwrite an unrelated record'],
-  ['freshness', 'freshness is measured here from the working tree at write time, never asserted by the writer'],
-  ['supports', 'link evidence to a claim with `claim --action link`, which updates both sides; a list written here would leave the claim unaware of it'],
-  ['contradicts', 'link evidence to a claim with `claim --action link`, which updates both sides; a list written here would leave the claim unaware of it'],
-  ['stage', 'the evidence record has no stage field — the batch *is* the stage boundary, so a stage name recorded here would be dropped'],
-  ['status', "lifecycle status starts 'active' and changes only through `evidence --action supersede` — asserting it here would let a caller declare an item superseded without naming what replaces it"],
-]);
-
-/** 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);
-  }
-}
-
-/**
- * Normalises a locator given either as an object or as a `file[:line]` / URI string.
- * @param {Object|string} raw
- * @returns {Object}
- */
-function parseLocator(raw     ) {
-  if (typeof raw === 'string') {
-    const text = raw.trim();
-    if (text === '') throw new Error('locator is empty');
-    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) return { uri: text };
-    const withLine = text.match(/^(.+):(\d+)$/);
-    if (withLine) return { file: withLine[1], line: Number(withLine[2]) };
-    return { file: text };
-  }
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new Error("locator must be an object, or a 'path/to/file[:line]' or URI string");
-  }
-  const locator                      = {};
-  for (const [key, value] of Object.entries(raw)) {
-    if (!EVIDENCE_LOCATOR_FIELDS.includes(key)) {
-      throw new Error(`unknown locator field '${key}'. Accepted: ${EVIDENCE_LOCATOR_FIELDS.join(', ')}`);
-    }
-    locator[key] = value;
-  }
-  if (locator.line !== undefined && (!Number.isInteger(locator.line) || locator.line < 1)) {
-    throw new Error(`locator.line must be a positive integer, got '${locator.line}'`);
-  }
-  for (const key of ['file', 'symbol', 'uri']) {
-    if (locator[key] !== undefined && (typeof locator[key] !== 'string' || locator[key].trim() === '')) {
-      throw new Error(`locator.${key} must be a non-empty string`);
-    }
-  }
-  if (!locator.file && !locator.uri) throw new Error('a locator needs at least a file or a uri');
-  return locator;
-}
-
-/**
- * Validates one raw evidence item and returns the record fields the ledger will store.
- *
- * Throws on anything it cannot account for. Every rule here traces to FR-007 or to the
- * vacuous-record family: a record with no statement and no locator asserts nothing, and storing it
- * inflates the evidence count that the readiness gate then reads.
- *
- * @param {Object} raw
- * @param {string} taskId the task the batch is being written to
- * @param {string} [repoRoot] root a relative locator resolves against; defaults to cwd
- * @returns {{kind:string, provenance:string, source:Object, locator:Object, content:(string|null)}}
- */
-function validateEvidenceItem(raw     , taskId     , repoRoot     ) {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('an evidence item must be a JSON object');
-  assertNoScoreFields(raw, '');
-
-  for (const key of Object.keys(raw)) {
-    if (EVIDENCE_REFUSED_FIELDS.has(key)) throw new Error(`'${key}' is not accepted here: ${EVIDENCE_REFUSED_FIELDS.get(key)}`);
-    if (!EVIDENCE_ITEM_FIELDS.includes(key)) {
-      throw new Error(`unknown evidence field '${key}'. Accepted: ${EVIDENCE_ITEM_FIELDS.join(', ')}`);
-    }
-  }
-
-  if (raw.taskId !== undefined && raw.taskId !== taskId) {
-    throw new Error(`item names task '${raw.taskId}' but this write targets '${taskId}' — one write, one task`);
-  }
-
-  const kinds = [...VALID_EVIDENCE_KINDS].sort().join(', ');
-  if (typeof raw.kind !== 'string' || raw.kind.trim() === '') throw new Error(`kind is required. Valid: ${kinds}`);
-  if (!VALID_EVIDENCE_KINDS.has(raw.kind)) throw new Error(`unknown evidence kind '${raw.kind}'. Valid: ${kinds}`);
-
-  const provenances = [...VALID_PROVENANCE].sort().join(', ');
-  if (typeof raw.provenance !== 'string' || raw.provenance.trim() === '') {
-    throw new Error('provenance is required and has no default here — defaulting it would file model '
-      + `analysis as repository fact, the one distinction FR-007 makes binding. Valid: ${provenances}`);
-  }
-  if (!VALID_PROVENANCE.has(raw.provenance)) throw new Error(`unknown provenance '${raw.provenance}'. Valid: ${provenances}`);
-  if (NON_REPOSITORY_KINDS.has(raw.kind) && raw.provenance === 'extracted') {
-    throw new Error(`kind '${raw.kind}' cannot carry provenance 'extracted': it is not a read of the `
-      + "repository, and labelling it as one is exactly how model analysis stops being distinguishable "
-      + "from fact. Use 'inferred' (derived by analysis) or 'asserted' (stated by a person).");
-  }
-
-  if (raw.source === undefined) {
-    throw new Error('source is required: which provider answered, under which capability. '
-      + "It has no default — 'unknown/general' is a plausible-looking answer to a question nobody asked.");
-  }
-  if (!raw.source || typeof raw.source !== 'object' || Array.isArray(raw.source)) {
-    throw new Error('source must be an object with provider and capability');
-  }
-  for (const key of Object.keys(raw.source)) {
-    if (!EVIDENCE_SOURCE_FIELDS.includes(key)) {
-      throw new Error(`unknown source field '${key}'. Accepted: ${EVIDENCE_SOURCE_FIELDS.join(', ')}`);
-    }
-  }
-  for (const key of EVIDENCE_SOURCE_FIELDS) {
-    if (typeof raw.source[key] !== 'string' || raw.source[key].trim() === '') {
-      throw new Error(`source.${key} is required and must be a non-empty string`);
-    }
-  }
-
-  const locator = raw.locator === undefined ? null : parseLocator(raw.locator);
-  // An item carrying an observation is anchored by the command it records — that command is what
-  // the next worker re-runs to check it — so the locator becomes optional there and only there.
-  if (raw.provenance === 'extracted' && !locator && raw.observation === undefined) {
-    throw new Error("provenance 'extracted' requires a locator — a fact read from the repository "
-      + 'must name where it was read, or the next worker cannot check it and cannot tell when it goes stale');
-  }
-
-  // A locator that parses is not a locator that resolves (FR-004). Shape validation alone let an
-  // item naming line 799 of a 28-line file be recorded as support and counted by the readiness
-  // gate. The refusal names what the file actually offers, so the writer can correct it here rather
-  // than discover it at the gate.
-  if (raw.provenance === 'extracted' && locator) {
-    const resolution = resolveLocator({ locator, repoRoot });
-    if (!resolution.resolved) {
-      throw new Error(`the locator does not resolve: ${describeResolution(locator, resolution)}. `
-        + "An 'extracted' item asserts a read of the repository, so a locator that points at nothing "
-        + 'records a fact nobody can check');
-    }
-  }
-
-  if (raw.content !== undefined && typeof raw.content !== 'string') throw new Error('content must be a string');
-  const content = typeof raw.content === 'string' && raw.content.trim() !== '' ? raw.content : null;
-  if (raw.provenance !== 'extracted' && !content) {
-    throw new Error(`provenance '${raw.provenance}' requires content — an inferred or asserted item `
-      + 'is the statement itself, so a record without one records nothing while still counting as evidence');
-  }
-
-  // Requirement bindings: which readiness-template requirements this item claims to establish.
-  // Declared by the writer, judged by the gate — the gate counts an item toward a requirement only
-  // when it is named here, so a structural item can no longer satisfy `architecture_mapped` and
-  // `blast_radius` at once by category alone (review R1).
-  let establishes = [];
-  if (raw.establishes !== undefined) {
-    const list = typeof raw.establishes === 'string' ? raw.establishes.split(',').map((s     ) => s.trim()) : raw.establishes;
-    if (!Array.isArray(list) || list.length === 0 || list.some((r) => typeof r !== 'string' || r.trim() === '')) {
-      throw new Error("'establishes' must be a requirement id, a comma-separated list of them, or a non-empty array of non-empty strings");
-    }
-    establishes = list.map((s) => s.trim());
-  }
-
-  // Typed observation: the execution behind a test-result or runtime-observation. Command and exit
-  // status are the two facts the gate can actually grade; tree identity and observation time are
-  // measured into freshness at this same write. Only an 'extracted' item may carry one — an
-  // observation asserts an execution happened, and an inferred item is by definition not one.
-  let observation = null;
-  if (raw.observation !== undefined) {
-    if (!raw.observation || typeof raw.observation !== 'object' || Array.isArray(raw.observation)) {
-      throw new Error('observation must be an object with command and exitCode');
-    }
-    for (const key of Object.keys(raw.observation)) {
-      if (!EVIDENCE_OBSERVATION_FIELDS.includes(key)) {
-        throw new Error(`unknown observation field '${key}'. Accepted: ${EVIDENCE_OBSERVATION_FIELDS.join(', ')}`);
-      }
-    }
-    if (typeof raw.observation.command !== 'string' || raw.observation.command.trim() === '') {
-      throw new Error('observation.command is required: the exact command whose exit status is being recorded');
-    }
-    if (!Number.isInteger(raw.observation.exitCode) || raw.observation.exitCode < 0) {
-      throw new Error(`observation.exitCode must be a non-negative integer, got '${raw.observation.exitCode}'`);
-    }
-    if (!OBSERVATION_KINDS.has(raw.kind)) {
-      throw new Error(`kind '${raw.kind}' cannot carry an observation — only ${[...OBSERVATION_KINDS].join(', ')} record an execution`);
-    }
-    if (raw.provenance !== 'extracted') {
-      throw new Error(`provenance '${raw.provenance}' cannot carry an observation: an observation asserts a command `
-        + 'was actually run, which is a read of the world, not an inference or an assertion. '
-        + "Either record the execution as 'extracted', or drop the observation.");
-    }
-    observation = { command: raw.observation.command.trim(), exitCode: raw.observation.exitCode };
-  }
-  if (raw.kind === 'test-result' && raw.provenance === 'extracted' && !observation) {
-    throw new Error("an 'extracted' test-result requires an observation ({command, exitCode}) — a test result "
-      + 'without the command and exit status behind it is a claim about an execution nobody can check, '
-      + 'and it is exactly how a failed baseline was once accepted as a passing one');
-  }
-
-  return {
-    kind: raw.kind,
-    provenance: raw.provenance,
-    source: { provider: raw.source.provider, capability: raw.source.capability },
-    locator: locator || {},
-    content,
-    establishes,
-    observation,
-  };
-}
+const {
+  EVIDENCE_SCORE_FIELDS,
+  scoreFieldRefusal,
+  assertNoScoreFields,
+} = require('./evidence-fields.js');
 
-/** HEAD of the tree the evidence was observed in, or null outside a repo. Measured, not asserted. */
-function headCommit(root     ) {
-  try {
-    return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], {
-      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim() || null;
-  } catch {
-    return null;
-  }
-}
 
 
 /**
  * Reads a stage's evidence batch: a JSON array, or `{ "evidence": [...] }`.
  * @param {string} batchPath a file path, or `-` for stdin
+ * @param {string} taskId
+ * @param {string} root
+ * @param {string|null} [slug]
  * @returns {Array<Object>}
  */
-function readEvidenceBatch(batchPath     ) {
+function readEvidenceBatch(batchPath     , taskId     , root     , slug      = null) {
   let text;
   try {
     text = batchPath === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(batchPath), 'utf8');
@@ -469,7 +229,9 @@ function readEvidenceBatch(batchPath     ) {
   if (data && typeof data === 'object') {
     for (const key of Object.keys(data)) {
       if (key === 'evidence') continue;
-      const named = EVIDENCE_REFUSED_FIELDS.has(key) ? ` — ${EVIDENCE_REFUSED_FIELDS.get(key)}` : '';
+      const refusedVal = EVIDENCE_REFUSED_FIELDS.get(key);
+      const reason = typeof refusedVal === 'function' ? refusedVal(taskId, root, slug) : refusedVal;
+      const named = reason ? ` — ${reason.endsWith('.') ? reason.slice(0, -1) : reason}` : '';
       throw new Error(`unknown batch field '${key}'${named}. A batch is a JSON array of items, `
         + "or an object whose only key is 'evidence'");
     }
@@ -483,7 +245,7 @@ function readEvidenceBatch(batchPath     ) {
  * The `--action add` arm: validate the whole batch, then write it.
  * @returns {number} exit code
  */
-function addEvidence({ ledger, root, taskId, item, batchPath, json }     ) {
+function addEvidence({ ledger, root, sourceRoot = root, attemptRoot, taskId, item, batchPath, json, slug = null }     ) {
   const flagged = item && Object.keys(item).length > 0;
   if (flagged && batchPath) {
     return usageError('evidence', '--batch and the single-item flags are two spellings of the same write; use one', json);
@@ -495,7 +257,7 @@ function addEvidence({ ledger, root, taskId, item, batchPath, json }     ) {
 
   let raws;
   try {
-    raws = batchPath ? readEvidenceBatch(batchPath) : [item];
+    raws = batchPath ? readEvidenceBatch(batchPath, taskId, root, slug) : [item];
   } catch (error     ) {
     return usageError('evidence', error.message, json, error);
   }
@@ -506,26 +268,30 @@ function addEvidence({ ledger, root, taskId, item, batchPath, json }     ) {
 
   // The whole batch is validated before any of it is written. A half-written stage batch is worse
   // than a rejected one: the half that landed looks complete to every later reader.
+  const treeState = measureTreeState(root);
+  const hasAbsence = raws.some((raw     ) => raw?.absence === true);
+  const absenceTreeState = hasAbsence && path.resolve(sourceRoot) !== path.resolve(root)
+    ? measureTreeState(sourceRoot) : null;
+  const providerFreshness = new Map();
+  let sourceModeOf      = null;
   const validated = [];
   for (const [index, raw] of raws.entries()) {
     try {
-      validated.push(validateEvidenceItem(raw, taskId, root));
+      if (raw && raw.absence && !sourceModeOf) {
+        sourceModeOf = sourceModeLookup(new CapabilityRouter({ repoRoot: REPO_ROOT }).capabilities);
+      }
+      validated.push(toEvidence({ item: raw }, { taskId, root, treeState, absenceTreeState, probeRoot: sourceRoot, attemptRoot, slug, providerFreshness, sourceModeOf }));
     } catch (error     ) {
       const where = raws.length > 1 ? `batch item ${index + 1} of ${raws.length}: ` : '';
       return usageError('evidence', `${where}${error.message}`, json, error);
     }
   }
 
-  const gitCommit = headCommit(root);
   const written = [];
   let stateFile;
   try {
     for (const record of validated) {
-      const id = ledger.addEvidence({
-        ...record,
-        taskId,
-        freshness: measureFreshness(root, record.locator, gitCommit),
-      });
+      const id = ledger.addEvidence(record);
       written.push(ledger.getEvidence(id));
     }
     stateFile = ledger.save(taskId);
@@ -552,7 +318,8 @@ function addEvidence({ ledger, root, taskId, item, batchPath, json }     ) {
   }
   console.log('─'.repeat(78));
   console.log(`Wrote ${written.length} item(s) to ${stateFile}`);
-  console.log(`Commit at observation: ${gitCommit || 'not a git worktree — freshness cannot expire by diff'}`);
+  const observedTree = absenceTreeState || treeState;
+  console.log(`Commit at observation: ${observedTree.gitCommit || (observedTree.prefix !== null ? 'not measured' : 'not a git worktree — freshness cannot expire by diff')}`);
   console.log('═'.repeat(78) + '\n');
   return finish(0);
 }
@@ -610,7 +377,7 @@ function supersedeEvidence({ ledger, taskId, evidenceId, replacedBy, json }
  * @param {string} [options.stateRoot]
  * @returns {number} exit code
  */
-function handleEvidenceCommand({ taskId = 'default', action = 'list', item = null, batchPath = null, evidenceId = null, replacedBy = null, json = false, repoRoot, stateRoot }      = {}) {
+function handleEvidenceCommand({ taskId = 'default', action = 'list', item = null, batchPath = null, evidenceId = null, replacedBy = null, json = false, repoRoot, stateRoot, sourceRoot, attemptRoot, slug = null }      = {}) {
   // See handleReadinessCommand: evidence is the caller's project state, not DoFlow package state.
   const root = stateRoot || repoRoot || process.cwd();
   const isQuery = action === 'list' || action === 'status';
@@ -630,7 +397,7 @@ function handleEvidenceCommand({ taskId = 'default', action = 'list', item = nul
     return usageError('evidence', error.message, json, error);
   }
 
-  if (action === 'add') return addEvidence({ ledger, root, taskId, item, batchPath, json });
+  if (action === 'add') return addEvidence({ ledger, root, sourceRoot: sourceRoot || root, attemptRoot, taskId, item, batchPath, json, slug });
   if (action === 'supersede') return supersedeEvidence({ ledger, taskId, evidenceId, replacedBy, json });
 
   const items = ledger.queryEvidence({ taskId });

package/src/runtime/context/budget.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { loadRegistry } = require('../../registry/index.js');
+
+const TASK_CLASS_BUDGETS                         = Object.freeze({
+  feature: 225000,
+  'dependency-change': 85000,
+  bug: 71000,
+  refactor: 71000,
+  documentation: 57000,
+  operations: 45000,
+  review: 42000,
+  research: 35302,
+  'trivial-edit': 30000,
+});
+
+let cachedHarnesses      = null;
+let cachedHarnessIds                  = null;
+let registryLoadCount         = 0;
+
+function clearRegistryCache()       {
+  cachedHarnesses = null;
+  cachedHarnessIds = null;
+  cachedBudgetsJson = null;
+}
+
+function getRegistryLoadCount()         {
+  return registryLoadCount;
+}
+
+function getRegisteredHarnesses()      {
+  if (cachedHarnesses) return cachedHarnesses;
+  registryLoadCount++;
+  const repoRoot = path.resolve(__dirname, '../../../');
+  const harnessesPath = path.join(repoRoot, 'core', 'registry', 'harnesses.json');
+  try {
+    const raw = JSON.parse(fs.readFileSync(harnessesPath, 'utf8'));
+    if (Array.isArray(raw?.harnesses)) {
+      cachedHarnesses = raw.harnesses;
+      return cachedHarnesses;
+    }
+  } catch {
+    // fallback if unreadable
+  }
+  cachedHarnesses = loadRegistry({ repoRoot }).harnesses;
+  return cachedHarnesses;
+}
+
+function getRegisteredHarnessIds()           {
+  if (cachedHarnessIds && cachedHarnesses) return cachedHarnessIds;
+  const ids = getRegisteredHarnesses().map((h     ) => h.id);
+  cachedHarnessIds = ids;
+  return ids;
+}
+
+let cachedBudgetsJson      = null;
+
+function getBudgetsJson()      {
+  if (cachedBudgetsJson) return cachedBudgetsJson;
+  try {
+    const budgetsPath = path.resolve(__dirname, '../../../bench/perf/budgets.json');
+    if (fs.existsSync(budgetsPath)) {
+      cachedBudgetsJson = JSON.parse(fs.readFileSync(budgetsPath, 'utf8'));
+      return cachedBudgetsJson;
+    }
+  } catch {
+    // fallback if unreadable
+  }
+  return null;
+}
+
+/**
+ * Resolves budget and harness identity per IC-012.
+ * Precedence:
+ * 1. Harness identity: flag -> env (DOFLOW_AGENT) -> unstated
+ * 2. Cap: override (--max-bytes) -> profile -> task-class
+ * 3. Capacity: declared -> unknown
+ */
+function resolveBudget({
+  taskClass = 'feature',
+  maxBytes,
+  harnessFlag = null,
+  env = process.env,
+  profiles = null,
+  budgetsJson = null,
+}      = {})      {
+  const harnesses = profiles || getRegisteredHarnesses();
+  const validIds = harnesses.map((h     ) => h.id);
+
+  // 1. Harness identity
+  let harness                                                                            ;
+
+  if (harnessFlag !== null && harnessFlag !== undefined && harnessFlag !== '') {
+    if (!validIds.includes(harnessFlag)) {
+      const err      = new Error(`Unknown harness '${harnessFlag}'. Valid harnesses: ${validIds.join(', ')}`);
+      err.code = 'USAGE_ERROR';
+      err.validIds = validIds;
+      throw err;
+    }
+    harness = { id: harnessFlag, source: 'flag' };
+  } else if (env && env.DOFLOW_AGENT) {
+    const agentEnv = env.DOFLOW_AGENT;
+    if (validIds.includes(agentEnv)) {
+      harness = { id: agentEnv, source: 'env' };
+    } else {
+      harness = { id: null, source: 'unstated', basis: 'env-unregistered' };
+    }
+  } else {
+    harness = { id: null, source: 'unstated' };
+  }
+
+  // Find harness declaration for profile lookup
+  const harnessObj = harness.id ? harnesses.find((h     ) => h.id === harness.id) : null;
+  const contextProfile = harnessObj?.contextProfile;
+
+  // Capacity & Tool Limit
+  let capacity                                         ;
+  let toolResultLimitBytes                = null;
+
+  if (!harness.id) {
+    capacity = { value: null, basis: 'unknown:harness-unstated' };
+  } else if (contextProfile?.capacityTokens && typeof contextProfile.capacityTokens.value === 'number') {
+    capacity = {
+      value: contextProfile.capacityTokens.value,
+      basis: `declared:${contextProfile.capacityTokens.source || 'profile'}`,
+    };
+  } else if (contextProfile?.capacityTokens?.unverified) {
+    capacity = {
+      value: null,
+      basis: `unknown:${contextProfile.capacityTokens.unverified}`,
+    };
+  } else {
+    capacity = {
+      value: null,
+      basis: 'unknown:profile-value-unavailable',
+    };
+  }
+
+  if (contextProfile?.toolResultLimitBytes && typeof contextProfile.toolResultLimitBytes.value === 'number') {
+    toolResultLimitBytes = contextProfile.toolResultLimitBytes.value;
+  }
+
+  // 2. Cap resolution
+  let resolvedMaxBytes        ;
+  let source                                       ;
+  let startupTokens                                          = null;
+
+  if (Number.isInteger(maxBytes) && maxBytes > 0) {
+    resolvedMaxBytes = maxBytes;
+    source = 'override';
+  } else if (
+    contextProfile?.capacityTokens &&
+    typeof contextProfile.capacityTokens.value === 'number' &&
+    contextProfile?.reserveTokens &&
+    typeof contextProfile.reserveTokens.value === 'number'
+  ) {
+    // Profile available calculation: (capacity - startup - reserve) * 4
+    const effectiveBudgets = budgetsJson !== null && budgetsJson !== undefined ? budgetsJson : getBudgetsJson();
+    let startupTokensEstimate = 0;
+    let startupTokensBasis = 'unmeasured:no-entry';
+    if (effectiveBudgets?.startupContext && Array.isArray(effectiveBudgets.startupContext)) {
+      const entry = effectiveBudgets.startupContext.find((s     ) => s.harness === harness.id);
+      if (typeof entry?.tokensEst === 'number') {
+        startupTokensEstimate = entry.tokensEst;
+        startupTokensBasis = entry.tokensBasis || 'estimated:bytes/4';
+      } else if (entry?.sessionStartStdoutBytes?.unmeasured) {
+        startupTokensBasis = `unmeasured:${entry.sessionStartStdoutBytes.unmeasured}`;
+      }
+    }
+    startupTokens = {
+      value: startupTokensEstimate,
+      basis: startupTokensBasis,
+    };
+    const available = (contextProfile.capacityTokens.value - startupTokensEstimate - contextProfile.reserveTokens.value) * 4;
+    resolvedMaxBytes = Math.max(0, available);
+    source = 'profile';
+  } else {
+    resolvedMaxBytes = TASK_CLASS_BUDGETS[taskClass] || 225000;
+    source = 'task-class';
+  }
+
+  return {
+    maxBytes: resolvedMaxBytes,
+    source,
+    harness,
+    capacity,
+    toolResultLimitBytes,
+    ...(startupTokens ? { startupTokens } : {}),
+  };
+}
+
+module.exports = {
+  TASK_CLASS_BUDGETS,
+  resolveBudget,
+  getRegisteredHarnessIds,
+  getRegisteredHarnesses,
+  clearRegistryCache,
+  getRegistryLoadCount,
+};