hafez 2.1.0 → 2.3.0

package/dist/vault.js

@@ -2,7 +2,7 @@
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
 import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, relative, sep } from 'path';
 import { HafezError } from './types.js';
 // Prevent gray-matter from auto-coercing YAML date strings into JS Date objects
 const MATTER_OPTIONS = { engines: { yaml: (s) => yaml.load(s, { schema: yaml.JSON_SCHEMA }) } };
@@ -17,17 +17,21 @@ export function slugify(name) {
         .replace(/-{2,}/g, '-');
 }
 const KIND_DIRS = { entity: 'entities', knowledge: 'knowledge', session: 'sessions' };
-/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
-export const INDEXED_KINDS = ['entity', 'knowledge'];
+/** Kinds that live in the SQLite read index: every kind. Sessions joined in
+ * #35 — before that they were files-and-git only, for no recorded reason. */
+export const INDEXED_KINDS = ['entity', 'knowledge', 'session'];
+/** The two kinds a mutation can address. A session note is written once and
+ * read; `update`, `link`, `promote` never resolve one. */
+export const MUTABLE_KINDS = ['entity', 'knowledge'];
 /** Vault directory for a kind, relative to the vault root. */
 export function kindDir(kind) {
     return KIND_DIRS[kind];
 }
 /** A vault content file: anything a sync/merge must treat semantically. */
 export const VAULT_FILE_RE = new RegExp(`^(?:${Object.values(KIND_DIRS).join('|')})/.+\\.md$`);
-/** True for vault-relative paths whose kind lives in the read index. */
-export function isIndexedRelPath(relPath) {
-    return INDEXED_KINDS.some(k => relPath.startsWith(`${KIND_DIRS[k]}/`));
+/** True for vault-relative paths of a mutable kind — what index.md shows. */
+export function isMutableRelPath(relPath) {
+    return MUTABLE_KINDS.some(k => relPath.startsWith(`${KIND_DIRS[k]}/`));
 }
 /** History pathspecs covering the indexed dirs (changelog, file times). */
 export const INDEXED_DIR_PATHSPECS = INDEXED_KINDS.map(k => `${KIND_DIRS[k]}/`);
@@ -43,6 +47,16 @@ export function classifyIndexedRelPath(relPath) {
     }
     return null;
 }
+/** The note a vault-relative ('/'-separated) path is, or null: the files
+ * scanVaultDir lists — a non-dot `.md` directly in a kind dir. Archive logs,
+ * scaffold files and anything outside the kind dirs are not notes. */
+export function noteAtRelPath(relPath) {
+    const match = relPath.match(/^([^/]+)\/([^/]+)\.md$/);
+    if (!match || match[2].startsWith('.'))
+        return null;
+    const kind = INDEXED_KINDS.find(k => KIND_DIRS[k] === match[1]);
+    return kind ? { kind, slug: match[2] } : null;
+}
 /** All .md files directly in dir — non-recursive (archive/ subdirs are
  * invisible by construction) and dotfile-free: dotfile slugs are rejected by
  * resolveFilePath, so listing them would surface files no operation can reach. */
@@ -69,8 +83,17 @@ export function resolveFilePath(vaultPath, slug, kind) {
     }
     return join(vaultPath, KIND_DIRS[kind], `${slug}.md`);
 }
