@lemoncode/lemony 0.1.0

package/catalog/harness.config.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "vendor_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-(alpha|beta|rc)\\.\\d+)?$"
+    },
+    "target": {
+      "type": "string",
+      "enum": [
+        "claude-code"
+      ]
+    },
+    "task_storage": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "github"
+          ]
+        },
+        "repo": {
+          "type": "string",
+          "pattern": "^[^\\s/]+\\/[^\\s/]+$"
+        }
+      },
+      "required": [
+        "type",
+        "repo"
+      ],
+      "additionalProperties": false
+    },
+    "agents": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "orchestrator",
+          "spec-author",
+          "implementer",
+          "reviewer",
+          "architect",
+          "ui-designer"
+        ]
+      }
+    },
+    "paths": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "state": {
+          "default": ".claude/state",
+          "type": "string"
+        },
+        "skills": {
+          "default": ".claude/skills",
+          "type": "string"
+        },
+        "agents": {
+          "default": ".claude/agents",
+          "type": "string"
+        },
+        "playbooks": {
+          "default": "docs/playbooks",
+          "type": "string"
+        },
+        "playbooks_global": {
+          "default": "~/.claude/playbooks",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "rollback": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "keep_snapshots": {
+          "default": 3,
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "string",
+              "const": "unlimited"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "telemetry": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "vendor_version",
+    "target",
+    "task_storage",
+    "agents"
+  ],
+  "additionalProperties": false
+}

package/catalog/hooks/README.md

