@aitne-sh/aitne 0.1.9 → 0.1.11

package/agent-assets/skills/schedule/references/importance.md

@@ -0,0 +1,23 @@
+---
+kind: reference
+name: importance
+description: The `importance` tier convention for `agent_schedule` rows — which tiers surface in `plans/roadmap.md` `Scheduled:` entries, defaults per endpoint, and when to use `strategic`.
+---
+
+# `importance` convention
+
+This controls whether `agent_schedule` rows become `plans/roadmap.md`
+`Scheduled:` entries:
+
+| Tier | Roadmap behavior | Use |
+|---|---|---|
+| `transient` | Never in roadmap; surfaces in today.md only on the day it fires | Default for `/api/schedule/dm`; short pings like "call mom next Tuesday" |
+| `normal` | In roadmap only when scheduled more than 7 days out | Default for `/api/schedule`; ordinary user-facing follow-ups |
+| `strategic` | In roadmap regardless of horizon | Long-prep commitments such as ESTA / travel / deadline reminders |
+| `low` | Never in roadmap | Internal ticks already visible elsewhere, e.g. Agent Plan rows, recurring-schedule instances, morning retries |
+
+For direct DMs, omit `importance` for ordinary one-off pings. If the
+reminder is clearly tied to a long-prep commitment ("remind me in a
+month about ESTA for the LA trip"), either write/promote the roadmap
+item via the roadmap skill and let AAP schedule the reminder, or call
+`/api/schedule/dm` with `"importance":"strategic"`.

package/agent-assets/skills/schedule/references/recurrence-rule.md

@@ -8,10 +8,12 @@ description: recurrenceRule grammar — hourly / daily / weekly / monthly. Engin
 
 The daemon's recurrence engine accepts four frequencies: `hourly`,
 `daily`, `weekly`, `monthly`. Each frequency requires its own set of
-fields and rejects fields that don't apply — the daemon's Zod
-refinements return a `schedule.frequency_field_mismatch` issue (with
-the offending field path) when the shape disagrees with the chosen
-frequency. Pre-validate to save a round-trip.
+fields and rejects fields that don't apply — the daemon rejects a
+mismatched shape with an HTTP 400 validation error naming the
+frequency/field conflict. The recurring-schedules endpoint (the
+`schedule` skill) surfaces it as a `schedule.frequency_field_mismatch`
+issue with a field path; the managed-tasks endpoint surfaces it as a
+`managed_tasks.validation_error`. Pre-validate to save a round-trip.
 
 Times are `HH:MM` 24-hour local; `timezone` is IANA (auto-fills from
 daemon config when omitted, but explicit is safer so a roaming laptop
@@ -67,20 +69,28 @@ of the four frequencies the engine accepts.
 > Managed tasks only support daily, weekly, or monthly cadences.
 > "every hour" / "every 5 minutes" is too tight for a recurring app
 > fetch — pick `daily` or coarser. (If you want a daemon-internal
-> hourly check, use `/api/recurring-schedules` via the `schedule`
+> activity scan, use `/api/recurring-schedules` via the `schedule`
 > skill.)
 
 Same template applies to "every 5 minutes", "every 30 minutes",
 "every 2 hours", etc. when the registering surface is managed-tasks.
 
-## Cadence string vs structured rule
-
-Always send both `cadence` (human-readable, rendered in
-`policies/management.md` §B) and `recurrenceRule` (structured, what the
-scheduler executes). They must agree — if they drift, the rendered
-file misleads the user about what the scheduler will actually do.
-
-When the user modifies just the time (`"9am instead of 10am"`),
-send the new `cadence` and new `recurrenceRule` together in the same
-PATCH so the §B label matches the executable schedule in one
-transition.
+## Cadence string vs structured rule — consumer-specific
+
+`cadence` and `recurrenceRule` are two views of the same schedule, but
+which one a given endpoint persists depends on the consumer:
+
+- **managed-tasks** (`mt_<n>` rows, rendered in `policies/management.md`
+  §B): send both `cadence` (human-readable, the §B label) and
+  `recurrenceRule` (structured, what the scheduler executes). They must
+  agree — if they drift, the rendered file misleads the user about what
+  the scheduler will actually do. When the user modifies just the time
+  (`"9am instead of 10am"`), send the new `cadence` and new
+  `recurrenceRule` together so the §B label matches the executable
+  schedule in one transition.
+- **recurring-schedules** (`/api/recurring-schedules`, the `schedule`
+  skill): persists ONLY `recurrenceRule`. The body schema has no
+  `cadence` field and the `recurring_schedules` table has no `cadence`
+  column — any `cadence` you send is silently dropped. Send just
+  `recurrenceRule` (plus `taskType`/`description`/`prompt`/`model`/
+  `tier`/`taskContext`); there is no §B label to keep in sync.

package/agent-assets/skills/scheduled-managed-task/SKILL.md

@@ -109,12 +109,13 @@ in order:
 #### 4.1 Exact `(source_key, external_id)` match
 
 ```bash
-curl -s "http://localhost:8321/api/entities?source=zoom&external_id=zm_xyz789" | jq .
+curl -s "http://localhost:8321/api/entities?source=zoom&external_id=zm_xyz789" | jq '.items | length'
 ```
 
-If 1 result, that's the entity. Reuse its `path`. This is the
-strongest signal and guarantees no duplicates when the upstream app
-exposes a stable id.
+The route returns an object `{tier, mode, items:[…]}` — results live
+under `items`. If 1 result, that's the entity; reuse its `path`
+(`jq -r '.items[0].path'`). This is the strongest signal and
+guarantees no duplicates when the upstream app exposes a stable id.
 
 If >1 result the mirror is corrupted — record
 `last_result='failed: entity-mirror conflict'` and stop. The boot
@@ -123,14 +124,16 @@ reconciler converges from the L2 files.
 #### 4.2 Fallback: `(domain, type, date, fuzzy title)` within ±48 h
 
 ```bash
-curl -s "http://localhost:8321/api/entities?domain=work&type=meeting&date=2026-12-04&q=foo+1on1" | jq .
+curl -s "http://localhost:8321/api/entities?domain=work&type=meeting&date=2026-12-04&q=foo+1on1" | jq '.items | length'
 ```
 
 The daemon does the fuzzy match server-side (token-overlap on
-`title`). If 1 confident result, reuse. If >1 confident result, pick
-the one whose `sources.<other_app>.*` already overlaps with this
-datum's metadata (e.g. a Calendar entity already bound to the same
-attendees → that's the right meeting).
+`title`) and returns the matches under `items` (object response
+`{tier, q, items:[…]}`). If 1 confident result, reuse it
+(`jq -r '.items[0].path'`). If >1 confident result, iterate
+`jq -r '.items[].path'` and pick the one whose `sources.<other_app>.*`
+already overlaps with this datum's metadata (e.g. a Calendar entity
+already bound to the same attendees → that's the right meeting).
 
 #### 4.3 Otherwise: allocate a new entity
 
@@ -215,9 +218,12 @@ If the entity file does not previously exist, PATCH returns
 `404 context.path_not_found` — today's API requires a PUT with full
 content to create it first (the `<domain>/<type-plural>/*` write path
 is whitelisted for both PUT and PATCH; only the file-existence rule
-forces the PUT-first ordering). The creating PUT must include a
-complete frontmatter block — `type`, `domain`, `slug`, `title`,
-`created`, `sources` — or the daemon returns 422 against `EntitySchema`.
+forces the PUT-first ordering). There is **no API-side entity
+validation**: the creating PUT succeeds even with incomplete
+frontmatter, but always write a complete block — `type`, `domain`,
+`slug`, `title`, `created`, `sources` — because the entity-mirror
+watcher parses loosely and silently skips rows it can't read, leaving
+the §7.6 dedup lookup blind.
 
 ### Step 5b — Update the row
 
