@holdyourvoice/hyv 3.4.5 → 3.5.0

package/dist/rule-allowances.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import { SAMPLE_ALLOWANCE_RULE_IDS } from './profile.js';
+const RULE_MATCHERS = {
+    'punct.em-dash': /—/u,
+    'punct.en-dash': /–/u,
+    'format.curly-quotes': /[“”]/u,
+};
+function evidenceDigest(ruleId, samples) {
+    const evidence = samples
+        .filter((sample) => RULE_MATCHERS[ruleId].test(sample))
+        .map((sample) => sample.replace(/\s+/gu, ' ').trim())
+        .sort();
+    return createHash('sha256').update(JSON.stringify({ ruleId, evidence })).digest('hex');
+}
+/**
+ * Returns only non-verbatim evidence for stylistic exceptions shown in two or
+ * more author-owned samples. Callers add the result to a signed Profile v3.
+ */
+export function deriveRuleAllowances(samples) {
+    const allowances = {};
+    for (const ruleId of SAMPLE_ALLOWANCE_RULE_IDS) {
+        const count = samples.filter((sample) => RULE_MATCHERS[ruleId].test(sample)).length;
+        if (count >= 2)
+            allowances[ruleId] = { sampleCount: count, evidenceDigest: evidenceDigest(ruleId, samples) };
+    }
+    return allowances;
+}

package/dist/rule-allowances.test.js

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { deriveRuleAllowances } from './rule-allowances.js';
+test('derives only non-verbatim style allowances from repeated sample evidence', () => {
+    const allowances = deriveRuleAllowances([
+        'I write this way — with a deliberate turn.',
+        'The point is direct — then I explain it.',
+        'The note says “ship Tuesday” after the check.',
+        'The runbook repeats “ship Tuesday” as a decision.',
+        'A plain sample has no allowance.',
+    ]);
+    assert.deepEqual(Object.keys(allowances), ['punct.em-dash', 'format.curly-quotes']);
+    assert.equal(allowances['punct.em-dash'].sampleCount, 2);
+    assert.match(allowances['punct.em-dash'].evidenceDigest, /^[a-f0-9]{64}$/);
+    assert.equal(allowances['format.curly-quotes'].sampleCount, 2);
+    assert.equal(JSON.stringify(allowances).includes('deliberate turn'), false);
+});

package/dist/sample-ingest.js

@@ -0,0 +1,94 @@
+import { createHash } from 'node:crypto';
+import { sentences } from './text.js';
+const EMPTY_REDACTIONS = { email: 0, phone: 0, card: 0, ip: 0, url: 0 };
+const REDACTORS = [
+    ['email', /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi],
+    ['phone', /(?<!\w)(?:\+?\d[\d .()/-]{7,}\d)(?!\w)/g],
+    ['card', /(?<!\d)(?:\d[ -]?){13,19}(?!\d)/g],
+    ['ip', /\b(?:\d{1,3}\.){3}\d{1,3}\b/g],
+    ['url', /\bhttps?:\/\/[^\s<>()]+/gi],
+];
+function digest(text) { return createHash('sha256').update(text).digest('hex'); }
+function textFromTelegram(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return '';
+    return value.map((part) => typeof part === 'string' ? part : part && typeof part === 'object' && typeof part.text === 'string' ? part.text : '').join('');
+}
+function decodeMboxBody(message) {
+    const body = message.replace(/^[\s\S]*?\r?\n\r?\n/, '');
+    return body.replace(/^>.*$/gm, '').replace(/=\r?\n/g, '').replace(/=([A-F0-9]{2})/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16))).trim();
+}
+function mboxMessages(source) {
+    return source.split(/^From .+$/m).slice(1).flatMap((part) => {
+        const from = part.match(/^From:\s*(.+)$/mi)?.[1]?.trim() ?? '';
+        const text = decodeMboxBody(part);
+        return from && text ? [{ owner: from, text }] : [];
+    });
+}
+function telegramMessages(source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new Error('Telegram Desktop export is not valid JSON.');
+    }
+    const values = parsed && typeof parsed === 'object' && Array.isArray(parsed.messages) ? parsed.messages : [];
+    return values.flatMap((value) => {
+        if (!value || typeof value !== 'object')
+            return [];
+        const message = value;
+        const owner = typeof message.from_id === 'string' ? message.from_id : typeof message.from === 'string' ? message.from : '';
+        const text = textFromTelegram(message.text);
+        return message.type === 'message' && owner && text ? [{ owner, text }] : [];
+    });
+}
+function containsBlockedWord(text, blockedWords) {
+    const lower = text.toLocaleLowerCase();
+    return blockedWords.some((word) => lower.includes(word.toLocaleLowerCase()));
+}
+function redact(text, counts) {
+    let output = text;
+    for (const [category, expression] of REDACTORS)
+        output = output.replace(expression, (value) => {
+            counts[category] += 1;
+            return '[REDACTED:' + category.toUpperCase() + ']';
+        });
+    return output;
+}
+function ingest(source, raw, messages, owner, blockedWords = []) {
+    if (!owner.trim())
+        throw new Error('Sample ingest requires an explicit owner identifier.');
+    if (blockedWords.some((word) => !word.trim()))
+        throw new Error('Blocked words must be non-empty.');
+    const redactions = { ...EMPTY_REDACTIONS };
+    let droppedSentences = 0;
+    const samples = [];
+    const accepted = messages.filter((message) => message.owner.toLocaleLowerCase() === owner.toLocaleLowerCase());
+    for (const message of accepted) {
+        const safe = sentences(message.text).flatMap((sentence) => {
+            if (containsBlockedWord(sentence.text, blockedWords)) {
+                droppedSentences += 1;
+                return [];
+            }
+            return [redact(sentence.text, redactions)];
+        }).join(' ').replace(/\s+/g, ' ').trim();
+        if (safe)
+            samples.push(safe);
+    }
+    return {
+        samples,
+        receipt: {
+            version: '1', source, sourceDigest: digest(raw), messagesSeen: messages.length, messagesAccepted: accepted.length, samplesAccepted: samples.length,
+            droppedSentences, redactions, presidio: 'NOT_CONFIGURED',
+        },
+    };
+}
+export function ingestGmailSentMbox(source, owner, blockedWords = []) {
+    return ingest('gmail-sent-mbox', source, mboxMessages(source), owner, blockedWords);
+}
+export function ingestTelegramDesktopJson(source, owner, blockedWords = []) {
+    return ingest('telegram-desktop-json', source, telegramMessages(source), owner, blockedWords);
+}

