@aitne-sh/aitne 0.1.8 → 0.1.10

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
@@ -31,9 +31,9 @@ user but compound into duplicate DMs/notifications at fire time.
    PATCH the existing item if it needs updating — never register a
    parallel second one).
 3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
-   confirm no recurring rule already covers this cadence (e.g. a daily
-   09:00 inbox triage). If covered, skip — the recurring instance will
-   regenerate on its own.
+   confirm no recurring rule/Agent already covers this cadence (e.g. a
+   daily 09:00 inbox triage, or the morning briefing). If covered, skip.
+   (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
@@ -54,11 +54,10 @@ If the request expresses an **ongoing management practice** with a
 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
-`rules/policies/<slug>.md` that captures the WHY alongside the cadence
-(via `routines/custom/<slug>.md`) so the rule survives a context
-reset. Plain recurring schedules via `/api/recurring-schedules` are
-still right when the cadence is all that matters and there is no need
-to record intent.
+`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, create the recurring work/DM per the "Recurring" section below.
 
 ## DM vs Agent Task
 
@@ -71,11 +70,11 @@ to record intent.
 
 **Default to DM** when possible. Every agent wake-up costs money and context.
 
-## Writing a Good Description (for agent tasks)
+## Writing a Good Prompt (for agent tasks)
 
-> **The wake-up agent has NO memory of why it was scheduled.** It receives only: `today.md`, a fresh 1-day calendar, `user/profile.md` + `rules/management.md`, and the `description` + `taskContext` fields you provide. Nothing else.
+> **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:
+Include all four elements in the `prompt`:
 
 | Element | What it answers |
 |---|---|
@@ -89,26 +88,14 @@ Include all four elements:
 **Bad:** `"Meeting prep"` — which meeting? when? what to prepare?
 
 ## Using `taskContext`
-Structured metadata for IDs, URLs, and correlation. Put long identifiers here so `description` stays under ~2 sentences:
+Structured metadata for IDs, URLs, and correlation. Put long identifiers here so the `prompt` stays focused:
 ```json
 { "scheduledBy": "morning_routine", "prUrl": "https://github.com/user/repo/pull/42" }
 ```
 
-**`importance` convention.** This controls whether `agent_schedule`
-rows become `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
 
@@ -149,16 +136,16 @@ Response: `{ "status":"scheduled", "scheduleId":"123", "scheduledFor":"..." }`.
 ```bash
 curl -s -X POST http://localhost:8321/api/schedule \
   -H 'Content-Type: application/json' \
-  -d '{"time":"2026-04-06T16:00:00-04:00","taskType":"wake","description":"Hourly docker health check: run `docker ps --format` and DM if any container is in restart loop.","tier":"lite","taskContext":{"scheduledBy":"docker_monitor"}}'
+  -d '{"time":"2026-04-06T16:00:00-04:00","taskType":"wake","prompt":"Hourly docker health check: run `docker ps --format` and DM if any container is in restart loop.","description":"Docker health check","tier":"lite","taskContext":{"scheduledBy":"docker_monitor"}}'
 ```
 | Field | Required | Description |
 |---|---|---|
 | `time` | Yes | ISO 8601 with timezone offset |
-| `taskType` | Yes | `wake` for scheduled tasks |
-| `description` | Yes | Self-contained (min 20 chars). See format above. Doubles as the agent body unless `prompt` overrides it. |
-| `prompt` | No | Optional override for the agent body (min 20 chars when set). When set, the dispatcher injects this — not `description` — into the task-flow template. Use when you want a short list-friendly `description` plus a longer, separate instruction for the agent. |
+| `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`. |
-| `model` | No | Registered model id (`claude-opus-4-7`, `gpt-5.4`, …), legacy alias (`sonnet` / `opus`, auto-rewritten to `tier`), or composite `<backendId>/<modelId>`. See "Tier / Model selection" above. Mutually exclusive with `tier`. |
+| `model` | No | Registered model id (`claude-opus-4-8`, `gpt-5.4`, …), legacy alias (`sonnet` / `opus`, auto-rewritten to `tier`), or composite `<backendId>/<modelId>`. See "Tier / Model selection" above. Mutually exclusive with `tier`. |
 | `taskContext` | No | Structured metadata object |
 
 Response: `{ "status":"scheduled", "scheduleId":"123", "scheduledFor":"YYYY-MM-DD HH:MM:SS" }`. `scheduledFor` is the normalized UTC SQLite timestamp the daemon actually stored — log this verbatim instead of re-formatting the input `time`. Rejects times in the past (> 1 min ago), same as `/api/schedule/dm`.
@@ -169,17 +156,17 @@ curl -s -X PATCH http://localhost:8321/api/schedule/42 \
   -H 'Content-Type: application/json' \
   -d '{"time":"2026-04-06T17:00:00-04:00"}'
 ```
-Fields: `time` (ISO 8601), `description` (min 20 chars, non-dm only), `prompt` (min 20 chars OR `null` to clear; non-dm only), `message` (dm only), `tier` (`lite`/`medium`/`high` OR `null` to clear), `model` (registered id / alias / composite OR `null` to clear), `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive. Tier ↔ model swap form is in the model-selection reference above. Response: `{ "status":"updated", "id":42, "warnings":[] }` / 404 / 409 — surface `warnings[]` (e.g. `schedule.model_deprecated`) to the next turn.
+Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-dm only, OR `null` to clear on a legacy row), `description` (optional label ≤200 chars, non-dm only), `message` (dm only), `tier` (`lite`/`medium`/`high` OR `null` to clear), `model` (registered id / alias / composite OR `null` to clear), `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive. Tier ↔ model swap form is in the model-selection reference above. Response: `{ "status":"updated", "id":42, "warnings":[] }` / 404 / 409 — surface `warnings[]` (e.g. `schedule.model_deprecated`) to the next turn.
 
 ### GET /api/schedule — List scheduled items
 ```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
