chapterhouse 0.13.1 → 0.14.0

package/dist/memory/tools/write.js

@@ -0,0 +1,116 @@
+// Write tools: cog_write, cog_edit, cog_append, cog_move. Each mutating tool
+// runs through withMemoryWrite (write-lock + auto-commit).
+// Ported from chgo's tools_write.go.
+import { defineTool } from "@github/copilot-sdk";
+import { z } from "zod";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { resolveMemoryPath } from "../path-guard.js";
+import { hasL0Header } from "../markdown.js";
+import { withMemoryWrite } from "./commit-wrapper.js";
+import { toolError } from "./shared.js";
+export function createWriteTools(manager) {
+    const root = manager.paths.memoryRoot;
+    return [
+        defineTool("cog_write", {
+            description: "Create or overwrite a memory file. A .md file must begin with an " +
+                "<!-- L0: summary --> line within the first few lines.",
+            parameters: z.object({
+                path: z.string().describe("File path relative to the memory root"),
+                content: z.string().describe("Full file content"),
+            }),
+            handler: async (args) => {
+                try {
+                    const abs = resolveMemoryPath(root, args.path);
+                    if (abs.endsWith(".md") && !hasL0Header(args.content)) {
+                        return "Error: a .md memory file must begin with an <!-- L0: summary --> line";
+                    }
+                    return await withMemoryWrite(manager, `memory: write ${args.path}`, () => {
+                        mkdirSync(dirname(abs), { recursive: true });
+                        writeFileSync(abs, args.content, "utf8");
+                        return `wrote ${args.path}`;
+                    });
+                }
+                catch (err) {
+                    return toolError(err);
+                }
+            },
+        }),
+        defineTool("cog_edit", {
+            description: "Replace an exact, unique string in a memory file (edit in place).",
+            parameters: z.object({
+                path: z.string().describe("File path"),
+                old: z.string().describe("Exact text to replace — must occur exactly once"),
+                new: z.string().describe("Replacement text"),
+            }),
+            handler: async (args) => {
+                try {
+                    const abs = resolveMemoryPath(root, args.path);
+                    const data = readFileSync(abs, "utf8");
+                    const occurrences = data.split(args.old).length - 1;
+                    if (occurrences === 0) {
+                        return `Error: old string not found in ${args.path}`;
+                    }
+                    if (occurrences > 1) {
+                        return `Error: old string is not unique in ${args.path} — include more context`;
+                    }
+                    return await withMemoryWrite(manager, `memory: edit ${args.path}`, () => {
+                        writeFileSync(abs, data.replace(args.old, args.new), "utf8");
+                        return `edited ${args.path}`;
+                    });
+                }
+                catch (err) {
+                    return toolError(err);
+                }
+            },
+        }),
+        defineTool("cog_append", {
+            description: "Append a block of text to a memory file (for append-only files like observations).",
+            parameters: z.object({
+                path: z.string().describe("File path"),
+                content: z.string().describe("Text to append"),
+            }),
+            handler: async (args) => {
+                try {
+                    const abs = resolveMemoryPath(root, args.path);
+                    const existing = readFileSync(abs, "utf8");
+                    let next = existing;
+                    if (next !== "" && !next.endsWith("\n"))
+                        next += "\n";
+                    next += args.content;
+                    if (!next.endsWith("\n"))
+                        next += "\n";
+                    return await withMemoryWrite(manager, `memory: append ${args.path}`, () => {
+                        writeFileSync(abs, next, "utf8");
+                        return `appended to ${args.path}`;
+                    });
+                }
+                catch (err) {
+                    return toolError(err);
+                }
+            },
+        }),
+        defineTool("cog_move", {
+            description: "Move or rename a memory file (used for glacier archival).",
+            parameters: z.object({
+                from: z.string().describe("Source path"),
+                to: z.string().describe("Destination path"),
+            }),
+            handler: async (args) => {
+                try {
+                    const from = resolveMemoryPath(root, args.from);
+                    const to = resolveMemoryPath(root, args.to);
+                    return await withMemoryWrite(manager, `memory: move ${args.from} -> ${args.to}`, () => {
+                        mkdirSync(dirname(to), { recursive: true });
+                        renameSync(from, to);
+                        return `moved ${args.from} -> ${args.to}`;
+                    });
+                }
+                catch (err) {
+                    return toolError(err);
+                }
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=write.js.map

package/dist/memory/tools/write.test.js

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { gitAvailable, gitLog } from "../git.js";
+import { MemoryManager } from "../manager.js";
+import { createMemoryTools } from "./index.js";
+const sandbox = join(process.cwd(), ".test-work", `mem-tools-write-${process.pid}`);
+function findTool(tools, name) {
+    const found = tools.find((t) => t.name === name);
+    assert.ok(found, `tool ${name} not found`);
+    return found;
+}
+async function call(tool, args) {
+    const result = await tool.handler(args, {
+        sessionId: "t",
+        toolCallId: "t",
+        toolName: tool.name,
+        arguments: args,
+    });
+    return String(result);
+}
+async function setup() {
+    const mgr = new MemoryManager(sandbox);
+    await mgr.ensureReady();
+    return { tools: createMemoryTools(mgr), root: mgr.paths.memoryRoot };
+}
+test.beforeEach(() => {
+    rmSync(sandbox, { recursive: true, force: true });
+    mkdirSync(sandbox, { recursive: true });
+});
+test.after(() => rmSync(sandbox, { recursive: true, force: true }));
+test("cog_write rejects a .md file with no L0 header", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools } = await setup();
+    const out = await call(findTool(tools, "cog_write"), {
+        path: "personal/note.md",
+        content: "# No L0 here\nbody",
+    });
+    assert.match(out, /<!-- L0: summary -->/);
+});
+test("cog_write accepts a .md file with an L0 header and commits it", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools, root } = await setup();
+    const before = (await gitLog(root, 50)).trim().split("\n").length;
+    const out = await call(findTool(tools, "cog_write"), {
+        path: "personal/note.md",
+        content: "<!-- L0: a note -->\n# Note\nbody",
+    });
+    assert.match(out, /wrote personal\/note\.md/);
+    assert.ok(existsSync(join(root, "personal/note.md")));
+    const log = await gitLog(root, 50);
+    assert.ok(log.includes("memory: write personal/note.md"));
+    assert.equal(log.trim().split("\n").length, before + 1, "exactly one new commit");
+});
+test("cog_edit errors on missing and non-unique matches, succeeds when unique", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools } = await setup();
+    await call(findTool(tools, "cog_write"), {
+        path: "personal/note.md",
+        content: "<!-- L0: a note -->\nalpha\nbeta\nalpha",
+    });
+    assert.match(await call(findTool(tools, "cog_edit"), { path: "personal/note.md", old: "zeta", new: "x" }), /not found/);
+    assert.match(await call(findTool(tools, "cog_edit"), { path: "personal/note.md", old: "alpha", new: "x" }), /not unique/);
+    assert.match(await call(findTool(tools, "cog_edit"), { path: "personal/note.md", old: "beta", new: "BETA" }), /edited/);
+});
+test("cog_append normalizes newlines", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools, root } = await setup();
+    await call(findTool(tools, "cog_write"), {
+        path: "personal/observations.md",
+        content: "<!-- L0: obs -->\nfirst line",
+    });
+    await call(findTool(tools, "cog_append"), { path: "personal/observations.md", content: "second line" });
+    assert.equal(readFileSync(join(root, "personal/observations.md"), "utf8"), "<!-- L0: obs -->\nfirst line\nsecond line\n");
+});
+test("cog_move relocates a file", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools, root } = await setup();
+    await call(findTool(tools, "cog_write"), {
+        path: "personal/old.md",
+        content: "<!-- L0: x -->\nbody",
+    });
+    const out = await call(findTool(tools, "cog_move"), {
+        from: "personal/old.md",
+        to: "glacier/personal/old.md",
+    });
+    assert.match(out, /moved/);
+    assert.ok(!existsSync(join(root, "personal/old.md")));
+    assert.ok(existsSync(join(root, "glacier/personal/old.md")));
+});
+test("cog_write rejects a path escaping the memory root", async () => {
+    if (!gitAvailable())
+        return;
+    const { tools } = await setup();
+    const out = await call(findTool(tools, "cog_write"), {
+        path: "../escape.md",
+        content: "<!-- L0: x -->\nbody",
+    });
+    assert.match(out, /escapes the memory root/);
+});
+//# sourceMappingURL=write.test.js.map

