chapterhouse 0.3.14 → 0.3.16

package/dist/wiki/frontmatter.test.js

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+async function loadFrontmatterModule() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    return await import(new URL(`./frontmatter.js?case=${nonce}`, import.meta.url).href);
+}
+test("parseWikiFrontmatter parses typed known fields and preserves unknown metadata", async () => {
+    const { parseWikiFrontmatter } = await loadFrontmatterModule();
+    const result = parseWikiFrontmatter(`---
+title: Chapterhouse
+summary: Team orchestrator runtime
+updated: 2026-05-12
+tags: [engineering, orchestration]
+autostub: true
+confidence: low
+contested: true
+contradictions: [pages/projects/chapterhouse/decisions.md]
+related: [pages/projects/chapterhouse/index.md]
+owner: brian
+---
+
+# Chapterhouse
+
+Runtime notes.
+`);
+    assert.deepEqual(result, {
+        parsed: {
+            title: "Chapterhouse",
+            summary: "Team orchestrator runtime",
+            updated: "2026-05-12",
+            tags: ["engineering", "orchestration"],
+            autostub: true,
+            confidence: "low",
+            contested: true,
+            contradictions: ["pages/projects/chapterhouse/decisions.md"],
+            related: ["pages/projects/chapterhouse/index.md"],
+            metadata: {
+                owner: "brian",
+            },
+        },
+        body: "# Chapterhouse\n\nRuntime notes.\n",
+    });
+});
+test("parseWikiFrontmatter tolerates legacy pages without frontmatter", async () => {
+    const { parseWikiFrontmatter } = await loadFrontmatterModule();
+    const result = parseWikiFrontmatter("# Legacy Page\n\nStill readable.\n");
+    assert.deepEqual(result, {
+        parsed: {
+            metadata: {},
+        },
+        body: "# Legacy Page\n\nStill readable.\n",
+    });
+});
+test("validateWikiFrontmatter requires authored pages to include title and summary", async () => {
+    const { validateWikiFrontmatter } = await loadFrontmatterModule();
+    const result = validateWikiFrontmatter(`---
+title: Chapterhouse
+---
+
+# Chapterhouse
+`);
+    assert.equal(result.valid, false);
+    assert.deepEqual(result.errors.map((error) => error.rule), ["missing-summary"]);
+    assert.match(result.errors[0]?.message ?? "", /missing 'summary'/i);
+});
+test("validateWikiFrontmatter rejects malformed summaries and invalid optional field types", async () => {
+    const { validateWikiFrontmatter } = await loadFrontmatterModule();
+    const result = validateWikiFrontmatter(`---
+title: Chapterhouse
+summary: **Bold summary**
+autostub: maybe
+confidence: unsure
+contested: perhaps
+contradictions: nope
+---
+
+# Chapterhouse
+`);
+    assert.equal(result.valid, false);
+    assert.deepEqual(result.errors.map((error) => error.rule), [
+        "invalid-summary",
+        "invalid-field-type",
+        "invalid-field-type",
+        "invalid-field-type",
+        "invalid-field-type",
+    ]);
+    assert.deepEqual(result.errors.map((error) => error.field), [
+        "summary",
+        "autostub",
+        "confidence",
+        "contested",
+        "contradictions",
+    ]);
+});
+test("validateWikiFrontmatter rejects unknown tags after taxonomy loading", async () => {
+    const { validateWikiFrontmatter } = await loadFrontmatterModule();
+    const result = validateWikiFrontmatter(`---
+title: Deploy
+summary: Runbook for production deployments
+tags: [engineering, made-up-tag]
+---
+
+# Deploy
+`, { allowedTags: ["engineering", "release"] });
+    assert.equal(result.valid, false);
+    assert.deepEqual(result.errors.map((error) => error.rule), ["unknown-tag"]);
+    assert.match(result.errors[0]?.message ?? "", /Add it to `pages\/_meta\/taxonomy\.md` first\./);
+});
+//# sourceMappingURL=frontmatter.test.js.map

