@holdyourvoice/hyv 3.2.0 → 3.3.0

package/Readme.md

@@ -14,7 +14,7 @@ Those programs keep separate findings, scores, and pass states. A strong result
 
 Everything in the CLI runs from local files: accounts, API calls, telemetry, payment collection, and runtime network requests stay out of the core path. The optional Claude extension adds a local stdio MCP adapter around that same engine; it is not a hosted service.
 
-> **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.
+> **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. Version 3.3.0 adds pre-edit judgments, range edits, and authorized rebuild. Writer-study kits remain blocked optional research. Product publish uses the version bump and CI.
 
 ## Why it exists
 
@@ -55,7 +55,7 @@ To contribute, clone this repository, run `npm install`, then run `npm test` and
 
 ### Use it in Claude Desktop
 
-Build the fully local Claude Desktop extension with `npm run pack:claude`, then install `dist/hold-your-voice.mcpb` from **Settings → Extensions → Advanced settings → Install Extension**. The extension accepts text and portable profile JSON in the current conversation only. 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 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. Verification is read-only. Learning requires an explicit learning command or an approved lifecycle transition; neither path retains writing text or makes network requests. See the [Claude Desktop guide](docs/CLAUDE-DESKTOP.md).
 
 ### Build a local VoiceDNA profile
 
@@ -167,7 +167,7 @@ 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. 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.
+`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 does not mutate 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
 
@@ -199,7 +199,7 @@ The check is deterministic. Without `atoms`, an immutable claim remains a verbat
 
 ### 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.
+Learning changes are explicit. Use the learning commands below, or complete the separately authorized semantic-review and final-approval lifecycle before recording approved learning. State lives under `~/.hyv/learning/`, scoped to the portable profile, and stores no draft or candidate text. The next `rewrite-prompt` uses a bounded list of approved repairs.
 
 ```bash
 hyv learning show profile.json
