@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/features/routines/evening-review.md

@@ -9,73 +9,126 @@ aliases:
   - retro
 category: features
 summary: |
-  The evening review fires once per day at 18:00 local time. It writes
-  the day's retrospective into the agent journal and rolls up unfinished
-  items for tomorrow's plan.
+  The evening review fires once per day at 18:00 local time. It closes out
+  the day by finalizing today.md's Handoff, doing light roadmap maintenance,
+  and folding the day's profile signals into your identity files. It rolls
+  up unfinished items so tomorrow's morning routine can re-pick them up.
 section: routines
 tags:
-  - routine
+  - routines
   - autonomous
   - daily
-  - light-tier
+  - core
 status: stable
 ask_examples:
   - When does the evening review run?
   - What does the evening review write?
-  - How do I disable it?
+  - How do I add my own evening checks?
+  - How do I disable the evening review?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - evening review
   - retro
   - end of day
+  - handoff
+  - carry-over
 related:
   - concepts/routines
   - features/memory-files/agent-journal
+  - features/memory-files/today
   - features/routines/morning-routine
+  - features/routines/custom-routines
 process_keys:
   - routine.evening_review
+context_files:
+  - state/today.md
+  - plans/roadmap.md
+  - journal/agent.md
+  - identity/profile.md
+  - policies/routines/evening.md
+ui_anchors:
+  - /connections/journal
+  - /settings/routines
 ---
 
 # Evening Review
 
 ## In One Sentence
 
-A light-tier routine that fires daily at 18:00 local time and writes
-the day's retro into the journal.
+A medium-tier autonomous routine that fires daily at 18:00 local time to
+close out the day: it finalizes the carry-over plan in `state/today.md`,
+does light roadmap maintenance, and folds the day's profile signals into
+your identity files.
 
 ## What It Does
 
-- Reads the day's `today.md`, the journal entries, the activity feed.
-- Writes a short retrospective into `agent/journal.md`.
-- Surfaces uncompleted carry-over items the morning routine should
-  re-pick-up tomorrow.
+The routine runs three internal bookkeeping steps. These are quiet by
+design — they prepare state that **tomorrow's morning routine depends on**
+rather than producing a chatty end-of-day report.
+
+1. **Finalize `state/today.md`.** Marks incomplete User Tasks, then fills
+   the `## Handoff` section: unfinished items roll into **Tomorrow** (with
+   a reason and suggested priority) so the morning routine re-picks them up;
+   longer-horizon items go to **Later**.
+2. **Light roadmap maintenance.** Promotes resolved Long-term Plans into the
+   Agent Action Plan and fires any plans whose review date has arrived,
+   editing only `## Long-term Plans` and `## Agent Action Plan` in
+   `plans/roadmap.md`. (The purely mechanical roadmap sweeps run 15 minutes
+   earlier as a separate daemon job, not here.)
+3. **Process profile signals.** Reads the day's Raw Signals from your
+   profile and routes each into `character`, Learned Context, or a
+   detailed identity file under `identity/`, then prunes stale entries.
 
 ## When It Runs / How It Is Triggered
 
 Every day at **18:00 local time**, exactly once. The cron expression
-is fixed in `packages/daemon/src/core/scheduler.ts` and is not
-operator-configurable.
+(`0 18 * * *`) is fixed in `packages/daemon/src/core/scheduler.ts`; the
+fire time is not operator-configurable. Like every autonomous cron, the
+run is skipped while the agent is paused (`!stop`) or setup is incomplete.
 
 ## What It Outputs
 
-- An `agent/journal.md` entry.
-- A "today wraps up here" notification (subject to quiet hours).
+- An updated `## Handoff` section in `state/today.md`.
+- Roadmap edits in `plans/roadmap.md` when a plan was promoted or fired.
+- A `journal/agent.md` line **only** when a roadmap review date fired or a
+  validation error needs recording.
+
+The built-in steps emit **no user-facing DM by default** — there is no
+"today wraps up here" message. (The one exception: any check you add to
+`policies/routines/evening.md` is authoritative and runs as written,
+including steps that call `POST /api/notify`.)
 
 ## Where in the Dashboard
 
