@lemoncode/lemony 0.5.1 → 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

@@ -26,6 +26,8 @@ The design tool is a **projection** of the canonical JSON, never a peer source o
 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,12 +65,37 @@ WARNINGS=()
 # awk/grep/git (preinstalled) cover the rest.
 CONFIG_VERSION=""
 CONFIG_REPO=""
-if [ ! -e "$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 dead link stays
-  # "not found" above and a link to one of these lands here.
+  # 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
@@ -147,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.")
@@ -225,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
@@ -402,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
@@ -519,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
@@ -537,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/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
 

package/catalog/schemas/tier2-events.md

@@ -36,14 +36,14 @@ Every event line starts with this envelope. Per-type fields are added at the
 same top level — there is no nested `payload`, so Zod discriminated unions key on
 `type`.
 
-| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                                 |
-| ----------------- | ------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`            | string | yes      | `internal-enum` | One of the 9 event types listed below. Discriminator.                                                                                                                                                                                                                 |
-| `ts`              | string | yes      | `metric`        | UTC ISO 8601 with `Z` suffix (e.g. `2026-05-28T14:30:00.000Z`). **No local offsets.**                                                                                                                                                                                 |
-| `user`            | string | yes      | `local-only`    | `git config user.email` of the actor. Never exported in any tier.                                                                                                                                                                                                     |
-| `project`         | string | yes      | `identity`      | `task_storage.repo` slug (e.g. `acme/widgets`), from `harness.config.yml`. **Never `OWNER/REPO`** — the CLI refuses to emit while that placeholder is the value (see [Placeholder guard](#placeholder-guard)).                                                        |
-| `task_id`         | string | no       | `identity`      | Task issue id (e.g. `42`) when the event has a task context. Absent on global events; `session_closed` carries it when HEAD is a `harness/<id>-<slug>` task branch. A per-project correlator — only meaningful alongside `project`, so it shares the `identity` axis. |
-| `harness_version` | string | yes      | `metric`        | `version` of the **installed** `@lemoncode/lemony` package — _not_ `vendor_version` from config.                                                                                                                                                                      |
+| Field             | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                                                                       |
+| ----------------- | ------ | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | string | yes      | `internal-enum` | One of the 9 event types listed below. Discriminator.                                                                                                                                                                                                                                                       |
+| `ts`              | string | yes      | `metric`        | UTC ISO 8601 with `Z` suffix (e.g. `2026-05-28T14:30:00.000Z`). **No local offsets.**                                                                                                                                                                                                                       |
+| `user`            | string | yes      | `local-only`    | `git config user.email` of the actor. Never exported in any tier.                                                                                                                                                                                                                                           |
+| `project`         | string | yes      | `identity`      | `task_storage.repo` slug (e.g. `acme/widgets`), from `harness.config.yml`. **Never `OWNER/REPO`** — the CLI refuses to emit while that placeholder is the value (see [Placeholder guard](#placeholder-guard)).                                                                                              |
+| `task_id`         | string | no       | `identity`      | Task issue id (e.g. `42`) when the event has a task context. Absent on global events; `session_closed` carries it when the live branch is a `harness/<id>-<slug>` or `harness/closeout-<id>` task branch. A per-project correlator — only meaningful alongside `project`, so it shares the `identity` axis. |
+| `harness_version` | string | yes      | `metric`        | `version` of the **installed** `@lemoncode/lemony` package — _not_ `vendor_version` from config.                                                                                                                                                                                                            |
 
 ### Placeholder guard
 
@@ -115,8 +115,9 @@ forward-compatible — readers dispatch on `type` and ignore unknowns.
 
 Emitted by `session-close.sh` on `SessionEnd` or `/pause` (manual). One per
 session. The envelope's `task_id` is derived from the live branch at close time
-(`harness/<id>-<slug>` → `<id>`); a session closed on the default branch or a
-detached HEAD carries none.
+(`harness/<id>-<slug>` or `harness/closeout-<id>` → `<id>`) — while a rebase has
+HEAD detached, the branch being rebased; a session closed on the default branch or
+any other detached HEAD carries none.
 
 | Field              | Type    | Required | Axis            | Notes                                                                                                           |
 | ------------------ | ------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
@@ -148,17 +149,18 @@ Emitted by the Orchestrator when it transitions `spec-in-progress → spec-ready
 
 ### 4. `task_done` _(P5)_
 
-Emitted by the Orchestrator at closeout (after `gh pr view` confirms `MERGED`,
-before `git rm` of the task state).
+Emitted by the Orchestrator at closeout **finalize** — after the closeout PR,
+which archives the spec and drops the task's `progress.md`, has merged.
 
-| Field               | Type   | Required | Axis            | Notes                                                                                                                                                |
-| ------------------- | ------ | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                              |
-| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                 |
-| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                          |
-| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                     |
-| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does).        |
-| `steps`             | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total groups after a mid-task downgrade. |
+| Field               | Type   | Required | Axis            | Notes                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------- | ------ | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `task_id`           | string | yes      | `identity`      | Required for this type.                                                                                                                                                                                                                                                                                                                                                                                |
+| `level`             | string | yes      | `internal-enum` | `L1` \| `L2` \| `L3` — the task-fit dial value used.                                                                                                                                                                                                                                                                                                                                                   |
+| `cycle_time_h`      | number | yes      | `metric`        | Wall-clock hours from issue creation to merge. ≥ 0, finite.                                                                                                                                                                                                                                                                                                                                            |
+| `review_rejections` | number | yes      | `metric`        | Count of `review_rejected` events for this `task_id` (≥ 0, int).                                                                                                                                                                                                                                                                                                                                       |
+| `mode`              | string | no       | `internal-enum` | `all_at_once` \| `step_by_step` — the mode chosen at the L1 approval gate. **Absent on L2** (the question only exists where `tasks.md` does), and on an L1 task whose gate choice closeout could not recover.                                                                                                                                                                                          |
+| `steps`             | number | no       | `metric`        | Count of **distinct steps** (distinct `step` values) across this task's `step_completed` events (≥ 1, int). Only meaningful when `mode` is `step_by_step`; < total groups after a mid-task downgrade. Before 0.6.0 it counted every event — see [history](tier2-events-history.md).                                                                                                                    |
+| `checkpoints`       | number | no       | `metric`        | Count of `step_completed` events for this task (≥ 1, int) — one per resolved human checkpoint, so a step sent back counts again. Sent together with `steps`; `checkpoints − steps` is the task's extra checkpoint rounds — normally its `changes` answers at step checkpoints. Not counted: any human gate after a downgrade to all-at-once (it emits nothing), and change requests at the merge gate. |
 
 ### 5. `review_rejected` _(P5)_
 