package/dist/sample-ingest.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ingestGmailSentMbox, ingestTelegramDesktopJson } from './sample-ingest.js';
+test('ingests only owner Gmail sent messages and redacts sensitive data before output', () => {
+    const mbox = [
+        'From sender@example.com Mon Jan 1 00:00:00 2026',
+        'From: Owner <owner@example.com>',
+        '',
+        'Call +1 415 555 0100 or owner@example.com. Secret client detail stays out.',
+        'From sender@example.com Mon Jan 2 00:00:00 2026',
+        'From: Other <other@example.com>',
+        '',
+        'This message must not become a sample.',
+    ].join('\n');
+    const result = ingestGmailSentMbox(mbox, 'Owner <owner@example.com>', ['secret client']);
+    assert.equal(result.samples.length, 1);
+    assert.match(result.samples[0], /REDACTED:PHONE/);
+    assert.match(result.samples[0], /REDACTED:EMAIL/);
+    assert.equal(result.samples[0].includes('Secret client'), false);
+    assert.equal(result.receipt.droppedSentences, 1);
+    assert.equal(JSON.stringify(result.receipt).includes('Secret client'), false);
+    assert.equal(JSON.stringify(result.receipt).includes('owner@example.com'), false);
+});
+test('ingests Telegram Desktop JSON by explicit owner and never places raw text in the receipt', () => {
+    const source = JSON.stringify({ messages: [
+            { type: 'message', from: 'Shashank', text: ['A link is ', { type: 'link', text: 'https://example.com/private' }, '.'] },
+            { type: 'message', from: 'Other', text: 'Ignore me.' },
+        ] });
+    const result = ingestTelegramDesktopJson(source, 'Shashank');
+    assert.equal(result.samples.length, 1);
+    assert.match(result.samples[0], /REDACTED:URL/);
+    assert.equal(JSON.stringify(result.receipt).includes('Ignore me'), false);
+    assert.equal(JSON.stringify(result.receipt).includes('example.com'), false);
+    assert.equal(result.receipt.presidio, 'NOT_CONFIGURED');
+});
+test('parsing local exports cannot open a socket', async () => {
+    const net = (await import('node:' + 'net')).default;
+    const writable = net;
+    const originalConnect = writable.connect;
+    const originalCreateConnection = writable.createConnection;
+    const denied = () => { throw new Error('network must remain unavailable'); };
+    writable.connect = denied;
+    writable.createConnection = denied;
+    try {
+        const result = ingestTelegramDesktopJson(JSON.stringify({ messages: [{ type: 'message', from: 'Owner', text: 'A local export stays local.' }] }), 'Owner');
+        assert.equal(result.samples.length, 1);
+    }
+    finally {
+        writable.connect = originalConnect;
+        writable.createConnection = originalCreateConnection;
+    }
+});

