@aitne-sh/aitne 0.1.7 → 0.1.9

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

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

package/agent-assets/skills/roadmap/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

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

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

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

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

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

package/agent-assets/skills/roadmap/references/preparation-timeline.md

@@ -7,14 +7,14 @@ Action line formats:
 
 ```
 - YYYY-MM-DD [tag]: description
-- ✓ completed YYYY-MM-DD: YYYY-MM-DD [tag]: description
+- completed YYYY-MM-DD: YYYY-MM-DD [tag]: description
 ```
 
 The completed prefix date is the completion date; the second date is
 the original planned date. Preserve completed rows byte-for-byte across
 refreshes. Morning Routine marks an open row complete by rewriting:
 `- YYYY-MM-DD [tag]: foo` →
-`- ✓ completed <today>: YYYY-MM-DD [tag]: foo`.
+`- completed <today>: YYYY-MM-DD [tag]: foo`.
 
 Tags: `[notify]`, `[today]`, `[check]`, `[schedule]`.
 

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" },