@lemoncode/lemony 0.5.0 → 0.6.0

package/catalog/agents/ui-design.md

@@ -74,7 +74,9 @@ This is opt-in surfacing of the client's own answers, not the harness authoring
 ## Design-tokens & design-tool on-ramp (offer)
 
 `docs/design-tokens.json` and a design-tool connection are **client-owned inputs** — consumed if
-present, never imposed. A repo adopting the harness fresh has neither, and silence there is a dead
+present, never imposed. When `harness.config.yml` sets `design_tokens.file`, the path it names is
+the token file wherever this file says `docs/design-tokens.json`; never create a second file at
+the default. A repo adopting the harness fresh has neither, and silence there is a dead
 end. So when your `grill-ui` interview finds **either absent**, surface it as an opt-in offer (a
 human-facing choice, so it is yours) rather than only an open question:
 

package/catalog/agents/ui-designer.md

@@ -58,7 +58,8 @@ Judge against your taste and the 11-section contract, then **return findings —
   decisions-altitude (not the placeholder template); sections that don't apply are marked
   N/A, not left blank.
 - **Internally consistent.** Dials, layout, components, states and motion agree; §9 sets an
-  a11y target; §11 points at `docs/design-tokens.json` (no invented tokens); §1 personas are
+  a11y target; §11 points at the token file — `docs/design-tokens.json`, or the path
+  `design_tokens.file` names in `harness.config.yml` (no invented tokens); §1 personas are
   coherent and actually shape the decisions.
 - **One verdict.** Return `pass` / `needs-another-pass` with specific findings. The
   Orchestrator resolves them — tighten the handoff, re-ask the human, or record an open
@@ -82,7 +83,8 @@ Reviewer's own shape — a **mechanical pre-pass**, then **judgment**, then **on
   design-aware — that separation is deliberate.
 
 **Token sync (on-demand, not a step).** If the project binds a design tool (a
-`com.lemony.design-tool` provider in `docs/design-tokens.json`), check the drift state
+`com.lemony.design-tool` provider in `docs/design-tokens.json`, or in the file
+`design_tokens.file` names in `harness.config.yml` when set), check the drift state
 (`lemony status`). When an export is pending **and the tool is connected**, the Orchestrator
 offers to project the change and dispatches you to run the **`design-tool-sync`** skill —
 never sync silently, and skip gracefully if the tool isn't connected. The human's explicit
@@ -100,7 +102,8 @@ skill (`ui-handoff-format.md`): (1) personas; (2) aesthetic direction — the di
   variant, state what matters); the full component anatomy only for a novel or critical
   component.
 - **Text-first, tokens by reference.** Screens travel as text — an inventory, a nav/flow
-  map and structural intent; tokens point at `docs/design-tokens.json`, never inlined.
+  map and structural intent; tokens point at the token file (`docs/design-tokens.json`, or
+  `design_tokens.file`), never inlined.
 
 A `Status:` field marks the handoff `in_progress` (design being defined) vs `completed`.
 

package/catalog/commands/pause.md

@@ -1,10 +1,18 @@
 ---
 description: Pause the current session — write a narrative resume + emit session_closed telemetry.
-allowed-tools: Read, Write, Bash(.claude/hooks/session-close.sh --manual), Bash(date -u *)
+allowed-tools: Read, Write, Bash(.claude/hooks/session-close.sh --manual), Bash(.claude/hooks/lib/lemony.sh status --local), Bash(.claude/hooks/lib/lemony.sh checkpoint *), Bash(date -u *), Bash(git diff --stat *), Bash(git ls-files --others *)
 ---
 
 # /pause
 
+**A checkpoint answer comes first.** When the human answered a pending checkpoint
+with this `/pause`, or just before it (`ok`, `changes`, `ok_downgrade`), resolve it
+before step 1, whatever the auto-commit setting, exactly as the orchestrator does
+at any checkpoint (§Checkpoint contract, items 4–5): the spec check and the
+human-delta revalidation first (a red one blocks the OK), on an OK under
+auto-commit ON the human-delta commit, then the resolved `progress.md` line and the `checkpoint` verb.
+Its commits and emit belong to the checkpoint, not to the pause.
+
 A two-step pause:
 
 1. **Write the resume narrative** so future-you (or whoever resumes) can pick
