@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/improvement/controller.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/improvement/controller.mjs — the approval-gated improvement-loop controller
+ * (construct-6zga.1.5).
+ *
+ * The controller is the mutation boundary for the governed loop. It admits only
+ * versioned artifacts — proposal objects, dataset items, and evaluation reports,
+ * never raw chat history — and refuses any candidate that lacks provenance,
+ * lacks held-out evaluation evidence, failed a deterministic gate, names an unknown
+ * approver, or has an unresolved dependency. Promotability is re-derived from the
+ * report's own gate results rather than a precomputed flag, so a tampered decision
+ * cannot pass. The final mutation boundary requires an explicit human approval act,
+ * recorded with the approver identity and timestamp; the controller never applies a
+ * change itself — it plans the rollout and records the human-performed apply and
+ * rollback, keeping the loop a chain of proposals, not autonomous mutations.
+ */
+import { transitionProposal, validateProposal } from './proposal.mjs';
+import { decidePromotion } from '../evals/gates.mjs';
+
+function isVersioned(artifact) {
+  return Boolean(artifact && typeof artifact === 'object' && Number.isInteger(artifact.schemaVersion));
+}
+
+/**
+ * Admit the input artifacts. Only versioned proposal/dataset/evaluation objects are
+ * accepted; an unversioned blob (such as raw chat history) is refused
+ * (construct-6zga.1.5 AC1).
+ */
+export function admitArtifacts({ proposal = null, dataset = null, evaluationReport = null } = {}) {
+  const refusals = [];
+  if (!validateProposal(proposal).valid) refusals.push('proposal-invalid');
+  if (!isVersioned(dataset)) refusals.push('dataset-unversioned');
+  if (!isVersioned(evaluationReport)) refusals.push('evaluation-report-unversioned');
+  return { admissible: refusals.length === 0, refusals };
+}
+
+/**
+ * Evaluate the refusal guards. Missing provenance, missing held-out results, a
+ * failed deterministic gate, an unknown approver, or an unresolved dependency each
+ * blocks the proposal from reaching the approval boundary (construct-6zga.1.5 AC2).
+ */
+export function evaluateGuards({ proposal = null, evaluationReport = null, knownApprovers = [], resolvedDependencies = [] } = {}) {
+  const refusals = [];
+
+  const traces = proposal?.lineage?.inputTraceIds;
+  if (!Array.isArray(traces) || traces.length < 1) refusals.push('insufficient-provenance');
+
+  if (!evaluationReport || evaluationReport.deltas == null) refusals.push('missing-held-out-results');
+  if (evaluationReport?.blocked === true) refusals.push('failed-deterministic-checks');
+
+  const approverId = proposal?.approver?.identity ?? null;
+  if (!approverId || !knownApprovers.includes(approverId)) refusals.push('unknown-approver');
+
+  const deps = Array.isArray(proposal?.dependencies) ? proposal.dependencies : [];
+  const resolved = new Set(resolvedDependencies);
+  if (deps.some((d) => !resolved.has(d))) refusals.push('unresolved-dependency');
+
+  return { admissible: refusals.length === 0, refusals };
+}
+
+/**
+ * Run the full admission + guard pipeline and re-derive promotability from the
+ * report's gate results (judges never stand alone). Returns the stage that refused,
+ * or admissible: true once the proposal is ready for the human approval boundary.
+ */
+export function governProposal({ proposal = null, dataset = null, evaluationReport = null, knownApprovers = [], resolvedDependencies = [] } = {}) {
+  const admission = admitArtifacts({ proposal, dataset, evaluationReport });
+  if (!admission.admissible) return { admissible: false, stage: 'admission', refusals: admission.refusals };
+
+  const guards = evaluateGuards({ proposal, evaluationReport, knownApprovers, resolvedDependencies });
+  if (!guards.admissible) return { admissible: false, stage: 'guards', refusals: guards.refusals };
+
+  const gates = Array.isArray(evaluationReport.gates) ? evaluationReport.gates : [];
+  const deterministic = {
+    blocked: evaluationReport.blocked === true,
+    regressions: gates.filter((g) => !g.pass).map((g) => g.gate),
+    gates,
+  };
+  const promotion = decidePromotion({ deterministic, judges: evaluationReport.evaluators || [] });
+  if (!promotion.promotable) return { admissible: false, stage: 'promotion', refusals: ['not-promotable'], promotion };
+
+  return { admissible: true, stage: 'awaiting-approval', refusals: [], promotion };
+}
+
+/**
+ * The final mutation boundary: an explicit human approval act is mandatory and is
+ * recorded with the approver identity and timestamp. Transitions
+ * awaiting_approval -> approved, or refuses (construct-6zga.1.5 AC3).
+ */
+export function requireApproval({ proposal = null, approval = null, knownApprovers = [], nowIso = null } = {}) {
+  if (proposal?.state !== 'awaiting_approval') {
+    return { ok: false, error: `approval requires state awaiting_approval, got ${proposal?.state}` };
+  }
+  const identity = approval?.identity ?? null;
+  if (!identity || !knownApprovers.includes(identity)) {
+    return { ok: false, error: 'approval refused: unknown approver' };
+  }
+  const approver = { identity, approvedAt: approval?.approvedAt ?? nowIso, decision: 'approved' };
+  return transitionProposal(proposal, 'approved', { approver });
+}
+
+/**
+ * Plan a traceable rollout for an approved proposal: sandbox, staged apply, and
+ * post-apply monitoring, plus the rollback target and blast radius. The controller
+ * plans but never applies — application is a human-performed action
+ * (construct-6zga.1.5 AC4).
+ */
+export function planRollout({ proposal = null } = {}) {
+  if (proposal?.state !== 'approved') return { ok: false, error: `rollout requires state approved, got ${proposal?.state}` };
+  return {
+    ok: true,
+    plan: {
+      mode: proposal.rolloutMode,
+      steps: ['sandbox', 'staged-apply', 'post-apply-monitor'],
+      rollbackTarget: proposal.rollbackTarget,
+      affectedProfiles: proposal.affectedProfiles,
+      blastRadius: proposal.blastRadius,
+    },
+  };
+}
+
+/**
+ * Record a human-performed application (approved -> applied) with its monitor
+ * handle, keeping the apply traceable (construct-6zga.1.5 AC4).
+ */
+export function recordApplication({ proposal = null, monitor = null, nowIso = null } = {}) {
+  return transitionProposal(proposal, 'applied', { rollout: { appliedAt: nowIso, monitor } });
+}
+
+/**
+ * Record a deterministic rollback (applied -> rolled_back) to the proposal's
+ * declared rollback target (construct-6zga.1.5 AC4).
+ */
+export function recordRollback({ proposal = null, reason = null, nowIso = null } = {}) {
+  return transitionProposal(proposal, 'rolled_back', {
+    rollout: { rolledBackTo: proposal?.rollbackTarget ?? null, reason, rolledBackAt: nowIso },
+  });
+}

