@lemoncode/lemony 0.4.1 → 0.5.1

package/catalog/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.1

package/catalog/agents/implementer.md

@@ -54,6 +54,16 @@ what you run, only how many calls carry it.
    behavior (vertical slices, never all-tests-then-all-code). When your invocation
    says **auto-commit is OFF**, the whole run obeys §Staging protocol (below) —
    zero commits, staged save-points.
+   **The checkbox is yours** (L1 — a task with a `tasks.md`; L2 has none). A task's
+   `- [ ]` is its done-marker: flip it to `- [x]` the moment the task reaches green
+   (suite passing), and let the tick ride the task's own commit (auto-commit OFF:
+   the same `git add` — at the human's OK the Orchestrator's pathspec split lands it
+   in the step's state commit beside the code commit; the index is where the two
+   move together) — so the file always says where the work is. Nobody
+   else ticks for you: `lemony review-ledger validate` reports a task still `[ ]` in
+   a group the loop has passed (`unticked-completed-task`) and the human reads it as
+   a forgotten mark **or as work never done** — the honest reason to keep the two in
+   step.
    **Scope: exactly what the invocation hands you.** By default that is the whole
    `tasks.md` list (all-at-once). In **step-by-step mode** the Orchestrator
    invokes you per step — scoped to **one group**, handed **by reference** (the
@@ -124,9 +134,10 @@ iteration only knows what this contract and the worktree tell it:
 
 - **Zero commits, zero pushes.** Never `git commit`, never `git push` — not for
   code, not for state. The Orchestrator commits once the human OKs.
-- **Stage after every green task** — `git add -A` when a checkbox/task reaches
-  green (suite passing). The index is your save-point ladder: everything staged
-  is a proven-green floor.
+- **Stage after every green task** — tick the task's checkbox in `tasks.md`
+  (`- [ ]` → `- [x]`, step 2 of the procedure), then `git add -A`, when a task
+  reaches green (suite passing). The index is your save-point ladder: everything
+  staged is a proven-green floor, and the tick is part of the floor.
 - **Never stage mid-experiment.** A `git add` while red or mid-refactor silently
   **overwrites the save-point** — `git status` looks identical afterwards, and
   recovery yields nameless blobs (practically unrecoverable). Stage only at

package/catalog/agents/orchestrator.md

@@ -365,7 +365,9 @@ numbers still never shift. For each group, in order:
    (fresh context, as always) scoped to **this one group**: give it the branch, the
    task-state paths, and the group's id + header line in `tasks.md` — by reference
    (§Sub-agent invocation), it reads the group's tasks from the file itself (`tdd`
-   skill — checkbox by checkbox with small commits, as always). It commits to the
+   skill — checkbox by checkbox with small commits, as always, and it **ticks each
+   checkbox at green** — the tick rides the task's commit, or its `git add` under
+   auto-commit OFF; the file is the group's progress record). It commits to the
    branch (auto-commit OFF: it **stages** instead of committing — point the
    invocation at the staging protocol in `implementer.md`), logs to `progress.md`,
    and signals done. **No PR yet** — the PR opens after the last group,
@@ -422,13 +424,15 @@ numbers still never shift. For each group, in order:
    gates or the bare real-run floor (`undeclared`).
    Red → **an APPROVE with a red ledger is never relayed**, and a red ledger is not a
    REJECT of the code: the Implementer is not at fault and is **never** re-invoked for
-   it. Route on the `[kind]` lines the verb prints — it closes with
+   the red itself (a human's `changes` at the checkpoint it feeds is the human's call, as
+   at every checkpoint). Route on the `[kind]` lines the verb prints — it closes with
    `N spec-side problem(s) … do not retry the Reviewer while any of these stands.`
    whenever any problem lives outside the sidecar:
 
    - **any spec-side problem** — the verb counts them out loud (`unknown-risk-class`, a
      tag or ref list that did not parse, a duplicated group number, an orphan task, an
-     empty group, a dangling requirement ref, a step with no group) → no retry. They
+     empty group, a dangling requirement ref, a step with no group, a task still
+     `[ ]` in a group the loop has passed) → no retry. They
      live in `tasks.md` / `requirements.md`, which the Reviewer cannot fix: stop and
      bring them to the human as an **anticipated checkpoint** (below) with the verb's
      lines as the content — the spec needs a decision, and the fix routes as a discovery
