Guide Freshness Check

---
name: guide-freshness-check
description: Weekly dev-env maintenance (REPORT-ONLY): external currency + internal drift pulse + ~/.claude audit → one combined report in ~/Developer.
---

Run the weekly DEV-ENV MAINTENANCE pass. **STRICTLY REPORT-ONLY** — your only writes are the two output files below; do NOT edit any docs, do NOT install/update/enable/disable any plugin or MCP, do NOT apply any fix. Detect + recommend only; the operator and a follow-up agent review and apply.

Do all three checks, then write ONE combined report:

(A) EXTERNAL currency — follow `~/.claude/commands/freshness.md` exactly: referenced github repos from your repo registry/watchlist, if you keep one, via `gh api` (drop reserved paths like topics/; detect 404 by exit code); `claude plugin marketplace update` then `claude plugin list`; `claude mcp list` core MCP health (context7 · semgrep · pinecone · chrome-devtools · serena · sequential-thinking) — IGNORE the dept-pack `plugin:engineering|data|design:*` stubs. Guide root = `$HOME/Developer/guide-setup`.

(B) INTERNAL drift — do `~/.claude/commands/groom.md` STEP 1 ONLY (the read-only "pulse"): compare documented state vs reality for the guide repo and the global brain (`$HOME/Developer/CLAUDE.md` + `CONTEXT.md` + `memory/`); score drift. Do NOT do any of groom's editing steps — **not §1b (the drain) and not §2–5**. You detect; `/groom` applies.

(B2) TEMPLATE conformance — **still part of check (B); its findings go in the Internal-drift section, not a fourth one.** The stamps drift silently because nothing reads them between projects.

**Judge ONLY against the required set. Optional sections are never a finding — present or absent, in any stamp.**
- **REQUIRED** (KORTANNA §4's project minimum): title + one-line identity · Workspace Map · **Routing** · Conventions · Current State · Avoid.
- **OPTIONAL, by design** — `Stack · Routing · Commands`, `Validation`, `Project-Specific Rules`, `Key Decisions (ADRs)`. The stamps deliberately carry different subsets (`templates/_index.md`: they differ "only in how many optional rows they carry"), so a difference here is **not** drift. Flagging it would mint a finding nobody can legitimately fix, which then escalates to `⚠️ STALE` forever — the exact rot this routine exists to prevent.
- **Routing may be satisfied by a bullet, not a heading.** Both project stamps carry it inside `## Stack · Routing · Commands`. Do not require a `## Routing` heading; require that routing information exists.

Two sub-checks, both read-only:
  - **Stamps vs their source of truth.** Compare `$HOME/Developer/projects/_template/CLAUDE.md`, `$HOME/Developer/clients/_template/CLAUDE.md`, and `$HOME/Developer/guide-setup/method/templates/new-project/project-CLAUDE.md.template` against §4's shape (b) — **required set only**. Flag a stamp missing a required section, or two stamps disagreeing on a **required** one.
  - **Live workspaces vs the same minimum.** Every project/client `CLAUDE.md` under `$HOME/Developer/{projects,clients}/*/`. **Routing is the one that actually breaks things** — without it the parent brain's row lands on a file that describes but dispatches nowhere. Do NOT flag deliberate scope exemptions: `$HOME/Developer/CLAUDE.md` and the guide repo omit Current State by design (§4 item 12's Scope clause); a **client** CLAUDE.md omits `Stack · Routing · Commands` and `Validation` by design (§4 shape (b), "Client variant").

**Keying — the one exception to the basename rule below.** Every project's L0 file is named `CLAUDE.md`, so a basename-only key would merge findings across projects and let one `fix applied` line silently clear the rest. For `CLAUDE.md`/`CONTEXT.md` findings, key on **enough of the path to be unique** — normally `<parent-dir>/<basename>#<slug>`, but two stamps both sit in a dir named `_template`, so those key on `projects/_template/CLAUDE.md#…` and `clients/_template/CLAUDE.md#…`. If two findings would share a key, lengthen the path until they don't — a merged key lets one `fix applied` line silently clear the other. Everything else keys on basename as usual. Route per the escalation rules below: stamps under `$HOME/Developer/guide-setup` → a guide-setup-rooted session; live project/client files → that project's own session or `/groom` in `$HOME/Developer`.

