heyspex 0.1.0 → 0.2.1

package/spexharness/src/doctrine/inject.mjs

@@ -0,0 +1,338 @@
+// spexharness/src/doctrine/inject.mjs
+//
+// DR3 (epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]], task
+// [[HS-X3S1-8CMW-TASK-dr3-doctrine-at-runtime-injected-into]]) — Doctrine AT RUNTIME. DR2
+// (writer.mjs/merge.mjs/synthesize.mjs) produces the committed artifacts
+// (spexharness/doctrine/SPEXCODE-DOCTRINE.json/.md); this module is the ONE seam every
+// runtime surface (a SpexCode seat's bootstrap, the chat front's system message, the Claude
+// Code plugin's SessionStart hook, the `/doctrine` built-in) reads that document through —
+// none of them re-parses the JSON or re-implements the confidence-ordered, budget-capped
+// rendering a second time.
+//
+// loadDoctrine() is CACHED (keyed by resolved path) and TOLERANT OF ABSENCE: a repo with no
+// SPEXCODE-DOCTRINE.json yet (DR5's concurrent learner re-run notwithstanding — this reads
+// whatever is on disk at call time, never bakes a snapshot into a test) returns `null` rather
+// than throwing, and every caller downstream (renderDoctrineBlock) turns that into an
+// explicit absence notice rather than silently injecting nothing. invalidateDoctrineCache()
+// is the other half of that cache: `/doctrine refresh` calls it once `hs doctrine learn`
+// finishes, so the NEXT read picks up the freshly written file instead of the stale cached
+// one.
+//
+// renderDoctrineBlock() is measured against its OWN documented budget (DOCTRINE_MAX_TOKENS),
+// deliberately separate from system-message.mjs's SYSTEM_MESSAGE_BYTE_CAP (2000 bytes,
+// sent on every turn) — the Doctrine block rides the bootstrap injection (once per session,
+// not per turn), so it gets real room; the system message only ever carries a one-line
+// pointer to it (system-message.mjs's own `doctrine` option), never the body.
+//
+// recordDoctrineInjection() is the bridge to ../context-budget.mjs's ONE measurement path
+// (recordContextInjection) — same pattern ../chat/system-message.mjs and
+// ../gates/inject-vault-context.mjs already use, under `source: 'doctrine'`.
+//
+// layerProfileOverDoctrine() is Scope 5's pure helper: the SpexCode Profile layer (a later
+// epic) sits ON TOP of Doctrine without silently overriding it — a profile entry with an
+// APPROVED `supersedes` renders as a refinement; one without keeps the Doctrine line and is
+// flagged, exactly the layering rule the doctrine writer's own DOCTRINE_HEADER documents
+// (writer.mjs: "a per-developer layer on top, which may refine a principle here but may not
+// silently contradict one").
+//
+// Pure aside from loadDoctrine's one fs.readFileSync — every other export here does no I/O.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { estimateTokens } from '../token-inventory.mjs';
+import { recordContextInjection } from '../context-budget.mjs';
+import { CATEGORY_ORDER, CATEGORY_LABELS } from './writer.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+/** Default location of the committed Doctrine artifact, relative to a repo root. */
+export function defaultDoctrinePath(repoRoot = REPO_ROOT) {
+  return path.join(repoRoot, 'spexharness', 'doctrine', 'SPEXCODE-DOCTRINE.json');
+}
+
+// ── Audience: platform checkout vs customer repo (HS-A2PO, owner ruling 2026-10-03) ──────────
+//
+// "yes, inject-doctrine ships to customers. Baseline foundational doctrine on which user's
+// doctrine will be built ontop." The full learned file (SPEXCODE-DOCTRINE.json, distilled from
+// the owner's own sessions and full of platform rules) is NOT in the npm package; what ships is
+// the curated BASELINE edition below. A session whose project is the package's own checkout
+// (heyspex-app) keeps reading the learned file; every other project reads ONLY the baseline
+// from the installed package — never a file under the customer's project, never the owner's
+// learned set — and gets nothing at all (a clean no-op) when the baseline is absent.
+
+/** The package root this module was loaded from (heyspex-app, or node_modules/heyspex). */
+export const PACKAGE_ROOT = REPO_ROOT;
+
+/** The shipped baseline edition, repo-relative (also listed in package.json `files`). */
+export const BASELINE_DOCTRINE_REL = 'spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json';
+
+/** Absolute path of the baseline edition inside a package root. */
+export function baselineDoctrinePath(packageRoot = PACKAGE_ROOT) {
+  return path.join(packageRoot, ...BASELINE_DOCTRINE_REL.split('/'));
+}
+
+function samePath(a, b) {
+  const norm = (p) => {
+    const s = path.resolve(p).replace(/\\/g, '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? s.toLowerCase() : s;
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * Which Doctrine a session in `projectRoot` reads. Pure (no fs).
+ *   - project IS the package checkout → `platform`: the learned file under the project.
+ *   - anything else                   → `customer`: the package's baseline edition only.
+ *
+ * @param {{ projectRoot: string, packageRoot?: string }} opts
+ * @returns {{ audience: 'platform'|'customer', path: string }}
+ */
+export function resolveDoctrineSource({ projectRoot, packageRoot = PACKAGE_ROOT }) {
+  if (projectRoot && samePath(projectRoot, packageRoot)) {
+    return { audience: 'platform', path: defaultDoctrinePath(projectRoot) };
+  }
+  return { audience: 'customer', path: baselineDoctrinePath(packageRoot) };
+}
+
+/**
+ * The bootstrap-injection budget this module's own render function is held to — separate
+ * from, and much larger than, system-message.mjs's per-turn SYSTEM_MESSAGE_BYTE_CAP (see
+ * this file's own header). Chosen to comfortably hold every category's top principles
+ * without needing to be raised for the doctrine set this epic ships with; a caller with a
+ * tighter/looser seat budget passes its own `maxTokens` to {@link renderDoctrineBlock}.
+ */
+export const DOCTRINE_MAX_TOKENS = 800;
+
+/** Shown (and injected) when no Doctrine document is readable at the resolved path. */
+export const DOCTRINE_ABSENT_NOTICE =
+  'Doctrine: not yet learned — spexharness/doctrine/SPEXCODE-DOCTRINE.json is missing or empty. ' +
+  'Run `hs doctrine learn` (or `/doctrine refresh`) to generate it.';
+
+/** loadDoctrine()'s cache: resolved path -> parsed doctrine (or `null` for absent/corrupt). */
+const cache = new Map();
+
+/**
+ * Load the Doctrine JSON document, cached by resolved path. Tolerant of absence: a missing
+ * file, an unreadable one, or one that fails to parse as JSON all resolve to `null` rather
+ * than throwing — a runtime surface with no Doctrine yet must still start.
+ *
+ * @param {{ path?: string }} [opts] - `path` overrides the default
+ *   `<repoRoot>/spexharness/doctrine/SPEXCODE-DOCTRINE.json` (tests point this at a fixture).
+ * @returns {object|null} the parsed document (writer.mjs's `buildDoctrineJson` shape), or null.
+ */
+export function loadDoctrine({ path: doctrinePath } = {}) {
+  const resolved = typeof doctrinePath === 'string' && doctrinePath ? doctrinePath : defaultDoctrinePath();
+  if (cache.has(resolved)) return cache.get(resolved);
+  let doctrine = null;
+  try {
+    doctrine = JSON.parse(readFileSync(resolved, 'utf8'));
+  } catch {
+    doctrine = null;
+  }
+  cache.set(resolved, doctrine);
+  return doctrine;
+}
+
+/**
+ * Invalidate loadDoctrine()'s cache — the whole thing, or just one resolved path. `/doctrine
+ * refresh` (builtins.mjs) calls this once `hs doctrine learn` finishes writing a fresh file,
+ * so the NEXT loadDoctrine() call re-reads instead of returning the stale cached document.
+ *
+ * @param {string} [doctrinePath] - when given, only this path's cache entry is dropped.
+ */
+export function invalidateDoctrineCache(doctrinePath) {
+  if (typeof doctrinePath === 'string' && doctrinePath) cache.delete(doctrinePath);
+  else cache.clear();
+}
+
+/** One principle rendered as a single line: `- [do] <text>` / `- [avoid] <text>`. */
+function principleLine(p) {
+  const stance = p?.stance === 'avoid' ? 'avoid' : 'do';
+  return `- [${stance}] ${p?.text ?? ''}`;
+}
+
+/**
+ * Render the Doctrine document into the block every runtime surface injects: a header line
+ * (`learnedAt` + principle count — AC3's "/doctrine prints the document header + principle
+ * count + learnedAt" reads exactly this line), then the TOP principles by confidence,
+ * grouped by category (writer.mjs's own CATEGORY_ORDER/CATEGORY_LABELS — the same section
+ * order the committed Markdown document uses), one line each, kept within `maxTokens`.
+ *
+ * Absence (`doctrine` is null/has no principles) renders {@link DOCTRINE_ABSENT_NOTICE}
+ * instead — AC1's "absent (with a notice) when the file is missing".
+ *
+ * Budget: categories (and the principles inside them) are added in confidence order; the
+ * FIRST principle that would push the rendered text over `maxTokens` and everything ranked
+ * below it are dropped (a true tail cut, matching token-inventory.mjs's own budgeting
+ * convention) — `truncated: true` says so. A category with zero principles that fit is
+ * omitted entirely rather than rendered as an empty header.
+ *
+ * @param {object|null} doctrine - loadDoctrine()'s result.
+ * @param {{ maxTokens?: number }} [opts] - defaults to {@link DOCTRINE_MAX_TOKENS}.
+ * @returns {{ text: string, tokens: number, chars: number, principleCount: number,
+ *   includedCount: number, learnedAt: string|null, truncated: boolean }}
+ */
+export function renderDoctrineBlock(doctrine, { maxTokens = DOCTRINE_MAX_TOKENS } = {}) {
+  const principles = Array.isArray(doctrine?.principles) ? doctrine.principles : [];
+  if (principles.length === 0) {
+    const text = DOCTRINE_ABSENT_NOTICE;
+    return { text, tokens: estimateTokens(text), chars: text.length, principleCount: 0, includedCount: 0, learnedAt: null, truncated: false };
+  }
+
+  const principleCount = principles.length;
+  const learnedAt = typeof doctrine?.learnedAt === 'string' ? doctrine.learnedAt : null;
+  const plural = `${principleCount} principle${principleCount === 1 ? '' : 's'}`;
+  const edition = typeof doctrine?.edition === 'string' && doctrine.edition ? doctrine.edition : null;
+  const header = edition
+    ? `Doctrine (${edition} edition, ${plural}):`
+    : `Doctrine (learned ${learnedAt ?? 'unknown'}, ${plural}):`;
+
+  // Selection is GLOBAL confidence order (AC1's "top principles by confidence within the
+  // budget") — a true tail cut, same convention token-inventory.mjs's own budgeting uses:
+  // the first principle that would overflow, and every lower-confidence one after it, are
+  // dropped together, rather than letting a cheaper low-confidence line jump the queue.
+  const sorted = [...principles].sort((a, b) => (Number(b?.confidence) || 0) - (Number(a?.confidence) || 0));
+
+  let usedTokens = estimateTokens(header);
+  let truncated = false;
+  const includedCats = new Set();
+  const included = []; // { cat, line } in confidence order — display groups these by category.
+
+  for (const p of sorted) {
+    const cat = typeof p?.category === 'string' && p.category ? p.category : 'product-taste';
+    const line = principleLine(p);
+    const lineTokens = estimateTokens(line);
+    const needsCatHeader = !includedCats.has(cat);
+    const catHeaderTokens = needsCatHeader ? estimateTokens(`${CATEGORY_LABELS[cat] ?? cat}:`) : 0;
+    if (usedTokens + catHeaderTokens + lineTokens > maxTokens) {
+      truncated = true;
+      break;
+    }
+    usedTokens += catHeaderTokens + lineTokens;
+    includedCats.add(cat);
+    included.push({ cat, line });
+  }
+
+  // Display grouping: the SELECTED principles, sectioned in writer.mjs's own canonical
+  // CATEGORY_ORDER (matching the committed Markdown document's section order), each section
+  // keeping the confidence order it was selected in.
+  const byCategory = new Map();
+  for (const item of included) {
+    if (!byCategory.has(item.cat)) byCategory.set(item.cat, []);
+    byCategory.get(item.cat).push(item.line);
+  }
+  const orderedCats = [
+    ...CATEGORY_ORDER.filter((c) => byCategory.has(c)),
+    ...[...byCategory.keys()].filter((c) => !CATEGORY_ORDER.includes(c)),
+  ];
+
+  const lines = [header];
+  for (const cat of orderedCats) {
+    lines.push(`${CATEGORY_LABELS[cat] ?? cat}:`, ...byCategory.get(cat));
+  }
+
+  const text = lines.join('\n');
+  return {
+    text,
+    tokens: estimateTokens(text),
+    chars: text.length,
+    principleCount,
+    includedCount: included.length,
+    learnedAt,
+    truncated,
+  };
+}
+
+/**
+ * Record a rendered Doctrine block onto a session record through ../context-budget.mjs's ONE
+ * measurement path — `source: 'doctrine'`, same convention ../chat/system-message.mjs uses
+ * for its own piece. A no-op (returns null) when no `record` is supplied, exactly like
+ * buildSystemMessage's own optional `sessionRecord` — a caller with no session record yet
+ * still gets the block back from {@link renderDoctrineBlock} without erroring here.
+ *
+ * @param {ReturnType<import('../session-record.mjs').createSessionRecord>|null} record
+ * @param {{ text?: string, tokens?: number }|null} block - renderDoctrineBlock()'s result.
+ * @returns {import('../context-budget.mjs').ContextInjectionMeasurement|null}
+ */
+export function recordDoctrineInjection(record, block) {
+  if (!record || !block) return null;
+  return recordContextInjection(record, { source: 'doctrine', name: 'doctrine', text: block.text, tokens: block.tokens });
+}
+
+/**
+ * Scope 5's layering rule, as a pure helper: fold a Profile's entries over the Doctrine
+ * principles they target, WITHOUT the Profile module existing yet (it ships in a later
+ * epic — HS-HEBV per the task's own depends_on). Consumed today only by this module's own
+ * tests (fixtures stand in for real profile entries); `/profile` (the later epic) is the
+ * eventual real caller.
+ *
+ * A profile entry targets one Doctrine principle by exact `targetText` match against that
+ * principle's `text` (Doctrine principles carry no stable id today — matching on the
+ * authored text is the same identity DR2's own merge.mjs dedup uses). An entry with no
+ * matching principle is ignored (Profile-only additions are out of this task's scope).
+ *
+ *   - entry.supersedes?.approved === true  → the layered line is the PROFILE's own text,
+ *     `source: 'profile-refines'`, carrying `refines` (the original Doctrine text) — "refines"
+ *     the Scope 5 language.
+ *   - anything else (no entry, entry present but not approved) → the Doctrine line is kept
+ *     verbatim, `source: 'doctrine'`; a present-but-unapproved entry additionally sets
+ *     `flagged: true` and `contradictedBy` — the `/profile` flag Scope 5 asks for.
+ *
+ * @param {object|null} doctrine - loadDoctrine()'s result.
+ * @param {Array<{ targetText: string, text?: string, stance?: 'do'|'avoid',
+ *   supersedes?: { approved?: boolean } }>} [profileEntries]
+ * @returns {Array<{ category: string, stance: string, text: string,
+ *   source: 'doctrine'|'profile-refines', flagged: boolean, refines?: string, contradictedBy?: string }>}
+ */
+export function layerProfileOverDoctrine(doctrine, profileEntries = []) {
+  const principles = Array.isArray(doctrine?.principles) ? doctrine.principles : [];
+  const entries = Array.isArray(profileEntries) ? profileEntries : [];
+  const byTarget = new Map();
+  for (const entry of entries) {
+    if (entry && typeof entry.targetText === 'string' && entry.targetText) byTarget.set(entry.targetText, entry);
+  }
+
+  return principles.map((p) => {
+    const entry = byTarget.get(p?.text);
+    if (!entry) {
+      return { category: p?.category ?? 'product-taste', stance: p?.stance ?? 'do', text: p?.text ?? '', source: 'doctrine', flagged: false };
+    }
+    const approved = entry?.supersedes?.approved === true;
+    if (approved) {
+      return {
+        category: p?.category ?? 'product-taste',
+        stance: entry.stance ?? p?.stance ?? 'do',
+        text: typeof entry.text === 'string' && entry.text ? entry.text : p?.text ?? '',
+        source: 'profile-refines',
+        refines: p?.text ?? '',
+        flagged: false,
+      };
+    }
+    return {
+      category: p?.category ?? 'product-taste',
+      stance: p?.stance ?? 'do',
+      text: p?.text ?? '',
+      source: 'doctrine',
+      flagged: true,
+      contradictedBy: typeof entry.text === 'string' ? entry.text : null,
+    };
+  });
+}
+
+export default {
+  defaultDoctrinePath,
+  PACKAGE_ROOT,
+  BASELINE_DOCTRINE_REL,
+  baselineDoctrinePath,
+  resolveDoctrineSource,
+  DOCTRINE_MAX_TOKENS,
+  DOCTRINE_ABSENT_NOTICE,
+  loadDoctrine,
+  invalidateDoctrineCache,
+  renderDoctrineBlock,
+  recordDoctrineInjection,
+  layerProfileOverDoctrine,
+};

package/spexharness/src/doctrine/merge.mjs

@@ -0,0 +1,184 @@
+// spexharness/src/doctrine/merge.mjs
+//
+// DR2 (epic [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]], task
+// [[HS-YMPY-8CMW-TASK-dr2-doctrine-synthesis-a-routed]]) — pure merge of candidate
+// principles (from synthesize.mjs's seat batches, plus the Command Code taste lines
+// seeded in as principles) into the final set a Doctrine document is written from.
+//
+// DR5 ([[HS-7Z9E-8CMW-TASK-dr5-vault-knowledge-as-a-doctrine]]) adds a second seeded
+// source: vault-source.mjs's curated vault rules (owner rulings, lessons, protocol
+// enforcement, accepted ADRs, north star/operating model/principles-index, the
+// naughty list, this repo's CLAUDE.md). Vault rules are seeded FIRST, ahead of the
+// seat's synthesized candidates, so a matching session-derived principle dedupes INTO
+// the vault rule (the vault rule's text stays canonical) and a contradicting one is
+// headlined by the vault rule — the owner's written word wins over inferred behaviour.
+//
+// Pure: no I/O, no randomness, no clock reads except a caller-supplied `now` (unused
+// today, reserved so a future "later ruling wins" tie-break can be date-aware without
+// changing this module's shape).
+//
+// What this does, in order:
+//   1. Dedupe near-identical principles (same category + stance, normalized-text
+//      similarity ≥ DEDUP_SIMILARITY_THRESHOLD) — union their evidence ids and raise
+//      confidence with each independent piece of evidence. The FIRST-seen candidate's
+//      text is kept as canonical; later matches only contribute evidence/confidence.
+//   2. Detect a contradiction: same category, OPPOSITE stance, similarity above the
+//      same threshold (i.e. clearly the same topic). Neither side is dropped — both
+//      stay in `principles`, and the pair is recorded under `conflicts`. The headline
+//      is the vault-sourced side when either side is vault-sourced; otherwise the
+//      later-seen one (later ruling wins for the headline; both cited either way).
+//   3. Seed the Command Code taste lines as principles at their own stated confidence,
+//      `evidence: ['taste:<...>']` (the observation id corpus.mjs already gives a
+//      taste line, which is itself prefixed `taste:` — see {@link seedTasteAsPrinciples}).
+//   4. Seed vault-source.mjs's `vault-rule` observations as principles at their own
+//      `seedConfidence`, `evidence: [obs.id]` (already shaped `vault:<spec id>...`),
+//      category from {@link import('./vault-source.mjs').classifyVaultCategory} — see
+//      {@link seedVaultRulesAsPrinciples}.
+
+import { classifyVaultCategory } from './vault-source.mjs';
+
+/**
+ * @typedef {{
+ *   text: string,
+ *   category: string,
+ *   confidence: number,
+ *   evidence: string[],
+ *   stance: 'do'|'avoid',
+ *   supersedes?: string[],
+ * }} DoctrinePrinciple
+ */
+
+const DEFAULT_CATEGORY = 'product-taste';
+
+/** Lowercase, strip punctuation, collapse whitespace — the text dedup/contradiction compares on. */
+export function normalizeForDedup(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Token-overlap (Jaccard) similarity of two principle texts, 0..1. Pure, no dependencies. */
+export function textSimilarity(a, b) {
+  const ta = new Set(normalizeForDedup(a).split(' ').filter(Boolean));
+  const tb = new Set(normalizeForDedup(b).split(' ').filter(Boolean));
+  if (ta.size === 0 || tb.size === 0) return 0;
+  let intersection = 0;
+  for (const t of ta) if (tb.has(t)) intersection++;
+  const union = ta.size + tb.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/** Similarity at/above this is "the same topic" for both dedup and contradiction detection. */
+export const DEDUP_SIMILARITY_THRESHOLD = 0.5;
+
+/**
+ * Seed the Command Code taste lines (corpus.mjs observations with `kind === 'taste'`)
+ * as candidate principles at their own stated confidence. `evidence` is the taste
+ * observation's own id (already shaped `taste:<project>:<session>:<seq>`), which both
+ * satisfies "cites an id that exists" and reads as `taste:<n>` per the task brief.
+ *
+ * @param {Array<{ id: string, text: string, confidence?: number }>} tasteObservations
+ * @returns {DoctrinePrinciple[]}
+ */
+export function seedTasteAsPrinciples(tasteObservations) {
+  return (tasteObservations ?? []).map((obs) => ({
+    text: obs.text,
+    category: DEFAULT_CATEGORY,
+    confidence: typeof obs.confidence === 'number' ? obs.confidence : 0.5,
+    evidence: [obs.id],
+    stance: 'do',
+  }));
+}
+
+/**
+ * Seed vault-source.mjs's `vault-rule` observations (owner decisions, lessons,
+ * protocol enforcement, accepted ADRs, north star/operating model/principles-index,
+ * the naughty list, CLAUDE.md) as candidate principles at their own `seedConfidence`.
+ * `evidence` is the observation's own id (already shaped `vault:<spec id>...`).
+ * `category` comes from {@link classifyVaultCategory} — never the seat (vault
+ * observations are never sent to it, see synthesize.mjs). Every seeded principle
+ * carries `vaultSourced: true` so {@link mergePrinciples} can headline it over a
+ * contradicting session-derived principle regardless of processing order.
+ *
+ * @param {Array<{ id: string, set: string, text: string, stance: 'do'|'avoid', seedConfidence: number }>} vaultObservations
+ * @returns {DoctrinePrinciple[]}
+ */
+export function seedVaultRulesAsPrinciples(vaultObservations) {
+  return (vaultObservations ?? [])
+    .filter((obs) => obs && obs.source === 'vault' && obs.kind === 'vault-rule')
+    .map((obs) => ({
+      text: obs.text,
+      category: classifyVaultCategory(obs),
+      confidence: typeof obs.seedConfidence === 'number' ? obs.seedConfidence : 0.5,
+      evidence: [obs.id],
+      stance: obs.stance === 'avoid' ? 'avoid' : 'do',
+      vaultSourced: true,
+    }));
+}
+
+/** Independent evidence nudges confidence up, asymptotic to 0.99 — never overridden downward by a merge. */
+function raiseConfidence(baseConfidence, candidateConfidence) {
+  const bumped = baseConfidence + (1 - baseConfidence) * 0.15;
+  return Math.min(0.99, Math.max(bumped, candidateConfidence ?? baseConfidence));
+}
+
+function dedupeEvidence(evidence) {
+  return Array.from(new Set(evidence.filter((id) => typeof id === 'string' && id.length > 0)));
+}
+
+/**
+ * Merge candidate principles (freshly synthesized + any `existing` from a prior run,
+ * oldest first) into the final principle set, deduping, raising confidence, and
+ * recording contradictions.
+ *
+ * @param {DoctrinePrinciple[]} candidates
+ * @param {{ existing?: DoctrinePrinciple[] }} [opts] `existing` — principles from a
+ *   prior incremental run, merged in FIRST (oldest), so a fresh candidate can still be
+ *   detected as a contradiction of (and become the new headline over) one already on
+ *   file.
+ * @returns {{ principles: DoctrinePrinciple[], conflicts: Array<{ category: string, a: string, b: string, headline: string }> }}
+ */
+export function mergePrinciples(candidates, { existing = [] } = {}) {
+  const ordered = [...existing, ...candidates];
+  const merged = [];
+  const conflicts = [];
+
+  for (const cand of ordered) {
+    if (!cand || typeof cand.text !== 'string' || !cand.text.trim()) continue;
+
+    const dupe = merged.find(
+      (m) => m.category === cand.category && m.stance === cand.stance && textSimilarity(m.text, cand.text) >= DEDUP_SIMILARITY_THRESHOLD,
+    );
+    if (dupe) {
+      dupe.evidence = dedupeEvidence([...dupe.evidence, ...(cand.evidence ?? [])]);
+      dupe.confidence = raiseConfidence(dupe.confidence, cand.confidence);
+      if (cand.vaultSourced) dupe.vaultSourced = true; // the vault-sourced flag propagates forward once true
+      continue;
+    }
+
+    const opposite = merged.find(
+      (m) => m.category === cand.category && m.stance !== cand.stance && textSimilarity(m.text, cand.text) >= DEDUP_SIMILARITY_THRESHOLD,
+    );
+    if (opposite) {
+      // The owner's written word wins over inferred behaviour: when either side of a
+      // contradiction is vault-sourced, IT is the headline regardless of which was
+      // seen first; otherwise the later-seen candidate is the headline as before.
+      const headline = opposite.vaultSourced && !cand.vaultSourced ? opposite.text : cand.text;
+      conflicts.push({ category: cand.category, a: opposite.text, b: cand.text, headline });
+    }
+
+    merged.push({
+      text: cand.text,
+      category: cand.category ?? DEFAULT_CATEGORY,
+      confidence: typeof cand.confidence === 'number' ? cand.confidence : 0.5,
+      evidence: dedupeEvidence(cand.evidence ?? []),
+      stance: cand.stance === 'avoid' ? 'avoid' : 'do',
+      ...(Array.isArray(cand.supersedes) && cand.supersedes.length ? { supersedes: cand.supersedes.slice() } : {}),
+      ...(cand.vaultSourced ? { vaultSourced: true } : {}),
+    });
+  }
+
+  return { principles: merged, conflicts };
+}