hypomnema 1.0.0

package/scripts/verify.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Hypomnema verify script
+ *
+ * Checks verify_by and verify_by_date fields across wiki pages.
+ * More detailed than the doctor check: shows the actual verify_by questions
+ * and groups results by status.
+ *
+ * Usage:
+ *   node scripts/verify.mjs [options]
+ *
+ * Options:
+ *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --file=<path>       Check a single file only
+ *   --json              Output as JSON
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, extname } from 'path';
+import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
+
+// ── arg parsing ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { hypoDir: null, file: null, json: false };
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
+    else if (arg.startsWith('--file='))    args.file   = expandHome(arg.slice(7));
+    else if (arg === '--json')             args.json   = true;
+  }
+  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  return args;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (hypoDir && isIgnored(full, hypoDir, ignorePatterns)) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) collectMdFiles(full, acc, hypoDir, ignorePatterns);
+    else if (extname(entry) === '.md') acc.push(full);
+  }
+  return acc;
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/\s*#.*$/, '').replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+const VERIFIED_TYPES = new Set(['adr', 'page', 'learning', 'concept', 'playbook', 'tool-eval']);
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+const today = new Date().toISOString().slice(0, 10);
+
+let files;
+if (args.file) {
+  files = [args.file];
+} else {
+  const ignorePatterns = loadHypoIgnore(args.hypoDir);
+  const scanDirs = ['pages', 'projects'].map(d => join(args.hypoDir, d));
+  files = scanDirs.flatMap(d => collectMdFiles(d, [], args.hypoDir, ignorePatterns));
+}
+
+const overdue  = [];
+const upcoming = [];
+const missing  = [];
+const ok       = [];
+
+for (const file of files) {
+  let content;
+  try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+  const fm = parseFrontmatter(content);
+  if (!fm) continue;
+
+  const type = fm.type || '';
+  if (!VERIFIED_TYPES.has(type)) continue;
+
+  const rel = args.hypoDir ? relative(args.hypoDir, file) : file;
+  const entry = {
+    file: rel,
+    title: fm.title || rel,
+    type,
+    verify_by: fm.verify_by || null,
+    verify_by_date: fm.verify_by_date || null,
+  };
+
+  if (!fm.verify_by) {
+    missing.push(entry);
+  } else if (fm.verify_by_date && /^\d{4}-\d{2}-\d{2}$/.test(fm.verify_by_date)) {
+    const daysUntil = Math.ceil((new Date(fm.verify_by_date) - new Date(today)) / 86400000);
+    if (fm.verify_by_date < today) {
+      overdue.push({ ...entry, daysOverdue: -daysUntil });
+    } else if (daysUntil <= 14) {
+      upcoming.push({ ...entry, daysUntil });
+    } else {
+      ok.push(entry);
+    }
+  } else {
+    ok.push(entry);
+  }
+}
+
+if (args.json) {
+  console.log(JSON.stringify({ overdue, upcoming, missing, ok }, null, 2));
+  process.exit(overdue.length > 0 ? 1 : 0);
+}
+
+const total = overdue.length + upcoming.length + missing.length + ok.length;
+console.log(`Scanned ${total} tracked page(s)\n`);
+
+if (overdue.length > 0) {
+  console.log(`✗ Overdue (${overdue.length}):`);
+  for (const p of overdue) {
+    console.log(`  ${p.file}  [${p.daysOverdue}d overdue]`);
+    console.log(`    verify_by: ${p.verify_by}`);
+  }
+  console.log('');
+}
+
+if (upcoming.length > 0) {
+  console.log(`⚠ Due soon (${upcoming.length}):`);
+  for (const p of upcoming) {
+    console.log(`  ${p.file}  [in ${p.daysUntil}d, ${p.verify_by_date}]`);
+    console.log(`    verify_by: ${p.verify_by}`);
+  }
+  console.log('');
+}
+
+if (missing.length > 0) {
+  console.log(`⚠ Missing verify_by (${missing.length}):`);
+  for (const p of missing) console.log(`  ${p.file}`);
+  console.log('');
+}
+
+if (ok.length > 0 && overdue.length === 0 && upcoming.length === 0) {
+  console.log(`✓ All ${ok.length} page(s) verified and up to date`);
+}
+
+const summary = [
+  overdue.length  ? `${overdue.length} overdue`  : '',
+  upcoming.length ? `${upcoming.length} due soon` : '',
+  missing.length  ? `${missing.length} missing verify_by` : '',
+  ok.length       ? `${ok.length} ok` : '',
+].filter(Boolean).join(', ');
+
+console.log(`Result: ${summary || 'nothing to verify'}`);
+
+// Emit signal lines for overdue/upcoming pages so /hypo:verify skill can drive review
+const needsReview = [...overdue, ...upcoming].filter(p => p.verify_by);
+if (needsReview.length > 0) {
+  console.log('');
+  for (const p of needsReview) {
+    console.log(`[HYPO VERIFY QUESTION: ${p.verify_by} (file: ${p.file})]`);
+  }
+}
+
+if (overdue.length > 0) process.exit(1);

