dreamcontext 0.8.7 → 0.8.8

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 the ClickUp backend 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>` (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-packs/council/SKILL.md

@@ -119,8 +119,9 @@ the user. Ask:
 
 - **y** → `dreamcontext council promote <debate_id>` (writes
   `_dream_context/knowledge/decision-<slug>.md`)
-- **n / later** → leave as-is. The rem-sleep agent will pick it up during the next
-  consolidation cycle and decide based on your engagement signals.
+- **n / later** → leave as-is. The next sleep consolidation will pick it up (the
+  main agent runs `dreamcontext council list --unpromoted` during the sleep flow)
+  and decide based on your engagement signals.
 
 ## Hard rules
 

package/skill-packs/council/debate-protocol.md

@@ -23,7 +23,7 @@ and idempotency notes.
 | `council synthesize <id>` | Prepare synthesis | Prints manifest. Status → `synthesizing`. |
 | `council complete <id>` | Finalize | Requires `final-report.md` to exist. |
 | `council promote <id>` | Copy to knowledge/ | Trims to Verdict + Why + Minority views + Open risks. Skips What-was-debated + Appendix. |
-| `council list [--unpromoted\|--all]` | Triage | `--unpromoted` used by rem-sleep agent. |
+| `council list [--unpromoted\|--all]` | Triage | `--unpromoted` used during the sleep consolidation (council-promote check). |
 | `council show <id>` | Inspection | Prints debate metadata + round-log. |
 
 ### Sub-agent commands

package/skill-packs/excalidraw/SKILL.md

@@ -205,9 +205,13 @@ See `reference/format.md` for the exact `.excalidraw.md` anatomy reverse-enginee
 
 ## Boards as first-class knowledge in dreamcontext
 
-When the project uses dreamcontext, Excalidraw boards belong in `_dream_context/knowledge/diagrams/`.
-They are indexed and recalled just like any knowledge file — but memory extracts ONLY the
-`## Text Elements` section (never the scene JSON).
+When the project uses dreamcontext, an Excalidraw board belongs **inside the context folder it
+documents** — co-located with that context's knowledge, e.g.
+`_dream_context/knowledge/<context>/<title>/<title>.excalidraw.md`. Diagrams are NOT a segregated
+top-level dump; they live with the context they illustrate (`knowledge/**/*.md` is indexed
+recursively, so a board in a context subfolder is fully recalled). Boards are indexed and recalled
+like any knowledge file — but memory extracts ONLY the `## Text Elements` section (never the scene
+JSON).
 
 ### Required frontmatter
 
@@ -225,26 +229,29 @@ excalidraw-plugin: parsed
 
 ### Folder convention (preferred)
 
+A board lives in its own `<title>/` wrapper folder, INSIDE the context it documents:
+
 ```
-_dream_context/knowledge/diagrams/
-├── my-board/
-│   ├── my-board.excalidraw.md   ← generated board (do NOT hand-edit scene JSON)
-│   ├── my-board.board.cjs       ← generator (dark sibling — excluded from index/recall)
-│   └── my-board.json            ← spec / source of truth (dark sibling — excluded)
-├── competitors/                 ← optional category subfolder (groups many boards)
-│   └── acme/
-│       └── acme.excalidraw.md
-└── legacy-flat.excalidraw.md    ← flat layout still works; no forced migration
+_dream_context/knowledge/
+├── recall/                          ← a context folder (its knowledge + its diagram)
+│   ├── recall-engine-v2.md
+│   └── recall/
+│       ├── recall.excalidraw.md     ← generated board (do NOT hand-edit scene JSON)
+│       ├── recall.board.cjs         ← generator (dark sibling — excluded from index/recall)
+│       └── recall.json              ← spec / source of truth (dark sibling — excluded)
+├── system/
+│   └── architecture/
+│       └── architecture.excalidraw.md
+└── diagrams/                        ← LEGACY top-level tree still works (apply-diagrams maintains it)
+    └── legacy-flat.excalidraw.md
 ```
 
