@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/config/schema.mjs

@@ -0,0 +1,159 @@
+/**
+ * lib/config/schema.mjs — construct.config.json v1 schema + tiny validator.
+ *
+ * Defines the project-level config shape. Hand-rolled validator instead of
+ * AJV/zod to keep Construct dependency-free at startup — the loader runs
+ * before npm install completes in some bootstrap paths.
+ *
+ * Schema v1 covers: alias, deployment, providers, autoEmbed, telemetry.
+ * Tier model selection lives in `agents/registry.json` only — this config
+ * file is intentionally not a second edit surface for model assignments.
+ * Later phases (6, 7b) extend it with `resources` and `costs` blocks
+ * without bumping the version — additive keys are allowed.
+ *
+ * Secret interpolation rule: any string starting with `$` is treated as
+ * an env-var pointer (`"$ANTHROPIC_API_KEY"` resolves at load time from
+ * process.env). Pointers keep secrets in .env where they belong.
+ */
+
+export const CONFIG_SCHEMA_VERSION = 1;
+
+export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
+export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
+
+export const DEFAULT_PROJECT_CONFIG = Object.freeze({
+  version: CONFIG_SCHEMA_VERSION,
+  alias: 'Construct',
+  deployment: Object.freeze({
+    mode: 'solo',
+    mcpBroker: 'auto',
+    projectName: null,
+    tenantId: null,
+  }),
+  providers: Object.freeze({}),
+  autoEmbed: false,
+  telemetry: Object.freeze({
+    enabled: true,
+  }),
+  roleSelection: Object.freeze({
+    primary: null,
+    secondary: null,
+    perConversationOverride: true,
+  }),
+  resources: Object.freeze({
+    disk: Object.freeze({
+      tracesMaxDays: 30,
+      intakeArchiveMaxItems: 500,
+      intakeArchiveMaxDays: 90,
+      taskGraphsMaxItems: 200,
+      taskGraphsMaxDays: 90,
+      workerLogsMaxMb: 100,
+      workerLogsMaxDays: 14,
+      sessionsMaxItems: 100,
+      backupsMaxDays: 60,
+      handoffsMaxDays: 30,
+      handoffsMaxItems: 50,
+      totalCxMaxMb: 2000,
+    }),
+    process: Object.freeze({
+      embedDaemonMaxRssMb: 800,
+      mcpServerMaxRssMb: 250,
+      workerReplicaMaxRssMb: 256,
+    }),
+  }),
+});
+
+export const FIELD_RULES = {
+  version: { type: 'number', required: true },
+  alias: { type: 'string', required: false, maxLength: 120 },
+  deployment: {
+    type: 'object',
+    required: false,
+    fields: {
+      mode: { type: 'string', enum: DEPLOYMENT_MODES },
+      mcpBroker: { type: 'string', enum: MCP_BROKER_VALUES },
+      projectName: { type: ['string', 'null'] },
+      tenantId: { type: ['string', 'null'] },
+    },
+  },
+  providers: { type: 'object', required: false },
+  autoEmbed: { type: 'boolean', required: false },
+  telemetry: {
+    type: 'object',
+    required: false,
+    fields: {
+      enabled: { type: 'boolean' },
+    },
+  },
+  roleSelection: {
+    type: 'object',
+    required: false,
+    fields: {
+      primary: { type: ['string', 'null'], maxLength: 50 },
+      secondary: { type: ['string', 'null'], maxLength: 50 },
+      perConversationOverride: { type: 'boolean' },
+    },
+  },
+  resources: { type: 'object', required: false },
+  costs: {
+    type: 'object',
+    required: false,
+    fields: {
+      billingMode: { type: 'string', enum: ['metered', 'subscription', 'mixed'] },
+      enforce: { type: 'boolean' },
+      budgets: { type: 'object' },
+      // Per-provider billing-mode overrides. The global billingMode is the
+      // fallback; entries here win for the provider id (anthropic, openai,
+      // openrouter, gemini, ollama, local, github-copilot, …). Subscription
+      // entries contribute $0 to "actual spend" headline numbers; the
+      // metered-equivalent stays in the footnote.
+      providers: { type: 'object', required: false },
+    },
+  },
+};
+
+function checkType(value, expected) {
+  if (Array.isArray(expected)) return expected.some((t) => checkType(value, t));
+  if (expected === 'null') return value === null;
+  if (expected === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (expected === 'array') return Array.isArray(value);
+  return typeof value === expected;
+}
+
+function validateField(value, rule, path) {
+  const errors = [];
+  if (value === undefined) {
+    if (rule.required) errors.push(`${path}: required field missing`);
+    return errors;
+  }
+  if (!checkType(value, rule.type)) {
+    errors.push(`${path}: expected type ${JSON.stringify(rule.type)}, got ${value === null ? 'null' : typeof value}`);
+    return errors;
+  }
+  if (rule.enum && !rule.enum.includes(value)) {
+    errors.push(`${path}: must be one of ${JSON.stringify(rule.enum)}, got ${JSON.stringify(value)}`);
+  }
+  if (rule.maxLength && typeof value === 'string' && value.length > rule.maxLength) {
+    errors.push(`${path}: exceeds maxLength ${rule.maxLength}`);
+  }
+  if (rule.fields && checkType(value, 'object')) {
+    for (const [key, subRule] of Object.entries(rule.fields)) {
+      errors.push(...validateField(value[key], subRule, `${path}.${key}`));
+    }
+  }
+  return errors;
+}
+
+export function validateProjectConfig(raw) {
+  const errors = [];
+  if (!checkType(raw, 'object')) {
+    return { valid: false, errors: ['root: must be an object'] };
+  }
+  for (const [key, rule] of Object.entries(FIELD_RULES)) {
+    errors.push(...validateField(raw[key], rule, key));
+  }
+  if (raw.version !== undefined && raw.version !== CONFIG_SCHEMA_VERSION) {
+    errors.push(`version: expected ${CONFIG_SCHEMA_VERSION}, got ${raw.version}`);
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}

package/lib/context-router.mjs

@@ -0,0 +1,308 @@
+/**
+ * lib/context-router.mjs — role-aware context routing for persona dispatch.
+ *
+ * Reduces token waste and context leakage by giving each persona only the
+ * artifact types its role policy prefers, within a caller-supplied token
+ * budget. Routing is deterministic: same input → same output. Each kept
+ * artifact carries a `reason` string; each omitted candidate carries the
+ * reason it was dropped so debug output can explain the packet end-to-end.
+ *
+ * Per-role policies map a persona name to a prioritized list of artifact
+ * kinds (e.g. product-manager prefers user-signal → prd → research-brief).
+ * Unknown roles fall through to a DEFAULT_POLICY so the router never
+ * silently produces an empty packet.
+ *
+ * The router does not call retrieval. The caller does hybrid retrieval
+ * up front, then hands the candidate list in. Keeps this module pure and
+ * fast to test.
+ */
+
+const APPROX_CHARS_PER_TOKEN = 4;
+
+function approximateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(String(text).length / APPROX_CHARS_PER_TOKEN);
+}
+
+function artifactTokenCost(artifact) {
+  return approximateTokens(artifact.summary || '') + approximateTokens(artifact.title || '') + approximateTokens(artifact.path || '');
+}
+
+/**
+ * Per-role context policy. `prefers` is an ordered list of artifact kinds
+ * for that role. `avoids` is an explicit reject list. `maxArtifacts` caps
+ * the count regardless of budget. Roles not listed here fall back to
+ * DEFAULT_POLICY.
+ *
+ * Artifact `kind` strings align with the existing storage taxonomy
+ * (lib/docs-routing.mjs lanes and construct_documents.kind values):
+ * user-signal, prd, prfaq, research-brief, adr, rfc, system-design,
+ * interface-contract, dep-map, target-file, test, build-command,
+ * eval-spec, success-metric, failure-case, trace, quality-score,
+ * incident, runbook, slo, log, service-dep.
+ */
+export const ROLE_POLICIES = {
+  'product-manager': {
+    prefers: ['user-signal', 'prd', 'prfaq', 'research-brief', 'acceptance-criteria', 'roadmap'],
+    avoids: ['runbook', 'service-dep'],
+    maxArtifacts: 8,
+  },
+  'ux-researcher': {
+    prefers: ['user-signal', 'research-brief', 'prfaq', 'prd'],
+    avoids: ['runbook', 'service-dep', 'interface-contract'],
+    maxArtifacts: 8,
+  },
+  'business-strategist': {
+    prefers: ['research-brief', 'prfaq', 'prd', 'roadmap'],
+    avoids: ['runbook', 'target-file'],
+    maxArtifacts: 8,
+  },
+  'researcher': {
+    prefers: ['research-brief', 'user-signal', 'prfaq', 'eval-spec'],
+    avoids: ['runbook'],
+    maxArtifacts: 10,
+  },
+  'rd-lead': {
+    prefers: ['research-brief', 'eval-spec', 'prfaq', 'prd', 'failure-case'],
+    avoids: ['runbook'],
+    maxArtifacts: 10,
+  },
+  'architect': {
+    prefers: ['adr', 'rfc', 'system-design', 'interface-contract', 'dep-map'],
+    avoids: ['runbook', 'user-signal'],
+    maxArtifacts: 8,
+  },
+  'ai-engineer': {
+    prefers: ['eval-spec', 'failure-case', 'trace', 'system-design', 'target-file'],
+    avoids: ['runbook'],
+    maxArtifacts: 10,
+  },
+  'engineer': {
+    prefers: ['target-file', 'test', 'interface-contract', 'build-command', 'system-design'],
+    avoids: ['prfaq', 'roadmap', 'user-signal'],
+    maxArtifacts: 12,
+  },
+  'debugger': {
+    prefers: ['target-file', 'test', 'trace', 'failure-case', 'log'],
+    avoids: ['prfaq', 'roadmap'],
+    maxArtifacts: 10,
+  },
+  'qa': {
+    prefers: ['test', 'acceptance-criteria', 'failure-case', 'target-file'],
+    avoids: ['research-brief', 'prfaq'],
+    maxArtifacts: 10,
+  },
+  'reviewer': {
+    prefers: ['target-file', 'test', 'interface-contract', 'adr'],
+    avoids: ['prfaq', 'roadmap'],
+    maxArtifacts: 10,
+  },
+  'evaluator': {
+    prefers: ['eval-spec', 'success-metric', 'failure-case', 'trace', 'quality-score'],
+    avoids: ['runbook', 'user-signal'],
+    maxArtifacts: 10,
+  },
+  'trace-reviewer': {
+    prefers: ['trace', 'failure-case', 'quality-score', 'eval-spec'],
+    avoids: ['runbook', 'roadmap'],
+    maxArtifacts: 10,
+  },
+  'security': {
+    prefers: ['adr', 'interface-contract', 'target-file', 'trace', 'failure-case'],
+    avoids: ['roadmap', 'prfaq'],
+    maxArtifacts: 10,
+  },
+  'sre': {
+    prefers: ['incident', 'runbook', 'slo', 'log', 'service-dep'],
+    avoids: ['prfaq', 'roadmap', 'research-brief'],
+    maxArtifacts: 12,
+  },
+  'platform-engineer': {
+    prefers: ['service-dep', 'runbook', 'slo', 'interface-contract', 'target-file'],
+    avoids: ['prfaq', 'roadmap'],
+    maxArtifacts: 12,
+  },
+  'operations': {
+    prefers: ['runbook', 'service-dep', 'slo', 'dep-map'],
+    avoids: ['prfaq', 'research-brief'],
+    maxArtifacts: 10,
+  },
+  'release-manager': {
+    prefers: ['acceptance-criteria', 'test', 'changelog', 'roadmap'],
+    avoids: ['research-brief'],
+    maxArtifacts: 8,
+  },
+  'docs-keeper': {
+    prefers: ['adr', 'rfc', 'prd', 'changelog'],
+    avoids: ['log', 'trace'],
+    maxArtifacts: 10,
+  },
+  'legal-compliance': {
+    prefers: ['adr', 'prfaq', 'research-brief', 'interface-contract'],
+    avoids: ['runbook', 'log'],
+    maxArtifacts: 8,
+  },
+  'designer': {
+    prefers: ['prd', 'prfaq', 'user-signal', 'research-brief'],
+    avoids: ['runbook', 'target-file'],
+    maxArtifacts: 8,
+  },
+  'accessibility': {
+    prefers: ['prd', 'failure-case', 'test', 'target-file'],
+    avoids: ['runbook', 'research-brief'],
+    maxArtifacts: 8,
+  },
+  'data-analyst': {
+    prefers: ['research-brief', 'success-metric', 'trace', 'eval-spec'],
+    avoids: ['runbook', 'roadmap'],
+    maxArtifacts: 10,
+  },
+  'data-engineer': {
+    prefers: ['interface-contract', 'system-design', 'target-file', 'dep-map'],
+    avoids: ['prfaq', 'roadmap'],
+    maxArtifacts: 10,
+  },
+  'explorer': {
+    prefers: ['research-brief', 'user-signal', 'prd', 'rfc'],
+    avoids: [],
+    maxArtifacts: 12,
+  },
+  'orchestrator': {
+    prefers: ['rfc', 'adr', 'prd', 'roadmap'],
+    avoids: [],
+    maxArtifacts: 10,
+  },
+};
+
+const DEFAULT_POLICY = {
+  prefers: ['rfc', 'adr', 'prd', 'target-file', 'test'],
+  avoids: [],
+  maxArtifacts: 8,
+};
+
+const DEFAULT_BUDGET_TOKENS = 6000;
+
+function policyFor(role) {
+  return ROLE_POLICIES[role] || DEFAULT_POLICY;
+}
+
+function scoreCandidate(candidate, policy) {
+  const kind = candidate.kind || 'unknown';
+  if (policy.avoids.includes(kind)) return -1;
+  const preferIdx = policy.prefers.indexOf(kind);
+  const preferenceScore = preferIdx === -1 ? 0 : (policy.prefers.length - preferIdx) / policy.prefers.length;
+  const retrievalScore = typeof candidate.score === 'number' ? candidate.score : 0;
+  return preferenceScore * 0.7 + retrievalScore * 0.3;
+}
+
+function reasonForKeep(candidate, policy) {
+  const kind = candidate.kind || 'unknown';
+  const idx = policy.prefers.indexOf(kind);
+  if (idx !== -1) return `role prioritizes "${kind}" (rank ${idx + 1}/${policy.prefers.length})`;
+  return `acceptable kind "${kind}" for role`;
+}
+
+function reasonForOmit(candidate, policy, cause) {
+  const kind = candidate.kind || 'unknown';
+  if (cause === 'avoid') return `kind "${kind}" is in this role's avoid list`;
+  if (cause === 'budget') return `exceeded token budget`;
+  if (cause === 'maxArtifacts') return `role's maxArtifacts cap (${policy.maxArtifacts}) reached`;
+  return 'no reason recorded';
+}
+
+function buildTaskSummary(request, triage) {
+  const lines = [];
+  if (request) lines.push(String(request).slice(0, 240));
+  if (triage?.intakeType && triage.intakeType !== 'unknown') {
+    lines.push(`Triage: ${triage.intakeType} / ${triage.rdStage} · owner ${triage.primaryOwner} · next ${triage.recommendedAction}`);
+  }
+  return lines.join(' — ');
+}
+
+/**
+ * Build a role-aware context packet.
+ *
+ * @param {object} opts
+ * @param {string} opts.request
+ * @param {object} [opts.triage]
+ * @param {string} opts.role
+ * @param {string} [opts.project]
+ * @param {object} [opts.budget]
+ * @param {number} [opts.budget.maxTokens]
+ * @param {Array}  [opts.candidates] — pre-retrieved artifacts (path, title, kind, summary, score)
+ * @param {Array}  [opts.constraints]
+ * @param {Array}  [opts.priorObservations]
+ * @param {Array}  [opts.verificationRequirements]
+ * @returns {{ role: string, contextPacket: object, omitted: Array, tokensUsed: number }}
+ */
+export function buildContextPacket({
+  request = '',
+  triage = null,
+  role = 'orchestrator',
+  project = null,
+  budget = {},
+  candidates = [],
+  constraints = [],
+  priorObservations = [],
+  verificationRequirements = [],
+} = {}) {
+  const policy = policyFor(role);
+  const maxTokens = budget?.maxTokens ?? DEFAULT_BUDGET_TOKENS;
+
+  const partitioned = [];
+  const omitted = [];
+
+  for (const c of candidates) {
+    const score = scoreCandidate(c, policy);
+    if (score < 0) {
+      omitted.push({ artifact: c, reason: reasonForOmit(c, policy, 'avoid') });
+      continue;
+    }
+    partitioned.push({ candidate: c, score });
+  }
+
+  partitioned.sort((a, b) => b.score - a.score);
+
+  const taskSummary = buildTaskSummary(request, triage);
+  let tokensUsed = approximateTokens(taskSummary);
+  const relatedArtifacts = [];
+
+  for (const { candidate } of partitioned) {
+    if (relatedArtifacts.length >= policy.maxArtifacts) {
+      omitted.push({ artifact: candidate, reason: reasonForOmit(candidate, policy, 'maxArtifacts') });
+      continue;
+    }
+    const cost = artifactTokenCost(candidate);
+    if (tokensUsed + cost > maxTokens) {
+      omitted.push({ artifact: candidate, reason: reasonForOmit(candidate, policy, 'budget') });
+      continue;
+    }
+    tokensUsed += cost;
+    relatedArtifacts.push({
+      path: candidate.path,
+      title: candidate.title,
+      kind: candidate.kind,
+      summary: candidate.summary,
+      reason: reasonForKeep(candidate, policy),
+    });
+  }
+
+  const relevantFiles = relatedArtifacts
+    .filter((a) => a.kind === 'target-file' || a.kind === 'test')
+    .map(({ path, reason, kind }) => ({ path, kind, reason }));
+
+  return {
+    role,
+    project,
+    contextPacket: {
+      taskSummary,
+      relevantFiles,
+      relatedArtifacts,
+      priorObservations: [...priorObservations],
+      constraints: [...constraints],
+      verificationRequirements: [...verificationRequirements],
+    },
+    omitted,
+    tokensUsed,
+  };
+}

package/lib/cost-ledger.mjs

@@ -0,0 +1,177 @@
+/**
+ * lib/cost-ledger.mjs — per-persona / per-day token-spend ledger.
+ *
+ * Tracks Claude API spend so the gateway can hard-stop persona invocations
+ * before they blow the daily budget. Separate from lib/roles/ because both
+ * the gateway and the cost watcher consume it.
+ *
+ * Storage: ~/.cx/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
+ * Rotates: entries older than 30 days are pruned on each write.
+ *
+ * Budgets are env-driven defaults; explicit `CONSTRUCT_BUDGET_<PERSONA>` wins.
+ *   CONSTRUCT_BUDGET_DEFAULT     — per persona, USD/day (default 1.00)
+ *   CONSTRUCT_BUDGET_TOTAL       — across all personas, USD/day (default 10.00)
+ *   CONSTRUCT_BUDGET_<PERSONA>   — specific persona override (uppercase, dashes → underscores)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { cwd as procCwd } from 'node:process';
+
+const PRUNE_DAYS = 30;
+const DEFAULT_PER_PERSONA = 10.0;
+const DEFAULT_TOTAL = 50.0;
+
+function rootDir() {
+  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+}
+function ledgerPath() {
+  return join(rootDir(), 'cost-ledger.json');
+}
+function ensureDir() {
+  const r = rootDir();
+  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+}
+
+export function dayKey(ts = Date.now()) {
+  const d = new Date(ts);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')}`;
+}
+
+function load() {
+  const p = ledgerPath();
+  if (!existsSync(p)) return {};
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; }
+}
+
+function save(state) {
+  ensureDir();
+  const cutoff = dayKey(Date.now() - PRUNE_DAYS * 24 * 60 * 60 * 1000);
+  const trimmed = {};
+  for (const [key, value] of Object.entries(state)) {
+    const k = key.split(':')[0];
+    if (k >= cutoff) trimmed[key] = value;
+  }
+  writeFileSync(ledgerPath(), JSON.stringify(trimmed));
+}
+
+export function recordSpend({ personaId, tokens = 0, costUsd = 0, sessionId = '', ts = Date.now() }) {
+  if (process.env.CONSTRUCT_ROLES === 'off') return null;
+  const state = load();
+  const tsMs = typeof ts === 'string' ? Date.parse(ts) : Number(ts);
+  const bucketTs = Number.isFinite(tsMs) && tsMs > 0 ? tsMs : Date.now();
+  const key = `${dayKey(bucketTs)}:${personaId || 'unknown'}`;
+  const entry = state[key] || { tokens: 0, costUsd: 0, invocations: 0, sessions: [] };
+  entry.tokens += tokens;
+  entry.costUsd += costUsd;
+  entry.invocations += 1;
+  if (sessionId && !entry.sessions.includes(sessionId)) entry.sessions.push(sessionId);
+  state[key] = entry;
+  save(state);
+  return entry;
+}
+
+export function getDailySpend({ personaId, ts = Date.now() } = {}) {
+  const state = load();
+  const key = `${dayKey(ts)}:${personaId || 'unknown'}`;
+  return state[key] || { tokens: 0, costUsd: 0, invocations: 0, sessions: [] };
+}
+
+export function getTotalDailySpend({ ts = Date.now() } = {}) {
+  const state = load();
+  const dk = dayKey(ts);
+  let total = { tokens: 0, costUsd: 0, invocations: 0 };
+  for (const [key, value] of Object.entries(state)) {
+    if (key.startsWith(dk + ':')) {
+      total.tokens += value.tokens;
+      total.costUsd += value.costUsd;
+      total.invocations += value.invocations;
+    }
+  }
+  return total;
+}
+
+function envBudget(name, fallback) {
+  const v = parseFloat(process.env[name]);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+// Reads construct.config.json.costs.budgets at lookup time. JSON wins
+// when set; env vars are back-compat fallback. Loader is best-effort
+// — config errors fall through to env / default so budget checks never
+// throw on a malformed file.
+function configBudgetValue(keyPath) {
+  try {
+    const cfgPath = join(procCwd(), 'construct.config.json');
+    if (!existsSync(cfgPath)) return null;
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    let cur = cfg;
+    for (const part of keyPath.split('.')) {
+      if (cur === null || typeof cur !== 'object') return null;
+      cur = cur[part];
+    }
+    const n = Number(cur);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch { return null; }
+}
+
+export function personaBudget(personaId) {
+  const envName = `CONSTRUCT_BUDGET_${String(personaId || '').toUpperCase().replace(/-/g, '_')}`;
+  const specific = parseFloat(process.env[envName]);
+  if (Number.isFinite(specific) && specific > 0) return specific;
+  const fromConfig = configBudgetValue(`costs.budgets.${personaId}.dailyUsd`);
+  if (fromConfig) return fromConfig;
+  const fromConfigDefault = configBudgetValue('costs.budgets.default.dailyUsd');
+  if (fromConfigDefault) return fromConfigDefault;
+  return envBudget('CONSTRUCT_BUDGET_DEFAULT', DEFAULT_PER_PERSONA);
+}
+
+export function totalBudget() {
+  const envVal = parseFloat(process.env.CONSTRUCT_BUDGET_TOTAL);
+  if (Number.isFinite(envVal) && envVal > 0) return envVal;
+  const fromConfig = configBudgetValue('costs.budgets.total.dailyUsd');
+  if (fromConfig) return fromConfig;
+  return DEFAULT_TOTAL;
+}
+
+export function enforcementActive() {
+  if (process.env.CONSTRUCT_BUDGET_ENFORCE === 'on') return true;
+  if (process.env.CONSTRUCT_BUDGET_ENFORCE === 'off') return false;
+  try {
+    const cfgPath = join(procCwd(), 'construct.config.json');
+    if (!existsSync(cfgPath)) return false;
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    return Boolean(cfg?.costs?.enforce);
+  } catch { return false; }
+}
+
+export function checkBudget({ personaId }) {
+  // Default to advisory-only. Hard-stop when CONSTRUCT_BUDGET_ENFORCE=on or
+  // construct.config.json.costs.enforce=true. Ledger still records and
+  // reports spend in both modes so over-budget shows up in the doctor
+  // report regardless.
+  if (!enforcementActive()) {
+    return { allowed: true, reason: 'enforcement-advisory' };
+  }
+  const personaSpend = getDailySpend({ personaId });
+  const personaCap = personaBudget(personaId);
+  if (personaSpend.costUsd >= personaCap) {
+    return { allowed: false, reason: 'persona-budget-exhausted', spent: personaSpend.costUsd, cap: personaCap };
+  }
+  const total = getTotalDailySpend();
+  const totalCap = totalBudget();
+  if (total.costUsd >= totalCap) {
+    return { allowed: false, reason: 'total-budget-exhausted', spent: total.costUsd, cap: totalCap };
+  }
+  const warnAt = 0.8;
+  let warning = null;
+  if (personaSpend.costUsd / personaCap >= warnAt) {
+    warning = `persona ${personaId} at ${Math.round((personaSpend.costUsd / personaCap) * 100)}% of $${personaCap.toFixed(2)} daily cap`;
+  } else if (total.costUsd / totalCap >= warnAt) {
+    warning = `total spend at ${Math.round((total.costUsd / totalCap) * 100)}% of $${totalCap.toFixed(2)} daily cap`;
+  }
+  return { allowed: true, reason: 'within-budget', warning };
+}
+
+export const _paths = { rootDir, ledgerPath };