@holdyourvoice/hyv 3.1.1 → 3.2.0

package/dist/cli.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync } from 'node:fs';
-import { rules, RULESET_VERSION } from './ai-editor.js';
+import { linkSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { RULESET_VERSION, serializedRules } from './ai-editor.js';
 import { parseCopySpec } from './copy-spec.js';
 import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
 import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { cleanHygiene, finalOutputCheck, inspectHygiene } from './hygiene.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';
-const usage = 'Commands: profile, analyze, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, verify, verify-spec, learning, patterns, mcp';
+const usage = 'Commands: profile, analyze, hygiene, final-check, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, verify, verify-spec, learning, patterns, mcp';
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
@@ -70,6 +72,58 @@ function profileArguments(args) {
         throw new Error('Usage: hyv profile profile.json sample-a.md sample-b.md [sample-c.md] [--avoid=phrase]');
     return { output, samples, avoid };
 }
+function cleanedPath(path) {
+    const extension = extname(path);
+    const stem = extension ? path.slice(0, -extension.length) : path;
+    return `${stem}.cleaned${extension}`;
+}
+function hygieneArguments(args) {
+    const [path, ...options] = args;
+    if (!path)
+        throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    let fix = false;
+    let output;
+    for (const option of options) {
+        if (option === '--fix')
+            fix = true;
+        else if (option.startsWith('--output='))
+            output = option.slice('--output='.length).trim();
+        else
+            throw new Error('Usage: hyv hygiene draft.md [--fix] [--output=cleaned.md]');
+    }
+    if (output !== undefined && (!output || !fix))
+        throw new Error('--output requires --fix and a non-empty path.');
+    return { path, fix, ...(output ? { output } : {}) };
+}
+function writeNewFileAtomically(path, text) {
+    const temporaryDirectory = mkdtempSync(join(dirname(resolve(path)), '.hyv-hygiene-'));
+    const temporaryPath = join(temporaryDirectory, 'cleaned');
+    let primaryError;
+    try {
+        writeFileSync(temporaryPath, text, 'utf8');
+        try {
+            linkSync(temporaryPath, path);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(code ?? ''))
+                throw error;
+            throw new Error(`Atomic hygiene output is not supported by this filesystem: ${path}`);
+        }
+    }
+    catch (error) {
+        primaryError = error.code === 'EEXIST' ? new Error(`Hygiene output already exists: ${path}`) : error;
+    }
+    try {
+        rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!primaryError)
+            console.error(`Warning: output was published, but temporary-file cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (primaryError)
+        throw primaryError;
+}
 export async function runCli(args) {
     const [command, ...rest] = args;
     if (command === 'profile') {
@@ -84,6 +138,37 @@ export async function runCli(args) {
         json(analyze(input(draft), readProfile(profilePath), readBrief(briefPath)));
         return 0;
     }
+    if (command === 'hygiene') {
+        const { path, fix, output } = hygieneArguments(rest);
+        if (fix && path === '-')
+            throw new Error('hyv hygiene --fix requires a file path so the original can be preserved.');
+        const text = input(path);
+        if (!fix) {
+            json(inspectHygiene(text));
+            return 0;
+        }
+        const outputPath = output ?? cleanedPath(path);
+        if (resolve(outputPath) === resolve(path))
+            throw new Error('Hygiene output must differ from the input path.');
+        const result = cleanHygiene(text);
+        writeNewFileAtomically(outputPath, result.cleaned);
+        json({ ...result.report, changed: result.changed, changes: result.changes, outputPath });
+        return 0;
+    }
+    if (command === 'final-check') {
+        const [path, ...options] = rest;
+        if (!path || options.length)
+            throw new Error('Usage: hyv final-check <path|->');
+        const result = finalOutputCheck(input(path));
+        if (!result.accepted) {
+            console.error(JSON.stringify(result, null, 2));
+            return 2;
+        }
+        if (result.changed)
+            console.error(JSON.stringify({ changed: true, changes: result.changes }, null, 2));
+        process.stdout.write(result.output);
+        return 0;
+    }
     if (command === 'batch-analyze') {
         if (rest.length < 2)
             throw new Error('Usage: hyv batch-analyze draft-a.md draft-b.md [draft-c.md]');
@@ -168,7 +253,7 @@ export async function runCli(args) {
         throw new Error('Usage: hyv learning <show|add|clear> profile.json [instruction]');
     }
     if (command === 'patterns') {
-        json({ version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) });
+        json({ version: RULESET_VERSION, rules: serializedRules() });
         return 0;
     }
     if (command === 'mcp') {

package/dist/cli.test.js

@@ -1,12 +1,13 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import test from 'node:test';
+import { patternsForMcp } from './mcp-tools.js';
 const cli = new URL('./cli.js', import.meta.url).pathname;
-function run(args, env = process.env) {
-    return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', env });
+function run(args, env = process.env, input) {
+    return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', env, input });
 }
 test('creates an explicit local avoid list and exposes the ruleset', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
@@ -27,6 +28,15 @@ test('creates an explicit local avoid list and exposes the ruleset', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('publishes the same normalized 145-rule catalog and version through CLI and MCP', () => {
+    const result = run(['patterns']);
+    assert.equal(result.status, 0, result.stderr);
+    const cliCatalog = JSON.parse(result.stdout);
+    const mcpCatalog = patternsForMcp();
+    assert.equal(cliCatalog.version, '2.9.24-static.2');
+    assert.equal(cliCatalog.rules.length, 145);
+    assert.deepEqual(cliCatalog, mcpCatalog);
+});
 test('runs contextual analysis and batch analysis without changing the profile contract', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
@@ -45,6 +55,7 @@ test('runs contextual analysis and batch analysis without changing the profile c
         assert.equal(run(['profile', profile, first, second]).status, 0);
         const contextual = JSON.parse(run(['analyze', draft, profile, brief]).stdout);
         assert.equal(contextual.editorial.findings[0].id, 'editorial.social.generic-opener');
+        assert.equal(contextual.hygiene.suspiciousCount, 0);
         const batch = JSON.parse(run(['batch-analyze', draft, duplicate]).stdout);
         assert.equal(batch.findings.length, 2);
         assert.equal(run(['prepare-rewrite', draft, profile, task, brief]).status, 0);
@@ -54,6 +65,66 @@ test('runs contextual analysis and batch analysis without changing the profile c
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('inspects and conservatively fixes Unicode hygiene without overwriting either file', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const draft = join(directory, 'draft.md');
+        const cleaned = join(directory, 'draft.cleaned.md');
+        const original = `\uFEFFkeep\u200Bthis\u00A0space\u200D`;
+        writeFileSync(draft, original);
+        const inspected = run(['hygiene', draft]);
+        assert.equal(inspected.status, 0, inspected.stderr);
+        const report = JSON.parse(inspected.stdout);
+        assert.equal(report.suspiciousCount, 4);
+        assert.equal(report.fixableCount, 1);
+        const fixed = run(['hygiene', draft, '--fix']);
+        assert.equal(fixed.status, 0, fixed.stderr);
+        const receipt = JSON.parse(fixed.stdout);
+        assert.equal(receipt.outputPath, cleaned);
+        assert.equal(receipt.changed, true);
+        assert.equal(receipt.changes.length, 1);
+        assert.equal(readFileSync(draft, 'utf8'), original);
+        assert.equal(readFileSync(cleaned, 'utf8'), `keep\u200Bthis\u00A0space\u200D`);
+        const custom = join(directory, 'review-copy.md');
+        const customFixed = run(['hygiene', draft, '--fix', `--output=${custom}`]);
+        assert.equal(customFixed.status, 0, customFixed.stderr);
+        assert.equal(JSON.parse(customFixed.stdout).outputPath, custom);
+        assert.equal(readFileSync(custom, 'utf8'), `keep\u200Bthis\u00A0space\u200D`);
+        const samePath = run(['hygiene', draft, '--fix', `--output=${draft}`]);
+        assert.equal(samePath.status, 1);
+        assert.match(samePath.stderr, /must differ from the input path/);
+        assert.equal(readFileSync(draft, 'utf8'), original);
+        const refused = run(['hygiene', draft, '--fix']);
+        assert.equal(refused.status, 1);
+        assert.match(refused.stderr, /already exists/);
+        assert.equal(readdirSync(directory).some((name) => name.startsWith('.hyv-hygiene-')), false);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('inspects stdin and refuses to clean it without a preservable input file', () => {
+    const inspected = run(['hygiene', '-'], process.env, 'one\u200Btwo');
+    assert.equal(inspected.status, 0, inspected.stderr);
+    assert.equal(JSON.parse(inspected.stdout).suspiciousCount, 1);
+    const refused = run(['hygiene', '-', '--fix'], process.env, 'one\u200Btwo');
+    assert.equal(refused.status, 1);
+    assert.match(refused.stderr, /requires a file path/);
+});
+test('gates final output from any producer without a voice profile', () => {
+    const clean = run(['final-check', '-'], process.env, 'exact output\n');
+    assert.equal(clean.status, 0, clean.stderr);
+    assert.equal(clean.stdout, 'exact output\n');
+    assert.equal(clean.stderr, '');
+    const bom = run(['final-check', '-'], process.env, '\uFEFFexact output');
+    assert.equal(bom.status, 0, bom.stderr);
+    assert.equal(bom.stdout, 'exact output');
+    assert.match(bom.stderr, /U\+FEFF/);
+    const unresolved = run(['final-check', '-'], process.env, 'Thai\u200Bboundary');
+    assert.equal(unresolved.status, 2);
+    assert.equal(unresolved.stdout, '');
+    assert.match(unresolved.stderr, /U\+200B/);
+});
 test('uses exit code 2 for a failed candidate gate and 1 for misuse', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {

package/dist/copy-spec.js

@@ -2,6 +2,15 @@ import { sentences } from './text.js';
 function normalized(value) {
     return value.toLowerCase().replace(/\s+/g, ' ').trim();
 }
+function escaped(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function atomMatches(value, atom) {
+    return new RegExp(`(?<![\\p{L}\\p{N}\\p{M}])${escaped(atom)}(?![\\p{L}\\p{N}\\p{M}])`, 'u').test(value);
+}
+function isAtom(value) {
+    return isText(value, 500) && /[\p{L}\p{N}]/u.test(normalized(value));
+}
 function isText(value, limit) {
     return typeof value === 'string' && value.trim().length > 0 && value.length <= limit;
 }
@@ -11,7 +20,8 @@ function isClaim(value) {
     const claim = value;
     return isText(claim.id, 100) && /^[A-Za-z0-9._-]+$/.test(claim.id)
         && isText(claim.text, 2_000) && isText(claim.evidence, 4_000)
-        && (claim.mutable === undefined || typeof claim.mutable === 'boolean');
+        && (claim.mutable === undefined || typeof claim.mutable === 'boolean')
+        && (claim.atoms === undefined || (Array.isArray(claim.atoms) && claim.atoms.length > 0 && claim.atoms.length <= 20 && claim.atoms.every(isAtom)));
 }
 export function parseCopySpec(value) {
     if (!value || typeof value !== 'object')
@@ -26,17 +36,34 @@ export function parseCopySpec(value) {
     return spec;
 }
 export function verifyClaims(candidate, spec) {
-    const draftSentences = sentences(candidate);
+    const draftSentences = sentences(candidate).map((sentence) => ({ ...sentence, normalizedText: normalized(sentence.text) }));
     const normalizedCandidate = normalized(candidate);
     const sentenceClaims = {};
     const failures = [];
     for (const claim of spec.claims) {
-        const claimText = normalized(claim.text);
-        const matching = draftSentences.filter((sentence) => normalized(sentence.text).includes(claimText));
-        for (const sentence of matching)
-            (sentenceClaims[sentence.index] ??= []).push(claim.id);
-        if (!claim.mutable && matching.length === 0) {
-            failures.push({ id: claim.id, code: 'missing_immutable_claim', message: `Immutable claim ${claim.id} is absent or changed.`, evidence: claim.evidence });
+        if (claim.atoms?.length) {
+            const atoms = claim.atoms.map(normalized);
+            const presentAtoms = new Set();
+            for (const sentence of draftSentences) {
+                if (atoms.some((atom) => atomMatches(sentence.normalizedText, atom))) {
+                    for (const atom of atoms)
+                        if (atomMatches(sentence.normalizedText, atom))
+                            presentAtoms.add(atom);
+                    (sentenceClaims[sentence.index] ??= []).push(claim.id);
+                }
+            }
+            const missingAtoms = atoms.filter((atom) => !presentAtoms.has(atom));
+            if (!claim.mutable && missingAtoms.length) {
+                failures.push({ id: claim.id, code: 'missing_immutable_atom', message: `Immutable claim ${claim.id} is missing atomic facts: ${missingAtoms.join(', ')}.`, evidence: claim.evidence });
+            }
+        }
+        else {
+            const claimText = normalized(claim.text);
+            const matching = draftSentences.filter((sentence) => sentence.normalizedText.includes(claimText));
+            for (const sentence of matching)
+                (sentenceClaims[sentence.index] ??= []).push(claim.id);
+            if (!claim.mutable && matching.length === 0)
+                failures.push({ id: claim.id, code: 'missing_immutable_claim', message: `Immutable claim ${claim.id} is absent or changed.`, evidence: claim.evidence });
         }
     }
     for (const claim of spec.prohibitedClaims ?? []) {

package/dist/editorial-packs.js

@@ -1,11 +1,18 @@
 import { paragraphs, sentences, words } from './text.js';
 const formats = ['general', 'social', 'deck', 'outreach', 'blog', 'audit', 'website'];
+const evidenceStatuses = ['primary', 'attributed', 'internal', 'unverified'];
 function isText(value, limit) {
     return typeof value === 'string' && value.trim().length > 0 && value.length <= limit;
 }
 function isTerms(value) {
     return Array.isArray(value) && value.length <= 100 && value.every((term) => isText(term, 200));
 }
+function isArgumentMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const map = value;
+    return isText(map.observation, 500) && isText(map.mechanism, 500) && isText(map.consequence, 500) && isText(map.readerValue, 500);
+}
 export function parseWritingBrief(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('WritingBrief must be a JSON object.');
@@ -14,17 +21,34 @@ export function parseWritingBrief(value) {
         || (brief.readerKnowsAuthor !== undefined && typeof brief.readerKnowsAuthor !== 'boolean')
         || (brief.vocabulary !== undefined && !isTerms(brief.vocabulary))
         || (brief.prohibitedTerms !== undefined && !isTerms(brief.prohibitedTerms))
-        || (brief.title !== undefined && !isText(brief.title, 500))) {
+        || (brief.title !== undefined && !isText(brief.title, 500))
+        || (brief.evidenceStatus !== undefined && !evidenceStatuses.includes(brief.evidenceStatus))
+        || (brief.argumentMap !== undefined && !isArgumentMap(brief.argumentMap))) {
         throw new Error('WritingBrief needs version "1", audience, intent, a known format, and optional bounded context fields.');
     }
     return brief;
 }
+function meaningfulTerms(value) {
+    return [...new Set(words(value.toLowerCase()).filter((word) => word.length > 3 && !['that', 'this', 'with', 'from', 'your', 'when', 'what', 'into', 'their'].includes(word)))];
+}
 function finding(id, severity, sentence, excerpt, reason, suggestion) {
     return { engine: 'editorial', id, severity, sentence, excerpt, reason, suggestion };
 }
 function formatFindings(text, draftSentences, brief) {
     const findings = [];
     const first = draftSentences[0];
+    if (brief.evidenceStatus === 'unverified' && first) {
+        findings.push(finding('editorial.evidence.unverified', 'yellow', first.index, first.text, 'The brief marks the source state as unverified.', 'Keep attribution explicit and verify the source before treating the claim as established.'));
+    }
+    if (brief.argumentMap && first) {
+        const expected = meaningfulTerms(brief.argumentMap.readerValue);
+        const draftWords = new Set(words(text.toLowerCase()));
+        const matchedTerms = expected.filter((term) => draftWords.has(term)).length;
+        const requiredTerms = expected.length === 1 ? 1 : Math.min(2, expected.length);
+        if (expected.length && matchedTerms < requiredTerms) {
+            findings.push(finding('editorial.argument-map.reader-value-missing', 'yellow', first.index, first.text, 'The draft does not carry a concrete reader-value cue from the brief.', 'Connect the observation to the operational consequence the reader can act on.'));
+        }
+    }
     if (brief.format === 'social') {
         for (const sentence of draftSentences) {
             if (/^(a pattern|a theme|something) i (keep )?(seeing|noticing)\b/i.test(sentence.text)) {

package/dist/editorial-packs.test.js

@@ -46,4 +46,49 @@ test('detects exact repeated openings and endings across a batch without judging
 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,4 +1,4 @@
-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';
@@ -6,6 +6,7 @@ import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.j
 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));
@@ -38,6 +39,12 @@ export function buildProfileForMcp(samples, avoid = []) {
 export function analyzeForMcp(draft, profileJson, writingBriefJson) {
     return analyze(draft, profileFromJson(profileJson), writingBriefFromJson(writingBriefJson));
 }
+export function inspectHygieneForMcp(draft) {
+    return inspectHygiene(draft);
+}
+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), writingBriefFromJson(writingBriefJson)) };
@@ -59,7 +66,7 @@ export function verifyCopySpecForMcp(original, candidate, profileJson, copySpecJ
     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);