@rm0nroe/coach-claw 1.0.6

package/coach/bin/user_config.py

@@ -0,0 +1,176 @@
+"""Read/write `~/.claude/coach/.user_config.json` — the operator-tunable
+settings the `/config` slash command edits.
+
+Schema (v1):
+    {
+      "schema_version": 1,
+      "statusline_variant": one of VALID_VARIANTS (see below),
+      "theme":             one of VALID_THEMES   (see below),
+      "elo_min":           int (default 1000, must be < elo_max),
+      "elo_max":           int (default 2800, must be > elo_min)
+    }
+
+The valid sets are defined as constants below — they are the single
+source of truth, consumed by `/config` validation and the statusline
+preview. Don't duplicate the lists into this docstring; they will rot.
+
+Missing file → defaults. Unknown keys → ignored. Invalid values →
+fall back to defaults for that field. Reads never raise.
+
+Writes are atomic (tempfile + os.replace) but NOT locked — `/config`
+is interactive + slow-path, no concurrency concern with `stats.py`
+which only reads.
+
+Path resolution: by default the file lives at
+`~/.claude/coach/.user_config.json`. Set `COACH_CONFIG_DIR=/some/dir` to
+override the directory (the file name `.user_config.json` is fixed).
+This is what lets `coach/bin/configure.py` invoked via `npx coach-claw
+config` honor a custom `CLAUDE_DIR` install — the npm wrapper exports
+`COACH_CONFIG_DIR` to match. Resolution happens at every read/write so
+tests can monkeypatch `COACH_CONFIG_DIR` via `monkeypatch.setenv`.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from coach_paths import resolve_coach_dir
+
+
+def _resolve_config_path() -> Path:
+    """Return the path to .user_config.json. Delegates to
+    `coach_paths.resolve_coach_dir()` so the COACH_CONFIG_DIR contract
+    is enforced in exactly one place. Resolved per-call so the env var
+    can be set at test time or by the npm wrapper before the Python
+    entry point reads it."""
+    return resolve_coach_dir() / ".user_config.json"
+
+
+def __getattr__(name):
+    """Module-level __getattr__ (PEP 562). Lets external code read
+    `user_config.CONFIG_PATH` and get a fresh, env-aware path. Internal
+    code should call `_resolve_config_path()` directly so behavior is
+    explicit at the call site."""
+    if name == "CONFIG_PATH":
+        return _resolve_config_path()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+DEFAULTS: dict = {
+    "schema_version": 1,
+    "statusline_variant": "crystal",
+    "theme": "craft",
+    "elo_min": 1000,
+    "elo_max": 2800,
+}
+
+VALID_VARIANTS = {"crystal", "pips", "slash", "forge"}
+VALID_THEMES = {
+    # abstract themes
+    "craft", "forge", "cosmic", "ocean",
+    # pop-culture-inspired (fan-themed; see themes.py docstring on brand safety)
+    "skyrim", "marvel", "dc", "finalfantasy",
+    "military", "lotr", "starwars", "hacker",
+}
+
+
+def load() -> dict:
+    """Return a complete config dict. Always populates every key — caller
+    can index without `.get()`."""
+    cfg = dict(DEFAULTS)
+    config_path = _resolve_config_path()
+    try:
+        if config_path.exists():
+            raw = json.loads(config_path.read_text())
+            if isinstance(raw, dict):
+                _coerce_into(cfg, raw)
+    except Exception:
+        pass
+    return cfg
+
+
+def _coerce_into(cfg: dict, raw: dict) -> None:
+    """Apply each valid field from `raw` into `cfg`. Invalid values stay
+    at their default — never raises."""
+    v = raw.get("statusline_variant")
+    if isinstance(v, str) and v in VALID_VARIANTS:
+        cfg["statusline_variant"] = v
+    t = raw.get("theme")
+    if isinstance(t, str) and t in VALID_THEMES:
+        cfg["theme"] = t
+    emin = raw.get("elo_min")
+    emax = raw.get("elo_max")
+    if isinstance(emin, int) and isinstance(emax, int) and 0 < emin < emax:
+        cfg["elo_min"] = emin
+        cfg["elo_max"] = emax
+
+
+def save(cfg: dict) -> None:
+    """Atomic write. Validates against schema before persisting; raises
+    ValueError on invalid input so `/config` can show a clear error."""
+    validated = dict(DEFAULTS)
+    _coerce_into(validated, cfg)
+    # If the caller passed an unknown variant/theme, _coerce_into silently
+    # kept the default. Detect that and complain so /config can surface
+    # which key was rejected.
+    for key in ("statusline_variant", "theme"):
+        if key in cfg and cfg[key] != validated[key]:
+            valid = (
+                VALID_VARIANTS if key == "statusline_variant" else VALID_THEMES
+            )
+            raise ValueError(
+                f"unknown {key} {cfg[key]!r}; valid: {sorted(valid)}"
+            )
+    if "elo_min" in cfg or "elo_max" in cfg:
+        emin = cfg.get("elo_min", validated["elo_min"])
+        emax = cfg.get("elo_max", validated["elo_max"])
+        if not (isinstance(emin, int) and isinstance(emax, int) and 0 < emin < emax):
+            raise ValueError(
+                f"elo_min ({emin}) must be a positive int less than "
+                f"elo_max ({emax})"
+            )
+
+    config_path = _resolve_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        prefix="." + config_path.name + ".",
+        suffix=".tmp",
+        dir=str(config_path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(json.dumps(validated, indent=2, sort_keys=True))
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, config_path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+        raise
+
+
+# --- Convenience accessors used by stats.py / variants render path ------
+
+def get_variant() -> str:
+    return load()["statusline_variant"]
+
+
+def get_theme() -> str:
+    return load()["theme"]
+
+
+def get_elo_range() -> tuple[int, int]:
+    cfg = load()
+    return cfg["elo_min"], cfg["elo_max"]
+
+
+def update(**kwargs) -> dict:
+    """Merge updates into the existing config and persist. Returns the
+    new config. Raises ValueError on invalid input."""
+    cfg = load()
+    cfg.update(kwargs)
+    save(cfg)
+    return cfg

package/coach/bin/xp_accounting.py

@@ -0,0 +1,98 @@
+"""Shared lifetime XP accounting for Coach profile data.
+
+The profile used to store all non-graduation lifetime XP in
+``banked_session_xp``. Newer code keeps the sources split so status output,
+exports, and future UI can explain where progress came from:
+
+  - session_banked_xp: completed-session XP converted at 10:1 by bank.py
+  - milestone_xp: mid-streak rewards from merge.py
+  - graduation_xp: derived from current graduated entries
+  - manual_adjustments: explicit operator edits
+
+``banked_session_xp`` remains as a deprecated alias for session banking only.
+"""
+from __future__ import annotations
+
+GRADUATION_XP = 5
+
+
+def _as_int(value, default: int = 0) -> int:
+    try:
+        return int(value or 0)
+    except Exception:
+        return default
+
+
+def graduation_xp(profile: dict) -> int:
+    graduated = [
+        g for g in (profile.get("graduated") or [])
+        if isinstance(g, dict)
+    ]
+    return len(graduated) * GRADUATION_XP
+
+
+def max_active_clean_streak(profile: dict) -> int:
+    max_streak = 0
+    for entry in profile.get("entries", []) or []:
+        if not isinstance(entry, dict):
+            continue
+        max_streak = max(max_streak, _as_int(entry.get("clean_streak_runs")))
+    return max_streak
+
+
+def normalize_profile_xp(profile: dict) -> dict:
+    """Ensure split XP fields exist and return an explainable breakdown.
+
+    Mutates ``profile`` in place. For legacy profiles with only
+    ``banked_session_xp``, that value is migrated into ``session_banked_xp``.
+    Historical milestone/session split cannot be recovered, so preserving the
+    total is the safe migration.
+    """
+    if not isinstance(profile, dict):
+        profile = {}
+
+    has_split = any(
+        key in profile
+        for key in ("session_banked_xp", "milestone_xp", "manual_adjustments")
+    )
+    legacy_banked = _as_int(profile.get("banked_session_xp"))
+
+    if has_split:
+        session_banked = _as_int(profile.get("session_banked_xp"))
+    else:
+        session_banked = legacy_banked
+
+    milestone = _as_int(profile.get("milestone_xp"))
+    manual = _as_int(profile.get("manual_adjustments"))
+    graduated = graduation_xp(profile)
+    clean_streak = max_active_clean_streak(profile)
+
+    profile["session_banked_xp"] = session_banked
+    profile["milestone_xp"] = milestone
+    profile["graduation_xp"] = graduated
+    profile["manual_adjustments"] = manual
+    # Deprecated compatibility alias. New code should read session_banked_xp.
+    profile["banked_session_xp"] = session_banked
+
+    lifetime = session_banked + milestone + graduated + clean_streak + manual
+    return {
+        "session_banked_xp": session_banked,
+        "milestone_xp": milestone,
+        "graduation_xp": graduated,
+        "manual_adjustments": manual,
+        "max_active_clean_streak": clean_streak,
+        "lifetime_xp": lifetime,
+    }
+
+
+def add_session_banked_xp(profile: dict, amount: int) -> dict:
+    normalize_profile_xp(profile)
+    profile["session_banked_xp"] = _as_int(profile.get("session_banked_xp")) + _as_int(amount)
+    profile["banked_session_xp"] = profile["session_banked_xp"]
+    return normalize_profile_xp(profile)
+
+
+def add_milestone_xp(profile: dict, amount: int) -> dict:
+    normalize_profile_xp(profile)
+    profile["milestone_xp"] = _as_int(profile.get("milestone_xp")) + _as_int(amount)
+    return normalize_profile_xp(profile)

package/coach/changelog.md

@@ -0,0 +1,4 @@
+# Coach changelog
+
+One line per `/coach-insights` run. Tailed by the SessionStart hook to surface
+a terse info message when new changes exist since the last session.

package/coach/default-statusline-command.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Coach Claw — default statusline composition.
+#
+# Thin trampoline: locates `bin/default_statusline.py` relative to this
+# wrapper's own directory using bash parameter expansion only — no
+# external commands, no PATH lookups. settings.json registers this
+# wrapper by absolute path, so ${BASH_SOURCE%/*} reliably yields the
+# wrapper's parent dir. Resolving relatively (instead of hardcoding
+# $HOME/.claude/coach/...) keeps custom CLAUDE_DIR installs working.
+#
+# `@PY@` is substituted with the absolute python3 path at install time
+# so the script doesn't depend on PATH at statusline-render time.
+#
+# To customize the rich default: edit `bin/default_statusline.py` (pure
+# Python, no external dependencies). Or run `/config` to change the
+# trailing coach segment's variant + theme without touching either
+# file.
+
+exec "@PY@" "${BASH_SOURCE%/*}/bin/default_statusline.py"

package/coach/default-statusline-wrap-command.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Coach Claw — wrap-mode statusline trampoline.
+#
+# Runs the user's saved original statusLine command first (captured in
+# `~/.claude/coach/.statusline-wrap.json` by `statusline_wrap_action.wrap`),
+# then appends the Coach segment with trailing-aware separator handling.
+#
+# Symmetric with `default-statusline-command.sh` — same `${BASH_SOURCE%/*}`
+# parameter expansion to locate the bin/ dir relative to this wrapper, so
+# custom CLAUDE_DIR installs keep working without configuration. `@PY@`
+# is substituted with the absolute python3 path at install time.
+#
+# To opt out of wrap mode after install: `/coach-claw:doctor --unwrap-statusline`.
+
+exec "@PY@" "${BASH_SOURCE%/*}/bin/statusline_wrap.py"

package/coach/profile.yaml

@@ -0,0 +1,37 @@
+schema_version: 1
+updated: null
+# Coach profile — autonomously maintained by /coach-insights.
+# Hand-editing is allowed but not required. Git-tracked for rollback.
+#
+# Tiers:
+#   candidate     — detected in 1 recent /coach-insights run; not yet injected
+#   probationary  — detected in 2-of-3 runs; injected at 30% probability
+#                   for first 7 days, then promoted to active
+#   active        — fully injected (confidence × cooldown gating)
+#
+# Confidence grows on recurrence, decays 5%/day untouched. <0.3 auto-retires.
+# Cap = 10 active entries; lowest-confidence evicted when a new one promotes.
+#
+# Each entry schema:
+#   id: stable-slug
+#   name: human-readable short name
+#   tier: candidate | probationary | active
+#   confidence: 0.0-1.0
+#   priority: 1-5 (for tie-breaking at the cap)
+#   nudge: single observational sentence, never prescriptive
+#   examples: short quoted evidence from transcripts (redacted)
+#   first_seen: ISO date
+#   last_seen_in_run: ISO date
+#   last_fired: ISO datetime (24h per-entry cooldown)
+#   promoted_at: ISO date | null  (probationary→active transition)
+#   source_session_ids: [short hashes]
+entries: []
+graduated: []
+archived: []
+session_banked_xp: 0
+milestone_xp: 0
+graduation_xp: 0
+manual_adjustments: 0
+# Deprecated compatibility alias for older installs; new code reads
+# session_banked_xp / milestone_xp / graduation_xp / manual_adjustments.
+banked_session_xp: 0

package/coach/tests/conftest.py

@@ -0,0 +1,13 @@
+"""Shared pytest fixtures + path setup for the coach suite.
+
+Adds coach/bin/ to sys.path so `import reward_hints, scoring, merge` works
+whether you run pytest from ~/.claude/coach/ or from the shareable bundle.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_BIN = Path(__file__).resolve().parent.parent / "bin"
+if str(_BIN) not in sys.path:
+    sys.path.insert(0, str(_BIN))