@geraldmaron/construct 1.3.1 → 1.4.0

package/README.md

@@ -136,6 +136,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct init` | Project setup (once per repo): scaffold .cx/, AGENTS.md, plan.md, adapters |
 | `construct install` | Machine setup (scoped per ADR-0029): --scope=project\|user\|both, default project |
 | `construct intake` | View and process the active profile's intake queue (queue label varies by profile) |
+| `construct oracle` | Oracle meta-controller — fleet health review and bounded-auto maintenance |
 | `construct recommendations` | View and manage artifact recommendations |
 | `construct sandbox` | Isolated tmpdir-based environment for QA / specialist dry-runs |
 | `construct scope` | Manage the active org scope and its lifecycle (draft, promote, archive, health) |
@@ -186,7 +187,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct hosts` | Show host support for Construct orchestration |
 | `construct mcp` | Manage MCP integrations |
 | `construct models` | Show or update model tier assignments |
-| `construct orchestrate` | Construct-owned local orchestration runtime, in-process or against the local daemon (--remote) |
+| `construct orchestrate` | Construct-owned local orchestration runtime and readiness preflight |
 | `construct plugin` | Manage external Construct plugin manifests |
 
 ### Integrations

package/bin/construct

@@ -28,6 +28,7 @@ import { runUninstall } from '../lib/uninstall/uninstall.mjs';
 import { maybeFirstInvocationProbe } from '../lib/install/first-invocation.mjs';
 import { loadConstructEnv, getUserEnvPath } from '../lib/env-config.mjs';
 import { ensureConstructCredentials } from '../lib/providers/credential-bootstrap.mjs';
