opencode-thrum-pro 0.1.0

package/assets/skills/implementer-receiving-review-feedback/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: implementer-receiving-review-feedback
+description: "Use when receiving review findings, when a reviewer flagged an issue, during a review cycle, or when responding to review. Loads implementer-specific discipline that complements superpowers:receiving-code-review."
+---
+
+# Implementer: Receiving Review Feedback
+
+This skill **complements** `superpowers:receiving-code-review` — it does not
+restate the technical-rigor and no-performative-agreement content from that
+skill. Layer the rules below on top of those universals.
+
+## The review gate is a hard stop, not a suggestion
+
+**Why:** Review gates exist because unreviewed code from one epic may require
+substantial changes before the next epic can build on it. Starting the next epic
+before the current one is reviewed creates compounding rework — when round-2
+fixes land in epic N, the early work on epic N+1 may need to be redone or
+reverted.
+
+**How to apply:** After sending DONE/DONE_WITH_CONCERNS for an epic: close beads
+tasks for that epic, ensure work is durably preserved per project policy, then
+enter idle. Do not claim tasks in the next epic. Do not pre-read its spec
+section. Do not "just start the trivial first task". Wait for the coordinator's
+explicit GREENLIT or APPROVED message.
+
+## Batch all review fixes into ONE commit
+
+**Why:** A single fix commit makes re-review straightforward — the coordinator
+inspects one diff against the numbered finding list. Per-finding commits multiply the surface the re-review has to traverse
+and increase the chance that a finding fixed in commit A is regressed by commit
+B.
+
+**How to apply:** Read the full numbered finding list before writing any code.
+Fix all BLOCKING and IMPORTANT findings in scope. Run tests once they're all
+addressed. Commit with a message that lists each finding number and its
+resolution:
+
+```bash
+git commit -m "$(cat <<'EOF'
+fix: address review findings #1-#5 for <task-id>
+
+- #1 (BLOCKING) — <one-line resolution>
+- #2 (IMPORTANT) — <one-line resolution>
+- #3 (LOW) — <one-line resolution>
+- #4 (LOW) — verified false positive: <one-line evidence>
+- #5 (LOW) — deferred per <decision/rationale>
+
+make test PASS (race), make lint PASS.
+
+Refs: <task-id>
+EOF
+)"
+```
+
+If a finding is truly independent and the coordinator explicitly requested
+separate commits, that's the only time to fragment.
+
+## Don't reflexively bucket findings as "follow-ups"
+
+**Why:** When the file you're already modifying contains a small adjacent issue,
+deferring it to a follow-up issue is often the wrong trade. The marginal cost of
+fixing it now is small (the file is already in your context, you already
+understand the surrounding code). The cost of a future follow-up is real
+(re-load context, re-read neighbors, redo verification). Default to fix-now when
+the file is already being touched.
+
+**How to apply:** For each finding categorized as "could defer", run the
+trade-off explicitly:
+
+- Is the file already in the diff? Default to fix-now
+- Is the fix a few lines? Default to fix-now
+- Does verification require running the same tests as the main fix? Default to
+  fix-now
+- Is the fix a meaningful refactor or design change? Defer is legitimate; file
+  the bd issue and link it in the commit message
+
+Don't reach for "deferred" as a shortcut to ship faster.
+
+## Push back with file:line evidence when the reviewer is wrong
+
+**Why:** Reviewers reading large diffs sometimes cite wrong line numbers,
+describe behavior that doesn't match the current code, or apply a universal rule
+to a project-specific exception. Pushback is welcome — it's how the feedback
+loop stays calibrated. But pushback without verification is just
+opinion against opinion.
+
+**How to apply:** When you disagree with a finding, verify against the source
+first:
+
+- For file/line claims: read the cited file at the cited lines, paste the actual
+  content
+- For API claims: grep for the symbol, paste the signature
+- For behavior claims: trace the call path and cite the relevant function
+
+Format pushback as: "Finding #N — verified false positive. <one-line
+restatement of what reviewer said>. Actual: <what the code does>, evidence at
+`<file>:<line>`." Then ask the coordinator to drop or restate. If after
+verification you're still convinced the finding is right, go fix it.
+
+## Re-review after fixes — don't ship the round-2 fix as DONE on round 1
+
+**Why:** When the coordinator dispatches re-review on the round-2 commit, they
+expect to find a clean diff from your fix work. Accidentally bundling unrelated
+changes into the fix commit muddies the review and either gets sent back or
+merges work the coordinator hasn't seen.
+
+**How to apply:** Between round-1 review feedback and round-2 ping:
+
+1. Fix only what the findings ask for
+2. Don't refactor, rename, or "improve" surrounding code
+3. Verify tests pass with `-race`
+4. Commit and ping with the per-finding disposition format from
+   `implementer-status-and-handoff`
+
+If you see additional issues during the fix work that weren't in the findings
+list, file them as bd issues — don't slip them into the fix commit.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `implementer-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.

