hafez 2.2.0 → 2.3.0

package/README.md

@@ -167,6 +167,9 @@ hafez query --kind knowledge --domain security
 # Full-text search across the whole vault
 hafez search "token rotation"
 
+# See it in context: a live graph of the vault in your browser
+hafez graph auth-refactor
+
 # Record progress
 hafez update auth-refactor --log "progress: JWT flow implemented"
 hafez update auth-refactor --complete-action "migration plan"
@@ -194,7 +197,49 @@ Frontmatter at a glance:
 | `resource` (canonical URI) | optional | — |
 | `subtype`, `confidence` | — | optional |
 
-Links (`parent`, `related`) are validated — they must point at slugs that exist. `hafez validate` checks vault integrity.
+Links (`parent`, `related`) are validated — they must point at slugs that exist. A `related` link between two entities, or two knowledge notes, is kept on both files. `hafez validate` checks vault integrity.
+
+## Where your judgement matters
+
+The agent writes to your vault as work lands, without asking. Behind a few of those writes is a judgement no rule in the tool can make, and the Health pass's proposals wait for your yes. Each choice is below as the question, the test, and what happens once it is made, so you can make it, or check the one the agent made.
+
+### 1. Child or related?
+
+**Question:** one piece of work bears on another. Is it part of it, or beside it?
+
+**Test:** would it carry on if the other were finished or dropped? If not, it is a **Child**. If so, the two are **Related**.
+
+**Then:** a Child carries `parent`, the one mark of childhood, and the parent's `read` lists it. Related between two entities, or two knowledge notes, is one edge the tool keeps on both files. A pair is never both: a `related` naming a parent or a child is rejected, and so is a `--parent` naming a related entity. A parent whose own work is coordination only is a **Hub**.
+
+### 2. Split a Workstream or not?
+
+**Question:** an entity's `read` shows a `workstream:` line: its actions share an ALL-CAPS prefix that no Child or related entity carries in its name. Is it a real thread of work, or a habit of phrasing?
+
+**Test:** would you track it, brief it and finish it apart from the parent?
+
+**Then:** split, and the agent does it with ordinary writes: a Child is created under the parent, the open actions move to it, the log entries stay where they are, and one `decision` entry on the parent records the split. Don't, and nothing is written: the line is a fact, not a request, and it goes once those actions are done.
+
+### 3. Decision or lesson?
+
+**Question:** something was settled. Where does it live?
+
+**Test:** is it still true with this entity gone, no slug, path or "we chose" needed? If not, it is a **Decision**; if so, a lesson.
+
+**Then:** a decision is one `decision` entry on the log of the entity that owns the work (or an entry pointing at the repo's own record). A lesson is a knowledge note, related to where it came from. One fact, one place: a knowledge note that only repeats a decision is the Health pass's "restated decision".
+
+### 4. Retire or delete?
+
+**Question:** something in the vault is no longer wanted.
+
+**Test:** is it an entity? Then it is retired. A knowledge or session note can be deleted.
+
+**Then:** retiring sets `--status done`: the entity stays, readable and linked, and leaves the live views unless a Child of it is not yet done. Deleting removes the note in one commit, together with the back-edges it owns (the notes its own `related` names that name it back); any other entity or knowledge note naming it as `parent` or `related` refuses the delete until that link goes. Every write is a git commit, so either can be undone.
+
+### 5. What `hafez health` lists
+
+`hafez health` is the **Health pass**: it reads the vault and lists what placement would change, applying nothing. Run it, or ask the agent to check the vault; a sample of its output is [`health.md`](tests/fixtures/surfaces/health.md).
+
+Its six groups take three kinds of answer. **One-way edges** (a `related` kept on one end only) and **unlinked mentions** (a `[[slug]]` with no edge either way) are mechanical: each comes with the `link` line that adds the edge the vault already implies, so one yes can cover the group. **Workstreams** are question 2, one entity at a time. **Leakage** (a parent's, or a related entity's, log naming an entity since that entity was created: was that its work?), **restated decisions** (question 3) and **recurring names** (a name that keeps coming back in one entity's log and actions) are judged one by one: nothing is proposed for them.
 
 ## CLI overview
 
@@ -212,8 +257,10 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez batch [--dry-run] [--data '<json>' \| --file payload.json]` | JSON ops (stdin, `--data` or `--file`) → atomic multi-op, single git commit, rollback on failure; dry-run runs the same validation as apply and reports derived slugs |
 | `hafez stats` | Vault summary: counts, stale items, recents |
 | `hafez changelog --since 7.days.ago` | Git-derived change history |
+| `hafez graph [slug] [--port N] [--no-open]` | Interactive, live graph of the vault in the browser (served on 127.0.0.1); a slug opens it focused on that note; `--json [--layers tag,domain,session]` prints `{nodes, edges}` |
 | `hafez sync` | Pull remote, push local commits (semantic merge on conflicts) |
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
+| `hafez health` | What placement would change: unsplit workstreams, recurring names, leakage, one-way `related` edges and unlinked `[[slug]]` mentions (each with its `hafez link` line), restated decisions; applies nothing |
 | `hafez onboard` | Setup status, then the script your agent follows: Mode, install, permissions, seeding |
 | `hafez onboard --install --mode <always-on\|invoke-only>` / `--remove` | Write (or remove) the two skills and, always-on, the marked Block in the harness's instructions file |
 | `hafez onboard --cloud --vault-repo <owner>/<repo>` | Print the setup script for Claude Code cloud sessions |

package/dist/apply.d.ts

@@ -26,6 +26,18 @@ export interface ApplyContext {
 export declare function validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields, subtype?: KnowledgeSubtype): void;
 export declare function buildEntityFrontmatter(name: string, ef: CreateEntityFields, existsFn: (slug: string) => boolean): Record<string, any>;
 export declare function buildKnowledgeFrontmatter(name: string, kf: CreateKnowledgeFields, existsFn: (slug: string) => boolean): Record<string, any>;
+/** The mirror file an edge op touched: what the arm appends to its
+ * filesWritten and indexUpserts. */
+export interface EdgeTouch {
+    file: string;
+    upsert: {
+        slug: string;
+        kind: VaultKind;
+    };
+}
+/** Drop `a` from `b`'s related when the edge is same-kind. Exported for the
+ * delete arm (#243) as well. */
+export declare function dropBackEdge(ctx: ApplyContext, a: string, aKind: VaultKind, b: string): EdgeTouch | null;
 /** The single apply path for every mutation. Writes vault files but never
  * touches git or SQLite: the Spine commits [...filesWritten, ...filesDeleted]
  * under commitMessage (single ops) or one composed batch message, then runs

package/dist/apply.js

@@ -369,6 +369,42 @@ function withMechanisedLog(kind, fields) {
         },
     };
 }
+function mirrorEdge(ctx, a, aKind, b, mode) {
+    if (a === b)
+        return null;
+    const bPath = findVaultFile(ctx.vaultPath, b);
+    if (!bPath || kindFromPath(bPath) !== aKind)
+        return null;
+    const parsed = parseFilePath(bPath);
+    const fm = parsed.frontmatter;
+    const related = fm.related ?? [];
+    if (mode === 'write' ? related.includes(a) : !related.includes(a))
+        return null;
+    ctx.captureOriginal(bPath);
+    if (mode === 'write')
+        fm.related = [...related, a];
+    else {
+        fm.related = related.filter(r => r !== a);
+        if (fm.related.length === 0)
+            delete fm.related;
+    }
+    const body = documentForFile(parsed).syncRelatedSection(parsed.body, fm);
+    writeFileSync(bPath, serializeFile(fm, body));
+    return { file: vaultRel(ctx.vaultPath, bPath), upsert: { slug: b, kind: aKind } };
+}
+/** Write `a` into `b`'s related when the edge is same-kind. */
+function writeBackEdge(ctx, a, aKind, b) {
+    return mirrorEdge(ctx, a, aKind, b, 'write');
+}
+/** Write `a` into every same-kind target's related. */
+function backEdges(ctx, a, aKind, targets) {
+    return targets.flatMap(b => writeBackEdge(ctx, a, aKind, b) ?? []);
+}
+/** Drop `a` from `b`'s related when the edge is same-kind. Exported for the
+ * delete arm (#243) as well. */
+export function dropBackEdge(ctx, a, aKind, b) {
+    return mirrorEdge(ctx, a, aKind, b, 'drop');
+}
 // --- The arms ---
 function applyUpdate(op, ctx) {
     const { vaultPath } = ctx;
@@ -379,6 +415,9 @@ function applyUpdate(op, ctx) {
     const doc = documentForFile(parsedFile);
     let fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    // The related list before the fields replace it: the diff against the new
+    // one is what the edge writer and dropper mirror on the targets.
+    const relatedBefore = fm.related ?? [];
     const applied = applyUpdateFields(doc, fm, body, withMechanisedLog(kind, op.fields));
     fm = applied.fm;
     body = applied.body;
@@ -400,19 +439,30 @@ function applyUpdate(op, ctx) {
     }
     body = doc.syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = [];
+    if (op.fields.related !== undefined) {
+        const relatedAfter = fm.related ?? [];
+        touches.push(...backEdges(ctx, op.slug, kind, relatedAfter.filter(r => !relatedBefore.includes(r))));
+        for (const r of relatedBefore.filter(r => !relatedAfter.includes(r))) {
+            const t = dropBackEdge(ctx, op.slug, kind, r);
+            if (t)
+                touches.push(t);
+        }
+    }
     // Only the files THIS update wrote. Keying off the archive file merely
     // existing swept any external hand-edit sitting in entities/archive/
     // into an unrelated commit.
     const files = [vaultRel(vaultPath, filePath)];
     if (wroteArchive)
         files.push(vaultRel(vaultPath, archivePath));
+    files.push(...touches.map(t => t.file));
     return {
         filesWritten: files,
         filesDeleted: [],
         result: { op: 'update', slug: op.slug, status: 'ok' },
         commitMessage: `update: ${op.slug}`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind }],
+        indexUpserts: [{ slug: op.slug, kind }, ...touches.map(t => t.upsert)],
         updateResult: applied.updateResult,
     };
 }
@@ -432,13 +482,14 @@ function applyCreateEntity(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
     body = documentFor({ kind: 'entity' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = backEdges(ctx, slug, 'entity', fm.related ?? []);
     return {
-        filesWritten: [vaultRel(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...touches.map(t => t.file)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [{ slug, kind: 'entity' }],
+        indexUpserts: [{ slug, kind: 'entity' }, ...touches.map(t => t.upsert)],
     };
 }
 function applyCreateKnowledge(op, ctx) {
@@ -454,13 +505,14 @@ function applyCreateKnowledge(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
     body = documentFor({ kind: 'knowledge' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
+    const touches = backEdges(ctx, slug, 'knowledge', fm.related ?? []);
     return {
-        filesWritten: [vaultRel(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...touches.map(t => t.file)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [{ slug, kind: 'knowledge' }],
+        indexUpserts: [{ slug, kind: 'knowledge' }, ...touches.map(t => t.upsert)],
     };
 }
 function applyCreateSession(op, ctx) {
@@ -480,14 +532,14 @@ function applyCreateSession(op, ctx) {
         appeared(slug);
     ctx.captureOriginal(filePath);
     const fm = { name: op.name, created: today() };
-    const kf = (op.fields ?? {});
+    const kf = op.fields ?? {};
     if (kf['session-date'])
         fm['session-date'] = kf['session-date'];
     if (kf.related?.length)
         fm.related = kf.related;
     // Session sections come from contracts.SESSION_SECTIONS — the same list
     // Document splits on, so the written body and the structural set agree.
-    let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis });
+    let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis, decisions: kf.decisions, entities_touched: kf.entities_touched });
     sessionBody = documentFor({ kind: 'session' }).syncRelatedSection(sessionBody, fm);
     writeFileSync(filePath, serializeFile(fm, sessionBody));
     return {
@@ -531,6 +583,8 @@ function applyLink(op, ctx) {
     const parsedFile = parseFilePath(filePath);
     const fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    const kind = kindFromPath(filePath);
+    let touch = null;
     if (op.relation === 'parent') {
         fm.parent = op.target;
     }
@@ -539,16 +593,17 @@ function applyLink(op, ctx) {
         if (!related.includes(op.target))
             related.push(op.target);
         fm.related = related;
+        touch = writeBackEdge(ctx, op.slug, kind, op.target);
     }
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [vaultRel(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...(touch ? [touch.file] : [])],
         filesDeleted: [],
         result: { op: 'link', slug: op.slug, status: 'ok' },
         commitMessage: `link: ${op.slug} → ${op.target} (${op.relation})`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
+        indexUpserts: [{ slug: op.slug, kind }, ...(touch ? [touch.upsert] : [])],
     };
 }
 function applyUnlink(op, ctx) {
@@ -558,23 +613,30 @@ function applyUnlink(op, ctx) {
     const parsedFile = parseFilePath(filePath);
     const fm = parsedFile.frontmatter;
     let body = parsedFile.body;
+    const kind = kindFromPath(filePath);
+    let touch = null;
     if (op.relation === 'parent' && fm.parent === op.target) {
         delete fm.parent;
     }
-    else if (op.relation === 'related' && fm.related) {
-        fm.related = fm.related.filter((r) => r !== op.target);
-        if (fm.related.length === 0)
-            delete fm.related;
+    else if (op.relation === 'related') {
+        if (fm.related) {
+            fm.related = fm.related.filter((r) => r !== op.target);
+            if (fm.related.length === 0)
+                delete fm.related;
+        }
+        // The target's end goes too, even when this file never carried the edge
+        // (a legacy one-way edge).
+        touch = dropBackEdge(ctx, op.slug, kind, op.target);
     }
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [vaultRel(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath), ...(touch ? [touch.file] : [])],
         filesDeleted: [],
         result: { op: 'unlink', slug: op.slug, status: 'ok' },
         commitMessage: `unlink: ${op.slug} ✕ ${op.target} (${op.relation})`,
         indexRemovals: [],
-        indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
+        indexUpserts: [{ slug: op.slug, kind }, ...(touch ? [touch.upsert] : [])],
     };
 }
 function applyPromote(op, ctx) {
@@ -681,14 +743,17 @@ function applyDelete(op, ctx) {
         vanished(op.slug);
     // The snapshot is the rollback: a commit-stage failure writes it back.
     ctx.captureOriginal(filePath);
+    // The other end of every same-kind edge the note owns goes with it (#243).
+    const own = kind === 'knowledge' ? parseFilePath(filePath).frontmatter.related ?? [] : [];
     unlinkSync(filePath);
+    const touches = own.flatMap(r => dropBackEdge(ctx, op.slug, 'knowledge', r) ?? []);
     return {
-        filesWritten: [],
+        filesWritten: touches.map(t => t.file),
         filesDeleted: [vaultRel(vaultPath, filePath)],
         result: { op: 'delete', slug: op.slug, status: 'ok' },
         commitMessage: `delete: ${op.slug} (${kind})`,
         indexRemovals: [op.slug],
-        indexUpserts: [],
+        indexUpserts: touches.map(t => t.upsert),
         deletedKind: kind,
     };
 }

package/dist/batch-ops.d.ts

@@ -34,12 +34,12 @@ export declare const UpdateFieldsSchema: z.ZodObject<{
     parent: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     confidence: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     add_evidence: z.ZodOptional<z.ZodString>;
@@ -52,10 +52,10 @@ export declare const CreateEntityFieldsSchema: z.ZodObject<{
     purpose: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     resource: z.ZodOptional<z.ZodString>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     parent: z.ZodOptional<z.ZodString>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     brief: z.ZodOptional<z.ZodString>;
     add_action: z.ZodOptional<z.ZodString>;
     add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -73,16 +73,18 @@ export declare const CreateKnowledgeFieldsSchema: z.ZodObject<{
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-    tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+    tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     'session-date': z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const CreateSessionFieldsSchema: z.ZodObject<{
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
-    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+    related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
     'session-date': z.ZodOptional<z.ZodString>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entities_touched: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
 }, z.core.$strict>;
 /** What `digest` may put in a session-create op — typechecked against the
  * schema so the two can never silently diverge again. */
@@ -119,12 +121,12 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         parent: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+        domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         confidence: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
         }>>;
-        tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-        related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+        tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+        related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         synthesis: z.ZodOptional<z.ZodString>;
         insight: z.ZodOptional<z.ZodString>;
         add_evidence: z.ZodOptional<z.ZodString>;
@@ -290,12 +292,12 @@ declare const OP_SPEC_ROWS: readonly [{
             parent: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             confidence: z.ZodOptional<z.ZodEnum<{
                 [x: string]: string;
             }>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             add_evidence: z.ZodOptional<z.ZodString>;
@@ -326,10 +328,10 @@ declare const OP_SPEC_ROWS: readonly [{
             purpose: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
             resource: z.ZodOptional<z.ZodString>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             parent: z.ZodOptional<z.ZodString>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             brief: z.ZodOptional<z.ZodString>;
             add_action: z.ZodOptional<z.ZodString>;
             add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -367,9 +369,9 @@ declare const OP_SPEC_ROWS: readonly [{
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
-            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
-            tags: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            domain: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
+            tags: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             'session-date': z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -395,11 +397,13 @@ declare const OP_SPEC_ROWS: readonly [{
         fields: z.ZodOptional<z.ZodObject<{
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
-            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
+            related: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
             'session-date': z.ZodOptional<z.ZodString>;
+            decisions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            entities_touched: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-    readonly description: "Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).";
+    readonly description: "Create a new session note linked to an entity. `synthesis` writes Summary, `decisions` one bullet each under Decisions, `entities_touched` one `[[slug]]` bullet each under Entities Touched. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).";
     readonly exampleInclude: readonly ["synthesis"];
     readonly check: (op: Extract<BatchOperation, {
         op: "create";
@@ -445,7 +449,7 @@ declare const OP_SPEC_ROWS: readonly [{
             related: "related";
         }>;
     }, z.core.$strict>;
-    readonly description: "Add a parent or related link between two entities.";
+    readonly description: "Add a parent or related link. A same-kind related link (entity↔entity, knowledge↔knowledge) is written on both files; a related naming the entity's parent or a child is rejected (parent subsumes related).";
     readonly exampleInclude: readonly [];
     readonly check: (op: Extract<BatchOperation, {
         op: "link";
@@ -466,7 +470,7 @@ declare const OP_SPEC_ROWS: readonly [{
             related: "related";
         }>;
     }, z.core.$strict>;
-    readonly description: "Remove a parent or related link between two entities.";
+    readonly description: "Remove a parent or related link. A same-kind related link is dropped from both files, a legacy one-way edge from whichever file carries it.";
     readonly exampleInclude: readonly [];
     readonly check: (op: Extract<BatchOperation, {
         op: "unlink";
@@ -503,7 +507,7 @@ declare const OP_SPEC_ROWS: readonly [{
         op: z.ZodLiteral<"delete">;
         slug: z.ZodString;
     }, z.core.$strict>;
-    readonly description: "Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. Rejected while another entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.";
+    readonly description: "Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. The back-edges the note owns (a knowledge note in its own related that names it back) are dropped with it, in the same commit. Rejected while any other entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.";
     readonly exampleInclude: readonly [];
     readonly addressesSessions: true;
     readonly check: (op: Extract<BatchOperation, {

package/dist/batch-ops.js

@@ -101,6 +101,9 @@ export const CreateSessionFieldsSchema = z.object({
     insight: nonEmptyText.optional(),
     related: stringList.optional(),
     'session-date': z.string().optional(),
+    // Decisions are prose: a list only, never a comma string split apart.
+    decisions: z.array(nonEmptyText).optional(),
+    entities_touched: stringList.optional(),
 }).strict();
 const CreateEntityBranch = z.object({
     op: z.literal('create'),
@@ -311,6 +314,48 @@ function parentCycleError(slug, parent, ctx) {
     const cycle = parentCycle(slug, parent, s => ctx.linksOf(s).parent);
     return cycle ? `Parent '${parent}' would make a cycle: ${cycle.join(' → ')}` : null;
 }
+/** An entity and its own parent or child are never `related` (ADR 0002):
+ * `parent` subsumes it. The errors for the links `slug` would carry after
+ * the op — the parent named in its related, a related whose parent is
+ * `slug`, or a parent whose related names `slug` (a legacy one-way edge) —
+ * against the batch so far. */
+function parentSubsumesErrors(slug, links, ctx) {
+    const errors = [];
+    for (const r of links.related ?? []) {
+        if (r === links.parent)
+            errors.push(`'${r}' is the parent of '${slug}' — parent subsumes related`);
+        else if (ctx.existsAnywhere(r) && ctx.linksOf(r).parent === slug)
+            errors.push(`'${r}' is a child of '${slug}' — parent subsumes related`);
+    }
+    const p = links.parent;
+    if (p && ctx.existsAnywhere(p) && ctx.linksOf(p).related?.includes(slug))
+        errors.push(`'${p}' names '${slug}' in its related — parent subsumes related`);
+    return errors;
+}
+/** Record what the edge writer and dropper will do to the targets: a
+ * same-kind `related` edge has two ends, so after `slug`'s related changes
+ * from `before` to `after`, every added same-kind target carries `slug` and
+ * every dropped one loses it. Cross-kind and unknown targets are left as
+ * they are, like the files. */
+function simulateBackEdges(slug, before, after, ctx) {
+    const kind = ctx.resolve(slug)?.kind;
+    const was = before ?? [];
+    const now = after ?? [];
+    for (const r of [...now.filter(r => !was.includes(r)), ...was.filter(r => !now.includes(r))]) {
+        if (r === slug || !kind || !ctx.existsAnywhere(r) || ctx.resolve(r)?.kind !== kind)
+            continue;
+        const links = ctx.linksOf(r);
+        const rest = (links.related ?? []).filter(x => x !== slug);
+        const related = now.includes(r) ? [...rest, slug] : rest;
+        ctx.simulateLinks(r, { ...links, related: related.length > 0 ? related : undefined });
+    }
+}
+/** The link fields after an op, simulated for `slug` and mirrored on the
+ * targets its related gained or lost. */
+function simulateLinkChange(slug, before, after, ctx) {
+    ctx.simulateLinks(slug, after);
+    simulateBackEdges(slug, before.related, after.related, ctx);
+}
 // `as const satisfies` rather than a `: OpSpec[]` annotation: it keeps each
 // row's `name` a literal, which is what OpSpecName (and through it the Apply
 // table's key type) is derived from. OP_SPECS below re-exports the rows under
@@ -383,8 +428,12 @@ const OP_SPEC_ROWS = [
             }
             if (target) {
                 const links = linkFieldsOf(op.fields);
-                if (links)
-                    ctx.simulateLinks(op.slug, { ...ctx.linksOf(op.slug), ...links });
+                if (links) {
+                    const before = ctx.linksOf(op.slug);
+                    const after = { ...before, ...links };
+                    errors.push(...parentSubsumesErrors(op.slug, after, ctx));
+                    simulateLinkChange(op.slug, before, after, ctx);
+                }
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -400,8 +449,11 @@ const OP_SPEC_ROWS = [
             const errors = [];
             const slug = slugify(op.name);
             const primaryCode = claimNew(ctx, errors, slug, { kind: 'entity', type: op.fields.type }, () => ctx.buildEntityFrontmatter(op.name, op.fields));
-            if (!primaryCode)
-                ctx.simulateLinks(slug, { parent: op.fields.parent, related: op.fields.related });
+            if (!primaryCode) {
+                const links = { parent: op.fields.parent, related: op.fields.related };
+                errors.push(...parentSubsumesErrors(slug, links, ctx));
+                simulateLinkChange(slug, {}, links, ctx);
+            }
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -417,7 +469,7 @@ const OP_SPEC_ROWS = [
             const slug = slugify(op.name);
             const primaryCode = claimNew(ctx, errors, slug, { kind: 'knowledge', type: 'knowledge', subtype: op.fields?.subtype }, () => ctx.buildKnowledgeFrontmatter(op.name, (op.fields || {})));
             if (!primaryCode)
-                ctx.simulateLinks(slug, { related: op.fields?.related });
+                simulateLinkChange(slug, {}, { related: op.fields?.related }, ctx);
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -426,7 +478,7 @@ const OP_SPEC_ROWS = [
         op: 'create',
         kind: 'session',
         schema: CreateSessionBranch,
-        description: 'Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).',
+        description: 'Create a new session note linked to an entity. `synthesis` writes Summary, `decisions` one bullet each under Decisions, `entities_touched` one `[[slug]]` bullet each under Entities Touched. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).',
         exampleInclude: ['synthesis'],
         check(op, ctx) {
             const slug = slugify(op.name);
@@ -454,7 +506,7 @@ const OP_SPEC_ROWS = [
         name: 'link',
         op: 'link',
         schema: LinkBranch,
-        description: 'Add a parent or related link between two entities.',
+        description: 'Add a parent or related link. A same-kind related link (entity↔entity, knowledge↔knowledge) is written on both files; a related naming the entity\'s parent or a child is rejected (parent subsumes related).',
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
@@ -472,9 +524,11 @@ const OP_SPEC_ROWS = [
             }
             if (!primaryCode) {
                 const links = ctx.linksOf(op.slug);
-                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                const after = op.relation === 'parent'
                     ? { ...links, parent: op.target }
-                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] });
+                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] };
+                errors.push(...parentSubsumesErrors(op.slug, after, ctx));
+                simulateLinkChange(op.slug, links, after, ctx);
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -483,7 +537,7 @@ const OP_SPEC_ROWS = [
         name: 'unlink',
         op: 'unlink',
         schema: UnlinkBranch,
-        description: 'Remove a parent or related link between two entities.',
+        description: 'Remove a parent or related link. A same-kind related link is dropped from both files, a legacy one-way edge from whichever file carries it.',
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
@@ -494,9 +548,13 @@ const OP_SPEC_ROWS = [
             }
             else {
                 const links = ctx.linksOf(op.slug);
-                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                simulateLinkChange(op.slug, links, op.relation === 'parent'
                     ? { ...links, parent: links.parent === op.target ? undefined : links.parent }
-                    : { ...links, related: links.related?.filter(r => r !== op.target) });
+                    : { ...links, related: links.related?.filter(r => r !== op.target) }, ctx);
+                // A legacy one-way edge may live on the target alone: the dropper
+                // takes it there too.
+                if (op.relation === 'related' && !links.related?.includes(op.target))
+                    simulateBackEdges(op.slug, [op.target], [], ctx);
             }
             return { slug: op.slug, errors, primaryCode };
         },
@@ -540,7 +598,7 @@ const OP_SPEC_ROWS = [
         name: 'delete',
         op: 'delete',
         schema: DeleteBranch,
-        description: 'Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. Rejected while another entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.',
+        description: 'Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. The back-edges the note owns (a knowledge note in its own related that names it back) are dropped with it, in the same commit. Rejected while any other entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.',
         exampleInclude: [],
         addressesSessions: true,
         check(op, ctx) {
@@ -560,12 +618,19 @@ const OP_SPEC_ROWS = [
             }
             else {
                 // Only knowledge can be linked to: a parent/related slug must name an
-                // entity or knowledge note, never a session.
-                const referrers = target ? ctx.referrers(op.slug) : [];
+                // entity or knowledge note, never a session. A same-kind back-edge
+                // the note owns — a note in its own related that names it back — is
+                // the other end of its edge, dropped with it (#243), not a blocker.
+                const own = target ? ctx.linksOf(op.slug).related ?? [] : [];
+                const referrers = target
+                    ? ctx.referrers(op.slug).filter(r => !(own.includes(r) && ctx.resolve(r)?.kind === target.kind))
+                    : [];
                 if (referrers.length > 0) {
                     errors.push(`'${op.slug}' is still linked from ${referrers.join(', ')} (parent/related) — unlink or re-point those first; an earlier op in the same batch counts`);
                 }
                 else {
+                    if (target)
+                        simulateBackEdges(op.slug, own, [], ctx);
                     ctx.simulateDelete(op.slug, target ? 'knowledge' : 'session');
                 }
             }