@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,392 @@
+---
+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.
+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.
+
+## When this skill activates
+
+Auto-loaded when the dispatcher routes a `scheduled.task` event whose
+`task_context.mt_id` matches `^mt_[1-9]\d*$`. The `mt_id` field in
+`task_context` is the contract between the managed-tasks route and
+this skill — both the recurring fire (`POST /api/managed-tasks` →
+`recurring_schedules` → `agent_schedule`) and the on-demand fire
+(`POST /api/managed-tasks/:id/run-now`) populate it. The
+`task_context.adhoc === true` boolean (also set by the on-demand
+route) signals which one you're in.
+
+If `task_context.mt_id` is absent, this is **not** a managed-task
+run — fall through to the regular `scheduled.task` flow per
+`scheduled.task.md`.
+
+## Algorithm (mirror of design 21 §10.4)
+
+### Step 0 — Identify the row
+
+Pull `mt_<n>` from `task_context.mt_id`. When `task_context.adhoc ===
+true`, this run came from `POST /api/managed-tasks/:id/run-now` — the
+row's `last_run_at` IS updated, but the audit row gets tagged
+`adhoc:true` so the activity-view reconciler can distinguish it. The
+`task_context.reason` field (from the run-now body) is a free-text
+hint about why the user pulled.
+
+### Step 1 — Read the row
+
+```bash
+curl -s "http://localhost:8321/api/managed-tasks/mt_43" | jq .item
+```
+
+The route wraps the row in `{item:<ManagedTask>}`. Relevant fields on
+`item`:
+
+```jsonc
+{
+  "id":             "mt_43",
+  "intent":         "Zoom recordings → meeting entity",
+  "app":            "zoom",
+  "app_normalized": "zoom",
+  "cadence":        "daily 10:00 (Asia/Tokyo)",
+  "output_path":    "work/meetings/",   // may be null on first run
+  "schedule_id":    17,
+  "last_run_at":    "2026-12-04T10:00:00Z",
+  "last_result":    "ok (3 new)",
+  "consecutive_failures": 0
+}
+```
+
+If the GET returns 404, the row was stopped between schedule firing
+and skill invocation. End the session quietly — the daemon's audit
+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
+`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
+reinstalled MCPs, the backend rotated), pick afresh.
+
+- **Zero plausible** → record `last_result='failed: connector
+  unavailable'`; the three-strikes rule (§10.4 step 6) handles
+  user-facing notification. Stop.
+- **Multiple plausible AND no hint** → record `last_result='failed:
+  ambiguous tool selection'`; the next on-demand DM lets the user
+  disambiguate. Stop.
+- **One plausible OR hint resolves** → continue.
+
+NEVER hardcode tool names — see ADR §8.4 / FR-4.
+
+### Step 3 — Invoke with `since = last_run_at`
+
+Issue the smallest read that returns "everything new since
+`last_run_at`". For most apps that is a `since` / `updated_after` /
+`q: "after:<ISO>"` parameter. If the tool only exposes a `limit`,
+fetch a generous page and filter client-side.
+
+For an `.adhoc` run with no explicit `since` from the user, default
+to `now − 24h` (safety: don't pull months on a manual fire).
+
+If the tool returns an error, record `last_result='failed: <verbatim
+error>'` and stop. The 3-strikes rule (Step 6) governs notifications.
+
+### Step 4 — Resolve each new datum to an entity (§7.6 lookup contract)
+
+For every new item the tool returned, decide *which* `<domain>/<type-plural>/<slug>.md`
+file to merge it into. Lookup precedence is **strict** — fall through
+in order:
+
+#### 4.1 Exact `(source_key, external_id)` match
+
+```bash
+curl -s "http://localhost:8321/api/entities?source=zoom&external_id=zm_xyz789" | jq .
+```
+
+If 1 result, that's the entity. Reuse its `path`. This is the
+strongest signal and guarantees no duplicates when the upstream app
+exposes a stable id.
+
+If >1 result the mirror is corrupted — record
+`last_result='failed: entity-mirror conflict'` and stop. The boot
+reconciler converges from the L2 files.
+
+#### 4.2 Fallback: `(domain, type, date, fuzzy title)` within ±48 h
+
+```bash
+curl -s "http://localhost:8321/api/entities?domain=work&type=meeting&date=2026-12-04&q=foo+1on1" | jq .
+```
+
+The daemon does the fuzzy match server-side (token-overlap on
+`title`). If 1 confident result, reuse. If >1 confident result, pick
+the one whose `sources.<other_app>.*` already overlaps with this
+datum's metadata (e.g. a Calendar entity already bound to the same
+attendees → that's the right meeting).
+
+#### 4.3 Otherwise: allocate a new entity
+
+Decide `(domain, type)` from the datum shape. **Bias toward the row's
+`output_path`** when present — it encodes the user's intent for this
+managed task:
+
+```
+output_path = "work/meetings/"  →  domain=work, type=meeting
+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.
+
+Slug: `<YYYY-MM-DD>-<sanitized-title>`. Sanitization rules:
+lowercase, ASCII-fold, replace `[^a-z0-9-]+` with `-`, collapse
+runs of `-`, trim leading/trailing `-`, cap at 64 chars. The slug
+must match `^[a-z0-9][a-z0-9-]*$` per §9.3 EntitySchema.
+
+### Step 5a — Merge into the entity file
+
+For each resolved entity:
+
+```bash
+curl -sS -X PATCH "http://localhost:8321/api/context/work/meetings/2026-12-04-foo-1on1" \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{
+  "section": "Zoom Notes",
+  "mode":    "append",
+  "content": "- duration 60 min\n- recording: <link>\n- external_id: zm_xyz789\n- transcript snippet: …\n"
+}
+JSON
+```
+
+The daemon's section-append `mode:"append"` adds the lines under the
+named `## Zoom Notes` heading; the heading itself is stable across
+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`.
+
+### Step 5b — Update the row
+
+The user-facing PATCH (`/api/managed-tasks/:id`) is **immutable** for
+`last_run_at` / `last_result` / `consecutive_failures` by design — those
+fields are written by this skill through a dedicated internal endpoint
+so the user-facing surface and the run-result surface have separate
+schemas and risk-tier intents.
+
+```bash
+# Success path
+curl -sS -X PATCH http://localhost:8321/api/managed-tasks/mt_43/run-result \
+  -H 'Content-Type: application/json' \
+  -d '{"last_run_at":"2026-12-04T10:00:00Z","last_result":"ok (3 new)","consecutive_failures":0}'
+
+# Failure path — explicit count, NOT an increment flag
+curl -sS -X PATCH http://localhost:8321/api/managed-tasks/mt_43/run-result \
+  -H 'Content-Type: application/json' \
+  -d '{"last_run_at":"2026-12-04T10:00:00Z","last_result":"failed: <reason>","consecutive_failures":<prev+1>}'
+```
+
+`managedTaskRunResultSchema` is **replace-semantics** for
+`consecutive_failures` — read the previous value from Step 1's
+response and send the next integer (`prev + 1` for failures, `0` for
+success). There is no `consecutiveFailuresIncrement` flag.
+
+**Output-path back-fill.** If `output_path` was null going in and you
+allocated entities under one consistent `<domain>/<type-plural>/`,
+relocate it via the user-facing PATCH **after** the run-result PATCH
+(two writes — the schemas don't overlap):
+
+```bash
+curl -sS -X PATCH http://localhost:8321/api/managed-tasks/mt_43 \
+  -H 'Content-Type: application/json' \
+  -d '{"output_path":"work/meetings/"}'
+```
+
+The two-step write is intentional — the user-facing PATCH emits a
+`management_task.modified` audit row with `from`/`to`, which is the
+right signal for "the agent learned the path on its own". Combining
+both into `/run-result` would hide the path change in a less specific
+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`.
+
+### 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).
+
+**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:
+
+```bash
+curl -sS -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message":  "Managed task mt_43 has failed 3 consecutive runs: <reason>. The schedule remains active. Stop or modify it via DM.",
+    "priority": "normal"
+  }'
+```
+
+The crossing-edge condition is critical — DM-ing on every failure
+once over the threshold would spam the user. Trip on the transition
+3-to-now-3, never on 4 → 4 / 5 → 5 / etc.
+
+The schedule is **never auto-stopped** — see ADR-flavored note in
+§10.4: "Auto-stop would silently lose user intent. Notify-then-defer-
+to-user honors 'destructive ops require user confirmation'." So the
+agent keeps trying, but doesn't disappear silently.
+
+### Step 7 — End the session
+
+`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
+`<domain>/_index.md`, not in a chat ping per fire.
+
+Exceptions:
+
+- 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.
+
+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
+in `scheduled.task.md` Step 4 is for DM-originated tasks, not for
+`mt_<n>` correlated firings. Skip Steps 1 / 4 of `scheduled.task.md`
+when this skill is the executing skill.
+
+## Idempotency
+
+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.
+
+## Caps
+
+`output_path` validation, app-string length, intent length all carry
+through from §13.3. The daemon enforces them at PATCH time; if the
+fetched data violates them (rare — usually upstream titles too long),
+truncate the offending field and surface a one-line warning in the
+appended `## <App> Notes` body, not as a separate DM.
+
+## Error envelope
+
+| 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/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 touch the §B row's `app` or `cadence` — those are
+  user-mutable only via `management-task-modify`.
+- 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
+  `frontmatter.sources.<app>.deleted_at` annotation, not a file
+  delete (the user's notes might still be valuable).
+- Does NOT call any skill outside the read-only context API + the
+  selected backend tool. Specifically: no `management-task-*`
+  variant, no `schedule` mutation, no `roadmap` write.
+- Does NOT include the row's `output_path` change in Step 5b unless
+  the run actually produced data confirming the path. Speculative
+  back-fill is forbidden.
+
+## API summary
+
+| Verb + path | Used in |
+|---|---|
+| `GET /api/managed-tasks/:id` | Step 1 (response wraps row in `{item}`) |
+| `GET /api/entities?source=&external_id=` | Step 4.1 (tier-1 exact) |
+| `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/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) |
+
+The PATCH on `/api/managed-tasks/:id/run-result` writes one
+`agent_actions` row (`management_task.run_recorded`); the §B render
+and snapshot are the daemon's job. Do NOT post a separate audit
+event.

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

@@ -0,0 +1,198 @@
+---
+name: today
+description: Load for any event that reads or writes today.md — morning routines, hourly checks, DMs, scheduled tasks. Owns the day-type filter, Agent Plan contract, Agent Log/Notes schema, schedule.approaching format, and Morning Routine lock.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# today.md Guide
+
+today.md has a **day-type header line** (second line) and **six required sections**.
+
+```
+# YYYY-MM-DD (day-of-week)
+> Day type: Weekday | Work focus: on | Study focus: on | Personal focus: on
+
+## User Schedule
+## User Tasks
+## Agent Plan
+## Agent Notes
+## Agent Log
+## Handoff
+```
+
+## Line 1 — which date?
+
+Always copy the date from the prompt's `<current_agent_day date="…" weekday="…" boundary_hour="…" />`.
+That attribute is the **agent-day date**, not the calendar date — they
+diverge between local midnight and `boundary_hour:00` local. Use the
+attribute value verbatim:
+
+```
+# <current_agent_day.date> (<current_agent_day.weekday>)
+```
+
+So when the prompt context contains
+`<current_agent_day date="2026-04-28" weekday="Tuesday" boundary_hour="4" />`,
+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.
+
+today.md has **no YAML frontmatter** — the H1 must be the first byte of
+the file.
+
+## Header line — day-type filter
+
+Line 2 encodes today's filter policy (field order is fixed — downstream parsers rely on it):
+
+```
+> 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 `user/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 it:
+- Morning Routine suppresses items with focus `off` at generation time
+- scheduled.task re-checks at fire time: if focus is off, skip + close as `skipped (focus off)`
+- DM handler skips follow-ups on rows whose focus is off
+- Hourly check drops observations whose focus is off
+- schedule.approaching suppresses notifications for off categories
+
+## Sections and 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.
+
+## User Tasks vs Agent Plan
+
+User Tasks = things the **user** will do.
+Agent Plan = things **Claude Code** will do to help the user.
+
+## Agent Plan contract
+
+1. Every Agent Plan row MUST be backed by exactly one `POST /api/schedule` that fires at the stated HH:MM.
+2. Every planned outbound reminder/DM/check-in MUST appear as a row so the user can audit it.
+3. When the scheduled wake-up fires, the handler MUST close the loop (see lifecycle below).
+
+Violations: row without schedule → silently never fires. Schedule without row → invisible work. Past `[ ]` row → bug or de-registered.
+
+## 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.
+
+## Agent Log format
+
+`- HH:MM Action description`. Log every user-visible action, context file write, or outbound API call. Skip purely internal no-ops.
+
+## Agent Notes flavors
+
+- **Look-ahead** (Morning Routine): `- [ ] (HIGH/MID/LOW) description — reasoning`
+- **Day-time observations**: `- Source: summary of notable change`
+- **Latent profile question** (Morning Routine Step 7.5):
+  `- Profile question (latent): <id> — wait for natural opportunity`
+  Flipped to `- Profile question (asked HH:MM): <id>` by the DM
+  handler / morning briefing when the question is woven into a reply.
+  Not an Agent Plan row — does NOT carry a leading HH:MM and is NOT
+  backed by a schedule entry. The question is opportunistic, not
+  scheduled. The parenthetical `(latent)` / `(asked HH:MM)` is the
+  state field; the LLM finds the line by matching the
+  `Profile question (latent): <id>` prefix. See the **user-interview**
+  skill for the full lifecycle.
+
+## 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`),
+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>]`
+
+**Agent Log** (always):
+`- HH:MM [cal] event_title — action`
+
+## Morning Routine lock
+
+Morning Routine acquires exclusive lock. Other sessions get 409 on PUT/PATCH (GET always allowed). If `<today_write_lock_id>` is in context, include `X-Lock-Id` header on every PUT/PATCH. Lock auto-releases on daemon timeout.
+
+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)
+
+```bash
+curl -s http://localhost:8321/api/context/today                    # Read
+curl -s -X PUT http://localhost:8321/api/context/today \            # Full replace (Morning only)
+  -H 'Content-Type: application/json' -d '{"content": "# 2026-04-02 (Thu)\n..."}'
+curl -s -X PATCH http://localhost:8321/api/context/today \          # Section operation
+  -H 'Content-Type: application/json' -d '{"section": "agent_log", "mode": "append", "content": "- 09:35 ..."}'
+```
+
+Add `X-Lock-Id` header if `<today_write_lock_id>` is in context. See context skill for full API reference.
+
+## Knowledge map — section shape (auto-curated)
+
+<!-- CURATION:knowledge_layout id="section-shape" -->
+
+## Agent Notes flavors (auto-curated)
+
+<!-- CURATION:convention_notes id="agent-notes-flavors" -->

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

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "section-shape",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"section-shape\" -->",
+      "human_label": "today.md section shape",
+      "description": "Required sections in today.md and what each holds",
+      "scope_paths": ["today.md"]
+    },
+    {
+      "id": "agent-notes-flavors",
+      "kind": "convention_notes",
+      "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"]
+    }
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "kind": "convention_notes",
+  "notes": [
+    {
+      "topic": "Look-ahead",
+      "rule": "Look-ahead notes flag a future event the user may want to prepare for, written as a single bullet under ## Agent Notes."
+    },
+    {
+      "topic": "Day-time observation",
+      "rule": "Day-time observations capture something the user said or did during the day that is worth surfacing later, often in the next morning routine."
+    },
+    {
+      "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."
+    }
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "today.md",
+      "purpose": "today's plan, schedule, agent 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": "## 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" }
+      ]
+    }
+  ]
+}