@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,330 @@
+---
+name: management-task-register
+description: Register a new recurring agent fetch against a third-party app from a DM — "check Zoom recordings daily at 10am", "check Gmail daily for invoices". Owns INSERT on §B "Managed tasks" rows. SKIP for one-off reminders, modify, stop.
+when_to_use: User asks to start a recurring external-app fetch / check / sync (Zoom, Gmail, Drive, Notion, custom MCP). SKIP for one-off reminders (`schedule`), durable rules without an external app (`management-policy`), or pure DM cadence (`schedule` recurring).
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# Register a Managed Task
+
+A **managed task** (`mt_<n>`) is a user-delegated commitment: the agent
+runs a recurring fetch against a specific App at a user-specified
+Cadence and writes the resulting entities into a primary L2 directory
+(the `Output path`). Each row lives in `rules/management.md` §B. The
+authoritative store is the `managed_tasks` SQLite table; the file is
+re-rendered from the table after every mutation, so do **not** PUT the
+file yourself — every legal mutation goes through
+`/api/managed-tasks` and the daemon owns the file write.
+
+## When to use
+
+The user's DM clearly asks for a **recurring fetch / check / sync
+against a third-party app** with a cadence:
+
+- "Check Zoom recordings every day at 10am"
+- "Check Gmail daily and triage invoices into receipts"
+- "Every Monday at 9 pull new Drive PDFs into receipts"
+- "Check Notion 'Reading' DB every evening and surface unread"
+
+## When NOT to use
+
+| Shape | Use instead |
+|---|---|
+| One-off "remind me at 3pm to call the bank" | `schedule` (`/api/schedule/dm`) |
+| Recurring DM with no external-app fetch ("ping me every Monday at 9") | `schedule` recurring-schedules |
+| "From now on, when X happens, do Y" passive rule with no cadence | `management-policy` |
+| Tone / style / single fact about the user | `user-profile` |
+| Source-of-Truth declaration ("notes live in Obsidian") | A-section binding via `PUT /api/sot-bindings` (separate flow) |
+| Modify cadence / output of an existing `mt_<n>` | `management-task-modify` |
+| Stop an existing `mt_<n>` | `management-task-stop` |
+| Run an existing `mt_<n>` once, off-schedule | `POST /api/managed-tasks/<id>/run-now` |
+
+If the user already has `mt_<n>` for the same app+cadence, this skill
+**refuses** with a DM pointing at the existing row — that is the dedup
+contract (FR-2). Do not register a duplicate.
+
+## Algorithm (mirror of design 21 §10.1)
+
+Run the steps in order. Any step's failure DMs the user with the
+verbatim reason and ends the flow — never skip, never silently retry,
+never hardcode a tool name (FR-4 / ADR §8.4).
+
+### Step 1 — Read current state
+
+```bash
+curl -s "http://localhost:8321/api/context/rules/management" | jq -r .content
+```
+
+Extract §B (Managed tasks) and §A (Source-of-Truth bindings). §A tells
+you which app already owns a category (e.g. `tasks → notion`); a
+duplicate-cadence registration against an unrelated app for the same
+category is a smell and should be confirmed before registering.
+
+### Step 2 — Semantic dedup (LLM judgment)
+
+For each existing §B row, compare the requested
+`(app_normalized, cadence_semantic, intent_semantic)` against the row.
+Treat a row as a **high-confidence match** when:
+
+- `app_normalized` matches case-insensitively (e.g. `zoom` ≡ `Zoom`),
+  AND
+- the cadence resolves to the same structured recurrence, AND
+- the intent describes the same fetch shape (e.g. "recordings → meeting
+  entity" is the same as "new recordings → meeting entity").
+
+On a match, DM the user verbatim with the existing row's id, cadence
+and last result, and stop:
+
+> Already managed as `mt_42` (daily 10:00 — last run ok 3 new). Modify
+> or stop it via DM.
+
+If multiple plausible matches exist, ask the user which one to update
+and end the flow (the user's reply triggers `management-task-modify`).
+
+If §B already holds the cap (default 100, configurable
+`managementMaxActiveTasks`), refuse with a DM pointing at the cap; the
+user must stop something first.
+
+### Step 3 — Tool selection (LLM judgment, in-session)
+
+Enumerate the tools available to this session (`mcp__*`, native
+backend connectors, custom MCP servers the user installed). Ask
+yourself: *"Which of these, if any, lets me read the user-typed app
+label?"*
+
+- **Zero plausible** → DM "I don't see a connected tool for `<app>` on
+  this backend. Connect one and ask again." Stop.
+- **Multiple plausible** → DM the user with the candidates verbatim
+  and ask which one to use. Stop. (The user's reply re-enters this
+  flow with the chosen tool as a hint.)
+- **One plausible** → continue.
+
+NEVER hardcode tool names or pattern-match against
+`mcp__claude_ai_<App>__*`. The user may have installed a custom MCP
+with non-standard names — you read the tool description and pick by
+**capability**, not by name.
+
+### Step 4 — Read-only probe
+
+Invoke the chosen tool with the **smallest** read-only payload that
+proves connectivity and authorization (e.g. list the first page with
+`limit: 1`, fetch the user's profile / "me" endpoint, search for an
+empty string). Do NOT mutate state.
+
+On any error — auth failure, network error, schema error,
+out-of-quota — DM the verbatim error message with one line of context
+and stop:
+
+> Couldn't reach `<app>`: `<verbatim error from tool>`.
+
+The probe failure must surface the connector's own error string, not a
+paraphrase. The user is the one who can fix auth / quota / install.
+
+### Step 4a — Decide `Output path` (LLM judgment)
+
+From the probe sample, infer the primary L2 directory the recurring
+fetch will write into. Bias toward existing matches:
+
+1. If the entity-mirror already holds entities with `sources.<app>.*`
+   under one `<domain>/<type-plural>/`, reuse that path. Probe with:
+   ```bash
+   curl -s "http://localhost:8321/api/entities?source=<app>&limit=5" | jq .
+   ```
+   The response is `{tier:1, mode:"by_source_key", items:[…]}`; each
+   item's `path` (`<domain>/<type-plural>/<slug>.md`) reveals where
+   that source already lives. If 1+ rows agree on `<domain>/<type>`,
+   that path wins.
+2. Otherwise, pick the `(domain, type)` pair whose semantic prior best
+   fits the data shape. Reference table:
+
+   | Probe sample shape | Likely `<domain>/<type-plural>/` |
+   |---|---|
+   | Recording with attendees + duration | `work/meetings/` |
+   | PDF / image with monetary amount | `finance/receipts/` |
+   | Task / ticket / issue | one of the project domains' `projects/` (rare — typically the Tasks SoT mirror handles this; only register a managed task if the SoT is *another* app) |
+   | Travel itinerary / booking | `travel/trips/` |
+   | Long-form note / article | `<domain>/notes/` (pick by content topic) |
+   | Book metadata / progress | `learning/books/` |
+3. If the data shape is genuinely ambiguous (e.g. the probe returned
+   zero rows), set `output_path: null` — the first scheduled run will
+   populate it from real data.
+
+**Path validation invariant** (§9.3, §13.3):
+
+- Format: `<domain>/<type-plural>/` — leading `context/` is implicit
+  and must NOT be included; the trailing `/` is mandatory.
+- `<domain>` ∈ `{work, travel, finance, personal, health, learning}`.
+- `<type-plural>` ∈ `{meetings, trips, receipts, projects, books, notes}`.
+- No `..` segments. No absolute paths.
+
+The daemon CHECKs the constraint at INSERT/UPDATE time and rejects with
+a 422 — surface that error verbatim if it fires. Pre-validate to avoid
+the round-trip when you can.
+
+### Step 5 — Resolve cadence to a `recurrenceRule`
+
+Translate the user's natural-language cadence into:
+- a free-text `cadence` string (what gets rendered in §B), AND
+- a structured `recurrenceRule` (what the scheduler executes).
+
+The daemon's recurrence engine accepts only `daily` / `weekly` /
+`monthly`. Sub-daily ("every hour", "every 5 minutes") is **not
+representable** — refuse those with a DM and ask for a daily-or-coarser
+cadence. Times are `HH:MM` 24-hour local; timezone is IANA (auto-fills
+from daemon config when omitted, but it's safer to pass it explicitly
+so a roaming laptop doesn't surprise the user).
+
+| User said | `cadence` | `recurrenceRule` |
+|---|---|---|
+| every day at 10am (Asia/Tokyo) | `daily 10:00 (Asia/Tokyo)` | `{frequency:"daily", time:"10:00", timezone:"Asia/Tokyo"}` |
+| every Monday 9am | `weekly Mon 09:00` | `{frequency:"weekly", time:"09:00", timezone:<user tz>, daysOfWeek:[1]}` |
+| every weekday at 8am | `weekdays 08:00` | `{frequency:"weekly", time:"08:00", timezone:<user tz>, daysOfWeek:[1,2,3,4,5]}` |
+| 1st of every month at noon | `monthly day 1 12:00` | `{frequency:"monthly", time:"12:00", timezone:<user tz>, daysOfMonth:[1]}` |
+| every hour | _refuse_ | _refuse_ |
+| every 5 minutes | _refuse_ | _refuse_ |
+
+`daysOfWeek` is `0=Sun..6=Sat`; `daysOfMonth` is `1..31` (29-31 clamp
+to last day of short months). `daysOfWeek` is forbidden on `daily` and
+`monthly`; `daysOfMonth` is forbidden on `daily` and `weekly` — the
+daemon's Zod refinements reject mismatches with a `validation_error`.
+
+For sub-daily requests, refuse with a DM:
+
+> The agent's recurrence engine only supports daily, weekly, or monthly
+> cadences. `every hour` is too tight — pick `daily` or coarser.
+
+### Step 6 — POST /api/managed-tasks
+
+```bash
+curl -sS -X POST http://localhost:8321/api/managed-tasks \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: <opaque uuid for this DM>' \
+  -d @- <<'JSON'
+{
+  "intent":      "Zoom recordings → meeting entity",
+  "app":         "zoom",
+  "cadence":     "daily 10:00 (Asia/Tokyo)",
+  "recurrenceRule": {
+    "frequency": "daily",
+    "time":      "10:00",
+    "timezone":  "Asia/Tokyo"
+  },
+  "output_path": "work/meetings/"
+}
+JSON
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `intent` | yes | ≤ 200 chars, NFC, no newlines, no pipe chars |
+| `app` | yes | ≤ 64 chars, NFC, no newlines, no pipe chars; user-typed label preserved verbatim (case + non-ASCII OK) |
+| `cadence` | yes | Human-readable; rendered in §B (≤ 200 chars) |
+| `recurrenceRule` | yes | `{frequency:"daily"\|"weekly"\|"monthly", time:"HH:MM", timezone?:<IANA>, daysOfWeek?:[0..6], daysOfMonth?:[1..31]}` — see Step 5 table |
+| `output_path` | no | `<domain>/<type-plural>/` per §9.3, ending `/`; omit while undecided (the first scheduled run back-fills it) |
+
+The response is `{status:"created", item:<ManagedTask>, render_status:"ok"|"lock_contended:..."}`.
+On an idempotent replay (same `Idempotency-Key` within 24 h, the row
+still exists) you get `{status:"idempotent_replay", item:<ManagedTask>}`
+with HTTP 200 — treat that as success, not a duplicate registration.
+
+**Idempotency-Key.** Generate a stable key per DM (e.g. SHA-256 of the
+inbound message id + app). Concurrent retries collapse to the same
+`mt_<n>`; a different key with the same `app+cadence` collides at the
+`(app_normalized, cadence)` uniqueness check and the second POST returns
+`409 conflict` with the existing `mt_id` — DM the user pointing at it
+instead of registering twice.
+
+**Server-side transaction (atomic).** The daemon allocates the next
+`mt_<n>` from `managed_task_seq`, INSERTs `recurring_schedules` and
+`managed_tasks` linked by FK, and writes one `agent_actions` row
+(`action_type='management_task.created'`). On any DB failure the
+transaction rolls back and you get a 5xx — surface the body verbatim.
+
+**File render.** Post-transaction the daemon re-renders
+`rules/management.md` from DB (locked, snapshotted into
+`md_file_snapshots`). You do NOT touch the file.
+
+### Step 7 — Confirm to user
+
+DM the user once with the assigned id (`item.id` from the POST
+response), the resolved output path (`item.output_path`), and the
+human cadence label (`item.cadence`). The next firing time is owned by
+the scheduler — phrase the confirmation around the cadence rather than
+fabricating a clock time.
+
+> Registered as `mt_43` (Zoom · daily 10:00 JST). Output → `work/meetings/`. Starts at the next 10:00 JST slot.
+
+Persona / language rules are in `notify` — the message itself follows
+the awareness gate and no-ceremony rules. Don't enumerate the steps
+("did probe, did INSERT, did re-render"); the daemon already audited
+them.
+
+## Validation cheatsheet (§13.3)
+
+| Field | Rule | Reject example |
+|---|---|---|
+| `app` | trimmed; NFC; ≤ 64 chars; no `\n`; no `\|` | `\|gmail` |
+| `intent` | trimmed; NFC; ≤ 200 chars; no `\n`; no `\|` | `<5×40 chars>` |
+| `cadence` | free text, ≤ 200 chars | _any non-empty string_ |
+| `recurrenceRule.frequency` | `daily` \| `weekly` \| `monthly` | `hourly`, `every-5-min` |
+| `recurrenceRule.time` | `HH:MM` zero-padded | `9:00`, `25:00` |
+| `recurrenceRule.timezone` | IANA zone string (auto-fills from daemon when omitted) | `EST+9` |
+| `recurrenceRule.daysOfWeek` | required for `weekly`; forbidden otherwise; ints `0..6` | `[7]`, `[]` |
+| `recurrenceRule.daysOfMonth` | required for `monthly`; forbidden otherwise; ints `1..31` | `[0]`, `[32]` |
+| `output_path` | `<domain>/<type-plural>/`; no `..`; trailing `/` | `work/meetings`, `../foo/`, `random/dir/` |
+| `mt_id` | server-allocated; never craft client-side | n/a |
+
+The daemon also enforces these — but pre-validating saves the user one
+round-trip of error chatter.
+
+## Error envelope
+
+| HTTP | `error` | What to do |
+|---|---|---|
+| 400 | `validation_error` | Body has Zod `details`; pick the offending field's message and ask the user to clarify. The Zod issue path tells you whether `recurrenceRule.*`, `app`, `output_path`, etc. is the culprit. |
+| 409 | `duplicate` | Body includes `item` (the existing row); DM "Already managed as `<item.id>`" and stop |
+| 409 | `cap_reached` | Surface `body.message` (cap value); user must stop something first |
+| 5xx | `internal_error` | DM "Couldn't register; daemon error. Try again, or check `aitne logs`." |
+
+`body.message` (when present) is intended for the user — preserve it
+verbatim. The daemon does not currently emit `cron_too_tight` because
+the recurrence schema only accepts daily/weekly/monthly — a sub-daily
+ask never reaches POST; refuse it client-side per Step 5.
+
+## What this skill does NOT do
+
+- Does NOT hardcode connector tool names — all tool selection is
+  LLM-judged (FR-4).
+- Does NOT PUT `rules/management.md` directly — the daemon owns that
+  write (FR-12). The only legal write is `POST /api/managed-tasks`.
+- Does NOT INSERT `recurring_schedules` directly. POST
+  `/api/managed-tasks` is the chokepoint that keeps the FK pair
+  consistent.
+- Does NOT touch §A (SoT bindings). Use `PUT /api/sot-bindings` for
+  that (separate "sot" flow).
+- Does NOT touch §C (Active Policies stub). Owned by
+  `management-policy`.
+- Does NOT silently re-register on retry. Use `Idempotency-Key`
+  per-DM; conflicts surface the existing `mt_id`.
+- Does NOT register a task that has no probe-passing connector. Probe
+  failure is a hard stop — never "register optimistically and hope".
+- Does NOT proceed when the vault is in degraded mode
+  (`Dispatcher.isAutonomousAllowed()` already filters). Trust that
+  upstream.
+
+## API summary
+
+| Verb + path | Used in |
+|---|---|
+| `GET /api/context/rules/management` | Step 1 (read §A + §B) |
+| `GET /api/entities?source=<app>` | Step 4a (output-path bias) |
+| `GET /api/managed-tasks` | Optional — alternative to parsing the file |
+| `POST /api/managed-tasks` | Step 6 (Notify-tier; the daemon DMs confirmation; no Approve gate) |
+| `POST /api/notify` | Step 7 (your own DM-to-user reply) — uses the `notify` skill's discipline |
+
+Every state-changing call is recorded in `agent_actions` and the file
+is snapshotted into `md_file_snapshots` — do NOT post a separate audit
+event yourself.

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

@@ -0,0 +1,166 @@
+---
+name: management-task-stop
+description: Stop (hard-delete) an existing managed task (`mt_<n>`) from a DM — "stop the daily Zoom check", "cancel mt_42". Owns DELETE on §B rows. SKIP for cadence tweaks (modify), pause (no soft-pause), or one-off skip.
+when_to_use: User wants to end a recurring agent commitment. SKIP for cadence / intent / output-path tweaks (`management-task-modify`), pause-then-resume (no soft-pause exists; user must re-register), or removing a one-off scheduled task (`schedule` skill DELETE).
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# Stop a Managed Task
+
+Hard-deletes a managed-task row. The `recurring_schedules` row
+cascade-deletes via FK and any pending `agent_schedule` rows for the
+old cron are cancelled. History is preserved entirely in
+`agent_actions` (`action_type='management_task.deleted'`) and
+`md_file_snapshots` — there is no soft-stop placeholder in the
+file (ADR §8.5).
+
+## When to use
+
+The user clearly asks to **end** a recurring commitment:
+
+- "Stop the daily Zoom check"
+- "Cancel `mt_42`"
+- "Remove the gmail invoice triage — I'm not reading those anymore"
+- "I don't need the Drive receipts pull anymore"
+
+## When NOT to use
+
+| Shape | Use instead |
+|---|---|
+| User wants to keep it running but tweak it | `management-task-modify` |
+| User wants to pause for a few days then resume | No soft-pause exists. Stop now; user re-registers when they want it back. Spell this out in the confirmation. |
+| User wants to skip exactly one upcoming run | DELETE the pending `/api/schedule/:id` row (the row in `agent_schedule`); the next slot fires normally. Use the `schedule` skill. |
+| User wants to drop a one-off `/api/schedule` reminder | `schedule` skill DELETE |
+| User wants to clear `_activity/<source>.md` | The reconciler regenerates it within 90 days; nothing to delete here |
+
+## Algorithm (mirror of design 21 §10.3)
+
+### Step 1 — Locate the row
+
+Same lookup as `management-task-modify`. Either the user named the id
+directly, or you fuzzy-match by `(app, cadence, intent)`.
+
+```bash
+curl -s "http://localhost:8321/api/managed-tasks/mt_42" | jq .item
+# or:
+curl -s "http://localhost:8321/api/managed-tasks" | jq '.items[] | select(.app_normalized == "zoom")'
+```
+
+GET-by-id wraps the row in `{item:<row>}`; the list returns
+`{items:[…], count:N}`.
+
+If multiple rows could match, list them and ask which to stop. Stop
+until the user picks. **Never stop more than one row in a single
+turn.** A bulk stop ("stop all gmail tasks") requires explicit
+confirmation per row.
+
+If no row matches, DM:
+
+> No managed task for `<app>` is registered.
+
+### Step 2 — Confirm with the user (Notify tier — destructive)
+
+DELETE on a managed task is **Notify tier** (§13.1) AND removes a
+recurring commitment that the user themselves set up. Both safety
+invariants ("destructive ops require user confirmation" from
+CLAUDE.md, plus the Notify-tier policy) demand a real DM confirmation
+in the user's preferred language. Never auto-stop.
+
+> Stop `mt_42` Zoom check (daily 10:00 JST · last run ok 3 new)? It
+> won't auto-resume.
+
+If the user declines, stop the flow. If they amend ("actually just
+make it weekly"), route to `management-task-modify` instead — do not
+stop and re-register on their behalf.
+
+The "last run" line in the confirmation matters: a row that has been
+silently failing (`consecutive_failures ≥ 3`) is exactly the kind the
+user is most likely stopping by mistake (they may not realize the
+failures alone are the problem). Surface `last_result` so they can
+make an informed call.
+
+### Step 3 — DELETE /api/managed-tasks/:id
+
+```bash
+curl -sS -X DELETE http://localhost:8321/api/managed-tasks/mt_42
+```
+
+The server-side transaction (atomic):
+
+a. snapshots the row's full state into `agent_actions.detail`,
+b. DELETEs `managed_tasks` (cascades to `recurring_schedules` via FK),
+c. cancels pending `agent_schedule` rows for the old cron,
+d. re-renders `rules/management.md` from DB (locked + snapshotted into
+   `md_file_snapshots`),
+e. INSERTs `agent_actions` (`action_type='management_task.deleted'`,
+   `detail={mt_id, original_row, deleted_at, by_user_message}`).
+
+The pre-delete file snapshot in `md_file_snapshots` plus the
+`detail.original_row` blob in `agent_actions` together let the user
+or the activity-view reconciler reconstruct the row at any later
+date — there is no further "soft-stop" archive needed.
+
+### Step 4 — Confirm to user
+
+One DM:
+
+> Stopped `mt_42` Zoom check. The row is gone from the registry; ask
+> me to register a new one any time.
+
+Persona / language rules from `notify` apply. Don't list the internal
+mechanics ("snapshotted, cascade-deleted") — the audit log is for
+the agent, not the user.
+
+The `_activity/zoom.md` file's "Recently changed (90d)" section
+auto-updates within ~10 s as the activity-view reconciler picks up
+the new `agent_actions` row. You do NOT touch that file.
+
+## Error envelope
+
+| HTTP | `error` | What to do |
+|---|---|---|
+| 400 | `invalid_id` | The `:id` segment didn't match `^mt_[1-9]\d*$`; ask the user to repeat |
+| 404 | `not_found` | DM "No managed task with that id"; if you used a fuzzy match, re-list candidates |
+| 5xx | `internal_error` | Surface `body.message` if present; advise `aitne logs` |
+
+The daemon's DELETE is unconditional — there is no `running_now` /
+`?force=true` in-flight guard today. If the cascade collides with a
+fire that is mid-execution the dispatcher's retry / orphan-detection
+path picks it up; do not try to "wait for it to finish" in the skill.
+
+The pre-delete row snapshot in `agent_actions` (`detail.original_row`)
+together with the file snapshot in `md_file_snapshots` is the
+recovery surface — surface it in audit/debug contexts only, never in
+the user-facing DM.
+
+## What this skill does NOT do
+
+- Does NOT pause / disable. There is no soft-stop; the row is gone.
+  If the user wants a temporary hiatus, tell them they'll need to
+  re-register when ready.
+- Does NOT delete entity files (`<domain>/<type-plural>/<slug>.md`)
+  produced by past runs. Those stay; the user's notes / receipts are
+  not the agent's to discard.
+- Does NOT regenerate `_activity/<source>.md`. The reconciler does.
+- Does NOT manipulate `recurring_schedules` directly. DELETE
+  `/api/managed-tasks/:id` is the chokepoint; cascade is automatic.
+- Does NOT touch §A (SoT bindings) or §C (Active Policies).
+- Does NOT PUT `rules/management.md` directly. The daemon owns the
+  file write.
+- Does NOT bulk-stop without per-row confirmation. "Stop all gmail
+  tasks" is a series of DM round-trips, one per row.
+
+## API summary
+
+| Verb + path | Used in |
+|---|---|
+| `GET /api/managed-tasks` / `/api/managed-tasks/:id` | Step 1 (lookup) |
+| `DELETE /api/managed-tasks/:id` | Step 3 (Notify-tier; destructive) |
+| `POST /api/notify` | Step 4 (user-facing confirmation) |
+
+The DELETE writes one `agent_actions` row, snapshots the file, and
+cascades the schedule — do NOT call any separate audit / cleanup
+endpoint.