-- **Connections → Journal** shows the appended entry.
+- **Connections → Journal** (`/connections/journal`) shows `journal/agent.md`
+  entries when the roadmap step logged one.
+- **Settings → Routines** (`/settings/routines`) is where you manage the
+  evening rulebook.
 
 ## Configuration
 
-This routine has no operator-tunable knobs. The fire time and tier
-are fixed in code.
+The fire time and tier are fixed in code, but the routine is not a black box:
+- **Add your own evening checks.** Append `### <label>` entries to
+  `policies/routines/evening.md` (via the dashboard, or the
+  [custom routines guide](../../guides/add-a-custom-routine.md)). They run
+  alongside the built-in steps using the same journaling conventions and
+  may notify you explicitly.
+- **Verify it stays healthy.** `aitne verify evening-review-slimdown`
+  checks that recent `routine.evening_review` sessions ran inside their
+  seeded token envelope (read-only; `--days N` widens the window).
 
 ## When Something Goes Wrong
 
-- A journal that **stops growing**: see [Auth Failed](../../troubleshooting/auth-failed.md) — the routine may be hitting a quota wall.
+- **The Handoff or journal stops updating:** the routine may be hitting a
+  quota wall — see [Quota Exhausted](../../troubleshooting/quota-exhausted.md)
+  or [Auth Failed](../../troubleshooting/auth-failed.md).
+- **It never fires at all:** confirm the agent is not paused (`!start`) and
+  that setup is complete.
 
 ## Related
 
-- [agent/journal.md](../memory-files/agent-journal.md)
+- [today.md](../memory-files/today.md) — where the Handoff lives.
+- [agent journal](../memory-files/agent-journal.md) — `journal/agent.md`.
+- [morning routine](morning-routine.md) — consumes the Handoff next day.

package/agent-assets/docs/features/routines/hourly-check.md

@@ -6,80 +6,200 @@ id: hourly-check
 aliases:
   - hourly
   - observation consumer
+  - hourly check gate
 category: features
 summary: |
-  A light-tier routine that fires every hour during active hours and
-  consumes accumulated observations from the polling integrations.
+  A medium-tier routine that fires every hour during active hours,
+  drains the pending observations queue, and decides whether the
+  accumulated change pattern warrants surfacing. Runs through a
+  four-layer gate that keeps quiet days quiet.
 section: routines
 tags:
-  - routine
+  - routines
   - autonomous
-  - light-tier
+  - observations
+  - polling
+  - hourly-check
 status: stable
+ui_anchors:
+  - /settings/routines
+  - /settings/schedule
+  - /activity?tab=system
 ask_examples:
   - What does the hourly check do?
   - When does it run?
-  - How do I tune the threshold?
+  - How does the hourly check decide whether to escalate?
+  - What is the harvest pre-pass?
+  - How do I tune the gate's freshness window?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - hourly
   - observations
   - polling
+  - hourly check
+  - gate
+  - layer 1
+  - layer 2
+  - layer 3
+  - harvestForGate
+  - decideStage
+  - pre-pass
 related:
   - concepts/observations
   - concepts/routines
+  - concepts/delegated-mode
+  - features/integrations/browser-history
 process_keys:
   - routine.hourly_check
+  - routine.hourly_check.triage
+  - routine.fetch_window
 config_keys:
   - hourlyCheckEnabled
   - hourlyCheckIntervalMinutes
   - hourlyCheckActiveStartHour
   - hourlyCheckActiveEndHour
   - hourlyCheckMinObservations
+  - hourlyCheckStage2Enabled
+  - hourlyCheckHeartbeatHours
+  - hourlyCheckLowSignalPendingCeiling
+  - hourlyCheckPrePassFreshnessMinutes
 ---
 
 # Hourly Check
 
-## In One Sentence
+A medium-tier routine that drains the observations queue every hour
+during active hours and decides whether the accumulated change
+pattern warrants notifying you or appending to `state/today.md`. The
+"decide" step is a four-layer gate designed to keep quiet days quiet
+without missing the moment when something piles up.
 
-A light-tier routine that empties the observations queue and decides
-whether the accumulated changes warrant a notification.
+## When It Runs
 