@@ -210,24 +197,28 @@ model, batch) are in the errors reference below.
 
 ---
 
-## Recurring Schedules
+## Recurring: work → Agent; DM → dm_session
+
+`/schedule` registers **one-shot** wake-ups and DMs. For repeating tasks:
 
-For tasks that repeat on a fixed pattern. The daemon auto-regenerates
-the next one-shot occurrence after each execution. **Hourly / daily /
-weekly / monthly** cadences are supported; the recurring reference
-below documents the full shape, the hourly + monthly missing-day
-recipes, pause-vs-delete trade-off, and PATCH / GET / DELETE surface.
+- **Recurring autonomous work** (daily inbox triage, weekly review, hourly
+  health check) is a **recurring Agent** — a durable, named identity with
+  metrics on `/agents`. Create it with the **`agent-create` skill**
+  (`POST /api/agents`). Creating a recurring `agent.task` row directly on
+  `POST /api/recurring-schedules` is **410 Gone** — use an Agent.
+- **Recurring scheduled DM / briefing** ("DM me a summary every morning")
+  stays on `POST /api/recurring-schedules` with `taskType: "dm_session"`
+  (its fire time can track quiet-hours; PATCH/DELETE edit it). The morning
+  briefing is one of these.
 
-{{> ref:recurring }}
+`GET /api/recurring-schedules` stays read-only for the dedup pre-check.
 
-### recurrenceRule grammar — engine vs consumer
+### recurrenceRule grammar — the shared recurrence engine
 
-The full engine grammar (mapping table, frequency-vs-field matrix,
-cadence-string-must-match-recurrenceRule discipline) is shared with
-the `managed-tasks` skill. The reference is byte-identical across
-both skills — pinned by `skills-manifest.test.ts` so they cannot
-drift. Schedule callers may use any of the four frequencies the
-engine accepts; the `managed-tasks` consumer chooses to refuse
-sub-daily for app-fetch correctness and that constraint lives there.
+The recurrence engine grammar (mapping table, frequency-vs-field matrix,
+cadence-string discipline) is shared with the `managed-tasks` skill and
+the `dm_session` recurring rule above. The reference is byte-identical
+across both skills —
+pinned by `skills-manifest.test.ts` so they cannot drift.
 
 {{> ref:recurrence-rule }}

package/agent-assets/skills/schedule/references/batch.md