package/skills/crystallize/SKILL.md

@@ -0,0 +1,85 @@
+---
+description: Surface synthesis candidates and consolidate scattered wiki knowledge into stable pages
+---
+
+You are running `/hypo:crystallize`. Find pages that are ready to be consolidated into stable, cross-linked knowledge — then guide the synthesis.
+
+## What this does
+
+- Finds tag groups with ≥ N pages sharing the same tag (synthesis candidates)
+- Lists orphan pages (no outbound `[[wikilinks]]`)
+- Lists draft / stub pages that could be fleshed out
+- After the script runs, you help the user pick what to crystallize and do it
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Run crystallize scan
+
+```bash
+node <package-root>/scripts/crystallize.mjs \
+  [--wiki-dir="<path>"] \
+  [--min-group=<n>] \
+  [--json]
+```
+
+Options:
+- `--min-group=<n>` — minimum pages per tag group to report (default: 2)
+- `--json` — output results as JSON
+
+Show the output verbatim.
+
+---
+
+## Step 3 — Session-close checklist (if triggered at session end)
+
+If `/hypo:crystallize` was invoked as a session-close action, run through this checklist before synthesizing. Proceed automatically without confirmation unless the user has not said "auto".
+
+1. **session-state.md** — update `projects/<name>/session-state.md` with the next tasks list (what to tackle first next time).
+2. **hot.md (project)** — update `projects/<name>/hot.md` with a session snapshot: what changed and decisions made. Keep under 500 words. Do not put next-step tasks here; those belong in session-state.md.
+3. **hot.md (root)** — update `<wiki-root>/hot.md` active-projects pointer table: set the `Last Session` date for this project to today.
+4. **session-log** — append a session entry to `projects/<name>/session-log/YYYY-MM.md` (create the file if it does not exist for this month).
+5. **open-questions** — only if `pages/open-questions.md` exists and questions were raised or resolved this session: move resolved ones out; add newly raised ones. Skip if unchanged.
+6. **log.md** — append a `session` entry to `<wiki-root>/log.md`.
+
+After completing the checklist, report each item with ✓ and ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
+
+---
+
+## Step 4 — Pick a synthesis target
+
+Present the top candidates from the script output:
+- Tag clusters with the most pages
+- Long-standing orphans
+- Pages marked `status: draft`
+
+Ask: "Which of these would you like to crystallize now? (or 'all' / 'skip')"
+
+---
+
+## Step 5 — Synthesize
+
+For the chosen target:
+
+1. Read all pages in the cluster.
+2. Write a new synthesis page at `pages/syntheses/<slug>.md` with:
+
+```yaml
+---
+title: <synthesis title>
+type: synthesis
+tags: [<shared tags>]
+updated: <today YYYY-MM-DD>
+evidence_strength: inferred
+---
+```
+
+3. Cross-link all source pages back to the synthesis with `[[wikilink]]`.
+4. Add the synthesis to `index.md` under `## Pages — Syntheses`.

