opencode-thrum-pro 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/assets/commands/thrum-compact-extended.md +14 -12
  2. package/assets/commands/thrum-compact.md +17 -15
  3. package/assets/commands/thrum-prime.md +1 -0
  4. package/assets/skills/configure-roles/SKILL.md +0 -1
  5. package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md +15 -6
  6. package/assets/skills/coordinator-maintaining-memory/SKILL.md +2 -0
  7. package/assets/skills/coordinator-merging-code/SKILL.md +25 -10
  8. package/assets/skills/coordinator-merging-code/resources/overbuild-check-prompt.md +60 -0
  9. package/assets/skills/coordinator-philosophy-merge-gate/SKILL.md +5 -4
  10. package/assets/skills/implementer-maintaining-memory/SKILL.md +2 -0
  11. package/assets/skills/memory-curate/SKILL.md +2 -0
  12. package/assets/skills/memory-current-rule/SKILL.md +121 -0
  13. package/assets/skills/memory-maintenance/SKILL.md +2 -0
  14. package/assets/skills/memory-write-discipline/SKILL.md +2 -0
  15. package/assets/skills/persistent-watcher-archetype/SKILL.md +142 -60
  16. package/assets/skills/project-hotpath-gate/SKILL.md +8 -0
  17. package/assets/skills/researcher-maintaining-memory/SKILL.md +2 -0
  18. package/assets/skills/thrum/resources/CLI_REFERENCE.md +14 -6
  19. package/assets/skills/thrum/resources/TMUX_SESSIONS.md +16 -8
  20. package/assets/skills/thrum-memory/SKILL.md +2 -0
  21. package/assets/skills/using-the-queue/SKILL.md +6 -7
  22. package/assets/skills/using-thrum-state/SKILL.md +2 -0
  23. package/assets/skills/using-tmux-ssh/resources/tmux-ssh +23 -2
  24. package/assets/skills/watcher-archetype/SKILL.md +13 -5
  25. package/dist/installer-assets.test.js +5 -2
  26. package/dist/installer.d.ts +5 -1
  27. package/dist/installer.js +38 -7
  28. package/dist/installer.test.js +53 -0
  29. package/package.json +4 -1
  30. package/dist/permission-fixture.integration.test.js +0 -506
  31. /package/dist/{permission-fixture.integration.test.d.ts → installer.test.d.ts} +0 -0
@@ -1,18 +1,14 @@
1
1
  ---
2
- description:
3
- Stage a comprehensive 16-section snapshot, verify it landed, then send /compact
4
- to this agent's OWN tmux pane so it stays alive and resumes at low context. Use
5
- for designer/architect-grade work needing wire contracts, capability matrix,
6
- and design rationale that the standard /thrum:compact format cannot carry.
2
+ description: "Stage and verify a comprehensive snapshot, settle owned background tasks, then compact this tmux session in place. Use for designer or architect work needing wire contracts, a capability matrix, and design rationale."
7
3
  ---
8
4
 
9
5
  # Compact — Extended (16-section snapshot)
10
6
 
11
7
  Compose a comprehensive 16-section prose continuation, write it directly to your
12
8
  restart file, verify it landed, then send `/compact` to your own tmux pane. Same
13
- in-place semantics as `/thrum:compact` — the agent stays ALIVE,
14
- sub-agents/loops/crons survive (confirmed empirically), no session end, no tmux
15
- kill. The only difference is snapshot grade.
9
+ in-place semantics as `/thrum:compact` — the agent stays ALIVE, its background
10
+ loops and cron schedules survive (confirmed empirically), no session end, no
11
+ tmux kill. The only difference is snapshot grade.
16
12
 
17
13
  ## When to use extended vs standard
18
14
 
@@ -70,7 +66,7 @@ survives even if post-compact orientation fails, so it is read-first and
70
66
  self-contained:
71
67
 
72
68
  > 🔴 ON RESUME — you were COMPACTED, not restarted. Daemon binding is intact
73
- > (subagents/loops/crons survived). Resume LEAN: this file is delivered inline in the injected briefing (read it FIRST). Expect a
69
+ > (background loops and cron schedules survived). Resume LEAN: this file is delivered inline in the injected briefing (read it FIRST). Expect a
74
70
  > `thrum prime --light` briefing already auto-injected by the SessionStart