-**Category subfolders** are optional and free-form: `diagrams/<category>/<title>/<title>.excalidraw.md`.
-The dashboard Knowledge view renders the whole `diagrams/` subtree as a nested, collapsible folder
-tree (each board shows a sketch icon), so a large diagram set stays navigable instead of collapsing
-into one flat list. A board's own `<title>/` folder is always its innermost folder. Note: a
-`.board.cjs` that `require()`s shared helpers by relative path must use a depth that matches its
-actual location.
+Nesting is free-form, any depth — the dashboard Knowledge view renders the whole `knowledge/` tree
+as a nested, collapsible folder tree (each board shows a sketch icon), so a large diagram set stays
+navigable. A board's own `<title>/` folder is always its innermost folder. Note: a `.board.cjs`
+that `require()`s shared helpers by relative path must use a depth that matches its actual location.
 
-**Dark siblings**: tooling files inside a `diagrams/<title>/` folder are automatically excluded
+**Dark siblings**: tooling files inside a board's `<title>/` folder are automatically excluded
 from the index, recall corpus, snapshot, and dashboard list — generator scripts (`.board.cjs`),
 spec JSON, and frontmatter-less helper `.md` notes. They are tooling — they do not pollute memory.
 
@@ -254,8 +261,9 @@ detailed write-up — e.g. `acme/acme.excalidraw.md` next to `acme/acme.teardown
 teardown recall normally. Only frontmatter-less notes stay dark, so good organization no longer
 costs you recall.
 
-**Flat layout** (`diagrams/<title>.excalidraw.md`) works without any migration. Use the
-per-title folder when you want to keep the board + generator + spec together cleanly.
+**Flat legacy layout** (`diagrams/<title>.excalidraw.md`) still works without migration, but new
+boards belong in their context folder (above); use a per-title `<title>/` folder to keep the
+board + generator + spec together cleanly.
 
 ### Memory contract
 
@@ -270,18 +278,20 @@ per-title folder when you want to keep the board + generator + spec together cle
 
 | Board nature | Location | Indexed? |
 |---|---|---|
-| Canonical / source-of-truth (architecture, system flows, roadmaps, durable plans the agent should recall in future sessions) | `_dream_context/knowledge/diagrams/<title>/` | Yes — indexed, recalled |
+| Canonical / source-of-truth (architecture, system flows, roadmaps, durable plans the agent should recall in future sessions) | inside its `knowledge/<context>/<title>/` folder | Yes — indexed, recalled |
 | Temporary / scratch / exploratory / in-progress | `inbox/` or `workspace/` (dark by location) | No — not indexed, will not pollute recall |
 
-**Decision rule**: "Will a future session need to know this? → `knowledge/diagrams/`. Throwaway/working? → `inbox/` or `workspace/`."
+**Decision rule**: "Will a future session need to know this? → its context folder under `knowledge/`. Throwaway/working? → `inbox/` or `workspace/`."
 
-Promote a board from inbox/workspace to `knowledge/diagrams/` only once it becomes canonical.
+Promote a board from inbox/workspace into its context folder only once it becomes canonical.
 
-### Migration
+### Legacy `knowledge/diagrams/` + migration
 
-Flat boards in `knowledge/diagrams/` do NOT auto-migrate.
+Older projects kept all boards under a single top-level `knowledge/diagrams/` tree. That still
+indexes and renders, and `sleep-product` keeps the store organized over time — but new boards
+should go in their **context folder** (above), not the segregated dump.
 
-- `dreamcontext migrations pending` — see pending migration task instructions (including 0.7.2 diagrams-folder-convention).
-- `dreamcontext migrations apply-diagrams` — opt-in: moves flat `knowledge/diagrams/*.excalidraw.md` boards into per-title folders AND rewrites all inbound [[wikilinks]] atomically. Safe to re-run. Do NOT hand-edit wikilinks manually.
+- `dreamcontext migrations pending` — see pending migration task instructions (incl. 0.7.2 diagrams-folder-convention).
+- `dreamcontext migrations apply-diagrams` — structural/legacy: folds flat `knowledge/diagrams/*.excalidraw.md` boards into per-title folders AND rewrites inbound [[wikilinks]] atomically. Safe to re-run. Do NOT hand-edit wikilinks manually.
 
 Only organize boards you confirm are canonical knowledge. Temp/scratch boards stay in inbox/workspace.