(C) ~/.claude AUDIT — groom step 5's system-layer check: hooks parse (`bash -n`) + their referenced files exist; commands/rules not broken or stale; `settings.json` valid JSON; no orphans.

OUTPUT (the only things you write):
- **First, age every finding.** Each finding has a **key**: `<file basename>#<subject-slug>` (e.g. `library-reference.md#react-video-editor`), or the plugin/MCP name. Derive the slug from the **subject only** — *what* is wrong — lowercase-hyphenated, from the file's **basename** (not its path — **except** where the basename is not unique across workspaces, e.g. `CLAUDE.md`/`CONTEXT.md`, which key as `<parent-dir>/<basename>`, see B2), and **containing no value that changes between runs**: no line numbers, dates, day counts, or version strings (`2.5.0→2.9.0` and `2.5.0→2.11.2` are the SAME finding; a slug like `primer.md#stale-36d` becomes `#stale-43d` next week and matches nothing). **If the previous `open:` list already carries a key for the same file + subject, REUSE IT VERBATIM** instead of re-deriving — a re-derived key that differs by one word silently resets the count, which is the whole failure this keying exists to prevent. Read `$HOME/Developer/_dev-env-health-log.md`, take the **most recent maintenance line**, and treat its `open:` list as the ONLY count source (a freshness, fix-applied, still-open or note line is NOT a run — don't count off one, and never re-derive counts from older prose). Then per finding: **N = that key's count in that list, + 1** — or **N = 1** if the key isn't listed or the log is absent. **If there is NO maintenance line at all** (a fresh install — a `freshness` line is not one), N = 1 for everything and print no warning. **If a maintenance line EXISTS and says `open: (none)`**, that was a clean run — N = 1 for everything, print no warning. **If a maintenance line EXISTS but carries no `open:` field at all**, restart every count at 1 **and print** `⚠️ previous run omitted its open: list — counts restarted` at the top of the report: a silent restart is exactly how this mechanism would rot back to useless. A **`fix applied`** line resets a key to 0 **only when it was appended after that most recent maintenance line**; ignore older ones, or one legacy line would suppress its keys forever. A **`still open`** line never clears anything.
- Overwrite `$HOME/Developer/_dev-env-health.md` — three sections (External / Internal drift / ~/.claude), each listing ONLY what needs action as `{what · where (file:line) · key · recommended fix · Nth run, first seen YYYY-MM-DD}`; if a section is clean, say "✅ current". Keep it short.
- **Escalate the stale.** Any finding on its **3rd run or older** **MOVES** (not copies — one fact, one location) into a `## ⚠️ STALE — apply now` block at the TOP of the report, above section 1: `{what · where · key · fix · Nth run, first seen YYYY-MM-DD}` — **keep the `key`**, since escalated findings move out of their section and the drain logs by key. Say plainly that detection is working and the *drain* is what's overdue, and **route each by class**: findings under `~/Developer/guide-setup` → **a guide-setup-rooted session** (the guide is read-only to every other session, so `/groom` would be denied); other doc/ADR/context findings → **run `/groom` in `~/Developer`**; `~/.claude` items, plugin/MCP updates, "classify or archive" judgment calls, and rewrite-scale doc rewrites → **needs the operator directly** — `/groom` is forbidden from those, so never route them to it. If nothing is ≥3 runs old, omit the block entirely.
- Append one dated line to `$HOME/Developer/_dev-env-health-log.md`: `YYYY-MM-DD · maintenance · <one-line verdict per section> · open: <key> ×N, <key> ×N, …` — that `open:` list is the ONLY thing that makes the next run's aging possible, so **always emit it: one entry per open finding, with its key and run count — and when there are no open findings, write `open: (none)` rather than omitting the field.**

Then summarize the report in your final message — **lead with the STALE block if there is one.** Nothing else.