@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/skills/context/seeds/file-responsibilities.seed.json

@@ -8,6 +8,7 @@
     { "path": "journal/monthly/*.md", "purpose": "monthly review snapshots (YYYY-MM)", "sections": [{ "heading": "## Theme", "contains": "the month's overall theme" }] },
     { "path": "policies/*.md", "purpose": "user-controlled policy files", "sections": [{ "heading": "## Why", "contains": "rationale for the rule" }, { "heading": "## How", "contains": "concrete rule shape" }] },
     { "path": "identity/*.md", "purpose": "user identity and preferences dictionary", "sections": [{ "heading": "## Identity", "contains": "name role tz" }] },
-    { "path": "journal/agent.md", "purpose": "agent-owned weekly + monthly self-critique", "sections": [{ "heading": "## Weekly", "contains": "what worked, what slipped, improvements" }] }
+    { "path": "journal/agent.md", "purpose": "agent-owned weekly + monthly self-critique", "sections": [{ "heading": "## Weekly", "contains": "what worked, what slipped, improvements" }] },
+    { "path": "knowledge/sources/*/*.md", "purpose": "source-document cards: summaries of user-sent files (PDF/PPTX/docs) stored in the source library; write via the sources skill", "sections": [{ "heading": "# <Title>", "contains": "summary + source_id frontmatter + project link" }] }
   ]
 }

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

@@ -25,15 +25,14 @@ user but compound into duplicate DMs/notifications at fire time.
 1. **Agent Plan check.** Scan `<today>` `## Agent Plan` for a row with
    HH:MM within ±15 min of your target AND an overlapping subject. If
    present, the plan is already in place — do NOT add a second one.
-2. **Pending schedule check.** `GET /api/schedule?status=pending,running`
-   and look for an item whose `scheduledFor` is within ±15 min of your
-   target with a matching `description` subject. If found, skip (or
-   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/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.)
+2. **Pending schedule check.** In a live owner DM pending one-off rows
+   appear in `<scheduled_reminders>` — dedup there and cancel/PATCH any
+   the conversation made moot. Else `GET
+   /api/schedule?status=pending,running` for one within ±15 min with a
+   matching `description`; if found, skip or PATCH.
+3. **Recurring check.** `GET /api/recurring-schedules?enabled=true&includeClaimed=true`
+   — confirm no recurring rule/Agent covers this cadence (a `claimedByAgentSlug`
+   row is Agent-owned and counts). If covered, skip (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
@@ -74,14 +73,16 @@ record, create the recurring work/DM per the "Recurring" section below.
 
 > **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`:
+Author the `prompt` with the **core frame** below. A one-shot task rarely needs the
+extended (operational) sections; if a one-shot *does* mutate code or state, add two
+sections on top of the core frame — `# Scope` (WHERE it may act: the editable
+surface, and what it must not touch) and `# Verification` (which checks confirm the
+change is good, and "don't claim success unless they passed").
 
-| Element | What it answers |
-|---|---|
-| **What** | Specific verb + object (notify, check, update, prepare) |
-| **Why** | The trigger or reason (meeting approaching, deadline, user request) |
-| **Who/What** | Concrete names, IDs, URLs, filenames |
-| **Expected output** | What "success" looks like (notification sent, file updated) |
+{{> ref:prompt-frame }}
+
+For a simple one-shot — a timed reminder — the frame collapses to one tight,
+self-contained brief:
 
 **Good:** `"15-minute reminder for the 14:00 design review. Attendees: Sarah, Mike. Agenda: API v2 breaking changes. Prepare the meeting-note template and notify the user via Slack."`
 
@@ -165,7 +166,7 @@ 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), `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.
+Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-dm only — cannot be cleared; a row must always carry a non-empty prompt), `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
@@ -220,7 +221,9 @@ model, batch) are in the errors reference below.
   (its fire time can track quiet-hours; PATCH/DELETE edit it). The morning
   briefing is one of these.
 
-`GET /api/recurring-schedules` stays read-only for the dedup pre-check.
+`GET /api/recurring-schedules` stays read-only for the dedup pre-check; `includeClaimed=true`
+keeps Agent-claimed (`claimedByAgentSlug`) + trigger-owned (`claimedByTriggerId`) rows visible.
+Writes on claimed rows: **409** → `/api/agents/<slug>`; trigger-owned → `/api/triggers/<id>`.
 
 ### recurrenceRule grammar — the shared recurrence engine
 

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

