@holdyourvoice/hyv 3.1.0 → 3.2.0

package/dist/editorial-packs.test.js

@@ -0,0 +1,94 @@
+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/);
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write', format: 'social', evidenceStatus: 'unknown' }), /WritingBrief/);
+    assert.throws(() => parseWritingBrief({ version: '1', audience: 'founders', intent: 'write', format: 'social', argumentMap: { observation: 'A', mechanism: 'B', consequence: 'C' } }), /WritingBrief/);
+});
+test('adds opt-in evidence and reader-value review cues without blocking publication', () => {
+    const brief = parseWritingBrief({
+        version: '1',
+        audience: 'operators',
+        intent: 'explain a reliability cost',
+        format: 'social',
+        evidenceStatus: 'unverified',
+        argumentMap: {
+            observation: 'A worker failed.',
+            mechanism: 'The cache was lost.',
+            consequence: 'The request restarts.',
+            readerValue: 'Avoid the cold restart cost.',
+        },
+    });
+    const report = analyzeEditorial('A worker failed. The request restarts.', brief);
+    assert.equal(report.passed, true);
+    assert.deepEqual(report.findings.map((finding) => finding.id), [
+        'editorial.evidence.unverified',
+        'editorial.argument-map.reader-value-missing',
+    ]);
+});
+test('does not flag an argument map when the draft carries the reader value', () => {
+    const brief = parseWritingBrief({
+        version: '1',
+        audience: 'operators',
+        intent: 'explain a reliability cost',
+        format: 'social',
+        argumentMap: {
+            observation: 'A worker failed.',
+            mechanism: 'The cache was lost.',
+            consequence: 'The request restarts.',
+            readerValue: 'Avoid the cold restart cost.',
+        },
+    });
+    assert.deepEqual(analyzeEditorial('A worker failed. Avoid the cold restart cost.', brief).findings, []);
+});
+test('keeps the reader-value cue when only one generic term overlaps', () => {
+    const brief = parseWritingBrief({
+        version: '1', audience: 'operators', intent: 'explain a reliability cost', format: 'social',
+        argumentMap: { observation: 'A worker failed.', mechanism: 'The cache was lost.', consequence: 'The request restarts.', readerValue: 'Avoid the cold restart cost.' },
+    });
+    assert.ok(analyzeEditorial('A worker failed. We avoid a delay.', brief).findings.some((item) => item.id === 'editorial.argument-map.reader-value-missing'));
+});

package/dist/hygiene.js

