chapterhouse 0.3.13 → 0.3.15

package/dist/daemon.js

@@ -2,7 +2,6 @@ import { getClient, stopClient } from "./copilot/client.js";
 import { initOrchestrator, setMessageLogger, setProactiveNotify, getAgentInfo, shutdownAgents } from "./copilot/orchestrator.js";
 import { stopEpisodeWriter } from "./copilot/episode-writer.js";
 import { startApiServer, broadcastToSSE } from "./api/server.js";
-import { killRalphOnShutdown } from "./api/ralph.js";
 import { getDb, closeDb, getState } from "./store/db.js";
 import { config } from "./config.js";
 import { spawn } from "child_process";
@@ -12,10 +11,10 @@ import { checkForUpdate } from "./update.js";
 import { ensureWikiStructure } from "./wiki/fs.js";
 import { seedTeamWiki } from "./wiki/seed-team-wiki.js";
 import { shouldMigrate, migrateMemoriesToWiki, shouldReorganize, reorganizeWiki } from "./wiki/migrate.js";
+import { shouldEnforceTopics, enforceTopicStructure } from "./wiki/migrate-topics.js";
 import { SESSIONS_DIR } from "./paths.js";
 import { getDisplayHost } from "./api/server-runtime.js";
 import { StandupScheduler } from "./copilot/standup.js";
-import { DecisionsSyncScheduler } from "./squad/mirror.scheduler.js";
 import { registerShutdownSignals } from "./shutdown-signals.js";
 import { logger } from "./util/logger.js";
 import { CHAPTERHOUSE_VERSION } from "./version.js";
@@ -115,6 +114,11 @@ async function main() {
         const count = reorganizeWiki();
         log.info({ count }, "Created entity pages during reorganization");
     }
+    if (shouldEnforceTopics()) {
+        log.info("Enforcing wiki topic-directory structure");
+        const moved = enforceTopicStructure();
+        log.info({ moved }, "Topic-structure migration complete");
+    }
     // Prune orphaned session folders older than 7 days
     pruneOldSessions();
     // One-time deprecation note for legacy Telegram users (v1 → v2)