@@ -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-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. |
+| `rows[].model` | No | Registered model id (`claude-opus-4-8`, `claude-sonnet-5`, `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/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-8`, `claude-sonnet-4-6`,
+  four backends. Examples: `claude-opus-4-8`, `claude-sonnet-5`,
   `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.

package/agent-assets/skills/schedule/references/prompt-frame.md

@@ -0,0 +1,125 @@
+---
+kind: reference
+name: prompt-frame
+description: The canonical core prompt frame (# Role / # Important / # Instruction / # Output), the operating-playbook references, and the clarify-back gate the DM agent uses to author a deployed agent's prompt. Shared byte-identical between agent-create and schedule.
+---
+
+### The core frame
+
+Author the deployed agent's prompt as this Markdown skeleton. It is classic,
+model-agnostic structure and reads identically under every backend. Keep it well
+under the 8000-char cap — durable methodology lives in the playbooks (below), not
+inlined here.
+
+```markdown
+# Role
+You are <agent identity>. Every <cadence> you <the single outcome this agent exists for>.
+
+# Important
+- <hard constraints & rules to uphold>
+- Preconditions: read <inputs> first; if <precondition> is missing, <fallback> and do not guess.
+- Do NOT <the things that would make the output wrong or unsafe>.
+- <playbook reference — name the methodology you'll follow, e.g. "Follow the research playbook.">
+
+# Instruction
+1. <ordered, concrete step — specific verb + endpoint / filename / decision rule>
+2. <step — include a worked EXAMPLE wherever a step is non-obvious>
+   e.g. "Classify each item actionable-today / FYI / ignore — 'PR review requested' → actionable-today; a newsletter → ignore."
+3. ...
+
+# Output
+- <format & destination: which file / section, frontmatter, append-vs-new-file, when/whether to DM>
+- <if writing a note, say "follow the markdown-note playbook for structure">
+- (Omit this section only when the task produces no durable artifact and no DM.)
+```
+
+Rules that make the difference between a sharp agent and a drifting one:
+
+- **`# Instruction` steps must include concrete examples.** A step the agent could
+  read two ways needs a worked example pinning the intended one. Vague steps are
+  the #1 cause of a drifting agent.
+- **`# Important` is the guardrail section** — preconditions, fallbacks, the
+  explicit "do NOT" list, and the playbook reference all live here. Don't scatter
+  guardrails across the other sections.
+- **The deployed agent has no memory of this conversation.** Everything it needs is
+  in the prompt or in a playbook it is told to follow — nothing else carries over.
+
+Migrating from the old four-element skeleton:
+
+| Old element | New home |
+|---|---|
+| Goal | `# Role` (identity + the single outcome) |
+| Requirements / preconditions | `# Important` (preconditions + fallbacks) |
+| Process | `# Instruction` (ordered steps, **with examples**) |
+| Expected output | `# Output` |
+| guardrails / "what NOT to do" | `# Important` |
+
+### Operating playbooks (never inline the full text)
+
+Durable methodology lives in the operating playbooks, kept central so a single
+update reaches every agent. Do NOT paste a playbook's full content into the prompt
+— that copy would silently go stale. How the methodology reaches the run depends
+on the path:
+
+- **Recurring Agent** (agent definition): name the playbook in `# Important` AND
+  declare its slug in the top-level `playbooks:` field. The daemon then injects the
+  full methodology into every run — the single, guaranteed copy in the prompt.
+- **One-off task** (`/schedule`): there is no `playbooks:` field and no injection.
+  Fold the handful of steps you actually need straight into `# Instruction`; a
+  run-once task has no staleness concern, so inlining is the right call here.
+
+| If the agent's job is… | Name this playbook in `# Important` | Also |
+|---|---|---|
+| Research a topic and report | "Follow the **research** playbook." | + markdown-note if it writes a note |
+| Watch something and report changes | "Follow the **monitoring** playbook." | + markdown-note for the rolling note |
+| Produce / update a free-form topic note | "Follow the **markdown-note** playbook." | — |
+
+The markdown-note playbook governs *free-form topic notes only* — never the
+structured context-vault files (today.md, journal, roadmap), which keep their own
+schemas.
+
+### Clarify-back before you deploy
+
+If a required slot for the agent's archetype is unknown from the conversation, ask
+the user **one consolidated question** before creating the agent — never guess. (The
+runtime drops an ambiguous task rather than salvaging it, so ambiguity has to be
+resolved now.) Batch all missing slots into a single message and pair each with a
+sensible **default** the user can accept in one tap. Ask only *missing, required*
+slots — don't interrogate.
+
+| Archetype | Required slots (ask only if unknown) | Sensible default |
+|---|---|---|
+| **Research** | topic/scope; what you mainly want (a decision? situational awareness? specific sub-questions?); depth (how many angles/sources); output destination (Obsidian note? DM? both); cadence + time | medium depth (3–5 angles); Obsidian note + short DM digest |
+| **Monitoring / digest** | what to watch; what counts as a noteworthy change; where to record; notify threshold (always vs only-on-change) | notify only on material change; record to a rolling note |
+| **Any task writing a note** | destination path; title pattern; append-to-existing vs new-file-per-run | new dated file under the topic folder |
+
+### Worked example — a content agent
+
+**Good** (research → note; core frame + playbook references):
+
+```markdown
+# Role
+You are the user's AI-news researcher. Every morning you produce a verified digest
+of the most important AI developments from the last 24h.
+
+# Important
+- Read context/research/ai-news.md for what you already reported; don't repeat it.
+- Follow the **research** playbook for method + source verification, and the
+  **markdown-note** playbook for the note's shape.
+- Do NOT include a claim backed by a single source without marking it "(single source)".
+
+# Instruction
+1. Pick 3–5 distinct angles not already covered in the existing note.
+2. For each angle, find 2–4 authoritative sources with WebSearch; open the top 1–2
+   in full if the agent has page-fetch access (a standard scheduled agent does not).
+   e.g. for "model releases" prefer the lab's own post over a news aggregator.
+3. Cross-check every material claim against ≥ 2 sources before including it.
+
+# Output
+- Write context/research/ai-news/<YYYY-MM-DD>-digest.md per the markdown-note playbook.
+- DM the user the 2–4 sentence "what matters" summary + the note path.
+```
+
+**Bad:** `"Research the latest AI news every morning and send me a summary."` — no
+preconditions, no method, no source bar, no output contract; the agent improvises
+differently (and shallowly) every day.

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

@@ -0,0 +1,68 @@
+---
+name: sources
+description: Load to manage the durable source library (user-sent PDFs/PPTX/docs) — list unfiled sources, file them as knowledge/sources/ cards, promote images, or send a stored source back. SKIP for delivering files you generated this turn (attach) or general vault edits (context).
+allowed-tools:
+  - Bash(curl *)
+  - Bash(unzip *)
+  - Read
+  - Write
+---
+
+# Source library
+
+Document attachments the user sends (PDF, PPTX, DOCX, XLSX, ODT) are captured automatically into a durable library the moment they arrive — they survive chat pruning. Each source is a ledger row (`src_…` id) plus the original bytes. Your job is the *organization* layer: write a markdown **card** for each source under `knowledge/sources/<collection>/`, link it to projects, and keep the collections tidy.
+
+- **Bash is limited to `curl` and `unzip`, literal arguments only.** No `$VAR` / `$(...)` / pipes / chained commands — anything else is silently denied. Pre-compute values and write literals.
+- Cards are written via the `context` API (this skill shows the calls); the library API below only records metadata and bindings.
+
+## API (all on `http://localhost:8321`)
+
+| Verb | Purpose |
+|---|---|
+| `GET /api/sources?status=unfiled` | List sources awaiting filing (also `filed`, `archived`; `limit`/`offset`). |
+| `GET /api/sources/<id>` | One source's metadata (filename, mime, size, caption, provenance, cardPath). |
+| `GET /api/sources/<id>/file` | The original bytes. Save to the workdir: `curl -s -o ./src-deck.pdf http://localhost:8321/api/sources/<id>/file` |
+| `POST /api/sources/promote` | Capture a chat attachment the auto-capture skipped (images, audio): `{"attachmentId":"<uuid>","caption":"…"}`. Returns the `src_…` id (`deduped:true` if already stored). |
+| `PATCH /api/sources/<id>` | Record the filing: `{"cardPath":"knowledge/sources/<collection>/<slug>.md"}` (implies `status:"filed"`). Also `{"status":"archived"}` for junk, `{"caption":"…"}`. |
+| `POST /api/sources/<id>/export` | Copy the original binary into the user's external Obsidian vault: `{"target":"obsidian"}`. Lands at `sources/<file>` with a companion note embedding it (`{"note":false}` to skip). 409 if no external vault is configured. For **Notion**, there is no binary path — create a page from the card markdown via `POST /api/notion/pages` instead. |
+
+Errors use the standard agent-error envelope; `404 sources.not_found` means a stale id — re-list. Never DELETE a source; archive instead (deletion is owner-only).
+
+## Filing a source (the core loop)
+
+1. `GET /api/sources?status=unfiled` — pick a source.
+2. Understand it. PDFs: fetch the bytes to the workdir and `Read` the file directly. PPTX/DOCX are zip archives of XML — best-effort text peek with `unzip -p ./src-deck.pptx ppt/slides/slide1.xml` (one file per call, no pipes; read the text between the XML tags in the output). If `unzip` is unavailable on this platform, fall back to filename + caption — they often suffice.
+3. Choose a collection per the taxonomy below (create a new one only when nothing fits).
+4. Write the card:
+
+```bash
+curl -s -X PUT http://localhost:8321/api/context/knowledge/sources/acme-launch/pitch-deck.md \
+  -H "Content-Type: application/json" \
+  -d '{"content":"---\ntype: source\nowner: agent\nupdated: 2026-07-01\nsource_id: src_1234\nmime: application/pdf\nreceived: 2026-07-01\nprovenance: user_telegram\n---\n# Acme launch pitch deck\n\nOne-paragraph summary of what the document contains and why the user sent it.\n\nProject: [[acme-launch]]\n"}'
+```
+
+5. Bind it: `curl -s -X PATCH http://localhost:8321/api/sources/src_1234 -H "Content-Type: application/json" -d '{"cardPath":"knowledge/sources/acme-launch/pitch-deck.md"}'`
+6. If the source belongs to a project, add a `- [[knowledge/sources/acme-launch/pitch-deck|Pitch deck]]` line under a `## Sources` heading in `plans/projects/<slug>.md` (PATCH, append mode).
+7. Keep `knowledge/sources/_index.md` current: one line per collection with a one-phrase scope.
+
+## Reorganizing
+
+Move a card = PUT the card at the new path, DELETE the old path (`curl -X DELETE http://localhost:8321/api/context/knowledge/sources/old/card.md`), then PATCH the source's `cardPath`. Deletes are snapshotted — recoverable. Merge singleton collections into broader ones; split collections past ~15 cards.
+
+## Sending a source back to the user
+
+Fetch the bytes to the workdir, then deliver through the outbound endpoint (see the `attach` skill for limits):
+
+```bash
+curl -s -o ./src-deck.pdf http://localhost:8321/api/sources/src_1234/file
+curl -s -X POST http://localhost:8321/api/chat/outbound-attachments \
+  -H "X-Filename: pitch-deck.pdf" -F "file=@./src-deck.pdf"
+```
+
+## Collection taxonomy (auto-curated)
+
+<!-- CURATION:knowledge_layout id="source-collections" -->
+
+## Filing conventions (auto-curated)
+
+<!-- CURATION:convention_notes id="filing-rules" -->

package/agent-assets/skills/sources/curation.json

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "source-collections",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"source-collections\" -->",
+      "human_label": "Source collection taxonomy",
+      "description": "Current collections under knowledge/sources/ and what belongs in each",
+      "scope_paths": ["knowledge/sources/**"]
+    },
+    {
+      "id": "filing-rules",
+      "kind": "convention_notes",
+      "anchor": "<!-- CURATION:convention_notes id=\"filing-rules\" -->",
+      "human_label": "Source filing conventions",
+      "description": "Card slug grammar, card body shape, and project cross-linking rules",
+      "scope_paths": ["knowledge/sources/**"]
+    }
+  ]
+}

