@holdyourvoice/hyv 3.4.4 → 3.5.0

package/skills/hyv-backtest/agent.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-backtest",
+  "title": "hyv-backtest",
+  "description": "Evaluate a caller-supplied reconstruction against a held-out local target without generating text.",
+  "instruction_file": "SKILL.md",
+  "role": "Information-isolated evaluator",
+  "workflow_phase": "verify",
+  "input": { "required": ["context path", "held-out target path", "candidate path", "profile path", "three or more held-out sample paths"], "optional": [] },
+  "output": { "required": ["text-free backtest report"], "optional": [] },
+  "evidence_requirements": ["Report preservation, AI Editor, and held-out-band results separately; never call the report an authorship or generation result."],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": ["Stop when the candidate was not supplied by the caller or fewer than three held-out samples are supplied."],
+  "tool_free_mode": { "available": true, "behavior": "Provide the exact command and state that the local backtest is NOT_RUN; never invent a score.", "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"] },
+  "handoff_to": ["hyv-verify"]
+}

package/skills/hyv-backtest/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Backtest"
+  short_description: "Evaluate a supplied reconstruction without generating text."
+  default_prompt: "Use $hyv-backtest to score a caller-supplied reconstruction against held-out local writing without making an authorship claim."

package/skills/hyv-evaluate-local/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: hyv-evaluate-local
+description: Run the optional deterministic local writing evaluation composite without model calls.
+---
+
+# hyv-evaluate-local
+
+Evaluate a caller-supplied candidate against an input and separate local user and AI-shadow paragraph fixtures. The module trains only on the paragraph IDs assigned to the train split. It does not generate prose, transmit samples, retain text, or establish authorship.
+
+```text
+hyv evaluate-local input.md candidate.md user-paragraphs.json ai-shadow-paragraphs.json
+```
+
+Each JSON file is an array of `{ "paragraph_id": "stable-id", "text": "..." }`. Keep variants under the same paragraph ID; HYV splits by ID before training. The report contains a train-only TF-IDF logistic-regression proxy, content F1, AI-tell change, and 9-d stylometric cosine. Treat every number as a local evaluation signal, not a publishing decision or identity claim.

package/skills/hyv-evaluate-local/agent.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-evaluate-local",
+  "title": "hyv-evaluate-local",
+  "description": "Run the optional deterministic local writing evaluation composite without model calls.",
+  "instruction_file": "SKILL.md",
+  "role": "Local writing evaluation reporter",
+  "workflow_phase": "verify",
+  "input": { "required": ["input path", "candidate path", "user paragraph JSON", "AI-shadow paragraph JSON"], "optional": [] },
+  "output": { "required": ["paragraph-isolated evaluation report"], "optional": [] },
+  "evidence_requirements": ["Report that the authorship component is a local train-only proxy, not an authorship verdict.", "Do not allow paragraph IDs in both train and test sets."],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": ["Stop when either fixture has fewer than two unique paragraph IDs or the JSON schema is invalid."],
+  "tool_free_mode": { "available": true, "behavior": "Provide the exact command and state that the report is NOT_RUN; never invent scores.", "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"] },
+  "handoff_to": ["hyv-verify"]
+}

package/skills/hyv-evaluate-local/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Local Evaluation"
+  short_description: "Run an isolated local writing-evaluation composite."
+  default_prompt: "Use $hyv-evaluate-local to run the paragraph-isolated local evaluation composite without making an authorship claim."

package/skills/hyv-final-check/SKILL.md

@@ -7,6 +7,8 @@ description: Gate exact user-facing text from any model, tool, or interface.
 
 Gate exact final text from every producer. Returns output only when clean or after removing a leading byte-order mark; unresolved hidden characters withhold output. It does not require or select a VoiceDNA profile. Run it immediately before display, copy, export, posting, or returning an API response.
 
