/brief

name: brief
description: Returns a 5-line executive summary of recent work. Checks active session first, falls back to latest report. Activates on messages like "brief", "what happened", "morning update", "overnight summary", "progress", "what are you working on", "how's it going".

Session Brief

Provide a concise executive summary of recent session activity. Designed for morning check-ins, phone/channel consumption, and quick status updates.

Always-On Delivery Rule

If `config.always_on` is `true`, deliver all operator-facing output per `CLAUDE-APPEND.md § Operator Notification`. The terminal is unmonitored in always-on mode. For the push-fallback branch, condense the brief to a single line (per § Operator Notification push format): include whichever of open proposal count and active heartbeat alerts are present and non-zero; omit zero or unavailable fields. Example: `Brief: 16 proposals open, 1 alert — open CC to view`. In interactive mode, output to terminal. This applies to all flags below.

Dispatch

Before composing any brief, determine the dispatch mode:

1. Read `session_state` from `.claude-code-hermit/state/runtime.json` (live state — always in main). 2. Resolve the active flag (`--morning`, `--evening`, "brief today"/"daily summary", or no flag).

Live files (SHELL.md, `alert-state.json`, `proposals/`) are read fresh on this turn; a value held in context from before a compaction is stale.

**Dispatch decision:**

• `--morning` → dispatch (mode: `morning`)
• `--evening` → dispatch (mode: `evening`)
• "brief today" / "daily summary" / "what happened today" → dispatch (mode: `daily`)
• No flag + `session_state` is `in_progress` → **no dispatch** — summarize the live SHELL.md in main (Plan step 1a)
• No flag + `session_state` is `idle` → **no dispatch** — read the live SHELL.md in main and emit the idle block (Plan step 1b)
• No flag + no active session (no SHELL.md / no `session_state`) → dispatch (mode: `default-no-session`, Plan step 1c)

For dispatching modes: invoke `claude-code-hermit:skill-eval-runner` pointed at `${CLAUDE_PLUGIN_ROOT}/skills/brief/reference.md`. Pass in the dispatch prompt: `plugin_root` (the resolved absolute path — `${CLAUDE_PLUGIN_ROOT}` is not substituted in `reference.md`), `mode` (one of the values above), `today` (current ISO date), and for `morning` only: `context_recovery` (set to `true` if auto-memory seems sparse — new instance, fresh machine — `false` otherwise).

**Boundary rule:** `sessions/SHELL.md` is the live session document — it stays in main, never goes to the runner. Archived `sessions/S-*-REPORT.md` bodies, `proposals/*.md` frontmatter, `OPERATOR.md`, and `NEXT-TASK.md` go to the runner.

**Failure policy:** if the runner returns null or malformed JSON, fail-open — compose the brief from whatever live data main holds (SHELL.md) and skip the runner-derived lines. Note nothing fatal to the operator.

**Eval runner return schema** — the runner returns a JSON object conforming to this block. The schema is byte-identical in `reference.md` (producer) and here (consumer); a contract test asserts this.

<!-- brief-eval-schema:start -->

{
  "report_summary": { "date": "<ISO>", "tags": ["<tag>"], "working_on": "<one-line>",
                       "status": "<completed|partial|blocked>", "next_start_point": "<text>" }|null,
  "sessions_today": [ { "session": "S-NNN", "summary": "<one-line>" } ],
  "findings": ["<text>"],
  "tomorrow": ["<text>"],
  "pending_proposals": ["<PROP-NNN: title>"],
  "operator_priorities": ["<text>"],
  "queued_work": ["<text>"]
}

<!-- brief-eval-schema:end -->

Flags

--morning (routine mode)

**Delivery:** Write the full composed brief text (before any push-fallback single-line condensing) to `.claude-code-hermit/state/last-brief.json` as `{"kind":"morning","text":"<brief text>","generated_at":"<now, ISO>"}`, so the dashboard's "latest brief" section can pick it up. Then refresh the dashboard per `${CLAUDE_PLUGIN_ROOT}/docs/artifacts.md`; if it returns a URL, append a final line `📎 <url>`. Then deliver the brief to the operator (see Always-On Delivery Rule above).

Emphasize forward-looking content. Compose from runner JSON (see Dispatch above) and live main-session data:

• **Pending proposals:** use `runner.pending_proposals`
• **Operator priorities:** use `runner.operator_priorities`
• **Queued work:** use `runner.queued_work`
• **Context recovery:** if `runner.report_summary` is non-null, use it for session context
• If `config.always_on` is `true`: frame as "what happened overnight (activity since evening routine)"
• If `config.always_on` is `false`: frame as "here's where things stand"
• If `config.always_on` is `true`: run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-upgrade.sh" "${CLAUDE_PLUGIN_ROOT}"` from the project root. If it emits an `---Upgrade Available---` section, append a final line to the brief: `⚠ Plugin update available: <the version line>` (pass the directive verbatim). If it emits `---Stale Plugin Runtime---` instead, append `⚠ Stale plugin install: <the notice>` — never label it an update, and never turn it into an evolve instruction (evolve cannot fix a stale install). Output nothing if the script is silent. (Interactive operators already see this notice at session-start step 2; the gate avoids double-notification.)

After composing the morning brief, age the micro-proposal queue in one pass: run `bun ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.ts micro .claude-code-hermit brief-cycle`. It reads `state/micro-proposals.json`, runs the whole lifecycle atomically (re-nudges `follow_up_count` 1 entries, expires `follow_up_count` ≥2 entries and records each expiry, prunes any entry whose `status` isn't `"pending"`), and prints one JSON line `{"new":[…],"renudged":[…],"expired":[…],"dropped":[…]}` — never hand-edit the file or read it separately. Render straight from that verdict:

• Each `new` entry (first display): append as a final line. Without `options`: `MP-YYYYMMD