package/agent-assets/skills/sources/seeds/filing-rules.seed.json

@@ -0,0 +1,25 @@
+{
+  "kind": "convention_notes",
+  "notes": [
+    {
+      "topic": "Card slug",
+      "rule": "Lowercase [a-z0-9._-], descriptive of the document content, not the filename (strip dates/version noise unless meaningful).",
+      "example": "knowledge/sources/acme-launch/pitch-deck.md for 'Acme_Pitch_FINAL_v3 (2).pdf'"
+    },
+    {
+      "topic": "One card per source",
+      "rule": "Exactly one card per src_ id; on dedup (same file re-sent) update the existing card's `updated:` instead of writing a second card.",
+      "example": "receive_count > 1 on GET /api/sources/<id> means the user re-sent the same bytes"
+    },
+    {
+      "topic": "Collection choice",
+      "rule": "Prefer a collection matching an active project slug; use a topical collection for project-less documents; reserve `inbox` for the genuinely unclassifiable.",
+      "example": "a tax PDF with no project goes to knowledge/sources/finance/, not inbox"
+    },
+    {
+      "topic": "Project cross-link",
+      "rule": "When a source supports a project, the project file gets a `## Sources` bullet linking the card — the card alone is not discoverable from the project side.",
+      "example": "plans/projects/acme-launch.md gains: - [[knowledge/sources/acme-launch/pitch-deck|Pitch deck]]"
+    }
+  ]
+}

