@aitne-sh/aitne 0.1.7 → 0.1.8

package/agent-assets/skills/notify/references/priority.md

@@ -0,0 +1,60 @@
+---
+kind: reference
+name: priority
+description: Notification priority levels — critical / high / normal / low — with quiet-hours behavior and per-level examples.
+---
+
+# Notification priority levels
+
+Pick the lowest priority that still preserves the user-visible
+behavior the message needs. **Default to `normal`.**
+
+| Priority | Quiet-hours | Use for |
+|---|---|---|
+| `critical` | Bypasses | Security alerts (credential leak, account lockout), data-loss risk (about to overwrite without backup, irreversible deletion in flight), system errors blocking the user from working. Wakes the user. |
+| `high` | Bypasses | Hard deadlines firing in the next 8 hours, urgent inbound messages from people the user has flagged as priority, "meeting starting now". User wants to see this even during quiet hours but not at 3 am. |
+| `normal` | Respects (dropped during quiet hours) | Regular reminders (`15 min until standup`), digest-style summaries, single-recipient FYIs the user opted into. **Default.** |
+| `low` | Respects (dropped during quiet hours) | Background updates, observational FYIs the user did not explicitly ask for, optional context. Often better as an Agent Log entry instead of a notification at all. |
+
+## Examples by level
+
+### `critical` — "3 am matters"
+
+- `AWS console session was used from an IP not on your allowlist 5 min ago — review and rotate keys if not you.`
+- `Backup job failed on the database for 3 consecutive runs — primary now 6 hours out of sync.`
+
+If the user would not want the message to wake them, it is not `critical`.
+
+### `high` — "8 hours delay matters"
+
+- `Design review at 14:00 was just moved up to 11:00 — you have a conflicting meeting.`
+- `Submission deadline for the grant is 5 pm today — draft still has 3 unresolved comments.`
+- `Inbound DM from Sarah (priority contact): "Can you call before noon?"`
+
+If the next morning would still be soon enough, it is not `high`.
+
+### `normal` — the default
+
+- `Standup starts in 15 minutes.`
+- `Daily digest: 3 emails from boss, 1 asks for Q2 plan by EOD.`
+- `Reminder you set yesterday for "call vet": now.`
+
+### `low` — opt-in informational
+
+- `Calendar found a 30-min slot at 16:00 today if you want to schedule the writeup.`
+- `Build #4291 on develop turned green (you asked to be notified).`
+
+If the user did not opt in to receiving this category of update, do not
+send `low`. Drop it to an Agent Log entry instead.
+
+## Rate-limit defaults
+
+3/hour, 12/day across all priorities (`critical` bypasses both caps).
+The agent CANNOT query `notification_log` directly (Approve-tier). Use
+`<today>` `## Agent Log` as the authoritative dedup source (look for
+`notify sent` / `DM sent` lines).
+
+A 429 response is final for this attempt — do NOT retry. Log `notify
+skipped (rate_limited)` to Agent Log. If the message is time-critical
+and the next opportunity arises, upgrade to `high` (or `critical` if
+the situation has escalated) rather than re-sending at the same level.

package/agent-assets/skills/notion/SKILL.delegated.claude.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Claude Code; `delegatedBackend` is non-Claude). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+description: Load when the task touches Notion AND Notion is cross-backend delegated from a Claude DM session (`delegatedBackend` is non-Claude). All Notion operations flow through `POST /api/integrations/notion/exec`. `GET /api/notion/databases` remains available for label resolution.
 allowed-tools:
   - Bash(curl *)
   - Read

package/agent-assets/skills/notion/SKILL.delegated.codex.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Codex CLI; `delegatedBackend` is non-Codex). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+description: Load when the task touches Notion AND Notion is cross-backend delegated from a Codex CLI DM session (`delegatedBackend` is non-Codex). All Notion operations flow through `POST /api/integrations/notion/exec`. `GET /api/notion/databases` remains available for label resolution.
 ---
 
 # Notion (delegated, cross-backend)