+This is a hidden-text boundary only. It does not prove AI-pattern quality or voice matching. When the caller needs that stricter decision, run hyv-strict-check first, then run final-check again on the exact text that will be delivered.
+
 ## Usage
 
 ```text

package/skills/hyv-find-writing-examples/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: hyv-find-writing-examples
+description: Find redacted excerpts from explicit local writing samples in memory only.
+---
+
+# hyv-find-writing-examples
+
+Use the `hyv_find_writing_examples` MCP tool with a query and one to 64 explicit local `{ basename, text }` samples. It returns at most three ranked excerpts, redacts sensitive values, exposes basenames only, and never writes a corpus or index.
+
+Pass approved examples to `hyv_rewrite_prompt` only as advisory cadence evidence. They cannot override preservation, facts, AI Editor blockers, or final-output checks.

package/skills/hyv-find-writing-examples/agent.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-find-writing-examples",
+  "title": "hyv-find-writing-examples",
+  "description": "Find redacted excerpts from explicit local writing samples in memory only.",
+  "instruction_file": "SKILL.md",
+  "role": "Private style evidence finder",
+  "workflow_phase": "analyze",
+  "input": { "required": ["query", "one to 64 explicit local samples with basenames"], "optional": [] },
+  "output": { "required": ["up to three redacted excerpts with basenames"], "optional": [] },
+  "evidence_requirements": ["Report only basenames and redacted excerpts. Never claim an index was stored or a network request was made."],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": ["Stop when samples are not explicitly supplied, a source is not a basename, or the query has no useful local terms."],
+  "tool_free_mode": { "available": true, "behavior": "State that local example lookup is NOT_RUN and provide the exact MCP operation; never invent excerpts.", "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"] },
+  "handoff_to": ["hyv-rewrite-prompt"]
+}

package/skills/hyv-find-writing-examples/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Writing Examples"
+  short_description: "Find redacted local style examples without storing an index."
+  default_prompt: "Use $hyv-find-writing-examples to find up to three redacted excerpts from explicit local writing samples."

package/skills/hyv-ingest/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: hyv-ingest
+description: Redact an owner-authorized Gmail or Telegram export into local VoiceDNA samples.
+---
+
+# hyv-ingest
+
+Turn an explicitly authorized local Gmail Sent.mbox or Telegram Desktop JSON export into redacted writing samples. This is opt-in local preprocessing, not background collection, training, synchronization, or network access.
+
+## Usage
+
+```text
+hyv ingest <gmail-sent-mbox|telegram-desktop-json> export --owner=owner --output=/absolute/safe-directory [--blocked=word]
+```
+
+## Preconditions
+
+- Confirm the source is authorized by its owner and select the source type exactly.
+- Use an existing absolute output directory outside every Git checkout. The command creates new `samples.jsonl` and text-free `receipt.json`; it refuses existing files and never overwrites exports.
+- Add `--blocked=word` for each user-supplied term that must drop its entire sentence. Do not put secrets or sample prose in command output or a status message.
+
+## Behavior
+
+- Only messages attributable to the explicit owner are retained.
+- Email addresses, phone numbers, card-like values, IP addresses, and URLs are deterministically redacted before `samples.jsonl` is created. The receipt records counts and digests, never raw prose, paths, or source content.
+- Presidio is optional. If no approved adapter ran, report `NOT_CONFIGURED`; do not imply it was installed.
+- This command makes no provider call, telemetry event, network request, profile, or model. It cannot open a socket.
+
+## Handoff
+
+Inspect the new samples locally, then use `hyv-profile` to build a profile or `hyv-score` with a separately held-out set. Do not add the redacted export to a repository without separate approval.

package/skills/hyv-ingest/agent.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-ingest",
+  "title": "hyv-ingest",
+  "description": "Redact an owner-authorized Gmail or Telegram export into local VoiceDNA samples.",
+  "instruction_file": "SKILL.md",
+  "role": "Private sample hygiene operator",
+  "workflow_phase": "analyze",
+  "input": {
+    "required": ["gmail-sent-mbox or telegram-desktop-json source", "explicit owner identifier", "absolute existing output directory outside every Git checkout"],
+    "optional": ["--blocked=word sentence-drop entries"]
+  },
+  "output": { "required": ["new redacted samples.jsonl", "new text-free receipt.json"], "optional": [] },
+  "evidence_requirements": [
+    "Confirm the explicit source type, owner identifier, output directory, and receipt counts without reproducing sample prose.",
+    "State Presidio as NOT_CONFIGURED unless an approved adapter actually reports otherwise."
+  ],
+  "permissions": ["execute_commands", "read_repository", "write_repository"],
+  "stop_conditions": [
+    "Stop when ownership is not explicit, the output is relative, inside a Git checkout, missing, or already contains either output file, or the source type is not supported."
+  ],
+  "tool_free_mode": {
+    "available": true,
+    "behavior": "Provide the exact local command and state that ingest is NOT_RUN; never claim redaction or write output without execution.",
+    "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"]
+  },
+  "handoff_to": ["hyv-profile", "hyv-score"]
+}

package/skills/hyv-ingest/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Ingest"
+  short_description: "Redact an owner-authorized Gmail or Telegram export into local writing samples."
+  default_prompt: "Use $hyv-ingest to create redacted local samples from an owner-authorized Gmail or Telegram export without network access."

package/skills/hyv-patterns/SKILL.md

@@ -16,6 +16,8 @@ hyv patterns
 ## Behavior
 
 - Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- The catalog is evaluated against author prose only; rule listing does not imply that a pattern proves AI authorship.
+- Profile v3 may disable only an eligible default through signed non-verbatim sample evidence. Inspect the profile policy separately because explicit policy wins.
 - Commands that write use an explicit output path. Confirm that path before running the command.
 - This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
 

package/skills/hyv-profile/SKILL.md

@@ -16,6 +16,8 @@ hyv profile profile.json sample-a.md sample-b.md [sample-c.md] [--avoid=phrase]
 ## Behavior
 
 - Deterministic and local-first: this command never calls a provider and never sends drafts, samples, profiles, or telemetry to a service.
+- This command writes the stable Profile v2 shape. For channel-specific V3 profiles use `hyv profile v3 profile.json --id=writer.email --channel=email sample-a.md sample-b.md [--tone=0,0,0,0,0] [--avoid=phrase]`; it signs policy and sample allowances without retaining raw prose. To blend approved V3 profiles locally, use `hyv profile compose --ratio 70:30 profile-a.json profile-b.json`.
+- To rebuild a V3 profile after explicit sample changes, use `hyv profile watch /absolute/profile.json --id=writer.email --channel=email sample-a.md sample-b.md`. The watcher debounces named local files and writes only to an existing, non-Git absolute directory; stop it with Ctrl-C.
 - Commands that write use an explicit output path. Confirm that path before running the command.
 - This agent describes how to invoke the command and what it returns. It does not change command behavior or exit codes.
 

package/skills/hyv-score/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hyv-score
+description: Score a draft against an explicit held-out local writing band.
+---
+
+# hyv-score
+
+Use this with three or more samples that were not used to build the profile. It reports whether a candidate sits inside the writer's observed range. It is local-only and is not an authorship, factuality, or publication-quality score. Profile v3 adds channel-aware scoring; Profile v2 remains general-channel compatible.
+
+## Usage
+
+```text
+hyv score draft.md profile.json heldout-a.md heldout-b.md heldout-c.md [--channel=email|chat|long-form|social|docs|general]
+```
+
+## Behavior
+
+- Use only writing the owner has authorized and retain no new samples or telemetry.
+- Keep profile-building and held-out samples separate. Do not relabel a different channel to force a score.
+- HYV abstains when there are too few usable held-out samples, language confidence is insufficient for its English-oriented metrics, or the channel conflicts with the profile. Report that abstention rather than treating it as a failure or a score.
+- The result includes component similarity and the writer's own pairwise range. A high score is not proof that the candidate was written by the person.
+- This command is read-only. It does not call a provider, change a draft, or write a profile.
+
+## Handoff
+
+Use `hyv-rewrite-prompt` for a bounded external editing brief, then `hyv-verify` for candidate verification. Re-run this score only with the same explicit held-out set when comparing drafts.

package/skills/hyv-score/agent.json

@@ -0,0 +1,28 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-score",
+  "title": "hyv-score",
+  "description": "Score a draft against an explicit held-out local writing band.",
+  "instruction_file": "SKILL.md",
+  "role": "Held-out voice evaluator",
+  "workflow_phase": "verify",
+  "input": {
+    "required": ["draft path", "profile path", "three or more held-out sample paths"],
+    "optional": ["--channel=email|chat|long-form|social|docs|general"]
+  },
+  "output": { "required": ["local held-out score report"], "optional": [] },
+  "evidence_requirements": [
+    "Report the returned band disposition and abstentions exactly; it is not an authorship claim.",
+    "Do not replace held-out samples with profile-building samples or claim a result when language confidence is insufficient."
+  ],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": [
+    "Stop when fewer than three held-out samples are supplied, the selected channel conflicts with the profile, or the score abstains."
+  ],
+  "tool_free_mode": {
+    "available": true,
+    "behavior": "Provide the exact command and state that local score execution is NOT_RUN; never invent a score.",
+    "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"]
+  },
+  "handoff_to": ["hyv-rewrite-prompt", "hyv-verify"]
+}

package/skills/hyv-score/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Score"
+  short_description: "Score a draft against an explicit held-out local writing band."
+  default_prompt: "Use $hyv-score to score a draft against three or more held-out local samples without making an authorship claim."

package/skills/hyv-strict-check/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hyv-strict-check
+description: Run the local strict AI-pattern and calibrated voice-match gate.
+---
+
+# hyv-strict-check
+
+Run the opt-in strict local quality gate without changing the draft, profile, or learning state.
+
+## Usage
+
+```text
+hyv strict-check draft.md profile-v3.json sample-a.md sample-b.md sample-c.md sample-d.md sample-e.md
+```
+
+## Behavior
+
+- Requires a Profile v3 built from at least five samples, five or more local validation samples, 1,500 validation-sample words, no duplicate samples, a consistent visible format baseline, and calibrated fingerprint tolerances.
+- Returns `strict-ready`, `needs-human-review`, or `blocked` as JSON and exits `0` only for `strict-ready`.
+- `blocked` covers missing strict evidence, configured blocking AI patterns, hard calibrated fingerprint drift, red VoiceDNA findings, and unresolved hidden text.
+- `needs-human-review` keeps advisory and judgment-required AI patterns visible. It is not a clean result.
+- It remains local-first and never sends samples or drafts to a provider.
+
+## Handoff
+
+Fix only the named finding, then rerun the command. Do not rewrite unflagged text or promote any edit into learning from this command. Only after `strict-ready`, run hyv-final-check on the exact text that will be delivered; that final output boundary remains required after any later edit or formatting step.

package/skills/hyv-strict-check/agent.json

@@ -0,0 +1,33 @@
+{
+  "schema_version": "1.0.0",
+  "id": "hyv-strict-check",
+  "title": "hyv-strict-check",
+  "description": "Run the local strict AI-pattern and calibrated voice-match gate.",
+  "instruction_file": "SKILL.md",
+  "role": "Strict quality gate",
+  "workflow_phase": "verify",
+  "input": {
+    "required": ["draft path", "Profile v3 path", "at least five local writing-sample paths"],
+    "optional": []
+  },
+  "output": {
+    "required": ["strict-ready, needs-human-review, or blocked report"],
+    "optional": []
+  },
+  "evidence_requirements": [
+    "Report the exact local result, including readiness and every blocking or review finding.",
+    "Never call strict-ready a fact, authorship, or publication verdict.",
+    "Treat a mixed-format baseline or a profile built from fewer than five samples as blocked evidence."
+  ],
+  "permissions": ["execute_commands", "read_repository"],
+  "stop_conditions": [
+    "Stop when a Profile v3, enough samples, or calibrated metric tolerances are missing.",
+    "Stop when the result is blocked or needs human review; do not change the draft or learning state."
+  ],
+  "tool_free_mode": {
+    "available": true,
+    "behavior": "Provide the required inputs and explain that no strict result was run.",
+    "unavailable_statuses": ["NOT_AVAILABLE", "NOT_CONFIGURED", "NOT_RUN", "STALE", "ERROR"]
+  },
+  "handoff_to": ["hyv-final-check"]
+}

package/skills/hyv-strict-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyv Strict Check"
+  short_description: "Run strict local AI-pattern and voice-match checks."
+  default_prompt: "Use $hyv-strict-check to run a strict local quality check on this draft."

package/skills/hyv-verify/SKILL.md

@@ -21,4 +21,4 @@ hyv verify original.md candidate.md profile.json [writing-brief.json]
 
 ## Handoff
 
-Run `hyv verify` directly to execute the operation. Follow-on agents: hyv-lifecycle.
+Run `hyv verify` directly to execute the operation. If the candidate must satisfy the strict AI-pattern and voice-match policy, run hyv-strict-check before any lifecycle handoff. A passing verify report does not substitute for strict-ready. Follow-on agents: hyv-strict-check, hyv-lifecycle.

package/skills/hyv-verify/agent.json

@@ -44,6 +44,7 @@
     ]
   },
   "handoff_to": [
+    "hyv-strict-check",
     "hyv-lifecycle"
   ]
 }