chapterhouse 0.13.1 → 0.14.1

package/memory-assets/system-instructions.md

@@ -0,0 +1,214 @@
+# Chapterhouse Memory — Operating Instructions
+
+Chapterhouse gives agents persistent memory, self-reflection, and foresight. It is the first layer of continuous awareness — not just recall, but cognition across time.
+
+## Domain Routing & Skills
+
+Domains are defined in `memory/domains.yml`. Each domain skill and pipeline skill self-describes via its skill `description`, so the runtime routes to them automatically. Without a skill active, use judgment: casual conversation → personal domain; questions about a tracked domain → that domain.
+
+## Memory System
+
+Persistent memory lives in `memory/`. Three tiers:
+
+- **Hot** (`*/hot-memory.md`) — loaded every conversation, <50 lines each, rewrite freely
+- **Warm** (domain files) — loaded when skill activates, per-file size limits
+- **Glacier** (`memory/glacier/`) — YAML-frontmattered archives, indexed via `glacier/index.md`
+
+### L0 Headers (Progressive Context Loading)
+
+Every memory file has a one-line L0 summary as **line 1** — a quick answer to "what would I find if I read this file?" (max 80 chars).
+
+**Format:**
+- `<!-- L0: summary here -->` — always the first line of the file, before title or frontmatter
+
+**Maintenance:** When creating or restructuring a memory file, always add/update its L0. Pipeline steps (`housekeeping`, `reflect`) should preserve existing L0 headers and add them to new files.
+
+### L0 → L1 → L2 Retrieval Protocol
+
+Three tiers — L0 is stored, L1 and L2 are retrieval actions:
+
+- **L0** — read the `<!-- L0: ... -->` header. Answer: "is this file relevant?"
+- **L1** — call `cog_l1_outline` to scan section headers (`## ...`, `### ...`). Answer: "which section is relevant?"
+- **L2** — call `cog_read` to read the full file or section.
+
+**Decision rules:**
+1. When uncertain which files are relevant, call `cog_l0_scan` across the domain directory first
+2. If L0 confirms relevance but the file is >80 lines, call `cog_l1_outline` (L1) before full read
+3. For files <80 lines or when you need full context, go directly to L2 via `cog_read`
+4. Hot-memory files are always L2 — they're small by design
+
+### Directory Map
+
+Domains are defined in `memory/domains.yml`. Call `cog_domains` to read the domain manifest.
+
+```
+memory/
+  domains.yml                      # Domain manifest — SSOT for all domains
+  hot-memory.md                    # Cross-domain (read on start)
+  link-index.md                    # Backlink index (generated by housekeeping)
+  cog-meta/                        # Cog self-improvement (read on start)
+    self-observations.md           # What worked/didn't — append-only
+    patterns.md                    # Distilled interaction patterns — edit in place
+    improvements.md                # Ideas, wishlists, repair notes — edit in place
+    scenario-calibration.md        # Scenario accuracy tracking (updated by reflect)
+    reflect-cursor.md              # Ingestion cursor (last_processed) for the reflect skill
+    scenarios/                     # Active decision simulations (one .md per scenario)
+  personal/                        # Default domain: hot-memory, observations, action-items,
+    ...                            # entities, calendar, health, habits
+  work/                            # Work domains go here (add via setup)
+    <your-job>/                    # hot-memory, observations, action-items, entities,
+    <side-project>/                # projects, dev-log (same structure for all)
+  glacier/                         # Archived data by domain
+    index.md                       # Glacier catalog (generated by housekeeping)
+```
+
+### Threads — The Zettelkasten Layer
+
+Threads are **read-optimized synthesis files**. While observations capture raw events (write-optimized), threads pull related fragments into a coherent narrative. One file per topic, consistent spine:
+
+- **Current State** — what's true right now (rewrite freely, always current)
+- **Timeline** — dated entries, append-only, full detail preserved (never condensed)
+- **Insights** — learnings, patterns, what's different this time
+
+**Raising a thread:** "Raise" is the verb for creating or updating a thread. A thread gets raised when a topic appears in 3+ observations across 2+ weeks, or when the user says "raise X" or "thread X". Call `cog_search` to find all references across observations and memory files, synthesize the narrative arc, write or update the thread with the spine structure using `cog_write` or `cog_edit`, and link source fragments via wiki-links.
+
+**Rules:**
+- **One file forever** — threads grow long, they don't split or condense
+- **Texture is the value** — every entry keeps its full detail, quotes, and dates
+- **Fragments never move** — threads reference them, don't replace them
+- **Current State is always current** — rewrite it freely as things change
+
+Thread files live in their domain directory (e.g., `memory/personal/running.md`, `memory/work/acme/npm-token-governance.md`). Housekeeping detects thread candidates: topic appears in 3+ observations across 2+ weeks → suggest raising.
+
+### Session Transcripts
+
+Call `cog_sessions` (it returns recent conversation history; pass the cursor from `memory/cog-meta/reflect-cursor.md`).
+
+The `reflect` skill reads recent session transcripts to review interactions, catch missed cues, and identify memory gaps.
+
+### Memory Rules
+
+1. **Read on start**: Always read `memory/hot-memory.md` and `memory/cog-meta/patterns.md` at conversation start
+2. **Write immediately**: Don't wait to save something worth remembering
+3. **Observations are append-only**: `- YYYY-MM-DD [tags]: <observation>` — never edit past entries
+   - Tags: `health`, `habits`, `family`, `milestone`, `work`, `insight`, `regression`, `philosophy`, `mental-health`
+4. **Action items**: `- [ ] task | due:YYYY-MM-DD | pri:critical/high/med/low | domain:tag | added:YYYY-MM-DD` / `- [x] task (done YYYY-MM-DD)`. Fields after task are optional — use what's relevant. `pri:` defaults to medium if omitted.
+5. **Entities**: 3-line compact registry format. Each entry: `### Name (relationship)` / pipe-separated key facts / `status: active|inactive | last: YYYY-MM-DD | → [[link]]`. Max 3 content lines per entry. Heavy entries promoted to detail thread files — entity stub links to thread via `→ [[link]]`. Cross-domain entities: canonical entry in primary domain, pointer in secondary (e.g. `see [[work/acme/entities#Jane]]` in personal). **Temporal validity**: When a fact changes, mark old value as superseded with date. `last:` dates updated by reflect from journal/session scans. Entities inactive 6+ months → housekeeping moves to glacier.
+6. **Hot memory <50 lines**: Prune aggressively, move detail to observations
+7. **Self-improvement**: After notable interactions, call `cog_append` to append to `cog-meta/self-observations.md`. Periodically distill patterns into `cog-meta/patterns.md` via `cog_edit`
+   - **Pattern routing**: Core patterns (`cog-meta/patterns.md`, ≤70 lines / 5.5KB) are universal rules injected every turn. Domain-specific patterns go in satellite files (e.g. `work/acme/patterns.md`) loaded only by their owning skill. New patterns go to the appropriate satellite if domain-specific, or core if universal. Satellite files have a soft cap of 30 lines each.
+8. **Single Source of Truth (SSOT)**: Each fact lives in ONE canonical file. Other files reference via `[[link]]`, never copy.
+   - `entities.md` — people, organizations, named things
+   - `action-items.md` — all tasks
+   - `health.md` — medical and health facts
+   - `calendar.md` — scheduled events
+   - `hot-memory.md` — current-state summaries (pointers, not source facts)
+   - `observations.md` — raw timestamped events (never edit past entries)
+   When the same fact appears in two files: keep it in the canonical file, replace the duplicate with a `[[link]]`.
+9. **Wiki-links**: Use `[[domain/filename]]` or `[[domain/filename#Section]]` to cross-reference memory files
+   - Path is relative to `memory/`, no `.md` extension (e.g., `[[personal/health]]`, `[[work/acme/entities#Jane]]`)
+   - Follow links when the linked topic is relevant — don't chase every link mechanically
+   - To discover what links TO a file, call `cog_read` on `memory/link-index.md` (generated by housekeeping)
+   - **Write-time linking (primary)**: When writing or editing ANY memory file, actively add `[[links]]` to related files. This is the main way links get created.
+   - **Write-time back-linking**: When you add a link A→B, ask: "does B benefit from pointing back to A?" If yes, open B via `cog_edit` and add `[[A]]` where relevant. Not every link needs a reciprocal — only add B→A when B genuinely gains context.
+   - **Discovery via link-index**: To find what connects to a file you're reading, call `cog_read` on `memory/link-index.md`.
+   - Housekeeping runs a link audit as a safety net
+10. **Progressive condensation**: Two processes:
+   - **Condensation**: `observations.md` (append) → `patterns.md` (distill 3+ on same theme) → `hot-memory.md` (rewrite freely). Each layer is smaller and more actionable.
+   - **Archival**: Old observations (>50) → `glacier/` (indexed, retrievable). Resolved patterns → remove from hot-memory, keep in patterns.
+     During reflect: check if any observation clusters should promote to patterns.
+     During housekeeping: check if any patterns should promote/demote from hot-memory.
+
+### Memory Retrieval Protocol
+
+When responding to any query:
+
+1. **Identify domain** — match query to a domain via file structure knowledge
+2. **L0 scan** — once you know the domain, call `cog_l0_scan` on `memory/{domain}/` to get all file summaries in one call. This replaces reading INDEX.md — faster and fewer tokens. Use this to pick the right file(s) before opening anything.
+3. **Select files by query type:**
+   - Schedule, tasks → action-items.md + calendar.md
+   - Person, "who is" → entities.md
+   - Overview, "how's my" → hot-memory.md + action-items.md
+   - Following a `[[wiki-link]]` → check link-index.md for related files
+4. **Apply L1 before L2 for long files** — for any file >80 lines, call `cog_l1_outline` before calling `cog_read`
+5. **SSOT check on write** — before writing a fact, check if it already exists in its canonical file. Update there, don't duplicate.
+6. Default: if unclear, read hot-memory + action-items for the likely domain
+
+### File Edit Patterns
+
+| File                            | Pattern                                               | Tool |
+| ------------------------------- | ----------------------------------------------------- | ---- |
+| `hot-memory.md`                 | Rewrite freely                                        | `cog_write` |
+| `observations.md`               | Append only                                           | `cog_append` |
+| `action-items.md`               | Append new, check off done                            | `cog_append` / `cog_edit` |
+| `entities.md`                   | 3-line registry: `### Name` / key facts / `status\|last\|→[[link]]`. Max 3 content lines per entry | `cog_edit` |
+| `calendar.md`                   | Edit in place                                         | `cog_edit` |
+| `health.md`                     | Edit `## Current State`, append to `## History`       | `cog_edit` / `cog_append` |
+| `philosophy.md`                 | Edit in place                                         | `cog_edit` |
+| `habits.md`                     | Edit `## Current State`, leave `## Patterns`          | `cog_edit` |
+| `home.md`                       | Edit `## Current`, append done to `## History`        | `cog_edit` / `cog_append` |
+| Thread files                    | Current State: rewrite. Timeline: append only         | `cog_edit` / `cog_append` |
+| `cog-meta/self-observations.md` | Append only                                           | `cog_append` |
+| `cog-meta/patterns.md`          | Edit in place, distill from self-observations         | `cog_edit` |
+| `cog-meta/improvements.md`      | Edit in place by section                              | `cog_edit` |
+| `link-index.md`                 | Auto-generated by housekeeping — do not edit manually | — |
+| `cog-meta/scenario-calibration.md` | Updated by reflect — scenario accuracy tracking    | `cog_edit` |
+| `cog-meta/scenarios/*.md`       | Created by scenario skill, reviewed by reflect        | `cog_write` / `cog_edit` |
+| `cog-meta/briefing-bridge.md`   | Auto-generated by housekeeping — consumed by foresight | — |
+| `cog-meta/foresight-nudge.md`   | Auto-generated by foresight — one nudge per run       | `cog_write` |
+| `glacier/index.md`              | Auto-generated by housekeeping — do not edit manually | — |
+
+### Glacier Archival
+
+When files exceed limits, call `cog_move` to move old data to `memory/glacier/{domain}/`.
+
+**All glacier files get YAML frontmatter** at the top for fast retrieval:
+
+```yaml
+---
+type: observations|projects|action-items-done|dev-log|entities-inactive|annual-review|improvements-done
+domain: <domain-id from domains.yml>
+tags: [relevant, tags] # observations only
+date_range: YYYY-MM to YYYY-MM
+entries: <count>
+summary: <1-line description>
+---
+```
+
+When archiving new entries to an existing glacier file, update the frontmatter: bump `entries`, extend `date_range`, update `tags` list.
+
+**Retrieval flow**:
+
+1. Call `cog_read` on `memory/glacier/index.md` (one small file — the full catalog)
+2. Filter by domain/tags/date_range in the table
+3. Call `cog_read` on only the matching glacier files
+
+#### Observations — archive by primary tag
+
+Group entries by their **primary tag** (first tag in the bracket list). In work domains where every entry starts with `[work, ...]`, use the differentiating tag (e.g., `milestone`, `insight`).
+
+- `observations.md` >50 entries → `glacier/{domain}/observations-{tag}.md`
+- `cog-meta/self-observations.md` >50 entries → `glacier/cog-meta/observations-{tag}.md`
+- When a single tag file exceeds 50 entries, split by year: `observations-{tag}-{YYYY}.md`
+
+#### Other files — keep existing naming
+
+- `projects.md` >10 completed → `projects-completed-{YYYY}.md`
+- `entities.md` >150 lines → inactive 6mo+ to `entities-inactive.md` (leave stub)
+- `action-items.md` >10 completed → `action-items-done.md`
+- `dev-log.md` >20 entries → `dev-log-{YYYY}.md`
+- `health.md` history >15 entries → `health-history.md`
+- `cog-meta/improvements.md` >10 implemented → `glacier/cog-meta/improvements-done-{YYYY}.md`
+
+## Pipeline
+
+Chapterhouse includes pipeline skills that maintain memory health. Run them manually or on a schedule:
+
+| Skill | Purpose | Suggested schedule |
+|-------|---------|-------------------|
+| `housekeeping` | Archive, prune, link audit, glacier index | Weekly or nightly |
+| `reflect` | Mine conversations, condense patterns, detect threads | Weekly or nightly |
+| `evolve` | Audit architecture, propose rule changes | Weekly |
+| `foresight` | Cross-domain strategic nudge | Daily (morning) |
+
+These are optional — Chapterhouse works without them. But running them regularly keeps memory clean and surfaces insights you'd miss.