@@ -31,7 +31,7 @@ curl -s -X POST http://localhost:8321/api/schedule/batch \
         "taskContext": {
           "background": "User flagged Q2 roadmap risks in yesterdays DM; standup needs the two open items front-loaded so the team aligns before 15:30.",
           "expected_output": "DM with two bullet items + one suggested mitigation each, sent 30min before standup.",
-          "references": ["projects/q2-roadmap.md#open-risks", "calendar:event:standup-2026-05-15"],
+          "references": ["plans/projects/q2-roadmap.md#open-risks", "calendar:event:standup-2026-05-15"],
           "tone": "concise"
         }
       }
@@ -57,7 +57,7 @@ curl -s -X POST http://localhost:8321/api/schedule/batch \
 | `rows[].taskContext.sub_flow` | No | Branches the task-flow rendering when the dispatcher needs a specialised sub-flow. |
 | `rows[].taskPrompt` | No | Override for the agent body (min 20 chars when set). |
 | `rows[].correlationId` | No | Defaults to the morning routine's correlation id when omitted. |
-| `rows[].model` | No | Registered model id (`claude-opus-4-7`, `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), composite `<backendId>/<modelId>`, or `null`. Mutually exclusive with `rows[].tier`. Omit both to let `process_backend_config` decide. |
+| `rows[].model` | No | Registered model id (`claude-opus-4-8`, `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), composite `<backendId>/<modelId>`, or `null`. Mutually exclusive with `rows[].tier`. Omit both to let `process_backend_config` decide. |
 | `atomic` | No | `true` (default) wraps inserts in one transaction — any row error rolls back all. `false` commits successful rows individually. |
 
 ## Success

package/agent-assets/skills/schedule/references/errors.md

@@ -133,9 +133,12 @@ Apply to `POST /api/schedule` and `POST /api/schedule/batch`.
 
 | Code | When | Fix |
 |---|---|---|
-| <a id="task_type_unknown"></a> `schedule.task_type_unknown` | `taskType` is not `wake` / `dm_session` / `check` / `dm`. | Pick the matching type. Use `/api/schedule/dm` for the precomposed-DM variant. |
-| <a id="description_too_short"></a> `schedule.description_too_short` | `description` / `taskDescription` < 20 chars. | Expand the description so the wake-up agent has enough context to act. |
-| <a id="prompt_too_short"></a> `schedule.prompt_too_short` | `prompt` / `taskPrompt` is set but < 20 chars. | Either remove it (description doubles as the body) or expand it. |
+| <a id="task_type_unknown"></a> `schedule.task_type_unknown` | **Batch only** (`/api/schedule/batch` rows): `taskType` is not one of the closed set `wake` / `dm_session` / `check` / `dm`. On the single `POST /api/schedule`, `taskType` is a free-form provenance label (no allowlist) — this code fires there only when `taskType` is missing or not a string. | Batch: pick one of the four. Single endpoint: send any non-empty string (`wake` is the convention for agent wake-ups). Use `/api/schedule/dm` for the precomposed-DM variant. |
+| <a id="prompt_required"></a> `schedule.prompt_required` | `POST /api/schedule` (or a PATCH that sets it) with `prompt` missing or empty. | `prompt` is the wake-up agent's only instruction — write the full instruction there. `description` is just the optional list label, no longer the agent body. |
+| <a id="prompt_too_long"></a> `schedule.prompt_too_long` | `prompt` / `taskPrompt` > 8000 chars. | Tighten the instruction (goal + key context + expected output); move bulk reference material into a file the agent reads at fire time instead of inlining it. |
+| <a id="description_too_long"></a> `schedule.description_too_long` | `description` > 200 chars. | The description is the short list label — keep it under 200 chars and put the full instruction in `prompt`. |
+| <a id="description_too_short"></a> `schedule.description_too_short` | `taskDescription` (batch) / recurring `description` < 20 chars. | Expand the body so the wake-up agent has enough context to act. (Does not apply to the single `/api/schedule` row, where `description` is an optional label.) |
+| <a id="prompt_too_short"></a> `schedule.prompt_too_short` | Batch `taskPrompt` / recurring `prompt` is set but < 20 chars. | Either remove it (the description body is used) or expand it. (The single `/api/schedule` row requires `prompt`; see `schedule.prompt_required`.) |
 
 ### taskContext required fields
 