package/dist/strict-quality.js

@@ -0,0 +1,64 @@
+import { finalOutputCheck } from './hygiene.js';
+import { analyze } from './pipeline.js';
+import { assessProfileReadiness } from './profile-quality.js';
+const MINIMUM_SAMPLES = 5;
+const MINIMUM_WORDS = 1_500;
+function finding(id, disposition, reason, suggestion, sentence) {
+    return { id, disposition, reason, suggestion, ...(sentence === undefined ? {} : { sentence }) };
+}
+function strictFinding(source, profile) {
+    if (source.engine === 'ai_editor') {
+        const disposition = source.appliedPolicy === 'blocking' ? 'block' : 'review';
+        return finding(`strict.${source.engine}.${source.id}`, disposition, source.reason, source.suggestion, source.sentence);
+    }
+    if (source.engine === 'voice_dna') {
+        if (source.severity === 'red')
+            return finding(`strict.${source.engine}.${source.id}`, 'block', source.reason, source.suggestion, source.sentence);
+        if (source.id.startsWith('dna.fingerprint.')) {
+            const metric = source.id.slice('dna.fingerprint.'.length);
+            const key = metric === 'contraction-rate' ? 'contractionRate'
+                : metric === 'sentence-length-distribution' ? 'sentenceLengthDistribution'
+                    : metric === 'bullet-rate' ? 'bulletRate'
+                        : metric === 'en-dash-rate' ? 'enDashRate' : undefined;
+            if (key && profile.tolerances[key].calibrated)
+                return finding(`strict.${source.engine}.${source.id}`, 'block', source.reason, source.suggestion, source.sentence);
+        }
+        return finding(`strict.${source.engine}.${source.id}`, 'review', source.reason, source.suggestion, source.sentence);
+    }
+    return finding(`strict.${source.engine}.${source.id}`, source.severity === 'red' ? 'block' : 'review', source.reason, source.suggestion, source.sentence);
+}
+export function evaluateStrictQuality(draft, profile, samples, brief) {
+    const readiness = assessProfileReadiness(samples);
+    const analysis = analyze(draft, profile, brief);
+    const output = finalOutputCheck(draft);
+    const findings = [];
+    if (profile.version !== '3') {
+        findings.push(finding('strict.profile.version', 'block', 'Strict quality requires a fixture-backed Profile v3.', 'Build and validate a Profile v3 before enabling strict quality.'));
+    }
+    else {
+        if (profile.sampleCount < MINIMUM_SAMPLES)
+            findings.push(finding('strict.profile.profile-sample-count', 'block', `Strict quality requires a Profile v3 built from at least ${MINIMUM_SAMPLES} samples; the profile declares ${profile.sampleCount}.`, 'Rebuild and calibrate the profile from at least five distinct, rights-cleared samples.'));
+        if (samples.length < MINIMUM_SAMPLES)
+            findings.push(finding('strict.profile.sample-count', 'block', `Strict quality requires at least ${MINIMUM_SAMPLES} local samples; received ${samples.length}.`, 'Add channel-matched, rights-cleared samples from the same writer.'));
+        if (readiness.totalWords < MINIMUM_WORDS)
+            findings.push(finding('strict.profile.sample-words', 'block', `Strict quality requires at least ${MINIMUM_WORDS} sample words; received ${readiness.totalWords}.`, 'Add channel-matched, rights-cleared samples before treating voice drift as strict evidence.'));
+        if (readiness.findings.some((item) => item.id === 'sample_length'))
+            findings.push(finding('strict.profile.sample-coverage', 'block', 'Strict quality requires enough sentence-level sample coverage to calibrate voice drift.', 'Add longer samples with distinct sentences before treating voice drift as strict evidence.'));
+        if (readiness.findings.some((item) => item.id === 'duplicate_sample'))
+            findings.push(finding('strict.profile.duplicate-sample', 'block', 'Strict quality cannot calibrate from duplicate samples.', 'Replace duplicate samples with distinct writing occasions.'));
+        if (readiness.findings.some((item) => item.id === 'format_spread'))
+            findings.push(finding('strict.profile.format-spread', 'block', 'Strict quality cannot use a mixed-format sample set as one voice baseline.', 'Use samples from the same intended format and audience, or maintain separate calibrated profiles.'));
+        for (const [metric, tolerance] of Object.entries(profile.tolerances)) {
+            if (!tolerance.calibrated)
+                findings.push(finding(`strict.profile.uncalibrated.${metric}`, 'block', `Strict quality requires a calibrated ${metric} tolerance.`, 'Calibrate this metric against held-out writing before treating its drift as a strict result.'));
+        }
+        for (const source of [...analysis.voiceDna.findings, ...analysis.aiEditor.findings, ...(analysis.editorial?.findings ?? [])])
+            findings.push(strictFinding(source, profile));
+    }
+    if (!output.accepted)
+        findings.push(finding('strict.final-output', 'block', 'Final output contains unresolved hidden text.', 'Resolve hidden-text findings before treating the draft as strict-ready.'));
+    const disposition = findings.some((item) => item.disposition === 'block')
+        ? 'blocked'
+        : findings.length ? 'needs-human-review' : 'strict-ready';
+    return { version: '1', disposition, readiness, analysis, finalOutputAccepted: output.accepted, findings };
+}