75
71
  > hook; only run `thrum:prime-agent` if it did NOT appear. Do NOT manually run
76
72
  > full `thrum prime`. Then continue from §16.
@@ -148,6 +144,12 @@ lines) re-resolves identity (the Bash tool does NOT persist shell state across
148
144
  calls, so earlier steps' variables are gone), verifies the snapshot on disk, and
149
145
  only then fires `/compact` — all in ONE call so nothing depends on a prior block.
150
146
 
147
+ Before Step 4, settle owned background tasks. In Claude Code, inspect the running-task list,
148
+ wait for active sub-agents, list Monitors with `thrum monitor list`, stop your own
149
+ Monitors, and stop or wait for background shells. In other runtimes, use only
150
+ existing task controls; skip this check if none exist. Send only when none remain;
151
+ if one cannot be settled, report and hold without sending.
152
+
151
153
  ```bash
152
154
  SNAPSHOT="<PASTE SNAPSHOT_PATH FROM STEP 3>"
153
155
  NONCE="<PASTE SNAPSHOT_NONCE FROM STEP 3>"
@@ -341,7 +343,7 @@ is synchronous.
341
343
  ## How resume works
342
344
 
343
345
  After `/compact` the SAME process and session survive — the daemon binding is
344
- intact (that is why your sub-agents, loops, and crons kept running). Full
346
+ intact (that is why your background loops and cron schedules kept running). Full
345
347
  `thrum prime` rebuilds identity + binding + full briefing for a NEW session; none
346
348
  of that is needed here. Resume LEAN, in this order:
347
349
 
@@ -361,8 +363,8 @@ of that is needed here. Resume LEAN, in this order:
361
363
  complete - please continue" prompt on the daemon right behind `/compact`; it
362
364
  is delivered once the pane is idle after compaction, so a turn starts even
363
365
  with an empty inbox.
364
- 3. **Continue** from §16. Reconnect to your still-live sub-agents, loops, and
365
- crons rather than re-dispatching.
366
+ 3. **Continue** from §16. Reconnect to your still-live background loops and
367
+ cron schedules rather than re-dispatching them.
366
368
 
367
369
  Runtime-specific compaction-recovery hooks (if this runtime has any) are
368
370
  documented in that runtime's own plugin tree (its hooks manifest and
@@ -1,9 +1,5 @@
1
1
  ---
2
- description:
3
- Stage a standard 11-section snapshot, verify it landed, then send /compact to
4
- this agent's OWN tmux pane so it stays alive (subagents, loops, crons survive)
5
- and resumes at low context. Use for in-place context relief when you do NOT
6
- want to kill the session.
2
+ description: "Stage and verify a standard snapshot, settle owned background tasks, then compact this tmux session in place. Use for context relief when you want to keep the current session."
7
3
  ---
8
4
 
9
5
  # Compact — Snapshot Then Compact In Place
@@ -11,16 +7,16 @@ description:
11
7
  Compose a standard 11-section prose continuation, write it directly to your
12
8
  restart file, verify it landed, then send `/compact` to your own tmux pane.
13
9
  Unlike `/thrum:restart` and `/thrum:sleep`, compact does NOT end your session and
14
- does NOT kill your tmux pane — the agent stays ALIVE. Any sub-agents, background
15
- loops, and cron schedules you own keep running across the compaction (confirmed
16
- empirically). After compaction you Read your snapshot by hand and re-prime lean.
10
+ does NOT kill your tmux pane — the agent stays ALIVE. Any background loops and
11
+ cron schedules you own keep running across the compaction (confirmed empirically).
12
+ After compaction, read your snapshot by hand and re-prime lean.
17
13
 
18
14
  ## When to Use
19
15
 
20
16
  - Your context is high and you want relief WITHOUT losing the live session —
21
- you own sub-agents, a background loop, or a cron that must survive.
22
- - You are mid-task and a fresh session (which loses in-flight sub-agent handles
23
- and scheduler state) would be more expensive than a compaction.
17
+ you own a background loop or a cron schedule that must survive.
18
+ - You are mid-task and a fresh session would disrupt a scheduled loop or cron
19
+ that you own.
24
20
 
25
21
  For context-exhaustion or stuck-state cases where a FRESH session is the right
26
22
  answer — or where the coordinator should move you — use `/thrum:restart`. For
@@ -72,7 +68,7 @@ survives even if post-compact orientation fails, so it is read-first and
72
68
  self-contained:
73
69
 
74
70
  > 🔴 ON RESUME — you were COMPACTED, not restarted. Daemon binding is intact
75
- > (subagents/loops/crons survived). Resume LEAN: this file is delivered inline in the injected briefing (read it FIRST). Expect a
71
+ > (background loops and cron schedules survived). Resume LEAN: this file is delivered inline in the injected briefing (read it FIRST). Expect a
76
72
  > `thrum prime --light` briefing already auto-injected by the SessionStart
77
73
  > hook; only run `thrum:prime-agent` if it did NOT appear. Do NOT manually run
78
74
  > full `thrum prime`. Then continue from §9.
@@ -148,6 +144,12 @@ lines) re-resolves identity (the Bash tool does NOT persist shell state across
148
144
  calls, so earlier steps' variables are gone), verifies the snapshot on disk, and
149
145
  only then fires `/compact` — all in ONE call so nothing depends on a prior block.
150
146
 
147
+ Before Step 4, settle owned background tasks. In Claude Code, inspect the running-task list,
148
+ wait for active sub-agents, list Monitors with `thrum monitor list`, stop your own
149
+ Monitors, and stop or wait for background shells. In other runtimes, use only
150
+ existing task controls; skip this check if none exist. Send only when none remain;
151
+ if one cannot be settled, report and hold without sending.
152
+
151
153
  ```bash
152
154
  SNAPSHOT="<PASTE SNAPSHOT_PATH FROM STEP 3>"
153
155
  NONCE="<PASTE SNAPSHOT_NONCE FROM STEP 3>"
@@ -275,7 +277,7 @@ your pane goes idle, which only happens if you stop acting now.
275
277
  ## How resume works
276
278
 
277
279
  After `/compact` the SAME process and session survive — the daemon binding is
278
- intact (that is why your sub-agents, loops, and crons kept running). Full
280
+ intact (that is why your background loops and cron schedules kept running). Full
279
281
  `thrum prime` rebuilds identity + binding + full briefing for a NEW session; none
280
282
  of that is needed here. Resume LEAN, in this order:
281
283
 
@@ -295,8 +297,8 @@ of that is needed here. Resume LEAN, in this order:
295
297
  complete - please continue" prompt on the daemon right behind `/compact`; it
296
298
  is delivered once the pane is idle after compaction, so a turn starts even
297
299
  with an empty inbox.
298
- 3. **Continue** from §9. Reconnect to your still-live sub-agents, loops, and
299
- crons rather than re-dispatching.
300
+ 3. **Continue** from §9. Reconnect to your still-live background loops and
301
+ cron schedules rather than re-dispatching them.
300
302
 
301
303
  Runtime-specific compaction-recovery hooks (if this runtime has any) are
302
304
  documented in that runtime's own plugin tree (its hooks manifest and
@@ -1,4 +1,5 @@
1
1
  ---
2
+ name: prime
2
3
  description: Load AI-optimized session context
3
4
  ---
4
5
 
@@ -116,7 +116,6 @@ which is single-variant):
116
116
  | tester | Writes and runs tests, verifies acceptance criteria |
