hafez 1.4.0 → 2.1.0

package/dist/batch-ops.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, KnowledgeSubtype, SessionLogEntry, UpdateFields } from './types.js';
+import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, DeletableKind, KnowledgeSubtype, SessionLogEntry, UpdateFields } from './types.js';
+export declare const splitCommaList: (value: string) => string[];
 export declare const SessionLogSchema: z.ZodObject<{
     type: z.ZodEnum<{
         [x: string]: string;
@@ -21,20 +22,24 @@ export declare const UpdateFieldsSchema: z.ZodObject<{
         body: z.ZodOptional<z.ZodString>;
         agent: z.ZodString;
     }, z.core.$strict>>;
+    agent: z.ZodOptional<z.ZodString>;
     brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     add_action: z.ZodOptional<z.ZodString>;
     add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     complete_action: z.ZodOptional<z.ZodString>;
+    complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     remove_action: z.ZodOptional<z.ZodString>;
+    remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     clear_actions: z.ZodOptional<z.ZodBoolean>;
+    parent: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
     confidence: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    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>>>;
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     add_evidence: z.ZodOptional<z.ZodString>;
@@ -47,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.ZodArray<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
     parent: z.ZodOptional<z.ZodString>;
-    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    tags: z.ZodOptional<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>>>;
     brief: z.ZodOptional<z.ZodString>;
     add_action: z.ZodOptional<z.ZodString>;
     add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -62,23 +67,30 @@ export declare const CreateKnowledgeFieldsSchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    tags: z.ZodOptional<z.ZodArray<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>>>;
     '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.ZodArray<z.ZodString>>;
+    related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
     'session-date': z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** What `digest` may put in a session-create op — typechecked against the
  * schema so the two can never silently diverge again. */
 export type CreateSessionFieldsInput = z.infer<typeof CreateSessionFieldsSchema>;
+/** The fields an update's mechanised session log entry names — empty when
+ * the update earns none. Shared by the update check (which rejects an
+ * `agent` with no entry to name) and the Apply update arm (which writes it). */
+export declare function loggedFields(fields: UpdateFields): (keyof UpdateFields)[];
 export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"update">;
     slug: z.ZodString;
@@ -95,20 +107,24 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             body: z.ZodOptional<z.ZodString>;
             agent: z.ZodString;
         }, z.core.$strict>>;
+        agent: z.ZodOptional<z.ZodString>;
         brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         add_action: z.ZodOptional<z.ZodString>;
         add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         complete_action: z.ZodOptional<z.ZodString>;
+        complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         remove_action: z.ZodOptional<z.ZodString>;
+        remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clear_actions: z.ZodOptional<z.ZodBoolean>;
+        parent: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
         confidence: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
         }>>;
-        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        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>>>;
         synthesis: z.ZodOptional<z.ZodString>;
         insight: z.ZodOptional<z.ZodString>;
         add_evidence: z.ZodOptional<z.ZodString>;
@@ -144,6 +160,9 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         project: "project";
         knowledge: "knowledge";
     }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"delete">;
