@aitne-sh/aitne 0.1.7 → 0.1.8

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

@@ -0,0 +1,86 @@
+---
+kind: reference
+name: recurrence-rule
+description: recurrenceRule grammar — hourly / daily / weekly / monthly. Engine accepts all four; the managed-tasks consumer specifically refuses sub-daily for app-fetch correctness (template below).
+---
+
+# recurrenceRule grammar
+
+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.
+
+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
+does not surprise the user).
+
+## Engine — per-frequency field rules
+
+| `frequency` | Required | Allowed | Forbidden |
+|---|---|---|---|
+| `hourly` | — | `intervalHours` (1..23, default 1), `minuteOfHour` (0..59, default 0), `timezone` | `time`, `daysOfWeek`, `daysOfMonth`, `onMissingDay` |
+| `daily` | `time` | `timezone` | `intervalHours`, `minuteOfHour`, `daysOfWeek`, `daysOfMonth`, `onMissingDay` |
+| `weekly` | `time`, `daysOfWeek` | `timezone` | `intervalHours`, `minuteOfHour`, `daysOfMonth`, `onMissingDay` |
+| `monthly` | `time`, `daysOfMonth` | `timezone`, `onMissingDay` (default `lastDayOfMonth`) | `intervalHours`, `minuteOfHour`, `daysOfWeek` |
+
+- `daysOfWeek` is `0=Sun..6=Sat`; 1..7 distinct entries, dupes rejected.
+- `daysOfMonth` is `1..31`; 1..31 distinct entries, dupes rejected.
+  Days 29-31 may not exist in a given month — see `onMissingDay`.
+- `onMissingDay`: `"skip"` (don't fire that month) or
+  `"lastDayOfMonth"` (fire on the actual last day, preserving the
+  pre-redesign clamp behavior). Default `"lastDayOfMonth"` for
+  back-compat. The engine also de-duplicates calendar dates that
+  collapse to the same fire (e.g. `[28,31]` in non-leap Feb with
+  `"lastDayOfMonth"` fires Feb 28 once, not twice).
+- `intervalHours=N` fires when `(localHour % N) == 0` at
+  `minuteOfHour` local, anchored at midnight in the rule's
+  `timezone`.
+
+## Mapping table
+
+| User said | `cadence` | `recurrenceRule` |
+|---|---|---|
+| every hour | `hourly :00 (UTC)` | `{frequency:"hourly"}` |
+| every 2 hours at :30 | `hourly /2 :30 (UTC)` | `{frequency:"hourly", intervalHours:2, minuteOfHour:30}` |
+| every day at 10am (Asia/Tokyo) | `daily 10:00 (Asia/Tokyo)` | `{frequency:"daily", time:"10:00", timezone:"Asia/Tokyo"}` |
+| every Monday 9am | `weekly Mon 09:00` | `{frequency:"weekly", time:"09:00", timezone:<user tz>, daysOfWeek:[1]}` |
+| every weekday at 8am | `weekdays 08:00` | `{frequency:"weekly", time:"08:00", timezone:<user tz>, daysOfWeek:[1,2,3,4,5]}` |
+| 1st of every month at noon | `monthly day 1 12:00` | `{frequency:"monthly", time:"12:00", timezone:<user tz>, daysOfMonth:[1]}` |
+| 25th of every month at 21:00 | `monthly day 25 21:00` | `{frequency:"monthly", time:"21:00", timezone:<user tz>, daysOfMonth:[25]}` |
+| last day of every month at 21:00 | `monthly last 21:00` | `{frequency:"monthly", time:"21:00", timezone:<user tz>, daysOfMonth:[31], onMissingDay:"lastDayOfMonth"}` |
+| every 5 minutes | _not representable_ | _refuse — sub-hour cadences are not supported_ |
+
+## Consumer-specific refusal — managed-tasks only
+
+The managed-tasks skill (`mt_<n>` rows) refuses sub-daily cadences
+because app-fetch correctness requires a daily-or-coarser window to
+amortise rate limits and to map cleanly onto the entity-mirror's
+daily granularity. Schedule callers (`/api/schedule`,
+`/api/recurring-schedules`) have no such constraint and may use any
+of the four frequencies the engine accepts.
+
+### managed-tasks sub-daily refusal — DM template
+
+> 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`
+> 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
+`rules/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.

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

@@ -0,0 +1,185 @@
+---
+kind: reference
+name: recurring
+description: /api/recurring-schedules — hourly / daily / weekly / monthly cadences auto-regenerating one-shot rows. Includes hourly anchor semantics, monthly missing-day recipes, and the tier ↔ model swap on PATCH.
+---
+
+# Recurring schedules
+
+For tasks that repeat on a fixed pattern. The daemon auto-regenerates
+the next one-shot occurrence after each execution; you never have to
+re-POST a daily reminder.
+
+Use a recurring schedule when the cadence is all that matters and
+there is no need to record *why* the rule exists. If the user wants
+the WHY captured alongside the cadence (so the rule survives a
+context reset), use the `management-policy` skill — it produces a
+`rules/policies/<slug>.md` linked to a `routines/custom/<slug>.md`
+custom routine.
+
+## POST /api/recurring-schedules — Create
+
+```bash
+# Hourly at :00 (every hour)
+curl -s -X POST http://localhost:8321/api/recurring-schedules \
+  -H 'Content-Type: application/json' \
+  -d '{"taskType":"wake","description":"Hourly docker container health check.","recurrenceRule":{"frequency":"hourly"},"tier":"lite"}'
+
+# Every 2 hours at :30 (00:30, 02:30, …, 22:30 local)
+curl -s -X POST http://localhost:8321/api/recurring-schedules \
+  -H 'Content-Type: application/json' \
+  -d '{"taskType":"wake","description":"Sync inbox triage signals.","recurrenceRule":{"frequency":"hourly","intervalHours":2,"minuteOfHour":30},"tier":"lite"}'
+
+# Daily at 09:00
+curl -s -X POST http://localhost:8321/api/recurring-schedules \
+  -H 'Content-Type: application/json' \
+  -d '{"taskType":"wake","description":"Morning inbox triage — check pending observations and update today.md.","recurrenceRule":{"frequency":"daily","time":"09:00"}}'
+
+# Weekly Mon/Wed/Fri at 10:00
+curl -s -X POST http://localhost:8321/api/recurring-schedules \
+  -H 'Content-Type: application/json' \
+  -d '{"taskType":"wake","description":"Standup prep — review PRs, calendar, and blockers.","recurrenceRule":{"frequency":"weekly","time":"10:00","daysOfWeek":[1,3,5]}}'
+
+# Monthly on the 25th at 21:00 (billing reconciliation)
+curl -s -X POST http://localhost:8321/api/recurring-schedules \
+  -H 'Content-Type: application/json' \
+  -d '{"taskType":"wake","description":"Monthly card reconciliation — pull statement, log balance to finance dossier.","recurrenceRule":{"frequency":"monthly","time":"21:00","daysOfMonth":[25]},"tier":"medium"}'
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `taskType` | Yes | Task type for dispatch (e.g. `wake`) |
+| `description` | Yes | Self-contained (min 20 chars). Same rules as one-shot. Doubles as the agent body unless `prompt` overrides it. |
+| `prompt` | No | Optional override for the agent body (min 20 chars when set). Each materialized one-shot row inherits this from the recurring parent. |
+| `recurrenceRule` | Yes | `{ frequency, time?, timezone?, intervalHours?, minuteOfHour?, daysOfWeek?, daysOfMonth?, onMissingDay? }` — fields gated by `frequency`; see grammar below. |
+| `tier` | No | `lite` / `medium` / `high`. Mutually exclusive with `model`. |
+| `model` | No | Registered model id (`claude-opus-4-7`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), or composite `<backendId>/<modelId>` for future disambiguation. Mutually exclusive with `tier`. The row stores `(model, backend_id)` together so the dispatcher honors the pin at fire time. |
+| `taskContext` | No | Structured metadata object |
+
+### Recurrence rule grammar (engine)
+
+The recurrence engine accepts four frequencies. Each frequency
+requires its own set of fields and rejects fields that don't apply.
+
+| `frequency` | Required | Allowed | Forbidden |
+|---|---|---|---|
+| `"hourly"` | — | `intervalHours` (1..23, default 1), `minuteOfHour` (0..59, default 0), `timezone` | `time`, `daysOfWeek`, `daysOfMonth`, `onMissingDay` |
+| `"daily"` | `time` | `timezone` | `intervalHours`, `minuteOfHour`, `daysOfWeek`, `daysOfMonth`, `onMissingDay` |
+| `"weekly"` | `time`, `daysOfWeek` (1..7 distinct entries, 0=Sun..6=Sat) | `timezone` | `intervalHours`, `minuteOfHour`, `daysOfMonth`, `onMissingDay` |
+| `"monthly"` | `time`, `daysOfMonth` (1..31 distinct entries) | `timezone`, `onMissingDay` (default `"lastDayOfMonth"`) | `intervalHours`, `minuteOfHour`, `daysOfWeek` |
+
+`time` is `HH:MM` 24-hour local. `timezone` is an IANA zone
+(`Asia/Tokyo`, `America/New_York`, `UTC`); auto-filled from daemon
+config when omitted, but explicit is safer so a roaming laptop does
+not surprise the user. The error envelope cites `validValues` on
+every range / format failure — read it and resubmit instead of
+guessing.
+
+### Hourly anchor semantics
+
+`intervalHours=N` fires when `(localHour % N) == 0` at
+`minuteOfHour` local. The anchor is **local midnight** in the rule's
+`timezone`, so `intervalHours:2, minuteOfHour:30` fires at 00:30,
+02:30, …, 22:30 local — predictable for the user's mental model.
+
+| Intent | `recurrenceRule` |
+|---|---|
+| Every hour at :00 | `{frequency:"hourly"}` |
+| Every hour at :15 | `{frequency:"hourly", minuteOfHour:15}` |
+| Every 2 hours at :30 | `{frequency:"hourly", intervalHours:2, minuteOfHour:30}` |
+| Every 6 hours at :00 (Asia/Tokyo) | `{frequency:"hourly", intervalHours:6, timezone:"Asia/Tokyo"}` |
+
+DST: in zones that observe it, a skipped local hour drops one fire;
+a doubled local hour fires once. Accepted edge case — do not try to
+compensate from the caller.
+
+Use hourly sparingly. Sub-hour cadences are not representable (the
+minimum is 1 hour); pick a coarser cadence or move the work into a
+daemon-internal poller instead.
+
+### Monthly missing-day semantics
+
+Some months don't contain the day the user asked for (Feb 30, Apr
+31). `onMissingDay` controls what happens that month:
+
+- `"skip"` — don't fire that month for the missing day.
+- `"lastDayOfMonth"` (default) — fire on the actual last day of the
+  month. Preserves the pre-redesign clamp behavior, so existing
+  recurring rules created before this redesign keep firing
+  bit-identically.
+
+The engine de-duplicates calendar dates that collapse to the same
+fire (e.g. `daysOfMonth:[28,31]` in non-leap Feb with
+`"lastDayOfMonth"` lands on Feb 28 once, not twice).
+
+| Recipe | `recurrenceRule` |
+|---|---|
+| 25th of every month at 21:00 | `{frequency:"monthly", time:"21:00", daysOfMonth:[25]}` |
+| 31st at 21:00, skip Feb/Apr/Jun/Sep/Nov | `{frequency:"monthly", time:"21:00", daysOfMonth:[31], onMissingDay:"skip"}` |
+| 31st at 21:00, fall back to last day | `{frequency:"monthly", time:"21:00", daysOfMonth:[31], onMissingDay:"lastDayOfMonth"}` |
+| **Last day of every month at 21:00** | same as above — `daysOfMonth:[31] + onMissingDay:"lastDayOfMonth"` clamps Feb/Apr/Jun/Sep/Nov to their last day; the 31st of every other month is already that month's last day |
+| 29th at 21:00, skip non-leap Feb | `{frequency:"monthly", time:"21:00", daysOfMonth:[29], onMissingDay:"skip"}` |
+| 1st AND 15th at 10:00 | `{frequency:"monthly", time:"10:00", daysOfMonth:[1,15]}` |
+
+When `daysOfMonth` contains 29/30/31 and `onMissingDay` is omitted,
+the daemon returns a `warnings[]` entry nudging you to be explicit.
+Persistence still happens — the warning is advisory.
+
+Response: `{ "status":"created", "item":{ "id","recurrenceRule","recurrenceLabel","nextRunAt",...}, "warnings":[] }`. `nextRunAt` is the UTC timestamp the engine has materialized as the first one-shot row's `scheduled_for`. `recurrenceLabel` is the human-readable form rendered into `rules/management.md` §B (e.g. `"Every 2 hours at :30 (UTC)"`, `"Monthly on the 31st at 21:00 (Asia/Tokyo); falls back to last day of month"`).
+
+## GET /api/recurring-schedules — List
+
+```bash
+curl -s "http://localhost:8321/api/recurring-schedules?enabled=true"
+```
+
+Response: `{ "items":[{ "id","taskType","description","recurrenceRule","enabled","nextRunAt","recurrenceLabel","model","backendId","tier","taskContext" }] }`. `model` / `backendId` are populated together when the row pins a registered id; otherwise `model:null, backendId:null` and `tier` carries the pin (or all three are null and the row inherits the dispatcher's process-key default).
+
+## PATCH /api/recurring-schedules/:id — Update
+
+```bash
+# Swap a daily rule to hourly + change model to Opus in one PATCH
+curl -s -X PATCH http://localhost:8321/api/recurring-schedules/1 \
+  -H 'Content-Type: application/json' \
+  -d '{"recurrenceRule":{"frequency":"hourly","intervalHours":2,"minuteOfHour":0},"tier":null,"model":"claude-opus-4-7"}'
+```
+
+Updatable: `recurrenceRule`, `description`, `prompt` (string sets an
+override, `null` clears), `tier` (set / `null` to clear), `model`
+(set / `null` to clear), `taskContext`, `enabled`. Changing
+`recurrenceRule` / `enabled` auto-reschedules — the pending one-shot
+row tied to the old rule is cancelled and a fresh row is materialized
+from the new `recurrenceRule` value, preserving the parent's
+`(model, backend_id)` or `tier` pin.
+
+**Tier ↔ model swap.** Pass `null` to clear one and a concrete value
+to set the other in the same request — the row carries at most one
+pin at rest. Setting a registered `model` token also clears any
+prior `tier_override`. Setting a legacy alias (`sonnet` / `opus`) on
+PATCH is rewritten to `tier:"medium"` / `tier:"high"`; the alias is
+never stored verbatim.
+
+**Re-materialization scope.** Changing `model` / `tier` alone does
+**not** re-point the already-materialized pending one-shot row — only
+`recurrenceRule` / `enabled` re-materialize. Delete the pending row
+(`DELETE /api/schedule/:id`) and let the next reconcile pass pick up
+the new pin, or PATCH `/api/schedule/:id` directly if you need the
+pending row repointed now.
+
+Set `{"enabled":false}` to pause without deleting. Surface
+`warnings[]` (e.g. `schedule.model_deprecated`,
+`schedule.on_missing_day_unused`) to the next turn — the PATCH still
+succeeds but the warning carries replacement guidance.
+
+## DELETE /api/recurring-schedules/:id — Delete
+
+```bash
+curl -s -X DELETE http://localhost:8321/api/recurring-schedules/1
+```
+
+Deletes the rule and cancels every materialized pending instance.
+Response: `{ "status":"deleted", "id":1 }`.
+
+Use pause (`PATCH ... {"enabled":false}`) instead when the user might
+want to resume the same cadence later — DELETE loses the
+`recurrenceRule` shape and the `taskContext` payload.

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

@@ -1,20 +1,18 @@
 ---
 name: scheduled-managed-task
-description: Run an `mt_<n>` managed task at its scheduled slot — pick a tool, fetch since last run, resolve to entity via §7.6, merge into `<domain>/<type-plural>/<slug>.md`. Trigger when `task_context.mt_id` matches `mt_<n>`; `task_context.adhoc === true` means run-now.
-when_to_use: A `scheduled.task` session with `task_context.mt_id` matching `mt_<n>`; `task_context.adhoc === true` marks on-demand pulls. SKIP for regular scheduled tasks, DM-tone scheduled sessions (`scheduled.dm`), or one-off reminder delivery.
+description: A `scheduled.task` session with `task_context.mt_id` matching `mt_<n>`; `task_context.adhoc === true` marks on-demand pulls. SKIP for regular scheduled tasks, DM-tone scheduled sessions (`scheduled.dm`), or one-off reminder delivery.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 
 # Scheduled Managed-Task Run
 
 This skill is the **scheduled execution** half of the management
-registry. The DM-side counterparts —
-`management-task-register` / `-modify` / `-stop` — own the row's
-lifecycle. This skill is what fires every cron slot to actually do
-the work.
+registry. The DM-side counterpart — the `managed-tasks` skill
+(`## Register` / `## Modify` / `## Stop` / `## Run once`) — owns the
+row's lifecycle. This skill is what fires every cron slot to actually
+do the work.
 
 ## When this skill activates
 
@@ -72,8 +70,8 @@ records the orphan firing.
 
 ### Step 2 — Select tool (LLM judgment, fresh each run)
 
-Same rule as `management-task-register` Step 3: enumerate the
-tools available to this session and pick by capability for
+Same rule as the `managed-tasks` skill's `## Register` Step 3:
+enumerate the tools available to this session and pick by capability for
 `item.app`. The user's prior choice (when surfaced as a hint in
 `task_context.lastToolChoice` by an earlier run) is a **hint**, not
 a binding — if it no longer exists in this session (the user
@@ -146,9 +144,9 @@ output_path = "finance/receipts/" → domain=finance, type=receipt
 ```
 
 If `output_path` is null (first run), pick the best `(domain, type)`
-from the data shape using the same prior table from
-`management-task-register` Step 4a. After this run, write the
-chosen path back to the row (Step 5b) so subsequent runs converge.
+from the data shape using the same prior table from the `managed-tasks`
+skill `## Register` Step 4a. After this run, write the chosen path back
+to the row (Step 5b) so subsequent runs converge.
 
 Slug: `<YYYY-MM-DD>-<sanitized-title>`. Sanitization rules:
 lowercase, ASCII-fold, replace `[^a-z0-9-]+` with `-`, collapse
@@ -256,8 +254,8 @@ audit shape.
 If the run produced a mix of domains/types (e.g. Drive PDFs that were
 half receipts and half random docs), leave `output_path` null — let
 the next run try again. The renderer marks null-path rows in §B with
-an em-dash; the user can also set the path explicitly via
-`management-task-modify`.
+an em-dash; the user can also set the path explicitly via the
+`managed-tasks` skill `## Modify` flow.
 
 ### Step 6 — Three-strikes notify
 
@@ -359,7 +357,7 @@ appended `## <App> Notes` body, not as a separate DM.
   daemon owns the threshold notify, the agent emits one DM at the
   3rd consecutive failure, then stays silent until success or stop.
 - Does NOT touch the §B row's `app` or `cadence` — those are
-  user-mutable only via `management-task-modify`.
+  user-mutable only via the `managed-tasks` skill `## Modify` flow.
 - Does NOT INSERT `agent_schedule` rows. The cron scheduler does.
 - Does NOT delete entity files when a tool returns "this item was
   removed upstream". Removal-from-source is recorded as a

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

@@ -8,10 +8,7 @@ allowed-tools:
 
 # today.md Guide
 
-Output language: follow `<output_language_policy>`. today.md is
-Policy B — the **skeleton lines listed below stay English verbatim**;
-bullets, narrative, and free-text fields under each H2 are written in
-`<settings primary_language>`. Preserve user-customized headers verbatim.
+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):**
 