117
117
  | deployer | Handles builds, releases, deployment operations |
118
118
  | documenter | Creates and maintains documentation |
119
- | monitor | Watches system health, reports anomalies |
120
119
  | orchestrator | Drives plan execution across agents (single-variant) |
121
120
 
122
121
  ### 4b: Autonomy Level Per Role
@@ -89,10 +89,11 @@ the one resource it cannot replace and leaves no durable verdict artifact.
89
89
  **Only run it yourself when there is NO gate-role agent available**, and say so
90
90
  explicitly in the merge record so the gap is visible rather than invisible.
91
91
 
92
- **Verdicts are artifacts:** the runner saves them to
93
- `<gate-reports-dir>/<ISO-week>/<date>/<gate-slug>/` (the project's gate-reports directory) and commits them BEFORE
94
- removing any worktree. A verdict that exists only in a message cannot be audited
95
- later.
92
+ **Verdicts are one log line:** the runner appends ONE line (date, gate, candidate SHA,
93
+ target SHA, verdict, one short reason) to `dev-docs/gate-log.md` and commits it. That
94
+ line is the only record a gate keeps; the verdict itself travels in the report message.
95
+ Never commit per-gate report directories, logs, archives or evidence (owner ruling 2026-10-17:
96
+ once a gate has decided and the candidate is landed or rejected, its output is deleted).
96
97
 
97
98
  ## Gate dispatch preamble
98
99
 
@@ -462,10 +463,18 @@ circuit-breaker — **BLOCKING**. Peer call with timeout but no circuit-breaker
462
463
  **Triage:**
463
464
  `git diff main...HEAD --name-only | xargs grep -n '{peer_call_patterns}'`
464
465
 
466
+ ## Test impact selection plan (per-merge gate)
467
+
468
+ Owner ruling, verbatim: "default ON as soon as it lands, no side-by-side; safety net = daily full gate + RDP load/regression test before deploy".
469
+
470
+ Run the per-merge test lanes through the repository's test-impact-selection plan wrapper (the gate role's documented
471
+ command, taking `--base`, `--head` and `--lane`), not the bare full-lane runner. It runs the plan, prints the `TIS_PLAN` line, and passes `--producer-rc` to the runner. Quote the `TIS_PLAN` line in the
472
+ verdict. FULL (`decision=FULL RUN`) is the normal fallback: a plan error or any fail-closed reason runs the whole lane. For a per-landing gate, a FULL RUN fallback means the full NON-race lane, never race-all.
473
+
465
474
  ## Lens 11 — Census classification coverage (mandatory test, not a pattern check)
