dreamcontext 0.8.7 → 0.9.0

package/skill/references/sleep.md

@@ -0,0 +1,88 @@
+# Sleep / Consolidation — full flow
+
+Sleep (RemSleep) is how working-session changes get folded back into the durable brain. It mirrors how the brain consolidates memory during sleep. **The main agent runs the orchestration directly** — sub-agents cannot reliably fan out to other sub-agents.
+
+## When to sleep
+
+Sleep debt accumulates automatically via hooks (per Write/Edit tool use). Hooks inject directives — honor them.
+
+| Debt | Level | Per-change score | Required behavior |
+|------|-------|------------------|-------------------|
+| 0–3 | Alert | 1–3 changes → +1 | No action |
+| 4–6 | Drowsy | 4–8 changes → +2 | After completing a task: **inform user + offer** consolidation |
+| 7–9 | Sleepy | 9+ changes → +3 | At session start: **inform user + recommend** consolidation before new work |
+| 10+ | Must sleep | — | **Consolidate immediately**, before or right after the current task |
+
+Also triggers an advisory: a **★★★ bookmark** exists (regardless of debt), or **3+ sessions** since last sleep.
+
+Injected directives (SessionStart + every user message via UserPromptSubmit when debt ≥4):
+- Debt ≥10 → "CONSOLIDATION REQUIRED"
+- Debt ≥7 → "CONSOLIDATION RECOMMENDED"
+- Debt ≥4 → offer after the current task
+
+**MANDATORY post-task check:** after any task/major implementation, if debt ≥4 tell the user: *"Sleep debt is [N]. I can consolidate now to preserve this work. Want me to run it?"* Never silently finish.
+**Auto-sleep (act without asking):** task completed with debt ≥7; major implementation finished with debt ≥4.
+**Ask first:** debt 4–6 after a task; accumulated small changes; user wrapping up.
+
+For non-file-change work (architecture discussion, a decision with no edits): `dreamcontext sleep add <score> "<reason>"`.
+
+---
+
+## The flow (run from the main agent context)
+
+1. **Tell the user** you're consolidating.
+2. **`dreamcontext sleep start`** — pins the epoch timestamp (safe clearing). Add `--deep` only when you intend to authorize destructive knowledge ops (merges/deletes); a normal sleep is non-destructive.
+3. **Build the brief inline** (cheap CLI, no transcript content):
+   - `cat _dream_context/state/.sleep.json` — session IDs, task slugs, `last_assistant_message`, `knowledge_access`
+   - `git status --short` and `git log --oneline --since=$(jq -r '.sleep_started_at // .last_sleep' _dream_context/state/.sleep.json)`
+   - `dreamcontext core releases active` — the planning version (create one with `dreamcontext core releases add --ver vX.Y.Z --status planning --summary "<theme>" --yes` if missing)
+4. **Dispatch specialists in parallel** — one message, multiple Agent tool calls. Each owns a non-overlapping file domain (no stomping):
+   - **Always fire:** `sleep-tasks`, `sleep-state`.
+   - **Conditionally fire `sleep-product`** if ANY of:
+     - `last_assistant_message` mentions research/analysis/decision
+     - a `knowledge_access` entry is 30+ days untouched
+     - a research bookmark exists
+     - a task slug matches an existing feature PRD filename
+     - `git status` shows changes under `_dream_context/core/features/`
+     - a session advanced ≥1 acceptance criterion, OR introduced a feature concept with ≥2 criteria, OR the user named something "a feature" / "we should add X", OR a task has `feature:` frontmatter pointing to a non-existent PRD
+     - the user hint mentions knowledge or a feature
+     - When unsure, **over-fire** `sleep-product` — it no-ops cheaply.
+   - **Conditionally fire `sleep-migration`** only when `dreamcontext migrations pending` produces output. Contract: structure-only (paths/frontmatter/fences), no body prose changes; writes the ledger via `dreamcontext migrations record` on completion.
+   - **Do NOT fire `sleep-federation`.** Copy-based federation is disabled; peers are read live at recall time, not synced at sleep. The specialist is retained but inert.
+   - Pass each specialist a small text brief: epoch, session IDs, active task slugs, planning version, the signals relevant to it, optional user hint. Do **not** paste transcript content — specialists call `dreamcontext transcript distill <id>` themselves.
+5. **Wait for all reports** (each returns a short structured report).
+6. **`dreamcontext reflect`** — each candidate is a term seen across multiple sessions not yet in soul/user/memory/knowledge. Promote into `2.memory.md` or a knowledge file ONLY if genuinely load-bearing; most are noise — discard. Never auto-promote.
+7. **Marketing pass** if `_dream_context/marketing/` exists: `dreamcontext mk rem-sleep`.
+8. **Council promote check:** `dreamcontext council list --unpromoted` — promote if the user engaged positively.
+9. **`dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"`** — clears pre-epoch state, resets debt, writes a history entry. (If a remote backend — ClickUp or GitHub — is active and any task pushes failed, this auto-retries once, then errors loudly with the failed slugs.)
+10. **Report** the consolidated summary to the user.
+
+---
+
+## Specialist ownership (non-overlapping domains)
+
+| Specialist | Owns | Notes |
+|---|---|---|
+| `sleep-tasks` | Task files (`state/*.md`) | Reconciles task bodies to truth, bumps statuses, creates tasks for untracked work, attaches to the planning version. |
+| `sleep-state` | Core identity (soul, user, memory, core 3–6), CHANGELOG, RELEASES | Records patterns/decisions/preferences, writes a changelog entry per meaningful change since the epoch, surfaces release readiness, enforces anti-bloat ceilings, flags stale knowledge for `sleep-product`. |
+| `sleep-product` | Knowledge files + feature PRDs | Creates/reconciles `knowledge/*.md` and `core/features/*.md`, processes staleness flags, maintains the knowledge index + taxonomy. |
+| `sleep-migration` | Structure only | Moves/renames folders, normalizes frontmatter, wraps fences. Never alters body prose. |
+
+**Consolidation discipline (remind specialists in the brief):** prefer *updating/extending* an existing entity over creating a new one. `sleep-tasks` folds a smaller slice into the task that already covers it (broaden its title + insert sub-items) rather than forking a duplicate. `sleep-product` keeps similar verticals/topics in the fewest knowledge files, splitting only on a sharp topical boundary. Duplicate tasks and fragmented near-duplicate knowledge are the top failure modes — but genuinely separate concerns still get their own task/file.
+
+---
+
+## Epoch safety
+
+`sleep start` pins a timestamp epoch. `sleep done` only clears sessions/changes/bookmarks from *before* the epoch — parallel sessions that finish during consolidation are preserved for the next cycle. This is why you always `sleep start` before dispatching and `sleep done` after, never in the reverse order.
+
+## Commands
+```bash
+dreamcontext sleep status              # debt level + history
+dreamcontext sleep start [--deep]      # begin epoch
+dreamcontext sleep done "<summary>"    # finish, reset debt
+dreamcontext sleep add <score> "<why>" # manual debt for non-file work
+dreamcontext sleep debt                # debt number (programmatic)
+dreamcontext sleep history [-n N]      # consolidation history
+dreamcontext reflect [--write]         # cross-session term candidates
+```

