copperhead 0.9.0 → 0.10.0

package/src/agent/recovery.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import type { Msg, Provider } from './types.js';
+import { resolveLibrarySymbol, searchInstalledSymbols, symbolSearchDirs, listInstalledLibraries } from '../kicad/symlib.js';
 
 /** Thrown when a single provider turn blows past its watchdog deadline. */
 export class TurnTimeoutError extends Error {
@@ -116,6 +117,91 @@ export async function transcriptExcerpt(transcriptDir: string, maxChars = 4000):
   return joined.length > maxChars ? joined.slice(joined.length - maxChars) : joined;
 }
 
+/**
+ * Deterministically re-probe every lib_id named in a failure narrative against
+ * the installed libraries, so the diagnostician judges symbol-availability
+ * claims from machine facts instead of the agent's prose. An agent that has
+ * been dead-ended by wrong library nicknames concludes — and records — that
+ * whole libraries are absent when they are installed; a refusal built on that
+ * premise reads exactly like a genuine environmental gap, and the one thing
+ * that distinguishes them is re-checking the named lib_ids, which costs no
+ * LLM turn. Never throws; on any probe error it reports what it could.
+ */
+export async function symbolAvailabilityFacts(text: string, dirs?: string[], cap = 8): Promise<string> {
+  const ids: string[] = [];
+  // A library nickname is its `.kicad_sym` filename stem, so it can carry `-`
+  // and `.` as well as `_` (`Custom-Parts`, `MyCorp.RF`) — a nickname the regex
+  // truncates is probed as the wrong lib_id and reported absent, which is the
+  // false negative this whole fact block exists to prevent. Separators are
+  // interior only, so a trailing sentence period is not swallowed.
+  for (const m of text.matchAll(/\b([A-Za-z0-9_](?:[A-Za-z0-9_.-]*[A-Za-z0-9_])?):([A-Za-z0-9][A-Za-z0-9_.+-]*)/g)) {
+    const lib = m[1]!;
+    const name = m[2]!;
+    // Require letters on both sides: drops file:line refs ("create.ts:311"),
+    // times and bare numbers. Engine-generated power symbols are not library
+    // facts.
+    if (!/[A-Za-z]/.test(lib) || !/[A-Za-z]/.test(name) || lib === 'copperhead_power') continue;
+    const libId = `${lib}:${name}`;
+    if (!ids.includes(libId)) ids.push(libId);
+  }
+  if (!ids.length) return '';
+  // Collection is unbounded but probing is capped, so a probe-heavy transcript
+  // stays cheap. The overflow is named rather than dropped: the supervisor is
+  // told these facts are ground truth, and silently probing 8 of 30 lib_ids
+  // would let it read "unprobed" as "absent".
+  const probed = ids.slice(0, cap);
+  const unprobed = ids.slice(cap);
+  let searchDirs: string[];
+  try {
+    searchDirs = dirs ?? (await symbolSearchDirs());
+  } catch {
+    return '';
+  }
+  if (!searchDirs.length) return '';
+  // A directory with no readable library means nothing was checked: emitting
+  // "not installed" lines as ground truth from that state is the exact false
+  // absence this block exists to prevent (same guard as bomSymbolDossier).
+  if (!(await listInstalledLibraries(searchDirs)).size) return '';
+  const lines: string[] = [];
+  for (const libId of probed) {
+    const name = libId.slice(libId.indexOf(':') + 1);
+    try {
+      const r = await resolveLibrarySymbol(libId, searchDirs);
+      if (r.status === 'ok') {
+        lines.push(`- ${libId}: RESOLVES on this machine (${r.pins.length} pins)`);
+      } else if (r.status === 'found-elsewhere') {
+        // The resolver already located the part under another lib_id; saying
+        // "not installed" here would be the exact false absence claim this
+        // block exists to prevent.
+        lines.push(`- ${libId}: not at that lib_id, but installed as: ${r.libIds.slice(0, 4).join(', ')}`);
+      } else {
+        const elsewhere = await searchInstalledSymbols(name, searchDirs, 4);
+        const inThat =
+          r.status === 'no-symbol' && r.candidates.length
+            ? ` (closest in that library: ${r.candidates.slice(0, 4).join(', ')})`
+            : '';
+        const where = elsewhere.length
+          ? `; installed as: ${elsewhere.join(', ')}`
+          : `; no installed symbol matches "${name}" in any library`;
+        lines.push(
+          r.status === 'no-symbol'
+            ? `- ${libId}: not in that library${inThat}${where}`
+            : `- ${libId}: no library of that nickname is installed${where}`,
+        );
+      }
+    } catch {
+      // a single unreadable library must not sink the fact block
+    }
+  }
+  if (!lines.length) return '';
+  if (unprobed.length) {
+    lines.push(
+      `- NOT RE-PROBED (probe limit ${cap}): ${unprobed.join(', ')} — these were named in the text but not checked, so nothing above says whether they exist.`,
+    );
+  }
+  return lines.join('\n');
+}
+
 /**
  * Ask the model whether a failed/incomplete stage is worth retrying, and if so
  * how. Uses a fresh, tool-less provider turn (the same saved-login backend the
@@ -132,6 +218,9 @@ export async function diagnoseStageFailure(
     excerpt: string;
     attempt: number;
     maxAttempts: number;
+    /** Deterministic re-probe results for lib_ids named in the failure/excerpt
+     *  (`symbolAvailabilityFacts`); authoritative over the transcript's claims. */
+    symbolFacts?: string;
   },
 ): Promise<StageDiagnosis> {
   const system =
@@ -145,10 +234,14 @@ export async function diagnoseStageFailure(
     `Failure: ${input.failure}\n` +
     `This was attempt ${input.attempt} of ${input.maxAttempts}.\n\n` +
     `Recent transcript (most recent last):\n${input.excerpt}\n\n` +
+    (input.symbolFacts
+      ? `Machine-verified symbol facts — a deterministic re-probe of the lib_ids named above, run just now against this machine's installed KiCad libraries. Each line reported below is ground truth and overrides anything the transcript claims about that symbol's availability. Coverage may be partial: a lib_id listed as NOT RE-PROBED, or absent from this block entirely, is unknown, never confirmed absent.\n${input.symbolFacts}\n\n`
+      : '') +
     'Reply with ONLY a JSON object, no prose:\n' +
     '{"verdict":"retry"|"abort","reason":"<one sentence>","guidance":"<if retry: concrete, specific instructions to prepend to the next attempt so it avoids this failure; otherwise empty>"}\n' +
     '- "retry" if the failure looks transient or fixable with clearer instructions (a dropped or locked tool call, an empty/no-op edit, a skipped step, a timeout, a formatting slip).\n' +
-    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).';
+    '- "abort" if repeating the same attempt will not help and a human should look (missing inputs, a genuine dead-end, or the same failure already seen on a prior attempt).\n' +
+    '- an agent\'s claim that a symbol or library is absent is NOT evidence: agents dead-ended by wrong library nicknames routinely conclude whole libraries are missing. If the machine-verified facts contradict the failure\'s premise (a cited-absent lib_id RESOLVES, or the part is installed under another library), the verdict is "retry", with guidance quoting the correct lib_ids.';
   const messages: Msg[] = [
     { role: 'system', content: system },
     { role: 'user', content: user },

package/src/agent/tools.ts

@@ -6,12 +6,16 @@ import { resolveInRepo, isKicadFile } from '../util/paths.js';
 import { runErc, runDrc, exportSvg, exportFab, kicadLoadError, isProbeableKicadFile } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { listSymbols, listNets } from '../kicad/sexp.js';
-import { verifySchematicSymbols } from '../kicad/symlib.js';
+import { checkLegibility, formatLegibility } from '../kicad/legibility.js';
+import { scoreSchematic, formatScore } from '../kicad/score.js';
+import { draftSchematic, defaultIntentPath, formatSchematicDraftReport } from '../kicad/draft/draft.js';
+import { verifySchematicSymbols, searchInstalledSymbols, symbolSearchDirs, resolveLibrarySymbol, comparePinNumbers } from '../kicad/symlib.js';
 import { checkDrift } from '../memory/drift.js';
 import { saveConstraint, classifyAffectsTarget, affectsTargetExists } from '../memory/constraints.js';
 import { openspecValidate } from '../openspec/cli.js';
 import { existsSync } from 'node:fs';
 import type { CopperheadConfig } from '../config.js';
+import { isEngineAuthoredSchematic } from '../kicad/fab.js';
 import { ObligationsLedger } from './ledger.js';
 import type { Transcript } from './transcript.js';
 
@@ -36,6 +40,10 @@ export interface RunContext {
   decisions: string[];
   lastErc: CheckReport | null;
   lastDrc: CheckReport | null;
+  /** Last check_legibility counts; feeds the run summary's verification section. */
+  lastLegibility: { error: number; advisory: number } | null;
+  /** Last score composite (AC-16.21); recorded in the run summary. */
+  lastScore: number | null;
   repairCycles: number;
   finishRequest: FinishRequest | null;
 }
@@ -239,6 +247,17 @@ export const TOOLS: ToolDef[] = [
       if (corrupt) return corrupt;
       const rel = str(args, 'path');
       const abs = resolveInRepo(ctx.repoRoot, rel);
+      // Engine-drafted sheets are regenerated wholesale from the IR: a hand
+      // edit would be destroyed by the next re-draft and would break the
+      // byte-identical staleness check. Geometry repairs go through the IR
+      // (design D5). Hand-drawn schematics never carry the draft generator
+      // marker, so `do` on existing repos is untouched by this guard.
+      if (rel.endsWith('.kicad_sch') && existsSync(abs)) {
+        const head = (await readFile(abs, 'utf8')).slice(0, 400);
+        if (isEngineAuthoredSchematic(head)) {
+          return `refused: ${rel} is engine-drafted from ${defaultIntentPath(rel)}. Revise the intent (edit_file on the intent JSON) and call draft_schematic to regenerate the sheet; direct geometry edits would be lost on the next re-draft.`;
+        }
+      }
       // Text edits can corrupt an s-expression file in ways the editor cannot
       // see; a corrupted file then fails every later ERC/DRC with an opaque
       // error. Validate loadability with KiCad itself and roll the edit back
@@ -322,6 +341,78 @@ export const TOOLS: ToolDef[] = [
       return out;
     },
   },
+  {
+    schema: {
+      name: 'search_symbols',
+      description:
+        'Search EVERY installed KiCad symbol library for a part or symbol name; returns matching lib_ids as Lib:Name, exact matches first. Library nicknames rarely follow from the part number (TPS61165DBV is in Driver_LED, AudioJack3 in Connector_Audio, INA226 in Sensor_Energy), so a failed single-library probe proves nothing about availability — use this before concluding a part has no symbol, and before committing any active part to the BOM: a part is only drawable if its symbol appears here.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'part or symbol name, e.g. "TLV320AIC3204" or "AudioJack3"' },
+        },
+        required: ['query'],
+      },
+    },
+    requiresUnlock: false,
+    handler: async (_ctx, args) => {
+      const query = str(args, 'query');
+      const dirs = await symbolSearchDirs();
+      if (!dirs.length) return 'no installed KiCad symbol library directories found on this machine';
+      const hits = await searchInstalledSymbols(query, dirs);
+      if (!hits.length) {
+        return `no installed symbol matches "${query}" (searched every library in: ${dirs.join(', ')}). The part is not capturable on this machine as named — choose a part whose symbol exists, or a same-family variant that does.`;
+      }
+      return `installed symbols matching "${query}":\n${hits.map((h) => `  - ${h}`).join('\n')}`;
+    },
+  },
+  {
+    schema: {
+      name: 'symbol_pins',
+      description:
+        'Return the REAL pins (number, name, electrical type) of an installed KiCad symbol by lib_id, following extends links, plus its unit count — the authoritative source for REF.PIN endpoints, instead of guessing pins or reading .kicad_sym files. Warns when the symbol is multi-unit, which the drafting engine refuses. On a miss it lists the closest names in that library and where the symbol actually lives, so one call answers both "what are the pins" and "which lib_id is right".',
+      parameters: {
+        type: 'object',
+        properties: {
+          lib_id: { type: 'string', description: 'full library identifier, e.g. "Device:R" or "Audio:TLV320AIC3100"' },
+        },
+        required: ['lib_id'],
+      },
+    },
+    requiresUnlock: false,
+    handler: async (_ctx, args) => {
+      const libId = str(args, 'lib_id');
+      const name = libId.includes(':') ? libId.slice(libId.indexOf(':') + 1) : libId;
+      const dirs = await symbolSearchDirs();
+      if (!dirs.length) {
+        return `cannot verify "${libId}": no installed KiCad symbol library directories were found on this machine, so nothing can be resolved or ruled out. Install the KiCad symbol libraries (or set KICAD_SYMBOL_DIR), or choose a part you can verify another way.`;
+      }
+      const r = await resolveLibrarySymbol(libId, dirs);
+      if (r.status === 'ok') {
+        const pins = [...r.pins]
+          .sort((a, b) => comparePinNumbers(a.number, b.number))
+          .map((p) => `  ${p.number}: ${p.name === '~' || !p.name ? '(unnamed)' : p.name} · ${p.type}`);
+        const multi =
+          r.units >= 2
+            ? `\nNOTE: this symbol defines ${r.units} units; the drafting engine places each unit separately under one refdes (U1A/U1B), and net endpoints keep plain package pin numbers.`
+            : '';
+        return `${libId} — ${r.pins.length} pin(s), ${r.units} unit(s):\n${pins.join('\n')}${multi}`;
+      }
+      if (r.status === 'found-elsewhere') {
+        return `"${libId}" does not resolve, but the symbol is installed as: ${r.libIds.join(', ')} — use one of these lib_ids (and call symbol_pins on it for the pin table).`;
+      }
+      const elsewhere = await searchInstalledSymbols(name, dirs, 6);
+      const where = elsewhere.length
+        ? `\ninstalled as: ${elsewhere.join(', ')}`
+        : `\nno installed symbol matches "${name}" in any library — the part is not capturable as named.`;
+      if (r.status === 'no-symbol') {
+        const close = r.candidates.length ? `\nclosest in that library: ${r.candidates.join(', ')}` : '';
+        return `"${libId}" does not exist in that library.${close}${where}`;
+      }
+      const lib = libId.includes(':') ? libId.slice(0, libId.indexOf(':')) : libId;
+      return `no library named "${lib}" is installed.${where}`;
+    },
+  },
   {
     schema: {
       name: 'verify_symbols',
@@ -344,6 +435,103 @@ export const TOOLS: ToolDef[] = [
       return `verify_symbols: ${checked} verified, ${skipped} unverifiable (library not installed), ${mismatches} issue(s) to reconcile:\n${lines.join('\n')}`;
     },
   },
+  {
+    schema: {
+      name: 'draft_schematic',
+      description:
+        'Regenerate the schematic deterministically from the netlist-intent IR (schematic.intent.json beside the schematic). Pass intent_json to write a new IR first, or omit it to re-draft the existing file. The engine computes ALL geometry (placement, wires, labels, power symbols, group boxes); never author coordinates. The report embeds the legibility findings and score for the fresh sheet. A failed validation leaves the previous schematic untouched.',
+      parameters: {
+        type: 'object',
+        properties: {
+          intent_json: { type: 'string', description: 'full IR document as JSON text (optional: omit to re-draft the current IR)' },
+        },
+        required: [],
+      },
+    },
+    requiresUnlock: true,
+    handler: async (ctx, args) => {
+      if (!ctx.config.schematic) return 'no schematic configured; set one in .copperhead/config.json first';
+      const intentRel = defaultIntentPath(ctx.config.schematic);
+      if (typeof args.intent_json === 'string' && args.intent_json.trim()) {
+        const corrupt = corruptionError({ intent_json: args.intent_json });
+        if (corrupt) return corrupt;
+        try {
+          JSON.parse(args.intent_json);
+        } catch (e) {
+          return `intent_json is not valid JSON (${(e as Error).message}); nothing written`;
+        }
+        await writeFile(resolveInRepo(ctx.repoRoot, intentRel), args.intent_json, 'utf8');
+        ctx.filesTouched.add(intentRel);
+      }
+      const res = await draftSchematic({
+        repoRoot: ctx.repoRoot,
+        schematic: ctx.config.schematic,
+        intentPath: intentRel,
+        docsDir: ctx.config.docs,
+      });
+      if (!res.ok) return res.message;
+      markTouched(ctx, ctx.config.schematic);
+      // embed the checker and score in the draft report (design D5): a
+      // draft-check-score iteration costs one tool call, and the embedded
+      // checker result drives the ledger obligation exactly like check_legibility
+      const docsAbs = path.join(ctx.repoRoot, ctx.config.docs);
+      const leg = await checkLegibility(res.schematicPath, {
+        docsDir: docsAbs,
+        ...(ctx.config.legibility ? { config: ctx.config.legibility } : {}),
+      });
+      ctx.lastLegibility = leg.counts;
+      ctx.ledger.onLegibilityResult(leg.counts.error);
+      const score = await scoreSchematic(res.schematicPath, {
+        docsDir: docsAbs,
+        ...(ctx.config.legibility ? { config: ctx.config.legibility } : {}),
+      });
+      ctx.lastScore = score.composite;
+      return [formatSchematicDraftReport(res.report), formatLegibility(leg), formatScore(score)].join('\n');
+    },
+  },
+  {
+    schema: {
+      name: 'score_schematic',
+      description:
+        'Deterministic quantitative legibility score for the schematic: composite 0-100 with the per-metric breakdown (crossings, bends, alignment, spacing, symmetry, balance, …). Error-severity legibility findings cap the composite. Advisory: informs, never gates by itself.',
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+    requiresUnlock: false,
+    handler: async (ctx) => {
+      if (!ctx.config.schematic) return 'no schematic configured; score_schematic does not apply yet';
+      const report = await scoreSchematic(path.join(ctx.repoRoot, ctx.config.schematic), {
+        docsDir: path.join(ctx.repoRoot, ctx.config.docs),
+        ...(ctx.config.legibility ? { config: ctx.config.legibility } : {}),
+      });
+      ctx.lastScore = report.composite;
+      return formatScore(report);
+    },
+  },
+  {
+    schema: {
+      name: 'check_legibility',
+      description:
+        'Run the deterministic legibility checker against the schematic: group boxes and captions, symbol/text collisions, grid alignment, frame and title-block use. Returns numbered findings with coordinates and the concrete fix, or "no findings". Error-severity findings must be reconciled before finish; clears the legibility obligation when clean.',
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+    requiresUnlock: false,
+    handler: async (ctx) => {
+      // Mirrors check_drift's vacuous path: with no schematic configured there is
+      // nothing to be illegible, and leaving the obligation open would deadlock
+      // any stage that edited a stray .kicad_sch without config wiring.
+      if (!ctx.config.schematic) {
+        ctx.ledger.clear('legibility');
+        return 'no schematic configured; legibility does not apply yet';
+      }
+      const report = await checkLegibility(path.join(ctx.repoRoot, ctx.config.schematic), {
+        docsDir: path.join(ctx.repoRoot, ctx.config.docs),
+        ...(ctx.config.legibility ? { config: ctx.config.legibility } : {}),
+      });
+      ctx.lastLegibility = report.counts;
+      ctx.ledger.onLegibilityResult(report.counts.error);
+      return formatLegibility(report);
+    },
+  },
   {
     schema: {
       name: 'run_drc',

package/src/agent/transcript.ts

@@ -35,6 +35,10 @@ export interface RunSummaryData {
   filesTouched: string[];
   ercResult: string | null;
   drcResult: string | null;
+  /** e.g. "0 error, 3 advisory finding(s)"; null when the checker never ran. */
+  legibilityResult?: string | null;
+  /** e.g. "87.5/100"; null when the scorer never ran (AC-16.21). */
+  scoreResult?: string | null;
   decisions: string[];
   tokensIn: number;
   tokensOut: number;
@@ -111,6 +115,8 @@ export class Transcript {
       ``,
       `- ERC: ${s.ercResult ?? 'not run'}`,
       `- DRC: ${s.drcResult ?? 'not run'}`,
+      `- legibility: ${s.legibilityResult ?? 'not run'}`,
+      `- score: ${s.scoreResult ?? 'not run'}`,
       ``,
       `## Decisions`,
       ``,

package/src/cli.ts

@@ -179,6 +179,77 @@ program
   .description('ERC + DRC + doc-drift + spec validation; no LLM calls; CI-safe')
   .action(checkAction);
 
+// `draft` and `score` are command groups taking the artifact as a noun
+// (`draft schematic` today, `draft pcb` when layout drafting exists), so the
+// verb alone never has to guess what it applies to.
+const draftGroup = program
+  .command('draft')
+  .description('deterministically draft an artifact from its declared intent; no LLM, no network');
+draftGroup
+  .command('schematic')
+  .description('draft the schematic from schematic.intent.json')
+  .option('--intent <path>', 'repo-relative intent file (default: schematic.intent.json beside the schematic)')
+  .action(async (opts: { intent?: string }) => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const { loadConfig } = await import('./config.js');
+      const { draftSchematic, defaultIntentPath, formatSchematicDraftReport } = await import('./kicad/draft/draft.js');
+      const config = await loadConfig(repo);
+      if (!config.schematic) {
+        console.error('no schematic configured in .copperhead/config.json');
+        process.exit(1);
+      }
+      const res = await draftSchematic({
+        repoRoot: repo,
+        schematic: config.schematic,
+        intentPath: opts.intent ?? defaultIntentPath(config.schematic),
+        docsDir: config.docs,
+      });
+      if (!res.ok) {
+        if (json) console.log(JSON.stringify({ ok: false, findings: res.findings }, null, 2));
+        else console.error(res.message);
+        process.exit(1);
+      }
+      if (json) console.log(JSON.stringify({ ok: true, report: res.report }, null, 2));
+      else console.log(formatSchematicDraftReport(res.report));
+      process.exit(0);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
+const scoreGroup = program
+  .command('score')
+  .description('quantitative quality score for an artifact; advisory exit code; no LLM, no network');
+scoreGroup
+  .command('schematic')
+  .description('legibility and layout score for the schematic')
+  .action(async () => {
+    const repo = repoOf(program.opts());
+    const json = Boolean(program.opts().json);
+    try {
+      const { loadConfig } = await import('./config.js');
+      const { scoreSchematic, formatScore } = await import('./kicad/score.js');
+      const path = await import('node:path');
+      const config = await loadConfig(repo);
+      if (!config.schematic) {
+        console.error('no schematic configured in .copperhead/config.json');
+        process.exit(1);
+      }
+      const report = await scoreSchematic(path.join(repo, config.schematic), {
+        docsDir: path.join(repo, config.docs),
+        ...(config.legibility ? { config: config.legibility } : {}),
+      });
+      console.log(json ? JSON.stringify(report, null, 2) : formatScore(report));
+      process.exit(0); // the exit code never depends on the composite (AC-16.26 family)
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('env preflight: kicad-cli, git, node, and the model provider credential; no LLM, no network')

package/src/commands/check.ts

@@ -5,7 +5,9 @@ import { runErc, runDrc } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
 import { checkDrift, emptySchematicWarning, type DriftMismatch } from '../memory/drift.js';
 import { loadConstraints, checkForbiddenPins, type ConstraintViolation } from '../memory/constraints.js';
-import { pinNets } from '../kicad/sexp.js';
+import { pinNets, readSheetGeometry } from '../kicad/sexp.js';
+import { scoreFromGeometry, type ScoreReport } from '../kicad/score.js';
+import { checkLegibility, formatLegibility, LEGIBILITY_FAMILIES, type LegibilityFinding } from '../kicad/legibility.js';
 import { openspecValidate } from '../openspec/cli.js';
 
 /**
@@ -19,6 +21,20 @@ export interface CheckResult {
   drift: { ok: boolean; mismatches: DriftMismatch[]; warning?: string };
   openspec: { ok: boolean; detail: string } | null;
   constraints: { ok: boolean; violations: ConstraintViolation[] };
+  /**
+   * Advisory at every severity (design C6): findings inform, the exit code
+   * never depends on them, so existing repos gain information, not failures.
+   * Always present — all families skipped when no schematic is configured.
+   */
+  legibility: {
+    findings: LegibilityFinding[];
+    counts: { error: number; advisory: number };
+    skipped: { family: string; reason: string }[];
+    disabled: string[];
+    suppressed: { family: string; sheet: string; count: number }[];
+    /** Advisory quantitative score; null when no schematic is configured. */
+    score: ScoreReport | null;
+  };
 }
 
 export async function runCheck(repoRoot: string, log: (s: string) => void): Promise<CheckResult> {
@@ -59,6 +75,39 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     log(res.ok ? 'openspec ✓' : `openspec: ${res.output}`);
   }
 
+  let legibility: CheckResult['legibility'];
+  if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
+    const report = await checkLegibility(path.join(repoRoot, config.schematic), {
+      docsDir: path.join(repoRoot, config.docs),
+      ...(config.legibility ? { config: config.legibility } : {}),
+    });
+    const score = scoreFromGeometry(
+      await readSheetGeometry(path.join(repoRoot, config.schematic)),
+      report,
+      config.legibility,
+    );
+    legibility = {
+      findings: report.findings,
+      counts: report.counts,
+      skipped: report.skipped,
+      disabled: report.disabled,
+      suppressed: report.suppressed,
+      score,
+    };
+    log(formatLegibility(report));
+    log(`legibility score: ${score.composite}/100${score.cap ? ` (capped: ${score.cap.reason})` : ''}`);
+  } else {
+    legibility = {
+      findings: [],
+      counts: { error: 0, advisory: 0 },
+      skipped: LEGIBILITY_FAMILIES.map((family) => ({ family, reason: 'no schematic configured' })),
+      disabled: [],
+      suppressed: [],
+      score: null,
+    };
+    log('legibility skipped (no schematic configured)');
+  }
+
   let constraintViolations: ConstraintViolation[] = [];
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
     const registry = await loadConstraints(repoRoot);
@@ -87,5 +136,6 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     drift: { ok: drift.length === 0, mismatches: drift, ...(driftWarning ? { warning: driftWarning } : {}) },
     openspec,
     constraints: { ok: constraintViolations.length === 0, violations: constraintViolations },
+    legibility,
   };
 }