+    slug: z.ZodString;
 }, z.core.$strict>], "op">;
 /** Canonicalize an operation's declared aliases.
  *
@@ -161,6 +180,12 @@ export interface ResolvedTarget {
     type: string;
     subtype?: KnowledgeSubtype;
 }
+/** The frontmatter links `validate` checks: what makes one file a referrer
+ * of another. */
+export interface FileLinks {
+    parent?: string;
+    related?: string[];
+}
 /** Vault context handed to each spec's semantic check by validateBatchCore.
  * Simulation-aware: creates earlier in the batch count as existing. */
 export interface OpCheckContext {
@@ -169,6 +194,15 @@ export interface OpCheckContext {
     sessionExists(slug: string): boolean;
     simulate(slug: string, info: ResolvedTarget): void;
     simulateSession(slug: string): void;
+    /** The parent/related a file carries after the earlier ops in the batch. */
+    linksOf(slug: string): FileLinks;
+    /** Record the parent/related a file will carry after this op. Every op
+     * that changes a link calls it, so `referrers` sees the batch so far. */
+    simulateLinks(slug: string, links: FileLinks): void;
+    /** Entities and knowledge notes whose parent or related names `slug`,
+     * after the earlier ops in the batch. A file never refers to itself. */
+    referrers(slug: string): string[];
+    simulateDelete(slug: string, kind: DeletableKind): void;
     /** Kind gating is subtype-aware for knowledge: a plan carries `status`,
      * an insight does not (see contracts.SUBTYPE_STATUSES). */
     validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields, subtype?: KnowledgeSubtype): void;
@@ -206,6 +240,11 @@ export declare function batchInvalidHeader(invalidCount: number, total: number):
  * dry-run (spec warning) and apply (BatchResult.warning) report it with this
  * same sentence so the two can never drift. */
 export declare function duplicateSessionWarning(slug: string): string;
+/** The parent chain `slug → parent → … → slug` that giving `slug` this
+ * parent closes, or null when the chain ends or loops without `slug`.
+ * Shared by the Op Spec checks (against the simulated batch) and
+ * `validateVault` (against the files). */
+export declare function parentCycle(slug: string, parent: string | undefined, parentOf: (s: string) => string | undefined): string[] | null;
 export interface OpSpec {
     /** Stable identifier used by `schema <name>` and the op catalog. */
     name: string;
@@ -215,6 +254,9 @@ export interface OpSpec {
     description: string;
     /** Optional fields force-included in the generated example payload. */
     exampleInclude: readonly string[];
+    /** The op's `slug` may name a session note as well as an entity or
+     * knowledge note. */
+    addressesSessions?: boolean;
     check(op: any, ctx: OpCheckContext): OpCheckResult;
 }
 declare const OP_SPEC_ROWS: readonly [{
@@ -236,27 +278,31 @@ declare const OP_SPEC_ROWS: readonly [{
                 body: z.ZodOptional<z.ZodString>;
                 agent: z.ZodString;
             }, z.core.$strict>>;
+            agent: z.ZodOptional<z.ZodString>;
             brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             add_action: z.ZodOptional<z.ZodString>;
             add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             complete_action: z.ZodOptional<z.ZodString>;
+            complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             remove_action: z.ZodOptional<z.ZodString>;
+            remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             clear_actions: z.ZodOptional<z.ZodBoolean>;
+            parent: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
             confidence: z.ZodOptional<z.ZodEnum<{
                 [x: string]: string;
             }>>;
-            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            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>>>;
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             add_evidence: z.ZodOptional<z.ZodString>;
             add_source: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>;
-    readonly description: "Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.";
+    readonly description: "Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action(s)` → `complete_action(s)` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity's archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.";
     readonly exampleInclude: readonly ["status"];
     readonly check: (op: Extract<BatchOperation, {
         op: "update";
@@ -280,10 +326,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.ZodArray<z.ZodString>>;
+            domain: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
             parent: z.ZodOptional<z.ZodString>;
-            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            tags: z.ZodOptional<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>>>;
             brief: z.ZodOptional<z.ZodString>;
             add_action: z.ZodOptional<z.ZodString>;
             add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -315,16 +361,19 @@ declare const OP_SPEC_ROWS: readonly [{
             status: z.ZodOptional<z.ZodEnum<{
                 [x: string]: string;
             }>>;
+            confidence: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
             synthesis: z.ZodOptional<z.ZodString>;
             insight: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
-            domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            tags: z.ZodOptional<z.ZodArray<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>>>;
             'session-date': z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
-    readonly description: "Create a new knowledge note (insight / plan subtype). `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.";
+    readonly description: "Create a new knowledge note (insight / plan subtype). `confidence` defaults to observation. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.";
     readonly exampleInclude: readonly ["subtype", "synthesis"];
     readonly check: (op: Extract<BatchOperation, {
         op: "create";
@@ -346,7 +395,7 @@ 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.ZodArray<z.ZodString>>;
+            related: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
             'session-date': z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
@@ -447,6 +496,23 @@ declare const OP_SPEC_ROWS: readonly [{
         errors: string[];
         primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
     };
+}, {
+    readonly name: "delete";
+    readonly op: "delete";
+    readonly schema: z.ZodObject<{
+        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 exampleInclude: readonly [];
+    readonly addressesSessions: true;
+    readonly check: (op: Extract<BatchOperation, {
+        op: "delete";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
 }];
 /** Every op the table defines. The Apply table (src/apply.ts) is keyed by this
  * union, so a spec row added here without an apply arm fails to build. */
@@ -465,6 +531,9 @@ export declare function validOpNames(): string[];
  * NOT_FOUND precedence on shape failure in validateBatchCore) without a
  * hand-kept list. */
 export declare function slugBearingOpNames(): string[];
+/** Slug-bearing ops whose slug may name a session note — a missing entity
+ * or knowledge note alone is not NOT_FOUND for them. */
+export declare function sessionAddressingOpNames(): string[];
 /** Create kinds for error text — derived from the table. */
 export declare function validCreateKinds(): string[];
 export {};

package/dist/batch-ops.js

@@ -17,12 +17,6 @@ import { HafezError } from './types.js';
 // Every z.object(...) is .strict() — unknown keys become `unrecognized_keys` issues
 // (not silently dropped), which is load-bearing for the error-formatter's did-you-mean
 // hints and for catching typos like `{"kind": "parent"}` on a link op.
-export const SessionLogSchema = z.object({
-    type: z.enum([...SESSION_LOG_TYPES]),
-    summary: z.string(),
-    body: z.string().optional(),
-    agent: z.string(),
-}).strict();
 // Body-section text must have text after trimming. An empty or whitespace-only
 // value (an agent expanding an unset variable) used to sail through the shape —
 // on the action/evidence fields it was dropped by a truthiness guard in apply
@@ -37,23 +31,39 @@ export const SessionLogSchema = z.object({
 // CLI maps `--brief ""` to it. Trimming also keeps accidental padding out of
 // stored text.
 const nonEmptyText = z.string().trim().min(1, 'must contain text — an empty value is rejected, never silently dropped');
+// A list field (domain, tags, related) takes a string[] or, like the CLI's
+// list flags (`--domain "a,b"`), one comma string. The split is the one rule
+// for both paths — the CLI's `splitList` calls it — so `"a, b"` is the same
+// two values everywhere (#33).
+export const splitCommaList = (value) => value.split(',').map(s => s.trim()).filter(Boolean);
+const stringList = z.preprocess(v => typeof v === 'string' ? splitCommaList(v) : v, z.array(z.string()));
+export const SessionLogSchema = z.object({
+    type: z.enum([...SESSION_LOG_TYPES]),
+    summary: z.string(),
+    body: nonEmptyText.optional(),
+    agent: z.string(),
+}).strict();
 export const UpdateFieldsSchema = z.object({
     status: z.enum([...ENTITY_STATUSES]).optional(),
     current_state: nonEmptyText.optional(),
     session_log: SessionLogSchema.optional(),
+    agent: nonEmptyText.optional(), // entity-only; names the agent on the added session log entry
     brief: z.string().nullable().optional(),
     add_action: nonEmptyText.optional(),
     add_actions: z.array(nonEmptyText).optional(),
     complete_action: nonEmptyText.optional(),
+    complete_actions: z.array(nonEmptyText).min(1).optional(),
     remove_action: nonEmptyText.optional(),
+    remove_actions: z.array(nonEmptyText).min(1).optional(),
     clear_actions: z.boolean().optional(),
+    parent: z.string().optional(), // entity-only; the slug must exist, no cycle
     // Knowledge metadata
     description: z.string().nullable().optional(),
     resource: z.string().nullable().optional(),
-    domain: z.array(z.string()).optional(),
+    domain: stringList.optional(),
     confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
-    tags: z.array(z.string()).optional(),
-    related: z.array(z.string()).optional(),
+    tags: stringList.optional(),
+    related: stringList.optional(),
     synthesis: nonEmptyText.optional(),
     insight: nonEmptyText.optional(), // alias for synthesis (normalized by normalizeAliases)
     add_evidence: nonEmptyText.optional(),
@@ -64,10 +74,10 @@ export const CreateEntityFieldsSchema = z.object({
     purpose: nonEmptyText.optional(),
     description: z.string().optional(),
     resource: z.string().optional(),
-    domain: z.array(z.string()).optional(),
+    domain: stringList.optional(),
     parent: z.string().optional(),
-    related: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
+    related: stringList.optional(),
+    tags: stringList.optional(),
     brief: nonEmptyText.optional(),
     add_action: nonEmptyText.optional(),
     add_actions: z.array(nonEmptyText).optional(),
@@ -77,18 +87,19 @@ export const CreateKnowledgeFieldsSchema = z.object({
     // Plan-only: insights have no lifecycle, so the semantic check rejects
     // status on any other subtype (the shape only pins the allowed values).
     status: z.enum([...PLAN_STATUSES]).optional(),
+    confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
     synthesis: nonEmptyText.optional(),
     insight: nonEmptyText.optional(),
     description: z.string().optional(),
-    domain: z.array(z.string()).optional(),
-    related: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
+    domain: stringList.optional(),
+    related: stringList.optional(),
+    tags: stringList.optional(),
     'session-date': z.string().optional(),
 }).strict();
 export const CreateSessionFieldsSchema = z.object({
     synthesis: nonEmptyText.optional(),
     insight: nonEmptyText.optional(),
-    related: z.array(z.string()).optional(),
+    related: stringList.optional(),
     'session-date': z.string().optional(),
 }).strict();
 const CreateEntityBranch = z.object({
@@ -109,6 +120,16 @@ const CreateSessionBranch = z.object({
     name: z.string(),
     fields: CreateSessionFieldsSchema.optional(),
 }).strict();
+/** Update fields the mechanised session log neither counts nor names:
+ * ticking a box is not history worth an entry, and `agent` only names it. */
+const UNLOGGED_FIELDS = new Set(['add_action', 'add_actions', 'complete_action', 'complete_actions', 'remove_action', 'remove_actions', 'clear_actions', 'agent']);
+/** The fields an update's mechanised session log entry names — empty when
+ * the update earns none. Shared by the update check (which rejects an
+ * `agent` with no entry to name) and the Apply update arm (which writes it). */
+export function loggedFields(fields) {
+    return Object.keys(fields)
+        .filter(f => fields[f] !== undefined && !UNLOGGED_FIELDS.has(f));
+}
 const UpdateBranch = z.object({
     op: z.literal('update'),
     slug: z.string(),
@@ -136,6 +157,12 @@ const PromoteBranch = z.object({
     slug: z.string(),
     target: z.enum(['entity', 'project', 'knowledge']),
 }).strict();
+// No `kind`: the slug alone says what is being deleted, the same as
+// `hafez delete <slug>`. The check resolves it and rejects an entity.
+const DeleteBranch = z.object({
+    op: z.literal('delete'),
+    slug: z.string(),
+}).strict();
 // Nested discriminated union: outer on `op`, inner on `kind` for create branch.
 // A flat `discriminatedUnion('op', [...])` cannot work because three branches share
 // op=create — Zod requires unique discriminator values per branch and throws at
@@ -154,6 +181,7 @@ export const BatchOperationSchema = z.discriminatedUnion('op', [
     LinkBranch,
     UnlinkBranch,
     PromoteBranch,
+    DeleteBranch,
 ]);
 // --- Alias normalization ---
 // The one place a declared alias (contracts.ts ALIAS_KEYS) becomes its canonical
@@ -251,6 +279,36 @@ function claimNew(ctx, errors, slug, info, build) {
         ctx.simulate(slug, info);
     return taken ? 'SLUG_EXISTS' : undefined;
 }
+/** The link fields an update payload sets, or null when it sets none. */
+function linkFieldsOf(fields) {
+    const links = {};
+    if (fields.parent !== undefined)
+        links.parent = fields.parent;
+    if (fields.related !== undefined)
+        links.related = fields.related;
+    return Object.keys(links).length > 0 ? links : null;
+}
+/** The parent chain `slug → parent → … → slug` that giving `slug` this
+ * parent closes, or null when the chain ends or loops without `slug`.
+ * Shared by the Op Spec checks (against the simulated batch) and
+ * `validateVault` (against the files). */
+export function parentCycle(slug, parent, parentOf) {
+    const path = [slug];
+    const seen = new Set(path);
+    for (let p = parent; p !== undefined; p = parentOf(p)) {
+        path.push(p);
+        if (p === slug)
+            return path;
+        if (seen.has(p))
+            return null;
+        seen.add(p);
+    }
+    return null;
+}
+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;
+}
 // `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
@@ -260,7 +318,7 @@ const OP_SPEC_ROWS = [
         name: 'update',
         op: 'update',
         schema: UpdateBranch,
-        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
+        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action(s)` → `complete_action(s)` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity\'s archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
         exampleInclude: ['status'],
         check(op, ctx) {
             const errors = [];
@@ -278,6 +336,29 @@ const OP_SPEC_ROWS = [
                     pushErr(errors, err);
                 }
             }
+            // Statically contradictory: clear_actions runs first and empties the
+            // list, so any query in the same op would fail at apply time with a
+            // misleading "No matching action". Reject here, where the message can
+            // say why and land beside the batch's other errors. Entity targets
+            // only — on a knowledge note validateKindFields has already rejected
+            // the fields themselves, and a second error about their order is noise.
+            if (target?.kind === 'entity' && op.fields.clear_actions) {
+                const queries = ['remove_action', 'remove_actions', 'complete_action', 'complete_actions'].filter(f => op.fields[f] !== undefined);
+                if (queries.length > 0) {
+                    errors.push(`clear_actions empties the list before ${queries.slice(0, -1).join(', ')}${queries.length > 1 ? ' and ' : ''}${queries.at(-1)} would run — drop the clear or use a separate op`);
+                }
+            }
+            // `agent` names the entry the Spine adds; with nothing added it would be
+            // dropped. Entity targets only — on a knowledge note validateKindFields
+            // has already rejected it as entity-only.
+            if (target?.kind === 'entity' && op.fields.agent !== undefined) {
+                if (op.fields.session_log) {
+                    errors.push('agent names the session log entry added when session_log is absent — with session_log, set session_log.agent instead');
+                }
+                else if (loggedFields(op.fields).length === 0) {
+                    errors.push('agent names the session log entry, and an update of action fields alone writes none — drop agent');
+                }
+            }
             if (op.fields.session_log) {
                 const logErrors = ctx.validateSessionLogEntry(op.fields.session_log);
                 if (logErrors.length > 0)
@@ -289,6 +370,20 @@ const OP_SPEC_ROWS = [
                         errors.push(`Related slug '${r}' does not exist`);
                 }
             }
+            if (op.fields.parent !== undefined) {
+                if (!ctx.existsAnywhere(op.fields.parent))
+                    errors.push(`Parent '${op.fields.parent}' does not exist`);
+                else if (target?.kind === 'entity') {
+                    const cycle = parentCycleError(op.slug, op.fields.parent, ctx);
+                    if (cycle)
+                        errors.push(cycle);
+                }
+            }
+            if (target) {
+                const links = linkFieldsOf(op.fields);
+                if (links)
+                    ctx.simulateLinks(op.slug, { ...ctx.linksOf(op.slug), ...links });
+            }
             return { slug: op.slug, errors, primaryCode };
         },
     },
@@ -303,6 +398,8 @@ 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 });
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -311,12 +408,14 @@ const OP_SPEC_ROWS = [
         op: 'create',
         kind: 'knowledge',
         schema: CreateKnowledgeBranch,
-        description: 'Create a new knowledge note (insight / plan subtype). `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.',
+        description: 'Create a new knowledge note (insight / plan subtype). `confidence` defaults to observation. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.',
         exampleInclude: ['subtype', 'synthesis'],
         check(op, ctx) {
             const errors = [];
             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 });
             return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
@@ -364,6 +463,17 @@ const OP_SPEC_ROWS = [
             }
             if (!ctx.existsAnywhere(op.target))
                 errors.push(`Target '${op.target}' does not exist`);
+            else if (!primaryCode && op.relation === 'parent') {
+                const cycle = parentCycleError(op.slug, op.target, ctx);
+                if (cycle)
+                    errors.push(cycle);
+            }
+            if (!primaryCode) {
+                const links = ctx.linksOf(op.slug);
+                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                    ? { ...links, parent: op.target }
+                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] });
+            }
             return { slug: op.slug, errors, primaryCode };
         },
     },
@@ -380,6 +490,12 @@ const OP_SPEC_ROWS = [
                 errors.push(notFoundError(op.slug));
                 primaryCode = 'NOT_FOUND';
             }
+            else {
+                const links = ctx.linksOf(op.slug);
+                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                    ? { ...links, parent: links.parent === op.target ? undefined : links.parent }
+                    : { ...links, related: links.related?.filter(r => r !== op.target) });
+            }
             return { slug: op.slug, errors, primaryCode };
         },
     },
@@ -406,6 +522,9 @@ const OP_SPEC_ROWS = [
                     }
                     else {
                         ctx.simulate(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
+                        // A promoted knowledge note keeps related but not parent.
+                        if (op.target === 'knowledge')
+                            ctx.simulateLinks(op.slug, { related: ctx.linksOf(op.slug).related });
                     }
                 }
                 catch (err) {
@@ -415,6 +534,42 @@ const OP_SPEC_ROWS = [
             return { slug: op.slug, errors, primaryCode };
         },
     },
+    {
+        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.',
+        exampleInclude: [],
+        addressesSessions: true,
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            const target = ctx.resolve(op.slug);
+            const session = ctx.sessionExists(op.slug);
+            if (target?.kind === 'entity') {
+                errors.push(`'${op.slug}' is an entity (${target.type}) — an entity is never deleted; retire it with \`hafez update ${op.slug} --status done\``);
+            }
+            else if (target && session) {
+                errors.push(`'${op.slug}' is ambiguous — it names both a knowledge note and a session note, and delete will not guess which`);
+            }
+            else if (!target && !session) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            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) : [];
+                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 {
+                    ctx.simulateDelete(op.slug, target ? 'knowledge' : 'session');
+                }
+            }
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
 ];
 export const OP_SPECS = OP_SPEC_ROWS;
 /** Find the spec for a (shape-valid) operation. */
@@ -440,6 +595,11 @@ export function slugBearingOpNames() {
         })
             .map(s => s.op))];
 }
+/** Slug-bearing ops whose slug may name a session note — a missing entity
+ * or knowledge note alone is not NOT_FOUND for them. */
+export function sessionAddressingOpNames() {
+    return OP_SPECS.filter(s => s.addressesSessions).map(s => s.op);
+}
 /** Create kinds for error text — derived from the table. */
 export function validCreateKinds() {
     return OP_SPECS.filter(s => s.op === 'create' && s.kind).map(s => s.kind);