@holdyourvoice/hyv 2.9.25 → 2.9.27

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable CLI changes. Also mirrored to [holdyourvoice.com/changelog](https://holdyourvoice.com/changelog) for user-facing releases.
 
+## [2.9.27] — 2026-07-15
+
+### Fixed
+- **MCP scan hang** — `hyv_scan`, `hyv_fix`, `hyv_check`, `hyv_score`, `hyv_diff`, and `hyv_validate` no longer block on account profile sync; they use local `~/.hyv` cache immediately (matching `hyv scan` CLI) and hydrate profiles in the background
+
+## [2.9.26] — 2026-07-09
+
+### Improved
+- **Tier 1 structural detection** — cross-sentence binary reframes (`this is not X. it is Y.`), sermon anaphora, and founder-carousel metaphors now sort first in scan output and rewrite prompts
+- **Rewrite prompts** split tier 1 structural hits vs other patterns so the model fixes architecture before vocabulary slop
+- **18 new structural cousin rules** synced in local scan engine (`scan.ts`, `tier-one.ts`)
+
 ## [2.9.25] — 2026-07-04
 
 ### Fixed

package/README.md

@@ -96,7 +96,7 @@ hyv doctor --fix-agents
 | tool | description |
 |------|-------------|
 | `hyv_welcome` / `hyv_demo` | onboarding + live free scan demo |
-| `hyv_scan` | fast local scan (free, offline) |
+| `hyv_scan` | fast local scan (free, offline; uses `~/.hyv` cache, no network wait) |
 | `hyv_analyze` | hybrid local + server analysis (paid when online) |
 | `hyv_clean` | scan → fix → validate → rewrite prompt |
 | `hyv_fix` / `hyv_check` / `hyv_score` / `hyv_diff` | local utilities |
@@ -209,6 +209,10 @@ HYV_API_URL=https://staging.holdyourvoice.com hyv init
 - [blog](https://holdyourvoice.com/blog)
 - [community](https://holdyourvoice.com/community)
 
+## documentation ownership
+
+Changes under `cli/` update this README, the more-specific owner README when applicable, and the root repository README. Package-relative paths, bin names, published files, and postinstall behavior are contracts; validate them with `npm run validate:publish` before merging.
+
 ## license
 
 UNLICENSED — [holdyourvoice.com](https://holdyourvoice.com)

package/agents/README.md

@@ -0,0 +1,20 @@
+# `cli/agents/`
+
+## Purpose
+
+`cli/agents/` contains agent resources included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Changes must preserve package inclusion and postinstall discovery behavior.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.

package/assets/README.md

@@ -0,0 +1,20 @@
+# `cli/assets/`
+
+## Purpose
+
+`cli/assets/` contains assets included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Keep package paths and postinstall consumers intact.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.

package/assets/ai-eliminator-rules.md

@@ -21,6 +21,16 @@ patterns, and uniform sentence rhythm within paragraphs.
 - "It's not X, it's Y" / "The point isn't X, it's Y"
 - "You don't need X, you need Y"
 - "Not just X, but Y" / "Not only... but also"
+- **structural cousins (top priority):** cross-sentence forms the vocabulary scan misses:
+  - "This is not X. It is Y." / "Is not X. It is Y."
+  - "You are not X. You are Y." / "You are no longer X. You are Y."
+  - "You stop X. You start Y."
+  - "They don't need X. They need Y."
+  - "They call it X. They call it Y." (staccato anaphora)
+  - Parallel sermon: "X because… / they X because…" and "endure through… / they endure through…"
+  - Founder-carousel metaphors: "competing with the void", "architect of a new reality", "friction into momentum", "cognitive architecture", "defines what good looks like", "the hidden goal", "quiet promise", "simple but uncomfortable:"
+
+**Tier 1 priority:** rules with ids `structural_*` and `founder_*` are primary flags. They sort first in scan output, win hit-budget slots in the editor, weigh heavier in cleanliness scoring, lead rewrite prompts, and gate rewrite output before vocabulary slop.
 
 ### Staccato drama (#2, #95, #96)
 - Short punchy sentence runs: "No X. No Y. Just Z."

package/dist/index.js

@@ -11316,6 +11316,23 @@ var init_patterns = __esm({
       { id: "struct.lesson-setup", category: "structure", severity: "yellow", regex: /\bhere'?s what .{3,60} taught\b/gi, suggestion: "just share the lesson" },
       // THE BIG ONE — antithesis negation pattern (Voice DNA: FATAL)
       { id: "struct.this-isnt-x-this-is-y", category: "structure", severity: "red", regex: /\bthis isn'?t .{2,40}\.?\s*(?:this is|it'?s) .{2,40}/gi, suggestion: "FATAL: delete the negation, just state the positive claim" },
+      { id: "struct.this-is-not-it-is", category: "structure", severity: "red", regex: /\bthis\s+is\s+not\b.{3,80}\.\s*it\s+is\b/gi, suggestion: 'FATAL: "this is not X. it is Y" \u2014 state what it is directly' },
+      { id: "struct.is-not-it-is", category: "structure", severity: "red", regex: /\bis\s+not\b.{3,80}\.\s*it\s+is\b/gi, suggestion: "FATAL: negation-then-reveal \u2014 drop the denial" },
+      { id: "struct.you-are-not-you-are", category: "structure", severity: "red", regex: /\byou\s+are\s+not\b.{3,80}\.\s*you\s+are\b/gi, suggestion: "FATAL: identity reframe carousel \u2014 say what they are" },
+      { id: "struct.you-no-longer-you-are", category: "structure", severity: "red", regex: /\byou\s+are\s+no\s+longer\b.{3,80}\.\s*you\s+are\b/gi, suggestion: "FATAL: escalation reframe \u2014 one grounded sentence" },
+      { id: "struct.you-stop-you-start", category: "structure", severity: "red", regex: /\byou\s+stop\b.{3,50}\.\s*you\s+start\b/gi, suggestion: "FATAL: pivot cadence \u2014 describe the behavior change" },
+      { id: "struct.need-negation-pivot", category: "structure", severity: "red", regex: /\b(?:do\s+not|don'?t)\s+need\b.{3,50}\.\s*(?:they|you)\s+need\b/gi, suggestion: "FATAL: need antithesis \u2014 say what they need" },
+      { id: "struct.they-call-it-anaphora", category: "structure", severity: "red", regex: /\bthey\s+call\s+it\b[^.!?]{2,50}[.!?]\s*they\s+call\s+it\b/gi, suggestion: "FATAL: staccato anaphora \u2014 name it once" },
+      { id: "struct.parallel-because", category: "structure", severity: "red", regex: /\b(\w+)\s+because\b[^.!?]{3,60}[.!?]\s*they\s+\1\s+because\b/gi, suggestion: "FATAL: parallel sermon rhythm \u2014 merge into one sentence" },
+      { id: "struct.parallel-endure", category: "structure", severity: "red", regex: /\bendure\s+through\b[^.!?]{3,60}[.!?]\s*they\s+endure\s+through\b/gi, suggestion: "FATAL: parallel maxim \u2014 say it once" },
+      { id: "struct.simple-but-uncomfortable", category: "structure", severity: "red", regex: /\bsimple\s+but\s+uncomfortable\s*:/gi, suggestion: "truth-posture colon reveal \u2014 state the mechanism" },
+      { id: "struct.hidden-goal", category: "structure", severity: "red", regex: /\bthe\s+hidden\s+goal\b/gi, suggestion: "reveal framing \u2014 say the goal directly" },
+      { id: "struct.quiet-promise", category: "structure", severity: "red", regex: /\bquiet\s+promise\b/gi, suggestion: "profundity metaphor \u2014 name the actual commitment" },
+      { id: "struct.competing-void", category: "structure", severity: "red", regex: /\bcompeting\s+with\s+the\s+void\b/gi, suggestion: "screenshot profundity \u2014 name the real competitor" },
+      { id: "struct.architect-reality", category: "structure", severity: "red", regex: /\barchitect\s+of\s+(?:a\s+)?new\s+reality\b/gi, suggestion: "thought-leader grandiosity \u2014 describe what you build" },
+      { id: "struct.friction-momentum", category: "structure", severity: "red", regex: /\b(?:turns?\s+)?friction\s+into\s+momentum\b/gi, suggestion: "transformation buzzphrase \u2014 explain the mechanism" },
+      { id: "struct.cognitive-architecture", category: "structure", severity: "red", regex: /\bcognitive\s+architecture\b/gi, suggestion: "abstract systems metaphor \u2014 use a concrete scene" },
+      { id: "struct.defines-good", category: "structure", severity: "red", regex: /\bdefines\s+what\s+good\s+looks\s+like\b/gi, suggestion: "consultant language \u2014 show an example of good" },
       { id: "struct.not-x-y", category: "structure", severity: "red", regex: /\bnot .{2,30}\.?\s*.{2,30}\b/gi, suggestion: 'the "Not X. Y." pattern is an AI tell \u2014 just state Y' },
       { id: "struct.forget-x", category: "structure", severity: "red", regex: /\bforget .{2,40}\.?\s*(?:this is|it'?s|you need)/gi, suggestion: "don't negate \u2014 just state what you mean" }
     ];
@@ -11375,6 +11392,34 @@ var init_patterns = __esm({
   }
 });
 
+// src/lib/tier-one.ts
+function isTierOneRule(ruleId) {
+  const id = String(ruleId || "");
+  if (TIER_ONE_PREFIXES.some((p) => id.startsWith(p)))
+    return true;
+  return TIER_ONE_SIGNAL_IDS.has(id);
+}
+function tierSortKey(ruleId) {
+  return isTierOneRule(ruleId) ? 0 : 1;
+}
+var TIER_ONE_PREFIXES, TIER_ONE_SIGNAL_IDS;
+var init_tier_one = __esm({
+  "src/lib/tier-one.ts"() {
+    "use strict";
+    TIER_ONE_PREFIXES = ["structural_", "founder_"];
+    TIER_ONE_SIGNAL_IDS = /* @__PURE__ */ new Set([
+      "struct.this-isnt-x-this-is-y",
+      "struct.not-x-y",
+      "struct.negation-cascade",
+      "struct.which-is-another",
+      "struct.in-other-words",
+      "struct.moment-becomes",
+      "struct.same-better",
+      "struct.generic-buyer"
+    ]);
+  }
+});
+
 // src/lib/scan.ts
 function words(text) {
   return (text || "").match(/[a-zA-Z][a-zA-Z0-9']*/g) || [];
@@ -11485,6 +11530,9 @@ function scanText(text) {
     }
   }
   return hits.sort((a, b) => {
+    const tier = tierSortKey(a.rule) - tierSortKey(b.rule);
+    if (tier !== 0)
+      return tier;
     if (a.line !== b.line)
       return a.line - b.line;
     return a.rule.localeCompare(b.rule);
@@ -11495,6 +11543,7 @@ var init_scan = __esm({
   "src/lib/scan.ts"() {
     "use strict";
     init_patterns();
+    init_tier_one();
     AI_PATTERN_RULES = [
       {
         id: "ai_antithesis",
@@ -11555,6 +11604,75 @@ var init_scan = __esm({
       {
         id: "founder_cadence_same_better",
         pattern: /\bsame\s+[^.!?\n]{1,35}[.!?]\s*(?:better|nicer|cleaner|calmer|safer)\s+[^.!?\n]{1,35}[.!?]?/i
+      },
+      // structural cousins — cross-sentence binary reframing (top priority)
+      {
+        id: "structural_this_is_not_it_is",
+        pattern: /\bthis\s+is\s+not\b.{3,80}\.\s*it\s+is\b/i
+      },
+      {
+        id: "structural_is_not_it_is",
+        pattern: /\bis\s+not\b.{3,80}\.\s*it\s+is\b/i
+      },
+      {
+        id: "structural_you_are_not_you_are",
+        pattern: /\byou\s+are\s+not\b.{3,80}\.\s*you\s+are\b/i
+      },
+      {
+        id: "structural_you_no_longer_you_are",
+        pattern: /\byou\s+are\s+no\s+longer\b.{3,80}\.\s*you\s+are\b/i
+      },
+      {
+        id: "structural_you_stop_you_start",
+        pattern: /\byou\s+stop\b.{3,50}\.\s*you\s+start\b/i
+      },
+      {
+        id: "structural_need_negation_pivot",
+        pattern: /\b(?:do\s+not|don'?t)\s+need\b.{3,50}\.\s*(?:they|you)\s+need\b/i
+      },
+      {
+        id: "structural_they_call_it_anaphora",
+        pattern: /\bthey\s+call\s+it\b[^.!?]{2,50}[.!?]\s*they\s+call\s+it\b/i
+      },
+      {
+        id: "structural_parallel_verb_because",
+        pattern: /\b(\w+)\s+because\b[^.!?]{3,60}[.!?]\s*they\s+\1\s+because\b/i
+      },
+      {
+        id: "structural_parallel_endure_through",
+        pattern: /\bendure\s+through\b[^.!?]{3,60}[.!?]\s*they\s+endure\s+through\b/i
+      },
+      {
+        id: "structural_simple_but_uncomfortable",
+        pattern: /\bsimple\s+but\s+uncomfortable\s*:/i
+      },
+      {
+        id: "structural_hidden_goal",
+        pattern: /\bthe\s+hidden\s+goal\b/i
+      },
+      {
+        id: "structural_quiet_promise",
+        pattern: /\bquiet\s+promise\b/i
+      },
+      {
+        id: "founder_competing_with_void",
+        pattern: /\bcompeting\s+with\s+the\s+void\b/i
+      },
+      {
+        id: "founder_architect_of_reality",
+        pattern: /\barchitect\s+of\s+(?:a\s+)?new\s+reality\b/i
+      },
+      {
+        id: "founder_friction_into_momentum",
+        pattern: /\b(?:turns?\s+)?friction\s+into\s+momentum\b/i
+      },
+      {
+        id: "founder_cognitive_architecture",
+        pattern: /\bcognitive\s+architecture\b/i
+      },
+      {
+        id: "founder_defines_good_looks_like",
+        pattern: /\bdefines\s+what\s+good\s+looks\s+like\b/i
       }
     ];
     ABSTRACT_STYLE_WORDS = /* @__PURE__ */ new Set([
@@ -16372,6 +16490,8 @@ var path11 = __toESM(require("path"));
 init_config();
 init_signals();
 init_profile_parse();
+init_scan();
+init_tier_one();
 function loadPromptTemplate() {
   const templatePath = path11.join(CACHE_DIR2, "prompt-template.md");
   try {
@@ -16420,6 +16540,7 @@ Rules:
 - "Not X. Y." is banned. Just state Y.
 - "Forget X. This is Y." is banned. Just state Y.
 - ANY sentence that negates one framing then asserts a corrected one fails.
+- Tier 1 structural patterns (binary reframes, negation pivots, parallel sermon cadence) outrank vocabulary fixes. Kill the architecture first.
 
 Voice profile:
 {profile_block}
@@ -16427,8 +16548,11 @@ Voice profile:
 Extra constraints:
 {constraints_block}
 
-Flagged lines:
-{issue_lines}
+Tier 1 \u2014 structural (fix first):
+{tier_one_lines}
+
+Other flagged patterns:
+{other_lines}
 
 Draft with line numbers ({draft_name}):
 {numbered_draft}
@@ -16488,6 +16612,38 @@ function buildProfileBlock(fullProfile, fallbackName) {
   }
   return { block: "(no voice profile supplied \u2014 use generic voice rules)", name: null };
 }
+function collectPromptIssues(draftContent, fullProfile) {
+  const issues = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addIssue = (line, rule, detail) => {
+    const key = `${line}|${rule}|${detail.slice(0, 80)}`;
+    if (seen.has(key))
+      return;
+    seen.add(key);
+    issues.push({ line, rule, detail, tierOne: isTierOneRule(rule) });
+  };
+  for (const signal of extractSignals(draftContent, fullProfile).signals) {
+    addIssue(signal.line, signal.id, signal.suggestion);
+  }
+  for (const hit of scanText(draftContent)) {
+    addIssue(hit.line, hit.rule, hit.phrase || hit.text || "");
+  }
+  issues.sort((a, b) => {
+    const tier = tierSortKey(a.rule) - tierSortKey(b.rule);
+    if (tier !== 0)
+      return tier;
+    if (a.line !== b.line)
+      return a.line - b.line;
+    return a.rule.localeCompare(b.rule);
+  });
+  return issues;
+}
+function formatIssueLines(issues, tierOneOnly) {
+  const filtered = issues.filter((i) => i.tierOne === tierOneOnly);
+  if (!filtered.length)
+    return "- none found";
+  return filtered.map((i) => `- line ${i.line} [${i.rule}]: ${i.detail}`).join("\n");
+}
 function buildRewritePrompt(options) {
   const {
     draftPath,
@@ -16498,16 +16654,19 @@ function buildRewritePrompt(options) {
     skipScan = false
   } = options;
   const { block: profileBlock, name: profileUsed } = buildProfileBlock(fullProfile, profileName);
-  const signals = skipScan ? [] : extractSignals(draftContent, fullProfile).signals;
-  const issueLines = signals.length > 0 ? signals.map((s) => `- line ${s.line} [${s.id}]: ${s.suggestion}`).join("\n") : "- none found by deterministic scan";
+  const issues = skipScan ? [] : collectPromptIssues(draftContent, fullProfile);
+  const tierOneLines = formatIssueLines(issues, true);
+  const otherLines = formatIssueLines(issues, false);
   const draftLines = draftContent.split("\n");
   const numberedDraft = draftLines.map((line, i) => `${i + 1}: ${line}`).join("\n");
   const template = loadPromptTemplate();
-  const prompt = template.replace("{profile_block}", profileBlock).replace("{constraints_block}", constraints || "(none)").replace("{issue_lines}", issueLines).replace("{draft_name}", draftPath).replace("{numbered_draft}", numberedDraft);
+  const prompt = template.replace("{profile_block}", profileBlock).replace("{constraints_block}", constraints || "(none)").replace("{tier_one_lines}", tierOneLines).replace("{other_lines}", otherLines).replace("{draft_name}", draftPath).replace("{numbered_draft}", numberedDraft);
   return {
-    prompt,
+    prompt: skipScan ? `${prompt}
+
+none found by deterministic scan` : prompt,
     profileUsed,
-    issuesFound: signals.length
+    issuesFound: issues.length
   };
 }
 
@@ -17781,6 +17940,7 @@ var MCP_SERVER_ARGS = ["mcp", "--stdio"];
 // src/lib/cli-entry.ts
 function resolveCliEntry() {
   const candidates = [
+    typeof __filename !== "undefined" ? path17.resolve(__filename) : "",
     path17.resolve(process.argv[1] || ""),
     path17.resolve(__dirname, "index.js"),
     path17.resolve(__dirname, "..", "dist", "index.js")
@@ -17792,7 +17952,7 @@ function mcpServerCommand() {
   if (entry) {
     return { command: process.execPath, args: [entry, ...MCP_SERVER_ARGS] };
   }
-  return { command: "hyv", args: [...MCP_SERVER_ARGS] };
+  throw new Error("could not resolve hyv CLI entry \u2014 reinstall @holdyourvoice/hyv or run via node dist/index.js");
 }
 function mcpServerSnippet() {
   const { command, args: args2 } = mcpServerCommand();
@@ -19670,6 +19830,10 @@ async function resolveProfile(slug) {
   }
   return profile;
 }
+async function loadLocalProfileForTool(slug) {
+  void ensureMcpProfilesHydrated();
+  return loadProfileForCommand(slug);
+}
 function jsonRpcOk(id, result) {
   return JSON.stringify({ jsonrpc: "2.0", id, result });
 }
@@ -19727,7 +19891,7 @@ async function toolScan(args2) {
     return "Error: no text or file provided";
   try {
     let scanText2 = text;
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     if (filePath) {
       try {
         scanText2 = readScanFile(filePath);
@@ -19775,7 +19939,7 @@ async function toolValidate(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(profileSlug);
+    const profile = await loadLocalProfileForTool(profileSlug);
     if (!profile)
       return "Error: no voice profile available. Run hyv init or use hyv scan for free generic checks.";
     const result = validateRewrite(text, text, profile);
@@ -19798,7 +19962,7 @@ async function toolFix(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, true);
     if (result.changes.length === 0)
       return "No auto-fixable issues found.";
@@ -19817,7 +19981,7 @@ async function toolCheck(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, false);
     if (result.stats.totalSignals === 0)
       return `Clean \u2014 score: ${result.score}/100. No AI patterns found.`;
@@ -19835,7 +19999,7 @@ async function toolScore(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, false);
     return result.score.toString();
   } catch (err) {
@@ -19847,7 +20011,7 @@ async function toolDiff(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, true);
     if (result.changes.length === 0)
       return "No auto-fixable changes available.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "2.9.25",
+  "version": "2.9.27",
   "description": "Free local AI writing scan for cursor & claude. MCP server, 220+ pattern detection, voice profiles. npx @holdyourvoice/hyv welcome",
   "main": "dist/index.js",
   "bin": {

package/scripts/README.md

@@ -0,0 +1,21 @@
+# `cli/scripts/`
+
+## Purpose
+
+`cli/scripts/` contains package install, publish validation, smoke-test, and supporting CLI scripts.
+
+## Contracts
+
+Scripts are referenced by `cli/package.json` and the npm package `files` list. Package-relative paths must remain valid when the package is published.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+npm run test:smoke
+```
+
+## Documentation ownership
+
+Changes under this folder update this README, `cli/README.md`, and the root `README.md`.

package/skills/README.md

@@ -0,0 +1,20 @@
+# `cli/skills/`
+
+## Purpose
+
+`cli/skills/` contains skills included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Changes must preserve package inclusion and any postinstall or agent configuration paths that reference these files.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.