@@ -161,7 +164,7 @@ here.
 
 `model` accepts a free-form token after SCHEDULE_API_REDESIGN_PLAN
 §4.3: legacy aliases (`sonnet` / `opus` — rewritten to `tier` at
-the route), full registered model ids (e.g. `claude-opus-4-7`,
+the route), full registered model ids (e.g. `claude-opus-4-8`,
 `gpt-5.4`), or the composite `<backendId>/<modelId>` form when an
 id appears under multiple backends. `tier` (`lite` | `medium` |
 `high`) is the abstract cost knob and is mutually exclusive with

package/agent-assets/skills/schedule/references/importance.md

@@ -0,0 +1,23 @@
+---
+kind: reference
+name: importance
+description: The `importance` tier convention for `agent_schedule` rows — which tiers surface in `plans/roadmap.md` `Scheduled:` entries, defaults per endpoint, and when to use `strategic`.
+---
+
+# `importance` convention
+
+This controls whether `agent_schedule` rows become `plans/roadmap.md`
+`Scheduled:` entries:
+
+| 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"`.

package/agent-assets/skills/schedule/references/model-selection.md

@@ -25,7 +25,7 @@ even after `/settings/models` re-routes the process key). The two are
   route to `tier:"medium"` / `tier:"high"`; the alias is not stored
   verbatim.
 - **Registered model ids** — any id from `MODEL_REGISTRY` across the
-  four backends. Examples: `claude-opus-4-7`, `claude-sonnet-4-6`,
+  four backends. Examples: `claude-opus-4-8`, `claude-sonnet-4-6`,
   `claude-haiku-4-5-20251001`, `gpt-5.4`, `gemini-3.1-pro-preview`.
   The row persists `(model, backend_id)` together so the dispatcher
   honors the pin at fire time.
@@ -33,7 +33,7 @@ even after `/settings/models` re-routes the process key). The two are
   registry that has the same model id under multiple backends (today
   unreachable but accepted). The prefix MUST be one of `claude` /
   `codex` / `gemini` / `opencode`; opencode model ids like
-  `anthropic/claude-opus-4-7` are NOT composites and fall through to
+  `anthropic/claude-opus-4-8` are NOT composites and fall through to
   the cross-backend scan.
 
 Unknown / ambiguous / deprecated model tokens surface through the