package/skills/graph/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Generate a wikilink dependency graph from wiki pages
+---
+
+You are running `/hypo:graph`. Build a wikilink dependency graph from all pages under `pages/` and `projects/` and output it in the requested format.
+
+## What this produces
+
+- **json** (default) — adjacency list with in/out-degree counts per node, sorted by total edges
+- **mermaid** — `graph TD` Mermaid diagram (paste into any Mermaid renderer)
+- **dot** — Graphviz DOT format (pipe to `dot -Tsvg` for an SVG)
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Ask for output format (optional)
+
+If the user did not specify a format, ask:
+
+> "Output format? (json / mermaid / dot) [json]"
+
+Default: `json`
+
+Optionally ask:
+
+> "Minimum edges to include a node? (0 = all) [0]"
+
+---
+
+## Step 3 — Run graph
+
+```bash
+node <package-root>/scripts/graph.mjs \
+  [--wiki-dir="<path>"] \
+  [--format=json|mermaid|dot] \
+  [--min-edges=<n>]
+```
+
+---
+
+## Step 4 — Present results
+
+- **json**: summarise the top 10 most-connected nodes (by `in + out`), then offer to show the full JSON.
+- **mermaid**: wrap the output in a fenced code block tagged `mermaid` so it renders inline.
+- **dot**: wrap the output in a fenced code block tagged `dot` and suggest the user pipe it to `dot -Tsvg -o graph.svg`.
+
+If the graph has 0 edges, note that no `[[wikilinks]]` were found between pages.

package/skills/ingest/SKILL.md

@@ -0,0 +1,83 @@
+---
+description: Add a source document to the wiki and synthesize a source-summary page
+---
+
+You are running `/hypo:ingest`. Add a new source document to `sources/` and create (or update) its corresponding `source-summary` page under `pages/`.
+
+## What this does
+
+- Checks which files in `sources/` are missing a `source-summary` page
+- Reports pages that reference a source file that does not exist in `sources/`
+- After the script runs, guides you to synthesize a summary for any un-ingested source
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Run ingest status check
+
+```bash
+node <package-root>/scripts/ingest.mjs [--wiki-dir="<path>"] [--json]
+```
+
+Options:
+- `--json` — output results as JSON (useful for tooling)
+
+Show the output verbatim.
+
+---
+
+## Step 3 — Handle the source file
+
+**If the user provided a file or URL to ingest:**
+
+1. Copy or download the source into `<wiki-root>/sources/<slug>.<ext>` (e.g., `sources/2026-05-07-article-title.md`).
+2. Confirm the file is now present.
+
+**If no file was provided:**
+
+List un-ingested sources from the script output and ask which one to process now.
+
+---
+
+## Step 4 — Synthesize a source-summary page
+
+For the chosen source, read its content and create `pages/<slug>.md` with the following frontmatter:
+
+```yaml
+---
+title: <descriptive title>
+type: source-summary
+source: <filename>
+tags: [<relevant tags>]
+updated: <today YYYY-MM-DD>
+evidence_strength: direct   # or inferred
+---
+```
+
+Then write a concise summary:
+- Key ideas (bullet list)
+- Why this source matters to the wiki
+- Any open questions or follow-up items
+
+Cross-reference existing pages with `[[wikilink]]` syntax where relevant.
+
+---
+
+## Step 5 — Update log.md
+
+Append an ingest entry to `<wiki-root>/log.md`:
+
+```
+## <YYYY-MM-DD> ingest — <slug>
+
+- source: sources/<filename>
+- summary: pages/<slug>.md
+- tags: <tags>
+```