package/agent-assets/skills/notion/SKILL.delegated.gemini.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in cross-backend delegated mode (DM session is Gemini CLI; `delegatedBackend` is non-Gemini). All Notion operations flow through `POST /api/integrations/notion/exec`; `/api/notion/*` write/read endpoints are not active in this configuration. The label-resolution endpoint `GET /api/notion/databases` remains available.
+description: Load when the task touches Notion AND Notion is cross-backend delegated from a Gemini CLI DM session (`delegatedBackend` is non-Gemini). All Notion operations flow through `POST /api/integrations/notion/exec`. `GET /api/notion/databases` remains available for label resolution.
 ---
 
 # Notion (delegated, cross-backend)

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

@@ -3,17 +3,12 @@ name: notion
 description: Load when the user mentions Notion or the agent needs to read, query, search, create, update, or archive Notion pages and databases. Mail is in `mail`; Calendar / external Obsidian / GitHub in `external-services`; scheduling in `schedule`.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 
 # Notion API Reference
 
-Output language: follow `<output_language_policy>`. **Property names**
-defined in the user's Notion database are Policy A (the API contract —
-never translate them; pass them through verbatim). **Property values**
-and page body content the agent fills are Policy C (write in
-`<settings primary_language>`).
+Output language: Notion property **names** are Policy A — never translate them; pass them through verbatim as the database defines them. Property **values** and page body content are Policy C (`<settings primary_language>`). See `<output_language_policy>`.
 
 Base URL: `http://localhost:8321`. All calls via `curl -s` with
 `Content-Type: application/json` on POST/PATCH/PUT. URL-encode spaces in paths.
@@ -85,8 +80,9 @@ Moves to trash (~30 days). Restore via `PATCH` with `{ "in_trash": false }`.
 
 - During `routine.hourly_check` this skill is **read-only** — no creates,
   property updates, content patches, or archives.
-- No bulk operations without user confirmation.
+- No bulk operations without user confirmation. If you're about to update
+  3+ pages at once, stop and ask the user first.
 - Writes are Autonomous; the daemon does not DM the owner. Single ops
-  only — the agent's own judgment is the gate, not the daemon. If you're
-  about to update 3+ pages at once, stop and ask the user. Call
-  `POST /api/notify` when the user would want immediate awareness.
+  only — the agent's own judgment is the gate, not the daemon. The
+  message-discipline contract for any `POST /api/notify` call you issue
+  here is in the `notify` skill — do not invent ad-hoc phrasing rules.

package/agent-assets/skills/notion/SKILL.native.claude.md

@@ -1,9 +1,8 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in native mode bound to Claude (`nativeBackend === "claude"`). Use the in-session Notion connector your harness exposes directly; the daemon does not proxy Notion. `/api/notion/databases` (label → UUID config dump) is the only daemon route still reachable.
+description: Load when the task touches Notion AND Notion is in native mode bound to Claude (`nativeBackend === "claude"`). Use the in-session Notion connector directly; the daemon does not proxy Notion. `/api/notion/databases` (label → UUID dump) is the only daemon route still reachable.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

package/agent-assets/skills/notion/SKILL.native.codex.md

@@ -1,9 +1,8 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in native mode bound to Codex (`nativeBackend === "codex"`). Use the in-session Notion connector your Codex harness exposes directly; the daemon does not proxy Notion. `/api/notion/databases` (label → UUID config dump) is the only daemon route still reachable.
+description: Load when the task touches Notion AND Notion is in native mode bound to Codex (`nativeBackend === "codex"`). Use the Codex Notion connector directly; daemon does not proxy Notion. `/api/notion/databases` (label → UUID dump) is the only daemon route still reachable.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

package/agent-assets/skills/notion/SKILL.native.gemini.md

@@ -1,9 +1,8 @@
 ---
 name: notion
-description: Load when the task touches Notion and Notion is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use the in-session Notion connector your Gemini harness exposes directly; the daemon does not proxy Notion. `/api/notion/databases` (label → UUID config dump) is the only daemon route still reachable.
+description: Load when the task touches Notion AND Notion is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use the Gemini Notion connector directly; daemon does not proxy Notion. `/api/notion/databases` (label → UUID dump) is the only daemon route still reachable.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 

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

@@ -8,12 +8,7 @@ allowed-tools:
 
 # Observations Review & Source Access
 
