@aitne-sh/aitne 0.1.8 → 0.1.10

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

@@ -15,20 +15,23 @@ 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).
 
 ## Hard rules
 
 - Write only through `/api/context/*`. Never edit files directly on disk.
-- Do not modify `today.md`, `roadmap.md`, `user/*`, `rules/*`, or
+- Do not modify `state/today.md`, `plans/roadmap.md`, `user/*`, `rules/*`, or
   unrelated context files.
 - Preserve valid frontmatter. The overview file uses `type: git-project`,
   the journal file uses `type: git-journal`. Both carry an ISO `updated`
@@ -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 projects/*.md and git-repos/*.md, and what each section holds",
-      "scope_paths": ["projects/*.md", "git-repos/*.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-repos/*.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,11 +14,14 @@
       ]
     },
     {
-      "path": "git-repos/*.md",
-      "purpose": "Per-repository context for non-project watched repositories",
+      "path": "knowledge/repos/*/overview.md",
+      "purpose": "Per-repository overview for every git-managed repo (replaces the retired git-repos/*.md layout)",
       "sections": [
-        { "heading": "## Activity", "contains": "summarised recent activity for the watched repo" },
-        { "heading": "## Recent Pushes", "contains": "list of push events with dates and short summaries" }
+        { "heading": "## Summary", "contains": "one-paragraph description of the repo and its current state" },
+        { "heading": "## Architecture", "contains": "structural notes on the repo's layout and components" },
+        { "heading": "## Notable Changes", "contains": "human-readable notes on important commits or decisions" },
+        { "heading": "## Open Threads", "contains": "manual prose; follow-ups and pending questions, preserved verbatim" },
+        { "heading": "## Daily Activity Log", "contains": "rolling 30-day window of summarised activity" }
       ]
     }
   ]

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

@@ -3,18 +3,18 @@
   "notes": [
     {
       "topic": "Slug format",
-      "rule": "Project and repo slugs are kebab-case, lowercase letters with hyphens between words.",
-      "example": "projects/cost-explorer.md, git-repos/personal-agent.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.",
-      "example": "projects/personal-agent-skills.md is at the upper bound"
+      "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"
     },
     {
       "topic": "Reserved stems",
       "rule": "Stems _index and _archive are reserved for daemon-maintained files and not in use as project slugs.",
-      "example": "projects/_index.md is a directory listing, not a project file"
+      "example": "plans/projects/_index.md is a directory listing, not a project file"
     }
   ]
 }

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,28 +115,26 @@ 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
 
 Update book status, rating, or notes.
 
+**Approve tier (Bearer required).** This is an operator/dashboard-gated
+write — an autonomous agent curl from a session workdir carries no
+`Authorization: Bearer` header and will be rejected with **401** before
+the handler runs. Do NOT call this autonomously and do NOT assume the
+update landed; book status/rating/notes corrections are made by the user
+via the dashboard. (Body shape, for reference: `status` enum
+`reading|completed|abandoned`, `rating` 1-5, `notes`.)
+
 ```bash
+# Operator/dashboard-only — requires Authorization: Bearer (Approve tier).
 curl -s -X PATCH "http://localhost:8321/api/books/1" \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <operator-token>" \
   -d '{"status": "completed", "rating": 4}'
 ```
 
@@ -195,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..."}'
 ```
@@ -146,12 +146,12 @@ the sweep to write the refreshed metadata and YAML `updated` date.
 
 ### First-write registration (_index.md)
 
-The `user/_index.md` file indexes available topic files. When
+The `identity/_index.md` file indexes available topic files. When
 creating `reading-taste.md` for the first time (GET returned 404),
 append a one-line entry to the index so other flows can discover it:
 
 ```bash
