@aitne-sh/aitne 0.1.0

package/agent-assets/skills/management-policy/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: management-policy
+description: Capture a durable management rule from a DM — "every morning X", "from now on when Y", or pause/resume/remove an existing one.
+when_to_use: Wires policy file + linked routine + dossier together. SKIP for one-off `schedule`, tone preferences, or single user facts (`user-profile`).
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Management Policy Capture
+
+A **management policy** is a durable, ongoing rule the user wants the
+agent to keep applying. It is NOT a one-off task.
+
+Each policy lives at `rules/policies/<slug>.md` and may link to:
+
+- `routines/custom/<slug>.md` — the cron-driven execution rulebook
+- `dossiers/<topic>.md` — where the policy's accumulating data lands
+
+A readable summary of every policy lives at `rules/policies/_index.md`,
+which the daemon's policy-index reconciler **auto-maintains** from the
+policy files on disk. The directory listing under `rules/policies/` is
+the source of truth; `_index.md` is a derived snapshot — **do not
+PATCH or PUT it by hand**. The same reconciler also re-renders the
+`## Active Policies` section in `rules/management.md` so it stays in
+sync. Both files refresh within ~10 s of any policy file write.
+
+## When to use this skill
+
+Use when the user expresses a **durable, ongoing management rule**:
+
+- "every morning, run my finance app and log the balance"
+- "from now on, when a Linear ticket lands in the Inbox project, summarize it for me"
+- "for travel, always check the weather the day before and DM me"
+- "stop doing the daily X check" → policy pause/remove
+- "actually let's resume the morning finance thing" → policy resume
+
+## When NOT to use this skill
+
+| Shape | Use instead |
+|---|---|
+| One-off "remind me at 3pm to call the bank" | `schedule` |
+| "Reply more tersely from now on" / tone, voice, style | `user-profile` (routes to `character`) |
+| "I'm an NYC-based dev" / single user fact | `user-profile` |
+| "Add a project for the Q3 roadmap" | `context` (`projects/*.md`) |
+| Pure data write — "log this transaction" | direct context write to the relevant `dossiers/<topic>.md` |
+
+If the user's request is **a recurring task with no need for a recorded
+reason** (e.g. "ping me every Monday at 9 to start standup prep"), use
+`schedule`'s recurring-schedules path. A management policy is the right
+home only when the user wants the **why** captured alongside the
+cadence so it survives a context reset.
+
+## Workflow
+
+### Step 1 — List existing policies (mandatory)
+
+Read the auto-maintained index for a quick summary, then fall back to
+the directory listing if you need authoritative state.
+
+```bash
+# Auto-maintained by the daemon — fastest read for slug / status /
+# cadence / linked routine + dossier / one-line why.
+curl -s "http://localhost:8321/api/context/rules/policies/_index"
+
+# Directory listing — authoritative source of truth. Use this if a
+# specific policy file looks newer than the index (the reconciler
+# debounces ~10 s; fresh writes may not be reflected yet).
+curl -s "http://localhost:8321/api/context/list/rules"
+```
+
+If the listing and `_index.md` rows disagree, **prefer the listing**
+and trust the next reconcile pass to refresh the index. Do **not**
+hand-PATCH `_index.md` to fix the drift — that just creates more churn.
+
+### Step 2 — Detect similarity
+
+Heuristics to compare against existing policies:
+
+| Signal | Likely interpretation |
+|---|---|
+| Same `linked.dossier` topic | Likely a duplicate or extension of an existing policy |
+| Same cron expression on the linked routine | Likely a duplicate cadence |
+| Slug stem matches an existing slug ("finance", "inbox", …) | Likely related |
+
+If a candidate matches, ask the user **before** creating:
+
+> "I already have `<existing-slug>` doing `<one-line why>` on
+> `<cadence>`. Update that one, or create a new policy?"
+
+Stop until the user picks. Do not create a duplicate silently.
+
+### Step 3 — Echo interpretation
+
+Paraphrase the rule back in **one short paragraph**:
+
+- the cadence (or trigger condition)
+- the action
+- where the data accumulates (which dossier)
+- which existing routine / dossier you'll create or extend
+
+Wait for an explicit yes. If the user corrects a detail, re-echo and
+wait again.
+
+### Step 4 — Build the policy file
+
+Emit the full `rules/policies/<slug>.md` content as a fenced markdown
+block in the DM **before** writing, so the user sees what's about to be
+saved. The slug must:
+
+- equal the filename stem
+- match `^[a-z0-9][a-z0-9-]*[a-z0-9]$` (or a single `[a-z0-9]`)
+- be ≤ 64 chars
+- equal the linked `routines/custom/<slug>.md` slug (if any) — keep
+  them aligned in v1
+
+### Step 5 — Wire the dependencies (strict order; on failure, roll back in reverse)
+
+Each step gates the next. If step `N` fails, attempt to roll back steps
+`N-1 … 1` in reverse before reporting the failure to the user.
+
+#### 5.1 Create the dossier (if it doesn't exist)
+
+```bash
+# Optional — only if the policy accumulates data into a new topic.
+curl -sS -X PUT http://localhost:8321/api/context/dossiers/<topic> \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{"content":"---\ntype: dossier\nowner: agent\nupdated: 2026-04-24\n---\n# <Topic>\n\n## Daily Log\n"}
+JSON
+```
+
+Skip this step if `linked.dossier` is not set or the dossier already
+exists. The dossier file is data only — no harm if it ends up empty
+when the rest of the flow rolls back.
+
+#### 5.2 Create the custom routine (if scheduling is needed)
+
+```bash
+curl -sS -X PUT http://localhost:8321/api/context/routines/custom/<slug> \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{"content":"---\ntype: rule\nslug: <slug>\nprocess_key: routine.custom.<slug>\ncron: \"0 7 * * *\"\nbackend_tier: light\nmax_budget_usd: 0.20\nenabled: true\n---\n# <Title>\n\n## Checks\n\n### <step label>\n**Action**: …\n"}
+JSON
+```
+
+The route's `onCustomRoutinesChanged` hook reloads the cron scheduler
+automatically — no separate reload call.
+
+Skip this step if the policy is purely passive (e.g. "from now on, when
+the user mentions X in DM, also …"). In that case the policy file
+itself documents the rule and the relevant DM/event task-flow picks it
+up via the global injection.
+
+#### 5.3 Create the policy file
+
+`origin` MUST be a **single-line** YAML scalar. The frontmatter
+extractor is line-scalar only — block scalars (`origin: |`, `origin: >`)
+are silently truncated to the marker character and the validator
+rejects them. If the user's message is too long for one line, write a
+short summary in `origin` and put the verbatim quote in a body section
+called `## Captured From`.
+
+```bash
+curl -sS -X PUT http://localhost:8321/api/context/rules/policies/<slug> \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{"content":"---\ntype: rule\nkind: policy\nowner: agent\nupdated: 2026-04-24\nslug: <slug>\nstatus: active\ncreated_at: 2026-04-24\ncreated_via: dm\norigin: \"User DM 2026-04-24T14:30Z: <one-line summary or short quote>\"\nlinked:\n  routine: <slug>\n  dossier: <topic>\ntemplate_version: 1\n---\n# <Title>\n\n## Why\n<one short paragraph>\n\n## How\n1. …\n\n## Source of Truth\n- Authoritative: …\n- Local cache: dossiers/<topic>.md\n\n## Captured From\n> <verbatim DM quote, only when too long for the origin line>\n\n## Notes\n- …\n"}
+JSON
+```
+
+The global FS-watch reconciler picks this up within ~1s and the policy
+appears in `context-index.md` automatically. The policy-index
+reconciler also fires on the same FS event (chained off the same
+debounce), so `rules/policies/_index.md` and `rules/management.md`'s
+`## Active Policies` section refresh within ~10 s — no manual PATCH
+needed.
+
+The `linked:` mapping uses nested YAML for human/LLM readability. The
+daemon's frontmatter validator does not parse nested keys, but the
+**policy-index reconciler does** — it reads `linked.routine` to
+populate the cadence column (by reading the routine file's `cron`
+field) and `linked.dossier` for the dossier column. Keep the slug
+values aligned with the filenames you created at 5.1 / 5.2 so the
+reconciler can resolve them.
+
+#### 5.4 _(no manual step required)_
+
+`rules/policies/_index.md` is auto-maintained by the daemon's
+policy-index reconciler — it re-renders within ~10 s of step 5.3's
+write. Same for the `## Active Policies` section in
+`rules/management.md`. Do not PATCH or PUT either path manually; doing
+so just races the reconciler and creates snapshot churn.
+
+If you need to confirm the index is up to date before replying to the
+user, GET `rules/policies/_index` after a short wait. The reconciler's
+last-run record lives at runtime_state key
+`reconciler.policy_index.last_run` for diagnostics.
+
+### Step 6 — Confirm to the user (one DM)
+
+Use the `notify` skill (or reply-in-channel, depending on flow) with a
+concise summary:
+
+- policy slug + cadence
+- what was created (dossier / routine / policy / index)
+- how to pause it later (e.g. "say 'pause the morning finance check'")
+
+### Step 7 — Audit
+
+Each PUT/PATCH at steps 5.1-5.4 is Autonomous (`risk-classifier.ts`,
+post-Notify-abolition). The route layer snapshots the prior file
+content into `md_file_snapshots` (trigger `api_put` / `api_patch` /
+`api_delete`) so the skill's rollback path can recover pre-edit state,
+and every write is logged to `agent_actions` for the user's on-demand
+retrospective via `GET /api/agent/actions`. Do **not** call any extra
+audit endpoint — the durable trail is already produced.
+
+## Pause / resume / remove (best-effort fan-out)
+
+Identify the policy slug from the user's wording. If ambiguous, list
+the active policies first and ask.
+
+### Pause
+
+1. GET the policy file, flip the frontmatter `status: paused` and
+   `updated: <today>`, PUT back. (The frontmatter parser is
+   line-scalar so a per-field PATCH section call would not target a
+   frontmatter key — always GET-merge-PUT for frontmatter edits.)
+2. If `linked.routine` is set: GET `routines/custom/<slug>`, flip
+   frontmatter `enabled: false`, PUT back. The reload hook flips the
+   cron job off automatically.
+
+The policy-index reconciler picks the change up on the FS event and
+re-renders both `_index.md` and the management.md section within
+~10 s. Do not PATCH them manually.
+
+If step 2 fails after step 1 succeeded, **attempt to roll back step 1**
+(`status` back to `active`). If the rollback itself fails, report the
+partial state to the user and tell them which file is in which state.
+
+### Resume
+
+Same fan-out, with `status: active` and `enabled: true`.
+
+### Remove
+
+1. GET the policy file, flip frontmatter `status: removed` and
+   `updated: <today>`, PUT back.
+2. If `linked.routine` is set: `DELETE
+   /api/context/routines/custom/<slug>` (whitelisted).
+
+The reconciler moves the row from `## Active` to `## Removed`
+automatically — the `removedAt` cell is read from the policy file's
+`updated` field, which step 1 set to today.
+
+The policy file itself is **kept for history** — DELETE on `rules/*`
+is intentionally not whitelisted (see MANAGEMENT-POLICY-CAPTURE-PLAN
+§5.1).
+
+## What this skill does NOT do
+
+- Does NOT touch `rules/management.md` body sections (Source of Truth
+  table, Notification Rules, Schedule, etc.). Those are wizard-only.
+- Does NOT create rows in the `recurring_schedules` DB table — defer to
+  `routines/custom/` for cron, which gives the user a visible MD file
+  to edit.
+- Does NOT migrate existing custom routines into policy files
+  retroactively. Migration is a separate one-time operation.
+
+## Cross-skill pointers
+
+- **Need a one-off wake-up?** Use `schedule` (`/api/schedule` or
+  `/api/schedule/dm`) — no policy file needed.
+- **Need a recurring DB-driven task with no recorded `## Why`?** Use
+  `schedule`'s `/api/recurring-schedules`.
+- **Tone / voice / language preference?** Use `user-profile`'s
+  character path (`PATCH /api/config/character`), NOT a policy file.
+
+## API summary
+
+All writes go through the standard `/api/context/*` chokepoint. No new
+endpoint exists for this skill.
+
+| Verb + path | Used in |
+|---|---|
+| `GET /api/context/rules/policies/_index` | Step 1 (read summary) |
+| `GET /api/context/list/rules` (entries prefixed `policies/` are policy files) | Step 1 (authoritative) |
+| `GET /api/context/rules/policies/<slug>` | Read before pause/resume/remove |
+| `PUT /api/context/dossiers/<topic>` | Step 5.1 (if new dossier) |
+| `PUT /api/context/routines/custom/<slug>` | Step 5.2 (if scheduling) |
+| `PUT /api/context/rules/policies/<slug>` | Step 5.3 |
+| `PATCH /api/context/rules/policies/<slug>` | Pause / resume / remove (frontmatter via GET-merge-PUT) |
+| `DELETE /api/context/routines/custom/<slug>` | Remove only |
+
+`rules/policies/_index.md` and the `## Active Policies` section in
+`rules/management.md` are written by the daemon's policy-index
+reconciler — they are NOT in the agent's write surface for this
+skill.
+
+Frontmatter validation enforces `kind: policy`, `owner: agent`, and the
+slug rules above. Malformed writes return 422 with the failing field —
+surface that text to the user verbatim rather than retrying blindly.
+
+## Policy file section shape (auto-curated)
+
+<!-- CURATION:knowledge_layout id="policy-file-shape" -->

package/agent-assets/skills/management-policy/curation.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "sections": [
+    {
+      "id": "policy-file-shape",
+      "kind": "knowledge_layout",
+      "anchor": "<!-- CURATION:knowledge_layout id=\"policy-file-shape\" -->",
+      "human_label": "Policy file section shape",
+      "description": "Required sections inside rules/policies/<slug>.md and what each holds",
+      "scope_paths": ["rules/policies/*.md"]
+    }
+  ]
+}

