@holdyourvoice/hyv 3.0.2 → 3.1.1

package/dist/editorial-packs.test.js

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { analyzeBatch, analyzeEditorial, parseWritingBrief } from './editorial-packs.js';
+test('uses only the selected format pack and keeps advisory format findings non-blocking', () => {
+    const brief = parseWritingBrief({
+        version: '1', audience: 'founders', intent: 'start a discussion', format: 'social',
+    });
+    const report = analyzeEditorial('A pattern I keep seeing in founder posts is vague advice.', brief);
+    assert.equal(report.engine, 'editorial');
+    assert.equal(report.passed, true);
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.severity, finding.sentence]), [['editorial.social.generic-opener', 'yellow', 1]]);
+});
+test('enforces explicit local disclosure terms independently from format guidance', () => {
+    const brief = parseWritingBrief({
+        version: '1', audience: 'operators', intent: 'write an update', format: 'general', prohibitedTerms: ['internal contract value'],
+    });
+    const report = analyzeEditorial('The internal contract value is $12,000.', brief);
+    assert.equal(report.passed, false);
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.severity]), [['editorial.prohibited-term', 'red']]);
+});
+test('matches prohibited terms as complete normalized words or phrases', () => {
+    const brief = parseWritingBrief({ version: '1', audience: 'operators', intent: 'write an update', format: 'general', prohibitedTerms: ['art'] });
+    assert.equal(analyzeEditorial('We start with the delivery date.', brief).passed, true);
+    assert.equal(analyzeEditorial('The art needs a signed owner.', brief).passed, false);
+});
+test('covers the remaining contextual format checks without applying packs outside their format', () => {
+    const social = parseWritingBrief({ version: '1', audience: 'founders', intent: 'write', format: 'social' });
+    assert.deepEqual(analyzeEditorial('One point.\n\nSecond point.\n\nThird point.', social).findings.map((item) => item.id), ['editorial.social.one-line-run']);
+    const deck = parseWritingBrief({ version: '1', audience: 'buyers', intent: 'present', format: 'deck', title: '3 ways to improve delivery' });
+    assert.deepEqual(analyzeEditorial('We make delivery simpler.', deck).findings.map((item) => item.id), ['editorial.deck.first-slide-we', 'editorial.deck.numeric-title']);
+    const outreach = parseWritingBrief({ version: '1', audience: 'operators', intent: 'start a conversation', format: 'outreach' });
+    assert.deepEqual(analyzeEditorial('Does that sound interesting?', outreach).findings.map((item) => item.id), ['editorial.outreach.generic-question-cta']);
+    assert.deepEqual(analyzeEditorial('We make delivery simpler.', outreach).findings, []);
+});
+test('detects exact repeated openings and endings across a batch without judging deliberate variation', () => {
+    const report = analyzeBatch([
+        'The launch needs a clear owner. Start with the dependency map.',
+        'The launch needs a clear owner. Start with the dependency map.',
+        'The invoice needs a clear owner. Check the due date.',
+    ]);
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.draftIndexes]), [
+        ['batch.repeated-opening', [1, 2]],
+        ['batch.repeated-ending', [1, 2]],
+    ]);
+});
+test('rejects malformed writing briefs before they activate editorial checks', () => {
+    assert.throws(() => parseWritingBrief({ version: '1', audience: '', intent: 'write', format: 'social' }), /WritingBrief/);
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write', format: 'unknown' }), /WritingBrief/);
+});