-## What It Does
+Every `hourlyCheckIntervalMinutes` (default 60), inside the active
+window `[hourlyCheckActiveStartHour, hourlyCheckActiveEndHour)`. The
+trigger:
 
-- Reads pending `observations` rows.
-- Decides whether the pattern adds up to something worth surfacing.
-- Either appends to `today.md` or sends a notification (or both).
+- **Skips** when the morning routine has not yet run today
+  (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
+  self-recovery and the hourly check resumes after the morning
+  routine succeeds).
+- **Skips** when another hourly check is in flight (atomic flag).
+- **Skips** when accumulated signal is below
+  `hourlyCheckMinObservations` and the heartbeat window
+  (`hourlyCheckHeartbeatHours`) hasn't elapsed.
 
-## When It Runs / How It Is Triggered
+Every tick writes one `agent_actions` row with
+`action_type = 'hourly_check.gate'` so the gate's decisions are
+auditable from `aitne audit` and the dashboard activity feed.
 
-Every `hourlyCheckIntervalMinutes` (default 60), inside the active
-window (`hourlyCheckActiveStartHour` to `hourlyCheckActiveEndHour`).
-Skips when the morning routine is in progress; an atomic flag
-prevents two hourly checks from running at once.
+## The Four-Layer Gate
+
+The gate replaced the pre-Phase-9 "30-minute rate-limit" gate. It
+runs on every cron tick; only Layer 4 actually spawns a medium-tier
+agent session.
+
+### Layer 1 — Harvest pre-pass
+
+`HourlyCheckCoordinator.harvestForGate` spawns a lite-tier
+`routine.fetch_window` session for each delegated / native
+integration whose `runtime_state.pre_pass_last_run:<key>` is older
+than `hourlyCheckPrePassFreshnessMinutes`. The pre-pass fetches the
+integration's hourly window (mail / calendar / Notion) and POSTs the
+results to `/api/observations`, so the rest of the gate sees a
+populated queue instead of stale data.
+
+Telemetry: `agent_actions.detail.harvest_ran` /
+`harvest_integrations` / `harvest_failed_integrations`.
+
+### Layer 2 — Signal compute
+
+`computeHourlyCheckSignals` reads the observation table mode-blind —
+it filters by source-prefix sets derived from
+`INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
+include unread-mail / event-change / repo-change / browser-history
+clusters; each category produces a (count, last-seen, summary)
+tuple. The pre-pass freshness gate from Layer 1 is what guarantees
+those counts reflect "now", not "an hour ago".
+
+### Layer 3 — Decide stage
+
+`decideStage` is a pure function over the signal snapshot plus the
+per-tick config (heartbeat status, `hourlyCheckStage2Enabled`,
+`hourlyCheckLowSignalPendingCeiling`). It returns one of three stages
+— `stage0_silent`, `stage2`, or `stage3`:
+
+| Stage | What happens |
+|---|---|
+| `stage0_silent` | No agent session. Consume the pending observations and append a single best-effort line to `state/today.md`'s `## Agent Log`. This is the verdict for both "no signals" and "low signal under the ceiling". |
+| `stage2` | Only reachable when `hourlyCheckStage2Enabled = true` (default `false`, so low-signal ticks fall through to `stage3`). Runs a lite-tier `routine.hourly_check.triage` call whose strict JSON output decides `log_only` (→ silent path) vs. `escalate` (→ `stage3`). |
+| `stage3` | Spawn the full medium-tier `routine.hourly_check` session — the visible agent run. Reached directly on high-novelty signals (VIP mail, calendar conflict, overdue agent plan, approaching schedule) or as the cautious default when Stage 2 is off. |
+
+When a Layer 1 pre-pass fails (`harvest.failed`), the gate
+short-circuits to a cautious `stage3` with reason
+`cautious_escalate_prepass_failure` and tags the audit row
+`agent_actions.detail.cautious_escalate = true` — a failed fetch
+should never silently swallow a tick's worth of signals.
+
+### Layer 4 — Dispatch
+
+When Layer 3 returns `stage0_silent` (or Stage 2 returns
+`log_only`), the daemon runs `runSilentHourlyCheckPath` — a
+daemon-direct write, no agent. When it returns `stage3` (or Stage 2
+returns `escalate`), `enqueueStage3HourlyCheck` puts a
+`routine.hourly_check` event on the bus, which becomes the visible
+agent session.
 
 ## What It Outputs
 
