hafez 1.4.0 → 2.0.0

package/README.md

@@ -29,18 +29,15 @@ Set up Hafez, an agent-native knowledge vault (github.com/shrvn-r/hafez):
 3. Create my vault — a git repo with entities/ and knowledge/ directories and an
    initial commit. Suggest ~/vault but ask me where I want it first.
 4. Register it: hafez init --register <vault-path>
-5. If you are Claude Code, install the bundled skill: copy skill/SKILL.md
-   from the installed package ("$(npm root -g)/hafez/skill/SKILL.md") to
-   ~/.claude/skills/hafez/SKILL.md. Any other harness: skip this — step 7
-   covers integration.
-6. Read hafez help --agent, then verify end-to-end: create a test capture,
+5. Read hafez help --agent, then verify end-to-end: create a test capture,
    hafez read it back, and show me hafez stats.
-7. Run hafez onboard and follow what it prints: interview me to seed the
-   vault with my current projects, then help me choose how deeply to
-   integrate Hafez into my agent setup.
+6. Run hafez onboard and follow what it prints: ask me how Hafez should
+   run, install it (the two skills, and the Block in your instructions
+   file), and, if the vault is empty, interview me to seed it with my
+   current projects.
 ```
 
-From then on, just mention your projects by name in any session — the skill
+From then on, just mention your projects by name in any session — the Block
 teaches the agent when to read and write the vault, no commands required.
 
 Upgrading from an earlier name of this tool? Remove the old skill directory
@@ -67,13 +64,9 @@ cd ~/vault && git init && git commit --allow-empty -m "init vault"
 hafez init --register ~/vault           # remember this vault (one-time)
 hafez init                              # show current vault resolution
 
-# Claude Code only (optional): the bundled skill
-mkdir -p ~/.claude/skills/hafez
-cp "$(npm root -g)/hafez/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
-
-# Then, in your agent — any harness: "run hafez onboard and follow it" —
-# guided first run (seed the vault with your current projects, choose an
-# integration level)
+# Then, in Claude Code or Codex: "run hafez onboard and follow it" —
+# guided setup (choose how Hafez runs, install the two skills and the Block,
+# seed an empty vault)
 ```
 
 Prefer installing without the npm registry? The GitHub release tarball is the
@@ -107,14 +100,11 @@ npm install -g hafez@<version> --allow-scripts=better-sqlite3
 #    From the GitHub release tarball instead (npm 12+ needs --allow-remote):
 npm install -g https://github.com/shrvn-r/hafez/releases/download/v<version>/hafez.tgz --allow-scripts=better-sqlite3 --allow-remote=root
 
-# 2. Claude Code only: re-copy the bundled skill. It ships inside the package,
-#    so an upgraded package leaves the installed copy stale.
-mkdir -p ~/.claude/skills/hafez
-cp "$(npm root -g)/hafez/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
-
-#    Under nvm, or for a symlinked dev install, `npm root -g` points at the
-#    wrong tree. Resolve it from the binary you actually run instead:
-cp "$(dirname "$(dirname "$(readlink -f "$(which hafez)")")")/skill/SKILL.md" ~/.claude/skills/hafez/SKILL.md
+# 2. The skills, and the Block if you have one, ship inside the package, so
+#    an upgraded package leaves the installed copies stale. The new binary
+#    has `hafez upgrade`: it checks them by hash and prints the
+#    `hafez onboard --install` line that refreshes them.
+hafez upgrade
 
 # 3. Rebuild the read index. A schema bump invalidates it rather than
 #    rebuilding it, so the first query after an upgrade can answer empty.
@@ -126,8 +116,9 @@ probe your npm — `hafez upgrade` does probe it and prints the exact form your
 npm accepts. Same instruction, two renderings; the extra flags are harmless
 (`npm warn Unknown cli config`, then it proceeds).
 
-Also compare the Hafez block in your global agent instructions against the one
-`hafez upgrade` prints, and reconcile any differences.
+A Hafez section pasted into your instructions file by hand, before the Block
+had markers, is not checked: delete it, then install the Block with
+`hafez onboard`.
 
 Your vault is untouched by an upgrade: the files, the git history, and the
 registered vault path all survive. Only the read index is invalidated.
@@ -158,7 +149,7 @@ hafez query --kind knowledge --domain security
 hafez search "token rotation"
 
 # Record progress
