agent-harness-kit 0.11.0 → 0.11.2

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.11.0"
+        "ref": "v0.11.2"
       },
-      "version": "0.11.0",
+      "version": "0.11.2",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/README.md

@@ -33,9 +33,11 @@ Option B: install as a Claude Code plugin
 
 ## What ships
 
-- 10 skills (`inspect-module`, `add-feature`, `garbage-collection`,
-  `propose-harness-improvement`, `write-skill`, `debug-flow`, `eval-runner`,
-  `add-adr`, `doc-drift-scan`, `structural-test-author`)
+- 17 skills (`add-adr`, `add-feature`, `debug-flow`, `deliver-html`,
+  `doc-drift-scan`, `eval-runner`, `garbage-collection`, `i18n-add-locale`,
+  `inspect-app`, `inspect-module`, `map-domain`,
+  `propose-harness-improvement`, `refactor-feature`, `review-this-pr`,
+  `setup-nightly-eval`, `structural-test-author`, `write-skill`)
 - 5 read-only review subagents (`architecture-reviewer`, `security-reviewer`,
   `reliability-reviewer`, `performance-reviewer`, `api-consistency-reviewer`)
 - 1 PostToolUse hook (structural-test on every edit) + 1 Stop hook
@@ -60,6 +62,12 @@ Option B: install as a Claude Code plugin
 | `/doc-drift-scan`                | Find stale path/command references in `docs/`            |
 | `/debug-flow`                    | Run the failing flow before fixing it                    |
 | `/deliver-html`                  | Ship an analysis/audit/plan as a self-contained HTML     |
+| `/i18n-add-locale <code>`        | Scaffold a new translation locale for skills + CLAUDE.md |
+| `/inspect-app`                   | Boot dev server + drive the failing flow before edits    |
+| `/map-domain`                    | Render layer config + flag config-vs-filesystem drift    |
+| `/refactor-feature`              | Restructure steps in `feature_list.json` with proof gate |
+| `/review-this-pr`                | Deterministic diff review against the current base       |
+| `/setup-nightly-eval`            | Enable the nightly eval GitHub Actions workflow          |
 
 ## Philosophy (5 axioms)
 
@@ -104,7 +112,7 @@ your-repo/
 ├── harness.config.json
 ├── .claude/
 │   ├── settings.json
-│   ├── skills/                        # 10 skills as SKILL.md files
+│   ├── skills/                        # 17 skills as SKILL.md files
 │   ├── agents/                        # 5 reviewer personas
 │   └── hooks/hooks.json
 ├── .harness/
@@ -159,7 +167,7 @@ agent-harness-kit --version
 What this kit **does** differentiate from bare claude-cli (anecdotal + design-level):
 
 - Opinionated CLAUDE.md template (50–80 lines) so context isn't blown on style
-- 10 skills (`/add-feature`, `/garbage-collection`, `/propose-harness-improvement`, …) that codify Hashimoto/OpenAI rituals
+- 17 skills (`/add-feature`, `/garbage-collection`, `/propose-harness-improvement`, …) that codify Hashimoto/OpenAI rituals
 - 5 read-only review subagents for cheap second-opinion passes
 - `feature_list.json` + ADR template + GC ritual for solo-scale planning hygiene
 - Solo-dev cost defaults (~$2/day) and per-run budget enforcement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {
@@ -42,7 +42,8 @@
     "lint": "echo 'no-op (kit is plain ESM JS)'",
     "selftest": "node bin/cli.mjs --version",
     "harness:eval": "node src/templates/_adapter-typescript/harness/eval-runner.mjs",
-    "harness:check": "node scripts/kit-structural-check.mjs"
+    "harness:check": "node scripts/kit-structural-check.mjs",
+    "check:skill-count": "node scripts/check-skill-count.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/src/templates/.claude/keybindings.json.example

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
+  "$docs": "https://code.claude.com/docs/en/keybindings",
+  "$comment": "agent-harness-kit sample. RENAME to ~/.claude/keybindings.json after editing. Claude Code's keybinding action list is FIXED — there is no action that runs a slash command (no `chat:runCommand` or similar), so we cannot bind keys to /gc, /add-feature, etc. The bindings below tune the chat workflow only. To run a slash command, type `/` and use autocomplete — that is the supported UX.",
+  "bindings": [
+    {
+      "context": "Chat",
+      "bindings": {
+        "ctrl+e": "chat:externalEditor"
+      }
+    },
+    {
+      "context": "Global",
+      "bindings": {
+        "ctrl+shift+t": "app:toggleTodos",
+        "ctrl+shift+r": "app:toggleTranscript"
+      }
+    }
+  ]
+}