-/** The file a slug names, or null — entities are resolved before knowledge,
- * the one resolution order every operation sees. */
+/** The inverse of resolveFilePath / archiveLogPath: a vault file as the
+ * Journal names it — vault-relative and '/'-separated on every platform.
+ * Everything downstream compares these lists as POSIX paths: stageablePaths
+ * (src/git.ts) keeps an absent path only if `git ls-files` echoes it back,
+ * always with '/', so a '\' deletion was dropped and never staged; and the
+ * index.md gate (isMutableRelPath) never matched a '\' path (#187). */
+export function vaultRel(vaultPath, filePath) {
+    return relative(vaultPath, filePath).split(sep).join('/');
+}
+/** The mutable file a slug names, or null — entities are resolved before
+ * knowledge, the one resolution order every mutation sees. */
 export function findVaultFile(vaultPath, slug) {
     const entity = resolveFilePath(vaultPath, slug, 'entity');
     if (existsSync(entity))
@@ -80,6 +103,14 @@ export function findVaultFile(vaultPath, slug) {
         return knowledge;
     return null;
 }
+/** The file `read` resolves: the mutable kinds first, then a session note. */
+export function findReadableFile(vaultPath, slug) {
+    const mutable = findVaultFile(vaultPath, slug);
+    if (mutable)
+        return mutable;
+    const session = resolveFilePath(vaultPath, slug, 'session');
+    return existsSync(session) ? session : null;
+}
 /** Does this slug name a vault file? An invalid slug definitionally doesn't
  * exist — reference checks (create parent/related, link targets, validate)
  * must report "does not exist", not crash. validate() in particular exists to

package/dist/workstream.d.ts

@@ -0,0 +1,17 @@
+/** The family lines fire at: Number A's threshold. */
+export declare const FAMILY_MIN_LINES = 3;
+/** The family a Next Actions line opens with, or null. */
+export declare function familyOf(text: string): string | null;
+/** One firing family and its open-line count, as `read --json` gives it. */
+export interface Workstream {
+    prefix: string;
+    open_actions: number;
+}
+/** The `[a-z0-9]+` word tokens of a slug and name, lowercased. */
+export declare const wordTokens: (text: string) => Set<string>;
+/** The families an entity body carries unsplit, in first-appearance order,
+ * against the entities whose `parent` or `related` names it (`naming`). */
+export declare function workstreams(body: string, naming: Array<{
+    slug: string;
+    name: string;
+}>): Workstream[];

package/dist/workstream.js

@@ -0,0 +1,78 @@
+// src/workstream.ts
+// Workstream (see CONTEXT.md): a prefix family on an entity's Next Actions
+// with no Child or Related entity carrying it, Number A of the
+// workstream-signal research (#230, #240). The reference definition is
+// tools/research/ws_caps_prefix.py; the Health pass shares this module.
+//
+// A line's family is its leading run of ALL-CAPS tokens (two or more
+// characters; digits, hyphen, apostrophe allowed; a `WS4`/`WS-A` code is one
+// such token), minus a trailing step id (`A3`, `B1`); a lone step id is not
+// a family; a trailing possessive `'S` is stripped from a token. A family
+// fires at three or more lines, open or ticked; it stops once an entity
+// whose `parent` or `related` names this one carries a family token among
+// the word tokens of its slug or name. A code family (`WS4`, `WS-A`) stops
+// on its whole code only — a segment of the slug (`ws-a-dynamics`) or a
+// word of the name (`WS-A dynamics`) — never on `ws` or `a` alone. The
+// count reported is the family's OPEN lines — what is left to split — so a
+// family with none does not render at all.
+import { getActionItems } from './document.js';
+const TOKEN = "[A-Z][A-Z0-9'’\\-]+";
+const PREFIX_RE = new RegExp(`^((?:${TOKEN})(?: ${TOKEN})*)(?=[,:;]|\\s[—–-]\\s|\\s|$)`);
+const STEP_RE = /^[A-Z]\d+$/;
+const POSSESSIVE_RE = /['’]S$/;
+const CODE_RE = /^WS(\d+|-[A-Z])$/;
+/** The family lines fire at: Number A's threshold. */
+export const FAMILY_MIN_LINES = 3;
+/** The family a Next Actions line opens with, or null. */
+export function familyOf(text) {
+    const m = PREFIX_RE.exec(text);
+    if (!m)
+        return null;
+    const toks = m[1].split(' ').map(t => t.replace(POSSESSIVE_RE, ''));
+    while (toks.length > 1 && STEP_RE.test(toks[toks.length - 1]))
+        toks.pop();
+    const fam = toks.join(' ');
+    if (STEP_RE.test(fam))
+        return null;
+    return fam.length >= 2 ? fam : null;
+}
+/** The `[a-z0-9]+` word tokens of a slug and name, lowercased. */
+export const wordTokens = (text) => new Set(text.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+/** Whether the entity carries the whole lowercased code: as a segment of
+ * its slug, or as a word of its name (hyphen kept). */
+function carriesCode(e, code) {
+    return `-${e.slug.toLowerCase()}-`.includes(`-${code}-`)
+        || (e.name.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)*/g) ?? []).some(w => w === code);
+}
+/** The families an entity body carries unsplit, in first-appearance order,
+ * against the entities whose `parent` or `related` names it (`naming`). */
+export function workstreams(body, naming) {
+    const families = new Map();
+    for (const item of getActionItems(body)) {
+        const fam = familyOf(item.text);
+        if (fam === null)
+            continue;
+        const f = families.get(fam) ?? { lines: 0, open: 0 };
+        f.lines++;
+        if ('handle' in item)
+            f.open++;
+        families.set(fam, f);
+    }
+    const named = naming.map(e => wordTokens(`${e.slug} ${e.name}`));
+    const out = [];
+    for (const [prefix, f] of families) {
+        if (f.lines < FAMILY_MIN_LINES || f.open === 0)
+            continue;
+        if (CODE_RE.test(prefix)) {
+            if (naming.some(e => carriesCode(e, prefix.toLowerCase())))
+                continue;
+        }
+        else {
+            const tokens = Array.from(wordTokens(prefix));
+            if (named.some(set => tokens.some(t => set.has(t))))
+                continue;
+        }
+        out.push({ prefix, open_actions: f.open });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hafez",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,9 +17,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "build": "rm -rf dist && tsc && esbuild src/graph/client/main.ts --bundle --minify --format=iife --target=es2020 --log-level=warning --outfile=dist/graph/client.js && node dist/graph/copy-fonts.js && chmod +x dist/cli.js",
     "install:local": "chmod +x \"$(pwd)/dist/cli.js\" && mkdir -p ~/.local/bin && ln -sf \"$(pwd)/dist/cli.js\" ~/.local/bin/hafez && for d in ~/.claude/skills ~/.agents/skills; do for s in hafez hafez-save; do mkdir -p \"$d/$s\" && cp \"$(pwd)/skill/$s/SKILL.md\" \"$d/$s/SKILL.md\"; done; done",
-    "typecheck": "tsc -p tsconfig.test.json",
+    "typecheck": "tsc -p tsconfig.test.json && tsc -p src/graph/client/tsconfig.json",
     "pretest": "npm run build && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -30,14 +30,20 @@
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.1",
     "proper-lockfile": "^4.1.2",
-    "simple-git": "^3.33.0",
+    "simple-git": "^4.0.2",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
+    "@fontsource-variable/outfit": "^5.3.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.4.0",
     "@types/proper-lockfile": "^4.1.4",
+    "esbuild": "^0.28.2",
+    "force-graph": "^1.52.0",
+    "markdown-it": "^15.0.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/skill/hafez/SKILL.md

@@ -3,10 +3,11 @@ name: hafez
 description: >
   Hafez vault: the less common operations and the tool itself. Use when the
   user asks what is in the vault ("what am I working on?", "what's stale?"),
-  wants to promote, link, unlink, delete, change a status or validate, or
-  wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez").
-  Also the reference to read when no Hafez block is in your instructions.
-hash: 01a30ae1e209
+  wants to promote, link, unlink, delete, change a status or validate, asks
+  to check the vault or clean it up, or wants to update or reconfigure Hafez
+  ("upgrade hafez", "set up hafez"). Also the reference to read when no
+  Hafez block is in your instructions.
+hash: c52f079e667f
 ---
 
 # Hafez
@@ -22,7 +23,7 @@ Open actions on an entity you read are yours: tick what landed, drop what is dea
 ## Create
 
 ```
-hafez create entity "<name>" --type <project|entity> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"
+hafez create entity "<name>" --type <project|entity> --parent <slug you read, or its parent> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"
 hafez create knowledge "<name>" --synthesis "<the insight>" --confidence <observation|pattern|principle> --related <slug>
 ```
 
@@ -32,10 +33,13 @@ A plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowle
 
 ```
 hafez query --filter <active|paused|done|stale|capture>
-hafez search "<terms>" --kind <entity|knowledge>
+hafez search "<terms>" --kind <entity|knowledge|session|all>
+hafez query --kind session --related-to <slug>
 hafez stats
 ```
 
+`search` and `query` reach entities and knowledge notes; `--kind all` adds the session notes, `--kind session` lists them alone, newest first. `hafez read <slug> --archive` prints an entity's archived log entries.
+
 ## Less common operations
 
 ```
@@ -45,9 +49,14 @@ hafez unlink <slug> <target> --relation <parent|related>
 hafez update <slug> --status <active|paused|done>
 hafez delete <slug>
 hafez validate
+hafez health
 ```
 
-A plan's status is `active|done`. `delete` removes a knowledge or session note only; an entity is retired with `--status done`.
+A plan's status is `active|done`. `delete` removes a knowledge or session note only; an entity is retired with `--status done`. `health` lists what placement would change and applies nothing.
+
+A vault check ("check the vault", "clean up the vault", "what has drifted"): run `hafez health --json` and bring back proposals grouped by kind, never the rows. In a session that read an entity, lead with that entity's rows; the rest of the vault as counts.
+One line per kind, with the count: the Workstreams to split (a `create entity … --parent` line each, named as the actions name it); the one-way edges and the unlinked mentions as one `hafez batch` of `link` ops, one commit; the restated decisions and the leakage pairs as a short list for the user to judge, nothing proposed.
+Apply nothing until the user confirms a kind, not even a `link` line that looks safe; then one `batch` per kind.
 
 Several writes that must land together go in one batch: a bare array, no wrapper. A slug is the name lowercased, apostrophes dropped, each other run of characters that are not letters or digits turned into one `-` and none left at either end, so a later op can name what an earlier one creates.