package/skill/references/tasks-and-features.md

@@ -0,0 +1,170 @@
+# Tasks & Features — full protocol
+
+## Tasks are your working documents
+
+All context, decisions, user stories, acceptance criteria, constraints, technical details, notes, and progress live in the **task body**. Features are retrospective product docs updated only during sleep — never put in-progress context in a feature.
+
+The auto-loaded snapshot already lists every non-completed task with status, priority, and last-updated date. Answer "what am I working on?" / "which tasks are active?" directly from it — no tool calls. Only read the full file when you need the body (the **Changelog** section is where the previous session left off).
+
+### Lifecycle
+```
+todo → in_progress → in_review → completed
+```
+The sleep agent picks the status that matches reality: `completed` for work that's demonstrably done, low-risk, already validated; `in_review` only when a human genuinely must verify (a behavior change, a design decision, a risky/critical-path change). It does not reflexively park everything in `in_review`, and it closes finished work — so tasks neither rot in `todo` nor rot half-closed in `in_review`.
+
+### Create
+```bash
+dreamcontext tasks create <name> \
+  --description "..." --priority medium --why "What this accomplishes" \
+  [--version v0.9.0] [--person "Ada"] [--due 2026-07-01] [--tags backend,api]
+```
+Defaults: `priority=medium`, `status=todo`. A task created without `--version` auto-attaches to the **active planning version** (see Versioning).
+
+### Enrich (insert into any section during active work)
+```bash
+dreamcontext tasks insert <name> user_stories "As a user, I want X so that Y"
+dreamcontext tasks insert <name> acceptance_criteria "API returns 200 with paginated results"
+dreamcontext tasks insert <name> constraints "Use native fetch, no axios"
+dreamcontext tasks insert <name> technical_details "Key file: src/api/tasks.ts (Express router)"
+dreamcontext tasks insert <name> notes "Edge case: empty results return [] not null"
+dreamcontext tasks insert <name> changelog "Implemented pagination for /api/tasks"
+```
+Sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`.
+
+### Lifecycle commands
+```bash
+dreamcontext tasks log <name> "what was done"        # changelog entry — MANDATORY each session
+dreamcontext tasks status <name> in_review "reason"  # bump status (logs automatically)
+dreamcontext tasks complete <name> "summary"         # mark complete
+dreamcontext tasks delete <name> --yes               # delete (propagates to remote on sync)
+```
+
+### Filtering & discovery
+```bash
+dreamcontext tasks list --version S5                              # one milestone
+dreamcontext tasks list --tag memoryos --tag backend --status todo  # --tag repeatable, AND
+dreamcontext tasks list --any-tag lina --any-tag studio          # --any-tag repeatable, OR
+dreamcontext tasks list --priority critical
+dreamcontext tasks list --feature recall-engine                  # match related_feature
+dreamcontext tasks list --group-by version --all                 # sectioned + counts
+dreamcontext tasks list --tag lina --json                        # scriptable (use this, not awk/grep)
+dreamcontext tasks tags                                           # distinct tags with counts
+```
+Filters compose (AND across flags), case-insensitive; version/priority/feature match exactly.
+
+---
+
+## RICE prioritization
+
+Optional, additive to priority/urgency; powers the dashboard Scatter view and RICE sort.
+```bash
+dreamcontext tasks create <name> --reach 5 --impact 3 --confidence 75 --effort 2
+dreamcontext tasks rice <name>                 # print current values
+dreamcontext tasks rice <name> --effort 4      # update one field, recompute
+dreamcontext tasks rice <name> --clear         # remove all RICE values
+```
+- `--reach` integer 1–10 · `--impact` integer 1–5 · `--confidence` one of 25/50/75/100 (%) · `--effort` person-weeks (>0, ≤52, 0.5 steps).
+- Score = `(reach × impact × confidence/100) / effort`, computed server-side, stored in frontmatter.
+
+## Due dates & urgency
+```bash
+dreamcontext tasks due <name> 2026-07-01     # set
+dreamcontext tasks due <name> clear          # clear
+```
+`urgency` (critical/high/medium/low) is the second Eisenhower axis (priority × urgency) for the dashboard matrix.
+
+---
+
+## People & assignees (multi-person)
+
+Single-person projects ignore all of this. For teams:
+```bash
+dreamcontext config people "Ada" "Mehmet"          # set the roster (syncs ## People in 1.user.md)
+dreamcontext tasks create <name> --person "Ada"    # records a person:ada tag
+dreamcontext tasks tag <name> person:mehmet        # add another assignee
+dreamcontext tasks tag <name> person:ada --remove  # unassign
+```
+- `person:<slug>` tags are the source of truth for assignment and support **multiple assignees**. The legacy scalar `assignee` field is deprecated (still read, not written).
+- With ClickUp enabled, the full assignee set round-trips to ClickUp's native `assignees[]` bidirectionally; map each person to a member with `dreamcontext config clickup-member <person> <memberId>`. With **GitHub** enabled, `person:<slug>` tags round-trip to issue assignees (repo collaborators; a non-collaborator is skipped, never a sync error). (see [integrations.md](integrations.md)).
+- `DREAMCONTEXT_PERSON` env names the current person for attribution.
+
+---
+
+## The Workflow flowchart (keep it in sync)
+
+Every task file has a `## Workflow` mermaid block near the top: one node per acceptance criterion, grouped under milestone subgraphs, with status classes `done` / `active` / `todo` / `blocked`. It is the load-bearing summary of the task — drift makes future sessions misread progress.
+
+**Whenever** you check off a criterion, start one, add/remove one, or hit a blocker → update that node's `:::class`. Then verify:
+```bash
+dreamcontext tasks doctor <name>     # checks flowchart ⇄ acceptance-criteria sync (all tasks if omitted)
+```
+And flip the matching `- [ ]` → `- [x]` in the Acceptance Criteria list immediately — don't wait for sleep.
+
+---
+
+## Task file schema (reference)
+```yaml
+---
+id: "task_abc123"
+name: "Implement auth middleware"
+description: "Add JWT validation to protected routes"
+priority: "high"          # critical | high | medium | low
+urgency: "medium"         # critical | high | medium | low (Eisenhower axis)
+status: "todo"            # todo | in_progress | in_review | completed
+created_at: "2026-02-25"
+updated_at: "2026-02-25"
+tags: []                  # includes person:<slug> for assignees
+version: "v0.9.0"         # planning-version association (auto-set to active planning version)
+parent_task: null
+related_feature: null     # feature slug for cross-link
+product: null             # multi-product scoping (optional)
+due: null                 # YYYY-MM-DD
+rice: { reach: 5, impact: 3, confidence: 75, effort: 2, score: 5.625 }
+---
+```
+Files live at `_dream_context/state/<slug>.md`. Lookup is fuzzy: exact slug → prefix → substring.
+
+---
+
+## Features (PRDs)
+
+Retrospective product documentation, **created and updated exclusively by the sleep agent**. During active work, everything goes in the task; sleep consolidates task content into the matching feature.
+
+```bash
+dreamcontext features create <name> -w "Why" -t backend,api -s planning --related-tasks a,b
+dreamcontext features set <name> status active
+dreamcontext features set <name> tags backend,api,topic:recall
+dreamcontext features insert <name> acceptance_criteria "..."   # auto-formats as - [ ]
+dreamcontext features doctor                                    # staleness / orphans / dangling refs
+```
+Status values: `planning | in_progress | in_review | active | shipped | deprecated`. Sections: `changelog`, `notes`, `technical_details`, `constraints`, `user_stories`, `acceptance_criteria`, `why`. PRDs live in `core/features/<name>.md` (flat directory; may carry `product:`).
+
+---
+
+## Versioning & releases
+
+Versions and releases are unified in `RELEASES.json`. A "version" is a release entry with `status: planning`; releasing flips it to `released` with a date. Lifecycle: `planning → released`.
+
+```bash
+dreamcontext core releases add --ver v0.9.0 --summary "Dashboard improvements" --status planning
+dreamcontext core releases active                # print the active planning version
+dreamcontext core releases active v0.10.0        # switch active planning version
+dreamcontext core releases active --clear        # unset
+dreamcontext core releases list -n 10
+dreamcontext core releases show v0.9.0
+```
+New tasks without `--version` auto-attach to the active planning version, so work is always linked to a milestone. If none exists, the sleep agent creates one. The dashboard Version Manager plans and releases versions; the sleep agent reports release readiness when all of a planning version's tasks are done.
+
+---
+
+## Multi-product (monorepos)
+
+`dreamcontext init` asks whether the project is a monorepo with multiple products and records the list in `state/.config.json` under `multiProduct: string[] | false`. When products are configured:
+
+- **Per-product data structures**: `knowledge/data-structures/<product>.md` (single-product → `default.md`). Body format is a single ` ```sql ` fenced block with `-- ...` comments (the dashboard highlights it). Recall-indexed, owned by `sleep-product`.
+- **Per-product knowledge**: `knowledge/products/<product>.md`. Cross-cutting knowledge stays at top-level `knowledge/`.
+- **Tasks** may carry `product: <name>` in frontmatter; CLI/dashboard surface a product filter.
+- **Feature PRDs** may carry `product: <name>` (still in the flat `core/features/` directory).
+- **Auto-injection**: the SessionStart hook resolves the active task (override `state/.active-task`, else most-recently-modified `in_progress` task). If its `product:` is in `multiProduct`, the hook injects `knowledge/products/<name>.md` into the snapshot under `## Active Product Knowledge: <name>` (capped ~200 lines). You don't load it manually — it's already in context.
+
+If `multiProduct` is `false`/absent, treat the project as single-product and use `data-structures/default.md`.

