@aitne-sh/aitne 0.1.9 → 0.1.10

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

@@ -14,11 +14,10 @@ Base URL: `http://localhost:8321`. All calls via `curl -s` with
 `Content-Type: application/json` on POST/PATCH/PUT. URL-encode spaces in paths.
 
 Full CRUD over Notion pages plus workspace search. Reads and writes are
-Autonomous; writes are still serialized per-process and pre-marked
-`notion:<pageId>` for write attribution. The daemon does not DM the
-owner before a write — the user's `deniedTools` setting is the gate.
-Call `POST /api/notify` yourself when you judge the user would
-want immediate awareness.
+Autonomous; writes are serialized per-process and pre-marked
+`notion:<pageId>` for attribution. The daemon does not DM the owner before
+a write — the `deniedTools` setting is the gate. Call `POST /api/notify`
+yourself when you judge the user would want immediate awareness.
 
 **Parent shorthand**: `parent` accepts a label string (`"tasks"`),
 `{ database: "tasks" }`, `{ data_source_id }`, `{ database_id }`, or
@@ -34,8 +33,10 @@ curl -s "http://localhost:8321/api/notion/search?q=launch+plan"             # se
 curl -s http://localhost:8321/api/notion/pages/abc123...                    # retrieve page
 ```
 
-Pagination: `page_size` (1–100, default 20) + `start_cursor` from response's
-`next_cursor`. Check `has_more` to know if more pages exist.
+Query also accepts `sorts` (URL-encoded JSON) alongside `filter`, and
+`in_trash=true` to query trashed rows. Pagination: `page_size` (1–100,
+default 20) + `start_cursor` from response's `next_cursor`; check
+`has_more` to know if more pages exist.
 
 ## Create a page (write — Autonomous)
 
@@ -55,12 +56,13 @@ curl -s -X PATCH http://localhost:8321/api/notion/pages/abc123... \
 
 ## Update page content (write — Autonomous)
 
-**Concurrency warning**: Notion v5 has no etags. If another client edits
-between GET and PATCH, `oldStr` may fail silently. For high-risk edits,
-prefer `mode=replace_all`.
+**Concurrency**: Notion v5 has no etags — if another client edits between
+GET and PATCH, `oldStr` may fail silently; for high-risk edits prefer
+`mode=replace_all`.
 
 Modes: `append`, `replace_all`, `update` (find-and-replace via
-`updates: [{oldStr, newStr}]`).
+`updates: [{oldStr, newStr}]`), `replace_range` (in-place swap of a line
+range; requires `content` + `contentRange`, optional `allowDeleting`).
 
 ```bash
 curl -s -X PATCH http://localhost:8321/api/notion/pages/abc123.../content \
@@ -80,9 +82,7 @@ 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. 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. 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.
+- No bulk operations without user confirmation: about to touch 3+ pages,
+  stop and ask first. Single ops only.
+- For any `POST /api/notify` call you issue, the message-discipline
+  contract lives in the `notify` skill — do not invent ad-hoc phrasing.

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

@@ -42,7 +42,7 @@ connector arguments carry concrete UUIDs.
 
 ```bash
 curl -s http://localhost:8321/api/notion/databases
-# → { "databases": { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { "databases": [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 This route is **not** part of the absolute deny set and is intentionally

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

@@ -36,7 +36,7 @@ the `<integration-routing-table>` block in the session preamble.
 
 ```bash
 curl -s http://localhost:8321/api/notion/databases
-# → { "databases": { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { "databases": [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 Resolve label → UUID before any Notion call so the connector arguments

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

@@ -46,7 +46,7 @@ the `<integration-routing-table>` block in the session preamble.
 
 ```bash
 curl -s http://localhost:8321/api/notion/databases
-# → { "databases": { "<label>": { "id": "<uuid>", "title": "..." }, ... } }
+# → { "databases": [ { "label": "<label>", "id": "<uuid>" }, ... ] }
 ```
 
 Resolve label → UUID before any Notion call.

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

@@ -1,6 +1,6 @@
 ---
 name: observations
