Merge dev → main (automated)

.githooks/pre-push

@@ -1,19 +1,64 @@
 #!/bin/sh
-# worklog:pre-push-hook:v1
-#
-# Auto-sync Worklog data before pushing.
-#
-# This hook runs `wl sync` before any push to ensure worklog data is
-# committed and pushed to the dedicated refs/worklog/data branch.
-# It uses a temporary worktree to avoid corrupting the project working tree
-# (see WL-0MQRBT8BS00355AB for the bug this prevents).
-#
-# BYPASS: Set WORKLOG_SKIP_PRE_PUSH=1 to skip the sync entirely.
-#   export WORKLOG_SKIP_PRE_PUSH=1
-#   git push origin HEAD:refs/heads/dev
+# worklog:pre-push-hook:v2
+# 1. Auto-sync Worklog data before pushing (committed hooks).
+# 2. Enforce branch naming policy: block pushes to protected branches.
+# 3. Context-budget regression gate (F6, SA-0MSLK7XNZ00366YY): fail the push
+#    when the startup context surface exceeds committed thresholds.
 #
+# Set WORKLOG_SKIP_PRE_PUSH=1 to bypass worklog sync.
+# Set BRANCH_POLICY_SKIP=1 to bypass branch policy check (not recommended).
+# Set CONTEXT_BUDGET_SKIP=1 to bypass the context-budget gate (not recommended).
 set -e
 
+# ── Branch policy enforcement ────────────────────────────────────────────────
+# Check that the current branch is not a protected branch.
+if [ "$BRANCH_POLICY_SKIP" != "1" ]; then
+  current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  # Protected branches that agents must never push to.
+  blocked_branches="main master HEAD"
+  for blocked in $blocked_branches; do
+    if [ "$current_branch" = "$blocked" ]; then
+      echo "ERROR: Push to '$current_branch' is blocked by branch policy." >&2
+      echo "  Regular agents must NOT push directly to main." >&2
+      echo "  Work in feature branches (wl-<id>-<desc>) and push into dev." >&2
+      echo "  See the framework ship skill for the push-to-dev workflow." >&2
+      exit 1
+    fi
+  done
+fi
+
+# ── Context-budget regression gate ──────────────────────────────────────────
+# Fail the push when the pi session startup context surface exceeds the
+# committed thresholds (docs/dev/context-budget.thresholds.json). The gate is
+# fail-open when the tooling or thresholds file is absent (e.g. worktrees of
+# old commits, or repositories that do not ship the context-audit skill).
+# measure_context.py is resolved first from the local skill/context-audit/
+# path, then from the installed global symlink
+# (~/.pi/agent/skills/context-audit/scripts/measure_context.py) installed by
+# the framework's install_pi.sh.
+if [ "$CONTEXT_BUDGET_SKIP" != "1" ]; then
+  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  if [ -f "$repo_root/skill/context-audit/scripts/measure_context.py" ]; then
+    measure="$repo_root/skill/context-audit/scripts/measure_context.py"
+  elif [ -f "$HOME/.pi/agent/skills/context-audit/scripts/measure_context.py" ]; then
+    measure="$HOME/.pi/agent/skills/context-audit/scripts/measure_context.py"
+  else
+    measure=""
+  fi
+  thresholds="$repo_root/docs/dev/context-budget.thresholds.json"
+  if [ -n "$repo_root" ] && [ -n "$measure" ] && [ -f "$measure" ] && [ -f "$thresholds" ]; then
+    if python3 "$measure" --repo-root "$repo_root" --include-hidden --thresholds "$thresholds" >/dev/null 2>&1; then
+      :
+    else
+      echo "ERROR: Context budget exceeded committed thresholds." >&2
+      echo "  Run: python3 $measure --repo-root $repo_root --include-hidden --thresholds $thresholds" >&2
+      echo "  See docs/dev/context-budget.md. Set CONTEXT_BUDGET_SKIP=1 to bypass." >&2
+      exit 1
+    fi
+  fi
+fi
+
+# ── Worklog sync ─────────────────────────────────────────────────────────────
 if [ "$WORKLOG_SKIP_PRE_PUSH" = "1" ]; then
   echo "worklog: pre-push sync skipped (WORKLOG_SKIP_PRE_PUSH=1)"
   exit 0

