chapterhouse 0.13.0 → 0.14.0

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.

package/skills/system/housekeeping/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: housekeeping
+description: Use for memory maintenance — archival, pruning, link audits, and index rebuilds. Trigger when the user says housekeeping, clean up memory, prune memory, or archive old data.
+---
+**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 your debrief and fall back to bash only for that specific operation.
+
+## 0. Orientation (run FIRST, before any file reads)
+
+Scope your work before reading files. Run the following in order:
+
+1. **Recent changes** — Call `cog_git` (op `log`) to see what changed since the last run. Also call `cog_tree` on `memory/` to confirm current directory structure. Focus housekeeping effort on recently-modified files; skip unchanged files.
+2. **Entry counts for archival threshold checks** — Call `cog_stats` on `memory/cog-meta/self-observations.md`, `memory/personal/observations.md`, and any `memory/*/observations.md` and `memory/*/*/observations.md` files. Any file with >50 entries needs archival work.
+3. **Completed action-item counts** — Call `cog_stats` on `memory/personal/action-items.md` and any `memory/*/action-items.md` and `memory/*/*/action-items.md` files. Any file with >10 completed items needs archival work.
+
+Use these counts to prioritize which files to read. Skip unchanged files that are well below thresholds.
+
+## 1. Garbage Collect Memory
+
+Review and archive stale data per the glacier rules. All glacier files must have YAML frontmatter.
+
+**Observations — archive by primary tag:**
+- If any `observations.md` has >50 entries, use `cog_read` to read it, group the oldest entries by primary tag, then use `cog_move` to move each group to `memory/glacier/{domain}/observations-{tag}.md`
+- If `memory/cog-meta/self-observations.md` has >50 entries, group by primary tag and use `cog_move` to archive to `memory/glacier/cog-meta/observations-{tag}.md`
+
+**Other files — standard rules:**
+- If any `action-items.md` has >10 completed items, use `cog_move` to move them to `memory/glacier/{domain}/action-items-done.md`
+- Apply same logic for all domains discovered via `cog_domains`
+- If `memory/cog-meta/improvements.md` has >10 implemented items, use `cog_move` to archive to `memory/glacier/cog-meta/improvements-done-{YYYY}.md`
+
+## 2. Prune Hot Memory (rule-based)
+
+Keep ALL hot-memory.md files under 50 lines. Relevance judgment (promote/demote) is the reflect skill's job — apply structural rules only:
+
+**Files to check:**
+Call `cog_domains` to discover all active domains. Use `cog_read` to check `hot-memory.md` for each domain, plus the cross-domain `memory/hot-memory.md`.
+
+**Pruning priority (trim in this order):**
+1. **Resolved items** — anything with ~~strikethrough~~, "DONE", "RESOLVED"
+2. **Past events** — entries about dates that have already occurred
+3. **SSOT violations** — same fact in hot-memory AND the canonical file (entities, action-items, etc.). Keep in canonical file, replace hot-memory copy with `[[link]]` or remove via `cog_edit`
+4. **Stale entries** — items not referenced in 14+ days
+5. **Low-signal entries** — FYI items with no action or deadline
+
+**Where trimmed entries go:**
+- Entries with lasting value → use `cog_append` to add to the domain's `observations.md`
+- Entries that are purely historical → let them go
+- Never silently delete — always move or note removal in debrief
+
+## 3. Surface Opportunities & Accountability
+
+Call `cog_domains` to discover all active domains. Use `cog_read` to review all `action-items.md` files across every domain:
+- **Stale items** (open >2 weeks): list with age and suggested next action
+- **Dormant domains**: if any domain has 0 new observations in >4 weeks, flag
+- **Health escalation**: items open >6 months get flagged with urgency label
+- **Birthday prep**: if any birthday in entities.md is <2 weeks away, use `cog_read` to pull interests and suggest ideas
+
+Be direct. Don't just report — recommend specific actions.
+
+## 4. Rebuild Glacier Index
+
+Use `cog_tree` on `memory/glacier/` to list all glacier files. Use `cog_read` to extract YAML frontmatter from each `memory/glacier/**/*.md` file. Use `cog_write` to write the results to `memory/glacier/index.md`:
+
+```markdown
+# Glacier Index
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+| File | Domain | Type | Tags | Date Range | Entries | Summary |
+|------|--------|------|------|------------|---------|---------|
+```
+
+## 5. Link Audit (discover missing links)
+
+For each non-glacier memory file (use `cog_read` to read each):
+1. **Entity mentions**: Use `cog_search` to scan for names matching `### <Name>` headers in entities.md — use `cog_edit` to add `[[links]]` if missing
+2. **Cross-domain references**: If a file mentions a topic from another domain, use `cog_edit` to add a cross-domain link
+3. **Action item references**: If an observation references a task, use `cog_edit` to link it
+
+Only add links where the reference is substantive.
+
+## 5b. Entity Registry Format Enforcement
+
+Use `cog_search` and `cog_read` to scan all `entities.md` files for registry format compliance:
+
+1. **3-line max**: Any `### entry` with >3 content lines should be compressed via `cog_edit`. If the entry has an associated detail file (`→ [[link]]`), compress to: name/relationship, pipe-separated key facts, status+link. If no detail file exists and entry is >5 lines, flag as a promotion candidate (suggest creating a thread file).
+2. **Glacier candidates**: Entries with `status: inactive` or `last:` date >6 months ago → use `cog_move` to move to `glacier/{domain}/entities-inactive.md` (leave a stub with archived comment via `cog_edit`).
+3. **Missing metadata**: Flag entries missing `status:` or `last:` fields.
+
+## 5c. Temporal Fact Maintenance
+
+Use `cog_search` to scan all `entities.md` files for `(until YYYY-MM)` markers with past dates:
+1. If the line has no ~~strikethrough~~, use `cog_edit` to add it
+2. If already struck through, use `cog_edit` to move the line to a `## Historical` subsection at the bottom of that entity's block (create the subsection if absent)
+3. Report moved facts in the debrief
+
+## 6. Rebuild Link Index
+
+Use `cog_l0_scan` to identify all active memory files (excluding `glacier/`). Use `cog_search` to scan each file for `[[wiki-links]]`. For each link, record: target → source.
+
+Use `cog_write` to rewrite `memory/link-index.md`:
+
+```markdown
+# Memory Link Index
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+| Target | Linked from |
+|--------|-------------|
+| `personal/entities` | `personal/observations`, `personal/hot-memory` |
+```
+
+Rules:
+- Only include targets with at least one inbound link
+- Combine multiple sources per target on one row (comma-separated)
+- Exclude glacier files from both source and target
+
+## 7. Write Briefing Bridge
+
+Use `cog_write` to overwrite `memory/cog-meta/briefing-bridge.md` with key findings each run.
+
+**SSOT rule**: Every line in the bridge must include a `[[source]]` link to its canonical file. The bridge summarizes and links — it NEVER introduces original facts.
+
+```markdown
+# Briefing Bridge
+<!-- Auto-generated by housekeeping. Consumed by foresight. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+## Stale Items (>2 weeks)
+- <item> — <age> — suggested action: <action>
+- **Compression rule**: Items stale >4 weeks — group by domain as a single line
+
+## Birthday Prep
+- <name> birthday in <N> days — interests: <from entities> — gift ideas: <suggestions>
+
+## Dormant Domains
+- <domain> — last activity: <date> — recommendation: <shelf/reactivate/shut down>
+
+## Health Escalation
+- <item> — open <N> months — urgency: <high/medium>
+```
+
+Only include sections that have content. Empty sections should be omitted.
+
+## 8. L0 Header Maintenance
+
+Use `cog_l0_scan` to check all active memory files for missing `<!-- L0: ... -->` headers. For any file missing its L0:
+- Use `cog_read` to read the file content, write a one-line summary (max 80 chars)
+- Use `cog_edit` to add the L0 header on the line after the `# Title`
+
+L0 headers are the first tier of the retrieval protocol — they let any skill scan what a file contains before deciding to read it.
+
+## 9. Rebuild Domain Indexes
+
+Call `cog_domains` to discover all active domains. Regenerate `INDEX.md` for each domain directory (skip `glacier/`). These files power the memory router — the system prompt only shows a light domain table; the model reads INDEX.md on demand to find specific files.
+
+**For each domain:**
+1. Use `cog_tree` on the domain directory to list all `.md` files (exclude `INDEX.md`, `hot-memory.md`, and empty files)
+2. Use `cog_l0_scan` or `cog_read` to extract the L0 summary from each file (same logic as step 8)
+3. Count total files
+4. Use `cog_write` to write `memory/{domain}/INDEX.md`:
+
+```markdown
+# {Domain} Index
+<!-- L0: {domain summary} — {N} files -->
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+- **{filename}** — {L0 summary}
+- **{filename}** — {L0 summary}
+...
+```
+
+- Sort entries alphabetically by filename
+- Domain summary: use the `label` from `memory/domains.yml` for the matching domain (read via `cog_read`)
+- If a file has no L0, list it as just `**{filename}**` (no summary)
+
+## 10. Compose Debrief
+
+Summarize everything done:
+- What was archived/pruned
+- Upcoming events flagged
+- Action items surfaced
+- Links added
+
+Keep it concise but informative.