package/skill-curator/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: curator
+description: >
+  Load when a dreamcontext brain has grown additively and needs a periodic refactor pass that
+  re-orders content into the right shape — or the user invokes `/curator`. Triggers: "curate
+  the brain", "re-organize my context", "the knowledge base has gotten messy", "clean up /
+  refactor the brain", "conform everything to current conventions", "dedup the knowledge",
+  "fix the structure, not just append to it", or any time the corpus has drifted from current
+  architecture conventions (duplicate knowledge, topics living as both feature and knowledge,
+  stale task statuses, off-vocabulary tags, a flat knowledge dump that should be foldered).
+  This is the interactive, sub-agent-driven brain REFACTOR — the pass that sleep won't do. It is
+  allowed to MOVE, MERGE, SPLIT, RENAME, RE-TYPE, and RETIRE content to reach the right
+  knowledge / feature / task / version shape.
+user-invocable: true
+alwaysApply: false
+tags: [curator, refactor, reorganize, cleanup, dedup, single-source-of-truth, orchestration, sub-agents, dreamcontext]
+---
+
+# Curator — interactive, sub-agent-driven brain refactor
+
+You are the **orchestrator**. Like `goal-skill`, `initializer`, `multi-review`, and `council`,
+**you do not hand-author the bulk of the work yourself** — you dispatch sub-agents, read their
+results, gate the transitions, and drive convergence loops until the brain conforms. Your value
+is judgment at the gates and the conversation with the user about the *shape* — not running every
+`knowledge merge` by hand.
+
+**Why this exists, vs sleep.** Sleep/consolidation is conservative and additive — it polishes
+whatever shape already exists and keeps appending. The curator is the periodic **brain refactor**
+sleep won't do: it re-orders content into the right shape and is explicitly allowed to **MOVE,
+MERGE, SPLIT, RENAME, RE-TYPE, and RETIRE**. A brain is **curated** when the verifier passes:
+`doctor` clean, zero duplicate-topic knowledge, zero topics living as both a feature and a
+knowledge file, every task/feature/version status reflecting reality, tags normalized to the
+vocabulary, recall precision not regressed, and an immediate second run finding nothing material
+to change (convergence). Not when "some files got tidied".
+
+**Conventions are read AT RUN TIME — never hardcoded.** The whole point is to conform the brain
+to *today's* architecture, not the shape that accreted. Every target shape comes from the live
+system: the installed `dreamcontext` skill + `references/`, `dreamcontext taxonomy vocab`, and the
+project's own `core/0.soul.md` / `1.user.md`. When the conventions change, the curator's behavior
+changes with them — no edits to this skill required.
+
+## When to invoke
+
+- `/curator` (primary entry).
+- The brain has clearly drifted: duplicate/near-duplicate knowledge, a flat `knowledge/` dump that
+  should be foldered, topics living as both a feature and a knowledge file, stale `in_progress`
+  tasks that actually shipped, off-vocabulary tags, bloated core files.
+- "Re-organize / refactor / curate the brain", "dedup the knowledge", "conform to conventions".
+
+**Scale the machinery to the drift.** A small, tidy brain does not need the full five-auditor
+fan-out. Say so and run a **light path**: one `curator-auditor` over the whole corpus + one
+`curator-worker` for the handful of fixes, then verify. Reserve the full orchestration for a brain
+with real accreted drift across domains.
+
+## Commitment ritual (do this FIRST — non-negotiable)
+
+1. **Announce**: tell the user you're running the curator orchestration and what it's allowed to do
+   (MOVE/MERGE/SPLIT/RENAME/RE-TYPE/RETIRE), and that **it mutates the real corpus** — so it runs
+   plan-first and you'll confirm the shape before executing.
+2. **TodoWrite** the phases (0–7) as items. A phase isn't done until its gate passes.
+3. **Track iteration counts** in the todo text for each convergence loop, e.g.
+   `Phase 4: execute (batch 3/6)`, `Phase 6: verify (iteration 2/3)`.
+
+Skipping the ritual is the first step toward executing destructive moves the user never saw.
+
+## Orchestration flow
+
+```mermaid
+flowchart TD
+    P0[Phase 0 — RECOGNIZE & SCOPE: confirm brain exists + drifted, announce, pick scope, READ current conventions] --> P1[Phase 1 — AUDIT: fan out curator-auditor, one per domain -> reorg findings]
+    P1 --> P2[Phase 2 — REORG PLAN: merge findings into ONE source→action→target plan; de-conflict; batch]
+    P2 --> P3{Phase 3 — CONFIRM THE SHAPE: show the dry-run plan, user adjusts -> approved?}
+    P3 -->|user revises| P2
+    P3 -->|approved| P4[Phase 4 — EXECUTE: fan out curator-worker per batch; track coverage]
+    P4 --> P5[Phase 5 — RECONCILE: knowledge index, releases/versions, taxonomy.json]
+    P5 --> P6{Phase 6 — VERIFY: curator-verifier — PASS? + idempotency re-run}
+    P6 -->|FAIL and iter < 3| P4
+    P6 -->|cap reached| ESC[ESCALATE to user with the unresolved gaps]
+    P6 -->|PASS| P7[Phase 7 — REPORT: what moved/merged/retired + recall before/after + offer a sleep]
+```
+
+### Phase 0 — RECOGNIZE & SCOPE (interactive — ask, then wait)
+
+1. Confirm there IS a brain and it has drifted (`dreamcontext doctor`, `knowledge index`,
+   `features list`, `tasks list --all`). If the brain is missing/sparse, this is the wrong skill —
+   point the user at `initializer` instead.
+2. **Read the current conventions** so the whole run targets *today's* shape: the installed
+   `dreamcontext` skill + references, `dreamcontext taxonomy vocab`, `core/0.soul.md`, `1.user.md`.
+3. **Announce** (per the ritual) and ask **only what you can't determine** (keep it short):
+   - **Scope**: the whole brain, or one domain (knowledge / features / tasks / versions)?
+   - **Anything off-limits** — files/areas you should not touch this pass?
+   - Confirm they want a **real run** (it mutates the corpus) — the plan is shown before execution.
+   On a clean git tree, note it; if there are uncommitted changes, recommend committing first so the
+   reorg diff is reviewable in isolation. Wait for the answers; capture them in TodoWrite.
+
+### Phase 1 — AUDIT (sub-agent fan-out → reorg findings)
+
+Dispatch **`curator-auditor`** (read-only). For a full curate, **fan out in parallel, one auditor
+per domain** (single message, multiple Agent calls), each blind to the others — you merge their
+findings:
+
+| Domain | What it audits |
+|---|---|
+| `knowledge` | bloat (COMPRESS), tag drift (RETAG), flat files that should be foldered (MOVE), near-duplicates (MERGE), stale files (RETIRE) |
+| `ssot` | the cross-cutting single-source-of-truth pass — topics as BOTH feature and knowledge, duplicate knowledge, overlapping features → fold/redirect to one home |
+| `features` | reconcile status to reality, rename to current vocabulary, dedup vs knowledge, flag stale |
+| `tasks` | finished tasks still open (STATUS-BUMP), duplicate/stale tasks (MERGE/RETIRE), orphans → attach to a planning version |
+| `versions` | reconcile release/version statuses so they're tidy and consistent |
+
+Give each auditor its domain + the conventions you read in Phase 0. Each returns a **source → action
+→ target** findings table. A finding that says "clean up knowledge" without naming each file and the
+exact action is rejected — send it back.
+
+### Phase 2 — REORG PLAN (you synthesize)
+
+Merge the auditors' findings into **ONE concrete reorg plan** — `source → action → target` per item.
+This is your synthesis work (not a sub-agent's):
+
+- **De-conflict.** Two auditors touching the same file → one action wins. Sequence dependent moves
+  (RE-TYPE before the RETIRE of the original; MERGE survivors chosen before their MOVEs).
+- **Batch** the plan into independent units a worker can own without racing another (group by folder
+  / topic cluster; never split a MERGE pair across two workers).
+- Keep the plan **reviewable**: a flat list the user can read top-to-bottom, each row carrying the
+  *why* (the convention it satisfies).
+
+### Phase 3 — CONFIRM THE SHAPE (interactive gate — the user owns the shape)
+
+Show the user the **dry-run reorg plan**: every `source → action → target` row, grouped by domain,
+with risk notes (anything that could move recall precision or a wikilink graph). **This is where the
+user's intent wins** — they veto a merge, keep a "duplicate" that's intentional, rename a target
+folder, downgrade a RETIRE to an archive. Iterate Phase 2 ↔ 3 until they approve. **Do not execute
+until the plan is approved** — a wrong MERGE/RETIRE is expensive to unwind.
+
+Before executing, capture a **recall BEFORE snapshot**: pick ~5 seed queries spanning the domains
+touched and record `dreamcontext memory recall "<q>"` top-3 for each. The verifier diffs against this.
+
+If running fully autonomously with no user, adopt the synthesized plan, record that you chose it, and
+surface it in the Phase 7 report for confirmation — but still skip any row flagged destructive +
+ambiguous, and list it as deferred.
+
+### Phase 4 — EXECUTE (sub-agent fan-out — the core)
+
+Dispatch **`curator-worker`** over the approved plan, **one batch per worker** so each fits in
+context. Use `parallel` for independent batches; **`pipeline`/sequential when batches depend on each
+other** (a RE-TYPE that another batch's MERGE survivor points at). Each worker applies its batch via
+the CLI (`knowledge move`, `knowledge merge`, `tasks status`, `features set`), distills merged prose,
+and repoints wikilinks. **Track coverage in TodoWrite** (`batch N/M`). Loop until every plan row is
+applied or consciously deferred. **Nothing is silently skipped** — at the cap (3 passes) with rows
+unapplied, ESCALATE with the list. Re-dispatch failed batches; don't drop them.
+
+### Phase 5 — RECONCILE
+
+Centralized cleanup after the workers (you or a final worker pass): rebuild/verify the knowledge index
+is coherent, reconcile `core releases` / version statuses, ensure any new canonical tags are in
+`core/taxonomy.json` (`taxonomy add`), and confirm no `[[wikilink]]` dangles.
+
+### Phase 6 — VERIFY (the real gate)
+
+Dispatch **`curator-verifier`** (read-only + Bash) with the seed queries + the BEFORE recall snapshot.
+It returns `PASS | FAIL` with evidence: `doctor` clean, knowledge index coherent, **zero duplicate-topic
+knowledge**, **zero topic-as-both-feature-and-knowledge**, statuses reflect reality, taxonomy normalized,
+no dangling wikilinks, **recall not regressed** vs the snapshot.
+
+- **FAIL** → route **back to Phase 4**, fix the specific gaps, re-verify. Cap = 3 → ESCALATE.
+- **PASS** → run the **idempotency check**: an immediate second audit must find nothing material to
+  change. Residual churn means the conventions weren't reached — treat it as a FAIL and loop. When the
+  re-run is clean, the brain is curated.
+
+### Phase 7 — REPORT
+
+Summarize what moved / merged / split / re-typed / retired (counts + the notable ones), the recall
+before/after for the seed queries (proving no regression), anything consciously **deferred** (and why),
+and then **offer a sleep** so the freshly-reorganized corpus is consolidated and the index/staleness warm.
+
+## Convergence rules (how the loops end)
+
+- Every loop has a hard **iteration cap of 3**. Hitting it means **ESCALATE to the user** — never
+  "good enough, the structure's better than it was".
+- Update the TodoWrite count before each loop-back. Past the cap → stop and escalate with specifics.
+- "Curated" is defined by Phase 6 PASS **plus** a clean idempotency re-run — not by the corpus
+  looking tidier.
+
+## Red Flags — STOP, you're about to corrupt the brain
+
+| Thought | Reality |
+|---|---|
+| "I'll just start moving and merging files." | Plan first, confirm the shape (Phase 3), THEN execute. The curator mutates real content. |
+| "I know the conventions, no need to read them." | Read them at run time (Phase 0). The brain conforms to *today's* shape, which you may be misremembering. |
+| "These two files look similar — I'll delete one." | MERGE folds + repoints + preserves; RETIRE archives. Silent deletion loses signal and dangles wikilinks. |
+| "This task is probably done, bump it to completed." | Reality-based only. Cite the changelog/release/code evidence, or leave it. |
+| "Recall is fine, skip the before/after." | A reorg can drop a relevant doc from reach. Snapshot before, diff after — it's an acceptance criterion. |
+| "Verifier passed, we're done." | Not until the idempotency re-run is clean. Residual churn = conventions not reached. |
+| "It's a feature AND a knowledge file — leave both." | One home per topic. RE-TYPE / fold to the canonical one; the verifier fails this. |
+| "I'll author the whole reorg myself." | The orchestrator dispatches auditors + workers. You synthesize the plan and gate; you don't run every merge by hand. |
+
+## Rationalization table
+
+| If you think… | The truth is… | So… |
+|---|---|---|
+| "Auditing every domain is overhead; I'll eyeball it." | One pass over a drifted brain misses cross-cutting dupes and status drift. | Fan out an auditor per domain; merge their findings. |
+| "The user will just approve the plan, skip the gate." | A wrong MERGE/RETIRE is expensive to unwind once files move. | Confirm the shape in Phase 3 before executing. |
+| "Conventions don't change that often, hardcoding is fine." | The point of the curator is to track *current* conventions. Hardcoding makes it stale the day the skill changes. | Read taxonomy vocab + the live skill + soul at run time. |
+| "Verifier will rubber-stamp." | A mis-prompted verifier rubber-stamps. Give it the checklist + the recall snapshot and demand evidence. | Treat FAIL as binding; loop or escalate. |
+
+## Hard rules
+
+- **Orchestrator drives sub-agents.** Auditor (intake) → worker (fan-out execute) → verifier (gate).
+  You synthesize the plan and gate; you don't run the whole reorg by hand.
+- **Read conventions at run time.** taxonomy vocab + the installed skill + soul define the target shape.
+- **Plan-first, confirm the shape (Phase 3) before executing.** The curator mutates real content.
+- **Preserve signal.** MOVE/MERGE/RETIRE keep content findable and repoint every inbound `[[wikilink]]`.
+  Never silent-delete a topic.
+- **One home per topic.** Feature **or** knowledge, never both — the verifier enforces it.
+- **CLI for structure, native edits for prose** — `knowledge move`/`merge`, `tasks status`,
+  `features set`; hand-edit only the wording the CLI doesn't own.
+- **Reality-based status.** Bump only what is demonstrably done, with cited evidence.
+- **Recall must not regress.** Snapshot seed queries before; the verifier diffs after.
+- **Caps are hard** (3 per loop). At the cap, escalate — never declare curated.
+- **Done = Phase 6 PASS + a clean idempotency re-run.** Use the `dreamcontext` skill throughout.
+
+## Relationship to other surfaces
+
+| Surface | Stage | Relationship |
+|---|---|---|
+| `curator` (this) | Periodic brain refactor | Re-orders an existing brain into the current shape — MOVE/MERGE/SPLIT/RENAME/RE-TYPE/RETIRE. The pass sleep won't do. |
+| `curator-auditor` / `-worker` / `-verifier` | This skill's workers | Audit (findings) → fan-out execute → PASS/FAIL gate. Dispatched at Phases 1 / 4 / 6. |
+| `initializer` | First-run / bootstrap | Builds the brain from raw material. Curator *refactors* an existing one. Use initializer to create, curator to re-shape. |
+| Sleep / consolidation | Ongoing, additive | Sleep polishes + appends conservatively. Curator is the periodic structural refactor sleep deliberately avoids. Offer a sleep *after* a curate (Phase 7). |
+| `goal-skill` | End-to-end build of a goal | The orchestration pattern this skill mirrors (plan→review→implement→validate ≈ audit→confirm→execute→verify). |
+
+## Slash command wiring
+
+`/curator` invokes this skill. The natural-language triggers in **When to invoke** also load it.
+(Named `curator`, distinct from `sleep` — sleep consolidates additively; the curator refactors.)