package/lib/improvement/proposal.mjs

@@ -0,0 +1,120 @@
+/**
+ * lib/improvement/proposal.mjs — the improvement-loop proposal record and its
+ * operator state machine (construct-6zga.1.5).
+ *
+ * Every candidate change in the governed loop is a proposal, never an applied
+ * mutation. A proposal declares its type, the affected profiles, the blast radius,
+ * a rollback target, the gates to pass, an approver, and a rollout mode, plus
+ * immutable lineage — input-trace references, baseline/candidate versions, the
+ * capability snapshot, evaluator versions, and budgets — so a reader can re-verify
+ * its provenance. The operator state machine encodes the only legal progressions
+ * (observed through applied/rolled_back), so a proposal can never jump the held-out
+ * evaluation or the approval boundary by skipping a state.
+ * Reference shape: schemas/improvement-proposal.schema.json.
+ */
+
+export const IMPROVEMENT_PROPOSAL_SCHEMA_VERSION = 1;
+
+export const PROPOSAL_TYPES = Object.freeze([
+  'prompt',
+  'role-flavor',
+  'skill',
+  'routing-rule',
+  'contract',
+  'provider-adapter',
+  'policy-config',
+]);
+
+export const PROPOSAL_STATES = Object.freeze([
+  'observed',
+  'rejected',
+  'reproduce_failed',
+  'baseline_failed',
+  'proposal_ready',
+  'evaluation_failed',
+  'awaiting_approval',
+  'approved',
+  'applied',
+  'rolled_back',
+  'superseded',
+]);
+
+export const BLAST_RADIUS = Object.freeze(['single-surface', 'multi-surface', 'global']);
+export const ROLLOUT_MODES = Object.freeze(['sandbox', 'staged', 'monitored']);
+
+// The only legal state progressions. superseded is reachable from any non-terminal
+// state (a newer proposal replaces this one); the terminal states have no
+// successor. Nothing reaches applied without passing through approved, and nothing
+// reaches approved without awaiting_approval — the held-out evaluation and the
+// human approval boundary cannot be skipped.
+
+const LEGAL_TRANSITIONS = Object.freeze({
+  observed: Object.freeze(['reproduce_failed', 'proposal_ready', 'rejected', 'superseded']),
+  proposal_ready: Object.freeze(['baseline_failed', 'evaluation_failed', 'awaiting_approval', 'superseded']),
+  awaiting_approval: Object.freeze(['approved', 'rejected', 'superseded']),
+  approved: Object.freeze(['applied', 'superseded']),
+  applied: Object.freeze(['rolled_back', 'superseded']),
+  rejected: Object.freeze([]),
+  reproduce_failed: Object.freeze([]),
+  baseline_failed: Object.freeze([]),
+  evaluation_failed: Object.freeze([]),
+  rolled_back: Object.freeze([]),
+  superseded: Object.freeze([]),
+});
+
+export function isTerminalState(state) {
+  return Array.isArray(LEGAL_TRANSITIONS[state]) && LEGAL_TRANSITIONS[state].length === 0;
+}
+
+export function canTransition(from, to) {
+  return Array.isArray(LEGAL_TRANSITIONS[from]) && LEGAL_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Advance a proposal to a new state, merging an optional patch. Returns
+ * { ok, proposal } on a legal transition or { ok: false, error } otherwise, so the
+ * controller can refuse rather than throw on an illegal progression.
+ */
+export function transitionProposal(proposal, to, patch = {}) {
+  const from = proposal?.state;
+  if (!PROPOSAL_STATES.includes(to)) return { ok: false, error: `unknown target state: ${to}` };
+  if (!canTransition(from, to)) return { ok: false, error: `illegal transition: ${from} -> ${to}` };
+  return { ok: true, proposal: { ...proposal, ...patch, state: to } };
+}
+
+/**
+ * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
+ * Returns { valid, errors } against schemas/improvement-proposal.schema.json.
+ */
+export function validateProposal(proposal) {
+  const errors = [];
+  if (!proposal || typeof proposal !== 'object') return { valid: false, errors: ['proposal is not an object'] };
+  if (proposal.schemaVersion !== IMPROVEMENT_PROPOSAL_SCHEMA_VERSION) errors.push(`schemaVersion must be ${IMPROVEMENT_PROPOSAL_SCHEMA_VERSION}`);
+  if (typeof proposal.id !== 'string' || !proposal.id) errors.push('id required');
+  if (!PROPOSAL_TYPES.includes(proposal.type)) errors.push(`type invalid: ${proposal.type}`);
+  if (!PROPOSAL_STATES.includes(proposal.state)) errors.push(`state invalid: ${proposal.state}`);
+  if (!Array.isArray(proposal.affectedProfiles)) errors.push('affectedProfiles must be an array');
+  if (!BLAST_RADIUS.includes(proposal.blastRadius)) errors.push(`blastRadius invalid: ${proposal.blastRadius}`);
+  if (!proposal.rollbackTarget || typeof proposal.rollbackTarget !== 'object' || typeof proposal.rollbackTarget.version !== 'string') {
+    errors.push('rollbackTarget.version required');
+  }
+  if (!Array.isArray(proposal.requiredGates)) errors.push('requiredGates must be an array');
+  if (!ROLLOUT_MODES.includes(proposal.rolloutMode)) errors.push(`rolloutMode invalid: ${proposal.rolloutMode}`);
+
+  const lineage = proposal.lineage;
+  if (!lineage || typeof lineage !== 'object') errors.push('lineage missing');
+  else {
+    if (!Array.isArray(lineage.inputTraceIds)) errors.push('lineage.inputTraceIds must be an array');
+    if (typeof lineage.baselineVersion !== 'string') errors.push('lineage.baselineVersion required');
+    if (typeof lineage.candidateVersion !== 'string') errors.push('lineage.candidateVersion required');
+    if (!lineage.capabilitySnapshot || typeof lineage.capabilitySnapshot !== 'object') errors.push('lineage.capabilitySnapshot required');
+    if (!Array.isArray(lineage.evaluatorVersions)) errors.push('lineage.evaluatorVersions must be an array');
+  }
+
+  const approver = proposal.approver;
+  if (approver !== null && (typeof approver !== 'object' || typeof approver.identity !== 'string')) {
+    errors.push('approver must be null or carry an identity');
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/lib/improvement/specialist-loop.mjs

@@ -0,0 +1,192 @@
+/**
+ * lib/improvement/specialist-loop.mjs — opt-in, attribution-first specialist
+ * improvement (construct-6zga.1.7).
+ *
+ * Specialist improvement is triggered, never ambient: no generic self-review loop
+ * is inserted into every prompt, and an evaluation runs only from one of the
+ * bounded triggers (human correction, deterministic failure, repeated baseline
+ * regression, or an explicit operator request). Before any change is proposed, a
+ * failure is attributed causally across upstream context, provider execution, the
+ * handoff contract, the downstream consumer, evaluator uncertainty, and only last
+ * the specialist's own output — so a specialist is never blamed for an upstream or
+ * provider failure. A change is proposed only when the specialist itself is at
+ * fault, targets a single specialist artifact, and is routed through the governed
+ * controller, which holds it to held-out evaluation and human approval. Nothing
+ * here applies a change or routes on a score. Reference shape:
+ * schemas/specialist-trace.schema.json.
+ */
+import { governProposal } from './controller.mjs';
+
+export const SPECIALIST_TRACE_SCHEMA_VERSION = 1;
+
+export const FAILURE_CAUSES = Object.freeze([
+  'upstream-context',
+  'provider-execution',
+  'handoff-contract',
+  'downstream-consumer',
+  'evaluator-uncertainty',
+  'specialist-prompt',
+  'none',
+]);
+
+export const TRIGGER_KINDS = Object.freeze([
+  'human-correction',
+  'deterministic-failure',
+  'repeated-baseline-regression',
+  'operator-request',
+]);
+
+export const SPECIALIST_TARGETS = Object.freeze(['prompt', 'skill', 'role-flavor', 'routing-rule', 'contract']);
+
+const HUMAN_TARGET_TO_CAUSE = Object.freeze({
+  upstream: 'upstream-context',
+  contract: 'handoff-contract',
+  downstream: 'downstream-consumer',
+  provider: 'provider-execution',
+  specialist: 'specialist-prompt',
+});
+
+/**
+ * Attribute a failure to a single cause. External causes are checked before the
+ * specialist, so a specialist is blamed only once upstream context, provider
+ * execution, the input handoff contract, the downstream consumer, and evaluator
+ * certainty are all clean (construct-6zga.1.7 AC1, AC2). A human correction that
+ * names a non-specialist cause is authoritative.
+ */
+export function attributeFailure(trace = {}) {
+  const t = trace || {};
+  const correctionTarget = t.humanCorrection?.target ?? null;
+
+  if (correctionTarget && correctionTarget !== 'specialist') {
+    return { cause: HUMAN_TARGET_TO_CAUSE[correctionTarget] || 'upstream-context', blameSpecialist: false, detail: `human correction -> ${correctionTarget}` };
+  }
+  if (t.upstream?.evidenceComplete === false || t.upstream?.inputsPresent === false) {
+    return { cause: 'upstream-context', blameSpecialist: false, detail: 'upstream evidence or inputs incomplete' };
+  }
+  if (t.provider?.executionError === true || t.provider?.degraded === true) {
+    return { cause: 'provider-execution', blameSpecialist: false, detail: 'provider execution error or degraded' };
+  }
+  if (t.handoff?.inputValid === false) {
+    return { cause: 'handoff-contract', blameSpecialist: false, detail: 'handoff input contract violated' };
+  }
+  if (t.downstream?.consumerError === true) {
+    return { cause: 'downstream-consumer', blameSpecialist: false, detail: 'downstream consumer error' };
+  }
+  if (t.evaluator?.abstained === true) {
+    return { cause: 'evaluator-uncertainty', blameSpecialist: false, detail: 'evaluator abstained' };
+  }
+
+  const specialistFault = t.specialistOutput?.evidenceVerdict === 'fail'
+    || t.handoff?.schemaValid === false
+    || correctionTarget === 'specialist';
+  if (specialistFault) {
+    return { cause: 'specialist-prompt', blameSpecialist: true, detail: 'specialist output failed with every external cause clean' };
+  }
+  return { cause: 'none', blameSpecialist: false, detail: 'no attributable failure' };
+}
+
+/**
+ * The improvement loop is opt-in and bounded: it runs only when explicitly enabled
+ * and only for one of the four recognized triggers (construct-6zga.1.7 AC3).
+ */
+export function shouldTrigger({ kind = null, optIn = false } = {}) {
+  return optIn === true && TRIGGER_KINDS.includes(kind);
+}
+
+/**
+ * Build a scoped improvement proposal for a single specialist artifact — only when
+ * the specialist itself is at fault. A non-specialist cause yields no proposal, so
+ * an upstream or provider failure never rewrites a specialist (construct-6zga.1.7
+ * AC2, AC5).
+ */
+export function proposeSpecialistChange({ trace = {}, attribution = null, target = 'prompt', baselineVersion = null, candidateVersion = null, heldOutProfiles = [], approver = null } = {}) {
+  const attr = attribution || attributeFailure(trace);
+  if (!attr.blameSpecialist) return { proposed: false, reason: attr.cause, attribution: attr };
+
+  const profiles = Array.isArray(heldOutProfiles) && heldOutProfiles.length
+    ? heldOutProfiles
+    : [trace.specialist?.profileId].filter(Boolean);
+  const traceIds = Array.isArray(trace.sourceTraceIds) && trace.sourceTraceIds.length
+    ? trace.sourceTraceIds
+    : [trace.id].filter(Boolean);
+
+  const proposal = {
+    schemaVersion: 1,
+    id: `prop-${trace.id || 'specialist'}`,
+    type: SPECIALIST_TARGETS.includes(target) ? target : 'prompt',
+    state: 'proposal_ready',
+    affectedProfiles: profiles,
+    blastRadius: 'single-surface',
+    rollbackTarget: { version: baselineVersion || trace.versions?.[target] || 'unknown', ref: null },
+    requiredGates: ['contract-schema', 'source-provenance', 'safety-permission'],
+    rolloutMode: 'staged',
+    dependencies: [],
+    evaluationReportId: null,
+    terminalReason: null,
+    lineage: {
+      inputTraceIds: traceIds,
+      baselineVersion: baselineVersion || 'unknown',
+      candidateVersion: candidateVersion || 'unknown',
+      capabilitySnapshot: { capabilityClass: trace.specialist?.capabilityClass || 'unknown' },
+      evaluatorVersions: ['gates@1'],
+      budgets: null,
+    },
+    approver: approver ? { identity: approver, approvedAt: null, decision: null } : null,
+    rollout: null,
+  };
+  return { proposed: true, attribution: attr, proposal };
+}
+
+/**
+ * Run the opt-in specialist improvement loop end to end: gate on the trigger,
+ * attribute the failure, and — only when the specialist is at fault — build a
+ * scoped proposal and route it through the governed controller for held-out
+ * evaluation and human approval. Never applies a change and never routes on a
+ * score (construct-6zga.1.7 AC4, AC5).
+ */
+export function runSpecialistImprovement({
+  trace = {}, trigger = null, target = 'prompt', heldOutProfiles = [],
+  baselineVersion = null, candidateVersion = null, approver = null,
+  dataset = null, evaluationReport = null, knownApprovers = [], resolvedDependencies = [],
+} = {}) {
+  if (!shouldTrigger(trigger)) return { triggered: false, reason: 'not-triggered' };
+
+  const attribution = attributeFailure(trace);
+  if (!attribution.blameSpecialist) return { triggered: true, attribution, proposed: false, reason: attribution.cause };
+
+  const { proposal } = proposeSpecialistChange({ trace, attribution, target, baselineVersion, candidateVersion, heldOutProfiles, approver });
+  const governance = governProposal({ proposal, dataset, evaluationReport, knownApprovers, resolvedDependencies });
+  return { triggered: true, attribution, proposed: true, proposal, governance };
+}
+
+/**
+ * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
+ * Returns { valid, errors } against schemas/specialist-trace.schema.json.
+ */
+export function validateSpecialistTrace(trace) {
+  const errors = [];
+  if (!trace || typeof trace !== 'object') return { valid: false, errors: ['trace is not an object'] };
+  if (trace.schemaVersion !== SPECIALIST_TRACE_SCHEMA_VERSION) errors.push(`schemaVersion must be ${SPECIALIST_TRACE_SCHEMA_VERSION}`);
+  if (typeof trace.id !== 'string' || !trace.id) errors.push('id required');
+  if (!trace.specialist || typeof trace.specialist.role !== 'string') errors.push('specialist.role required');
+
+  for (const [key, fields] of [
+    ['upstream', ['evidenceComplete', 'inputsPresent']],
+    ['provider', ['executionError', 'degraded']],
+    ['handoff', ['inputValid', 'schemaValid']],
+  ]) {
+    const block = trace[key];
+    if (!block || typeof block !== 'object') { errors.push(`${key} missing`); continue; }
+    for (const f of fields) if (typeof block[f] !== 'boolean') errors.push(`${key}.${f} must be boolean`);
+  }
+
+  if (!trace.specialistOutput || !['pass', 'fail', 'unverified'].includes(trace.specialistOutput.evidenceVerdict)) {
+    errors.push('specialistOutput.evidenceVerdict invalid');
+  }
+  if (!trace.downstream || !['accepted', 'rejected', 'unknown'].includes(trace.downstream.outcome)) {
+    errors.push('downstream.outcome invalid');
+  }
+  if (!trace.evaluator || typeof trace.evaluator.abstained !== 'boolean') errors.push('evaluator.abstained must be boolean');
+
+  return { valid: errors.length === 0, errors };
+}

package/lib/improvement/store.mjs

@@ -0,0 +1,89 @@
+/**
+ * lib/improvement/store.mjs — durable proposal records for the governed
+ * improvement loop (construct-6zga.1.11).
+ *
+ * Each submission is a versioned JSON file under `.cx/improvement/proposals/`
+ * holding the proposal, held-out dataset item, evaluation report, optional
+ * specialist trace, governance verdict, and rollout plan. The store is the
+ * operator surface's source of truth; the controller never mutates artifacts in
+ * place without persisting the new state here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const IMPROVEMENT_STORE_SCHEMA_VERSION = 1;
+
+export function improvementDir(projectDir) {
+  return path.join(projectDir, '.cx', 'improvement');
+}
+
+export function proposalsDir(projectDir) {
+  return path.join(improvementDir(projectDir), 'proposals');
+}
+
+export function proposalRecordPath(projectDir, id) {
+  return path.join(proposalsDir(projectDir), `${id}.json`);
+}
+
+export function approversPath(projectDir) {
+  return path.join(improvementDir(projectDir), 'approvers.json');
+}
+
+function ensureProposalsDir(projectDir) {
+  const dir = proposalsDir(projectDir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function loadApprovers(projectDir) {
+  const file = approversPath(projectDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed?.identities) ? parsed.identities : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveRecord(projectDir, record) {
+  ensureProposalsDir(projectDir);
+  const id = record?.id || record?.proposal?.id;
+  if (!id) throw new Error('record id required');
+  const now = new Date().toISOString();
+  const { projectDir: _omit, ...rest } = record;
+  const payload = {
+    schemaVersion: IMPROVEMENT_STORE_SCHEMA_VERSION,
+    ...rest,
+    id,
+    updatedAt: now,
+    submittedAt: record.submittedAt || now,
+  };
+  fs.writeFileSync(proposalRecordPath(projectDir, id), JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+export function loadRecord(projectDir, id) {
+  const file = proposalRecordPath(projectDir, id);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function listRecords(projectDir, { state = null } = {}) {
+  const dir = proposalsDir(projectDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const record = loadRecord(projectDir, name.replace(/\.json$/, ''));
+    if (!record) continue;
+    if (state && record.proposal?.state !== state) continue;
+    out.push(record);
+  }
+  out.sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
+  return out;
+}