@aitne-sh/aitne 0.1.9 → 0.1.10

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

@@ -1,6 +1,6 @@
 ---
 name: schedule
-description: Load when scheduling a future agent wake-up, pre-composed DM, recurring task, or de-duping against existing pending schedules.
+description: Schedule future agent wake-ups, pre-composed DMs, or recurring tasks via /api/schedule. Use when registering a timed follow-up, a one-off reminder, or de-duping against pending schedules.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -33,8 +33,7 @@ user but compound into duplicate DMs/notifications at fire time.
 3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
    confirm no recurring rule/Agent already covers this cadence (e.g. a
    daily 09:00 inbox triage, or the morning briefing). If covered, skip.
-   (Recurring *work* is created as an Agent via the `agent-create` skill;
-   recurring *DMs* via `POST /api/recurring-schedules` `taskType:dm_session`.)
+   (How recurring work/DMs are created — see "Recurring" below.)
 4. **`confirm_dedup_key` check (mandatory for `confirm:` sub-flow rows
    only).** When scheduling a `dm_session` row with
    `taskContext.sub_flow="confirm"`, run the dedup pre-check + shape
@@ -58,11 +57,7 @@ Y" — switch to the `management-policy` skill instead. It creates a
 `policies/management-captures/<slug>.md` that captures the WHY alongside the cadence
 (via `policies/routines/custom/<slug>.md`) so the rule survives a context
 reset. When the cadence is all that matters and there is no intent to
-record: recurring autonomous **work** → create a **recurring Agent** via
-the `agent-create` skill (`POST /api/agents`); recurring scheduled
-**DM / briefing** → `POST /api/recurring-schedules` with
-`taskType: "dm_session"`. (Creating a recurring `agent.task` row directly
-on `/api/recurring-schedules` is **410 Gone** — use an Agent.)
+record, create the recurring work/DM per the "Recurring" section below.
 
 ## DM vs Agent Task
 
@@ -77,7 +72,7 @@ on `/api/recurring-schedules` is **410 Gone** — use an Agent.)
 
 ## Writing a Good Prompt (for agent tasks)
 
-> **The wake-up agent has NO memory of why it was scheduled.** It receives only: `state/today.md`, a fresh 1-day calendar, `identity/profile.md` + `policies/management.md`, and the `prompt` + `taskContext` fields you provide. Nothing else. (`description` is just an optional list label — never the agent body.)
+> **The wake-up agent has NO memory of why it was scheduled.** A `scheduled.task` session is self-contained: it receives only `state/today.md` (which carries the day's schedule and state) plus the `prompt` + `taskContext` you provide — **NOT** `identity/profile.md` or `policies/management.md` (the `scheduled.task` injection policy opts those out). Nothing else. (`description` is just an optional list label — never the agent body.)
 
 Include all four elements in the `prompt`:
 
@@ -98,21 +93,9 @@ Structured metadata for IDs, URLs, and correlation. Put long identifiers here so
 { "scheduledBy": "morning_routine", "prUrl": "https://github.com/user/repo/pull/42" }
 ```
 
-**`importance` convention.** This controls whether `agent_schedule`
-rows become `plans/roadmap.md` `Scheduled:` entries:
+**`importance`** controls whether a row becomes a `plans/roadmap.md` `Scheduled:` entry. Default `transient` for `/api/schedule/dm`, `normal` for `/api/schedule`; use `strategic` only for roadmap-shaped long-prep reminders. Tier table + defaults in the reference below.
 
-| 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"`.
+{{> ref:importance }}
 
 ## Tier / Model selection
 
@@ -158,7 +141,7 @@ curl -s -X POST http://localhost:8321/api/schedule \
 | Field | Required | Description |
 |---|---|---|
 | `time` | Yes | ISO 8601 with timezone offset |
-| `taskType` | Yes | Free-form provenance label for the row (no allowlist on the single endpoint). Use `wake` for an agent wake-up — the convention this skill follows. The closed set `wake`/`dm_session`/`check`/`dm` is enforced only on `/api/schedule/batch`; e.g. the dashboard's manual "+ New task" sends `custom`. The label does not change firing — the scheduler runs every non-`dm`/`dm_session`/`browser_task` row as a generic `scheduled.task`. |
+| `taskType` | Yes | Free-form provenance label; use `wake` for agent wake-ups. The closed set `wake`/`dm_session`/`check`/`dm` is enforced only on `/api/schedule/batch`. The label doesn't change firing — every non-`dm`/`dm_session`/`browser_task` row runs as a generic `scheduled.task`. |
 | `prompt` | Yes | The agent's instruction at fire time — its ONLY context (the session has no memory). Self-contained: what + why + who + expected output. See format above. Max 8000 chars (~2000 tokens); move bulk reference material into a file the agent reads at fire time rather than inlining it. |
 | `description` | No | Optional short label shown in the schedule list (max 200 chars). NOT the agent body — that is `prompt`. Omit it and the list shows a `prompt` excerpt. |
 | `tier` | No | `lite` / `medium` / `high`. Omit to use the dispatcher's process-key default (medium for `scheduled.task`). See "Tier / Model selection" above. Mutually exclusive with `model`. |
@@ -179,11 +162,11 @@ Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-d
 ```bash
 curl -s "http://localhost:8321/api/schedule?status=pending"
 ```
-Param `status` (default `pending,running`): comma-separated `pending`, `running`, `completed`, `failed`.
+Param `status` (default `pending,running`): comma-separated `pending`, `running`, `completed`, `failed`, `skipped`. DELETE/cancel does not remove a row — it moves it to `status='skipped'`, so re-listing a cancelled item requires `status=skipped`.
 Param `roadmapEligible=true`: return only rows that may become
 roadmap `Scheduled:` entries (`transient` / `low` excluded, `normal`
 only beyond 7 days, `strategic` included).
-Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","backendId","tier","taskContext","createdAt" }] }`. `prompt` / `tier` / `model` / `backendId` are `null` when no override is set. `model` is a registered id verbatim and travels with `backendId` when set — the row carries either the `(model, backendId)` pin or `tier`, never both. Legacy alias inputs (`sonnet` / `opus`) are normalized to `tier` at write time. `taskContext` is the parsed JSON (or `null`); filter with `jq` e.g. `'.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
+Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","backendId","tier","taskContext","createdAt" }] }`. `prompt` / `tier` / `model` / `backendId` are `null` when no override is set. `model` is a registered id verbatim and travels with `backendId` when set — the row carries either the `(model, backendId)` pin or `tier`, never both. Legacy alias inputs (`sonnet` / `opus`) are normalized to `tier` at write time. `taskContext` is the parsed JSON (always an object — `{}` when unset); filter with `jq` e.g. `'.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
 
 ### DELETE /api/schedule/:id — Cancel a pending item
 ```bash

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

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

@@ -215,9 +215,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 +272,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 +309,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 +331,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 +353,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

@@ -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,27 @@ 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 |
+## Sections and entry formats
 
-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
+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.
 
-## 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, 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
 
@@ -173,7 +126,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 +144,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/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/hourly events do not need this.
+---
+
+# today.md skeleton — derivation, sections, entry formats
+
+Only the Morning Routine writes the full skeleton from scratch. DM
+handlers, hourly checks, 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
+- Hourly check 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, 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 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" }
       ]
     }
   ]