package/src/templates/.claude/skills/setup-nightly-eval/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: setup-nightly-eval
+description: Use this skill when the user wants to schedule the harness eval to run every night, asks "how do I set up nightly evals", "schedule the eval", "run evals on a cron", or "nightly regression for the harness". The kit already ships a GitHub Actions workflow at .github/workflows/eval-nightly.yml — this skill walks the user through enabling it (secret setup, smoke run via workflow_dispatch, verifying the first scheduled run). Do NOT use this skill to "remind me to run eval every night in this Claude session" — that is the /loop skill or CronCreate (which is session-only), a different concern.
+allowed-tools: Read, Bash(gh:*), Bash(ls:*), Bash(cat:*), Bash(test:*)
+suggested-turns: 4
+---
+
+## Background — why GitHub Actions, not CronCreate
+
+A common request is "use CronCreate to run the eval every night". That
+does not do what the user wants:
+
+- `CronCreate` jobs live only in the **current Claude Code session**.
+  Closing the REPL deletes them. Auto-expire after 7 days regardless.
+- Jobs only fire while the REPL is **idle**, not when the laptop is
+  asleep or off.
+- They run *Claude turns*, which spend tokens for every fire.
+
+For a real nightly cadence ("runs at 6am whether I'm at the keyboard or
+not"), the right substrate is OS-level cron / launchd / GitHub Actions.
+This kit ships a GitHub Actions workflow as the default because:
+
+1. No local daemon to babysit.
+2. Free for public repos and within the free tier for most private ones.
+3. Results land in workflow artifacts — visible from anywhere.
+
+## When to use
+
+Trigger phrases (English / Vietnamese):
+
+- "set up nightly eval" / "lập lịch eval mỗi đêm"
+- "schedule the harness eval"
+- "make the eval run on a cron"
+- "nightly regression for the harness"
+
+Do **NOT** invoke for:
+
+- One-off ad-hoc eval runs — use `/eval-runner` directly.
+- In-session polling ("re-run every 10 min until I say stop") — that's
+  the `/loop` skill.
+- Local-machine cron setup (launchd / crontab) — that path is on the
+  user's machine and a skill cannot install OS daemons. Print the
+  recipe and let them paste it.
+
+## Steps
+
+1. **Verify the workflow file exists.** It ships via `installCi: true`.
+
+   ```bash
+   test -f .github/workflows/eval-nightly.yml && echo OK || echo MISSING
+   ```
+
+   If MISSING: the user opted out of CI files at scaffold time. Tell
+   them to re-run `agent-harness-kit upgrade --ci` (or to manually copy
+   from `node_modules/agent-harness-kit/src/templates/_ci/`).
+
+2. **Check the eval transport.** The workflow defaults to `mock`
+   transport unless `ANTHROPIC_API_KEY` is set in repo secrets. Decide
+   with the user:
+
+   - **Mock (free):** smoke-tests the eval runner shape — catches a
+     broken JSONL writer, but does not exercise the model. Good
+     default for forks / OSS.
+   - **claude-cli (real, costs tokens):** runs the actual model on
+     each task. Catches regressions caused by prompt/skill changes.
+     Costs ~$0.05–0.50/night depending on task set size.
+
+3. **(If real transport) ensure the secret is set:**
+
+   ```bash
+   gh secret list | grep ANTHROPIC_API_KEY
+   ```
+
+   If absent, ask the user to set it via:
+
+   ```bash
+   gh secret set ANTHROPIC_API_KEY
+   # paste the key when prompted (it never appears in shell history)
+   ```
+
+4. **Trigger a first manual run** via `workflow_dispatch` so the user
+   does not wait 24h to confirm the wiring:
+
+   ```bash
+   gh workflow run eval-nightly.yml --field set=quick --field transport=mock
+   # then watch:
+   gh run watch
+   ```
+
+5. **Print the contract.** What the user just enabled:
+
+   ```
+   ### Nightly eval enabled
+   **Workflow:** .github/workflows/eval-nightly.yml
+   **Cron:** 0 6 * * * UTC (offset: see `gh run list` for actual fire times)
+   **Transport:** mock | claude-cli
+   **Set:** quick (3 tasks) | full (all tasks)
+   **Results:** uploaded as `eval-results` artifact on each run
+   ```
+
+## Output contract
+
+The skill prints a single block matching the shape above. Do not edit
+the workflow file from here — if the user wants to change the cron, the
+task set, or the transport default, they edit
+`.github/workflows/eval-nightly.yml` directly (it is a normal yml file,
+not a templated artifact, after install).
+
+## When the workflow file is owned by the kit
+
+Re-running `agent-harness-kit upgrade` will refresh
+`.github/workflows/eval-nightly.yml`. If the user has hand-tuned cron
+or transport defaults, mention this — they should either:
+
+- Move their customisation into `harness.config.json#evals` (kit reads
+  it on next render) and let the workflow stay vanilla, or
+- Document the customisation in a comment so the next upgrade does not
+  silently overwrite it.

package/src/templates/docs/env-vars.md

@@ -0,0 +1,54 @@
+# Environment variables
+
+Every kit hook and side-car honors one or more `AHK_*` env vars for opt-out,
+debugging, or non-default behavior. Defaults are tuned for "just works" —
+override only when you have a specific reason.
+
+## Opt-out
+
+| Var | Default | Effect |
+| --- | --- | --- |
+| `AHK_DISABLE_TELEMETRY` | unset | When `1`, the `telemetry-on-skill` and `subagent-stop` hooks exit before reading stdin — no `.harness/telemetry.jsonl` is created. Use when you do not want per-skill activity recorded. |
+| `AHK_DISABLE_NOTIFY` | unset | When `1`, the `notify-on-block` hook skips the OS-native notification (osascript / notify-send). The telemetry row still logs the notification event. |
+| `AHK_DISABLE_HTML_OPEN` | unset | When `1`, `/deliver-html` writes the HTML file but does not auto-open it in the browser. Also implied when `CI=true`. |
+| `AHK_DISABLE_HTML_NUDGE` | unset | When `1`, suppresses the inline reminder that `/deliver-html` is available for analysis-style tasks. |
+| `AHK_DISABLE_JQ` | unset | When `1`, hooks pretend `jq` is not on `$PATH` and use the Node fallback (`scripts/_lib/json-pick.mjs`). Used by tests to exercise the fallback path. |
+
+## Bypass (audited)
+
+| Var | Default | Effect |
+| --- | --- | --- |
+| `AHK_ALLOW_BYPASS` | unset | When `1`, `userprompt-guard`, `pretooluse-bash-guard`, and `pretooluse-edit-guard` allow the action through but append a record to `.harness/bypass.log` (timestamp + sha + reason + payload). The bypass leaves a paper trail so it cannot be silent. Use only with explicit intent — e.g. a mass-rename refactor that legitimately touches `.claude/`. |
+| `AHK_HOOK_MODE` | unset | When `warn`, every gate hook (structural-test-on-edit, pretooluse-edit-guard, subagent-stop) logs the would-be violation to stderr but does not deny. Useful for one-off debugging; do not leave set in normal use. |
+
+## Tuning
+
+| Var | Default | Effect |
+| --- | --- | --- |
+| `AHK_TELEMETRY_MAX_LINES` | `5000` | Soft cap on `.harness/telemetry.jsonl` size. The `telemetry_append` helper rotates via `tail -n <N>` once the file grows past this number of lines. Set `0` to disable rotation entirely. Numeric only — non-numeric values fall back to the default rather than failing the hook. |
+| `AHK_HEADLESS_RECOVER` | `0` | When `1`, the Stop hook spawns `claude -p` for one turn of recovery on failure. Costs tokens; off by default. Persistent equivalent: `harness.config.json#recovery.headless`. |
+| `AHK_RECOVERY_LOCK_STALE_SECS` | `300` | How long the Stop-hook recovery lock is considered stale before a new recovery attempt can take it. Prevents stuck locks after a killed session. |
+| `AHK_STATUSLINE_NO_COLOR` | unset | When `1`, the statusline emits plain text — no ANSI color escapes. Useful on terminals that do not render colors well, or when piping the output. |
+
+## Where each variable lives
+
+```
+AHK_DISABLE_TELEMETRY  → scripts/telemetry-on-skill.sh, scripts/subagent-stop.sh
+AHK_DISABLE_NOTIFY     → scripts/notify-on-block.sh
+AHK_DISABLE_HTML_OPEN  → .claude/skills/deliver-html/scripts/wrap-html.mjs
+AHK_DISABLE_HTML_NUDGE → .claude/skills/deliver-html/SKILL.md
+AHK_DISABLE_JQ         → scripts/_lib/jp.sh (probed by every hook that parses JSON)
+AHK_ALLOW_BYPASS       → scripts/userprompt-guard.sh, scripts/pretooluse-*.sh
+AHK_HOOK_MODE          → scripts/structural-test-on-edit.sh, scripts/pretooluse-edit-guard.sh, scripts/subagent-stop.sh
+AHK_TELEMETRY_MAX_LINES→ scripts/_lib/telemetry.sh (used by telemetry-on-skill, subagent-stop, notify-on-block)
+AHK_HEADLESS_RECOVER   → scripts/precompletion-checklist.sh
+AHK_STATUSLINE_NO_COLOR→ scripts/statusline.mjs
+```
+
+## Disabling vs. removing
+
+Prefer env-var opt-out over removing a hook from `.claude/settings.json` —
+the kit's structural-test and version-sync checks expect every hook listed in
+`hooks.json` to be present. Removing a hook leaves the index claiming a
+contract the file system no longer fulfills, and `agent-harness-kit upgrade`
+will keep re-installing it.

package/src/templates/docs/memory-cheatsheet.md

@@ -0,0 +1,82 @@
+# Auto-memory cheat sheet
+
+Claude Code maintains a per-project memory directory at
+`~/.claude/projects/<repo-slug>/memory/`. It persists across sessions and is
+automatically loaded into the next conversation. The kit does **not**
+manage this — Claude Code does. This file is a cheat sheet on when to push
+something into it and when to leave it out.
+
+## The four types
+
+| Type | When to write | Half-life | Example |
+| --- | --- | --- | --- |
+| **user** | You learn something durable about the person you're working with — role, expertise, team, preferences | months to years | "data scientist, 10 years Go, new to React" |
+| **feedback** | The user corrects an approach ("don't X") *or* validates an unusual choice ("yes the bundled PR was right") | months | "integration tests must hit a real DB, not mocks — burned by mock/prod divergence in Q3" |
+| **project** | A fact about the work that the codebase itself does not show — deadlines, stakeholder decisions, the *why* behind a refactor | weeks to months | "auth rewrite is driven by legal compliance, not tech debt — scope toward compliance" |
+| **reference** | A pointer to an external system — Linear project, Grafana dashboard, on-call runbook | until that system moves | "pipeline bugs in Linear project INGEST" |
+
+## What's actually worth saving
+
+Save when **all three** apply:
+
+1. **Non-obvious from the code.** If `git log` or reading the file shows
+   it, the memory is dead weight.
+2. **Survives across sessions.** Today's in-progress task is not memory —
+   it's a task list.
+3. **Decision-shaping.** A future-you (or future-Claude) would behave
+   differently knowing it.
+
+Trigger words from the user that mean "save this":
+
+- "remember that …"
+- "next time, do X / don't do X"
+- "this is how we always do it"
+- "the reason is …"
+
+## What's NOT worth saving
+
+- Code patterns, file paths, architecture diagrams — re-read the code.
+- Git history, "who changed X last week" — `git log` is authoritative.
+- Today's debug recipe — the fix lives in the commit; the commit message
+  has the context.
+- A list of files you just edited — the diff has it.
+- Anything documented in `CLAUDE.md` — it's already loaded.
+
+Reject the request even if the user explicitly asks. Bigger memory is
+*not* better memory — every dead entry is noise the next session will
+have to scan past.
+
+## Working with what's there
+
+Claude Code loads `MEMORY.md` (the index) into every conversation. So:
+
+- If you want a memory honored, make sure its index line is concise and
+  specific. Bad: `notes.md — stuff`. Good: `feedback_tests.md — never
+  mock the database in integration tests`.
+- If a memory turns out wrong or stale, ask Claude to remove or update it
+  — don't let it accumulate.
+- Memory is **not** automatically synced across machines. If your
+  workflow spans laptops, treat it as scratch, not source-of-truth.
+
+## Privacy and scope
+
+- Memory lives in `~/.claude/` — local-only. Nothing is uploaded.
+- A project-scoped memory is keyed by repo slug. Cloning the repo on a
+  new machine does **not** carry memory over.
+- If a memory contains something sensitive (credentials, customer names),
+  delete it. The kit's `userprompt-guard` hook does not see memory; the
+  burden of redaction is on you.
+
+## Related kit features
+
+- The **Stop hook** writes a JSONL row to `.harness/telemetry.jsonl` on
+  every Skill invocation — that is observability for the kit, not memory.
+- The **SessionStart hook** inject branch + uncommitted diff + current
+  feature as `additionalContext`. That is per-session context, not
+  memory.
+- The **PROGRESS.md** file at `.harness/PROGRESS.md` is the human-readable
+  session log appended by `SessionEnd`. Useful next-day rehydration; not
+  memory.
+
+Memory ≠ context. Memory persists. Context is rebuilt every session from
+files in the repo.

package/src/templates/scripts/_lib/jp.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# _lib/jp.sh — source-only library. DO NOT execute directly.
+#
+# Provides three shared helpers used by every hook script that parses Claude
+# Code's JSON stdin:
+#
+#   have_jq        — true iff jq is on PATH AND not disabled via env
+#   have_jp        — true iff EITHER jq OR (node + _lib/json-pick.mjs) is usable
+#   jp <expr> [f]  — run a jq-subset expression, preferring jq when present,
+#                    else the Node fallback. Accepts optional file arg (some
+#                    callers pass it; most read from stdin).
+#
+# Why this exists: the same ~14 lines were duplicated across 12 hook scripts.
+# Single source of truth so fixing one bug (e.g. the "json-pick.mjs only
+# supports one `// default` per expression" footgun documented in
+# session-end.sh.hbs) only needs one edit, not twelve.
+#
+# Sourcing convention — the calling script MUST set _LIB_DIR before . :
+#
+#   SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+#   _LIB_DIR="$SCRIPT_DIR/_lib"
+#   . "$_LIB_DIR/jp.sh"
+#
+# Env vars:
+#   AHK_DISABLE_JQ=1 → pretend jq is missing; forces the Node fallback path.
+#                      Lets us test the fallback on machines that have jq.
+
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 \
+    && [ -f "$_LIB_DIR/json-pick.mjs" ] \
+    && return 0
+  return 1
+}
+
+jp() {
+  if have_jq; then
+    if [ -n "${2:-}" ]; then jq -r "$1" "$2"
+    else jq -r "$1"
+    fi
+  else
+    if [ -n "${2:-}" ]; then
+      node "$_LIB_DIR/json-pick.mjs" "$1" "$2"
+    else
+      node "$_LIB_DIR/json-pick.mjs" "$1"
+    fi
+  fi
+}

