@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/skills/schedule/references/model-selection.md

@@ -0,0 +1,96 @@
+---
+kind: reference
+name: model-selection
+description: Tier vs model selection for schedule rows + `GET /api/schedule/options` discovery endpoint. Mutual-exclusion rules, legacy alias rewrite, composite-form disambiguator.
+---
+
+# Tier / Model selection
+
+`tier` is the backend-neutral cost knob — **prefer it**. `model` pins
+a specific registered model id when the row must run against a
+particular backend (e.g. a routine that depends on Opus reasoning
+even after `/settings/models` re-routes the process key). The two are
+**mutually exclusive on a single row** — passing both returns
+`schedule.tier_and_model_conflict` (no "tier wins" precedence).
+
+| `tier` | Class | When |
+|---|---|---|
+| `"lite"` | Haiku | hourly polling / health checks (e.g. docker `ps` summary) |
+| `"medium"` | Sonnet | lock against future `/settings/models` re-routes |
+| `"high"` | Opus | one-off generative work driving user-visible output |
+
+`model` accepts:
+
+- **Legacy aliases** — `"sonnet"` / `"opus"`. Auto-rewritten at the
+  route to `tier:"medium"` / `tier:"high"`; the alias is not stored
+  verbatim.
+- **Registered model ids** — any id from `MODEL_REGISTRY` across the
+  four backends. Examples: `claude-opus-4-8`, `claude-sonnet-4-6`,
+  `claude-haiku-4-5-20251001`, `gpt-5.4`, `gemini-3.1-pro-preview`.
+  The row persists `(model, backend_id)` together so the dispatcher
+  honors the pin at fire time.
+- **Composite `<backendId>/<modelId>`** — disambiguator for a future
+  registry that has the same model id under multiple backends (today
+  unreachable but accepted). The prefix MUST be one of `claude` /
+  `codex` / `gemini` / `opencode`; opencode model ids like
+  `anthropic/claude-opus-4-8` are NOT composites and fall through to
+  the cross-backend scan.
+
+Unknown / ambiguous / deprecated model tokens surface through the
+error envelope's `validValues` field — read it instead of guessing.
+The full code list lives in `references/errors.md`.
+
+## PATCH semantics — tier ↔ model swap
+
+A row carries at most one pin at rest. On PATCH:
+
+- Pass `null` to clear one and a concrete value to set the other in
+  the same request — that is the documented form for swapping a
+  tier-pinned row to a model-pinned row (and vice versa).
+- Setting a registered `model` token also clears any prior
+  `tier_override` automatically; setting `tier` does not auto-clear
+  `model` — pair the change with `"model": null` when the intent is
+  to swap.
+- Setting a legacy alias (`sonnet` / `opus`) on PATCH is rewritten to
+  `tier:"medium"` / `tier:"high"`; the alias is never stored verbatim.
+
+## Discovery — `GET /api/schedule/options`
+
+Read-only one-stop endpoint that returns every value the daemon will
+accept right now: registered models per backend, model aliases,
+allowed tiers, recurrence frequencies, `daysOfWeek` map, hourly /
+monthly bounds (`intervalHours` 1..23, `minuteOfHour` 0..59,
+`onMissingDay` default), and the operator's configured timezone.
+Fetch once per cold session before composing tricky schedules; the
+error envelope also cites this endpoint via `docsUrl` so you can
+recover after a 400.
+
+```bash
+curl -s http://localhost:8321/api/schedule/options
+```
+
+Response shape:
+
+```jsonc
+{
+  "tiers": ["lite", "medium", "high"],
+  "modelAliases": { "sonnet": "medium", "opus": "high" },
+  "models": {
+    "claude":   [{ "id": "claude-opus-4-8", "tier": "high", "deprecated": false }, ...],
+    "codex":    [...],
+    "gemini":   [...],
+    "opencode": [...]
+  },
+  "frequencies": ["hourly", "daily", "weekly", "monthly"],
+  "daysOfWeek":  { "0": "Sun", "1": "Mon", ..., "6": "Sat" },
+  "recurrence": {
+    "intervalHours": { "min": 1, "max": 23 },
+    "minuteOfHour":  { "min": 0, "max": 59 },
+    "daysOfMonth":   { "min": 1, "max": 31 },
+    "onMissingDay":  { "values": ["skip", "lastDayOfMonth"], "default": "lastDayOfMonth" }
+  },
+  "timeFormat":      "HH:MM (24h)",
+  "timezoneExample": "Asia/Tokyo",
+  "defaults":        { "timezone": "<operator's configured primary timezone>" }
+}
+```

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
+`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.

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
@@ -177,39 +175,49 @@ runs. The (`section`, `mode`, `content`, `cutoff`, `maxEntries`)
 shape is the contract today — see `contextPatchSchema` in
 `packages/shared/src/schemas.ts`.
 
-**Source-id capture (write the `external_id` into the body lines):**
-the entity-mirror watcher (P5) reparses the file's frontmatter on
-change, so the dedup contract in §7.6 hinges on the upstream id
-landing in **frontmatter**, not just the body. Until the entity-mirror
-reconciler ships AND the context API gains a `frontmatter*` patch
-mode for `<domain>/<type-plural>/*` files, do this:
-
-1. Always include `- external_id: <id>` on its own line in the
-   appended `## <App> Notes` body so a future reconciler-rebuild can
-   recover the binding from prose.
-2. Track the binding in the §B "Recently changed" path — the
-   `agent_actions.management_task.run_recorded` row's `detail` is
-   structured and survives even when the file body doesn't reflect
-   the binding cleanly.
-
-> **Implementation gap to flag** (Phase 5 / extended Phase 3): the
-> context PATCH route does not currently:
->   - allow writes under `<domain>/<type-plural>/*` (no entry in
->     `CONTEXT_WRITE_PERMISSIONS`), so this PATCH returns `403
->     forbidden` until the whitelist is widened, and
->   - expose a `frontmatterMerge` mode for deep-merging
->     `frontmatter.sources.<app>`.
-> Both are required by design 21 §10.4 step 4b and must land before
-> this Step 5a goes from "designed" to "operational". Until then,
-> Step 5b's audit row is the durable trace of the run — surface that
-> in the activity-view rather than relying on the entity body.
-
-If the entity file does not previously exist, today's API requires a
-PUT with full content (the `<domain>/<type-plural>/*` write path is
-gated by the same whitelist note above). When the gap closes, the
-first PATCH must include a complete frontmatter block — `type`,
-`domain`, `slug`, `title`, `created`, `sources` — or the daemon
-returns 422 against `EntitySchema`.
+**Source-id capture — deep-merge into frontmatter (`mode:"frontmatterMerge"`):**
+the §7.6 dedup contract hinges on the upstream id landing in **frontmatter**
+(`sources.<app>.external_id`) — the canonical signal the entity-mirror watcher
+reparses and `GET /api/entities?source=…&external_id=…` queries — not just the
+body. The context PATCH route exposes `mode:"frontmatterMerge"` for exactly this
+(design 21 §10.4 step 4b): it deep-merges a partial frontmatter object into the
+file's existing YAML (nested objects merge key-by-key; scalars/arrays replace),
+so a new `<app>` source is linked without clobbering other apps' ids, other
+frontmatter keys, or the body:
+
+```bash
+curl -sS -X PATCH "http://localhost:8321/api/context/work/meetings/2026-12-04-foo-1on1" \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{
+  "mode": "frontmatterMerge",
+  "frontmatter": {
+    "sources": { "zoom": { "external_id": "zm_xyz789" } },
+    "last_synced_at": "2026-12-04T09:00:00Z"
+  }
+}
+JSON
+```
+
+`frontmatterMerge` requires a non-empty `frontmatter` object and takes no
+`section` (it never touches the body). Append the human-readable
+`## <App> Notes` section in a separate `mode:"append"` / `"append_to_file"`
+PATCH. Also keep Step 5b's audit row as the durable structured trace of the run.
+
+> **Write path:** the bare `<domain>/<type-plural>/<slug>` path is alias-rewritten
+> to `knowledge/entities/<domain>/<type-plural>/<slug>` by `context-vault-aliases.ts`,
+> which **is** whitelisted in `CONTEXT_WRITE_PERMISSIONS` for `PUT`/`PATCH`
+> (autonomous tier), so both the frontmatterMerge and the body-append PATCH
+> succeed on an existing entity file. (Recognised domains: `work`, `travel`,
+> `finance`, `personal`, `health`, `learning`.)
+
+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`.
 
 ### Step 5b — Update the row
 
@@ -256,8 +264,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
 
@@ -298,7 +306,7 @@ agent keeps trying, but doesn't disappear silently.
 `scheduled.task` flow's "Output contract — your final text becomes a
 DM" applies (`scheduled.task.md`). For managed-task runs the default
 is **empty final text**: bookkeeping is invisible by design. The user
-sees the change reflected in `_activity/<source>.md` (auto-built) and
+sees the change reflected in `state/activity/<source>.md` (auto-built) and
 `<domain>/_index.md`, not in a chat ping per fire.
 
 Exceptions:
@@ -345,7 +353,7 @@ 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` |
-| 403 (`/api/context/<domain>/<type-plural>/...`) | `forbidden` | Entity-domain write paths are not yet whitelisted (Phase 5 gap, §Step 5a). Skip the entity merge for this run, still record run-result, and surface a one-line warning in `last_result`. |
+| 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 |
@@ -359,7 +367,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
@@ -381,7 +389,7 @@ appended `## <App> Notes` body, not as a separate DM.
 | `GET /api/entities?source=` | Step 4 bias hint (list-by-source-key) |
 | `GET /api/entities?domain=&type=&date=&q=` | Step 4.2 (tier-2 fuzzy) |
 | `GET /api/entities/by-path?path=` | Step 4 (verify before merging) |
-| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (gated by entity-domain write whitelist — Phase 5 gap) |
+| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (whitelisted PUT/PATCH; PATCH requires the file to exist — PUT-create first if 404) |
 | `PATCH /api/managed-tasks/:id/run-result` | Step 5b (internal — last_run_at / last_result / consecutive_failures) |
 | `PATCH /api/managed-tasks/:id` | Step 5b output-path back-fill only |
 | `POST /api/notify` | Step 6 (only on the 3-failures-in-a-row crossing edge) |

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):**
 
@@ -26,7 +23,7 @@ bullets, narrative, and free-text fields under each H2 are written in
    `## Agent Plan`, `## Agent Notes`, `## Agent Log`, `## Handoff` —
    in this order.
 
-A `PUT /api/context/today` whose line 1 or line 2 fails the exact regex
+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
@@ -66,9 +63,9 @@ line 1 is exactly `# 2026-04-28 (Tuesday)`. Do **not** advance the date
 because the routine is "preparing tomorrow"; the morning routine always
 prepares the agent-day in progress, not the next one.
 
-`PUT /api/context/today` returns 422 if line 1 disagrees with the
-daemon's current agent-day; the error message echoes both values so a
-mistake is recoverable in the same session.
+`PUT /api/context/state/today` returns 400 (`error:"validation_error"`) if
+line 1 disagrees with the daemon's current agent-day; the error message
+echoes both values so a mistake is recoverable in the same session.
 
 today.md has **no YAML frontmatter** — the H1 must be the first byte of
 the file.
@@ -83,7 +80,7 @@ Line 2 encodes today's filter policy (field order is fixed — downstream parser
 
 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 `user/profile.md` → ## Notification Preferences. Apply matching policy.
+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:
@@ -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 `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.
+
+{{> 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.** `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.
 
 ## Knowledge map — section shape (auto-curated)
 

package/agent-assets/skills/today/curation.json

@@ -5,9 +5,9 @@
       "id": "section-shape",
       "kind": "knowledge_layout",
       "anchor": "<!-- CURATION:knowledge_layout id=\"section-shape\" -->",
-      "human_label": "today.md section shape",
+      "human_label": "state/today.md section shape",
       "description": "Required sections in today.md and what each holds",
-      "scope_paths": ["today.md"]
+      "scope_paths": ["state/today.md"]
     },
     {
       "id": "agent-notes-flavors",
@@ -15,7 +15,7 @@
       "anchor": "<!-- CURATION:convention_notes id=\"agent-notes-flavors\" -->",
       "human_label": "Agent Notes flavors",
       "description": "Sub-shapes the agent uses inside ## Agent Notes (look-ahead, day-time observation, latent profile question)",
-      "scope_paths": ["today.md"]
+      "scope_paths": ["state/today.md"]
     }
   ]
 }

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

@@ -0,0 +1,114 @@
+---
+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/state/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/state/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 `state/today.md` write lock. Other sessions
+get `409 morning_routine_lock_held` on PUT / PATCH while the lock is held.
+
+- Detect by the response body `{"error":"morning_routine_lock_held"}`
+  (with `errors[0].code: "context.morning_routine_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.