466
475
 
467
- **Why:** `go test ./...` never runs in Pass-3 — targeted-test selection is
468
- scoped to files the diff touches, and `internal/daemon/rpc/testcensus` is an ad
476
+ **Why:** `go test ./...` never runs in Pass-3 — test impact selection
477
+ (the plan wrapper) is scoped to files the diff touches, and `internal/daemon/rpc/testcensus` is an ad
469
478
  hoc test target nothing routes to. A merge that adds a `state.NewState(...)`
470
479
  call site in an `internal/daemon/rpc/*_test.go` file (test-fixture setup, not a
471
480
  handler) can leave it unclassified and desync the frozen census snapshot with
@@ -5,6 +5,8 @@ description: "Use when the coordinator writes a role-rule, captures an observati
5
5
 
6
6
  # Coordinator memory discipline
7
7
 
8
+ > **Before writing or editing any memory or state entry, use the `memory-current-rule` skill:** a memory states only the CURRENT rule (exceptions allowed), never a timeline of rulings, corrections or reversals, and every touch re-examines the whole memory.
9
+
8
10
  As coordinator, write role-rules (when the user corrects your judgment),
9
11
  capture observations about agent behavior, and periodically note
10
12
  project-state changes. Common memory operations (write command shape, body
@@ -111,6 +111,20 @@ preamble.
111
111
 
112
112
  **Do not duplicate lens definitions here.** Point at them and keep the order.
113
113
 
114
+ ## 0a. OVERBUILD CHECK — first step, before any gate
115
+
116
+ Before a product branch goes to a gate, run one judgment-tier sub-agent with
117
+ `resources/overbuild-check-prompt.md` from this skill's folder. Fill in the
118
+ ask (issue, plan, dispatch message), later rulings and gate findings, the trunk
119
+ ref, the branch tip and the owner's report.
120
+
121
+ - **PROPORTIONATE:** continue to §1.
122
+ - **OVERBUILT:** send the findings to the owner for the simplest version, with
123
+ a files-and-lines plan first. Do not dispatch a gate.
124
+ - **UNCLEAR:** read the findings against source and decide.
125
+
126
+ Test-only, docs and tooling branches skip this step.
127
+
114
128
  ## 1. PRECONDITION — dual review, and it is NOT the gate
115
129
 
116
130
  Two axes, run in parallel, on the branch: **code-quality** and **spec-compliance /
@@ -250,9 +264,10 @@ executed half is **scoped to the change**:
250
264
  acceptable (a targeted run misses cross-test races). Never on primary (the
251
265
  shared fleet build box) — it is CPU-heavy; run it on the gate box.
252
266
  - The fast structural checks on the merged tree — `gate-ban-check`,
253
- `gate-omitempty-check`, `gate-lockspan-check`, `gate-marker-diff`,
254
- `gate-stamp-protocol-check`, `gate-plugin-bundle-leaks` (seconds each; they
255
- catch banned flags, `omitempty` drift, lock-span, marker and stamp drift
267
+ `gate-omitempty-check`, `gate-lockspan-check`, `gate-sourcetree-check`,
268
+ `gate-marker-diff`, `gate-stamp-protocol-check`, `gate-plugin-bundle-leaks`
269
+ (seconds each; they catch banned flags, `omitempty` drift, lock-span,
270
+ shipped code that needs a source-tree-only file, marker and stamp drift
256
271
  regardless of the change; `gate-plugin-bundle-leaks` self-skips when no plugin
257
272
  path changed).
258
273
  - The `merge-base --is-ancestor` fast-forward check (§6).
@@ -361,12 +376,12 @@ agreeing (`rev-parse origin/<branch>` and `ls-remote`). **Assert the branch TIP*
361
376
 
362
377
  ## 7. AFTER THE MERGE — four things, none optional
363
378
 
364
- 1. **The verdict artifact.** The runner saves verdicts to
365
- `<gate-reports-dir>/<ISO-week>/<date>/<gate-slug>/` (the project's gate-reports directory) and **commits them
366
- BEFORE removing any worktree.** Save → commit → then destroy. A verdict that
367
- exists only in a message cannot be audited later. The artifact must be able to
368
- carry a `CLEAN-WITH-GATE-FIXES` outcome, and when one applies it cites the
369
- `GATE-AUTHORED` commit SHA.
379
+ 1. **The gate-log line.** The runner appends ONE line (date, gate, candidate SHA, target
380
+ SHA, verdict, one short reason) to `dev-docs/gate-log.md` and commits it. That line is
381
+ the only record a gate keeps: never commit per-gate report directories, logs, archives
382
+ or evidence, and delete the gate's output once you confirm the candidate landed or was
383
+ rejected (owner ruling 2026-10-17). The line must be able to carry a `CLEAN-WITH-GATE-FIXES`
384
+ outcome, and when one applies it cites the `GATE-AUTHORED` commit SHA.
370
385
  2. **The efficacy row**, in the hotpath-gate efficacy log — required for
371
386
  **every** trigger-dir merge, including `SKIPPED_WITH_EVIDENCE` rows and
372
387
  orchestrator-run merges. The log measures gate **coverage**, not just outcomes.
@@ -438,7 +453,7 @@ hides staleness.
438
453
  - `coordinator-hotpath-merge-gate` · `coordinator-philosophy-merge-gate` — the lenses
439
454
  - `coordinator-running-review-cycles` — the dual-review cycle feeding §1
440
455
  - `coordinator-branch-split-on-block` — when a gate blocks one concern of a bundled branch
441
- - the gate-reports README — the artifact contract
456
+ - `dev-docs/gate-log.md` — the one-line-per-gate record
442
457
  - `.thrum/hotpath-gate.json` · `.thrum/philosophy.md` — the configs; read these, not prose
443
458
 
444
459
  ## Project-specific rules (already loaded)
@@ -0,0 +1,60 @@
1
+ # Overbuild check — sub-agent prompt
2
+
3
+ Give this whole file to one judgment-tier sub-agent, with the inputs filled in.
4
+ It is read-only and takes about 10 minutes.
5
+
6
+ ---
7
+
8
+ You are checking whether a branch built more than it was asked to build. Work
9
+ read-only in the repository named below: read files and run `git log`,
10
+ `git diff`, `git show` and `grep`. Do not build, run tests, edit, check out,
11
+ commit or push.
12
+
13
+ ## Inputs
14
+
15
+ - Repository and trunk ref: `<REPO>`, `<TRUNK_REF>`
16
+ - Branch tip: `<TIP_SHA>`
17
+ - What was asked (the spec): `<ISSUE TEXT, PLAN PATH, DISPATCH MESSAGE>`
18
+ - Later rulings and gate findings that changed the ask, if any: `<LIST>`
19
+ - The owner's "tip ready" report: `<TEXT>`
20
+
21
+ ## Steps
22
+
23
+ 1. Read the ask. Write down, in your own notes, the list of behaviours it asks
24
+ for. Nothing else counts as asked unless a later ruling or gate finding in
25
+ the inputs adds it.
26
+ 2. Read the change: `git diff --numstat <TRUNK_REF>...<TIP_SHA>`, the full
27
+ diff, and every commit message (`git log <TRUNK_REF>..<TIP_SHA>`).
28
+ 3. For each production file and each new function, type or field, trace it to
29
+ one behaviour in the ask. Anything that does not trace is a finding unless a
30
+ commit message, a ruling or a gate finding gives a concrete reason.
31
+ 4. Look for these patterns:
32
+ - **Invented scenario:** code that handles a case the ask never mentions,
33
+ with no reproduction, log, failing test or gate finding showing the case
34
+ happens.
35
+ - **Duplicate machinery:** a new cache, lock, retry loop, deadline, queue,
36
+ state or helper. Search the codebase for an existing one that does the
37
+ same job; if one exists, the new one is a finding.
38
+ - **Bundled feature:** a separate behaviour carried inside the fix.
39
+ - **Unrequested guard:** a new refusal, deadline, bound, cap or
40
+ authorization check that the ask did not request.
41
+ - **Test volume:** more test lines than production lines is fine only when
42
+ each test checks a distinct behaviour. Flag tests that check the same
43
+ behaviour twice, tests that pin an old path or a past revision, and tests
44
+ for an invented scenario.
45
+ 5. Estimate what the simplest version that does exactly the ask would keep.
46
+
47
+ ## Report (one page)
48
+
49
+ - **Verdict:** PROPORTIONATE (send to the gate), OVERBUILT (send back), or
50
+ UNCLEAR (the coordinator decides).
51
+ - **Sizes:** production lines and test lines added, and your estimate for the
52
+ simplest version.
53
+ - **Findings:** a numbered list. For each give the pattern, `file:line`, why it
54
+ does not trace to the ask, whether a commit or ruling gives a reason, and
55
+ what the simplest version would do instead.
56
+ - **Keep:** anything that looks large but is justified, with the reason, so it
57
+ is not cut by mistake.
58
+
59
+ When the ask is thin (one line), say so and treat findings as pointers for the
60
+ coordinator to check, not as automatic rejections.
@@ -62,10 +62,11 @@ the one resource it cannot replace and leaves no durable verdict artifact.
62
62
  **Only run it yourself when there is NO gate-role agent available**, and say so
63
63
  explicitly in the merge record so the gap is visible rather than invisible.
64
64
 
65
- **Verdicts are artifacts:** the runner saves them to
66
- `<gate-reports-dir>/<ISO-week>/<date>/<gate-slug>/` (the project's gate-reports directory) and commits them BEFORE
67
- removing any worktree. A verdict that exists only in a message cannot be audited
68
- later.
65
+ **Verdicts are one log line:** the runner appends ONE line (date, gate, candidate SHA,
66
+ target SHA, verdict, one short reason) to `dev-docs/gate-log.md` and commits it. That
67
+ line is the only record a gate keeps; the verdict itself travels in the report message.
68
+ Never commit per-gate report directories, logs, archives or evidence (owner ruling 2026-10-17:
69
+ once a gate has decided and the candidate is landed or rejected, its output is deleted).
69
70
 
70
71
  ## Gate dispatch preamble
71
72
 
@@ -5,6 +5,8 @@ description: "Use when the implementer writes a role-rule after user correction,
5
5
 
6
6
  # Implementer memory discipline
7
7
 
8
+ > **Before writing or editing any memory or state entry, use the `memory-current-rule` skill:** a memory states only the CURRENT rule (exceptions allowed), never a timeline of rulings, corrections or reversals, and every touch re-examines the whole memory.
9
+
8
10
  You are the implementer. Your memory discipline is intentionally narrow: you
9
11
  READ rules at session start and you WRITE rules when the user corrects your judgment
10
12
  mid-implementation. Refactoring opportunities, lessons learned, design questions
@@ -8,6 +8,8 @@ license: "Apache-2.0"
8
8
 
9
9
  # memory-curate — edges, status, hierarchy
10
10
 
11
+ > **Before writing or editing any memory or state entry, use the `memory-current-rule` skill:** a memory states only the CURRENT rule (exceptions allowed), never a timeline of rulings, corrections or reversals, and every touch re-examines the whole memory.
12
+
11
13
  Load this sub-skill from `thrum-memory` (umbrella) when relationships between
12
14
  memories matter — supersession, parent/child structure, comment threads, or
13
15
  related-context grouping.
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: memory-current-rule
3
+ description: "Use BEFORE writing or editing ANY memory - thrum memory create/update, thrum state set, a file-based memory, a memory index line (MEMORY.md), or a restart snapshot. A memory states only the CURRENT rule, never a timeline of rulings, corrections and reversals. Also use to audit or rewrite existing memories; written so a helper agent can apply it with no other context."
4
+ ---
5
+
6
+ # A memory states the current rule, never its history
7
+
8
+ A memory written as a timeline ("X; later corrected to Y; exception Z; Z
9
+ reversed") is worse than no memory. The reader has to rebuild what is true now,
10
+ often rebuilds it wrong, and then acts on a rule that no longer holds.
11
+ Exceptions are fine. Reversals, and layers of revisions, are not.
12
+
13
+ This applies to every store: `thrum memory`, `thrum state`, file-based memories
14
+ and their indexes, and restart snapshots.
15
+
16
+ ## Every time you touch a memory
17
+
18
+ Whenever you create, edit, append to or merge a memory, examine the WHOLE memory,
19
+ not just your change. If any part of it is a timeline, a stale version of a rule,
20
+ or a summary that disagrees with the body, rewrite the whole memory to the
21
+ current rule in the same edit.
22
+
23
+ ## The shape
24
+
25
+ ```text
26
+ <Rule, present tense, one or two sentences, with its full scope:
27
+ which roles, runtimes, repos, peers, boxes or paths it covers.>
28
+ <Exceptions as part of the rule: "except X, where Y". An exception that ends
29
+ on a condition says so: "until <bead/event>; check it before applying".>
30
+ Owner, date and one short quote of the CURRENT ruling (optional).
31
+
32
+ Why: <the reason, short>
33
+ How to apply: <as many bullets as the rule needs: every still-current
34
+ precondition, command, control and bound>
35
+ ```
36
+
37
+ A memory that carries several independent rules (a reader could need one without
38
+ the others) keeps each as its own headed section in this shape, or is split into
39
+ separate memories that link to each other. Never collapse independent rules into
40
+ one sentence, and never drop a rule because it is not the title's rule.
41
+
42
+ ## What stays and what goes
43
+
44
+ Stays:
45
+ - The current rule, its full scope words, and its current exceptions.
46
+ - The current ruling's owner, date and one short quote.
47
+ - The reason. A past incident stays only if, without it, the Why would be empty
48
+ or the rule would look optional; keep it to two lines.
49
+ - Every still-current precondition, command, control and bound.
50
+
51
+ Goes:
52
+ - Replaced statements, their quotes and their dates.
53
+ - "First X, then Y" narratives of how the rule changed.
54
+ - An exception that no longer applies.
55
+ - Evidence (file:line, probes, controls) that only supported a replaced
56
+ statement. Never keep evidence for a rule that no longer holds.
57
+ - Markers: "UPDATE", "CORRECTED", "SUPERSEDED", "REVERSED", "STRICKEN",
58
+ "later", "(late)", strikethrough.
59
+
60
+ ## Scope is part of the rule
61
+
62
+ Never shorten scope words (which repo, role, runtime, peer, box, path). A rule
63
+ that loses its scope is a different rule. For anything about authorization,
64
+ peering, capability or access, read the project's security model before
65
+ rewriting and keep every scope qualifier word for word.
66
+
67
+ ## Every summary must agree with the body
68
+
69
+ A memory can have several summaries; find them all and make each match the
70
+ rewritten body:
71
+ - File memory: its front-matter `description:`, its line in the main index
72
+ (e.g. MEMORY.md), and its line in any secondary index (e.g.
73
+ MEMORY-reference.md). Grep the file name in every index.
74
+ - `thrum memory`: its `--title` and `--oneline`. Find related entries with
75
+ `thrum memory search <topic>`; rewrite with `thrum memory update <id>`.
76
+ - `thrum state`: the value of every key that restates the rule. When a file
77
+ memory names a state key, read it and keep the two identical.
78
+
79
+ In an index, one entry is one `[text](file.md)` link. Rewrite only that entry's
80
+ text; never touch the entries that share its line. Follow any format contract the
81
+ index states about itself (caps, demotion), except that an index entry which
82
+ annotates a memory as superseded or corrected is itself a timeline and must be
83
+ rewritten or removed.
84
+
85
+ ## Rewriting a memory, step by step
86
+
87
+ 1. Read the memory in full, every memory it links to, and every memory on the
88
+ same topic (search by topic, not only by title). If it names a live source
89
+ (a config key, skill, template, bead), read that too: when the live source is
90
+ newer, it decides the current rule, and the memory should say "read X at the
91
+ moment of use" instead of restating X.
92
+ 2. List, privately, every distinct statement it makes, with its date or position.
93
+ 3. Decide the current rule POINT BY POINT, not file by file. For each point,
94
+ take the latest owner statement on that point. A later statement REPLACES an
95
+ earlier one only when it covers the same scope. If it covers a narrower scope,
96
+ it is an exception, and the earlier statement still governs everywhere else.
97
+ If two statements have the same scope and no clear order, mark the memory
98
+ AMBIGUOUS, change nothing, and report the exact question for the owner.
99
+ 4. Rewrite the memory in the shape above, one section per independent rule.
100
+ 5. Rewrite every summary (see above) to match.
101
+ 6. If another memory states the same rule: move every still-current point from
102
+ it into the memory you keep, then reduce it to a one-line body
103
+ ("Merged into <name>.") and re-point or remove its index entries. Never reduce
104
+ a memory to a pointer before its current points have moved.
105
+ 7. Self-check (all must be yes):
106
+ - A reader could act correctly after reading only the first section.
107
+ - Each rule is stated once, with no earlier version beside it.
108
+ - Every summary says the same thing as the body.
109
+ - No other memory states a different version of the rule.
110
+ - No scope word, current exception, precondition or reason was lost.
111
+ 8. Report each memory as REWRITTEN, MERGED INTO x, AMBIGUOUS (question) or
112
+ UNCHANGED (why), with one line saying which rules were kept, dropped (and
113
+ why) or moved (and where).
114
+
115
+ Never invent a rule. When unsure whether a statement is still current, ask.
116
+
117
+ ## Auditing a store
118
+
119
+ Grep the store for the markers above and for topics that more than one memory
120
+ covers, then follow the steps for each hit. Grep finds only marked memories, so
121
+ also read memories that share a topic with a hit.
@@ -5,6 +5,8 @@ description: "Use when an agent needs to update, delete, supersede, or audit an
5
5
 
6
6
  # Maintaining thrum memory entries
7
7
 
8
+ > **Before writing or editing any memory or state entry, use the `memory-current-rule` skill:** a memory states only the CURRENT rule (exceptions allowed), never a timeline of rulings, corrections or reversals, and every touch re-examines the whole memory.
9
+
8
10
  This skill carries the canonical lifecycle operations on existing memory entries
9
11
  — edit, delete, supersede, history audit.
10
12
 
@@ -5,6 +5,8 @@ description: "Use when an agent needs to capture a new memory entry — a rule,
5
5
 
6
6
  # Writing thrum memory entries
7
7
 
8
+ > **Before writing or editing any memory or state entry, use the `memory-current-rule` skill:** a memory states only the CURRENT rule (exceptions allowed), never a timeline of rulings, corrections or reversals, and every touch re-examines the whole memory.
9
+
8
10
  This skill carries the canonical write-command shape + content discipline shared
9
11
  by every role that writes memory. Per-role skills
10
12
  (researcher/coordinator/implementer-maintaining-memory) reference this skill for