opencode-thrum-pro 0.1.0

package/assets/skills/memory-maintenance/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: memory-maintenance
+description: "Use when an agent needs to update, delete, supersede, or audit an existing memory entry — e.g., after verification, when a finding becomes stale, or when a rule needs amendment. Loads the edit/delete/history protocol + when to retire vs amend."
+---
+
+# Maintaining thrum memory entries
+
+This skill carries the canonical lifecycle operations on existing memory entries
+— edit, delete, supersede, history audit.
+
+## Editing an existing entry
+
+To update a memory entry's body, title, tags, or zoom levels:
+
+```bash
+cat > /tmp/memory-edit-body.md <<'EOF'
+<updated body>
+EOF
+thrum memory edit <id> --short "@/tmp/memory-edit-body.md"
+thrum memory edit <id> --title "<updated title>"
+thrum memory edit <id> --add-tag <new-tag>    # appends (repeatable); --rm-tag removes
+```
+
+Edits create a **history record** — the daemon retains the prior version. View
+edit history:
+
+```bash
+thrum memory history <id>
+```
+
+Each history row shows the field changed, the prior value, and the timestamp.
+
+## When to edit vs supersede
+
+| Situation                                                                                  | Action                                                                                               |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Small correction (typo, clarification, tag refinement)                                     | **Edit** — preserves the entry's identity + tracks the change in history                             |
+| The fact has changed but the topic is still relevant (e.g., updated rule, refined finding) | **Edit** — same topic, evolving content                                                              |
+| The entry is superseded by a fundamentally different fact / a redirected understanding     | **Supersede** — write a new entry, delete the old, optionally tag the new with `supersedes:<old-id>` |
+
+## Deletion
+
+```bash
+thrum memory delete <id>
+```
+
+Soft-delete by default — the entry is marked deleted but retained in the
+underlying store (recoverable via the daemon's tombstone protocol). To
+hard-purge:
+
+```bash
+thrum memory delete <id> --hard --confirm "DELETE <id>"
+```
+
+`--hard` is irreversible — it issues `memory.purge` instead of `memory.delete`,
+removing the row + tags + edges + FTS shadow and authorizing JSONL compaction on
+next sync. The `--confirm` token must equal `DELETE <id>` exactly; omitting
+`--confirm` falls through to an interactive `Type DELETE <id> to confirm:`
+prompt on stderr, which hangs in non-interactive contexts. Use only when the
+entry contains content that must be physically removed (e.g., credentials
+accidentally captured).
+
+## Staleness review
+
+For research notes that carry a `Verified: YYYY-MM-DD @ <commit-sha>` footer,
+periodic staleness review is the researcher's discipline (see
+`researcher-maintaining-memory` skill for the git-diff-based protocol). For
+role-rules, staleness is event-driven: when your behavior is corrected or
+project policy changes, edit the entry to update the `Why:` line.
+
+## Audit trail
+
+Every memory entry has a creation timestamp + a `created_by` field tracking the
+authoring agent. Edits append to history; deletions create a tombstone. The
+audit trail is queryable via:
+
+```bash
+thrum memory history <id>
+thrum memory show <id> --format json    # includes created_at, created_by, edit_count
+```
+
+## Refs to other skills
+
+- For writing new entries (including supersedes): `memory-write-discipline`
+- For finding entries by ID or topic: `memory-read-discipline`
+- Role-specific maintenance patterns (staleness checks, index file updates):
+  invoke your role's `*-maintaining-memory` skill.