@@ -269,19 +275,16 @@ an em-dash; the user can also set the path explicitly via the
 
 ### Step 6 — Three-strikes notify
 
-The design (§10.4 step 6) places the 3-strikes notify on the daemon
-side: the `/run-result` route should auto-enqueue a `POST /api/notify`
-when the post-update `consecutive_failures` crosses the threshold,
-keeping the agent out of the user-paging loop and centralizing the
-threshold (`managementFailureNotifyThreshold`, default 3).
+The daemon emits **no** 3-strikes notify: `updateManagedTaskRunResult`
+is a bare UPDATE and the `/run-result` route only records the run and
+re-renders — it never calls `sendNotification`. (The similarly-named
+`failureNotifyThreshold` param is metrics-only — a dashboard
+"failing_now" gauge — not a daemon-side notify mechanism.)
 
-**Implementation status:** the daemon does NOT currently emit this
-notify — `/api/managed-tasks/:id/run-result` records the run and
-re-renders the file but stops there. Until the daemon closes the
-gap, **this skill is the safety net**: after Step 5b's failure-path
-PATCH, if the post-update `consecutive_failures` you computed is ≥ 3
-AND was < 3 before this run (i.e. the *crossing*, not every
-subsequent failure), call:
+**This skill is the sole notifier** — the safety net for failing
+managed tasks. After Step 5b's failure-path PATCH, if the post-update
+`consecutive_failures` you computed is ≥ 3 AND was < 3 before this run
+(i.e. the *crossing*, not every subsequent failure), call:
 
 ```bash
 curl -sS -X POST http://localhost:8321/api/notify \
@@ -309,16 +312,15 @@ is **empty final text**: bookkeeping is invisible by design. The user
 sees the change reflected in `state/activity/<source>.md` (auto-built) and
 `<domain>/_index.md`, not in a chat ping per fire.
 
-Exceptions:
+Exceptions (final text stays empty in all cases — these only govern
+whether a `/api/notify` fires):
 
 - The `notify` skill's awareness gate fired *during* this run — e.g.
   the new datum is a meeting starting in 15 min. Then call
-  `/api/notify` and keep the final text empty (a follow-up "Sent"
-  line is duplicate noise per `scheduled.task.md`).
-- `last_result='failed: ...'` with `consecutive_failures < 3` — final
-  text empty; the activity view records it; the user is not paged.
-- `last_result='failed: ...'` at the threshold crossing — Step 6 fired
-  the `/api/notify`; final text empty.
+  `/api/notify` (a follow-up "Sent" line is duplicate noise per
+  `scheduled.task.md`).
+- A failure: notify only on the Step 6 threshold crossing; below it,
+  the activity view records the failure and the user is not paged.
 
 NEVER write a `## Agent Plan` row for a managed-task run — managed
 tasks are not the same as Agent Plan rows. The Agent Plan loop close