-- Updates to `today.md`.
-- Notifications when warranted.
+- A best-effort line in `state/today.md`'s `## Agent Log` — even the
+  silent path appends one (skipped only if `today.md` is missing or
+  the write lock is held; the observations are still consumed either
+  way).
+- Notifications when warranted (only on a `stage3` agent session).
+- An audit row on every tick:
+  `agent_actions.action_type = 'hourly_check.gate'`, carrying the
+  harvest + signal + stage detail.
 
 ## Configuration
 
-| Setting | Default |
-|---|---|
-| `hourlyCheckEnabled` | true |
-| `hourlyCheckIntervalMinutes` | 60 |
-| `hourlyCheckActiveStartHour` | 4 |
-| `hourlyCheckActiveEndHour` | 24 (end-exclusive, ≡ midnight) |
-| `hourlyCheckMinObservations` | 1 |
+| Setting | Default | Layer | Notes |
+|---|---|---|---|
+| `hourlyCheckEnabled` | `true` | trigger | Master kill switch. |
+| `hourlyCheckIntervalMinutes` | `60` | trigger | Cron cadence. |
+| `hourlyCheckActiveStartHour` | `4` | trigger | Active window start. |
+| `hourlyCheckActiveEndHour` | `24` | trigger | End-exclusive; `24` ≡ midnight. |
+| `hourlyCheckMinObservations` | `1` | trigger | Minimum pending observations before a non-silent stage dispatches; below this the tick records a `below_threshold` skip. |
+| `hourlyCheckPrePassFreshnessMinutes` | `30` | Layer 1 | Range `0`–`240`. Skip a per-integration fetch if its pre-pass ran more recently; `0` fetches every tick, `240` is cost-minimal. |
+| `hourlyCheckStage2Enabled` | `false` | Layer 3 | Adds the lite-tier triage call; while `false`, low-signal ticks route straight to `stage3`. |
+| `hourlyCheckHeartbeatHours` | `4` | Layer 3 | Range `1`–`48`. Force a non-silent stage at least this often, even on a quiet day. |
+| `hourlyCheckLowSignalPendingCeiling` | `0` | Layer 3 | Range `0`–`20`. At or below this pending count, a low-signal tick stays silent. `0` keeps the cautious default (any pending observation escalates). |
+
+(`hourlyCheckGateMode` was removed in HOURLY_CHECK_GATE_REDESIGN_PLAN
+Phase 4 — the gate has a single execution path now.)
 
 ## When Something Goes Wrong
 
