@holdyourvoice/hyv 3.0.1 → 3.1.0

package/Readme.md

@@ -55,7 +55,7 @@ To contribute, clone this repository, run `npm install`, then run `npm test` and
 
 ### Use it in Claude Desktop
 
-Build the fully local Claude Desktop extension with `npm run pack:claude`, then install `dist/hold-your-voice.mcpb` from **Settings → Extensions → Advanced settings → Install Extension**. The extension accepts text and portable profile JSON in the current conversation only. It does not read or write files, make network requests, or retain writing. See the [Claude Desktop guide](docs/CLAUDE-DESKTOP.md).
+Build the fully local Claude Desktop extension with `npm run pack:claude`, then install `dist/hold-your-voice.mcpb` from **Settings → Extensions → Advanced settings → Install Extension**. The extension accepts text and portable profile JSON in the current conversation only. A successful verification records resolved finding IDs in local learning state; it never retains writing text or makes network requests. See the [Claude Desktop guide](docs/CLAUDE-DESKTOP.md).
 
 ### Build a local VoiceDNA profile
 
@@ -97,7 +97,19 @@ Give the brief and draft to a human editor or any model you trust. This reposito
 npx @holdyourvoice/hyv verify draft.md candidate.md profile.json
 ```
 
-`verify` returns the original and candidate reports, identifies newly introduced findings, calculates a coarse preservation score, and exits with status `2` when the candidate fails the dual gate. It exits with `1` for a usage or runtime error. Treat status `2` as a release signal in scripts or CI.
+`verify` returns the original and candidate reports, identifies newly introduced findings, calculates a coarse preservation score, and exits with status `2` when the candidate fails the dual gate. A passing verification automatically records only the resolved finding IDs for that profile in local learning state. It exits with `1` for a usage or runtime error. Treat status `2` as a release signal in scripts or CI.
+
+### Local voice memory
+
+Learning is on by default. After a successful `verify`, Hold Your Voice records resolved rule IDs under `~/.hyv/learning/`, scoped to a fingerprint of the portable profile. It stores no draft or candidate text. The next `rewrite-prompt` uses a bounded list of those verified repairs.
+
+```bash
+hyv learning show profile.json
+hyv learning add profile.json "Keep the direct opening."
+hyv learning clear profile.json
+```
+
+`show` lets you inspect the exact local preferences. `clear` removes only that profile's learning file. Set `HYV_HOME` to place this local state elsewhere.
 
 ## The editing loop
 
@@ -187,6 +199,7 @@ The preservation score is a guardrail based on retained original words longer th
 | `hyv analyze <draft> <profile.json>` | Draft and profile | Analysis JSON | You need both reports before editing. |
 | `hyv rewrite-prompt <draft> <profile.json>` | Draft and profile | Markdown editing brief | You need a constrained request for an editor or model. |
 | `hyv verify <original> <candidate> <profile.json>` | Original, candidate, profile | Verification JSON and exit code | You need the candidate gate. |
+| `hyv learning <show\|add\|clear> <profile.json>` | Profile and optional instruction | Local learning JSON | You need to inspect or manage profile-scoped learning. |
 | `hyv patterns` | None | Ruleset JSON | You need the exact enabled rules. |
 
 Every file argument can be `-` when the command accepts text input from standard input. Profile output is always written to the path you give it. Use `npx @holdyourvoice/hyv <command>` in place of `hyv <command>` when you have not installed the CLI globally.
@@ -199,6 +212,7 @@ Every file argument can be `-` when the command accepts text input from standard
 | `src/text.ts` | Sentence, paragraph, word, and basic statistics helpers. |
 | `src/voice-dna.ts` | Builds profiles and runs VoiceDNA checks. |
 | `src/ai-editor.ts` | Owns the versioned deterministic editorial rules. |
+| `src/learning.ts` | Stores text-free, profile-scoped verified repairs and composes bounded local preferences. |
 | `src/pipeline.ts` | Combines pass states, makes briefs, and verifies candidates. |
 | `src/cli.ts` | Local file and standard-input command adapter. |
 | `src/pipeline.test.ts` | Contract and regression tests. |
@@ -209,9 +223,9 @@ Every file argument can be `-` when the command accepts text input from standard
 
 ## Privacy and data rights
 
-The runtime uses files on your machine. Samples, drafts, profiles, candidates, feedback history, embeddings, and client data stay there.
+The runtime uses files on your machine. Samples, drafts, profiles, candidates, and client data stay there. Successful verification writes a text-free local learning event under `~/.hyv/learning/`: profile fingerprint, finding IDs, severities, counts, timestamp, and an opaque one-way candidate digest for retry deduplication. An instruction added through `hyv learning add` is stored as entered.
 
-Keep writing samples, edit histories, client text, embeddings, and datasets out of public commits unless you hold explicit rights and a provenance record. A profile is aggregated JSON and can still reveal vocabulary and preferences. Store private profiles outside public repositories.
+The package does not upload writing, use embeddings, or make runtime network requests. Keep writing samples, edit histories, client text, local learning files, and datasets out of public commits unless you hold explicit rights and a provenance record. A profile is aggregated JSON and can still reveal vocabulary and preferences. Store private profiles outside public repositories.
 
 See the [privacy guide](https://github.com/shashank-sn/holdyourvoice/wiki/Privacy-and-Data-Rights) for maintainer and contributor boundaries.
 
@@ -228,6 +242,7 @@ Treat those as dated reference material. A reproducible benchmark needs rights-c
 | [The complete Wiki](https://github.com/shashank-sn/holdyourvoice/wiki) | Product, workflow, and contributor documentation. |
 | [Thesis](docs/THESIS.md) | The design argument for two independent engines. |
 | [Architecture](docs/ARCHITECTURE.md) | Source boundaries and extension rules. |
+| [Local voice memory](docs/wiki/Local-Voice-Memory.md) | What default local learning stores, uses, and never changes. |
 | [Prompt contract](docs/PROMPT-CONTRACT.md) | The tier order and editing constraints. |
 | [Pattern taxonomy](docs/PATTERN-TAXONOMY.md) | The catalog/executable-rule boundary. |
 | [Support](SUPPORT.md) | Funding without a feature gate. |

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync } from 'node:fs';
 import { rules, RULESET_VERSION } from './ai-editor.js';
+import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
 import { analyze, rewritePrompt, verify } from './pipeline.js';
 import { parseProfile } from './profile.js';
 import { buildProfile } from './voice-dna.js';
-const usage = 'Commands: profile, analyze, rewrite-prompt, verify, patterns';
+const usage = 'Commands: profile, analyze, rewrite-prompt, verify, learning, patterns, mcp';
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
@@ -33,7 +34,7 @@ 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 };
 }
-export function runCli(args) {
+export async function runCli(args) {
     const [command, ...rest] = args;
     if (command === 'profile') {
         const { output, samples, avoid } = profileArguments(rest);
@@ -51,27 +52,64 @@ export function runCli(args) {
         const [draft, profilePath] = rest;
         if (!draft || !profilePath)
             throw new Error('Usage: hyv rewrite-prompt draft.md profile.json');
-        console.log(rewritePrompt(input(draft), readProfile(profilePath)));
+        const profile = readProfile(profilePath);
+        console.log(rewritePrompt(input(draft), profile, composeLearning(profile)));
         return 0;
     }
     if (command === 'verify') {
         const [original, candidate, profilePath] = rest;
         if (!original || !candidate || !profilePath)
             throw new Error('Usage: hyv verify original.md candidate.md profile.json');
-        const result = verify(input(original), input(candidate), readProfile(profilePath));
+        const profile = readProfile(profilePath);
+        const originalText = input(original);
+        const candidateText = input(candidate);
+        const result = verify(originalText, candidateText, profile);
+        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)
+            throw new Error('Usage: hyv learning <show|add|clear> profile.json [instruction]');
+        const profile = readProfile(profilePath);
+        if (action === 'show') {
+            json({ profile: profileFingerprint(profile), preferences: composeLearning(profile) });
+            return 0;
+        }
+        if (action === 'add') {
+            const text = instruction.join(' ').trim();
+            if (!text)
+                throw new Error('Usage: hyv learning add profile.json "instruction"');
+            json({ added: addLearningInstruction(profile, text) });
+            return 0;
+        }
+        if (action === 'clear') {
+            json({ cleared: clearLearning(profile) });
+            return 0;
+        }
+        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 })) });
         return 0;
     }
+    if (command === 'mcp') {
+        if (rest.length > 0)
+            throw new Error('Usage: hyv mcp');
+        await import('./mcp.js');
+        return 0;
+    }
     throw new Error(`${usage}.`);
 }
-try {
-    process.exitCode = runCli(process.argv.slice(2));
-}
-catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-}
+void (async () => {
+    try {
+        process.exitCode = await runCli(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+})();

package/dist/cli.test.js

@@ -5,8 +5,8 @@ import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import test from 'node:test';
 const cli = new URL('./cli.js', import.meta.url).pathname;
-function run(...args) {
-    return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8' });
+function run(args, env = process.env) {
+    return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8', env });
 }
 test('creates an explicit local avoid list and exposes the ruleset', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
@@ -16,10 +16,10 @@ test('creates an explicit local avoid list and exposes the ruleset', () => {
         const profile = join(directory, 'profile.json');
         writeFileSync(first, 'i write plainly. i name the work.');
         writeFileSync(second, 'i keep the mechanism clear. i avoid filler.');
-        const created = run('profile', profile, first, second, '--avoid=unlock');
+        const created = run(['profile', profile, first, second, '--avoid=unlock']);
         assert.equal(created.status, 0, created.stderr);
         assert.deepEqual(JSON.parse(readFileSync(profile, 'utf8')).avoid, ['unlock']);
-        const patterns = run('patterns');
+        const patterns = run(['patterns']);
         assert.equal(patterns.status, 0, patterns.stderr);
         assert.ok(JSON.parse(patterns.stdout).rules.every((rule) => rule.id && rule.severity && rule.reason && rule.suggestion));
     }
@@ -39,11 +39,12 @@ test('uses exit code 2 for a failed candidate gate and 1 for misuse', () => {
         writeFileSync(second, 'i keep the mechanism clear. i avoid filler.');
         writeFileSync(original, 'i name the work.');
         writeFileSync(candidate, 'i unlock the answer.');
-        assert.equal(run('profile', profile, first, second, '--avoid=unlock').status, 0);
-        const verification = run('verify', original, candidate, profile);
+        assert.equal(run(['profile', profile, first, second, '--avoid=unlock']).status, 0);
+        const verification = run(['verify', original, candidate, profile]);
         assert.equal(verification.status, 2);
         assert.deepEqual(Object.keys(JSON.parse(verification.stdout)).sort(), ['candidate', 'original', 'passed', 'preservationScore', 'regressions', 'version']);
-        assert.equal(run('unknown-command').status, 1);
+        assert.equal(run(['unknown-command']).status, 1);
+        assert.equal(run(['mcp', 'unexpected']).status, 1);
     }
     finally {
         rmSync(directory, { recursive: true, force: true });
@@ -56,7 +57,7 @@ test('rejects a malformed hand-edited profile before analysis', () => {
         const profile = join(directory, 'profile.json');
         writeFileSync(draft, 'i name the work.');
         writeFileSync(profile, JSON.stringify({ version: '2', sampleCount: 2, metrics: {}, avoid: [1] }));
-        const result = run('analyze', draft, profile);
+        const result = run(['analyze', draft, profile]);
         assert.equal(result.status, 1);
         assert.match(result.stderr, /not a valid Hold Your Voice version 2 profile/);
     }
@@ -90,7 +91,7 @@ test('rejects malformed profile enum values and punctuation', () => {
             },
             avoid: [''],
         }));
-        assert.equal(run('analyze', draft, profile).status, 1);
+        assert.equal(run(['analyze', draft, profile]).status, 1);
     }
     finally {
         rmSync(directory, { recursive: true, force: true });
@@ -106,12 +107,41 @@ test('rejects hand-edited metrics outside their semantic bounds', () => {
         writeFileSync(first, 'i write plainly.');
         writeFileSync(second, 'i name the work.');
         writeFileSync(draft, 'i name the work.');
-        assert.equal(run('profile', profile, first, second).status, 0);
+        assert.equal(run(['profile', profile, first, second]).status, 0);
         const malformed = JSON.parse(readFileSync(profile, 'utf8'));
         malformed.sampleCount = 2.5;
         malformed.metrics.questionRate = 1.2;
         writeFileSync(profile, JSON.stringify(malformed));
-        assert.equal(run('analyze', draft, profile).status, 1);
+        assert.equal(run(['analyze', draft, profile]).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('learns from a successful local verification by default and exposes local controls', () => {
+    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 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.');
+        writeFileSync(original, 'I leverage the answer with useful detail and clear mechanism.');
+        writeFileSync(candidate, 'I use the answer with useful detail and clear mechanism.');
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage'], env).status, 0);
+        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/);
+        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.equal(run(['learning', 'clear', profile], env).status, 0);
+        assert.deepEqual(JSON.parse(run(['learning', 'show', profile], env).stdout).preferences, []);
     }
     finally {
         rmSync(directory, { recursive: true, force: true });

package/dist/learning.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const MAX_PREFERENCES = 10;
+const MAX_EVENTS = 40;
+const MAX_RESOLVED_FINDINGS = 20;
+const MAX_INSTRUCTION_CHARACTERS = 240;
+const MAX_COMPOSED_CHARACTERS = 1_200;
+const MAX_STORAGE_BYTES = 64 * 1024;
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function profileFingerprint(profile) {
+    return createHash('sha256').update(canonicalJson(profile)).digest('hex');
+}
+function learningDirectory(options = {}) {
+    return join(options.root ?? process.env.HYV_HOME ?? join(homedir(), '.hyv'), 'learning');
+}
+function eventFile(profile, options = {}) {
+    return join(learningDirectory(options), `${profileFingerprint(profile)}.jsonl`);
+}
+function normalizeInstruction(instruction) {
+    return instruction.replace(/\s+/g, ' ').trim();
+}
+function isResolvedFinding(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const finding = value;
+    return (finding.engine === 'voice_dna' || finding.engine === 'ai_editor')
+        && typeof finding.id === 'string' && finding.id.length > 0
+        && (finding.severity === 'red' || finding.severity === 'yellow')
+        && Number.isInteger(finding.count) && (finding.count ?? 0) > 0;
+}
+function parseEvent(line) {
+    try {
+        const event = JSON.parse(line);
+        if (!event || event.version !== '1' || typeof event.timestamp !== 'string')
+            return undefined;
+        if (event.kind === 'instruction' && typeof event.instruction === 'string') {
+            const instruction = normalizeInstruction(event.instruction);
+            if (instruction.length > 0 && instruction.length <= MAX_INSTRUCTION_CHARACTERS)
+                return { version: '1', timestamp: event.timestamp, kind: 'instruction', instruction };
+        }
+        const resolved = event.resolved;
+        if (event.kind === 'verified_candidate' && Array.isArray(resolved) && resolved.length > 0 && resolved.every(isResolvedFinding) && typeof event.outcome === 'string') {
+            return { version: '1', timestamp: event.timestamp, kind: 'verified_candidate', resolved, outcome: event.outcome };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function readRecentText(file) {
+    try {
+        const size = statSync(file).size;
+        const length = Math.min(size, MAX_STORAGE_BYTES);
+        const descriptor = openSync(file, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            readSync(descriptor, buffer, 0, length, Math.max(0, size - length));
+            return buffer.toString('utf8');
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+function readEvents(profile, options = {}) {
+    const file = eventFile(profile, options);
+    return readRecentText(file).split('\n').flatMap((line) => {
+        const event = parseEvent(line);
+        return event ? [event] : [];
+    }).slice(-MAX_EVENTS);
+}
+function serialize(events) {
+    return `${events.map((event) => JSON.stringify(event)).join('\n')}\n`;
+}
+function withCompactionLock(file, operation) {
+    const lock = `${file}.lock`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            const descriptor = openSync(lock, 'wx', 0o600);
+            try {
+                return operation();
+            }
+            finally {
+                closeSync(descriptor);
+                unlinkSync(lock);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                return undefined;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+    return undefined;
+}
+function appendEvent(profile, event, options = {}) {
+    try {
+        const directory = learningDirectory(options);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = eventFile(profile, options);
+        const line = `${JSON.stringify(event)}\n`;
+        const events = readEvents(profile, options);
+        const needsCompaction = events.length >= MAX_EVENTS || (statSync(file, { throwIfNoEntry: false })?.size ?? 0) + Buffer.byteLength(line) > MAX_STORAGE_BYTES;
+        if (needsCompaction) {
+            const compacted = withCompactionLock(file, () => {
+                const retained = [...readEvents(profile, options), event].slice(-MAX_EVENTS);
+                while (Buffer.byteLength(serialize(retained)) > MAX_STORAGE_BYTES)
+                    retained.shift();
+                writeFileSync(file, serialize(retained), { encoding: 'utf8', mode: 0o600 });
+            });
+            if (compacted === undefined)
+                return false;
+        }
+        else {
+            appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function countFindings(findings) {
+    const counted = new Map();
+    for (const finding of findings) {
+        const key = `${finding.engine}:${finding.id}:${finding.severity}`;
+        const entry = counted.get(key);
+        if (entry)
+            entry.count += 1;
+        else
+            counted.set(key, { finding, count: 1 });
+    }
+    return counted;
+}
+export function recordVerifiedCandidate(profile, verification, candidate, options = {}) {
+    if (!verification.passed)
+        return 'nothing_to_learn';
+    const original = countFindings([...verification.original.voiceDna.findings, ...verification.original.aiEditor.findings]);
+    const candidateFindings = countFindings([...verification.candidate.voiceDna.findings, ...verification.candidate.aiEditor.findings]);
+    const resolved = [...original].flatMap(([key, entry]) => {
+        const count = entry.count - (candidateFindings.get(key)?.count ?? 0);
+        return count > 0 ? [{ engine: entry.finding.engine, id: entry.finding.id, severity: entry.finding.severity, count }] : [];
+    });
+    if (!resolved.length)
+        return 'nothing_to_learn';
+    const bounded = resolved.slice(0, MAX_RESOLVED_FINDINGS);
+    const outcome = createHash('sha256').update(`${profileFingerprint(profile)}\0${candidate}`).digest('hex');
+    if (readEvents(profile, options).some((event) => event.kind === 'verified_candidate' && event.outcome === outcome))
+        return 'nothing_to_learn';
+    return appendEvent(profile, { version: '1', timestamp: new Date().toISOString(), kind: 'verified_candidate', resolved: bounded, outcome }, options) ? 'recorded' : 'write_failed';
+}
+export function addLearningInstruction(profile, instruction, options = {}) {
+    const trimmed = normalizeInstruction(instruction);
+    if (!trimmed)
+        throw new Error('Learning instructions cannot be empty.');
+    if (trimmed.length > MAX_INSTRUCTION_CHARACTERS)
+        throw new Error(`Learning instructions must be ${MAX_INSTRUCTION_CHARACTERS} characters or fewer.`);
+    return appendEvent(profile, { version: '1', timestamp: new Date().toISOString(), kind: 'instruction', instruction: trimmed }, options);
+}
+export function composeLearning(profile, options = {}) {
+    const preferences = new Map();
+    for (const event of readEvents(profile, options)) {
+        const texts = event.kind === 'instruction' && event.instruction
+            ? [{ text: event.instruction, count: 1 }]
+            : (event.resolved ?? []).map((finding) => ({ text: `Previously verified repair: ${finding.engine}/${finding.id}.`, count: finding.count }));
+        for (const { text, count } of texts) {
+            const current = preferences.get(text) ?? { count: 0, lastSeen: event.timestamp };
+            current.count += count;
+            if (event.timestamp > current.lastSeen)
+                current.lastSeen = event.timestamp;
+            preferences.set(text, current);
+        }
+    }
+    const result = [];
+    let characters = 0;
+    for (const [text, value] of [...preferences.entries()]
+        .sort(([firstText, first], [secondText, second]) => second.count - first.count || second.lastSeen.localeCompare(first.lastSeen) || firstText.localeCompare(secondText))
+        .slice(0, MAX_PREFERENCES)) {
+        if (characters + text.length > MAX_COMPOSED_CHARACTERS)
+            break;
+        result.push({ text, count: value.count });
+        characters += text.length;
+    }
+    return result;
+}
+export function clearLearning(profile, options = {}) {
+    const file = eventFile(profile, options);
+    try {
+        unlinkSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/dist/learning.test.js

@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import { appendFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { verify } from './pipeline.js';
+import { buildProfile } from './voice-dna.js';
+const profile = buildProfile([
+    'I write plainly. I name the work.',
+    'I keep the mechanism clear. I avoid filler.',
+], ['leverage']);
+function directory() {
+    return mkdtempSync(join(tmpdir(), 'holdyourvoice-learning-'));
+}
+test('records only resolved findings from successful verification without draft text', () => {
+    const root = directory();
+    try {
+        const original = 'I leverage the answer with useful detail and clear mechanism.';
+        const candidate = 'I use the answer with useful detail and clear mechanism.';
+        const result = verify(original, candidate, profile);
+        assert.equal(result.passed, true);
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'recorded');
+        const eventFile = join(root, 'learning', `${profileFingerprint(profile)}.jsonl`);
+        const stored = readFileSync(eventFile, 'utf8');
+        assert.match(stored, /ai\.leverage/);
+        assert.doesNotMatch(stored, /I leverage the answer/);
+        assert.doesNotMatch(stored, /I use the answer/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('keeps learning isolated by profile and bounds composed preferences', () => {
+    const root = directory();
+    try {
+        const other = buildProfile(['We explain the mechanism.', 'We keep the useful detail.']);
+        for (let index = 0; index < 12; index += 1)
+            addLearningInstruction(profile, `Keep preference ${index}.`, { root });
+        addLearningInstruction(other, 'Use a different preference.', { root });
+        const composed = composeLearning(profile, { root });
+        assert.equal(composed.length, 10);
+        assert.ok(composed.every((item) => item.text.startsWith('Keep preference')));
+        assert.ok(!composed.some((item) => item.text === 'Use a different preference.'));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('does not create an event for a failed candidate and clears a single profile', () => {
+    const root = directory();
+    try {
+        const failed = verify('I name the work.', 'I leverage the work.', profile);
+        assert.equal(failed.passed, false);
+        assert.equal(recordVerifiedCandidate(profile, failed, 'I leverage the work.', { root }), 'nothing_to_learn');
+        assert.equal(existsSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`)), false);
+        addLearningInstruction(profile, 'Keep it direct.', { root });
+        assert.equal(clearLearning(profile, { root }), true);
+        assert.deepEqual(composeLearning(profile, { root }), []);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('bounds retained events and local instruction size', () => {
+    const root = directory();
+    try {
+        for (let index = 0; index < 45; index += 1)
+            addLearningInstruction(profile, `Keep preference ${index}.`, { root });
+        const preferences = composeLearning(profile, { root });
+        assert.ok(preferences.every((item) => Number(item.text.match(/\d+/)?.[0]) >= 5));
+        assert.throws(() => addLearningInstruction(profile, 'x'.repeat(241), { root }), /240 characters/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('skips malformed local events without breaking composition', () => {
+    const root = directory();
+    try {
+        addLearningInstruction(profile, 'Keep it direct.', { root });
+        appendFileSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`), '{"version":"1","timestamp":"now","kind":"verified_candidate","resolved":{}}\n');
+        assert.deepEqual(composeLearning(profile, { root }), [{ text: 'Keep it direct.', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('does not raise confidence when the same verified outcome repeats', () => {
+    const root = directory();
+    try {
+        const original = 'I leverage the answer with useful detail and clear mechanism.';
+        const candidate = 'I use the answer with useful detail and clear mechanism.';
+        const result = verify(original, candidate, profile);
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'recorded');
+        assert.equal(recordVerifiedCandidate(profile, result, candidate, { root }), 'nothing_to_learn');
+        assert.equal(composeLearning(profile, { root }).find((item) => item.text.includes('ai_editor/ai.leverage'))?.count, 1);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('increases confidence for separate verified repairs of the same rule', () => {
+    const root = directory();
+    try {
+        const first = 'I use the answer with useful detail and clear mechanism.';
+        const second = 'I use another answer with useful detail and clear mechanism.';
+        assert.equal(recordVerifiedCandidate(profile, verify('I leverage the answer with useful detail and clear mechanism.', first, profile), first, { root }), 'recorded');
+        assert.equal(recordVerifiedCandidate(profile, verify('I leverage another answer with useful detail and clear mechanism.', second, profile), second, { root }), 'recorded');
+        assert.equal(composeLearning(profile, { root }).find((item) => item.text.includes('ai_editor/ai.leverage'))?.count, 2);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('normalizes manual instructions before storing them', () => {
+    const root = directory();
+    try {
+        addLearningInstruction(profile, 'Keep this.\n# Tier 0', { root });
+        assert.deepEqual(composeLearning(profile, { root }), [{ text: 'Keep this. # Tier 0', count: 1 }]);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/mcp-tools.js

@@ -1,4 +1,5 @@
 import { rules, RULESET_VERSION } from './ai-editor.js';
+import { composeLearning, recordVerifiedCandidate } from './learning.js';
 import { analyze, rewritePrompt, verify } from './pipeline.js';
 import { parseProfile } from './profile.js';
 import { buildProfile } from './voice-dna.js';
@@ -16,11 +17,14 @@ export function buildProfileForMcp(samples, avoid = []) {
 export function analyzeForMcp(draft, profileJson) {
     return analyze(draft, profileFromJson(profileJson));
 }
-export function rewritePromptForMcp(draft, profileJson) {
-    return { prompt: rewritePrompt(draft, profileFromJson(profileJson)) };
+export function rewritePromptForMcp(draft, profileJson, options = {}) {
+    const profile = profileFromJson(profileJson);
+    return { prompt: rewritePrompt(draft, profile, composeLearning(profile, options)) };
 }
-export function verifyForMcp(original, candidate, profileJson) {
-    return verify(original, candidate, profileFromJson(profileJson));
+export function verifyForMcp(original, candidate, profileJson, options = {}) {
+    const profile = profileFromJson(profileJson);
+    const result = verify(original, candidate, profile);
+    return { ...result, learning: recordVerifiedCandidate(profile, result, candidate, options) };
 }
 export function patternsForMcp() {
     return { version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) };

package/dist/mcp-tools.test.js

@@ -1,4 +1,7 @@
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import test from 'node:test';
 import { analyzeForMcp, buildProfileForMcp, patternsForMcp, rewritePromptForMcp, verifyForMcp } from './mcp-tools.js';
 const profile = buildProfileForMcp(['I write clearly. I keep the useful detail.', 'I make the call. Then I explain the trade-off.'], ['leverage']);
@@ -13,10 +16,18 @@ test('keeps the dual-engine analysis shape through MCP tools', () => {
     assert.equal(result.aiEditor.engine, 'ai_editor');
 });
 test('creates and verifies an editing loop through MCP tools', () => {
-    const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson);
-    const result = verifyForMcp('I make the call.', 'I make the call.', profileJson);
-    assert.match(brief.prompt, /Tier 0/);
-    assert.equal(result.preservationScore, 100);
+    const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-'));
+    try {
+        const result = verifyForMcp('I leverage the answer with useful detail and clear mechanism.', 'I use the answer with useful detail and clear mechanism.', profileJson, { root });
+        const brief = rewritePromptForMcp('I leverage a clear plan.', profileJson, { root });
+        assert.match(brief.prompt, /Tier 0/);
+        assert.match(brief.prompt, /Learned local preferences/);
+        assert.equal(result.preservationScore >= 70, true);
+        assert.equal(result.learning, 'recorded');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
 });
 test('exposes the executable pattern IDs through MCP tools', () => {
     assert.ok(patternsForMcp().rules.some((rule) => rule.id === 'ai.leverage'));

package/dist/mcp.js

@@ -12,7 +12,7 @@ function json(value) {
 function failure(error) {
     return { content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true };
 }
-const server = new McpServer({ name: 'hold-your-voice', version: '3.0.1' });
+const server = new McpServer({ name: 'hold-your-voice', version: '3.1.0' });
 server.registerTool('hyv_build_profile', {
     description: 'Build a portable VoiceDNA profile from at least two writing samples. The samples stay in memory and are not saved.',
     inputSchema: { samples, avoid },
@@ -50,9 +50,9 @@ server.registerTool('hyv_rewrite_prompt', {
     }
 });
 server.registerTool('hyv_verify', {
-    description: 'Verify a revised candidate against an original draft and portable profile. Reports regressions and preservation without saving either text.',
+    description: 'Verify a revised candidate against an original draft and portable profile. On a successful check, it stores only resolved finding IDs in local profile-scoped learning state; it never retains either text.',
     inputSchema: { original: writing, candidate: writing, profile_json: profileJson },
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
 }, async ({ original, candidate, profile_json }) => {
     try {
         return json(verifyForMcp(original, candidate, profile_json));

package/dist/mcp.test.js

@@ -1,9 +1,14 @@
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
 import { once } from 'node:events';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import test from 'node:test';
-test('serves the read-only Claude tools over stdio', async () => {
-    const server = spawn(process.execPath, [new URL('./mcp.js', import.meta.url).pathname], { stdio: ['pipe', 'pipe', 'pipe'] });
+import { profileFingerprint } from './learning.js';
+import { buildProfile } from './voice-dna.js';
+test('serves local Claude tools over stdio', async () => {
+    const server = spawn(process.execPath, [new URL('./cli.js', import.meta.url).pathname, 'mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     server.stdout.on('data', (chunk) => { stdout += chunk; });
@@ -18,5 +23,38 @@ test('serves the read-only Claude tools over stdio', async () => {
     const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
     const tools = responses.find((response) => response.id === 2)?.result?.tools;
     assert.deepEqual(tools?.map((tool) => tool.name), ['hyv_build_profile', 'hyv_analyze', 'hyv_rewrite_prompt', 'hyv_verify', 'hyv_patterns']);
-    assert.ok(tools?.every((tool) => tool.annotations?.readOnlyHint));
+    assert.ok(tools?.filter((tool) => tool.name !== 'hyv_verify').every((tool) => tool.annotations?.readOnlyHint));
+    assert.equal(tools?.find((tool) => tool.name === 'hyv_verify')?.annotations?.readOnlyHint, false);
+});
+test('uses default local learning through the registered MCP tools', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'holdyourvoice-mcp-server-'));
+    try {
+        const profile = buildProfile(['I write plainly. I name the work.', 'I keep the mechanism clear. I avoid filler.'], ['leverage']);
+        const server = spawn(process.execPath, [new URL('./cli.js', import.meta.url).pathname, 'mcp'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, HYV_HOME: root },
+        });
+        let stdout = '';
+        let stderr = '';
+        server.stdout.on('data', (chunk) => { stdout += chunk; });
+        server.stderr.on('data', (chunk) => { stderr += chunk; });
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'hyv_verify', arguments: { original: 'I leverage the answer with useful detail and clear mechanism.', candidate: 'I use the answer with useful detail and clear mechanism.', profile_json: JSON.stringify(profile) } } })}\n`);
+        server.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'hyv_rewrite_prompt', arguments: { draft: 'I use the answer with useful detail and clear mechanism.', profile_json: JSON.stringify(profile) } } })}\n`);
+        server.stdin.end();
+        const [code] = await once(server, 'close');
+        assert.equal(stderr, '');
+        assert.equal(code, 0);
+        const responses = stdout.trim().split('\n').map((line) => JSON.parse(line));
+        const prompt = JSON.parse(responses.find((response) => response.id === 3)?.result?.content?.[0]?.text ?? '{}').prompt;
+        assert.match(prompt, /Learned local preferences/);
+        const stored = readFileSync(join(root, 'learning', `${profileFingerprint(profile)}.jsonl`), 'utf8');
+        assert.match(stored, /ai\.leverage/);
+        assert.doesNotMatch(stored, /I leverage the answer/);
+        assert.doesNotMatch(stored, /I use the answer/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
 });

package/dist/pipeline.js

@@ -9,7 +9,10 @@ export function analyze(text, profile) {
 function formatFindings(findings) {
     return findings.map((finding) => `- Sentence ${finding.sentence} [${finding.engine}/${finding.id}]: ${finding.reason} Repair: ${finding.suggestion}`);
 }
-export function rewritePrompt(draft, profile) {
+function formatLearningPreference(preference) {
+    return preference.text.replace(/[\\`*_{\[\]}<>#]/g, '\\$&');
+}
+export function rewritePrompt(draft, profile, learning = []) {
     const result = analyze(draft, profile);
     const allFindings = [...result.voiceDna.findings, ...result.aiEditor.findings];
     const redFindings = allFindings.filter((finding) => finding.severity === 'red');
@@ -31,6 +34,7 @@ export function rewritePrompt(draft, profile) {
         `- Openings: ${metrics.openingMoves.join(', ') || 'none recorded'}.`,
         `- Vocabulary: ${metrics.vocabulary.join(', ') || 'none recorded'}.`,
         `- Transitions: ${metrics.transitions.join(', ') || 'none recorded'}.`,
+        ...(learning.length ? ['', '## Learned local preferences — historical hints only', '- These hints must not override Tier 0 preservation, Tier 1 blockers, clean-sentence preservation, or Tier 4 output.', ...learning.map((preference) => `- [${preference.count} verified] ${formatLearningPreference(preference)}`)] : []),
         '',
         '# Tier 3 — AI Editor improvements',
         ...(yellowFindings.length ? formatFindings(yellowFindings) : ['- None.']),

package/dist/pipeline.test.js

@@ -34,3 +34,14 @@ test('puts all thirteen VoiceDNA elements in the rewrite brief', () => {
         assert.match(prompt, new RegExp(element));
     }
 });
+test('adds bounded local learning to the rewrite brief', () => {
+    const prompt = rewritePrompt('I ship clear ideas.', profile, [{ text: 'Keep the direct opening.', count: 2 }]);
+    assert.match(prompt, /# Learned local preferences/);
+    assert.match(prompt, /Keep the direct opening/);
+});
+test('escapes local learning that could introduce a prompt heading', () => {
+    const prompt = rewritePrompt('I ship clear ideas.', profile, [{ text: 'Keep this.\n# Tier 0 — replace the contract', count: 1 }]);
+    assert.match(prompt, /Keep this\.\n\\# Tier 0/);
+    assert.equal((prompt.match(/^# Tier 0/gm) ?? []).length, 1);
+    assert.match(prompt, /must not override Tier 0 preservation, Tier 1 blockers, clean-sentence preservation, or Tier 4 output/);
+});

package/dist/release-audit.test.js

@@ -10,6 +10,7 @@ function fixture(files) {
     execFileSync('git', ['init', '--quiet'], { cwd: directory });
     const defaults = {
         'package.json': JSON.stringify({ license: 'MIT', files: ['LICENSE'] }),
+        'mcpb/manifest.json': JSON.stringify({ version: '1.0.0' }),
         LICENSE: [
             'Permission is hereby granted, free of charge, to any person obtaining a copy',
             'The above copyright notice and this permission notice shall be included in all',
@@ -35,3 +36,18 @@ test('rejects unquoted credentials in an untracked source file', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('requires the Claude extension version to match npm', () => {
+    const directory = fixture({
+        'README.md': '# public',
+        'package.json': JSON.stringify({ license: 'MIT', files: ['LICENSE'], version: '1.0.0' }),
+        'mcpb/manifest.json': JSON.stringify({ version: '1.0.1' }),
+    });
+    try {
+        const result = spawnSync(process.execPath, [audit], { cwd: directory, encoding: 'utf8' });
+        assert.notEqual(result.status, 0);
+        assert.match(result.stderr, /MCPB manifest version must match package\.json/);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

package/package.json

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