@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/cli.test.js

@@ -1,12 +1,30 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, 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 { createHash, generateKeyPairSync, sign } from 'node:crypto';
 import test from 'node:test';
+import { patternsForMcp } from './mcp-tools.js';
+import { canonicalJson } from './canonical-json.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 });
+}
+function installedContextEnvironment(root, context) {
+    const home = join(root, 'home');
+    const config = join(home, '.config', 'holdyourvoice');
+    mkdirSync(config, { recursive: true, mode: 0o700 });
+    const contextPath = join(config, 'approval-context.json');
+    writeFileSync(contextPath, canonicalJson(context), { mode: 0o600 });
+    chmodSync(contextPath, 0o600);
+    const fakeOs = join(root, 'fake-os.mjs');
+    const hooks = join(root, 'hooks.mjs');
+    const register = join(root, 'register.mjs');
+    writeFileSync(fakeOs, `import * as actual from 'node:os'; export const userInfo = () => ({ ...actual.userInfo(), homedir: process.env.HYV_TEST_HOME });\n`);
+    writeFileSync(hooks, `export async function resolve(specifier, context, nextResolve) { if (specifier === 'node:os' && context.parentURL?.endsWith('/approval-context.js')) return { url: new URL('./fake-os.mjs', import.meta.url).href, shortCircuit: true }; return nextResolve(specifier, context); }\n`);
+    writeFileSync(register, `import { register } from 'node:module'; register(new URL('./hooks.mjs', import.meta.url));\n`);
+    return { ...process.env, NODE_NO_WARNINGS: '1', NODE_OPTIONS: `--import=${register}`, HYV_TEST_HOME: home };
 }
 test('creates an explicit local avoid list and exposes the ruleset', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
@@ -27,6 +45,15 @@ test('creates an explicit local avoid list and exposes the ruleset', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('publishes the same normalized reconciled 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, '3.2.0-reconciled.1');
+    assert.equal(cliCatalog.rules.length, 148);
+    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 +72,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 +82,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 {
@@ -126,6 +214,96 @@ test('prepares and applies the same constrained rewrite task without a provider
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('prepares and reduces pre-edit judgment envelopes through CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-judgment-'));
+    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');
+        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.');
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+            const taskPath = join(directory, `${kind}.json`);
+            assert.equal(run(['prepare-judgment', 'pre-edit', kind, draft, profile, taskPath]).status, 0);
+            const task = JSON.parse(readFileSync(taskPath, 'utf8'));
+            const envelopePath = join(directory, `${kind}-envelope.json`);
+            writeFileSync(envelopePath, JSON.stringify({
+                version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: task.taskFingerprint,
+                bindings: { ...task.bindings, evaluatorId: 'writer.1' }, findings: [], decision: 'SHIP',
+            }));
+            return envelopePath;
+        });
+        const result = run(['reduce-judgment', ...envelopes]);
+        assert.equal(result.status, 0, result.stderr);
+        assert.equal(JSON.parse(result.stdout).decision, 'SHIP');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares, submits, and inspects a normal lifecycle through CLI canonical envelopes', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-lifecycle-'));
+    try {
+        const deterministicBase = { version: '1', verificationKind: 'standard', passed: true, analysisVersion: '2', rulesetVersion: '3.2.0', preservationMetricVersion: 'legacy-set-v1', preservationScore: 100, sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64), regressionKeys: [] };
+        const deterministic = { ...deterministicBase, artifactFingerprint: createHash('sha256').update(`hyv:deterministic-verification:v1\0${canonicalJson(deterministicBase)}`).digest('hex') };
+        const binding = { rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: deterministic.artifactFingerprint, sourceHash: deterministic.sourceHash, candidateHash: deterministic.candidateHash, profileId: deterministic.profileId, profileRevisionDigest: deterministic.profileRevisionDigest, rulesetVersion: deterministic.rulesetVersion, schemaVersion: '1' };
+        const receipt = { version: '1', taskFingerprint: binding.rewriteTaskFingerprint, responseFingerprint: binding.rewriteResponseFingerprint, adapterIds: [], replacementSentenceIds: [1] };
+        const paths = Object.fromEntries(['deterministic', 'binding', 'receipt', 'violations', 'output', 'artifact', 'task', 'verdict'].map((name) => [name, join(directory, `${name}.json`)]));
+        writeFileSync(paths.deterministic, JSON.stringify(deterministic));
+        writeFileSync(paths.binding, JSON.stringify(binding));
+        writeFileSync(paths.receipt, JSON.stringify(receipt));
+        writeFileSync(paths.violations, JSON.stringify(['action_change']));
+        const prepared = run(['lifecycle', 'prepare-semantic', paths.deterministic, paths.binding, paths.receipt, 'normal', paths.violations, paths.output]);
+        assert.equal(prepared.status, 0, prepared.stderr);
+        const envelope = JSON.parse(prepared.stdout);
+        assert.equal(envelope.artifact.status, 'needs_semantic_review');
+        assert.deepEqual(JSON.parse(readFileSync(paths.output, 'utf8')), envelope);
+        writeFileSync(paths.artifact, JSON.stringify(envelope.artifact));
+        writeFileSync(paths.task, JSON.stringify(envelope.task));
+        writeFileSync(paths.verdict, JSON.stringify({ approved: true, violations: [] }));
+        const context = { now: 0, trustStore: { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] }, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+        const submitted = run(['lifecycle', 'submit-verdict', paths.artifact, paths.task, 'reviewer-1', paths.verdict], installedContextEnvironment(directory, context));
+        assert.equal(submitted.status, 0, submitted.stderr);
+        assert.equal(JSON.parse(submitted.stdout).status, 'ready_for_human_review');
+        const inspected = run(['lifecycle', 'inspect', paths.artifact]);
+        assert.equal(inspected.status, 0, inspected.stderr);
+        assert.equal(JSON.parse(inspected.stdout).status, 'needs_semantic_review');
+        assert.doesNotMatch(inspected.stdout, /sourceHash|candidateHash|verdicts/);
+        assert.equal(run(['lifecycle', 'prepare-semantic', paths.deterministic, paths.binding, paths.receipt, 'high_assurance', paths.violations, join(directory, 'high.json')]).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('accepts only one bounded capability transport and treats a file named stdin literally', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-capability-'));
+    try {
+        const capability = JSON.stringify({ payload: 'secret-payload', signature: 'secret-signature' });
+        const literal = join(directory, 'stdin');
+        writeFileSync(literal, capability, { mode: 0o600 });
+        const literalResult = spawnSync(process.execPath, [cli, 'lifecycle', 'validate-final-approval', 'missing.json', '--capability-file', 'stdin'], { cwd: directory, encoding: 'utf8' });
+        assert.equal(literalResult.status, 1);
+        assert.doesNotMatch(literalResult.stderr, /Capability file is unavailable or unsafe|secret-payload|secret-signature/);
+        chmodSync(literal, 0o644);
+        const unsafe = spawnSync(process.execPath, [cli, 'lifecycle', 'validate-final-approval', 'missing.json', '--capability-file', 'stdin'], { cwd: directory, encoding: 'utf8' });
+        assert.equal(unsafe.status, 1);
+        assert.match(unsafe.stderr, /Capability file is unavailable or unsafe/);
+        assert.doesNotMatch(unsafe.stderr, /secret-payload|secret-signature/);
+        const duplicate = run(['lifecycle', 'validate-final-approval', 'missing.json', '--capability-stdin', '--capability-file', literal], process.env, capability);
+        assert.equal(duplicate.status, 1);
+        assert.match(duplicate.stderr, /Choose one capability source/);
+        assert.doesNotMatch(duplicate.stderr, /secret-payload|secret-signature/);
+        const oversized = run(['lifecycle', 'validate-final-approval', 'missing.json', '--capability-stdin'], process.env, 'x'.repeat(1024 * 1024 + 1));
+        assert.equal(oversized.status, 1);
+        assert.match(oversized.stderr, /exceeds the byte limit/);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
 test('rejects a malformed hand-edited profile before analysis', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
@@ -194,7 +372,7 @@ test('rejects hand-edited metrics outside their semantic bounds', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
-test('learns from a successful local verification by default and exposes local controls', () => {
+test('keeps verification read-only and exposes learning only through explicit controls', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
         const first = join(directory, 'first.md');
@@ -211,11 +389,10 @@ test('learns from a successful local verification by default and exposes local c
         assert.equal(run(['verify', original, candidate, profile], env).status, 0);
         const brief = run(['rewrite-prompt', candidate, profile], env);
         assert.equal(brief.status, 0, brief.stderr);
-        assert.match(brief.stdout, /Learned local preferences/);
-        assert.match(brief.stdout, /ai\\_editor\/ai\.leverage/);
+        assert.doesNotMatch(brief.stdout, /Learned local preferences/);
         const learned = run(['learning', 'show', profile], env);
         assert.equal(learned.status, 0, learned.stderr);
-        assert.ok(JSON.parse(learned.stdout).preferences.some((item) => item.text.includes('ai_editor/ai.leverage')));
+        assert.deepEqual(JSON.parse(learned.stdout).preferences, []);
         assert.equal(run(['learning', 'clear', profile], env).status, 0);
         assert.deepEqual(JSON.parse(run(['learning', 'show', profile], env).stdout).preferences, []);
     }
@@ -223,3 +400,94 @@ test('learns from a successful local verification by default and exposes local c
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('records and inspects text-free learning metadata through the CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-learning-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const env = { ...process.env, HYV_HOME: join(directory, 'state') };
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        assert.equal(run(['profile', profile, first, second]).status, 0);
+        const recorded = run(['learning', 'record', profile, 'Keep the mechanism concrete.', '--authority=founder', '--provenance=editor-review', '--weight=2', '--compatibility=exact', '--mutation-id=cli-1'], env);
+        assert.equal(recorded.status, 0, recorded.stderr);
+        assert.equal(JSON.parse(recorded.stdout).mutationId, 'cli-1');
+        assert.equal(JSON.parse(run(['learning', 'record', profile, 'Different instruction.', '--mutation-id=cli-1'], env).stdout).status, 'conflict');
+        const inspected = run(['learning', 'inspect', profile], env);
+        assert.equal(inspected.status, 0, inspected.stderr);
+        assert.equal(JSON.parse(inspected.stdout)[0].authority, 'founder');
+        assert.doesNotMatch(inspected.stdout, /Keep the mechanism concrete/);
+        assert.equal(run(['learning', 'ratify', profile, JSON.parse(recorded.stdout).eventId], env).status, 1);
+        assert.equal(run(['learning', 'record', profile, 'Boundary.', `--mutation-id=${'m'.repeat(200)}`, `--provenance=${'p'.repeat(500)}`], env).status, 0);
+        assert.equal(run(['learning', 'record', profile, 'Too long.', `--mutation-id=${'m'.repeat(201)}`], env).status, 1);
+        assert.equal(run(['learning', 'record', profile, 'Too long.', `--provenance=${'p'.repeat(501)}`], env).status, 1);
+        assert.equal(run(['learning', 'inspect', profile, '--mutation-id=nope'], env).status, 1);
+        assert.equal(run(['learning', 'clear', profile, '--authority=team'], env).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares and applies an authorized rebuild through CLI', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-rebuild-'));
+    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 spec = join(directory, 'copy-spec.json');
+        const reduction = join(directory, 'reduction.json');
+        const task = join(directory, 'rebuild-task.json');
+        const response = join(directory, 'response.json');
+        const capability = join(directory, 'capability.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. The launch is on 14 August.');
+        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, 7 August.' }] }));
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        const envelopes = ['triage', 'argument', 'form'].map((kind) => {
+            const taskPath = join(directory, `${kind}.json`);
+            assert.equal(run(['prepare-judgment', 'pre-edit', kind, draft, profile, taskPath]).status, 0);
+            const prepared = JSON.parse(readFileSync(taskPath, 'utf8'));
+            const envelopePath = join(directory, `${kind}-envelope.json`);
+            writeFileSync(envelopePath, JSON.stringify({
+                version: '1', stage: 'pre-edit', judgmentType: kind, taskFingerprint: prepared.taskFingerprint,
+                bindings: { ...prepared.bindings, evaluatorId: 'writer.1' }, findings: [], decision: kind === 'argument' ? 'REBUILD' : 'SHIP',
+            }));
+            return envelopePath;
+        });
+        const reduced = run(['reduce-judgment', ...envelopes]);
+        assert.equal(reduced.status, 0, reduced.stderr);
+        writeFileSync(reduction, reduced.stdout);
+        const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+        const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host.example', keyId: 'key-1', publicKeySpki: publicKey.export({ type: 'spki', format: 'der' }).toString('base64url'), status: 'active' }] };
+        const context = { now: 0, trustStore, authorizedSemanticEvaluatorIds: { normal: [], highAssurance: [] }, authorizedHumanFinalizerIds: [] };
+        const env = installedContextEnvironment(directory, context);
+        const sourceHash = createHash('sha256').update(readFileSync(draft)).digest('hex');
+        const profileValue = JSON.parse(readFileSync(profile, 'utf8'));
+        const identity = `legacy-v2:${createHash('sha256').update(canonicalJson(profileValue)).digest('hex')}`;
+        const claims = {
+            version: '1', purpose: 'hyv.rebuild-authorization', issuer: 'host.example', audience: '@holdyourvoice/hyv',
+            subjectArtifactFingerprint: JSON.parse(reduced.stdout).recommendationFingerprint, sourceHash, candidateHash: sourceHash,
+            profileId: identity, profileRevisionDigest: identity, keyId: 'key-1', issuedAt: Math.floor(Date.now() / 1000) - 1,
+            notBefore: Math.floor(Date.now() / 1000) - 1, expiresAt: Math.floor(Date.now() / 1000) + 120, nonce: 'cli-rebuild',
+        };
+        const payload = Buffer.from(canonicalJson(claims));
+        writeFileSync(capability, canonicalJson({ payload: payload.toString('base64url'), signature: sign(null, payload, privateKey).toString('base64url') }));
+        chmodSync(capability, 0o600);
+        const prepared = run(['prepare-rebuild', draft, profile, reduction, spec, task, '--capability-file', capability], env);
+        assert.equal(prepared.status, 0, prepared.stderr);
+        writeFileSync(response, JSON.stringify({
+            version: '1', mode: 'REBUILD', taskFingerprint: JSON.parse(readFileSync(task, 'utf8')).fingerprint,
+            candidate: 'Ship planning now treats one calendar fact as fixed. The launch is on 14 August. Every other sentence in this note is new operational language for the release desk.',
+        }));
+        const applied = run(['apply-rebuild', task, response, profile, '--capability-file', capability], env);
+        assert.equal(applied.status, 2, applied.stderr);
+        assert.equal(JSON.parse(applied.stdout).status, 'needs_semantic_review');
+        assert.equal(run(['apply-rebuild', task, response, profile], env).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

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,91 @@
+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 hygieneSourceFindings(text) {
+    return inspectHygiene(text).hits.flatMap((hit) => hit.offsets.map((start) => {
+        const character = String.fromCodePoint(text.codePointAt(start));
+        return { kind: 'hygiene', start, end: start + character.length, codepoint: hit.codepoint, eligible: hit.fix === 'remove' };
+    }));
+}
+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 };
+}