API.md

@@ -51,6 +51,10 @@ npm start
 
 **Note:** All endpoints also support project prefix routing via `/projects/:prefix/...`
 
+### Audit field on updates
+
+`PUT /items/:id` (and the prefixed variant) accepts an `audit` body field containing structured audit text whose first non-empty line is `Ready to close: Yes` or `Ready to close: No`. The audit is routed to the `audit_results` table (the sole source of truth for audit state). When the verdict is `Ready to close: No` and the item is in `in_review` (status `completed`), the item is automatically reverted to `open`/`plan_complete` (priority preserved) and the response includes a `reverted` field (`{ item, from: { status, stage }, to: { status, stage } }`) — consistent with the CLI audit write paths. See docs/AUDIT_STATUS.md.
+
 ## Examples
 
 ### Create a Work Item

CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## v1.0.12 (2026-08-25)
+### Features
+- Herdr downtime dispatcher: scheduled prompts (best-effort frequency) config (WL-0MSS1Q5ER007QDKX)
+- Downtime dispatcher: priority-first selection with round-robin tie-break across instances (WL-0MSSRED76008LGB6)
+- Exclude child items from audit-tier dispatch selection (WL-0MSTLFW14000KPEC)
+- Shortcut key to toggle downtime dispatch per herdr instance (WL-0MSZ4NSOE007AQEF)
+- Downtime dispatcher: critical items always progress first regardless of stage (stage-appropriate skill) (WL-0MT3FM8VA005XBHE)
+- Use centered toast for shortcut feedback instead of status line (WL-0MS7EP7U8008DCXO)
+- FTS search: keep index fresh (wire upsertFtsEntry into save paths) and surface query syntax errors (WL-0MSLW8UCP001771K)
+- Refactor Downtime Dispatcher: leader election with shared coordination file (WL-0MST3OJ8S0001ROL)
+- Detail view ToC overflows pane — first lines scroll off the top of the screen (WL-0MSI28AP80002F5S)
+- Dispatching continues while downtime dispatch is disabled (WL-0MT4BWUHW008LIFE)
+- Downtime dispatch: use available slots while some slots busy (spare-capacity dispatch, default N instead of all-slots-free) (WL-0MT32F90V008UAD2)
+- Subscribe to herdr window events instead of polling active window status (WL-0MSHB7DHO004RHBJ)
+- Enable cut and paste in the herdr command-input page (all command forms) (WL-0MSW6KCTA0092DCV)
+- Refresh the selection list when background (no-pane) shortcut commands complete (WL-0MT1KB70U0012X6T)
+- Herdr worklist: mouse and touch support in the selection list (WL-0MSGHM5BQ0096BNJ)
+- Herdr selection list: metadata section should use the same icons as the list section (WL-0MSGIXHHI009KFW9)
+- Keep focus on the Herdr selection list when a shortcut command creates a pane (WL-0MSHIA53D009DJOT)
+- Add per-shortcut option to control whether a shortcut opens a command pane (WL-0MSJLD1I70045ZUL)
+- Herdr: filter by priority via f-p-* chords (stage filters become f-s-*) (WL-0MSKC8T46006999S)
+- Herdr selection list: collapsible group headings with item counts (WL-0MSL5MPSZ003TG94)
+- a-r (audit reject) should reset item to open/plan_complete/medium (WL-0MSM72QXN008GUP2)
+- Herdr: flipping needsProducerReview must not make a valid audit stale (WL-0MSN6ZCTN0027U2R)
+- Add tolerant work-item ID resolution to wl show (exact-first, unique substring fallback, ambiguity error) for agent tool use (WL-0MSOMI4GQ009WL8E)
+- Incremental sync: only export/push changed work items instead of full JSONL (WL-0MSAKUBKW006FN8Q)
+- Show complete, right-aligned model name on footer Line 3 (remove 30-col truncation) (WL-0MSMDYJ3X00895MP)
+### Bug Fixes
+- Fix riskOrdinal/effortOrdinal exact-match in packages/shared database.ts (server-side wl next risk/effort filter) (WL-0MT3FLZJ20076X9B)
+- Audit lifecycle: verify status/stage transition after persist (silent failure leaves items in idea) (WL-0MSVVFBJ2003RRYK)
+- Herdr worklist pane crashes with exit code 1 seconds after opening (prefix+l) due to unhandled ECONNRESET (WL-0MSZXB3OF009V5IQ)
+- Fix NVIDIA kernel/userspace driver API mismatch (chrome-headless) (WL-0MT1KJNDK004SNPK)
+- Herdr selection list: no indication of items below the fold (WL-0MSG8YXYJ008PWJJ)
+- Herdr plugin: activity-gated proxy mode switching (cheap on operator idle, fast on operator command) (WL-0MSN3FWV5008KQE9)
+- Downtime title bar shows 'idle' while llama UI is busy (per-slot mode display bug) (WL-0MT65T14L002HTWB)
+- snapd udev monitor goroutine hang - watchdog kills and restart loops (WL-0MT1KJNHE0048HW3)
+- Audit auto-green-run never works for ContextHub: NODE_SUITE_DIRS includes tests/node which does not exist (WL-0MSKSMRFP001Q3XU)
+- Auto-revert in_review items to plan_complete when marked not ready to close (WL-0MSKHYI5U0069FVV)
+### Other
+- Worklist refresh wl spawns have no timeout — a hung wl wedges refreshInFlight permanently (WL-0MSJNJXX2001NMHS)
+- Investigate chrome-headless workload causing GPU crashes and memory pressure (WL-0MT1KJNHY00286QE)
+- wl pre-push author-identity gate blocks all pushes (empty user.email) (CG-0MSUZASM10035QSG)
+- Operator action: reset herdr refreshIntervalMs to 30000 and restart pre-fix panes (WL-0MSBVYN700074A1T)
+- Demote completed/in_review parent to plan_complete when a child is added (WL-0MSJL00P5004Y0L6)
+- Repeat questions in final summary when dispatched in downtime (WL-0MT50K6BI000T052)
+- Extensible shortcuts.json: bundled defaults + project-local overrides (WL-0MSHUMX5C004NC4O)
+- wl next: exclude stage=done items from results by default (WL-0MSGRJWRX0068W3W)
+- Provide worklog shortcuts when working with a work item id (WL-0MQTHL7ER0012JK1)
+- Create npm run install routine for install steps and add install:plugin rule (WL-0MSHZR0J2000Q9SW)
+- Rename 'Podcast Editing' tab to 'Worklog' (WL-0MSI4TAT70058921)
+- Merge icons.ts into theme.ts as single source of truth; deprecate icons.ts wrapper (WL-0MSJ4BT4Z009LIB4)
+- Lower downtimeIdleThresholdMs 240s -> ~60s (plus downtimePollIntervalMs 30s -> 10s floor) (WL-0MSOMV6CW003OXTK)
+- Fully remove deprecated icons.ts from all projects that use it (src + herdr) (WL-0MSJ4BT4Z002HH9B)
+
 ## v1.0.11 (2026-08-16)
 ### Features
 - Idle tracking now requires the same slots to stay free, not just any slots. (WL-0MSG7P9N8009PCKG)