@@ -0,0 +1,56 @@
+# hooks/ — lifecycle & enforcement hooks
+
+Shell hooks the installer wires into the client's `.claude/settings.json` and
+copies executable under `.claude/hooks/`. Helpers shared between hooks live in
+`catalog/hooks/lib/` and are copied alongside.
+
+## Hooks
+
+| Hook                  | Trigger                    | Purpose                                                                                                                                                                                                                                        |
+| --------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init.sh`             | `SessionStart`             | Orient the session (read-only state summary). Blocks on hard errors (config invalid, state corruption, no git user, no `gh` auth), warns otherwise (version drift, peer hook missing, branch behind, residual markers). <1s p99. Decision #54. |
+| `session-close.sh`    | `SessionEnd` + `/pause`    | Emit `session_closed` event with duration math, write `current-<user>.md` / `sessions/<user>/{ts}.md`. No auto-commit (prints `git status --porcelain`). Decision #52.                                                                         |
+| `require-playbook.sh` | `PreToolUse` (Write\|Edit) | Block writes that match a playbook's `applies_to` glob list until that playbook has been read in this conversation. Decision #11. See `catalog/playbook-format.md`.                                                                            |
+| `suggest-playbook.sh` | `UserPromptSubmit`         | Non-blocking nudge — emit a `<system-reminder>` when a prompt matches a playbook's `keywords` regex list and that playbook hasn't been read yet. Decision #11.                                                                                 |
+
+## Shared lib
+
+`lib/transcript-grep.sh` — find evidence in the JSONL transcript (parent +
+`<transcript>/subagents/agent-*.jsonl`) that Claude actually called the `Read`
+tool with a given path. Required on day 1 by both `require-playbook.sh` and
+`suggest-playbook.sh` to avoid a misfire whereby sub-agent reads (Implementer,
+Reviewer always run as sub-agents) would not satisfy the parent's gate.
+
+`lib/playbook-scan.sh` — discover playbooks across the two layers
+(`docs/playbooks/<topic>.md` local; `~/.claude/playbooks/<topic>.md` global; local
+shadows global) and expose `playbook_scan_for_path` + `playbook_scan_for_prompt`.
+Reads frontmatter via a single `awk` pass (no `yq` — decision #29) that
+supports the documented format subset — see `catalog/playbook-format.md`.
+
+## Fail-open philosophy
+
+The three enforcement hooks (`session-close.sh`, `require-playbook.sh`,
+`suggest-playbook.sh`) fail **open**: when their dependencies (`jq`, the
+transcript file) are missing or malformed, they exit 0 — possibly with a
+stderr warning — rather than blocking the agent. They are an enforcement
+layer, not the gate of last resort.
+
+`init.sh` is the only hook that **blocks** (exit 2) — and only on hard errors
+the session cannot proceed past (missing/invalid config, state corruption,
+missing git user, missing `gh` auth). That's by design (decision #54): the
+session-start orient is the right place to fail loud, because everything
+downstream depends on those preconditions.
+
+## Bash 3.2 compatibility
+
+macOS still ships `/bin/bash` 3.2 by default. The hooks avoid `declare -A`,
+`globstar` (`**`), and other bash 4-only features so they run end-to-end on a
+stock macOS install. `init.sh`'s doctor still recommends `brew install bash` —
+the suggestion is forward-looking, not a hard dependency for these hooks.
+
+## Local testing
+
+Each hook is exercised by a Vitest spec that spawns `bash <hook>` against a
+tmpdir fixture: `src/install/init-hook.spec.ts`,
+`src/install/session-close-hook.spec.ts`, `src/install/require-playbook-hook.spec.ts`,
+`src/install/suggest-playbook-hook.spec.ts`. Run with `node --run test`.

package/catalog/hooks/init.sh

@@ -0,0 +1,281 @@
+#!/usr/bin/env bash
+# Lemony — Claude Code SessionStart hook (decision #54).
+#
+# Read-only orient run on every session entry filtered by source: orient on
+# {startup, resume, clear}; skip {compact} silently to keep long sessions free
+# of noise.
+#
+# Outputs four blocks (exit 2, stderr — model sees it) and four warnings
+# (stdout — folded into session context). Plus a doctor check for bash version.
+# Target: <1s p99.
+
+set -u
+
+# Read stdin only when Claude Code is piping a payload; if a developer runs
+# this hook interactively (no pipe), default to an empty payload so the script
+# doesn't hang on `cat` waiting for input.
+if [ -t 0 ]; then
+  INPUT=""
+else
+  INPUT="$(cat)"
+fi
+
+# Extract `source` field from the JSON Claude Code pipes in. Bash-only
+# (no jq dep) — minimal stdin parse keeps the hook startup cheap.
+SOURCE="$(printf '%s' "$INPUT" \
+  | grep -o '"source"[[:space:]]*:[[:space:]]*"[^"]*"' \
+  | head -1 \
+  | sed 's/.*"\([^"]*\)"$/\1/')"
+if [ "$SOURCE" = "compact" ]; then
+  exit 0
+fi
+
+REPO_ROOT="$(pwd)"
+CONFIG="$REPO_ROOT/harness.config.yml"
+
+ERRORS=()
+WARNINGS=()
+
+# ── Block 1 ─ harness.config.yml present and parseable ─────────────────────
+# Pure-bash validation (no yq — #41): presence of the four keys the harness
+# needs to operate, checked top-level plus block-scoped under `task_storage`
+# in one awk pass, then extraction of the two values the orient output uses.
+# Deep schema validation (formats, enums, did-you-mean typos) lives in
+# `lemony doctor`; init.sh stays fail-closed yet node-free, so the boot
+# path never depends on the CLI being installed. `jq` is the sole hard dep;
+# awk/grep/git (preinstalled) cover the rest.
+CONFIG_VERSION=""
+CONFIG_REPO=""
+if [ ! -f "$CONFIG" ]; then
+  ERRORS+=("harness.config.yml not found at $REPO_ROOT. Run \`lemony install\`.")
+elif ! awk '
+    { sub(/\r$/, "") }
+    /^[^[:space:]#]/ {
+      in_ts = ($1 == "task_storage:") ? 1 : 0
+      if ($1 == "vendor_version:") have_vv = 1
+      else if ($1 == "target:") have_tg = 1
+      else if ($1 == "task_storage:") have_ts = 1
+    }
+    in_ts && /^[[:space:]]+type:/ { have_tt = 1 }
+    in_ts && /^[[:space:]]+repo:/ { have_tr = 1 }
+    END {
+      exit !(have_vv && have_tg && have_ts && have_tt && have_tr)
+    }
+  ' "$CONFIG"; then
+  ERRORS+=("harness.config.yml is missing required keys (vendor_version, target, task_storage.type, task_storage.repo).")
+else
+  CONFIG_VERSION="$(awk '{ sub(/\r$/, "") } /^vendor_version:/ { sub(/^vendor_version:[[:space:]]*/, ""); gsub(/"/, ""); print; exit }' "$CONFIG")"
+  CONFIG_REPO="$(awk '
+    { sub(/\r$/, "") }
+    /^[^[:space:]#]/ { in_ts = ($1 == "task_storage:") ? 1 : 0 }
+    in_ts && /^[[:space:]]*repo:/ { sub(/^[[:space:]]*repo:[[:space:]]*/, ""); gsub(/"/, ""); print; exit }
+  ' "$CONFIG")"
+fi
+
+# ── Block 2 ─ state corruption (critical dirs missing) ─────────────────────
+for dir in .claude/state .claude/skills .claude/agents; do
+  if [ ! -d "$REPO_ROOT/$dir" ]; then
+    ERRORS+=("Harness directory missing: $dir (state corruption — re-run \`lemony install\`).")
+  fi
+done
+
+# ── Block 3 ─ git config user.email present ────────────────────────────────
+GIT_USER_EMAIL="$(git config user.email 2>/dev/null || true)"
+if [ -z "$GIT_USER_EMAIL" ]; then
+  ERRORS+=("git config user.email is empty. Run: git config --global user.email 'you@example.com'.")
+fi
+
+# ── Block 4 ─ gh CLI installed and authenticated ───────────────────────────
+# Uses `gh auth token` (local-only) instead of `gh auth status` (HTTPS round
+# trip) to keep the orient inside the <1s p99 budget.
+if ! command -v gh >/dev/null 2>&1; then
+  ERRORS+=("\`gh\` CLI not found in PATH. Install: https://cli.github.com")
+elif ! gh auth token >/dev/null 2>&1; then
+  ERRORS+=("\`gh auth token\` returned no token. Run \`gh auth login\`.")
+fi
+
+# ── Warning 1 ─ vendor version drift (config vs installed CLI) ─────────────
+# Resolve the CLI for the version read: the project-local devDependency bin first
+# (it survives an fnm Node switch, #113), then a global install. No npx fallback —
+# the orient hook stays inside its <1s p99 budget, so a non-resolvable CLI just
+# skips the drift check rather than paying a network round trip every session.
+LF_BIN=""
+if [ -x "$REPO_ROOT/node_modules/.bin/lemony" ]; then
+  LF_BIN="$REPO_ROOT/node_modules/.bin/lemony"
+elif command -v lemony >/dev/null 2>&1; then
+  LF_BIN="lemony"
+fi
+if [ -n "$CONFIG_VERSION" ] && [ -n "$LF_BIN" ]; then
+  INSTALLED_VERSION="$("$LF_BIN" --version 2>/dev/null | head -1)"
+  if [ -n "$INSTALLED_VERSION" ] && [ "$CONFIG_VERSION" != "$INSTALLED_VERSION" ]; then
+    # Direction-neutral by design (#172): the hook stays offline + node-free, so it
+    # can't order the two versions reliably (no portable semver compare in bash —
+    # BSD `sort` lacks `-V`). It flags the drift with a remedy safe in BOTH
+    # directions; `lemony doctor` resolves the precise direction (it has a
+    # real comparator) and the exact remediation.
+    WARNINGS+=("vendor version drift: harness.config.yml pins $CONFIG_VERSION, installed CLI is $INSTALLED_VERSION. If your CLI is newer, run \`lemony update\`; if it is older, upgrade your CLI (\`npm install\`) and do NOT run \`update\` (it would downgrade the repo). \`lemony doctor\` tells you which.")
+  fi
+elif [ -n "$CONFIG_VERSION" ]; then
+  # #180: the repo pins a version but no CLI resolves (a teammate never ran
+  # `npm install`, no global). This used to be a silent skip — so a stale CLI could
+  # drift with no signal at all. Emit a visible line instead, so the check's absence
+  # isn't mistaken for "no drift". Still offline (#129): no registry lookup, just a
+  # heads-up to install the project-local CLI.
+  WARNINGS+=("could not verify CLI version: harness.config.yml pins $CONFIG_VERSION but no \`lemony\` CLI resolved. Run \`npm install\` to get the project-local one (then re-check with \`lemony doctor\`). Version-drift check skipped.")
+fi
+
+# ── Warning 2 ─ peer hook missing or non-executable ────────────────────────
+PEER_HOOK="$REPO_ROOT/.claude/hooks/session-close.sh"
+if [ ! -x "$PEER_HOOK" ]; then
+  WARNINGS+=("$PEER_HOOK is missing or not executable — \`/pause\` and SessionEnd telemetry will fail. Re-run \`lemony install\` (or chmod +x).")
+fi
+
+# ── Warning 3 ─ local branch behind origin (no fetch — uses existing refs) ─
+DEFAULT_BRANCH="$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')"
+if [ -n "$DEFAULT_BRANCH" ]; then
+  BEHIND="$(git rev-list --count "HEAD..origin/$DEFAULT_BRANCH" 2>/dev/null || echo 0)"
+  if [ "${BEHIND:-0}" -gt 0 ]; then
+    WARNINGS+=("local branch is $BEHIND commit(s) behind origin/$DEFAULT_BRANCH. Consider \`git pull --rebase\` before starting.")
+  fi
+fi
+
+# ── Warning 4 ─ residual harness branches (parked tasks) ───────────────────
+STALE_BRANCHES="$(git for-each-ref --format='%(refname:short)' refs/heads/harness/ 2>/dev/null | wc -l | tr -d ' ')"
+if [ "${STALE_BRANCHES:-0}" -gt 0 ]; then
+  CURRENT_BRANCH="$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+  case "$CURRENT_BRANCH" in
+    harness/*) : ;;
+    *) WARNINGS+=("$STALE_BRANCHES parked harness branch(es) present. Resume with \`continue <id>\` or close them with task-closeout.") ;;
+  esac
+fi
+
+# ── Doctor (informational; never blocking) ─────────────────────────────────
+BASH_MAJOR="${BASH_VERSION%%.*}"
+if [ "${BASH_MAJOR:-0}" -lt 4 ]; then
+  # The shipped hooks (lifecycle + playbook enforcement) are explicitly bash
+  # 3.2 compatible. The warning is forward-looking: a future hook MAY require
+  # bash 4 features (`shopt -s globstar`, associative arrays). On stock macOS
+  # `/bin/bash` is 3.2 and current hooks run cleanly there.
+  WARNINGS+=("bash $BASH_VERSION detected; current hooks run on 3.2 but future ones may want 4+. \`brew install bash\` to be future-proof.")
+fi
+
+# ── Lazy-init current-<user>.md (per-dev pointer, gitignored) ──────────────
+# If the blocks didn't fire and we know the user, ensure the per-dev pointer
+# file exists with a fresh `session_start_ts` so `session-close.sh` can compute
+# `session_active_h` accurately. The refresh is a pure-awk in-place rewrite of
+# the frontmatter scalar (#41: no yq).
+if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$GIT_USER_EMAIL" ]; then
+  NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  # `%%@*` strips from the FIRST `@` (parity with status.ts's `email.split('@')[0]`),
+  # not `%@*` which strips from the last — they diverge only on a malformed multi-`@`
+  # address, but the pointer filename must match what status.ts reads back.
+  USER_SLUG="${GIT_USER_EMAIL%%@*}"
+  # The slug becomes a filename — drop anything path-significant so a crafted
+  # user.email (`../../x@y`) can't make CURRENT_PATH escape `.claude/state/`.
+  # Mirrors the readPointer guard in status.ts; skips the write (status returns
+  # empty), since the boot can otherwise proceed.
+  case "$USER_SLUG" in
+    '' | */* | *'\'* | *..*) USER_SLUG="" ;;
+  esac
+  CURRENT_PATH="$REPO_ROOT/.claude/state/current-$USER_SLUG.md"
+  if [ -z "$USER_SLUG" ]; then
+    : # path-unsafe slug — pointer write skipped above
+  elif [ ! -f "$CURRENT_PATH" ]; then
+    mkdir -p "$REPO_ROOT/.claude/state"
+    cat > "$CURRENT_PATH" <<EOF
+---
+active_task: null
+branch: $(git symbolic-ref --quiet --short HEAD 2>/dev/null || echo "(unknown)")
+session_start_ts: $NOW_ISO
+last_close_ts: ""
+---
+
+# Current session — $GIT_USER_EMAIL
+
+Per-dev pointer (gitignored). The lifecycle hooks read \`session_start_ts\`
+to compute \`session_active_h\` and reset it on each SessionStart that orients.
+
+## Resume hint
+
+_(One paragraph — what to pick up next. Updated by \`/pause\`.)_
+EOF
+  else
+    # Refresh session_start_ts on every orient so close-time math is accurate.
+    # awk in-place rewrite of the frontmatter scalar — without this,
+    # `session_start_ts` would stay frozen at the first orient and
+    # `session_active_h` would be cumulative across every clear/resume.
+    # Write through a mktemp file, not a predictable `$CURRENT_PATH.tmp`: the
+    # latter is a known path an attacker could pre-plant as a symlink for the
+    # redirect to follow. `mktemp` refuses to reuse an existing path, and `mv`
+    # over CURRENT_PATH itself safely replaces a symlink with a regular file.
+    if tmp="$(mktemp "$REPO_ROOT/.claude/state/.ptr.XXXXXX")"; then
+      awk -v ts="$NOW_ISO" '
+        /^---/ {
+          block++
+          if (block == 2 && !seen) print "session_start_ts: " ts
+          print
+          next
+        }
+        block == 1 && /^session_start_ts:/ { print "session_start_ts: " ts; seen = 1; next }
+        { print }
+      ' "$CURRENT_PATH" > "$tmp" && mv "$tmp" "$CURRENT_PATH" || rm -f "$tmp"
+    fi
+  fi
+fi
+
+# ── Telemetry opt-out disclosure (#232, D11/D13) ───────────────────────────
+# Anonymous telemetry is on by default, so the first session — and any session
+# after the effective consent changes — must surface the opt-out. The sentinel +
+# fingerprint logic lives in TS (one resolver, no bash duplication of the env ›
+# local › config precedence + .strict() fail-safe — #232 G); init.sh just shells
+# out when a CLI resolves ($LF_BIN from the version-drift check) and skips
+# otherwise. A CLI-less teammate is not left uninformed: `install` already showed
+# the notice once. Healthy-path only, and never fails the boot — the command
+# self-suppresses when telemetry is OFF and `|| true` swallows any non-zero.
+if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$LF_BIN" ]; then
+  "$LF_BIN" telemetry notice 2>/dev/null || true
+fi
+
+# ── Telemetry catch-up send (#228, Phase 4) ────────────────────────────────
+# SessionEnd's send (#225) is the timely path; this is the safety net for a
+# session that closed uncleanly (crash / SIGKILL / no SessionEnd fired) and so
+# never shipped its tail. Flush the unsent tail of events.jsonl now, on entry.
+# Detached in a subshell (`( … & )`) with output redirected so SessionStart never
+# waits on the network; `nohup` lets it outlive a SIGHUP if the orient's process
+# group tears down before the send completes — same fire-and-forget shape as
+# session-close.sh (the CLI carries its own hard per-request timeout, D4, and
+# never throws). The byte-offset cursor dedups: a clean prior close already
+# advanced it, so this finds nothing to send. A failure (offline) leaves the
+# cursor untouched and the next hook retries the same bytes — the offline
+# invariant. No-op when no endpoint is configured. Runs AFTER the disclosure so a
+# first-ever session surfaces the opt-out first (there is no backlog on a first
+# session anyway, and the engine re-checks consent before any byte leaves the box).
+if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$LF_BIN" ]; then
+  ( nohup "$LF_BIN" telemetry send >/dev/null 2>&1 & )
+fi
+
+# ── Output ─────────────────────────────────────────────────────────────────
+if [ "${#WARNINGS[@]}" -gt 0 ]; then
+  echo "Lemony — orient ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
+  if [ -n "$CONFIG_REPO" ]; then
+    echo "  project: $CONFIG_REPO  user: ${GIT_USER_EMAIL:-(unset)}"
+  fi
+  for w in "${WARNINGS[@]}"; do
+    echo "  ⚠ $w"
+  done
+fi
+
+if [ "${#ERRORS[@]}" -gt 0 ]; then
+  {
+    echo "Lemony — blocking issues:"
+    for e in "${ERRORS[@]}"; do
+      echo "  ✖ $e"
+    done
+    # Self-identify so a maintainer reading the log can locate the source
+    # without a grep — same treatment as the playbook hooks' block messages.
+    echo "(Hook: ${BASH_SOURCE[0]})"
+  } >&2
+  exit 2
+fi
+
+exit 0

package/catalog/hooks/lib/lemony.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Lemony — CLI launcher (issues #107 / #113).
+#
+# The harness's hooks, agents and commands invoke the telemetry CLI (`lemony
+# emit …`). Calling the bare `lemony` binary is fragile: an `npx …` install
+# leaves nothing on PATH (#107), and a Node version manager (fnm/nvm) drops the
+# global bin when the active version changes (#113), so `command -v lemony`
+# silently fails and telemetry is skipped.
+#
+# This launcher resolves the CLI deterministically, preferring the project-local
+# devDependency bin (which survives PATH / Node-manager churn because it lives in
+# the repo's own `node_modules`), then a global install:
+#
+#   1. <repo-root>/node_modules/.bin/lemony   — the devDependency (canonical)
+#   2. a `lemony` on PATH                      — a global install
+#
+# Deliberately NO `npx` fallback: the package is private on GitHub Packages, so an
+# `npx @lemoncode/lemony` in a hook (no `GITHUB_TOKEN` in the env) can't auth and
+# would 401 or, worse, hang the SessionEnd hook on a network stall with no timeout —
+# the exact reason init.sh avoids npx too. When neither resolves, fail fast with exit
+# 127 and a one-line hint; callers (session-close, …) fail open on that.
+#
+# Call it with the CLI args, e.g. `.claude/hooks/lib/lemony.sh emit …`. It
+# `exec`s the resolved CLI, so its exit code and stderr are the CLI's own — callers
+# keep their existing fail-open / forward-the-error handling. Not a lifecycle hook
+# (no stdin envelope, no exit-2 block) — a thin dispatcher.
+set -u
+
+# Repo root from the launcher's own location (.claude/hooks/lib/ → up three), so
+# resolution is independent of the caller's cwd and of any git state.
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+LOCAL_BIN="$ROOT/node_modules/.bin/lemony"
+if [ -x "$LOCAL_BIN" ]; then
+  exec "$LOCAL_BIN" "$@"
+elif command -v lemony >/dev/null 2>&1; then
+  exec lemony "$@"
+else
+  echo "lemony: CLI not found — add the devDependency (\`npm i -D @lemoncode/lemony\`) or install it globally. Skipping." >&2
+  exit 127
+fi