-description: Load when a session needs to drain the pending-observations queue or inspect raw external-source state (Obsidian edits, new git commits, Notion updates) and optionally mark entries consumed.
+description: Drain the pending-observations queue and inspect raw external-source state (Obsidian edits, new git commits, Notion updates), marking processed entries consumed. Use during hourly check or morning routine review.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -60,20 +60,7 @@ The daemon pre-summarizes every observation with a per-source LLM call (lite tie
 
 ### Legacy fetch-on-doubt (used when `summary_status !== 'done'`)
 
-Before fetching, ask: **"If I fetch this, will my next action actually differ from what I'd do now?"** No → don't fetch. Yes → fetch. Fetching for "verification" wastes tokens; fetching to resolve ambiguity is what these endpoints exist for.
-
-| Situation | Action | Why |
-|---|---|---|
-| Preview contains TODO, deadline, or concrete task reference | **Act on preview** | You have what you need |
-| Preview is truncated on a relevant section | **Fetch full** | Missing load-bearing content |
-| Preview is empty or says `(file read failed)` | **Fetch full** | Preview is broken, not empty |
-| Change type is `deleted` | **Log only — no fetch** | Nothing to read |
-| Journal/diary entry with no task markers visible | **Skip entirely** | Usually no action needed |
-| Active project file with ambiguous preview | **Fetch full** | Active project justifies cost |
-| Clear commit message + small/routine diff | **Act on preview** | Common refactors, renames |
-| Generic commit message ("update","fix","wip") + multi-file | **Fetch full diff** | Vague message requires actual change |
-
-**Availability:** Obsidian → 503 when app not running (fall back to preview); Git → 400 for repos not in `PA_GIT_REPOS`; Notion → empty for unconfigured DBs.
+When the summarizer hasn't run (`summary_status !== 'done'`) or its summary aged out (`summaryStale === true`), fall back to the fetch-on-doubt heuristic table: {{> ref:fetch-fallback }}
 
 ---
 
@@ -105,7 +92,7 @@ Params: `pending` (bool, default true), `actor` (user/agent/system/unknown), `li
 
 The `source` filter is a prefix match: `source=obsidian` returns rows from both the primary management vault (`obsidian:primary`) and the external note vault (`obsidian:external`). Narrow to one side with the namespaced form when the distinction matters — typically `obsidian:primary` refers to the agent's own files and most user-actionable edits come from `obsidian:external`.
 
-Response: `{ "observations": [{ "id", "source", "ref", "changeType", "actor", "observedAt", "payload", "consumedAt?", "consumedBy?", "summaryText?", "noveltyScore?", "summaryStatus?", "summaryAt?", "summaryStale" }], "limit", "offset", "pending" }`
+Response: `{ "observations": [{ "id", "source", "ref", "changeType", "actor", "observedAt", "payload", "consumedAt?", "consumedBy?", "summaryText?", "noveltyScore?", "summaryStatus?", "summaryAt?", "summaryBackend?", "summaryStale" }], "limit", "offset", "pending" }`
 
 `summaryText` / `noveltyScore` are populated asynchronously by the per-observation summarizer (cost-reduction-structural §A). When `summaryStatus !== 'done'` the row may have been skipped (deny-list, agent-actor) or the summarizer hasn't caught up yet — fall back to the legacy fetch-on-doubt rules in that case. `summaryStale === true` flags summaries older than 6 h relative to `observedAt`; treat them the same way as a missing summary.
 
@@ -228,15 +215,13 @@ you to.**
 
 #### Common mistakes — do not retry these, they will keep failing
 
+The live `issues[]` array names any other malformed field; these are the highest-frequency ones.
+
 | Wrong call | Why it fails | Correct shape |
 |---|---|---|
-| `POST /api/observations -d 'limit=30'` | Body is a query string. POST records, GET fetches. | `GET /api/observations?limit=30&pending=true` |
 | `POST /api/observations/14/consume` | Per-id path returns 405 `use_bulk_endpoint`. | `POST /api/observations/consume -d '{"ids":[14],"correlationId":"..."}'` |
-| `GET /api/observations/consume` | Consume is POST-only; GET returns 405. | `POST /api/observations/consume -d '{"ids":[...],"correlationId":"..."}'` |
-| `PATCH /api/observations` | No PATCH route — auth middleware returns 401. | `POST /api/observations/consume` (or `POST /api/observations` for new rows). |
 | `-d '{"ids":[14],"correlation_id":"..."}'` | snake_case. Field must be camelCase. | `-d '{"ids":[14],"correlationId":"..."}'` |
 | `-d '{"ids":["14"],"correlationId":"..."}'` | Stringified ids. Use integers. | `-d '{"ids":[14],"correlationId":"..."}'` |
-| `-d '{"ids":[14],"correlationId":"<event_correlation_id>"}'` | Pasted the angle-bracket placeholder. | Paste the actual id, e.g. `"hourly-2026-04-23T15:00:00Z-7af3"`. |
 
 ### GET /api/observations/stats
 

package/agent-assets/skills/observations/references/fetch-fallback.md

@@ -0,0 +1,22 @@
+---
+kind: reference
+name: fetch-fallback
+description: Legacy fetch-on-doubt rules — used only when summary_status !== 'done' (summarizer disabled/lagging/crashed) or summaryStale === true.
+---
+
+# Legacy fetch-on-doubt (used when `summary_status !== 'done'`)
+
+Before fetching, ask: **"If I fetch this, will my next action actually differ from what I'd do now?"** No → don't fetch. Yes → fetch. Fetching for "verification" wastes tokens; fetching to resolve ambiguity is what these endpoints exist for.
+
+| Situation | Action | Why |
+|---|---|---|
+| Preview contains TODO, deadline, or concrete task reference | **Act on preview** | You have what you need |
+| Preview is truncated on a relevant section | **Fetch full** | Missing load-bearing content |
+| Preview is empty or says `(file read failed)` | **Fetch full** | Preview is broken, not empty |
+| Change type is `deleted` | **Log only — no fetch** | Nothing to read |
+| Journal/diary entry with no task markers visible | **Skip entirely** | Usually no action needed |
+| Active project file with ambiguous preview | **Fetch full** | Active project justifies cost |
+| Clear commit message + small/routine diff | **Act on preview** | Common refactors, renames |
+| Generic commit message ("update","fix","wip") + multi-file | **Fetch full diff** | Vague message requires actual change |
+
+**Availability:** Obsidian → 503 when app not running (fall back to preview); Git → 400 for repos not in `PA_GIT_REPOS`; Notion → empty for unconfigured DBs.

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

@@ -15,13 +15,16 @@ repositories layout (see
 `docs/design/appendices/unified-repositories.md` §4.5):
 
 - **Git-managed repositories** (any classification) write to
-  `git/<slug>/overview.md` plus per-day `git/<slug>/journal/<YYYY-MM-DD>.md`.
+  `knowledge/repos/<slug>/overview.md` plus per-day
+  `journal/repos/<slug>/<YYYY-MM-DD>.md`.
 - **Non-git project pages** (manual projects without a backing repo)
-  still live at `projects/<slug>.md` per the original layout.
+  still live at `plans/projects/<slug>.md` per the original layout.
 
 The pre-cutover paths `projects/<slug>.md` (for git-backed projects)
-and `git-repos/<slug>.md` are **retired** — every git-managed repo
-now lives under `git/<slug>/`. Classification (`project` vs `repo-only`)
+and `git-repos/<slug>.md` are **retired**; the `git/<slug>/` spelling is
+a deprecated alias the daemon still normalizes for one release. Every
+git-managed repo now lives under `knowledge/repos/<slug>/` (overview)
+plus `journal/repos/<slug>/` (daily journal). Classification (`project` vs `repo-only`)
 no longer changes the path; it controls which sections the overview
 carries (project keeps `## Lifecycle Phases`, repo-only stays light).
 
@@ -40,7 +43,7 @@ carries (project keeps `## Lifecycle Phases`, repo-only stays light).
 - Preserve user prose, manual notes, and existing headings. Compress
   old Git history instead of deleting meaningful context.
 
-## Overview file shape (`git/<slug>/overview.md`)
+## Overview file shape (`knowledge/repos/<slug>/overview.md`)
 
 - Frontmatter: `type: git-project`, `repository_id`, `slug`,
   `github_repo` (or null), `local_path`, `classification`, `category`,
@@ -53,7 +56,7 @@ carries (project keeps `## Lifecycle Phases`, repo-only stays light).
 - `## Open Threads` (manual prose; preserved verbatim)
 - `## Daily Activity Log` (rolling 30-day window)
 
-## Journal file shape (`git/<slug>/journal/<YYYY-MM-DD>.md`)
+## Journal file shape (`journal/repos/<slug>/<YYYY-MM-DD>.md`)
 
 - Frontmatter: `type: git-journal`, `repository_id`, `date`,
   `commit_count`, `pr_events`, `workflow_events`.

package/agent-assets/skills/project-doc/curation.json

@@ -6,8 +6,8 @@
       "kind": "knowledge_layout",
       "anchor": "<!-- CURATION:knowledge_layout id=\"project-shape\" -->",
       "human_label": "Project / git-repo file shape",
-      "description": "Required sections in git/<slug>/overview.md (git-managed repos) and projects/*.md (non-git manual projects), and what each section holds",
-      "scope_paths": ["projects/*.md", "git/*/overview.md"]
+      "description": "Required sections in knowledge/repos/<slug>/overview.md (git-managed repos) and plans/projects/*.md (non-git manual projects), and what each section holds",
+      "scope_paths": ["plans/projects/*.md", "knowledge/repos/*/overview.md"]
     },
     {
       "id": "slug-grammar",
@@ -15,7 +15,7 @@
       "anchor": "<!-- CURATION:convention_notes id=\"slug-grammar\" -->",
       "human_label": "Project slug grammar",
       "description": "Slug format, length cap, reserved stems",
-      "scope_paths": ["projects/*.md", "git/*/overview.md"]
+      "scope_paths": ["plans/projects/*.md", "knowledge/repos/*/overview.md"]
     }
   ]
 }