@@ -0,0 +1,85 @@
+const CHARACTER_POLICIES = new Map([
+    [0x180e, { kind: 'zero_width', label: 'Mongolian vowel separator', fix: 'none' }],
+    [0x200b, { kind: 'zero_width', label: 'Zero width space', fix: 'none' }],
+    [0x200c, { kind: 'zero_width', label: 'Zero width non-joiner', fix: 'none' }],
+    [0x200d, { kind: 'zero_width', label: 'Zero width joiner', fix: 'none' }],
+    [0x2060, { kind: 'zero_width', label: 'Word joiner', fix: 'none' }],
+    [0xfeff, { kind: 'zero_width', label: 'Byte order mark / zero width no-break space', fix: 'none' }],
+]);
+for (const [codepoint, label] of [
+    [0x061c, 'Arabic letter mark'], [0x200e, 'Left-to-right mark'], [0x200f, 'Right-to-left mark'],
+    [0x202a, 'Left-to-right embedding'], [0x202b, 'Right-to-left embedding'], [0x202c, 'Pop directional formatting'],
+    [0x202d, 'Left-to-right override'], [0x202e, 'Right-to-left override'], [0x2066, 'Left-to-right isolate'],
+    [0x2067, 'Right-to-left isolate'], [0x2068, 'First strong isolate'], [0x2069, 'Pop directional isolate'],
+])
+    CHARACTER_POLICIES.set(codepoint, { kind: 'bidi', label, fix: 'none' });
+for (const [codepoint, label] of [
+    [0x00a0, 'No-break space'], [0x1680, 'Ogham space mark'], [0x2000, 'En quad'], [0x2001, 'Em quad'],
+    [0x2002, 'En space'], [0x2003, 'Em space'], [0x2004, 'Three-per-em space'], [0x2005, 'Four-per-em space'],
+    [0x2006, 'Six-per-em space'], [0x2007, 'Figure space'], [0x2008, 'Punctuation space'], [0x2009, 'Thin space'],
+    [0x200a, 'Hair space'], [0x202f, 'Narrow no-break space'], [0x205f, 'Medium mathematical space'], [0x3000, 'Ideographic space'],
+])
+    CHARACTER_POLICIES.set(codepoint, { kind: 'unusual_space', label, fix: 'none' });
+function formattedCodepoint(codepoint) {
+    return `U+${codepoint.toString(16).toUpperCase().padStart(4, '0')}`;
+}
+function classification(codepoint) {
+    return CHARACTER_POLICIES.get(codepoint) ?? (codepoint >= 0xe0001 && codepoint <= 0xe007f
+        ? { kind: 'tag', label: 'Unicode tag character', fix: 'none' }
+        : undefined);
+}
+function policyAt(codepoint, offset) {
+    const policy = classification(codepoint);
+    return codepoint === 0xfeff && offset === 0 && policy ? { ...policy, fix: 'remove' } : policy;
+}
+function scanHygiene(text, clean) {
+    const grouped = new Map();
+    const cleanedParts = [];
+    const changes = [];
+    let unchangedStart = 0;
+    for (let offset = 0; offset < text.length;) {
+        const codepoint = text.codePointAt(offset);
+        const character = String.fromCodePoint(codepoint);
+        const found = policyAt(codepoint, offset);
+        if (found) {
+            const key = `${codepoint}:${found.fix}`;
+            const hit = grouped.get(key) ?? { ...found, codepoint, offsets: [] };
+            hit.offsets.push(offset);
+            grouped.set(key, hit);
+            if (clean && found.fix !== 'none') {
+                cleanedParts.push(text.slice(unchangedStart, offset));
+                changes.push({ offset, codepoint: formattedCodepoint(codepoint), action: 'removed' });
+                unchangedStart = offset + character.length;
+            }
+        }
+        offset += character.length;
+    }
+    const hits = [...grouped.values()].sort((left, right) => left.codepoint - right.codepoint || left.offsets[0] - right.offsets[0]).map((hit) => {
+        const { codepoint } = hit;
+        const base = { codepoint: formattedCodepoint(codepoint), label: hit.label, kind: hit.kind, count: hit.offsets.length, offsets: hit.offsets };
+        return { ...base, fix: hit.fix };
+    });
+    const report = {
+        version: '1',
+        length: text.length,
+        suspiciousCount: hits.reduce((total, hit) => total + hit.count, 0),
+        fixableCount: hits.filter((hit) => hit.fix !== 'none').reduce((total, hit) => total + hit.count, 0),
+        hits,
+    };
+    if (cleanedParts.length)
+        cleanedParts.push(text.slice(unchangedStart));
+    return { report, cleaned: cleanedParts.length ? cleanedParts.join('') : text, changes };
+}
+export function inspectHygiene(text) {
+    return scanHygiene(text, false).report;
+}
+export function cleanHygiene(text) {
+    const result = scanHygiene(text, true);
+    return { ...result, changed: result.changes.length > 0 };
+}
+export function finalOutputCheck(text) {
+    const cleaned = cleanHygiene(text);
+    const remaining = inspectHygiene(cleaned.cleaned);
+    const base = { version: '1', changed: cleaned.changed, changes: cleaned.changes, input: cleaned.report, remaining };
+    return remaining.suspiciousCount === 0 ? { ...base, accepted: true, output: cleaned.cleaned } : { ...base, accepted: false };
+}