package/agent-assets/skills/management-policy/seeds/policy-file-shape.seed.json

@@ -0,0 +1,16 @@
+{
+  "kind": "knowledge_layout",
+  "files": [
+    {
+      "path": "rules/policies/*.md",
+      "purpose": "Durable management policy capturing why a recurring rule exists, how it runs, and where data lands",
+      "sections": [
+        { "heading": "## Why", "contains": "one short paragraph stating the motivation behind the policy" },
+        { "heading": "## How", "contains": "ordered steps describing what the policy does on each fire" },
+        { "heading": "## Source of Truth", "contains": "authoritative reference plus the local cache file under dossiers" },
+        { "heading": "## Captured From", "contains": "verbatim DM quote when the origin line is too short to hold it" },
+        { "heading": "## Notes", "contains": "operational notes, exceptions, manual override history" }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,202 @@
+---
+name: management-task-modify
+description: Change cadence, intent, or output path on an existing managed task (`mt_<n>`) from a DM — "move daily Zoom check to 9am", "switch Gmail triage to Mondays". Owns PATCH on §B rows. SKIP for new registrations, stops, or app changes.
+when_to_use: User wants to keep a managed task running but adjust its cadence / intent / output path. SKIP for new registrations (`management-task-register`), stops (`management-task-stop`), or one-off run-now (`POST /api/managed-tasks/:id/run-now`).
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# Modify a Managed Task
+
+Changes the cadence, intent, or `Output path` on an existing
+`mt_<n>` row in place. The `mt_id` is preserved across modifications
+so historical references in `agent_actions` and
+`_activity/<source>.md` remain unambiguous (§10.2).
+
+## When to use
+
+The user clearly references an existing recurring commitment and asks
+to change its **cadence**, **intent text**, or **output path**:
+
+- "Move the Zoom check to 9am instead of 10am"
+- "Switch the Gmail invoice triage to every Monday"
+- "Send Drive receipts to `finance/receipts/` instead of `personal/receipts/`"
+- "Rename the intent on `mt_42` to `Zoom recordings → meeting notes`"
+
+## When NOT to use
+
+| Shape | Use instead |
+|---|---|
+| New recurring commitment | `management-task-register` |
+| User wants to stop / pause it | `management-task-stop` (no soft-pause; hard-delete + re-register if they want to resume) |
+| User wants to run once off-schedule | `POST /api/managed-tasks/<id>/run-now` |
+| User wants to change which **app** an existing task targets | `management-task-stop` then `management-task-register` (different connector ⇒ different commitment) |
+| User wants to change the SoT for a category | `PUT /api/sot-bindings` (A-section flow) |
+
+A change of `app` is a different commitment — stop and re-register
+rather than mutating the row, because the connector probe must run
+fresh and the entity-mirror associations may differ.
+
+## Algorithm (mirror of design 21 §10.2)
+
+### Step 1 — Locate the row
+
+Read the registry and find the row the user means. If the user named
+an `mt_<n>` directly, fetch by id; otherwise dedup by `(app, cadence,
+intent)` the same way `management-task-register` does.
+
+```bash
+# By id when the user said "mt_42":
+curl -s "http://localhost:8321/api/managed-tasks/mt_42" | jq .item
+
+# By app fuzzy lookup:
+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 no row matches, DM:
+
+> No managed task for `<app>` is registered. Want me to register one?
+
+If multiple rows could plausibly match, list them with id + cadence +
+intent and ask the user to pick. Stop until they reply.
+
+### Step 2 — Diff the requested change
+
+Map the user's request to one or more of these fields:
+
+| User request | PATCH field | Notes |
+|---|---|---|
+| "9am instead of 10am" / "every Monday" | `cadence` + `recurrenceRule` (send both together) | Same `recurrenceRule` shape as `management-task-register` Step 5; only `daily`/`weekly`/`monthly` are representable |
+| "Rename intent" / "describe it as `<text>`" | `intent` | ≤ 200 chars, NFC, no `\n`, no `\|` |
+| "Send to `<dir>/`" | `output_path` | Validate against §9.3 (`<domain>/<type-plural>/`, trailing `/`, no `..`); send `null` to clear |
+
+If the request implies **app change**, stop and route the user to
+"stop + re-register" (Step 1 disambiguator above).
+
+### Step 3 — Confirm with the user before mutating (Notify tier)
+
+PATCH on a managed task is **Notify tier** (§13.1). DM the user
+verbatim with the proposed change and wait for an explicit yes:
+
+> `mt_42` Zoom check — change cadence from `daily 10:00 (Asia/Tokyo)`
+> to `daily 09:00 (Asia/Tokyo)`?
+
+Only after the user confirms do you issue the PATCH. If they decline
+or amend, restart at Step 2 with the new shape.
+
+When the user's confirmation also implies a different output path
+("…and write into `work/meetings/agendas/`"), include both fields in
+one PATCH so the audit row reflects the user's actual intent in a
+single transition.
+
+### Step 4 — PATCH /api/managed-tasks/:id
+
+```bash
+curl -sS -X PATCH http://localhost:8321/api/managed-tasks/mt_42 \
+  -H 'Content-Type: application/json' \
+  -d @- <<'JSON'
+{
+  "cadence":     "daily 09:00 (Asia/Tokyo)",
+  "recurrenceRule": {
+    "frequency": "daily",
+    "time":      "09:00",
+    "timezone":  "Asia/Tokyo"
+  }
+}
+JSON
+```
+
+| Field | When to send | Notes |
+|---|---|---|
+| `cadence` + `recurrenceRule` | Cadence change | Send both together so the rendered §B label matches the executable schedule. PATCH body must include at least one mutable field; an empty body returns `validation_error`. |
+| `intent` | Intent rename | ≤ 200 chars; trimmed + NFC at the boundary |
+| `output_path` | Output relocation | `<domain>/<type-plural>/` per §9.3; `null` clears it (back to "first run decides") |
+
+`app` / `app_normalized` / `last_run_at` / `last_result` /
+`consecutive_failures` are NOT mutable through this PATCH. Run-result
+writes go through the internal `/run-result` route used by
+`scheduled-managed-task`; app rename goes through the dedicated
+`POST /api/managed-tasks/:id/rename-app` (Step 1 disambiguator above
+already routes that case to "stop + re-register" for safety).
+
+The server-side transaction:
+
+a. UPDATEs `recurring_schedules` (if `recurrenceRule` changed),
+b. UPDATEs `managed_tasks.{intent,cadence,output_path,updated_at}`,
+c. re-renders `rules/management.md` from DB (locked + snapshotted),
+d. INSERTs `agent_actions` (`action_type='management_task.modified',
+detail={changed, from, to}`).
+
+The response is `{status:"updated", item:<ManagedTask>, render_status}`.
+
+The `mt_id`, `last_run_at`, `last_result`, and
+`consecutive_failures` are preserved across the PATCH — history is
+continuous (§10.2).
+
+A cadence change cancels any in-flight `agent_schedule` row tied to
+the old cron; the new cron takes effect from the next eligible slot.
+Do not separately DELETE `agent_schedule` items — the daemon owns
+that.
+
+**Output-path relocation does NOT move existing entity files.** Past
+entities stay where they were written. If the user wants
+re-organization, stop the task, move the entity files manually (or
+ask the user to), and re-register.
+
+### Step 5 — Confirm to user
+
+One DM, persona-tone (`notify` skill discipline applies). Read the
+resolved fields from the PATCH response — do NOT echo what you sent
+in case the daemon normalized something:
+
+> Updated `mt_42` Zoom check — now daily 09:00 JST. Next run 2026-12-05 09:00 JST.
+
+If the PATCH only changed `intent` or `output_path` (no cadence
+shift), do not announce a "next run" line — the next firing is
+unchanged.
+
+## Error envelope
+
+| HTTP | `error` | What to do |
+|---|---|---|
+| 400 | `invalid_id` | The `:id` segment didn't match `^mt_[1-9]\d*$`; the user typed the id wrong — ask them to repeat |
+| 400 | `validation_error` | Body has Zod `details`; pin the failing path (e.g. `recurrenceRule.daysOfWeek` not allowed for `daily`) and ask for a fix |
+| 404 | `not_found` | DM "I don't have an `mt_<id>` to modify"; offer to register one |
+| 5xx | `internal_error` | Surface `body.message` if present; advise `aitne logs` |
+
+The daemon does not currently emit `cron_too_tight` (the recurrence
+schema only accepts daily/weekly/monthly — sub-daily is impossible),
+nor `cadence_partial` (the recurrence rule is one structured field, so
+there is no partial-cadence shape to reject). If a future schema gain
+adds them, surface them verbatim.
+
+## What this skill does NOT do
+
+- Does NOT mutate `app` — that is a different commitment, stop +
+  re-register.
+- Does NOT pause / disable a task — there is no soft-pause; stop +
+  re-register if the user wants a hiatus.
+- 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 migrate entity files when `output_path` changes; only
+  future runs honor the new path.
+- Does NOT auto-confirm "this looks right" — Notify-tier means a real
+  user-facing confirmation in the user's preferred language.
+
+## API summary
+
+| Verb + path | Used in |
+|---|---|
+| `GET /api/managed-tasks` | Step 1 (lookup by app/cadence) |
+| `GET /api/managed-tasks/:id` | Step 1 (lookup by id) |
+| `PATCH /api/managed-tasks/:id` | Step 4 (Notify-tier) |
+| `POST /api/notify` | Step 5 (user-facing confirmation) |
+
+The PATCH writes one `agent_actions` row and snapshots the file —
+do NOT post a separate audit event yourself.