@@ -148,9 +152,6 @@ async function main() {
     if (config.chapterhouseMode === "personal" && (config.adoPat || config.teamChapterhouseUrl)) {
         new StandupScheduler().schedule();
     }
-    // Start periodic decisions→wiki sync for all registered projects
-    decisionsSyncScheduler = new DecisionsSyncScheduler();
-    decisionsSyncScheduler.start();
     const url = `http://${getDisplayHost(config.apiHost)}:${config.apiPort}`;
     log.info({ url }, "Chapterhouse is fully operational");
     if (process.env.CHAPTERHOUSE_OPEN_BROWSER === "1") {
@@ -177,7 +178,6 @@ async function main() {
 }
 // Graceful shutdown
 let shutdownState = "idle";
-let decisionsSyncScheduler;
 async function shutdown() {
     if (shutdownState === "shutting_down") {
         log.warn("Forced exit");
@@ -202,10 +202,6 @@ async function shutdown() {
     forceTimer.unref();
     // Destroy all active agent sessions
     await shutdownAgents();
-    try {
-        decisionsSyncScheduler?.stop();
-    }
-    catch { /* best effort */ }
     try {
         stopEpisodeWriter();
     }
@@ -214,10 +210,6 @@ async function shutdown() {
         await stopClient();
     }
     catch { /* best effort */ }
-    try {
-        killRalphOnShutdown();
-    }
-    catch { /* best effort */ }
     closeDb();
     log.info("Goodbye");
     process.exit(0);
@@ -231,10 +223,6 @@ export async function restartDaemon() {
     }
     // Destroy all active agent sessions
     await shutdownAgents();
-    try {
-        decisionsSyncScheduler?.stop();
-    }
-    catch { /* best effort */ }
     try {
         stopEpisodeWriter();
     }
@@ -243,10 +231,6 @@ export async function restartDaemon() {
         await stopClient();
     }
     catch { /* best effort */ }
-    try {
-        killRalphOnShutdown();
-    }
-    catch { /* best effort */ }
     closeDb();
     // Spawn a detached replacement process with the same args (include execArgv for tsx/loaders)
     const child = spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {

package/dist/store/db.js

@@ -68,42 +68,6 @@ export function getDb() {
         created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
         last_accessed DATETIME DEFAULT CURRENT_TIMESTAMP
       )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS project_squads (
-        project_root TEXT PRIMARY KEY,
-        squad_dir TEXT NOT NULL,
-        team_dir TEXT NOT NULL,
-        personal_dir TEXT,
-        mode TEXT NOT NULL CHECK(mode IN ('local', 'remote')),
-        project_key TEXT,
-        config_source TEXT,
-        registered INTEGER NOT NULL DEFAULT 0,
-        loaded_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS squad_agents (
-        project_root TEXT NOT NULL,
-        slug TEXT NOT NULL,
-        role TEXT NOT NULL,
-        description TEXT,
-        charter_path TEXT NOT NULL,
-        model_preference TEXT,
-        tools_json TEXT,
-        capabilities_json TEXT,
-        stale INTEGER NOT NULL DEFAULT 0,
-        loaded_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-        PRIMARY KEY (project_root, slug)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS squad_task_links (
-        task_id TEXT PRIMARY KEY,
-        project_root TEXT NOT NULL,
-        squad_agent_slug TEXT NOT NULL,
-        wiki_decision_path TEXT NOT NULL
-      )
     `);
         // Migrate: if the table already existed with a stricter CHECK, recreate it
         try {
@@ -146,7 +110,7 @@ export function getDb() {
         if (!taskCols.some((c) => c.name === 'session_key')) {
             db.exec(`ALTER TABLE agent_tasks ADD COLUMN session_key TEXT NOT NULL DEFAULT 'default'`);
         }
-        // Migrate: add source column to agent_tasks ('adhoc' | 'squad') if not present
+        // Migrate: add source column to agent_tasks ('adhoc') if not present
         if (!taskCols.some((c) => c.name === 'source')) {
             db.exec(`ALTER TABLE agent_tasks ADD COLUMN source TEXT NOT NULL DEFAULT 'adhoc'`);
         }
@@ -168,13 +132,6 @@ export function getDb() {
         if (!taskColsNow.some((c) => c.name === 'event_seq')) {
             db.exec(`ALTER TABLE agent_tasks ADD COLUMN event_seq INTEGER NOT NULL DEFAULT 0`);
         }
-        // Migrate: add last_used_at column to project_squads (epoch ms, nullable)
-        const projectCols = db.prepare(`PRAGMA table_info(project_squads)`).all();
-        if (!projectCols.some((c) => c.name === 'last_used_at')) {
-            db.exec(`ALTER TABLE project_squads ADD COLUMN last_used_at INTEGER`);
-            // Backfill from loaded_at so sidebar is not empty for existing projects
-            db.exec(`UPDATE project_squads SET last_used_at = CAST((julianday(loaded_at) - 2440587.5) * 86400000 AS INTEGER) WHERE last_used_at IS NULL`);
-        }
         // turn_events: append-only per-turn event log for the SSE chat channel (#130).
         // Events are written on turn completion; ring buffer serves live/recent replay.
         db.exec(`
@@ -297,7 +254,7 @@ export function getTaskSessionKey(taskId) {
  * Get recent conversation history formatted for injection into system message.
  *
  * When `sessionKey` is provided, only rows belonging to that session are
- * returned — useful for project/squad sessions that must not bleed context
+ * returned — useful for per-session isolation that must not bleed context
  * from other sessions. When omitted, rows from all sessions are returned
  * (legacy behavior for callers that don't care about session isolation).
  */
@@ -408,11 +365,6 @@ export function getTaskEvents(taskId, afterSeq = 0) {
         summary: r.summary,
     }));
 }
-export function bumpProjectLastUsed(projectRoot) {
-    getDb()
-        .prepare(`UPDATE project_squads SET last_used_at = ? WHERE project_root = ?`)
-        .run(Date.now(), projectRoot);
-}
 export function closeDb() {
     if (db) {
         db.close();

package/dist/store/db.test.js

@@ -167,51 +167,6 @@ test("getSessionMessages returns structured messages in chronological order, exc
     }
 });
 // ---------------------------------------------------------------------------
-// #26 — bumpProjectLastUsed
-// ---------------------------------------------------------------------------
-test("migration adds last_used_at column to project_squads when absent", async () => {
-    const dbModule = await loadDbModule();
-    try {
-        const db = dbModule.getDb();
-        const cols = db.prepare(`PRAGMA table_info(project_squads)`).all();
-        assert.equal(cols.some((c) => c.name === "last_used_at"), true, "last_used_at column should exist after migration");
-    }
-    finally {
-        dbModule.closeDb();
-    }
-});
-test("bumpProjectLastUsed updates last_used_at for the given project_root", async () => {
-    const dbModule = await loadDbModule();
-    try {
-        const db = dbModule.getDb();
-        db.prepare(`INSERT INTO project_squads (project_root, squad_dir, team_dir, mode, registered) VALUES (?, ?, ?, 'local', 1)`).run("/home/user/test-proj", "/home/user/test-proj/.squad", "/home/user/test-proj/.squad");
-        const before = db
-            .prepare(`SELECT last_used_at FROM project_squads WHERE project_root = ?`)
-            .get("/home/user/test-proj");
-        const beforeTs = before.last_used_at ?? 0;
-        await new Promise((r) => setTimeout(r, 5));
-        dbModule.bumpProjectLastUsed("/home/user/test-proj");
-        const after = db
-            .prepare(`SELECT last_used_at FROM project_squads WHERE project_root = ?`)
-            .get("/home/user/test-proj");
-        assert.ok(after.last_used_at !== null, "last_used_at should not be null after bump");
-        assert.ok(after.last_used_at > beforeTs, "last_used_at should advance after bump");
-    }
-    finally {
-        dbModule.closeDb();
-    }
-});
-test("bumpProjectLastUsed is a no-op for unknown project_root (no throw)", async () => {
-    const dbModule = await loadDbModule();
-    try {
-        dbModule.getDb();
-        dbModule.bumpProjectLastUsed("/does/not/exist");
-    }
-    finally {
-        dbModule.closeDb();
-    }
-});
-// ---------------------------------------------------------------------------
 // #86: agent_task_events — appendTaskEvent and getTaskEvents
 // ---------------------------------------------------------------------------
 test("#86: appendTaskEvent inserts a row and getTaskEvents returns it ordered by seq", async () => {

package/dist/wiki/fs.js

@@ -5,6 +5,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlink
 import { join, dirname, relative, resolve, sep } from "path";
 import { WIKI_DIR, WIKI_PAGES_DIR, WIKI_SOURCES_DIR } from "../paths.js";
 import { normalizeWikiPath } from "./path-utils.js";
+import { topicPathError } from "./topic-structure.js";
 const INDEX_PATH = join(WIKI_DIR, "index.md");
 const LOG_PATH = join(WIKI_DIR, "log.md");
 /**
@@ -43,6 +44,10 @@ export function assertPagePath(relativePath) {
     if (!normalizedPath.endsWith(".md")) {
         throw new Error(`Wiki page paths must end in .md: ${relativePath}`);
     }
+    const structureError = topicPathError(normalizedPath);
+    if (structureError) {
+        throw new Error(`Wiki path violates the topic structure: ${structureError}`);
+    }
     // resolvePath also enforces the wiki-root containment check.
     resolvePath(normalizedPath);
 }

package/dist/wiki/index-manager.js

@@ -6,6 +6,7 @@ import { join } from "path";
 import { WIKI_DIR } from "../paths.js";
 import { readIndexFile, writeIndexFile, listPages, readPage } from "./fs.js";
 import { normalizeWikiPath } from "./path-utils.js";
+import { entityCategories, FLAT_CATEGORIES } from "./topic-structure.js";
 const INDEX_PATH = join(WIKI_DIR, "index.md");
 // mtime-based cache so per-message context injection doesn't re-parse on every turn.
 let cache;
@@ -39,8 +40,9 @@ export function parseIndex() {
             currentSection = sectionMatch[1].trim();
             continue;
         }
-        // Entry lines: - [Title](path) — Summary | tags: t1, t2 | updated: YYYY-MM-DD
-        const entryMatch = line.match(/^-\s+\[(.+?)\]\((.+?)\)\s*[—–-]\s*(.+)/);
+        // Entry lines (possibly indented sub-bullets):
+        //   - [Title](path) — Summary | tags: t1, t2 | updated: YYYY-MM-DD
+        const entryMatch = line.match(/^\s*-\s+\[(.+?)\]\((.+?)\)\s*[—–-]\s*(.+)/);
         if (entryMatch) {
             const rawSummary = entryMatch[3].trim();
             // Parse optional | tags: ... | updated: ... suffixes
@@ -120,9 +122,11 @@ export function buildIndexEntryForPage(path, fallback) {
         const body = content.replace(/^---[\s\S]*?---\s*/, "");
         for (const raw of body.split("\n")) {
             const line = raw.trim();
-            if (!line || line.startsWith("#"))
+            if (!line || line.startsWith("#") || line.startsWith("<!--"))
                 continue;
             summary = line.replace(/^[-*]\s+/, "").replace(/_\(\d{4}-\d{2}-\d{2}\)_$/, "").trim();
+            if (!summary)
+                continue;
             break;
         }
     }
@@ -157,7 +161,7 @@ export function rebuildIndexFromPages() {
                 section = sm[1].trim();
                 continue;
             }
-            const em = line.match(/^-\s+\[.+?\]\((.+?)\)/);
+            const em = line.match(/^\s*-\s+\[.+?\]\((.+?)\)/);
             if (em) {
                 const normalizedPath = normalizeWikiPath(em[1].trim());
                 previous.set(normalizedPath, { path: normalizedPath, title: "", summary: "", section });
@@ -181,13 +185,51 @@ export function writeIndex(entries) {
     writeIndexInternal(entries);
     invalidateCache();
 }
+/** Derive the top-level category of a page from its path under pages/. */
+function categoryOfPath(path) {
+    const rest = path.startsWith("pages/") ? path.slice("pages/".length) : path;
+    const segs = rest.split("/").filter(Boolean);
+    if (segs.length <= 1)
+        return (segs[0] || "pages").replace(/\.md$/i, "");
+    return segs[0];
+}
+/** Derive the topic slug of an entity-category page (pages/<cat>/<topic>/<file>), if any. */
+function topicOfPath(path) {
+    const rest = path.startsWith("pages/") ? path.slice("pages/".length) : path;
+    const segs = rest.split("/").filter(Boolean);
+    return segs.length >= 3 ? segs[1] : undefined;
+}
+function isTopicIndexFile(path) {
+    return /\/index\.md$/i.test(path);
+}
+function humanize(slug) {
+    return slug.split(/[-_]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function renderEntryLine(item, indent = "") {
+    let line = `${indent}- [${item.title}](${item.path}) — ${item.summary}`;
+    if (item.tags?.length)
+        line += ` | tags: ${item.tags.join(", ")}`;
+    if (item.updated)
+        line += ` | updated: ${item.updated}`;
+    return line;
+}
 function writeIndexInternal(entries) {
-    const sections = new Map();
+    // Group by top-level category derived from the page path (not the stored
+    // `section`, which is no longer authoritative).
+    const byCategory = new Map();
     for (const entry of entries) {
-        const list = sections.get(entry.section) || [];
+        const cat = categoryOfPath(entry.path);
+        const list = byCategory.get(cat) || [];
         list.push(entry);
-        sections.set(entry.section, list);
+        byCategory.set(cat, list);
     }
+    const entityCats = entityCategories();
+    const entityCatSet = new Set(entityCats);
+    const known = [...entityCats, ...FLAT_CATEGORIES];
+    const orderedCategories = [
+        ...known.filter((c) => byCategory.has(c)),
+        ...[...byCategory.keys()].filter((c) => !known.includes(c)).sort(),
+    ];
     const lines = [
         "# Wiki Index",
         "",
@@ -196,19 +238,52 @@ function writeIndexInternal(entries) {
         `Last updated: ${new Date().toISOString().slice(0, 10)}`,
         "",
     ];
-    for (const [section, items] of sections) {
-        lines.push(`## ${section}`, "");
-        for (const item of items) {
-            let line = `- [${item.title}](${item.path}) — ${item.summary}`;
-            if (item.tags?.length)
-                line += ` | tags: ${item.tags.join(", ")}`;
-            if (item.updated)
-                line += ` | updated: ${item.updated}`;
-            lines.push(line);
+    for (const cat of orderedCategories) {
+        const items = byCategory.get(cat);
+        lines.push(`## ${humanize(cat)}`, "");
+        if (entityCatSet.has(cat)) {
+            // Two-level layout: topic directory -> overview (index.md) + facet pages.
+            // Pages not yet in canonical <category>/<topic>/<file> shape are listed as
+            // plain bullets (they'll be relocated by the topic-structure migration).
+            const byTopic = new Map();
+            const ungrouped = [];
+            for (const entry of items) {
+                const topic = topicOfPath(entry.path);
+                if (!topic) {
+                    ungrouped.push(entry);
+                    continue;
+                }
+                const list = byTopic.get(topic) || [];
+                list.push(entry);
+                byTopic.set(topic, list);
+            }
+            for (const topic of [...byTopic.keys()].sort()) {
+                const topicItems = byTopic.get(topic);
+                const overview = topicItems.find((e) => isTopicIndexFile(e.path));
+                const facets = topicItems
+                    .filter((e) => !isTopicIndexFile(e.path))
+                    .sort((a, b) => a.path.localeCompare(b.path));
+                if (overview) {
+                    lines.push(renderEntryLine(overview));
+                }
+                else {
+                    lines.push(`- **${humanize(topic)}** _(no overview page)_`);
+                }
+                for (const facet of facets)
+                    lines.push(renderEntryLine(facet, "  "));
+            }
+            for (const entry of ungrouped.sort((a, b) => a.path.localeCompare(b.path))) {
+                lines.push(renderEntryLine(entry));
+            }
+        }
+        else {
+            for (const entry of [...items].sort((a, b) => a.path.localeCompare(b.path))) {
+                lines.push(renderEntryLine(entry));
+            }
         }
         lines.push("");
     }
-    if (sections.size === 0) {
+    if (orderedCategories.length === 0) {
         lines.push("## Pages", "", "_(No pages yet.)_", "");
     }
     writeIndexFile(lines.join("\n"));

package/dist/wiki/index-manager.test.js

@@ -73,6 +73,25 @@ test("parseIndex self-heals an empty index from on-disk pages", async () => {
     ]);
     assert.match(wikiFs.readIndexFile(), /\[Vision\]\(pages\/team\/vision\.md\)/);
 });
+test("the index renders entity categories as topic groups with nested facet pages", async () => {
+    const { indexManager, wikiFs } = await loadModules();
+    wikiFs.writePage("pages/projects/chapterhouse/index.md", "---\ntitle: Chapterhouse\nupdated: 2026-05-09\n---\n\n# Chapterhouse\n\nThe per-session orchestrator.\n");
+    wikiFs.writePage("pages/projects/chapterhouse/decisions.md", "---\ntitle: Chapterhouse Decisions\nupdated: 2026-05-09\n---\n\n# Decisions\n\nUse SSE for streaming.\n");
+    wikiFs.writePage("pages/preferences.md", "---\ntitle: Preferences\n---\n\n# Preferences\n\nDark mode.\n");
+    indexManager.rebuildIndexFromPages();
+    const index = wikiFs.readIndexFile();
+    assert.match(index, /## Projects/);
+    assert.match(index, /^- \[Chapterhouse\]\(pages\/projects\/chapterhouse\/index\.md\) — /m);
+    assert.match(index, /^ {2}- \[Chapterhouse Decisions\]\(pages\/projects\/chapterhouse\/decisions\.md\) — /m);
+    assert.match(index, /## Preferences/);
+    // Indented facet bullets must still round-trip through parseIndex.
+    const paths = indexManager.parseIndex().map((entry) => entry.path).sort();
+    assert.deepEqual(paths, [
+        "pages/preferences.md",
+        "pages/projects/chapterhouse/decisions.md",
+        "pages/projects/chapterhouse/index.md",
+    ]);
+});
 test("searchIndex ranks strong metadata matches and falls back to page bodies", async () => {
     const { indexManager, wikiFs } = await loadModules();
     wikiFs.writePage("pages/team/api.md", "# API\n\nObservability budget and telemetry plans.\n");

package/dist/wiki/migrate-topics.js

@@ -0,0 +1,132 @@
+// ---------------------------------------------------------------------------
+// One-time migration: enforce the topic-directory structure for entity
+// categories (pages/<category>/<topic-slug>/index.md + facet pages).
+//
+// Fixes wikis created before the structure was enforced, e.g.:
+//   pages/projects/chapterhouse.md               -> pages/projects/chapterhouse/index.md
+//   pages/projects/chapterhouse-feature-ideas.md -> pages/projects/chapterhouse/feature-ideas.md
+//   pages/projects/chapterhouse/decisions.md     -> (already correct, left alone)
+// ---------------------------------------------------------------------------
+import { existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import { getState, setState } from "../store/db.js";
+import { WIKI_PAGES_DIR } from "../paths.js";
+import { ensureWikiStructure, readPage, writePage, deletePage, listPages } from "./fs.js";
+import { rebuildIndexFromPages } from "./index-manager.js";
+import { appendLog } from "./log-manager.js";
+import { entityCategories, slugify } from "./topic-structure.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("wiki:migrate-topics");
+const TOPIC_STRUCTURE_KEY = "wiki_topic_structure_v1";
+export function shouldEnforceTopics() {
+    return getState(TOPIC_STRUCTURE_KEY) !== "true";
+}
+function dirNamesUnder(absDir) {
+    if (!existsSync(absDir))
+        return [];
+    return readdirSync(absDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+function fileBaseNamesUnder(absDir) {
+    if (!existsSync(absDir))
+        return [];
+    return readdirSync(absDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".md"))
+        .map((e) => e.name.replace(/\.md$/i, ""));
+}
+function stripFrontmatter(content) {
+    return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+}
+/** Move src -> dest. If dest exists, merge src's body into it. Returns true if anything happened. */
+function moveOrMerge(srcRel, destRel, today) {
+    if (srcRel === destRel)
+        return false;
+    const srcContent = readPage(srcRel);
+    if (srcContent == null)
+        return false;
+    const destContent = readPage(destRel);
+    if (destContent != null) {
+        const merged = `${destContent.trimEnd()}\n\n<!-- merged from ${srcRel} on ${today} -->\n\n${stripFrontmatter(srcContent).trim()}\n`;
+        writePage(destRel, merged);
+    }
+    else {
+        writePage(destRel, srcContent);
+    }
+    deletePage(srcRel);
+    appendLog("migrate", `topic-structure: ${srcRel} -> ${destRel}${destContent != null ? " (merged)" : ""}`);
+    log.info({ from: srcRel, to: destRel, merged: destContent != null }, "moved wiki page into topic structure");
+    return true;
+}
+/**
+ * Bring the wiki page tree into compliance with the topic structure.
+ * Idempotent; safe to call repeatedly. Returns the number of pages moved/merged.
+ */
+export function enforceTopicStructure() {
+    ensureWikiStructure();
+    const today = new Date().toISOString().slice(0, 10);
+    let moves = 0;
+    for (const cat of entityCategories()) {
+        const catAbs = join(WIKI_PAGES_DIR, cat);
+        if (!existsSync(catAbs) || !statSync(catAbs).isDirectory()) {
+            // Also handle a bare `pages/<cat>.md` flat file for an entity category.
+            const bareFlat = `pages/${cat}.md`;
+            if (readPage(bareFlat) != null) {
+                if (moveOrMerge(bareFlat, `pages/${cat}/general/index.md`, today)) {
+                    moves++;
+                    log.warn({ page: bareFlat }, "moved entity-category flat file to a 'general' topic; consider splitting it");
+                }
+            }
+            continue;
+        }
+        // Topics already represented by a directory under pages/<cat>/.
+        const existingDirs = new Set(dirNamesUnder(catAbs));
+        // All bare files directly under pages/<cat>/ (the things that need relocating).
+        const bareFiles = fileBaseNamesUnder(catAbs);
+        // The full set of candidate topic stems: existing dirs + every bare file stem.
+        const topicSet = new Set([...existingDirs, ...bareFiles]);
+        for (const base of bareFiles) {
+            const srcRel = `pages/${cat}/${base}.md`;
+            // Is `base` a facet of some other topic T (i.e. base === "T-<facet>")? Pick the longest such T.
+            let facetOf;
+            let facetName = "";
+            for (const t of topicSet) {
+                if (t === base)
+                    continue;
+                if (base.startsWith(`${t}-`) && t.length > (facetOf?.length ?? 0)) {
+                    facetOf = t;
+                    facetName = base.slice(t.length + 1);
+                }
+            }
+            if (facetOf) {
+                const dest = `pages/${cat}/${slugify(facetOf)}/${slugify(facetName) || "notes"}.md`;
+                if (moveOrMerge(srcRel, dest, today))
+                    moves++;
+            }
+            else {
+                const dest = `pages/${cat}/${slugify(base)}/index.md`;
+                if (moveOrMerge(srcRel, dest, today))
+                    moves++;
+            }
+        }
+    }
+    if (moves > 0) {
+        rebuildIndexFromPages();
+        appendLog("migrate", `topic-structure: ${moves} page(s) relocated; index rebuilt`);
+    }
+    else {
+        // Still rebuild once so the index picks up the hierarchical layout.
+        rebuildIndexFromPages();
+    }
+    // Sanity log of anything still off (non-blocking).
+    for (const p of listPages()) {
+        const segs = p.replace(/^pages\//, "").split("/").filter(Boolean);
+        if (entityCategories().includes(segs[0]) && segs.length !== 3) {
+            log.warn({ page: p }, "wiki page still not in canonical topic shape after migration");
+        }
+    }
+    setState(TOPIC_STRUCTURE_KEY, "true");
+    log.info({ moves }, "topic-structure migration complete");
+    return moves;
+}
+//# sourceMappingURL=migrate-topics.js.map

package/dist/wiki/migrate-topics.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-migrate-topics-${process.pid}`);
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+async function loadModules() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const migrate = await import(new URL(`./migrate-topics.js?case=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?case=${nonce}`, import.meta.url).href);
+    return { migrate, wikiFs };
+}
+test.beforeEach(() => {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("enforceTopicStructure relocates bare entity pages and folds facet pages", async () => {
+    const { migrate, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/chapterhouse.md", "---\ntitle: Chapterhouse\n---\n\n# Chapterhouse\n\n- Source at ~/projects/chapterhouse\n");
+    wikiFs.writePage("pages/projects/chapterhouse-feature-ideas.md", "---\ntitle: Chapterhouse Feature Ideas\n---\n\n# Feature Ideas\n\n- Add wiki topics\n");
+    wikiFs.writePage("pages/projects/chapterhouse/decisions.md", "---\ntitle: Decisions\n---\n\n# Decisions\n\n- Use SSE\n");
+    wikiFs.writePage("pages/conversations/2026-05-09.md", "# 2026-05-09\n\nDaily summary.\n");
+    const moves = migrate.enforceTopicStructure();
+    assert.equal(moves, 2);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse.md"), false);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse-feature-ideas.md"), false);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/index.md"), true);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/feature-ideas.md"), true);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/decisions.md"), true);
+    // Conversations are exempt and untouched.
+    assert.equal(wikiFs.pageExists("pages/conversations/2026-05-09.md"), true);
+    assert.match(wikiFs.readPage("pages/projects/chapterhouse/index.md") ?? "", /Source at ~\/projects\/chapterhouse/);
+    assert.match(wikiFs.readPage("pages/projects/chapterhouse/feature-ideas.md") ?? "", /Add wiki topics/);
+    // Index reflects the new shape.
+    assert.match(wikiFs.readIndexFile(), /^- \[Chapterhouse\]\(pages\/projects\/chapterhouse\/index\.md\) — /m);
+    assert.match(wikiFs.readIndexFile(), /^ {2}- \[.+\]\(pages\/projects\/chapterhouse\/feature-ideas\.md\) — /m);
+    // Idempotent.
+    assert.equal(migrate.enforceTopicStructure(), 0);
+});
+test("enforceTopicStructure merges into an existing topic index instead of clobbering it", async () => {
+    const { migrate, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/people/brian/index.md", "---\ntitle: Brian\n---\n\n# Brian\n\n- Likes Go\n");
+    wikiFs.writePage("pages/people/brian.md", "---\ntitle: Brian\n---\n\n# Brian\n\n- Based in the US\n");
+    const moves = migrate.enforceTopicStructure();
+    assert.equal(moves, 1);
+    assert.equal(wikiFs.pageExists("pages/people/brian.md"), false);
+    const merged = wikiFs.readPage("pages/people/brian/index.md") ?? "";
+    assert.match(merged, /Likes Go/);
+    assert.match(merged, /Based in the US/);
+});
+//# sourceMappingURL=migrate-topics.test.js.map