@@ -14,14 +22,19 @@ A two-step pause:
      narrative lives; `current-<your-user>.md` only holds session timestamps.
    - Generate a UTC timestamp slug — run `date -u +%Y-%m-%dT%H:%M:%SZ` and use
      it as `<ts>`. Pick a short topic slug from the work in progress.
+   - Read the task and branch — run `.claude/hooks/lib/lemony.sh status --local`
+     (local reads only, no network call): its `Active task:` and `Branch:` lines
+     are read off the live branch (a task branch, the `harness/closeout-<id>`
+     record branch, or the branch being rebased while a rebase has HEAD
+     detached). If it fails, write `null` and `(unknown)`.
    - Write `.claude/state/sessions/<your-user>/<ts>-<topic>.md` with this
      skeleton (fill the body — what you did, where you are, the next step):
 
      ```markdown
      ---
      session_close_ts: <ts>
-     active_task: <issue-id or null — the current branch's id: `harness/<id>-<slug>` → `<id>`>
-     branch: <current branch, or (unknown) if HEAD is detached>
+     active_task: <the `Active task:` id, or null when it reads (none)>
+     branch: <the `Branch:` name without its parenthesised suffix — (unknown) as printed>
      topic: <topic>
      reason: manual
      auto_close: false
@@ -29,6 +42,8 @@ A two-step pause:
 
      # Session — <topic> (<ts>)
 
+     <auto-commit OFF only — the unstaged-work line, see below>
+
      ## What I did
 
      - …
@@ -42,9 +57,38 @@ A two-step pause:
      - …
      ```
 