@@ -332,13 +334,15 @@ A scheduled fire that crashes mid-run leaves the row's
 `last_run_at` un-updated. The next slot picks up the same `since`
 window and re-fetches the same data — the entity-mirror's
 `(source_key, external_id)` lookup makes this a **merge**, not a
-duplicate. The PATCH body is content-additive: a section appended
-twice with the same content is harmless because Step 5a's
-`frontmatterMerge` is deep, and the section-append mode is
-"add this block as-is" (the daemon de-duplicates exact-string-match
-sections with the same heading on append). For sources without a
-stable `external_id`, use Step 4.2's date+title window — at the cost
-of occasional dedup misses, never duplicates by construction.
+duplicate at the file level, and Step 5a's `frontmatterMerge` is deep,
+so re-writing the same frontmatter is idempotent. **Body
+section-appends are NOT de-duplicated** — `mode:"append"` concatenates
+unconditionally, so re-appending the same block on a replay WILL
+duplicate it. Guard against that: on a re-run, `GET` the section first
+and skip any block already present (or carry the structured fields in
+frontmatter, which merges). For sources without a stable `external_id`,
+use Step 4.2's date+title window — at the cost of occasional dedup
+misses, never duplicates by construction.
 
 ## Caps
 
@@ -352,20 +356,16 @@ appended `## <App> Notes` body, not as a separate DM.
 
 | HTTP | `error` | What to do |
 |---|---|---|
