@damiangilgonzalez/harness 1.3.7

package/scripts/lib/repetition-report.js

@@ -0,0 +1,47 @@
+// repetition-report.js — the I/O half of the repetition detector.
+//
+// Kept apart from repetition.js on purpose: the deciding is pure and heavily tested, the reading of two
+// files is not. Mixing them would make the interesting logic need fixtures on disk.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { gapLogPath, globalGapLogPath, capabilities } from './capabilities.js';
+import { parseGapLog, groupProcedures, decideOffer, mergeLogs, THRESHOLD } from './repetition.js';
+
+/**
+ * Read local + global logs, group, decide. FAILS CLOSED: an unreadable log yields `blocked`, never an
+ * invented count. countGaps() already sets the precedent of not taking `doctor` down over a malformed
+ * log; the difference here is that the degradation is announced instead of swallowed.
+ */
+export function repetitionReport({ cwd = process.cwd(), home = homedir(), target = 'claude' } = {}) {
+  const read = (p, label) => {
+    if (!existsSync(p)) return { entries: [], missing: true };
+    try { return { entries: parseGapLog(readFileSync(p, 'utf8')), missing: false }; }
+    catch (e) { return { error: `no se pudo leer el registro ${label} (${p}): ${e.message}` }; }
+  };
+  const local = read(gapLogPath(cwd), 'local');
+  const global = read(globalGapLogPath(home), 'global');
+  if (local.error || global.error) {
+    return { blocked: true, reason: local.error || global.error, offer: null, uncertain: [], entries: 0 };
+  }
+  const merged = mergeLogs(local.entries, global.entries);
+  if (!merged.length) {
+    return { blocked: false, offer: null, reason: 'no hay entradas registradas todavía', uncertain: [], entries: 0 };
+  }
+  const { groups, uncertain } = groupProcedures(merged);
+
+  // "Already covered" is answered by the command that reads the disk, never by memory — the decision
+  // capabilities.js already made and for the right reason.
+  let covered = false;
+  try {
+    const caps = capabilities({ target, cwd });
+    const top = [...groups].sort((a, b) => b.entries.length - a.entries.length)[0];
+    if (top) {
+      const words = top.key.toLowerCase();
+      covered = caps.installed.some((s) => words.includes(s.id)) || (caps.agents || []).some((a) => words.includes(a.id));
+    }
+  } catch { /* enumeration failing must not fabricate "covered" — leave it false */ }
+
+  const { offer, reason } = decideOffer({ groups, threshold: THRESHOLD, covered });
+  return { blocked: false, offer, reason, uncertain, entries: merged.length, groups: groups.length };
+}

package/scripts/lib/repetition.js

