chore(process): harden agent handoff, ledger revalidation, and wins classifier

.agents/skills/handover/SKILL.md

@@ -6,8 +6,8 @@ description: Prepare a concise evidence-backed Database handover without automat
 # Handover
 
 1. Inspect branch, upstream, worktrees, status, relevant diffs, and recent commits.
-2. Run `npm run workflow:lifecycle -- --phase handoff --write-evidence`.
-3. Run the smallest proportionate offline verification; prefer `npm run verify:pr-local` for non-trivial ready work.
+2. Run `npm run workflow:lifecycle -- --phase handoff --write-evidence` and use its verification routing.
+3. Run one smallest proportionate offline gate; prefer `npm run verify:pr-local` for non-trivial ready work and do not stack broad gates without a distinct failure class.
 4. Separate intended changes from unrelated dirty work and list generated artifacts.
-5. Summarize files, checks, failures, skipped gates, risks, and the exact next action.
+5. Summarize files, checks, failures, skipped gates, risks, the decisive proof line (not exit 0 alone), and the exact next action.
 6. Do not commit, push, open a PR, merge, or call providers unless explicitly requested and authorized.

.claude/agents/verification-router.md

@@ -37,8 +37,11 @@ Default to running **only** offline-safe gates. For any provider-touching comman
 
 - **Retrieval / ranking / selection / chunking / scoring:** offline gate is `verify:cheap`; note that the merge gate `eval:retrieval:quality` (36/36) is provider-touching → report and ask.
 - **Ingestion / answer-gen / source-governance / privacy / production env:** smallest relevant domain check + `check:production-readiness` (runs fail-closed offline).
-- **UI / frontend / a11y / routing / styling:** `npm run ensure` then `verify:ui`.
+- **UI / frontend / a11y / routing / styling:** `npm run ensure`, then the affected journey;
+  add `verify:ui` only for shared UI foundations or a distinct unclosed failure class.
 - **Supabase env/config change:** `check:supabase-project` (provider — report and ask).
-- **Default source/config/test change:** `verify:cheap` first, `verify:pr-local` before PR handoff.
+- **Default source/config/test change:** `verify:pr-local` at PR handoff; do not pre-run
+  `verify:cheap` because the routed handoff gate already owns that coverage.
 
-Report the chosen gate, why it fits the diff, and any provider command that the author must run manually with confirmation.
+Report the chosen gate, why it fits the diff, its decisive proof line (not exit 0 alone), checks
+deliberately not stacked, and any provider command that requires confirmation.

.claude/skills/gates/SKILL.md

@@ -9,7 +9,9 @@ A green exit code is not proof. Contended gates can wait a long time before fail
 leave later checks unrun, and a stale worktree makes healthy-looking runs meaningless. This skill
 exists because those failures have cost real time more than once.
 
-**Rule: never report a gate as passing without quoting the line that proves it ran.**
+**Rule: never report a gate as passing without quoting the decisive line that proves it ran. Pick
+one smallest sufficient gate first; do not stack broad gates unless each covers a distinct plausible
+failure path.**
 
 ## The false-green traps
 

.claude/skills/handoff/SKILL.md

@@ -18,27 +18,45 @@ force-push, or discard work.
 ## Steps
 
 1. **Inspect first (read-only):** `git status --short --branch`, `git diff`, `git diff --cached`,