-Output language: follow `<output_language_policy>`. This skill routes
-observations into other Policy B destinations (`today.md`, `roadmap.md`,
-`projects/*.md`) — write-ups inherit the destination file's policy
-(English skeleton, body in `<settings primary_language>`) via the
-`today` / `roadmap` / `context` / `project-doc` skills you call to land
-the update.
+Output language: write-ups inherit the destination file's policy via the `today` / `roadmap` / `context` / `project-doc` skills you call. See `<output_language_policy>`.
 
 ## Workflow
 

package/agent-assets/skills/project-doc/SKILL.md

@@ -8,11 +8,7 @@ allowed-tools:
 
 # Project Doc
 
-Output language: follow `<output_language_policy>`. Project docs are
-Policy B — H2/H3 headers from `agent-assets/templates/projects/` and
-`agent-assets/templates/git/` are skeleton (English); body prose,
-bullets, and summaries are written in `<settings primary_language>`.
-Preserve user-customized headers verbatim.
+Output language: project docs are Policy B — see `<output_language_policy>`. Template H2/H3 headers stay English skeleton; body prose, bullets, and summaries are in `<settings primary_language>`. Preserve user-customized headers verbatim.
 
 Use this skill for Git-backed context documents under the unified
 repositories layout (see

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

@@ -185,8 +185,8 @@ Currently reading: 3
 New highlights: 34
 
 ### Completed This Month
-1. "Deep Work" by Cal Newport — ★★★★★
-2. "Atomic Habits" by James Clear — ★★★★
+1. "Deep Work" by Cal Newport — rating: 5/5
+2. "Atomic Habits" by James Clear — rating: 4/5
 
 ### Currently Reading
 - "Thinking, Fast and Slow" by Daniel Kahneman (47 highlights)

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

@@ -8,12 +8,7 @@ allowed-tools:
 
 # roadmap.md Guide
 
-Output language: follow `<output_language_policy>`. roadmap.md is
-Policy B — the section headers (`## Annual Goals`, `## Quarterly Focus`,
-`## Long-term Plans`, `## Agent Action Plan`, `## Recurring`) are
-skeleton and stay English; items, narrative, and preparation-timeline
-prose underneath are written in `<settings primary_language>`. Preserve
-user-customized headers verbatim.
+Output language: roadmap.md is Policy B — see `<output_language_policy>`. Section headers stay English skeleton; items, narrative, and preparation-timeline prose are in `<settings primary_language>`. Preserve user-customized headers verbatim.
 
 `roadmap.md` is the single source of truth for **long-horizon user
 intent** — everything that does not belong in `today.md`. It aggregates
@@ -86,7 +81,7 @@ Destination: <resolved location or "unknown — pending check">
 ```
 ### Scheduled: <description>  (task #<id>)  <!-- id: rm-YYYYMMDD-abcdef -->
 Source: scheduled.task — wake-up YYYY-MM-DD HH:MM
-Status: ⏳ pending | ▶ running | ✓ completed | ✗ failed
+Status: pending | running | completed | failed
 
 **Preparation Timeline:** (optional — only when the agent judges prep is useful)
 - ...
@@ -157,153 +152,60 @@ must carry a daemon-minted HTML comment ID:
 
 ## travel_bookings cross-check
 
-Before generating a new entry or a `[check]` line for accommodation or
-flights:
+Before generating a new event entry or a `[check]` prep line for
+accommodation or flights, match against the user's actual booked
+travel via `GET /api/travel-bookings/upcoming`. Match rules,
+flip-to-completed grammar, and the no-match fallback are in the
+cross-check reference below.
 
-```
-curl -s 'http://localhost:8321/api/travel-bookings/upcoming?limit=50'
-```
-
-If a matching booking exists, mark the corresponding prep line with the
-completed-row grammar above and include the confirmation number in
-Agent Notes.
+{{> ref:cross-check }}
 
 ## Long-horizon DM-intent detection
 
-Referenced from `message.received.dm` and `message.received.dm_first`.
-Identify user messages that describe a commitment or plan beyond the
-current day so the DM handler can route them into roadmap.
-
-**Signals (positive):**
-- Explicit forward-looking verb + horizon phrase:
-  *"going to X next month"*, *"planning to do Y this summer"*,
-  *"want to Z this quarter"*
-- Specific future date ≥ 48h out
-- Concrete object (destination, deliverable, learning target,
-  reservation)
-
-**Not signals:**
-- Speculative language (*"maybe"*, *"someday"*, *"might"*, *"perhaps"*,
-  *"thinking about"*) without a concrete anchor
-- Current-week commitments (those belong in `today.md`)
-- Opinions, preferences, taste statements
-  (those belong in `user/*.md` via the `user-profile` skill)
-
-**Routing after detection:**
-- Dated ≥ 48h out → Agent Action Plan event entry (Preparation
-  Timeline grows once destination / details resolve).
-- Undated horizon ("this summer", "this quarter") →
-  `## Long-term Plans` line with a horizon-tag.
-- Ambiguous → keep in `agent-journal.md` as a candidate line and
-  surface via the next morning routine for user confirmation
-  (dry-run mode).
+DM-driven long-horizon writes are dispatched from
+`message.received.dm.md` / `message.received.dm_first.md` Step 4 via
+the `_partials/dm-intent.long-horizon.md` task-flow partial — that
+partial carries the signal/non-signal enumeration and the
+post-detection routing rules (Agent Action Plan vs Long-term Plans vs
+agent-journal candidate line).
+
+**This skill is the writer.** Entry-shape recipes, stable identity,
+preparation timeline taxonomy, destination extraction, retention, and
+the cross-request write lock all live below — the partial dispatches,
+this skill executes the writes.
 
 ## Section auto-ensure PATCH recipe
 
-Legacy roadmaps created before the `## Long-term Plans` section was
-introduced may be missing it. Before the first PATCH to that section:
+Legacy roadmaps may be missing `## Long-term Plans`. The PATCH-driven
+recovery recipe — GET-inspect, insert after `## Quarterly Focus`,
+then PATCH the target section — is in the migration reference below.
 
-1. `curl -s http://localhost:8321/api/context/roadmap` and inspect the
-   body for `## Long-term Plans`.
-2. If absent, insert it after `## Quarterly Focus`:
-   ```bash
-   curl -s -X PATCH http://localhost:8321/api/context/roadmap \
-     -H 'Content-Type: application/json' \
-     -d '{"section": "quarterly_focus", "mode": "append", "content": "\n## Long-term Plans\n"}'
-   ```
-3. Then PATCH `long_term_plans` normally.
+Full-file PUT writers (e.g. `routine.roadmap_refresh`) do not need
+this recipe — they always emit the full section schema.
 
-Full-file PUT writers (e.g. `routine.roadmap_refresh`) do not need this
-recipe — they always emit the full section schema.
+{{> ref:migration }}
 
 ## Retention (RFC-D preview)
 
 - **Agent Action Plan event entries** — kept while the event's header
-  date is within `[today - 7d, today + 180d]`. Older ✓'d entries roll
-  off into `daily/` history.
+  date is within `[today - 7d, today + 180d]`. Older entries whose
+  Preparation Timeline rows are all `completed` roll off into `daily/`
+  history.
 - **`Scheduled:` entries** — kept while the Wake-up date is within
-  `[today - 1d, today + 180d]`. On completion, Status flips to ✓ and
-  the entry persists one extra day for the journal.
+  `[today - 1d, today + 180d]`. On completion, Status flips to
+  `completed` and the entry persists one extra day for the journal.
 - **Long-term Plans** — entries without date movement for 90 days are
   marked `[stale]` by Evening Review. 180 days without user
   confirmation → DM; no reply in 7 days → remove.
 
-## Cross-request write lock
-
-Roadmap writes serialize via an optional exclusive lock so a
-mid-session refresh is not interleaved with a DM handler PATCH.
-
-**Lock endpoint paths — get the order right:**
-
-| Operation | Method | Path |
-|---|---|---|
-| Acquire | `POST` | `/api/context/lock/roadmap` |
-| Release | `DELETE` | `/api/context/lock/roadmap` |
-
-**Common mistakes (NOT registered):**
-
-- `POST /api/context/roadmap/lock` — order reversed
-- `POST /api/context/roadmap/write-lock` — order reversed and wrong noun
-- `POST /api/context/lock/roadmap-write` — wrong noun
-
-Any of these return `404 {"error":"unknown_route", ...}` with a hint
-pointing at the correct path — re-read the table above and resend. The
-correct lock endpoints are Autonomous-tier, so no bearer token is
-required; if you see `401 {"error":"unauthorized"}` from a path you
-believe is correct, the path is still wrong.
-
-- If `<roadmap_write_lock_id>` is in your context, include
-  `X-Lock-Id: <roadmap_write_lock_id>` on every PUT / PATCH to
-  `/api/context/roadmap`.
-- Dispatcher auto-acquires the lock for `routine.roadmap_refresh`.
-- Flows that need to write roadmap outside that routine (DM handler,
-  evening sweeper) can acquire via
-  `POST /api/context/lock/roadmap` and release via
-  `DELETE /api/context/lock/roadmap` with `{ "lockId": "..." }`.
-- If another session holds the lock, PUT / PATCH returns **409
-  `roadmap_write_lock_held`** — back off 30 s and retry up to 3 times.
-
-## roadmap.md API
-
-Body submission follows `_safety.md` "Daemon-API body submission":
-small POST / PATCH bodies use inline `-d '{...}'`; the full-file PUT
-runs multi-KB and uses the stdin heredoc `-d @- <<'JSON'` shape.
-Include `X-Lock-Id: <roadmap_write_lock_id>` on every PUT / PATCH
-when that tag is in your context.
-
-```bash
-# Read
-curl -s http://localhost:8321/api/context/roadmap
-
-# Mint a new stable entry id
-curl -s -X POST http://localhost:8321/api/context/roadmap/id \
-  -H 'Content-Type: application/json' \
-  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
-  -d '{"creationDate":"YYYY-MM-DD"}'
-
-# Full replace (roadmap refresh) — multi-KB body, use heredoc.
-curl -s -X PUT http://localhost:8321/api/context/roadmap \
-  -H 'Content-Type: application/json' \
-  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
-  -d @- <<'JSON'
-{"content":"# Roadmap\n> Last synced: 2026-04-23\n\n## Annual Goals\n- ...\n\n## Quarterly Focus\n- ...\n\n## Long-term Plans\n- [2026-Q3] ...  <!-- id: rm-20260419-b8e7d4 -->\n\n## Agent Action Plan\n\n## Recurring\n- Every Friday: weekly review\n"}
-JSON
-
-# Section PATCH
-curl -s -X PATCH http://localhost:8321/api/context/roadmap \
-  -H 'Content-Type: application/json' \
-  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
-  -d '{"section":"long_term_plans","mode":"append","content":"- [2026-Q3] ...\n"}'
-```
+## API surface
+
+Generic GET / PUT / PATCH / DELETE lives in the **context** skill's
+`references/api.md`. The roadmap-specific layer — lock endpoints
+(with the path-name gotchas), ID mint, the duplicate-id retry recipe,
+and the transition guard — is in the reference below.
 
-Snapshotting, mtime updates, and path validation are handled by the
-context API — see the `context` skill for the full endpoint reference.
-For roadmap writes, the API also validates ID uniqueness and runs a
-transition guard: if an entry ID survives from previous → next content,
-every previous `✓ completed ...` row for that ID must still exist
-byte-for-byte. If an entry ID disappears entirely, removal is accepted
-only when the retention window permits it or the operator bypass header
-is used.
+{{> ref:api }}
 
 ## Roadmap section schema (auto-curated)
 

package/agent-assets/skills/roadmap/references/api.md

@@ -0,0 +1,100 @@
+---
+kind: reference
+name: api
+description: roadmap.md-specific layering on top of /api/context/* — lock endpoints, ID-mint, transition guard, duplicate-id retry recipe.
+---
+
+# roadmap.md API — specific rules
+
+The generic GET / PUT / PATCH surface lives in the **context** skill's
+`references/api.md`. The rules below are the roadmap-specific layer.
+
+## Lock — `roadmap_write_lock_id`
+
+| Action | Verb | Path |
+|---|---|---|
+| Acquire | `POST` | `/api/context/lock/roadmap` |
+| Release | `DELETE` | `/api/context/lock/roadmap` (body `{"lockId":"…"}`) |
+
+The dispatcher auto-acquires this lock for `routine.roadmap_refresh`
+and exposes the id via `<roadmap_write_lock_id>` in the prompt
+context. Other flows (DM handler, evening sweeper) may acquire and
+release manually.
+
+Include `X-Lock-Id: <roadmap_write_lock_id>` on every PUT / PATCH to
+`/api/context/roadmap` when the tag is in your context. Other
+sessions get `409 roadmap_write_lock_held` while the lock is held —
+back off 30 s and retry up to 3 times.
+
+### Path-name gotchas
+
+These return `404 {"error":"unknown_route", …}` with a hint pointing
+at the correct path:
+
+- `POST /api/context/roadmap/lock` — order reversed
+- `POST /api/context/roadmap/write-lock` — order reversed and wrong noun
+- `POST /api/context/lock/roadmap-write` — wrong noun
+
+A `401 {"error":"unauthorized"}` from a path you believe is correct
+means the path is still wrong (the lock endpoints are Autonomous-tier
+so no bearer token is required).
+
+## ID mint — `POST /api/context/roadmap/id`
+
+```bash
+curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"creationDate":"YYYY-MM-DD"}'
+```
+
+Returns `{"id":"rm-YYYYMMDD-<6hex>"}`. Use the returned value as the
+`<!-- id: ... -->` HTML comment on a new entry. Never invent the
+6-hex suffix in prose.
+
+When promoting a Long-term Plans line into Agent Action Plan, transfer
+the existing id to the new `###` heading and remove the original line
+— do NOT mint a fresh id (the journal trail would break).
+
+## ID uniqueness + transition guard
+
+The roadmap API validates two invariants on every PUT / PATCH:
+
+1. **Uniqueness.** Every `<!-- id: rm-* -->` is unique within the
+   file. Duplicate ids return:
+
+   ```json
+   {"error":"validation_error","message":"duplicate roadmap id rm-YYYYMMDD-abcdef","path":"roadmap.md"}
+   ```
+
+   Recovery: re-GET `roadmap`, mint a fresh id **for the colliding
+   new entry only**, retry the PUT / PATCH once. If the same error
+   fires twice, abort and surface the message to the user — something
+   in the pipeline is double-emitting.
+
+2. **Transition guard.** If an entry id survives from previous → next
+   content, every prior `completed …` row for that id must still
+   exist byte-for-byte. Removing or rewording a historical completed
+   row returns:
+
+   ```json
+   {"error":"validation_error","message":"transition_guard: completed row for rm-… changed","path":"roadmap.md"}
+   ```
+
+   This is intentional: completed prep rows are the audit trail for
+   what the agent actually did. Edit only forward-looking rows.
+
+If an entry id disappears entirely between previous → next, removal
+is accepted only when:
+
+- The entry's retention window has elapsed (see §"Retention" in the
+  skill body), OR
+- The operator passes the `X-Operator-Bypass: 1` header (dashboard
+  flows only; never set this from an agent curl).
+
+## Body submission
+
+- Full PUT body is multi-KB → use the heredoc shape
+  (`-d @- <<'JSON'`) per `_safety.md` "Daemon-API body submission".
+- Section PATCH bodies are small → inline `-d '{...}'`.
+- ID-mint POST is small → inline `-d '{"creationDate":"…"}'`.

package/agent-assets/skills/roadmap/references/cross-check.md

@@ -0,0 +1,73 @@
+---
+kind: reference
+name: cross-check
+description: Travel-bookings cross-check — match new roadmap event entries against /api/travel-bookings/upcoming before minting a [check] prep line.
+---
+
+# Travel-bookings cross-check
+
+Before generating a new event entry — or a `[check] <date>: Confirm
+…` line in an existing entry's Preparation Timeline — for
+**accommodation** or **flights**, look up the user's actual booked
+travel. If a matching booking already exists, the prep line is
+redundant; mark it `completed` and surface the confirmation number in
+Agent Notes instead.
+
+## Query
+
+```bash
+curl -s 'http://localhost:8321/api/travel-bookings/upcoming?limit=50'
+```
+
+Response shape (one row per booking):
+
+```json
+{
+  "bookings": [
+    {
+      "kind": "flight" | "hotel" | "rail" | "other",
+      "depart_at": "ISO8601 with tz",
+      "return_at": "ISO8601 with tz | null",
+      "destination": "city / airport / property name",
+      "confirmation_number": "<string>",
+      "source": "gmail" | "manual" | "ical"
+    }
+  ]
+}
+```
+
+## Match rules
+
+A booking matches a roadmap event entry when **either**:
+
+- The booking's `destination` substring-matches the event entry's
+  `Destination:` field (case-insensitive, after stripping common
+  prefixes / suffixes — "Paris" matches "Paris, FR" and "Paris CDG").
+- The booking's `depart_at` date falls within the event entry's
+  `YYYY-MM-DD ~ MM-DD` header range (inclusive on both ends).
+
+When a match is found:
+
+1. Locate the matching `[check]` row in the event entry's Preparation
+   Timeline.
+2. Flip it to the completed-row grammar (`completed: <prep>
+   <YYYY-MM-DD> confirmation #<conf>`), preserving the original
+   `[tag]` and date.
+3. Append a line to the entry's `**Agent Notes:**` block:
+   `- Booking confirmed (<kind>) — #<confirmation_number>`.
+
+## When no match exists
+
+The `[check] <event_date - 28d>: Confirm <…> for <title>` line stays
+in the Preparation Timeline. The morning routine will surface it as
+an Agent Plan row when its date is within `today + 7d`.
+
+## When NOT to run this cross-check
+
+- Inside the morning routine when it is rebuilding `## Agent Action
+  Plan` from scratch — the routine already has the bookings table
+  loaded in its pre-pass and runs the match itself.
+- For non-travel entries (work projects, deadlines, study sessions).
+  Travel-bookings is a travel-specific source of truth.
+- When `/api/travel-bookings/upcoming` returns an empty list — skip
+  the match step entirely.

package/agent-assets/skills/roadmap/references/migration.md

@@ -0,0 +1,56 @@
+---
+kind: reference
+name: migration
+description: Section auto-ensure recipe for legacy roadmaps missing ## Long-term Plans. PATCH-driven; full-file PUT writers (refresh routine) do not need this.
+---
+
+# Section auto-ensure — legacy `roadmap.md` files
+
+Roadmaps created before the `## Long-term Plans` section was
+introduced may be missing that header. A direct
+`PATCH section=long_term_plans` against such a file returns
+`400 section_not_found`. This reference is the one-time recovery
+recipe DM handlers and the evening sweeper run before their first
+write to `long_term_plans`.
+
+## When to run
+
+Run this **only** if you are about to PATCH `long_term_plans` and the
+file's body is unknown to you. Full-file PUT writers
+(`routine.roadmap_refresh`) always emit the full section schema, so
+they never trigger `section_not_found` and never need this recipe.
+
+## Steps
+
+```bash
+# 1. Read the file
+curl -s http://localhost:8321/api/context/roadmap
+
+# 2. Inspect the body for "## Long-term Plans". If present, skip the
+#    insert and go straight to the normal PATCH below.
+
+# 3. Absent → insert it after "## Quarterly Focus":
+curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"section": "quarterly_focus", "mode": "append", "content": "\n## Long-term Plans\n"}'
+
+# 4. Then PATCH long_term_plans normally
+curl -s -X PATCH http://localhost:8321/api/context/roadmap \
+  -H 'Content-Type: application/json' \
+  -H 'X-Lock-Id: <roadmap_write_lock_id>' \
+  -d '{"section": "long_term_plans", "mode": "append", "content": "- [undated] …"}'
+```
+
+## Don'ts
+
+- Do NOT insert `## Long-term Plans` blindly without GET-ing first;
+  appending it twice produces a malformed file (the PATCH route does
+  not deduplicate H2 headers).
+- Do NOT use this recipe to insert `## Agent Action Plan` or other
+  agent-writable sections. The roadmap refresh routine owns the
+  per-section schema; section-by-section insertion from DM is not
+  supported.
+- Do NOT skip the `X-Lock-Id` header when the
+  `<roadmap_write_lock_id>` tag is in your context — PATCH without it
+  returns `409 roadmap_write_lock_held` during a held-lock window.