+import { enableSecretAuditTrail } from '../lib/providers/secret-audit-wiring.mjs';
 import {
   loadProjectConfig,
   writeProjectConfig,
@@ -81,6 +82,7 @@ import { loadRegistry, listSpecialists } from '../lib/registry/loader.mjs';
 
 const ROOT_DIR = path.resolve(import.meta.dirname, '..');
 const HOME = os.homedir();
+enableSecretAuditTrail();
 ensureConstructCredentials({ env: process.env, cwd: ROOT_DIR, home: HOME });
 const ENV = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: HOME, env: process.env });
 for (const [key, value] of Object.entries(ENV)) {
@@ -399,7 +401,6 @@ async function cmdDoctor() {
     println(`${COLORS.bold}Credential diagnostics${COLORS.reset}`);
     println('');
 
-    const { execSync } = await import('node:child_process');
     const { homedir } = await import('node:os');
     const { join } = await import('node:path');
     const fs = await import('node:fs');
@@ -420,7 +421,7 @@ async function cmdDoctor() {
 
       // process.env
       if (process.env[varName]) {
-        sources.push(`process.env (${process.env[varName].slice(0, 8)}…)`);
+        sources.push('process.env (set)');
       }
 
       // .env files
@@ -443,13 +444,7 @@ async function cmdDoctor() {
           const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
           const opMatch = content.match(opRe);
           if (opMatch) {
-            try {
-              const r = execSync(`op read '${opMatch[1]}'`, { encoding: 'utf8', timeout: 5000 });
-              sources.push(`${rcPath.replace(homedir(), '~')} → op read ✓ (${r.stdout?.trim()?.slice(0, 8)}…)`);
-            } catch (e) {
-              const err = (e.stderr || e.message || '').slice(0, 120);
-              sources.push(`${rcPath.replace(homedir(), '~')} → op read ✗: ${err}`);
-            }
+            sources.push(`${rcPath.replace(homedir(), '~')} → op:// reference (run \`op read\` to verify)`);
           }
           // Check for direct export (allow leading whitespace for indented rc files)
           const directRe = new RegExp(`^\\s*export\\s+${varName}=(.+)$`, 'm');
@@ -464,11 +459,7 @@ async function cmdDoctor() {
       println(`  ${pip}${COLORS.reset} ${COLORS.bold}${varName}${COLORS.reset}`);
       if (sources.length) {
         for (const s of sources.slice(0, 3)) {
-          if (s.includes('op read ✗')) {
-            println(`       ${COLORS.red}⚠${COLORS.reset} ${s}`);
-          } else {
-            println(`       ${s}`);
-          }
+          println(`       ${s}`);
         }
         if (sources.length > 3) println(`       … +${sources.length - 3} more`);
       } else {
@@ -3690,8 +3681,62 @@ async function cmdOrchestrate(args) {
   const sub = args[0];
   const rest = args.slice(1);
   const flag = (name) => { const i = rest.indexOf(name); return i !== -1 ? rest[i + 1] : undefined; };
+  const eqFlag = (name) => {
+    const hit = rest.find((arg) => arg.startsWith(`${name}=`));
+    return hit ? hit.slice(name.length + 1) : flag(name);
+  };
   const wantsJson = rest.includes('--json') || args.includes('--json');
 
+  if (sub === 'preflight') {
+    const { buildOrchestrationReadiness, recordOrchestrationReadinessEvent, summarizeOrchestrationReadiness } = await import('../lib/orchestration/readiness.mjs');
+    const { probeStdioMcpTools } = await import('../lib/mcp/stdio-mcp-probe.mjs');
+    const splitCsv = (value) => value ? String(value).split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const timeoutMs = Number(eqFlag('--timeout-ms') || 8000);
+    let observedTools = splitCsv(eqFlag('--observed-tools'));
+    let reachableTools = splitCsv(eqFlag('--reachable-tools'));
+    let probeError = null;
+
+    if (!rest.includes('--no-probe') && !observedTools && !reachableTools) {
+      try {
+        const tools = await probeStdioMcpTools(process.execPath, [path.join(ROOT_DIR, 'lib', 'mcp', 'server.mjs')], {
+          env: { CX_TOOLKIT_DIR: ROOT_DIR },
+          timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 8000,
+        });
+        observedTools = tools.map((tool) => tool.name);
+        reachableTools = tools.flatMap((tool) => (
+          tool.name === 'call' ? (tool.inputSchema?.properties?.tool?.enum ?? []) : []
+        ));
+      } catch (err) {
+        probeError = err.message || String(err);
+      }
+    }
+
+    const readiness = buildOrchestrationReadiness({
+      host: eqFlag('--host'),
+      sessionId: eqFlag('--session-id'),
+      observedTools,
+      reachableTools,
+      requiredTools: splitCsv(eqFlag('--required-tools')),
+      clientContractVersion: eqFlag('--client-contract-version'),
+      observationScope: eqFlag('--observation-scope') || (observedTools || reachableTools ? 'host-session' : 'local-config'),
+      probeError,
+      authRequired: rest.includes('--auth-required'),
+    }, { env: process.env, cwd: process.cwd() });
+    let eventResult = null;
+    try { eventResult = recordOrchestrationReadinessEvent(readiness, { homeDir: HOME }); } catch { /* telemetry must not break preflight */ }
+
+    if (wantsJson) {
+      println(JSON.stringify({ ...readiness, eventPath: eventResult?.path ?? null }, null, 2));
+      process.exit(readiness.attached ? 0 : 1);
+    }
+
+    println(summarizeOrchestrationReadiness(readiness));
+    println(`Reason: ${readiness.reasonCode}`);
+    println(`Next: ${readiness.nextStep}`);
+    println(`Diagnostic id: ${readiness.diagnosticBundle?.diagnosticId}`);
+    process.exit(readiness.attached ? 0 : 1);
+  }
+
   // Thin-client mode: drive the local orchestration daemon over HTTP instead of
   // running in-process, proving the engine-as-service contract editors/CI use.
   if (rest.includes('--remote')) {
@@ -3783,9 +3828,10 @@ async function cmdOrchestrate(args) {
     return;
   }
 
-  println('Usage: construct orchestrate <run|status> [options]');
+  println('Usage: construct orchestrate <run|status|preflight> [options]');
   println('  run "<request>" [--workflow-type T] [--strategy S] [--host H] [--host-model M] [--no-construct] [--no-execute] [--json]');
   println('  status [run-id] [--json]');
+  println('  preflight [--host H] [--json] [--no-probe] [--observed-tools=a,b] [--reachable-tools=a,b]');
 }
 
 async function cmdModels(args) {

package/lib/a11y-audit.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/a11y-audit.mjs — Per-format accessibility checks with an honest coverage report.
+ *
+ * Each export format declares the a11y checks that apply to it (contrast, alt text, heading
+ * hierarchy, font floor, text extractability) and, just as importantly, the checks that are NOT
+ * machine-verifiable for that format — rendered-text contrast in a PDF, reading order in a PPTX.
+ * auditAccessibility runs the declared checks and returns both the results and the uncheckable
+ * list, so the report never implies coverage it does not have. A missing tool degrades with a
+ * typed reason rather than silently passing.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { validateBrandContrast } from './brand-contrast.mjs';
+import { auditDeckMarkdownLayout } from './deck-export-pptx.mjs';
+import { whichBin } from './document-export.mjs';
+
+// Each format names the checks it runs and the a11y concerns that cannot be machine-verified for
+// it, so the report distinguishes "checked and passed" from "not checkable here".
+
+export const FORMAT_A11Y = Object.freeze({
+  html: { checks: ['alt_text', 'heading_hierarchy', 'contrast'], uncheckable: [] },
+  deck: { checks: ['alt_text', 'heading_hierarchy', 'contrast', 'font_floor'], uncheckable: [{ id: 'reading_order', reason: 'slide reading order is a visual-review judgment' }] },
+  pptx: { checks: ['alt_text', 'font_floor'], uncheckable: [{ id: 'contrast', reason: 'rendered-text contrast needs OCR' }, { id: 'reading_order', reason: 'shape reading order is a visual-review judgment' }] },
+  pdf: { checks: ['alt_text', 'text_extractable'], uncheckable: [{ id: 'contrast', reason: 'rendered-text contrast needs OCR' }, { id: 'tag_structure', reason: 'Typst/pandoc PDFs are untagged; structure is a manual check' }] },
+  docx: { checks: ['alt_text'], uncheckable: [{ id: 'contrast', reason: 'theme contrast resolves in the office client' }] },
+});
+
+function altText(sourceMarkdown) {
+  const body = String(sourceMarkdown || '').replace(/```[\s\S]*?```/g, '');
+  const missing = [];
+  for (const match of body.matchAll(/!\[([^\]]*)\]\(([^)]+)\)/g)) {
+    if (!match[1].trim()) missing.push(match[2].split(/\s+/)[0]);
+  }
+  return missing.length === 0
+    ? { id: 'alt_text', status: 'pass', detail: 'all images carry alt text' }
+    : { id: 'alt_text', status: 'fail', detail: `images without alt text: ${missing.join(', ')}` };
+}
+
+// The branded templates supply the document h1 from the frontmatter title, so a source whose
+// top section level is h2 is well-formed; a first heading of h3 or deeper, or any skipped level,
+// is a real hierarchy break a screen reader cannot recover from.
+
+function headingHierarchy(sourceMarkdown) {
+  const body = String(sourceMarkdown || '').replace(/^---\n[\s\S]*?\n---\n/, '').replace(/```[\s\S]*?```/g, '');
+  const levels = [...body.matchAll(/^(#{1,6})\s+\S/gm)].map((m) => m[1].length);
+  if (levels.length === 0) return { id: 'heading_hierarchy', status: 'pass', detail: 'no headings' };
+  if (levels[0] > 2) return { id: 'heading_hierarchy', status: 'fail', detail: `first heading is h${levels[0]}; sections should start at h1 or h2` };
+  for (let i = 1; i < levels.length; i += 1) {
+    if (levels[i] - levels[i - 1] > 1) return { id: 'heading_hierarchy', status: 'fail', detail: `heading jumps from h${levels[i - 1]} to h${levels[i]}` };
+  }
+  return { id: 'heading_hierarchy', status: 'pass', detail: 'headings start at the top level and never skip' };
+}
+
+function contrast() {
+  const result = validateBrandContrast();
+  return result.ok
+    ? { id: 'contrast', status: 'pass', detail: 'brand text palette meets WCAG AA' }
+    : { id: 'contrast', status: 'fail', detail: `${result.failures.length} brand pair(s) below AA` };
+}
+
+function fontFloor(sourceMarkdown) {
+  const audit = auditDeckMarkdownLayout(sourceMarkdown, {});
+  const below = audit.issues.filter((i) => i.code === 'font_below_floor');
+  return below.length === 0
+    ? { id: 'font_floor', status: 'pass', detail: 'no slide implies a sub-floor font' }
+    : { id: 'font_floor', status: 'fail', detail: below.map((i) => `slide ${i.slide}`).join(', ') };
+}
+
+function textExtractable(exportPath, env) {
+  if (!whichBin('pdftotext', env)) return { id: 'text_extractable', status: 'degraded', degradation: 'missing-dependency', detail: 'pdftotext not available' };
+  if (!exportPath || !fs.existsSync(exportPath)) return { id: 'text_extractable', status: 'degraded', degradation: 'skipped-by-policy', detail: 'export not found' };
+  const result = spawnSync('pdftotext', [exportPath, '-'], { encoding: 'utf8', env });
+  const text = result.status === 0 ? (result.stdout || '').replace(/\s+/g, '') : '';
+  return text.length > 20
+    ? { id: 'text_extractable', status: 'pass', detail: 'PDF carries a real text layer (not image-only)' }
+    : { id: 'text_extractable', status: 'fail', detail: 'PDF has little or no extractable text — likely image-only' };
+}
+
+export function auditAccessibility({ format, exportPath = null, sourceMarkdown = '', env = process.env } = {}) {
+  const spec = FORMAT_A11Y[format];
+  if (!spec) return { format, ok: true, results: [], coverage: { checked: [], uncheckable: [] }, unsupported: true };
+
+  const results = [];
+  for (const id of spec.checks) {
+    if (id === 'alt_text') results.push(altText(sourceMarkdown));
+    else if (id === 'heading_hierarchy') results.push(headingHierarchy(sourceMarkdown));
+    else if (id === 'contrast') results.push(contrast());
+    else if (id === 'font_floor') results.push(fontFloor(sourceMarkdown));
+    else if (id === 'text_extractable') results.push(textExtractable(exportPath, env));
+  }
+
+  const failures = results.filter((r) => r.status === 'fail');
+  return {
+    format,
+    ok: failures.length === 0,
+    results,
+    failures: failures.map((r) => `${r.id}: ${r.detail}`),
+    coverage: {
+      checked: results.map((r) => ({ id: r.id, status: r.status })),
+      uncheckable: spec.uncheckable,
+    },
+  };
+}

package/lib/artifact-completion-states.mjs

@@ -0,0 +1,35 @@
+/**
+ * lib/artifact-completion-states.mjs — the single ordered completion-state vocabulary.
+ *
+ * One canonical list, shared by the manifest schema ($defs.completionState), the manifest
+ * validator (qualityContract.requiredStates), and — as they land — the workflow report and CLI
+ * output. The order is the completion ladder: an artifact carries the highest rung for which it
+ * holds re-verifiable evidence. Keep this array byte-identical to the schema enum; the parity
+ * test (tests/asset-quality/completion-states.test.mjs) fails if they drift.
+ */
+
+export const COMPLETION_STATES = Object.freeze([
+  'planned',
+  'authored',
+  'structurally-valid',
+  'source-linted',
+  'exported',
+  'file-valid',
+  'renderable',
+  'screenshot-captured',
+  'visually-reviewed',
+  'accessibility-reviewed',
+  'approved',
+  'completed',
+]);
+
+export function isCompletionState(state) {
+  return COMPLETION_STATES.includes(state);
+}
+
+// Rank is the ladder position; -1 for an unknown state. Lets callers compare progression
+// (a later rung requires every earlier rung's evidence) without hardcoding the order.
+
+export function completionRank(state) {
+  return COMPLETION_STATES.indexOf(state);
+}

package/lib/artifact-completion.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/artifact-completion.mjs — Evidence objects and the no-forgery completion ledger.
+ *
+ * A completion state advances only when backed by a re-verifiable evidence object; a step that
+ * could not run records a typed degradation that documents the miss without advancing the ladder.
+ * The no-forgery invariant lives in code: no path records a rung without constructing valid
+ * evidence for it. Timestamps are injected (null by default) so a run report stays
+ * deterministic — the workflow asserts deepEqual across identical runs.
+ */
+import { COMPLETION_STATES, isCompletionState, completionRank } from './artifact-completion-states.mjs';
+
+export const DEGRADATION_REASONS = Object.freeze([
+  'unavailable-renderer',
+  'missing-dependency',
+  'unsupported-format',
+  'headless-limitation',
+  'skipped-by-policy',
+]);
+
+export function makeEvidence(state, {
+  actor,
+  artifact = null,
+  proof = null,
+  digest = null,
+  degradation = null,
+  reversible = true,
+  timestamp = null,
+} = {}) {
+  if (!isCompletionState(state)) {
+    throw new Error(`unknown completion state: ${state} (expected one of ${COMPLETION_STATES.join(', ')})`);
+  }
+  if (degradation !== null && !DEGRADATION_REASONS.includes(degradation)) {
+    throw new Error(`unknown degradation reason: ${degradation}`);
+  }
+  if (typeof actor !== 'string' || actor.length === 0) {
+    throw new Error('evidence requires a non-empty actor');
+  }
+  return Object.freeze({ state, actor, artifact, proof, digest, degradation, reversible, timestamp });
+}
+
+// recordCompletion is the only way a state enters the ledger; passing anything but a valid
+// evidence object throws, so a rung cannot be claimed without proof for it.
+
+export function recordCompletion(ledger, evidence) {
+  if (!evidence || typeof evidence !== 'object' || !isCompletionState(evidence.state)) {
+    throw new Error('completion requires a valid evidence object');
+  }
+  return [...ledger, evidence];
+}
+
+// The achieved state is the highest-ranked rung with non-degraded evidence; a degraded entry is
+// kept for the record but never lifts the ladder.
+
+export function highestState(ledger = []) {
+  let best = null;
+  let bestRank = -1;
+  for (const evidence of ledger) {
+    if (evidence.degradation) continue;
+    const rank = completionRank(evidence.state);
+    if (rank > bestRank) {
+      bestRank = rank;
+      best = evidence.state;
+    }
+  }
+  return best;
+}

package/lib/artifact-gate-levels.mjs

@@ -0,0 +1,69 @@
+/**
+ * lib/artifact-gate-levels.mjs — Declarative gate-level → check-category registry.
+ *
+ * Each gate level (fast → human-reviewed) requires a cumulative set of check categories. A
+ * category is either available (a real check runs today) or pending (no check exists yet — the
+ * entry names the bead that will implement it). planGateForLevel partitions a level into what
+ * runs now and what is owed, so a higher level never silently passes the checks it cannot yet
+ * perform: the pending categories surface with their beads instead. Mapping mirrors
+ * docs/notes/research/construct-asset-quality/synthesis/visual-quality-matrix.md.
+ */
+import { GATE_LEVELS } from './artifact-manifest.mjs';
+
+export const DEFAULT_GATE_LEVEL = 'standard';
+
+// Each category records whether a real check exists today; pending categories carry the bead that
+// implements them so a gate plan can name what it is not yet enforcing.
+
+export const CHECK_CATEGORIES = Object.freeze({
+  'source-lint': { label: 'Source presentation + structure lint', status: 'available' },
+  'export-validation': { label: 'Exported file integrity', status: 'pending', bead: 'construct-cuxq.5.2' },
+  'content-roundtrip': { label: 'Content-preservation roundtrip', status: 'pending', bead: 'construct-cuxq.5.2' },
+  'reference-integrity': { label: 'Missing image / broken link references', status: 'pending', bead: 'construct-cuxq.5.2' },
+  'render-screenshot': { label: 'Rendered page/slide screenshot', status: 'pending', bead: 'construct-cuxq.3.3' },
+  'font-floor': { label: 'Minimum font size', status: 'pending', bead: 'construct-cuxq.4.2' },
+  contrast: { label: 'WCAG AA contrast', status: 'pending', bead: 'construct-cuxq.7.1' },
+  'pixel-regression': { label: 'Pixel regression vs golden', status: 'pending', bead: 'construct-cuxq.10.2' },
+  'full-a11y': { label: 'Full per-format accessibility', status: 'pending', bead: 'construct-cuxq.8.1' },
+  'judgment-review': { label: 'Model/human judgment review', status: 'pending', bead: 'construct-cuxq.3.4' },
+});
+
+// Levels are cumulative: each adds categories on top of the cheaper level below it. fast carries
+// only source lint so local feedback stays ms-fast.
+
+const LEVEL_ADDITIONS = Object.freeze({
+  fast: ['source-lint'],
+  standard: ['export-validation', 'content-roundtrip', 'reference-integrity'],
+  'render-smoke': ['render-screenshot', 'font-floor', 'contrast'],
+  'full-certification': ['pixel-regression', 'full-a11y'],
+  'human-reviewed': ['judgment-review'],
+});
+
+export function categoriesForLevel(level) {
+  const out = [];
+  for (const name of GATE_LEVELS) {
+    out.push(...LEVEL_ADDITIONS[name]);
+    if (name === level) return out;
+  }
+  return out;
+}
+
+export function resolveGateLevel(qualityContract) {
+  const level = qualityContract?.gateLevel;
+  return GATE_LEVELS.includes(level) ? level : DEFAULT_GATE_LEVEL;
+}
+
+// planGateForLevel splits a level's required categories into the checks that run today and the
+// ones still owed; a pending category is never reported as running.
+
+export function planGateForLevel(level) {
+  const resolved = GATE_LEVELS.includes(level) ? level : DEFAULT_GATE_LEVEL;
+  const runs = [];
+  const pending = [];
+  for (const category of categoriesForLevel(resolved)) {
+    const meta = CHECK_CATEGORIES[category];
+    if (meta?.status === 'available') runs.push(category);
+    else pending.push({ category, bead: meta?.bead ?? null });
+  }
+  return { level: resolved, runs, pending };
+}

package/lib/artifact-manifest.mjs

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveActiveScope } from './scopes/loader.mjs';
+import { COMPLETION_STATES, isCompletionState } from './artifact-completion-states.mjs';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EMPTY_MANIFEST = { version: 1, artifacts: {} };
@@ -21,6 +22,12 @@ const EMPTY_MANIFEST = { version: 1, artifacts: {} };
 export const BRAND_CAPABLE_FORMATS = Object.freeze(['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex']);
 export const PLAIN_OUTPUT_FORMATS = Object.freeze(['txt', 'md', 'mdx']);
 
+// Quality-gate levels run from cheapest source lint to full visual certification; an artifact's
+// qualityContract.gateLevel selects which deterministic checks block. The completion-state
+// vocabulary it references lives in artifact-completion-states.mjs.
+
+export const GATE_LEVELS = Object.freeze(['fast', 'standard', 'render-smoke', 'full-certification', 'human-reviewed']);
+
 let cached = null;
 let cachedRoot = null;
 
@@ -152,6 +159,10 @@ export function resolveArtifactWorkflowContract(type, {
     formats: [...BRAND_CAPABLE_FORMATS, ...PLAIN_OUTPUT_FORMATS],
     branding: 'construct',
   }, configured.outputs);
+  const qualityContract = mergeObjects({
+    gateLevel: 'standard',
+    requiredStates: ['exported'],
+  }, configured.qualityContract);
   const validation = mergeObjects({ releaseGate: true }, configured.validation);
 
   return {
@@ -169,6 +180,7 @@ export function resolveArtifactWorkflowContract(type, {
     validation,
     releaseGate,
     outputs,
+    qualityContract,
     appliedOverrides,
   };
 }
@@ -197,6 +209,15 @@ export function validateArtifactManifest(manifest) {
     if (entry.outputs?.branding !== undefined && !['construct', 'plain'].includes(entry.outputs.branding)) {
       errors.push(`${prefix}.outputs.branding: must be construct or plain`);
     }
+    const gateLevel = entry.qualityContract?.gateLevel;
+    if (gateLevel !== undefined && !GATE_LEVELS.includes(gateLevel)) {
+      errors.push(`${prefix}.qualityContract.gateLevel: must be one of ${GATE_LEVELS.join(', ')}`);
+    }
+    if (entry.qualityContract?.requiredStates !== undefined
+      && (!Array.isArray(entry.qualityContract.requiredStates)
+        || entry.qualityContract.requiredStates.some((state) => !isCompletionState(state)))) {
+      errors.push(`${prefix}.qualityContract.requiredStates: must be completion states (${COMPLETION_STATES.join(', ')})`);
+    }
   }
   return errors.length ? { valid: false, errors } : { valid: true, errors: [] };
 }

package/lib/artifact-release-gate.mjs

@@ -10,7 +10,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { lintDocStructure, lintDocVisuals } from './templates/visual-requirements.mjs';
 import { lintDocPresentationFile } from './templates/doc-presentation.mjs';
-import { getArtifactEntry, resolveToneForArtifact } from './artifact-manifest.mjs';
+import { getArtifactEntry, resolveToneForArtifact, resolveArtifactWorkflowContract } from './artifact-manifest.mjs';
+import { planGateForLevel, resolveGateLevel } from './artifact-gate-levels.mjs';
 import { lintFile } from './comment-lint.mjs';
 import {
   missingRequiredReviewers,
@@ -203,6 +204,23 @@ export function validateArtifactRelease({
   return { ...result, filePath };
 }
 
+// Level-aware entry: runs the release gate (the source-lint category that exists today) and
+// attaches the gate plan for the artifact's level, so callers see both what was enforced and the
+// higher-tier categories still owed. The level comes from the artifact's qualityContract unless
+// passed explicitly. Pending categories are reported, never silently treated as passed.
+
+export function runGateAtLevel({ filePath, type, level, cwd = process.cwd(), rootDir } = {}) {
+  const resolvedType = type || inferArtifactTypeFromPath(filePath, { rootDir: cwd });
+  let effectiveLevel = level;
+  if (!effectiveLevel) {
+    const contract = resolveArtifactWorkflowContract(resolvedType, { rootDir, cwd });
+    effectiveLevel = resolveGateLevel(contract?.qualityContract);
+  }
+  const release = validateArtifactRelease({ filePath, type: resolvedType, cwd, rootDir });
+  const plan = planGateForLevel(effectiveLevel);
+  return { ...release, gateLevel: plan.level, gatePlan: { runs: plan.runs, pending: plan.pending } };
+}
+
 export async function runArtifactValidateCli(args = []) {
   const positional = args.filter((a) => !a.startsWith('--'));
   const filePath = positional[0];

package/lib/artifact-workflow.mjs

@@ -16,6 +16,7 @@ import {
 import { inferArtifactTypeFromPath } from './artifact-type-from-path.mjs';
 import { validateArtifactRelease } from './artifact-release-gate.mjs';
 import { exportMarkdown } from './document-export.mjs';
+import { makeEvidence, recordCompletion, highestState } from './artifact-completion.mjs';
 
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -178,6 +179,8 @@ export function runArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir
     skippedSteps: [],
     producedFiles: [],
     validation: null,
+    completion: [],
+    completionState: null,
     appliedOverrides: plan.appliedOverrides,
   };
   if (plan.status !== 'planned') return report;
@@ -235,10 +238,22 @@ export function runArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir
         if (!result.ok) {
           report.status = 'export-failed';
           report.skippedSteps.push({ id: step.id, reason: result.message });
+          report.completion = recordCompletion(report.completion, makeEvidence('exported', {
+            actor: 'construct-export',
+            artifact: sourcePath,
+            degradation: result.missing?.length ? 'missing-dependency' : 'unsupported-format',
+            proof: { format: step.format, message: result.message },
+          }));
+          report.completionState = highestState(report.completion);
           return report;
         }
         report.executedSteps.push({ id: step.id, result: 'produced', format: step.format });
         report.producedFiles.push({ path: result.outputPath, format: step.format, branding: result.branding });
+        report.completion = recordCompletion(report.completion, makeEvidence('exported', {
+          actor: 'construct-export',
+          artifact: result.outputPath,
+          proof: { format: step.format, branding: result.branding },
+        }));
         const brandStep = report.skippedSteps.findIndex((entry) => entry.id === 'brand');
         if (brandStep >= 0 && result.branding?.applied === 'construct') {
           report.skippedSteps.splice(brandStep, 1);
@@ -248,5 +263,6 @@ export function runArtifactWorkflow(request = {}, { cwd = process.cwd(), rootDir
     }
   }
   report.status = report.executedSteps.length ? 'completed-local-steps' : 'planned';
+  report.completionState = highestState(report.completion);
   return report;
 }

package/lib/brand-contrast.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/brand-contrast.mjs — WCAG contrast over the Construct brand palette.
+ *
+ * Computes WCAG 2.1 relative-luminance contrast ratios between brand colors and checks them
+ * against the AA thresholds (4.5:1 for body text, 3:1 for large text and UI). validateBrandContrast
+ * runs a declared set of text-bearing ink-on-surface pairs so a palette change that drops legibility
+ * fails a test instead of shipping unverified. Mirrors the gap in
+ * docs/notes/research/construct-asset-quality/subagents/branding-typography-spacing.md.
+ */
+import { BRAND_TOKENS } from './brand-tokens.mjs';
+
+export const AA_BODY = 4.5;
+export const AA_LARGE = 3.0;
+
+function channel(value) {
+  const c = value / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+function relativeLuminance(hex) {
+  const clean = hex.replace('#', '');
+  const r = parseInt(clean.slice(0, 2), 16);
+  const g = parseInt(clean.slice(2, 4), 16);
+  const b = parseInt(clean.slice(4, 6), 16);
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+export function contrastRatio(fg, bg) {
+  const l1 = relativeLuminance(fg);
+  const l2 = relativeLuminance(bg);
+  const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export function meetsWcagAA(ratio, { large = false } = {}) {
+  return ratio >= (large ? AA_LARGE : AA_BODY);
+}
+
+// The text-bearing pairs that must stay legible: body and strong ink against every surface they
+// land on, and muted secondary text held to body AA. ink.faint is a decorative color measuring
+// 2.86:1 on paper (below large-text AA), excluded here and guarded by the test as decorative-only
+// rather than promoted to a text color.
+
+export const BRAND_TEXT_PAIRS = Object.freeze([
+  { label: 'ink.default on paper', fg: BRAND_TOKENS.ink.default, bg: BRAND_TOKENS.surface.paper, large: false },
+  { label: 'ink.strong on paper', fg: BRAND_TOKENS.ink.strong, bg: BRAND_TOKENS.surface.paper, large: false },
+  { label: 'ink.body on paper', fg: BRAND_TOKENS.ink.body, bg: BRAND_TOKENS.surface.paper, large: false },
+  { label: 'ink.body on surface', fg: BRAND_TOKENS.ink.body, bg: BRAND_TOKENS.surface.default, large: false },
+  { label: 'ink.body on surfaceAlt', fg: BRAND_TOKENS.ink.body, bg: BRAND_TOKENS.surface.alt, large: false },
+  { label: 'ink.muted on paper', fg: BRAND_TOKENS.ink.muted, bg: BRAND_TOKENS.surface.paper, large: false },
+]);
+
+export function validateBrandContrast(pairs = BRAND_TEXT_PAIRS) {
+  const results = pairs.map((pair) => {
+    const ratio = contrastRatio(pair.fg, pair.bg);
+    return { ...pair, ratio: Math.round(ratio * 100) / 100, pass: meetsWcagAA(ratio, { large: pair.large }) };
+  });
+  const failures = results.filter((result) => !result.pass);
+  return { ok: failures.length === 0, results, failures };
+}

package/lib/brand-tokens.mjs

@@ -31,6 +31,20 @@ export const STATUS = Object.freeze({
   danger: '#e06c75',
 });
 
+// One spacing scale as base-unit multiples so PDF (Typst em), HTML/CSS (rem), and templates derive
+// from a single rhythm instead of drifting with ad hoc per-surface values. Consumers multiply by
+// their own base unit.
+
+export const SPACING_SCALE = Object.freeze({
+  none: 0,
+  xs: 0.25,
+  sm: 0.5,
+  md: 1,
+  lg: 1.5,
+  xl: 2,
+  xxl: 3,
+});
+
 export const BRAND_TOKENS = Object.freeze({
   ink: Object.freeze({
     default: INK.ink,