dravoice 0.1.2 → 0.1.3

package/src/v2/revise-plan.js

@@ -1,433 +1,437 @@
-import fs from "node:fs";
-import path from "node:path";
-import { evidenceTypes, isAbstractClaim } from "./analyzers/evidence.js";
-import { transitionLabel } from "./analyzers/discourse.js";
-import { moveFor } from "./analyzers/rhetorical-shape.js";
-import { parseDocument } from "./document-model.js";
-import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
-import { clampScore, round } from "./text-utils.js";
-import {
-  STYLOMETRIC_REFERENCES,
-  familyDiagnosticsFor,
-  familyWeight,
-  styleDistanceFromDiagnostics,
-} from "./stylometry.js";
-
-const MAX_ACTIONS = 8;
-
-const EDITABILITY = {
-  evidence: 1.00,
-  rhetoricalShape: 0.90,
-  rhythm: 0.80,
-  discourse: 0.75,
-  lexical: 0.55,
-  register: 0.50,
-  structure: 0.60,
-};
-
-export function revisePlanDraftV2({ file, voice, cwd = process.cwd(), maxActions = MAX_ACTIONS }) {
-  const sourceProfile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
-  const filePath = path.resolve(file);
-  const draftDocument = parseDocument({
-    filePath,
-    rootDir: cwd,
-    contents: fs.readFileSync(filePath, "utf8"),
-  });
-  const draftProfile = buildVoiceProfileV2({ documents: [draftDocument] });
-  const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
-  const rollingWindows = rollingWindowsFor({ sourceProfile, draftDocument });
-  const actions = rankedActions({
-    sourceProfile,
-    draftDocument,
-    familyDiagnostics,
-    rollingWindows,
-    maxActions,
-  });
-
-  return {
-    schemaVersion: 2,
-    generatedBy: "dravoice-v2-revise-plan",
-    file: displayPath(filePath, cwd),
-    method: {
-      name: "calibrated-stylometric-revision-plan",
-      references: STYLOMETRIC_REFERENCES,
-      caution: "Revision planning only; not AI detection and not proof of authorship.",
-    },
-    summary: {
-      corpusConfidence: sourceProfile.source.confidence,
-      distance: styleDistanceFromDiagnostics(familyDiagnostics),
-      familyScores: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.score])),
-      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])),
-      rollingWindows,
-    },
-    actions,
-  };
-}
-
-export function renderRevisePlanV2(plan) {
-  const lines = [
-    "# Revision Plan",
-    "",
-    "Voice revision guidance, not AI detection.",
-    `Method: calibrated stylometric distance using Burrows Delta, Cosine Delta, function-word stylometry, and discourse features.`,
-    "",
-    plan.file,
-    `Corpus confidence: ${capitalize(plan.summary.corpusConfidence.band)} - ${plan.summary.corpusConfidence.message}`,
-    `Style distance: ${plan.summary.distance}`,
-    "Family scores:",
-  ];
-
-  for (const [family, score] of Object.entries(plan.summary.familyScores)) {
-    const drift = plan.summary.familyDrift[family];
-    lines.push(`- ${family}: ${score} (drift ${drift})`);
-  }
-
-  lines.push("");
-  if (plan.actions.length === 0) {
-    lines.push("No calibrated revision actions exceeded the writer's normal style variance.");
-    lines.push("");
-    return lines.join("\n");
-  }
-
-  lines.push("Start here:");
-  plan.actions.forEach((action, index) => {
-    lines.push(`${index + 1}. ${action.priority} ${action.family} ${action.id}`);
-    lines.push(`   Unit: ${action.unit.type} at line ${action.unit.line}`);
-    lines.push(`   Score: ${action.actionScore}`);
-    lines.push(`   Why flagged: ${action.why}`);
-    lines.push(`   Revise by: ${action.reviseBy}`);
-  });
-  lines.push("");
-  return lines.join("\n");
-}
-
-function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, rollingWindows, maxActions }) {
-  const confidence = confidenceWeight(sourceProfile.source.confidence.band);
-  const actions = [
-    ...evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
-    ...rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
-    ...shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
-    ...discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
-    ...rollingWindowActions({ rollingWindows, confidence }),
-    ...documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
-  ].filter((action) => action.actionScore > 0);
-
-  return actions
-    .sort((left, right) => right.actionScore - left.actionScore || left.id.localeCompare(right.id))
-    .slice(0, maxActions)
-    .map((action, index) => ({ ...action, rank: index + 1 }));
-}
-
-function evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
-  const family = "evidence";
-  const drift = familyDiagnostics[family]?.drift ?? 0;
-  if (drift <= 0) {
-    return [];
-  }
-  const sourceRate = sourceProfile.families.evidence.features.evidenceSentenceRate;
-  return draftDocument.sentences.flatMap((sentence, index) => {
-    const types = evidenceTypes(sentence.text);
-    const claim = isAbstractClaim(sentence.text);
-    const localMismatch = claim && types.length === 0
-      ? 1
-      : types.length === 0 && sourceRate >= 0.25
-        ? 0.65
-        : 0;
-    if (localMismatch <= 0) {
-      return [];
-    }
-    return [makeAction({
-      family,
-      ordinal: index + 1,
-      priority: claim ? "review" : "consider",
-      unit: { type: "sentence", line: sentence.line },
-      confidence,
-      drift,
-      stability: familyDiagnostics[family]?.stability,
-      localMismatch,
-      why: "This sentence carries a broad claim pattern without the concrete support rate learned from the source corpus.",
-      reviseBy: "Add concrete support: a scene, quote, number, date, citation, URL, sensory detail, or specific example the writer can verify.",
-    })];
-  });
-}
-
-function rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
-  const family = "rhythm";
-  const drift = familyDiagnostics[family]?.drift ?? 0;
-  if (drift <= 0) {
-    return [];
-  }
-  const source = sourceProfile.families.rhythm.features.sentenceWords;
-  return draftDocument.sentences.flatMap((sentence, index) => {
-    const wordCount = sentence.tokens.length;
-    const nearestBound = wordCount < source.p25 ? source.p25 : wordCount > source.p75 ? source.p75 : wordCount;
-    const localMismatch = Math.min(1, Math.abs(wordCount - nearestBound) / Math.max(1, source.median));
-    if (localMismatch <= 0) {
-      return [];
-    }
-    const direction = wordCount > source.p75 ? "longer" : "shorter";
-    return [makeAction({
-      family,
-      ordinal: index + 1,
-      priority: "consider",
-      unit: { type: "sentence", line: sentence.line },
-      confidence,
-      drift,
-      stability: familyDiagnostics[family]?.stability,
-      localMismatch,
-      why: `This sentence is ${direction} than the learned sentence-length band (${source.p25}-${source.p75} words).`,
-      reviseBy: "Adjust sentence pacing toward the learned range by splitting, tightening, or pairing it with a deliberately shorter sentence.",
-    })];
-  });
-}
-
-function shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
-  const family = "rhetoricalShape";
-  const drift = familyDiagnostics[family]?.drift ?? 0;
-  if (drift <= 0 || draftDocument.sentences.length === 0) {
-    return [];
-  }
-  const sourceOpening = sourceProfile.families.rhetoricalShape.features.openingMoves.slice(0, 3);
-  const draftOpening = draftDocument.sentences.slice(0, 3).map((sentence) => moveFor(sentence.text));
-  const mismatches = draftOpening.filter((move, index) => move !== sourceOpening[index]).length;
-  const localMismatch = mismatches / Math.max(1, Math.min(3, draftOpening.length));
-  if (localMismatch <= 0) {
-    return [];
-  }
-  return [makeAction({
-    family,
-    ordinal: 1,
-    priority: "consider",
-    unit: { type: "opening", line: draftDocument.sentences[0].line },
-    confidence,
-    drift,
-    stability: familyDiagnostics[family]?.stability,
-    localMismatch,
-    why: `Draft opening moves (${draftOpening.join(" -> ")}) drift from the learned opening pattern (${sourceOpening.join(" -> ")}).`,
-    reviseBy: "Rework the opening toward a compatible scene, claim, contrast, reflection, or evidence sequence without inventing new facts.",
-  })];
-}
-
-function discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
-  const family = "discourse";
-  const drift = familyDiagnostics[family]?.drift ?? 0;
-  if (drift <= 0) {
-    return [];
-  }
-  const sourceTransitions = sourceProfile.families.discourse.features.transitionRates;
-  return draftDocument.sentences.flatMap((sentence, index) => {
-    const label = transitionLabel(sentence.text);
-    if (label === "plain") {
-      return [];
-    }
-    const sourceRate = sourceTransitions[label] ?? 0;
-    const draftRate = draftDocument.sentences.filter((candidate) => transitionLabel(candidate.text) === label).length / Math.max(1, draftDocument.sentences.length);
-    const localMismatch = Math.max(0, draftRate - sourceRate);
-    if (localMismatch <= 0.1) {
-      return [];
-    }
-    return [makeAction({
-      family,
-      ordinal: index + 1,
-      priority: "consider",
-      unit: { type: "sentence", line: sentence.line },
-      confidence,
-      drift,
-      stability: familyDiagnostics[family]?.stability,
-      localMismatch: Math.min(1, localMismatch),
-      why: `The draft overuses ${label} transitions compared with the source corpus.`,
-      reviseBy: "Vary the sentence turn: replace a repeated transition with a callback, concrete example, or direct continuation where it fits.",
-    })];
-  });
-}
-
-function documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
-  const result = [];
-  for (const family of ["lexical", "register", "structure"]) {
-    const drift = familyDiagnostics[family]?.drift ?? 0;
-    if (drift <= 0) {
-      continue;
-    }
-    result.push(makeAction({
-      family,
-      ordinal: 1,
-      priority: "consider",
-      unit: { type: "document", line: draftDocument.sentences[0]?.line ?? 1 },
-      confidence,
-      drift,
-      stability: familyDiagnostics[family]?.stability,
-      localMismatch: 0.7,
-      why: documentLevelWhy(sourceProfile, family),
-      reviseBy: documentLevelReviseBy(family),
-    }));
-  }
-  return result;
-}
-
-function documentLevelWhy(sourceProfile, family) {
-  if (family === "lexical") {
-    return "Function words, character trigrams, punctuation, or word-length habits drift from the calibrated source profile.";
-  }
-  if (family === "register") {
-    return `The draft register differs from the learned primary register (${sourceProfile.families.register.features.primary.value}).`;
-  }
-  return "The document-level opening structure drifts from the source corpus.";
-}
-
-function documentLevelReviseBy(family) {
-  if (family === "lexical") {
-    return "Revise diction and punctuation only where it improves the article; avoid topic-word stuffing or random imperfections.";
-  }
-  if (family === "register") {
-    return "Bring the paragraph stance closer to the learned genre mix without pretending to be someone else.";
-  }
-  return "Reorder the first section so the piece starts with a structure the source corpus actually uses.";
-}
-
-function rollingWindowsFor({ sourceProfile, draftDocument }) {
-  const sentences = draftDocument.sentences;
-  if (sentences.length < 5) {
-    return [];
-  }
-  const windowSize = sentences.length < 8 ? 3 : 4;
-  const windowStarts = rollingWindowStarts(sentences.length, windowSize, 2);
-  const result = [];
-  for (const start of windowStarts) {
-    const windowSentences = sentences.slice(start, start + windowSize);
-    const windowProfile = buildVoiceProfileV2({ documents: [documentForSentences(draftDocument, windowSentences, start)] });
-    const diagnostics = familyDiagnosticsFor(sourceProfile, windowProfile);
-    const ranked = ["evidence", "rhythm", "discourse", "rhetoricalShape", "lexical"]
-      .map((family) => ({ family, ...diagnostics[family] }))
-      .sort((left, right) => right.drift - left.drift || (100 - right.score) - (100 - left.score));
-    const best = ranked[0];
-    if (best?.drift > 0) {
-      result.push({
-        family: best.family,
-        startSentence: start + 1,
-        endSentence: start + windowSentences.length,
-        startLine: windowSentences[0].line,
-        endLine: windowSentences.at(-1).line,
-        distance: best.distance,
-        drift: best.drift,
-        score: best.score,
-        threshold: best.threshold,
-        stability: best.stability,
-      });
-    }
-  }
-  return result
-    .sort((left, right) => right.drift - left.drift || left.startLine - right.startLine)
-    .slice(0, 4);
-}
-
-function rollingWindowStarts(sentenceCount, windowSize, stride) {
-  const starts = [];
-  for (let start = 0; start <= sentenceCount - windowSize; start += stride) {
-    starts.push(start);
-  }
-  const finalStart = Math.max(0, sentenceCount - windowSize);
-  if (!starts.includes(finalStart)) {
-    starts.push(finalStart);
-  }
-  return starts;
-}
-
-function documentForSentences(draftDocument, sentences, windowIndex) {
-  const text = sentences.map((sentence) => sentence.text).join(" ");
-  const block = {
-    type: "paragraph",
-    line: sentences[0]?.line ?? 1,
-    heading: null,
-    headingId: null,
-    headingDepth: 0,
-    lines: [text],
-  };
-  return {
-    file: `${draftDocument.file ?? "draft"}#window-${windowIndex + 1}`,
-    path: draftDocument.path,
-    headings: [],
-    sections: [{ heading: null, blocks: [block] }],
-    blocks: [block],
-    paragraphs: [{
-      type: "paragraph",
-      line: block.line,
-      heading: null,
-      headingId: null,
-      text,
-    }],
-    sentences,
-    wordCount: sentences.reduce((sum, sentence) => sum + sentence.tokens.length, 0),
-    text,
-  };
-}
-
-function rollingWindowActions({ rollingWindows, confidence }) {
-  return rollingWindows.map((window, index) => makeAction({
-    family: window.family,
-    ordinal: `window-${index + 1}`,
-    priority: window.family === "evidence" ? "review" : "consider",
-    unit: { type: "window", line: window.startLine, endLine: window.endLine },
-    confidence,
-    drift: window.drift,
-    stability: window.stability,
-    localMismatch: Math.min(1, window.drift / Math.max(1, window.drift + 0.5)),
-    why: `Sentences ${window.startSentence}-${window.endSentence} show localized ${window.family} drift beyond the writer's calibrated range.`,
-    reviseBy: rollingWindowReviseBy(window.family),
-  }));
-}
-
-function rollingWindowReviseBy(family) {
-  if (family === "evidence") {
-    return "Add or move concrete support into this local passage, or narrow the unsupported claims in the same window.";
-  }
-  if (family === "rhythm") {
-    return "Revise this passage's sentence and paragraph pacing before changing the whole draft.";
-  }
-  if (family === "discourse") {
-    return "Vary the local sentence turns, callbacks, and transitions in this passage.";
-  }
-  if (family === "rhetoricalShape") {
-    return "Adjust this passage's move sequence so the local claim, turn, evidence, and implication pattern is less abrupt.";
-  }
-  return "Revise this local passage for style fit before making document-wide lexical changes.";
-}
-
-function makeAction({ family, ordinal, priority, unit, confidence, drift, stability = 0.7, localMismatch, why, reviseBy }) {
-  return {
-    id: `v2.revise-plan.${family}.${ordinal}`,
-    family,
-    priority,
-    unit,
-    actionScore: clampScore(100 * confidence * familyWeight(family) * (EDITABILITY[family] ?? 0.6) * Math.max(0.35, stability) * drift * localMismatch),
-    localMismatch: round(localMismatch, 3),
-    why,
-    reviseBy,
-  };
-}
-
-function confidenceWeight(band) {
-  if (band === "deep") {
-    return 1;
-  }
-  if (band === "strong") {
-    return 0.9;
-  }
-  if (band === "usable") {
-    return 0.75;
-  }
-  return 0.45;
-}
-
-function displayPath(filePath, cwd) {
-  const relative = path.relative(cwd, filePath);
-  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
-    return relative.split(path.sep).join("/");
-  }
-  return filePath.split(path.sep).join("/");
-}
-
-function capitalize(value) {
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}
+import path from "node:path";
+import { evidenceTypes, isAbstractClaim } from "./analyzers/evidence.js";
+import { transitionLabel } from "./analyzers/discourse.js";
+import { moveFor } from "./analyzers/rhetorical-shape.js";
+import { parseDocument } from "./document-model.js";
+import { readUtf8FileBounded } from "./io-utils.js";
+import { buildVoiceProfileV2, loadVoicePackV2 } from "./profile.js";
+import { clampScore, round } from "./text-utils.js";
+import {
+  STYLOMETRIC_REFERENCES,
+  familyDiagnosticsFor,
+  familyWeight,
+  styleDistanceFromDiagnostics,
+} from "./stylometry.js";
+
+const MAX_ACTIONS = 8;
+
+const EDITABILITY = {
+  evidence: 1.00,
+  rhetoricalShape: 0.90,
+  rhythm: 0.80,
+  discourse: 0.75,
+  lexical: 0.55,
+  register: 0.50,
+  structure: 0.60,
+};
+
+export function revisePlanDraftV2({ file, voice, cwd = process.cwd(), maxActions = MAX_ACTIONS }) {
+  const sourceProfile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
+  const filePath = resolvePath(cwd, file);
+  const draftDocument = parseDocument({
+    filePath,
+    rootDir: cwd,
+    contents: readUtf8FileBounded(filePath, { label: "Draft file", maxBytes: 2 * 1024 * 1024 }),
+  });
+  const draftProfile = buildVoiceProfileV2({ documents: [draftDocument] });
+  const familyDiagnostics = familyDiagnosticsFor(sourceProfile, draftProfile);
+  const rollingWindows = rollingWindowsFor({ sourceProfile, draftDocument });
+  const actions = rankedActions({
+    sourceProfile,
+    draftDocument,
+    familyDiagnostics,
+    rollingWindows,
+    maxActions,
+  });
+
+  return {
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2-revise-plan",
+    file: displayPath(filePath, cwd),
+    method: {
+      name: "calibrated-stylometric-revision-plan",
+      references: STYLOMETRIC_REFERENCES,
+      caution: "Revision planning only; not AI detection and not proof of authorship.",
+    },
+    summary: {
+      corpusConfidence: sourceProfile.source.confidence,
+      distance: styleDistanceFromDiagnostics(familyDiagnostics),
+      familyScores: Object.fromEntries(Object.entries(familyDiagnostics).map(([family, item]) => [family, item.score])),
+      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])),
+      rollingWindows,
+    },
+    actions,
+  };
+}
+
+export function renderRevisePlanV2(plan) {
+  const lines = [
+    "# Revision Plan",
+    "",
+    "Voice revision guidance, not AI detection.",
+    `Method: calibrated stylometric distance using Burrows Delta, Cosine Delta, function-word stylometry, and discourse features.`,
+    "",
+    plan.file,
+    `Corpus confidence: ${capitalize(plan.summary.corpusConfidence.band)} - ${plan.summary.corpusConfidence.message}`,
+    `Style distance: ${plan.summary.distance}`,
+    "Family scores:",
+  ];
+
+  for (const [family, score] of Object.entries(plan.summary.familyScores)) {
+    const drift = plan.summary.familyDrift[family];
+    lines.push(`- ${family}: ${score} (drift ${drift})`);
+  }
+
+  lines.push("");
+  if (plan.actions.length === 0) {
+    lines.push("No calibrated revision actions exceeded the writer's normal style variance.");
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  lines.push("Start here:");
+  plan.actions.forEach((action, index) => {
+    lines.push(`${index + 1}. ${action.priority} ${action.family} ${action.id}`);
+    lines.push(`   Unit: ${action.unit.type} at line ${action.unit.line}`);
+    lines.push(`   Score: ${action.actionScore}`);
+    lines.push(`   Why flagged: ${action.why}`);
+    lines.push(`   Revise by: ${action.reviseBy}`);
+  });
+  lines.push("");
+  return lines.join("\n");
+}
+
+function rankedActions({ sourceProfile, draftDocument, familyDiagnostics, rollingWindows, maxActions }) {
+  const confidence = confidenceWeight(sourceProfile.source.confidence.band);
+  const actions = [
+    ...evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+    ...rollingWindowActions({ rollingWindows, confidence }),
+    ...documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }),
+  ].filter((action) => action.actionScore > 0);
+
+  return actions
+    .sort((left, right) => right.actionScore - left.actionScore || left.id.localeCompare(right.id))
+    .slice(0, maxActions)
+    .map((action, index) => ({ ...action, rank: index + 1 }));
+}
+
+function evidenceActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "evidence";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const sourceRate = sourceProfile.families.evidence.features.evidenceSentenceRate;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const types = evidenceTypes(sentence.text);
+    const claim = isAbstractClaim(sentence.text);
+    const localMismatch = claim && types.length === 0
+      ? 1
+      : types.length === 0 && sourceRate >= 0.25
+        ? 0.65
+        : 0;
+    if (localMismatch <= 0) {
+      return [];
+    }
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: claim ? "review" : "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      stability: familyDiagnostics[family]?.stability,
+      localMismatch,
+      why: "This sentence carries a broad claim pattern without the concrete support rate learned from the source corpus.",
+      reviseBy: "Add concrete support: a scene, quote, number, date, citation, URL, sensory detail, or specific example the writer can verify.",
+    })];
+  });
+}
+
+function rhythmActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "rhythm";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const source = sourceProfile.families.rhythm.features.sentenceWords;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const wordCount = sentence.tokens.length;
+    const nearestBound = wordCount < source.p25 ? source.p25 : wordCount > source.p75 ? source.p75 : wordCount;
+    const localMismatch = Math.min(1, Math.abs(wordCount - nearestBound) / Math.max(1, source.median));
+    if (localMismatch <= 0) {
+      return [];
+    }
+    const direction = wordCount > source.p75 ? "longer" : "shorter";
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      stability: familyDiagnostics[family]?.stability,
+      localMismatch,
+      why: `This sentence is ${direction} than the learned sentence-length band (${source.p25}-${source.p75} words).`,
+      reviseBy: "Adjust sentence pacing toward the learned range by splitting, tightening, or pairing it with a deliberately shorter sentence.",
+    })];
+  });
+}
+
+function shapeActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "rhetoricalShape";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0 || draftDocument.sentences.length === 0) {
+    return [];
+  }
+  const sourceOpening = sourceProfile.families.rhetoricalShape.features.openingMoves.slice(0, 3);
+  const draftOpening = draftDocument.sentences.slice(0, 3).map((sentence) => moveFor(sentence.text));
+  const mismatches = draftOpening.filter((move, index) => move !== sourceOpening[index]).length;
+  const localMismatch = mismatches / Math.max(1, Math.min(3, draftOpening.length));
+  if (localMismatch <= 0) {
+    return [];
+  }
+  return [makeAction({
+    family,
+    ordinal: 1,
+    priority: "consider",
+    unit: { type: "opening", line: draftDocument.sentences[0].line },
+    confidence,
+    drift,
+    stability: familyDiagnostics[family]?.stability,
+    localMismatch,
+    why: `Draft opening moves (${draftOpening.join(" -> ")}) drift from the learned opening pattern (${sourceOpening.join(" -> ")}).`,
+    reviseBy: "Rework the opening toward a compatible scene, claim, contrast, reflection, or evidence sequence without inventing new facts.",
+  })];
+}
+
+function discourseActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const family = "discourse";
+  const drift = familyDiagnostics[family]?.drift ?? 0;
+  if (drift <= 0) {
+    return [];
+  }
+  const sourceTransitions = sourceProfile.families.discourse.features.transitionRates;
+  return draftDocument.sentences.flatMap((sentence, index) => {
+    const label = transitionLabel(sentence.text);
+    if (label === "plain") {
+      return [];
+    }
+    const sourceRate = sourceTransitions[label] ?? 0;
+    const draftRate = draftDocument.sentences.filter((candidate) => transitionLabel(candidate.text) === label).length / Math.max(1, draftDocument.sentences.length);
+    const localMismatch = Math.max(0, draftRate - sourceRate);
+    if (localMismatch <= 0.1) {
+      return [];
+    }
+    return [makeAction({
+      family,
+      ordinal: index + 1,
+      priority: "consider",
+      unit: { type: "sentence", line: sentence.line },
+      confidence,
+      drift,
+      stability: familyDiagnostics[family]?.stability,
+      localMismatch: Math.min(1, localMismatch),
+      why: `The draft overuses ${label} transitions compared with the source corpus.`,
+      reviseBy: "Vary the sentence turn: replace a repeated transition with a callback, concrete example, or direct continuation where it fits.",
+    })];
+  });
+}
+
+function documentLevelActions({ sourceProfile, draftDocument, familyDiagnostics, confidence }) {
+  const result = [];
+  for (const family of ["lexical", "register", "structure"]) {
+    const drift = familyDiagnostics[family]?.drift ?? 0;
+    if (drift <= 0) {
+      continue;
+    }
+    result.push(makeAction({
+      family,
+      ordinal: 1,
+      priority: "consider",
+      unit: { type: "document", line: draftDocument.sentences[0]?.line ?? 1 },
+      confidence,
+      drift,
+      stability: familyDiagnostics[family]?.stability,
+      localMismatch: 0.7,
+      why: documentLevelWhy(sourceProfile, family),
+      reviseBy: documentLevelReviseBy(family),
+    }));
+  }
+  return result;
+}
+
+function documentLevelWhy(sourceProfile, family) {
+  if (family === "lexical") {
+    return "Function words, character trigrams, punctuation, or word-length habits drift from the calibrated source profile.";
+  }
+  if (family === "register") {
+    return `The draft register differs from the learned primary register (${sourceProfile.families.register.features.primary.value}).`;
+  }
+  return "The document-level opening structure drifts from the source corpus.";
+}
+
+function documentLevelReviseBy(family) {
+  if (family === "lexical") {
+    return "Revise diction and punctuation only where it improves the article; avoid topic-word stuffing or random imperfections.";
+  }
+  if (family === "register") {
+    return "Bring the paragraph stance closer to the learned genre mix without pretending to be someone else.";
+  }
+  return "Reorder the first section so the piece starts with a structure the source corpus actually uses.";
+}
+
+function rollingWindowsFor({ sourceProfile, draftDocument }) {
+  const sentences = draftDocument.sentences;
+  if (sentences.length < 5) {
+    return [];
+  }
+  const windowSize = sentences.length < 8 ? 3 : 4;
+  const windowStarts = rollingWindowStarts(sentences.length, windowSize, 2);
+  const result = [];
+  for (const start of windowStarts) {
+    const windowSentences = sentences.slice(start, start + windowSize);
+    const windowProfile = buildVoiceProfileV2({ documents: [documentForSentences(draftDocument, windowSentences, start)] });
+    const diagnostics = familyDiagnosticsFor(sourceProfile, windowProfile);
+    const ranked = ["evidence", "rhythm", "discourse", "rhetoricalShape", "lexical"]
+      .map((family) => ({ family, ...diagnostics[family] }))
+      .sort((left, right) => right.drift - left.drift || (100 - right.score) - (100 - left.score));
+    const best = ranked[0];
+    if (best?.drift > 0) {
+      result.push({
+        family: best.family,
+        startSentence: start + 1,
+        endSentence: start + windowSentences.length,
+        startLine: windowSentences[0].line,
+        endLine: windowSentences.at(-1).line,
+        distance: best.distance,
+        drift: best.drift,
+        score: best.score,
+        threshold: best.threshold,
+        stability: best.stability,
+      });
+    }
+  }
+  return result
+    .sort((left, right) => right.drift - left.drift || left.startLine - right.startLine)
+    .slice(0, 4);
+}
+
+function rollingWindowStarts(sentenceCount, windowSize, stride) {
+  const starts = [];
+  for (let start = 0; start <= sentenceCount - windowSize; start += stride) {
+    starts.push(start);
+  }
+  const finalStart = Math.max(0, sentenceCount - windowSize);
+  if (!starts.includes(finalStart)) {
+    starts.push(finalStart);
+  }
+  return starts;
+}
+
+function documentForSentences(draftDocument, sentences, windowIndex) {
+  const text = sentences.map((sentence) => sentence.text).join(" ");
+  const block = {
+    type: "paragraph",
+    line: sentences[0]?.line ?? 1,
+    heading: null,
+    headingId: null,
+    headingDepth: 0,
+    lines: [text],
+  };
+  return {
+    file: `${draftDocument.file ?? "draft"}#window-${windowIndex + 1}`,
+    path: draftDocument.path,
+    headings: [],
+    sections: [{ heading: null, blocks: [block] }],
+    blocks: [block],
+    paragraphs: [{
+      type: "paragraph",
+      line: block.line,
+      heading: null,
+      headingId: null,
+      text,
+    }],
+    sentences,
+    wordCount: sentences.reduce((sum, sentence) => sum + sentence.tokens.length, 0),
+    text,
+  };
+}
+
+function rollingWindowActions({ rollingWindows, confidence }) {
+  return rollingWindows.map((window, index) => makeAction({
+    family: window.family,
+    ordinal: `window-${index + 1}`,
+    priority: window.family === "evidence" ? "review" : "consider",
+    unit: { type: "window", line: window.startLine, endLine: window.endLine },
+    confidence,
+    drift: window.drift,
+    stability: window.stability,
+    localMismatch: Math.min(1, window.drift / Math.max(1, window.drift + 0.5)),
+    why: `Sentences ${window.startSentence}-${window.endSentence} show localized ${window.family} drift beyond the writer's calibrated range.`,
+    reviseBy: rollingWindowReviseBy(window.family),
+  }));
+}
+
+function rollingWindowReviseBy(family) {
+  if (family === "evidence") {
+    return "Add or move concrete support into this local passage, or narrow the unsupported claims in the same window.";
+  }
+  if (family === "rhythm") {
+    return "Revise this passage's sentence and paragraph pacing before changing the whole draft.";
+  }
+  if (family === "discourse") {
+    return "Vary the local sentence turns, callbacks, and transitions in this passage.";
+  }
+  if (family === "rhetoricalShape") {
+    return "Adjust this passage's move sequence so the local claim, turn, evidence, and implication pattern is less abrupt.";
+  }
+  return "Revise this local passage for style fit before making document-wide lexical changes.";
+}
+
+function makeAction({ family, ordinal, priority, unit, confidence, drift, stability = 0.7, localMismatch, why, reviseBy }) {
+  return {
+    id: `v2.revise-plan.${family}.${ordinal}`,
+    family,
+    priority,
+    unit,
+    actionScore: clampScore(100 * confidence * familyWeight(family) * (EDITABILITY[family] ?? 0.6) * Math.max(0.35, stability) * drift * localMismatch),
+    localMismatch: round(localMismatch, 3),
+    why,
+    reviseBy,
+  };
+}
+
+function confidenceWeight(band) {
+  if (band === "deep") {
+    return 1;
+  }
+  if (band === "strong") {
+    return 0.9;
+  }
+  if (band === "usable") {
+    return 0.75;
+  }
+  return 0.45;
+}
+
+function displayPath(filePath, cwd) {
+  const relative = path.relative(cwd, filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join("/");
+  }
+  return filePath.split(path.sep).join("/");
+}
+
+function resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}