@holdyourvoice/hyv 3.1.0 → 3.2.0

package/dist/cli.js

@@ -1,17 +1,55 @@
 #!/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 { analyze, rewritePrompt, verify } from './pipeline.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, rewrite-prompt, verify, 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');
 }
 function readProfile(path) {
     return parseProfile(JSON.parse(input(path)));
 }
+function readBrief(path) {
+    return path ? parseWritingBrief(JSON.parse(input(path))) : undefined;
+}
+function prepareContext(paths) {
+    let copySpec;
+    let writingBrief;
+    for (const path of paths) {
+        const value = JSON.parse(input(path));
+        try {
+            const parsed = parseCopySpec(value);
+            if (copySpec)
+                throw new Error('Prepare-rewrite accepts at most one CopySpec.');
+            copySpec = parsed;
+            continue;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'Prepare-rewrite accepts at most one CopySpec.')
+                throw error;
+        }
+        try {
+            const parsed = parseWritingBrief(value);
+            if (writingBrief)
+                throw new Error('Prepare-rewrite accepts at most one WritingBrief.');
+            writingBrief = parsed;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'Prepare-rewrite accepts at most one WritingBrief.')
+                throw error;
+            throw new Error(`Expected a valid CopySpec or WritingBrief at ${path}.`);
+        }
+    }
+    return { copySpec, writingBrief };
+}
 function json(value) {
     console.log(JSON.stringify(value, null, 2));
 }
@@ -34,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') {
@@ -42,34 +132,104 @@ export async function runCli(args) {
         return 0;
     }
     if (command === 'analyze') {
-        const [draft, profilePath] = rest;
+        const [draft, profilePath, briefPath] = rest;
         if (!draft || !profilePath)
-            throw new Error('Usage: hyv analyze draft.md profile.json');
-        json(analyze(input(draft), readProfile(profilePath)));
+            throw new Error('Usage: hyv analyze draft.md profile.json [writing-brief.json]');
+        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]');
+        json(analyzeBatch(rest.map(input)));
         return 0;
     }
     if (command === 'rewrite-prompt') {
-        const [draft, profilePath] = rest;
+        const [draft, profilePath, briefPath] = rest;
         if (!draft || !profilePath)
-            throw new Error('Usage: hyv rewrite-prompt draft.md profile.json');
+            throw new Error('Usage: hyv rewrite-prompt draft.md profile.json [writing-brief.json]');
         const profile = readProfile(profilePath);
-        console.log(rewritePrompt(input(draft), profile, composeLearning(profile)));
+        console.log(rewritePrompt(input(draft), profile, composeLearning(profile), readBrief(briefPath)));
         return 0;
     }
+    if (command === 'prepare-rewrite') {
+        const [draft, profilePath, output, ...contextPaths] = rest;
+        if (!draft || !profilePath || !output)
+            throw new Error('Usage: hyv prepare-rewrite draft.md profile.json task.json [copy-spec.json] [writing-brief.json]');
+        const context = prepareContext(contextPaths);
+        const task = prepareRewriteTask(input(draft), readProfile(profilePath), context.copySpec, context.writingBrief);
+        writeFileSync(output, `${JSON.stringify(task, null, 2)}\n`);
+        json({ version: task.version, fingerprint: task.fingerprint, eligibleSentenceIds: task.eligibleSentenceIds });
+        return 0;
+    }
+    if (command === 'apply-rewrite') {
+        const [taskPath, responsePath, profilePath] = rest;
+        if (!taskPath || !responsePath || !profilePath)
+            throw new Error('Usage: hyv apply-rewrite task.json response.json profile.json');
+        const result = evaluateRewriteResponse(parseRewriteTask(JSON.parse(input(taskPath))), input(responsePath), readProfile(profilePath));
+        json(result);
+        return result.status === 'accepted' ? 0 : 2;
+    }
     if (command === 'verify') {
-        const [original, candidate, profilePath] = rest;
+        const [original, candidate, profilePath, briefPath] = rest;
         if (!original || !candidate || !profilePath)
-            throw new Error('Usage: hyv verify original.md candidate.md profile.json');
+            throw new Error('Usage: hyv verify original.md candidate.md profile.json [writing-brief.json]');
         const profile = readProfile(profilePath);
         const originalText = input(original);
         const candidateText = input(candidate);
-        const result = verify(originalText, candidateText, profile);
+        const result = verify(originalText, candidateText, profile, readBrief(briefPath));
         const learning = recordVerifiedCandidate(profile, result, candidateText);
         if (learning === 'write_failed')
             console.error('Warning: verification passed, but local learning could not be saved.');
         json(result);
         return result.passed ? 0 : 2;
     }