+   - **Auto-commit OFF: the note opens with the unstaged work.** When the task
+     runs auto-commit OFF (config pins `implementation.auto_commit: off`, or the
+     task's `progress.md` carries the `Auto-commit: off` line), run — `':/'`
+     scopes both to the whole repository, whatever the shell's directory:
+
+     ```bash
+     git diff --stat -- ':/' ':(top,exclude).claude/state'; \
+       git ls-files --others --exclude-standard --full-name -- ':/' ':(top,exclude).claude/state'
+     ```
+
+     and make the first line under the heading say what the output is, which
+     depends on where the task stands:
+     - **Mid-implementation** (`progress.md` not at `awaiting human checkpoint`):
+       the staged index is the last save-point (green, except the red starting
+       point of a `(red human delta)` fix-loop) and everything unstaged is
+       **unverified by construction** — a hand probe stopped between its mutation
+       and its revert looks exactly like work in progress.
+       `**Unverified (unstaged since the last save-point):** <files + stat summary>`
+       — or `**Unverified:** none` when both print nothing.
+     - **At an `awaiting` checkpoint**: every agent save-point was staged at
+       presentation, so unstaged work is the human's own edits.
+       `**Human delta (unstaged, to revalidate at the checkpoint):** <files + stat summary>`
+       — or `**Human delta:** none`.
+
+     Report only: stage, revert, or fix nothing here (a stage now is the
+     mid-experiment `add` the staging protocol forbids). Task state under
+     `.claude/state` is left out — it is disk-only by design in this mode.
+
 2. **Trigger the session-close hook** so the `session_closed` event lands in
    `events.jsonl` (its `task_id` is derived from the current branch when it is
-   a `harness/<id>-<slug>` task branch) and `current-<your-user>.md` gets its
+   a `harness/<id>-<slug>` or `harness/closeout-<id>` task branch, or is being
+   rebased) and `current-<your-user>.md` gets its
    `last_close_ts` stamped:
 
    ```bash
@@ -54,7 +98,8 @@ A two-step pause:
 The hook prints `git status --porcelain` after emitting — it never
 auto-commits. Decide what (if anything) to stage and commit before leaving.
 Exception — a task running **auto-commit OFF** (orchestrator §Auto-commit
-OFF): do **not** commit; the zero-commit deferral binds `/pause` too.
+OFF): do **not** commit; the zero-commit deferral binds `/pause` too (an answered
+checkpoint was already resolved above, by the `checkpoint` verb).
 Leave the staged save-point untouched (it survives the session; staging
 anything now is the mid-experiment `add` the protocol forbids), note the pause
 in `progress.md` — disk-only, per the mode's contract.

package/catalog/commands/resume.md

@@ -37,7 +37,13 @@ drop `harness:needs-design` and continue toward spec-ready. When `progress.md` r
 exactly there: `awaiting human checkpoint (step N/M)` re-presents that pending
 checkpoint (inspect / run / OK / changes / OK+downgrade; in all-at-once under
 auto-commit OFF the line carries no `(step N/M)` counter — same
-re-entry); a `fix-loop iteration K`
+re-entry). Every answer — `changes` too — resolves in the turn that records it,
+after the human-delta check (orchestrator §Checkpoint contract, item 4), through one
+call, `.claude/hooks/lib/lemony.sh checkpoint <answer> …` (orchestrator
+§Checkpoint contract, item 5): it makes the commits and, step-by-step, the
+`step_completed` emit together (the all-at-once gate omits `--step` and emits
+nothing) — never make them by hand or copy them from `git log`. A
+`fix-loop iteration K`
 line re-enters the per-step implement→review loop at that iteration; an
 `awaiting ledger retry (step N/M, retry 1/1)` line — or its full-pass twin
 `awaiting ledger retry (full pass, retry 1/1)` — re-runs
@@ -71,7 +77,12 @@ makes same-machine resume lossless). From a **different** machine, anything comm
 after the last successful push is unreachable and undetectable (origin is
 self-consistent, just older): resume from the pushed state and tell the human which
 state that is (`progress.md`'s last entry), so a re-run of an already-done review or
-checkpoint is a conscious replay, not a silent assumption. An `in-review` one resumes at the
+checkpoint is a conscious replay, not a silent assumption. Same machine, auto-commit
+OFF, mid-implementation (`progress.md` not at `awaiting human checkpoint`): work found
+**unstaged** in the worktree is **unverified by construction** — never stage or present
+it on sight; the fresh Implementer confirms or redoes it. At an `awaiting` checkpoint,
+unstaged work is the human's own delta instead (authority: the orchestrator §Auto-commit
+OFF). An `in-review` one resumes at the
 **merge gate**: surface the open PR's review comments and run the merge-gate procedure
 (route change-requests back to the Implementer, then offer to post threaded replies —
 authority is the orchestrator). A `closeout-pending` task has **nothing to check out** —

package/catalog/commands/spinoff.md

@@ -16,9 +16,11 @@ code pointer). If empty, ask one short question to capture the symptom, then pro
 
 ## Procedure
 
-1. **Identify the parent task** (best-effort): the task in flight. Recover its id from
-   the current branch (`harness/<id>-<slug>` → `<id>`) or the active task state. If there
-   is no active task, capture with no parent (a deferred stub).
+1. **Identify the parent task** (best-effort): the task in flight. Run
+   `.claude/hooks/lib/lemony.sh status --local` and read its `Active task:` line — it
+   derives the id from the live branch (`harness/<id>-<slug>`, the `harness/closeout-<id>`
+   record branch, or the branch being rebased while a rebase has HEAD detached). If it
+   reads `(none)`, or the command fails, capture with no parent (a deferred stub).
 
 2. **Capture the stub** with the `spinoff` CLI verb via the launcher. In one call it
    opens a `harness:managed` + `harness:status:pending` issue (the level is decided at

package/catalog/commands/sync-design-tokens.md

@@ -18,12 +18,16 @@ Designer; follow the steps there.
   deletes tool-only variables). Preview the plan, push on confirmation, then record the drift
   baseline only after the push succeeds.
 - _empty_ — check the drift state (`lemony status`) and, if an export is pending and the tool
-  is connected, offer `export`; otherwise report the current state.
+  is connected, offer `export`; otherwise report the current state. `status` shows no drift
+  line both when there is no token file and when the file cannot be read or fails
+  validation — tell the two apart with `lemony doctor`'s `design-tool-drift` check.
 
 The design tool is a **projection** of the canonical JSON, never a peer source of truth.
 Detect the tool at runtime: read the `com.lemony.design-tool` binding at the root of
 `docs/design-tokens.json`; if no tool is declared, the project is pure-code and there is
 nothing to sync. If the declared tool's MCP server is not connected, skip gracefully with a
-note — the deterministic drift check still works without it.
+note — the deterministic drift check still works without it. When `harness.config.yml` sets
+`design_tokens.file`, the path it names is the token file wherever this command says
+`docs/design-tokens.json`.
 
 The human reviews every write (to the JSON and to the tool). Never sync silently.

package/catalog/harness.config.schema.json

@@ -93,6 +93,10 @@
         "verify": {
           "type": "string",
           "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
         }
       },
       "additionalProperties": false

package/catalog/hooks/init.sh

@@ -11,6 +11,22 @@
 
 set -u
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/live-branch.sh
+if [ -f "$SCRIPT_DIR/lib/live-branch.sh" ] && [ -r "$SCRIPT_DIR/lib/live-branch.sh" ]; then
+  source "$SCRIPT_DIR/lib/live-branch.sh"
+  LIVE_BRANCH_LIB=1
+else
+  # A hand-copied or partial install without the helper (`lemony install`
+  # copies all of lib/): read HEAD's branch only — a rebase in progress reads
+  # as no branch — and say so once instead of failing on every call.
+  live_branch() {
+    git -C "$1" symbolic-ref --quiet HEAD 2>/dev/null | sed -n 's#^refs/heads/##p'
+  }
+  LIVE_BRANCH_LIB=0
+fi
+
 # 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.
@@ -35,6 +51,9 @@ CONFIG="$REPO_ROOT/harness.config.yml"
 
 ERRORS=()
 WARNINGS=()
+if [ "$LIVE_BRANCH_LIB" -eq 0 ]; then
+  WARNINGS+=(".claude/hooks/lib/live-branch.sh is missing or unreadable — the task branch is read from HEAD only, so a rebase in progress reads as no branch. Run \`lemony repair\` to restore it.")
+fi
 
 # ── Block 1 ─ harness.config.yml present and parseable ─────────────────────
 # Pure-bash validation (no yq): presence of the four keys the harness
@@ -46,8 +65,42 @@ WARNINGS=()
 # awk/grep/git (preinstalled) cover the rest.
 CONFIG_VERSION=""
 CONFIG_REPO=""
-if [ ! -f "$CONFIG" ]; then
+# An install's baseline: a version directory (not a dot entry, not a link) under
+# `.claude/.harness/baseline/` — the CLI's `hasInstallBaseline`. The `baseline/` entry
+# alone is no trace: an ignored file in it keeps it on a branch from before the install.
+has_install_baseline() {
+  local base="$REPO_ROOT/.claude/.harness/baseline" dir
+  # One it may not list is there all the same: "run install" would clobber edits.
+  if [ -d "$base" ] && { [ ! -r "$base" ] || [ ! -x "$base" ]; }; then
+    return 0
+  fi
+  for dir in "$base"/*/; do
+    [ -d "$dir" ] && [ ! -L "${dir%/}" ] && return 0
+  done
+  return 1
+}
+if [ -L "$CONFIG" ] && [ ! -e "$CONFIG" ]; then
+  # `-e` follows the link, so a dead one (or a loop, or one behind a directory it
+  # may not search) read as "not found" — and `lemony install` refuses to write
+  # through a symlink, so "run install" went in a circle. On an installed repo,
+  # install after removing it re-scaffolds over the user's edits: restore first.
+  ERRORS+=("harness.config.yml at $REPO_ROOT is a symlink that does not resolve (its target is missing or cannot be reached, or it loops). Repoint it at the config file, or replace it with a copy of the config (from git history or a backup); remove it and run \`lemony install\` only in a repo that was never installed.")
+elif [ ! -e "$CONFIG" ] && has_install_baseline; then
+  # No config next to an install's baseline: removed from an installed repo, or an
+  # install that did not finish (it writes the config last). "Run install" is wrong
+  # for the first — with no TTY it keeps the vendor copy of every edited file.
+  ERRORS+=("harness.config.yml not found at $REPO_ROOT, but .claude/.harness/baseline exists: the harness was installed here, or an install did not finish. If a \`lemony install\` did not finish here, re-run it; otherwise restore harness.config.yml from git history or a backup (\`lemony install\` would, with no TTY, replace the files you edited with the vendor copy).")
+elif [ ! -e "$CONFIG" ]; then
   ERRORS+=("harness.config.yml not found at $REPO_ROOT. Run \`lemony install\`.")
+elif [ ! -f "$CONFIG" ]; then
+  # There, but not a file awk can read: a directory, or a FIFO it would block on
+  # until something wrote to it. `-e`/`-f` follow a symlink, so a link to one of
+  # these lands here.
+  ERRORS+=("harness.config.yml at $REPO_ROOT is not a regular file (a directory, a FIFO, a socket or a device), so it was not read. Replace it with the config file.")
+elif [ ! -r "$CONFIG" ]; then
+  # A file awk cannot open failed the key check below, so the boot blamed missing keys
+  # under a raw awk error.
+  ERRORS+=("harness.config.yml at $REPO_ROOT cannot be read (check its permissions), so it was not read.")
 elif ! awk '
     { sub(/\r$/, "") }
     /^[^[:space:]#]/ {
@@ -138,12 +191,18 @@ fi
 # ladder, and following `git pull --rebase` with `rebase.autostash` set flattens
 # that index — the documented rollback then reverts to the last commit and the
 # group's whole uncommitted work is gone. So on any other branch: silence.
-# The full ref with `refs/heads/` stripped, not `--short`: the short form
-# lengthens to `heads/<name>` when a tag shares the branch's name, which would
-# fail the `harness/*` test below (same read as `session-close.sh` / `status`).
-CURRENT_BRANCH="$(git symbolic-ref --quiet HEAD 2>/dev/null | sed -n 's#^refs/heads/##p')"
+# Silence too while a rebase has HEAD detached, even a rebase of the default
+# branch: the count would be taken from the half-replayed HEAD, and the advice
+# cannot be followed mid-rebase — hence the attached-HEAD check.
+# `live_branch` (same read as `session-close.sh` / `status`): the full ref
+# with `refs/heads/` stripped — `--short` lengthens to `heads/<name>` when a
+# tag shares the branch's name, failing the `harness/*` test below — or, while
+# a rebase has HEAD detached, the branch being rebased (a rebase of a task
+# branch is not a parked task).
+CURRENT_BRANCH="$(live_branch "$REPO_ROOT")"
 DEFAULT_BRANCH="$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')"
-if [ -n "$DEFAULT_BRANCH" ] && [ "$CURRENT_BRANCH" = "$DEFAULT_BRANCH" ]; then
+if [ -n "$DEFAULT_BRANCH" ] && [ "$CURRENT_BRANCH" = "$DEFAULT_BRANCH" ] \
+  && git symbolic-ref --quiet HEAD >/dev/null 2>&1; 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.")
@@ -190,6 +249,19 @@ if [ "${#ERRORS[@]}" -eq 0 ] && [ -n "$GIT_USER_EMAIL" ]; then
   CURRENT_PATH="$REPO_ROOT/.claude/state/current-$USER_SLUG.md"
   if [ -z "$USER_SLUG" ]; then
     : # path-unsafe slug — pointer write skipped above
+  elif [ -L "$REPO_ROOT/.claude" ] || [ -L "$REPO_ROOT/.claude/state" ]; then
+    # A linked directory takes the pointer, and every refresh after it, out of the
+    # repo — the same write-through the dangling-link branch below refuses.
+    WARNINGS+=(".claude or .claude/state is a symlink, so the session start was not recorded (the pointer would be written wherever it points). Replace it with a directory.")
+  elif [ -e "$CURRENT_PATH" ] && [ ! -f "$CURRENT_PATH" ]; then
+    # There, but not a file: writing to a FIFO blocks until something reads it, and
+    # awk reading one blocks until something writes. The pointer is not critical, so
+    # the boot goes on without it — a warning, not a blocking error.
+    WARNINGS+=(".claude/state/current-$USER_SLUG.md is not a regular file (a directory, a FIFO, a socket or a device), so the session start was not recorded. Remove it; the next session recreates it.")
+  elif [ -L "$CURRENT_PATH" ] && [ ! -e "$CURRENT_PATH" ]; then
+    # A symlink whose target is gone: `-e`/`-f` follow it and see nothing, and the
+    # `cat >` below would create the target wherever the link points.
+    WARNINGS+=(".claude/state/current-$USER_SLUG.md is a symlink whose target is missing, so the session start was not recorded (writing through it would create the file it points at). Remove it; the next session recreates it.")
   elif [ ! -f "$CURRENT_PATH" ]; then
     mkdir -p "$REPO_ROOT/.claude/state"
     cat > "$CURRENT_PATH" <<EOF
@@ -203,7 +275,8 @@ last_close_ts: ""
 Per-dev pointer (gitignored). The lifecycle hooks read \`session_start_ts\`
 to compute \`session_active_h\` and reset it on each SessionStart that orients.
 The active task and its branch are not recorded here — \`session-close.sh\`
-derives them from the live branch (\`harness/<id>-<slug>\`) at close time — and
+derives them from the live branch (\`harness/<id>-<slug>\` or
+\`harness/closeout-<id>\`, the rebasing branch mid-rebase) at close time — and
 the narrative resume lives under \`sessions/<user>/\` (written by \`/pause\`).
 EOF
   else

package/catalog/hooks/lib/live-branch.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# The branch a session is working on, read off live git state — sourced by
+# `session-close.sh` (task id of the auto-close record + `session_closed`) and
+# `init.sh` (the parked-branch nudge). The TS twin is `readLiveBranch`
+# (`src/status/live-branch.ts`, `lemony status`); `live-branch.spec.ts` runs
+# both against the same real repositories.
+#
+# `live_branch <repo-root>` prints the branch name (no `refs/heads/`), or
+# nothing when there is none — never a guess:
+#
+#   1. HEAD's full ref with `refs/heads/` stripped. Not `--short`: the short
+#      form lengthens to `heads/<name>` when a tag shares the branch's name.
+#   2. When HEAD is detached, git's own record of a rebase in progress —
+#      `rebase-merge/head-name` (merge backend, `rebase -i`) or
+#      `rebase-apply/head-name` (apply backend) under the git dir. A conflicted
+#      or stopped rebase detaches HEAD for its whole duration, and that is
+#      exactly when a session is likely to pause. `--absolute-git-dir` resolves
+#      inside a linked worktree. `git am` writes no `head-name`, and a rebase
+#      of an already-detached HEAD records `detached HEAD` — both stay empty,
+#      as does a plain `git checkout --detach` and anything outside a repo.
+
+live_branch() {
+  local root="$1" branch git_dir head_name
+  branch="$(git -C "$root" symbolic-ref --quiet HEAD 2>/dev/null | sed -n 's#^refs/heads/##p')"
+  if [ -z "$branch" ]; then
+    git_dir="$(git -C "$root" rev-parse --absolute-git-dir 2>/dev/null)"
+    if [ -n "$git_dir" ]; then
+      for head_name in "$git_dir/rebase-merge/head-name" "$git_dir/rebase-apply/head-name"; do
+        if [ -f "$head_name" ]; then
+          branch="$(sed -n 's#^refs/heads/##p' "$head_name" 2>/dev/null)"
+          break
+        fi
+      done
+    fi
+  fi
+  printf '%s' "$branch"
+}

package/catalog/hooks/lib/merge-pr.sh

@@ -38,7 +38,8 @@
 #                     APPROVE comment) and verify the PR's current content is
 #                     what that APPROVE reviewed. Three outcomes: tree equal →
 #                     merge; tree differs but diff fingerprint equal → the
-#                     base advanced (update-branch) → merge, informing on
+#                     base advanced (update-branch) and/or only task state
+#                     under .claude/state changed → merge, informing on
 #                     stderr; fingerprint differs → exit 40, never merge. The
 #                     merge call is then pinned with --match-head-commit to
 #                     the exact head the guard verified, so a push racing the
@@ -309,12 +310,13 @@ fi
 # same recipe as playbook-scan.sh): emit `<key>\t<value>` for the uncommented
 # `checks_timeout_secs` / `allow_no_checks` entries — inline comments stripped
 # (on the block header too) and surrounding quotes removed. Any column-0 line
-# ends the block. Absent/unreadable config → baked defaults.
+# ends the block. Absent/unreadable/non-regular config → baked defaults.
 CONFIG_TIMEOUT=""
 CONFIG_ALLOW_NO_CHECKS=""
 read_merge_config() {
   local config="$ROOT/harness.config.yml"
-  [ -r "$config" ] || return 0
+  # `-f` as well as `-r`: a FIFO is readable, and awk on it would hang the merge.
+  { [ -f "$config" ] && [ -r "$config" ]; } || return 0
 
   local key value
   while IFS=$'\t' read -r key value; do
@@ -401,7 +403,14 @@ fi
 # before merge is standing practice and must not invalidate verdicts: a clean
 # base advance changes the tree but not the PR's own diff (verified
 # empirically, including that a base edit to a file the PR also touched DOES
-# change it — exactly the case that needs fresh eyes). `--no-abbrev` is
+# change it — exactly the case that needs fresh eyes). The digest excludes
+# `.claude/state`: the Reviewer writes its evidence ledger and
+# `progress.md` section after posting the APPROVE, by contract, and the
+# Orchestrator keeps writing task state until the merge — none of it is
+# reviewed content, so a commit of it must not read as a stale approve.
+# `:(top,…)` anchors the exclude at the repo root: a bare `:(exclude)` is
+# cwd-relative and silently excludes nothing when the recipe runs from a
+# subdirectory. `--no-abbrev` is
 # load-bearing: --raw abbreviates blob OIDs to a repo-size-dependent width by
 # default, so two machines could digest different bytes for the same diff.
 # The parity of this command with the Reviewer's recipe (reviewer.md) is
@@ -518,9 +527,11 @@ EOF
     fi
     # Canonical fingerprint command — byte-for-byte the Reviewer's recipe
     # (reviewer.md records the APPROVE side with the same pinned flags).
+    # --no-literal-pathspecs: under GIT_LITERAL_PATHSPECS=1 the exclude is read
+    # as a literal path, the diff comes out empty and every head digests alike.
     cur_fp="$(
       set -o pipefail
-      git -C "$ROOT" -c core.quotePath=true diff --raw --no-abbrev --no-renames --no-color "$merge_root" "$head_oid" \
+      git -C "$ROOT" --no-literal-pathspecs -c core.quotePath=true diff --raw --no-abbrev --no-renames --no-color "$merge_root" "$head_oid" -- ':(top,exclude).claude/state' \
         | git -C "$ROOT" hash-object --stdin
     )"
     if [ $? -ne 0 ] || [ -z "$cur_fp" ]; then
@@ -536,7 +547,7 @@ EOF
       echo "A human's informed \"merge anyway\" re-runs with --force."
       fail 40
     fi
-    warn "stale-approve guard: the tree differs from the APPROVE on issue #$APPROVE_ISSUE but the diff fingerprint matches — the base advanced (e.g. update-branch); merging the approved content on the new base."
+    warn "stale-approve guard: the tree differs from the APPROVE on issue #$APPROVE_ISSUE but the diff fingerprint matches — the base advanced (e.g. update-branch) and/or only task state under .claude/state changed; merging the approved content."
   fi
 
   # Pin the merge to the exact head this guard verified: a push landing

package/catalog/hooks/lib/playbook-scan.sh

@@ -39,7 +39,8 @@
 # which would breach the per-fire budget) and with no materialized state file to
 # go stale before an `update` command exists (P7). Falls back to the baked
 # defaults when the config, its `paths` block, or a key is absent or commented
-# out (fresh clone, the vendor repo dogfooding itself, an un-customized install).
+# out (fresh clone, the vendor repo dogfooding itself, an un-customized install),
+# and when the config is not a regular file.
 _resolve_playbook_dirs() {
   local repo_root="$1"
   local home_dir="$2"
@@ -47,7 +48,8 @@ _resolve_playbook_dirs() {
   PLAYBOOKS_GLOBAL_DIR="$home_dir/.claude/playbooks"
 
   local config="$repo_root/harness.config.yml"
-  [ -r "$config" ] || return 0
+  # `-f` as well as `-r`: a FIFO is readable, and awk on it would hang the hook.
+  { [ -f "$config" ] && [ -r "$config" ]; } || return 0
 
   # One awk pass: within the top-level `paths:` block, emit `<key>\t<value>` for
   # the (uncommented) `playbooks` / `playbooks_global` entries — inline comments

package/catalog/hooks/session-close.sh

@@ -12,6 +12,22 @@
 
 set -u
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/live-branch.sh
+if [ -f "$SCRIPT_DIR/lib/live-branch.sh" ] && [ -r "$SCRIPT_DIR/lib/live-branch.sh" ]; then
+  source "$SCRIPT_DIR/lib/live-branch.sh"
+  LIVE_BRANCH_LIB=1
+else
+  # A hand-copied or partial install without the helper (`lemony install`
+  # copies all of lib/): read HEAD's branch only — a rebase in progress reads
+  # as no branch — and say so once instead of failing on every call.
+  live_branch() {
+    git -C "$1" symbolic-ref --quiet HEAD 2>/dev/null | sed -n 's#^refs/heads/##p'
+  }
+  LIVE_BRANCH_LIB=0
+fi
+
 MANUAL=0
 for arg in "$@"; do
   case "$arg" in
@@ -93,13 +109,16 @@ fi
 # The pointer never carried a real `active_task` / `branch` — nothing in the
 # contract wrote them after init, so every auto-close record copied `null` /
 # the init-day branch. The branch is the source of truth: the Orchestrator
-# works every task on `harness/<id>-<slug>`, so HEAD names the task. The full
-# ref is read and `refs/heads/` stripped rather than `--short`: the short form
-# lengthens to `heads/<name>` when a tag shares the branch's name, which would
-# silently drop the id. Empty (→ `(unknown)`, no task) on a detached HEAD, a
-# rebase in progress, or outside a repo — never a stale guess.
-TASK_BRANCH="$(git -C "$REPO_ROOT" symbolic-ref --quiet HEAD 2>/dev/null | sed -n 's#^refs/heads/##p')"
-ACTIVE_TASK="$(printf '%s' "$TASK_BRANCH" | sed -n 's#^harness/\([0-9][0-9]*\)-..*$#\1#p')"
+# works every task on `harness/<id>-<slug>` and closes it out on
+# `harness/closeout-<id>`, so the branch names the task. `live_branch` reads
+# HEAD, or the rebasing branch while a rebase has HEAD detached; empty
+# (→ `(unknown)`, no task) on any other detached HEAD or outside a repo —
+# never a stale guess.
+TASK_BRANCH="$(live_branch "$REPO_ROOT")"
+if [ "$LIVE_BRANCH_LIB" -eq 0 ]; then
+  echo "session-close: .claude/hooks/lib/live-branch.sh is missing or unreadable — the task branch was read from HEAD only (a rebase in progress reads as no branch). Run \`lemony repair\` to restore it." >&2
+fi
+ACTIVE_TASK="$(printf '%s' "$TASK_BRANCH" | sed -n -e 's#^harness/\([0-9][0-9]*\)-..*$#\1#p' -e 's#^harness/closeout-\([0-9][0-9]*\)$#\1#p')"
 
 # 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.

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

@@ -27,11 +27,42 @@ Format per entry (one block per release):
 - `<event_type>.<field>` — <semantics-only change: shape untouched, meaning/unit changed>
 ```
 
-Empty sections may be omitted.
+Empty sections may be omitted. `<version>` is the release that ships the entry —
+written ahead, under the version the train expects; the version cut fails if a heading
+names a version it neither ships nor already shipped (rename it to the real one).
 
 ---
 
-## 0.4.2 — 2026-09-10
+## 0.6.0 — 2026-09-27
+
+### Added
+
+- `task_done.checkpoints` — optional count of `step_completed` events for the
+  task (≥ 1): one per resolved human checkpoint, so a step the human sent back
+  counts again. Carries the number `task_done.steps` reported before this
+  version. Sent with `steps` on step-by-step tasks; `checkpoints − steps` is the
+  task's extra checkpoint rounds — normally its `changes` answers at step
+  checkpoints. `lemony emit` refuses a `task_done` whose counts contradict each
+  other (see the Writer contract); lines already written are not re-checked.
+
+### Changed
+
+- **`task_done.steps` — now counts distinct steps**, not `step_completed`
+  events. Before this version the Orchestrator counted every event, including
+  checkpoints that ended in `changes`, so a task with 4 groups could report 10.
+  Shape untouched; readers comparing `steps` across versions should treat
+  earlier lines as checkpoint counts (the same unit as `checkpoints`), not
+  group counts.
+
+- **`session_closed.task_id` — present in two more task contexts**: on a
+  `harness/closeout-<id>` branch (the `task-closeout` record branch), and while a
+  rebase has HEAD detached (the id of the branch being rebased, read from git's
+  own rebase record). Shape untouched; the value simply appears where it used to
+  be absent.
+
+---
+
+## 0.5.0 — 2026-09-10
 
 ### Changed