@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/improvement/cli.mjs

@@ -0,0 +1,189 @@
+/**
+ * lib/improvement/cli.mjs — CLI handlers for `construct improvement <subcommand>`.
+ *
+ * Subcommands: submit, review, pending, show, approve, apply, rollback, list.
+ * Each command reads or writes durable state under `.cx/improvement/` and routes
+ * proposals through the governed controller; apply and rollback record human acts
+ * but do not mutate live artifacts.
+ */
+import fs from 'node:fs';
+
+import {
+  applyRecord,
+  approveRecord,
+  formatReviewSummary,
+  listPending,
+  resolveKnownApprovers,
+  reviewRecord,
+  rollbackRecord,
+  submitBundle,
+} from './surface.mjs';
+import { listRecords, loadRecord } from './store.mjs';
+
+function readJsonArg(args, prefix) {
+  const hit = args.find((a) => a.startsWith(prefix));
+  if (!hit) return null;
+  const file = hit.slice(prefix.length);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function flagValue(args, prefix) {
+  const hit = args.find((a) => a.startsWith(prefix));
+  return hit ? hit.slice(prefix.length) : null;
+}
+
+function usage() {
+  process.stderr.write(
+    'Usage: construct improvement <submit|review|pending|show|approve|apply|rollback|list> [--json]\n'
+    + '  submit   --bundle=FILE | (--trace=FILE --dataset=FILE --report=FILE [--trigger=KIND])\n'
+    + '  review   <id>\n'
+    + '  pending\n'
+    + '  show     <id>\n'
+    + '  approve  <id> [--identity=USER]\n'
+    + '  apply    <id> [--monitor=ID]\n'
+    + '  rollback <id> [--reason=TEXT]\n'
+    + '  list     [--state=STATE]\n',
+  );
+}
+
+export async function runImprovementCli(args, { projectDir = process.cwd() } = {}) {
+  const json = args.includes('--json');
+  const sub = args.find((a) => !a.startsWith('-'));
+  const positional = args.filter((a) => !a.startsWith('-'));
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    usage();
+    return sub === '--help' || sub === '-h' ? 0 : 1;
+  }
+
+  const write = (payload) => {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  };
+
+  switch (sub) {
+    case 'submit': {
+      const bundle = readJsonArg(args, '--bundle=');
+      const trace = bundle?.trace ?? readJsonArg(args, '--trace=');
+      const dataset = bundle?.dataset ?? readJsonArg(args, '--dataset=');
+      const evaluationReport = bundle?.evaluationReport ?? readJsonArg(args, '--report=');
+      const triggerKind = flagValue(args, '--trigger=') || bundle?.trigger?.kind || 'operator-request';
+      const trigger = bundle?.trigger || { kind: triggerKind, optIn: true };
+      const result = submitBundle({
+        projectDir,
+        bundle: bundle || {
+          trace,
+          trigger,
+          dataset,
+          evaluationReport,
+          approver: flagValue(args, '--approver=') || resolveKnownApprovers(projectDir)[0] || null,
+        },
+      });
+      if (json) write(result);
+      else if (!result.ok) {
+        process.stderr.write(`submit refused: ${result.stage || result.error}\n`);
+        if (result.governance?.refusals?.length) {
+          process.stderr.write(`  refusals: ${result.governance.refusals.join(', ')}\n`);
+        }
+        return 1;
+      } else {
+        process.stdout.write(`submitted ${result.record.id} → ${result.record.proposal.state}\n`);
+      }
+      return result.ok ? 0 : 1;
+    }
+
+    case 'review': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = reviewRecord(projectDir, id);
+      if (!result.ok) {
+        process.stderr.write(`review failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(formatReviewSummary(result.record, result.governance) + '\n');
+      return 0;
+    }
+
+    case 'pending': {
+      const pending = listPending(projectDir);
+      if (json) write({ pending });
+      else {
+        if (!pending.length) process.stdout.write('No proposals awaiting approval.\n');
+        for (const row of pending) {
+          process.stdout.write(`${row.id} · ${row.proposal?.type} · ${row.proposal?.state}\n`);
+        }
+      }
+      return 0;
+    }
+
+    case 'show': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const record = loadRecord(projectDir, id);
+      if (!record) {
+        process.stderr.write(`not found: ${id}\n`);
+        return 1;
+      }
+      if (json) write(record);
+      else process.stdout.write(formatReviewSummary(record) + '\n');
+      return 0;
+    }
+
+    case 'approve': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = approveRecord(projectDir, id, { identity: flagValue(args, '--identity=') });
+      if (!result.ok) {
+        process.stderr.write(`approve failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`approved ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'apply': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = applyRecord(projectDir, id, { monitor: flagValue(args, '--monitor=') });
+      if (!result.ok) {
+        process.stderr.write(`apply failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`applied ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'rollback': {
+      const id = positional[1];
+      if (!id) { usage(); return 1; }
+      const result = rollbackRecord(projectDir, id, { reason: flagValue(args, '--reason=') || 'operator-rollback' });
+      if (!result.ok) {
+        process.stderr.write(`rollback failed: ${result.error}\n`);
+        return 1;
+      }
+      if (json) write(result);
+      else process.stdout.write(`rolled back ${id} → ${result.record.proposal.state}\n`);
+      return 0;
+    }
+
+    case 'list': {
+      const state = flagValue(args, '--state=');
+      const rows = listRecords(projectDir, { state });
+      if (json) write({ proposals: rows });
+      else {
+        if (!rows.length) process.stdout.write('No improvement proposals.\n');
+        for (const row of rows) {
+          process.stdout.write(`${row.id} · ${row.proposal?.type} · ${row.proposal?.state}\n`);
+        }
+      }
+      return 0;
+    }
+
+    default:
+      process.stderr.write(`Unknown subcommand: ${sub}\n`);
+      usage();
+      return 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 };
+}