package/dist/hygiene.test.js

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { cleanHygiene, finalOutputCheck, inspectHygiene } from './hygiene.js';
+test('reports zero-width, bidi, tag, and unusual-space characters with exact offsets', () => {
+    const text = `one\u200Btwo\u202Ethree\u{E0001}\u00A0four`;
+    const report = inspectHygiene(text);
+    assert.equal(report.suspiciousCount, 4);
+    assert.equal(report.fixableCount, 0);
+    assert.deepEqual(report.hits.map((hit) => [hit.codepoint, hit.kind, hit.count]), [
+        ['U+00A0', 'unusual_space', 1],
+        ['U+200B', 'zero_width', 1],
+        ['U+202E', 'bidi', 1],
+        ['U+E0001', 'tag', 1],
+    ]);
+    assert.deepEqual(report.hits.find((hit) => hit.codepoint === 'U+E0001')?.offsets, [13]);
+});
+test('removes only a leading byte-order mark and preserves language, spacing, bidi, and tag controls', () => {
+    const text = `\uFEFFa\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`;
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, `a\u200Bb\uFEFFc\u00A0d\u200Ce\u200Df\u202Eg\u{E0001}`);
+    assert.equal(result.changed, true);
+    assert.deepEqual(result.changes.map((change) => [change.codepoint, change.action]), [['U+FEFF', 'removed']]);
+    assert.equal(result.report.suspiciousCount, 8);
+    assert.equal(result.report.fixableCount, 1);
+});
+test('leaves clean text byte-for-byte unchanged', () => {
+    const text = 'plain text\nwith normal spaces.';
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.changed, false);
+    assert.deepEqual(result.changes, []);
+    assert.deepEqual(result.report.hits, []);
+});
+test('groups repeated report-only hits and preserves supplementary characters', () => {
+    const text = `😀\u200Bword\u200B`;
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.report.suspiciousCount, 2);
+    assert.equal(result.report.hits.length, 1);
+    assert.equal(result.report.hits[0]?.count, 2);
+    assert.deepEqual(result.report.hits[0]?.offsets, [2, 7]);
+});
+test('preserves multilingual spacing and word-boundary controls byte-for-byte', () => {
+    const text = `ไทย\u200Bภาษา 10\u00A0kg 日本語\u3000本文 ᠮ\u180Eᠣ a\u2060b`;
+    const result = cleanHygiene(text);
+    assert.equal(result.cleaned, text);
+    assert.equal(result.changed, false);
+    assert.equal(result.report.suspiciousCount, 5);
+    assert.equal(result.report.fixableCount, 0);
+});
+test('accepts exact clean output and minimally removes only a leading BOM', () => {
+    const clean = finalOutputCheck('exact output\n');
+    assert.equal(clean.accepted, true);
+    assert.equal(clean.accepted && clean.output, 'exact output\n');
+    assert.equal(clean.changed, false);
+    const bom = finalOutputCheck('\uFEFFexact output');
+    assert.equal(bom.accepted, true);
+    assert.equal(bom.accepted && bom.output, 'exact output');
+    assert.deepEqual(bom.changes, [{ offset: 0, codepoint: 'U+FEFF', action: 'removed' }]);
+});
+test('withholds output when hidden characters remain unresolved', () => {
+    const result = finalOutputCheck('Thai\u200Bboundary 👩\u200D💻');
+    assert.equal(result.accepted, false);
+    assert.equal('output' in result, false);
+    assert.equal(result.changed, false);
+    assert.deepEqual(result.remaining.hits.map((hit) => hit.codepoint), ['U+200B', 'U+200D']);
+});

package/dist/mcp-tools.js

@@ -1,8 +1,12 @@
-import { rules, RULESET_VERSION } from './ai-editor.js';
+import { RULESET_VERSION, serializedRules } from './ai-editor.js';
+import { parseCopySpec } from './copy-spec.js';
+import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
 import { composeLearning, recordVerifiedCandidate } from './learning.js';