package/assets/skills/implementer-status-and-handoff/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: implementer-status-and-handoff
+description: "Use when reporting status to the coordinator, marking a task done, or handing off completed work. Loads implementer-specific discipline for closing the loop cleanly."
+---
+
+# Implementer: Status and Handoff
+
+## Use the four-token status vocabulary exactly
+
+**Why:** The coordinator uses your status token to decide whether to proceed,
+hold for review, or unblock. Vague reports like "I finished the work"
+or "mostly done" force the coordinator to re-read the full implementation to
+judge state, which adds latency to every dispatch they manage. The token is a
+100ms decision instead of a five-minute re-read.
+
+**How to apply:** Every completion or escalation message starts with exactly one
+of:
+
+| Token                | Meaning                                                          | Send when                                                    |
+| -------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
+| `DONE`               | All tasks complete, tests pass, work committed, ready for review | Standard completion path                                     |
+| `DONE_WITH_CONCERNS` | Done but with caveats the coordinator should see                 | Unresolved finding, architectural concern, iteration cap hit |
+| `NEEDS_CONTEXT`      | Cannot proceed without more information                          | Missing design decision, ambiguous spec, unclear scope       |
+| `BLOCKED`            | Cannot proceed — external dependency or tooling issue            | Cross-epic dependency, test infra broken, auth problem       |
+
+For anything other than `DONE`, include a brief reason. For `BLOCKED`, state
+exactly what would unblock you.
+
+## Commit per task with the bead ID in the trailer
+
+**Why:** Beads links commits to issues via `Refs: <id>` trailers in the commit
+message body. Skipping the trailer breaks the audit chain; using the
+parent epic ID instead of the specific task ID flags as a traceability nit
+during review. Per-task commits also keep the diff small enough that the
+dual-review pass can reason about it without context exhaustion.
+
+**How to apply:** Commit after each closed task — not in bulk at the end. Use
+the heredoc form so the trailer renders correctly:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>(<scope>): <description>
+
+Refs: <task-id>
+EOF
+)"
+```
+
+Use the **subtask** ID (`thrum-abc.1`), not the parent epic ID. Run
+`bd show <task-id>` before committing if you need to confirm the ID.
+
+## Push your branch before reporting DONE
+
+**Why:** once you exit, your in-session context is gone and the pushed branch is
+the only artifact that survives you. An unpushed branch is unreachable from every
+other machine and indistinguishable from work that was lost.
+
+**How to apply:** commit, then push. Every time.
+
+```bash
+git push origin <branch>
+```
+
+Report the result as one line:
+
+```text
+Branch pushed: <branch-name> @ <sha> (git ls-remote origin refs/heads/<branch-name> confirms)
+```
+
+**Never push `thrum-agents`, `main`, or `website-dev`** — the coordinator merges
+those.
+
+Never report DONE with the push status silently omitted — an orchestrator
+that removes a worktree assuming "DONE implies pushed" on a project that
+does NOT push feature branches would destroy the only copy of the work.
+
+## Mark queue items done as you commit, push, and report
+
+As each step lands, mark its queue item `done`. Do NOT `drop` the bundle at your own
+DONE report — a review finding can reopen the task (`start` reopens a done bundle).
+Drop the bundle only once the coordinator confirms the merge landed (R1); until then
+it is your live record of what's addressed vs. still open.
+
+## Cite SHAs and per-finding dispositions in status messages
+
+**Why:** A vague status message ("addressed all findings", "done with the
+changes") forces the coordinator to re-read your diff to verify each finding was
+handled. A status message with concrete SHAs and per-finding dispositions is a
+30-second confirmation. The cost is the same on your side; the time saved is the
+coordinator's.
+
+**How to apply:** Cite the commit SHA(s) and one disposition per finding:
+
+```text
+DONE: Epic <id> review fixes complete.
+
+Commits: <SHA1> <SHA2>
+
+Per-finding disposition:
+- #1 (BLOCKING, file:line) — fixed at <SHA>
+- #2 (IMPORTANT, file:line) — fixed at <SHA>
+- #3 (LOW) — verified false positive: <one-line evidence>
+- #4 (LOW) — deferred per <decision/rationale>
+
+make test PASS (race), make lint PASS.
+```
+
+For first-pass DONE (not review-fix), cite the closing SHA and the test result.
+
+## Close beads tasks with `--suggest-next` when relevant
+
+**Why:** `bd close <id>` works fine, but `bd close <id> --suggest-next` prints
+newly-unblocked downstream issues immediately. If you're in the middle of an
+epic, the next task is often the most useful next move; the flag saves a
+`bd ready` round-trip.
+
+**How to apply:** When closing a task that has dependents, use
+`bd close <id> --suggest-next`. For the last task in an epic where you're
+stopping at a review gate, plain `bd close` is fine — you're not picking up the
+next task anyway.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `implementer-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.
+
+## Pattern D self-write — set `agent_status=idle` on DONE handoff
+
+When reporting DONE to the coordinator, write `agent_status="idle"` to your
+local identity file. This closes the `working→idle` transition opened by the ACK
+template's `set-status working` (sibling skill
+`implementer-receiving-dispatch`). The sweep script reads this field to
+distinguish "agent finished cleanly" from "agent stuck claiming to work" — see
+`coordinator-context-monitoring` SKILL.md for the tier-ladder consumption.
+
+```bash
+# Step 1: Report DONE to coordinator
+thrum send --to @your_coordinator --stdin <<'EOF'
+DONE: <task-id>. <one-line summary>. Commits: <SHA1>, <SHA2>.
+EOF
+
+# Step 2: Mark yourself idle (RPC-preferred; falls back to a local identity-file write if the daemon is unreachable)
+thrum agent set-status idle
+```
+
+The local-write path is identical to the ACK side.