package/assets/skills/memory-read-discipline/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: memory-read-discipline
+description: "Use when an agent needs to find existing memory entries - load role-rules at session start, recall a topic mid-session, or pull the full body of a specific entry. Loads the canonical 3-step zoom-escalation read pattern (scan index, triage short, fetch full on confirm) and covers the list / search / show verbs. For advanced FTS5 plus embedding search options, see also the memory-search-advanced skill."
+---
+
+# Reading thrum memory entries
+
+This skill carries the canonical read-command patterns shared by every role.
+Three distinct use cases map to three distinct verbs, all following the same
+**3-step zoom escalation**: scan the index first, triage at short zoom, fetch
+full only when confirmed.
+
+## Canonical Memory Read Flow (3 steps)
+
+1. **SCAN the index** — get onelines for all relevant records:
+
+   ```
+   thrum memory index [--scope <scope>] [--kind <kind>]
+   ```
+
+   or
+
+   ```
+   thrum memory list --zoom oneline [--scope <scope>] [--kind <kind>]
+   ```
+
+   Review titles and onelines. This is cheap — no body content loaded.
+
+2. **TRIAGE with short** — for records that look promising after the scan:
+
+   ```
+   thrum memory show <id> --zoom short
+   ```
+
+   or
+
+   ```
+   thrum memory list --zoom short --kind <kind>
+   ```
+
+   The short body (a paragraph summary) lets you confirm relevance before
+   pulling the full content.
+
+3. **FETCH full only when confirmed** — only when the short tier confirms the
+   record is what you need:
+   ```
+   thrum memory show <id> --zoom full
+   ```
+   or
+   ```
+   thrum memory show <id>
+   ```
+   (default zoom = full)
+
+**Rule:** Never jump straight to `--zoom full` or `--format body` without first
+scanning and triaging. The index + short tiers exist to save context tokens.
+
+## Use case 1: Session-start enumeration of role-rules
+
+To load all role-rules at session start (scope + kind known in advance):
+
+```bash
+# Step 1: scan index
+thrum memory list --zoom oneline --kind agent_rule --scope role
+```
+
+The `--scope role` filter auto-infers your role via daemon identity binding (no
+`:role:<role-name>` qualifier needed). Output shows one record per line with
+`body_oneline` only — scannable.
+
+To narrow further by tag (`list` has no tag filter; use `search`):
+
+```bash
+thrum memory search --kind agent_rule --scope role --tag <slug>
+```
+
+If a specific rule looks relevant after the index scan, triage it:
+
+```bash
+thrum memory show <id> --zoom short
+# If still not enough detail:
+thrum memory show <id> --zoom full
+```
+
+## Use case 2: Topic-driven recall
+
+For a topic without a known specific entry, follow all 3 steps:
+
+```bash
+# Step 1: scan
+thrum memory search "<topic keywords>"
+
+# Step 2: triage promising hits
+thrum memory show <id> --zoom short
+
+# Step 3: fetch confirmed entries
+thrum memory show <id> --zoom full
+```
+
+`search` invokes FTS5 + (when wired) embedding search. Multi-word queries are
+honored. Optional filters:
+
+```bash
+thrum memory search "<topic>" --kind research_note    # filter by kind
+thrum memory search "<topic>" --tag <slug>            # filter by tag
+thrum memory search "<topic>" --since 30d             # filter by recency
+```
+
+Default render: ranked summaries, each showing `body_oneline` only. The deeper
+zoom levels are NOT polluted into search results — triage with `--zoom short`
+before fetching full.
+
+## Use case 3: Pulling the full body of a specific entry
+
+When you already know the entry ID (e.g. from a prior search or the index):
+
+```bash
+# Step 2: triage (skip if you already know this is the right entry)
+thrum memory show <id> --zoom short
+
+# Step 3: fetch full body
+thrum memory show <id> --zoom full
+# equivalently:
+thrum memory show <id>
+```
+
+Default format (text) renders metadata fields (ID, Kind, Status, Scope, Agent,
+Created, Updated, Tags, Parent) plus all zoom levels present in the entry
+(title, oneline, short, full). To pull just the body:
+
+```bash
+thrum memory show <id> --zoom full  # preferred — explicit zoom
+thrum memory show <id> --format json | jq -r '.body_full'  # JSON extraction
+```
+
+## Cross-scope reads
+
+Default scope filter (when `--scope` is omitted) returns all scopes the caller
+can access. To explicitly read other roles' rules:
+
+```bash
+thrum memory list --zoom oneline --kind agent_rule --scope role          # YOUR role (identity-inferred)
+thrum memory list --zoom oneline --kind agent_rule --scope project       # project-wide rules
+thrum memory list --zoom oneline --kind agent_rule                       # all visible scopes
+```
+
+The CLI does not expose `--scope role:<other-role>` filtering. To inspect
+another role's rules, query the broader scope and grep the result (or narrow
+with `thrum memory search --tag <slug>`).
+
+## Output discipline
+
+Default multi-record output (from `list` and `search`) prints `body_oneline`
+only — this is the right zoom level for scanning a result set. Don't pull deeper
+zoom levels for a whole result set; use `show <id> --zoom short` then
+`show <id> --zoom full` for specific entries you need.
+
+## Refs to other skills
+
+- For writing new entries: `memory-write-discipline`
+- For deleting / editing / superseding entries: `memory-maintenance`
+- For advanced FTS5 + embedding search options: `memory-search-advanced`
+- Role-specific read patterns (session-start sequences, etc.): invoke your
+  role's `*-maintaining-memory` skill.