package/agent-assets/skills/sources/seeds/source-collections.seed.json

@@ -0,0 +1,20 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "knowledge/sources/_index.md",
+      "purpose": "Directory of collections — one line per collection with its one-phrase scope",
+      "sections": [
+        { "heading": "## Collections", "contains": "bullet list: - [[<collection>]] — what belongs there" }
+      ]
+    },
+    {
+      "path": "knowledge/sources/*/*.md",
+      "purpose": "One card per stored source document; collections usually mirror an active project slug from plans/projects/",
+      "sections": [
+        { "heading": "# <Title>", "contains": "H1 naming the document in plain words" },
+        { "heading": "(body)", "contains": "one-paragraph summary, why the user sent it, and a Project: [[<slug>]] link when one applies" }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,82 @@
+---
+name: task
+description: Unified write facade for tracked work — create/edit/delete any task through one path. POST /api/tasks {kind: reminder|dm|agent|app_fetch|background}; PATCH/DELETE /api/tasks/<ref>. Forwards to the hardened owners (dedup, cascade, dm_session split intact).
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Task — one path to create, edit, or delete any tracked work
+
+Instead of choosing among six creation skills, route every write through
+`/api/tasks`. The facade **forwards** your request to the existing hardened
+owner endpoint by `kind` (create) or ref prefix (edit/delete) — it never
+re-implements them, so each owner's dedup, FK cascade, validation, the
+`dm_session` recurring split, and auth tier all still apply unchanged.
+
+Pair it with the **`board`** skill (read inventory + blast-radius).
+
+## Create — `POST /api/tasks`
+
+Send `{ "kind": "...", ...ownerFields }`. The facade strips `kind` and forwards
+the rest to the owner, so **provide the owner's own fields** (it does not rename
+them). Pick the kind:
+
+| `kind` | Routes to | Provide | Detailed authoring skill |
+|---|---|---|---|
+| `reminder` | `POST /api/schedule/dm` | `time` (ISO8601), `message` | `schedule` |
+| `dm` | `POST /api/recurring-schedules` | `description` (≥20), `recurrenceRule`, `prompt?` (task_type is pinned to `dm_session`) | `schedule` |
+| `agent` | `POST /api/agents` | `slug`, `name`, `schedule` (`{kind:"recurring",recurrence}` or `{kind:"cron",expression}`), `prompt?` | `agent-create` |
+| `app_fetch` | `POST /api/managed-tasks` | `intent`, `app`, `cadence`, `recurrenceRule`, `output_path?` (send an `Idempotency-Key` header) | `managed-tasks` |
+| `background` | `POST /api/background-task` | `brief`, `title?`, `notificationPolicy?` | `background-task` |
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"kind":"reminder","time":"2026-07-01T15:00:00+09:00","message":"call the dentist"}' \
+  http://localhost:8321/api/tasks
+```
+
+For anything beyond the simple case — authoring a full recurring Agent, an
+app-fetch where dedup / output-path shape matter, a self-contained background
+brief — open the **detailed skill** in the last column for its field rules, then
+either POST through that skill directly or mirror its body here. The facade is
+the front door; the specialised skills are the manual.
+
+## Edit / delete — `PATCH` / `DELETE /api/tasks/<ref>`
+
+Address the row by its typed `ref` from the board (`rs:<id>`, `mt_<n>`,
+`agent:<slug>`, `as:<id>`, `trigger:<id>`). PATCH forwards your patch body to
+the owning edit endpoint; DELETE forwards to the owning delete (cascade
+preserved). A `trigger:` write routes to `/api/triggers/<id>` (Approve tier;
+`401` = needs the dashboard's authorization; no facade create kind) and its
+delete removes the paired recurring schedule too.
+
+```bash
+curl --silent --fail -X PATCH -H 'Content-Type: application/json' \
+  -d '{"enabled":false}' http://localhost:8321/api/tasks/rs:42
+
+curl --silent --fail -X DELETE http://localhost:8321/api/tasks/mt_3
+```
+
+## Response envelope
+
+Every dispatch returns the owner's HTTP status with
+`{ ok, dispatchedTo, kind, result }` — `result` is the owner's own body
+(e.g. `{ status:"created", item }`). Read `result` for ids and warnings.
+
+## Hard rules
+
+1. **Localhost only.** `http://localhost:8321/api/tasks*`.
+2. **A `dm` create is always a `dm_session` row.** You cannot create recurring
+   autonomous *work* through `kind:"dm"` — that is `kind:"agent"`. The facade
+   enforces this (it never opens the 410'd recurring agent-task door, and never
+   stamps an agent id onto a schedule).
+3. **Editing/deleting an Agent is privileged.** `agent:<slug>` routes to
+   `/api/agents`, which may require the dashboard's authorization — a `401` means
+   it needs human approval, exactly as editing the Agent directly does. Built-in
+   Agents are undeletable (`409`); stopping one needs the stop-warning ack.
+4. **Fulfillers are read-only here.** `bt:` / `bx:` / `cluster:` refs return
+   `422` — manage them on their own surfaces; never resume a force-failed browser
+   task or surface a pending `!~` confirm token.
+5. **Preview destructive changes first.** For a delete/modify the user may not
+   fully grasp, run `GET /api/tasks/impact?ref=<ref>` (the `board` skill) and
+   confirm the blast radius before acting.