-- Skipped hourly checks below the min-observations threshold are
-  expected. The daemon log shows the skip reason.
+- **Skipped because the morning routine hasn't run.** The
+  dispatcher's `morningRoutineRanToday` gate keys on
+  `agent_actions.result = 'success'`. The skip reason is
+  `morning_routine_pending_for_today` and triggers a
+  `queueMorningRoutineWake` self-recovery. See
+  [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
+- **Stage 3 never fires on a quiet day.** Expected.
+  `hourlyCheckHeartbeatHours` forces a tick occasionally so silence
+  doesn't last indefinitely.
+- **Pre-pass keeps failing for one integration.** Read
+  `agent_actions.detail.harvest_failed_integrations`; the failing
+  integration name is recorded. Usually an auth issue — check
+  `/health.integrationModes` and the integration's settings page.
 
 ## Related
 
-- [Observations](../../concepts/observations.md)
+- [Observations](../../concepts/observations.md) — what populates the
+  queue Layer 2 reads.
+- [Delegated Mode](../../concepts/delegated-mode.md) — the
+  delegated / native integrations that participate in Layer 1's
+  harvest.
+- [Routines](../../concepts/routines.md)

package/agent-assets/docs/features/routines/morning-routine.md

@@ -14,10 +14,9 @@ summary: |
   morning hour to produce today.md and the day's plan.
 section: routines
 tags:
-  - routine
+  - routines
   - autonomous
   - daily
-  - heavy-tier
   - core
 status: stable
 ask_examples:
@@ -27,12 +26,16 @@ ask_examples:
   - What model does morning routine use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - morning
   - day plan
   - 04:00
   - day boundary
+  - two-stage pipeline
+  - stage A
+  - stage B
+  - daily journal
 related:
   - concepts/agent-day
   - features/memory-files/today
@@ -40,15 +43,20 @@ prerequisites:
   - concepts/agent-day
 ui_anchors:
   - /settings/routines
+  - /settings/models
+  - /schedule
+  - /activity
   - /
 process_keys:
   - routine.morning_routine
-  - routine.morning_routine_initial
+  - routine.morning_routine_today
+  - routine.morning_routine_journal
 config_keys:
   - dayBoundaryHour
 context_files:
-  - today.md
-  - daily/<date>.md
+  - state/today.md
+  - journal/daily/<date>.md
+  - journal/agent.md
 ---
 
 # Morning Routine
@@ -56,26 +64,36 @@ context_files:
 ## In One Sentence
 
 Once per agent day, at `dayBoundaryHour` local time, Aitne
-rebuilds `today.md` and the day's schedule from your calendar, mail,
+rebuilds `state/today.md` and the day's schedule from your calendar, mail,
 roadmap, and recent observations.
 
 ## What It Does
 
 The morning routine is the single highest-value process in Aitne.
-It runs at the **heavy tier** (default Opus 4.7 on Claude, GPT-5.5 on
-Codex, Gemini 3 Pro on Gemini) because every downstream routine for
-the next 24 hours reads its output. A bad morning briefing degrades
-the entire day.
-
-In sequence, the routine:
-
-1. Reads the previous day's `today.md` and rolls forward unfinished items.
-2. Pulls today's calendar events from any connected calendar integration.
-3. Scans recent unread mail and surfaces the few that need owner attention.
-4. Walks the roadmap looking for items whose **Preparation Timeline** rows fire today.
-5. Consumes any pending observations the hourly check has already dropped into the queue.
-6. Writes the rebuilt `today.md` and the per-date snapshot at `daily/YYYY-MM-DD.md`.
-7. Logs a single status line to the dashboard activity feed.
+It runs as a **two-stage pipeline**, with both stages dispatched in
+parallel:
+
+- **Stage A** (`routine.morning_routine_today`, medium tier) rebuilds
+  `state/today.md`, walks the roadmap, fans out the day's schedule, and
+  self-reports structured metadata.
+- **Stage B** (`routine.morning_routine_journal`, lite tier) authors
+  yesterday's daily journal at `journal/daily/<yesterday>.md` from a
+  daemon-prepared skeleton, then drops the run's audit-trail paragraph
+  into `journal/agent.md`.
+
+Every downstream routine for the next 24 hours reads Stage A's output,
+so a bad morning briefing degrades the entire day — hence the
+medium-tier ceiling on Stage A even after the split.
+
+Within Stage A, the work proceeds in this order:
+
+1. Read the previous day's `state/today.md` and roll forward unfinished items.
+2. Pull today's calendar events from any connected calendar integration.
+3. Scan recent unread mail and surface the few that need owner attention.
+4. Walk the roadmap for items whose **Preparation Timeline** rows fire today.
+5. Consume any pending observations the hourly check has already queued.
+6. Write the rebuilt `state/today.md`.
+7. Log a single status line to the dashboard activity feed.
 
 ## When It Runs / How It Is Triggered
 
@@ -85,15 +103,21 @@ so a post-midnight install does not run two morning routines back-to-back.
 There is no separate `morningRoutineHour` — the morning routine and the
 agent-day rollover are the same instant.
 
-`routine.morning_routine_initial` is a one-shot heavy-tier variant fired
-during the setup wizard's first day. After the first run, only
-`routine.morning_routine` triggers.
+There is no separate "initial" process key. The first morning after
+setup is detected inline by Stage A from the absence of `state/yesterday.md`;
+the daemon injects a `<roadmap_skeleton>` block carrying the pre-aggregated
+Annual Goals / Quarterly Focus / Preparation Timeline facts so Stage A
+can populate the wizard's placeholder roadmap on medium tier instead of
+paying for a one-shot high-tier session. (The dedicated
+`routine.morning_routine_initial` process key was retired in Phase 4, and
+Phase 7 — 2026-05-16 — removed its high-tier seed entirely.)
 
 ## What It Outputs
 
-- A rebuilt `today.md` with sections for User Schedule, Tasks, Agent Plan, Agent Log, and Handoff.
-- A per-date `daily/YYYY-MM-DD.md` capturing the day's calendar snapshot.
-- A short notification ("Good morning, here's today...") when notifications are enabled and quiet hours have ended.
+- A rebuilt `state/today.md` with sections for User Schedule, User Tasks, Agent Plan, Agent Log, and Handoff (Stage A).
+- Yesterday's daily journal at `journal/daily/<date>.md` (Stage B).
+- A run audit paragraph appended to `journal/agent.md` (Stage B).
+- A short morning notification when notifications are enabled and quiet hours have ended.
 - An entry in the Activity feed.
 
 ## Where in the Dashboard
@@ -107,15 +131,18 @@ during the setup wizard's first day. After the first run, only
 | Setting | Default | Notes |
 |---|---|---|
 | `dayBoundaryHour` | `4` | Both the agent-day boundary and the morning-routine fire time. See [Agent Day](../../concepts/agent-day.md). |
-| Tier (heavy/light) | heavy | Forced heavy by default — Sonnet/Flash routines tend to skip critical context. |
-| Max turns | 50 (router cap, P95+) | Adjustable per-process in Settings → Models. |
-| Max budget USD | 5.00 | Per-execute cap. The router enforces this before token costs accumulate. |
+| Stage A tier (`routine.morning_routine_today`) | medium (Sonnet 4.6) | Synthesises `state/today.md` + the day's roadmap fan-out. Adjustable per-row in Settings → Models. |
+| Stage B tier (`routine.morning_routine_journal`) | lite (Haiku 4.5) | Authors `journal/daily/<date>.md` and the `journal/agent.md` audit paragraph. |
+| Stage A max turns / budget | 50 turns / $1.50 | Per-execute envelope for `routine.morning_routine_today`. Adjustable in Settings → Models. |
+| Stage B max turns / budget | 20 turns / $0.30 | Per-execute envelope for `routine.morning_routine_journal`. |
+
+The parent `routine.morning_routine` key keeps its own envelope (50 turns / $2.00) for the pipeline entry point. Codex and Gemini backends scale the dollar caps by a per-tier factor (lite ×2.5, medium ×1.5); the router enforces the cap before token costs accumulate.
 
 ## When Something Goes Wrong
 
-- The most common failure is **morning routine did not run** because the daemon was offline at the trigger window. The next launch picks the run up via the catch-up scheduler if it is still the same agent day.
-- A failed morning routine emits a fallback-success notification when the secondary backend caught the run, or a fallback-failed notification (high priority) when both failed.
-- Heavy-tier quota exhaustion is the second most common cause: a provider rate limit on your `ANTHROPIC_API_KEY`, or — when running on the subscription fallback — the rolling Opus window of the underlying Claude plan. Switch the routine's model to a different heavy-tier option in Settings → Models or wait for the provider window to refresh.
+- The most common failure is **morning routine did not run** because the daemon was offline at the trigger window. The next launch picks the run up via the boot-time catch-up scheduler if it is still the same agent day (a stale or missing `state/today.md` triggers an inline catch-up run).
+- If Stage A runs but fails to produce a valid `state/today.md`, the daemon schedules retries with exponential back-off (5 → 10 → 15 minutes, max 3 attempts) via the `agent_schedule` path, so the retry survives daemon restarts. After the third failure it sends a single **critical** notification asking you to regenerate from the dashboard, and stops retrying. (Stage B is not re-fired on retry — only Stage A regen fixes `state/today.md`.)
+- Backend quota exhaustion is the second most common cause: a provider rate limit, or — when running on the subscription fallback — the rolling window of the underlying Claude plan. The router surfaces this as a `BackendQuotaError` and automatically retries on the configured fallback backend first; switch the routine's model in Settings → Models or wait for the provider window to refresh.
 
 ## Related