-hafez update auth-refactor --log "progress: JWT flow implemented" --agent claude
+hafez update auth-refactor --log "progress: JWT flow implemented"
 hafez update auth-refactor --complete-action "migration plan"
 ```
 
@@ -196,18 +187,20 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez create <entity\|knowledge> <name> [flags]` | Create a document |
 | `hafez capture <name> [--notes]` | Quick inbox capture |
 | `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
+| `hafez delete <slug>` | Delete a knowledge or session note (entities retire with `--status done`) |
 | `hafez update <slug> [flags]` | Status, brief, actions, session log, synthesis, evidence… |
 | `hafez link / unlink <slug> <target> --relation <parent\|related>` | Manage relationships |
-| `hafez batch [--dry-run] [--file payload.json]` | JSON ops (stdin or `--file`) → atomic multi-op, single git commit, rollback on failure; dry-run runs the same validation as apply and reports derived slugs |
+| `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 sync` | Pull remote, push local commits (semantic merge on conflicts) |
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
-| `hafez onboard` | Agent-directed first run: seeding interview + integration setup |
+| `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 schema [op] [--examples]` | Machine-readable JSON schema for every operation |
 | `hafez export --okf [--out <dir>]` | Read-only OKF v0.1 bundle export |
 
-This is not exhaustive — `hafez help --agent` prints the full, always-current reference. Add `--json` to any command for structured output.
+This is not exhaustive — `hafez --help` lists every command, and `hafez schema <op>` prints the machine-readable shape of any op. Add `--json` to any command for structured output.
 
 ## Library usage
 
@@ -246,9 +239,9 @@ for everything on the [AGENTS.md standard](https://agents.md) (Codex, Cursor,
 Copilot, …). This repo follows the same convention: `AGENTS.md` is canonical
 and `CLAUDE.md` imports it.
 
-- **`hafez onboard`** — an agent-directed first-run guide: a seeding interview for the empty vault, then a choice of integration level (an always-active block for the harness's global instructions file, or invoke-only). Re-running it later is the intended way to seed newly started work — on a set-up vault it's just the interview.
-- **`hafez help --agent`** — a complete API reference designed to be loaded into an agent's context.
-- **Claude Code skill** — an optional adapter for one harness: the package bundles a skill (installed in [Setup](#setup)) covering the full session lifecycle: loading context at session start, vault ops mid-session, and a session-end digest.
+- **`hafez onboard`** — agent-directed setup, run from inside Claude Code or Codex (any other harness: `onboard --install --harness <h>`): where things stand (the vault, and per harness found the Block, skills, hook and allowlist), then the script the agent follows — choose always-on or invoke-only, install, allow the command, optionally add the session-start hook, seed an empty vault, and four lines for the user. Re-running it is reconfigure: it walks only what is not current.
+- **`hafez help --agent`** — the `hafez` skill body, one text from the same source: the reference an agent reads when the skill is not installed.
+- **Two skills, `hafez` and `hafez-save`** — written by `hafez onboard --install` to `~/.claude/skills` and `~/.agents/skills`, so every harness reading either directory gets them: the less common operations and the tool itself, and the session save. The Block, the skills and every sample of command output are rendered from one source and checked byte for byte in CI; the samples are in [`tests/fixtures/surfaces/`](tests/fixtures/surfaces/).
 - **`hafez schema <op> --examples`** — JSON schemas with working examples for every batch operation, so agents can self-correct.
 - **`hafez batch`** — apply a whole session's worth of updates atomically from a single JSON payload. Validation errors report every bad op at once with did-you-mean hints.
 - **Markdown-native output** by default, `--json` everywhere for machine consumption.

package/dist/apply.d.ts

@@ -1,4 +1,4 @@
-import type { BatchOperation, BatchResult, CreateEntityFields, CreateKnowledgeFields, KnowledgeSubtype, UpdateFields } from './types.js';
+import type { BatchOperation, BatchResult, CreateEntityFields, DeletableKind, CreateKnowledgeFields, KnowledgeSubtype, UpdateFields, UpdateResult } from './types.js';
 export interface AppliedOp {
     filesWritten: string[];
     filesDeleted: string[];
@@ -9,7 +9,10 @@ export interface AppliedOp {
         slug: string;
         kind: 'entity' | 'knowledge';
     }>;
-    matchedAction?: string;
+    /** Set by the update arm: the line each Next Actions query matched. */
+    updateResult?: UpdateResult;
+    /** Set by the delete arm: the kind of note it removed. */
+    deletedKind?: DeletableKind;
 }
 /** Everything an apply arm needs from its caller: where the vault is, and how
  * to hand the Spine a pre-write snapshot for rollback. Path resolution, the

package/dist/apply.js

@@ -22,10 +22,11 @@ import { join, relative, dirname } from 'path';
 import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
 import { bodyTemplate, knowledgeBodyTemplate, sessionBodyTemplate } from './templates.js';
-import { formatSessionLogEntry, documentFor, documentForFile } from './document.js';
+import { formatSessionLogEntry, stampAction, documentFor, documentForFile } from './document.js';
 import { sectionsFor, statusesFor, unreachableFields, describeTarget } from './contracts.js';
 import { localDay } from './dates.js';
-import { specFor } from './batch-ops.js';
+import { detectAgent } from './harness.js';
+import { specFor, loggedFields } from './batch-ops.js';
 import { HafezError } from './types.js';
 /** A vault file that validation resolved but is gone at apply time. The vault
  * lock excludes other hafez processes, not external actors (Obsidian, a hand
@@ -49,7 +50,7 @@ function entityPath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, '
 function knowledgePath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, 'knowledge'); }
 function today() { return localDay(); }
 // --- Field policy ---
-const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'resource'];
+const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'agent', 'resource', 'parent'];
 const KNOWLEDGE_ONLY_FIELDS = ['confidence', 'synthesis', 'add_evidence', 'add_source'];
 // An entity-only field is still reachable on a knowledge note when THAT
 // note's contract declares the capability the field needs. The gate asks the
@@ -131,6 +132,11 @@ export function buildEntityFrontmatter(name, ef, existsFn) {
         throw new HafezError('VALIDATION_FAILED', 'Invalid entity frontmatter', errors);
     return fm;
 }
+// Every action add — create, update, batch, digest — lands here, so this is
+// the one place the added-date stamp is written (local day, never twice).
+function addStampedAction(doc, body, action) {
+    return doc.addNextAction(body, stampAction(action, today()));
+}
 // Body-side optional fields (brief, actions) must behave identically in both
 // paths, like buildEntityFrontmatter's.
 function buildEntityBody(ef) {
@@ -139,15 +145,15 @@ function buildEntityBody(ef) {
     if (ef.brief)
         body = doc.setBrief(body, ef.brief);
     if (ef.add_action !== undefined)
-        body = doc.addNextAction(body, ef.add_action);
+        body = addStampedAction(doc, body, ef.add_action);
     for (const action of ef.add_actions ?? [])
-        body = doc.addNextAction(body, action);
+        body = addStampedAction(doc, body, action);
     return body;
 }
 export function buildKnowledgeFrontmatter(name, kf, existsFn) {
     const target = { kind: 'knowledge', subtype: kf.subtype };
     assertFieldsReachable(target, kf);
-    const fm = { name, confidence: 'observation', 'reinforcement-count': 0, created: today() };
+    const fm = { name, confidence: kf.confidence ?? 'observation', 'reinforcement-count': 0, created: today() };
     if (kf.domain?.length)
         fm.domain = kf.domain;
     if (kf.related?.length) {
@@ -177,6 +183,67 @@ export function buildKnowledgeFrontmatter(name, kf, existsFn) {
         fm['session-date'] = kf['session-date'];
     return fm;
 }
+// The Next Actions fields are the one group in UpdateFields that all touch
+// the same section, so their order within an op IS their meaning. The
+// contract: prune, tick, add — clear_actions → remove_action →
+// complete_action → add_action → add_actions. Every query is resolved
+// against the list as it stands after the clear and before any edit, so a
+// query never sees a line another field of the same op removed or added;
+// two queries naming one line is a collision, not a silent overwrite. The
+// section is pruned once at the end, after the adds — a tick that empties
+// the open list and an add in the same op edit the section in place rather
+// than removing and recreating it. The "rebuild the list" payload
+// (`clear_actions` + `add_actions`) does what it reads as. Contradictory
+// payloads (clear + a query) are rejected in the validate phase, not here.
+//
+// Lines leaving the list go to the archive log, never nowhere: the removed
+// line, a cleared list, the ticked lines a prune takes with the section, and
+// — once the section holds ARCHIVE_LIMIT or more ticked lines — the oldest of
+// them, leaving one fewer than the limit (the session log's rule). Each line
+// takes the lines nested under it (up to the next checkbox line). Run on
+// every update, so a list grown by hand is trimmed by the next write; never
+// on read.
+const ARCHIVE_LIMIT = 10;
+function applyNextActionFields(doc, body, fields) {
+    const result = {};
+    const cleared = fields.clear_actions ? doc.actionLines(body) : [];
+    let removedLine;
+    if (fields.clear_actions)
+        body = doc.clearNextActions(body);
+    const removed = fields.remove_action !== undefined ? doc.matchNextAction(body, fields.remove_action) : undefined;
+    const completed = fields.complete_action !== undefined ? doc.matchNextAction(body, fields.complete_action) : undefined;
+    // Caller misuse, not a Spine bug: like no-match and ambiguous (matchNextAction),
+    // it depends on the list as the earlier ops of a batch leave it, so it is
+    // resolved here rather than in the validate phase.
+    if (removed && completed && removed.line === completed.line) {
+        throw new HafezError('VALIDATION_FAILED', `remove_action and complete_action both match "${removed.text}" — one line, one field`);
+    }
+    if (removed)
+        result.removed_action = removed.text;
+    if (completed)
+        result.completed_action = completed.text;
+    // Both matches are line positions in the pre-edit list. A tick leaves every
+    // position where it was; a removal shifts the lines below it — so tick first.
+    if (completed)
+        body = doc.completeNextAction(body, completed).body;
+    if (removed)
+        ({ body, line: removedLine } = doc.removeNextAction(body, removed));
+    if (fields.add_action !== undefined)
+        body = addStampedAction(doc, body, fields.add_action);
+    if (fields.add_actions !== undefined) {
+        for (const action of fields.add_actions) {
+            body = addStampedAction(doc, body, action);
+        }
+    }
+    const overflow = doc.extractOldestTickedActions(body, ARCHIVE_LIMIT - 1);
+    // With no open line left the prune takes the section, ticked lines and all.
+    const pruned = doc.getNextActions(overflow.body).length === 0 ? doc.actionLines(overflow.body) : [];
+    return {
+        body: doc.pruneNextActions(overflow.body),
+        result,
+        archived: { cleared, removed: removedLine, ticked: [...overflow.lines, ...pruned] },
+    };
+}
 // Pure field application, like every arm above it: the Spine has already run
 // Op Spec validation (shape + semantics). `doc` is the Document bound to the
 // file's kind (see documentFor).
@@ -189,26 +256,8 @@ function applyUpdateFields(doc, fm, body, fields) {
     if (fields.brief !== undefined) {
         body = fields.brief === null ? doc.removeBrief(body) : doc.setBrief(body, fields.brief);
     }
-    let matchedAction;
-    if (fields.add_action !== undefined)
-        body = doc.addNextAction(body, fields.add_action);
-    if (fields.add_actions !== undefined) {
-        for (const action of fields.add_actions) {
-            body = doc.addNextAction(body, action);
-        }
-    }
-    if (fields.complete_action !== undefined) {
-        const r = doc.completeNextAction(body, fields.complete_action);
-        body = r.body;
-        matchedAction = r.matched;
-    }
-    if (fields.remove_action !== undefined) {
-        const r = doc.removeNextAction(body, fields.remove_action);
-        body = r.body;
-        matchedAction = r.matched;
-    }
-    if (fields.clear_actions)
-        body = doc.clearNextActions(body);
+    const actions = applyNextActionFields(doc, body, fields);
+    body = actions.body;
     if (fields.session_log) {
         body = doc.prependSessionLogEntry(body, formatSessionLogEntry(fields.session_log));
     }
@@ -233,6 +282,8 @@ function applyUpdateFields(doc, fm, body, fields) {
     }
     if (fields.confidence !== undefined)
         fm.confidence = fields.confidence;
+    if (fields.parent !== undefined)
+        fm.parent = fields.parent;
     if (fields.tags !== undefined)
         fm.tags = fields.tags;
     if (fields.related !== undefined)
@@ -253,85 +304,46 @@ function applyUpdateFields(doc, fm, body, fields) {
     }
     if (fm['last-touched'] !== today())
         fm['last-touched'] = today();
-    return { fm, body, matchedAction };
+    const updateResult = { ...actions.result, ...(fields.session_log && { logged: true }) };
+    return { fm, body, updateResult, archivedActions: archivedActionEntries(actions.archived) };
 }
-function promoteCore(ctx, slug, target, filePath, fm, body, kind) {
-    const { vaultPath } = ctx;
-    const currentType = kind === 'knowledge' ? 'knowledge' : fm.type;
-    const modifiedFiles = [];
-    const deletedFiles = [];
-    if (target === 'knowledge') {
-        // Cross-kind: move file from entities/ to knowledge/. The source body
-        // is read under the entity Document binding.
-        const sourceDoc = documentFor({ kind: 'entity' });
-        const newPath = knowledgePath(vaultPath, slug);
-        // Promote must behave like create AT THE TARGET. A diverged vault can
-        // hold the same slug as both an entity and a knowledge note (findFile
-        // resolves entities first, so the validate phase sees only the entity);
-        // without this check the write below silently destroys the note.
-        if (existsSync(newPath)) {
-            throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists in ${kindDir('knowledge')}/`);
-        }
-        const notesSection = sourceDoc.findSection(body, 'Notes');
-        const notesContent = notesSection?.content ?? '';
-        const newFm = {
-            name: fm.name, subtype: 'insight', confidence: 'observation', created: fm.created || today(),
-        };
-        if (fm.description)
-            newFm.description = fm.description;
-        // resource is intentionally dropped on entity→knowledge promote (entity-only field)
-        if (fm.domain)
-            newFm.domain = fm.domain;
-        if (fm.related)
-            newFm.related = fm.related;
-        if (fm.tags)
-            newFm.tags = fm.tags;
-        const knBody = knowledgeBodyTemplate('insight', { synthesis: notesContent || undefined });
-        const finalBody = documentFor({ kind: 'knowledge' }).syncRelatedSection(knBody, newFm);
-        // An entities-only vault has no knowledge/ yet — create it like the
-        // create-knowledge arm does, and map any fs failure onto a HafezError
-        // so no raw ENOENT/ENOTDIR escapes the promote path.
-        try {
-            mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
-            writeFileSync(newPath, serializeFile(newFm, finalBody));
-            unlinkSync(filePath);
-        }
-        catch (err) {
-            throw new HafezError('VALIDATION_FAILED', `Failed to promote '${slug}' to knowledge: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        modifiedFiles.push(relative(vaultPath, newPath));
-        // The deletion must be staged too — `git add` of a removed path stages
-        // the removal; omitting it leaves the vault permanently dirty.
-        deletedFiles.push(relative(vaultPath, filePath));
+/** The archive log's entries for action lines leaving the list. Entry-shaped
+ * like the session log entries archived beside them, so the file stays one
+ * entry stream (merge.ts unions it by entry). */
+function archivedActionEntries(archived) {
+    const entries = [];
+    const plural = (n) => n === 1 ? '' : 's';
+    if (archived.cleared.length > 0) {
+        const n = archived.cleared.length;
+        entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: `Cleared ${n} action${plural(n)}`, body: archived.cleared.join('\n') }));
     }
-    else {
-        // Same-kind: capture→entity, capture→project, entity→project
-        fm.type = target;
-        fm['last-touched'] = today();
-        // All body reshaping goes through Document — structural sections only,
-        // so quoted heading mentions inside content can no longer suppress or
-        // hijack the splice points.
-        const doc = documentFor({ kind: 'entity' });
-        let newBody = body;
-        if (target === 'entity') {
-            newBody = doc.renameSection(newBody, 'Notes', 'Context');
-        }
-        else {
-            // project
-            newBody = doc.renameSection(newBody, 'Notes', 'Purpose');
-            newBody = doc.renameSection(newBody, 'Context', 'Purpose');
-            newBody = doc.ensureSection(newBody, 'Goals', { after: 'Purpose' });
-        }
-        newBody = doc.prependSessionLogEntry(newBody, formatSessionLogEntry({
-            type: 'decision',
-            agent: 'system',
-            summary: `Promoted from ${currentType} to ${target}`,
-        }));
-        newBody = doc.syncRelatedSection(newBody, fm);
-        writeFileSync(filePath, serializeFile(fm, newBody));
-        modifiedFiles.push(relative(vaultPath, filePath));
+    if (archived.removed !== undefined) {
+        entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: 'Removed action', body: archived.removed }));
+    }
+    const n = archived.ticked.length;
+    if (n > 0) {
+        entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: `Archived ${n} ticked action${plural(n)}`, body: archived.ticked.join('\n') }));
     }
-    return { modifiedFiles, deletedFiles };
+    return entries;
+}
+/** Mechanised session log (#85, moved into the Spine by #107): an entity
+ * update with no session_log gets a `progress` entry naming the fields
+ * written, so history is complete whichever caller wrote it. Action-only
+ * updates are exempt, and only entities carry a Session Log. */
+function withMechanisedLog(kind, fields) {
+    if (kind !== 'entity' || fields.session_log)
+        return fields;
+    const logged = loggedFields(fields);
+    if (logged.length === 0)
+        return fields;
+    return {
+        ...fields,
+        session_log: {
+            type: 'progress',
+            summary: `Updated ${logged.map(f => f.replace(/_/g, '-')).join(', ')}`,
+            agent: fields.agent ?? detectAgent(),
+        },
+    };
 }
 // --- The arms ---
 function applyUpdate(op, ctx) {
@@ -343,29 +355,32 @@ function applyUpdate(op, ctx) {
     const doc = documentForFile(parsedFile);
     let fm = parsedFile.frontmatter;
     let body = parsedFile.body;
-    const applied = applyUpdateFields(doc, fm, body, op.fields);
+    const applied = applyUpdateFields(doc, fm, body, withMechanisedLog(kind, op.fields));
     fm = applied.fm;
     body = applied.body;
-    // Session log archival
-    const archivePath = archiveLogPath(vaultPath, op.slug);
-    let archived = false;
-    if (doc.countSessionLogEntries(body) >= 10) {
+    // Archival: action lines that left the list, and the oldest session log entry
+    const archiveEntries = [...applied.archivedActions];
+    if (doc.countSessionLogEntries(body) >= ARCHIVE_LIMIT) {
         const extracted = doc.extractOldestSessionLogEntry(body);
         if (extracted) {
-            ctx.captureOriginal(archivePath);
-            mkdirSync(dirname(archivePath), { recursive: true });
-            appendFileSync(archivePath, extracted.entry + '\n\n');
+            archiveEntries.push(extracted.entry);
             body = extracted.remaining;
-            archived = true;
         }
     }
+    const archivePath = archiveLogPath(vaultPath, op.slug);
+    const wroteArchive = archiveEntries.length > 0;
+    if (wroteArchive) {
+        ctx.captureOriginal(archivePath);
+        mkdirSync(dirname(archivePath), { recursive: true });
+        appendFileSync(archivePath, archiveEntries.map(e => e + '\n\n').join(''));
+    }
     body = doc.syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     // 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 = [relative(vaultPath, filePath)];
-    if (archived)
+    if (wroteArchive)
         files.push(relative(vaultPath, archivePath));
     return {
         filesWritten: files,
@@ -374,7 +389,7 @@ function applyUpdate(op, ctx) {
         commitMessage: `update: ${op.slug}`,
         indexRemovals: [],
         indexUpserts: [{ slug: op.slug, kind }],
-        matchedAction: applied.matchedAction,
+        updateResult: applied.updateResult,
     };
 }
 function applyCreateEntity(op, ctx) {
@@ -551,7 +566,79 @@ function applyPromote(op, ctx) {
     const fm = parsedFile.frontmatter;
     const body = parsedFile.body;
     const sourceType = kind === 'knowledge' ? 'knowledge' : fm.type;
-    const { modifiedFiles, deletedFiles } = promoteCore(ctx, op.slug, op.target, filePath, fm, body, kind);
+    const modifiedFiles = [];
+    const deletedFiles = [];
+    if (op.target === 'knowledge') {
+        // Cross-kind: move file from entities/ to knowledge/. The source body
+        // is read under the entity Document binding.
+        const sourceDoc = documentFor({ kind: 'entity' });
+        const newPath = knowledgePath(vaultPath, op.slug);
+        // Promote must behave like create AT THE TARGET. A diverged vault can
+        // hold the same slug as both an entity and a knowledge note (findFile
+        // resolves entities first, so the validate phase sees only the entity);
+        // without this check the write below silently destroys the note.
+        if (existsSync(newPath)) {
+            throw new HafezError('SLUG_EXISTS', `Slug '${op.slug}' already exists in ${kindDir('knowledge')}/`);
+        }
+        const notesSection = sourceDoc.findSection(body, 'Notes');
+        const notesContent = notesSection?.content ?? '';
+        const newFm = {
+            name: fm.name, subtype: 'insight', confidence: 'observation', created: fm.created || today(),
+        };
+        if (fm.description)
+            newFm.description = fm.description;
+        // resource is intentionally dropped on entity→knowledge promote (entity-only field)
+        if (fm.domain)
+            newFm.domain = fm.domain;
+        if (fm.related)
+            newFm.related = fm.related;
+        if (fm.tags)
+            newFm.tags = fm.tags;
+        const knBody = knowledgeBodyTemplate('insight', { synthesis: notesContent || undefined });
+        const finalBody = documentFor({ kind: 'knowledge' }).syncRelatedSection(knBody, newFm);
+        // An entities-only vault has no knowledge/ yet — create it like the
+        // create-knowledge arm does, and map any fs failure onto a HafezError
+        // so no raw ENOENT/ENOTDIR escapes the promote path.
+        try {
+            mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
+            writeFileSync(newPath, serializeFile(newFm, finalBody));
+            unlinkSync(filePath);
+        }
+        catch (err) {
+            throw new HafezError('VALIDATION_FAILED', `Failed to promote '${op.slug}' to knowledge: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        modifiedFiles.push(relative(vaultPath, newPath));
+        // The deletion must be staged too — `git add` of a removed path stages
+        // the removal; omitting it leaves the vault permanently dirty.
+        deletedFiles.push(relative(vaultPath, filePath));
+    }
+    else {
+        // Same-kind: capture→entity, capture→project, entity→project
+        fm.type = op.target;
+        fm['last-touched'] = today();
+        // All body reshaping goes through Document — structural sections only,
+        // so quoted heading mentions inside content can no longer suppress or
+        // hijack the splice points.
+        const doc = documentFor({ kind: 'entity' });
+        let newBody = body;
+        if (op.target === 'entity') {
+            newBody = doc.renameSection(newBody, 'Notes', 'Context');
+        }
+        else {
+            // project
+            newBody = doc.renameSection(newBody, 'Notes', 'Purpose');
+            newBody = doc.renameSection(newBody, 'Context', 'Purpose');
+            newBody = doc.ensureSection(newBody, 'Goals', { after: 'Purpose' });
+        }
+        newBody = doc.prependSessionLogEntry(newBody, formatSessionLogEntry({
+            type: 'decision',
+            agent: 'system',
+            summary: `Promoted from ${sourceType} to ${op.target}`,
+        }));
+        newBody = doc.syncRelatedSection(newBody, fm);
+        writeFileSync(filePath, serializeFile(fm, newBody));
+        modifiedFiles.push(relative(vaultPath, filePath));
+    }
     return {
         filesWritten: modifiedFiles,
         filesDeleted: deletedFiles,
@@ -561,6 +648,29 @@ function applyPromote(op, ctx) {
         indexUpserts: [{ slug: op.slug, kind: op.target === 'knowledge' ? 'knowledge' : 'entity' }],
     };
 }
+function applyDelete(op, ctx) {
+    const { vaultPath } = ctx;
+    // By path, not findVaultFile's entity-first order: the Op Spec ruled out
+    // an entity, and resolved the slug to exactly one of these two.
+    const knowledgeFile = knowledgePath(vaultPath, op.slug);
+    const kind = existsSync(knowledgeFile) ? 'knowledge' : 'session';
+    const filePath = kind === 'knowledge' ? knowledgeFile : resolveFilePath(vaultPath, op.slug, 'session');
+    if (!existsSync(filePath))
+        vanished(op.slug);
+    // The snapshot is the rollback: a commit-stage failure writes it back.
+    ctx.captureOriginal(filePath);
+    unlinkSync(filePath);
+    return {
+        filesWritten: [],
+        filesDeleted: [relative(vaultPath, filePath)],
+        result: { op: 'delete', slug: op.slug, status: 'ok' },
+        commitMessage: `delete: ${op.slug} (${kind})`,
+        // Sessions are not indexed; a knowledge row goes with its file.
+        indexRemovals: kind === 'knowledge' ? [op.slug] : [],
+        indexUpserts: [],
+        deletedKind: kind,
+    };
+}
 const APPLY = {
     'update': applyUpdate,
     'create-entity': applyCreateEntity,
@@ -570,6 +680,7 @@ const APPLY = {
     'link': applyLink,
     'unlink': applyUnlink,
     'promote': applyPromote,
+    'delete': applyDelete,
 };
 /** The single apply path for every mutation. Writes vault files but never
  * touches git or SQLite: the Spine commits [...filesWritten, ...filesDeleted]