chapterhouse 0.7.0 → 0.8.0

package/dist/wiki/timeline.js

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Wiki timeline — append-only timeline section management
+// ---------------------------------------------------------------------------
+import { readPage, writePage } from "./fs.js";
+import { parseWikiFrontmatter } from "./frontmatter.js";
+import { upsertWikiPage } from "./index-manager.js";
+import { normalizeWikiPath } from "./path-utils.js";
+const TIMELINE_HEADING = "## Timeline";
+/**
+ * Append an entry to the `## Timeline` section of a wiki page.
+ * Creates the section (and the page itself) if absent.
+ * Calls upsertWikiPage to keep SQLite in sync after writing.
+ */
+export function appendTimeline(pagePath, entry, timestamp) {
+    const normalized = normalizeWikiPath(pagePath);
+    const ts = timestamp ?? new Date().toISOString();
+    const block = `\n### ${ts}\n\n${entry.trim()}\n`;
+    let content = readPage(normalized);
+    if (!content) {
+        // Create a minimal page with frontmatter + empty timeline
+        const title = deriveTitleFromPath(normalized);
+        content = `---\ntitle: ${title}\nsummary: ${title}\nupdated: ${ts.slice(0, 10)}\ntags: []\n---\n\n# ${title}\n\n${TIMELINE_HEADING}\n${block}`;
+        writePage(normalized, content);
+    }
+    else if (content.includes(TIMELINE_HEADING)) {
+        // Append after the last content in the timeline section
+        const idx = content.lastIndexOf(TIMELINE_HEADING);
+        const before = content.slice(0, idx + TIMELINE_HEADING.length);
+        const after = content.slice(idx + TIMELINE_HEADING.length);
+        content = before + after + block;
+        writePage(normalized, content);
+    }
+    else {
+        // Add timeline section at end of page
+        const trimmed = content.trimEnd();
+        content = trimmed + `\n\n${TIMELINE_HEADING}\n${block}`;
+        writePage(normalized, content);
+    }
+    // Keep SQLite in sync
+    const { parsed: fm } = parseWikiFrontmatter(readPage(normalized) ?? content);
+    const summary = fm.summary ?? deriveTitleFromPath(normalized);
+    upsertWikiPage(normalized, fm, summary);
+}
+function deriveTitleFromPath(path) {
+    const segs = path.split("/").filter(Boolean);
+    const file = segs[segs.length - 1] || path;
+    const base = file.replace(/\.md$/, "");
+    const titleBase = base === "index" && segs.length >= 2 ? segs[segs.length - 2] : base;
+    return titleBase.split(/[-_]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+//# sourceMappingURL=timeline.js.map

package/dist/wiki/timeline.test.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// Timeline tests — appendTimeline
+// Sandbox: single CHAPTERHOUSE_HOME per file to avoid module-singleton confusion
+// ---------------------------------------------------------------------------
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+let SANDBOX;
+let mods;
+test.before(async () => {
+    mkdirSync(join(process.cwd(), ".test-work"), { recursive: true });
+    SANDBOX = mkdtempSync(join(process.cwd(), ".test-work", "timeline-"));
+    process.env.CHAPTERHOUSE_HOME = SANDBOX;
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const timeline = await import(new URL(`./timeline.js?c=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?c=${nonce}`, import.meta.url).href);
+    const indexManager = await import(new URL(`./index-manager.js?c=${nonce}`, import.meta.url).href);
+    mods = { timeline, wikiFs, indexManager };
+    mods.wikiFs.ensureWikiStructure();
+});
+test.after(() => {
+    try {
+        rmSync(SANDBOX, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+});
+test("appendTimeline creates page if it doesn't exist", () => {
+    mods.timeline.appendTimeline("pages/topics/rust/index.md", "First mention of Rust");
+    const content = mods.wikiFs.readPage("pages/topics/rust/index.md");
+    assert.ok(content, "Page should be created");
+    assert.ok(content.includes("## Timeline"), "Should have Timeline section");
+    assert.ok(content.includes("First mention of Rust"), "Should contain entry text");
+});
+test("appendTimeline creates Timeline section if absent", () => {
+    mods.wikiFs.writePage("pages/topics/go/index.md", "---\ntitle: Go\nsummary: Go programming language\nupdated: 2026-01-01\ntags: []\n---\n\n# Go\n\nSimple language.\n");
+    mods.timeline.appendTimeline("pages/topics/go/index.md", "Go 1.22 released");
+    const content = mods.wikiFs.readPage("pages/topics/go/index.md");
+    assert.ok(content.includes("## Timeline"), "Should have added Timeline section");
+    assert.ok(content.includes("Go 1.22 released"), "Should contain the entry");
+    assert.ok(content.includes("# Go"), "Should preserve original content");
+});
+test("appendTimeline is append-only: existing entries are unchanged", () => {
+    mods.timeline.appendTimeline("pages/topics/node/index.md", "First entry");
+    const after1 = mods.wikiFs.readPage("pages/topics/node/index.md");
+    assert.ok(after1.includes("First entry"));
+    mods.timeline.appendTimeline("pages/topics/node/index.md", "Second entry");
+    const after2 = mods.wikiFs.readPage("pages/topics/node/index.md");
+    assert.ok(after2.includes("First entry"), "First entry should still be present");
+    assert.ok(after2.includes("Second entry"), "Second entry should be appended");
+    assert.ok(after2.indexOf("First entry") < after2.indexOf("Second entry"), "Order should be preserved");
+});
+test("appendTimeline calls upsertWikiPage to sync SQLite", () => {
+    mods.timeline.appendTimeline("pages/topics/typescript/index.md", "TypeScript 5.0 notes");
+    const results = mods.indexManager.wikiSearch("typescript");
+    assert.ok(results.some((r) => r.path === "pages/topics/typescript/index.md"), "Page should be in SQLite after appendTimeline");
+});
+test("appendTimeline adds timestamp heading to each entry", () => {
+    const ts = "2026-05-14T20:45:55.900Z";
+    mods.timeline.appendTimeline("pages/topics/deno/index.md", "Deno 2.0 released", ts);
+    const content = mods.wikiFs.readPage("pages/topics/deno/index.md");
+    assert.ok(content.includes(`### ${ts}`), "Should have timestamp heading");
+    assert.ok(content.includes("Deno 2.0 released"), "Should have entry text");
+});
+//# sourceMappingURL=timeline.test.js.map

package/dist/wiki/topic-structure.js

@@ -31,7 +31,7 @@ export const EXEMPT_PREFIXES = [
 export const EXEMPT_PAGES = [
     "pages/index.md",
 ];
-/** Map a `remember`-style category name to its directory under pages/. */
+/** Map a legacy category name to its directory under pages/. */
 const CATEGORY_DIR_MAP = {
     person: "people",
     people: "people",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.7.0",
+  "version": "0.8.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/pkb-ideas/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: pkb-ideas
+description: Lightweight idea capture in the PKB. Creates pages/ideas/<slug>.md with a status lifecycle (seed → germinating → mature → archived) and links to related topics.
+when_to_load: When the user wants to capture a new idea, hypothesis, or proposal to develop over time.
+related_skills:
+  - wiki-conventions
+---
+
+# PKB Idea Capture
+
+Use this skill to record and develop ideas in the wiki. Ideas live as flat pages (not topic directories) under `pages/ideas/`.
+
+## Page Location
+
+`pages/ideas/<slug>.md`
+
+- Slug is lowercase kebab-case from the idea title (e.g. `async-wiki-sync`, `personal-memory-tiering`).
+- Ideas are flat pages, not directories — no sub-facets.
+
+## Frontmatter Template
+
+```yaml
+---
+title: <Idea Title>
+entity_type: idea
+status: seed
+summary: <One sentence capturing the core hypothesis or proposal>
+tags: [<topic-tag>]
+related:
+  - pages/topics/<topic-slug>/index.md
+updated: <YYYY-MM-DD>
+---
+```
+
+## Status Lifecycle
+
+| Status | Meaning |
+|--------|---------|
+| `seed` | Just captured — raw, unvalidated |
+| `germinating` | Actively exploring — some evidence or development |
+| `mature` | Well-developed — ready to act on or publish |
+| `archived` | Abandoned or superseded — kept for reference |
+
+Progress the status forward as the idea develops. Move `archived` ideas to `pages/_archive/ideas/<slug>.md`.
+
+## Page Structure
+
+```markdown
+## Hypothesis
+
+<Core claim or proposal — what would be true if this idea is right?>
+
+## Evidence / Notes
+
+- <Supporting observation, date>
+- <Counter-evidence or open question>
+
+## Next Steps
+
+- [ ] <Concrete action to develop this idea>
+
+## Related
+
+- [[<Topic or Project>]] — <connection>
+```
+
+## Workflow
+
+1. Run `wiki_search` for the idea topic to check for existing related ideas or pages.
+2. Create the page with `wiki_update` using the template above.
+3. Set `status: seed` for fresh captures.
+4. Link to relevant topic pages in `related:` frontmatter.
+5. When returning to an idea, update the status and append new evidence or notes.
+
+## Link Conventions
+
+- Add `related:` links to topic pages (`pages/topics/<slug>/index.md`) that this idea draws from.
+- When an idea matures into a decision or project, add a `related:` link to the decision or project page and set status to `archived`.

package/skills/pkb-ideas/_meta.json

@@ -0,0 +1,4 @@
+{
+  "slug": "pkb-ideas",
+  "version": "1.0.0"
+}

package/skills/pkb-org/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pkb-org
+description: Capture and maintain organization knowledge in the PKB. Creates or updates pages/orgs/<slug>/index.md with compiled truth, interaction timeline, and bidirectional links to people, projects, and topics.
+when_to_load: When the user mentions an organization, company, team, or employer and wants it recorded or updated in the wiki.
+related_skills:
+  - wiki-conventions
+---
+
+# PKB Organization Capture
+
+Use this skill when capturing or updating knowledge about an organization (company, team, consortium, employer) in the wiki.
+
+## Page Location
+
+Organization pages live at `pages/orgs/<slug>/index.md`.
+
+- Slug is lowercase kebab-case from the org name (e.g. `acme-corp`, `rust-foundation`).
+- Create `pages/orgs/<slug>/` as a topic directory; `index.md` is the compiled truth overview.
+
+## Frontmatter Template
+
+```yaml
+---
+title: <Org Name>
+entity_type: org
+summary: <One sentence describing what this org does>
+tags: [<industry-tag>, <tech-tag>]
+related:
+  - pages/people/<person-slug>/index.md
+  - pages/projects/<project-slug>/index.md
+  - pages/topics/<topic-slug>/index.md
+updated: <YYYY-MM-DD>
+---
+```
+
+## Page Structure
+
+```markdown
+## Overview
+
+<Compiled truth: 2–4 sentences about the org — mission, size, domain, key products.>
+
+## People
+
+- [[<Person Name>]] — <role>
+
+## Projects
+
+- [[<Project Name>]] — <brief description>
+
+## Topics
+
+- [[<Topic>]] — <relevance>
+
+## Timeline
+
+- _(<YYYY-MM-DD>)_ <What happened in this interaction or what was learned>
+```
+
+## Workflow
+
+1. Run `wiki_search` for the org name to check if a page exists.
+2. If it exists, read it with `wiki_read`. If not, create it with the template above.
+3. Append a new timeline entry with today's date.
+4. Update compiled truth (Overview section) if materially new facts emerged.
+5. Add or update `related` frontmatter with links to people/projects/topics.
+6. Write with `wiki_update`.
+
+## Link Conventions
+
+- Bidirectional: after writing the org page, check linked person/project pages and add `related:` back-links where they're missing.
+- Use `[[Page Name]]` for inline cross-references in body text.
+- Keep `related:` frontmatter in sync with `[[...]]` body links.
+
+## Status Lifecycle
+
+Add a `status` field in frontmatter when relevant:
+
+- `active` — current engagement or known ongoing relationship
+- `past` — former employer, closed project, ended relationship
+- `prospect` — potential future engagement
+- `archived` — org no longer relevant; move page to `pages/_archive/orgs/<slug>/`

package/skills/pkb-org/_meta.json

@@ -0,0 +1,4 @@
+{
+  "slug": "pkb-org",
+  "version": "1.0.0"
+}

package/skills/pkb-people/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: pkb-people
+description: Capture and maintain a PKB profile for a person — compiled truth, interaction timeline, and follow-up extraction.
+---
+
+# PKB People Capture
+
+Creates and maintains wiki profiles for people in the Personal Knowledge Base.
+
+## When to Use
+
+- User mentions a person they've interacted with
+- User says "add {name} to my PKB", "capture notes about {name}", "I met with {name}"
+- User wants to update someone's profile with new information
+- After meetings, calls, or interactions where a person is central
+
+## Person Page Structure
+
+Page path: `pages/people/{slug}/index.md`
+
+Sections:
+1. **Frontmatter** — title, summary, updated, tags
+2. **## Summary** — compiled truth: role, affiliation, key facts, relationship to user (rewritten on updates)
+3. **## Timeline** — append-only record of interactions and observations
+
+## Steps
+
+### 1. Find or Create Profile
+
+Search first:
+```
+wiki_search("{person name}")
+```
+
+If no profile exists, create one:
+```
+wiki_update(
+  path="pages/people/{slug}/index.md",
+  title="{Person Name}",
+  summary="{one-line description of who this person is}",
+  content="---\ntitle: {Person Name}\nsummary: {description}\nupdated: {today}\ntags: [person]\nmetadata:\n  entity_type: person\n---\n\n# {Person Name}\n\n## Summary\n\n{Compiled truth about this person: role, org, relationship to user, key facts}\n\n## Timeline\n"
+)
+```
+
+### 2. Add Interaction to Timeline
+
+```
+wiki_append_timeline(
+  page="pages/people/{slug}/index.md",
+  entry="{Description of interaction, meeting, or observation}\n\n{Key points discussed or observed}"
+)
+```
+
+### 3. Update Compiled Truth
+
+After significant new information, rewrite the `## Summary` section via `wiki_update` to reflect current understanding. Keep it factual and concise (3–8 bullet points).
+
+### 4. Extract Follow-ups
+
+If the interaction produced action items or follow-ups, propose them to memory:
+```
+memory_propose(kind="action_item", payload={
+  title: "Follow up with {name} on {topic}",
+  detail: "{context from interaction}",
+  due_at: "{date if mentioned}"
+})
+```
+
+## Notes
+
+- Always rewrite the summary after new interactions — don't let it become stale
+- Timeline entries get their own `### {ISO timestamp}` heading automatically
+- Use `wiki_ingest_source` with `type: "text"` to ingest meeting notes or email text
+- Keep summaries under 200 chars for the frontmatter field; use the `## Summary` section for detail

package/skills/pkb-people/_meta.json

@@ -0,0 +1,4 @@
+{
+  "slug": "pkb-people",
+  "version": "1.0.0"
+}

package/skills/pkb-research/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pkb-research
+description: Manage a PKB research session — create a research hub, ingest sources, maintain a living synthesis document.
+---
+
+# PKB Research Session
+
+Manages a structured research session in the Personal Knowledge Base.
+
+## When to Use
+
+- User wants to research a topic deeply using multiple sources
+- User says "start a research session on X", "help me research X", "I'm researching X"
+- User wants a synthesis document that stays updated as they add sources
+
+## Session Structure
+
+For a research topic `{slug}` (derived from the topic name):
+
+- **Hub page**: `pages/research/{slug}/index.md` — overview, links, and timeline
+- **Synthesis**: `pages/research/{slug}/synthesis.md` — compiled truth, rewritten after each source
+
+## Steps
+
+### 1. Open the Session
+
+Create the hub page if it doesn't exist:
+```
+wiki_update(
+  path="pages/research/{slug}/index.md",
+  title="{Topic Name} Research",
+  summary="Research hub for {topic}",
+  content="---\ntitle: {Topic Name} Research\nsummary: Research hub for {topic}\nupdated: {today}\ntags: [research]\n---\n\n# {Topic Name} Research\n\n## Sources\n\n_(none yet)_\n\n## Timeline\n"
+)
+```
+
+Then open a timeline entry:
+```
+wiki_append_timeline(page="pages/research/{slug}/index.md", entry="Research session opened.")
+```
+
+### 2. Ingest Each Source
+
+For each source the user provides:
+```
+wiki_ingest_source(source="{url_or_text}", topic="{slug}")
+```
+
+Then update the synthesis:
+```
+wiki_update(
+  path="pages/research/{slug}/synthesis.md",
+  title="{Topic Name} Synthesis",
+  summary="Compiled synthesis for {topic} research",
+  content="... rewritten synthesis based on all sources so far ..."
+)
+```
+
+Append to hub timeline:
+```
+wiki_append_timeline(
+  page="pages/research/{slug}/index.md",
+  entry="Source ingested: {title}\n\nKey takeaways: {1-2 sentences}",
+  source_id="{source_id from ingest result}"
+)
+```
+
+### 3. Close the Session
+
+When the user is done:
+```
+wiki_append_timeline(
+  page="pages/research/{slug}/index.md",
+  entry="Research session closed. Final synthesis written to pages/research/{slug}/synthesis.md"
+)
+```
+
+## Notes
+
+- The synthesis document is rewritten (not appended) after each new source
+- The hub timeline is always append-only
+- Provide the user a brief summary after each source ingestion
+- If a source was already ingested, note it and skip synthesis update

package/skills/pkb-research/_meta.json

@@ -0,0 +1,4 @@
+{
+  "slug": "pkb-research",
+  "version": "1.0.0"
+}

package/skills/pkb-source/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pkb-source
+description: Ingest a source (URL, PDF, repo, or text) into the PKB wiki and get a summary of pages created or updated.
+---
+
+# PKB Source Ingestion
+
+Accepts a URL, PDF file path, Git repo URL, or raw text and ingests it into the Personal Knowledge Base.
+
+## When to Use
+
+- User shares a URL they want saved to their PKB
+- User wants to ingest a PDF, Git repo, or raw text
+- User says "add this to my PKB", "save this source", "ingest this"
+
+## Steps
+
+1. **Determine source type** — if not specified, auto-detect:
+   - `http://` or `https://` URL → `url` (or `repo` for GitHub/GitLab)
+   - Path ending in `.pdf` → `pdf`
+   - Everything else → `text`
+
+2. **Call `wiki_ingest_source`**:
+   ```
+   wiki_ingest_source(source="{source}", type="{type}", topic="{optional topic hint}")
+   ```
+
+3. **Report results** to the user:
+   - Number of pages created/updated
+   - List of entity pages (names and paths)
+   - Source ID for future reference
+   - If `already_existed: true`, tell the user it was already in the PKB
+
+## Notes
+
+- Ingestion is idempotent — the same source will not be duplicated
+- Entity extraction uses LLM; it may miss entities for very short or unstructured content
+- For raw text >10KB, consider splitting into multiple topical ingestions with `topic` hints

package/skills/pkb-source/_meta.json

@@ -0,0 +1,4 @@
+{
+  "slug": "pkb-source",
+  "version": "1.0.0"
+}

package/skills/wiki-conventions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wiki-conventions
 description: Use when creating, editing, linting, restructuring, or reviewing Chapterhouse wiki content.
-when_to_load: Wiki tools, remember/forget workflows, or direct edits under the Chapterhouse wiki.
+when_to_load: Wiki tools, wiki_update/wiki_ingest_source workflows, or direct edits under the Chapterhouse wiki.
 related_skills:
   - squad
 ---
@@ -12,7 +12,7 @@ Use this skill before creating, editing, linting, restructuring, archiving, or r
 
 ## Orientation Ritual — Mandatory Before Any Wiki Write
 
-Perform this checklist before using `wiki_update`, `remember`, `forget`, `wiki_ingest`, `wiki_lint`, or `wiki_rebuild_index`:
+Perform this checklist before using `wiki_update`, `wiki_append_timeline`, or `wiki_ingest_source`:
 
 1. Read `pages/index.md` with `wiki_read`.
 2. Scan the last 20-30 entries of `pages/_meta/log.md` to see recent edits, archives, and reorganizations.
@@ -52,8 +52,8 @@ Do not skip the ritual because the task feels small. The point is to avoid dupli
 
 ## Decision Recording Protocol
 
-- With `remember`, use `category: "decision"` plus both `about` and `entity`.
 - Record the decision against the actual entity that owns it.
+- Use `wiki_update` to write to that entity's canonical `decisions.md` page.
 - Keep decision facets canonical; prefer `decisions.md` over inventing one-off decision page names.
 
 ## Cross-Reference Standards
@@ -139,7 +139,7 @@ Use `autostub: true` only for genuine stubs that are intentionally thin and expe
 
 - A durable fact about a named project, tool, person, org, topic, or area -> `pages/<category>/<slug>/index.md`
 - A durable subtopic of an existing entity -> `pages/<category>/<slug>/<facet>.md`
-- A decision about an entity -> `remember` with `category: "decision"`, `about`, and `entity`, or write to that entity's `decisions.md`
+- A decision about an entity -> write to that entity's `decisions.md` with `wiki_update`
 - A user preference or routine -> the corresponding flat category page
-- Source material you want preserved before synthesis -> `wiki_ingest`
+- Source material you want preserved before synthesis -> `wiki_ingest_source`
 - A passing mention with no durable value yet -> do not create a new page; add it to existing context or leave it out