@@ -268,7 +268,7 @@ Read the full [VoiceDNA reference](docs/VOICE-DNA.md) and [Wiki guide](https://g
 
 ## AI Editor: inspectable rules
 
-AI Editor uses a local, deterministic ruleset. The current `2.9.24-static.2` ruleset restores the reviewed 143-rule static catalog from the published `@holdyourvoice/hyv@2.9.24` `signals.ts` artifact and retains two detectors introduced in 3.1, for 145 rules total. Most rules inspect sentences; selected inherited rules inspect one physical line to preserve multi-sentence and line-start behavior. Each rule has a stable ID, severity, reason, repair direction, reconstructable expression, and explicit scope. Intentional inherited overlaps remain visible as separate findings.
+AI Editor uses a local, deterministic ruleset. The current `3.2.0-reconciled.1` ruleset contains 148 stable catalog entries: the inherited catalog plus en-dash and performative-sincerity coverage. Applied profile policy determines whether a match blocks, advises, requires judgment, or is disabled. Duplicate legacy expressions remain cataloged for ID compatibility but emit one canonical finding. Most rules inspect sentences; selected inherited rules inspect one physical line to preserve multi-sentence and line-start behavior.
 
 Run this command to see the rules and ruleset version that actually execute in the published CLI:
 
@@ -302,13 +302,20 @@ The preservation score is a guardrail based on retained original words longer th
 | `hyv hygiene <draft> [--fix] [--output=path]` | Draft | Hygiene report or cleaned copy plus receipt | You need to inspect or conservatively clean hidden Unicode. |
 | `hyv final-check <path\|->` | Any final text | Exact accepted text on stdout or a withheld-output report on stderr | Text is about to cross a user-facing boundary. |
 | `hyv rewrite-prompt <draft> <profile.json>` | Draft and profile | Markdown editing brief | You need a constrained request for an editor or model. |
+| `hyv prepare-rewrite <draft> <profile.json> <task.json>` | Draft and profile | Versioned task file plus metadata | A host needs a fingerprint-bound sentence-edit task. |
+| `hyv apply-rewrite <task.json> <response.json> <profile.json>` | Task, response, and profile | Candidate evaluation JSON | A host needs to apply and recheck eligible sentence replacements. |
 | `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 learning <show\|inspect\|add\|record\|ratify\|supersede\|migrate\|clear> ...` | Profile, operation value, and bounded metadata options | Preferences or a text-free mutation receipt | You need to inspect, migrate, or manage profile-scoped learning. |
+| `hyv lifecycle <prepare-semantic\|submit-verdict\|inspect\|validate-final-approval\|finalize> ...` | Versioned lifecycle artifacts | Canonical lifecycle artifact or metadata | A normal-policy semantic review or human decision must advance through the shared reducer. |
 | `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.
 
+Profile v3 learning is keyed by its stable local profile ID, so compatible history survives profile revisions. `record`, `ratify`, and `supersede` accept bounded `--mutation-id`, `--authority`, `--provenance`, `--weight`, and `--compatibility` options. `ratify` and `supersede` require Profile v3. `migrate` explicitly copies compatible legacy Profile v2 learning into one Profile v3 identity. Replaying an identical mutation is idempotent; reusing its ID for a different operation returns a conflict. Inspection and receipts expose event metadata only, never stored instructions or draft text.
+
+The standalone CLI supports normal-policy semantic review. High-assurance review requires a trusted embedding and is rejected by the CLI. Approval capabilities are accepted only through `--capability-stdin` or a permission-checked `--capability-file`; adapters validate capabilities but never mint them. Rejection needs no capability. Approval and `learning record-approved` require the matching signed final-approval capability. `apply-rewrite`, `lifecycle submit-verdict`, and `lifecycle finalize` exit `2` when the candidate or transition is not accepted, while usage and runtime failures exit `1`.
+
 ## Project map
 
 | Path | Responsibility |
@@ -320,17 +327,23 @@ Every file argument can be `-` when the command accepts text input from standard
 | `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/pipeline.ts` | Combines scored pass states, makes briefs, and verifies candidates. |
+| `src/rewrite-task.ts` | Prepares and evaluates fingerprint-bound sentence-replacement tasks. |
+| `src/semantic-review.ts` | Defines and reduces semantic and human-review lifecycle artifacts. |
+| `src/approval-capability.ts` | Verifies canonical signed approval capabilities. |
+| `src/approval-context.ts` | Loads permission-checked trust roots and evaluator authorization. |
+| `src/lifecycle-adapter.ts` | Shares lifecycle operations across CLI and MCP adapters. |
 | `src/cli.ts` | Local file and standard-input command adapter. |
+| `src/mcp.ts` | Local stdio MCP registration and host-capability gating. |
 | `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.
+`pipeline.ts` is the sole scored output-composition point. It combines pass states and preserves each engine’s separate score. Rewrite-task and lifecycle modules compose their own versioned, non-scoring artifacts.
 
 ## Privacy and data rights
 
-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.
+The runtime uses files on your machine. Samples, drafts, profiles, candidates, and client data stay there. Verification is read-only. Explicit learning commands and approved lifecycle recording can write text-free local events 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.
 
 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.
 
@@ -365,7 +378,7 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Keep chan
 
 ## 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.
+`@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. Writer-study kits stay optional research. Product publish uses the version bump and CI. Keep writer-checkpoint claims off the publish.
 
 ## Support
 

package/dist/ai-editor-rules.js

@@ -114,9 +114,10 @@ export const rules = [
     { id: "struct.heres-where", severity: "yellow", expression: /\b(?:here'?s|here\s+is)\s+(?:where|why|what|the\s+part|the\s+(?:harder|real|actual|main|bigger)\s+problem)\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "just make the point without the signpost" },
     { id: "struct.generic-buyer", severity: "red", expression: /\bpeople\s+don'?t\s+just\s+buy\b|\bpeople\s+buy\s+the\s+feeling\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "generic buyer psychology is AI filler" },
     { id: "struct.this-isnt-x-this-is-y", severity: "red", expression: /\bthis isn'?t .{2,40}\.?\s*(?:this is|it'?s) .{2,40}/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "FATAL: delete the negation, just state the positive claim", scope: "line" },
-    { id: "struct.not-x-y", severity: "red", expression: /\bnot .{2,30}\.?\s*.{2,30}\b/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: 'the "Not X. Y." pattern is an AI tell \u2014 just state Y', scope: "line" },
+    { id: "struct.not-x-y", severity: "red", expression: /^\s*not\s+[^.!?\n]{1,60}\.\s+[^.!?\n]{1,60}(?:[.!?]|$)/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: 'the "Not X. Y." pattern is an AI tell \u2014 just state Y', scope: "line" },
     { id: "struct.forget-x", severity: "red", expression: /\bforget .{2,40}\.?\s*(?:this is|it'?s|you need)/i, reason: "A formulaic structure can make the sentence feel manufactured.", suggestion: "don't negate \u2014 just state what you mean", scope: "line" },
-    { id: "punct.em-dash", severity: "yellow", expression: /—/, reason: "A stock phrase can flatten the writer's meaning.", suggestion: "em dashes are an AI tell \u2014 use a period, comma, or parentheses" },
+    { id: "punct.em-dash", severity: "red", expression: /—/, reason: "A stock phrase can flatten the writer's meaning.", suggestion: "em dashes are an AI tell \u2014 use a period, comma, or parentheses" },
+    { id: "punct.en-dash", severity: "red", expression: /–/, reason: "A stock phrase can flatten the writer's meaning.", suggestion: "en dashes are an AI tell \u2014 use a plain hyphen, period, comma, or parentheses" },
     { id: "bait.let-that-sink", severity: "red", expression: /\blet that sink in\b/i, reason: "The phrase asks for attention instead of earning it.", suggestion: "cut the sink. make your point and move on." },
     { id: "bait.read-that-again", severity: "red", expression: /\bread that again\b/i, reason: "The phrase asks for attention instead of earning it.", suggestion: "if it needs repeating, repeat it yourself" },
     { id: "bait.full-stop", severity: "red", expression: /\bfull stop\b/i, reason: "The phrase asks for attention instead of earning it.", suggestion: "the period already does this job" },
@@ -143,6 +144,8 @@ export const rules = [
     { id: "ogilvy.deep-dive", severity: "yellow", expression: /\bdeep dive\b/i, reason: "A stock phrase can flatten the writer's meaning.", suggestion: 'Ogilvy: say "look closely at" or "examine"' },
     { id: "ogilvy.preamble-i-want-to", severity: "yellow", expression: /^\s*i want to (?:share|talk about|discuss|mention)\b/i, reason: "A hedge or preamble weakens the direct claim.", suggestion: "Ogilvy: just say it. skip the preamble.", scope: "line" },
     { id: "ogilvy.preamble-just-wanted", severity: "yellow", expression: /^\s*(?:i just wanted|i wanted to)\b/i, reason: "A hedge or preamble weakens the direct claim.", suggestion: "Ogilvy: just say it.", scope: "line" },
+    { id: "formula.performative-sincerity", severity: "red", expression: /\b(?:to be honest|in all honesty)\b/i, reason: "The phrase announces sincerity instead of making the claim directly.", suggestion: "cut the sincerity preamble and state the claim" },
+    { id: "hedge.performative-sincerity-adverb", severity: "yellow", expression: /\b(?:honestly|genuinely|truly|frankly|actually)\b/i, reason: "The adverb performs sincerity instead of adding evidence.", suggestion: "cut the adverb or replace it with the evidence" },
     { id: "ai.question-hook", severity: "yellow", expression: /^(?:have you|do you|what if|why do|how do)\b/i, reason: "A question opener delays the concrete observation.", suggestion: "Open from an observation." },
     { id: "ai.abstract-cluster", severity: "yellow", expression: /\b(?:alignment|authenticity|clarity|strategy|value)\b.*\b(?:alignment|authenticity|clarity|strategy|value)\b/i, reason: "Abstract nouns pile up without a mechanism.", suggestion: "Use concrete nouns and actions." },
 ];

package/dist/ai-editor.js

@@ -1,10 +1,42 @@
 import { rules } from './ai-editor-rules.js';
 import { sentences } from './text.js';
 export { rules } from './ai-editor-rules.js';
-export const RULESET_VERSION = '2.9.24-static.2';
+export const RULESET_VERSION = '3.2.0-reconciled.1';
 const sentenceRules = rules.filter((rule) => rule.scope !== 'line');
 const lineRules = rules.filter((rule) => rule.scope === 'line');
 const ruleOrder = new Map(rules.map((rule, index) => [rule.id, index]));
+const ruleIds = new Set(rules.map((rule) => rule.id));
+const policyStates = new Set(['blocking', 'advisory', 'judgment-required', 'disabled']);
+const suppressedDuplicateIds = new Set(['hedge.worth-noting', 'struct.in-other-words']);
+const reconciledPolicies = {
+    'struct.not-x-y': 'advisory',
+    'struct.this-isnt-x-this-is-y': 'advisory',
+    'struct.same-better': 'disabled',
+    'struct.moment-becomes': 'disabled',
+    'hedge.i-think': 'disabled',
+    'ai.question-hook': 'advisory',
+};
+function defaultPolicy(id, severity) {
+    const reconciled = reconciledPolicies[id];
+    if (reconciled)
+        return reconciled;
+    if (severity === 'red' && (id.startsWith('ai.') || id.startsWith('ogilvy.')))
+        return 'judgment-required';
+    return severity === 'red' ? 'blocking' : 'advisory';
+}
+function policiesFor(profile) {
+    if (profile?.version === '3') {
+        for (const [id, state] of Object.entries(profile.rulePolicy)) {
+            if (!ruleIds.has(id))
+                throw new Error(`Profile rulePolicy contains unknown rule ID: ${id}`);
+            if (!policyStates.has(state))
+                throw new Error(`Profile rulePolicy contains invalid state for rule ID: ${id}`);
+        }
+    }
+    return new Map(rules.map((rule) => [rule.id, profile?.version === '3' && profile.rulePolicy[rule.id]
+            ? profile.rulePolicy[rule.id]
+            : defaultPolicy(rule.id, rule.severity)]));
+}
 export function serializedRules() {
     return rules.map((rule) => ({
         id: rule.id,
@@ -15,13 +47,13 @@ export function serializedRules() {
         scope: rule.scope ?? 'sentence',
     }));
 }
-export function analyzeAiEditor(text) {
-    const findings = [];
+export function analyzeAiEditor(text, profile) {
+    const matched = [];
     const mapped = sentences(text);
     for (const sentence of mapped) {
         for (const rule of sentenceRules) {
             if (rule.expression.test(sentence.text)) {
-                findings.push({
+                matched.push({
                     engine: 'ai_editor',
                     id: rule.id,
                     severity: rule.severity,
@@ -43,7 +75,7 @@ export function analyzeAiEditor(text) {
             const sentence = mapped.find((candidate) => candidate.start <= matchStart && matchStart < candidate.end);
             if (!sentence)
                 continue;
-            findings.push({
+            matched.push({
                 engine: 'ai_editor',
                 id: rule.id,
                 severity: rule.severity,
@@ -55,8 +87,19 @@ export function analyzeAiEditor(text) {
         }
         lineStart += line.length + 1;
     }
-    findings.sort((left, right) => left.sentence - right.sentence || (ruleOrder.get(left.id) ?? 0) - (ruleOrder.get(right.id) ?? 0));
-    const reds = findings.reduce((count, finding) => count + Number(finding.severity === 'red'), 0);
-    const score = Math.max(0, 100 - reds * 18 - (findings.length - reds) * 6);
-    return { engine: 'ai_editor', version: RULESET_VERSION, score, passed: reds === 0, findings };
+    matched.sort((left, right) => left.sentence - right.sentence || (ruleOrder.get(left.id) ?? 0) - (ruleOrder.get(right.id) ?? 0));
+    const policies = policiesFor(profile);
+    const findings = matched.flatMap((finding) => {
+        if (suppressedDuplicateIds.has(finding.id))
+            return [];
+        if (finding.id === 'ai.question-hook' && finding.sentence !== 1)
+            return [];
+        const appliedPolicy = policies.get(finding.id);
+        if (!appliedPolicy || appliedPolicy === 'disabled')
+            return [];
+        return [{ ...finding, appliedPolicy, severity: appliedPolicy === 'blocking' ? 'red' : 'yellow' }];
+    });
+    const blocking = findings.reduce((count, finding) => count + Number(finding.appliedPolicy === 'blocking'), 0);
+    const score = Math.max(0, 100 - blocking * 18 - (findings.length - blocking) * 6);
+    return { engine: 'ai_editor', version: RULESET_VERSION, score, passed: blocking === 0, findings };
 }

package/dist/ai-editor.test.js

@@ -1,8 +1,12 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { analyzeAiEditor, rules, serializedRules } from './ai-editor.js';
+import { analyzeAiEditor, RULESET_VERSION, rules, serializedRules } from './ai-editor.js';
+import { createHash } from 'node:crypto';
 test('publishes executable rules with stable IDs and repair directions', () => {
-    assert.equal(rules.length, 145);
+    assert.equal(RULESET_VERSION, '3.2.0-reconciled.1');
+    assert.equal(rules.length, 148);
+    assert.equal(createHash('sha256').update(JSON.stringify(rules.map((rule) => rule.id))).digest('hex'), '8d3cdde1922686076cb3baa79c55db95f37c9088d246f47c24405417fe58f979');
+    assert.equal(createHash('sha256').update(JSON.stringify(serializedRules())).digest('hex'), 'a758d7cd8e53e42d1a3ada81aff3e61f2994555d286f8915a9fc52767f145094');
     assert.equal(new Set(rules.map((rule) => rule.id)).size, rules.length);
     for (const rule of rules) {
         assert.match(rule.id, /^(ai|formula|hedge|struct|punct|bait|cringe|insider|ogilvy)\./);
@@ -12,6 +16,57 @@ test('publishes executable rules with stable IDs and repair directions', () => {
         assert.equal(rule.expression.sticky, false, rule.id);
     }
 });
+function profileWithPolicies(rulePolicy) {
+    return {
+        version: '3', id: 'founder.test', revision: 1, revisionDigest: '0'.repeat(64), sampleCount: 2,
+        metrics: { sentenceLength: 5, sentenceVariation: 1, sentenceStructure: [], rhythm: 1, paragraphLength: 1, openingMoves: [], vocabulary: [], lexicalDensity: 0.5, pointOfView: 'mixed', punctuation: {}, caseStyle: 'mixed', questionRate: 0, transitions: [] },
+        avoid: [], provenance: { source: 'test', rights: 'test', createdAt: '2026-08-13T00:00:00.000Z' }, rulePolicy,
+        fingerprint: { contractionRate: 0, sentenceLengthDistribution: { short: 1, medium: 0, long: 0 }, bulletRate: 0, enDashRate: 0 },
+        tolerances: { contractionRate: { absolute: 0, calibrated: false }, sentenceLengthDistribution: { absolute: 0, calibrated: false }, bulletRate: { absolute: 0, calibrated: false }, enDashRate: { absolute: 0, calibrated: false } },
+        metricFixtures: { contractionRate: ['test'], sentenceLengthDistribution: ['test'], bulletRate: ['test'], enDashRate: ['test'] },
+    };
+}
+test('applies all four v3 policy states after matching and preserves catalog order', () => {
+    const report = analyzeAiEditor('Firstly, perhaps we leverage a holistic plan.', profileWithPolicies({
+        'formula.firstly': 'blocking',
+        'hedge.perhaps': 'advisory',
+        'ai.leverage': 'judgment-required',
+        'ai.holistic': 'disabled',
+    }));
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.appliedPolicy, finding.severity]), [
+        ['ai.leverage', 'judgment-required', 'yellow'],
+        ['formula.firstly', 'blocking', 'red'],
+        ['hedge.perhaps', 'advisory', 'yellow'],
+    ]);
+    assert.equal(report.passed, false);
+});
+test('fails closed when a v3 policy names a rule outside the catalog', () => {
+    assert.throws(() => analyzeAiEditor('Plain text.', profileWithPolicies({ 'ai.missing': 'blocking' })), /unknown rule ID/);
+});
+test('uses reconciled defaults for v2 profiles and suppresses inherited duplicate emissions', () => {
+    const report = analyzeAiEditor("It's worth noting: in other words, I think the same plan. Better results.");
+    assert.equal(report.findings.some((finding) => finding.id === 'hedge.worth-noting'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'struct.in-other-words'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'hedge.i-think'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'struct.same-better'), false);
+    assert.ok(report.findings.every((finding) => finding.appliedPolicy !== undefined));
+});
+test('treats bare red vocabulary as pending judgment and clear sincerity or dashes as blocking', () => {
+    const vocabulary = analyzeAiEditor('We leverage the existing scheduler.');
+    assert.deepEqual(vocabulary.findings.find((finding) => finding.id === 'ai.leverage')?.appliedPolicy, 'judgment-required');
+    assert.equal(vocabulary.passed, true);
+    const blocked = analyzeAiEditor('To be honest, the scheduler failed — twice.');
+    assert.ok(blocked.findings.some((finding) => finding.id === 'formula.performative-sincerity' && finding.appliedPolicy === 'blocking'));
+    assert.ok(blocked.findings.some((finding) => finding.id === 'punct.em-dash' && finding.appliedPolicy === 'blocking'));
+    assert.equal(blocked.passed, false);
+    const advisory = analyzeAiEditor('Honestly, the scheduler failed twice.');
+    assert.ok(advisory.findings.some((finding) => finding.id === 'hedge.performative-sincerity-adverb' && finding.appliedPolicy === 'advisory'));
+    assert.equal(advisory.passed, true);
+});
+test('only applies the question-hook policy to document sentence one', () => {
+    assert.ok(analyzeAiEditor('Have you checked the invoice? It is overdue.').findings.some((finding) => finding.id === 'ai.question-hook'));
+    assert.equal(analyzeAiEditor('The invoice is overdue. Have you checked it?').findings.some((finding) => finding.id === 'ai.question-hook'), false);
+});
 test('detects representative rules from every inherited rule family', () => {
     const examples = [
         ['ai.delve', 'we will delve into it.'],
@@ -87,10 +142,7 @@ test('executes inherited cross-sentence rules and maps them to the first sentenc
     const report = analyzeAiEditor('No demos. No decks. No distractions. Same team. Better results.');
     assert.deepEqual(report.findings
         .filter((finding) => finding.id === 'struct.negation-cascade' || finding.id === 'struct.same-better')
-        .map((finding) => [finding.id, finding.sentence]), [
-        ['struct.negation-cascade', 1],
-        ['struct.same-better', 4],
-    ]);
+        .map((finding) => [finding.id, finding.sentence]), [['struct.negation-cascade', 1]]);
 });
 test('preserves inherited physical-line matching and line-start anchors', () => {
     const sameLine = analyzeAiEditor("This isn't positioning. This is proof. Forget vanity metrics. You need retention.");
@@ -106,16 +158,16 @@ test('retains the current question-hook and abstract-cluster detectors', () => {
 });
 test('serializes reconstructable regular expressions and explicit scopes', () => {
     const catalog = serializedRules();
-    assert.equal(catalog.length, 145);
+    assert.equal(catalog.length, 148);
     assert.ok(catalog.every((rule) => rule.scope === 'sentence' || rule.scope === 'line'));
     const meaningful = catalog.find((rule) => rule.id === 'ai.meaningful');
     assert.ok(meaningful);
     assert.equal(new RegExp(meaningful.expression.source, meaningful.expression.flags).test('Meaningful work.'), true);
 });
-test('keeps intentional inherited overlaps visible and scores each finding', () => {
+test('suppresses intentional inherited overlaps before scoring', () => {
     const report = analyzeAiEditor('In other words, use logs.');
-    assert.deepEqual(report.findings.map((finding) => finding.id), ['formula.in-other-words', 'struct.in-other-words']);
-    assert.equal(report.score, 64);
+    assert.deepEqual(report.findings.map((finding) => finding.id), ['formula.in-other-words']);
+    assert.equal(report.score, 82);
 });
 test('returns zero AI findings for clean input', () => {
     assert.deepEqual(analyzeAiEditor('The launch starts Tuesday. The owner signed the release checklist.').findings, []);

package/dist/approval-capability.js

@@ -0,0 +1,111 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { parseCanonicalJson } from './canonical-json.js';
+const DIGEST = /^[a-f0-9]{64}$/;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+const CLAIM_KEYS = ['version', 'purpose', 'issuer', 'audience', 'subjectArtifactFingerprint', 'sourceHash', 'candidateHash', 'profileId', 'profileRevisionDigest', 'keyId', 'issuedAt', 'notBefore', 'expiresAt', 'nonce'];
+const STORE_KEYS = ['version', 'audience', 'maxCapabilityLifetimeSeconds', 'keys'];
+function fail(error) { return { ok: false, error }; }
+function plain(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
+function exactKeys(value, required, optional = []) {
+    return required.every((key) => key in value) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function bounded(value) { return typeof value === 'string' && value.length > 0 && value.length <= 128; }
+function safeTime(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function validClaims(value) {
+    if (!plain(value) || !exactKeys(value, CLAIM_KEYS))
+        return false;
+    return bounded(value.issuer) && bounded(value.keyId) && bounded(value.profileId) && bounded(value.nonce)
+        && typeof value.version === 'string' && typeof value.purpose === 'string' && typeof value.audience === 'string'
+        && [value.subjectArtifactFingerprint, value.sourceHash, value.candidateHash].every((item) => typeof item === 'string' && DIGEST.test(item)) && bounded(value.profileRevisionDigest)
+        && safeTime(value.issuedAt) && safeTime(value.notBefore) && safeTime(value.expiresAt);
+}
+export function parseApprovalTrustStore(value) {
+    if (!plain(value) || !exactKeys(value, STORE_KEYS) || value.version !== '1' || value.audience !== '@holdyourvoice/hyv'
+        || !Number.isSafeInteger(value.maxCapabilityLifetimeSeconds) || value.maxCapabilityLifetimeSeconds < 1 || value.maxCapabilityLifetimeSeconds > 86400 || !Array.isArray(value.keys) || value.keys.length > 128)
+        return undefined;
+    const pairs = new Set();
+    for (const item of value.keys) {
+        if (!plain(item) || !exactKeys(item, ['issuer', 'keyId', 'publicKeySpki', 'status'], ['activeFrom', 'activeUntil']) || !bounded(item.issuer) || !bounded(item.keyId)
+            || typeof item.publicKeySpki !== 'string' || !BASE64URL.test(item.publicKeySpki) || !['active', 'revoked'].includes(item.status)
+            || (item.activeFrom !== undefined && !safeTime(item.activeFrom)) || (item.activeUntil !== undefined && !safeTime(item.activeUntil)))
+            return undefined;
+        const pair = `${item.issuer}\0${item.keyId}`;
+        if (pairs.has(pair))
+            return undefined;
+        pairs.add(pair);
+        try {
+            if (item.publicKeySpki.length > 128)
+                return undefined;
+            const der = Buffer.from(item.publicKeySpki, 'base64url');
+            const key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+            if (der.length !== 44 || key.asymmetricKeyType !== 'ed25519')
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value;
+}
+export function verifyApprovalCapability(envelope, trustValue, expected) {
+    if (!safeTime(expected.now))
+        return fail('invalid_schema');
+    if (!plain(envelope) || !exactKeys(envelope, ['payload', 'signature']) || typeof envelope.payload !== 'string' || typeof envelope.signature !== 'string'
+        || !BASE64URL.test(envelope.payload) || !BASE64URL.test(envelope.signature))
+        return fail('invalid_encoding');
+    if (envelope.payload.length > 5462 || envelope.signature.length !== 86)
+        return fail('size_exceeded');
+    const payload = Buffer.from(envelope.payload, 'base64url');
+    const signature = Buffer.from(envelope.signature, 'base64url');
+    if (payload.length > 4096 || signature.length !== 64)
+        return fail('size_exceeded');
+    if (payload.toString('base64url') !== envelope.payload || signature.toString('base64url') !== envelope.signature)
+        return fail('invalid_encoding');
+    let parsed;
+    try {
+        parsed = parseCanonicalJson(payload);
+    }
+    catch (error) {
+        return fail(error instanceof Error && /canonical/i.test(error.message) ? 'non_canonical' : 'invalid_schema');
+    }
+    if (!validClaims(parsed))
+        return fail('invalid_schema');
+    const claims = parsed;
+    if (claims.version !== '1')
+        return fail('wrong_version');
+    if (claims.purpose !== expected.expectedPurpose)
+        return fail('wrong_purpose');
+    if (claims.audience !== '@holdyourvoice/hyv')
+        return fail('wrong_audience');
+    if (claims.subjectArtifactFingerprint !== expected.expectedSubjectArtifactFingerprint || claims.sourceHash !== expected.binding.sourceHash || claims.candidateHash !== expected.binding.candidateHash || claims.profileId !== expected.binding.profileId || claims.profileRevisionDigest !== expected.binding.profileRevisionDigest)
+        return fail('binding_mismatch');
+    const trustStore = parseApprovalTrustStore(trustValue);
+    if (!trustStore)
+        return fail('invalid_schema');
+    if (claims.audience !== trustStore.audience)
+        return fail('wrong_audience');
+    const key = trustStore.keys.find((item) => item.issuer === claims.issuer && item.keyId === claims.keyId);
+    if (!key)
+        return fail('unknown_key');
+    if (key.status === 'revoked')
+        return fail('revoked_key');
+    if ((key.activeFrom !== undefined && (claims.issuedAt < key.activeFrom || expected.now < key.activeFrom)) || (key.activeUntil !== undefined && (claims.issuedAt >= key.activeUntil || expected.now >= key.activeUntil)))
+        return fail('inactive_key');
+    if (!(claims.issuedAt <= claims.notBefore && claims.notBefore < claims.expiresAt))
+        return fail('invalid_schema');
+    if (claims.expiresAt - claims.issuedAt > trustStore.maxCapabilityLifetimeSeconds)
+        return fail('lifetime_exceeded');
+    if (expected.now < claims.notBefore)
+        return fail('premature');
+    if (expected.now >= claims.expiresAt)
+        return fail('expired');
+    try {
+        const publicKey = createPublicKey({ key: Buffer.from(key.publicKeySpki, 'base64url'), format: 'der', type: 'spki' });
+        if (!verify(null, payload, publicKey, signature))
+            return fail('invalid_signature');
+    }
+    catch {
+        return fail('invalid_signature');
+    }
+    return { ok: true, capabilityFingerprint: createHash('sha256').update('hyv:approval-capability:v1\0').update(payload).update(signature).digest('hex') };
+}

package/dist/approval-capability.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { generateKeyPairSync, sign } from 'node:crypto';
+import test from 'node:test';
+import { canonicalJsonBytes } from './canonical-json.js';
+import { verifyApprovalCapability } from './approval-capability.js';
+const binding = {
+    rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: '3'.repeat(64),
+    sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64),
+    rulesetVersion: '3.2.0', schemaVersion: '1',
+};
+const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+const publicKeySpki = publicKey.export({ format: 'der', type: 'spki' }).toString('base64url');
+const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host.example', keyId: 'key-1', publicKeySpki, status: 'active' }] };
+function envelope(overrides = {}, signer = privateKey) {
+    const claims = {
+        version: '1', purpose: 'hyv.final-approval', issuer: 'host.example', audience: '@holdyourvoice/hyv',
+        subjectArtifactFingerprint: '7'.repeat(64), sourceHash: binding.sourceHash, candidateHash: binding.candidateHash,
+        profileId: binding.profileId, profileRevisionDigest: binding.profileRevisionDigest, keyId: 'key-1',
+        issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'nonce-1', ...overrides,
+    };
+    const payload = canonicalJsonBytes(claims);
+    return { payload: payload.toString('base64url'), signature: sign(null, payload, signer).toString('base64url') };
+}
+test('verifies one canonical bound Ed25519 final-approval capability', () => {
+    const result = verifyApprovalCapability(envelope(), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' });
+    assert.equal(result.ok, true);
+    if (result.ok)
+        assert.match(result.capabilityFingerprint, /^[a-f0-9]{64}$/);
+});
+test('fails closed for purpose, binding, trust, time, signature, and canonical encoding', () => {
+    assert.deepEqual(verifyApprovalCapability(envelope({ purpose: 'hyv.rebuild-authorization' }), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'wrong_purpose' });
+    assert.deepEqual(verifyApprovalCapability(envelope({ candidateHash: '8'.repeat(64) }), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'binding_mismatch' });
+    assert.deepEqual(verifyApprovalCapability(envelope(), { ...trustStore, keys: [{ ...trustStore.keys[0], status: 'revoked' }] }, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'revoked_key' });
+    assert.deepEqual(verifyApprovalCapability(envelope(), trustStore, { now: 201, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'expired' });
+    const forged = envelope();
+    const forgedBytes = Buffer.from(forged.signature, 'base64url');
+    forgedBytes[0] = forgedBytes[0] ^ 1;
+    forged.signature = forgedBytes.toString('base64url');
+    assert.deepEqual(verifyApprovalCapability(forged, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_signature' });
+    const nonCanonical = envelope();
+    nonCanonical.payload = Buffer.from(` ${Buffer.from(nonCanonical.payload, 'base64url').toString('utf8')}`).toString('base64url');
+    assert.deepEqual(verifyApprovalCapability(nonCanonical, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'non_canonical' });
+});
+test('rejects malformed envelopes and invalid trust stores without returning secret material', () => {
+    const result = verifyApprovalCapability({ payload: `${envelope().payload}=`, signature: envelope().signature }, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' });
+    assert.deepEqual(result, { ok: false, error: 'invalid_encoding' });
+    assert.doesNotMatch(JSON.stringify(result), /nonce-1|signature|publicKeySpki/);
+    assert.deepEqual(verifyApprovalCapability(envelope(), { ...trustStore, keys: [...trustStore.keys, trustStore.keys[0]] }, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_schema' });
+});
+test('rejects an invalid host clock', () => {
+    assert.deepEqual(verifyApprovalCapability(envelope(), trustStore, { now: Number.NaN, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_schema' });
+});

package/dist/approval-context.js

@@ -0,0 +1,54 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { parseApprovalTrustStore } from './approval-capability.js';
+const MAX_BYTES = 1024 * 1024;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function readBounded(descriptor) {
+    const chunks = [];
+    let size = 0;
+    while (size <= MAX_BYTES) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_BYTES + 1 - size));
+        const count = readSync(descriptor, chunk, 0, chunk.length, null);
+        if (!count)
+            break;
+        chunks.push(chunk.subarray(0, count));
+        size += count;
+    }
+    if (size > MAX_BYTES)
+        throw new Error();
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+function validIds(value) {
+    return Array.isArray(value) && value.length <= 128 && value.every((item) => typeof item === 'string' && ID.test(item)) && new Set(value).size === value.length;
+}
+export function approvalContextMetadataIsSafe(value, effectiveUserId) {
+    if (!value.isFile() || value.nlink !== 1 || value.size > MAX_BYTES)
+        return false;
+    if (effectiveUserId === undefined)
+        return process.platform === 'win32';
+    return value.uid === effectiveUserId && (value.mode & 0o077) === 0;
+}
+export function loadApprovalContext(path = join(userInfo().homedir, '.config', 'holdyourvoice', 'approval-context.json')) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const before = fstatSync(descriptor);
+        if (!approvalContextMetadataIsSafe(before, process.geteuid?.()))
+            throw new Error();
+        const value = JSON.parse(readBounded(descriptor));
+        const after = fstatSync(descriptor);
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || !value || typeof value !== 'object' || !parseApprovalTrustStore(value.trustStore) || !value.authorizedSemanticEvaluatorIds
+            || !validIds(value.authorizedSemanticEvaluatorIds.normal) || !validIds(value.authorizedSemanticEvaluatorIds.highAssurance) || !validIds(value.authorizedHumanFinalizerIds))
+            throw new Error();
+        return { ...value, now: Math.floor(Date.now() / 1000) };
+    }
+    catch {
+        throw new Error('Approval context is unavailable or unsafe.');
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}

package/dist/approval-context.test.js

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { approvalContextMetadataIsSafe, loadApprovalContext } from './approval-context.js';
+const context = { now: 0, trustStore: { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] }, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+test('loads only a permission-checked installed approval context and replaces its clock', () => {
+    const root = mkdtempSync(join(tmpdir(), 'hyv-approval-context-'));
+    try {
+        const safe = join(root, 'safe.json');
+        writeFileSync(safe, JSON.stringify(context), { mode: 0o600 });
+        const loaded = loadApprovalContext(safe);
+        assert.deepEqual(loaded.authorizedSemanticEvaluatorIds.normal, ['reviewer-1']);
+        assert.notEqual(loaded.now, 0);
+        chmodSync(safe, 0o644);
+        assert.throws(() => loadApprovalContext(safe), /unavailable or unsafe/);
+        chmodSync(safe, 0o600);
+        const link = join(root, 'link.json');
+        symlinkSync(safe, link);
+        assert.throws(() => loadApprovalContext(link), /unavailable or unsafe/);
+        const malformed = join(root, 'malformed.json');
+        writeFileSync(malformed, JSON.stringify({ ...context, authorizedSemanticEvaluatorIds: { normal: ['bad id'], highAssurance: [] } }), { mode: 0o600 });
+        assert.throws(() => loadApprovalContext(malformed), /unavailable or unsafe/);
+        const malformedTrust = join(root, 'malformed-trust.json');
+        writeFileSync(malformedTrust, JSON.stringify({ ...context, trustStore: { ...context.trustStore, maxCapabilityLifetimeSeconds: 0 } }), { mode: 0o600 });
+        assert.throws(() => loadApprovalContext(malformedTrust), /unavailable or unsafe/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('fails closed when POSIX ownership metadata is unavailable on this host', () => {
+    const metadata = { isFile: () => true, nlink: 1, size: 10, uid: 501, mode: 0o600 };
+    assert.equal(approvalContextMetadataIsSafe(metadata, undefined), process.platform === 'win32');
+    assert.equal(approvalContextMetadataIsSafe(metadata, 501), true);
+    assert.equal(approvalContextMetadataIsSafe({ ...metadata, mode: 0o644 }, 501), false);
+});