CLI.md

@@ -152,6 +152,8 @@ Automatic re-sort:
 
 Update fields on one or more existing work items. Accepts multiple IDs. Options mirror `create` for updatable fields, plus `--description-file <file>` (read description from a file), `--audit-text <text>` and `--audit-file <file>` (read audit text from a file; writes to the `audit_results` table), `--needs-producer-review <true|false>` (set needsProducerReview flag), and `--do-not-delegate <true|false>` (set or clear the do-not-delegate tag).
 
+> **Auto-revert:** when `--audit-text`/`--audit-file` carries a `Ready to close: No` verdict for an item in `in_review` (status `completed`), the item is automatically reverted to `open`/`plan_complete` (priority preserved) and the output reports the transition (`reverted` field in JSON, `[ID reverted from completed/in_review to open/plan_complete]` in human mode). See docs/AUDIT_STATUS.md.
+
 Automatic re-sort:
 
 - `wl update` will automatically invoke a re-sort when one or more updated fields are among: `status`, `priority`, `risk`, `effort`, or `stage`. By default this re-sort runs asynchronously so the CLI is not blocked. This helps `wl next` and other selection-based commands reflect recent priority or status changes without requiring a manual `wl re-sort`.
@@ -261,6 +263,8 @@ Behavior:
 - Automatically sets `audited_at` to the current ISO 8601 timestamp.
 - Derives `author` from `WL_USER` / `USER` / `USERNAME` environment variables unless overridden by `--author`.
 