-| 400 (`/api/managed-tasks/:id/run-result`) | `invalid_id` / `validation_error` | Body shape drift — re-check field names exactly match `last_run_at` / `last_result` / `consecutive_failures` |
+| 400 (`/api/managed-tasks/:id` or `:id/run-result`) | `invalid_id` / `validation_error` | All managed-task body validation is 400 (never 422). Re-check field names exactly match `last_run_at` / `last_result` / `consecutive_failures`; for the user-facing PATCH, drop the offending field (typically `output_path`) and retry once with the rest |
 | 404 (`/api/context/<domain>/<type-plural>/...`) | `context.path_not_found` | The entity file does not exist yet — PATCH cannot create it. Create it first with a PUT carrying full content + complete frontmatter (§Step 5a), then the merge succeeds. (Entity-domain write paths ARE whitelisted for PUT/PATCH; the prior 403 claim is obsolete.) |
 | 404 (`/api/managed-tasks/:id`) | `not_found` | Row was stopped mid-run. End the session quietly. |
-| 422 (`/api/context/...`) | `validation_error` | Frontmatter incomplete or malformed; populate all required fields and retry once |
-| 422 (`/api/managed-tasks/:id`) | `validation_error` | Path / body shape rejected; drop the offending field (typically `output_path`) and retry once with the rest |
 | 5xx | `internal_error` | Record `last_result='failed: <body.message>'` via Step 5b's failure form and end the session |
 
 ## What this skill does NOT do
 
-- Does NOT post `/api/notify` for routine successes (silent by design).
-- Does NOT post `/api/notify` for routine failures (final text empty).
-  The exception is the 3-strikes crossing — see Step 6: until the
-  daemon owns the threshold notify, the agent emits one DM at the
-  3rd consecutive failure, then stays silent until success or stop.
+- Does NOT post `/api/notify` for routine successes or failures
+  (silent by design). The sole exception is the 3-strikes crossing —
+  see Step 6.
 - Does NOT touch the §B row's `app` or `cadence` — those are
   user-mutable only via the `managed-tasks` skill `## Modify` flow.
 - Does NOT INSERT `agent_schedule` rows. The cron scheduler does.

package/agent-assets/skills/today/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: today
-description: Load for any event that reads or writes today.md — morning routines, hourly checks, DMs, scheduled tasks. Owns the day-type filter, Agent Plan contract, Agent Log/Notes schema, schedule.approaching format, and Morning Routine lock.
+description: Load for any event that reads or writes today.md — morning routines, activity scans, DMs, scheduled tasks. Owns the day-type filter, Agent Plan contract, Agent Log/Notes schema, schedule.approaching format, and Morning Routine lock.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -8,29 +8,7 @@ allowed-tools:
 
 # today.md Guide
 
-Output language: today.md is Policy B — see `<output_language_policy>`. The skeleton lines listed below stay English verbatim; bullets and narrative under each H2 are in `<settings primary_language>`.
-
-**Skeleton (do NOT translate — exact-regex-validated on PUT):**
-
-1. **Line 1** — `# YYYY-MM-DD (day-of-week)` H1 date line. The weekday
-   inside `(...)` is free-form and may be localized; the rest is fixed.
-2. **Line 2** — `> Day type: …` blockquote (full pattern below). Field
-   labels (`Day type`, `Work focus`, `Study focus`, `Personal focus`),
-   values (`Weekday`/`Weekend`, `on`/`off`), pipe separators (` | `),
-   and the leading `> ` are **all English ASCII, fixed casing, fixed
-   spacing**. This is parsed by every downstream event handler.
-3. **The six H2 headers** — `## User Schedule`, `## User Tasks`,
-   `## Agent Plan`, `## Agent Notes`, `## Agent Log`, `## Handoff` —
-   in this order.
-
-A `PUT /api/context/state/today` whose line 1 or line 2 fails the exact regex
-is rejected with 400 and the daemon does NOT write the file. Translating
-any keyword on line 2 (the field labels, the `Weekday`/`Weekend` value,
-or `on`/`off`) into the user's primary language is the most common
-failure mode — keep it English even when the rest of today.md is being
-written in another language. The `<output_language_policy>` skeleton
-precedence rule already covers this; this paragraph just makes the
-consequence explicit.
+Output language: today.md is Policy B — see `<output_language_policy>`. The skeleton (line 1, line 2, the six H2 headers) stays English verbatim — line 1 and line 2 are exact-regex-validated on PUT; bullets and narrative under each H2 are in `<settings primary_language>`. §Line 1 and §Header line carry the exact patterns and the consequence of translating a line-2 keyword.
 
 today.md has a **day-type header line** (second line) and **six required sections**.
 
