@holdyourvoice/hyv 2.0.1 → 2.1.1

package/scripts/hold_voice_sync.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+#!/usr/bin/env python3
+"""Push voice profile, meta, and voice.md to Cloudflare R2 for backup.
+
+Cost design: R2 has no egress fees. This script uses S3-compatible PUT only
+(no Workers, no compute). Typical payload: 5-20KB. At $0.015/GB stored with
+1 sync/day, annual cost is essentially zero.
+
+Requires: pip install boto3
+
+Env vars (set once):
+  HYV_R2_ACCESS_KEY_ID
+  HYV_R2_SECRET_ACCESS_KEY
+  HYV_R2_ENDPOINT (e.g. https://<account>.r2.cloudflarestorage.com)
+  HYV_R2_BUCKET (e.g. hyv-voice-profiles)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def sync_profile(
+    profile_path: Path,
+    meta_path: Path | None = None,
+    voice_md_path: Path | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """push files to R2. returns summary dict."""
+    try:
+        import boto3
+    except ImportError:
+        return {"synced": False, "error": "boto3 not installed. pip install boto3"}
+
+    required = ["HYV_R2_ACCESS_KEY_ID", "HYV_R2_SECRET_ACCESS_KEY", "HYV_R2_ENDPOINT", "HYV_R2_BUCKET"]
+    missing = [v for v in required if not os.environ.get(v)]
+    if missing:
+        return {"synced": False, "error": f"missing env vars: {', '.join(missing)}"}
+
+    if not profile_path.exists():
+        return {"synced": False, "error": f"profile not found: {profile_path}"}
+
+    s3 = boto3.client(
+        "s3",
+        endpoint_url=os.environ["HYV_R2_ENDPOINT"],
+        aws_access_key_id=os.environ["HYV_R2_ACCESS_KEY_ID"],
+        aws_secret_access_key=os.environ["HYV_R2_SECRET_ACCESS_KEY"],
+        region_name="auto",
+    )
+    bucket = os.environ["HYV_R2_BUCKET"]
+    profile_name = profile_path.stem  # e.g. "voice-profile"
+
+    files_to_sync: list[tuple[Path, str]] = [
+        (profile_path, f"{profile_name}/{profile_path.name}"),
+    ]
+    if meta_path and meta_path.exists():
+        files_to_sync.append((meta_path, f"{profile_name}/{meta_path.name}"))
+    if voice_md_path and voice_md_path.exists():
+        files_to_sync.append((voice_md_path, f"{profile_name}/{voice_md_path.name}"))
+
+    total_size = sum(f.stat().st_size for f, _ in files_to_sync if f.exists())
+    if total_size > 1_000_000:  # 1MB safety cap
+        return {"synced": False, "error": f"payload too large: {total_size} bytes"}
+
+    if dry_run:
+        return {"synced": False, "dry_run": True, "would_sync": [k for _, k in files_to_sync], "size": total_size}
+
+    sync_time = _now_iso()
+    uploaded = []
+    for local_path, remote_key in files_to_sync:
+        if not local_path.exists():
+            continue
+        s3.upload_file(
+            str(local_path),
+            bucket,
+            remote_key,
+            ExtraArgs={"ContentType": "application/json" if local_path.suffix == ".json" else "text/markdown"},
+        )
+        uploaded.append(remote_key)
+
+    return {"synced": True, "uploaded": uploaded, "size": total_size, "time": sync_time}
+
+
+def was_synced_recently(meta: dict[str, Any], max_hours: int = 24) -> bool:
+    """check if a sync happened within max_hours."""
+    last = meta.get("last_sync")
+    if not last:
+        return False
+    try:
+        last_dt = datetime.fromisoformat(last)
+        hours_since = (datetime.now(timezone.utc) - last_dt.replace(tzinfo=timezone.utc)).total_seconds() / 3600
+        return hours_since < max_hours
+    except (ValueError, TypeError):
+        return False
+
+
+def try_auto_sync(
+    profile_path: str,
+    meta_path: str | None = None,
+    voice_md_path: str | None = None,
+) -> bool:
+    """called by profile-evolve after saving. syncs if env is configured and
+    last sync was > 24h ago. returns True if sync happened."""
+    p = Path(profile_path).expanduser()
+    if not p.exists():
+        return False
+
+    m = Path(meta_path).expanduser() if meta_path else p.with_suffix(".meta.json")
+    meta: dict[str, Any] = {}
+    if m.exists():
+        try:
+            meta = json.loads(m.read_text(encoding="utf-8", errors="ignore"))
+        except (json.JSONDecodeError, OSError):
+            meta = {}
+
+    if was_synced_recently(meta, max_hours=23):
+        return False
+
+    vm = Path(voice_md_path).expanduser() if voice_md_path else p.with_suffix(".voice.md")
+    result = sync_profile(p, meta_path=m, voice_md_path=vm)
+
+    if result.get("synced"):
+        meta["last_sync"] = result.get("time", _now_iso())
+        m.parent.mkdir(parents=True, exist_ok=True)
+        m.write_text(json.dumps(meta, indent=2, ensure_ascii=False), encoding="utf-8")
+        return True
+    return False
+
+
+def main() -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Sync voice profile to Cloudflare R2")
+    parser.add_argument("--profile", required=True, help="voice profile JSON file")
+    parser.add_argument("--meta", help="meta JSON file (default: profile path with .meta.json)")
+    parser.add_argument("--voice-md", help="voice.md file (default: profile path with .voice.md)")
+    parser.add_argument("--dry-run", action="store_true", help="print what would be synced without uploading")
+    parser.add_argument("--force", action="store_true", help="sync even if recently synced")
+    args = parser.parse_args()
+
+    profile_path = Path(args.profile).expanduser()
+    meta_path = Path(args.meta).expanduser() if args.meta else profile_path.with_suffix(".meta.json")
+    voice_md_path = Path(args.voice_md).expanduser() if args.voice_md else profile_path.with_suffix(".voice.md")
+
+    if not args.force:
+        meta: dict[str, Any] = {}
+        if meta_path.exists():
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8", errors="ignore"))
+            except (json.JSONDecodeError, OSError):
+                pass
+        if was_synced_recently(meta):
+            print("sync skipped — already synced within 24h (use --force to override)")
+            return 0
+
+    result = sync_profile(profile_path, meta_path=meta_path, voice_md_path=voice_md_path, dry_run=args.dry_run)
+
+    if args.dry_run:
+        print(json.dumps(result, indent=2))
+        return 0
+
+    if result.get("synced"):
+        meta: dict[str, Any] = {}
+        if meta_path.exists():
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8", errors="ignore"))
+            except (json.JSONDecodeError, OSError):
+                meta = {}
+        meta["last_sync"] = result.get("time", _now_iso())
+        meta_path.parent.mkdir(parents=True, exist_ok=True)
+        meta_path.write_text(json.dumps(meta, indent=2, ensure_ascii=False), encoding="utf-8")
+
+        print(f"synced {len(result.get('uploaded', []))} files ({result.get('size', 0)} bytes)")
+        for f in result.get("uploaded", []):
+            print(f"  {f}")
+        return 0
+
+    print(f"sync failed: {result.get('error', 'unknown')}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ai-writing-eliminator/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ai-writing-eliminator
+description: Use when the user wants to remove AI writing patterns, humanize a draft, make prose less generic, scan for AI cadence, or rewrite only the lines that sound synthetic.
+---
+
+# AI Writing Eliminator (v2)
+
+This skill removes machine-shaped writing without destroying the draft. The
+algorithm now detects 220+ named AI writing patterns across 31 composite regex
+rules, plus 9 structural/rhythmic signals (burstiness, paragraph uniformity,
+contraction density, formal hedging, intensifier overuse, fragment ratio,
+staccato detection, over-structured lists, uniform sentence rhythm).
+
+## Non-Negotiables
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+Use the helper script when a draft is in a file:
+
+```bash
+hyv scan <draft path>
+```
+
+For pasted text, apply the same rules manually from
+`assets/ai-eliminator-rules.md`.
+
+## Repair Prompt
+
+When a model rewrite is needed, generate a line-level prompt:
+
+```bash
+hyv rewrite-prompt \
+  --profile .hold-your-voice/voice-profile.json \
+  <draft path>
+```
+
+If there is no profile, still repair the AI patterns, but do not claim the
+result is voice-matched.
+
+## Bad Fixes
+
+Reject fixes that:
+
+- turn the draft into a tidy founder post
+- make every paragraph land as a lesson
+- replace a concrete scene with an abstract principle
+- use dramatic line breaks to fake rhythm
+- make the writer sound more professional but less specific
+

package/skills/hold-your-voice/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: hyv-hold-your-voice
+description: "Use when the user wants Hold Your Voice-style writing help across any project: build a voice profile from samples, match a writer's voice, remove AI-writing drift, rewrite drafts without flattening voice, or preserve project-specific writing style."
+---
+
+# Hold Your Voice
+
+This is the orchestration skill. Use the narrower `voice-matcher` and
+`ai-writing-eliminator` skills when a task is only one half of the workflow.
+
+## Core Doctrine
+
+- Hold Your Voice is not a generic AI humanizer. It is a voice-preservation
+  layer around the writing.
+- The benchmark is the writer's own samples, not a universal "good writing"
+  style guide.
+- Trust samples over stated preferences when they disagree.
+- Rewrite only the lines that fail the voice or AI-pattern check.
+- Preserve surrounding text unless the user explicitly asks for a full rewrite.
+- Rough private-note texture beats polished founder cadence.
+
+## Workflow
+
+1. Identify the target writer and output format.
+2. Find or ask for source samples. Prefer real writing from the current project:
+   posts, emails, essays, docs, landing copy, changelog notes, founder notes.
+3. Build a profile when no current profile exists:
+
+   ```bash
+   hyv profile \
+     --name "project voice" \
+     --out .hold-your-voice/voice-profile.json \
+     <sample paths>
+   ```
+
+4. Scan the draft:
+
+   ```bash
+   hyv scan \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+   Passing `--meta` skips patterns the system has learned are not applicable.
+
+5. Rewrite by line, not by vibe:
+
+   ```bash
+   hyv rewrite-prompt \
+     --profile .hold-your-voice/voice-profile.json \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+6. Verify by rescanning the revised draft.
+
+## Output Standard
+
+When returning prose to the user, lead with the finished writing. Keep process
+notes short. If you changed only flagged lines, say that plainly.
+
+For project work, store generated profiles under:
+
+```text
+.hold-your-voice/voice-profile.json
+```
+
+Do not store private samples inside the plugin folder. Keep project-specific
+profiles inside the project that owns the writing.
+
+## Auto-Improvement (default)
+
+The profile **evolves automatically** after every accepted writing session. No
+manual reinforce or update commands needed.
+
+### How it works
+
+After the user accepts a revision, run **one command**:
+
+```bash
+hyv profile-evolve \
+  --original <original draft file> \
+  --accepted <accepted/output draft file> \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--new-samples <paths>` to merge new writing samples in the same step.
+Optional: `--meta <path>` if you need a custom meta file location (defaults to
+`voice-profile.meta.json` alongside the profile).
+
+This does three things simultaneously:
+
+1. **Signal extraction** — diffs original vs accepted to find which AI patterns
+   the user agreed with (`patterns_accepted`) vs overrode (`patterns_overridden`).
+2. **Temporal meta update** — each pattern now tracks `first_seen`,
+   `last_confirmed`, `contradictions`, `confidence` (0.0–1.0), and status
+   (`active` / `declining` / `stale`). Accepted signals boost confidence.
+   Overrides penalize it. Untouched patterns slowly decay.
+3. **Profile stat merge** — sentence length, paragraph shape, and opening moves
+   use weighted rolling averages so the voice benchmark improves with every
+   session.
+
+### Pattern lifecycle
+
+- **Active** — confidence ≥ 0.30, last confirmed within 14 days. These
+  patterns fire during scans.
+- **Declining** — 3+ contradictions and confidence < 0.30. Still tracked
+  but no longer flagged in scan output.
+- **Stale** — 5+ contradictions and confidence < 0.15, or untouched for
+  > 14 days. Archived; does not fire.
+
+This means after a few days of usage:
+
+- Patterns the user consistently accepts (e.g., "inflated_verbs") become
+  high-confidence and reliably flag real AI drift.
+- Patterns the user consistently ignores (e.g., "the user's writing style
+  uses landscape-era phrasing intentionally") quietly fade out.
+- The profile's sentence/paragraph stats converge on the actual voice.
+
+### Check learning state
+
+```bash
+hyv profile-status \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--write-voice voice.md` produces the human-readable voice profile
+with confidence bars per pattern.
+
+### Auto-sync to cloud (daily)
+
+`profile-evolve` automatically tries to sync to Cloudflare R2 after each
+evolution. Sync only happens if:
+
+- The env vars `HYV_R2_ACCESS_KEY_ID`, `HYV_R2_SECRET_ACCESS_KEY`,
+  `HYV_R2_ENDPOINT`, `HYV_R2_BUCKET` are set.
+- The last sync was more than 23 hours ago (no wasteful pushes).
+- The payload is under 1MB (safety cap).
+
+To set up one-time:
+
+```bash
+export HYV_R2_ACCESS_KEY_ID="your-access-key"
+export HYV_R2_SECRET_ACCESS_KEY="your-secret-key"
+export HYV_R2_ENDPOINT="https://<account-id>.r2.cloudflarestorage.com"
+export HYV_R2_BUCKET="hyv-voice-profiles"
+pip install boto3  # only dependency
+```
+
+R2 has **zero egress fees**. With ~5-20KB profiles synced once daily, annual
+cost rounds to zero. No Cloudflare Workers, no compute — just S3 PUT.
+
+Manual sync (force override):
+
+```bash
+hyv-sync \
+  --profile .hold-your-voice/voice-profile.json \
+  --force
+```
+
+### Export and import
+
+```bash
+hyv profile-export \
+  --profile .hold-your-voice/voice-profile.json \
+  --out ~/my-voice.hyv
+
+hyv profile-import \
+  --profile .hold-your-voice/voice-profile.json \
+  --source ~/my-voice.hyv
+```
+
+The learning is entirely local — no API calls, no third-party services.
+

package/skills/voice-matcher/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: voice-matcher
+description: Use when the user wants to write from their own writing, build a voice profile from samples, match an existing writer's style, or make new copy sound like a project/person without copying generic style advice.
+---
+
+# Voice Matcher
+
+Build from the writer's own writing. Do not invent a voice from adjectives.
+
+## Source Hierarchy
+
+1. User-provided samples in the conversation.
+2. Project files the user identifies as their own writing.
+3. Obvious authored prose in the repo, such as essays, posts, emails, public
+   copy, changelog entries, or founder notes.
+4. `assets/economic-drift-voice.md` only when the user asks for Shashank's or
+   "my" voice and no better current samples exist.
+
+## Profile Build
+
+Run the portable profiler when files are available:
+
+```bash
+hyv profile \
+  --name "project voice" \
+  --out .hold-your-voice/voice-profile.json \
+  <sample paths>
+```
+
+The profile is a working benchmark, not a literary biography. It should capture:
+
+- sentence rhythm
+- paragraph shape
+- openings
+- argument pattern
+- recurring concrete textures
+- things the writer avoids
+- sample anchors that prove the profile
+
+## Writing Method
+
+- Start from the user's requested point, not from decorative tone imitation.
+- Use the profile as a constraint system.
+- Match cadence and thinking pattern before vocabulary.
+- Keep the writer's roughness when it is part of the voice.
+- Do not sand the draft into smooth, generic competence.
+- After drafting, run an AI-pattern scan and repair only weak lines.
+
+## Verification
+
+Before handing back final copy, ask:
+
+- Does the opening sound like a real observation rather than a template?
+- Could this line belong unchanged to five other people? If yes, rewrite it.
+- Are there profile anchors that justify this cadence?
+- Did the rewrite preserve the user's meaning and risk appetite?
+