@@ -76,7 +76,7 @@ Response shape:
   "tiers": ["lite", "medium", "high"],
   "modelAliases": { "sonnet": "medium", "opus": "high" },
   "models": {
-    "claude":   [{ "id": "claude-opus-4-7", "tier": "high", "deprecated": false }, ...],
+    "claude":   [{ "id": "claude-opus-4-8", "tier": "high", "deprecated": false }, ...],
     "codex":    [...],
     "gemini":   [...],
     "opencode": [...]

package/agent-assets/skills/schedule/references/recurrence-rule.md

@@ -8,10 +8,12 @@ description: recurrenceRule grammar — hourly / daily / weekly / monthly. Engin
 
 The daemon's recurrence engine accepts four frequencies: `hourly`,
 `daily`, `weekly`, `monthly`. Each frequency requires its own set of
-fields and rejects fields that don't apply — the daemon's Zod
-refinements return a `schedule.frequency_field_mismatch` issue (with
-the offending field path) when the shape disagrees with the chosen
-frequency. Pre-validate to save a round-trip.
+fields and rejects fields that don't apply — the daemon rejects a
+mismatched shape with an HTTP 400 validation error naming the
+frequency/field conflict. The recurring-schedules endpoint (the
+`schedule` skill) surfaces it as a `schedule.frequency_field_mismatch`
+issue with a field path; the managed-tasks endpoint surfaces it as a
+`managed_tasks.validation_error`. Pre-validate to save a round-trip.
 
 Times are `HH:MM` 24-hour local; `timezone` is IANA (auto-fills from
 daemon config when omitted, but explicit is safer so a roaming laptop
@@ -76,7 +78,7 @@ Same template applies to "every 5 minutes", "every 30 minutes",
 ## Cadence string vs structured rule
 
 Always send both `cadence` (human-readable, rendered in
-`rules/management.md` §B) and `recurrenceRule` (structured, what the
+`policies/management.md` §B) and `recurrenceRule` (structured, what the
 scheduler executes). They must agree — if they drift, the rendered
 file misleads the user about what the scheduler will actually do.
 

package/agent-assets/skills/scheduled-managed-task/SKILL.md

@@ -175,39 +175,52 @@ runs. The (`section`, `mode`, `content`, `cutoff`, `maxEntries`)
 shape is the contract today — see `contextPatchSchema` in
 `packages/shared/src/schemas.ts`.
 
-**Source-id capture (write the `external_id` into the body lines):**
-the entity-mirror watcher (P5) reparses the file's frontmatter on
-change, so the dedup contract in §7.6 hinges on the upstream id
-landing in **frontmatter**, not just the body. Until the entity-mirror
-reconciler ships AND the context API gains a `frontmatter*` patch
-mode for `<domain>/<type-plural>/*` files, do this:
-
-1. Always include `- external_id: <id>` on its own line in the
-   appended `## <App> Notes` body so a future reconciler-rebuild can
-   recover the binding from prose.
-2. Track the binding in the §B "Recently changed" path — the
-   `agent_actions.management_task.run_recorded` row's `detail` is
-   structured and survives even when the file body doesn't reflect
-   the binding cleanly.
-
-> **Implementation gap to flag** (Phase 5 / extended Phase 3): the
-> context PATCH route does not currently:
->   - allow writes under `<domain>/<type-plural>/*` (no entry in
->     `CONTEXT_WRITE_PERMISSIONS`), so this PATCH returns `403
->     forbidden` until the whitelist is widened, and
->   - expose a `frontmatterMerge` mode for deep-merging
->     `frontmatter.sources.<app>`.
-> Both are required by design 21 §10.4 step 4b and must land before
-> this Step 5a goes from "designed" to "operational". Until then,
-> Step 5b's audit row is the durable trace of the run — surface that
-> in the activity-view rather than relying on the entity body.
-
-If the entity file does not previously exist, today's API requires a
-PUT with full content (the `<domain>/<type-plural>/*` write path is
-gated by the same whitelist note above). When the gap closes, the
-first PATCH must include a complete frontmatter block — `type`,
-`domain`, `slug`, `title`, `created`, `sources` — or the daemon
-returns 422 against `EntitySchema`.
+**Source-id capture — deep-merge into frontmatter (`mode:"frontmatterMerge"`):**
+the §7.6 dedup contract hinges on the upstream id landing in **frontmatter**
+(`sources.<app>.external_id`) — the canonical signal the entity-mirror watcher
+reparses and `GET /api/entities?source=…&external_id=…` queries — not just the
+body. The context PATCH route exposes `mode:"frontmatterMerge"` for exactly this
+(design 21 §10.4 step 4b): it deep-merges a partial frontmatter object into the
+file's existing YAML (nested objects merge key-by-key; scalars/arrays replace),
+so a new `<app>` source is linked without clobbering other apps' ids, other
+frontmatter keys, or the body:
+
+```bash
+curl -sS -X PATCH "http://localhost:8321/api/context/work/meetings/2026-12-04-foo-1on1" \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{
+  "mode": "frontmatterMerge",
+  "frontmatter": {
+    "sources": { "zoom": { "external_id": "zm_xyz789" } },
+    "last_synced_at": "2026-12-04T09:00:00Z"
+  }
+}
+JSON
+```
+
+`frontmatterMerge` requires a non-empty `frontmatter` object and takes no
+`section` (it never touches the body). Append the human-readable
+`## <App> Notes` section in a separate `mode:"append"` / `"append_to_file"`
+PATCH. Also keep Step 5b's audit row as the durable structured trace of the run.
+
+> **Write path:** the bare `<domain>/<type-plural>/<slug>` path is alias-rewritten
+> to `knowledge/entities/<domain>/<type-plural>/<slug>` by `context-vault-aliases.ts`,
+> which **is** whitelisted in `CONTEXT_WRITE_PERMISSIONS` for `PUT`/`PATCH`
+> (autonomous tier), so both the frontmatterMerge and the body-append PATCH
+> succeed on an existing entity file. (Recognised domains: `work`, `travel`,
+> `finance`, `personal`, `health`, `learning`.)
+
+If the entity file does not previously exist, PATCH returns
+`404 context.path_not_found` — today's API requires a PUT with full
+content to create it first (the `<domain>/<type-plural>/*` write path
+is whitelisted for both PUT and PATCH; only the file-existence rule
+forces the PUT-first ordering). There is **no API-side entity
+validation**: the creating PUT succeeds even with incomplete
+frontmatter, but always write a complete block — `type`, `domain`,
+`slug`, `title`, `created`, `sources` — because the entity-mirror
+watcher parses loosely and silently skips rows it can't read, leaving
+the §7.6 dedup lookup blind.
 
 ### Step 5b — Update the row
 
@@ -259,19 +272,16 @@ an em-dash; the user can also set the path explicitly via the
 
 ### Step 6 — Three-strikes notify
 
-The design (§10.4 step 6) places the 3-strikes notify on the daemon
-side: the `/run-result` route should auto-enqueue a `POST /api/notify`
-when the post-update `consecutive_failures` crosses the threshold,
-keeping the agent out of the user-paging loop and centralizing the
-threshold (`managementFailureNotifyThreshold`, default 3).
+The daemon emits **no** 3-strikes notify: `updateManagedTaskRunResult`
+is a bare UPDATE and the `/run-result` route only records the run and
+re-renders — it never calls `sendNotification`. (The similarly-named
+`failureNotifyThreshold` param is metrics-only — a dashboard
+"failing_now" gauge — not a daemon-side notify mechanism.)
 
-**Implementation status:** the daemon does NOT currently emit this
-notify — `/api/managed-tasks/:id/run-result` records the run and
-re-renders the file but stops there. Until the daemon closes the
-gap, **this skill is the safety net**: after Step 5b's failure-path
-PATCH, if the post-update `consecutive_failures` you computed is ≥ 3
-AND was < 3 before this run (i.e. the *crossing*, not every
-subsequent failure), call:
+**This skill is the sole notifier** — the safety net for failing
+managed tasks. After Step 5b's failure-path PATCH, if the post-update
+`consecutive_failures` you computed is ≥ 3 AND was < 3 before this run
+(i.e. the *crossing*, not every subsequent failure), call:
 
 ```bash
 curl -sS -X POST http://localhost:8321/api/notify \
@@ -296,19 +306,18 @@ agent keeps trying, but doesn't disappear silently.
 `scheduled.task` flow's "Output contract — your final text becomes a
 DM" applies (`scheduled.task.md`). For managed-task runs the default
 is **empty final text**: bookkeeping is invisible by design. The user
-sees the change reflected in `_activity/<source>.md` (auto-built) and
+sees the change reflected in `state/activity/<source>.md` (auto-built) and
 `<domain>/_index.md`, not in a chat ping per fire.
 
-Exceptions:
+Exceptions (final text stays empty in all cases — these only govern
+whether a `/api/notify` fires):
 
 - The `notify` skill's awareness gate fired *during* this run — e.g.
   the new datum is a meeting starting in 15 min. Then call
-  `/api/notify` and keep the final text empty (a follow-up "Sent"
-  line is duplicate noise per `scheduled.task.md`).
-- `last_result='failed: ...'` with `consecutive_failures < 3` — final
-  text empty; the activity view records it; the user is not paged.
-- `last_result='failed: ...'` at the threshold crossing — Step 6 fired
-  the `/api/notify`; final text empty.
+  `/api/notify` (a follow-up "Sent" line is duplicate noise per
+  `scheduled.task.md`).
+- A failure: notify only on the Step 6 threshold crossing; below it,
+  the activity view records the failure and the user is not paged.
 
 NEVER write a `## Agent Plan` row for a managed-task run — managed
 tasks are not the same as Agent Plan rows. The Agent Plan loop close
@@ -322,13 +331,15 @@ A scheduled fire that crashes mid-run leaves the row's
 `last_run_at` un-updated. The next slot picks up the same `since`
 window and re-fetches the same data — the entity-mirror's
 `(source_key, external_id)` lookup makes this a **merge**, not a
-duplicate. The PATCH body is content-additive: a section appended
-twice with the same content is harmless because Step 5a's
-`frontmatterMerge` is deep, and the section-append mode is
-"add this block as-is" (the daemon de-duplicates exact-string-match
-sections with the same heading on append). For sources without a
-stable `external_id`, use Step 4.2's date+title window — at the cost
-of occasional dedup misses, never duplicates by construction.
+duplicate at the file level, and Step 5a's `frontmatterMerge` is deep,
+so re-writing the same frontmatter is idempotent. **Body
+section-appends are NOT de-duplicated** — `mode:"append"` concatenates
+unconditionally, so re-appending the same block on a replay WILL
+duplicate it. Guard against that: on a re-run, `GET` the section first
+and skip any block already present (or carry the structured fields in
+frontmatter, which merges). For sources without a stable `external_id`,
+use Step 4.2's date+title window — at the cost of occasional dedup
+misses, never duplicates by construction.
 
 ## Caps
 
@@ -342,20 +353,16 @@ appended `## <App> Notes` body, not as a separate DM.
 
 | HTTP | `error` | What to do |
 |---|---|---|
-| 400 (`/api/managed-tasks/:id/run-result`) | `invalid_id` / `validation_error` | Body shape drift — re-check field names exactly match `last_run_at` / `last_result` / `consecutive_failures` |
-| 403 (`/api/context/<domain>/<type-plural>/...`) | `forbidden` | Entity-domain write paths are not yet whitelisted (Phase 5 gap, §Step 5a). Skip the entity merge for this run, still record run-result, and surface a one-line warning in `last_result`. |
+| 400 (`/api/managed-tasks/:id` or `:id/run-result`) | `invalid_id` / `validation_error` | All managed-task body validation is 400 (never 422). Re-check field names exactly match `last_run_at` / `last_result` / `consecutive_failures`; for the user-facing PATCH, drop the offending field (typically `output_path`) and retry once with the rest |
+| 404 (`/api/context/<domain>/<type-plural>/...`) | `context.path_not_found` | The entity file does not exist yet — PATCH cannot create it. Create it first with a PUT carrying full content + complete frontmatter (§Step 5a), then the merge succeeds. (Entity-domain write paths ARE whitelisted for PUT/PATCH; the prior 403 claim is obsolete.) |
 | 404 (`/api/managed-tasks/:id`) | `not_found` | Row was stopped mid-run. End the session quietly. |
-| 422 (`/api/context/...`) | `validation_error` | Frontmatter incomplete or malformed; populate all required fields and retry once |
-| 422 (`/api/managed-tasks/:id`) | `validation_error` | Path / body shape rejected; drop the offending field (typically `output_path`) and retry once with the rest |
 | 5xx | `internal_error` | Record `last_result='failed: <body.message>'` via Step 5b's failure form and end the session |
 
 ## What this skill does NOT do
 
-- Does NOT post `/api/notify` for routine successes (silent by design).
-- Does NOT post `/api/notify` for routine failures (final text empty).
-  The exception is the 3-strikes crossing — see Step 6: until the
-  daemon owns the threshold notify, the agent emits one DM at the
-  3rd consecutive failure, then stays silent until success or stop.
+- Does NOT post `/api/notify` for routine successes or failures
+  (silent by design). The sole exception is the 3-strikes crossing —
+  see Step 6.
 - Does NOT touch the §B row's `app` or `cadence` — those are
   user-mutable only via the `managed-tasks` skill `## Modify` flow.
 - Does NOT INSERT `agent_schedule` rows. The cron scheduler does.
@@ -379,7 +386,7 @@ appended `## <App> Notes` body, not as a separate DM.
 | `GET /api/entities?source=` | Step 4 bias hint (list-by-source-key) |
 | `GET /api/entities?domain=&type=&date=&q=` | Step 4.2 (tier-2 fuzzy) |
 | `GET /api/entities/by-path?path=` | Step 4 (verify before merging) |
-| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (gated by entity-domain write whitelist — Phase 5 gap) |
+| `PATCH /api/context/<domain>/<type-plural>/<slug>` | Step 5a (whitelisted PUT/PATCH; PATCH requires the file to exist — PUT-create first if 404) |
 | `PATCH /api/managed-tasks/:id/run-result` | Step 5b (internal — last_run_at / last_result / consecutive_failures) |
 | `PATCH /api/managed-tasks/:id` | Step 5b output-path back-fill only |
 | `POST /api/notify` | Step 6 (only on the 3-failures-in-a-row crossing edge) |