@@ -0,0 +1,186 @@
+// repetition.js — has this procedure been done before, and does it deserve to stop being manual?
+//
+// The always-on rule already asks "did you just deliver a repeatable PROCEDURE?" — a judgment about ONE
+// episode, made by the same agent that just performed it, at the moment it is most convinced its work
+// was special. Grepping the always-on layer for repeat|repetit|twice|recurr returns nothing: nothing
+// looks backwards.
+//
+// The registry that would allow it already exists. `rsc capabilities gap-log` writes one line per
+// observed procedure, and the only thing that consumes it is countGaps(), which returns a TOTAL for
+// `doctor` to display. The ledger is written and nobody interrogates it — the passive form of the same
+// P2 defect.
+//
+// The evidence is the session that wrote this: four manual mutation runs (8, 17, 12, 6 mutants) and
+// five identical score-then-rescore passes, none of which ever triggered the rule, because each episode
+// looked like one-off work on its own.
+//
+// Two decisions from clarify (2026-08-18): the count is GLOBAL with a per-repo breakdown (a procedure
+// repeated across projects is stronger signal, not weaker), and the threshold is THREE — a reasoned
+// bet, not a measurement, and it says so.
+
+import { tokenize } from './text-rank.js';
+
+export const THRESHOLD = 3;
+
+// Numerals and structural filler carry no information about WHICH procedure this is — "eight mutants"
+// and "twelve mutants" are the same work. Dropping them is what made the margin measurable at all.
+const FILLER = /^(uno|dos|tres|cuatro|cinco|seis|siete|ocho|nueve|diez|once|doce|trece|catorce|quince|dieciseis|diecisiet|dieciocho|diecinuev|veint|cada|por|sobr|un|una|one|two|three|four|five|six|seven|eight|nine|ten|each)$/;
+
+// CALIBRATED, NOT GUESSED. Three metrics were measured on real descriptions from the session that
+// motivated this (3 same-procedure pairs, 12 different-procedure pairs):
+//
+//   metric    same            different   margin
+//   jaccard   0.17–0.30       ≤0.09       0.08
+//   overlap   0.29–0.50       ≤0.20       0.09
+//   dice      0.29–0.46       ≤0.17       0.12   ← widest, so this is the one
+//
+// The first version used Jaccard at 0.6 and grouped nothing: the real case came out as four groups of
+// one. Guessing a threshold for a similarity metric is how you ship a detector that never fires.
+//
+// HONEST LIMIT: n=15 pairs from one session. This is calibration, not validation. If it groups wrongly
+// in practice the number moves, and the measurement above is the record of how it was chosen.
+export const GROUP_AT = 0.25;
+// The band where the answer is "maybe": it does NOT group, and it records what it refused to assume.
+// Grouping wrongly inflates the count and fires an offer about something that never repeated — the more
+// expensive of the two mistakes (P7: a system that nags in the harmless 80% gets switched off).
+export const UNCERTAIN_AT = 0.17;
+
+const LOG_LINE = /^- (\d{4}-\d{2}-\d{2}) · (.+?) · \*\*([a-z-]+)\*\*\s*$/;
+const REPO_TAG = /\s*·?\s*\[repo:([^\]]+)\]\s*$/;
+
+/** Parse a gap log. Malformed lines are skipped, not guessed at; the caller decides what silence means. */
+export function parseGapLog(text) {
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = LOG_LINE.exec(lines[i]);
+    if (!m) continue;
+    let procedure = m[2];
+    let repo = null;
+    const tag = REPO_TAG.exec(procedure);
+    if (tag) { repo = tag[1]; procedure = procedure.slice(0, tag.index).trim(); }
+    out.push({ date: m[1], procedure, verdict: m[3], repo, line: i + 1 });
+  }
+  return out;
+}
+
+/** Significant tokens: text-rank's (accent-folded, stopworded, stemmed) minus numerals and filler. */
+export function terms(text) {
+  return new Set(tokenize(String(text || '')).filter((tk) => !FILLER.test(tk)));
+}
+
+/**
+ * Dice coefficient over significant tokens: 2|A∩B| / (|A|+|B|). Not cosine — that weights by IDF over a
+ * corpus and here there are just two sentences. Not Jaccard — measured narrower on real data (see the
+ * table above).
+ */
+export function similarity(a, b) {
+  const A = terms(a);
+  const B = terms(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const tk of A) if (B.has(tk)) inter++;
+  return (2 * inter) / (A.size + B.size);
+}
+
+/**
+ * Group entries describing the same procedure. Deterministic: first entry of a group is its key, and a
+ * candidate joins only if it clears GROUP_AT against that key. Anything in the uncertain band is left
+ * ungrouped and recorded, so a human can see what the detector refused to assume.
+ */
+export function groupProcedures(entries, threshold = GROUP_AT) {
+  const groups = [];
+  const uncertain = [];
+  for (const e of entries) {
+    let best = null;
+    let bestScore = 0;
+    for (const g of groups) {
+      const s = similarity(e.procedure, g.key);
+      if (s > bestScore) { bestScore = s; best = g; }
+    }
+    if (best && bestScore >= threshold) {
+      best.entries.push(e);
+      if (e.repo) best.repos.set(e.repo, (best.repos.get(e.repo) || 0) + 1);
+      continue;
+    }
+    if (best && bestScore >= UNCERTAIN_AT) {
+      uncertain.push({ procedure: e.procedure, nearest: best.key, score: Number(bestScore.toFixed(2)) });
+    }
+    groups.push({
+      key: e.procedure,
+      entries: [e],
+      repos: new Map(e.repo ? [[e.repo, 1]] : []),
+    });
+  }
+  return { groups, uncertain };
+}
+
+const CAPABILITY_VERBS = /\b(plantar|plant|correr|ejecutar|run|contar|count|restaurar|restore|medir|measure|extraer|extract|puntuar|score|comparar|compare|generar|generate)\b/i;
+const AGENT_VERBS = /\b(revisar|review|refutar|refute|auditar|audit|verificar|verify|juzgar|judge|a ciegas|blind)\b/i;
+
+/**
+ * Which shape does this procedure want? Order matters: the first match wins, and capability comes
+ * first because it is the majority case observed and the one with no verdict until now. Writing a
+ * paragraph for something that needs a script is the failure the generalization gate already named.
+ */
+export function recommendKind(procedure) {
+  const p = String(procedure || '');
+  if (CAPABILITY_VERBS.test(p)) {
+    return {
+      kind: 'capability',
+      why: 'describe algo que hay que ejecutar y comparar; una skill escribiría un párrafo donde hace falta un script o un hook',
+    };
+  }
+  if (AGENT_VERBS.test(p)) {
+    return {
+      kind: 'agent',
+      why: 'describe mirar o juzgar sin arrastrar el contexto de quien lo pide, que es para lo que sirve un contexto fresco',
+    };
+  }
+  return { kind: 'skill', why: 'describe guía y disciplina sobre lo que ya se está haciendo en la conversación' };
+}
+
+const DECLINED = 'proposed-declined';
+
+/**
+ * Should anything be said? Silence is the default and the common case.
+ *
+ * Never offers when: below threshold, already covered, or previously declined. A "no" that has to be
+ * repeated every week is what makes someone switch the whole harness off.
+ */
+export function decideOffer({ groups, threshold = THRESHOLD, covered = false }) {
+  if (covered) return { offer: null, reason: 'ya cubierto por una skill o agente instalado' };
+  const ranked = [...groups].sort((a, b) => b.entries.length - a.entries.length);
+  for (const g of ranked) {
+    if (g.entries.length < threshold) continue;
+    // A decline anywhere in the group retires it permanently.
+    if (g.entries.some((e) => e.verdict === DECLINED)) continue;
+    const rec = recommendKind(g.key);
+    return {
+      offer: {
+        procedure: g.key,
+        seen: g.entries.length,
+        dates: g.entries.map((e) => e.date),
+        repos: [...g.repos.entries()].map(([repo, n]) => ({ repo, n })),
+        kind: rec.kind,
+        why: rec.why,
+        threshold,
+      },
+      reason: null,
+    };
+  }
+  return { offer: null, reason: `ningún procedimiento alcanza el umbral de ${threshold}` };
+}
+
+/** Merge local + global entries, de-duplicated by date+procedure+verdict, so double-writing cannot double-count. */
+export function mergeLogs(localEntries, globalEntries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of [...localEntries, ...globalEntries]) {
+    const k = `${e.date}|${e.procedure}|${e.verdict}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(e);
+  }
+  return out;
+}

package/scripts/lib/result-envelope.js

@@ -0,0 +1,35 @@
+const REQUIRED = [
+  'status',
+  'executive_summary',
+  'artifact',
+  'next_recommended',
+  'risk',
+  'skill_resolution',
+  'evidence',
+];
+
+export function validateResultEnvelope(envelope) {
+  const errors = [];
+  for (const key of REQUIRED) {
+    if (envelope?.[key] === undefined) errors.push(`missing ${key}`);
+  }
+  const sr = envelope?.skill_resolution;
+  if (sr !== undefined) {
+    for (const key of ['used', 'missing', 'fallback', 'compact_rules']) {
+      if (!Array.isArray(sr?.[key])) errors.push(`skill_resolution.${key} must be array`);
+    }
+  }
+  if (envelope?.evidence !== undefined && !Array.isArray(envelope.evidence)) {
+    errors.push('evidence must be array');
+  }
+  return errors;
+}
+
+export function parseResultEnvelope(text) {
+  const match = text.match(/```json\s+result-envelope\s*\n([\s\S]*?)\n```/);
+  if (!match) throw new Error('missing result-envelope json block');
+  const envelope = JSON.parse(match[1]);
+  const errors = validateResultEnvelope(envelope);
+  if (errors.length) throw new Error(`invalid result envelope: ${errors.join(', ')}`);
+  return envelope;
+}

package/scripts/lib/skill-lint.js

@@ -0,0 +1,29 @@
+// Structural lint of a skill body. Pure: give it the text, get a verdict.
+//
+// Scope is deliberately one defect class. A stray closing delimiter inverts every block boundary
+// after it, so a skill can render half its body as one code block while every other gate stays
+// green: the frontmatter validates, the description fits, the prose reads fine in the source. It is
+// a purely deterministic defect, so it belongs to a binary, not to a reader's attention.
+
+const FENCE = /^(?:```|~~~)/;
+
+/**
+ * @param {string} body raw skill markdown
+ * @returns {{balanced: boolean, fences: number, opened: number|null}}
+ *   `fences` counts column-0 delimiters; `opened` is the 1-indexed line of the unpaired one.
+ */
+export function fenceBalance(body) {
+  const lines = String(body ?? '').split('\n');
+  let open = null; // line number of the delimiter that opened the current block
+  let fences = 0;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    // Only a column-0 delimiter is a block boundary. Indented ones are content: a fenced sample
+    // inside a fenced block. Counting those would flag correct documents.
+    if (!FENCE.test(lines[i])) continue;
+    fences += 1;
+    open = open === null ? i + 1 : null;
+  }
+
+  return { balanced: open === null, fences, opened: open };
+}