package/assets/skills/memory-search-advanced/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: memory-search-advanced
+description: "Use when running thrum memory search with RAG (--near), composing complex predicate stacks, paginating large result sets, interpreting MEM-001..010 hint codes, or diagnosing embedding adapter behavior. Loads three-vector ranking semantics, length-bias caveat, and the full hint catalog."
+allowed-tools: "Bash(thrum memory:*),Bash(thrum config:*)"
+version: "0.11.0"
+license: "Apache-2.0"
+---
+
+# memory-search-advanced — RAG, hint codes, complex predicates
+
+Load this sub-skill from `thrum-memory` (umbrella) for predicate needs beyond
+tag + kind + recency filtering.
+
+## Predicate surface (shipped)
+
+`thrum memory search` combines all predicates with AND:
+
+```text
+Query:
+  positional args — FTS query text; `thrum memory search "<topic>"` is
+  equivalent to --grep "<topic>" (multiple args join with single spaces;
+  giving both positional and --grep is refused as ambiguous)
+
+Identity / structure:
+  --kind <kind>, --tag <tag> (SINGLE tag per query), --scope project|agent|role,
+  --status <status> ("*" for any; default active)
+
+Text:
+  --grep <terms> (full-text MATCH over title + body_oneline/short/full;
+  terms matched literally — punctuation is not FTS5 operators)
+
+Semantic (when embedding adapter enabled):
+  --near "<text>"
+
+Time:
+  --since 7d | <Go duration> | <RFC3339>
+
+Sort & limit:
+  --sort created_at_desc|updated_at_desc|relevance|pinned_first
+  --limit 10 (default)
+  --offset N
+```
+
+Output formats: `table` (default), `ids`, `oneline`, `short`, `full`, `json`.
+
+Tag-set OR is NOT expressible in one query — `--tag` takes a single tag. For OR
+semantics, run one search per tag and merge.
+
+## DESIGNED — NOT YET SHIPPED (do not use)
+
+The original memory-search design specifies a wider predicate surface that the
+shipped CLI does not implement. The flags below DO NOT EXIST today — the CLI
+rejects them with `unknown flag`. They are recorded here as the spec diff for
+the eventual search-surface implementer, NOT as usable commands:
+
+```text
+--id, --kinds (multi-kind), --subkind, --agent / --author, --pinned,
+--tags-any (tag-set OR),
+--since-created, --since-updated, --until,
+--parent <id>, --supersedes <id>, --superseded-by <id>,
+--related-to <id>, --derived-from <id>,
+--grep-field <oneline|short|full|title>, --regex,
+--near-id <id>, --near-limit N
+```
+
+Workarounds with the shipped surface: time filtering = `--since` only (no
+created-vs-updated split); per-field grep = not available (grep spans title +
+all three zooms); edge predicates = not available (edge reads are the
+`memory.listByEdge` RPC, no CLI); `--pinned` = `--tag pinned` (pinned is a
+tag).
+
+## Pagination patterns
+
+Default `--limit 10` keeps context bounded. Walk a large set:
+
+```bash
+thrum memory search --kind session_summary --since 30d --limit 25 --offset 0
+thrum memory search --kind session_summary --since 30d --limit 25 --offset 25
+```
+
+For counting: `thrum memory count` is the cheap O(1) counter, but it counts by
+`--agent` / `--role` only — it accepts NO kind/time filters. To count a filtered
+set, read the `total` field from the JSON response (a separate COUNT query,
+computed before LIMIT applies):
+
+```bash
+thrum memory count --role researcher                  # cheap, coarse
+thrum memory search --kind session_summary --since 30d \
+  --limit 1 --format json | jq '.total'               # filtered count
+```
+
+Do NOT count via `--limit 0 --format ids | wc -l` — the `--limit 0`
+streaming/export reservation is currently non-functional (the CLI drops
+`limit=0` from the RPC params and the daemon clamps the absent limit to 10, so
+output caps at 10 rows regardless of the real match count).
+
+## RAG semantics (`--near`)
+
+`--near "<text>"` runs semantic search against memory embeddings. Three
+per-memory vectors are stored — one per zoom level, embedding the title-prefixed
+string:
+
+- `<title> — <body_oneline>`
+- `<title> — <body_short>`
+- `<title> — <body_full>`
+
+Ranking is `score = max(sim_oneline, sim_short, sim_full)`. Each result carries
+`matched_zoom` so the CLI can render the zoom level that actually matched.
+Per-zoom embeddings let topical queries dock against `oneline` while
+deep-content queries dock against `full`.
+
+### Length-bias caveat — read before trusting `--near` results
+
+Title-prefixed `oneline` strings (~40-50 chars) and `body_full` (up to 256 KB)
+embed in different subspaces of `granite-30m-english`'s 384-dim space. **Short
+queries can systematically match `oneline` over `full` for length-similarity
+reasons rather than semantic-relevance reasons.** This is a real bias inherited
+from the embedding model.
+
+Detection and recovery (manual in v1; a future MEM-011+ zoom-divergence
+detector is reserved for this case; the shipped MEM-008 is the
+embed-enqueue-failed warning, not a zoom-divergence detector):
+
+- Inspect `matched_zoom` in each result. If short queries return rows dominated
+  by `matched_zoom=oneline`, the ranking may have been misled.
+- Re-run with a longer query phrasing.
+- Add `--kind <X>` to narrow before semantic re-rank.
+- Inspect the full body manually, following the shared 3-step read pattern
+  (`memory-read-discipline`): triage with `thrum memory show <id> --zoom short`
+  first, then fetch with `thrum memory show <id> --zoom full` once confirmed.
+
+Mitigations weighed and deferred (don't reach for them yet): weighted
+combination, cross-encoder re-rank, per-kind length normalization. v1 ships
+max-of-three; tune later only if `matched_zoom` diagnostics surface systematic
+problems.
+
+## Hint codes (MEM-001..010)
+
+Hints render as a `hints` array in `--json` mode and as inline notices in human
+mode. Suppress everywhere with `THRUM_NO_HINTS=1`. Severity is `warn` for
+blocking-shaped advice, `info` for nudges.
+
+| Code      | Trigger                                                           | What it tells you                                                    |
+| --------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `MEM-001` | search returned >50 matches                                       | Narrow with `--kind` / `--tag` / `--since`                           |
+| `MEM-002` | `--near` supplied without `--kind`                                | Add `--kind` to narrow before semantic re-rank (deferred)            |
+| `MEM-003` | empty result with two or more narrowing predicates                | Drop the most-restrictive flag                                       |
+| `MEM-004` | `--near` with embedding adapter disabled                          | Hard refusal — enable the adapter (see setup below)                  |
+| `MEM-005` | `--grep` matched nothing AND field is empty for most rows of kind | Broaden: drop `--kind`                                               |
+| `MEM-006` | `--near` found rows with `embed_status=pending` → FTS fallback    | Wait for backfill or run `memory.embed.rebuild` (deferred)           |
+| `MEM-007` | `--near` skipped rows whose `embedding_model` ≠ configured model  | Run backfill to migrate vectors (deferred)                           |
+| `MEM-008` | `memory.create` enqueue to embed worker failed                    | Best-effort; the worker will retry via `memory.embed.rebuild`        |
+| `MEM-009` | `memory.edit` projection detected concurrent edit; LWW loser      | Loser's value is preserved in `memory.history` (deferred surfacing)  |
+| `MEM-010` | `memory.create` omitted `body_short` or `body_full`               | Three-zoom retrieval works better with all three; non-blocking nudge |
+
+**Deferred triggers:** MEM-002, MEM-006, MEM-007 are registered today but the
+emission path lights up in a future epic (`--near` adapter wiring +
+multi-model support). MEM-009 emission lights up when LWW-loser surfacing
+lands in the projection response. The codes are stable; only the trigger
+conditions are in flight.
+
+**Hard refusal:** MEM-004 is the only hint with `AllowForce=false`. There is no
+recovery flag — the adapter is either present or absent.
+
+## Embedding adapter awareness
+
+`--near` only works when the embedding adapter is enabled:
+
+```bash
+thrum config set llm.embedding.enabled true
+thrum config set llm.embedding.provider ollama
+thrum config set llm.embedding.base_url http://localhost:11434
+thrum config set llm.embedding.model "granite-embedding:30m-english"
+```
+
+Embedding work is queued on write (OS-nice `+10`, single-flight per memory_id,
+exponential backoff). Writes never block on embedding. Searches degrade
+gracefully to FTS for not-yet-embedded rows and surface MEM-006 when the
+degradation happens.
+
+Edits mark only affected zoom-levels as `embed_status=stale`; tag-only edits
+re-embed nothing, title-only edits re-embed all three. Old vectors stay
+queryable during the staleness window.
+
+Cold-start backfill runs once on the first daemon boot with the adapter enabled.
+Disable with `embedding.backfill_on_boot: false`; rate-limit via
+`embedding.max_per_minute` (default 60).
+
+## Composing complex predicates
+
+Stack predicates left-to-right; they AND. Use `--scope` only when you
+specifically want to filter by assembly scope (it is NOT visibility — see
+umbrella skill).
+
+Example: every active arch decision tagged `substrate`, edited recently,
+semantically related to "RPC routing" (tag-set OR = one query per tag):
+
+```bash
+thrum memory search \
+  --kind arch_decision \
+  --tag substrate \
+  --status active \
+  --since 14d \
+  --near "RPC routing" \
+  --limit 25
+```
+
+Example: every superseded session summary that touched a given epic, paged:
+
+```bash
+thrum memory search \
+  --kind session_summary \
+  --status superseded \
+  --tag epic-thrum-abc \
+  --sort updated_at_desc \
+  --limit 50 --offset 0
+```

package/assets/skills/memory-write-discipline/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: memory-write-discipline
+description: "Use when an agent needs to capture a new memory entry — a rule, a research finding, an observation. Loads the canonical write-command shape, body conventions, title prose convention, tags-as-slug pattern, and scope semantics. Common across all roles that write memory."
+---
+
+# Writing thrum memory entries
+
+This skill carries the canonical write-command shape + content discipline shared
+by every role that writes memory. Per-role skills
+(researcher/coordinator/implementer-maintaining-memory) reference this skill for
+the write-command basics and add role-specific guidance (when to write,
+role-specific kinds, etc.).
+
+## Canonical write command
+
+```bash
+cat > /tmp/memory-body.md <<'EOF'
+<body — rule + Why + How to apply, or finding + cites>
+EOF
+thrum memory create --kind <K> --scope <S> \
+  --title "<short prose title — what this entry says>" \
+  --oneline "<one-line summary, ≤280 bytes>" \
+  --short "@/tmp/memory-body.md" \
+  --tag <slug-or-keyword> [--tag <additional-tag>]
+```
+
+`--short`/`--full` carry real prose — compose via heredoc or file, never
+double-quoted inline; see the role preamble's 🔴 PROSE INTO A COMMAND rule.
+
+Three flags are **REQUIRED** (schema NOT NULL): `--kind`, `--title`,
+`--oneline`. The daemon rejects any `memory.create` call missing these.
+`--short` and `--full` are optional but strongly encouraged — omitting both
+surfaces the MEM-010 hint ("created without all three zoom levels") and degrades
+future retrieval.
+
+## Body shape conventions
+
+**For role-rules (`--kind agent_rule`):**
+
+```text
+<rule statement — one sentence>
+
+Why: <reason — past incident, project policy, or strong preference>
+How to apply: <when/where this kicks in>
+```
+
+Lead with the rule itself; the `Why:` line is what future-you needs to judge
+edge cases the rule doesn't literally cover. This shape matches the previous
+bd-remember convention by design.
+
+**For research notes (`--kind research_note`):**
+
+```text
+<finding statement>
+
+Evidence: <file:line citations or external links>
+Verified: YYYY-MM-DD @ <commit-sha>
+```
+
+The Verified-stamp footer enables staleness checks via git diff (see
+`researcher-maintaining-memory` skill).
+
+**For other kinds (`arch_decision`, `project_note`, `epic_status`, etc.):**
+Free-form body matching the kind's semantic. Lead with the decision/observation
+itself, then context.
+
+## Title shape
+
+**Free-form prose**, ~80 character soft limit. The title appears in every
+`thrum memory list` output, so optimize for human scanability:
+
+- GOOD: `"Coordinator must verify implementer findings before forwarding"`
+- GOOD: `"safecmd.Bd 2-return signature mirrors safecmd.Tmux"`
+- GOOD: `"thrum-bot Telegram group monitored by the operator"`
+- AVOID slug-style or role-prefixed: `"coord-verify-findings"` — slug belongs in
+  `--tag`, not title.
+
+## Tags as the slug-style handle
+
+Per-entry slug (kebab-case keywords describing the topic) lives in `--tag`, not
+the title. This preserves the bd-key-suffix convention as a grep/filter handle:
+
+```bash
+thrum memory create --kind agent_rule --scope role \
+  --title "Implementer must use safecmd.Bd not raw exec for bd calls" \
+  --oneline "Daemon-adjacent bd invocations must use safecmd.Bd helper" \
+  --short "..." \
+  --tag safecmd-bd --tag daemon-discipline
+```
+
+Multiple tags are valid — repeat `--tag` per tag. The slug-as-tag pattern lets
+`thrum memory search --tag safecmd-bd` find the entry by its conceptual key.
+
+## Scope semantics
+
+`--scope` accepts three values: `project | agent | role`. The CLI auto-infers
+identity from the caller's daemon binding — there is NO `:role:<role-name>`
+shape.
+
+| Scope     | Use for                                           | Visibility                                                              |
+| --------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `role`    | Role-rules, role-specific guidance                | All agents sharing this role; preferred default for `agent_rule` writes |
+| `agent`   | Private rules / notes for this agent instance     | Only this agent (by agent_id)                                           |
+| `project` | Shared knowledge across all agents in the project | Every agent in the project                                              |
+
+For role-rules, **always use `--scope role`**. The daemon's identity binding
+ensures the entry is scoped to the caller's role automatically; no further
+qualifier needed.
+
+## Zoom-level discipline (oneline / short / full)
+
+Per the v0.11 substrate design, memory entries support three body zoom levels:
+
+| Field          | Length budget | Purpose                                                       |
+| -------------- | ------------- | ------------------------------------------------------------- |
+| `body_oneline` | ≤280 bytes    | Default search/list render — must convey the gist in one line |
+| `body_short`   | ≤4 KB         | Mid-zoom — default `show <id>` render                         |
+| `body_full`    | ≤256 KB       | Deep zoom — full body via `show <id> --format body`           |
+
+Populate all three when authoring. Skipping `body_short` and `body_full`
+triggers MEM-010 ("created without all three zoom levels") and degrades
+retrieval quality — search ranks by all three fields, and shallow entries are
+less discoverable.
+
+For role-rules, the typical shape: `oneline` = the rule one-liner, `short` =
+rule + Why + How-to-apply, `full` = `short` if no longer body needed (or omit
+`full`).
+
+## Refs to other skills
+
+- For loading + querying memory: `memory-read-discipline`
+- For deleting / editing / superseding: `memory-maintenance`
+- Role-specific write triggers + extensions: invoke
+  `researcher-maintaining-memory`, `coordinator-maintaining-memory`, or
+  `implementer-maintaining-memory` based on your role.