package/dist/wiki/fs.js

@@ -5,8 +5,9 @@ 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");
+const LOG_PATH = join(WIKI_PAGES_DIR, "_meta", "log.md");
 /**
  * Write a file atomically: write to a temp file in the same directory, fsync,
  * then rename over the destination. Prevents partial writes on crash and
@@ -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);
 }
@@ -58,9 +63,9 @@ Last updated: ${new Date().toISOString().slice(0, 10)}
 _(No pages yet.)_
 `;
 }
-const INITIAL_LOG = `# Wiki Log
+const INITIAL_LOG = `# Wiki Action Log
 
-_Chronological record of wiki operations._
+_Append-only record of wiki operations._
 
 `;
 /**

package/dist/wiki/fs.test.js

@@ -20,11 +20,12 @@ test("wiki fs creates the wiki structure and supports page CRUD", async () => {
     assert.equal(wiki.ensureWikiStructure(), true);
     assert.equal(wiki.ensureWikiStructure(), false);
     assert.equal(existsSync(join(wikiDir, "index.md")), true);
-    assert.equal(existsSync(join(wikiDir, "log.md")), true);
+    assert.equal(existsSync(join(wikiDir, "pages", "_meta", "log.md")), true);
     wiki.writePage("pages/shared/runbooks/deploy.md", "# Deploy\n");
     assert.equal(wiki.pageExists("pages/shared/runbooks/deploy.md"), true);
     assert.equal(wiki.readPage("pages/shared/runbooks/deploy.md"), "# Deploy\n");
-    assert.deepEqual(wiki.listPages(), ["pages/shared/runbooks/deploy.md"]);
+    assert.equal(wiki.listPages().includes("pages/shared/runbooks/deploy.md"), true);
+    assert.match(wiki.readLogFile(), /^# Wiki Action Log/m);
     assert.equal(wiki.deletePage("pages/shared/runbooks/deploy.md"), true);
     assert.equal(wiki.deletePage("pages/shared/runbooks/deploy.md"), false);
     assert.equal(wiki.readPage("pages/shared/runbooks/deploy.md"), undefined);

package/dist/wiki/index-manager.js

@@ -5,8 +5,11 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 import { WIKI_DIR } from "../paths.js";
 import { readIndexFile, writeIndexFile, listPages, readPage } from "./fs.js";
+import { parseWikiFrontmatter } from "./frontmatter.js";
 import { normalizeWikiPath } from "./path-utils.js";
+import { entityCategories, FLAT_CATEGORIES } from "./topic-structure.js";
 const INDEX_PATH = join(WIKI_DIR, "index.md");
+const ACTION_LOG_PAGE_RE = /^pages\/_meta\/log(?:-\d{4})?\.md$/;
 // mtime-based cache so per-message context injection doesn't re-parse on every turn.
 let cache;
 function invalidateCache() {
@@ -39,8 +42,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
@@ -71,7 +75,7 @@ export function parseIndex() {
     }
     // Self-heal: if index is empty/corrupted but pages exist on disk, rebuild from disk.
     if (entries.length === 0) {
-        const pages = listPages();
+        const pages = listPages().filter((path) => !isActionLogPage(path));
         if (pages.length > 0) {
             const rebuilt = rebuildIndexFromPages();
             cache = { mtimeMs, size, entries: rebuilt };
@@ -81,48 +85,27 @@ export function parseIndex() {
     cache = { mtimeMs, size, entries };
     return entries;
 }
-/** Parse YAML frontmatter (very simple — supports key: value and key: [a, b]). */
-function parseFrontmatter(content) {
-    const m = content.match(/^---\s*\n([\s\S]*?)\n---/);
-    if (!m)
-        return {};
-    const out = {};
-    for (const line of m[1].split("\n")) {
-        const idx = line.indexOf(":");
-        if (idx <= 0)
-            continue;
-        const key = line.slice(0, idx).trim();
-        let value = line.slice(idx + 1).trim();
-        if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
-            value = value.slice(1, -1).split(",").map((s) => s.trim()).filter(Boolean);
-        }
-        else if (typeof value === "string") {
-            value = value.replace(/^['"]|['"]$/g, "");
-        }
-        out[key] = value;
-    }
-    return out;
-}
 /** Build (or refresh) an IndexEntry by reading the page from disk. */
 export function buildIndexEntryForPage(path, fallback) {
     const normalizedPath = normalizeWikiPath(path);
     const content = readPage(normalizedPath);
     if (!content)
         return undefined;
-    const fm = parseFrontmatter(content);
-    const title = (typeof fm.title === "string" && fm.title) || fallback?.title || basenameTitle(normalizedPath);
-    const tags = Array.isArray(fm.tags) ? fm.tags : (fallback?.tags ?? []);
-    const updated = (typeof fm.updated === "string" && fm.updated) || fallback?.updated;
-    // Summary heuristic: existing summary if provided, else first non-frontmatter
-    // non-heading content line trimmed to 160 chars.
-    let summary = fallback?.summary?.trim() || "";
+    const { parsed: fm, body } = parseWikiFrontmatter(content);
+    const title = fm.title || fallback?.title || basenameTitle(normalizedPath);
+    const tags = fm.tags ?? fallback?.tags ?? [];
+    const updated = fm.updated || fallback?.updated;
+    // Compliant pages treat frontmatter summary as canonical. Legacy pages fall back
+    // to the first non-frontmatter, non-heading content line.
+    let summary = fm.summary?.trim() || fallback?.summary?.trim() || "";
     if (!summary) {
-        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;
         }
     }
@@ -145,7 +128,7 @@ function basenameTitle(path) {
 }
 /** Rebuild every index entry from on-disk pages. Preserves section if known. */
 export function rebuildIndexFromPages() {
-    const pages = listPages();
+    const pages = listPages().filter((path) => !isActionLogPage(path));
     const previous = new Map();
     // Try to keep section assignments by re-parsing the (possibly-corrupted) index without recursion.
     try {
@@ -157,7 +140,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 +164,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,23 +217,59 @@ 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"));
 }
+function isActionLogPage(path) {
+    return ACTION_LOG_PAGE_RE.test(path);
+}
 /** Add or update an entry in the index. Upserts by path. */
 export function addToIndex(entry) {
     const normalizedEntry = { ...entry, path: normalizeWikiPath(entry.path) };

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

@@ -43,14 +43,14 @@ test("parseIndex reads sections, summaries, tags, and updated dates", async () =
         },
     ]);
 });