package/skills/lint/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Lint wiki pages for frontmatter and broken wikilinks
+---
+
+You are running `/hypo:lint`. Validate all wiki pages for frontmatter correctness and broken `[[wikilink]]` references.
+
+## What this checks
+
+- Every `.md` file under `pages/` and `projects/` should have `---` frontmatter (missing frontmatter is a warning, not an error)
+- Required fields: `title`, `type`
+- `type` must be one of the recognised values (concept, source-summary, learning, adr, …)
+- `updated` field should be present
+- All `[[wikilinks]]` must resolve to an existing page slug
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Run lint
+
+```bash
+node <package-root>/scripts/lint.mjs [--wiki-dir="<path>"] [--json] [--fix]
+```
+
+Options:
+- `--json` — output results as JSON (useful for tooling)
+- `--fix` — auto-add missing `updated` field (safe repairs only; no other fields are modified)
+
+Show the output verbatim.
+
+---
+
+## Step 3 — Interpret results
+
+- `✓ No lint issues found` — wiki is clean
+- `✗ <file>: <message>` — error (missing required field or malformed frontmatter); must be fixed
+- `⚠ <file>: <message>` — warning (unknown type, missing `updated`, broken link); worth fixing
+
+A non-zero exit code means at least one **error** was found (warnings alone do not produce a non-zero exit code).
+
+---
+
+## Step 4 — Offer to fix
+
+For **broken wikilinks**: list the affected files and ask if the user wants help correcting the links now.
+
+For **missing `updated`**: suggest running with `--fix` to auto-add `updated: <today>` to each affected page's frontmatter. Note: `--fix` only repairs files that already have a valid, closed frontmatter block — files with no frontmatter or malformed frontmatter are skipped.
+
+For **missing required fields** (`title`, `type`): open the affected files and help the user fill them in.

package/skills/query/SKILL.md

@@ -0,0 +1,58 @@
+---
+description: Search wiki pages by keyword and retrieve relevant knowledge
+---
+
+You are running `/hypo:query`. Full-text search across all wiki pages and projects, then synthesize an answer from the matching pages.
+
+## What this does
+
+- Searches `pages/` and `projects/` for the given query terms
+- Returns matching files with a context excerpt and frontmatter summary
+- You then read the top results and synthesize an answer
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Extract the query
+
+Use the search terms from the user's message. If no query was provided, ask:
+
+> "What would you like to search for in your wiki?"
+
+---
+
+## Step 3 — Run query
+
+```bash
+node <package-root>/scripts/query.mjs \
+  --q="<search terms>" \
+  [--wiki-dir="<path>"] \
+  [--limit=<n>] \
+  [--json]
+```
+
+Options:
+- `--q=<query>` — search query (required)
+- `--limit=<n>` — max results (default: 10)
+- `--json` — output results as JSON
+
+Show the output verbatim.
+
+---
+
+## Step 4 — Synthesize an answer
+
+Read the top matching pages (up to 5) and produce a synthesized response:
+
+1. **Direct answer** — if the query has a clear answer from the wiki, state it first.
+2. **Supporting pages** — list the relevant pages with one-line descriptions and `[[wikilink]]` references.
+3. **Gaps** — if the wiki lacks coverage on the topic, note what is missing and suggest an ingest target.
+
+If zero results are returned, say so and offer to broaden the search or suggest using `/hypo:ingest` to add relevant sources.

package/skills/verify/SKILL.md