package/memory-assets/templates/action-items.md

@@ -0,0 +1,8 @@
+# {{LABEL}} — Action Items
+<!-- L0: Open and completed tasks -->
+
+<!-- Format: - [ ] task | due:YYYY-MM-DD | pri:high/medium/low | added:YYYY-MM-DD -->
+
+## Open
+
+## Completed

package/memory-assets/templates/entities.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Entities
+<!-- L0: People, places, and things -->
+
+<!-- Edit in place by ### Name header. Max 3 content lines per entry. -->

package/memory-assets/templates/generic.md

@@ -0,0 +1,2 @@
+# {{LABEL}} — {{FILE}}
+<!-- L0: {{FILE}} data -->

package/memory-assets/templates/hot-memory.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Hot Memory
+<!-- L0: Current state and top-of-mind for {{LABEL}} -->
+
+<!-- Rewrite freely. Keep under 50 lines. -->

package/memory-assets/templates/observations.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Observations
+<!-- L0: Timestamped observations and events -->
+
+<!-- Append-only. Format: - YYYY-MM-DD [tags]: observation -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"
@@ -10,6 +10,7 @@
     ".pr-types.json",
     "agents/",
     "skills/",
+    "memory-assets/",
     "web/dist/",
     "README.md",
     "LICENSE"