-curl -s -X PATCH http://localhost:8321/api/context/user/_index \
+curl -s -X PATCH http://localhost:8321/api/context/identity/_index \
   -H 'Content-Type: application/json' \
   -d '{"section": "topics", "mode": "append", "content": "- reading-taste — derived taste profile + rolling book candidates (updated weekly)"}'
 ```

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

@@ -10,11 +10,11 @@ allowed-tools:
 
 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
+`plans/roadmap.md` is the single source of truth for **long-horizon user
+intent** — everything that does not belong in `state/today.md`. It aggregates
 Calendar events, pending `agent_schedule` rows, DM-captured intent,
 mail-derived bookings, reading goals, and observations; Morning Routine
-consumes it to shape `today.md`.
+consumes it to shape `state/today.md`.
 
 ## Section schema
 
@@ -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
 
@@ -117,9 +110,9 @@ must carry a daemon-minted HTML comment ID:
 - The `YYYYMMDD` segment is the entry creation date / Source date, not
   the event date. Keep it stable when dates are refined.
 - Do not invent IDs in prose. Before adding a new roadmap entry, call
-  `POST /api/context/roadmap/id`:
+  `POST /api/context/plans/roadmap/id`:
   ```bash
-  curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+  curl -s -X POST http://localhost:8321/api/context/plans/roadmap/id \
     -H 'Content-Type: application/json' \
     -d '{"creationDate": "YYYY-MM-DD"}'
   ```
@@ -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/curation.json

@@ -7,7 +7,7 @@
       "anchor": "<!-- CURATION:knowledge_layout id=\"entry-types\" -->",
       "human_label": "Roadmap section schema",
       "description": "Required sections in roadmap.md and what each holds",
-      "scope_paths": ["roadmap.md"]
+      "scope_paths": ["plans/roadmap.md"]
     }
   ]
 }

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

@@ -22,7 +22,7 @@ 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
+`/api/context/plans/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.
 
@@ -31,18 +31,18 @@ back off 30 s and retry up to 3 times.
 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/plans/roadmap/lock` — order reversed
+- `POST /api/context/plans/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`
+## ID mint — `POST /api/context/plans/roadmap/id`
 
 ```bash
-curl -s -X POST http://localhost:8321/api/context/roadmap/id \
+curl -s -X POST http://localhost:8321/api/context/plans/roadmap/id \
   -H 'Content-Type: application/json' \
   -H 'X-Lock-Id: <roadmap_write_lock_id>' \
   -d '{"creationDate":"YYYY-MM-DD"}'
@@ -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":"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":"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/cross-check.md

@@ -25,14 +25,21 @@ Response shape (one row per booking):
 {
   "bookings": [
     {
-      "kind": "flight" | "hotel" | "rail" | "other",
-      "depart_at": "ISO8601 with tz",
-      "return_at": "ISO8601 with tz | null",
+      "id": "<int>",
+      "type": "flight" | "hotel" | "restaurant" | "train" | "bus" | "other",
+      "provider": "<string>",
       "destination": "city / airport / property name",
-      "confirmation_number": "<string>",
-      "source": "gmail" | "manual" | "ical"
+      "startDate": "ISO8601 | YYYY-MM-DD | null",
+      "endDate": "ISO8601 | YYYY-MM-DD | null",
+      "confirmationNumber": "<string | null>",
+      "amount": "<number | null>",
+      "currency": "<string | null>",
+      "status": "upcoming",
+      "providerMsgId": "<string | null>",
+      "createdAt": "ISO8601"
     }
-  ]
+  ],
+  "total": "<int>"
 }
 ```
 
@@ -43,7 +50,7 @@ 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
+- The booking's `startDate` date falls within the event entry's
   `YYYY-MM-DD ~ MM-DD` header range (inclusive on both ends).
 
 When a match is found:
@@ -54,7 +61,7 @@ When a match is found:
    <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>`.
+   `- Booking confirmed (<type>) — #<confirmationNumber>`.
 
 ## When no match exists
 

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

@@ -4,18 +4,18 @@ 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
+# 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.
@@ -24,22 +24,24 @@ they never trigger `section_not_found` and never need this recipe.
 
 ```bash
 # 1. Read the file
-curl -s http://localhost:8321/api/context/roadmap
+curl -s http://localhost:8321/api/context/plans/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 \
+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": "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 \
+# 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.

package/agent-assets/skills/roadmap/seeds/entry-types.seed.json

@@ -2,7 +2,7 @@
   "kind": "knowledge_layout",
   "files": [
     {
-      "path": "roadmap.md",
+      "path": "plans/roadmap.md",
       "purpose": "Long-horizon user intent: goals, focus, plans, scheduled tasks, and recurring entries",
       "sections": [
         { "heading": "## Annual Goals", "contains": "user-authored yearly goals preserved verbatim" },