@@ -436,6 +440,37 @@ numbers still never shift. For each group, in order:
      the sidecar on disk: green → the checkpoint; a sidecar-side red then follows the
      one-retry rule below. The human's `ok` on an anticipated checkpoint is their call,
      as at every gate — what never happens is you relaying a red as an APPROVE.
+     **`unticked-completed-task` is the one spec-side kind that needs no discovery**:
+     the Implementer ticks each task at green, so an unticked task in a passed group
+     is a forgotten mark or work that was never done, and only the human can tell
+     which. Name the task ids in the checkpoint and ask. `ok` = "done, the mark was
+     forgotten" → tick it yourself (`- [ ]` → `- [x]`) and **stage it the moment you
+     do** (`git add .claude/state/tasks/<id>/spec/tasks.md`) — a mediated edit, staged
+     on arrival like a Spec Author update, so the checkpoint contract's spec check
+     (item 4) never reads it as an unconfirmed human spec edit — then re-run the verb.
+     Wherever an OK's composite commits state, the staged tick rides its
+     `.claude/state` half and needs nothing more: every step OK (both knob states),
+     and auto-commit OFF's deferral-ending checkpoint OK, which its pre-gate full pass
+     feeds. **At the merge-gate presentation nothing else commits state before the
+     merge** — the step-8 full pass in either mode, all-at-once under auto-commit ON
+     having had no checkpoint at all — so there, commit it yourself as you stage it,
+     in the same composite turn as the re-run (§Turn economy):
+
+     ```bash
+     git commit -m "task(<id>): tick <T-ids> — human ok on unticked-completed-task" \
+       -- .claude/state/tasks/<id>/spec/tasks.md; \
+       git push   # best-effort — a failure warns, never blocks
+     ```
+
+     A merged `tasks.md` still reading `[ ]` is exactly the harm the kind exists to
+     stop. That post-APPROVE state write moves the stale-approve fingerprint the way
+     the ledger's own write does, and routes as the merge gate's exit-40 rule says
+     (§Merge gate) — a fresh APPROVE re-records the hashes; `--force` stays the
+     human's separate, informed call. `changes` = the
+     task is not done → the normal fix iteration, feedback naming the task. Never tick
+     on your own judgment: the mark is the Implementer's claim, and the verb exists so
+     a missing one is read by a person, not smoothed over by you.
+
    - **anything else** (a problem in the sidecar itself) → re-invoke the **Reviewer**
      (fresh, as always) **once**, with the
      verb's `[kind] message` lines **verbatim** in the spawn prompt — the delta is the
@@ -461,7 +496,12 @@ numbers still never shift. For each group, in order:
    `step_completed` emit (here `review_iterations` is 3) and the same transient
    `awaiting human checkpoint (step N/M)` line in `progress.md` — except you present
    the unresolved disagreement (both positions, the spec slice) instead of a clean
-   step.
+   step. When its content is the verb's `unticked-completed-task` lines, `ok` carries
+   one act before the state commit — tick and stage the named tasks (step 2's routing
+   bullet) — and the transient line names them,
+   `awaiting human checkpoint (step N/M) [unticked: T3, T4]` (step 5), so a cold
+   `/resume` re-presents the same content and owes the same act (the clean-step line
+   carries no suffix).
 
    In auto-commit OFF, `OK` is also the moment the group's single code commit
    lands, and `changes` sends the fresh Implementer to iterate **over the worktree**
