agent-harness-kit 0.10.2 → 0.11.1

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.10.2"
+        "ref": "v0.11.1"
       },
-      "version": "0.10.2",
+      "version": "0.11.1",
       "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.10.2",
+  "version": "0.11.1",
   "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.10.2",
+  "version": "0.11.1",
   "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/core/render-templates.mjs

@@ -288,10 +288,14 @@ function sha256(buf) {
 }
 
 // Inject a statusLine block into .claude/settings.json. Idempotent: if the
-// existing statusLine already references the kit's script, leave it; otherwise
-// set it to invoke scripts/statusline.mjs via node. Doesn't clobber a
+// existing statusLine already references the kit's script with the desired
+// padding + refreshInterval, leave it; otherwise update. Doesn't clobber a
 // user-customised type:"command" entry that points at a different command.
 //
+// padding/refreshInterval are sourced from harness.config.json#statusline
+// (with defaults) so a user can tune through one config file and the merge
+// keeps settings.json in sync.
+//
 // Returns {changed, rawContent} for the lockfile bookkeeping (mirrors the
 // mergeHooksIntoSettings contract).
 export async function mergeStatusLineIntoSettings(cwd) {
@@ -310,9 +314,31 @@ export async function mergeStatusLineIntoSettings(cwd) {
       );
     }
   }
+
+  // Read padding + refreshInterval from harness.config.json#statusline if
+  // present; otherwise V4 defaults (padding 1, refresh 2s for live updates
+  // during long-running turns).
+  let padding = 1;
+  let refreshInterval = 2;
+  const cfgPath = resolve(cwd, "harness.config.json");
+  if (existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+      const sl = cfg?.statusline;
+      if (sl && typeof sl === "object") {
+        if (typeof sl.padding === "number" && sl.padding >= 0) padding = sl.padding;
+        if (typeof sl.refreshInterval === "number" && sl.refreshInterval >= 1) {
+          refreshInterval = sl.refreshInterval;
+        }
+      }
+    } catch { /* malformed config → use defaults */ }
+  }
+
   const desired = {
     type: "command",
     command: "node scripts/statusline.mjs",
+    padding,
+    refreshInterval,
   };
   // Preserve a user-customised entry if it already points elsewhere. We only
   // inject when statusLine is absent OR explicitly references our script.
@@ -330,7 +356,9 @@ export async function mergeStatusLineIntoSettings(cwd) {
     cur &&
     typeof cur === "object" &&
     cur.type === desired.type &&
-    cur.command === desired.command
+    cur.command === desired.command &&
+    cur.padding === desired.padding &&
+    cur.refreshInterval === desired.refreshInterval
   ) {
     return { changed: false, rawContent: Buffer.from(raw) };
   }

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/deliver-html/SKILL.md.hbs

@@ -60,6 +60,10 @@ Do **NOT** use for:
    - Converts MD → HTML (self-rolled subset: headings, lists, code blocks,
      tables, blockquotes, links, inline formatting — no npm dependency).
    - Writes `<slug>.html` at the path you pass.
+   - **Auto-opens** the file in the default browser (`open`/`xdg-open`/`start`).
+     Suppress with `--no-open`, or by setting `AHK_DISABLE_HTML_OPEN=1` /
+     `CI=true` in the environment. Open failures (missing binary, headless
+     box) never fail the deliverable.
 
 5. **Print the deliverable contract** (the script already does this — copy it
    into your response):
@@ -69,7 +73,7 @@ Do **NOT** use for:
    **File:** <path>  (<size>)
    **Template:** decision-doc | audit-report | status-report
    **Lang:** vi | en
-   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   **Open:** auto-opened   (or fallback hint if --no-open / CI=true)
    ```
 
 ## Output contract

package/src/templates/.claude/skills/deliver-html/SKILL.md.vi.hbs

@@ -59,6 +59,10 @@ Trigger keyword từ user (tiếng Việt / English):
    - Convert MD → HTML (self-rolled subset: heading, list, code block, table,
      blockquote, link, inline format — không cần npm dependency).
    - Ghi `<slug>.html` tại path bạn truyền.
+   - **Tự mở** file trong browser mặc định (`open`/`xdg-open`/`start`).
+     Tắt bằng `--no-open`, hoặc set `AHK_DISABLE_HTML_OPEN=1` /
+     `CI=true` trong env. Lỗi mở (thiếu binary, headless) không làm
+     fail deliverable.
 
 5. **In deliverable contract** (script tự in — bạn copy vào response):
 
@@ -67,7 +71,7 @@ Trigger keyword từ user (tiếng Việt / English):
    **File:** <path>  (<size>)
    **Template:** decision-doc | audit-report | status-report
    **Lang:** vi | en
-   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   **Open:** auto-opened   (hoặc fallback hint khi --no-open / CI=true)
    ```
 
 ## Output contract

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/statusline-cache.mjs

@@ -0,0 +1,57 @@
+// statusline-cache.mjs — tiny file-based memo for statusLine segments.
+//
+// Why this exists: Claude Code re-spawns the statusLine command on every
+// refresh, so in-process memoization is useless — each invocation is a
+// fresh node process. File-based cache keyed on `session_id` (stable per
+// Claude Code session) is the documented pattern.
+//
+// The cache lives under $TMPDIR. Each key gets a separate file with mtime
+// as the freshness signal. Reads bypass the file when stale; writes are
+// best-effort (failure to write = next call recomputes, no error surfaced).
+//
+// Usage:
+//   import { cached } from "./statusline-cache.mjs";
+//   const branch = cached(
+//     { sessionId, key: "git-branch", ttlMs: 5000 },
+//     () => spawnSync("git", ["branch", "--show-current"], ...).stdout.trim(),
+//   );
+
+import { readFileSync, writeFileSync, statSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CACHE_DIR = join(tmpdir(), "ahk-statusline");
+
+function ensureDir() {
+  try { mkdirSync(CACHE_DIR, { recursive: true }); } catch { /* exists */ }
+}
+
+function cachePath(sessionId, key) {
+  // session_id can contain anything → sanitize. No path separator survives.
+  const safeSession = String(sessionId || "no-session").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+  const safeKey = String(key).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 32);
+  return join(CACHE_DIR, `${safeSession}-${safeKey}.cache`);
+}
+
+// Synchronous because statusline.mjs runs as a one-shot command and the
+// upstream caller blocks on its output anyway. async would add no value.
+export function cached({ sessionId, key, ttlMs }, fetchFn) {
+  ensureDir();
+  const file = cachePath(sessionId, key);
+  try {
+    const st = statSync(file);
+    if (Date.now() - st.mtimeMs < ttlMs) {
+      return readFileSync(file, "utf8");
+    }
+  } catch { /* miss */ }
+  let value;
+  try {
+    value = fetchFn();
+  } catch {
+    value = "";
+  }
+  if (value == null) value = "";
+  const s = String(value);
+  try { writeFileSync(file, s); } catch { /* best-effort */ }
+  return s;
+}

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
+}