@@ -0,0 +1,92 @@
+---
+description: Check wiki pages for stale or unverified knowledge and prompt review
+---
+
+You are running `/hypo:verify`. Check all wiki pages for `verify_by` and `verify_by_date` fields, surface overdue pages, and guide a review pass.
+
+## What this does
+
+- Scans all pages for `verify_by` (a question to re-check) and `verify_by_date` (deadline)
+- Groups results: **overdue**, **due soon** (within 14 days), and **ok**
+- After the script runs, you help the user review and update each overdue page
+
+---
+
+## Step 1 — Locate package root
+
+Locate the Hypomnema package root (the directory two levels above this file (`skills/<name>/SKILL.md` → package root)).
+
+If the user specified a wiki directory, pass it as `--wiki-dir="<path>"`. Otherwise omit the flag and the script resolves the wiki root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
+
+---
+
+## Step 2 — Run verify
+
+```bash
+node <package-root>/scripts/verify.mjs \
+  [--wiki-dir="<path>"] \
+  [--file="<path>"] \
+  [--json]
+```
+
+Options:
+- `--file=<path>` — check a single file only
+- `--json` — output results as JSON
+
+Show the output verbatim.
+
+---
+
+## Step 3 — Interpret results
+
+- **overdue** — `verify_by_date` is in the past; the page needs immediate review
+- **due soon** — `verify_by_date` is within 14 days; worth reviewing this session
+- **ok** — no verify fields, or deadline is far enough out
+
+A page with `verify_by` but no `verify_by_date` is treated as **ok** (no deadline set — add `verify_by_date` to schedule a review).
+
+---
+
+## Step 4 — Review overdue pages
+
+For each overdue page, in priority order:
+
+1. Read the page content.
+2. Show the `verify_by` question to the user.
+3. Ask: "Is this still accurate? (yes / no / partially)"
+4. Based on the answer:
+   - **yes** — update `last_reviewed: <today>` and push `verify_by_date` forward by 90 days.
+   - **no / partially** — help the user edit the page to correct the outdated content, then update `last_reviewed` and `verify_by_date`.
+5. Offer to move to the next overdue page.
+
+---
+
+## Step 5 — Update frontmatter
+
+After each review, apply the updated `last_reviewed` and `verify_by_date` fields to the page frontmatter. Do not change any other fields unless the user approves.
+
+---
+
+## Step 6 — Append stale items to open-questions.md
+
+For each page reviewed as **no** or **partially** (content found stale or incorrect):
+
+1. Open `<wiki-root>/pages/open-questions.md`. If absent, create it with this frontmatter:
+
+```
+---
+title: Open Questions
+type: open-questions
+updated: <today YYYY-MM-DD>
+---
+
+# Open Questions
+```
+
+2. Append an entry:
+
+```
+- [ ] Re-verify [[<page-slug>|<page-title>]]: <verify_by question>  (surfaced: <today YYYY-MM-DD>)
+```
+
+3. Save the file. Do not remove or reorder existing entries.

package/templates/.hypoignore

@@ -0,0 +1,18 @@
+# .hypoignore — patterns excluded from Hypomnema hooks
+# One glob per line. Lines starting with # are comments.
+# Matched files are not read by hooks or included in index lookups.
+# Syntax follows .gitignore glob rules.
+
+# Large binaries
+*.pdf
+*.zip
+*.tar.gz
+
+# Credentials and secrets
+*.pem
+*.key
+*.env
+
+# Draft / scratch (uncomment to hide from hooks)
+# drafts/
+# scratch/

package/templates/Home.md

@@ -0,0 +1,34 @@
+---
+title: Home
+type: reference
+updated: YYYY-MM-DD
+tags: [wiki, home]
+---
+
+# Wiki
+
+> Personal knowledge base powered by [Hypomnema](https://github.com/sk-lim19f/Hypomnema).
+
+---
+
+## Quick Start
+
+- [[index]] — full page catalog
+- [[hot]] — active projects and last session context
+- [[log]] — chronological activity log
+- [[SCHEMA]] — type system reference
+- [[hypo-guide]] — operations guide
+
+---
+
+## Active Projects
+
+<!-- Links to your active project indexes -->
+<!-- [[projects/my-project/index|my-project]] -->
+
+---
+
+## Recent Pages
+
+<!-- Update after each significant ingest or writing session -->
+<!-- [[learnings/topic]] — date -->