package/dist/strict-quality.test.js

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import test from 'node:test';
+import { evaluateStrictQuality } from './strict-quality.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value !== null && typeof value === 'object')
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+function profile() {
+    const unsigned = {
+        version: '3', id: 'strict.author', revision: 1, sampleCount: 5,
+        metrics: { sentenceLength: 6, sentenceVariation: 2, sentenceStructure: [], rhythm: 1, paragraphLength: 1, openingMoves: [], vocabulary: [], lexicalDensity: 0.5, pointOfView: 'mixed', punctuation: { '!': 0, '?': 0, ';': 0, ':': 0, '—': 0 }, caseStyle: 'standard', questionRate: 0, transitions: [] },
+        avoid: [], provenance: { source: 'local', rights: 'author-owned', createdAt: '2026-08-25T00:00:00.000Z' }, rulePolicy: {},
+        fingerprint: { contractionRate: 0, sentenceLengthDistribution: { short: 1, medium: 0, long: 0 }, bulletRate: 0, enDashRate: 0 },
+        tolerances: { contractionRate: { absolute: 1, calibrated: true }, sentenceLengthDistribution: { absolute: 1, calibrated: true }, bulletRate: { absolute: 1, calibrated: true }, enDashRate: { absolute: 1, calibrated: true } },
+        metricFixtures: { contractionRate: ['fixture.a'], sentenceLengthDistribution: ['fixture.b'], bulletRate: ['fixture.c'], enDashRate: ['fixture.d'] },
+    };
+    return { ...unsigned, revisionDigest: createHash('sha256').update(canonical(unsigned)).digest('hex') };
+}
+function samples() { return Array.from({ length: 5 }, (_, index) => Array.from({ length: 100 }, () => `sample${index} records one concrete detail.`).join(' ')); }
+test('returns strict-ready only for a calibrated, adequately sampled, clean v3 profile', () => {
+    const report = evaluateStrictQuality('The launch starts Tuesday. The owner signed the checklist.', profile(), samples());
+    assert.equal(report.disposition, 'strict-ready');
+    assert.deepEqual(report.findings, []);
+});
+test('blocks an underpowered or uncalibrated voice profile before trusting voice matching', () => {
+    const underpowered = evaluateStrictQuality('The launch starts Tuesday.', profile(), samples().slice(0, 2));
+    assert.equal(underpowered.disposition, 'blocked');
+    assert.ok(underpowered.findings.some((item) => item.id === 'strict.profile.sample-count'));
+    const sparse = evaluateStrictQuality('The launch starts Tuesday.', profile(), Array.from({ length: 5 }, (_, index) => `sample ${index}.`));
+    assert.ok(sparse.findings.some((item) => item.id === 'strict.profile.sample-coverage'));
+    const uncalibrated = profile();
+    uncalibrated.tolerances.bulletRate.calibrated = false;
+    const report = evaluateStrictQuality('The launch starts Tuesday.', uncalibrated, samples());
+    assert.ok(report.findings.some((item) => item.id === 'strict.profile.uncalibrated.bulletRate'));
+    const thinProfile = profile();
+    thinProfile.sampleCount = 2;
+    const thinProfileReport = evaluateStrictQuality('The launch starts Tuesday.', thinProfile, samples());
+    assert.ok(thinProfileReport.findings.some((item) => item.id === 'strict.profile.profile-sample-count'));
+    const mixedFormats = samples();
+    mixedFormats[0] = Array.from({ length: 100 }, () => 'subject: a concise update for the release list.').join(' ');
+    const mixedFormatReport = evaluateStrictQuality('The launch starts Tuesday.', profile(), mixedFormats);
+    assert.ok(mixedFormatReport.findings.some((item) => item.id === 'strict.profile.format-spread'));
+});
+test('requires human review for a judgment-required AI pattern and blocks a configured one', () => {
+    const review = evaluateStrictQuality('We leverage the existing checklist.', profile(), samples());
+    assert.equal(review.disposition, 'needs-human-review');
+    assert.ok(review.findings.some((item) => item.id === 'strict.ai_editor.ai.leverage' && item.disposition === 'review'));
+    const blockedProfile = profile();
+    blockedProfile.rulePolicy['ai.leverage'] = 'blocking';
+    const blocked = evaluateStrictQuality('We leverage the existing checklist.', blockedProfile, samples());
+    assert.equal(blocked.disposition, 'blocked');
+    assert.ok(blocked.findings.some((item) => item.id === 'strict.ai_editor.ai.leverage' && item.disposition === 'block'));
+});
+test('blocks unresolved final-output hygiene', () => {
+    const report = evaluateStrictQuality('The launch starts\u200b Tuesday.', profile(), samples());
+    assert.equal(report.disposition, 'blocked');
+    assert.ok(report.findings.some((item) => item.id === 'strict.final-output'));
+});