+> **Auto-revert:** when `--ready-to-close no` is set on an item in `in_review` (status `completed`), the item is automatically reverted to `open`/`plan_complete` (priority preserved) and the output reports the transition (`reverted` field in JSON, `[ID reverted from completed/in_review to open/plan_complete]` in human mode). See docs/AUDIT_STATUS.md.
+
 Options:
 
 - `--ready-to-close <yes|no>` — Whether the work item is ready to close (required).
@@ -440,6 +444,35 @@ Options:
 `-c, --children` — Also display descendants in a tree layout (optional).
 `--prefix <prefix>` (optional)
 `--no-icons` — Disable icon rendering for clean text output. When icons are disabled, priority and status display as plain text (e.g., `[CRIT]`, `[OPEN]`) instead of emoji. This is useful for scripting or copy-paste operations.
+`--exact` — Force strict exact-match only (skip the tolerant substring fallback).
+
+#### Tolerant ID resolution
+
+`wl show` resolves work-item IDs with a two-tier strategy:
+
+1. **Exact match** — `normalizeCliId` normalises the ID (adds prefix if missing,
+   normalises case/prefix). If an item with that normalised ID exists, it is
+   returned.
+2. **Substring fallback** — If no exact match is found and `--exact` is *not*
+   specified, the CLI scans all item IDs for a **case-insensitive substring**
+   match. When exactly one item matches, it is returned transparently. When
+   multiple items match, the CLI reports an `ambiguous-match` error listing the
+   candidate IDs so the caller can disambiguate. When nothing matches, the
+   CLI reports "Work item not found" (same as before).
+
+This tolerant resolution is especially useful for agent tooling that may hold
+truncated, case-differing, or partial ID references.
+
+The `--exact` flag disables the substring fallback, restoring strict
+exact-match semantics for callers that need deterministic behaviour.
+
+#### JSON error formats
+
+When `--json` is used the error output is always valid JSON:
+
+- **Ambiguous match** — `{"success": false, "error": "ambiguous-match",
+  "candidates": ["WL-XXX1", "WL-XXX2"]}`
+- **Not found** — `{"success": false, "error": "Work item not found: <id>"}`
 
 The output always includes `Risk` and `Effort` fields. When a field has no value a placeholder `—` is shown so the field is consistently visible for triage and prioritization.
 
@@ -449,6 +482,9 @@ Examples:
 wl show WL-ABC123
 wl --json show WL-ABC123
 wl show WL-ABC123 -c