package/agent-assets/task-flows/background_task.md

@@ -44,8 +44,8 @@ notification policy. Read it carefully and satisfy it end to end.
 
 ## Finishing — the artifact (read this carefully)
 
-`finish(result, draft, notify, significance?)` is the only thing the
-owner ever sees the effect of. Each field has a distinct job:
+`finish(result, draft, notify, verification, significance?)` is the only
+thing the owner ever sees the effect of. Each field has a distinct job:
 
 - **`result`** — the FULL, verbatim outcome: every finding, number, URL,
   id, quote. This is persisted unchanged and is what a precise follow-up
@@ -67,15 +67,41 @@ owner ever sees the effect of. Each field has a distinct job:
     the brief. If the criteria are not met, `notify = false`.
   - `silent` → `notify = false`.
   - When you are on `always` and unsure, prefer `true`.
+- **`verification`** *(required)* — your self-verification checklist: 1–10
+  `{requirement, met, evidence}` items (see "Self-verification before
+  finish" below). Any `met=false` automatically appends a gap disclosure
+  to your `draft` and records the completion as `completed_with_gaps` —
+  you do not need to (and cannot) hide a gap.
 - **`significance`** *(optional)* — one line on why notify is true/false
   ("2 repos red" / "no criteria met"). Used for the audit + the
   filed-results digest.
 
+## Self-verification before finish
+
+Before calling `finish`, verify your own result against the brief:
+
+1. **Derive a checklist** from the brief's **Expected output** section
+   (fallback: the Objective) — 1–10 concrete requirements, each stated in
+   ≤300 chars.
+2. **Verify each item against your ACTUAL result**, not your intent.
+   `evidence` must point at something real in `result` ("table has one
+   row per repo, all 6 listed"), never a restatement of the requirement.
+3. **If a requirement is unmet and you have turn budget left, attempt the
+   repair FIRST** — go back, gather what is missing, then re-verify.
+4. Finish with `met=false` only when you genuinely cannot fix it (source
+   unavailable, out of scope, budget exhausted). Say what is missing and
+   why in `evidence`.
+
+Never claim `met=true` your evidence does not support: any unmet item is
+disclosed to the owner automatically, but a false "met" is a silent lie
+the owner will act on.
+
 ## Typical loop
 
 ```
 1. (optional) read_memory(...)            # pull owner context you need
 2. WebSearch / WebFetch / reason          # do the actual work
 3. (only if blocked) ask_user(...)        # then STOP this turn
-4. finish(result=<full>, draft=<summary>, notify=<policy eval>, significance=<one line>)
+4. self-verify vs the brief's Expected output; repair gaps if budget remains
+5. finish(result=<full>, draft=<summary>, notify=<policy eval>, verification=<checklist>, significance=<one line>)
 ```

package/agent-assets/task-flows/message.received.dm.md

@@ -160,7 +160,7 @@ Schedules go through this daemon — never through any cloud-hosted scheduled-ag
 
 **Default schedules** (morning briefing, etc.) are stored as `recurring_schedules` rows. When the user asks to disable / change time / skip today / re-enable — e.g. "turn off morning briefing", "move it to 7:30", "skip today's briefing":
 
-1. `GET /api/recurring-schedules` — locate the row by matching `task_context.sub_flow` (e.g. `morning_briefing`).
+1. `GET /api/recurring-schedules?includeClaimed=true` — locate the row by matching `task_context.sub_flow` (e.g. `morning_briefing`). If the matched row carries `claimedByAgentSlug`, it is an Agent's cadence satellite — apply the change via `PATCH /api/agents/<slug>` instead of the row (a direct PATCH/DELETE is 409).
 2. Apply the change:
    - **Disable** → `PATCH /api/recurring-schedules/:id` `{"enabled": false}`, then `DELETE /api/schedule/:id` for any pending instance scheduled for today.
    - **Change time** → `PATCH /api/recurring-schedules/:id` with `{"recurrenceRule": {...}, "taskContext": {"sub_flow": "<unchanged>", "pin_to_quiet_hours_end": false}}`. Setting `pin_to_quiet_hours_end: false` is mandatory — without it, the next quiet-hours change overwrites the user's pinned time.

package/agent-assets/task-flows/routine.activity_scan.md

@@ -94,6 +94,19 @@ emits it. The block tells you *why* you were spawned — pull the
   `<fetch_report status="failed">` block in your prompt tells you
   which integration is lossy; treat its observations as potentially
   stale and lean on whatever rows the previous tick left.
+- `reason: agent_chronic_failure` → an enabled agent keeps failing
+  its runs; the `<system_health>` block lists which. See "System
+  health" below.
+
+### System health
+A `<system_health>` block (when present) lists enabled agents whose
+recent runs all failed. An entry there qualifies as a positive notify
+trigger under Step 9 rule (c) — a silent, repeated failure the user
+will not discover on their own. The Step 9 dedup pre-check still
+applies: if the same agent's failure was already surfaced today, log
+only. When notifying, name the agent, suggest checking
+`/agents/<slug>` on the dashboard, or offer to have it disabled ("say
+'disable it'").
 
 ### Pre-summarized observations (cost-reduction-structural §A)
 Every observation arrives with `summary_text` (≤120 chars) and
@@ -159,8 +172,10 @@ This rule applies regardless of integration mode (direct, same-backend delegated
      skip (log `skipped: already in User Tasks`).
    - For schedule registrations, also query:
      `GET /api/schedule?status=pending,running` AND
-     `GET /api/recurring-schedules?enabled=true`.
-     If a pending/recurring item covers the same trigger → skip.
+     `GET /api/recurring-schedules?enabled=true&includeClaimed=true`
+     (rows with `claimedByAgentSlug` are Agent-managed but still count
+     as coverage). If a pending/recurring item covers the same
+     trigger → skip.
 
    Only after dedup clears, route the observation:
    - New TODO for the user → append to ## User Tasks with the row shape in the