@@ -571,8 +611,10 @@ numbers still never shift. For each group, in order:
    step's line is transient — update it in place as the loop progresses
    (`fix-loop iteration K — in progress` while implementing/reviewing,
    `awaiting ledger retry (step N/M, retry 1/1)` while the fresh Reviewer redoes a red
-   ledger, `awaiting human checkpoint (step N/M)` while waiting on the human), then
-   replace it with the resolved outcome:
+   ledger, `awaiting human checkpoint (step N/M)` while waiting on the human — with
+   the `[unticked: T3, T4]` suffix when the checkpoint is the anticipated one an
+   `unticked-completed-task` red raised, in all-at-once too, where the counter is
+   absent), then replace it with the resolved outcome:
 
    ```markdown
    Mode: step-by-step
@@ -611,7 +653,10 @@ spec-side problem to the human, and never an APPROVE relayed on a red ledger. Ou
 the step loop the transient line is `awaiting ledger retry (full pass, retry 1/1)` in
 `progress.md` (no step counter), and "the human" is the gate the pass feeds: the
 auto-commit-OFF checkpoint when there is one, otherwise the merge-gate presentation,
-with the verb's lines as the content.
+with the verb's lines as the content. An `unticked-completed-task` there resolves as
+in step 2's routing bullet — on `ok`, tick and stage the named tasks; at the
+auto-commit-OFF checkpoint the OK's composite commits them, at the merge-gate
+presentation you commit them yourself — then re-run the verb.
 
 ## Checkpoint contract (how a human gate presents work)
 
@@ -668,7 +713,10 @@ contract, not a vibe:
      agent-staged floor, so this check fires only on **unmediated** edits and
      the re-presented checkpoint is clean; an unstaged edit that matches the
      recorded `**Resolution**` in `discoveries.md` is confirmed content — stage
-     it, don't re-raise.
+     it, don't re-raise. The one mediated edit that is **not** a discovery — your
+     own `- [ ]` → `- [x]` tick on the human's `ok` to an `unticked-completed-task`
+     checkpoint (step 2) — is staged the same way, as you make it; it has no
+     `discoveries.md` entry to match, and needs none: the `ok` is its record.
 
    The **spec check runs in both knob states** — in auto-commit ON, run it
    **before** step 3's `awaiting` state commit, which would otherwise silently

package/catalog/agents/reviewer.md

@@ -228,9 +228,15 @@ What the validator enforces in this version, so you never have to guess:
 - **Spec-side problems are reported, never dropped — and they are not yours to fix.** A
   `[risk: …]` tag outside the vocabulary (`unknown-risk-class`), a tag or a `(R<n>)` ref
   list that did not parse, a duplicated group number, a task above the first header, an
-  empty group, a ref `requirements.md` never declares, a step with no group: each names
+  empty group, a ref `requirements.md` never declares, a step with no group, a task
+  still `[ ]` in a group the loop has passed (`unticked-completed-task` — the
+  Implementer's done-marker is missing, and whether the work is too is the human's
+  call, not yours): each names
   a defect in `tasks.md` / `requirements.md`, and the verb counts them out loud as
-  **spec-side**. Finish the ledger (a dangling ref leaves the slice — never invent an
+  **spec-side**. The ticks themselves, wherever a diff shows them (the full pass's PR
+  diff does), are the Implementer's done-marks flipped at green — **not a spec
+  change**: never drift, never a finding on their own. Finish the ledger (a dangling
+  ref leaves the slice — never invent an
   entry for a requirement that does not exist), return your verdict as usual, and name
   them in it — the Orchestrator takes them to the human instead of sending you back.
 

package/catalog/commands/pause.md

@@ -9,8 +9,9 @@ A two-step pause:
 
 1. **Write the resume narrative** so future-you (or whoever resumes) can pick
    up cold:
-   - Read `.claude/state/current-<your-user>.md` and the active task's
-     `progress.md` (if any).
+   - Read the active task's `progress.md` (if any) and the latest note under
+     `.claude/state/sessions/<your-user>/` (if any) — that is where the
+     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.
    - Write `.claude/state/sessions/<your-user>/<ts>-<topic>.md` with this
@@ -19,8 +20,8 @@ A two-step pause:
      ```markdown
      ---
      session_close_ts: <ts>