-import { analyze, rewritePrompt, verify } from './pipeline.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';
+import { finalOutputCheck, inspectHygiene } from './hygiene.js';
 function profileFromJson(profileJson) {
     try {
         return parseProfile(JSON.parse(profileJson));
@@ -11,21 +15,59 @@ 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 inspectHygieneForMcp(draft) {
+    return inspectHygiene(draft);
 }
-export function rewritePromptForMcp(draft, profileJson, options = {}) {
+export function finalOutputCheckForMcp(text) {
+    return finalOutputCheck(text);
+}
+export function rewritePromptForMcp(draft, profileJson, options = {}, writingBriefJson) {
     const profile = profileFromJson(profileJson);
-    return { prompt: rewritePrompt(draft, profile, composeLearning(profile, options)) };
+    return { prompt: rewritePrompt(draft, profile, composeLearning(profile, options), writingBriefFromJson(writingBriefJson)) };
+}
+export function prepareRewriteForMcp(draft, profileJson, copySpecJson, writingBriefJson) {
+    return prepareRewriteTask(draft, profileFromJson(profileJson), copySpecJson ? copySpecFromJson(copySpecJson) : undefined, writingBriefFromJson(writingBriefJson));
 }
-export function verifyForMcp(original, candidate, profileJson, options = {}) {
+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);
+    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 })) };
+    return { version: RULESET_VERSION, rules: serializedRules() };
+}
+export function analyzeBatchForMcp(drafts) {
+    return analyzeBatch(drafts);
 }

package/dist/mcp-tools.test.js

@@ -3,7 +3,7 @@ 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, finalOutputCheckForMcp, inspectHygieneForMcp, 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', () => {
@@ -11,9 +11,33 @@ test('builds a portable profile for MCP without files', () => {
     assert.equal(profile.sampleCount, 2);
 });
 test('keeps the dual-engine analysis shape through MCP tools', () => {
-    const result = analyzeForMcp('I leverage a clear plan.', profileJson);
+    const result = analyzeForMcp('I leverage a clear plan.\u200B', profileJson);
     assert.equal(result.voiceDna.engine, 'voice_dna');
     assert.equal(result.aiEditor.engine, 'ai_editor');
+    assert.equal(result.hygiene.suspiciousCount, 1);
+});
+test('inspects Unicode hygiene through MCP without a voice profile', () => {
+    const result = inspectHygieneForMcp('one\u200Btwo\u00A0three');
+    assert.equal(result.suspiciousCount, 2);
+    assert.equal(result.fixableCount, 0);
+});
+test('gates exact final output through MCP without a voice profile', () => {
+    const accepted = finalOutputCheckForMcp('exact output');
+    assert.equal(accepted.accepted && accepted.output, 'exact output');
+    const rejected = finalOutputCheckForMcp('hidden\u200Boutput');
+    assert.equal(rejected.accepted, false);
+    assert.equal('output' in rejected, false);
+});
+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', evidenceStatus: 'unverified',
+        argumentMap: { observation: 'Founders repeat vague advice.', mechanism: 'The advice skips the work.', consequence: 'Readers cannot act.', readerValue: 'Avoid a vague post.' },
+    });
+    const analysis = analyzeForMcp('A pattern I keep seeing in founder posts is vague advice.', profileJson, brief);
+    assert.ok(analysis.editorial?.findings.some((item) => item.id === 'editorial.social.generic-opener'));
+    assert.ok(analysis.editorial?.findings.some((item) => item.id === 'editorial.evidence.unverified'));
+    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 root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-'));
@@ -30,5 +54,33 @@ test('creates and verifies an editing loop through MCP tools', () => {
     }
 });
 test('exposes the executable pattern IDs through MCP tools', () => {
-    assert.ok(patternsForMcp().rules.some((rule) => rule.id === 'ai.leverage'));
+    const catalog = patternsForMcp();
+    assert.ok(catalog.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('allows declared CopySpec atoms to survive a split MCP rewrite', () => {
+    const spec = JSON.stringify({
+        version: '1', audience: 'operators', intent: 'explain', channel: 'email',
+        claims: [{ id: 'model-size', text: 'Kimi K2.6 has 600 GB of INT4 weights.', atoms: ['Kimi K2.6 uses INT4 weights', 'payload is 600 GB'], evidence: 'Technical report.' }],
+    });
+    const preserved = verifyCopySpecForMcp('Kimi K2.6 has 600 GB of INT4 weights.', 'Kimi K2.6 uses INT4 weights. The payload is 600 GB.', profileJson, spec);
+    assert.equal(preserved.claims.passed, true);
+    const missing = verifyCopySpecForMcp('Kimi K2.6 has 600 GB of INT4 weights.', 'Kimi K2.6 uses INT4 weights.', profileJson, spec);
+    assert.deepEqual(missing.claims.failures.map((failure) => failure.code), ['missing_immutable_atom']);
+});
+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,13 @@
 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, finalOutputCheckForMcp, inspectHygieneForMcp, patternsForMcp, prepareRewriteForMcp, rewritePromptForMcp, verifyCopySpecForMcp, verifyForMcp } from './mcp-tools.js';
+import { HYV_VERSION } from './version.js';
 const writing = z.string().min(1).max(100_000);
+const hygieneText = z.string().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 +16,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.1.0' });
+const server = new McpServer({ name: 'hold-your-voice', version: HYV_VERSION });
 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 },
@@ -26,24 +30,58 @@ 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 },
+    description: 'Run separate VoiceDNA and AI Editor checks plus a non-scoring Unicode hygiene inspection against a draft using a portable profile JSON string.',
+    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);
     }
 });
