@lemoncode/lemony 0.1.0

package/catalog/hooks/session-close.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# Lemony — Claude Code SessionEnd hook + `/pause` adaptor (decision #52).
+#
+# Fires:
+#   • automatically on SessionEnd (no `--manual`) → auto-close path: writes a
+#     skeleton `sessions/<user>/<ts>-auto.md`.
+#   • from `/pause` with `--manual` → Claude has already written
+#     `sessions/<user>/<ts>-<topic>.md`; the hook only emits + updates pointers.
+#
+# Both paths emit a `session_closed` event and print `git status --porcelain`
+# without auto-committing (the user decides what to commit).
+
+set -u
+
+MANUAL=0
+for arg in "$@"; do
+  case "$arg" in
+    --manual) MANUAL=1 ;;
+  esac
+done
+
+REPO_ROOT="$(pwd)"
+INPUT=""
+if [ "$MANUAL" -eq 0 ]; then
+  # Claude Code pipes a JSON payload on SessionEnd. The hook reads stdin once;
+  # if no payload was sent (manual invocation, missing pipe) we proceed with
+  # `reason=other`.
+  if [ -t 0 ]; then
+    INPUT=""
+  else
+    INPUT="$(cat || true)"
+  fi
+fi
+
+# ── Resolve the user (filename + envelope `user` derive from git config) ───
+EMAIL="$(git config user.email 2>/dev/null || true)"
+if [ -z "$EMAIL" ]; then
+  # Self-identify so a maintainer reading the log can locate the source
+  # without a grep — same treatment as the playbook hooks.
+  echo "session-close (${BASH_SOURCE[0]}): git config user.email is empty — skipping (init.sh would have blocked the session, so this is a defensive guard)." >&2
+  exit 0
+fi
+# `%%@*` 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="${EMAIL%%@*}"
+# The slug becomes a filename — bail on 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; fail-open like the empty-email case.
+case "$USER_SLUG" in
+  '' | */* | *'\'* | *..*)
+    echo "session-close (${BASH_SOURCE[0]}): git config user.email derives a path-unsafe slug — skipping." >&2
+    exit 0
+    ;;
+esac
+
+# ── Timestamps ─────────────────────────────────────────────────────────────
+NOW_EPOCH="$(date -u +%s)"
+NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# ── Read current-<user>.md frontmatter ─────────────────────────────────────
+# An awk scrape of the leading frontmatter block — works for the shallow
+# scalars the harness writes, fails gracefully on anything richer. yq was
+# removed harness-wide (#41): jq is the sole hard dependency; awk/grep/git
+# (preinstalled) cover the rest.
+CURRENT_PATH="$REPO_ROOT/.claude/state/current-$USER_SLUG.md"
+SESSION_START_TS=""
+ACTIVE_TASK=""
+TASK_BRANCH=""
+read_frontmatter_field() {
+  local field="$1"
+  awk -v field="$field" '
+    /^---/ { block++; next }
+    block == 1 {
+      n = index($0, ":")
+      if (n > 0) {
+        key = substr($0, 1, n - 1)
+        sub(/^[[:space:]]+|[[:space:]]+$/, "", key)
+        if (key == field) {
+          value = substr($0, n + 1)
+          sub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+          gsub(/"/, "", value)
+          print value
+          exit
+        }
+      }
+    }
+  ' "$CURRENT_PATH" 2>/dev/null
+}
+if [ -f "$CURRENT_PATH" ]; then
+  SESSION_START_TS="$(read_frontmatter_field session_start_ts)"
+  ACTIVE_TASK="$(read_frontmatter_field active_task)"
+  TASK_BRANCH="$(read_frontmatter_field branch)"
+fi
+
+# Fallback: a session with no recorded start defaults to "started now" so the
+# math is well-defined; duration becomes 0 hours, which the schema accepts.
+if [ -z "$SESSION_START_TS" ]; then
+  SESSION_START_TS="$NOW_ISO"
+fi
+
+# Convert SESSION_START_TS to epoch (portable between GNU and BSD date).
+iso_to_epoch() {
+  local ts="$1"
+  # Strip fractional seconds and the trailing Z for BSD `date -j -f`.
+  local clean="${ts%%.*}"
+  clean="${clean%Z}"
+  if date -u -d "@0" +%s >/dev/null 2>&1; then
+    date -u -d "$ts" +%s
+  else
+    date -juf "%Y-%m-%dT%H:%M:%S" "$clean" +%s 2>/dev/null
+  fi
+}
+START_EPOCH="$(iso_to_epoch "$SESSION_START_TS")"
+if [ -z "${START_EPOCH:-}" ]; then
+  START_EPOCH="$NOW_EPOCH"
+fi
+DURATION_H="$(awk -v start="$START_EPOCH" -v now="$NOW_EPOCH" 'BEGIN { printf "%.4f", (now - start) / 3600.0 }')"
+# Floor at zero — a clock skew between session_start_ts and now must not yield
+# a negative duration that fails Zod validation.
+if awk -v d="$DURATION_H" 'BEGIN { exit !(d < 0) }'; then
+  DURATION_H="0.0000"
+fi
+
+# ── Resolve reason + auto_close flag ───────────────────────────────────────
+if [ "$MANUAL" -eq 1 ]; then
+  REASON="manual"
+  AUTO_CLOSE="false"
+else
+  REASON="$(printf '%s' "$INPUT" \
+    | grep -o '"reason"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 \
+    | sed 's/.*"\([^"]*\)"$/\1/')"
+  REASON="${REASON:-other}"
+  AUTO_CLOSE="true"
+fi
+
+# ── Emit the event via the CLI (Zod-validates the line) ────────────────────
+EMIT_ARGS=(
+  emit session_closed
+  --session-start-ts="$SESSION_START_TS"
+  --session-active-h="$DURATION_H"
+  --reason="$REASON"
+  --auto-close="$AUTO_CLOSE"
+)
+# Skip a literal "null" — a buggy frontmatter may emit the string instead of a
+# real YAML null. The schema would accept it but the line is forensic noise.
+if [ -n "$ACTIVE_TASK" ] && [ "$ACTIVE_TASK" != "null" ]; then
+  EMIT_ARGS+=(--task-id="$ACTIVE_TASK")
+fi
+# Resolve the CLI via the launcher (local devDependency → global → fail-fast, #107/#113)
+# rather than a bare `command -v` on PATH, which an npx install or an fnm Node
+# switch leaves empty. Fail open — a missing launcher or a failed emit warns and
+# continues; the session must never be blocked by telemetry.
+LF_CLI="$REPO_ROOT/.claude/hooks/lib/lemony.sh"
+if [ -x "$LF_CLI" ]; then
+  "$LF_CLI" "${EMIT_ARGS[@]}" || \
+    echo "session-close: \`lemony emit\` failed (continuing — see previous error)." >&2
+else
+  echo "session-close: CLI launcher missing ($LF_CLI) — skipping event emit. Re-run \`lemony install\`." >&2
+fi
+
+# ── Fire-and-forget telemetry send (#225, Phase 1 walking skeleton) ─────────
+# Flush the unsent tail of events.jsonl to the ingest Worker. Detached in a
+# subshell (`( … & )`) so SessionEnd never waits on the network; `nohup` lets it
+# outlive a SIGHUP if the session tears down its process group before the send
+# completes. The CLI has its own hard per-request timeout (D4) and never throws —
+# output is discarded and a failure leaves the cursor untouched, so the next run
+# (or init.sh catch-up, #228) retries the same bytes. No-op when no endpoint is
+# configured. Telemetry must never block or break session exit.
+if [ -x "$LF_CLI" ]; then
+  ( nohup "$LF_CLI" telemetry send >/dev/null 2>&1 & )
+fi
+
+# ── Auto-close path: write the session skeleton ───────────────────────────
+if [ "$MANUAL" -eq 0 ]; then
+  SESSIONS_DIR="$REPO_ROOT/.claude/state/sessions/$USER_SLUG"
+  mkdir -p "$SESSIONS_DIR"
+  SESSION_FILE="$SESSIONS_DIR/$NOW_ISO-auto.md"
+  cat > "$SESSION_FILE" <<EOF
+---
+session_start_ts: $SESSION_START_TS
+session_close_ts: $NOW_ISO
+session_active_h: $DURATION_H
+active_task: ${ACTIVE_TASK:-null}
+branch: ${TASK_BRANCH:-(unknown)}
+reason: $REASON
+auto_close: true
+---
+
+# Session — auto-close ($NOW_ISO)
+
+_Closed by Claude Code's SessionEnd event with no narrative model run._
+_If you want a written resume, use \`/pause\` before exiting next time._
+EOF
+fi
+
+# ── Update current-<user>.md frontmatter pointers ──────────────────────────
+# Blank session_start_ts (the next SessionStart re-stamps it) and record the
+# close ts. awk in-place rewrite of the frontmatter scalars — mirrors the read
+# fallback above and the session_start_ts rewrite in init.sh (#41: no yq).
+if [ -f "$CURRENT_PATH" ]; then
+  # Rewrite each scalar if present; if a legacy/hand-edited pointer lacks the
+  # line, append it just before the closing `---` (parity with the `yq -i` set
+  # this replaced — `block == 2` is the frontmatter's closing fence).
+  # 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) {
+          if (!seen_start) print "session_start_ts: \"\""
+          if (!seen_close) print "last_close_ts: " ts
+        }
+        print
+        next
+      }
+      block == 1 && /^session_start_ts:/ { print "session_start_ts: \"\""; seen_start = 1; next }
+      block == 1 && /^last_close_ts:/ { print "last_close_ts: " ts; seen_close = 1; next }
+      { print }
+    ' "$CURRENT_PATH" > "$tmp" && mv "$tmp" "$CURRENT_PATH" || rm -f "$tmp"
+  fi
+fi
+
+# ── Print git status without committing ────────────────────────────────────
+echo "git status --porcelain ($NOW_ISO):"
+git -C "$REPO_ROOT" status --porcelain 2>/dev/null || true
+
+exit 0

package/catalog/hooks/suggest-playbook.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Lemony — Claude Code UserPromptSubmit hook (playbook suggestion).
+#
+# Non-blocking. Scans the user's freshly submitted prompt and, when it mentions
+# a topic covered by a playbook (per the `keywords` regex list in the
+# frontmatter) that hasn't been read yet in this conversation, emits a
+# <system-reminder> on stdout — Claude Code attaches it as guidance for the
+# agent's next turn.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/playbook-scan.sh
+source "$SCRIPT_DIR/lib/playbook-scan.sh"
+# shellcheck source=lib/transcript-grep.sh
+source "$SCRIPT_DIR/lib/transcript-grep.sh"
+
+if [ -t 0 ]; then
+  PAYLOAD=""
+else
+  PAYLOAD="$(cat 2>/dev/null || true)"
+fi
+[ -n "$PAYLOAD" ] || exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+PROMPT="$(printf '%s' "$PAYLOAD" | jq -r '.prompt // empty')"
+[ -n "$PROMPT" ] || exit 0
+
+REPO_ROOT="$(pwd)"
+HOME_DIR="${HOME:-$REPO_ROOT}"
+
+playbook_scan_for_prompt "$REPO_ROOT" "$HOME_DIR" "$PROMPT"
+if [ ${#MATCHED_KEYWORD_PLAYBOOKS[@]} -eq 0 ]; then
+  exit 0
+fi
+
+TRANSCRIPT_PATH="$(printf '%s' "$PAYLOAD" | jq -r '.transcript_path // empty')"
+
+NEW_SUGGESTIONS=()
+for pb in "${MATCHED_KEYWORD_PLAYBOOKS[@]}"; do
+  if [ -n "$TRANSCRIPT_PATH" ] && [ -r "$TRANSCRIPT_PATH" ]; then
+    if transcript_contains_playbook "$TRANSCRIPT_PATH" "$pb"; then
+      continue
+    fi
+  fi
+  NEW_SUGGESTIONS+=("$pb")
+done
+
+if [ ${#NEW_SUGGESTIONS[@]} -eq 0 ]; then
+  exit 0
+fi
+
+{
+  printf '<system-reminder>\n'
+  printf 'Topic detection on your prompt suggests reading these playbook(s) before planning:\n\n'
+  for pb in "${NEW_SUGGESTIONS[@]}"; do
+    printf '  - %s\n' "$pb"
+  done
+  printf '\nUse the Read tool on each. Playbooks contain this project'\''s canonical patterns\n'
+  printf 'for that kind of work — reading them avoids re-discovering already-solved problems.\n'
+  printf '\nIf a playbook clearly does not apply to the current context, you may skip it —\n'
+  printf 'this hook errs on the side of suggesting too much rather than too little.\n'
+  # Name the actual file the agent / human reader can inspect (same treatment
+  # as require-playbook.sh — works both at an installed `.claude/hooks/`
+  # location and when the hook runs from the vendor repo).
+  printf '\n(Hook: %s)\n' "${BASH_SOURCE[0]}"
+  printf '</system-reminder>\n'
+}
+
+exit 0

package/catalog/playbook-format.md

@@ -0,0 +1,198 @@
+# Playbook format — specification
+
+The canonical structure for a **playbook** (the renamed _blueprint_): a project-agnostic
+document describing **how to build** a category of software (a backend service, an SPA, a
+testing strategy, a release flow). Playbooks live in the **client's** repo (and an optional
+global layer); the vendor ships **no concrete playbooks** (decision #8 — client-owned).
+
+The two enforcement hooks shipped in P5 slice 2 (`require-playbook.sh`,
+`suggest-playbook.sh`) read this format. Skills that consult playbooks read it too.
+
+---
+
+## File layout
+
+A playbook is a markdown file with leading YAML frontmatter, located by **topic
+filename** across two layers:
+
+| Layer           | Path                             | Notes                    |
+| --------------- | -------------------------------- | ------------------------ |
+| Project (local) | `docs/playbooks/<topic>.md`      | Committed with the repo. |
+| Global          | `~/.claude/playbooks/<topic>.md` | Personal, generic.       |
+
+The **filename stem is the topic** — there is no index. Lookup is **local → global**: if
+both layers define `<topic>.md`, the **local one wins** and the global one is ignored for
+that topic. A missing playbook is **not an error** — agents that consult one degrade
+gracefully when it is absent.
+
+> Both layers are **configurable** via `harness.config.yml`: set `paths.playbooks`
+> (repo-relative) to relocate the local layer, and `paths.playbooks_global`
+> (absolute or `~`-based) to relocate the global one. The hooks read those keys
+> directly on each fire; editing them takes effect on the next fire (no install
+> or restart). Omit a key to keep the default shown above.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+name: testing
+applies_to:
+  - '**/*.spec.ts'
+  - '**/*.spec.tsx'
+  - '**/*.bench.ts'
+keywords:
+  - 'vitest'
+  - 'test runner'
+  - 'AAA pattern'
+status: active
+---
+```
+
+### Fields
+
+| Field        | Required | Type                            | Purpose                                                                                                    |
+| ------------ | -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `name`       | yes      | kebab-case string               | Identifier. Must equal the filename stem (`testing.md` → `name: testing`).                                 |
+| `applies_to` | no       | list of bash globs              | Files whose `Write`/`Edit` should be **blocked** until this playbook is read. Empty/absent → never blocks. |
+| `keywords`   | no       | list of regex strings           | Prompt patterns that **suggest** reading this playbook (non-blocking). Empty/absent → never suggests.      |
+| `status`     | no       | `draft \| active \| deprecated` | Author intent. Hooks ignore status today; reserved for skills/tooling.                                     |
+
+`applies_to` and `keywords` are **independently optional**: a playbook can be require-only
+(globs but no keywords), suggest-only (keywords but no globs), both, or neither (a doc
+agents read on demand but is not enforced).
+
+> **Frontmatter subset (awk-parsed).** The hooks read frontmatter with a single
+> `awk` pass over every discovered playbook — no `yq` (decision #29: one `yq`
+> fork per playbook blew the <50ms p99 budget, and its only edge here — YAML
+> escape-sequence fidelity — is unused because keywords are constrained to the
+> awk subset anyway). Supported: block lists (`field:\n  - item`) and simple
+> inline lists (`field: [a, b]`) of scalar strings, optionally single- or
+> double-quoted (quotes are stripped). The reader does **not** unescape YAML double-quote
+> sequences (`"\b"` stays the two characters `\b`, not a backspace) and does
+> **not** respect quotes when splitting an inline list on commas — a
+> `keywords: ["foo, bar"]` splits into `"foo` and `bar"`. Author keywords
+> within this subset: no `\b` word boundaries, no comma-bearing strings.
+> (`yq` has since left the harness entirely — decision #41 moved `init.sh` config
+> validation and `session-close.sh` state to pure bash, so `jq` is the only hard
+> dependency.)
+
+### `applies_to` semantics
+
+Each pattern is a glob-style string, transliterated to a POSIX-ERE regex and
+matched against the **full file path passed to Write/Edit** with bash
+`[[ =~ ]]`. The regex path (rather than `shopt -s globstar`) keeps the hooks
+runnable on stock macOS `/bin/bash` 3.2. Supported subset:
+
+| Glob      | Means                                                                                                                                                                                        |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `*`       | any sequence within a single path component (no `/`)                                                                                                                                         |
+| `**/`     | zero or more leading path components (so `**/x` matches `x` at root too)                                                                                                                     |
+| `**`      | any sequence including `/`                                                                                                                                                                   |
+| `?`       | any single non-separator character                                                                                                                                                           |
+| `[abc]`   | character class (passthrough)                                                                                                                                                                |
+| `[!abc]`  | negated class (translated to ERE `[^abc]`)                                                                                                                                                   |
+| `{a,b,c}` | alternation, becomes `(a\|b\|c)`. Nested braces and **empty alternatives** (`{,X}`, `{X,}`, `{,}`) are not supported — BSD ERE rejects empty branches; the playbook silently fails to match. |
+| `\X`      | literal `X` (escape)                                                                                                                                                                         |
+
+Examples (with the absolute path Claude Code passes in mind):
+
+| Pattern                             | Matches                                                         |
+| ----------------------------------- | --------------------------------------------------------------- |
+| `**/*.spec.ts`                      | any `*.spec.ts` at any depth, including root                    |
+| `**/apps/web/**/*.tsx`              | TSX files under any `apps/web/`                                 |
+| `**/Dockerfile`                     | a Dockerfile at any depth, including root                       |
+| `**/Dockerfile*`                    | `Dockerfile` plus variants (`Dockerfile.web`, `Dockerfile.dev`) |
+| `**/.github/workflows/*.{yml,yaml}` | CI workflow files                                               |
+
+Tip: prefix patterns with `**/` rather than relying on a bare filename — Claude
+Code passes **absolute** file paths to `Write`/`Edit`, so a literal `Dockerfile`
+(without `**/`) only matches a target whose path is exactly that string.
+
+Order **within a playbook** does not matter — any pattern matching the file path triggers
+the require. Order **across playbooks** does not matter either — if two playbooks both
+match the same path, the agent must read **both** before the write passes.
+
+**Chicken-and-egg:** a playbook whose `applies_to` matches its own location —
+e.g. `**/*.md` — will block the very file you're trying to author. Prefer
+narrow globs (file-type-specific), and if you ever need a generic-Markdown
+playbook, carve out `docs/playbooks/**` from the pattern.
+
+### `keywords` semantics
+
+Each entry is a **case-insensitive regex** evaluated against the raw user prompt
+(multi-line aware — the matcher slurps the prompt into a single string before
+testing) with `jq`'s Oniguruma engine (PCRE-like). Use `\b` for word
+boundaries, `|` for alternation inside a single pattern, etc.
+
+Examples:
+
+| Pattern                    | Fires on                               |
+| -------------------------- | -------------------------------------- |
+| `\bvitest\b`               | "let's add vitest", "Vitest config"    |
+| `\b(new pod\|nuevo pod)\b` | English or Spanish                     |
+| `\bMongo(DB)? aggregate\b` | "MongoDB aggregate", "Mongo aggregate" |
+
+Multiple playbooks may match the same prompt — all matching playbooks are suggested in
+a single `<system-reminder>` block.
+
+---
+
+## How the hooks interpret it
+
+### `require-playbook.sh` (PreToolUse on `Write`/`Edit`)
+
+1. Scan all playbooks: `docs/playbooks/*.md` (local) + `~/.claude/playbooks/*.md` (global,
+   only for topics not shadowed by a local file).
+2. For each playbook with non-empty `applies_to`, test every glob against the target
+   `file_path`. If any matches, the playbook is **required**.
+3. For each required playbook, grep the conversation transcript (and any sub-agent
+   transcripts under `<transcript>/subagents/*.jsonl`) for evidence that **Claude actually
+   read it** via the `Read` tool with the playbook's absolute path.
+4. If at least one required playbook is unread, exit 2 with a message naming the missing
+   playbook(s) and the exact `Read(...)` call the agent must make. Otherwise exit 0.
+
+### `suggest-playbook.sh` (UserPromptSubmit, non-blocking)
+
+1. Scan all playbooks (same precedence as above).
+2. For each playbook with non-empty `keywords`, test every regex against the prompt. If
+   any matches, the playbook is **suggested**.
+3. Drop playbooks already read in this conversation (transcript grep, same as above).
+4. If any remain, emit a `<system-reminder>` listing them. Always exit 0.
+
+### Fail-open philosophy
+
+Both **playbook** hooks (`require-playbook.sh`, `suggest-playbook.sh`) fail
+**open** — when `yq` is missing, the transcript is unreadable, or a playbook
+frontmatter cannot be parsed, they exit 0 (suggest) or 0 with a warning
+(require) rather than blocking the agent.
+
+The lifecycle hook `init.sh` (`SessionStart`) is the one exception: it
+**blocks** by design (decision #54) on hard errors that the session cannot
+proceed past — missing/invalid config, state corruption, missing git user,
+missing `gh` auth. See `catalog/hooks/README.md` for the full fail-open vs
+blocking matrix.
+
+### No cache
+
+Each hook fire scans the catalog fresh. Playbooks are read sparingly (PreToolUse fires
+only on Write/Edit; UserPromptSubmit fires once per turn) and the catalog is small. A
+cache would add a staleness failure mode without measurably improving latency.
+
+---
+
+## Authoring conventions
+
+- One topic per file. Split when a topic grows beyond a single screen of frontmatter.
+- Project-**specific** rules — a business rule, a quirk of one app — do **not** belong
+  here. Put them in `CLAUDE.md`, a project-local ADR (`docs/adr/`), or `CONTEXT.md`.
+- Reference other playbooks with `[topic](./topic.md)` — relative links so they resolve
+  in any Markdown viewer.
+
+### Iteration
+
+Playbooks evolve with the codebase. The **Architect**'s `playbook-iterate` skill proposes
+edits when a spec collides with an existing playbook (a `T6 PLAYBOOK_CONFLICT` review
+finding) or when a recurring pattern in the code is not yet captured. The Architect
+proposes; the client decides.

package/catalog/schemas/README.md

@@ -0,0 +1,13 @@
+# schemas/ — telemetry & config schemas
+
+Schema definitions the harness writes/validates against. Tier 1 (client-local)
+writes events in these formats from day one so the data is forward-compatible with
+the Tier 2 central backend designed in Fase 1+.
+
+## Documents
+
+| File                                                 | Decision | Status                     | Purpose                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------------------------- | -------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tier2-events.md`](tier2-events.md)                 | #27, #61 | **Authority — P5.**        | Event schema for `events.jsonl`: 9 event types (`session_closed`, `spec_created`, `spec_approved`, `task_done`, `review_rejected`, `bug_post_merge`, `l3_bypass`, `followup_captured`, `step_completed`), the common envelope (`type`, `ts`, `user`, `project`, `task_id`, `harness_version`), and per-field tags (`sensitive`/`internal`/`metric`) for forward-sanitization. |
+| [`tier2-events-history.md`](tier2-events-history.md) | #51      | Seeded at `0.1.0-alpha.0`. | Forward-only per-release deltas (ADDED/REMOVED/DEPRECATED/RENAMED fields, new event types) — supports forward-only, dispatch-on-read. ~30 min/release.                                                                                                                                                                                                                        |
+| `harness.config.schema.json`                         | #53(e)   | Pending (S3).              | JSON Schema generated from the Zod config schema via `zod-to-json-schema`, distributed for IDE autocomplete.                                                                                                                                                                                                                                                                  |

package/catalog/schemas/tier2-events-history.md

@@ -0,0 +1,104 @@
+# Tier 2 events — schema history
+
+> **Forward-only changelog** of the event schema defined in
+> [`tier2-events.md`](tier2-events.md). Readers add aliases here when they care
+> about renamed fields; the schema document is always the current truth (decision
+> \#51). One entry per release that touches the schema. ~30 min/release.
+
+Format per entry (one block per release):
+
+```
+## <version> — <YYYY-MM-DD>
+
+### Added
+- `<event_type>.<field>` — <one-line rationale>
+- `<event_type>` — <new event type rationale>
+
+### Removed
+- `<event_type>.<field>` — <readers that need the value should pin to ≤ <prev-version>>
+
+### Deprecated
+- `<event_type>.<field>` — replaced by `<new_field>`; both written until <future-version>
+
+### Renamed
+- `<event_type>.<old_field>` → `<new_field>` — <rationale>
+```
+
+Empty sections may be omitted.
+
+---
+
+## 0.1.0-alpha.9 — 2026-06-18
+
+### Added
+
+- `review_rejected.attributed_kind` — optional `agent` | `skill` | `playbook`: the
+  kind of component the friction is attributed to (#217). Omitted when the emitter
+  can't attribute.
+- `review_rejected.attributed_name` — optional free string (1-200): the component's
+  name (#217). Free-string by design this phase (measure-then-decide).
+- `step_completed.attributed_kind` — optional, as above (#217).
+- `step_completed.attributed_name` — optional, as above (#217).
+
+### Changed
+
+- **Field-tag model → 5 axes, assigned per `(event_type, field)`** (#226, D9). The
+  old `sensitive` / `internal` / `metric` tags become `local-only` / `identity` /
+  `free-text` / `internal-enum` / `metric`. **No field renamed, added, or removed** —
+  only the axis column changed (the tag is now a property of the occurrence, fixing
+  `reason` = enum in `session_closed` vs free-text in `review_rejected` / `l3_bypass`).
+  The export sanitizer (`src/telemetry/sanitize.ts`) reads these axes: the
+  `anonymous` tier (on by default) drops `user`, `project`, `task_id`,
+  `parent_task_id`, `topic`, and free-text `reason`, keeping enums, metrics, and
+  `attributed_name`. Tier-2 readers of the anonymous corpus therefore see **no
+  per-install identifier** — only counts, durations, enums, and roster names.
+
+---
+
+## 0.1.0-alpha.4 — 2026-06-12
+
+### Added
+
+- `step_completed` — new event type emitted by the Orchestrator at each resolved
+  human checkpoint in step-by-step mode (#176). Fields: `task_id` (required),
+  `step` (required, 1-based `tasks.md` task number), `review_iterations`
+  (required, ≥ 1), `checkpoint_result` (required, `ok` | `changes` |
+  `ok_downgrade`). One event per checkpoint — a "changes" step emits again when
+  it re-checkpoints.
+- `task_done.mode` — optional `all_at_once` | `step_by_step`: the mode chosen at
+  the L1 approval gate (#176). Absent on L2 and on pre-#176 lines.
+- `task_done.steps` — optional count of `step_completed` events for the task
+  (≥ 1). Only meaningful when `mode` is `step_by_step`.
+- `review_rejected.step` — optional 1-based task number when the rejection came
+  from a per-step review (#176). Absent on full-pass and all-at-once rejections.
+
+---
+
+## 0.1.0-alpha.3 — 2026-06-05
+
+### Added
+
+- `followup_captured` — new event type emitted by `/spinoff` (#112) when a
+  non-blocking defect found mid-task is parked as a stub. Fields: `task_id`
+  (required, the stub), `parent_task_id` (optional, the originating task),
+  `severity` (optional, best-effort). Distinct from `bug_post_merge` (post-merge
+  signal) by design.
+
+---
+
+## 0.1.0-alpha.0 — 2026-05-28
+
+Initial schema. The seven event types of this release and their fields are
+listed in `tier2-events.md` (the authority doc tracks the current set, since
+expanded — see later entries).
+
+### Added
+
+- Envelope: `type`, `ts`, `user`, `project`, `task_id` (optional), `harness_version`.
+- `session_closed` — `session_start_ts`, `session_active_h`, `reason`, `auto_close`.
+- `spec_created` — `task_id` (required), `topic`, `requirements`.
+- `spec_approved` — `task_id` (required), `iterations`.
+- `task_done` — `task_id` (required), `level`, `cycle_time_h`, `review_rejections`.
+- `review_rejected` — `task_id` (required), `reason`, `iteration`.
+- `bug_post_merge` — `task_id`, `discovered_h`, `severity`. _(Schema only, emitter lands in P8.)_
+- `l3_bypass` — `topic`, `reason`. _(Schema only, emitter lands in P6.)_