package/dist/memory/walk.js

@@ -0,0 +1,39 @@
+// Walks the markdown files of the memory tree (or one domain subtree),
+// skipping the .git directory. Ported from chgo's tools_read.go walkMemoryMarkdown.
+import { readdirSync } from "fs";
+import { join, relative, sep } from "path";
+import { resolveMemoryPath } from "./path-guard.js";
+/**
+ * Calls `fn(rel, abs)` for every `.md` file under the memory root, or under a
+ * domain subdirectory when `domain` is given. `rel` is slash-separated and
+ * relative to the memory root.
+ */
+export function walkMemoryMarkdown(memoryRoot, domain, fn) {
+    let base = memoryRoot;
+    if (domain && domain.trim() !== "") {
+        base = resolveMemoryPath(memoryRoot, domain);
+    }
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // directory may not exist yet
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === ".git")
+                    continue;
+                walk(full);
+            }
+            else if (entry.name.endsWith(".md")) {
+                const rel = relative(memoryRoot, full).split(sep).join("/");
+                fn(rel, full);
+            }
+        }
+    };
+    walk(base);
+}
+//# sourceMappingURL=walk.js.map

package/dist/store/repositories/sessions.js

@@ -229,6 +229,46 @@ export function getSessionMessages(sessionKey, limit, options = {}) {
         return message;
     });
 }
