@holdyourvoice/hyv 3.4.0 → 3.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/Readme.md +70 -127
  2. package/dist/cli.js +365 -327
  3. package/dist/fact-linter.js +107 -98
  4. package/dist/mcp.js +43 -192
  5. package/dist/rebuild-task.test.js +1 -1
  6. package/dist/stage1-evaluation.js +74 -48
  7. package/dist/text.js +8 -1
  8. package/dist/version.js +1 -1
  9. package/package.json +1 -1
package/Readme.md CHANGED
@@ -2,179 +2,122 @@
2
2
 
3
3
  [![npm downloads](https://img.shields.io/npm/dt/%40holdyourvoice%2Fhyv?label=npm%20downloads&color=2f81f7)](https://www.npmjs.com/package/@holdyourvoice/hyv)
4
4
 
5
- Hold Your Voice is a local-first writing gate. It helps you use AI without losing the parts of your writing that make it yours.
5
+ Hold Your Voice (`hyv`) is a local writing checker. It helps you edit AI-assisted writing without losing your own writing patterns.
6
6
 
7
- It runs two checks on a draft, with separate scores and pass states. A strong result in one engine leaves the other engine's finding unchanged.
7
+ It runs two independent checks:
8
8
 
9
- - **VoiceDNA** compares your draft with observable elements from your own writing samples.
10
- - **AI Editor** flags a versioned set of editorial patterns that make writing sound generic or formulaic.
9
+ - VoiceDNA compares a draft with a profile built from your writing samples.
10
+ - AI Editor finds deterministic patterns that often make writing generic or formulaic.
11
11
 
12
- Everything runs from local files. There are no accounts, no telemetry, and no runtime network requests. The optional Claude extension is a local adapter around the same engine.
12
+ The package also checks hidden Unicode, source-backed facts, document logic, and protected claims. All checks run locally, without model calls, automatic draft changes, or runtime network requests.
13
13
 
14
- > **Status:** [`@holdyourvoice/hyv`](https://www.npmjs.com/package/@holdyourvoice/hyv) runs locally and makes no runtime network requests.
14
+ ## install
15
15
 
16
- ## Start here
17
-
18
- **Requirements:** Node.js 20+, npm, and at least two writing samples you have the right to use.
19
-
20
- ### Install
16
+ You need Node.js 20 or newer and at least two writing samples you have the right to use.
21
17
 
22
18
  ```bash
23
19
  npm install --global @holdyourvoice/hyv
24
- hyv patterns
25
20
  ```
26
21
 
27
- No global install? Run any command with `npx @holdyourvoice/hyv`.
22
+ For a one-off command, replace `hyv` with `npx @holdyourvoice/hyv`.
23
+
24
+ ## basic workflow
28
25
 
29
- ### Build a profile
26
+ 1. Build a local profile from your samples.
30
27
 
31
28
  ```bash
32
- hyv profile profile.json samples/one.md samples/two.md --avoid=overused-phrase
29
+ hyv profile profile.json samples/one.md samples/two.md
33
30
  ```
34
31
 
35
- Use writing by one person, with a similar audience and format. The command needs at least two samples. It writes a portable JSON profile and keeps your samples on your machine. Repeat `--avoid=phrase` for each phrase that must block a candidate.
32
+ Add `--avoid=phrase` for wording that must block a draft. Repeat the option for more phrases.
36
33
 
37
- ### Analyze a draft
34
+ 2. Check a draft against that profile.
38
35
 
39
36
  ```bash
40
37
  hyv analyze draft.md profile.json
41
38
  ```
42
39
 
43
- The result is JSON with independent reports. The outer `passed` field is true only when each engine passes.
44
-
45
- ```json
46
- {
47
- "voiceDna": { "score": 93, "passed": true, "findings": [] },
48
- "aiEditor": { "score": 88, "passed": true, "findings": [] },
49
- "hygiene": { "suspiciousCount": 0, "fixableCount": 0, "hits": [] },
50
- "passed": true
51
- }
52
- ```
40
+ The result contains separate VoiceDNA and AI Editor reports. The top-level `passed` value is true only when every required check passes.
53
41
 
54
- ### Edit and verify
42
+ 3. Create an editing brief, edit the draft, and verify the candidate.
55
43
 
56
44
  ```bash
57
45
  hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
58
46
  hyv verify draft.md candidate.md profile.json
59
47
  ```
60
48
 
61
- Give the brief and draft to a human editor or any model you trust. Ask for replacement sentences keyed by sentence number, then save them as a separate candidate file. `verify` compares the original and candidate, reports new findings, and exits `2` when the candidate fails the gate.
49
+ Send the brief to a human editor or a model you choose. Delivery stays under your control.
62
50
 
63
- ### Gate final output
51
+ 4. Check the exact text before delivery.
64
52
 
65
53
  ```bash
54
+ hyv final-check candidate.md
66
55
  producer | hyv final-check -
67
- hyv final-check final-response.md
68
56
  ```
69
57
 
70
- `final-check` is the last step before text reaches a user. It needs no profile. Clean text goes to stdout byte-for-byte. If hidden Unicode remains, stdout stays empty and the command exits `2`. Run it after the last edit, formatter, or template expansion.
58
+ `final-check` writes accepted text to stdout. It withholds output and exits with code `2` when unresolved hidden Unicode remains.
71
59
 
72
- ### Clean hidden Unicode
60
+ ## commands
73
61
 
74
- ```bash
75
- hyv hygiene draft.md
76
- hyv hygiene draft.md --fix
77
- ```
62
+ | Command | Purpose |
63
+ | --- | --- |
64
+ | `hyv profile <profile.json> <sample...>` | Build a local profile from two or more samples. |
65
+ | `hyv analyze <draft> <profile.json>` | Run VoiceDNA, AI Editor, and hygiene checks. |
66
+ | `hyv hygiene <draft> [--fix]` | Inspect hidden Unicode or write a conservative cleaned copy. |
67
+ | `hyv inspect-hidden-text <draft> [policy.json]` | Inspect hidden text with an optional policy. |
68
+ | `hyv apply-hidden-text-policy <draft> <policy.json> <output>` | Apply approved hidden-text removals. |
69
+ | `hyv final-check <path\|->` | Gate the exact text before delivery. |
70
+ | `hyv fact-lint <draft\|-> --source=id:path` | Check claims against local source files. |
71
+ | `hyv logic-lint <draft\|-> [brief.json]` | Check deterministic document logic. |
72
+ | `hyv batch-analyze <draft...>` | Find repeated openings and endings across drafts. |
73
+ | `hyv rewrite-prompt <draft> <profile.json>` | Create a constrained editing brief. |
74
+ | `hyv prepare-rewrite ...` | Create a fingerprint-bound edit task. |
75
+ | `hyv apply-rewrite ...` | Apply and verify a response to an edit task. |
76
+ | `hyv prepare-judgment ...` | Create a pre-edit or post-candidate judgment task. |
77
+ | `hyv reduce-judgment <envelope...>` | Reduce judgments to SHIP, EDIT, REBUILD, CLEAR, or ESCALATE. |
78
+ | `hyv prepare-rebuild ...` | Create an authorized whole-document rebuild task. |
79
+ | `hyv rebuild-writer-request ...` | Create the writer-only part of a rebuild task. |
80
+ | `hyv apply-rebuild ...` | Apply and verify an authorized rebuild response. |
81
+ | `hyv verify <original> <candidate> <profile.json>` | Verify a candidate without changing learning state. |
82
+ | `hyv verify-spec ...` | Verify a candidate and a CopySpec. |
83
+ | `hyv lifecycle ...` | Run semantic review and final approval steps. |
84
+ | `hyv learning ...` | Inspect or change local profile learning. |
85
+ | `hyv patterns` | Print the active AI Editor rule catalog. |
86
+ | `hyv agent list\|validate\|describe\|emit` | Inspect or emit portable agent contracts. |
87
+ | `hyv mcp` | Start the local MCP server on standard input/output. |
78
88
 
79
- Inspect zero-width characters, bidirectional controls, tag characters, and unusual spaces. Add `--fix` to write a cleaned copy while leaving the original untouched. The cleaner only removes non-semantic ASCII controls and byte-order marks; everything else is reported for review because it can carry real meaning.
80
-
81
- ## The editing loop
82
-
83
- ```mermaid
84
- flowchart LR
85
- S[Your samples] --> P[Build profile]
86
- P --> D[VoiceDNA profile]
87
- T[Draft] --> A[Analyze]
88
- D --> A
89
- A --> V[VoiceDNA report]
90
- A --> E[AI Editor report]
91
- V --> B[Tiered brief]
92
- E --> B
93
- B --> C[Human or chosen model]
94
- T --> G[Verify candidate]
95
- C --> G
96
- D --> G
97
- G --> R[Errors block; findings stay visible]
98
- R --> H[final-check before output]
99
- ```
89
+ Most commands return JSON. Exit code `0` means the command completed, `2` means a content or policy gate failed, and `1` means the command or input was invalid.
100
90
 
101
- The tool never edits your draft. You decide which findings are valid, apply the changes yourself, and run the final check.
91
+ Run `hyv <command>` without enough arguments to see its exact usage. Read the [CLI reference](docs/wiki/CLI-Reference.md) for every option.
102
92
 
103
- ## A few more commands
93
+ ## portable agents and MCP
104
94
 
105
- | Command | Use it when |
106
- | --- | --- |
107
- | `hyv verify-spec` | A draft has facts that must stay verbatim (CopySpec). |
108
- | `hyv fact-lint` | Check a draft against local evidence sources. |
109
- | `hyv batch-analyze` | Catch exact repeated sentences across drafts. |
110
- | `hyv prepare-rewrite` / `apply-rewrite` | Fingerprint-bound sentence or range edits. |
111
- | `hyv prepare-rebuild` / `apply-rebuild` | Whole-document rebuild after an authorized recommendation. |
112
- | `hyv prepare-judgment` / `reduce-judgment` | Reduce findings to SHIP, EDIT, or REBUILD. |
113
- | `hyv lifecycle` | Semantic and human-review lifecycle steps. |
114
- | `hyv learning show` | Inspect local voice-memory preferences. |
115
-
116
- ## Commands
117
-
118
- | Command | Input | Output |
119
- | --- | --- | --- |
120
- | `hyv profile <profile.json> <sample...>` | Two or more text files | Profile JSON |
121
- | `hyv analyze <draft> <profile.json>` | Draft and profile | Analysis JSON |
122
- | `hyv hygiene <draft> [--fix] [--output=path]` | Draft | Hygiene report or cleaned copy plus receipt |
123
- | `hyv inspect-hidden-text <draft> [policy.json]` | Draft and optional policy | Hidden-text inspection report |
124
- | `hyv apply-hidden-text-policy <draft> <policy.json> <output.md>` | Draft and approved policy | Sanitized output plus receipt |
125
- | `hyv final-check <path\|->` | Any final text | Accepted text on stdout or a withheld-output report |
126
- | `hyv logic-lint <draft\|-> [writing-brief.json]` | Draft and optional brief | Deterministic logic-lint report |
127
- | `hyv rewrite-prompt <draft> <profile.json>` | Draft and profile | Markdown editing brief |
128
- | `hyv prepare-rewrite <draft> <profile.json> <task.json>` | Draft and profile | Versioned task file |
129
- | `hyv apply-rewrite <task.json> <response.json> <profile.json>` | Task, response, profile | Candidate evaluation JSON |
130
- | `hyv prepare-judgment <pre-edit\|post-candidate> <kind> <draft> <profile.json> <task.json> [candidate.md]` | Draft, profile, optional candidate | Versioned judgment task |
131
- | `hyv reduce-judgment <envelope.json> ...` | Signed judgment envelopes | Recommendation JSON |
132
- | `hyv prepare-rebuild <draft> <profile.json> <reduction.json> <copy-spec.json> <task.json> [--recomposition-policy policy.json]` | Draft, recommendation, CopySpec, capability, optional policy | Versioned rebuild task |
133
- | `hyv rebuild-writer-request <task.json> <writer-request.json>` | Rebuild task | Writer-only rebuild request |
134
- | `hyv apply-rebuild <task.json> <response.json> <profile.json>` | Task, response, profile, capability | Candidate evaluation JSON |
135
- | `hyv verify <original> <candidate> <profile.json>` | Original, candidate, profile | Verification JSON and exit code |
136
- | `hyv verify-spec <original> <candidate> <profile.json> <copy-spec.json>` | Original, candidate, profile, CopySpec | Verification JSON with hard claim gate |
137
- | `hyv learning <show\|inspect\|add\|record\|record-approved\|ratify\|supersede\|migrate\|clear> ...` | Profile, operation, bounded metadata | Preferences or a text-free receipt |
138
- | `hyv lifecycle <prepare-semantic\|submit-verdict\|inspect\|validate-final-approval\|finalize> ...` | Versioned lifecycle artifacts | Lifecycle artifact or metadata |
139
- | `hyv patterns` | None | Ruleset JSON |
140
- | `hyv mcp` | None | Local MCP server on stdio |
141
- | `hyv agent list\|validate\|describe\|emit <id> [--host HOST] [--mode prompt\|json] [--output FILE]` | Optional agent id | Portable agent contract (see below) |
142
-
143
- Every file argument can be `-` when the command accepts input on standard input. Use `npx @holdyourvoice/hyv <command>` if you have not installed the CLI globally.
144
-
145
- ## Portable agents
146
-
147
- The 23 writing and runtime commands are also model-neutral portable agent packages under `skills/hyv-*/` (an `agent.json` contract, a `SKILL.md`, and an `agents/openai.yaml` interface), mirroring the clean-code portable-agent pattern. `hyv agent list` prints every package; `hyv agent validate [id]` checks the contract schema; `hyv agent describe <id> --host HOST` resolves permissions against a host catalog; and `hyv agent emit <id> --mode prompt|json --host HOST` emits a host-aware contract. The subcommand stays local. `emit --output` creates a new contract file and refuses an existing target. Read the [portable agents guide](docs/wiki/Portable-Agents.md) for the package contract, host model, and examples.
148
-
149
- ## Privacy
150
-
151
- Your samples, drafts, profiles, and candidates stay on your machine. Verification is read-only. Learning commands can write text-free local events under `~/.hyv/learning/` — profile fingerprint, finding IDs, counts, and an opaque digest. No writing text is uploaded, and the package makes no runtime network requests.
152
-
153
- Keep writing samples, edit histories, and client text out of public commits unless you hold the rights and a provenance record. A profile is aggregated JSON and can still reveal vocabulary, so store private profiles outside public repositories.
154
-
155
- ## Documentation
156
-
157
- | Read this | When you need |
158
- | --- | --- |
159
- | [The Wiki](https://github.com/shashank-sn/holdyourvoice/wiki) | Product and contributor docs. |
160
- | [Architecture](docs/ARCHITECTURE.md) | Source boundaries and extension rules. |
161
- | [Prompt contract](docs/PROMPT-CONTRACT.md) | The tier order and editing constraints. |
162
- | [VoiceDNA](docs/VOICE-DNA.md) | The 13 profile elements. |
163
- | [Fact linter](docs/wiki/Fact-Linter.md) | The source-consistency checker. |
164
- | [Portable agents](docs/wiki/Portable-Agents.md) | Load or emit a host-aware contract for one HYV command. |
165
- | [Support](SUPPORT.md) | Funding without a feature gate. |
95
+ The `skills/hyv-*` directories package the CLI workflows as portable agent contracts. Use `hyv agent validate` to check them and `hyv agent emit` to create a host-specific prompt or JSON contract.
96
+
97
+ The MCP server exposes the same local engine for compatible hosts. Read [Portable Agents](docs/wiki/Portable-Agents.md), [Claude Desktop setup](docs/CLAUDE-DESKTOP.md), or [Claude Code setup](docs/CLAUDE-CODE.md).
98
+
99
+ ## privacy and safety
100
+
101
+ Drafts, samples, profiles, candidates, and source files stay on your machine. The package has no accounts, telemetry, hosted analysis, or runtime network requests.
102
+
103
+ Learning commands can write text-free events under `~/.hyv/learning/`. A manually added learning instruction is stored as entered. Keep private writing, profiles, and client data out of public repositories.
166
104
 
167
- ## Contribute
105
+ VoiceDNA fit, AI-pattern findings, fact consistency, and human approval are separate results. A clean report only states that its configured checks passed. Authorship, factual truth, and publication quality still need separate evidence or review.
106
+
107
+ ## performance
108
+
109
+ The frozen synthetic runtime benchmark covers natural text, punctuation-heavy text, final checking, cold CLI startup, and fact linting. On its 100,000-character dotted v3 fixture, seven-run median process CPU time fell from 8,823.134 ms to 17.245 ms. That is 99.8045% lower for this stress case, not a whole-application speedup. Read the [runtime benchmark contract and full results](https://github.com/shashank-sn/holdyourvoice/blob/main/benchmarks/runtime/README.md).
110
+
111
+ ## development
168
112
 
169
113
  ```bash
114
+ npm ci
170
115
  npm test
171
116
  npm run check:release
172
117
  ```
173
118
 
174
- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Keep changes narrow, add tests when behavior changes, and keep private or unlicensed material out of the repo.
175
-
176
- `@holdyourvoice/hyv` publishes automatically when a change reaches `main`. Bump the version in `package.json` in the same pull request as a release-worthy change; the workflow publishes only if that version is not already on npm.
119
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The main design boundaries are in [Architecture](docs/ARCHITECTURE.md) and the full user guides are in the [wiki](https://github.com/shashank-sn/holdyourvoice/wiki).
177
120
 
178
- ## License
121
+ ## license
179
122
 
180
- [MIT](LICENSE). Third-party writing and data retain their own rights.
123
+ [MIT](LICENSE). Third-party writing and data keep their own rights.