+server.registerTool('hyv_hygiene', {
+    description: 'Inspect text for zero-width characters, bidirectional controls, Unicode tag characters, and unusual spaces without changing it or requiring a voice profile.',
+    inputSchema: { draft: hygieneText },
+    annotations: { readOnlyHint: true },
+}, async ({ draft }) => json(inspectHygieneForMcp(draft)));
+server.registerTool('hyv_final_check', {
+    description: 'Gate exact user-facing text from any model, tool, or interface. Returns output only when clean or after removing a leading byte-order mark; unresolved hidden characters withhold output.',
+    inputSchema: { text: hygieneText },
+    annotations: { readOnlyHint: true },
+}, async ({ text }) => json(finalOutputCheckForMcp(text)));
 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, writing_brief_json }) => {
+    try {
+        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 ({ draft, profile_json }) => {
+}, async ({ task_json, response_json, profile_json }) => {
     try {
-        return json(rewritePromptForMcp(draft, profile_json));
+        return json(applyRewriteForMcp(task_json, response_json, profile_json));
     }
     catch (error) {
         return failure(error);
@@ -51,11 +89,35 @@ server.registerTool('hyv_rewrite_prompt', {
 });
 server.registerTool('hyv_verify', {
     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 },
+    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 remain verbatim unless atoms are supplied; then each declared atom must remain. 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 }) => {
+}, 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 ({ drafts }) => {
     try {
-        return json(verifyForMcp(original, candidate, profile_json));
+        return json(analyzeBatchForMcp(drafts));
     }
     catch (error) {
         return failure(error);

package/dist/mcp.test.js

@@ -22,9 +22,43 @@ test('serves local Claude tools over stdio', async () => {
     assert.equal(code, 0);
     const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
     const tools = responses.find((response) => response.id === 2)?.result?.tools;
-    assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_rewrite_prompt', 'hyv_verify', 'hyv_patterns']);
-    assert.ok(tools?.filter((tool) => tool.name !== 'hyv_verify').every((tool) => tool.annotations?.readOnlyHint));
+    assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_hygiene', 'hyv_final_check', 'hyv_rewrite_prompt', 'hyv_prepare_rewrite', 'hyv_apply_rewrite', 'hyv_verify', 'hyv_verify_copy_spec', 'hyv_batch_analyze', 'hyv_patterns']);
+    assert.ok(tools?.filter((tool) => tool.name !== 'hyv_verify' && tool.name !== 'hyv_verify_copy_spec').every((tool) => tool.annotations?.readOnlyHint));
     assert.equal(tools?.find((tool) => tool.name === 'hyv_verify')?.annotations?.readOnlyHint, false);
+    assert.equal(tools?.find((tool) => tool.name === 'hyv_verify_copy_spec')?.annotations?.readOnlyHint, false);
+});
+test('accepts empty text for profile-free hygiene inspection', async () => {
+    const server = spawn(process.execPath, [new URL('./cli.js', import.meta.url).pathname, 'mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    server.stdout.on('data', (chunk) => { stdout += chunk; });
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'hyv_hygiene', arguments: { draft: '' } } })}\n`);
+    server.stdin.end();
+    const [code] = await once(server, 'close');
+    assert.equal(code, 0);
+    const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
+    const report = JSON.parse(responses.find((response) => response.id === 2)?.result?.content?.[0]?.text ?? '{}');
+    assert.equal(report.suspiciousCount, 0);
+});
+test('gates exact final output through the registered profile-free MCP tool', async () => {
+    const server = spawn(process.execPath, [new URL('./cli.js', import.meta.url).pathname, 'mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    server.stdout.on('data', (chunk) => { stdout += chunk; });
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'hyv_final_check', arguments: { text: 'Exact output.' } } })}\n`);
+    server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'hyv_final_check', arguments: { text: 'Hidden\u200B output.' } } })}\n`);
+    server.stdin.end();
+    const [code] = await once(server, 'close');
+    assert.equal(code, 0);
+    const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
+    const accepted = JSON.parse(responses.find((response) => response.id === 2)?.result?.content?.[0]?.text ?? '{}');
+    const rejected = JSON.parse(responses.find((response) => response.id === 3)?.result?.content?.[0]?.text ?? '{}');
+    assert.equal(accepted.accepted, true);
+    assert.equal(accepted.output, 'Exact output.');
+    assert.equal(rejected.accepted, false);
+    assert.equal('output' in rejected, false);
 });
 test('uses default local learning through the registered MCP tools', async () => {
     const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-server-'));
@@ -42,13 +76,26 @@ test('uses default local learning through the registered MCP tools', async () =>
         server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
         server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'hyv_verify', arguments: { original: 'I leverage the answer with useful detail and clear mechanism.', candidate: 'I use the answer with useful detail and clear mechanism.', profile_json: JSON.stringify(profile) } } })}\n`);
         server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'hyv_rewrite_prompt', arguments: { draft: 'I use the answer with useful detail and clear mechanism.', profile_json: JSON.stringify(profile) } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'hyv_analyze', arguments: { draft: 'A pattern I keep seeing in founder posts is vague advice.\u200B', profile_json: JSON.stringify(profile), writing_brief_json: JSON.stringify({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' }) } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 5, method: 'tools/call', params: { name: 'hyv_batch_analyze', arguments: { drafts: ['The launch needs a clear owner.', 'The launch needs a clear owner.'] } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 6, method: 'tools/call', params: { name: 'hyv_analyze', arguments: { draft: 'Plain draft.', profile_json: JSON.stringify(profile), writing_brief_json: '{' } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 7, method: 'tools/call', params: { name: 'hyv_hygiene', arguments: { draft: 'Plain\u200B draft.' } } })}\n`);
         server.stdin.end();
         const [code] = await once(server, 'close');
         assert.equal(stderr, '');
         assert.equal(code, 0);
         const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
         const prompt = JSON.parse(responses.find((response) => response.id === 3)?.result?.content?.[0]?.text ?? '{}').prompt;
+        const contextual = JSON.parse(responses.find((response) => response.id === 4)?.result?.content?.[0]?.text ?? '{}');
+        const batch = JSON.parse(responses.find((response) => response.id === 5)?.result?.content?.[0]?.text ?? '{}');
+        const malformed = responses.find((response) => response.id === 6)?.result;
+        const hygiene = JSON.parse(responses.find((response) => response.id === 7)?.result?.content?.[0]?.text ?? '{}');
         assert.match(prompt, /Learned local preferences/);
+        assert.equal(contextual.editorial.findings[0].id, 'editorial.social.generic-opener');
+        assert.equal(contextual.hygiene.suspiciousCount, 1);
+        assert.deepEqual(batch.findings.map((finding) => finding.id), ['batch.repeated-opening', 'batch.repeated-ending']);
+        assert.equal(malformed?.isError, true);
+        assert.equal(hygiene.suspiciousCount, 1);
         const stored = readFileSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`), 'utf8');
         assert.match(stored, /ai\.leverage/);
         assert.doesNotMatch(stored, /I leverage the answer/);