package/dist/learning.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const MAX_PREFERENCES = 10;
+const MAX_EVENTS = 40;
+const MAX_RESOLVED_FINDINGS = 20;
+const MAX_INSTRUCTION_CHARACTERS = 240;
+const MAX_COMPOSED_CHARACTERS = 1_200;
+const MAX_STORAGE_BYTES = 64 * 1024;
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function profileFingerprint(profile) {
+    return createHash('sha256').update(canonicalJson(profile)).digest('hex');
+}
+function learningDirectory(options = {}) {
+    return join(options.root ?? process.env.HYV_HOME ?? join(homedir(), '.hyv'), 'learning');
+}
+function eventFile(profile, options = {}) {
+    return join(learningDirectory(options), `${profileFingerprint(profile)}.jsonl`);
+}
+function normalizeInstruction(instruction) {
+    return instruction.replace(/\s+/g, ' ').trim();
+}
+function isResolvedFinding(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const finding = value;
+    return (finding.engine === 'voice_dna' || finding.engine === 'ai_editor')
+        && typeof finding.id === 'string' && finding.id.length > 0
+        && (finding.severity === 'red' || finding.severity === 'yellow')
+        && Number.isInteger(finding.count) && (finding.count ?? 0) > 0;
+}
+function parseEvent(line) {
+    try {
+        const event = JSON.parse(line);
+        if (!event || event.version !== '1' || typeof event.timestamp !== 'string')
+            return undefined;
+        if (event.kind === 'instruction' && typeof event.instruction === 'string') {
+            const instruction = normalizeInstruction(event.instruction);
+            if (instruction.length > 0 && instruction.length <= MAX_INSTRUCTION_CHARACTERS)
+                return { version: '1', timestamp: event.timestamp, kind: 'instruction', instruction };
+        }
+        const resolved = event.resolved;
+        if (event.kind === 'verified_candidate' && Array.isArray(resolved) && resolved.length > 0 && resolved.every(isResolvedFinding) && typeof event.outcome === 'string') {
+            return { version: '1', timestamp: event.timestamp, kind: 'verified_candidate', resolved, outcome: event.outcome };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function readRecentText(file) {
+    try {
+        const size = statSync(file).size;
+        const length = Math.min(size, MAX_STORAGE_BYTES);
+        const descriptor = openSync(file, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            readSync(descriptor, buffer, 0, length, Math.max(0, size - length));
+            return buffer.toString('utf8');
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+function readEvents(profile, options = {}) {
+    const file = eventFile(profile, options);
+    return readRecentText(file).split('\n').flatMap((line) => {
+        const event = parseEvent(line);
+        return event ? [event] : [];
+    }).slice(-MAX_EVENTS);
+}
+function serialize(events) {
+    return `${events.map((event) => JSON.stringify(event)).join('\n')}\n`;
+}
+function withCompactionLock(file, operation) {
+    const lock = `${file}.lock`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            const descriptor = openSync(lock, 'wx', 0o600);
+            try {
+                return operation();
+            }
+            finally {
+                closeSync(descriptor);
+                unlinkSync(lock);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                return undefined;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    return undefined;
+}
+function appendEvent(profile, event, options = {}) {
+    try {
+        const directory = learningDirectory(options);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = eventFile(profile, options);
+        const line = `${JSON.stringify(event)}\n`;
+        const events = readEvents(profile, options);
+        const needsCompaction = events.length >= MAX_EVENTS || (statSync(file, { throwIfNoEntry: false })?.size ?? 0) + Buffer.byteLength(line) > MAX_STORAGE_BYTES;
+        if (needsCompaction) {
+            const compacted = withCompactionLock(file, () => {
+                const retained = [...readEvents(profile, options), event].slice(-MAX_EVENTS);
+                while (Buffer.byteLength(serialize(retained)) > MAX_STORAGE_BYTES)
+                    retained.shift();
+                writeFileSync(file, serialize(retained), { encoding: 'utf8', mode: 0o600 });
+            });
+            if (compacted === undefined)
+                return false;
+        }
+        else {
+            appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function countFindings(findings) {
+    const counted = new Map();
+    for (const finding of findings) {
+        const key = `${finding.engine}:${finding.id}:${finding.severity}`;
+        const entry = counted.get(key);
+        if (entry)
+            entry.count += 1;
+        else
+            counted.set(key, { finding, count: 1 });
+    }
+    return counted;
+}
+export function recordVerifiedCandidate(profile, verification, candidate, options = {}) {
+    if (!verification.passed)
+        return 'nothing_to_learn';
+    const original = countFindings([...verification.original.voiceDna.findings, ...verification.original.aiEditor.findings]);
+    const candidateFindings = countFindings([...verification.candidate.voiceDna.findings, ...verification.candidate.aiEditor.findings]);
+    const resolved = [...original].flatMap(([key, entry]) => {
+        const count = entry.count - (candidateFindings.get(key)?.count ?? 0);
+        return count > 0 ? [{ engine: entry.finding.engine, id: entry.finding.id, severity: entry.finding.severity, count }] : [];
+    });
+    if (!resolved.length)
+        return 'nothing_to_learn';
+    const bounded = resolved.slice(0, MAX_RESOLVED_FINDINGS);
+    const outcome = createHash('sha256').update(`${profileFingerprint(profile)}\0${candidate}`).digest('hex');
+    if (readEvents(profile, options).some((event) => event.kind === 'verified_candidate' && event.outcome === outcome))
+        return 'nothing_to_learn';
+    return appendEvent(profile, { version: '1', timestamp: new Date().toISOString(), kind: 'verified_candidate', resolved: bounded, outcome }, options) ? 'recorded' : 'write_failed';
+}
+export function addLearningInstruction(profile, instruction, options = {}) {
+    const trimmed = normalizeInstruction(instruction);
+    if (!trimmed)
+        throw new Error('Learning instructions cannot be empty.');
+    if (trimmed.length > MAX_INSTRUCTION_CHARACTERS)
+        throw new Error(`Learning instructions must be ${MAX_INSTRUCTION_CHARACTERS} characters or fewer.`);
+    return appendEvent(profile, { version: '1', timestamp: new Date().toISOString(), kind: 'instruction', instruction: trimmed }, options);
+}
+export function composeLearning(profile, options = {}) {
+    const preferences = new Map();
+    for (const event of readEvents(profile, options)) {
+        const texts = event.kind === 'instruction' && event.instruction
+            ? [{ text: event.instruction, count: 1 }]
+            : (event.resolved ?? []).map((finding) => ({ text: `Previously verified repair: ${finding.engine}/${finding.id}.`, count: finding.count }));
+        for (const { text, count } of texts) {
+            const current = preferences.get(text) ?? { count: 0, lastSeen: event.timestamp };
+            current.count += count;
+            if (event.timestamp > current.lastSeen)
+                current.lastSeen = event.timestamp;
+            preferences.set(text, current);
+        }
+    }
+    const result = [];
+    let characters = 0;
+    for (const [text, value] of [...preferences.entries()]
+        .sort(([firstText, first], [secondText, second]) => second.count - first.count || second.lastSeen.localeCompare(first.lastSeen) || firstText.localeCompare(secondText))
+        .slice(0, MAX_PREFERENCES)) {
+        if (characters + text.length > MAX_COMPOSED_CHARACTERS)
+            break;
+        result.push({ text, count: value.count });
+        characters += text.length;
+    }
+    return result;
+}
+export function clearLearning(profile, options = {}) {
+    const file = eventFile(profile, options);
+    try {
+        unlinkSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/learning.test.js

@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import { appendFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { verify } from './pipeline.js';
+import { buildProfile } from './voice-dna.js';
+const profile = buildProfile([
+    'I write plainly. I name the work.',
+    'I keep the mechanism clear. I avoid filler.',
+], ['leverage']);
+function directory() {
+    return mkdtempSync(join(tmpdir(), 'holdyourvoice-learning-'));
+}
+test('records only resolved findings from successful verification without draft text', () => {
+    const root = directory();
+    try {
+        const original = 'I leverage the answer with useful detail and clear mechanism.';
+        const candidate = 'I use the answer with useful detail and clear mechanism.';
+        const result = verify(original, candidate, profile);
+        assert.equal(result.passed, true);
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'recorded');
+        const eventFile = join(root, 'learning', `${profileFingerprint(profile)}.jsonl`);
+        const stored = readFileSync(eventFile, 'utf8');
+        assert.match(stored, /ai\.leverage/);
+        assert.doesNotMatch(stored, /I leverage the answer/);
+        assert.doesNotMatch(stored, /I use the answer/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('keeps learning isolated by profile and bounds composed preferences', () => {
+    const root = directory();
+    try {
+        const other = buildProfile(['We explain the mechanism.', 'We keep the useful detail.']);
+        for (let index = 0; index < 12; index += 1)
+            addLearningInstruction(profile, `Keep preference ${index}.`, { root });
+        addLearningInstruction(other, 'Use a different preference.', { root });
+        const composed = composeLearning(profile, { root });
+        assert.equal(composed.length, 10);
+        assert.ok(composed.every((item) => item.text.startsWith('Keep preference')));
+        assert.ok(!composed.some((item) => item.text === 'Use a different preference.'));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('does not create an event for a failed candidate and clears a single profile', () => {
+    const root = directory();
+    try {
+        const failed = verify('I name the work.', 'I leverage the work.', profile);
+        assert.equal(failed.passed, false);
+        assert.equal(recordVerifiedCandidate(profile, failed, 'I leverage the work.', { root }), 'nothing_to_learn');
+        assert.equal(existsSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`)), false);
+        addLearningInstruction(profile, 'Keep it direct.', { root });
+        assert.equal(clearLearning(profile, { root }), true);
+        assert.deepEqual(composeLearning(profile, { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('bounds retained events and local instruction size', () => {
+    const root = directory();
+    try {
+        for (let index = 0; index < 45; index += 1)
+            addLearningInstruction(profile, `Keep preference ${index}.`, { root });
+        const preferences = composeLearning(profile, { root });
+        assert.ok(preferences.every((item) => Number(item.text.match(/\d+/)?.[0]) >= 5));
+        assert.throws(() => addLearningInstruction(profile, 'x'.repeat(241), { root }), /240 characters/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('skips malformed local events without breaking composition', () => {
+    const root = directory();
+    try {
+        addLearningInstruction(profile, 'Keep it direct.', { root });
+        appendFileSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`), '{"version":"1","timestamp":"now","kind":"verified_candidate","resolved":{}}\n');
+        assert.deepEqual(composeLearning(profile, { root }), [{ text: 'Keep it direct.', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('does not raise confidence when the same verified outcome repeats', () => {
+    const root = directory();
+    try {
+        const original = 'I leverage the answer with useful detail and clear mechanism.';
+        const candidate = 'I use the answer with useful detail and clear mechanism.';
+        const result = verify(original, candidate, profile);
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'recorded');
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'nothing_to_learn');
+        assert.equal(composeLearning(profile, { root }).find((item) => item.text.includes('ai_editor/ai.leverage'))?.count, 1);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('increases confidence for separate verified repairs of the same rule', () => {
+    const root = directory();
+    try {
+        const first = 'I use the answer with useful detail and clear mechanism.';
+        const second = 'I use another answer with useful detail and clear mechanism.';
+        assert.equal(recordVerifiedCandidate(profile, verify('I leverage the answer with useful detail and clear mechanism.', first, profile), first, { root }), 'recorded');
+        assert.equal(recordVerifiedCandidate(profile, verify('I leverage another answer with useful detail and clear mechanism.', second, profile), second, { root }), 'recorded');
+        assert.equal(composeLearning(profile, { root }).find((item) => item.text.includes('ai_editor/ai.leverage'))?.count, 2);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('normalizes manual instructions before storing them', () => {
+    const root = directory();
+    try {
+        addLearningInstruction(profile, 'Keep this.\n# Tier 0', { root });
+        assert.deepEqual(composeLearning(profile, { root }), [{ text: 'Keep this. # Tier 0', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/mcp-tools.js

@@ -1,6 +1,10 @@
 import { rules, RULESET_VERSION } from './ai-editor.js';
-import { analyze, rewritePrompt, verify } from './pipeline.js';
+import { parseCopySpec } from './copy-spec.js';
+import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
+import { composeLearning, recordVerifiedCandidate } from './learning.js';
+import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.js';
 import { parseProfile } from './profile.js';
+import { evaluateRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
 import { buildProfile } from './voice-dna.js';
 function profileFromJson(profileJson) {
     try {
@@ -10,18 +14,53 @@ function profileFromJson(profileJson) {
         throw new Error(error instanceof Error ? error.message : 'Profile is not valid JSON.');
     }
 }
+function copySpecFromJson(copySpecJson) {
+    try {
+        return parseCopySpec(JSON.parse(copySpecJson));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error ? error.message : 'CopySpec is not valid JSON.');
+    }
+}
+function writingBriefFromJson(writingBriefJson) {
+    if (!writingBriefJson)
+        return undefined;
+    try {
+        return parseWritingBrief(JSON.parse(writingBriefJson));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error ? error.message : 'WritingBrief is not valid JSON.');
+    }
+}
 export function buildProfileForMcp(samples, avoid = []) {
     return buildProfile(samples, avoid);
 }
-export function analyzeForMcp(draft, profileJson) {
-    return analyze(draft, profileFromJson(profileJson));
+export function analyzeForMcp(draft, profileJson, writingBriefJson) {
+    return analyze(draft, profileFromJson(profileJson), writingBriefFromJson(writingBriefJson));
+}
+export function rewritePromptForMcp(draft, profileJson, options = {}, writingBriefJson) {
+    const profile = profileFromJson(profileJson);
+    return { prompt: rewritePrompt(draft, profile, composeLearning(profile, options), writingBriefFromJson(writingBriefJson)) };
 }
-export function rewritePromptForMcp(draft, profileJson) {
-    return { prompt: rewritePrompt(draft, profileFromJson(profileJson)) };
+export function prepareRewriteForMcp(draft, profileJson, copySpecJson, writingBriefJson) {
+    return prepareRewriteTask(draft, profileFromJson(profileJson), copySpecJson ? copySpecFromJson(copySpecJson) : undefined, writingBriefFromJson(writingBriefJson));
 }
-export function verifyForMcp(original, candidate, profileJson) {
-    return verify(original, candidate, profileFromJson(profileJson));
+export function applyRewriteForMcp(taskJson, responseJson, profileJson) {
+    return evaluateRewriteResponse(parseRewriteTask(JSON.parse(taskJson)), responseJson, profileFromJson(profileJson));
+}
+export function verifyForMcp(original, candidate, profileJson, options = {}, writingBriefJson) {
+    const profile = profileFromJson(profileJson);
+    const result = verify(original, candidate, profile, writingBriefFromJson(writingBriefJson));
+    return { ...result, learning: recordVerifiedCandidate(profile, result, candidate, options) };
+}
+export function verifyCopySpecForMcp(original, candidate, profileJson, copySpecJson, options = {}, writingBriefJson) {
+    const profile = profileFromJson(profileJson);
+    const result = verifyWithCopySpec(original, candidate, profile, copySpecFromJson(copySpecJson), writingBriefFromJson(writingBriefJson));
+    return { ...result, learning: result.passed ? recordVerifiedCandidate(profile, result, candidate, options) : 'nothing_to_learn' };
 }
 export function patternsForMcp() {
     return { version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) };
 }
+export function analyzeBatchForMcp(drafts) {
+    return analyzeBatch(drafts);
+}

package/dist/mcp-tools.test.js

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import test from 'node:test';
-import { analyzeForMcp, buildProfileForMcp, patternsForMcp, rewritePromptForMcp, verifyForMcp } from './mcp-tools.js';
+import { analyzeBatchForMcp, analyzeForMcp, applyRewriteForMcp, buildProfileForMcp, patternsForMcp, prepareRewriteForMcp, rewritePromptForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
 const profile = buildProfileForMcp(['I write clearly. I keep the useful detail.', 'I make the call. Then I explain the trade-off.'], ['leverage']);
 const profileJson = JSON.stringify(profile);
 test('builds a portable profile for MCP without files', () => {
@@ -12,12 +15,44 @@ test('keeps the dual-engine analysis shape through MCP tools', () => {
     assert.equal(result.voiceDna.engine, 'voice_dna');
     assert.equal(result.aiEditor.engine, 'ai_editor');
 });
+test('accepts optional WritingBrief context and exposes batch findings through MCP helpers', () => {
+    const brief = JSON.stringify({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' });
+    const analysis = analyzeForMcp('A pattern I keep seeing in founder posts is vague advice.', profileJson, brief);
+    assert.equal(analysis.editorial?.findings[0]?.id, 'editorial.social.generic-opener');
+    const batch = analyzeBatchForMcp(['The launch needs a clear owner.', 'The launch needs a clear owner.']);
+    assert.equal(batch.findings.length, 2);
+});
 test('creates and verifies an editing loop through MCP tools', () => {
-    const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson);
-    const result = verifyForMcp('I make the call.', 'I make the call.', profileJson);
-    assert.match(brief.prompt, /Tier 0/);
-    assert.equal(result.preservationScore, 100);
+    const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-'));
+    try {
+        const result = verifyForMcp('I leverage the answer with useful detail and clear mechanism.', 'I use the answer with useful detail and clear mechanism.', profileJson, { root });
+        const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson, { root });
+        assert.match(brief.prompt, /Tier 0/);
+        assert.match(brief.prompt, /Learned local preferences/);
+        assert.equal(result.preservationScore >= 70, true);
+        assert.equal(result.learning, 'recorded');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
 });
 test('exposes the executable pattern IDs through MCP tools', () => {
     assert.ok(patternsForMcp().rules.some((rule) => rule.id === 'ai.leverage'));
 });
+test('fails closed on changed CopySpec claims through MCP tools', () => {
+    const result = verifyCopySpecForMcp('The launch is on 14 August.', 'The launch is next month.', profileJson, JSON.stringify({
+        version: '1', audience: 'operators', intent: 'explain', channel: 'email',
+        claims: [{ id: 'launch-date', text: 'The launch is on 14 August.', evidence: 'Release calendar.' }],
+    }));
+    assert.equal(result.passed, false);
+    assert.equal(result.claims.failures[0]?.code, 'missing_immutable_claim');
+    assert.equal(result.learning, 'nothing_to_learn');
+});
+test('prepares and applies the rewrite task through MCP helpers', () => {
+    const task = prepareRewriteForMcp('I leverage the answer with useful detail and clear mechanism.', profileJson);
+    const result = applyRewriteForMcp(JSON.stringify(task), JSON.stringify({
+        version: '1', taskFingerprint: task.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer with useful detail and clear mechanism.' }],
+    }), profileJson);
+    assert.equal(result.status, 'needs_semantic_review');
+    assert.equal(result.candidate, 'I use the answer with useful detail and clear mechanism.');
+});

package/dist/mcp.js

@@ -1,9 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { analyzeForMcp, buildProfileForMcp, patternsForMcp, rewritePromptForMcp, verifyForMcp } from './mcp-tools.js';
+import { analyzeBatchForMcp, analyzeForMcp, applyRewriteForMcp, buildProfileForMcp, patternsForMcp, prepareRewriteForMcp, rewritePromptForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
 const writing = z.string().min(1).max(100_000);
 const profileJson = z.string().min(1).max(50_000);
+const copySpecJson = z.string().min(1).max(250_000);
+const writingBriefJson = z.string().min(1).max(50_000);
 const samples = z.array(writing).min(2).max(20);
 const avoid = z.array(z.string().min(1).max(200)).max(50).optional();
 function json(value) {
@@ -12,7 +14,7 @@ function json(value) {
 function failure(error) {
     return { content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true };
 }
-const server = new McpServer({ name: 'hold-your-voice', version: '3.0.2' });
+const server = new McpServer({ name: 'hold-your-voice', version: '3.1.1' });
 server.registerTool('hyv_build_profile', {
     description: 'Build a portable VoiceDNA profile from at least two writing samples. The samples stay in memory and are not saved.',
     inputSchema: { samples, avoid },
@@ -27,11 +29,11 @@ server.registerTool('hyv_build_profile', {
 });
 server.registerTool('hyv_analyze', {
     description: 'Run the separate VoiceDNA and AI Editor checks against a draft using a portable profile JSON string.',
-    inputSchema: { draft: writing, profile_json: profileJson },
+    inputSchema: { draft: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
     annotations: { readOnlyHint: true },
-}, async ({ draft, profile_json }) => {
+}, async ({ draft, profile_json, writing_brief_json }) => {
     try {
-        return json(analyzeForMcp(draft, profile_json));
+        return json(analyzeForMcp(draft, profile_json, writing_brief_json));
     }
     catch (error) {
         return failure(error);
@@ -39,23 +41,71 @@ server.registerTool('hyv_analyze', {
 });
 server.registerTool('hyv_rewrite_prompt', {
     description: 'Create a constrained editing brief. It does not rewrite the draft or call a model.',
-    inputSchema: { draft: writing, profile_json: profileJson },
+    inputSchema: { draft: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
     annotations: { readOnlyHint: true },
-}, async ({ draft, profile_json }) => {
+}, async ({ draft, profile_json, writing_brief_json }) => {
     try {
-        return json(rewritePromptForMcp(draft, profile_json));
+        return json(rewritePromptForMcp(draft, profile_json, {}, writing_brief_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_prepare_rewrite', {
+    description: 'Prepare a local, versioned rewrite task. The caller may forward it to a provider; doing so shares the draft and must be an explicit choice.',
+    inputSchema: { draft: writing, profile_json: profileJson, copy_spec_json: copySpecJson.optional(), writing_brief_json: writingBriefJson.optional() },
+    annotations: { readOnlyHint: true },
+}, async ({ draft, profile_json, copy_spec_json, writing_brief_json }) => {
+    try {
+        return json(prepareRewriteForMcp(draft, profile_json, copy_spec_json, writing_brief_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_apply_rewrite', {
+    description: 'Validate and apply a model response to a prepared task, then run the local gates. It never calls a provider or stores source or candidate text.',
+    inputSchema: { task_json: z.string().min(1).max(250_000), response_json: z.string().min(1).max(100_000), profile_json: profileJson },
+    annotations: { readOnlyHint: true },
+}, async ({ task_json, response_json, profile_json }) => {
+    try {
+        return json(applyRewriteForMcp(task_json, response_json, profile_json));
     }
     catch (error) {
         return failure(error);
     }
 });
 server.registerTool('hyv_verify', {
-    description: 'Verify a revised candidate against an original draft and portable profile. Reports regressions and preservation without saving either text.',
-    inputSchema: { original: writing, candidate: writing, profile_json: profileJson },
+    description: 'Verify a revised candidate against an original draft and portable profile. On a successful check, it stores only resolved finding IDs in local profile-scoped learning state; it never retains either text.',
+    inputSchema: { original: writing, candidate: writing, profile_json: profileJson, writing_brief_json: writingBriefJson.optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async ({ original, candidate, profile_json, writing_brief_json }) => {
+    try {
+        return json(verifyForMcp(original, candidate, profile_json, {}, writing_brief_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_verify_copy_spec', {
+    description: 'Verify a candidate against the existing voice gates and a local CopySpec. Immutable claims must remain verbatim and each carries local evidence; prohibited claims fail closed.',
+    inputSchema: { original: writing, candidate: writing, profile_json: profileJson, copy_spec_json: copySpecJson, writing_brief_json: writingBriefJson.optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async ({ original, candidate, profile_json, copy_spec_json, writing_brief_json }) => {
+    try {
+        return json(verifyCopySpecForMcp(original, candidate, profile_json, copy_spec_json, {}, writing_brief_json));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.registerTool('hyv_batch_analyze', {
+    description: 'Inspect two to one hundred drafts for repeated opening and closing sentences. It returns advisory batch findings and does not store the drafts.',
+    inputSchema: { drafts: z.array(writing).min(2).max(100) },
     annotations: { readOnlyHint: true },
-}, async ({ original, candidate, profile_json }) => {
+}, async ({ drafts }) => {
     try {
-        return json(verifyForMcp(original, candidate, profile_json));
+        return json(analyzeBatchForMcp(drafts));
     }
     catch (error) {
         return failure(error);