@@ -78,52 +56,35 @@ Line 2 encodes today's filter policy (field order is fixed — downstream parser
 > Day type: {Weekday|Weekend} | Work focus: {on|off} | Study focus: {on|off} | Personal focus: {on|off}
 ```
 
-Derivation (Morning Routine at 04:00):
-1. Day-of-week from `<current_time>`. Weekday = Mon–Fri, Weekend = Sat–Sun (unless user/profile.md overrides).
-2. Read `identity/profile.md` → ## Notification Preferences. Apply matching policy.
-3. No explicit policy → default: weekday = all on, weekend = work off, study on, personal on.
+The field labels (`Day type`, `Work focus`, `Study focus`, `Personal
+focus`), the values (`Weekday`/`Weekend`, `on`/`off`), the ` | `
+separators, and the leading `> ` are all English ASCII, fixed casing,
+fixed spacing — exact-regex-validated. **Translating any line-2 keyword
+into the primary language is the most common write failure: PUT is
+rejected 400 and the file is not written.** Keep line 2 English even
+when the rest of today.md is in another language.
 
-Category → focus-dimension mapping:
+Derivation, focus-dimension mapping, and downstream focus-filter usage —
+needed only when the Morning Routine writes line 2 — are in the
+**today-skeleton** reference.
 
-| Category tag | Controlled by |
-|---|---|
-| `[work]` | Work focus |
-| `[study]` | Study focus |
-| `[personal]`, `[home]` | Personal focus |
+Line 2 is not frozen for the day: when the user declares a day-shape
+change ("taking the afternoon off", "sick today"), the DM handler
+updates the matching focus value(s) in place — exact format above,
+English keywords. PATCH targets sections only and cannot reach line 2:
+GET `/api/context/state/today`, edit line 2 alone, PUT the full
+document straight back. Fire-time filters then suppress or re-admit
+whole categories; never hand-edit individual rows for a focus change.
 
-How downstream events use it:
-- Morning Routine suppresses items with focus `off` at generation time
-- scheduled.task re-checks at fire time: if focus is off, skip + close as `skipped (focus off)`
-- DM handler skips follow-ups on rows whose focus is off
-- Hourly check drops observations whose focus is off
-- schedule.approaching suppresses notifications for off categories
+## Sections and entry formats
 
-## Sections and when to update
+The per-section update matrix (when/mode/who-writes) and the
+per-section entry-format table (User Schedule / User Tasks / Agent Plan
+/ Agent Log row shapes, category tags, trigger tags, mandatory-HH:MM
+fallback rules) are reference-grade detail the Morning Routine needs to
+write the full skeleton. They live in the **today-skeleton** reference.
 
-| Section | When to update | Mode | Who writes |
-|---|---|---|---|
-| `user_schedule` | Morning from calendar; refresh after sync | PUT (Morning) / PATCH replace | Morning primary |
-| `user_tasks` | Status changes, new tasks, hourly observations | PATCH append (new) / replace (flip) | Morning + event-driven |
-| `agent_plan` | Morning lays out actions; hourly adds new; scheduled.task flips `[x]` | PATCH append / replace (flip) | Morning + hourly + scheduled.task |
-| `agent_notes` | Look-ahead + day-time events | PATCH append | Morning (look-ahead) + event-driven |
-| `agent_log` | Every non-trivial agent action | PATCH append | All events |
-| `handoff` | Evening Review finalizes carry-overs | PATCH replace | Evening Review only |
-
-## Entry formats
-
-| Section | Format | Example |
-|---|---|---|
-| `user_schedule` | `- HH:MM[–HH:MM] <title> [category]` | `- 14:00–15:00 Design review [work]` |
-| `user_tasks` | `- [ ] HH:MM <description> [category]` | `- [ ] 11:00 Finalize Q2 draft [work]` |
-| `agent_plan` | `- [ ] HH:MM <action> [category] →<trigger>` | `- [ ] 08:55 DM reminder: standup [work] →DM` |
-| `agent_notes` | see flavors below | |
-| `agent_log` | `- HH:MM <action description>` | `- 13:50 [cal] Design review — reminder sent` |
-
-**Category tags**: `[work]`, `[study]`, `[personal]`, `[home]` — mandatory on Agent Plan rows (not decorative).
-
-**Trigger tags** (Agent Plan only): `→DM`, `→notify`, `→check-in`, `→wake`
-
-**HH:MM is mandatory** on User Tasks and Agent Plan rows. If no natural time: (1) deadline → 2h before, (2) calendar-adjacent → 15 min before, (3) otherwise → working-hours midpoint.
+{{> ref:today-skeleton }}
 
 ## User Tasks vs Agent Plan
 
@@ -146,11 +107,19 @@ below: execute, append Agent Log entry, read-then-flip the row to
 `[x]` with annotation, retry on `state/today.md` lock, surface missing-row
 state.
 
-DM handlers and hourly checks do not flip Agent Plan rows — read the
-reference only if your event type is in its applicability list.
+DM handlers and activity scans never flip rows for execution outcomes —
+their only row write is the cancel / amend revision below.
 
 {{> ref:agent-plan-lifecycle }}
 
+## Agent Plan revision — cancel / amend before fire time
+
+When a pending row's premise dies or its time must change before it
+fires, the session that detects it — DM handlers and activity scans
+included — revises schedule + row + Agent Log in the same turn:
+
+{{> ref:agent-plan-revision }}
+
 ## Agent Log format
 
 `- HH:MM Action description`. Log every user-visible action, context file write, or outbound API call. Skip purely internal no-ops.
@@ -173,7 +142,7 @@ reference only if your event type is in its applicability list.
 ## schedule.approaching → Agent Notes + Agent Log
 
 The firing flow gates timing — `schedule.approaching` only fires at
-`minutesUntil <= 15` (`packages/daemon/src/observers/calendar-poller.ts:125`),
+`minutesUntil <= 15` (`packages/daemon/src/observers/imminent-event-scheduler.ts:281`),
 so the LLM never sees this format-using event with a wider lookahead.
 No additional gate is restated here.
 
@@ -191,19 +160,7 @@ PUT today.md must contain the H1 date line, day-type header quote, and all six s
 
 ## today.md API
 
-The generic GET / PUT / PATCH / DELETE surface — modes, fields, error
-envelopes, body-submission shape — is documented in the **context**
-skill `references/api.md`. today.md-specific rules layered on top:
-
-- **Lock.** `state/today.md` is locked by the Morning Routine. Include
-  `X-Lock-Id: <today_write_lock_id>` on every PUT / PATCH when the
-  tag is in your context; other sessions get `409
-  morning_routine_lock_held` while the lock is held.
-- **Skeleton validators.** PUT is rejected (400) if line 1 fails the
-  H1 date regex or line 2 fails the day-type quote regex (see §"Line 1
-  — which date?" and §"Header line — day-type filter" above). PUT is
-  also rejected (400) if line 1's date disagrees with the daemon's current
-  agent-day — the error echoes both values.
+The generic GET / PUT / PATCH / DELETE shape lives in the **context** skill `references/api.md`. today.md adds only the Morning Routine lock (§Morning Routine lock) and the line-1/line-2 skeleton validators (§Line 1, §Header line) detailed above.
 
 ## Knowledge map — section shape (auto-curated)
 

package/agent-assets/skills/today/references/agent-plan-lifecycle.md

@@ -8,9 +8,10 @@ description: Agent Plan close-the-loop lifecycle for scheduled.task / scheduled.
 
 This reference is consumed by `scheduled.task`, `scheduled.dm`,
 `routine.morning_routine`, and `routine.evening_review` — every event
-that may flip an Agent Plan row. DM handlers and hourly checks never
-flip Agent Plan rows; if you are not one of the listed events, the
-lifecycle below does not apply to your turn.
+that flips an Agent Plan row at fire time. DM handlers and hourly
+checks never flip rows for execution outcomes; their one write path is
+the pre-fire cancel / amend revision in the `today` skill body, not
+this lifecycle.
 
 ## Why flip inside the scheduled task, not later?
 
@@ -84,6 +85,10 @@ Leaving rows as `[ ]` is a bug: Morning Routine's reconciliation
 treats unflipped past rows as "scheduler dropped the wake", which
 triggers self-recovery and inflates the agent-actions audit.
 
+A fourth terminal state — `(cancelled: <reason>)` — is written before
+fire time by the cancel / amend revision path (today skill body),
+never by this lifecycle.
+
 ## Lock retry rules
 
 The Morning Routine holds the `state/today.md` write lock. Other sessions
@@ -94,7 +99,7 @@ get `409 morning_routine_lock_held` on PUT / PATCH while the lock is held.
   status code 409 alone.
 - Retry policy: 30 s back-off, max 3 attempts. If the third attempt
   also returns 409, log `loop-closeout deferred (lock_held)` to Agent
-  Log and exit. The next Evening Review reconciliation will catch the
+  Log and exit. The next Morning Routine reconciliation will catch the
   un-flipped row.
 - Do NOT retry without the `X-Lock-Id` header when the tag is in
   context. Sending a PATCH without the header during a held-lock

package/agent-assets/skills/today/references/agent-plan-revision.md

@@ -0,0 +1,28 @@
+---
+kind: reference
+name: agent-plan-revision
+description: Pre-fire cancel / amend recipe for Agent Plan rows — schedule + row + Agent Log revised in one turn, with the confidence gate.
+---
+
+# Agent Plan revision — cancel / amend recipe
+
+Triggers: the referenced calendar event was cancelled or moved; the
+user already handled the item or says it is no longer needed; a
+schedule PATCH/DELETE would otherwise orphan the row.
+
+All three in the same turn — lock-step holds in both directions:
+
+1. **Schedule** — `DELETE /api/schedule/:id` to cancel, or
+   `PATCH /api/schedule/:id` to re-time. Find the id via
+   `GET /api/schedule?status=pending` (match subject + HH:MM).
+2. **Row** — read-before-write PATCH of `agent_plan` (lifecycle
+   recipe): cancel → flip to
+   `- [x] HH:MM <action> [category] →<trigger> (cancelled: <reason>)`;
+   amend → update the row's HH:MM / action text, keep `[ ]`.
+3. **Agent Log** — `- HH:MM [agent_plan] cancelled <action> — <reason>`
+   (or `rescheduled <action> to HH:MM — <reason>`).
+
+Confidence gate: revise only when subject AND time both unambiguously
+match the invalidating fact. A wrong cancellation silently never fires
+— worse than a stale wake, which fire-time guards can still skip.
+Uncertain → leave the pair alone.

package/agent-assets/skills/today/references/today-skeleton.md

@@ -0,0 +1,66 @@
+---
+kind: reference
+name: today-skeleton
+description: today.md full-skeleton detail for Morning Routine — day-type derivation, focus-dimension mapping, downstream focus-filter usage, per-section update matrix, and entry-format table. Only Morning Routine writes the full skeleton; DM/activity-scan events do not need this.
+---
+
+# today.md skeleton — derivation, sections, entry formats
+
+Only the Morning Routine writes the full skeleton from scratch. DM
+handlers, activity scans, and scheduled.task sessions patch individual
+sections and do not need this detail — load it only when populating
+line 2 or laying out the section bodies.
+
+## Day-type derivation (Morning Routine at 04:00)
+
+Line 2 is:
+
+```
+> Day type: {Weekday|Weekend} | Work focus: {on|off} | Study focus: {on|off} | Personal focus: {on|off}
+```
+
+1. Day-of-week from `<current_time>`. Weekday = Mon–Fri, Weekend = Sat–Sun (unless user/profile.md overrides).
+2. Read `identity/profile.md` → ## Notification Preferences. Apply matching policy.
+3. No explicit policy → default: weekday = all on, weekend = work off, study on, personal on.
+
+Category → focus-dimension mapping:
+
+| Category tag | Controlled by |
+|---|---|
+| `[work]` | Work focus |
+| `[study]` | Study focus |
+| `[personal]`, `[home]` | Personal focus |
+
+How downstream events use the filter:
+- Morning Routine suppresses items with focus `off` at generation time
+- scheduled.task re-checks at fire time: if focus is off, skip + close as `skipped (focus off)`
+- DM handler skips follow-ups on rows whose focus is off
+- Activity scan drops observations whose focus is off
+- schedule.approaching suppresses notifications for off categories
+
+## Sections and when to update
+
+| Section | When to update | Mode | Who writes |
+|---|---|---|---|
+| `user_schedule` | Morning from calendar; refresh after sync | PUT (Morning) / PATCH replace | Morning primary |
+| `user_tasks` | Status changes, new tasks, activity-scan observations | PATCH append (new) / replace (flip) | Morning + event-driven |
+| `agent_plan` | Morning lays out actions; activity scan adds new; scheduled.task flips `[x]` | PATCH append / replace (flip) | Morning + activity scan + scheduled.task |
+| `agent_notes` | Look-ahead + day-time events | PATCH append | Morning (look-ahead) + event-driven |
+| `agent_log` | Every non-trivial agent action | PATCH append | All events |
+| `handoff` | Evening Review finalizes carry-overs | PATCH replace | Evening Review only |
+
+## Entry formats
+
+| Section | Format | Example |
+|---|---|---|
+| `user_schedule` | `- HH:MM[–HH:MM] <title> [category]` | `- 14:00–15:00 Design review [work]` |
+| `user_tasks` | `- [ ] HH:MM <description> [category]` | `- [ ] 11:00 Finalize Q2 draft [work]` |
+| `agent_plan` | `- [ ] HH:MM <action> [category] →<trigger>` | `- [ ] 08:55 DM reminder: standup [work] →DM` |
+| `agent_notes` | see flavors in the `today` skill body | |
+| `agent_log` | `- HH:MM <action description>` | `- 13:50 [cal] Design review — reminder sent` |
+
+**Category tags**: `[work]`, `[study]`, `[personal]`, `[home]` — mandatory on Agent Plan rows (not decorative).
+
+**Trigger tags** (Agent Plan only): `→DM`, `→notify`, `→check-in`, `→wake`
+
+**HH:MM is mandatory** on User Tasks and Agent Plan rows. If no natural time: (1) deadline → 2h before, (2) calendar-adjacent → 15 min before, (3) otherwise → working-hours midpoint.

package/agent-assets/skills/today/seeds/agent-notes-flavors.seed.json

@@ -11,7 +11,7 @@
     },
     {
       "topic": "Latent profile question",
-      "rule": "Latent profile questions are open questions the agent wants to ask the user when context allows, marked with the suffix `(asked HH:MM)` once asked."
+      "rule": "Latent profile questions are open questions to ask the user when context allows. The parenthetical is the state: `(latent)` while waiting, `(asked HH:MM)` once woven into a reply."
     }
   ]
 }

package/agent-assets/skills/today/seeds/section-shape.seed.json

@@ -3,14 +3,14 @@
   "files": [
     {
       "path": "state/today.md",
-      "purpose": "today's plan, schedule, agent log, and handoff to tomorrow",
+      "purpose": "today's schedule, tasks, agent plan, log, and handoff to tomorrow",
       "sections": [
-        { "heading": "## Plan", "contains": "the day's intent in plain prose" },
-        { "heading": "## Schedule", "contains": "time-blocked events for today" },
-        { "heading": "## Tasks", "contains": "open task entries with status checkbox" },
+        { "heading": "## User Schedule", "contains": "time-blocked events for today" },
+        { "heading": "## User Tasks", "contains": "open task entries the user will do, with status checkbox" },
+        { "heading": "## Agent Plan", "contains": "scheduled actions Claude Code will take to help, each backed by a schedule entry" },
         { "heading": "## Agent Notes", "contains": "look-aheads, day-time observations, latent profile questions" },
-        { "heading": "## Handoff", "contains": "context for tomorrow's morning routine" },
-        { "heading": "## Done", "contains": "tasks the user marked complete" }
+        { "heading": "## Agent Log", "contains": "running log of every non-trivial agent action" },
+        { "heading": "## Handoff", "contains": "context carried over to tomorrow's morning routine" }
       ]
     }
   ]