@aitne-sh/aitne 0.1.9 → 0.1.11

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 activity scan or morning routine review.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -56,30 +56,17 @@ The daemon pre-summarizes every observation with a per-source LLM call (lite tie
 | `summaryStale === true` | Treat as if `summary_status !== 'done'` — fall back to legacy fetch-on-doubt | Summary aged out (>6h since observed_at); content may have drifted under it |
 | `summary_status !== 'done'` (pending/skipped/failed/null) | Fall back to legacy fetch-on-doubt below | Summarizer disabled, lagging, or crashed |
 
-**Hard rule:** never fetch raw content when `novelty_score < 2`, unless a different observation in the same batch references the same path/ref OR `summaryStale === true`. This is the primary lever for hourly_check cost reduction.
+**Hard rule:** never fetch raw content when `novelty_score < 2`, unless a different observation in the same batch references the same path/ref OR `summaryStale === true`. This is the primary lever for activity_scan cost reduction.
 
 ### 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 }}
 
 ---
 
 ## Observation Review Logging
 
-Hourly check and Morning Routine review pending observations in aggregate. Even when nothing is surfaced, the review must remain auditable.
+Activity scan and Morning Routine review pending observations in aggregate. Even when nothing is surfaced, the review must remain auditable.
 
 ### observations → Agent Log
 
@@ -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.
 
@@ -113,7 +100,7 @@ Response: `{ "observations": [{ "id", "source", "ref", "changeType", "actor", "o
 
 Record an agent-queued observation (only `actor: "agent"` or `"system"`
 accepted — user-authored observations arrive through the vault / mail
-watchers, never this route). Used by `routine.hourly_check` to queue
+watchers, never this route). Used by `routine.activity_scan` to queue
 `roadmap_candidate` signals the next `routine.roadmap_refresh` consumes.
 
 ```bash
@@ -146,7 +133,7 @@ cardinality mismatch without weakening either hook.
 > `too-complex` gate and cascade to a denied curl / wasted retry /
 > `budget-cap`. The tool input is the same `{"observations":[…]}` envelope
 > and the response is identical. The curl form below is the fallback for
-> sessions without the MCP tool (the hourly check, Codex/Gemini).
+> sessions without the MCP tool (the activity scan, Codex/Gemini).
 
 ```bash
 curl -s -X POST http://localhost:8321/api/observations/batch \
@@ -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,10 +88,24 @@ 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 operator passes the `X-Operator-Bypass: 1` header (dashboard
-  flows only; never set this from an agent curl).
+- The entry's retention window has elapsed (see the **retention**
+  reference loaded by the skill body), OR
+- The operator passes the `X-Roadmap-Validation: off` 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.
+
+`X-Roadmap-Validation: off` is roadmap-scoped — it only takes effect
+when `path = plans/roadmap` — and it disables **all** roadmap content
+validation: the transition guard, the duplicate-id check, **and** the
+retention window. It is not a retention-only escape hatch.
 
 ## Body submission
 

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.

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

@@ -1,6 +1,6 @@
 ---
 name: schedule
-description: Load when scheduling a future agent wake-up, pre-composed DM, recurring task, or de-duping against existing pending schedules.
+description: Schedule future agent wake-ups, pre-composed DMs, or recurring tasks via /api/schedule. Use when registering a timed follow-up, a one-off reminder, or de-duping against pending schedules.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -33,8 +33,7 @@ user but compound into duplicate DMs/notifications at fire time.
 3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
    confirm no recurring rule/Agent already covers this cadence (e.g. a
    daily 09:00 inbox triage, or the morning briefing). If covered, skip.
-   (Recurring *work* is created as an Agent via the `agent-create` skill;
-   recurring *DMs* via `POST /api/recurring-schedules` `taskType:dm_session`.)
+   (How recurring work/DMs are created — see "Recurring" below.)
 4. **`confirm_dedup_key` check (mandatory for `confirm:` sub-flow rows
    only).** When scheduling a `dm_session` row with
    `taskContext.sub_flow="confirm"`, run the dedup pre-check + shape
@@ -56,13 +55,9 @@ recorded reason — "every morning, run my finance app and log the
 balance to a finance dossier", "from now on whenever X happens, do
 Y" — switch to the `management-policy` skill instead. It creates a
 `policies/management-captures/<slug>.md` that captures the WHY alongside the cadence
-(via `policies/routines/custom/<slug>.md`) so the rule survives a context
-reset. When the cadence is all that matters and there is no intent to
-record: recurring autonomous **work** → create a **recurring Agent** via
-the `agent-create` skill (`POST /api/agents`); recurring scheduled
-**DM / briefing** → `POST /api/recurring-schedules` with
-`taskType: "dm_session"`. (Creating a recurring `agent.task` row directly
-on `/api/recurring-schedules` is **410 Gone** — use an Agent.)
+(scheduled via a linked recurring Agent, `POST /api/agents`) so the rule
+survives a context reset. When the cadence is all that matters and there is no intent to
+record, create the recurring work/DM per the "Recurring" section below.
 
 ## DM vs Agent Task
 
@@ -77,7 +72,7 @@ on `/api/recurring-schedules` is **410 Gone** — use an Agent.)
 
 ## Writing a Good Prompt (for agent tasks)
 
-> **The wake-up agent has NO memory of why it was scheduled.** It receives only: `state/today.md`, a fresh 1-day calendar, `identity/profile.md` + `policies/management.md`, and the `prompt` + `taskContext` fields you provide. Nothing else. (`description` is just an optional list label — never the agent body.)
+> **The wake-up agent has NO memory of why it was scheduled.** A `scheduled.task` session is self-contained: it receives only `state/today.md` (which carries the day's schedule and state) plus the `prompt` + `taskContext` you provide — **NOT** `identity/profile.md` or `policies/management.md` (the `scheduled.task` injection policy opts those out). Nothing else. (`description` is just an optional list label — never the agent body.)
 
 Include all four elements in the `prompt`:
 
@@ -98,21 +93,9 @@ Structured metadata for IDs, URLs, and correlation. Put long identifiers here so
 { "scheduledBy": "morning_routine", "prUrl": "https://github.com/user/repo/pull/42" }
 ```
 
-**`importance` convention.** This controls whether `agent_schedule`
-rows become `plans/roadmap.md` `Scheduled:` entries:
+**`importance`** controls whether a row becomes a `plans/roadmap.md` `Scheduled:` entry. Default `transient` for `/api/schedule/dm`, `normal` for `/api/schedule`; use `strategic` only for roadmap-shaped long-prep reminders. Tier table + defaults in the reference below.
 
-| Tier | Roadmap behavior | Use |
-|---|---|---|
-| `transient` | Never in roadmap; surfaces in today.md only on the day it fires | Default for `/api/schedule/dm`; short pings like "call mom next Tuesday" |
-| `normal` | In roadmap only when scheduled more than 7 days out | Default for `/api/schedule`; ordinary user-facing follow-ups |
-| `strategic` | In roadmap regardless of horizon | Long-prep commitments such as ESTA / travel / deadline reminders |
-| `low` | Never in roadmap | Internal ticks already visible elsewhere, e.g. Agent Plan rows, recurring-schedule instances, morning retries |
-
-For direct DMs, omit `importance` for ordinary one-off pings. If the
-reminder is clearly tied to a long-prep commitment ("remind me in a
-month about ESTA for the LA trip"), either write/promote the roadmap
-item via the roadmap skill and let AAP schedule the reminder, or call
-`/api/schedule/dm` with `"importance":"strategic"`.
+{{> ref:importance }}
 
 ## Tier / Model selection
 
@@ -129,6 +112,15 @@ Pick `tier` (`lite` / `medium` / `high`) by default — backend-neutral cost kno
 - **Max 5 wake-ups per execution.** Consolidate into a single briefing task if more.
 - **Morning Routine batches all day's wake-ups at once.** Other events schedule only immediate needs.
 
+## Lock-step on PATCH / DELETE
+
+Agent Plan rows and schedule entries move together in both directions.
+When a schedule you PATCH or DELETE backs an `## Agent Plan` row in
+<today>, update that row in the same turn — today skill §"Agent Plan
+revision — cancel / amend" (flip + `(cancelled: <reason>)`, or re-time
+the row) — and append the Agent Log line. A schedule edit without the
+row edit leaves a plan that lies.
+
 ---
 
 ## API Reference
@@ -158,7 +150,7 @@ curl -s -X POST http://localhost:8321/api/schedule \
 | Field | Required | Description |
 |---|---|---|
 | `time` | Yes | ISO 8601 with timezone offset |
-| `taskType` | Yes | Free-form provenance label for the row (no allowlist on the single endpoint). Use `wake` for an agent wake-up — the convention this skill follows. The closed set `wake`/`dm_session`/`check`/`dm` is enforced only on `/api/schedule/batch`; e.g. the dashboard's manual "+ New task" sends `custom`. The label does not change firing — the scheduler runs every non-`dm`/`dm_session`/`browser_task` row as a generic `scheduled.task`. |
+| `taskType` | Yes | Free-form provenance label; use `wake` for agent wake-ups. The closed set `wake`/`dm_session`/`check`/`dm` is enforced only on `/api/schedule/batch`. The label doesn't change firing — every non-`dm`/`dm_session`/`browser_task` row runs as a generic `scheduled.task`. |
 | `prompt` | Yes | The agent's instruction at fire time — its ONLY context (the session has no memory). Self-contained: what + why + who + expected output. See format above. Max 8000 chars (~2000 tokens); move bulk reference material into a file the agent reads at fire time rather than inlining it. |
 | `description` | No | Optional short label shown in the schedule list (max 200 chars). NOT the agent body — that is `prompt`. Omit it and the list shows a `prompt` excerpt. |
 | `tier` | No | `lite` / `medium` / `high`. Omit to use the dispatcher's process-key default (medium for `scheduled.task`). See "Tier / Model selection" above. Mutually exclusive with `model`. |
@@ -179,11 +171,11 @@ Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-d
 ```bash
 curl -s "http://localhost:8321/api/schedule?status=pending"
 ```
-Param `status` (default `pending,running`): comma-separated `pending`, `running`, `completed`, `failed`.
+Param `status` (default `pending,running`): comma-separated `pending`, `running`, `completed`, `failed`, `skipped`. DELETE/cancel does not remove a row — it moves it to `status='skipped'`, so re-listing a cancelled item requires `status=skipped`.
 Param `roadmapEligible=true`: return only rows that may become
 roadmap `Scheduled:` entries (`transient` / `low` excluded, `normal`
 only beyond 7 days, `strategic` included).
-Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","backendId","tier","taskContext","createdAt" }] }`. `prompt` / `tier` / `model` / `backendId` are `null` when no override is set. `model` is a registered id verbatim and travels with `backendId` when set — the row carries either the `(model, backendId)` pin or `tier`, never both. Legacy alias inputs (`sonnet` / `opus`) are normalized to `tier` at write time. `taskContext` is the parsed JSON (or `null`); filter with `jq` e.g. `'.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
+Response: `{ "items":[{ "id","scheduledFor","taskType","description","prompt","status","model","backendId","tier","taskContext","createdAt" }] }`. `prompt` / `tier` / `model` / `backendId` are `null` when no override is set. `model` is a registered id verbatim and travels with `backendId` when set — the row carries either the `(model, backendId)` pin or `tier`, never both. Legacy alias inputs (`sonnet` / `opus`) are normalized to `tier` at write time. `taskContext` is the parsed JSON (always an object — `{}` when unset); filter with `jq` e.g. `'.items[] | select(.taskContext.confirm_dedup_key == "create_project:la-pm-masters")'`.
 
 ### DELETE /api/schedule/:id — Cancel a pending item
 ```bash