@@ -143,28 +140,16 @@ Violations: row without schedule → silently never fires. Schedule without row
 
 ## Agent Plan lifecycle — close the loop
 
-When spawned by a `scheduled.task` for an Agent Plan row:
-
-1. Execute the task (send DM, fire notification, run check-in).
-2. Append to Agent Log: `- HH:MM [agent_plan] <action> — <outcome>`
-   Outcomes: `DM sent`, `notify sent`, `skipped (user in meeting)`, `failed: <reason>`
-3. Read today.md, locate the matching Agent Plan row (match HH:MM + action text), flip `[ ]` → `[x]`:
-   ```bash
-   curl -s http://localhost:8321/api/context/today
-   # Edit the agent_plan section body, then:
-   curl -s -X PATCH http://localhost:8321/api/context/today \
-     -H 'Content-Type: application/json' \
-     -d '{"section": "agent_plan", "mode": "replace", "content": "- [x] 08:55 ..."}'
-   ```
-   **Read-before-write is mandatory** — PATCH replace replaces the entire section.
-4. If the Agent Plan row is missing (user hand-edited), log and skip.
-5. Always flip to `[x]`, even for skips/failures — annotate non-success:
-   - Success: no annotation
-   - Skip: `⚠ skipped: <reason>`
-   - Failure: `⚠ failed: <reason>`
-6. If PATCH returns 409 (Morning Routine lock), retry after 30s up to 3 times. If still locked, log `loop-closeout deferred`.
-
-**Why flip inside the scheduled task, not later?** The user may DM at 09:00 asking "did you send the reminder?" — if the row is still `[ ]`, the DM handler can't tell whether it was sent.
+`scheduled.task` and `scheduled.dm` (and any other event that flips an
+Agent Plan row) follow the close-the-loop lifecycle in the reference
+below: execute, append Agent Log entry, read-then-flip the row to
+`[x]` with annotation, retry on `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.
+
+{{> ref:agent-plan-lifecycle }}
 
 ## Agent Log format
 
@@ -193,7 +178,7 @@ so the LLM never sees this format-using event with a wider lookahead.
 No additional gate is restated here.
 
 **Agent Notes**:
-`- 📅 event_title starts at HH:MM [— blocks/relates to: <task>]`
+`- event_title starts at HH:MM [— blocks/relates to: <task>]`
 
 **Agent Log** (always):
 `- HH:MM [cal] event_title — action`
@@ -204,36 +189,21 @@ Morning Routine acquires exclusive lock. Other sessions get 409 on PUT/PATCH (GE
 
 PUT today.md must contain the H1 date line, day-type header quote, and all six sections in order.
 
-## today.md API (subset of context API)
-
-Body submission follows the rule in `_safety.md` "Daemon-API body
-submission": small section PATCHes use inline `-d '{...}'`; full-file
-PUT uses the stdin heredoc `-d @- <<'JSON'` shape because the body
-runs multi-KB. Add `X-Lock-Id: <today_write_lock_id>` on every
-PUT / PATCH when that tag is in your context.
-
-```bash
-# Read
-curl -s http://localhost:8321/api/context/today
-
-# Full replace — Morning Routine only. Multi-KB body → heredoc.
-curl -s -X PUT http://localhost:8321/api/context/today \
-  -H 'Content-Type: application/json' \
-  -H 'X-Lock-Id: <today_write_lock_id>' \
-  -d @- <<'JSON'
-{"content":"# 2026-04-02 (Thursday)\n> Day type: Weekday | Work focus: on | Study focus: on | Personal focus: on\n\n## User Schedule\n- 14:00–15:00 Design review [work]\n\n## User Tasks\n- [ ] 11:00 Finalize Q2 draft [work]\n\n## Agent Plan\n- [ ] 08:55 DM reminder: standup [work] →DM\n\n## Agent Notes\n\n## Agent Log\n- 04:00 Morning Routine completed (day-type: Weekday)\n\n## Handoff\n- (none)\n"}
-JSON
-
-# Section operation — small body, inline `-d` is fine.
-curl -s -X PATCH http://localhost:8321/api/context/today \
-  -H 'Content-Type: application/json' \
-  -H 'X-Lock-Id: <today_write_lock_id>' \
-  -d '{"section":"agent_log","mode":"append","content":"- 09:35 ..."}'
-```
-
-The H1 date and the `> Day type:` quote line are validated by exact
-regex on PUT — keep both English-shaped exactly as the template. See
-context skill for the full endpoint reference.
+## 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.** `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
+  today_write_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
+  rejected (422) if line 1's date disagrees with the daemon's current
+  agent-day — the error echoes both values.
 
 ## Knowledge map — section shape (auto-curated)
 

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

