@holdyourvoice/hyv 3.0.2 → 3.1.1

package/Readme.md

@@ -55,18 +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).
-
-### Use it in Claude Code
-
-Hold Your Voice is also a free Claude Code plugin. It starts the same local MCP server through the public npm package; drafts, samples, and profiles stay on your machine.
-
-```text
-/plugin marketplace add shashank-sn/holdyourvoice
-/plugin install hold-your-voice@hold-your-voice
-```
-
-It requires Node.js 20 or newer and npm. See the [Claude Code guide](docs/CLAUDE-CODE.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
 
@@ -94,6 +83,38 @@ The result is JSON with independent reports:
 
 Read both reports. The outer `passed` field means each engine passed. Scores remain independent.
 
+### Add contextual editorial guidance
+
+Use an optional local WritingBrief when the same writer needs different guidance for a social post, deck, outreach note, blog, audit, or website. A brief activates only the relevant advisory format checks and can block explicitly prohibited local terms. It never changes your VoiceDNA profile or the default two-engine analysis.
+
+```json
+{
+  "version": "1",
+  "audience": "technical founders",
+  "intent": "start a useful discussion",
+  "format": "social",
+  "readerKnowsAuthor": false,
+  "vocabulary": ["deployment", "incident"],
+  "prohibitedTerms": ["internal contract value"]
+}
+```
+
+```bash
+hyv analyze draft.md profile.json writing-brief.json
+hyv rewrite-prompt draft.md profile.json writing-brief.json > rewrite-brief.md
+hyv verify original.md candidate.md profile.json writing-brief.json
+```
+
+Format checks are yellow review cues. Explicit `prohibitedTerms` are red release blockers. Keep client-specific briefs outside public repositories unless you have the right to publish them.
+
+### Inspect a batch
+
+Use batch analysis to catch exact repeated opening or closing sentences across two or more drafts. It is advisory and keeps all drafts local.
+
+```bash
+hyv batch-analyze posts/one.md posts/two.md posts/three.md
+```
+
 ### Create an editing brief
 
 ```bash
@@ -108,7 +129,46 @@ 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.
+
+### Lock factual claims with a CopySpec
+
+Use `verify-spec` when a draft has claims that must remain exact. A local CopySpec records each immutable claim alongside its evidence, then blocks a candidate if that claim is absent, changed, or joined by a prohibited claim.
+
+```json
+{
+  "version": "1",
+  "audience": "operators",
+  "intent": "explain a launch date",
+  "channel": "email",
+  "claims": [
+    {
+      "id": "launch-date",
+      "text": "The launch is on 14 August.",
+      "evidence": "Release calendar, checked 7 August."
+    }
+  ],
+  "prohibitedClaims": ["The launch is guaranteed to double revenue."]
+}
+```
+
+```bash
+hyv verify-spec original.md candidate.md profile.json copy-spec.json
+```
+
+The check is deterministic. It covers declared claims and prohibited text; arbitrary unsupported assertions need a separate factual evaluator.
+
+### 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
 
@@ -198,6 +258,8 @@ 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 verify-spec <original> <candidate> <profile.json> <copy-spec.json>` | Original, candidate, profile, CopySpec | Verification JSON with hard claim gate | A brief contains locked facts or prohibited claims. |
+| `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.
@@ -210,6 +272,8 @@ 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/editorial-packs.ts` | Parses WritingBrief context and runs format and batch checks. |
+| `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. |
@@ -220,9 +284,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.
 
@@ -239,6 +303,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,16 +1,53 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync } from 'node:fs';
 import { rules, RULESET_VERSION } from './ai-editor.js';
-import { analyze, rewritePrompt, verify } from './pipeline.js';
+import { parseCopySpec } from './copy-spec.js';
+import { analyzeBatch, parseWritingBrief } from './editorial-packs.js';
+import { addLearningInstruction, clearLearning, composeLearning, profileFingerprint, recordVerifiedCandidate } from './learning.js';
+import { analyze, rewritePrompt, verify, verifyWithCopySpec } from './pipeline.js';
 import { parseProfile } from './profile.js';
+import { evaluateRewriteResponse, parseRewriteTask, prepareRewriteTask } from './rewrite-task.js';
 import { buildProfile } from './voice-dna.js';
-const usage = 'Commands: profile, analyze, rewrite-prompt, verify, patterns, mcp';
+const usage = 'Commands: profile, analyze, batch-analyze, rewrite-prompt, prepare-rewrite, apply-rewrite, verify, verify-spec, learning, patterns, mcp';
 function input(path) {
     return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
 }
 function readProfile(path) {
     return parseProfile(JSON.parse(input(path)));
 }
+function readBrief(path) {
+    return path ? parseWritingBrief(JSON.parse(input(path))) : undefined;
+}
+function prepareContext(paths) {
+    let copySpec;
+    let writingBrief;
+    for (const path of paths) {
+        const value = JSON.parse(input(path));
+        try {
+            const parsed = parseCopySpec(value);
+            if (copySpec)
+                throw new Error('Prepare-rewrite accepts at most one CopySpec.');
+            copySpec = parsed;
+            continue;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'Prepare-rewrite accepts at most one CopySpec.')
+                throw error;
+        }
+        try {
+            const parsed = parseWritingBrief(value);
+            if (writingBrief)
+                throw new Error('Prepare-rewrite accepts at most one WritingBrief.');
+            writingBrief = parsed;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'Prepare-rewrite accepts at most one WritingBrief.')
+                throw error;
+            throw new Error(`Expected a valid CopySpec or WritingBrief at ${path}.`);
+        }
+    }
+    return { copySpec, writingBrief };
+}
 function json(value) {
     console.log(JSON.stringify(value, null, 2));
 }
@@ -41,27 +78,95 @@ export async function runCli(args) {
         return 0;
     }
     if (command === 'analyze') {
-        const [draft, profilePath] = rest;
+        const [draft, profilePath, briefPath] = rest;
         if (!draft || !profilePath)
-            throw new Error('Usage: hyv analyze draft.md profile.json');
-        json(analyze(input(draft), readProfile(profilePath)));
+            throw new Error('Usage: hyv analyze draft.md profile.json [writing-brief.json]');
+        json(analyze(input(draft), readProfile(profilePath), readBrief(briefPath)));
+        return 0;
+    }
+    if (command === 'batch-analyze') {
+        if (rest.length < 2)
+            throw new Error('Usage: hyv batch-analyze draft-a.md draft-b.md [draft-c.md]');
+        json(analyzeBatch(rest.map(input)));
         return 0;
     }
     if (command === 'rewrite-prompt') {
-        const [draft, profilePath] = rest;
+        const [draft, profilePath, briefPath] = rest;
         if (!draft || !profilePath)
-            throw new Error('Usage: hyv rewrite-prompt draft.md profile.json');
-        console.log(rewritePrompt(input(draft), readProfile(profilePath)));
+            throw new Error('Usage: hyv rewrite-prompt draft.md profile.json [writing-brief.json]');
+        const profile = readProfile(profilePath);
+        console.log(rewritePrompt(input(draft), profile, composeLearning(profile), readBrief(briefPath)));
+        return 0;
+    }
+    if (command === 'prepare-rewrite') {
+        const [draft, profilePath, output, ...contextPaths] = rest;
+        if (!draft || !profilePath || !output)
+            throw new Error('Usage: hyv prepare-rewrite draft.md profile.json task.json [copy-spec.json] [writing-brief.json]');
+        const context = prepareContext(contextPaths);
+        const task = prepareRewriteTask(input(draft), readProfile(profilePath), context.copySpec, context.writingBrief);
+        writeFileSync(output, `${JSON.stringify(task, null, 2)}\n`);
+        json({ version: task.version, fingerprint: task.fingerprint, eligibleSentenceIds: task.eligibleSentenceIds });
         return 0;
     }
+    if (command === 'apply-rewrite') {
+        const [taskPath, responsePath, profilePath] = rest;
+        if (!taskPath || !responsePath || !profilePath)
+            throw new Error('Usage: hyv apply-rewrite task.json response.json profile.json');
+        const result = evaluateRewriteResponse(parseRewriteTask(JSON.parse(input(taskPath))), input(responsePath), readProfile(profilePath));
+        json(result);
+        return result.status === 'accepted' ? 0 : 2;
+    }
     if (command === 'verify') {
-        const [original, candidate, profilePath] = rest;
+        const [original, candidate, profilePath, briefPath] = rest;
         if (!original || !candidate || !profilePath)
-            throw new Error('Usage: hyv verify original.md candidate.md profile.json');
-        const result = verify(input(original), input(candidate), readProfile(profilePath));
+            throw new Error('Usage: hyv verify original.md candidate.md profile.json [writing-brief.json]');
+        const profile = readProfile(profilePath);
+        const originalText = input(original);
+        const candidateText = input(candidate);
+        const result = verify(originalText, candidateText, profile, readBrief(briefPath));
+        const learning = recordVerifiedCandidate(profile, result, candidateText);
+        if (learning === 'write_failed')
+            console.error('Warning: verification passed, but local learning could not be saved.');
+        json(result);
+        return result.passed ? 0 : 2;
+    }
+    if (command === 'verify-spec') {
+        const [original, candidate, profilePath, specPath, briefPath] = rest;
+        if (!original || !candidate || !profilePath || !specPath)
+            throw new Error('Usage: hyv verify-spec original.md candidate.md profile.json copy-spec.json [writing-brief.json]');
+        const profile = readProfile(profilePath);
+        const candidateText = input(candidate);
+        const result = verifyWithCopySpec(input(original), candidateText, profile, parseCopySpec(JSON.parse(input(specPath))), readBrief(briefPath));
+        if (result.passed) {
+            const learning = recordVerifiedCandidate(profile, result, candidateText);
+            if (learning === 'write_failed')
+                console.error('Warning: verification passed, but local learning could not be saved.');
+        }
         json(result);
         return result.passed ? 0 : 2;
     }
+    if (command === 'learning') {
+        const [action, profilePath, ...instruction] = rest;
+        if (!action || !profilePath)
+            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;

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));
     }
@@ -27,6 +27,33 @@ test('creates an explicit local avoid list and exposes the ruleset', () => {
         rmSync(directory, { recursive: true, force: true });
     }
 });
+test('runs contextual analysis and batch analysis without changing the profile contract', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const brief = join(directory, 'brief.json');
+        const draft = join(directory, 'draft.md');
+        const duplicate = join(directory, 'duplicate.md');
+        const task = join(directory, 'task.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(brief, JSON.stringify({ version: '1', audience: 'founders', intent: 'start a discussion', format: 'social' }));
+        writeFileSync(draft, 'A pattern I keep seeing in founder posts is vague advice.');
+        writeFileSync(duplicate, 'A pattern I keep seeing in founder posts is vague advice.');
+        assert.equal(run(['profile', profile, first, second]).status, 0);
+        const contextual = JSON.parse(run(['analyze', draft, profile, brief]).stdout);
+        assert.equal(contextual.editorial.findings[0].id, 'editorial.social.generic-opener');
+        const batch = JSON.parse(run(['batch-analyze', draft, duplicate]).stdout);
+        assert.equal(batch.findings.length, 2);
+        assert.equal(run(['prepare-rewrite', draft, profile, task, brief]).status, 0);
+        assert.equal(JSON.parse(readFileSync(task, 'utf8')).writingBrief.format, 'social');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
 test('uses exit code 2 for a failed candidate gate and 1 for misuse', () => {
     const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
     try {
@@ -39,12 +66,61 @@ 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('mcp', 'unexpected').status, 1);
+        assert.equal(run(['unknown-command']).status, 1);
+        assert.equal(run(['mcp', 'unexpected']).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('fails the CopySpec gate when a locked claim changes', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const original = join(directory, 'original.md');
+        const candidate = join(directory, 'candidate.md');
+        const spec = join(directory, 'copy-spec.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(original, 'The launch is on 14 August.');
+        writeFileSync(candidate, 'The launch is next month.');
+        writeFileSync(spec, JSON.stringify({ version: '1', audience: 'operators', intent: 'explain', channel: 'email', claims: [{ id: 'launch-date', text: 'The launch is on 14 August.', evidence: 'Release calendar.' }] }));
+        assert.equal(run(['profile', profile, first, second]).status, 0);
+        const result = run(['verify-spec', original, candidate, profile, spec]);
+        assert.equal(result.status, 2);
+        assert.equal(JSON.parse(result.stdout).claims.failures[0].code, 'missing_immutable_claim');
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('prepares and applies the same constrained rewrite task without a provider call', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const first = join(directory, 'first.md');
+        const second = join(directory, 'second.md');
+        const profile = join(directory, 'profile.json');
+        const draft = join(directory, 'draft.md');
+        const task = join(directory, 'task.json');
+        const response = join(directory, 'response.json');
+        writeFileSync(first, 'I write plainly. I name the work.');
+        writeFileSync(second, 'I keep the mechanism clear. I avoid filler.');
+        writeFileSync(draft, 'I leverage the answer with useful detail and clear mechanism.');
+        assert.equal(run(['profile', profile, first, second, '--avoid=leverage']).status, 0);
+        assert.equal(run(['prepare-rewrite', draft, profile, task]).status, 0);
+        const prepared = JSON.parse(readFileSync(task, 'utf8'));
+        writeFileSync(response, JSON.stringify({ version: '1', taskFingerprint: prepared.fingerprint, replacements: [{ sentenceId: 1, text: 'I use the answer with useful detail and clear mechanism.' }] }));
+        const result = run(['apply-rewrite', task, response, profile]);
+        assert.equal(result.status, 2, result.stderr);
+        const applied = JSON.parse(result.stdout);
+        assert.equal(applied.status, 'needs_semantic_review');
+        assert.equal(applied.candidate, 'I use the answer with useful detail and clear mechanism.');
     }
     finally {
         rmSync(directory, { recursive: true, force: true });
@@ -57,7 +133,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/);
     }
@@ -91,7 +167,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 });
@@ -107,12 +183,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/copy-spec.js

@@ -0,0 +1,48 @@
+import { sentences } from './text.js';
+function normalized(value) {
+    return value.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+function isText(value, limit) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= limit;
+}
+function isClaim(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const claim = value;
+    return isText(claim.id, 100) && /^[A-Za-z0-9._-]+$/.test(claim.id)
+        && isText(claim.text, 2_000) && isText(claim.evidence, 4_000)
+        && (claim.mutable === undefined || typeof claim.mutable === 'boolean');
+}
+export function parseCopySpec(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('CopySpec must be a JSON object.');
+    const spec = value;
+    if (spec.version !== '1' || !isText(spec.audience, 500) || !isText(spec.intent, 500) || !isText(spec.channel, 100)
+        || !Array.isArray(spec.claims) || spec.claims.length === 0 || spec.claims.length > 100 || !spec.claims.every(isClaim)
+        || new Set(spec.claims.map((claim) => claim.id)).size !== spec.claims.length
+        || (spec.prohibitedClaims !== undefined && (!Array.isArray(spec.prohibitedClaims) || spec.prohibitedClaims.length > 100 || !spec.prohibitedClaims.every((claim) => isText(claim, 2_000))))) {
+        throw new Error('CopySpec is not valid. It needs version "1", audience, intent, channel, unique claims with text and evidence, and optional prohibitedClaims.');
+    }
+    return spec;
+}
+export function verifyClaims(candidate, spec) {
+    const draftSentences = sentences(candidate);
+    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 });
+        }
+    }
+    for (const claim of spec.prohibitedClaims ?? []) {
+        if (normalizedCandidate.includes(normalized(claim))) {
+            failures.push({ id: claim, code: 'prohibited_claim', message: `Prohibited claim appears in the candidate: ${claim}` });
+        }
+    }
+    return { passed: failures.length === 0, failures, sentenceClaims };
+}

package/dist/editorial-packs.js

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