-test("buildIndexEntryForPage derives title, metadata, and a trimmed summary from page content", async () => {
+test("buildIndexEntryForPage treats frontmatter summary as the canonical index summary", async () => {
     const { indexManager, wikiFs } = await loadModules();
-    wikiFs.writePage("pages/shared/runbooks/deploy.md", `---\ntitle: Deploy Runbook\ntags: [ops, release]\nupdated: 2026-05-04\n---\n\n# Deploy\n\n${"Deploy carefully ".repeat(20)}\n`);
+    wikiFs.writePage("pages/shared/runbooks/deploy.md", `---\ntitle: Deploy Runbook\nsummary: Production deployment checklist\ntags: [ops, release]\nupdated: 2026-05-04\n---\n\n# Deploy\n\n${"Deploy carefully ".repeat(20)}\n`);
     const entry = indexManager.buildIndexEntryForPage("pages/shared/runbooks/deploy.md");
     assert.deepEqual(entry, {
         path: "pages/shared/runbooks/deploy.md",
         title: "Deploy Runbook",
-        summary: `${("Deploy carefully ".repeat(20)).trim().slice(0, 157)}…`,
+        summary: "Production deployment checklist",
         section: "Knowledge",
         tags: ["ops", "release"],
         updated: "2026-05-04",
@@ -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");