@@ -0,0 +1,113 @@
+---
+kind: reference
+name: agent-plan-lifecycle
+description: Agent Plan close-the-loop lifecycle for scheduled.task / scheduled.dm sessions — execute, log, flip [x], handle missing rows / failures / lock retries.
+---
+
+# Agent Plan lifecycle — close the loop
+
+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.
+
+## Why flip inside the scheduled task, not later?
+
+The user may DM at 09:00 asking "did you send the reminder?" — if the
+matching Agent Plan row is still `[ ]`, the DM handler cannot tell
+whether the reminder was sent. The flip must land in the same turn as
+the action it represents, before the session exits.
+
+## Steps (when spawned by `scheduled.task` for an Agent Plan row)
+
+1. **Execute the task.** Send the DM, fire the notification, run the
+   check-in — whatever the row's action text describes. The row's
+   trigger tag (`→DM`, `→notify`, `→check-in`, `→wake`) selects the
+   API surface (see `today` skill §"Entry formats").
+
+2. **Append an Agent Log entry** describing the outcome:
+
+   ```
+   - HH:MM [agent_plan] <action> — <outcome>
+   ```
+
+   Outcomes (use exactly one, lowercase):
+   - `DM sent`
+   - `notify sent`
+   - `check-in done`
+   - `wake fired`
+   - `skipped (<reason>)` — e.g. `skipped (user in meeting)`,
+     `skipped (focus off)`, `skipped (deduped)`
+   - `failed: <reason>` — short, single-line, no stack trace
+
+   Agent Log entries are mandatory before the flip, not after. If the
+   PATCH that flips the row to `[x]` fails, the log entry is the only
+   record that the action ran.
+
+3. **Read today.md, locate the matching Agent Plan row** (match HH:MM
+   + action text), and flip `[ ]` → `[x]`:
+
+   ```bash
+   curl -s http://localhost:8321/api/context/today
+   # Find the agent_plan section. Edit the matching row's checkbox.
+   # Then PATCH the full updated section body:
+   curl -s -X PATCH http://localhost:8321/api/context/today \
+     -H 'Content-Type: application/json' \
+     -H 'X-Lock-Id: <today_write_lock_id>' \
+     -d '{"section": "agent_plan", "mode": "replace", "content": "<full merged section>"}'
+   ```
+
+   **Read-before-write is mandatory** — `PATCH mode: "replace"` replaces
+   the entire section body. Send only the flipped row and you erase
+   every other Agent Plan row.
+
+4. **If the Agent Plan row is missing** (user hand-edited, row was
+   pruned by Evening Review, race with a concurrent rewrite), log
+   `skipped (row_missing)` to Agent Log and exit. Do not append a
+   new row to back-fill — the row's absence is informative state.
+
+## Flip-to-[x] cardinality rule
+
+**Always flip to `[x]`, even for skips and failures.** The cardinality
+rule is: every Agent Plan row reaches exactly one terminal state per
+agent-day, and that state is `[x]`. Annotate the non-success cases in
+parentheses appended to the action text:
+
+| Outcome | Row content after flip |
+|---|---|
+| Success | `- [x] HH:MM <action> [category] →<trigger>` (no annotation) |
+| Skip | `- [x] HH:MM <action> [category] →<trigger> (skipped: <reason>)` |
+| Failure | `- [x] HH:MM <action> [category] →<trigger> (failed: <reason>)` |
+
+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.
+
+## Lock retry rules
+
+The Morning Routine holds the `today.md` write lock. Other sessions
+get `409 today_write_lock_held` on PUT / PATCH while the lock is held.
+
+- Detect by the response body `{"error":"lock_held"}` or by the
+  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
+  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
+  window returns 409 even though you would have been allowed in
+  during a no-lock window.
+
+## What this lifecycle does NOT cover
+
+- Agent Notes flavors and their flips (`Profile question (latent)` ↔
+  `Profile question (asked HH:MM)`) — those live in the
+  `user-interview` skill, not in this lifecycle.
+- The schedule.approaching → Agent Notes / Agent Log format — that
+  is in the `today` skill body (§"schedule.approaching → Agent Notes
+  + Agent Log"), not here. The 15-minute firing gate is the daemon's,
+  not the skill's.
+- The Morning Routine's initial population of Agent Plan rows — see
+  the morning routine task-flow.