cli-enforcement 0.1.0__py3-none-any.whl

cli_enforcement/__init__.py

@@ -0,0 +1,10 @@
+"""cli-enforcement: model-agnostic hook-level enforcement for AI coding agents.
+
+The enforcement *engine* (state manager, points/tiers, the hook scripts) is
+platform-neutral. WHERE and HOW it deploys onto a given model — config dir, hook
+event names, instructions file — is supplied dynamically by cli-wikia. So one
+engine deploys onto Claude, Gemini, Copilot, DeepSeek, Antigravity, … with no
+per-platform template.
+"""
+
+__version__ = "0.1.0"

cli_enforcement/cli.py

@@ -0,0 +1,58 @@
+"""cli-enforcement command. Deploy the enforcement engine onto any model."""
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+from . import deploy as D
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="cli-enforcement",
+        description="Model-agnostic hook-level enforcement for AI coding agents "
+        "(deploys onto any model via cli-wikia).",
+    )
+    p.add_argument("--version", action="version", version=f"cli-enforcement {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("deploy", help="deploy the enforcement engine for a model (dry-run unless --write)")
+    s.add_argument("model", help="target model (claude, gemini, copilot, deepseek, …)")
+    s.add_argument("--dir", help="project directory to deploy into (default: current dir)")
+    s.add_argument("--write", action="store_true", help="actually write files (default: dry-run)")
+    s.set_defaults(func=D.cmd_deploy)
+
+    s = sub.add_parser("sync", help="re-apply a model after a wikia update (gates/wiring change, points engine stays constant)")
+    s.add_argument("model")
+    s.add_argument("--dir")
+    s.add_argument("--write", action="store_true", help="apply the changes")
+    s.set_defaults(func=D.cmd_sync)
+
+    s = sub.add_parser("status", help="show which models have the engine deployed here")
+    s.add_argument("--dir")
+    s.set_defaults(func=D.cmd_status)
+
+    from . import fleet as F
+
+    s = sub.add_parser("fleet", help="wire enforcement into a fleetcode config + make it hardware-aware")
+    s.add_argument("config", help="path to a fleetcode config.json")
+    s.add_argument("--per-team-points", action="store_true", help="isolate points per team (default: shared 'we' pool)")
+    s.add_argument("--write", action="store_true", help="write config + deploy into existing team dirs")
+    s.set_defaults(func=F.cmd_fleet)
+
+    s = sub.add_parser("remove", help="remove the deployed engine (dry-run unless --write)")
+    s.add_argument("model")
+    s.add_argument("--dir")
+    s.add_argument("--write", action="store_true")
+    s.set_defaults(func=D.cmd_remove)
+
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

cli_enforcement/deploy.py

@@ -0,0 +1,393 @@
+"""The dynamic deployer.
+
+It does NOT hardcode per-platform templates. It carries one platform-neutral
+enforcement wiring (STAGES — which engine script runs at which lifecycle stage,
+taken verbatim from the canonical Claude template) and, for whatever model you
+target, asks cli-wikia for that model's real facts:
+
+  - config_root      e.g. .claude / .gemini / .github   (where files go)
+  - hook_events      e.g. PreToolUse / BeforeTool / …    (the real event names)
+  - instruction_file e.g. CLAUDE.md / GEMINI.md / AGENTS.md
+
+then maps each enforcement STAGE to the matching real event name and writes the
+hook registry + copies the engine in. Dry-run by default.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+from importlib import resources
+
+# Canonical enforcement wiring: stage -> engine scripts. Lifted directly from the
+# real Claude template's settings.json (the proven mapping), expressed as
+# platform-neutral STAGES instead of one platform's event names.
+# (stage, canonical_event, scripts). canonical_event is the exact Claude event
+# name; for other platforms it's matched semantically via STAGE_PATTERNS.
+STAGES = [
+    ("session_start", "SessionStart", ["session_init.py"]),
+    ("user_prompt", "UserPromptSubmit", ["flush_reads.py", "enforcement_unlock.py", "check_dismissal.py"]),
+    ("pre_tool", "PreToolUse", ["enforce_check.py", "bash_gate.py"]),
+    ("post_tool", "PostToolUse", ["record_read.py", "record_edit.py", "post_bash_check.py"]),
+    ("tool_failure", "PostToolUseFailure", ["tool_failure.py"]),
+    ("stop", "Stop", ["stop_check.py"]),
+    ("session_end", "SessionEnd", ["session_end.py"]),
+    ("permission", "PermissionRequest", ["permission_check.py"]),
+    ("subagent_start", "SubagentStart", ["subagent_start.py"]),
+    ("subagent_stop", "SubagentStop", ["subagent_stop.py"]),
+    ("pre_compact", "PreCompact", ["pre_compact.py"]),
+    ("post_compact", "PostCompact", ["post_compact.py"]),
+    ("instructions_loaded", "InstructionsLoaded", ["instructions_loaded.py"]),
+    ("config_change", "ConfigChange", ["config_change.py"]),
+    ("stop_failure", "StopFailure", ["stop_failure.py"]),
+    ("task_completed", "TaskCompleted", ["task_completed.py"]),
+]
+
+# How to recognize each stage among a platform's real event names (case-insensitive).
+STAGE_PATTERNS = {
+    "session_start": r"session.*start|^start",
+    "user_prompt": r"prompt|before.*agent|user.*submit",
+    "pre_tool": r"(pre|before).?tool(?!.*select)",
+    "post_tool": r"(post|after).?tool",
+    "tool_failure": r"tool.*fail",
+    "stop": r"^stop$|after.*agent|turn.*end",
+    "session_end": r"session.*end",
+    "permission": r"permission",
+    "subagent_start": r"subagent.*start",
+    "subagent_stop": r"subagent.*stop",
+    "pre_compact": r"(pre).?(compact|compress)",
+    "post_compact": r"(post).?(compact|compress)",
+    "instructions_loaded": r"instruction",
+    "config_change": r"config.*change",
+    "stop_failure": r"stop.*fail",
+    "task_completed": r"task.*complet",
+}
+
+
+def _wikia():
+    """cli-wikia is the knowledge layer; import lazily so errors are clear."""
+    try:
+        from cli_wikia import hooks as H
+
+        return H
+    except ImportError:
+        sys.exit("cli-enforcement needs cli-wikia installed (pip install cli-wikia).")
+
+
+def engine_files():
+    """The vendored, platform-neutral engine scripts shipped in this package."""
+    root = resources.files("cli_enforcement") / "engine"
+    return [p for p in root.iterdir() if p.name.endswith(".py") and p.name != "__init__.py"]
+
+
+def points_config_text():
+    """The CONSTANT points engine config (same for every model)."""
+    return (resources.files("cli_enforcement") / "engine" / "points_config.yaml").read_text(
+        encoding="utf-8"
+    )
+
+
+def build_kb_gate_components(model, topics, root):
+    """The DYNAMIC application: turn the model's cli-wikia topics into KB-gate
+    components. Each topic the AI must understand (by reading the wikia page)
+    before editing this model's config. New wikia pages -> new gates, so the
+    enforcement application tracks the model's features automatically.
+
+    The points ENGINE is unchanged; only this mapping changes per model."""
+    comps = []
+    for t in topics:
+        cid = "kb_" + re.sub(r"[^a-z0-9]+", "_", t.lower()).strip("_")
+        comps.append({
+            "id": cid,
+            "topic": t,
+            "display_name": f"{model}: {t}",
+            "understanding": f"wikia read {model} {t}",
+        })
+    return comps
+
+
+def render_project_config(model, root, comps):
+    """Render project_config.yaml text (KB gates from wikia). Hand-rendered to
+    keep cli-enforcement dependency-light; matches the engine's expected schema."""
+    lines = [
+        f"# GENERATED by cli-enforcement from cli-wikia's knowledge of '{model}'.",
+        "# The points ENGINE (points_config.yaml) is constant; these KB-gate",
+        "# components are the per-model APPLICATION and are re-derived on `sync`.",
+        "project:",
+        f'  name: "{model} (enforced)"',
+        '  subdirectory: ""',
+        f'  description: "Enforcement applied to {model}; gates derived from cli-wikia."',
+        "",
+        "# KB gates: the AI must read each wikia page (understanding) before it may",
+        f"# edit files under {root}/ that rely on that {model} feature.",
+        "components:",
+    ]
+    for c in comps:
+        lines += [
+            f'  - id: {c["id"]}',
+            f'    file_pattern: "{root}/**"',
+            f'    display_name: "{c["display_name"]}"',
+            f'    description: "Read & understand: {c["understanding"]}"',
+        ]
+    lines.append("")
+    return "\n".join(lines)
+
+
+def map_stages_to_events(events):
+    """Match each enforcement stage to one of the platform's real event names.
+    Prefers the exact canonical event when the platform has it (so Claude stays
+    verbatim), falling back to semantic matching otherwise (Gemini, etc.).
+    Returns {stage: event_name} and the list of stages with no matching event."""
+    eset = set(events)
+    mapping, unmatched = {}, []
+    for stage, canonical, _scripts in STAGES:
+        if canonical in eset:
+            mapping[stage] = canonical
+            continue
+        pat = re.compile(STAGE_PATTERNS[stage], re.I)
+        hit = next((e for e in events if pat.search(e)), None)
+        if hit:
+            mapping[stage] = hit
+        else:
+            unmatched.append(stage)
+    return mapping, unmatched
+
+
+def build_registry(model, root, events):
+    """Build the platform's settings.json `hooks` block by wiring each matched
+    stage's engine scripts to that platform's real event name."""
+    mapping, unmatched = map_stages_to_events(events)
+    scripts_by_stage = {stage: scr for stage, _canon, scr in STAGES}
+    # Claude hooks resolve via $CLAUDE_PROJECT_DIR; other tools run hooks from the
+    # project root, so a path relative to it works and the engine resolves the
+    # rest from cwd / $ENFORCEMENT_PROJECT_DIR.
+    prefix = "$CLAUDE_PROJECT_DIR/" if model == "claude" else ""
+    hooks = {}
+    for stage, event in mapping.items():
+        handlers = [
+            {"type": "command", "command": f'python3 "{prefix}{root}/mcp/{s}"'}
+            for s in scripts_by_stage[stage]
+        ]
+        hooks.setdefault(event, []).append({"hooks": handlers})
+    return hooks, mapping, unmatched
+
+
+def merge_hooks(existing, new):
+    """Merge enforcement hooks into existing per-event arrays WITHOUT clobbering
+    other tools' hooks (e.g. fleetcode's mailbox hook on UserPromptSubmit).
+    Appends new handler groups; skips any whose command is already present so
+    re-deploys are idempotent."""
+    out = {k: list(v) for k, v in existing.items()}
+    for event, groups in new.items():
+        cur = out.setdefault(event, [])
+        present = {h.get("command") for g in cur for h in g.get("hooks", [])}
+        for g in groups:
+            if {h.get("command") for h in g.get("hooks", [])} & present:
+                continue
+            cur.append(g)
+    return out
+
+
+def _script_summary(name):
+    """First meaningful docstring line of an engine script (its purpose)."""
+    try:
+        text = (resources.files("cli_enforcement") / "engine" / name).read_text(encoding="utf-8")
+        m = re.search(r'"""(.*?)"""', text, re.S)
+        if m:
+            for line in m.group(1).strip().splitlines():
+                if line.strip():
+                    return line.strip()
+    except OSError:
+        pass
+    return ""
+
+
+def render_hooks_doc(model, root, mapping):
+    """Document every enforcement hook active for this model."""
+    lines = [
+        f"# Enforcement Hooks — {model}",
+        "",
+        "Each hook fires automatically at a lifecycle event, **outside the model's",
+        "control**, and runs the listed engine scripts. This is generated from the",
+        "deployed wiring; events come from cli-wikia's knowledge of this model.",
+        "",
+        "| Stage | Event (this model) | Scripts | What it enforces |",
+        "|-------|--------------------|---------|------------------|",
+    ]
+    for stage, _canon, scripts in STAGES:
+        event = mapping.get(stage, "— _(not exposed by this model)_")
+        purpose = "; ".join(s for s in (_script_summary(x) for x in scripts) if s)[:140]
+        lines.append(f"| `{stage}` | `{event}` | {', '.join(scripts)} | {purpose} |")
+    lines += ["", "> Wiring is re-derived on `cli-enforcement sync` when the model changes."]
+    return "\n".join(lines) + "\n"
+
+
+def render_points_doc(root):
+    """User-editable scoring reference — shows the values and where to edit them."""
+    cfg = points_config_text()
+    return (
+        f"# What's Worth Points — {root}\n\n"
+        "This is the **scoring** the enforcement engine uses. To change what any\n"
+        f"action is worth, **edit `{root}/config/points_config.yaml`** (the source of\n"
+        "truth below). The engine reads it live; no code changes needed.\n\n"
+        "Principle: earn points for reading-before-editing, clean edits, and using the\n"
+        "cheapest model; lose them for hallucination, skipping docs, or bypassing gates.\n"
+        "Drop below the edit threshold and editing is blocked until you earn it back.\n\n"
+        "```yaml\n" + cfg + "```\n\n"
+        "> The scoring is **constant across every model** — only *how* it's applied\n"
+        "> (which gates/hooks) changes per model. Messages on every gain/loss are\n"
+        '> framed as "we" so mistakes are shared problems to solve, never blame.\n'
+    )
+
+
+def cmd_deploy(args):
+    H = _wikia()
+    model = args.model
+    target = os.path.abspath(args.dir or ".")
+    root = H.config_root(model)
+    events = H.hook_events(model)
+    instr = H.instruction_file(model)
+    if not root:
+        sys.exit(f"cli-wikia couldn't determine a config dir for '{model}'. "
+                 f"(Is it a known model? try: wikia models)")
+    if not events:
+        print(f"⚠ cli-wikia lists no hook events for '{model}' — wiring may be partial.")
+
+    import cli_wikia.cli as W
+
+    topics = W.topics(model)
+    comps = build_kb_gate_components(model, topics, root)
+
+    hooks, mapping, unmatched = build_registry(model, root, events)
+    settings_path = os.path.join(target, root, "settings.json")
+    engine_dst = os.path.join(target, root, "mcp")
+    config_dst = os.path.join(target, root, "config")
+    files = engine_files()
+
+    print(f"model:        {model}")
+    print(f"config root:  {root}/   (from cli-wikia)")
+    print(f"instructions: {instr}")
+    print(f"engine:       {len(files)} scripts -> {root}/mcp/  (constant)")
+    print(f"points engine: {root}/config/points_config.yaml  (CONSTANT — same for every model)")
+    print(f"KB gates:     {len(comps)} -> {root}/config/project_config.yaml  (DYNAMIC — from cli-wikia topics)")
+    print(f"wired {len(mapping)}/{len(STAGES)} enforcement stages to real events:")
+    for stage, event in mapping.items():
+        print(f"    {stage:18} -> {event}")
+    if unmatched:
+        print(f"  no matching event for: {', '.join(unmatched)}"
+              f"  (this platform doesn't expose those lifecycle points)")
+
+    if not args.write:
+        print("\n[dry-run] nothing written. Re-run with --write to deploy.")
+        print(f"--- {len(comps)} KB-gate components (first 6) ---")
+        for c in comps[:6]:
+            print(f"    {c['id']:22} <- read: {c['understanding']}")
+        return
+
+    os.makedirs(engine_dst, exist_ok=True)
+    for f in files:
+        with open(os.path.join(engine_dst, f.name), "w", encoding="utf-8") as out:
+            out.write(f.read_text(encoding="utf-8"))
+    os.makedirs(config_dst, exist_ok=True)
+    with open(os.path.join(config_dst, "points_config.yaml"), "w", encoding="utf-8") as fh:
+        fh.write(points_config_text())  # constant engine
+    with open(os.path.join(config_dst, "project_config.yaml"), "w", encoding="utf-8") as fh:
+        fh.write(render_project_config(model, root, comps))  # dynamic application
+    docs_dst = os.path.join(target, root, "docs")
+    os.makedirs(docs_dst, exist_ok=True)
+    with open(os.path.join(docs_dst, "HOOKS.md"), "w", encoding="utf-8") as fh:
+        fh.write(render_hooks_doc(model, root, mapping))  # all-hooks document
+    with open(os.path.join(docs_dst, "POINTS.md"), "w", encoding="utf-8") as fh:
+        fh.write(render_points_doc(root))  # editable scoring reference
+    current = {}
+    if os.path.exists(settings_path):
+        with open(settings_path, encoding="utf-8") as fh:
+            current = json.load(fh)
+    # MERGE (don't overwrite) — preserves fleetcode's mailbox hook etc.
+    current["hooks"] = merge_hooks(current.get("hooks", {}), hooks)
+    os.makedirs(os.path.dirname(settings_path), exist_ok=True)
+    with open(settings_path, "w", encoding="utf-8") as fh:
+        json.dump(current, fh, indent=2)
+    print(f"\n✓ deployed enforcement for {model} into {target}/{root}/")
+    print(f"  {len(files)} engine scripts + constant points engine + "
+          f"{len(comps)} wikia-derived KB gates + {len(mapping)} wired events.")
+
+
+def cmd_sync(args):
+    """Re-derive the per-model APPLICATION from current cli-wikia and show what
+    changed (KB gates / hook wiring) because the model's features changed. The
+    points ENGINE (points_config.yaml) is never touched."""
+    H = _wikia()
+    import cli_wikia.cli as W
+
+    model = args.model
+    target = os.path.abspath(args.dir or ".")
+    root = H.config_root(model)
+    if not root:
+        sys.exit(f"unknown model '{model}'.")
+    pc = os.path.join(target, root, "config", "project_config.yaml")
+    if not os.path.exists(pc):
+        sys.exit(f"{model} isn't deployed in {target} — run `cli-enforcement deploy {model}` first.")
+
+    deployed_ids = set(re.findall(r"^\s*- id:\s*(\S+)", open(pc, encoding="utf-8").read(), re.M))
+    topics = W.topics(model)
+    comps = build_kb_gate_components(model, topics, root)
+    new_ids = {c["id"] for c in comps}
+    added = sorted(new_ids - deployed_ids)
+    removed = sorted(deployed_ids - new_ids)
+
+    print(f"{model}: {len(new_ids)} KB gates from current wikia (was {len(deployed_ids)} deployed)")
+    for a in added:
+        print(f"  + {a}   (model gained this — new gate)")
+    for r in removed:
+        print(f"  - {r}   (no longer in wikia — gate dropped)")
+    if not added and not removed:
+        print("  in sync — nothing changed.")
+        return
+    if not args.write:
+        print("\n[dry-run] points engine stays constant; only the application changes. "
+              "Re-run with --write to apply.")
+        return
+    events = H.hook_events(model)
+    hooks, _, _ = build_registry(model, root, events)
+    with open(pc, "w", encoding="utf-8") as fh:
+        fh.write(render_project_config(model, root, comps))
+    settings_path = os.path.join(target, root, "settings.json")
+    current = {}
+    if os.path.exists(settings_path):
+        with open(settings_path, encoding="utf-8") as fh:
+            current = json.load(fh)
+    current.setdefault("hooks", {}).update(hooks)
+    with open(settings_path, "w", encoding="utf-8") as fh:
+        json.dump(current, fh, indent=2)
+    print(f"\n✓ re-applied {model}: {len(new_ids)} gates, {len(hooks)} wired events. "
+          f"points_config.yaml untouched.")
+
+
+def cmd_status(args):
+    H = _wikia()
+    target = os.path.abspath(args.dir or ".")
+    for model in (__import__("cli_wikia").MODELS):
+        root = H.config_root(model)
+        if not root:
+            continue
+        deployed = os.path.isdir(os.path.join(target, root, "mcp"))
+        print(f"{model:12} root={root:16} deployed_here={'yes' if deployed else 'no'}")
+
+
+def cmd_remove(args):
+    H = _wikia()
+    model = args.model
+    target = os.path.abspath(args.dir or ".")
+    root = H.config_root(model)
+    mcp = os.path.join(target, root, "mcp") if root else None
+    if not mcp or not os.path.isdir(mcp):
+        print(f"{model}: no enforcement engine found in {target}")
+        return
+    if not args.write:
+        print(f"[dry-run] would remove {mcp} (re-run with --write)")
+        return
+    shutil.rmtree(mcp)
+    print(f"removed enforcement engine from {mcp} (settings.json left intact)")

cli_enforcement/engine/achievements.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Achievement System - Milestone & Progression Tracking
+====================================================
+
+Tracks unlocked achievements, milestones, and progression metrics.
+Integrates with state_manager to award bonuses for achievements.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+ACHIEVEMENT_DEFS = {
+    "first_clean_edit": {
+        "name": "First Clean Edit",
+        "description": "Your first edit with no violations",
+        "icon": "🎯",
+        "bonus_points": 10,
+    },
+    "five_edit_streak": {
+        "name": "5-Edit Streak",
+        "description": "5 consecutive clean edits",
+        "icon": "🔥",
+        "bonus_points": 25,
+    },
+    "ten_edit_streak": {
+        "name": "10-Edit Streak",
+        "description": "10 consecutive clean edits",
+        "icon": "👑",
+        "bonus_points": 50,
+    },
+    "perfect_session": {
+        "name": "Perfect Session",
+        "description": "Complete session with zero violations",
+        "icon": "⭐",
+        "bonus_points": 100,
+    },
+    "fifty_edits": {
+        "name": "50 Edits",
+        "description": "Completed 50 edits (milestone)",
+        "icon": "💎",
+        "bonus_points": 75,
+    },
+    "hundred_edits": {
+        "name": "100 Edits",
+        "description": "Completed 100 edits (mastery)",
+        "icon": "👑",
+        "bonus_points": 150,
+    },
+    "thousand_points": {
+        "name": "1000 Points",
+        "description": "Earned 1000 total points",
+        "icon": "🏆",
+        "bonus_points": 0,  # Meta-achievement
+    },
+    "clean_recovery": {
+        "name": "Clean Recovery",
+        "description": "Recovered from negative points to 500+",
+        "icon": "💪",
+        "bonus_points": 100,
+    },
+}
+
+
+class AchievementTracker:
+    """Track and manage achievements."""
+    
+    def __init__(self, claude_dir: Path):
+        """Initialize achievement tracker."""
+        self.claude_dir = Path(claude_dir)
+        self.achievements_file = self.claude_dir / ".achievements.json"
+        self.achievements = self._load_achievements()
+    
+    def _load_achievements(self) -> Dict[str, Any]:
+        """Load achievements from file."""
+        if self.achievements_file.exists():
+            try:
+                return json.loads(self.achievements_file.read_text())
+            except (json.JSONDecodeError, IOError):
+                pass
+        return {"unlocked": [], "history": []}
+    
+    def _save_achievements(self):
+        """Save achievements to file."""
+        self.achievements_file.write_text(json.dumps(self.achievements, indent=2))
+    
+    def unlock(self, achievement_id: str) -> bool:
+        """
+        Unlock an achievement.
+        Returns True if newly unlocked, False if already unlocked.
+        """
+        if achievement_id in self.achievements["unlocked"]:
+            return False  # Already unlocked
+        
+        if achievement_id not in ACHIEVEMENT_DEFS:
+            return False  # Invalid achievement
+        
+        # Unlock it
+        self.achievements["unlocked"].append(achievement_id)
+        self.achievements["history"].append({
+            "id": achievement_id,
+            "unlocked_at": datetime.now().isoformat(),
+        })
+        self._save_achievements()
+        
+        return True
+    
+    def check_unlock_triggers(self, stats: Dict[str, Any]) -> List[str]:
+        """
+        Check what achievements should be unlocked based on current stats.
+        Returns list of newly unlocked achievement IDs.
+        """
+        unlocked = []
+        
+        # First clean edit
+        if "first_clean_edit" not in self.achievements["unlocked"]:
+            if stats.get("all_time_clean_edits", 0) >= 1:
+                if self.unlock("first_clean_edit"):
+                    unlocked.append("first_clean_edit")
+        
+        # Streak achievements
+        current_streak = stats.get("current_streak", 0)
+        if "five_edit_streak" not in self.achievements["unlocked"]:
+            if current_streak >= 5:
+                if self.unlock("five_edit_streak"):
+                    unlocked.append("five_edit_streak")
+        
+        if "ten_edit_streak" not in self.achievements["unlocked"]:
+            if current_streak >= 10:
+                if self.unlock("ten_edit_streak"):
+                    unlocked.append("ten_edit_streak")
+        
+        # Edit count milestones
+        total_edits = stats.get("all_time_clean_edits", 0)
+        if "fifty_edits" not in self.achievements["unlocked"]:
+            if total_edits >= 50:
+                if self.unlock("fifty_edits"):
+                    unlocked.append("fifty_edits")
+        
+        if "hundred_edits" not in self.achievements["unlocked"]:
+            if total_edits >= 100:
+                if self.unlock("hundred_edits"):
+                    unlocked.append("hundred_edits")
+        
+        # Perfect session (no violations this session)
+        if "perfect_session" not in self.achievements["unlocked"]:
+            if stats.get("session_violations", 0) == 0 and stats.get("clean_edits", 0) >= 3:
+                if self.unlock("perfect_session"):
+                    unlocked.append("perfect_session")
+        
+        # Points milestone
+        if "thousand_points" not in self.achievements["unlocked"]:
+            if stats.get("all_time_points", 0) >= 1000:
+                if self.unlock("thousand_points"):
+                    unlocked.append("thousand_points")
+        
+        # Clean recovery
+        if "clean_recovery" not in self.achievements["unlocked"]:
+            was_negative = stats.get("was_negative_last_session", False)
+            if was_negative and stats.get("current_points", 0) >= 500:
+                if self.unlock("clean_recovery"):
+                    unlocked.append("clean_recovery")
+        
+        return unlocked
+    
+    def get_achievement_bonus(self, achievement_id: str) -> int:
+        """Get bonus points for an achievement."""
+        return ACHIEVEMENT_DEFS.get(achievement_id, {}).get("bonus_points", 0)
+    
+    def get_achievement_message(self, achievement_id: str) -> str:
+        """Get announcement message for an achievement."""
+        if achievement_id not in ACHIEVEMENT_DEFS:
+            return ""
+        
+        ach = ACHIEVEMENT_DEFS[achievement_id]
+        icon = ach.get("icon", "🎯")
+        name = ach.get("name", "Unknown")
+        bonus = ach.get("bonus_points", 0)
+        
+        if bonus > 0:
+            return f"{icon} ACHIEVEMENT UNLOCKED: {name}! +{bonus} bonus points!"
+        else:
+            return f"{icon} ACHIEVEMENT UNLOCKED: {name}!"
+    
+    def is_unlocked(self, achievement_id: str) -> bool:
+        """Check if achievement is unlocked."""
+        return achievement_id in self.achievements.get("unlocked", [])
+    
+    def get_unlocked_count(self) -> int:
+        """Get count of unlocked achievements."""
+        return len(self.achievements.get("unlocked", []))
+    
+    def get_all_unlocked(self) -> List[str]:
+        """Get all unlocked achievement IDs."""
+        return self.achievements.get("unlocked", [])
+
+
+if __name__ == "__main__":
+    # Test
+    tracker = AchievementTracker(Path.cwd() / ".claude")
+    
+    # Simulate unlocking achievements
+    tracker.unlock("first_clean_edit")
+    tracker.unlock("five_edit_streak")
+    
+    print("Unlocked:", tracker.get_all_unlocked())
+    print("Count:", tracker.get_unlocked_count())
+    print("Bonus for first_clean_edit:", tracker.get_achievement_bonus("first_clean_edit"))
+    print("Message:", tracker.get_achievement_message("five_edit_streak"))