package/agent-assets/skills/project-doc/seeds/project-shape.seed.json

@@ -2,7 +2,7 @@
   "kind": "knowledge_layout",
   "files": [
     {
-      "path": "projects/*.md",
+      "path": "plans/projects/*.md",
       "purpose": "Per-project context document for Git-backed projects",
       "sections": [
         { "heading": "## Overview", "contains": "one-paragraph description of the project and its current state" },
@@ -14,7 +14,7 @@
       ]
     },
     {
-      "path": "git/*/overview.md",
+      "path": "knowledge/repos/*/overview.md",
       "purpose": "Per-repository overview for every git-managed repo (replaces the retired git-repos/*.md layout)",
       "sections": [
         { "heading": "## Summary", "contains": "one-paragraph description of the repo and its current state" },

package/agent-assets/skills/project-doc/seeds/slug-grammar.seed.json

@@ -3,12 +3,12 @@
   "notes": [
     {
       "topic": "Slug format",
-      "rule": "Project and repo slugs are kebab-case, lowercase letters with hyphens between words.",
-      "example": "plans/projects/cost-explorer.md, git/personal-agent/overview.md"
+      "rule": "Project and repo slugs are lowercase; deriveSlug sanitizes to [a-z0-9._-], so digits, dots, underscores, and hyphens all survive (e.g. v1.2.3).",
+      "example": "plans/projects/cost-explorer.md, knowledge/repos/personal-agent/overview.md"
     },
     {
       "topic": "Slug length",
-      "rule": "Slugs are 32 characters or fewer, including the hyphens but excluding the .md suffix.",
+      "rule": "Slugs are 60 characters or fewer (SLUG_MAX), including the hyphens but excluding the .md suffix.",
       "example": "plans/projects/personal-agent-skills.md is at the upper bound"
     },
     {

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

@@ -1,6 +1,6 @@
 ---
 name: reading
-description: Load when the user mentions a book or highlight, weekly/monthly reviews need reading progress, or routines need to refresh the reading-taste profile (`user/reading-taste.md`) and propose new book candidates. Owns the taste-profile schema and recommendation rules.
+description: Load when the user mentions a book or highlight, weekly/monthly reviews need reading progress, or routines need to refresh the reading-taste profile (`identity/reading-taste.md`) and propose new book candidates. Owns the taste-profile schema and recommendation rules.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -12,8 +12,7 @@ allowed-tools:
 
 The daemon stores books and reading highlights imported from Kindle
 (My Clippings.txt and the "Export Notebook" email pipeline) and manual
-entries. Data lives in `books` and `reading_highlights` tables. All
-display text in `reading-taste.md` must be English (project convention).
+entries. Data lives in `books` and `reading_highlights` tables.
 
 ## When to Use
 
@@ -93,30 +92,9 @@ curl -s "http://localhost:8321/api/books?limit=200&offset=200"
 | `limit` | number | 50 | Page size (1–200) |
 | `offset` | number | 0 | Rows to skip. Use with `limit` to paginate beyond the 200 cap |
 
-Response:
-```json
-{
-  "books": [
-    {
-      "id": 1,
-      "title": "Thinking, Fast and Slow",
-      "author": "Daniel Kahneman",
-      "source": "kindle",
-      "status": "reading",
-      "startedAt": null,
-      "completedAt": null,
-      "rating": null,
-      "notes": null,
-      "highlightCount": 47,
-      "createdAt": "2026-04-01T10:00:00Z"
-    }
-  ],
-  "total": 1,
-  "limit": 50,
-  "offset": 0,
-  "hasMore": false
-}
-```
+Response: `{ books: [...], total, limit, offset, hasMore }`. Each
+book carries `id`, `title`, `author`, `source`, `status`, `rating`,
+`highlightCount` (plus `startedAt`/`completedAt`/`notes`/`createdAt`).
 
 When iterating the entire library, keep calling with `offset += limit`
 until `hasMore === false`.
@@ -137,20 +115,8 @@ Reading statistics.
 curl -s "http://localhost:8321/api/books/summary?months=12"
 ```
 
-Response:
-```json
-{
-  "byStatus": [
-    { "status": "reading", "count": 3 },
-    { "status": "completed", "count": 12 }
-  ],
-  "monthlyCompleted": [
-    { "month": "2026-04", "count": 1 },
-    { "month": "2026-03", "count": 2 }
-  ],
-  "totalHighlights": 234
-}
-```
+Response: `{ byStatus: [{status, count}], monthlyCompleted:
+[{month, count}], totalHighlights }`.
 
 ### PATCH /api/books/:id
 
@@ -205,6 +171,6 @@ New highlights: 34
 
 ---
 
-## Reading Taste Profile (`user/reading-taste.md`)
+## Reading Taste Profile (`identity/reading-taste.md`)
 
 {{> ref:reading-taste }}

package/agent-assets/skills/reading/references/reading-taste.md

@@ -6,7 +6,7 @@ parent_skill: reading
 This file captures what the user reads and *why* — topics they return to,
 how they think, values that keep surfacing in their highlights, and a
 rolling list of candidate books. It is dictionary-like (same layer as
-other `user/*.md` files) and is consumed on-demand — never injected
+other `identity/*.md` files) and is consumed on-demand — never injected
 into every session. Do not notify the user about taste updates.
 
 ### When to refresh
@@ -26,7 +26,7 @@ The file carries a dedicated frontmatter line `Highlights at last sweep: N`
 holding the `totalHighlights` value from `GET /api/books/summary` at the
 time of the last successful write. To decide whether to refresh:
 
-1. `GET /api/context/user/reading-taste` — if 404, treat as
+1. `GET /api/context/identity/reading-taste` — if 404, treat as
    `N = 0` and proceed (first sweep).
 2. `GET /api/books/summary` — read `totalHighlights` as `M`.
 3. If `M - N < 10`, skip the sweep (log one bullet under agent-journal
@@ -62,7 +62,7 @@ The refresh-trigger check (previous section) uses `totalHighlights` from
 
 ### Required file schema
 
-First refresh writes the whole file via `PUT /api/context/user/reading-taste`.
+First refresh writes the whole file via `PUT /api/context/identity/reading-taste`.
 Subsequent refreshes use `PATCH` per section (but the metadata lines must
 be updated via a full-file `PUT`). Required structure:
 
@@ -126,7 +126,7 @@ updated: YYYY-MM-DD
 Replace a single section (snake_case the heading):
 
 ```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/reading-taste \
+curl -s -X PATCH http://localhost:8321/api/context/identity/reading-taste \
   -H 'Content-Type: application/json' \
   -d '{"section": "topics_of_interest", "mode": "replace", "content": "- cognitive biases\n- systems design"}'
 ```
@@ -134,7 +134,7 @@ curl -s -X PATCH http://localhost:8321/api/context/user/reading-taste \
 Replace the full file (first time, or after a major reset):
 
 ```bash
-curl -s -X PUT http://localhost:8321/api/context/user/reading-taste \
+curl -s -X PUT http://localhost:8321/api/context/identity/reading-taste \
   -H 'Content-Type: application/json' \
   -d '{"content": "---\ntype: user\nowner: shared\nupdated: 2026-04-21\n---\n# Reading Taste\n> Last updated: 2026-04-16 09:00\n> Sampled: 87 highlights across 8 books (window: last 12 weeks)\n> Highlights at last sweep: 245\n\n## Topics of Interest\n- ...\n..."}'
 ```

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

@@ -93,16 +93,9 @@ Status: pending | running | completed | failed
 - [<horizon-tag>] <intent> — Source: <dm|mail|observation|reading|dashboard|manual> <YYYY-MM-DD> — Review: <YYYY-MM-DD|[noreview]> — ReviewCount: <0-3>  <!-- id: rm-YYYYMMDD-abcdef -->
 ```
 
-Horizon-tag grammar (validated by the context API):
-- `YYYY-MM` → month-granular
-- `YYYY-Qn` → calendar quarter
-- `YYYY spring|summer|autumn|winter`
-- `undated` → no horizon yet
-
-Examples:
+One worked example (full horizon-tag grammar + more examples are in
+the horizon-tags reference):
 - `- [2026-05] LA trip candidate — Source: dm 2026-04-19 — Review: 2026-04-20 — ReviewCount: 0  <!-- id: rm-20260419-a3f1c2 -->`
-- `- [2026-Q3] US study prep — Source: dm 2026-04-19 — Review: 2026-05-17 — ReviewCount: 0  <!-- id: rm-20260419-b8e7d4 -->`
-- `- [undated] Eventually learn Spanish — Source: dm 2026-04-19 — Review: [noreview] — ReviewCount: 3  <!-- id: rm-20260419-0d4c9a -->`
 
 ## Stable entry identity
 
@@ -187,16 +180,7 @@ this recipe — they always emit the full section schema.
 
 ## Retention (RFC-D preview)
 
-- **Agent Action Plan event entries** — kept while the event's header
-  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
-  `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.
+{{> ref:retention }}
 
 ## API surface
 

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

@@ -64,7 +64,7 @@ The roadmap API validates two invariants on every PUT / PATCH:
    file. Duplicate ids return:
 
    ```json
-   {"error":"validation_error","message":"duplicate roadmap id rm-YYYYMMDD-abcdef","path":"plans/roadmap.md"}
+   {"ok":false,"errors":[{"code":"context.content_validation_failed"}],"error":"validation_error","message":"Duplicate roadmap entry id `rm-YYYYMMDD-abcdef` (first seen on line N).","path":"roadmap.md"}
    ```
 
    Recovery: re-GET `roadmap`, mint a fresh id **for the colliding
@@ -74,11 +74,12 @@ The roadmap API validates two invariants on every PUT / PATCH:
 
 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:
+   exist byte-for-byte. If a completed prep row that existed before is
+   gone — dropped or reworded, since a reword no longer matches
+   byte-for-byte — the write returns:
 
    ```json
-   {"error":"validation_error","message":"transition_guard: completed row for rm-… changed","path":"plans/roadmap.md"}
+   {"ok":false,"errors":[{"code":"context.content_validation_failed"}],"error":"validation_error","message":"Completed Preparation Timeline row for entry `rm-…` was dropped.","path":"roadmap.md"}
    ```
 
    This is intentional: completed prep rows are the audit trail for
@@ -87,11 +88,20 @@ The roadmap API validates two invariants on every PUT / PATCH:
 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 entry's retention window has elapsed (see the **retention**
+  reference loaded by the skill body), OR
 - The operator passes the `X-Operator-Bypass: 1` header (dashboard
   flows only; never set this from an agent curl).
 
+A removal before the retention window permits it returns:
+
+```json
+{"ok":false,"errors":[{"code":"context.content_validation_failed"}],"error":"validation_error","message":"Roadmap entry `rm-…` was removed before its retention window permits removal.","path":"roadmap.md"}
+```
+
+Do not blind-retry this — wait out the window or use the operator
+bypass from a dashboard flow.
+
 ## Body submission
 
 - Full PUT body is multi-KB → use the heredoc shape

package/agent-assets/skills/roadmap/references/horizon-tags.md

@@ -3,6 +3,17 @@ kind: reference
 parent_skill: roadmap
 ---
 
+Horizon-tag grammar (validated by the context API):
+- `YYYY-MM` → month-granular
+- `YYYY-Qn` → calendar quarter
+- `YYYY spring|summer|autumn|winter`
+- `undated` → no horizon yet
+
+Worked examples:
+- `- [2026-05] LA trip candidate — Source: dm 2026-04-19 — Review: 2026-04-20 — ReviewCount: 0  <!-- id: rm-20260419-a3f1c2 -->`
+- `- [2026-Q3] US study prep — Source: dm 2026-04-19 — Review: 2026-05-17 — ReviewCount: 0  <!-- id: rm-20260419-b8e7d4 -->`
+- `- [undated] Eventually learn Spanish — Source: dm 2026-04-19 — Review: [noreview] — ReviewCount: 3  <!-- id: rm-20260419-0d4c9a -->`
+
 `Review:` is the date when Evening Review should re-evaluate whether the
 line is ready to become an Agent Action Plan entry. Date math uses the
 configured user timezone, not UTC midnight.

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

@@ -7,15 +7,15 @@ description: Section auto-ensure recipe for legacy roadmaps missing ## Long-term
 # Section auto-ensure — legacy `plans/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
+introduced may be missing that header. A PATCH targeting the
+`Long-term Plans` section 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`.
+write to the `Long-term Plans` section.
 
 ## When to run
 
-Run this **only** if you are about to PATCH `long_term_plans` and the
+Run this **only** if you are about to PATCH the `Long-term Plans` section 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.
@@ -35,11 +35,13 @@ curl -s -X PATCH http://localhost:8321/api/context/plans/roadmap \
   -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
+# 4. Then PATCH the Long-term Plans section normally (note: section value
+#    "long-term plans" normalizes to match the "## Long-term Plans" header;
+#    the underscore form "long_term_plans" does NOT match)
 curl -s -X PATCH http://localhost:8321/api/context/plans/roadmap \
   -H 'Content-Type: application/json' \
   -H 'X-Lock-Id: <roadmap_write_lock_id>' \
-  -d '{"section": "long_term_plans", "mode": "append", "content": "- [undated] …"}'
+  -d '{"section": "long-term plans", "mode": "append", "content": "- [undated] …"}'
 ```
 
 ## Don'ts

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

@@ -0,0 +1,18 @@
+---
+kind: reference
+name: retention
+description: Roadmap retention windows (RFC-D preview) — when Agent Action Plan entries, Scheduled rows, and Long-term Plans roll off. Governs removal acceptance in the transition guard.
+---
+
+# Retention (RFC-D preview)
+
+- **Agent Action Plan event entries** — kept while the event's header
+  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
+  `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.