package/dist/version.js

@@ -1 +1 @@
-export const HYV_VERSION = '3.4.5';
+export const HYV_VERSION = '3.5.0';

package/dist/voice-dna.js

@@ -1,3 +1,6 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+import { deriveRuleAllowances } from './rule-allowances.js';
 import { deviation, mean, paragraphs, sentences, words } from './text.js';
 const STOP_WORDS = new Set(['the', 'and', 'that', 'with', 'this', 'from', 'your', 'have', 'were', 'they', 'will', 'into', 'about', 'what', 'when', 'where']);
 const TRANSITIONS = ['but', 'because', 'instead', 'then', 'still', 'so', 'yet', 'therefore'];
@@ -13,7 +16,7 @@ function top(items, limit) {
         counts.set(item, (counts.get(item) ?? 0) + 1);
     return [...counts].sort((left, right) => right[1] - left[1]).slice(0, limit).map(([item]) => item);
 }
-function profileMetrics(text) {
+export function profileMetrics(text) {
     const draftSentences = sentences(text);
     const draftWords = words(text);
     const lengths = draftSentences.map((sentence) => words(sentence.text).length);
@@ -85,6 +88,35 @@ export function buildProfile(samples, avoid = []) {
         throw new Error('Every local writing sample must contain writing.');
     return { version: '2', sampleCount: samples.length, metrics: profileMetrics(samples.join('\n\n')), avoid };
 }
+export function buildProfileV3(samples, id, channel, avoid = [], tone) {
+    const base = buildProfile(samples, avoid);
+    const sampleText = samples.join('\n\n');
+    const fixtureIds = samples.map((_, index) => 'sample.' + String(index + 1).padStart(3, '0'));
+    const unsigned = {
+        version: '3',
+        id,
+        revision: 1,
+        sampleCount: base.sampleCount,
+        metrics: base.metrics,
+        avoid: base.avoid,
+        provenance: { source: 'local-author-owned-samples', rights: 'author-owned', createdAt: new Date().toISOString() },
+        rulePolicy: {},
+        ...(Object.keys(deriveRuleAllowances(samples)).length ? { ruleAllowances: deriveRuleAllowances(samples) } : {}),
+        channel,
+        ...(tone ? { tone } : {}),
+        fingerprint: measureFounderFingerprint(sampleText),
+        tolerances: {
+            contractionRate: { absolute: 0.1, calibrated: false },
+            sentenceLengthDistribution: { absolute: 0.15, calibrated: false },
+            bulletRate: { absolute: 0.1, calibrated: false },
+            enDashRate: { absolute: 0.05, calibrated: false },
+        },
+        metricFixtures: {
+            contractionRate: fixtureIds, sentenceLengthDistribution: fixtureIds, bulletRate: fixtureIds, enDashRate: fixtureIds,
+        },
+    };
+    return { ...unsigned, revisionDigest: createHash('sha256').update(canonicalJson(unsigned)).digest('hex') };
+}
 function finding(id, severity, sentence, excerpt, reason, suggestion) {
     return { engine: 'voice_dna', id, severity, sentence, excerpt, reason, suggestion };
 }

package/dist/voice-dna.test.js

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { analyzeVoiceDna, buildProfile, measureFounderFingerprint } from './voice-dna.js';
+import { analyzeVoiceDna, buildProfile, buildProfileV3, measureFounderFingerprint } from './voice-dna.js';
+import { parseProfile } from './profile.js';
 function profileV3(overrides = {}) {
     const base = buildProfile(['i write plainly. i name the work.', 'i keep the mechanism clear. i avoid filler.']);
     return {
@@ -64,6 +65,16 @@ test('keeps buildProfile and v2 analysis output exactly on version 2', () => {
     assert.deepEqual(Object.keys(profile), ['version', 'sampleCount', 'metrics', 'avoid']);
     assert.equal(analyzeVoiceDna('i write plainly.', profile).version, '2');
 });
+test('builds a signed channel-specific Profile v3 without retaining sample prose', () => {
+    const profile = buildProfileV3([
+        'I write directly about the release — and name the owner.',
+        'I keep the mechanism visible — then choose the next step.',
+    ], 'founder.email', 'email', [], { formality: 0.4, confidence: 0.7, warmth: 0.6, energy: 0.3, complexity: 0.5 });
+    assert.equal(profile.channel, 'email');
+    assert.equal(profile.ruleAllowances?.['punct.em-dash']?.sampleCount, 2);
+    assert.strictEqual(parseProfile(profile), profile);
+    assert.equal(JSON.stringify(profile).includes('keep the mechanism visible'), false);
+});
 test('measures contractions in both directions and accepts curly apostrophes', () => {
     assert.equal(measureFounderFingerprint("I can't stop because I won't stop.").contractionRate, 2 / 7);
     assert.equal(measureFounderFingerprint('I cannot stop because I will not stop.').contractionRate, 0);

package/dist/writing-examples.js

@@ -0,0 +1,83 @@
+import { basename } from 'node:path';
+import { sentences } from './text.js';
+const STOP_WORDS = new Set(['the', 'and', 'that', 'with', 'this', 'from', 'your', 'have', 'were', 'they', 'will', 'into', 'about', 'what', 'when', 'where', 'then', 'than']);
+const REDACTIONS = [
+    ['EMAIL', /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi],
+    ['PHONE', /(?<!\w)(?:\+?\d[\d .()/-]{7,}\d)(?!\w)/g],
+    ['CARD', /(?<!\d)(?:\d[ -]?){13,19}(?!\d)/g],
+    ['IP', /\b(?:\d{1,3}\.){3}\d{1,3}\b/g],
+    ['URL', /\bhttps?:\/\/[^\s<>()]+/gi],
+];
+function tokens(text) {
+    return (text.toLocaleLowerCase().match(/\p{L}[\p{L}\p{N}'’-]*/gu) ?? []).filter((token) => token.length > 2 && !STOP_WORDS.has(token));
+}
+function redact(text) {
+    let output = text;
+    for (const [kind, expression] of REDACTIONS)
+        output = output.replace(expression, `[REDACTED:${kind}]`);
+    return output.replace(/\s+/g, ' ').trim().slice(0, 480);
+}
+function validate(inputs) {
+    if (!inputs.length || inputs.length > 64)
+        throw new Error('Writing example lookup needs one to 64 explicit local samples.');
+    for (const input of inputs) {
+        if (!input.text.trim() || input.text.length > 100_000)
+            throw new Error('Every writing example must contain at most 100,000 characters of text.');
+        if (!input.basename || basename(input.basename) !== input.basename || input.basename.length > 160)
+            throw new Error('Writing example sources must use basenames only.');
+    }
+}
+/** Builds an explicit in-memory inverted index; it is never written or retained. */
+function indexExamples(inputs) {
+    const entries = inputs.flatMap((input) => sentences(input.text).map((sentence, position) => ({ source: input.basename, position, text: sentence.text, terms: tokens(sentence.text) })));
+    const postings = new Map();
+    const documentFrequency = new Map();
+    for (const [entryIndex, entry] of entries.entries()) {
+        const seen = new Set();
+        for (const term of entry.terms) {
+            const posting = postings.get(term) ?? new Map();
+            posting.set(entryIndex, (posting.get(entryIndex) ?? 0) + 1);
+            postings.set(term, posting);
+            seen.add(term);
+        }
+        for (const term of seen)
+            documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+    }
+    return { entries, postings, documentFrequency };
+}
+/** Finds redacted local examples in supplied memory only; it never creates a corpus or index on disk. */
+export function findWritingExamples(query, inputs, limit = 3) {
+    validate(inputs);
+    const queryTokens = new Set(tokens(query));
+    if (!queryTokens.size)
+        return [];
+    const index = indexExamples(inputs);
+    const scores = new Map();
+    const averageLength = index.entries.reduce((sum, entry) => sum + entry.terms.length, 0) / Math.max(1, index.entries.length);
+    for (const term of queryTokens) {
+        const posting = index.postings.get(term);
+        if (!posting)
+            continue;
+        const idf = Math.log(1 + (index.entries.length - (index.documentFrequency.get(term) ?? 0) + 0.5) / ((index.documentFrequency.get(term) ?? 0) + 0.5));
+        for (const [entryIndex, frequency] of posting) {
+            const entry = index.entries[entryIndex];
+            const denominator = frequency + 1.2 * (1 - 0.75 + 0.75 * entry.terms.length / Math.max(1, averageLength));
+            scores.set(entryIndex, (scores.get(entryIndex) ?? 0) + idf * frequency * 2.2 / denominator);
+        }
+    }
+    const ranked = [...scores].map(([entryIndex, score]) => ({ ...index.entries[entryIndex], score })).sort((left, right) => right.score - left.score || left.source.localeCompare(right.source) || left.position - right.position);
+    const usedSources = new Set();
+    const excerpts = [];
+    for (const candidate of ranked) {
+        if (usedSources.has(candidate.source))
+            continue;
+        const text = redact(candidate.text);
+        if (!text)
+            continue;
+        excerpts.push({ source: candidate.source, text });
+        usedSources.add(candidate.source);
+        if (excerpts.length === Math.min(3, Math.max(1, limit)))
+            break;
+    }
+    return excerpts;
+}

package/dist/writing-examples.test.js

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { findWritingExamples } from './writing-examples.js';
+test('retrieves at most three redacted excerpts with basenames only', () => {
+    const result = findWritingExamples('The rollout preserves the retry queue.', [
+        { basename: 'email.md', text: 'The retry queue preserves work after a rollout; contact owner@example.com.' },
+        { basename: 'notes.md', text: 'A rollback keeps the queue visible for operators.' },
+        { basename: 'third.md', text: 'This unrelated sentence does not rank.' },
+    ]);
+    assert.equal(result.length, 2);
+    assert.deepEqual(result.map((item) => item.source), ['email.md', 'notes.md']);
+    assert.match(result[0].text, /REDACTED:EMAIL/);
+    assert.equal(result[0].text.includes('owner@example.com'), false);
+    assert.equal(JSON.stringify(result).includes('/'), false);
+});
+test('requires explicit bounded in-memory samples and a real basename', () => {
+    assert.throws(() => findWritingExamples('queue', []), /one to 64/);
+    assert.throws(() => findWritingExamples('queue', [{ basename: '/private/email.md', text: 'The queue is visible.' }]), /basenames only/);
+});
+test('lookup cannot open a socket', async () => {
+    const net = (await import('node:' + 'net')).default;
+    const writable = net;
+    const originalConnect = writable.connect;
+    const originalCreateConnection = writable.createConnection;
+    const denied = () => { throw new Error('network must remain unavailable'); };
+    writable.connect = denied;
+    writable.createConnection = denied;
+    try {
+        assert.equal(findWritingExamples('queue', [{ basename: 'one.md', text: 'The queue stays local.' }]).length, 1);
+    }
+    finally {
+        writable.connect = originalConnect;
+        writable.createConnection = originalCreateConnection;
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "3.4.5",
+  "version": "3.5.0",
   "description": "A local-first dual-engine writing gate that protects voice and catches generic AI patterns.",
   "type": "module",
   "bin": {

package/skills/hyv-analyze/SKILL.md

@@ -16,9 +16,11 @@ hyv analyze draft.md profile.json [writing-brief.json]
 ## Behavior
 
 - Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- AI Editor scans author prose only. Frontmatter, fenced code, inline code, URLs, and Markdown link targets are excluded; a match remains an editorial signal, not proof of AI authorship.
+- A Profile v3 can carry a signed, non-verbatim allowance for a narrow stylistic default. An explicit profile policy always takes precedence, and no allowance weakens hygiene, fact, logic, or avoid-list checks.
 - Commands that write use an explicit output path. Confirm that path before running the command.
 - This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
 
 ## Handoff
 
-Run `hyv analyze` directly to execute the operation. Follow-on agents: hyv-rewrite-prompt, hyv-prepare-rewrite.
+Run `hyv analyze` directly to execute the operation. For ordinary editing, follow on with hyv-rewrite-prompt or hyv-prepare-rewrite. When the caller asks for a strict AI-pattern and voice-match decision, hand off to hyv-strict-check with a calibrated Profile v3 and the required local samples; analysis alone is not a strict-ready result.

package/skills/hyv-analyze/agent.json

@@ -44,6 +44,7 @@
   },
   "handoff_to": [
     "hyv-rewrite-prompt",
-    "hyv-prepare-rewrite"
+    "hyv-prepare-rewrite",
+    "hyv-strict-check"
   ]
 }

package/skills/hyv-backtest/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: hyv-backtest
+description: Evaluate a caller-supplied reconstruction against a held-out local target without generating text.
+---
+
+# hyv-backtest
+
+Run an information-isolated evaluation. HYV receives context, a real held-out target, and a candidate supplied by a person or external writer. It does not generate the candidate, return either text, or call a provider.
+
+```text
+hyv backtest context.md heldout-target.md candidate.md profile.json heldout-a.md heldout-b.md heldout-c.md
+```
+
+The result carries only digests plus separate preservation, AI Editor, and held-out-band reports. It is not an authorship score or publishing approval.

package/skills/hyv-backtest/agent.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-backtest",
+  "title": "hyv-backtest",
+  "description": "Evaluate a caller-supplied reconstruction against a held-out local target without generating text.",
+  "instruction_file": "SKILL.md",
+  "role": "Information-isolated evaluator",
+  "workflow_phase": "verify",
+  "input": { "required": ["context path", "held-out target path", "candidate path", "profile path", "three or more held-out sample paths"], "optional": [] },
+  "output": { "required": ["text-free backtest report"], "optional": [] },
+  "evidence_requirements": ["Report preservation, AI Editor, and held-out-band results separately; never call the report an authorship or generation result."],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": ["Stop when the candidate was not supplied by the caller or fewer than three held-out samples are supplied."],
+  "tool_free_mode": { "available": true, "behavior": "Provide the exact command and state that the local backtest is NOT_RUN; never invent a score.", "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"] },
+  "handoff_to": ["hyv-verify"]
+}

package/skills/hyv-backtest/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Backtest"
+  short_description: "Evaluate a supplied reconstruction without generating text."
+  default_prompt: "Use $hyv-backtest to score a caller-supplied reconstruction against held-out local writing without making an authorship claim."

package/skills/hyv-evaluate-local/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: hyv-evaluate-local
+description: Run the optional deterministic local writing evaluation composite without model calls.
+---
+
+# hyv-evaluate-local
+
+Evaluate a caller-supplied candidate against an input and separate local user and AI-shadow paragraph fixtures. The module trains only on the paragraph IDs assigned to the train split. It does not generate prose, transmit samples, retain text, or establish authorship.
+
+```text
+hyv evaluate-local input.md candidate.md user-paragraphs.json ai-shadow-paragraphs.json
+```
+
+Each JSON file is an array of `{ "paragraph_id": "stable-id", "text": "..." }`. Keep variants under the same paragraph ID; HYV splits by ID before training. The report contains a train-only TF-IDF logistic-regression proxy, content F1, AI-tell change, and 9-d stylometric cosine. Treat every number as a local evaluation signal, not a publishing decision or identity claim.

package/skills/hyv-evaluate-local/agent.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-evaluate-local",
+  "title": "hyv-evaluate-local",
+  "description": "Run the optional deterministic local writing evaluation composite without model calls.",
+  "instruction_file": "SKILL.md",
+  "role": "Local writing evaluation reporter",
+  "workflow_phase": "verify",
+  "input": { "required": ["input path", "candidate path", "user paragraph JSON", "AI-shadow paragraph JSON"], "optional": [] },
+  "output": { "required": ["paragraph-isolated evaluation report"], "optional": [] },
+  "evidence_requirements": ["Report that the authorship component is a local train-only proxy, not an authorship verdict.", "Do not allow paragraph IDs in both train and test sets."],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": ["Stop when either fixture has fewer than two unique paragraph IDs or the JSON schema is invalid."],
+  "tool_free_mode": { "available": true, "behavior": "Provide the exact command and state that the report is NOT_RUN; never invent scores.", "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"] },
+  "handoff_to": ["hyv-verify"]
+}