+/**
+ * Group conversation_log rows into sessions for the cog_sessions tool. Rows are
+ * grouped by (session_key, run_id); `agent_completion` rows map to role
+ * "assistant"; empty-content rows are skipped. When `since` (an ISO-8601
+ * string) is given, only later turns are kept. Sessions are sorted
+ * newest-first; `limit` (0 = no cap) bounds the count.
+ *
+ * Note: conversation_log is pruned to the last 1000 rows, so only recent
+ * history is visible — adequate for the reflect skill's cursor model.
+ */
+export function getConversationSessions(since, limit = 0) {
+    const db = getDb();
+    const rows = db.prepare(`SELECT role, content, ts, session_key, run_id, agent_slug FROM conversation_log
+     WHERE role IN ('user', 'assistant', 'agent_completion')
+     ORDER BY session_key, run_id, id ASC`).all();
+    const sinceIso = since ? normalizeSqliteTsToIso(since) : undefined;
+    const byKey = new Map();
+    for (const r of rows) {
+        if (!r.content || r.content.trim() === "")
+            continue;
+        const at = normalizeSqliteTsToIso(r.ts);
+        if (sinceIso && at <= sinceIso)
+            continue;
+        const key = `${r.session_key}|${r.run_id ?? ""}`;
+        let session = byKey.get(key);
+        if (!session) {
+            session = { sessionKey: r.session_key, runId: r.run_id, startedAt: at, turns: [] };
+            byKey.set(key, session);
+        }
+        session.turns.push({
+            role: r.role === "agent_completion" ? "assistant" : r.role,
+            content: r.content,
+            ts: at,
+            agentSlug: r.agent_slug,
+        });
+    }
+    const sessions = Array.from(byKey.values()).filter((s) => s.turns.length > 0);
+    sessions.sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : 0));
+    return limit > 0 ? sessions.slice(0, limit) : sessions;
+}
 /**
  * Append one event to agent_task_events and return the new event.
  * Uses a transaction so seq is monotonically incremented.

package/dist/wiki/consolidation.js

@@ -3,8 +3,6 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, renameSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { config } from "../config.js";
-import { recordActionItem } from "../memory/action-items.js";
-import { getScope } from "../memory/scopes.js";
 import { getChapterhouseHome, resolveWikiRelativePath } from "../paths.js";
 import { childLogger } from "../util/logger.js";
 import { deletePage, listPages, readPage, writePage } from "./fs.js";
@@ -77,13 +75,14 @@ export async function runConsolidationWithDeps(db, partialDeps = {}) {
     await deps.commitWikiChanges(runAt);
     return result;
 }
-function createDefaultDeps(db) {
+function createDefaultDeps(_db) {
     return {
         now: () => new Date(),
         synthesizeTruth: synthesizeTruthWithCopilot,
         rebuildIndex: rebuildWikiIndex,
         commitWikiChanges: async (runAt) => commitWikiChanges(runAt),
-        createActionItem: ({ title, detail, source }) => createStaleSessionActionItem(db, { title, detail, source }),
+        // Wiki consolidation no longer records action items into agent memory.
+        createActionItem: () => false,
         truthRewriteBudget: config.pkbTruthRewriteBudget,
     };
 }
@@ -466,33 +465,6 @@ function notifyStaleSessions(db, deps, runAt) {
     }
     return created;
 }
-function createStaleSessionActionItem(db, input) {
-    const globalScope = getScope("global");
-    if (!globalScope) {
-        return false;
-    }
-    const existing = recordDuplicateActionItemCheck(db, globalScope.id, input.title);
-    if (existing) {
-        return false;
-    }
-    recordActionItem({
-        scope_id: globalScope.id,
-        title: input.title,
-        detail: input.detail,
-        source: input.source,
-        tier: "warm",
-    });
-    return true;
-}
-function recordDuplicateActionItemCheck(db, scopeId, title) {
-    const row = db.prepare(`
-    SELECT 1
-    FROM mem_action_items
-    WHERE scope_id = ? AND title = ? AND status IN ('open', 'snoozed')
-    LIMIT 1
-  `).get(scopeId, title);
-    return Boolean(row);
-}
 async function synthesizeTruthWithCopilot(input) {
     const token = config.copilotAuthToken;
     if (!token) {

package/dist/wiki/consolidation.test.js

@@ -118,25 +118,6 @@ test("runConsolidation removes orphaned wiki_links rows", async () => {
     assert.equal(result.linksRepaired, 1);
     assert.equal(orphanCount.c, 0);
 });
-test("runConsolidation creates an action item for research sessions inactive for 7+ days", async () => {
-    const { dbModule, wikiFs, consolidation, memory } = await loadModules();
-    const db = dbModule.getDb();
-    wikiFs.ensureWikiStructure();
-    const globalScope = memory.getScope("global");
-    assert.ok(globalScope);
-    db.prepare(`
-    INSERT INTO wiki_sources (id, source_type, origin, title, ingested_at, raw_path, parsed_content, pages_updated, status, session_id, session_name)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run("source-1", "url", "https://example.test/1", "Research note", "2026-05-01T10:00:00.000Z", "sources/source-1.md", "content", "[]", "active", "session-123", "Compiler research");
-    const result = await consolidation.runConsolidationWithDeps(db, {
-        now: () => new Date("2026-05-14T22:30:03.086Z"),
-        synthesizeTruth: async () => "unused",
-        commitWikiChanges: async () => false,
-    });
-    const actionItems = memory.listActionItems({ scope_id: globalScope.id, includeArchived: true });
-    assert.equal(result.staleSessionsNotified, 1);
-    assert.equal(actionItems.some((item) => item.title.includes("Research session 'Compiler research' has been inactive for 7+ days")), true);
-});
 test("runConsolidation caps truth rewrites before exceeding the LLM budget", async () => {
     const { dbModule, wikiFs, indexManager, consolidation } = await loadModules();
     const db = dbModule.getDb();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"

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.