package/src/templates/scripts/_lib/telemetry.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# _lib/telemetry.sh — source-only library. DO NOT execute directly.
+#
+# Provides telemetry_append <jsonl-line> — write one line to
+# .harness/telemetry.jsonl and rotate when the file grows past
+# AHK_TELEMETRY_MAX_LINES (default 5000).
+#
+# Why centralised:
+#   - Two hooks append (telemetry-on-skill, notify-on-block). Rotation logic
+#     written once = one place to fix when the file format evolves.
+#   - harness-report.mjs only ever inspects the last 14 days; older lines are
+#     pure I/O cost. Bounding lines bounds report time at O(1).
+#
+# Env vars:
+#   AHK_DISABLE_TELEMETRY=1     → caller is expected to early-exit; this
+#                                 helper does NOT re-check (avoids double
+#                                 work) — gate in the caller.
+#   AHK_TELEMETRY_MAX_LINES=N   → cap (default 5000). Set 0 to disable
+#                                 rotation entirely (keep unbounded).
+
+telemetry_append() {
+  local line="$1"
+  [ -z "$line" ] && return 0
+  mkdir -p .harness
+  printf '%s\n' "$line" >> .harness/telemetry.jsonl
+
+  local limit="${AHK_TELEMETRY_MAX_LINES:-5000}"
+  # 0 = caller opted out of rotation explicitly.
+  [ "$limit" = "0" ] && return 0
+  # Non-numeric → fall back to default rather than failing the hook.
+  case "$limit" in
+    ''|*[!0-9]*) limit=5000 ;;
+  esac
+
+  # wc -l is sub-millisecond on files we care about (< 1MB at the default
+  # cap). Cheap enough to run every append; avoids needing a daemon.
+  local lines
+  lines=$(wc -l < .harness/telemetry.jsonl 2>/dev/null || echo 0)
+  if [ "$lines" -gt "$limit" ]; then
+    # tail to tmp + mv = atomic on POSIX. Reader can't catch a half-written
+    # file mid-rotate.
+    tail -n "$limit" .harness/telemetry.jsonl > .harness/telemetry.jsonl.tmp \
+      && mv .harness/telemetry.jsonl.tmp .harness/telemetry.jsonl
+  fi
+}

