skill and develop

skills/compact-memory/SKILL.md

@@ -3,14 +3,12 @@ name: compact-memory
 description: >
    Audit and compact memory/MEMORY.md by removing superseded, duplicated, overly detailed, 
    or ephemeral entries, and merging related items within a subsection. 
-   Runs interactively by default; use auto mode for unattended execution.
+   Runs interactively when the user asks; nightly mode is driven by a script.
 ---
 
 # compact-memory
 
-Compact `memory/MEMORY.md` when it grows too large or stale. The skill reads `memory/MEMORY.md` plus `USER.md`, `SOUL.md`, and `keep.md` (all three in the workspace root) to detect duplicates and outdated context, but only edits `memory/MEMORY.md`.
-
-This skill has no accompanying script — every step below is performed by you, the agent, directly with your file read/edit tools. There is nothing to `exec` or spawn.
+Compact `memory/MEMORY.md` when it grows too large or stale. The skill reads `memory/MEMORY.md` plus `USER.md`, `SOUL.md`, and `keep.md` (all three in the workspace root) to detect duplicates and outdated context, but only ever changes `memory/MEMORY.md`.
 
 ## When to use
 
@@ -25,6 +23,8 @@ The line threshold is only a proactive trigger. When the user invokes the skill
 
 ### Interactive mode (default)
 
+You perform every step yourself with your file tools. There is nothing to `exec` or spawn.
+
 1. Read `memory/MEMORY.md`, and — for duplicate detection — also `USER.md`, `SOUL.md`, and `keep.md` (all three in the workspace root).
 2. Count total lines (`wc -l memory/MEMORY.md`). If the skill was **not** invoked explicitly by the user, the file is ≤ 250 lines, and there is no obvious staleness, report "nothing to clean up" and stop. When invoked explicitly, always continue to the audit.
 3. **Audit the WHOLE file in a single pass.** Walk every `##` section and every `###` subsection in order, top to bottom, and evaluate every bullet. Do not stop after the first few findings — the proposal in step 5 must cover the entire file at once. Re-running the skill should find nothing left, not "the next batch".
@@ -45,32 +45,26 @@ The line threshold is only a proactive trigger. When the user invokes the skill
    - `delete 2, 5` — delete only listed items.
    - `cancel` — abort.
 8. Apply approved changes to `memory/MEMORY.md`.
-9. Append deleted items to `log/memory-clean.log` with timestamp `YYYY-MM-DD HH:MM` (create the file if it does not exist).
+9. Append deleted items to `log/memory-clean.log` with timestamp `YYYY-MM-DD HH:MM`, one line per item, via `exec` shell append so existing lines cannot be lost:
+   `printf '%s\n' '<YYYY-MM-DD HH:MM> DELETED [<category>] "<text>" — <reason>' >> log/memory-clean.log`
 10. Report summary.
 
-### Auto mode
+### Nightly mode (script-driven)
 
-Triggered by the user saying "memory-compact auto" or an equivalent with explicit auto intent.
+Triggered only by `scripts/compact_memory_auto.py` from the crontab. Never start this mode from a chat message — the change-set you produce here is applied by the script, and outside that script nothing would apply it. A user asking for an unattended-style cleanup in chat gets interactive mode.
 
-1. Perform the same audit as interactive mode.
-2. Before deleting anything, write a full snapshot of `MEMORY.md` to `backup/<YYYY-MM-DD_HHMM>_memory.backup.md`.
-3. Apply changes immediately without waiting for approval.
-4. Print a detailed list of changes.
-5. Append deleted items to `log/memory-clean.log` (create the file if it does not exist).
+**You change nothing in this mode.** Do not edit `memory/MEMORY.md`, do not write a backup, do not touch `log/memory-clean.log`. The script applies the change-set, writes the backup and the log, and composes the message the user receives. Your prose is never delivered.
 
