dravoice 0.1.3 → 0.2.0

package/src/v2/profile.js

@@ -17,9 +17,9 @@ import {
   stabilityFromDistances,
 } from "./stylometry.js";
 
-export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [] }) {
+export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [], registerMarkers }) {
   const documents = loadDocuments({ examplesDir, excludePaths });
-  const profile = buildVoiceProfileV2({ documents });
+  const profile = buildVoiceProfileV2({ documents, registerMarkers });
   if (outDir) {
     writeVoicePackV2(outDir, profile);
   }
@@ -39,9 +39,10 @@ export function loadVoicePackV2(voiceDir) {
   return profile;
 }
 
-export function buildVoiceProfileV2({ documents }) {
+export function buildVoiceProfileV2({ documents, registerMarkers }) {
   const source = sourceSummary(documents);
-  const families = analyzeFeatureFamilies(documents);
+  const families = analyzeFeatureFamilies(documents, { registerMarkers });
+  const styleThresholds = styleThresholdsFor(documents, families, { registerMarkers });
 
   return {
     schemaVersion: 2,
@@ -56,7 +57,8 @@ export function buildVoiceProfileV2({ documents }) {
         rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
         evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
       },
-      styleThresholds: styleThresholdsFor(documents, families),
+      styleThresholds,
+      familyDiagnostics: familyCalibrationDiagnostics({ source, families, styleThresholds }),
       minimumDraftSize: {
         words: source.confidence.band === "weak" ? 25 : 35,
         sentences: source.confidence.band === "weak" ? 3 : 4,
@@ -65,11 +67,11 @@ export function buildVoiceProfileV2({ documents }) {
   };
 }
 
-function analyzeFeatureFamilies(documents) {
+function analyzeFeatureFamilies(documents, { registerMarkers } = {}) {
   return {
     rhythm: analyzeRhythm(documents),
     lexical: analyzeLexical(documents),
-    register: analyzeRegister(documents),
+    register: analyzeRegister(documents, registerMarkers ? { markers: registerMarkers } : undefined),
     discourse: analyzeDiscourse(documents),
     rhetoricalShape: analyzeRhetoricalShape(documents),
     evidence: analyzeEvidence(documents),
@@ -77,15 +79,32 @@ function analyzeFeatureFamilies(documents) {
   };
 }
 
-function styleThresholdsFor(documents, fallbackFamilies) {
+function styleThresholdsFor(documents, fallbackFamilies, { registerMarkers } = {}) {
   const fallbackThresholds = defaultStyleThresholds();
   const distancesByFamily = Object.fromEntries(Object.keys(fallbackFamilies).map((family) => [family, []]));
 
   if (documents.length >= 2) {
     for (let index = 0; index < documents.length; index += 1) {
       const referenceDocuments = documents.filter((_, candidateIndex) => candidateIndex !== index);
-      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments);
-      const heldoutFamilies = analyzeFeatureFamilies([documents[index]]);
+      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments, { registerMarkers });
+      const heldoutFamilies = analyzeFeatureFamilies([documents[index]], { registerMarkers });
+      for (const family of Object.keys(fallbackFamilies)) {
+        distancesByFamily[family].push(distanceByFamily(
+          family,
+          referenceFamilies[family].features,
+          heldoutFamilies[family].features,
+        ));
+      }
+    }
+  }
+
+  if (documents.length >= 5) {
+    for (let start = 0; start < documents.length; start += 1) {
+      const heldoutIndexes = new Set([start, (start + 1) % documents.length]);
+      const referenceDocuments = documents.filter((_, index) => !heldoutIndexes.has(index));
+      const heldoutDocuments = documents.filter((_, index) => heldoutIndexes.has(index));
+      const referenceFamilies = analyzeFeatureFamilies(referenceDocuments, { registerMarkers });
+      const heldoutFamilies = analyzeFeatureFamilies(heldoutDocuments, { registerMarkers });
       for (const family of Object.keys(fallbackFamilies)) {
         distancesByFamily[family].push(distanceByFamily(
           family,
@@ -109,7 +128,9 @@ function styleThresholdsFor(documents, fallbackFamilies) {
   }
 
   return {
-    method: "leave-one-out-cosine-delta",
+    method: documents.length >= 5
+      ? "leave-one-out-and-rotating-holdout-cosine-delta"
+      : "leave-one-out-cosine-delta",
     references: STYLOMETRIC_REFERENCES,
     families,
   };
@@ -168,6 +189,100 @@ function sourceSummary(documents) {
     sentenceCount,
     genres: [],
     confidence,
+    quality: sourceQualityFor(documents),
+  };
+}
+
+function sourceQualityFor(documents) {
+  const wordCounts = documents.map((document) => document.wordCount);
+  const sentenceCounts = documents.map((document) => document.sentences.length);
+  const fingerprints = new Map();
+  for (const document of documents) {
+    const fingerprint = documentFingerprint(document);
+    if (!fingerprint) {
+      continue;
+    }
+    fingerprints.set(fingerprint, (fingerprints.get(fingerprint) ?? 0) + 1);
+  }
+  const duplicateGroups = Array.from(fingerprints.values()).filter((count) => count > 1).length;
+  const minWords = minValue(wordCounts);
+  const maxWords = maxValue(wordCounts);
+  const warnings = [];
+  if (duplicateGroups > 0) {
+    warnings.push(`${duplicateGroups} duplicate-looking source group(s) detected; remove repeated drafts before trusting calibration.`);
+  }
+  if (documents.length >= 3 && minWords > 0 && maxWords / minWords >= 5) {
+    warnings.push(`Document length imbalance detected (${minWords}-${maxWords} words); long pieces may dominate the learned profile.`);
+  }
+  if (documents.some((document) => document.wordCount < 80)) {
+    warnings.push("One or more source files are very short; prefer representative long-form pieces.");
+  }
+  return {
+    lengthSpread: {
+      minWords,
+      maxWords,
+      minSentences: minValue(sentenceCounts),
+      maxSentences: maxValue(sentenceCounts),
+    },
+    duplicateGroups,
+    warnings,
+  };
+}
+
+function minValue(values) {
+  return values.length ? Math.min(...values) : 0;
+}
+
+function maxValue(values) {
+  return values.length ? Math.max(...values) : 0;
+}
+
+function documentFingerprint(document) {
+  return String(document.text ?? "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .replace(/[^a-z0-9 ]+/g, "")
+    .trim();
+}
+
+function familyCalibrationDiagnostics({ source, families, styleThresholds }) {
+  return Object.fromEntries(Object.keys(families).map((family) => {
+    const minimumEvidence = minimumEvidenceFor(family, source, families[family]);
+    const threshold = styleThresholds.families[family] ?? {};
+    return [family, {
+      confidence: families[family].confidence,
+      threshold: threshold.threshold ?? 0,
+      observations: threshold.observations ?? 0,
+      stability: threshold.stability ?? 0.45,
+      minimumEvidence,
+      usableForFindings: source.confidence.band !== "weak" &&
+        minimumEvidence.documentsMet &&
+        minimumEvidence.sentencesMet &&
+        minimumEvidence.wordsMet &&
+        (threshold.stability ?? 0.45) >= 0.35,
+    }];
+  }));
+}
+
+function minimumEvidenceFor(family, source, familyData) {
+  const requirements = {
+    rhythm: { documents: 1, sentences: 8, words: 80 },
+    lexical: { documents: 1, sentences: 4, words: 120 },
+    register: { documents: 3, sentences: 8, words: 120 },
+    discourse: { documents: 1, sentences: 12, words: 120 },
+    rhetoricalShape: { documents: 1, sentences: 12, words: 120 },
+    evidence: { documents: 1, sentences: 12, words: 120 },
+    structure: { documents: 3, sentences: 8, words: 120 },
+  }[family] ?? { documents: 1, sentences: 1, words: 1 };
+  const wordCount = familyData.features?.wordCount ?? source.wordCount;
+  const sentenceCount = familyData.features?.sentenceCount ?? source.sentenceCount;
+  return {
+    requiredDocuments: requirements.documents,
+    requiredSentences: requirements.sentences,
+    requiredWords: requirements.words,
+    documentsMet: source.documentCount >= requirements.documents,
+    sentencesMet: sentenceCount >= requirements.sentences,
+    wordsMet: wordCount >= requirements.words,
   };
 }
 
@@ -187,35 +302,139 @@ function confidenceFor(documentCount, sentenceCount, wordCount) {
 function guidanceFor({ source, families }) {
   const primaryRegister = families.register.features.primary.value;
   const evidenceRate = families.evidence.features.evidenceSentenceRate;
-  const sentenceMedian = families.rhythm.features.sentenceWords.median;
-  const opening = families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ");
+  const sentenceWords = families.rhythm.features.sentenceWords;
+  const registerMix = registerMixLabel(families.register.features.scores);
+  const openingPatterns = (families.rhetoricalShape.features.openingMovePatterns || [])
+    .slice(0, 3)
+    .map((item) => item.value)
+    .filter(Boolean);
 
   const draftingRules = [
-    `Keep sentence pacing near the learned median of ${sentenceMedian} words when it fits the draft.`,
-    `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
+    sentenceWords.count > 0
+      ? `Vary sentence length across the corpus band of ${sentenceWords.p25}-${sentenceWords.p75} words (median ${sentenceWords.median}). Mix short and long sentences; do not hold a constant length.`
+      : "Vary sentence length; mix short and long sentences rather than holding a constant cadence.",
+    sentenceWords.stdev > 0
+      ? `Keep sentence-length variation (burstiness) near the corpus standard deviation of about ${sentenceWords.stdev} words; flattening every sentence to the median reads as machine-made.`
+      : "Preserve natural variation in sentence length rather than flattening it to one value.",
+    registerMix
+      ? `Default to the learned register mix (${registerMix}) instead of one fixed genre; let each piece lean differently within it.`
+      : `Use ${primaryRegister} register as the default genre signal unless the piece intentionally changes genre.`,
     evidenceRate > 0.35
       ? "Anchor broad claims with concrete scenes, numbers, quotes, citations, or specific examples."
       : "Do not force evidence density higher than the source corpus supports.",
-    opening
-      ? `Prefer opening moves compatible with: ${opening}.`
-      : "Start from the article's real subject rather than generic positioning.",
+    openingPatterns.length
+      ? `Rotate among the corpus's observed opening shapes (e.g. ${openingPatterns.join("; ")}) rather than reusing one opening every time.`
+      : "Start from the article's real subject rather than generic positioning, and vary openings across pieces.",
   ];
 
   return {
     summary: [
       `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
-      `Primary register signal: ${primaryRegister}.`,
+      `Primary register signal: ${primaryRegister}${registerMix ? ` (mix: ${registerMix})` : ""}.`,
     ],
     draftingRules,
+    formatting: formattingGuidance(families.structure.features),
     avoid: [
       "Do not treat topic vocabulary as proof of voice fit.",
       "Do not claim a draft is or is not the writer's true voice.",
       "Do not invent concrete evidence to satisfy a style finding.",
+      "Do not reuse the same outline, opening, or formatting on every piece; stay inside the learned ranges and vary within them.",
     ],
     examples: [],
   };
 }
 
+function registerMixLabel(scores) {
+  const active = (scores || []).filter((item) => item.score > 0).slice(0, 3);
+  if (active.length < 2) {
+    return "";
+  }
+  return active.map((item) => `${item.value} ${item.score}`).join(", ");
+}
+
+function formattingGuidance(structure) {
+  const rules = [];
+  const headingCount = structure.headingCount || {};
+  if (headingCount.count > 0 && (headingCount.min !== headingCount.max)) {
+    rules.push(`Heading count varies across the corpus (${headingCount.min}-${headingCount.max}); pick a level of sectioning that fits the piece rather than a fixed template.`);
+  }
+  const patterns = (structure.sectionOrderPatterns || []).slice(0, 4).map((item) => item.value).filter(Boolean);
+  if (patterns.length) {
+    rules.push(`Observed section shapes to choose among (do not reuse one skeleton): ${patterns.join(" | ")}.`);
+  }
+  if (typeof structure.listDocumentRate === "number") {
+    rules.push(`Lists appear in about ${Math.round(structure.listDocumentRate * 100)}% of pieces and quotes in about ${Math.round((structure.quoteDocumentRate ?? 0) * 100)}%; use them where they fit, not on every draft.`);
+  }
+  return [
+    "Formatting and document structure are NOT the writer's voice and must not be reproduced as if they were. Voice lives in the Drafting Rules above (rhythm, diction, register, evidence). The items below are formatting habits to deliberately vary: do not justify keeping a repeated tic as \"authentic voice.\"",
+    ...rules,
+    ...antiTemplateGuidance(structure.templateTics),
+    ...paletteGuidance(structure.formattingPalette),
+  ];
+}
+
+const PALETTE_LABELS = {
+  blockquote: "blockquotes",
+  bulletList: "bullet lists",
+  orderedList: "numbered lists",
+  nestedList: "nested lists",
+  subHeading: "sub-headings (h3+)",
+  table: "tables",
+  codeBlock: "code blocks",
+  inlineCode: "inline code",
+  boldInline: "bold emphasis",
+  italicInline: "italic emphasis",
+  link: "links",
+  horizontalRule: "section dividers",
+};
+
+// Markdown offers far more range than the few devices a homogeneous corpus reaches for.
+// Name what the corpus leans on and which devices it underuses, and push the model to
+// broaden the palette where the content genuinely calls for it.
+function paletteGuidance(palette) {
+  if (!palette) {
+    return [];
+  }
+  const leanedOn = Object.keys(palette).filter((device) => palette[device] >= 0.6);
+  const underused = Object.keys(palette).filter((device) => palette[device] <= 0.2);
+  const rules = [];
+  if (leanedOn.length) {
+    rules.push(`The corpus's formatting palette is narrow: it leans on ${labelList(leanedOn)}. Treat that as a habit to widen, not a target to hit.`);
+  }
+  if (underused.length) {
+    rules.push(`Markdown devices the corpus rarely or never uses: ${labelList(underused)}. Reach for these where the content fits (a comparison wants a table, steps want numbered items, a definition wants inline code, an aside wants italics) so pieces do not all share one formatting shape.`);
+  }
+  return rules;
+}
+
+function labelList(devices) {
+  return devices.map((device) => PALETTE_LABELS[device] ?? device).join(", ");
+}
+
+// When the corpus over-relies on a formatting template, faithfully reproducing it is
+// what makes generated pieces look copy-pasted. This guidance is prescriptive (injected
+// to break the habit), not a learned pattern to match — surfaced only when a tic
+// dominates the corpus, so varied corpora are left alone.
+function antiTemplateGuidance(tics) {
+  if (!tics) {
+    return [];
+  }
+  const rules = [];
+  if (tics.singleSentenceParagraphRate >= 0.35) {
+    rules.push(`Watch a strong template tic: about ${Math.round(tics.singleSentenceParagraphRate * 100)}% of corpus paragraphs are a single sentence. This staccato one-line-paragraph cadence is the loudest "copy-paste" tell. Deliberately group related sentences into multi-sentence paragraphs; reserve one-line paragraphs for genuine emphasis.`);
+  }
+  if (tics.titleCaseHeadingRate >= 0.6) {
+    rules.push(`Watch a template tic: about ${Math.round(tics.titleCaseHeadingRate * 100)}% of headings are Title Case. Vary heading style (sentence case, questions, or no headings at all) instead of the same Title-Case section labels every time.`);
+  }
+  if (tics.ledeBlockquoteRate >= 0.5) {
+    rules.push(`Watch a template tic: about ${Math.round(tics.ledeBlockquoteRate * 100)}% of pieces drop a pull-quote (blockquote) into the intro before the first heading. Do not open with an aphoristic blockquote by default; let most pieces earn a quote later or skip it.`);
+  }
+  if (tics.sectionListRate >= 0.45) {
+    rules.push(`Watch a template tic: about ${Math.round(tics.sectionListRate * 100)}% of sections contain a bullet list. Do not put a list in section after section; carry most points in connected prose and reserve lists for genuinely enumerable material.`);
+  }
+  return rules;
+}
+
 function toleranceFor(band, deep, strong, weak) {
   if (band === "deep") {
     return deep;

package/src/v2/prompt.js

@@ -23,9 +23,9 @@ function renderPrompt(profile, format) {
     system: "System writing guidance: Dravoice V2",
   }[format];
   const preface = {
-    agents: "Use this as local, inspectable drafting guidance from the writer's own corpus. It is not an AI detector or a license to imitate a third party.",
-    claude: "Use these project-local voice notes when drafting or reviewing prose for this repository. Treat them as guidance, not identity proof.",
-    system: "Follow these local voice constraints when writing prose. Do not expose private source text or claim authorship identity from them.",
+    agents: "Use this as local guidance that complements AI by preserving reusable, inspectable constraints from the writer's own corpus. It is not an AI detector or a license to imitate a third party.",
+    claude: "Use these project-local voice notes as guidance that complements AI by preserving reusable, inspectable constraints for drafting or reviewing prose. Treat them as guidance, not identity proof.",
+    system: "Follow these local voice constraints as reusable, inspectable guidance for AI-assisted prose. Do not expose private source text or claim authorship identity from them.",
   }[format];
   const lines = [
     header,
@@ -49,6 +49,13 @@ function renderPrompt(profile, format) {
     lines.push(`- ${rule}`);
   }
 
+  if (profile.guidance.formatting && profile.guidance.formatting.length) {
+    lines.push("", "## Formatting: Vary Deliberately (Not Voice)", "");
+    for (const rule of profile.guidance.formatting) {
+      lines.push(`- ${rule}`);
+    }
+  }
+
   lines.push("", "## Avoid", "");
   for (const item of profile.guidance.avoid) {
     lines.push(`- ${item}`);

package/src/v2/review.js

@@ -10,11 +10,11 @@ const REVIEW_MODES = {
     exitOnDrift: false,
   },
   balanced: {
-    findingThresholds: { evidence: 65, rhythm: 55, rhetoricalShape: 50 },
+    findingThresholds: { evidence: 65, rhythm: 55, rhetoricalShape: 50, discourse: 55, lexical: 55, register: 55, structure: 55 },
     exitOnDrift: false,
   },
   strict: {
-    findingThresholds: { evidence: 75, rhythm: 70, rhetoricalShape: 65 },
+    findingThresholds: { evidence: 75, rhythm: 70, rhetoricalShape: 65, discourse: 65, lexical: 65, register: 70, structure: 91 },
     exitOnDrift: true,
   },
 };
@@ -34,6 +34,7 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
     draftDocument.wordCount < sourceProfile.calibration.minimumDraftSize.words ||
     draftDocument.sentences.length < sourceProfile.calibration.minimumDraftSize.sentences
   ) {
+    const familyConfidence = familyConfidenceFor(sourceProfile, {});
     return {
       schemaVersion: 2,
       file: displayPath(filePath, cwd),
@@ -41,6 +42,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
         mode: reviewMode,
         fit: { band: "insufficient-evidence", distance: 0 },
         familyScores: {},
+        familyConfidence,
+        suppressedFindings: suppressedFindingsFor(sourceProfile, familyConfidence),
         corpusConfidence: sourceProfile.source.confidence,
       },
       findings: [],
@@ -51,7 +54,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
   const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
   const familyScores = Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.score]));
   const distance = styleDistanceFromDiagnostics(familyDiagnostics);
-  const findings = reviewFindings(sourceProfile, draftProfile, familyScores, reviewMode);
+  const familyConfidence = familyConfidenceFor(sourceProfile, familyDiagnostics);
+  const findings = reviewFindings(sourceProfile, draftProfile, familyScores, reviewMode, familyConfidence);
   const fit = {
     band: fitBand(distance, findings, familyDiagnostics),
     distance,
@@ -64,6 +68,8 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
       mode: reviewMode,
       fit,
       familyScores,
+      familyConfidence,
+      suppressedFindings: suppressedFindingsFor(sourceProfile, familyConfidence),
       familyDistances: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.distance])),
       familyDrift: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.drift])),
       thresholds: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.threshold])),
@@ -76,71 +82,175 @@ export function reviewVoiceDraftV2({ file, voice, cwd = process.cwd(), mode = "b
 
 export function renderVoiceReviewV2(result) {
   const lines = [
-    "Voice rewrite notes, not AI detection.",
+    "Voice review notes, not AI detection.",
     "",
     result.file,
-    `Voice fit: ${capitalize(result.summary.fit.band)} (${result.summary.fit.distance} distance)`,
+    `Fit: ${capitalize(result.summary.fit.band)} (${result.summary.fit.distance} style distance)`,
     `Corpus confidence: ${capitalize(result.summary.corpusConfidence.band)} - ${result.summary.corpusConfidence.message}`,
     "Family scores:",
   ];
 
   for (const [family, score] of Object.entries(result.summary.familyScores)) {
-    lines.push(`- ${family}: ${score}`);
+    lines.push(`- ${familyLabel(family)}: ${score}`);
   }
 
   lines.push("");
   if (result.findings.length === 0) {
-    lines.push("No high-confidence V2 voice drift findings.");
+    lines.push("No high-confidence voice drift findings.");
+    appendSuppressedFindings(lines, result.summary.suppressedFindings);
     lines.push("");
     return lines.join("\n");
   }
 
   lines.push("Start here:");
-  for (const finding of result.findings.slice(0, 6)) {
-    lines.push(`${finding.priority} ${finding.family} ${finding.id}`);
-    lines.push(`Why flagged: ${finding.why}`);
-    lines.push(`Revise by: ${finding.action}`);
+  result.findings.slice(0, 6).forEach((finding, index) => {
+    lines.push(`${index + 1}. ${priorityLabel(finding.priority)} ${familyLabel(finding.family)}`);
+    if (finding.confidence) {
+      lines.push(`Confidence: ${capitalize(finding.confidence.band)}; stability ${finding.confidence.stability}`);
+    }
+    lines.push(`Why: ${finding.why}`);
+    lines.push(`Do this: ${finding.action}`);
     lines.push("");
-  }
+  });
+  appendSuppressedFindings(lines, result.summary.suppressedFindings);
   return lines.join("\n");
 }
 
-function reviewFindings(source, draft, scores, mode) {
+function reviewFindings(source, draft, scores, mode, familyConfidence) {
   const modeConfig = REVIEW_MODES[mode];
   if (source.source?.confidence?.band === "weak" || !modeConfig.findingThresholds) {
     return [];
   }
   const findings = [];
-  if (scores.evidence < modeConfig.findingThresholds.evidence) {
+  if (shouldFlag("evidence", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.evidence-drift",
       family: "evidence",
       priority: "review",
+      confidence: familyConfidence.evidence,
       why: `Source evidence sentence rate is ${source.families.evidence.features.evidenceSentenceRate}; draft rate is ${draft.families.evidence.features.evidenceSentenceRate}.`,
       action: "Add concrete support before broad claims: a scene, quote, number, citation, URL, sensory detail, or specific example.",
     });
   }
-  if (scores.rhythm < modeConfig.findingThresholds.rhythm) {
+  if (shouldFlag("rhythm", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.rhythm-drift",
       family: "rhythm",
       priority: "consider",
+      confidence: familyConfidence.rhythm,
       why: `Source median sentence/paragraph length is ${source.families.rhythm.features.sentenceWords.median}/${source.families.rhythm.features.paragraphWords.median}; draft is ${draft.families.rhythm.features.sentenceWords.median}/${draft.families.rhythm.features.paragraphWords.median}.`,
       action: "Revise sentence and paragraph pacing toward the learned range.",
     });
   }
-  if (scores.rhetoricalShape < modeConfig.findingThresholds.rhetoricalShape) {
+  if (shouldFlag("rhetoricalShape", scores, modeConfig, familyConfidence)) {
     findings.push({
       id: "v2.shape-drift",
       family: "rhetoricalShape",
       priority: "consider",
+      confidence: familyConfidence.rhetoricalShape,
       why: `Source opening shape is ${source.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ")}; draft opening shape is ${draft.families.rhetoricalShape.features.openingMoves.slice(0, 3).join(" -> ")}.`,
       action: "Rework the opening so it uses a compatible scene, claim, contrast, reflection, or example sequence.",
     });
   }
+  if (shouldFlag("discourse", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.discourse-drift",
+      family: "discourse",
+      priority: "consider",
+      confidence: familyConfidence.discourse,
+      why: `Source transition rates are ${rateMapLabel(source.families.discourse.features.transitionRates)}; draft rates are ${rateMapLabel(draft.families.discourse.features.transitionRates)}.`,
+      action: "Revise repeated sentence turns, callbacks, and transitions so the draft does not lean on a different discourse pattern.",
+    });
+  }
+  if (shouldFlag("lexical", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.lexical-drift",
+      family: "lexical",
+      priority: "consider",
+      confidence: familyConfidence.lexical,
+      why: `Function-word, masked character, punctuation, or boundary-token habits drift from the calibrated source profile.`,
+      action: "Revise diction and punctuation where it improves the article; do not stuff source topic words or add artificial imperfections.",
+    });
+  }
+  if (shouldFlag("register", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.register-drift",
+      family: "register",
+      priority: "consider",
+      confidence: familyConfidence.register,
+      why: `Source primary register is ${source.families.register.features.primary.value}; draft primary register is ${draft.families.register.features.primary.value}.`,
+      action: "Bring the stance closer to the learned genre mix while preserving the draft's real subject and audience.",
+    });
+  }
+  if (shouldFlag("structure", scores, modeConfig, familyConfidence)) {
+    findings.push({
+      id: "v2.structure-drift",
+      family: "structure",
+      priority: "consider",
+      confidence: familyConfidence.structure,
+      why: `Source heading/list/quote and section-size patterns differ from the draft's document structure.`,
+      action: "Adjust section shape, opening order, list use, or quote placement only where the article benefits from that structure.",
+    });
+  }
   return findings;
 }
 
+function shouldFlag(family, scores, modeConfig, familyConfidence) {
+  return familyConfidence[family]?.usableForFindings &&
+    Number.isFinite(scores[family]) &&
+    scores[family] < modeConfig.findingThresholds[family];
+}
+
+function familyConfidenceFor(sourceProfile, familyDiagnostics) {
+  const profileDiagnostics = sourceProfile.calibration?.familyDiagnostics ?? {};
+  return Object.fromEntries(Object.keys(sourceProfile.families ?? {}).map((family) => {
+    const profile = profileDiagnostics[family] ?? {};
+    const runtime = familyDiagnostics[family] ?? {};
+    return [family, {
+      band: sourceProfile.families[family]?.confidence ?? "low",
+      stability: runtime.stability ?? profile.stability ?? 0.45,
+      observations: profile.observations ?? runtime.observations ?? 0,
+      usableForFindings: profile.usableForFindings ?? sourceProfile.source?.confidence?.band !== "weak",
+      minimumEvidence: profile.minimumEvidence ?? null,
+    }];
+  }));
+}
+
+function suppressedFindingsFor(sourceProfile, familyConfidence) {
+  return Object.entries(familyConfidence)
+    .filter(([, confidence]) => !confidence.usableForFindings)
+    .map(([family, confidence]) => ({
+      family,
+      reason: suppressedReasonFor(sourceProfile, confidence),
+    }));
+}
+
+function suppressedReasonFor(sourceProfile, confidence) {
+  if (sourceProfile.source?.confidence?.band === "weak") {
+    return "weak corpus confidence; add more representative source documents before trusting this family.";
+  }
+  const minimum = confidence.minimumEvidence;
+  if (minimum && (!minimum.documentsMet || !minimum.sentencesMet || !minimum.wordsMet)) {
+    return `minimum evidence not met; requires ${minimum.requiredDocuments} document(s), ${minimum.requiredSentences} sentence(s), and ${minimum.requiredWords} word(s).`;
+  }
+  return "calibration stability is too low for a high-confidence finding.";
+}
+
+function appendSuppressedFindings(lines, suppressedFindings = []) {
+  if (!suppressedFindings.length) {
+    return;
+  }
+  lines.push("");
+  lines.push("Suppressed findings:");
+  suppressedFindings.slice(0, 6).forEach((item) => {
+    lines.push(`- ${familyLabel(item.family)}: ${item.reason}`);
+  });
+}
+
+function rateMapLabel(value = {}) {
+  return Object.entries(value).map(([key, rate]) => `${key}:${rate}`).join(", ") || "none";
+}
+
 function normalizeReviewMode(mode) {
   const normalized = String(mode ?? "balanced").toLowerCase();
   if (!Object.hasOwn(REVIEW_MODES, normalized)) {
@@ -175,3 +285,19 @@ function resolvePath(cwd, value) {
 function capitalize(value) {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
+
+function familyLabel(family) {
+  return {
+    evidence: "Evidence",
+    rhythm: "Rhythm",
+    rhetoricalShape: "Rhetorical shape",
+    discourse: "Discourse",
+    lexical: "Lexical style",
+    register: "Register",
+    structure: "Structure",
+  }[family] ?? capitalize(family);
+}
+
+function priorityLabel(priority) {
+  return priority === "review" ? "Review" : "Consider";
+}