@@ -211,7 +213,9 @@ post-merge / production signal; conflating them would dirty the post-merge metri
 ### 9. `step_completed` _(step-by-step mode)_
 
 Emitted by the Orchestrator each time a human checkpoint **resolves** in
-step-by-step mode (L1 opt-in, chosen at the approval gate). One event per
+step-by-step mode (L1 opt-in, chosen at the approval gate), through the
+`checkpoint` verb that also makes the resolution's commits — or by hand,
+late, when that call never ran for an answer. One event per
 checkpoint, not per step: a step the human sends back ("changes") emits again
 when it re-checkpoints, with the same `step`. This is the signal that justifies
 (or condemns) the mode — the rate of checkpoints that catch things, and where
@@ -272,7 +276,11 @@ A writer (the `lemony emit` CLI):
 2. Merges per-type fields into the same top level (no nested `payload`).
 3. Validates against the Zod schema for `type` (each schema is `.strict()`,
    so an unknown key — typically a typo'd `--task-iid` flag — **rejects**
-   loud). Never writes a partial line.
+   loud). `task_done` also rejects step counts that contradict each other:
+   `steps`/`checkpoints` on a task whose `mode` is not `step_by_step`,
+   `checkpoints` without `steps`, and `checkpoints < steps`. These rules run at
+   emit time only — readers do not re-check lines already written. Never writes
+   a partial line.
 4. Appends the JSON line via `fs.appendFile` (single `O_APPEND` `write(2)`,
    POSIX-atomic up to `PIPE_BUF`) to `.claude/state/events.jsonl`. Creates the
    file (and parent dir, scaffolded by `install`) when missing.

package/catalog/skills/build-ui/SKILL.md

@@ -10,7 +10,9 @@ invoked-by: [implementer]
 # Build UI
 
 The implementer's **build method**: turn a `ui-handoff.md` (the design contract) plus
-`docs/design-tokens.json` (the token source of truth) into UI code that applies the
+`docs/design-tokens.json` (the token source of truth — or the path `design_tokens.file` names
+in `harness.config.yml`, when set; read that file wherever this skill says
+`docs/design-tokens.json`) into UI code that applies the
 project's tokens correctly, carries the design's point of view instead of generic
 defaults, and is accessible by construction.
 
@@ -44,7 +46,8 @@ v3→v4 jump turns it into a lie); the live model does not. So this skill names
 
 ## Tokens-as-code — the contract
 
-`docs/design-tokens.json` is the **single, client-owned source of truth**, a 3-tier
+`docs/design-tokens.json` is the **single, client-owned source of truth** (or the path
+`harness.config.yml` names in `design_tokens.file`, when set — read that file instead), a 3-tier
 W3C-DTCG model: **primitive** (raw scale values) → **semantic** (intent: `color.surface`,
 `space.inset.md`) → **component** (a component's specific slots). Two rules hold on every
 stack: