@holdyourvoice/hyv 3.6.0 → 4.0.0

package/Readme.md

@@ -1,200 +1,139 @@
-# Hold Your Voice
+# hold your voice
 
 [![npm downloads](https://img.shields.io/npm/dt/%40holdyourvoice%2Fhyv?label=npm%20downloads&color=2f81f7)](https://www.npmjs.com/package/@holdyourvoice/hyv)
 
-Hold Your Voice (`hyv`) is a local writing checker. It helps you edit AI-assisted writing without losing your own writing patterns. It is not an AI-authorship detector: it provides local, inspectable writing evidence while a human still decides what to publish.
-
-It runs two independent checks:
-
-- VoiceDNA compares a draft with a profile built from your writing samples.
-- AI Editor finds deterministic patterns that often make writing generic or formulaic.
-
-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.
-
-## how it works
-
-```mermaid
-flowchart TD
-    samples["Writing samples"] --> profile["Local VoiceDNA profile"]
-    draft["Draft"] --> analyze["hyv analyze"]
-    profile --> analyze
-    brief["Optional WritingBrief"] -.-> analyze
-
-    subgraph inspect["1 · inspect the draft"]
-        analyze --> voice["VoiceDNA check"]
-        analyze --> patterns["AI pattern lint"]
-        analyze --> hidden["Hidden-text / Unicode check"]
-        voice --> local{"Local result"}
-        patterns --> local
-        hidden -.-> local
-    end
-
-    local -->|No blocking change| candidate["Candidate text"]
-    local -->|Blocking edit scope| editTask["Prepare fingerprint-bound edit task"]
-    local -->|Judgment required| judgment["Prepare and reduce judgments"]
-    judgment --> route{"SHIP, EDIT, or REBUILD?"}
-    route -->|SHIP| candidate
-    route -->|EDIT| editTask
-    route -->|REBUILD| authorization["REBUILD recommendation + CopySpec + signed authorization"]
-    authorization --> rebuildTask["Prepare fingerprint-bound rebuild task"]
-    editTask --> editor["Human editor or model you choose"]
-    rebuildTask --> editor
-    editor --> response["Bound response"]
-
-    brief -.-> logic
-    sources["Optional fact sources in WritingBrief"] -.-> facts
-    spec["Optional for verify-spec; required for rebuild"] -.-> authorization
-    spec -.-> standard
-
-    subgraph verification["2 · verification gate"]
-        candidate --> standard["hyv verify / verify-spec"]
-        response --> mode{"Bound task mode"}
-        mode -->|EDIT| editApply["apply-rewrite + standard verification"]
-        mode -->|REBUILD| rebuildApply["apply-rebuild + rebuild verification"]
-        standard --> standardRules["Preservation gate + CopySpec claims when supplied"]
-        editApply --> standardRules
-        rebuildApply --> rebuildRules["CopySpec claims; preservation reported"]
-        standardRules --> engines["VoiceDNA + AI Editor checks and blocking regressions"]
-        rebuildRules --> engines
-        engines --> logic["Logic lint"]
-        logic --> facts["Fact lint when sources are supplied"]
-        facts --> outputGate["Hidden-text + final-output gate"]
-        outputGate --> passed{"All required checks pass?"}
-    end
-
-    passed -->|No| repair["Repair externally or prepare a new task"]
-    repair --> analyze
-    passed -->|Yes| review["Semantic review and human approval, when required"]
-    review --> final["Run final-check after the last change"]
-    final --> output["Exact accepted text"]
-```
+hold your voice (`hyv`) checks writing locally. it compares a draft with your writing samples, flags generic writing patterns, and checks an edited candidate before you use it. you supply the writing and the edits; hyv supplies inspectable findings and verification.
 
-HYV keeps draft inspection, candidate verification, and final delivery separate. Standard verification reruns VoiceDNA and AI Editor, rejects blocking regressions, enforces preservation, runs logic lint, applies fact lint when a WritingBrief supplies sources, and withholds hidden-text failures. `verify-spec` adds CopySpec claim checks. Authorized rebuilds require an upstream REBUILD recommendation, a CopySpec, and signed authorization; their verification reports preservation without using the standard preservation threshold. Run `final-check` again after the last human, model, formatter, or template change. HYV never calls a model; a human editor or model you choose supplies edits and judgments.
+it works through a command-line tool, an mcp server, and portable agent contracts. it needs node.js 20 or newer. it makes no model calls and needs no account or api key.
 
-## install
+## what it does
 
-You need Node.js 20 or newer and at least two writing samples you have the right to use.
+| check or workflow | result |
+| --- | --- |
+| voice dna | compares sentence structure, rhythm, vocabulary, punctuation, and other measurements with a local profile. |
+| ai editor | flags deterministic wording and structural patterns, with sentence locations and repair guidance. |
+| profiles | builds v2 or v3 profiles, assesses sample readiness, composes profiles, watches local sample files, and scores against held-out samples. |
+| fact and logic checks | compares claims with supplied source files and checks document structure, required facts, and claim polarity. |
+| hidden-text checks | inspects unicode controls, applies an explicit removal policy, and gates the exact final text. |
+| delivery checks | optionally checks placeholders, likely secrets, local links, and supplied citation ids offline. |
+| editing and rebuilding | prepares fingerprint-bound tasks, accepts a supplied response, preserves locked text or required claims, and verifies the candidate. |
+| review and approval | binds semantic judgments and signed approval capabilities to the exact candidate. |
+| local learning | records explicit instructions or verified repairs and applies profile revision and authority rules. |
+| evaluation | runs local backtests, synthetic comparisons, and evidence-bound benchmark workflows. |
+
+voice fit, generic-pattern findings, factual evidence, and approval stay separate. a passing check does not prove authorship, truth, or publication quality.
+
+## install
 
 ```bash
 npm install --global @holdyourvoice/hyv
 ```
 
-For a one-off command, replace `hyv` with `npx @holdyourvoice/hyv`.
-
-For Humanizer's complementary editor skill, install it separately with `npx skills add blader/humanizer`. It is not a HYV dependency: HYV's local AI Editor keeps its own versioned rules and final-output gate.
+for a one-off command, replace `hyv` with `npx @holdyourvoice/hyv`.
 
-## basic workflow
+## check and edit a draft
 
-1. Build a local profile from your samples.
+build a profile from at least two writing samples you have the right to use:
 
 ```bash
 hyv profile profile.json samples/one.md samples/two.md
+hyv analyze draft.md profile.json
 ```
 
-Add `--avoid=phrase` for wording that must block a draft. Repeat the option for more phrases.
+`analyze` returns separate voice dna, ai editor, and hygiene reports. hygiene is informational here; use `final-check` to gate delivery.
 
-2. Check a draft against that profile.
+create an editing brief, give it to your editor or a model you choose, then check the candidate:
 
 ```bash
-hyv analyze draft.md profile.json
+hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
+hyv verify draft.md candidate.md profile.json
+hyv final-check candidate.md
 ```
 
-The result contains separate VoiceDNA and AI Editor reports. The top-level `passed` value is true only when every required check passes.
+before verification, the editing brief asks for a word economy review: **every word must earn its place.** cut filler, repeated ideas, and needless setup when removing them loses no meaning, evidence, clarity, or voice. preserve necessary uncertainty, attribution, emphasis, and rhythm. this is an editor or model judgment, not an automatic score or a word-count target. edits must stay within the authorized scope.
+
+rewrite and verification commands are strict by default: every active ai editor finding must be repaired. a v3 profile can deliberately disable a rule. verification also checks preservation, logic, required facts when supplied, and final-output hygiene. it does not record learning.
 
-3. Create an editing brief, edit the draft, and verify the candidate.
+`final-check` writes accepted text to stdout. it removes a leading byte-order mark; unresolved hidden characters withhold output and return exit code `2`. run it after the last edit or formatting change. stdin works too:
 
 ```bash
-hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
-hyv verify draft.md candidate.md profile.json
+producer | hyv final-check -
 ```
 
-Send the brief to a human editor or a model you choose. Delivery stays under your control.
+## commands
 
-4. Check the exact text before delivery.
+most commands return json. exit code `0` means completion, `2` means a content or policy gate failed, and `1` means invalid input or a command error. run a command without enough arguments for its usage, or read the [full cli reference](docs/wiki/CLI-Reference.md).
+
+| command | purpose |
+| --- | --- |
+| `profile <output> <sample...>` | build a v2 profile; repeat `--avoid=phrase` for blocked phrases. |
+| `profile v3 <output> --id=writer.channel --channel=email <sample...>` | build a revisioned, digest-bound v3 profile. |
+| `profile assess <sample...>` | check sample readiness. |
+| `profile compose --ratio 70:30 <profile...>` | combine v3 measurements and conservative rule policies. |
+| `profile watch ...` | rebuild a local profile as its sample files change. |
+| `team-profile validate\|compose ...` | work with consent-bound team metadata. |
+| `ingest ...` | import owner-authorized gmail or telegram exports into redacted local samples. |
+| `analyze <draft> <profile>` | run the writing checks. |
+| `score <draft> <profile-v3> <heldout...>` | compare against a separate local writing range; abstain when evidence is inadequate. |
+| `strict-check <draft> <profile-v3> <sample...>` | return `strict-ready`, `needs-human-review`, or `blocked` using calibrated voice evidence. |
+| `dispositions <draft> <profile>` | normalize findings into `block`, `review`, and `signal`. |
+| `patterns` | print the active rule catalog. |
+| `batch-analyze <draft...>` | find repeated openings and endings. |
+| `fact-lint <draft\|-> --source=id:path` | check claims against supplied local sources. |
+| `logic-lint <draft\|-> [brief.json]` | check deterministic document logic. |
+| `hygiene <draft> [--fix]` | inspect hidden characters or write a conservative cleaned copy. |
+| `inspect-hidden-text <draft> [policy.json]` | inspect with an optional hidden-text policy. |
+| `apply-hidden-text-policy <draft> <policy.json> <output>` | apply explicitly permitted removals. |
+| `final-check <path\|->` | gate the exact output text. |
+| `delivery-check <path\|-> [policy.json]` | run the separate optional delivery check. |
+| `rewrite-prompt <draft> <profile>` | prepare a constrained editing brief. |
+| `prepare-rewrite ...` / `apply-rewrite ...` | prepare and verify sentence replacements or range edits. |
+| `prepare-judgment ...` / `reduce-judgment ...` | collect and reduce pre-edit or post-candidate judgments. |
+| `prepare-rebuild ...` / `rebuild-writer-request ...` / `apply-rebuild ...` | run a whole-document rebuild with required claims and signed authorization. |
+| `verify <original> <candidate> <profile>` | verify an edited candidate. |
+| `verify-spec ...` | also enforce a `CopySpec` claim contract. |
+| `lifecycle ...` | prepare semantic review, submit verdicts, inspect state, and finalize approval or rejection. |
+| `learning ...` | inspect, add, ratify, supersede, migrate, or clear local learning. |
+| `backtest ...` / `evaluate-local ...` | evaluate supplied candidates locally without generating writing. |
+| `agent list\|validate\|describe\|emit` | inspect or emit portable agent contracts. |
+| `mcp` | start the local server over standard input/output. |
+
+`strict-check` requires a v3 profile built from at least five samples, plus five non-duplicate validation samples with a consistent visible format and at least 1,500 words in total.
+
+whole-document rebuilding requires an upstream `REBUILD` recommendation, a `CopySpec`, and a signed `hyv.rebuild-authorization` capability. it checks required claims instead of enforcing the ordinary lexical preservation threshold. semantic review and final approval remain separate steps. see the [workflow and architecture](docs/ARCHITECTURE.md) and [recomposition contract](docs/RECOMPOSITION.md).
+
+## use with an agent
+
+start the mcp server with `hyv mcp`. compatible hosts can call the same local checks through tools. the `skills/hyv-*` packages describe inputs, outputs, evidence, permissions, and stop conditions for agent workflows.
 
 ```bash
-hyv final-check candidate.md
-producer | hyv final-check -
+hyv agent list
+hyv agent validate
 ```
 
-`final-check` writes accepted text to stdout. It withholds output and exits with code `2` when unresolved hidden Unicode remains.
+setup guides: [codex](docs/CODEX.md), [claude desktop](docs/CLAUDE-DESKTOP.md), [claude code](docs/CLAUDE-CODE.md), and [portable agents](docs/wiki/Portable-Agents.md).
 
-`delivery-check` is a separate opt-in offline check for placeholders, likely credential patterns, local Markdown links, and citation IDs in a local policy. It never fetches a URL or proves a fact.
+## local data
 
-## commands
+hyv has no runtime network requests, telemetry, hosted analysis, or profile sync. samples, drafts, profiles, candidates, and source files stay local unless you choose to send them elsewhere.
 
-| Command | Purpose |
-| --- | --- |
-| `hyv profile <profile.json> <sample...>` | Build a local profile from two or more samples. |
-| `hyv profile v3 <profile.json> --id=writer.channel --channel=email <sample...>` | Build a signed channel-specific Profile v3; optional tone is advisory metadata. |
-| `hyv profile compose --ratio 70:30 <profile...>` | Locally compose two or more Profile v3 metrics without creating writing. |
-| `hyv score <draft> <profile-v3.json> <heldout...>` | Measure the draft against a separate held-out local writing range; may abstain. |
-| `hyv ingest <source> <export> --owner=owner --output=/absolute/dir` | Create redacted, owner-authorized Gmail or Telegram samples and a text-free receipt. |
-| `hyv analyze <draft> <profile.json>` | Run VoiceDNA, AI Editor, and hygiene checks. |
-| `hyv strict-check <draft> <profile-v3.json> <sample...>` | Run the calibrated local strict-quality gate. It requires a V3 profile built from five or more samples, five non-duplicate validation samples with a consistent visible format and 1,500 words total, and returns `strict-ready`, `needs-human-review`, or `blocked`. |
-| `hyv hygiene <draft> [--fix]` | Inspect hidden Unicode or write a conservative cleaned copy. |
-| `hyv inspect-hidden-text <draft> [policy.json]` | Inspect hidden text with an optional policy. |
-| `hyv apply-hidden-text-policy <draft> <policy.json> <output>` | Apply approved hidden-text removals. |
-| `hyv final-check <path\|->` | Gate the exact text before delivery. |
-| `hyv delivery-check <path\|-> [policy.json]` | Run optional local delivery-integrity checks. |
-| `hyv profile assess <sample...>` | Inspect sample readiness before building a profile. |
-| `hyv team-profile validate\|compose ...` | Validate or locally compose consent-bound team profile metadata. |
-| `hyv dispositions <draft> <profile>` | Return normalized `block`, `review`, and `signal` findings. |
-| `hyv fact-lint <draft\|-> --source=id:path` | Check claims against local source files. |
-| `hyv logic-lint <draft\|-> [brief.json]` | Check deterministic document logic. |
-| `hyv batch-analyze <draft...>` | Find repeated openings and endings across drafts. |
-| `hyv rewrite-prompt <draft> <profile.json>` | Create a strict constrained editing brief. |
-| `hyv prepare-rewrite ...` | Create a fingerprint-bound edit task. |
-| `hyv apply-rewrite ...` | Apply and verify a response to an edit task. |
-| `hyv prepare-judgment ...` | Create a pre-edit or post-candidate judgment task. |
-| `hyv reduce-judgment <envelope...>` | Reduce judgments to SHIP, EDIT, REBUILD, CLEAR, or ESCALATE. |
-| `hyv prepare-rebuild ...` | Create an authorized whole-document rebuild task. |
-| `hyv rebuild-writer-request ...` | Create the writer-only part of a rebuild task. |
-| `hyv apply-rebuild ...` | Apply and verify an authorized rebuild response. |
-| `hyv verify <original> <candidate> <profile.json>` | Verify a candidate without changing learning state. |
-| `hyv verify-spec ...` | Verify a candidate and a CopySpec. |
-| `hyv lifecycle ...` | Run semantic review and final approval steps. |
-| `hyv learning ...` | Inspect or change local profile learning. |
-| `hyv patterns` | Print the active AI Editor rule catalog. |
-| `hyv agent list\|validate\|describe\|emit` | Inspect or emit portable agent contracts. |
-| `hyv mcp` | Start the local MCP server on standard input/output. |
-
-`rewrite-prompt`, `prepare-rewrite`, `apply-rewrite`, and `verify` are strict by default: every active AI Editor finding must be repaired, and verification rejects a candidate that leaves one unresolved. A Profile v3 `disabled` policy is the only deliberate exception. `strict-check` adds the separate calibrated voice-evidence decision.
-
-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.
-
-Run `hyv <command>` without enough arguments to see its exact usage. Read the [CLI reference](docs/wiki/CLI-Reference.md) for every option.
-
-## portable agents and MCP
-
-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.
-
-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).
-
-## privacy and safety
-
-Drafts, samples, profiles, candidates, and source files stay on your machine. The package has no accounts, telemetry, hosted analysis, or runtime network requests.
-
-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.
-
-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.
-
-## performance
-
-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).
-
-## development
+learning lives under `~/.hyv/learning/` by default. verified-repair events store findings and hashes rather than draft text. explicit learning instructions store the instruction itself. approval trust is loaded separately from a permission-checked local context. private samples and approval keys do not belong in a public repository.
+
+## version 4 and development
+
+version 4 rebuilds the implementation boundaries while retaining the existing cli commands, mcp contracts, profile formats, deep-import paths, rules, and agent packages. existing profiles need no migration. verification artifacts include the package version: prepare fresh version-bound tasks and approvals after upgrading.
+
+start with [architecture](docs/ARCHITECTURE.md) to find the owner of a behavior. the compatibility check compares the rebuilt implementation with the frozen v3 source, including serialized outputs and errors.
 
 ```bash
 npm ci
 npm test
 npm run check:release
+npm run pack:claude
 ```
 
-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).
-
-See the [roadmap](docs/ROADMAP.md), [rule authoring guide](docs/RULE-AUTHORING.md), and synthetic [benchmark scorecard command](scripts/public-scorecard.mjs). The public fixture scorecard does not measure human preference or model quality.
+read [contributing](CONTRIBUTING.md), [rule authoring](docs/RULE-AUTHORING.md), the [roadmap](docs/ROADMAP.md), and the [wiki](https://github.com/shashank-sn/holdyourvoice/wiki). existing [runtime measurements](benchmarks/runtime/README.md) describe their recorded fixtures and revisions; they are not a new version 4 performance claim. public synthetic scorecards do not measure human preference.
 
 ## license
 
-[MIT](LICENSE). Third-party writing and data keep their own rights.
+[mit](LICENSE). third-party writing and data keep their own rights.

package/dist/ai-editor-rules.js

@@ -106,6 +106,7 @@ export const rules = [
     { id: "struct.rhetorical-truth", severity: "yellow", expression: /\b(?:the\s+)?(?:uncomfortable|hard|harsh|brutal|ugly|unsexy|real|honest)\s+(?:truth|reality)\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "state the fact directly, skip the framing" },
     { id: "struct.truth-is", severity: "yellow", expression: /\bthe\s+truth\s+is\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "just say the truth. the framing is filler." },
     { id: "struct.lesson-setup", severity: "yellow", expression: /\b(?:here'?s\s+)?what\s+.{3,80}\s+(?:taught|teaches)\s+(?:me|us|you|everyone)\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "just share the lesson" },
+    { id: "struct.colon-reveal", severity: "yellow", expression: /^\s*(?!#{1,6}\s)(?:(?:The|the)\s+(?:best\s+part|detail\s+that\s+makes\s+(?:it|this)\s+work|real\s+reason|kicker|twist|secret)|(?:Kicker|kicker|Twist|twist|Secret|secret))\s*:\s*(?=\p{Ll})/u, reason: "A reveal label can manufacture drama before an ordinary point.", suggestion: "State the fact without presenting it as a reveal.", scope: "line" },
     { id: "struct.negation-cascade", severity: "yellow", expression: /\b(?:no|not)\s+\w[^.!?\n]{0,80}[.!?][ \t]*\n?[ \t]*(?:no|not)\s+\w[^.!?\n]{0,80}[.!?][ \t]*\n?[ \t]*(?:no|not)\s+\w/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "three negations in a row reads like AI performance", scope: "line" },
     { id: "struct.inline-triplet", severity: "yellow", expression: /\bit'?s\s+\w[^,.!?;\n]{0,30},\s*it'?s\s+\w[^,.!?;\n]{0,30}[,.]?\s*(?:and\s+)?it'?s\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: `the "it's X, it's Y, it's Z" pattern is an AI tell` },
     { id: "struct.moment-becomes", severity: "red", expression: /\b(?:the\s+)?moment\b.{3,80}\bbecomes?\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: '"the moment X becomes Y" is polished founder cadence \u2014 restructure' },

package/dist/ai-editor.js

@@ -1,7 +1,7 @@
 import { rules } from './ai-editor-rules.js';
 import { sentences } from './text.js';
 export { rules } from './ai-editor-rules.js';
-export const RULESET_VERSION = '3.5.0-local.3';
+export const RULESET_VERSION = '3.5.0-local.4';
 const sentenceRules = rules.filter((rule) => rule.scope === undefined || rule.scope === 'sentence');
 const lineRules = rules.filter((rule) => rule.scope === 'line');
 const documentRules = rules.filter((rule) => rule.scope === 'document');
@@ -104,23 +104,25 @@ export function serializedRules() {
         scope: rule.scope ?? 'sentence',
     }));
 }
-function documentFinding(rule, sentence) {
+function ruleFinding(rule, sentence) {
     return { engine: 'ai_editor', id: rule.id, severity: rule.severity, sentence: sentence.index, excerpt: sentence.text, reason: rule.reason, suggestion: rule.suggestion };
 }
 function documentMatches(rule, prose, mapped) {
-    const at = (index) => mapped[index] ? [documentFinding(rule, mapped[index])] : [];
+    const at = (index) => mapped[index] ? [ruleFinding(rule, mapped[index])] : [];
     if (rule.id === 'ai.repeated-sentence-opening') {
-        for (let index = 0; index + 2 < mapped.length; index += 1) {
-            const opening = mapped[index].text.match(/^\s*(\p{L}+)/u)?.[1]?.toLocaleLowerCase();
-            if (opening && [1, 2].every((offset) => mapped[index + offset].text.match(/^\s*(\p{L}+)/u)?.[1]?.toLocaleLowerCase() === opening))
+        const openings = mapped.map((sentence) => sentence.text.match(/^\s*(\p{L}+)/u)?.[1]?.toLocaleLowerCase());
+        for (let index = 0; index + 2 < openings.length; index += 1) {
+            const opening = openings[index];
+            if (opening && openings[index + 1] === opening && openings[index + 2] === opening)
                 return at(index);
         }
         return [];
     }
     if (rule.id === 'format.bold-density') {
-        const line = prose.split('\n').findIndex((value) => (value.match(/\*\*[^*\n]+\*\*/gu) ?? []).length >= 2);
+        const lines = prose.split('\n');
+        const line = lines.findIndex((value) => (value.match(/\*\*[^*\n]+\*\*/gu) ?? []).length >= 2);
         if (line >= 0)
-            return at(mapped.findIndex((sentence) => sentence.start >= prose.split('\n').slice(0, line).join('\n').length));
+            return at(mapped.findIndex((sentence) => sentence.start >= lines.slice(0, line).join('\n').length));
         const total = (prose.match(/\*\*[^*\n]+\*\*/gu) ?? []).length;
         return total >= 4 ? at(0) : [];
     }
@@ -133,9 +135,11 @@ function documentMatches(rule, prose, mapped) {
         return [];
     }
     if (rule.id === 'ai.clipped-fragment-run') {
-        for (let index = 0; index + 2 < mapped.length; index += 1)
-            if ([0, 1, 2].every((offset) => (mapped[index + offset].text.match(/\p{L}+/gu) ?? []).length <= 4))
+        const fragments = mapped.map((sentence) => (sentence.text.match(/\p{L}+/gu) ?? []).length <= 4);
+        for (let index = 0; index + 2 < fragments.length; index += 1) {
+            if (fragments[index] && fragments[index + 1] && fragments[index + 2])
                 return at(index);
+        }
         return [];
     }
     if (rule.id === 'ai.jargon-stack') {
@@ -144,12 +148,14 @@ function documentMatches(rule, prose, mapped) {
         return index >= 0 ? at(index) : [];
     }
     if (rule.id === 'ai.sentence-length-cluster') {
-        for (let index = 0; index + 3 < mapped.length; index += 1)
-            if ([0, 1, 2, 3].every((offset) => {
-                const count = (mapped[index + offset].text.match(/\p{L}+/gu) ?? []).length;
-                return count >= 15 && count <= 20;
-            }))
+        const clustered = mapped.map((sentence) => {
+            const count = (sentence.text.match(/\p{L}+/gu) ?? []).length;
+            return count >= 15 && count <= 20;
+        });
+        for (let index = 0; index + 3 < clustered.length; index += 1) {
+            if (clustered[index] && clustered[index + 1] && clustered[index + 2] && clustered[index + 3])
                 return at(index);
+        }
         return [];
     }
     return [];
@@ -161,15 +167,7 @@ export function analyzeAiEditor(text, profile) {
     for (const sentence of mapped) {
         for (const rule of sentenceRules) {
             if (rule.expression.test(prose.slice(sentence.start, sentence.end))) {
-                matched.push({
-                    engine: 'ai_editor',
-                    id: rule.id,
-                    severity: rule.severity,
-                    sentence: sentence.index,
-                    excerpt: sentence.text,
-                    reason: rule.reason,
-                    suggestion: rule.suggestion,
-                });
+                matched.push(ruleFinding(rule, sentence));
             }
         }
     }
@@ -184,15 +182,7 @@ export function analyzeAiEditor(text, profile) {
                 ?? mapped.find((candidate) => candidate.start >= lineStart && candidate.start < lineStart + line.length);
             if (!sentence)
                 continue;
-            matched.push({
-                engine: 'ai_editor',
-                id: rule.id,
-                severity: rule.severity,
-                sentence: sentence.index,
-                excerpt: sentence.text,
-                reason: rule.reason,
-                suggestion: rule.suggestion,
-            });
+            matched.push(ruleFinding(rule, sentence));
         }
         lineStart += line.length + 1;
     }

package/dist/analysis.js

@@ -0,0 +1,33 @@
+import { analyzeAiEditor } from './ai-editor.js';
+import { analyzeEditorial } from './editorial-packs.js';
+import { inspectHygiene } from './hygiene.js';
+import { analyzeVoiceDna } from './voice-dna.js';
+export function analyze(text, profile, brief) {
+    const voiceDna = analyzeVoiceDna(text, profile);
+    const aiEditor = analyzeAiEditor(text, profile);
+    const editorial = brief ? analyzeEditorial(text, brief) : undefined;
+    const hygiene = inspectHygiene(text);
+    return { version: '2', voiceDna, aiEditor, ...(editorial ? { editorial } : {}), hygiene, passed: voiceDna.passed && aiEditor.passed && (editorial?.passed ?? true) };
+}
+export function isBlockingFinding(finding) {
+    return finding.engine === 'ai_editor' ? finding.appliedPolicy === 'blocking' : finding.severity === 'red';
+}
+export function isStrictFinding(finding) {
+    return finding.engine === 'ai_editor' || isBlockingFinding(finding);
+}
+export function analysisFindings(result) {
+    return [...result.voiceDna.findings, ...result.aiEditor.findings, ...(result.editorial?.findings ?? [])];
+}
+export function strictFindings(result) {
+    return analysisFindings(result).filter(isStrictFinding);
+}
+export function deriveEditScope(result, strict = false) {
+    const findings = analysisFindings(result);
+    const blocking = findings.filter(strict ? isStrictFinding : isBlockingFinding);
+    const pendingJudgment = strict ? [] : findings.filter((finding) => finding.appliedPolicy === 'judgment-required');
+    return {
+        eligibleSentenceIds: [...new Set(blocking.map((finding) => finding.sentence))].sort((left, right) => left - right),
+        blocking,
+        pendingJudgment,
+    };
+}

package/dist/cli/agents.js

@@ -0,0 +1,88 @@
+import { writeFileSync } from 'node:fs';
+import { loadAll, validateAll, validateId, sortedIds, describe, emitJson, emitPrompt } from '../agents/index.js';
+import { json } from './io.js';
+function agentFlags(args) {
+    const values = [];
+    let host = 'generic';
+    let mode;
+    let output;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        const separator = argument.indexOf('=');
+        const name = separator < 0 ? argument : argument.slice(0, separator);
+        if (name !== '--host' && name !== '--mode' && name !== '--output') {
+            values.push(argument);
+            continue;
+        }
+        const inline = separator >= 0;
+        const value = inline ? argument.slice(separator + 1) : args[++index];
+        if (name === '--mode') {
+            if (value !== 'prompt' && value !== 'json')
+                throw new Error('Usage: hyv agent --mode prompt|json requires a mode.');
+            mode = value;
+        }
+        else {
+            if (!value || (!inline && value.startsWith('--'))) {
+                throw new Error(name === '--host' ? 'Usage: hyv agent --host HOST requires a value.' : 'Usage: hyv agent --output FILE requires a value.');
+            }
+            if (name === '--host')
+                host = value;
+            else
+                output = value;
+        }
+    }
+    return { values, host, mode, output };
+}
+export function runAgent(args) {
+    const [subcommand, ...subargs] = args;
+    if (subcommand === 'list') {
+        if (subargs.length)
+            throw new Error('Usage: hyv agent list');
+        const packages = loadAll();
+        const ids = sortedIds(packages);
+        json(ids.map((id) => {
+            const descriptor = packages.get(id).descriptor;
+            return { id, role: descriptor.role, workflow_phase: descriptor.workflow_phase, description: descriptor.description };
+        }));
+        return 0;
+    }
+    if (subcommand === 'validate') {
+        if (subargs.length > 1)
+            throw new Error('Usage: hyv agent validate [id]');
+        const packages = loadAll();
+        const id = subargs[0];
+        if (id !== undefined)
+            validateId(packages, id);
+        validateAll(packages);
+        json({ schema_version: '1.0.0', status: 'PASS', agent: id ?? 'all' });
+        return 0;
+    }
+    if (subcommand === 'describe') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1 || mode !== undefined || output !== undefined)
+            throw new Error('Usage: hyv agent describe <id> [--host HOST]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        json(describe(packages.get(values[0]), host));
+        return 0;
+    }
+    if (subcommand === 'emit') {
+        const { values, host, mode, output } = agentFlags(subargs);
+        if (values.length !== 1)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        if (!mode)
+            throw new Error('Usage: hyv agent emit <id> --mode prompt|json [--host HOST] [--output FILE]');
+        const packages = loadAll();
+        validateId(packages, values[0]);
+        const pkg = packages.get(values[0]);
+        const body = mode === 'prompt' ? emitPrompt(pkg, host) : `${emitJson(pkg, host)}\n`;
+        if (output !== undefined) {
+            writeFileSync(output, body, { encoding: 'utf8', flag: 'wx' });
+        }
+        else {
+            process.stdout.write(body);
+        }
+        return 0;
+    }
+    throw new Error('Usage: hyv agent <list|validate|describe|emit> ...');
+}