dravoice 0.1.1 → 0.1.3

package/src/v2/inspect.js

@@ -1,67 +1,67 @@
-export function renderInspectV2(profile) {
-  const lines = [
-    "Dravoice V2 Profile",
-    "",
-    `Source: ${profile.source.documentCount} document(s), ${profile.source.wordCount} words, ${profile.source.sentenceCount} sentences`,
-    `Corpus confidence: ${capitalize(profile.source.confidence.band)} - ${profile.source.confidence.message}`,
-    "",
-    "Feature families:",
-  ];
-
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${family.confidence}`);
-    if (family.warnings.length) {
-      for (const warning of family.warnings) {
-        lines.push(`  warning: ${warning}`);
-      }
-    }
-  }
-
-  lines.push("", "Feature details:");
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${featureSummary(name, family.features)}`);
-    if (family.revisionHandles?.length) {
-      lines.push("  Revision handles:");
-      for (const handle of family.revisionHandles) {
-        lines.push(`  - ${handle}`);
-      }
-    }
-  }
-
-  lines.push("", "Guidance:");
-  for (const rule of profile.guidance.draftingRules) {
-    lines.push(`- ${rule}`);
-  }
-
-  lines.push("");
-  return `${lines.join("\n")}`;
-}
-
-function capitalize(value) {
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}
-
-function featureSummary(name, features) {
-  if (name === "rhythm") {
-    return `sentenceWords.median=${features.sentenceWords.median}; paragraphWords.median=${features.paragraphWords.median}; listDensity=${features.listDensity}; quoteDensity=${features.quoteDensity}`;
-  }
-  if (name === "lexical") {
-    return `wordCount=${features.wordCount}; contentTypeTokenRatio=${features.vocabularyRichness.contentTypeTokenRatio}; wordLength.median=${features.wordLength.median}`;
-  }
-  if (name === "register") {
-    return `primary=${features.primary.value} (${features.primary.score}); alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
-  }
-  if (name === "discourse") {
-    return `transitionRates=${Object.entries(features.transitionRates).map(([key, value]) => `${key}:${value}`).join(", ")}; sentenceCallbacks=${features.sentenceCallbacks}`;
-  }
-  if (name === "rhetoricalShape") {
-    return `openingMoves=${features.openingMoves.slice(0, 5).join(" -> ") || "none"}; commonSequences=${features.commonSequences.slice(0, 3).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
-  }
-  if (name === "evidence") {
-    return `evidenceSentenceRate=${features.evidenceSentenceRate}; claimSentenceRate=${features.claimSentenceRate}; unsupportedClaimRate=${features.unsupportedClaimRate}; evidenceTypes=${features.evidenceTypes.map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
-  }
-  if (name === "structure") {
-    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
-  }
-  return JSON.stringify(features);
-}
+export function renderInspectV2(profile) {
+  const lines = [
+    "Dravoice V2 Profile",
+    "",
+    `Source: ${profile.source.documentCount} document(s), ${profile.source.wordCount} words, ${profile.source.sentenceCount} sentences`,
+    `Corpus confidence: ${capitalize(profile.source.confidence.band)} - ${profile.source.confidence.message}`,
+    "",
+    "Feature families:",
+  ];
+
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${family.confidence}`);
+    if (family.warnings.length) {
+      for (const warning of family.warnings) {
+        lines.push(`  warning: ${warning}`);
+      }
+    }
+  }
+
+  lines.push("", "Feature details:");
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${featureSummary(name, family.features)}`);
+    if (family.revisionHandles?.length) {
+      lines.push("  Revision handles:");
+      for (const handle of family.revisionHandles) {
+        lines.push(`  - ${handle}`);
+      }
+    }
+  }
+
+  lines.push("", "Guidance:");
+  for (const rule of profile.guidance.draftingRules) {
+    lines.push(`- ${rule}`);
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}`;
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function featureSummary(name, features) {
+  if (name === "rhythm") {
+    return `sentenceWords.median=${features.sentenceWords.median}; paragraphWords.median=${features.paragraphWords.median}; listDensity=${features.listDensity}; quoteDensity=${features.quoteDensity}`;
+  }
+  if (name === "lexical") {
+    return `wordCount=${features.wordCount}; contentTypeTokenRatio=${features.vocabularyRichness.contentTypeTokenRatio}; wordLength.median=${features.wordLength.median}; maskedCharacterFourgrams=${features.maskedCharacterFourgrams?.length ?? 0}; functionWordBigrams=${features.functionWordBigrams?.length ?? 0}`;
+  }
+  if (name === "register") {
+    return `primary=${features.primary.value} (${features.primary.score}); alternates=${features.scores.slice(1, 4).map((score) => `${score.value}:${score.score}`).join(", ")}`;
+  }
+  if (name === "discourse") {
+    return `transitionRates=${Object.entries(features.transitionRates).map(([key, value]) => `${key}:${value}`).join(", ")}; sentenceCallbacks=${features.sentenceCallbacks}`;
+  }
+  if (name === "rhetoricalShape") {
+    return `openingMoves=${features.openingMoves.slice(0, 5).join(" -> ") || "none"}; moveTrigrams=${features.moveTrigrams?.slice(0, 2).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}; commonSequences=${features.commonSequences.slice(0, 3).map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
+  }
+  if (name === "evidence") {
+    return `evidenceSentenceRate=${features.evidenceSentenceRate}; claimSentenceRate=${features.claimSentenceRate}; supportedClaimRate=${features.supportedClaimRate}; unsupportedClaimRate=${features.unsupportedClaimRate}; evidenceTypes=${features.evidenceTypes.map((item) => `${item.value}:${item.count}`).join(", ") || "none"}`;
+  }
+  if (name === "structure") {
+    return `sectionWords.median=${features.sectionWords.median}; headingCount.median=${features.headingCount.median}; listDocumentRate=${features.listDocumentRate}; quoteDocumentRate=${features.quoteDocumentRate}`;
+  }
+  return JSON.stringify(features);
+}

package/src/v2/io-utils.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_MAX_READ_BYTES = 5 * 1024 * 1024;
+
+export function readUtf8FileBounded(filePath, {
+  label = "File",
+  maxBytes = DEFAULT_MAX_READ_BYTES,
+  rejectBinary = true,
+} = {}) {
+  const resolved = path.resolve(filePath);
+  const stats = fs.statSync(resolved);
+  if (!stats.isFile()) {
+    throw new Error(`${label} is not a regular file: ${filePath}`);
+  }
+  if (stats.size > maxBytes) {
+    throw new Error(`${label} ${displayPath(filePath)} exceeds the ${maxBytes} byte limit.`);
+  }
+  const contents = fs.readFileSync(resolved, "utf8");
+  if (rejectBinary && contents.includes("\0")) {
+    throw new Error(`${label} ${displayPath(filePath)} looks like binary-looking text and cannot be analyzed.`);
+  }
+  return contents;
+}
+
+export function readJsonFileBounded(filePath, options = {}) {
+  const label = options.label ?? "JSON file";
+  const contents = readUtf8FileBounded(filePath, { ...options, label });
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    throw new Error(`${label} ${displayPath(filePath)} is not valid JSON: ${error.message}`);
+  }
+}
+
+export function writeUtf8FileSafely(filePath, contents) {
+  rejectSymlink(filePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  rejectSymlink(filePath);
+  fs.writeFileSync(filePath, contents, "utf8");
+}
+
+function rejectSymlink(filePath) {
+  if (fs.existsSync(filePath) && fs.lstatSync(filePath).isSymbolicLink()) {
+    throw new Error(`Refusing to write through symlink: ${filePath}`);
+  }
+}
+
+function displayPath(filePath) {
+  return String(filePath).split(path.sep).join("/");
+}

package/src/v2/profile.js

@@ -1,54 +1,57 @@
-import fs from "node:fs";
-import path from "node:path";
-import { analyzeDiscourse } from "./analyzers/discourse.js";
-import { analyzeEvidence } from "./analyzers/evidence.js";
-import { analyzeLexical } from "./analyzers/lexical.js";
-import { analyzeRegister } from "./analyzers/register.js";
-import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
-import { analyzeRhythm } from "./analyzers/rhythm.js";
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeDiscourse } from "./analyzers/discourse.js";
+import { analyzeEvidence } from "./analyzers/evidence.js";
+import { analyzeLexical } from "./analyzers/lexical.js";
+import { analyzeRegister } from "./analyzers/register.js";
+import { analyzeRhetoricalShape } from "./analyzers/rhetorical-shape.js";
+import { analyzeRhythm } from "./analyzers/rhythm.js";
 import { analyzeStructure } from "./analyzers/structure.js";
 import { loadDocuments } from "./document-model.js";
+import { readJsonFileBounded, writeUtf8FileSafely } from "./io-utils.js";
 import {
   STYLOMETRIC_REFERENCES,
   defaultStyleThresholds,
   distanceByFamily,
   percentile,
+  stabilityFromDistances,
 } from "./stylometry.js";
-
-export function learnVoicePackV2({ examplesDir, outDir }) {
-  const documents = loadDocuments({ examplesDir });
-  const profile = buildVoiceProfileV2({ documents });
-  if (outDir) {
-    writeVoicePackV2(outDir, profile);
-  }
-  return profile;
-}
-
-export function loadVoicePackV2(voiceDir) {
-  const profilePath = path.join(voiceDir, "profile.json");
-  if (!fs.existsSync(profilePath)) {
-    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
-  }
-  const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
-  if (profile.schemaVersion !== 2) {
-    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
-  }
-  return profile;
-}
-
+
+export function learnVoicePackV2({ examplesDir, outDir, excludePaths = [] }) {
+  const documents = loadDocuments({ examplesDir, excludePaths });
+  const profile = buildVoiceProfileV2({ documents });
+  if (outDir) {
+    writeVoicePackV2(outDir, profile);
+  }
+  return profile;
+}
+
+export function loadVoicePackV2(voiceDir) {
+  const profilePath = path.join(voiceDir, "profile.json");
+  if (!fs.existsSync(profilePath)) {
+    throw new Error(`No Dravoice V2 profile found at ${voiceDir}`);
+  }
+  const profile = readJsonFileBounded(profilePath, { label: "Dravoice profile", maxBytes: 2 * 1024 * 1024 });
+  if (profile.schemaVersion !== 2) {
+    throw new Error(`Expected a Dravoice V2 profile at ${voiceDir}; found schemaVersion ${profile.schemaVersion ?? "unknown"}.`);
+  }
+  validateVoiceProfileV2(profile, voiceDir);
+  return profile;
+}
+
 export function buildVoiceProfileV2({ documents }) {
   const source = sourceSummary(documents);
   const families = analyzeFeatureFamilies(documents);
 
   return {
-    schemaVersion: 2,
-    generatedBy: "dravoice-v2",
-    tool: { name: "Dravoice", cli: "drav" },
-    source,
-    families,
-    guidance: guidanceFor({ source, families }),
-    calibration: {
-      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
+    schemaVersion: 2,
+    generatedBy: "dravoice-v2",
+    tool: { name: "Dravoice", cli: "drav" },
+    source,
+    families,
+    guidance: guidanceFor({ source, families }),
+    calibration: {
+      featureStability: Object.fromEntries(Object.entries(families).map(([name, family]) => [name, family.confidence])),
       tolerances: {
         rhythmMedianWords: toleranceFor(source.confidence.band, 5, 8, 12),
         evidenceRate: toleranceFor(source.confidence.band, 0.12, 0.18, 0.25),
@@ -57,8 +60,8 @@ export function buildVoiceProfileV2({ documents }) {
       minimumDraftSize: {
         words: source.confidence.band === "weak" ? 25 : 35,
         sentences: source.confidence.band === "weak" ? 3 : 4,
-      },
-    },
+      },
+    },
   };
 }
 
@@ -101,6 +104,7 @@ function styleThresholdsFor(documents, fallbackFamilies) {
     families[family] = {
       threshold: Math.max(0.01, Math.min(0.95, observedThreshold || fallback)),
       observations: observations.length,
+      stability: stabilityFromDistances(observations),
     };
   }
 
@@ -110,92 +114,114 @@ function styleThresholdsFor(documents, fallbackFamilies) {
     families,
   };
 }
-
-function writeVoicePackV2(outDir, profile) {
-  fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
-  fs.writeFileSync(
-    path.join(outDir, ".dravoice.yml"),
-    [
-      "schemaVersion: 2",
-      "generatedBy: dravoice-v2",
-      `confidence: ${profile.source.confidence.band}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-}
-
-function sourceSummary(documents) {
-  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
-  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
-  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
-  return {
-    files: documents.map((document, index) => ({
-      id: `source-${index + 1}`,
-      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
-      wordCount: document.wordCount,
-      sentenceCount: document.sentences.length,
-    })),
-    documentCount: documents.length,
-    wordCount,
-    sentenceCount,
-    genres: [],
-    confidence,
-  };
-}
-
-function confidenceFor(documentCount, sentenceCount, wordCount) {
-  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
-    return { band: "deep", message: "Enough material for stricter family-level review." };
-  }
-  if (documentCount >= 5 && sentenceCount >= 30) {
-    return { band: "strong", message: "Enough examples for stable family-level review." };
-  }
-  if (documentCount >= 3 && sentenceCount >= 10) {
-    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
-  }
-  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
-}
-
-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 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.`,
-    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.",
-  ];
-
-  return {
-    summary: [
-      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
-      `Primary register signal: ${primaryRegister}.`,
-    ],
-    draftingRules,
-    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.",
-    ],
-    examples: [],
-  };
-}
-
-function toleranceFor(band, deep, strong, weak) {
-  if (band === "deep") {
-    return deep;
-  }
-  if (band === "strong") {
-    return strong;
-  }
-  return weak;
-}
+
+function writeVoicePackV2(outDir, profile) {
+  fs.mkdirSync(outDir, { recursive: true });
+  writeUtf8FileSafely(path.join(outDir, "profile.json"), `${JSON.stringify(profile, null, 2)}\n`);
+  writeUtf8FileSafely(
+    path.join(outDir, ".dravoice.yml"),
+    [
+      "schemaVersion: 2",
+      "generatedBy: dravoice-v2",
+      `confidence: ${profile.source.confidence.band}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function validateVoiceProfileV2(profile, voiceDir) {
+  assertObject(profile.source, "profile.source", voiceDir);
+  assertObject(profile.source.confidence, "profile.source.confidence", voiceDir);
+  assertObject(profile.families, "profile.families", voiceDir);
+  for (const family of ["rhythm", "lexical", "register", "discourse", "rhetoricalShape", "evidence", "structure"]) {
+    assertObject(profile.families[family], `profile.families.${family}`, voiceDir);
+    assertObject(profile.families[family].features, `profile.families.${family}.features`, voiceDir);
+  }
+  assertObject(profile.guidance, "profile.guidance", voiceDir);
+  if (!Array.isArray(profile.guidance.summary) || !Array.isArray(profile.guidance.draftingRules) || !Array.isArray(profile.guidance.avoid)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: profile.guidance must include summary, draftingRules, and avoid arrays.`);
+  }
+  assertObject(profile.calibration, "profile.calibration", voiceDir);
+  assertObject(profile.calibration.minimumDraftSize, "profile.calibration.minimumDraftSize", voiceDir);
+  assertObject(profile.calibration.styleThresholds, "profile.calibration.styleThresholds", voiceDir);
+}
+
+function assertObject(value, field, voiceDir) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid Dravoice V2 profile at ${voiceDir}: missing ${field}.`);
+  }
+}
+
+function sourceSummary(documents) {
+  const wordCount = documents.reduce((sum, document) => sum + document.wordCount, 0);
+  const sentenceCount = documents.reduce((sum, document) => sum + document.sentences.length, 0);
+  const confidence = confidenceFor(documents.length, sentenceCount, wordCount);
+  return {
+    files: documents.map((document, index) => ({
+      id: `source-${index + 1}`,
+      extension: path.extname(document.path || document.file).toLowerCase() || ".txt",
+      wordCount: document.wordCount,
+      sentenceCount: document.sentences.length,
+    })),
+    documentCount: documents.length,
+    wordCount,
+    sentenceCount,
+    genres: [],
+    confidence,
+  };
+}
+
+function confidenceFor(documentCount, sentenceCount, wordCount) {
+  if (documentCount >= 10 && sentenceCount >= 80 && wordCount >= 5000) {
+    return { band: "deep", message: "Enough material for stricter family-level review." };
+  }
+  if (documentCount >= 5 && sentenceCount >= 30) {
+    return { band: "strong", message: "Enough examples for stable family-level review." };
+  }
+  if (documentCount >= 3 && sentenceCount >= 10) {
+    return { band: "usable", message: "Enough text for prompt guidance and cautious review." };
+  }
+  return { band: "weak", message: "Limited corpus; use findings as weak signals." };
+}
+
+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 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.`,
+    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.",
+  ];
+
+  return {
+    summary: [
+      `Local Dravoice V2 profile from ${source.documentCount} document(s), ${source.wordCount} words, confidence ${source.confidence.band}.`,
+      `Primary register signal: ${primaryRegister}.`,
+    ],
+    draftingRules,
+    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.",
+    ],
+    examples: [],
+  };
+}
+
+function toleranceFor(band, deep, strong, weak) {
+  if (band === "deep") {
+    return deep;
+  }
+  if (band === "strong") {
+    return strong;
+  }
+  return weak;
+}

package/src/v2/prompt.js

@@ -1,64 +1,65 @@
-import fs from "node:fs";
-import path from "node:path";
-import { loadVoicePackV2 } from "./profile.js";
-
-export function voicePromptPackV2({ voice, format = "agents", outPath }) {
-  const profile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
-  if (format !== "agents" && format !== "claude" && format !== "system") {
-    throw new Error(`Unsupported prompt format: ${format}`);
-  }
-  const rendered = renderPrompt(profile, format);
-  if (outPath) {
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, rendered, "utf8");
-  }
-  return rendered;
-}
-
-function renderPrompt(profile, format) {
-  const header = {
-    agents: "# Dravoice V2 Writing Guidance",
-    claude: "# CLAUDE.md guidance for Dravoice V2",
-    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.",
-  }[format];
-  const lines = [
-    header,
-    "",
-    preface,
-    "",
-    "## Summary",
-    "",
-    ...profile.guidance.summary.map((item) => `- ${item}`),
-    "",
-    "## Feature Families",
-    "",
-  ];
-
-  for (const [name, family] of Object.entries(profile.families)) {
-    lines.push(`- ${name}: ${family.confidence} confidence; ${family.revisionHandles[0]}`);
-  }
-
-  lines.push("", "## Drafting Rules", "");
-  for (const rule of profile.guidance.draftingRules) {
-    lines.push(`- ${rule}`);
-  }
-
-  lines.push("", "## Avoid", "");
-  for (const item of profile.guidance.avoid) {
-    lines.push(`- ${item}`);
-  }
-
-  if (profile.guidance.examples.length) {
-    lines.push("", "## Source-Backed Examples", "");
-    for (const example of profile.guidance.examples) {
-      lines.push(`- ${example}`);
-    }
-  }
-
-  return `${lines.join("\n")}\n`;
-}
+import fs from "node:fs";
+import path from "node:path";
+import { writeUtf8FileSafely } from "./io-utils.js";
+import { loadVoicePackV2 } from "./profile.js";
+
+export function voicePromptPackV2({ voice, format = "agents", outPath }) {
+  const profile = typeof voice === "string" ? loadVoicePackV2(voice) : voice;
+  if (format !== "agents" && format !== "claude" && format !== "system") {
+    throw new Error(`Unsupported prompt format: ${format}`);
+  }
+  const rendered = renderPrompt(profile, format);
+  if (outPath) {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    writeUtf8FileSafely(outPath, rendered);
+  }
+  return rendered;
+}
+
+function renderPrompt(profile, format) {
+  const header = {
+    agents: "# Dravoice V2 Writing Guidance",
+    claude: "# CLAUDE.md guidance for Dravoice V2",
+    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.",
+  }[format];
+  const lines = [
+    header,
+    "",
+    preface,
+    "",
+    "## Summary",
+    "",
+    ...profile.guidance.summary.map((item) => `- ${item}`),
+    "",
+    "## Feature Families",
+    "",
+  ];
+
+  for (const [name, family] of Object.entries(profile.families)) {
+    lines.push(`- ${name}: ${family.confidence} confidence; ${family.revisionHandles[0]}`);
+  }
+
+  lines.push("", "## Drafting Rules", "");
+  for (const rule of profile.guidance.draftingRules) {
+    lines.push(`- ${rule}`);
+  }
+
+  lines.push("", "## Avoid", "");
+  for (const item of profile.guidance.avoid) {
+    lines.push(`- ${item}`);
+  }
+
+  if (profile.guidance.examples.length) {
+    lines.push("", "## Source-Backed Examples", "");
+    for (const example of profile.guidance.examples) {
+      lines.push(`- ${example}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}