-   and the ahead/behind from `node scripts/check-base-freshness.mjs`. If staged paths are found
-   that aren't part of the current session's own work (leftover from other sessions' WIP),
-   unstage them with `git restore --staged <path>` before proceeding.
+   and the ahead/behind from `node scripts/check-base-freshness.mjs`. Record the exact cached index
+   state with `git diff --cached --raw --no-renames` before staging. Also record the worktree and
+   untracked state for every intended path with `git status --porcelain=v1 -z --untracked-files=all -- <intended-paths>`.
+   Immediately before staging, repeat and compare both snapshots; if any intended path changed,
+   appeared, or disappeared, stop or move the handoff to an isolated worktree. Do not accept a
+   concurrent change merely because its path is intended. If the cached index contains paths outside
+   this session, stop and move the handoff to an isolated worktree; never unstage or otherwise
+   mutate another session's index entries.
+   Record `git branch --show-current` and `git rev-parse HEAD`; repeat both immediately before and
+   after the commit. Immediately before committing, repeat `git diff --cached --raw --no-renames`
+   and verify that every pre-existing cached entry is unchanged and every new entry is in the
+   explicit intended-path allowlist. Stop if the branch moved, HEAD changed before your commit, or
+   the cached index differs outside those intended paths. A shared worktree/index is not safe
+   handoff state.
 2. **Stage coherent, completed changes only.** Stage explicit paths — never `git add -A`
    blindly. Do not stage `.env*`, secrets, build output, logs, or unrelated WIP; if you
    see a possible secret, report the path (never the value) and stop.
-3. **Verify** with the smallest sufficient gate:
-   - Default: `npm run verify:pr-local` (format + cheap gate, plus build/RAG when the
-     scope needs them).
-   - Touched UI/routing/styling: add `npm run verify:ui`.
+3. **Verify** by invoking `verification-router` (or the `gates` skill when scope is already clear)
+   and run the one smallest sufficient gate it selects. Default PR-ready work uses
+   `npm run verify:pr-local`; inspect its selection with `--dry-run` when uncertain. For
+   UI/routing/styling, prove the affected journey first and add `verify:ui` only for shared UI
+   foundations or when the router says its distinct coverage is necessary. Never stack
+   `verify:cheap` + `verify:ui` + `verify:release` by default.
    - Touched `src/app/`, `src/components/`, or `tests/` (or design-system adoption
      inputs): run `npm run design-system:adoption:update` and stage any regenerated
      `docs/design-system/adoption-manifest.json` / marked COMPONENTS/ADOPTION sections
      before push. Pre-commit syncs this when hooks are installed; Cloud agents that
      bypass hooks still need the explicit update or static-pr + coverage fail together
      (PR #1782).
    - Touched Supabase env/config: `npm run check:supabase-project` (provider — confirm first).
-     Do not claim a gate passed unless it actually ran.
-4. **Commit** with a clear message. End the message with:
+     Do not claim a gate passed unless it actually ran. Paste the decisive proof line (for example,
+     the test count or named check success), not only exit code 0.
+4. **Commit** with a clear message, then verify the new commit has your message, only your intended
+   paths (`git show --name-only --format=fuller HEAD`), and the same branch name recorded in step 1.
+   End the message with:
    `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
-5. **Push** the feature branch: `git push -u origin <branch>`. The pre-push guards run
+5. **Push** the feature branch: `git push -u origin <branch>`. Never pipe the push through `tail`,
+   `head`, or another command that can mask its status. Confirm the remote tip equals local HEAD
+   with `git ls-remote` before reporting success. The pre-push guards run
    (auto-merge sentinel, format, drift) — heed a block rather than overriding blindly.
 6. **Open a PR** with `gh pr create --base main`, body ending with the Claude Code
    attribution line. Write the body from `.github/pull_request_template.md` in full normal

.claude/skills/issues/SKILL.md

@@ -9,8 +9,13 @@ description: Track and recall all outstanding tasks, recommendations, and issues
 execution order, open **tasks**, **recommendations**, **issues**, provider/operator work, and archive
 history. Chat context resets; that file does not. This skill reads it back and keeps it current.
 
-**The ledger is the source of truth, not chat memory.** Never answer `/issues` from conversation
-recall — always read the file first, so the answer is correct even in a fresh session.
+**The ledger on the remote `main` branch is the source of truth, not chat memory or a stale
+worktree.** Never answer `/issues` from conversation recall or by reading the checkout file
+directly. Run `npm run issues:report -- --json`; it reads the locally cached
+`origin/main:docs/outstanding-issues.md`, reports the checkout's `behind`/`ahead` counts, and labels
+that source `revalidated: false`. Repeat its warning instead of presenting cached state as current.
+A current remote read requires an explicitly authorized `git fetch origin main` immediately before
+the report; record that fetch separately because the report itself performs no provider access.
 
 ## Trigger
 
@@ -21,7 +26,7 @@ recall — always read the file first, so the answer is correct even in a fresh
 
 ## Default: `/issues` (read-only)
 
-1. Read `docs/outstanding-issues.md`.
+1. Run `npm run issues:report -- --json` and use that payload, preserving its cached-state warning.
 2. State the **Recommended execution queue** back in order, including acuity, timing, and gate.
 3. Summarize any open items not represented in that queue, grouped by priority (P1 → P3), each as
    `#ID · type · summary — next action (source)`.
@@ -32,6 +37,13 @@ If a filter is given, filter the open items before rendering steps 2–3, then s
 queued tasks and matching non-queued items: `/issues P1` (by priority), `/issues issues` /
 `/issues recs` / `/issues tasks` (by type), `/issues <keyword>` (summary/detail substring match).
 
+`/issues wins` or `/issues agent-safe` runs
+`npm run issues:report -- --agent-safe-wins --json`. The classifier includes only queued work
+estimated at no more than four hours whose capability is not Operator and whose timing/outcome names
+no provider, live environment, RAG/retrieval/clinical surface, approval, owner decision, or human
+decision. Keep report order unchanged and always state A1 priority blockers before these convenience
+wins; the filter never changes acuity.
+
 **A row being open is not evidence that nobody is working on it.** Some rows carry a progress marker
 in their prose (`IN PROGRESS`, `IMPLEMENTED in PR #1766`), but there is no structured status field and
 no atomic claim — a marker is written by whoever did the work, usually after the fact, and nothing
@@ -85,6 +97,13 @@ to prevent; treat it like `ledger:append` for the review ledger. It does **not**
 between concurrent branches (see `#156` / `#168`) — that needs a different id scheme, not a better
 writer.
 
+Immediately before any mutation, explicitly refresh `origin/main` after provider authorization,
+then run `npm run issues:report -- --json` again and rebuild the intended edit against that cached
+ref rather than the worktree copy. Record the fetched SHA because the report deliberately does not
+claim that a local remote-tracking ref is independently revalidated. After the writer returns,
+inspect `git diff -- docs/outstanding-issues.md` and refuse any result that drops or duplicates
+unrelated rows. Never use GitHub's Update branch button for a PR touching this file.
+
 - Keep the table format and column order exactly as in `docs/outstanding-issues.md`. One row per item.
 - Add a retained task to the recommended queue with order, acuity, capability, timing, estimate,
   gate, success criteria, verification, and stop rule. Reorder rather than duplicate related work.
@@ -96,8 +115,8 @@ writer.
 - This file deliberately has **no** merge driver, so an overlapping edit conflicts loudly.
   `merge=union` was tried and removed: it concatenated both sides silently, duplicating rows and
   the `next-id` marker (`#133`). Never resolve a conflict by taking one side wholesale — that
-  drops the other agent's rows. Rebuild from `origin/main` and re-apply only the rows you
-  changed. `npm run check:outstanding-issues` fails on duplicate IDs, a stale next-id marker,
+  drops the other agent's rows. Rebuild from `origin/main` and re-apply only the rows you changed;
+  never take either side wholesale. `npm run check:outstanding-issues` fails on duplicate IDs, a stale next-id marker,
   or a merge driver reappearing.
 - Respect the repo's RAG/clinical/privacy flagging rules if an item _itself_ touches a protected
   surface — recording it here is fine, but acting on it later still needs the usual gate.

AGENTS.md

@@ -883,8 +883,9 @@ status ledger. Update the universal ledger when work completes, is dropped, beco
 materially re-scoped. Never restore completed, duplicate, speculative, superseded, or rejected work
 to the recommended queue.
 
-- When the user types `/issues`, invoke the `issues` skill (`.claude/skills/issues/SKILL.md`): read
-  `docs/outstanding-issues.md`, state the recommended queue in order, then summarize other open
+- When the user types `/issues`, invoke the `issues` skill (`.claude/skills/issues/SKILL.md`): run
+  `npm run issues:report -- --json` to read the cached `origin/main` ledger with an explicit stale-state warning;
+  refresh that ref first only with provider authorization. State the recommended queue in order, then summarize other open
   items by priority. A plain `/issues` is read-only — it mutates and commits nothing.
 - `/issues add|done|update|capture …` mutate the ledger; each mutation commits **only**
   `docs/outstanding-issues.md` (no push unless the user asks or you are already handing off).