@holdyourvoice/hyv 2.9.28 → 3.0.0

package/LICENSE

@@ -1,26 +1,21 @@
-License
-Copyright © 2025 Hold Your Voice (holdyourvoice.com)
+MIT License
 
-All Rights Reserved.
+Copyright (c) 2026 Shashank
 
-This software ("@holdyourvoice/hyv") is proprietary and confidential.
-It is provided for use solely by authorized licensees of Hold Your Voice.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-1. **Grant of License**: A non-exclusive, non-transferable, revocable license
-   is granted to use this software for its intended purpose as a writing
-   analysis tool.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-2. **Restrictions**: You may not:
-   a) Redistribute, sublicense, sell, or lease this software or any
-      derivative works.
-   b) Modify, reverse engineer, decompile, or disassemble this software.
-   c) Remove or alter any proprietary notices.
-   d) Use this software in violation of applicable law.
-
-3. **No Warranty**: This software is provided "as is" without warranty of
-   any kind, express or implied.
-
-4. **Limitation of Liability**: Hold Your Voice shall not be liable for any
-   damages arising from the use of this software.
-
-For licensing inquiries: hello@holdyourvoice.com
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,247 @@
+# Hold Your Voice
+
+Hold Your Voice is an MIT-licensed, local-first writing gate for people who want AI help without losing the parts of their writing that make it theirs.
+
+It checks a draft through two separate programs:
+
+- **VoiceDNA** compares the draft with 13 observable elements from your own local writing samples.
+- **AI Editor** flags a small, versioned set of editorial patterns that can make writing generic, formulaic, or inflated.
+
+Those programs keep separate findings, scores, and pass states. A strong result from one never cancels a failure in the other. The tool creates a tiered editing brief, then checks the candidate again before you accept it.
+
+Everything runs from local files: accounts, API calls, MCP servers, telemetry, payment collection, and runtime network requests stay out of the core path.
+
+> **Status:** the public CLI is published as [`@holdyourvoice/hyv`](https://www.npmjs.com/package/@holdyourvoice/hyv). It runs locally and makes no runtime network requests.
+
+## Why it exists
+
+A draft can avoid obvious AI-shaped writing and still sound unlike its author. It can also match a writer’s short sentences while leaning on empty persuasion templates. Those are different problems. Treating them as one generic score hides the useful signal.
+
+Hold Your Voice keeps the work visible:
+
+| Question | Program | Result |
+| --- | --- | --- |
+| Does the draft still resemble this writer’s observable mechanics? | VoiceDNA | A profile-based score, findings, and pass state. |
+| Does the draft contain a configured editorial pattern worth inspecting? | AI Editor | A rule-based score, sentence findings, and pass state. |
+| Did the rewrite introduce a new blocker or replace too much? | Verification | Regressions, preservation score, and a release decision. |
+
+Its scope is a local writing gate. Authorship detection, fact checking, plagiarism review, and hosted generation each need their own tools. Hold Your Voice gives a writer or chosen model a narrow editing brief, then asks the same two engines to inspect the result.
+
+## Start here
+
+### Requirements
+
+- Node.js 20 or newer.
+- npm.
+- At least two local writing samples you have the right to use.
+
+### Install and verify
+
+```bash
+npx @holdyourvoice/hyv patterns
+```
+
+Run any command without a global install with `npx @holdyourvoice/hyv`. To use the short `hyv` command repeatedly:
+
+```bash
+npm install --global @holdyourvoice/hyv
+hyv patterns
+```
+
+To contribute, clone this repository, run `npm install`, then run `npm test` and `npm run check:release`.
+
+### Build a local VoiceDNA profile
+
+```bash
+npx @holdyourvoice/hyv profile profile.json samples/one.md samples/two.md --avoid=overused-phrase
+```
+
+Use writing by one person, with a similar audience and format where possible. The command needs at least two samples. It creates a portable JSON profile and keeps the samples on your machine. Repeat `--avoid=phrase` for each local phrase that must block a candidate.
+
+### Inspect a draft
+
+```bash
+npx @holdyourvoice/hyv analyze draft.md profile.json
+```
+
+The result is JSON with independent reports:
+
+```json
+{
+  "voiceDna": { "score": 93, "passed": true, "findings": [] },
+  "aiEditor": { "score": 88, "passed": true, "findings": [] },
+  "passed": true
+}
+```
+
+Read both reports. The outer `passed` field means each engine passed. Scores remain independent.
+
+### Create an editing brief
+
+```bash
+npx @holdyourvoice/hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
+```
+
+Give the brief and draft to a human editor or any model you trust. This repository stays out of that provider call. Ask for replacement sentences keyed by sentence number, then save the output as a separate candidate file.
+
+### Verify the candidate
+
+```bash
+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.
+
+## The editing loop
+
+```mermaid
+flowchart LR
+  S[Your local samples] --> P[Build profile]
+  P --> D[VoiceDNA JSON]
+  T[Draft] --> A[Analyze]
+  D --> A
+  A --> V[VoiceDNA report]
+  A --> E[AI Editor report]
+  V --> B[Tiered brief]
+  E --> B
+  B --> C[Human or chosen model]
+  T --> G[Verify candidate]
+  C --> G
+  D --> G
+  G --> R[Pass or inspect regressions]
+```
+
+The tool never applies changes to your draft. You decide which findings are valid, apply replacement sentences deliberately, and run the final check.
+
+## The five rewrite tiers
+
+The prompt has an order. Lower tiers can refine a higher tier; they cannot override it.
+
+1. **Tier 0: preservation.** Keep facts, names, numbers, claims, and every unflagged sentence exactly. Keep the response within the supplied sentences.
+2. **Tier 1: release blockers.** Resolve profile avoid-list phrases and red findings.
+3. **Tier 2: VoiceDNA.** Use the 13 profile elements as a writer-specific target.
+4. **Tier 3: AI Editor.** Inspect yellow findings. Change a line only when the repair helps.
+5. **Tier 4: output.** Return replacement sentences keyed by sentence number.
+
+This order protects meaning before style. Read the complete [prompt contract](docs/PROMPT-CONTRACT.md) before changing it.
+
+## VoiceDNA: 13 observable elements
+
+VoiceDNA is a local profile of writing mechanics drawn from the samples you choose. It makes no claim about personality. Its structural measurements support Unicode writing; the current point-of-view and transition lists are English-specific evidence.
+
+| # | Element | What it captures | Current gate behavior |
+| --- | --- | --- | --- |
+| 1 | Sentence length | Mean words per sentence | Yellow finding outside the profile band. |
+| 2 | Sentence variation | Spread of sentence lengths | Used to set the sentence-length tolerance. |
+| 3 | Sentence structure | Frequent three-word openings | Profile evidence. |
+| 4 | Rhythm | Change between neighbouring sentence lengths | Profile evidence. |
+| 5 | Paragraph length | Mean sentences per paragraph | Profile evidence. |
+| 6 | Opening moves | Frequent first words | Profile evidence. |
+| 7 | Vocabulary | Frequent non-stop words | Profile evidence and rewrite context. |
+| 8 | Lexical density | Share of non-stop words | Profile evidence. |
+| 9 | Point of view | First, second, third, or mixed | Yellow finding for a dominant-profile mismatch. |
+| 10 | Punctuation | Counts of selected marks | Profile evidence. |
+| 11 | Case style | Lowercase, standard, or mixed | Yellow finding on mismatch. |
+| 12 | Question rate | Sentences ending in questions | Yellow finding for a material difference. |
+| 13 | Transitions | Frequent recognised connectors | Profile evidence and rewrite context. |
+
+An explicit profile avoid list creates red findings. The other evidence-only elements are calculated and shown. Future enforcement needs a written policy, counterexamples, and tests.
+
+Read the full [VoiceDNA reference](docs/VOICE-DNA.md) and [Wiki guide](https://github.com/shashank-sn/holdyourvoice/wiki/VoiceDNA).
+
+## AI Editor: inspectable rules
+
+AI Editor uses a local, deterministic ruleset. Each rule has a stable ID, severity, reason, and repair direction. Run this command to see the rules that actually execute in your checkout:
+
+```bash
+npx @holdyourvoice/hyv patterns
+```
+
+Red findings are release blockers. Yellow findings are a request to inspect a sentence in context. A match never proves who wrote the text, and a clean scan never proves the text is good.
+
+The repository also includes a public [220-pattern editorial catalog](docs/patterns/AI-WRITING-PATTERNS-1-220.md). That catalog is broader than the executable ruleset on purpose. A catalog entry becomes executable only after the project has defined its counterexamples, reviewed public provenance, written tests, and decided the rule is narrow enough to help without creating noise.
+
+## Verification contract
+
+Verification analyzes the original and candidate with the same profile and ruleset. It passes only when:
+
+- VoiceDNA passes.
+- AI Editor passes.
+- The candidate introduces zero new red findings.
+- The lexical preservation score is at least 70.
+
+The preservation score is a guardrail based on retained original words longer than four characters. A human still needs to review facts, source links, intent, and reader value.
+
+## Commands
+
+| Command | Input | Output | Use it when |
+| --- | --- | --- | --- |
+| `hyv profile <profile.json> <sample...>` | Two or more text files | Profile JSON | You need a new local reference. |
+| `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 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.
+
+## Project map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/contracts.ts` | Profiles, findings, reports, analysis, and verification data shapes. |
+| `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/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. |
+| `CONTRIBUTING.md` | Public-safety rules and the contributor model. |
+| `scripts/release-audit.mjs` | Checks source files for credential and network markers. |
+
+`pipeline.ts` is the sole composition point. It combines pass states and preserves each engine’s separate score.
+
+## Privacy and data rights
+
+The runtime uses files on your machine. Samples, drafts, profiles, candidates, feedback history, embeddings, and client data stay there.
+
+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.
+
+See the [privacy guide](https://github.com/shashank-sn/holdyourvoice/wiki/Privacy-and-Data-Rights) for maintainer and contributor boundaries.
+
+## Benchmarks and claims
+
+The repository preserves historical product material in [docs/BENCHMARKS.md](docs/BENCHMARKS.md), with related public articles about the [Voice Memory Composer](https://holdyourvoice.com/blog/voice-memory-composer) and [Hold Your Voice vs GPT-5.6 writing](https://holdyourvoice.com/blog/hold-your-voice-vs-gpt-5-6-writing).
+
+Treat those as dated reference material. A reproducible benchmark needs rights-cleared data, frozen settings, a published rubric, separate dimensions, and visible limitations. The [benchmark guide](https://github.com/shashank-sn/holdyourvoice/wiki/Benchmarks-and-Research) explains the standard.
+
+## Documentation
+
+| Read this | When you need |
+| --- | --- |
+| [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. |
+| [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. |
+
+## Contribute
+
+```bash
+npm test
+npm run check:release
+```
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Keep changes narrow. Add tests when code behavior changes. Separate current executable behavior, editorial guidance, historical research, and proposals. Keep private, client, secret, and unlicensed material out of issues, fixtures, tests, and documentation.
+
+## npm releases
+
+`@holdyourvoice/hyv` is published automatically after a change to the package source reaches `main`. The workflow publishes only when the version in `package.json` is not already on npm, so bump that version in the same pull request as a release-worthy change. It runs the tests and release audit before publishing, then verifies that npm reports the package as MIT licensed.
+
+## Support
+
+Hold Your Voice stays fully open source. Read the [funding policy](FUNDING.md) or [sponsor maintenance on GitHub](https://github.com/sponsors/shashank-sn) with a one-time or recurring sponsorship. Sponsorship funds maintenance while the feature set and local privacy contract remain the same for everyone.
+
+## License
+
+[MIT](LICENSE). You can use, modify, and distribute the code under its terms. Third-party writing and data retain their own rights.

package/dist/ai-editor.js

@@ -0,0 +1,9 @@
+import { sentences } from './text.js';
+export const RULESET_VERSION = '2026.08.04.1';
+export const rules = [
+    ['ai.delve', 'red', /\bdelve\b/i, 'Generic AI verb.', 'Use a concrete verb.'], ['ai.leverage', 'red', /\bleverage\b/i, 'Business-jargon default.', 'Say what is being used.'], ['ai.tapestry', 'red', /\btapestry\b/i, 'Abstract metaphor without content.', 'Name the thing.'], ['ai.holistic', 'red', /\bholistic\b/i, 'Vague qualifier.', 'Describe the actual approach.'], ['ai.robust', 'yellow', /\brobust\b/i, 'Claims strength without evidence.', 'State what makes it strong.'], ['ai.landscape', 'yellow', /\blandscape\b/i, 'Generic context word.', 'Name the field.'], ['ai.game-changer', 'red', /\bgame[ -]changer\b/i, 'Promotional cliche.', 'Explain what changed.'], ['ai.formulaic-connector', 'yellow', /\b(firstly|secondly|moreover|furthermore|in conclusion)\b/i, 'Formulaic connector.', 'State the next point directly.'], ['ai.hedging', 'yellow', /\b(arguably|perhaps|it is worth noting|some might say)\b/i, 'Hedge hides the claim.', 'Make or remove the claim.'], ['ai.signpost', 'yellow', /\b(this is why|this is how|here.?s why)\b/i, 'Meta-signpost.', 'Lead with the observation.'], ['ai.not-just', 'red', /\bnot just\b.{0,80}\bbut\b/i, 'Binary persuasion template.', 'State the point plainly.'], ['ai.truth-setup', 'yellow', /\b(the hard|the brutal|the uncomfortable) truth\b/i, 'Manufactured revelation.', 'Name the fact.'], ['ai.em-dash', 'yellow', /—/, 'Dramatic em-dash use.', 'Use a sentence break when needed.'], ['ai.question-hook', 'yellow', /^(have you|do you|what if|why do|how do)\b/i, 'Question opener instead of a concrete start.', 'Open from an observation.'], ['ai.abstract-cluster', 'yellow', /\b(alignment|authenticity|clarity|strategy|value)\b.*\b(alignment|authenticity|clarity|strategy|value)\b/i, 'Abstract nouns pile up.', 'Use concrete nouns and actions.']
+].map(([id, severity, expression, reason, suggestion]) => ({ id: id, severity: severity, expression: expression, reason: reason, suggestion: suggestion }));
+export function analyzeAiEditor(text) { const findings = []; for (const s of sentences(text))
+    for (const r of rules)
+        if (r.expression.test(s.text))
+            findings.push({ engine: 'ai_editor', id: r.id, severity: r.severity, sentence: s.index, excerpt: s.text, reason: r.reason, suggestion: r.suggestion }); const reds = findings.filter(f => f.severity === 'red').length, score = Math.max(0, 100 - reds * 18 - (findings.length - reds) * 6); return { engine: 'ai_editor', version: RULESET_VERSION, score, passed: reds === 0, findings }; }

package/dist/ai-editor.test.js

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { analyzeAiEditor, rules } from './ai-editor.js';
+test('publishes executable rules with stable IDs and repair directions', () => {
+    assert.ok(rules.length > 0);
+    for (const rule of rules) {
+        assert.match(rule.id, /^ai\./);
+        assert.ok(rule.reason.length > 0);
+        assert.ok(rule.suggestion.length > 0);
+    }
+});
+test('detects every executable rule against its exact sentence', () => {
+    const examples = [
+        ['ai.delve', 'we will delve into it.'],
+        ['ai.leverage', 'we leverage the existing logs.'],
+        ['ai.tapestry', 'the tapestry explains the work.'],
+        ['ai.holistic', 'a holistic review starts today.'],
+        ['ai.robust', 'robust evidence supports the claim.'],
+        ['ai.landscape', 'the market landscape changed.'],
+        ['ai.game-changer', 'this is a game-changer.'],
+        ['ai.formulaic-connector', 'Firstly, check the invoice.'],
+        ['ai.hedging', 'Perhaps the invoice is late.'],
+        ['ai.signpost', 'This is why the invoice matters.'],
+        ['ai.not-just', 'this is not just fast but reliable.'],
+        ['ai.truth-setup', 'the hard truth is in the logs.'],
+        ['ai.em-dash', 'the logs failed — retry later.'],
+        ['ai.question-hook', 'Have you checked the logs?'],
+        ['ai.abstract-cluster', 'alignment and clarity are missing.'],
+    ];
+    for (const [id, example] of examples) {
+        const report = analyzeAiEditor(example);
+        assert.deepEqual(report.findings.map((finding) => [finding.id, finding.sentence]), [[id, 1]], id);
+    }
+});
+test('keeps a counterexample for every executable rule', () => {
+    const counterexamples = [
+        ['ai.delve', 'we inspect the logs.'],
+        ['ai.leverage', 'we use the existing logs.'],
+        ['ai.tapestry', 'the report explains the work.'],
+        ['ai.holistic', 'the review covers the named files.'],
+        ['ai.robust', 'the evidence includes three dated reports.'],
+        ['ai.landscape', 'the market changed after the price cut.'],
+        ['ai.game-changer', 'the release removed a manual step.'],
+        ['ai.formulaic-connector', 'next, check the invoice.'],
+        ['ai.hedging', 'the invoice is late.'],
+        ['ai.signpost', 'the invoice matters because it is overdue.'],
+        ['ai.not-just', 'the service is fast and reliable.'],
+        ['ai.truth-setup', 'the logs show the service failed.'],
+        ['ai.em-dash', 'the logs failed; retry later.'],
+        ['ai.question-hook', 'the reviewer asked, have you checked the logs?'],
+        ['ai.abstract-cluster', 'the editor checked the contract and sent the invoice.'],
+    ];
+    for (const [id, example] of counterexamples) {
+        assert.equal(analyzeAiEditor(example).findings.some((finding) => finding.id === id), false, id);
+    }
+});
+test('keeps yellow findings as review cues rather than release blockers', () => {
+    const report = analyzeAiEditor('Firstly, the editor checked the invoice.');
+    assert.ok(report.findings.every((finding) => finding.severity === 'yellow'));
+    assert.equal(report.passed, true);
+});

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/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 { buildProfile } from './voice-dna.js';
+const usage = 'Commands: profile, analyze, rewrite-prompt, verify, patterns';
+function input(path) {
+    return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+}
+function isNumberRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    return Object.values(value).every((item) => typeof item === 'number' && Number.isFinite(item));
+}
+function isPunctuation(value) {
+    const marks = ['!', '?', ';', ':', '—'];
+    return isNumberRecord(value) && Object.values(value).every((item) => item >= 0) && Object.keys(value).length === marks.length && marks.every((mark) => mark in value);
+}
+function isMetrics(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const metrics = value;
+    const numbers = [metrics.sentenceLength, metrics.sentenceVariation, metrics.rhythm, metrics.paragraphLength, metrics.lexicalDensity, metrics.questionRate];
+    const stringArrays = [metrics.sentenceStructure, metrics.openingMoves, metrics.vocabulary, metrics.transitions];
+    return numbers.every((item) => typeof item === 'number' && Number.isFinite(item) && item >= 0)
+        && typeof metrics.lexicalDensity === 'number' && metrics.lexicalDensity <= 1
+        && typeof metrics.questionRate === 'number' && metrics.questionRate <= 1
+        && ['first_person', 'second_person', 'third_person', 'mixed'].includes(metrics.pointOfView ?? '')
+        && ['lowercase', 'standard', 'mixed'].includes(metrics.caseStyle ?? '')
+        && stringArrays.every((items) => Array.isArray(items) && items.every((item) => typeof item === 'string'))
+        && isPunctuation(metrics.punctuation);
+}
+function readProfile(path) {
+    const value = JSON.parse(input(path));
+    if (!value || typeof value !== 'object')
+        throw new Error('Profile must be a JSON object.');
+    const profile = value;
+    if (profile.version !== '2' || typeof profile.sampleCount !== 'number' || !Number.isInteger(profile.sampleCount) || profile.sampleCount < 2 || !isMetrics(profile.metrics) || !Array.isArray(profile.avoid) || !profile.avoid.every((item) => typeof item === 'string' && item.trim().length > 0)) {
+        throw new Error('Profile is not a valid Hold Your Voice version 2 profile. Rebuild it with the profile command.');
+    }
+    return profile;
+}
+function json(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function profileArguments(args) {
+    const [output, ...rest] = args;
+    const samples = [];
+    const avoid = [];
+    for (const argument of rest) {
+        if (argument.startsWith('--avoid=')) {
+            const phrase = argument.slice('--avoid='.length).trim();
+            if (!phrase)
+                throw new Error('Avoid phrases must use --avoid=phrase.');
+            avoid.push(phrase);
+        }
+        else {
+            samples.push(argument);
+        }
+    }
+    if (!output || samples.length < 2)
+        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) {
+    const [command, ...rest] = args;
+    if (command === 'profile') {
+        const { output, samples, avoid } = profileArguments(rest);
+        writeFileSync(output, `${JSON.stringify(buildProfile(samples.map(input), avoid), null, 2)}\n`);
+        return 0;
+    }
+    if (command === 'analyze') {
+        const [draft, profilePath] = rest;
+        if (!draft || !profilePath)
+            throw new Error('Usage: hyv analyze draft.md profile.json');
+        json(analyze(input(draft), readProfile(profilePath)));
+        return 0;
+    }
+    if (command === 'rewrite-prompt') {
+        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)));
+        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));
+        json(result);
+        return result.passed ? 0 : 2;
+    }
+    if (command === 'patterns') {
+        json({ version: RULESET_VERSION, rules: rules.map(({ expression, ...rule }) => ({ ...rule, expression: expression.source })) });
+        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;
+}

package/dist/cli.test.js

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+const cli = new URL('./cli.js', import.meta.url).pathname;
+function run(...args) {
+    return spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8' });
+}
+test('creates an explicit local avoid list and exposes the ruleset', () => {
+    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');
+        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');
+        assert.equal(created.status, 0, created.stderr);
+        assert.deepEqual(JSON.parse(readFileSync(profile, 'utf8')).avoid, ['unlock']);
+        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));
+    }
+    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 {
+        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');
+        writeFileSync(first, 'i write plainly. i name the work.');
+        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(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);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('rejects a malformed hand-edited profile before analysis', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const draft = join(directory, 'draft.md');
+        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);
+        assert.equal(result.status, 1);
+        assert.match(result.stderr, /not a valid Hold Your Voice version 2 profile/);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('rejects malformed profile enum values and punctuation', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'holdyourvoice-cli-'));
+    try {
+        const draft = join(directory, 'draft.md');
+        const profile = join(directory, 'profile.json');
+        writeFileSync(draft, 'i name the work.');
+        writeFileSync(profile, JSON.stringify({
+            version: '2',
+            sampleCount: 2,
+            metrics: {
+                sentenceLength: 4,
+                sentenceVariation: 1,
+                sentenceStructure: [],
+                rhythm: 1,
+                paragraphLength: 1,
+                openingMoves: [],
+                vocabulary: [],
+                lexicalDensity: 0.5,
+                pointOfView: 'fourth_person',
+                punctuation: [],
+                caseStyle: 'titlecase',
+                questionRate: 0,
+                transitions: [],
+            },
+            avoid: [''],
+        }));
+        assert.equal(run('analyze', draft, profile).status, 1);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+test('rejects hand-edited metrics outside their semantic bounds', () => {
+    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');
+        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);
+        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);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};