-## Rules
+1. Run the same audit as interactive mode steps 1–5.
+2. Answer with **exactly one ```json code block and nothing else** — no narration, no summary, no text before or after it.
+3. Nothing qualifies → a block with an empty `changes` list.
+4. If the script replies that the validator rejected your change-set, fix exactly what it lists and answer again with one corrected block and nothing else.
 
-- Only edit `memory/MEMORY.md`.
-- Do not touch `SOUL.md`, `USER.md`, or `keep.md`.
-- In interactive mode do not create backups of `MEMORY.md`; rely on `log/memory-clean.log` for traceability. Auto mode always writes a full snapshot to `backup/` before deleting.
-- Merge only within the same `###` subsection (never across `##` sections or across different `###` subsections).
-- Preserve active project context, user preferences, and durable infrastructure facts.
-- Be exhaustive: propose every qualifying candidate in one pass, not a handful. The user prunes via `keep`/`delete`, so in interactive mode propose generously and flag borderline items rather than silently keeping them.
-- In **auto mode** only, when in doubt keep it (no user is there to prune); list the borderline items you kept in the report.
+When in doubt, keep the item — no user is there to prune, and there is no way to mention what you kept.
 
 ## Output format
 
-Interactive proposal:
+### Interactive proposal
 
 ```
 Found X candidates to change in MEMORY.md:
@@ -88,18 +82,58 @@ Merge:
 Commands: apply | keep <numbers> | delete <numbers> | cancel
 ```
 
-Auto mode report:
+### Nightly change-set
 
+```json
+{
+  "changes": [
+    {
+      "op": "delete",
+      "category": "ephemeral",
+      "original": ["- Debug run 2026-07-25: output-format test in progress"],
+      "reason": "one-off debug marker, task finished"
+    },
+    {
+      "op": "merge",
+      "original": [
+        "- Runs as a systemd user service `nanobot.service`",
+        "- Model switching via `my` tool requires `tools.my.allow_set = true`"
+      ],
+      "new_text": ["- Runs as a systemd user service `nanobot.service`; model switching via `my` needs `tools.my.allow_set = true`"],
+      "reason": "same subsection, one topic"
+    }
+  ]
+}
 ```
-Memory compact (auto):
-- deleted: X
-- merged: Y
-- unchanged: Z
 
-Details:
-...
+Nothing to change:
+
+```json
+{
+  "changes": []
+}
 ```
 
+Field rules — the validator rejects the whole change-set if any of these is violated:
+
+- `op` — `"delete"` or `"merge"`. No other fields than the ones shown above are allowed.
+- `category` — `delete` only, one of `superseded`, `detail`, `duplicate`, `ephemeral`, `stale-section`.
+- `original` — list of whole lines copied **character-for-character** from `MEMORY.md`, in file order, max 20 lines. The block must appear in the file exactly once, so include enough surrounding lines to make it unique.
+- `new_text` — `merge` only, list of lines replacing `original`. Max 3 lines, max 300 characters, and always fewer lines than `original`.
+- `reason` — max 120 characters, **in English**, one clause saying why. It is shown to the user verbatim.
+- Blocks of different items must not overlap, and the change-set must not remove more than half of the file.
+
+## Rules
+
+- Only ever change `memory/MEMORY.md` — and in nightly mode not even that; the script does it.
+- Do not touch `SOUL.md`, `USER.md`, or `keep.md`.
+- In interactive mode do not create backups of `MEMORY.md`; rely on `log/memory-clean.log` for traceability.
+- `log/memory-clean.log` is append-only: write new lines with `>>` via `exec`, never with `write_file`/`edit_file`. Never delete, reformat, or "clean up" existing lines — not even ones that do not match the current format.
+- Write to `log/memory-clean.log` only when something was deleted or merged — never a "no changes" entry.
+- Merge only within the same `###` subsection (never across `##` sections or across different `###` subsections).
+- Preserve active project context, user preferences, and durable infrastructure facts.
+- Be exhaustive: propose every qualifying candidate in one pass, not a handful. In interactive mode the user prunes via `keep`/`delete`, so propose generously and flag borderline items rather than silently keeping them.
+
 ## Example
 
 User: `compact memory`