+    if (command === 'verify-spec') {
+        const [original, candidate, profilePath, specPath, briefPath] = rest;
+        if (!original || !candidate || !profilePath || !specPath)
+            throw new Error('Usage: hyv verify-spec original.md candidate.md profile.json copy-spec.json [writing-brief.json]');
+        const profile = readProfile(profilePath);
+        const candidateText = input(candidate);
+        const result = verifyWithCopySpec(input(original), candidateText, profile, parseCopySpec(JSON.parse(input(specPath))), readBrief(briefPath));
+        if (result.passed) {
+            const learning = recordVerifiedCandidate(profile, result, candidateText);
+            if (learning === 'write_failed')
+                console.error('Warning: verification passed, but local learning could not be saved.');
+        }
+        json(result);
+        return result.passed ? 0 : 2;
+    }
     if (command === 'learning') {
         const [action, profilePath, ...instruction] = rest;
         if (!action || !profilePath)
@@ -93,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,103 @@ 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 {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const brief = join(directory, 'brief.json');
+        const draft = join(directory, 'draft.md');
+        const duplicate = join(directory, 'duplicate.md');
+        const task = join(directory, 'task.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(brief, JSON.stringify({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' }));
+        writeFileSync(draft, 'A pattern I keep seeing in founder posts is vague advice.');
+        writeFileSync(duplicate, 'A pattern I keep seeing in founder posts is vague advice.');
+        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);
+        assert.equal(JSON.parse(readFileSync(task, 'utf8')).writingBrief.format, 'social');
+    }
+    finally {
+        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 {
@@ -50,6 +148,55 @@ test('uses exit code 2 for a failed candidate gate and 1 for misuse', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('fails the CopySpec gate when a locked claim changes', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const original = join(directory, 'original.md');
+        const candidate = join(directory, 'candidate.md');
+        const spec = join(directory, 'copy-spec.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(original, 'The launch is on 14 August.');
+        writeFileSync(candidate, 'The launch is next month.');
+        writeFileSync(spec, 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(run(['profile', profile, first, second]).status, 0);
+        const result = run(['verify-spec', original, candidate, profile, spec]);
+        assert.equal(result.status, 2);
+        assert.equal(JSON.parse(result.stdout).claims.failures[0].code, 'missing_immutable_claim');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares and applies the same constrained rewrite task without a provider call', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const draft = join(directory, 'draft.md');
+        const task = join(directory, 'task.json');
+        const response = join(directory, 'response.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(draft, 'I leverage the answer with useful detail and clear mechanism.');
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        assert.equal(run(['prepare-rewrite', draft, profile, task]).status, 0);
+        const prepared = JSON.parse(readFileSync(task, 'utf8'));
+        writeFileSync(response, JSON.stringify({ version: '1', taskFingerprint: prepared.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer with useful detail and clear mechanism.' }] }));
+        const result = run(['apply-rewrite', task, response, profile]);
+        assert.equal(result.status, 2, result.stderr);
+        const applied = JSON.parse(result.stdout);
+        assert.equal(applied.status, 'needs_semantic_review');
+        assert.equal(applied.candidate, 'I use the answer with useful detail and clear mechanism.');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
 test('rejects a malformed hand-edited profile before analysis', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {

package/dist/copy-spec.js

@@ -0,0 +1,75 @@
+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;
+}
+function isClaim(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    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.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')
+        throw new Error('CopySpec must be a JSON object.');
+    const spec = value;
+    if (spec.version !== '1' || !isText(spec.audience, 500) || !isText(spec.intent, 500) || !isText(spec.channel, 100)
+        || !Array.isArray(spec.claims) || spec.claims.length === 0 || spec.claims.length > 100 || !spec.claims.every(isClaim)
+        || new Set(spec.claims.map((claim) => claim.id)).size !== spec.claims.length
+        || (spec.prohibitedClaims !== undefined && (!Array.isArray(spec.prohibitedClaims) || spec.prohibitedClaims.length > 100 || !spec.prohibitedClaims.every((claim) => isText(claim, 2_000))))) {
+        throw new Error('CopySpec is not valid. It needs version "1", audience, intent, channel, unique claims with text and evidence, and optional prohibitedClaims.');
+    }
+    return spec;
+}
+export function verifyClaims(candidate, spec) {
+    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) {
+        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 ?? []) {
+        if (normalizedCandidate.includes(normalized(claim))) {
+            failures.push({ id: claim, code: 'prohibited_claim', message: `Prohibited claim appears in the candidate: ${claim}` });
+        }
+    }
+    return { passed: failures.length === 0, failures, sentenceClaims };
+}

package/dist/editorial-packs.js

@@ -0,0 +1,126 @@
+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.');
+    const brief = value;
+    if (brief.version !== '1' || !isText(brief.audience, 500) || !isText(brief.intent, 500) || !formats.includes(brief.format)
+        || (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.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)) {
+                findings.push(finding('editorial.social.generic-opener', 'yellow', sentence.index, sentence.text, 'Uses a generic observation opener that often reads as templated.', 'Open from the concrete observation or claim instead.'));
+            }
+        }
+        const draftParagraphs = paragraphs(text);
+        const allSingleSentence = draftParagraphs.length >= 3 && draftParagraphs.every((paragraph) => sentences(paragraph).length === 1);
+        if (allSingleSentence && first)
+            findings.push(finding('editorial.social.one-line-run', 'yellow', first.index, first.text, 'Every paragraph contains one sentence.', 'Combine related sentences where the writing needs a fuller rhythm.'));
+    }
+    if (brief.format === 'deck') {
+        if (first && /^we\b/i.test(first.text))
+            findings.push(finding('editorial.deck.first-slide-we', 'yellow', first.index, first.text, 'The opening starts with the company rather than the reader or claim.', 'Lead with the reader context or the slide claim.'));
+        if (brief.title && /^\s*\d/.test(brief.title))
+            findings.push(finding('editorial.deck.numeric-title', 'yellow', 1, brief.title, 'The title starts with a number.', 'State the slide claim without leading with a count.'));
+    }
+    if (brief.format === 'outreach') {
+        for (const sentence of draftSentences) {
+            if (/\b(would you be open to|does that sound interesting|what do you think)\??$/i.test(sentence.text)) {
+                findings.push(finding('editorial.outreach.generic-question-cta', 'yellow', sentence.index, sentence.text, 'Uses a stock outbound question CTA.', 'Close with a specific next step or a direct observation.'));
+            }
+        }
+    }
+    return findings;
+}
+export function analyzeEditorial(text, brief) {
+    const draftSentences = sentences(text);
+    const findings = formatFindings(text, draftSentences, brief);
+    const prohibitedTerms = (brief.prohibitedTerms ?? []).map((term) => [term, normalizedWords(term)]).filter(([, term]) => term);
+    for (const sentence of draftSentences) {
+        const normalizedSentence = normalizedWords(sentence.text);
+        for (const [term, normalizedTerm] of prohibitedTerms) {
+            if (normalizedTerm && ` ${normalizedSentence} `.includes(` ${normalizedTerm} `)) {
+                findings.push(finding('editorial.prohibited-term', 'red', sentence.index, sentence.text, `Uses prohibited term: ${term}.`, 'Remove the term or replace it with approved wording.'));
+            }
+        }
+    }
+    const red = findings.filter((item) => item.severity === 'red').length;
+    const yellow = findings.length - red;
+    return { engine: 'editorial', version: '1', score: Math.max(0, 100 - red * 25 - yellow * 6), passed: red === 0, findings };
+}
+function normalizedWords(text) {
+    return words(text.toLowerCase()).join(' ');
+}
+function normalizedBoundary(text) {
+    if (!text)
+        return undefined;
+    const normalized = normalizedWords(text);
+    return normalized || undefined;
+}
+function duplicateBoundary(id, boundaries, reason, suggestion) {
+    const groups = new Map();
+    boundaries.forEach((boundary, index) => {
+        if (boundary) {
+            const indexes = groups.get(boundary) ?? [];
+            indexes.push(index + 1);
+            groups.set(boundary, indexes);
+        }
+    });
+    return [...groups.values()].filter((indexes) => indexes.length > 1).map((draftIndexes) => ({ id, severity: 'yellow', draftIndexes, reason, suggestion }));
+}
+export function analyzeBatch(drafts) {
+    if (drafts.length < 2 || drafts.length > 100 || drafts.some((draft) => !isText(draft, 100_000)))
+        throw new Error('Batch analysis needs 2 to 100 non-empty drafts.');
+    const parsed = drafts.map(sentences);
+    return {
+        version: '1',
+        findings: [
+            ...duplicateBoundary('batch.repeated-opening', parsed.map((draft) => normalizedBoundary(draft[0]?.text)), 'Drafts share the same opening sentence.', 'Vary the opening shape or lead with a different concrete observation.'),
+            ...duplicateBoundary('batch.repeated-ending', parsed.map((draft) => normalizedBoundary(draft.at(-1)?.text)), 'Drafts share the same closing sentence.', 'Give each draft a closing beat that fits its own argument.'),
+        ],
+        passed: true,
+    };
+}