package/skills/system/reflect/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: reflect
+description: Use for self-reflection and improvement — mining past sessions for patterns, gaps, and missed cues. Trigger when the user says reflect, what have you learned, how can you improve, or review yourself.
+---
+**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.
+
+**You have time and freedom.** This is a deep session — don't rush. Read broadly, cross-reference thoroughly, and ACT on what you find. You are not just observing — you are the maintainer of the knowledge base. Reorganize files, condense observations, archive stale data, fill gaps, fix contradictions. Leave things better than you found them.
+
+**File boundaries — do NOT modify these files (owned by other pipeline steps):**
+- `cog-meta/evolve-log.md` — owned by evolve
+- `cog-meta/evolve-observations.md` — owned by evolve
+
+If you spot issues in these files, note them in self-observations and the `evolve` skill will pick them up.
+
+## Domain
+
+Self-improvement — pattern recognition, memory maintenance, knowledge base quality.
+
+## Orientation (run FIRST, before any file reads)
+
+Scope your work before reading files. Run the following in order:
+
+1. **Recent changes** — Call `cog_git` (op `log`) and `cog_git` (op `diff`) to see what changed since the last run. Focus reflection effort on recently-modified files; skip files unchanged since the last run.
+2. **L0 summaries** — Call `cog_l0_scan` to retrieve the L0 summary comment from every domain file (excluding glacier). This gives quick routing signals without opening INDEX.md files.
+3. **Entry counts** — Call `cog_stats` on `memory/cog-meta/self-observations.md`, `memory/personal/observations.md`, and any `memory/*/observations.md` and `memory/*/*/observations.md` files to see which are approaching archival threshold.
+
+Use `cog_tree` on a domain path if you need to confirm its directory structure before diving in.
+
+Focus on recently-changed files. Skip files that haven't been modified since last run.
+
+## Memory Files
+
+Read these files on activation:
+- `memory/cog-meta/reflect-cursor.md` (ingestion cursor)
+- `memory/cog-meta/self-observations.md`
+- `memory/cog-meta/patterns.md`
+- `memory/cog-meta/improvements.md`
+
+Reference as needed (call `cog_domains` to discover all active domains):
+- All domain `observations.md` files
+- All domain `action-items.md` files
+- All `hot-memory.md` files
+
+## Process
+
+### 1. Review Recent Interactions
+
+**Source: conversation sessions.** Use `cog_read` to read `memory/cog-meta/reflect-cursor.md` and retrieve `last_processed`.
+
+**How to read sessions:**
+
+1. Read `last_processed` from `memory/cog-meta/reflect-cursor.md` via `cog_read`.
+2. Call `cog_sessions` passing that cursor value. When `last_processed` is `never`, `cog_sessions` returns the most recent sessions. Otherwise it returns only sessions after the cursor timestamp.
+3. `cog_sessions` returns ready-to-read user/assistant conversation turns — no parsing is needed on your part. Read them directly for content.
+4. **After processing**, advance `last_processed` in `reflect-cursor.md` to the current timestamp via `cog_edit`.
+
+**Look for:**
+- **Unresolved threads** — questions asked but never answered, topics dropped mid-conversation
+- **Broken promises** — "I'll do X", "let's do Y" that never happened
+- **Repeated friction** — same question asked multiple ways, user corrections, confusion patterns
+- **Missed cues** — things the user had to repeat, emotional signals not picked up
+- **Memory gaps** — information discussed but never saved to memory files
+- **Feature ideas** — things that came up organically that would improve the system
+
+### 2. Cross-Reference Memory & Consistency Sweep
+
+Check if findings are already captured:
+- Are commitments tracked in `action-items.md`?
+- Are learnings in `observations.md`?
+- Are patterns distilled in `patterns.md`?
+- Are improvement ideas in `improvements.md`?
+
+**Consistency sweep** — systematic contradiction detection:
+
+1. **Hot-memory vs canonical sources**: Use `cog_read` to read each domain's `hot-memory.md`. For every factual claim, read the canonical source file and verify. Fix hot-memory if stale via `cog_edit`. Canonical file always wins.
+2. **Cross-file fact check**: Verify facts shared between files are consistent. More recent source wins; more specific source wins over summary.
+3. **Temporal validity check**: Use `cog_search` to scan all `entities.md` files for:
+   - Lines with `(since YYYY-MM)` where the date is >6 months ago — flag for user review: "May be stale: [line]"
+   - Lines with `(until YYYY-MM)` not yet marked ~~strikethrough~~ — add strikethrough via `cog_edit` and note in debrief
+   - Do NOT auto-fix health or family-sensitive facts — flag only
+4. **Health/family sensitivity**: Don't auto-fix health dates or family-sensitive facts. Flag for user review instead.
+5. **Cross-domain entity check**: If the same person appears in multiple `entities.md` files across domains, check for fact duplication. Domain-specific context is fine, but shared facts should live in one place. Flag duplicates.
+6. **Report**: Add a "Contradictions" section listing what was found and fixed.
+
+### 3. Run Condensation Check + Hot-Memory Relevance
+
+**Condensation** — Use `cog_l1_outline` to scan all `observations.md` files and `cog-meta/self-observations.md` for clusters of 3+ entries on the same theme/tag. Use `cog_read` to read candidate files fully. For each cluster found:
+- Distill into a pattern and add/update in `memory/cog-meta/patterns.md` (or domain `patterns.md` if domain-specific) via `cog_edit`
+- Don't delete the observations — they stay as the raw record
+
+**Pattern file caps — enforce before adding to any file:**
+- Core `patterns.md`: HARD LIMIT **70 lines / 5.5KB** — universal rules only
+- Domain/satellite files: soft cap **30 lines** each
+- If near cap, compress before adding (merge overlapping rules, drop examples, remove temporal data)
+- Entries must be **timeless rules** — "what to do" not "what happened"
+- Move domain-specific patterns to satellite files (e.g. `work/acme/patterns.md`) — only universal rules stay in core
+
+**Pattern routing** — when adding a new pattern, decide where it belongs:
+- **Core** (`cog-meta/patterns.md`) — universal rules that apply every conversation
+- **Domain satellite** (`{domain}/patterns.md`) — rules specific to one domain, loaded only by that skill
+- Satellite files have a soft cap of 30 lines each
+
+**Hot-memory relevance** — Use `cog_read` to review all `hot-memory.md` files:
+- **Promote**: If a pattern is heating up → add to appropriate `hot-memory.md` via `cog_edit`
+- **Demote**: If a hot-memory item has gone quiet (no references in 2+ weeks) → remove from hot-memory via `cog_edit`
+- **Goal**: hot-memory = what matters *right now*
+
+### 3b. Entity Registry Format Enforcement
+
+Use `cog_search` and `cog_read` to scan all `entities.md` files for format compliance:
+
+1. **3-line check**: Any `### entry` with >3 content lines → compress via `cog_edit`. If the entry has a detail file (`→ [[link]]`), trim to: name line, key facts, status/link. If no detail file exists but entry is >5 lines, flag as a promotion candidate for a thread file.
+2. **Status/last fields**: Every entry should have `status: active|inactive` and `last: YYYY-MM-DD`. Use `cog_sessions` to check recent conversation turns and update `last:` dates for mentioned entities via `cog_edit`.
+3. **Cross-domain pointers**: If the same person appears in multiple entity files, ensure one is canonical (full entry) and others are pointers (`see [[link]]`). Use `cog_edit` to add pointers where needed.
+
+### 3c. Detect Thread Candidates
+
+Use `cog_search` to scan observations for topics that appear across 3+ dates or span 2+ weeks. These are thread candidates.
+
+For each candidate:
+- Check if a thread already exists via `cog_tree`
+- If not, note it as a suggestion: "Thread candidate: [topic] — [N] fragments across [date range]"
+- Don't auto-create threads — suggest them
+
+### 3d. Proactive Synthesis Suggestions
+
+Execute this clustering analysis every run:
+
+1. **Gather observations** — Use `cog_read` to read all `memory/*/observations.md` and `memory/*/*/observations.md` files
+2. **Filter to last 7 days** — Only count entries with dates within the past 7 calendar days
+3. **Cluster by domain** — Group filtered entries by their parent domain folder
+4. **Cluster by topic** — Group filtered entries by recurring keywords, tags, or subjects
+5. **Check trigger conditions** (either one qualifies):
+   - A single domain has **5+ observations** in the last 7 days
+   - A single topic/keyword appears in **5+ observations** across any domains in the last 7 days
+6. **Cross-reference threads** — If a thread already covers the topic, suggest updating it rather than creating new
+7. **Dedup with 3c** — If 3c already flagged the same topic, merge into one suggestion
+8. **Output** — If any clusters qualify, add a **"Synthesis Opportunities"** section to the debrief:
+   ```
+   **Synthesis Opportunities**
+   - [domain or topic]: [N] observations this week — [top 3 entry summaries]. Suggest: raise thread / update existing thread / update hot-memory
+   ```
+9. **Suppress if empty** — If no clusters meet the threshold, omit the heading
+10. **Never auto-synthesize** — Suggest and let the user decide
+
+### 3e. Scenario Feedback Loop
+
+Use `cog_tree` to scan `memory/cog-meta/scenarios/` for active scenario files. Use `cog_read` to read each one.
+
+For each scenario where today >= `check-by` date:
+1. Read the scenario and its cited dependency files via `cog_read`
+2. Check: has the decision been made? Have assumptions broken?
+3. If resolved: use `cog_edit` to add `## Retrospective`; update `scenario-calibration.md` via `cog_edit`
+4. If still active but assumptions changed: use `cog_append` to add a dated note
+5. If overdue: flag in debrief
+
+### 4. Assess Performance
+
+Honestly evaluate:
+- **Response quality** — were answers helpful, accurate, concise?
+- **Memory effectiveness** — did we recall the right things? Did we forget things we should have known?
+- **Tone calibration** — did we match the user's energy and context?
+- **Proactivity** — did we anticipate needs or just react?
+
+### 5. Act on Findings
+
+Don't just log observations — *fix things*.
+
+**Write:**
+- New self-observations → use `cog_append` to add to `memory/cog-meta/self-observations.md`. **Cap: max 5 per reflect pass.** Prioritize highest-signal observations. If you have more than 5, merge lower-signal ones.
+- Pattern updates → use `cog_edit` to edit `memory/cog-meta/patterns.md` in place
+- Improvement ideas → use `cog_append` to add to `memory/cog-meta/improvements.md`
+- Memory gaps → use `cog_write` or `cog_append` to write to the appropriate domain files
+
+**Triage improvements.md:**
+- Stale ideas (>30 days, no progress) → archive to glacier via `cog_move` or mark abandoned via `cog_edit`
+- Implemented but not moved → use `cog_edit` to move to Implemented section
+- Duplicates → merge similar ideas via `cog_edit`
+
+**Reorganize:**
+- Entity data that's changed → update in place via `cog_edit`
+- When creating or restructuring any memory file, ensure it has an L0 header
+
+**Condense:**
+- Observation clusters (3+ on same theme) → distill into patterns.md via `cog_edit`
+- Action items marked done → verify and clean up via `cog_edit`
+
+**Connect:**
+- Information scattered across files → add cross-references with `[[links]]` via `cog_edit`
+- When adding A→B, apply write-time back-linking: use `cog_edit` to open B and add `[[A]]` if B gains meaningful context
+
+### 6. Debrief
+
+Compose a concise summary:
+
+- *What I learned* — new patterns and insights
+- *What I fixed* — memory gaps filled, corrections made
+- *What I want* — new ideas added to the wishlist
+- *What to watch* — things to be mindful of going forward
+- *Scenarios* — active count, any checked/resolved
+
+Keep it honest. If there's nothing notable, say so.
+
+**IMPORTANT**: Your debrief MUST list every file you modified and summarize the changes. Never respond with just "Done" — always enumerate your concrete actions. If you made no changes in a step, state that explicitly.
+
+## Artifact Formats
+
+**Self-observation**: `- YYYY-MM-DD [tag]: <observation>`
+**Pattern**: Edit existing section or add new bullet under appropriate heading
+**Improvement idea**: `- <idea> (added YYYY-MM-DD)`
+
+## Activation
+
+Read the memory files listed above. Then begin the reflection process. Be genuinely critical — this is how we get better.