package/assets/skills/implementer-tdd-and-quality/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: implementer-tdd-and-quality
+description: "Use when writing tests, running tests, hitting a quality gate, or before reporting a task done. Loads project-specific test and quality discipline that complements superpowers:test-driven-development."
+---
+
+# Implementer: TDD and Quality
+
+This skill **complements** `superpowers:test-driven-development` — it does not
+restate the red-green-refactor discipline, the iron law on watching tests fail,
+or any other content from that skill. Layer this content on top of those
+universals: the rules below capture project-specific Go conventions and
+quality-gate practice.
+
+## Race detector is mandatory
+
+**Why:** Thrum's daemon has significant concurrent state (goroutines for
+WebSocket, Unix socket, sync, telegram bridge, peer transport). Race conditions
+that pass bare `go test` fail under `-race` — sometimes with silent data
+corruption that takes hours to track down later. The
+Makefile's `make test` includes `-race` by default for exactly this reason.
+
+**How to apply:** Always run `go test -race ./...` (or scope to specific
+packages with `-race`). Never report tests passing without having run with
+`-race`. For a specific package:
+`go test ./internal/daemon/... -race -count=1 -timeout=120s`. For everything:
+`make test`.
+
+## Scope test runs to packages you touched
+
+**Why:** Running the entire test tree on every iteration of a fix-test loop is
+wasteful — most packages weren't touched and their tests will pass identically
+every iteration. Scoping speeds the inner loop without sacrificing correctness;
+the full tree gets one final run before reporting done.
+
+**How to apply:** During the inner fix-test loop, run only the affected
+packages: `go test -race ./internal/<pkg>/... -run <TestName>`. Once the scoped
+tests pass and you're ready to report done, run `make test` once to confirm
+nothing else broke.
+
+## Use `t.TempDir()` for filesystem fixtures — never hardcoded paths
+
+**Why:** Hardcoded absolute paths (especially the implementer's home directory)
+only work on one machine. A test that bakes in a literal path like
+`<repo-root>` passes locally and fails everywhere else — the fix is usually as
+small as swapping in `t.TempDir()`. The same pattern shows up with
+`os.UserHomeDir()` results being baked into expected values.
+
+**How to apply:** Any test that creates a temporary directory, writes files, or
+needs an isolated git repo must use `t.TempDir()`. It is cleaned up
+automatically and is unique per test run. If you need a git repo, initialize it
+in the temp dir: `cmd := exec.Command("git", "init", t.TempDir())`. For fixtures
+comparing paths, capture the temp dir into a variable and reference it in
+expected values — never hardcode.
+
+## Avoid `go vet ./...` regressions before reporting
+
+**Why:** `go vet` catches a class of bugs that compile but are wrong:
+unreachable code, suspicious type conversions, malformed printf args. Lint-clean
+code that fails `vet` will get caught in CI or by review; running `vet` locally
+catches it pre-commit when the fix is one line.
+
+**How to apply:** Before reporting done, run `go vet ./...` and `make lint`.
+Both should pass clean. If a `vet` finding looks like a false positive, prefer a
+small annotation or refactor to silencing the warning.
+
+## Two-stage self-review before pinging the coordinator
+
+**Why:** A self-review pass before the coordinator's dual review reduces total
+review round-trips. Self-review is not ceremony; it pre-pays the cost of issues
+that would otherwise come back as findings.
+
+**How to apply:** At task close, before sending DONE:
+
+1. **Spec compliance pass.** Read each acceptance criterion from the task
+   description. For every test case the spec mentions, verify it exists in the
+   test file. For every behavior change the spec specifies, verify it's
+   implemented and tested.
+2. **Code quality pass.** Read your full diff
+   (`git --no-pager diff <base>...HEAD`). Watch for: hardcoded paths,
+   `os.UserHomeDir` baked into tests, inline `exec.Command` calls that should
+   use `safecmd`, swallowed errors, missing `slog` calls on recoverable
+   failures.
+3. **Primitive ledger pass.** If this diff adds I/O or SQL under a hot root
+   (`Handle*`/tick/sweeper/`SyncApplier`/boot — see `.thrum/hotpath-gate.json`'s
+   `lenses.existing_primitive_bypass.hot_root_indicators`), confirm you have a ledger row: raw op -> callee
+   package searched -> primitive adopted, or none exists + bounded cost formula
+   (frequency x production cardinality, at production scale). Include it in
+   your DONE report.
+
+Fix what you find before sending the ping.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `implementer-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.

package/assets/skills/memory-audit-recover/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: memory-audit-recover
+description: "Use when investigating change history (`memory history`), recovering a soft-deleted memory, recovering the losing side of a concurrent edit (MEM-009 LWW loser), or running a confirmed hard-delete. Loads the audit walk, LWW conflict-resolution semantics, undelete flow, and the `Type DELETE <id>` hard-delete gate."
+allowed-tools: "Bash(thrum memory:*)"
+version: "0.11.0"
+license: "Apache-2.0"
+---
+
+# memory-audit-recover — history, undelete, hard-delete
+
+Load this sub-skill from `thrum-memory` (umbrella) to look back at what changed
+or recover something that was deleted or overwritten.
+
+## The JSONL is the audit log
+
+Every event (`memory.create`, `memory.edit`, `memory.delete`, `memory.edge.add`,
+`memory.edge.remove`, `memory.purge_executed`) appends to the author's
+`memories/<agent_id>.jsonl`. Replay rebuilds the projection; the JSONL itself
+never mutates. That makes the audit trail authoritative.
+
+Walk the history of one memory:
+
+```bash
+thrum memory history <id>            # all events touching this memory, chronological
+thrum memory history <id> --diff     # unified diff of each edit's fields
+```
+
+Projection stores `created_at` (first-event ts), `updated_at` (latest-event ts),
+`created_by` (first-event author), and `last_edited_by` (latest-event author).
+The full event timeline always comes from JSONL replay — per-memory event count
+is typically <10, so replay is cheap.
+
+Provenance now lives in the durable `memory-events-v2/` lane and is read by
+`memory history` directly — it survives events.jsonl compaction and cold boot.
+
+## Conflict resolution (LWW by event ULID)
+
+Memories use last-write-wins by event ULID — **not** semantic priority. ULID is
+monotonic-ish and globally comparable; the larger ULID wins.
+
+| Scenario                                                                        | Result                                                   |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Concurrent edits to disjoint fields                                             | Both apply (no conflict).                                |
+| Concurrent edits to the SAME field                                              | Larger-ULID event wins. Loser preserved in JSONL.        |
+| Concurrent tombstones                                                           | Idempotent. One delete-event wins by ts; status=purged.  |
+| Edit + delete, delete-ULID > edit-ULID                                          | Final `status=purged`.                                   |
+| Edit + delete, edit-ULID > delete-ULID AND edit explicitly sets `status=active` | Edit wins → `status=active` (undelete).                  |
+| Edit + delete, edit-ULID > delete-ULID AND edit does NOT touch `status`         | Patch applies to body/tags but `status=purged` persists. |
+
+LWW is acceptable here because memories aren't a high-write-conflict surface
+(single agent typically authors; cross-clone edits to the same field within a
+sync window is a corner case). Audit preserves both edits so loss is recoverable
+in practice.
+
+### Detecting and recovering a MEM-009 LWW loser
+
+When `memory.edit` projection detects that LWW chose someone else's value, the
+response surfaces hint `MEM-009: memory.edit.lww-loser`. (Trigger lights up when
+LWW-loser surfacing lands in the projection response — code path exists today;
+emission is the deferred half.)
+
+Recovery:
+
+```bash
+thrum memory history <id> --diff
+```
+
+Find the losing edit in the diff stream; the JSONL preserves its body. Lift the
+wanted value out and re-apply as a new edit:
+
+```bash
+thrum memory edit <id> --short @rescued-short.md
+```
+
+The new edit becomes the latest ULID, so it wins the next read. If both sides
+actually had useful changes, consider a `comment` child memory recording the
+alternative wording instead of overwriting.
+
+## Soft delete and undelete
+
+Default delete is soft — `status` flips to `purged` but the JSONL keeps every
+event:
+
+```bash
+thrum memory delete <id>             # default soft
+```
+
+Soft-deleted memories are excluded from default search. Re-surface with
+`--include-purged` (or `--status all`). Edges remain in place.
+
+Undelete by writing `status=active`:
+
+```bash
+thrum memory edit <id> --status active
+```
+
+Undelete works regardless of who won the concurrent edit/delete race (see LWW
+table above). The audit history is intact, so the recovered memory carries its
+full provenance.
+
+## Hard delete (`--hard`)
+
+Hard delete is irreversible after the next sync compaction. It reuses thrum's
+`purge_metadata` mechanism (proven for messages) — `memory.delete --hard` emits
+a `memory.purge_executed` event the existing purge logic recognizes; on next
+sync compaction, the JSONL entries for that memory are physically removed across
+all peers.
+
+Mandatory confirmation gate:
+
+```bash
+thrum memory delete <id> --hard
+Type DELETE <id> to confirm: DELETE <id>
+```
+
+The exact token (`DELETE <id>`) must be typed back — matches beads'
+`DESTROY-<prefix>` pattern. There is no `--yes` bypass.
+
+| Mode            | Mechanism                                                      | Recovery                                 |
+| --------------- | -------------------------------------------------------------- | ---------------------------------------- |
+| Soft (default)  | `memory.delete` → projection `status=purged`                   | `thrum memory edit <id> --status active` |
+| Hard (`--hard`) | `memory.purge_executed` → physical JSONL removal at compaction | Not recoverable post-compaction          |
+
+## When NOT to hard-delete
+
+Default to soft delete. The audit trail is the value memories add over ad-hoc
+notes; hard-deleting throws it away.
+
+Reach for `--hard` only when:
+
+- The body contains secrets (API keys, credentials, customer PII) that must not
+  survive in JSONL or any clone.
+- A misfire of `memory.create` recorded clearly wrong content the team agrees
+  should leave no trace.
+- A legal/compliance requirement mandates physical removal.
+
+For everything else — wrong tags, outdated decisions, deprecated rules — prefer
+one of:
+
+- Edit with the corrected content (audit preserves the original).
+- Supersede with a new memory and let the old one go to `status=superseded`.
+- Soft-delete; the audit trail stays.
+
+## Memory-history quick reference
+
+```bash
+thrum memory history <id>             # chronological events touching <id> (durable lane)
+thrum memory history <id> --diff      # with unified field-level diff
+```
+
+The events that show up: `memory.create`, `memory.edit`, `memory.delete`,
+`memory.edge.add`, `memory.edge.remove`, `memory.purge_executed`. Each carries
+`author`, ULID timestamp, and (for edits) the field-level patch.

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

@@ -0,0 +1,139 @@
+---
+name: memory-curate
+description: "Use when managing relationships between memories — adding/removing edges, superseding old decisions, threading comments, walking hierarchies, or deciding whether to unlink, supersede, or both. Loads edge kinds, status-driven read semantics, cycle and single-parent rules, and the unlink-supersede footgun."
+allowed-tools: "Bash(thrum memory:*)"
+version: "0.11.0"
+license: "Apache-2.0"
+---
+
+# memory-curate — edges, status, hierarchy
+
+Load this sub-skill from `thrum-memory` (umbrella) when relationships between
+memories matter — supersession, parent/child structure, comment threads, or
+related-context grouping.
+
+## Edge kinds and when to use each
+
+| Kind           | Meaning                                                        | When to use                                                                                               |
+| -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `supersedes`   | A replaces B. Adding the edge ALSO sets `B.status=superseded`. | A new `arch_decision` overrides an older one. A consolidated session summary replaces several stale ones. |
+| `child_of`     | A is a sub-piece of B; forms a tree. Single-parent.            | A `worktree_status` row is `child_of` a `session_summary`. A `comment` is `child_of` its parent memory.   |
+| `related_to`   | A and B share context; symmetric, advisory.                    | Two `arch_decision`s touching the same subsystem.                                                         |
+| `derived_from` | A was generated or distilled from B.                           | A `short` summary `derived_from` the `full` body when an LLM expanded it.                                 |
+
+Edge kind is an open string (same hybrid pattern as memory kind). Future edges
+like `blocks`, `duplicates`, or `parent-child` can be added without schema
+change.
+
+Add and remove edges:
+
+```bash
+thrum memory link <a> supersedes <b>
+thrum memory link <child> child_of <parent>
+thrum memory unlink <a> supersedes <b>
+```
+
+## Status-driven read semantics
+
+When A supersedes B, the supersede event writes B's status to `superseded` **in
+addition to** creating the edge. Default assembly and `memory search` filter on
+`status=active`. Edges are pure structural metadata; the answer to "is this
+memory current" is always the status field, never an edge walk.
+
+**Why it matters:** this avoids the "do I respect the edge or trust the status
+field" ambiguity at read time. The status field wins.
+
+## The unlink-supersede footgun
+
+Removing a supersede edge via `memory unlink` does **NOT** automatically restore
+the superseded memory to active. The edge disappears but the `status=superseded`
+set by the original supersede event persists.
+
+Agents who try to "undo" a supersede by unlinking the edge will see the edge
+gone while the memory stays hidden from default search and assembly.
+
+To genuinely undo a supersede:
+
+```bash
+thrum memory unlink <new-id> supersedes <old-id>
+thrum memory edit <old-id> --status active
+```
+
+Both steps are required. If you only need to keep the historical link but
+re-surface the old memory, just run the `--status active` edit and leave the
+edge in place.
+
+## Cycle prevention
+
+| Edge kind      | Cycle policy                             |
+| -------------- | ---------------------------------------- |
+| `supersedes`   | Acyclic — write-time DFS reject.         |
+| `child_of`     | Acyclic — write-time DFS reject.         |
+| `derived_from` | Acyclic — write-time DFS reject.         |
+| `related_to`   | Symmetric / undirected — cycles allowed. |
+
+Cycle detection runs a bounded DFS from the proposed edge's target node up the
+existing graph in the same edge-kind direction, looking for the source. Bounded
+by `memory.limits.edge_depth` (default 32) — worst-case O(32) per write,
+constant-time in corpus size.
+
+A chain that exceeds the depth limit returns `ErrMemoryEdgeChainTooDeep` with
+the chain length, the configured limit, and a hint suggesting either
+consolidation via `supersedes` or raising the limit in config.
+
+## Single-parent constraint for `child_of`
+
+`child_of` is enforced single-parent at write-time. A memory has at most one
+parent.
+
+| Edge kind      | Plurality                                                 |
+| -------------- | --------------------------------------------------------- |
+| `related_to`   | Multiple — and obviously so.                              |
+| `supersedes`   | Multiple — A supersedes B AND C in a consolidation merge. |
+| `child_of`     | **One** — enforced.                                       |
+| `derived_from` | Multiple — a summary distilling several sources.          |
+
+If a v2 use case ever needs "comments threaded across multiple memories," the
+single-parent constraint will need to be revisited. Not a v1 use case.
+
+## Comments-as-memories pattern
+
+A comment on memory X is just another memory:
+
+```bash
+thrum memory create --kind comment \
+  --title "Note on Tailscale sync" \
+  --oneline "Confirmed leaving git a-sync removes the dual-consumer conflict." \
+  --parent <X-id>
+```
+
+`--short`/`--full` carry real prose — compose via heredoc or file, never
+double-quoted inline; see your role preamble's 🔴 PROSE INTO A COMMAND rule.
+
+`--parent` shorthand creates the `child_of` edge in the same operation. Author =
+`agent_id`, timestamp = `created_at`. Threading walks via the daemon's
+`memory.listByEdge` RPC on the parent.
+
+No separate `comments` table exists. All the search predicates, audit history,
+edges, and embeddings apply to comments just like any other memory kind.
+
+## Hierarchy navigation
+
+Edge WRITES are CLI-exposed (`link`, `unlink`, `create --parent`). Edge READS
+are daemon-RPC-only today: `memory.listByEdge` walks one hop along an edge kind
+(`direction`: `inbound` finds rows pointing AT an id, `outbound` finds rows the
+id points TO), but no `thrum memory` subcommand exposes it yet and
+`thrum memory show` does not render edges. Until a CLI read surface ships,
+navigate hierarchies by convention instead: give children a shared `--tag` (e.g.
+the parent's slug) at create time and walk with
+`thrum memory search --tag <slug>`.
+
+## Edge limits
+
+| Limit                      | Default     | Configurable via                 |
+| -------------------------- | ----------- | -------------------------------- |
+| Edge depth (acyclic kinds) | 32          | `memory.limits.edge_depth`       |
+| Edges per memory           | 64 outbound | `memory.limits.edges_per_memory` |
+
+Raise per deployment if a genuine workflow needs more — both bounds exist to
+prevent pathological hierarchies and fan-out abuse, not to constrain real use.