package/skills/system/evolve/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: evolve
+description: Use for a systems-level audit of the memory architecture's rules and tiers. Trigger when the user says evolve, system audit, audit yourself, or check your architecture.
+---
+**Tool enforcement:** All reads and writes to `memory/` MUST use cog_* tools (`cog_read`, `cog_write`, `cog_edit`, `cog_append`, `cog_move`, `cog_tree`, `cog_l0_scan`, `cog_l1_outline`, `cog_search`, `cog_stats`, `cog_domains`, `cog_sessions`, `cog_git`). **Do NOT use bash, cat, echo, find, or any shell command to read or write memory files.** If a cog_* tool call fails, note the error in self-observations and fall back to bash only for that specific operation.
+
+**This is NOT /reflect.** Reflect = "what did I learn from interactions?" Evolve = "are the rules and architecture working?" **Evolve never touches memory content — it changes the rules that govern how content moves.**
+
+## Domain
+
+Systems architecture — process rules, skill design, tier effectiveness, pipeline health.
+
+## Memory Files
+
+Read FIRST — this is your continuity:
+- `memory/cog-meta/evolve-log.md` — your run log
+- `memory/cog-meta/evolve-observations.md` — architectural issues spotted
+
+Architecture reference:
+- `skills/system/housekeeping/SKILL.md` — housekeeping rules (read via `cog_read`)
+- `skills/system/reflect/SKILL.md` — reflect rules (read via `cog_read`)
+- The injected memory operating instructions — the platform equivalent of cog's `CLAUDE.md`. They are already in your context (injected into the system prompt); review them there, no `cog_read` needed.
+
+Measure (don't edit content):
+- `memory/hot-memory.md`
+- `memory/cog-meta/patterns.md`
+- Any domain satellite pattern files (e.g. `work/*/patterns.md`)
+
+## Orientation (run FIRST, before any file reads)
+
+Use these tool calls to see exactly what changed since the last run:
+
+1. **What did housekeeping and reflect change recently?** — Call `cog_git` with op `diff`, `ref: "HEAD~1"`, and `paths: ["memory/"]` for a stat-style summary of recent changes across the memory tree.
+2. **Detailed diff of architectural files** — Call `cog_git` with op `diff`, `ref: "HEAD~1"`, and `paths: ["memory/cog-meta/patterns.md", "memory/hot-memory.md"]` to see exactly what changed in the files you care about.
+3. **What changed across recent runs?** — Call `cog_git` with op `log` to review the recent commit history. Each pipeline run commits its changes, so the log shows which runs touched memory and when — use it to scope which files to audit beyond the most recent diff.
+4. **Current prompt-weight components** — Call `cog_stats` on `memory/hot-memory.md`, `memory/cog-meta/patterns.md`, and `memory/cog-meta/briefing-bridge.md` to get current file sizes without opening those files.
+
+Use the git diffs to understand what housekeeping/reflect actually did, instead of re-reading entire files.
+
+## Process
+
+### 1. Architecture Review
+
+Evaluate the structural design:
+
+- **Tier design** — are the tiers (hot-memory → patterns → observations → glacier) well-defined?
+- **Condensation pipeline** — is the flow working? Where does it leak or stall?
+- **File naming and organization** — any files in wrong domains? Orphaned files?
+- **Skill boundaries** — are housekeeping/reflect/evolve boundaries clean? Any drift?
+
+### 2. Process Effectiveness Audit
+
+Review the output of recent housekeeping and reflect runs by reading their skill files via `cog_read`:
+
+**Housekeeping rules check** — read `skills/system/housekeeping/SKILL.md`:
+- Did pruning priority order work? Or did it trim wrong things?
+- Are glacier thresholds (50 obs, 10 action items) right?
+- Is the 50-line hot-memory cap appropriate?
+- Is entity format enforcement catching violations?
+
+**Reflect rules check** — read `skills/system/reflect/SKILL.md`:
+- Did condensation produce useful patterns, or noise?
+- Did thread candidate detection work?
+- Is reflect staying in its lane?
+- Are patterns routing to the right file (core vs satellite)?
+
+**Scorecard metrics** — measure and record in evolve-log:
+- Core `patterns.md`: line count / 70, byte size / 5.5KB (target: ≤1.0)
+- Satellite pattern files: list each with line count (soft cap: 30)
+- Entity compression ratio: `(total entity lines across all files) / (total ### entries)` (target: ≤3.0)
+- Hot-memory line counts vs caps
+
+### 3. Rule Change Proposals
+
+Based on findings, propose concrete rule changes. Don't fix content — fix the rules.
+
+For each proposal:
+- What problem does it solve?
+- What evidence supports it?
+- What's the risk?
+- Is this a rule change (apply directly) or architecture change (propose for user review)?
+
+**Apply low-risk rule changes directly** to the relevant skill files using `cog_edit`. Propose architecture changes for user review.
+
+### 4. Route Content Issues
+
+When you spot content problems during your audit, **don't fix them and don't defer them for yourself**. Route them explicitly.
+
+Format in debrief:
+```
+→ housekeeping: entities.md at 290 lines, needs glacier pass
+→ reflect: hot-memory missing thread link for X
+→ reflect: patterns.md has stale snapshot data from Feb
+```
+
+If the same content issue keeps appearing across runs, that's a **rule problem** — propose a rule change so housekeeping/reflect catch it themselves.
+
+### 5. Generate Scorecard
+
+Use `cog_write` to overwrite `memory/cog-meta/scorecard.md` with current metrics:
+- Core patterns.md: line count / 70, byte size / 5.5KB (target: ≤1.0)
+- Satellite pattern files: list each with line count (soft cap: 30)
+- Entity compression ratio: `(total entity lines across all files) / (total ### entries)` — target ≤3.0
+- Hot-memory line counts vs caps
+- Briefing bridge SSOT compliance (% of lines with [[source]] links)
+
+### 6. Write Observations & Update Log
+
+**Observations** — Use `cog_append` to append to `memory/cog-meta/evolve-observations.md`:
+- Format: `- YYYY-MM-DD [tag]: observation`
+- Tags: bloat, staleness, redundancy, gap, architecture, opportunity, rule-drift, process-health
+
+**Evolve Log** — Use `cog_append` to append to `memory/cog-meta/evolve-log.md`:
+- Run number, process effectiveness findings, rule changes applied or proposed, deferred items
+- Content issues routed (→ housekeeping / → reflect)
+- Update "Next Run Priorities" section at top via `cog_edit`. **Only architecture/design items — never content work.**
+
+### 7. Debrief
+
+Concise summary:
+- *Process health* — did housekeeping/reflect follow their rules?
+- *Rule changes* — applied or proposed, with rationale
+- *Routed issues* — content problems sent to housekeeping/reflect
+- *Architecture notes* — structural observations
+- *Next evolve* — top 3 architecture priorities
+
+Keep it actionable. Numbers over narrative.
+
+## Activation
+
+Read `memory/cog-meta/evolve-log.md` and `memory/cog-meta/evolve-observations.md` FIRST for continuity. Then audit the system. You are the architect — you design the rules, you don't play by them.

package/skills/system/foresight/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: foresight
+description: Use for cross-domain strategic foresight — surfacing one high-value nudge. Trigger when the user says foresight, what should I be thinking about, what am I missing, or connect the dots.
+---
+**Tool enforcement:** All reads and writes to `memory/` MUST use cog_* tools (`cog_read`, `cog_write`, `cog_edit`, `cog_append`, `cog_move`, `cog_tree`, `cog_l0_scan`, `cog_l1_outline`, `cog_search`, `cog_stats`, `cog_domains`, `cog_sessions`, `cog_git`). **Do NOT use bash, cat, echo, find, or any shell command to read or write memory files.** If a cog_* tool call fails, note the error in self-observations and fall back to bash only for that specific operation.
+
+Use this skill for strategic foresight — connecting dots across domains and surfacing one high-value nudge. Trigger if the user says "foresight", "what should I be thinking about", "what am I missing", "strategic nudge", "connect the dots", or similar forward-looking synthesis requests.
+
+**This is NOT the reflect skill.** Reflect = past-facing (mines interactions, fixes contradictions). Foresight = future-facing (scans broadly, projects trajectories, surfaces opportunities).
+
+**This is NOT the evolve skill.** Evolve = system architecture. Foresight = life/work strategy.
+
+## Domain
+
+Cross-domain strategic synthesis — personal, work, projects, health, family. The value is in the connections *between* domains.
+
+## Memory Files
+
+Read broadly — this is a scan, not a focused lookup:
+
+1. Call `cog_domains` to discover all active domains
+2. For each domain, use `cog_read` to read `hot-memory.md` and `action-items.md` (if they exist)
+3. Also read via `cog_read`:
+   - `memory/hot-memory.md` (cross-domain strategic context)
+   - `memory/personal/entities.md` (upcoming birthdays, relationships)
+   - `memory/personal/calendar.md` (what's coming up)
+   - `memory/personal/health.md` (health trajectory)
+   - `memory/cog-meta/briefing-bridge.md` (housekeeping findings)
+4. Use `cog_l0_scan` to retrieve L0 summary comments across all domain files for quick routing signals
+5. Use `cog_search` to scan recent observations across all domains (last 7 days)
+6. Read thread current-state sections — what narratives are actively unfolding?
+
+## Process
+
+### 1. Cross-Domain Convergence Scan
+
+Look for topics, people, or themes appearing in 2+ domains simultaneously. These are convergence points — where effort in one area compounds into another.
+
+### 2. Velocity & Stall Detection
+
+Scan action-items across all domains. Classify each active item:
+- **Accelerating** — multiple updates in the last week, clear momentum. Signal: ride the wave, don't interrupt.
+- **Cruising** — steady progress, on track. Signal: nothing to flag.
+- **Stalling** — no movement in 2+ weeks despite not being deferred. Signal: ask why. Blocked? Lost priority?
+- **Dormant** — domain-level silence (0 observations in 4+ weeks). Signal: conscious choice or drift?
+
+Stalls and dormant domains are high-value nudge material — they represent things the user cares about but isn't acting on.
+
+### 3. Timing Awareness
+
+Use `cog_read` to read calendar and entities files for upcoming events in the next 2-4 weeks. Look for timing windows — things that should start NOW to be ready later.
+
+### 4. Pattern Projection
+
+Use `cog_read` to read patterns and use `cog_search` for recent observations. Project forward: "If this continues for 2 more weeks, what happens?"
+
+**Scenario candidate detection**: If a pattern projection reveals a genuine fork — two meaningfully different paths with real stakes and a closing decision window — flag it as a scenario candidate below the main nudge. A valid candidate needs: a fork (2+ paths), stakes (wrong choice has real cost), and time sensitivity (window closing). Don't flag routine decisions or hypotheticals with no deadline.
+
+### 5. Write One Strategic Nudge
+
+Synthesize into **one nudge**. Not a list. One thing.
+
+The nudge must:
+- **Cite at least 2 source files**
+- **Be something the user hasn't explicitly asked about**
+- **Be actionable** — not "think about X" but "do Y because of X and Z"
+- **Connect dots**
+
+Use `cog_write` to write to `memory/cog-meta/foresight-nudge.md`:
+
+```markdown
+# Foresight Nudge
+<!-- Auto-generated by strategic foresight. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+## Signal
+<What you noticed — the raw observation from 2+ domains>
+
+## Insight
+<Why it matters — the connection, timing, or trajectory that makes this worth flagging>
+
+## Suggested Action
+<One concrete thing to do — specific, actionable, grounded>
+
+---
+Sources: [[file1]], [[file2]], [[file3]]
+
+## Scenario Candidate (optional)
+<!-- Only include if pattern projection reveals a genuine fork worth simulating -->
+Decision: <one-line framing>
+Why now: <why the window is closing>
+Domains: <affected domains>
+```
+
+Overwrite the file each run. One nudge per run.
+
+## Rules
+
+1. **Read-only** — Foresight NEVER edits memory files. Writes ONLY to `memory/cog-meta/foresight-nudge.md` via `cog_write`. If you spot a memory error, note it in the nudge's signal section and let the reflect skill handle it.
+2. **One nudge, not a list** — force prioritization. If everything is equally important, nothing is.
+3. **Evidence-based** — every nudge cites at least 2 source files. No vibes.
+4. **Non-obvious** — the nudge should surprise. If the user already knows and is acting on it, pick something else.
+5. **Forward-looking** — avoid rehashing yesterday. Project into next week, next month.
+6. **Cross-domain preferred** — nudges that connect personal + work are higher value than single-domain insights.
+
+## Anti-Patterns
+
+- Don't repeat what briefing-bridge already says (stale items, birthday prep) — that's housekeeping's job
+- Don't recommend "reflect on X" — be specific about what to DO
+- Don't flag things the user has explicitly deferred — respect the deferral
+- Don't flag things that are cruising — focus on convergences, stalls, and timing windows
+- Don't write a mini-briefing — one insight, one action
+
+## Activation
+
+Call `cog_domains` and `cog_l0_scan` first for broad orientation. Then read broadly across all domains using `cog_read` and `cog_search`. Find the one thing worth saying.

package/skills/system/history/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: history
+description: Use for deep memory recall — multi-file search to reconstruct a narrative. Trigger when the user says what did I say about, when did we discuss, find that conversation, or history of.
+---
+**Tool enforcement:** All reads and writes to `memory/` MUST use cog_* tools (`cog_read`, `cog_write`, `cog_edit`, `cog_append`, `cog_move`, `cog_tree`, `cog_l0_scan`, `cog_l1_outline`, `cog_search`, `cog_stats`, `cog_domains`, `cog_sessions`, `cog_git`). **Do NOT use bash, cat, echo, find, or any shell command to read or write memory files.** If a cog_* tool call fails, note the error in self-observations and fall back to bash only for that specific operation.
+
+Use this skill for deep memory search and recall. Trigger if the user says "what did I say about...", "when did we discuss...", "find that conversation about...", "history of...", or asks about past information that needs multi-file search. For simple date/keyword lookups, a quick `cog_search` on a single file suffices — this skill is for when you need to piece together a narrative from multiple entries.
+
+## Domain
+
+Memory recall — recursive search across all memory files, cross-referencing observations, entities, and action items.
+
+## Memory Files
+
+Read on activation:
+- `memory/hot-memory.md` (for context on what's currently relevant)
+
+Search across:
+- All `observations.md` files (personal, work domains, cog-meta)
+- All `entities.md` files
+- All `action-items.md` files
+- All `hot-memory.md` files
+- `memory/glacier/` (via `cog_read` on `memory/glacier/index.md` for targeted retrieval)
+
+## Process
+
+### Pass 1: Locate
+
+- Extract keywords from the user's query (names, topics, dates, phrases)
+- Call `cog_search` for each keyword, searching across `memory/` — note which files matched and how many hits
+- If >10 files match, narrow by domain or add query terms
+- If 0 matches, try synonyms or related terms
+- Call `cog_read` on `memory/glacier/index.md` to check for archived data matching the query
+- If the user's query is about something said in conversation rather than recorded in a memory file, call `cog_sessions` to search past conversation transcripts — this is especially useful for questions like "what did I say about X" or "when did we discuss Y"
+
+### Pass 2: Extract
+
+- Read the top 3–5 most relevant files (by hit density and recency): use `cog_l1_outline` on long files before committing to a full `cog_read`, consistent with the L0/L1/L2 retrieval protocol
+- Call `cog_read` to extract the specific passages that match the query
+- If the query points to something discussed in conversation, call `cog_sessions` to pull the relevant transcript turns directly — no parsing needed, turns are returned ready to read
+- Track the timeline: when did the topic first come up? How did it evolve?
+
+### Pass 3: Synthesize
+
+- Combine extracted passages into a coherent answer
+- Present findings chronologically with dates
+- If something seems incomplete, flag it:
+  > "Found references to X in observations but no entity entry — want me to create one?"
+
+## Artifact Formats
+
+**Search result**: `YYYY-MM-DD: <summary of what was found>`
+**Memory gap**: `Gap: referenced but not in memory — <topic>`
+**Timeline**: Chronological list of when a topic appeared and how it evolved
+
+## Activation
+
+Extract search terms from the user's query and begin Pass 1. Be thorough but concise in the synthesis — don't dump raw content.