hafez 2.2.0 → 2.3.0

package/dist/vault.js

@@ -47,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. */

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.2.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",
@@ -34,10 +34,16 @@
     "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: 24f12671554e
+  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>
 ```
 
@@ -48,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.