-     active_task: <issue-id or null>
-     branch: <current branch>
+     active_task: <issue-id or null — the current branch's id: `harness/<id>-<slug>` → `<id>`>
+     branch: <current branch, or (unknown) if HEAD is detached>
      topic: <topic>
      reason: manual
      auto_close: false
@@ -42,7 +43,9 @@ A two-step pause:
      ```
 
 2. **Trigger the session-close hook** so the `session_closed` event lands in
-   `events.jsonl` and `current-<your-user>.md` pointers update:
+   `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
+   `last_close_ts` stamped:
 
    ```bash
    .claude/hooks/session-close.sh --manual

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

@@ -18,7 +18,9 @@ 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

package/catalog/harness.config.schema.json

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

package/catalog/hooks/init.sh

@@ -46,8 +46,17 @@ WARNINGS=()
 # awk/grep/git (preinstalled) cover the rest.
 CONFIG_VERSION=""
 CONFIG_REPO=""
-if [ ! -f "$CONFIG" ]; then
+if [ ! -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.
+  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,7 +147,10 @@ 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.
-CURRENT_BRANCH="$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+# 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')"
 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
   BEHIND="$(git rev-list --count "HEAD..origin/$DEFAULT_BRANCH" 2>/dev/null || echo 0)"
@@ -187,12 +199,23 @@ 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
 ---
-active_task: null
-branch: $(git symbolic-ref --quiet --short HEAD 2>/dev/null || echo "(unknown)")
 session_start_ts: $NOW_ISO
 last_close_ts: ""
 ---
@@ -201,22 +224,45 @@ 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.
-
-## Resume hint
-
-_(One paragraph — what to pick up next. Updated by \`/pause\`.)_
+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
+the narrative resume lives under \`sessions/<user>/\` (written by \`/pause\`).
 EOF
   else
     # Refresh session_start_ts on every orient so close-time math is accurate.
     # awk in-place rewrite of the frontmatter scalar — without this,
     # `session_start_ts` would stay frozen at the first orient and
     # `session_active_h` would be cumulative across every clear/resume.
+    # The same pass drops the dead `active_task` / `branch` scalars a pointer
+    # created by an earlier version still carries — nothing ever updated them,
+    # so they lie (`null` / the init-day branch); the live branch is the source.
+    # Its "Resume hint" section goes too, but ONLY while it is still exactly
+    # the untouched placeholder — the heading, blank lines, the one placeholder
+    # line, and nothing else up to the next heading or EOF (its "Updated by
+    # `/pause`" promise was never kept). Anything a person wrote there — the
+    # placeholder replaced, a paragraph added below it, even a `---` rule —
+    # makes the section theirs and it stays, heading included; so does a
+    # section stripped to its bare heading. Decided by a read-only pre-pass so
+    # the rewrite below never looks ahead; `[[:space:]]*$` tolerates CRLF.
+    PRUNE_HINT="$(awk '
+      inhint && /^---/ { other = 1; next }
+      /^---/ { block++; next }
+      block < 2 { next }
+      /^## Resume hint[[:space:]]*$/ { inhint = 1; seen = 1; next }
+      inhint && /^## / { inhint = 0 }
+      !inhint { next }
+      /^[[:space:]]*$/ { next }
+      /Updated by `\/pause`/ { placeholder++; next }
+      { other = 1 }
+      END { print (seen && placeholder == 1 && !other) ? 1 : 0 }
+    ' "$CURRENT_PATH" 2>/dev/null)"
+    [ "$PRUNE_HINT" = "1" ] || PRUNE_HINT=0
     # 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" '
+      awk -v ts="$NOW_ISO" -v prune="$PRUNE_HINT" '
         /^---/ {
           block++
           if (block == 2 && !seen) print "session_start_ts: " ts
@@ -224,6 +270,10 @@ EOF
           next
         }
         block == 1 && /^session_start_ts:/ { print "session_start_ts: " ts; seen = 1; next }
+        block == 1 && /^(active_task|branch):/ { next }
+        prune && block >= 2 && /^## Resume hint[[:space:]]*$/ { inhint = 1; next }
+        inhint && /^## / { inhint = 0 }
+        inhint { next }
         { print }
       ' "$CURRENT_PATH" > "$tmp" && mv "$tmp" "$CURRENT_PATH" || rm -f "$tmp"
     fi

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

@@ -309,12 +309,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

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

@@ -65,8 +65,6 @@ NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 # (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" '
@@ -89,10 +87,20 @@ read_frontmatter_field() {
 }
 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
 
+# ── Derive the task context from the live branch ───────────────────────────
+# 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')"
+
 # 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
@@ -143,9 +151,9 @@ EMIT_ARGS=(
   --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
+# Only a task branch yields an id; a session closed on `main` (or detached)
+# emits the envelope without `task_id`, as the schema allows.
+if [ -n "$ACTIVE_TASK" ]; then
   EMIT_ARGS+=(--task-id="$ACTIVE_TASK")
 fi
 # Resolve the CLI via the launcher (local devDependency → global → fail-fast)

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

@@ -31,6 +31,20 @@ Empty sections may be omitted.
 
 ---
 
+## 0.4.2 — 2026-09-10
+
+### Changed
+
+- **`session_closed.task_id` — now derived from the live branch at close time**
+  (`harness/<id>-<slug>` → `<id>`); absent on the default branch or a detached
+  HEAD. Previously the field was **never populated** on this event: the emitter
+  read it from a per-dev pointer field nothing ever wrote. **No field renamed,
+  added, or removed** — the envelope's optional `task_id` is simply present from
+  this version on when a session closes on a task branch. Readers bucketing
+  `session_closed` by task should expect the value to appear at this version.
+
+---
+
 ## 0.2.0 — 2026-07-31
 
 ### 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 session/global events. 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 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.                                                                                                                                                                      |
 
 ### Placeholder guard
 
@@ -114,7 +114,9 @@ forward-compatible — readers dispatch on `type` and ignore unknowns.
 ### 1. `session_closed` _(P5)_
 
 Emitted by `session-close.sh` on `SessionEnd` or `/pause` (manual). One per
-session.
+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.
 
 | Field              | Type    | Required | Axis            | Notes                                                                                                           |
 | ------------------ | ------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- |

package/catalog/skills/a11y-audit/SKILL.md

@@ -29,7 +29,9 @@ Run the tiers in order; each adds evidence the next builds on.
   token pair — including any dark-mode override — and exits non-zero on a pair below its
   floor. This is the one a11y measurement doable offline, because colour comes from the
   token file. It is complementary to `lemony design-tokens validate` (validate proves colour
-  is a token reference; contrast proves the pair meets its floor).
+  is a token reference; contrast proves the pair meets its floor). When the project declares
+  `design_tokens.verify` in `harness.config.yml`, the same command also runs the design
+  system's own verifier and forwards its report — read that output as T0 evidence too.
 - **T1 — source a11y lint (rides the project).** The project's own linter usually carries an
   accessibility plugin (`eslint-plugin-jsx-a11y`, Svelte's or Vue's a11y rules). Run the
   project's `lint`; don't reimplement it. Read what it flags.

package/catalog/skills/design-tool-sync/SKILL.md

@@ -70,34 +70,67 @@ variables and the DTCG JSON:
 - `name` — the variable's dotted path. Map it to/from the tool's own grouping separator.
 - `value` for a literal; `ref` for an alias (the name of the variable it points at).
 - `modes` — per-theme overrides (the base theme is `value`/`ref`, not repeated).
+- Every `value` and mode value is a **string** — `"1024"`, not `1024` — and every `ref` a
+  non-empty one; each variable carries a `value` or a `ref` (a `value` beside a `ref` is
+  ignored), and `modes` is an object whose mode names are not blank nor `__proto__`. A name
+  is dot-separated segments, none empty, none starting with `$`, none `__proto__`, not just
+  a tier (`primitive`, `semantic`, `component`), and no two variables share one. The CLI
+  refuses a file that breaks any of these, naming the variable (and the mode, for a mode
+  value).
 
 The CLI maps this to the 3-tier DTCG model: `ref` → an alias `{path}`, `modes` →
-`$extensions["com.lemony.modes"]`, and the tier follows the path (a literal defaults to
-`primitive`, an alias to `semantic` when the name carries no tier).
+`$extensions["com.lemony.modes"]`, and the tier follows the path. A name without a tier
+lands on the one tier `docs/design-tokens.json` already has it in; otherwise a literal
+defaults to `primitive` and an alias to `semantic`. A bare `ref` — or a bare `{alias}` mode
+value — resolves to the tiered path its target lands at in the same neutral file, or to the
+one tier the token file has it in.
 
 ## import — tool → JSON
 
 1. **Read** the tool's variables over MCP and write them to a neutral file (a temp path).
 2. **Preview** the diff (writes nothing):
    `lemony design-tokens import --from=<neutral-file>`. It prints, per token, the target tier
-   and `new` / `changed` (with the old → new value) / `unchanged`.
+   and `new` / `changed` (each thing that changes, old → new: the value, the `$type`, each
+   mode) / `unchanged`. When
+   `docs/design-tokens.json` already fails validation it adds a `Warning:` saying so: the
+   apply will refuse any slice that leaves it failing, so tell the human before curating.
 3. **Present and curate.** Walk the human through it: which new tokens to take, which changes
    to accept, and — where a tool-origin name is ambiguous — whether a literal belongs in
    `primitive` or `semantic`. The human owns the slice.
 4. **Apply** the agreed slice:
    `lemony design-tokens import --from=<neutral-file> --apply --only=<dotted,paths>`.
    This does the additive merge into `docs/design-tokens.json` deterministically (it
-   bootstraps the file if it does not exist yet). Then run `lemony design-tokens validate` to
-   confirm the result is well-formed.
+   bootstraps the file if it does not exist yet and the slice writes something). A changed
+   token keeps what the neutral file does not carry — `$description`, a contrast pairing,
+   other extensions — and an unchanged one is left as it is. A token the tool cannot hold
+   (see export) is never written over: the preview shows it as a change from
+   `(outside the sync: <why>)`, and the apply lists it as not applied. It writes nothing
+   when the merged file would fail validation — typically a `semantic` alias whose
+   `primitive` target is neither in the file nor in the slice: add the target to the same
+   `--only`, or fix the file first. When the neutral file does not carry the target at
+   all, the refusal says so: create it in the tool first, or leave out what references
+   it. An `--only` path no variable lands at is refused rather than skipped. A refusal
+   prints the preview again, so the slice can be re-curated from the paths it lists. Then run
+   `lemony design-tokens validate` to confirm the result is well-formed.
 
 ## export — JSON → tool
 
-1. **Plan.** Read the tool's current variables over MCP into a neutral file, then:
+1. **Plan.** `export` refuses (exit 1) a `docs/design-tokens.json` that fails
+   `lemony design-tokens validate` — fix the file first. Read the tool's current variables
+   over MCP into a neutral file, then:
    `lemony design-tokens export --tool-state=<tool-state> --out=<projection-file>`. It prints
    the additive upsert plan (how many to create, how many to update — **never any deletes**)
    and writes the projection the tool should hold to `<projection-file>`. The `--tool-state`
    is optional; without it every variable is planned as a create (the upsert is idempotent by
-   name either way).
+   name either way). A tool variable named without its tier (`color.brand`) is matched to the
+   path `import` lands it at (`primitive.color.brand`), so when you push, write into that
+   existing variable rather than creating a tiered twin. A token a tool variable cannot hold
+   is not projected: a composite (a shadow, a typography, a cubic Bézier — an object or
+   array `$value`), a token whose modes the neutral format cannot carry (a mode value that
+   is not text, a number or a boolean, a blank or `__proto__` mode name, a modes extension
+   that is not an object), and any alias to one of those. The plan names each as "not
+   projected", with why — say so to the human. `--out` takes a file path (not a pipe, nor
+   the token file itself).
 2. **Confirm.** Show the plan; the human approves.
 3. **Push.** Write the projection's variables into the tool over MCP — create new ones, update
    changed ones, leave tool-only variables untouched.

package/catalog/skills/prd-to-spec/SKILL.md

@@ -215,6 +215,11 @@ The review evidence ledger's validator enumerates each group's review slice from
 refs; a task it cannot read is reported as `malformed-task-refs` — a spec defect that
 pauses the loop, never read as "declares none".
 
+The checkbox itself is the **Implementer's done-marker**: it flips `- [ ]` → `- [x]`
+when the task reaches green, with the task's commit. Write every task `- [ ]`; the same
+validator reports a task still `[ ]` in a group the loop has passed
+(`unticked-completed-task`), so the file tracks the progress its shape promises.
+
 Rules: order so the first task is a tracer bullet; never "write all tests" then
 "write all code"; keep each task small enough to verify on its own. Grouping never
 changes task granularity — checkboxes stay atomic and TDD runs per task; only review

package/catalog/skills/resolve-discovery/SKILL.md

@@ -68,12 +68,12 @@ decision **stated in full** — at this moment it exists nowhere on disk; the en
 `**Resolution**` block is only written at step 4 — plus the `discoveries.md` entry
 **by path** for the surrounding context (it reads the entry itself):
 
-| Artifact changed by the decision                                                        | Owner to invoke                                                                                                                                             |
-| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `spec/requirements.md`, `spec/design.md`, `spec/tasks.md`                               | **Spec Author**                                                                                                                                             |
-| Implementation code, `progress.md`, `notes.md`                                          | **Implementer** (often just the resumed sub-agent)                                                                                                          |
-| A child issue's trace lines, a triage issue's fix plan, the parent partition-plan issue | **Orchestrator** (you) — `gh issue edit --body-file`, read-modify-write (an oversize discovery answered "partition": `.claude/agents/partition.md`)         |
-| `docs/adr/NNNN-<slug>.md`, `docs/architecture.md`, `docs/playbooks/`                    | **Architect** (on-demand) — `write-adr` to record the decision, `update-architecture` to keep the map true, `playbook-iterate` for a `T6 PLAYBOOK_CONFLICT` |
+| Artifact changed by the decision                                                        | Owner to invoke                                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `spec/requirements.md`, `spec/design.md`, `spec/tasks.md`                               | **Spec Author** — except a task's checkbox: `- [ ]` → `- [x]` is the Implementer's done-mark at green (the Orchestrator's on a checkpoint `ok`), never a spec edit |
+| Implementation code, `progress.md`, `notes.md`                                          | **Implementer** (often just the resumed sub-agent)                                                                                                                 |
+| A child issue's trace lines, a triage issue's fix plan, the parent partition-plan issue | **Orchestrator** (you) — `gh issue edit --body-file`, read-modify-write (an oversize discovery answered "partition": `.claude/agents/partition.md`)                |
+| `docs/adr/NNNN-<slug>.md`, `docs/architecture.md`, `docs/playbooks/`                    | **Architect** (on-demand) — `write-adr` to record the decision, `update-architecture` to keep the map true, `playbook-iterate` for a `T6 PLAYBOOK_CONFLICT`        |
 
 Not every resolution needs an artifact update first. If the decision is simply "do X"
 with no change to the contract, skip straight to recording it and resuming. If it