package/scripts/lib/starting-point.js

@@ -0,0 +1,314 @@
+// What does this project already own to start from, and does its colour hold up?
+//
+// The design area declares three times that it will propose a starting point when the user has
+// none — `design-loop` phase 1 on `skip`, the closing line of `design`'s brand grounding, and
+// `design-dna`'s REUSE mode — and none of the three had anything behind it. An unbacked promise to
+// propose falls back to the model's prior, which is the AI-template median the area exists to
+// escape. Spec: docs/wiki/sdd/specs/design-starting-point.md
+//
+// This file is the half that can be an algorithm (P1): listing what is installed, and refusing to
+// propose a colour that fails contrast. The half that needs judgement — which reference is the right
+// bar for what you are building — is prose, in design/references/starting-point.md.
+//
+// Read-only, always. `docs` is untracked and has no undo (P9), and a discovery pass has no
+// business writing anywhere.
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { designIdentity, BRAND_DIR } from './design-identity.js';
+
+// WCAG 2.2 AA. Body text, and the relaxed floor for large text and UI components.
+export const TEXT_MIN = 4.5;
+export const UI_MIN = 3.0;
+
+// Which palette roles are held to which floor. `design-dna`'s schema fixes the role vocabulary
+// (ground, ink, accent, secondary, hairline); anything outside it is skipped rather than guessed at,
+// because inventing a threshold for an unknown role is how a gate starts approving things.
+const TEXT_ROLES = new Set(['ink', 'secondary']);
+const UI_ROLES = new Set(['accent']);
+const GROUND_ROLE = 'ground';
+
+// A record is only reusable if it carries the fields a style is actually rebuilt from. Half a record
+// cannot be reused, so it is reported as unreadable instead of offered as a candidate.
+const REQUIRED = ['palette'];
+const DIMENSIONS = ['palette', 'type', 'space', 'surface', 'motion', 'signatures', 'voice'];
+
+/** Where `design-dna` emits, and where rsc installs, in both scopes. */
+export function defaultRoots({ home = homedir(), cwd = process.cwd() } = {}) {
+  const roots = [];
+  for (const base of home === cwd ? [cwd] : [cwd, home]) {
+    roots.push(join(base, '.claude', 'skills'));
+    roots.push(join(base, '.rsc', 'skills'));
+  }
+  return roots;
+}
+
+function parseHex(hex) {
+  if (typeof hex !== 'string') return null;
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+// WCAG relative luminance. The sRGB transfer function, not a shortcut: an approximation here is a
+// wrong ratio everywhere downstream, and it would pass a test written against this file's own output.
+function luminance([r, g, b]) {
+  const lin = [r, g, b].map((c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+}
+
+/**
+ * WCAG 2.x contrast ratio between two colours, 1.0 … 21.0. Symmetric.
+ * @param {string} a sRGB hex, `#rrggbb`
+ * @param {string} b sRGB hex, `#rrggbb`
+ */
+export function contrastRatio(a, b) {
+  const ca = parseHex(a);
+  const cb = parseHex(b);
+  if (!ca || !cb) throw new TypeError(`not an sRGB hex colour: ${!ca ? a : b}`);
+  const la = luminance(ca);
+  const lb = luminance(cb);
+  const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Does this palette's text hold up against its own ground?
+ *
+ * Runs before a measured colour is written as a proposed dimension: a value that fails is not
+ * proposed at all, rather than proposed and flagged. Three outcomes are kept apart on purpose —
+ * measured-and-passing, measured-and-failing, and **not measured**. Collapsing the third into the
+ * first is the vacuous pass this area has already paid for twice.
+ *
+ * @param {Array<{role: string, hex: string, name?: string}>} colors — `palette.colors` from a dna.json
+ * @returns {{ok: boolean, pairs: Array<object>, failures: Array<object>, skipped: Array<object>,
+ *            unparsed: string[], reason: string}}
+ */
+export function checkPairings(colors) {
+  const list = Array.isArray(colors) ? colors : [];
+  const pairs = [];
+  const skipped = [];
+  const unparsed = [];
+
+  const ground = list.find((c) => c && c.role === GROUND_ROLE);
+  const groundHex = ground ? parseHex(ground.hex) : null;
+  if (!ground) {
+    return { ok: false, pairs, failures: [], skipped, unparsed, reason: 'no ground role in the palette — nothing to measure against' };
+  }
+  if (!groundHex) {
+    unparsed.push(String(ground.hex));
+    return { ok: false, pairs, failures: [], skipped, unparsed, reason: `ground colour is not an sRGB hex: ${ground.hex}` };
+  }
+
+  for (const c of list) {
+    if (!c || c.role === GROUND_ROLE) continue;
+    const isText = TEXT_ROLES.has(c.role);
+    const isUi = UI_ROLES.has(c.role);
+    if (!isText && !isUi) {
+      // A hairline is not text. Saying so is not the same as saying it passed.
+      skipped.push({ role: c.role, name: c.name, reason: 'role carries no text, so no text floor applies' });
+      continue;
+    }
+    if (!parseHex(c.hex)) {
+      unparsed.push(String(c.hex));
+      continue;
+    }
+    const min = isText ? TEXT_MIN : UI_MIN;
+    const ratio = Math.round(contrastRatio(c.hex, ground.hex) * 100) / 100;
+    pairs.push({ role: c.role, name: c.name, fg: c.hex, bg: ground.hex, ratio, min, ok: ratio >= min });
+  }
+
+  const failures = pairs.filter((p) => !p.ok);
+  // Not measuring anything is not a pass. An empty failure list only means green when at least one
+  // pair was actually evaluated and nothing was left unparsed.
+  const ok = failures.length === 0 && unparsed.length === 0 && pairs.length > 0;
+  const reason = unparsed.length
+    ? `${unparsed.length} colour(s) could not be parsed, so they were not measured`
+    : pairs.length === 0
+      ? 'no text or UI role to measure against the ground'
+      : failures.length
+        ? `${failures.length} pair(s) below their floor`
+        : `${pairs.length} pair(s) measured, all above their floor`;
+  return { ok, pairs, failures, skipped, unparsed, reason };
+}
+
+function readRecord(dir, slug) {
+  const file = join(dir, 'dna.json');
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (e) {
+    return { error: `cannot read dna.json: ${e.code || e.message}` };
+  }
+  let dna;
+  try {
+    dna = JSON.parse(raw);
+  } catch (e) {
+    return { error: `dna.json is not valid JSON: ${e.message}` };
+  }
+  const missing = REQUIRED.filter((k) => !dna || !dna[k]);
+  if (missing.length) return { error: `record is missing ${missing.join(', ')} — half a record cannot be reused` };
+
+  return {
+    record: {
+      slug: (dna.meta && dna.meta.slug) || slug,
+      name: (dna.meta && dna.meta.name) || slug,
+      path: file,
+      covers: DIMENSIONS.filter((d) => dna[d]),
+      palette: (dna.palette && dna.palette.colors) || [],
+    },
+  };
+}
+
+// What the harness's own identity articles mention. A record the project actually used outranks one
+// that merely happens to be installed — but the others stay on the list, because choosing for the
+// user is exactly what the spec forbids.
+function citedSlugs(harnessRoot) {
+  const dir = join(harnessRoot, BRAND_DIR);
+  let text = '';
+  try {
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      try { text += readFileSync(join(dir, f), 'utf8').toLowerCase(); } catch { /* one unreadable article is not the answer */ }
+    }
+  } catch { /* no identity here; designIdentity reports that half */ }
+  return text;
+}
+
+/**
+ * What this project already owns to start a design from.
+ *
+ * @param {string[]} roots — skill directories to scan. Defaults to both scopes, both layouts.
+ * @param {string} harnessRoot — where `docs/` lives, for the identity half and the ordering.
+ * @returns {{state: 'owned'|'none'|'inconclusive', identity: object, records: object[],
+ *            unreadable: Array<{path: string, reason: string}>, reason: string, fix?: string}}
+ *   `owned`        — an identity or at least one legible record exists.
+ *   `none`         — looked everywhere, found nothing. Carries the way out (P6).
+ *   `inconclusive` — something could not be read. Never reported as `none`, never as green.
+ */
+export function ownedStartingPoints(roots = defaultRoots(), harnessRoot = process.cwd()) {
+  const identity = designIdentity(harnessRoot);
+  const records = [];
+  const unreadable = [];
+  let blind = 0;
+
+  for (const root of roots) {
+    // existsSync follows symlinks, so a dangling one answers false and would be filed as "nothing
+    // installed here". That is unreadability, not absence — the exact conflation designIdentity was
+    // fixed for. lstat sees the link itself and tells them apart.
+    if (!existsSync(root)) {
+      let dangling = false;
+      try { dangling = lstatSync(root).isSymbolicLink(); } catch { /* genuinely absent */ }
+      if (dangling) {
+        blind += 1;
+        unreadable.push({ path: root, reason: 'skills root is a symlink that does not resolve' });
+      }
+      continue;
+    }
+    let entries;
+    try {
+      if (!statSync(root).isDirectory()) {
+        blind += 1;
+        unreadable.push({ path: root, reason: 'skills root exists but is not a directory' });
+        continue;
+      }
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch (e) {
+      blind += 1;
+      unreadable.push({ path: root, reason: `cannot read skills root: ${e.code || e.message}` });
+      continue;
+    }
+    for (const entry of entries) {
+      // Dirents, not statSync: a symlinked entry could otherwise report on a directory outside the
+      // root we were asked to scan.
+      if (!entry.isDirectory()) continue;
+      const dir = join(root, entry.name);
+      if (!existsSync(join(dir, 'dna.json'))) continue;
+      const { record, error } = readRecord(dir, entry.name);
+      if (error) { unreadable.push({ path: join(dir, 'dna.json'), reason: error }); continue; }
+      if (!records.some((r) => r.slug === record.slug)) records.push(record);
+    }
+  }
+
+  const cited = citedSlugs(harnessRoot);
+  records.sort((a, b) => {
+    const ac = cited.includes(a.slug.toLowerCase()) ? 0 : 1;
+    const bc = cited.includes(b.slug.toLowerCase()) ? 0 : 1;
+    return ac - bc || a.slug.localeCompare(b.slug);
+  });
+
+  if (records.length || identity.state === 'present') {
+    return {
+      state: 'owned',
+      identity,
+      records,
+      unreadable,
+      reason: [
+        identity.state === 'present' ? `identity present (${identity.articles.length} article(s))` : 'no harness identity',
+        `${records.length} style record(s)`,
+        unreadable.length ? `${unreadable.length} unreadable` : null,
+      ].filter(Boolean).join(', '),
+    };
+  }
+
+  // Something was there and we could not use it. Saying "nothing to propose" would be a finding we
+  // did not earn, and saying nothing at all would hide it.
+  if (unreadable.length || blind || identity.state === 'inconclusive') {
+    return {
+      state: 'inconclusive',
+      identity,
+      records,
+      unreadable,
+      reason: unreadable.length
+        ? `could not read ${unreadable.length} candidate(s): ${unreadable[0].reason}`
+        : `identity could not be read: ${identity.reason}`,
+      fix: 'name what could not be read, and ask for another route to it — never propose past a blind spot',
+    };
+  }
+
+  return {
+    state: 'none',
+    identity,
+    records: [],
+    unreadable,
+    reason: 'no harness identity and no style record installed in any scope',
+    fix: 'propose at most three openable references as candidate bars (design/references/starting-point.md), then run `design-loop`',
+  };
+}
+
+/**
+ * The compact projection `doctor` reports: one object, not a section (P5 — every byte of a report is
+ * paid by every user who runs it). Contrast is folded in per record because a record whose own
+ * palette fails is not a starting point anyone should be offered.
+ *
+ * @returns {{state: string, records: string[], contrast: string, unreadable: number, reason: string}}
+ */
+export function startingPointSummary(root = process.cwd(), roots = defaultRoots({ cwd: root })) {
+  const r = ownedStartingPoints(roots, root);
+  let failing = 0;
+  let unmeasured = 0;
+  for (const rec of r.records) {
+    const c = checkPairings(rec.palette);
+    if (c.failures.length) failing += 1;
+    else if (!c.ok) unmeasured += 1;
+  }
+  const contrast = r.records.length === 0
+    ? 'no record to measure'
+    : failing
+      ? `${failing} record(s) with a pair below its floor`
+      : unmeasured
+        ? `${unmeasured} record(s) could not be measured`
+        : 'all records above their floors';
+  return {
+    state: r.state,
+    records: r.records.map((x) => x.slug),
+    contrast,
+    unreadable: r.unreadable.length,
+    reason: r.reason,
+    ...(r.fix ? { fix: r.fix } : {}),
+  };
+}

package/scripts/lib/state.js

@@ -0,0 +1,12 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export function readState(file) {
+  if (!existsSync(file)) return { skills: {} };
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return { skills: {} }; }
+}
+
+export function writeState(file, state) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+}