+wl show WL-ABC          # tolerant: resolves if unique substring
+wl --json show WL-ABC   # tolerant JSON output
+wl show --exact WL-ABC  # strict: fails if not an exact match
 ```
 
 ### `next` [options]
@@ -686,6 +722,10 @@ enhancement degrades gracefully when no embedder is configured.
 - **Partial ID** — Tokens of 8+ alphanumeric characters are matched as substrings against all work item IDs; partial matches appear below exact matches.
 - **Mixed queries** — `wl search WL-XXXXX some text` returns the ID match first, followed by FTS results for the full query (duplicates removed).
 
+**Fresh index:** The FTS index is updated on every save path — creating/updating items, adding/updating/deleting comments, `import`, `upsert-items`, and status reconciliation — so `wl search` always reflects the latest data without a manual `--rebuild-index`.
+
+**Quoting punctuated terms:** Unquoted punctuated terms (version strings like `v0.1.11`, file paths like `src/lib/util.ts`, and IDs) are not valid FTS5 syntax, so the command auto-quotes the query as a phrase and prints a **warning** (also emitted as a `warning` field in `--json` output) — it is never a silent empty result. If auto-quoting also fails, the command exits non-zero with `Invalid search query: ...`. To search a literal punctuated phrase explicitly, quote it yourself: `wl search "v0.1.11"`. Genuinely zero-match queries return "No results found." with no warning.
+
 Options:
 
 `-s, --status <status>` (optional) — Filter results by status
@@ -705,7 +745,7 @@ Query embeddings are cached in-memory to avoid redundant API calls.
 `--semantic-only` (optional) — Return only semantic (embedding-based) results.
 Requires an embedder; errors if OPENAI_API_KEY is not set.
 `--prefix <prefix>` (optional)
-`--json` (optional) — Output structured JSON with `id`, `title`, `status`, `priority`, `score`, `snippet`, `matchedField`. When `--semantic` is used, includes `semanticAvailable: true/false`.
+`--json` (optional) — Output structured JSON with `id`, `title`, `status`, `priority`, `score`, `snippet`, `matchedField`. When the query was auto-quoted as a phrase (invalid FTS5 syntax), a `warning` field is included. When `--semantic` is used, includes `semanticAvailable: true/false`.
 
 Examples:
 
@@ -1066,15 +1106,15 @@ Other commands cover repository bootstrap and local system status. Use these to
 
 ### `init`
 
-Initialize Worklog configuration in the repository (creates `.worklog` and default config). `wl init` also installs `AGENTS.md` in the project root, prefixed with a pointer line to the global `AGENTS.md`. If `AGENTS.md` already contains the pointer line, installation is skipped (idempotent, no prompt). If `AGENTS.md` exists without the pointer, it prompts O/A/M — **O**verwrite (destructive), **A**dd pointer (keeps existing content), **M**anual (skip) — unless you pass `--agents-template` for unattended runs. When workflow templates are available, `wl init` prompts you to choose between no formal workflow, a basic Worklog-aware workflow, or manual management (unless you pass `--workflow-inline` for unattended runs). See [AGENTS.md Install Model](docs/AGENTS-INSTALL.md) for the full install flow.
+Initialize Worklog configuration in the repository (creates `.worklog` and default config). `wl init` also installs `AGENTS.md` in the project root with the canonical global-reference structure (`## Global agent guidance` pointing at `~/.pi/agent/AGENTS.md` plus a `## Project-specific guidance` placeholder). If `AGENTS.md` already contains the global reference, installation is skipped (idempotent, no prompt). If `AGENTS.md` exists without the reference, it prompts O/A/M — **O**verwrite (destructive), **A**dd reference above existing content, **M**anual (skip) — unless you pass `--agents-template` for unattended runs. When workflow templates are available, `wl init` prompts you to choose between no formal workflow, a basic Worklog-aware workflow, or manual management (unless you pass `--workflow-inline` for unattended runs). See [AGENTS.md Install Model](docs/AGENTS-INSTALL.md) for the full install flow.
 
 Options:
 
 - `--project-name <name>` — Project name (optional).
 - `--prefix <prefix>` — Issue ID prefix (optional).
 - `--auto-export <yes|no>` — Auto-export data to JSONL after changes (optional).
 - `--auto-sync <yes|no>` — Auto-sync data to git after changes (optional).
-- `--agents-template <overwrite|append|skip>` — What to do when AGENTS.md exists (optional). Append inserts the pointer line at the top while keeping existing content.
+- `--agents-template <overwrite|append|skip>` — What to do when AGENTS.md exists (optional). Append inserts the global-agents reference at the top while keeping existing content below.
 - `--workflow-inline <yes|no>` — Answer the workflow prompt (yes chooses the basic workflow option; no chooses no formal workflow). Omit to prompt interactively.
 - `--stats-plugin-overwrite <yes|no>` — Overwrite existing stats plugin if present (optional).