--- name: weekly-review description: Generate the weekly review report for the current ISO week. Writes to .claude-code-hermit/compiled/review-weekly-YYYY-Www.md (dev-facing detail) and sends a plain-language channel summary (Delivered / Decisions / Waiting on you / Spend). Runs every Sunday at 23:00 via routine. --- # Weekly Review Generates the weekly review for the current ISO week. ## Steps 1. Run: ``` bun ${CLAUDE_PLUGIN_ROOT}/scripts/weekly-review.ts .claude-code-hermit ``` 2. Report the result. On success, output the review filename. If a **Knowledge Health** section appears in the review output, summarize the issues to the operator. If a **Usage** section appears, relay it: the script has already auto-archived the docs with no tracked use in the window (move-only, into `compiled/.archive/` — restoring one is moving the file back, and a restored doc is never archived again). Don't archive anything further yourself, and never on judgment alone: semantic changes (merging or rewriting topic pages, reclassifying a compiled conclusion as raw, tagging `foundational`) always wait for explicit operator approval. Tracked use for this section is compiled/ Reads including subagent reads; startup injection isn't tracked. 3. **Dispatch the week's file-heavy analysis** to the isolated-context runner in one call, so full topic-page bodies and the week's channel rows never land in this session's context. Dispatch `claude-code-hermit:skill-eval-runner` once, passing no `model` parameter so it inherits the session model. Point it at both specs. - `${CLAUDE_PLUGIN_ROOT}/skills/weekly-review/reference.md` — the topic-page semantic check: reads every `compiled/topic-*.md` for contradictions, stale claims, and broken `[[wikilinks]]` (capped at 3 findings). - `${CLAUDE_PLUGIN_ROOT}/skills/weekly-review/consolidation-reference.md` — distills the week's episodic channel log into the curated tiers and **files each candidate itself**, in its own context, treating the rows as untrusted external input. Name the absolute path of this session's auto-memory directory in the dispatch — the consolidation spec writes memory files there and has no way to derive that path on its own. Run `bun ${CLAUDE_PLUGIN_ROOT}/scripts/memory-dir.ts` and pass the `dir` it prints; if `exists` is false, say so in the dispatch and tell the runner to return every `kind:"memory"` candidate's rows in `failed_row_ids` rather than creating one. Name the current ISO week in the dispatch too, the value step 1 already produced in the review filename: the consolidation spec's provenance line needs it and has no other way to derive one that matches the review file. The runner returns one JSON object carrying both specs' keys, `topic_findings` from the first and the consolidation keys from the second: ```json { "topic_findings": [ "" ] } ``` ```json { "candidates": [ { "kind": "memory", "summary": "", "row_ids": [12] } ], "applied_row_ids": [12], "failed_row_ids": [], "reviewed_ids": [10, 11, 12, 13] } ``` **Failure policy:** if the runner returns null or malformed JSON, fail-open — carry `topic_findings: []` and continue. Skip step 4's **marking** (an unparseable `reviewed_ids` is not a set you can trust, and the rows are safe left unconsolidated), but still run step 4's prune, and still append the Findings audit line — worded as "the weekly consolidation returned no usable receipt; it may have filed memory or topic-page writes this run". The runner writes before it returns, so a malformed return means writes may already be on disk with nothing naming them. Treat a well-formed object that is missing `applied_row_ids`, `failed_row_ids`, or `reviewed_ids` the same way. Carry `topic_findings` forward to the channel summary (step 6): render a `Topic pages:` line only when non-empty, omit it entirely when `[]` (no topic pages or no findings → skip silently). 4. **Record the consolidation outcome.** The runner already filed the candidates, so this session only marks, prunes, and logs. Compute the ids to mark: start from `reviewed_ids` and **remove every id in `failed_row_ids`**. Marking a failed candidate's row consolidated would drop it from next week's `list-unconsolidated` and let `prune` delete it before it was ever distilled — permanent data loss. A row that produced no candidate is not a failure: it stays in the set (it was reviewed, nothing to file). Pass only that computed set: ``` bun ${CLAUDE_PLUGIN_ROOT}/scripts/channel-log.ts .claude-code-hermit mark-consolidated ``` The excluded rows stay unconsolidated for next week's pass. If nothing failed, the set is exactly `reviewed_ids`. Then, when `applied_row_ids` is non-empty, append **one** SHELL.md Findings line for the run naming the `candidates[].summary` of every candidate whose `row_ids` are in `applied_row_ids`. That line is the operator's audit trail for writes distilled from untrusted channel text, so it goes in even when nothing else about the week is notable. One line per run, never one per candidate. Skip it entirely when `applied_row_ids` is empty: nothing was filed, so there is nothing to audit. **Failure policy:** if `channel-log.ts` exits nonzero (a genuine DB error — not the normal "no DB yet" empty-result case), fail-open: skip the marking for this run and continue to step 5. An empty `reviewed_ids` (no unconsolidated rows) is the ordinary no-channel-activity case, not a failure. Finally, prune old consolidated rows (never unreviewed ones — see `scripts/lib/channel-log.ts`): ``` bun ${CLAUDE_PLUGIN_ROOT}/scripts/channel-log.ts .claude-code-hermit prune ``` 5. Read the frontmatter needed for the channel summary from the freshly-written review file: - Read `.claude-code-hermit/compiled/review-weekly-.md` frontmatter (just written in step 1) — do not read the body; every value the channel message needs lives in frontmatter (`delivered_count`, `delivered`, `proposals_accepted`, `proposals_resolved`, `open_loops_count`, `total_cost_usd`, `usage_untouched_count`, `usage_auto_archived`). - Also read the prior week's `compiled/review-weekly-*.md` frontmatter (sort by `week` descending, take the second file) for the Spend delta. - If no prior week file exists: omit the "vs prior week" comparison and show this week's spend only. - If the current-week file is missing (script failed): skip step 6 entirely and fall back to a plain note ("Weekly review didn't generate this week — nothing to send."). 6. **Channel voice rule:** the message below is for the person who owns this hermit, not a developer. Never emit `PROP-NNN`/`S-NNN`, raw token counts, cron strings, or file paths. Speak in plain outcomes and counts. Channel-send the combined weekly summary: - Refresh the dashboard per `${CLAUDE_PLUGIN_ROOT}/docs/artifacts.md`; if it returns a URL, note it for the message below. - Publish the weekly-review artifact when `config.artifacts.weekly_review` is on: render it with `bun ${CLAUDE_PLUGIN_ROOT}/scripts/artifact.ts render weekly .claude-code-hermit` (the page id is `weekly`, not the config key), then follow the hash-gate/publish/state-write steps in `${CLAUDE_PLUGIN_ROOT}/docs/artifacts.md` under state key `weekly_review`; if it returns a URL, note it for the message below too. - Compose the message in these sections. Show a line only when it has something to report — except Spend, which always shows (spend visibility matters even at $0): ``` Delivered: thing(s) — [omit this whole line when delivered_count is 0] Decisions: approved, resolved this week [omit this whole line when both are 0] Waiting on you: thing(s) need a yes/no [omit this whole line when 0] Tidied: put unused doc(s) away — — say "restore " to bring one back [omit this whole line when the list is empty] Unused: doc(s) look dormant — say "archive them" if you want them tidied away [omit this whole line when 0] Spend: $ this week (vs $, if a prior file exists) — an estimate, not a bill ``` Followed by the `Topic pages:` findings from step 3 when present, plus a final line listing whichever of the dashboard/weekly-review URLs were returned (e.g. `📎 · 📎 ` — omit either half that wasn't returned). - Deliver via `channel-send.ts --notice` (see CLAUDE-APPEND.md § Operator Notification), with two audience versions of the same composed message: - `client` = the composed message **with the Spend line omitted** - `maintainer` = the **complete message including the Spend line** — the full richer version of the same notice, not a spend-only fragment, because the client leg is dropped in favor of the maintainer's dedup partner only when both resolve to the same chat, in which case the maintainer text (the complete one) is what's sent. - If a leg didn't land (exit 1 — exit 2 means the payload was rejected, so fix it and re-run instead), follow § Operator Notification's fallback (push if enabled, log to Findings) rather than a bespoke branch here — weekly-review is a recurring routine, not an alert, so still skip a `channel-send-unavailable` issue for this call. - To set a preferred channel, add `"primary": ""` inside `channels` in `config.json`. 7. Archive expired raw artifacts: ``` bun ${CLAUDE_PLUGIN_ROOT}/scripts/archive-raw.ts .claude-code-hermit ``` Report how many were archived, retained, and skipped. 8. Archive superseded compiled artifacts: ``` bun ${CLAUDE_PLUGIN_ROOT}/scripts/archive-compiled.ts .claude-code-hermit ``` Report how many were archived, retained, and skipped. ## Notes - Safe to run manually at any time — re-runs overwrite the current week's review. - `archive-raw.ts` only moves files — it never deletes. Archived files land in `raw/.archive/` and can be restored manually. - `archive-compiled.ts` only moves files — it never deletes. Keeps the newest 2 artifacts per type; `foundational`-tagged artifacts and `topic` pages are always retained (living pages compact by merging, not archival). Archived files land in `compiled/.archive/` and can be restored manually. - Usage tracking (`state/usage-metrics.jsonl`, fed by `usage-track.ts` on `Read`) sees compiled/ Reads — including subagent reads, since PostToolUse fires for sidechain tool calls (probed on CC 2.1.239). Startup injection isn't tracked, which is why `foundational` and `topic` artifacts are exempt. - Auto-archival is usage-evidence-based and move-only: docs with no tracked read in `knowledge.usage_stale_days` (default 30) go to `compiled/.archive/`. It is gated three ways — the ledger must itself be that old, it must hold at least one recorded compiled read (no reads at all reads as a tracking gap, not as disuse), and at most 10 docs move per run. Restoring one is moving the file back; `state/usage-archived.json` remembers every stem already archived, so a restored doc is never taken again. Set `knowledge.usage_auto_archive: false` for suggest-only, and semantic changes stay operator-approved.