package/src/templates/scripts/notify-on-block.sh.hbs

@@ -6,26 +6,9 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
+. "$_LIB_DIR/telemetry.sh"
 
 if [ "${AHK_DISABLE_NOTIFY:-}" = "1" ]; then
   exit 0
@@ -46,12 +29,12 @@ if [ -n "$TYPE" ]; then
 fi
 [ -z "$BODY" ] && BODY="Claude Code wants your attention."
 
-mkdir -p .harness
 TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 ESCAPED_TITLE=${TITLE//\"/\\\"}
 ESCAPED_BODY=${BODY//\"/\\\"}
-printf '{"ts":"%s","hook":"Notification","type":"%s","title":"%s","body":"%s"}\n' \
-  "$TS" "$TYPE" "$ESCAPED_TITLE" "$ESCAPED_BODY" >> .harness/telemetry.jsonl
+LINE=$(printf '{"ts":"%s","hook":"Notification","type":"%s","title":"%s","body":"%s"}' \
+  "$TS" "$TYPE" "$ESCAPED_TITLE" "$ESCAPED_BODY")
+telemetry_append "$LINE"
 
 OS_KIND=$(uname -s 2>/dev/null || echo "Unknown")
 case "$OS_KIND" in

package/src/templates/scripts/pre-compact.sh.hbs

@@ -28,26 +28,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 TRIGGER=""
 TOKENS=""

package/src/templates/scripts/pre-push.sh

@@ -8,26 +8,8 @@ set -eo pipefail
 # Without this fallback, `jq` missing on a fresh CI image silently disabled
 # the baseline-monotonic guard — a known audit hole.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 # Baseline monotonic guard. .harness/structural-baseline.json is decreasing-
 # only — fixes REMOVE entries; no path should ADD them. Catches the "mask

package/src/templates/scripts/precompletion-checklist.sh.hbs

@@ -14,37 +14,11 @@ INPUT=$(cat)
 
 # Resolve the directory this hook lives in (used to find _lib/json-pick.mjs).
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-# have_jq — env-overridable probe. AHK_DISABLE_JQ=1 forces the Node fallback,
-# used by tests to exercise the jq-less code path on machines that have jq
-# installed locally.
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-# jp — JSON picker. Uses `jq` when available, else falls back to a bundled
-# Node script with a jq-subset implementation. Keeps hooks portable on
-# minimal CI / Windows where jq is not installed by default. Without this
-# fallback, the entire pre-completion check used to be a silent no-op.
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
-# Probe: do we have either jq or the Node fallback? Node is always
-# present (kit's `engines` field requires >=20), so this is just an explicit
-# probe and a fail-loud branch if even node is missing.
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+# have_jq / have_jp / jp shared across all hook scripts. AHK_DISABLE_JQ=1
+# forces the Node fallback, used by tests to exercise the jq-less code path
+# on machines that have jq installed locally.
+. "$_LIB_DIR/jp.sh"
 
 # CRITICAL: avoid infinite loops. If the hook already ran, do not block again.
 if have_jp; then

package/src/templates/scripts/pretooluse-bash-guard.sh.hbs

@@ -32,26 +32,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 if ! have_jp; then
   # Without a JSON parser we can't read the command. Skip rather than

package/src/templates/scripts/pretooluse-edit-guard.sh.hbs

@@ -23,20 +23,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then jq -r "$1"
-  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 if ! have_jp; then exit 0; fi
 
 # Resolve target file. Write/Edit ship .tool_input.file_path; MultiEdit ships

package/src/templates/scripts/session-end.sh.hbs

@@ -19,20 +19,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then jq -r "$1"
-  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 REASON=""
 SESSION_ID=""

package/src/templates/scripts/session-start.sh.hbs

@@ -22,26 +22,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 SOURCE=""
 if have_jp; then

package/src/templates/scripts/statusline.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-// statusLine — "Two-line Dashboard" (V4).
+// statusLine — "Dashboard Style" (Variant 4).
 //
-// LINE 1 — vitals (always emitted when any segment resolves):
-//   ▶ Opus│terse│⏱1h12m  main(±3) feat:health-endpoint  ▓▓▓▓░ 42% $0.83 +156/-23
+// LINE 1 — vitals with rich icons (always emitted when any segment resolves):
+//   ▶ Opus 4.7 │ 📝 terse │ ⏱ 1h12m │ ⎇ main(±3) │ ✓ clean │ ▓▓▓▓░ 42% │ $0.83 │ +156/-23
 //
-// LINE 2 — alerts (only when ≥1 trigger fires; otherwise omitted):
-//   ⚠ >200K — auto-compact next msg  ⚠ ctx 84%  ⏳ 5h limit 78%, resets in 1h12m  🚫 last-block: <title>
+// LINE 2 — alerts with clear segmentation (only when ≥1 trigger fires):
+//   ⚠ >200K — auto-compact next msg │ ⏳ 5h limit 78%, resets in 1h12m │ 🚫 last-block: <title>
 //
 // Payload (Claude Code v2.1.132+ schema):
 //   model.display_name, output_style.name, session_id, version,
@@ -236,61 +236,72 @@ function bar(pct, width = 10) {
 }
 
 // ---------------------------------------------------------------------------
-// Line 1 — vitals.
+// Line 1 — vitals (Dashboard Style with rich icons).
 // ---------------------------------------------------------------------------
 function renderLine1(payload, git, feat, config) {
-  const left = []; // identity group: model, style, duration
-  const mid = [];  // workspace group: branch, feat
-  const right = []; // burn group: ctx, cost, lines
+  const segments = [];
 
+  // Segment 1: Model with play icon
   const modelName = payload?.model?.display_name;
-  if (modelName) left.push(cyan(`▶ ${modelName}`));
+  if (modelName) {
+    segments.push(`${green("▶")} ${cyan(modelName)}`);
+  }
 
+  // Segment 2: Output style with document icon
   const styleName = payload?.output_style?.name;
-  if (styleName && styleName !== "default") left.push(dim(styleName));
+  if (styleName && styleName !== "default") {
+    segments.push(`${dim("📝")} ${dim(styleName)}`);
+  }
 
+  // Segment 3: Duration with timer icon
   const durMs = payload?.cost?.total_duration_ms;
-  if (durMs && durMs >= 1000) left.push(dim(`⏱${fmtDuration(durMs)}`));
+  if (durMs && durMs >= 1000) {
+    segments.push(`${dim("⏱")} ${dim(fmtDuration(durMs))}`);
+  }
 
+  // Segment 4: Branch with git icon
   if (git?.branch) {
-    const tag = git.conflict ? red(`${git.branch}!CONFLICT`)
-              : git.dirty > 0 ? yellow(`${git.branch}(±${git.dirty})`)
-              : green(git.branch);
-    mid.push(tag);
+    const branchIcon = dim("⎇");
+    const branchText = git.conflict ? red(`${git.branch}!CONFLICT`)
+                     : git.dirty > 0 ? `${yellow(git.branch)}${dim("(")}${yellow(`±${git.dirty}`)}${dim(")")}`
+                     : yellow(git.branch);
+    segments.push(`${branchIcon} ${branchText}`);
   }
 
+  // Segment 5: Feature status with checkmark/cross icon
   if (feat) {
-    mid.push(feat.open ? magenta(`feat:${feat.open}`) : dimGreen("feat:clean"));
+    const featIcon = feat.open ? red("✗") : green("✓");
+    const featText = feat.open ? magenta(feat.open) : green("clean");
+    segments.push(`${featIcon} ${featText}`);
   }
 
+  // Segment 6: Context usage (bar + percentage)
   const pct = payload?.context_window?.used_percentage;
   if (typeof pct === "number") {
     const col = ctxColor(pct);
-    right.push(`${col(bar(pct))} ${col(`${Math.round(pct)}%`)}`);
+    segments.push(`${col(bar(pct))} ${col(`${Math.round(pct)}%`)}`);
   }
 
+  // Segment 7: Cost
   const cost = payload?.cost?.total_cost_usd;
   if (typeof cost === "number" && cost > 0) {
-    right.push(costStr(cost));
+    segments.push(costStr(cost));
   }
 
+  // Segment 8: Lines changed
   if (config.showLines) {
     const add = num(payload?.cost?.total_lines_added, 0);
     const rem = num(payload?.cost?.total_lines_removed, 0);
     if (add > 0 || rem > 0) {
-      right.push(`${green("+" + add)}/${dimRed("-" + rem)}`);
+      segments.push(`${green("+" + add)}/${dimRed("-" + rem)}`);
     }
   }
 
-  const parts = [];
-  if (left.length) parts.push(left.join(dim("│")));
-  if (mid.length) parts.push(mid.join("  "));
-  if (right.length) parts.push(right.join(" "));
-  return parts.join("  ");
+  return segments.join(` ${dim("│")} `);
 }
 
 // ---------------------------------------------------------------------------
-// Line 2 — alerts.
+// Line 2 — alerts (Dashboard Style with rich icons and clear segmentation).
 // ---------------------------------------------------------------------------
 function renderLine2(payload, sessionId, config, lang) {
   if (config.compact) return "";
@@ -299,19 +310,19 @@ function renderLine2(payload, sessionId, config, lang) {
 
   // Order by severity: hardest stop first.
   if (payload?.exceeds_200k_tokens === true) {
-    alerts.push(red(`⚠ ${t.over_200k}`));
+    alerts.push(`${red("⚠")} ${red(t.over_200k)}`);
   }
 
   const pct = payload?.context_window?.used_percentage;
   if (typeof pct === "number" && pct >= 80 && payload?.exceeds_200k_tokens !== true) {
-    alerts.push(red(`⚠ ctx ${Math.round(pct)}%${t.compact_soon}`));
+    alerts.push(`${red("⚠")} ${red(`ctx ${Math.round(pct)}%${t.compact_soon}`)}`);
   }
 
   if (config.showRateLimit) {
     const five = payload?.rate_limits?.five_hour;
     if (five && typeof five.used_percentage === "number" && five.used_percentage >= 75) {
       const resetTxt = five.resets_at ? `${t.rate_resets}${fmtCountdown(five.resets_at)}` : "";
-      alerts.push(yellow(`⏳ 5h limit ${Math.round(five.used_percentage)}%${resetTxt}`));
+      alerts.push(`${yellow("⏳")} ${yellow(`5h limit ${Math.round(five.used_percentage)}%${resetTxt}`)}`);
     }
   }
 
@@ -319,11 +330,11 @@ function renderLine2(payload, sessionId, config, lang) {
     const lb = fetchLastBlock(sessionId);
     if (lb) {
       const title = String(lb.title || "").slice(0, 40);
-      alerts.push(red(`🚫 ${t.last_block}${title}`));
+      alerts.push(`${red("🚫")} ${red(`${t.last_block}${title}`)}`);
     }
   }
 
-  return alerts.join("  ");
+  return alerts.join(` ${dim("│")} `);
 }
 
 // ---------------------------------------------------------------------------

package/src/templates/scripts/structural-test-on-edit.sh.hbs

@@ -13,20 +13,8 @@ INPUT=$(cat)
 # when jq is missing — silently skipping the structural check on jq-less
 # environments (minimal CI, Windows without WSL+brew) was a known audit hole.
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then jq -r "$1"
-  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 if ! have_jp; then
   echo "[ahk] structural-test-on-edit: no JSON parser available (need jq OR node + scripts/_lib/json-pick.mjs)." >&2
   exit 0

package/src/templates/scripts/subagent-stop.sh.hbs

@@ -14,20 +14,9 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then jq -r "$1"
-  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
+. "$_LIB_DIR/telemetry.sh"
 
 SUBAGENT="(unknown)"
 if have_jp; then
@@ -35,12 +24,12 @@ if have_jp; then
 fi
 
 # Telemetry first so we record every subagent boundary, even if the
-# structural-test bails below.
-mkdir -p .harness
+# structural-test bails below. telemetry_append handles rotation.
 TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
-printf '{"ts":"%s","event":"subagent_stop","subagent":"%s","sha":"%s"}\n' \
-  "$TS" "$SUBAGENT" "$SHA" >> .harness/telemetry.jsonl
+LINE=$(printf '{"ts":"%s","event":"subagent_stop","subagent":"%s","sha":"%s"}' \
+  "$TS" "$SUBAGENT" "$SHA")
+telemetry_append "$LINE"
 
 # Skip if structural test disabled.
 if [ -f harness.config.json ] \

package/src/templates/scripts/telemetry-on-skill.sh

@@ -8,25 +8,20 @@
 # v0.7: migrated from `command -v jq` fail-open gate to the kit's jp() helper
 # so the telemetry record still gets written on jq-less CI / Windows. Without
 # the migration, telemetry quietly went dark anywhere jq wasn't installed.
+# v0.10.3: jp/have_jq/have_jp extracted to _lib/jp.sh; AHK_DISABLE_TELEMETRY
+# opt-out + AHK_TELEMETRY_MAX_LINES rotation added.
 set -e
 
+# Opt-out: respect AHK_DISABLE_TELEMETRY=1 before reading stdin so the user
+# can fully disable observability without removing the hook from settings.
+[ "${AHK_DISABLE_TELEMETRY:-}" = "1" ] && exit 0
+
 INPUT=$(cat)
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then jq -r "$1"
-  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
+. "$_LIB_DIR/telemetry.sh"
 if ! have_jp; then exit 0; fi
 
 TOOL=$(echo "$INPUT" | jp '.tool_name // empty')
@@ -35,14 +30,13 @@ TOOL=$(echo "$INPUT" | jp '.tool_name // empty')
 SKILL=$(echo "$INPUT" | jp '.tool_input.skill // empty')
 [ -z "$SKILL" ] && exit 0
 
-mkdir -p .harness
 TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
 
 # Compose JSONL line by hand — same shape as the previous jq-built record.
-# Quoting via printf '%s' so embedded spaces in skill names don't break the
-# line. Skill names are constrained to `[a-z0-9-]+` upstream so we don't
-# need full JSON escaping here.
-printf '{"ts":"%s","event":"skill_invoked","skill":"%s","sha":"%s"}\n' \
-  "$TS" "$SKILL" "$SHA" >> .harness/telemetry.jsonl
+# Skill names are constrained to `[a-z0-9-]+` upstream so we don't need full
+# JSON escaping here. telemetry_append handles mkdir, append, and rotation.
+LINE=$(printf '{"ts":"%s","event":"skill_invoked","skill":"%s","sha":"%s"}' \
+  "$TS" "$SKILL" "$SHA")
+telemetry_append "$LINE"
 exit 0

package/src/templates/scripts/userprompt-guard.sh.hbs

@@ -14,26 +14,8 @@ set -eo pipefail
 
 INPUT=$(cat)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-have_jq() {
-  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
-  command -v jq >/dev/null 2>&1
-}
-have_jp() {
-  have_jq && return 0
-  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
-  return 1
-}
-jp() {
-  if have_jq; then
-    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
-  else
-    if [ -n "$2" ]; then
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
-    else
-      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
-    fi
-  fi
-}
+_LIB_DIR="$SCRIPT_DIR/_lib"
+. "$_LIB_DIR/jp.sh"
 
 if ! have_jp; then
   exit 0