hafez 1.1.0 → 1.3.0

package/dist/document.d.ts

@@ -0,0 +1,108 @@
+import type { SessionLogEntry, SessionLogType } from './types.js';
+/**
+ * Known structural section headings in Hafez entities, knowledge notes, and
+ * session files. Derived from contracts.ts (defaultSections + optionalSections
+ * + session sections) plus auto-generated sections not tracked in contracts
+ * (Related). Only these are treated as section boundaries. Any other `## `
+ * heading inside section content (e.g. in a brief or session log) is
+ * preserved as-is.
+ */
+export declare const STRUCTURAL_SECTIONS: Set<string>;
+/**
+ * Find the next structural `## Heading` boundary after a given position.
+ * Skips `## ` headings that are not known structural sections (content headings).
+ * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
+ */
+export declare function findNextStructuralHeading(body: string, from: number): number;
+/**
+ * Find a ## Heading section and its content.
+ * Returns { start, headingEnd, end, content } or null if not found.
+ * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
+ * Trailing whitespace on the heading line is tolerated — the splitter's
+ * boundary tokenizer trims headings, so anything it treats as a boundary
+ * must also be findable here (a hand-edited `## Session Log ` otherwise
+ * gets a duplicate section and archival never fires).
+ * Only treats known structural headings as section boundaries -- content
+ * inside a section may contain arbitrary `## ` headings without corruption.
+ */
+export declare function findSection(body: string, heading: string): {
+    start: number;
+    headingEnd: number;
+    end: number;
+    content: string;
+} | null;
+export interface DocSection {
+    heading: string;
+    content: string;
+}
+/**
+ * Split a body into preamble + structural sections. Non-structural `## `
+ * headings stay inside the enclosing section's content — sections are
+ * atomic units of authored content, never split at user headings.
+ * Headings and content come back trimmed; reassemble with
+ * `## ${heading}\n\n${content}` joined by blank lines.
+ */
+export declare function splitStructural(body: string): {
+    preamble: string;
+    sections: DocSection[];
+};
+/**
+ * Replace a structural section's content, or create the section: before
+ * `insertBefore` when that section exists, at EOF otherwise.
+ */
+export declare function setSection(body: string, heading: string, content: string, insertBefore?: string): string;
+/** Append content at the end of a structural section (creating it at EOF if absent). */
+export declare function appendToSection(body: string, heading: string, content: string): string;
+/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
+export declare function prependSessionLogEntry(body: string, entry: string): string;
+/** Body up to the real Session Log section — the `summary` read depth. */
+export declare function bodyBeforeSessionLog(body: string): string;
+export declare function parseSessionLogHeading(line: string): {
+    date: string;
+    agent: string;
+    type: SessionLogType;
+} | null;
+export declare function formatSessionLogEntry(entry: SessionLogEntry): string;
+/** Entries inside the real Session Log section only — entry-shaped lines
+ * elsewhere in the body (e.g. quoted in a Brief) do not count. */
+export declare function countSessionLogEntries(body: string): number;
+export declare function parseSessionLog(body: string): Array<{
+    date: string;
+    agent: string;
+    type: SessionLogType;
+    summary: string;
+}>;
+export declare function extractOldestSessionLogEntry(body: string): {
+    entry: string;
+    remaining: string;
+} | null;
+export declare function getBrief(body: string): string | null;
+export declare function setBrief(body: string, content: string): string;
+export declare function removeBrief(body: string): string;
+export declare function getNextActions(body: string): string[];
+export declare function addNextAction(body: string, action: string): string;
+export declare function completeNextAction(body: string, query: string): {
+    matched: string;
+    body: string;
+};
+export declare function removeNextAction(body: string, query: string): {
+    matched: string;
+    body: string;
+};
+export declare function clearNextActions(body: string): string;
+export declare function firstNonEmptyLine(s: string | null | undefined): string;
+/**
+ * One-line summary for a doc: frontmatter description first, then the first
+ * non-empty line of the kind's primary section (entity: Brief; knowledge:
+ * Synthesis, falling back to Goal for plans; session: Summary).
+ * Shared by the vault index and the OKF export so the two surfaces agree.
+ */
+export declare function deriveSummary(kind: 'entity' | 'knowledge' | 'session', fm: Record<string, any>, body: string): string;
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
+export declare const WIKI_LINK_RE: RegExp;
+export declare function syncRelatedSection(body: string, frontmatter: {
+    parent?: string;
+    related?: string[];
+}): string;

package/dist/{sections.js → document.js}

@@ -1,19 +1,23 @@
-// src/sections.ts
-// Pure string→string functions for Brief and Next Actions section manipulation.
-import { ALL_CONTRACTS, SUBTYPE_SECTIONS } from './contracts.js';
+// src/document.ts
+// The Document module (see CONTEXT.md): owns the body of a vault file —
+// structural sections, session-log entries, wiki-links. Absorbs the former
+// sections.ts and parser.ts; every body read or mutation goes through the
+// single structural-heading model defined here. Pure string→string.
+import { ALL_CONTRACTS, SUBTYPE_SECTIONS, SESSION_SECTIONS } from './contracts.js';
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
 /**
- * Known structural section headings in Hafez entities and knowledge notes.
- * Derived from contracts.ts (defaultSections + optionalSections) plus
- * auto-generated sections not tracked in contracts (Related, Summary).
- * Only these are treated as section boundaries. Any other `## ` heading
- * inside section content (e.g. in a brief or session log) is preserved as-is.
+ * Known structural section headings in Hafez entities, knowledge notes, and
+ * session files. Derived from contracts.ts (defaultSections + optionalSections
+ * + session sections) plus auto-generated sections not tracked in contracts
+ * (Related). Only these are treated as section boundaries. Any other `## `
+ * heading inside section content (e.g. in a brief or session log) is
+ * preserved as-is.
  */
 export const STRUCTURAL_SECTIONS = new Set([
     ...ALL_CONTRACTS.flatMap(c => [...c.defaultSections, ...c.optionalSections]),
     ...Object.values(SUBTYPE_SECTIONS).flat(),
+    ...SESSION_SECTIONS,
     'Related', // auto-generated by syncRelatedSection
-    'Summary', // used in session files
 ]);
 /**
  * Find the next structural `## Heading` boundary after a given position.
@@ -32,31 +36,176 @@ export function findNextStructuralHeading(body, from) {
     }
     return -1;
 }
-// --- Internal helpers ---
 /**
  * Find a ## Heading section and its content.
- * Returns { start, end, content } or null if not found.
+ * Returns { start, headingEnd, end, content } or null if not found.
  * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
+ * Trailing whitespace on the heading line is tolerated — the splitter's
+ * boundary tokenizer trims headings, so anything it treats as a boundary
+ * must also be findable here (a hand-edited `## Session Log ` otherwise
+ * gets a duplicate section and archival never fires).
  * Only treats known structural headings as section boundaries -- content
  * inside a section may contain arbitrary `## ` headings without corruption.
  */
 export function findSection(body, heading) {
-    const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)})(?:\\n|$)`);
+    const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)}[ \\t]*)(?:\\n|$)`);
     const match = re.exec(body);
     if (!match)
         return null;
     const start = match.index + match[1].length;
-    const afterHeading = start + match[2].length + 1;
-    // Find the next structural ## heading or EOF
-    const nextHeading = findNextStructuralHeading(body, afterHeading);
+    const headingEnd = start + match[2].length;
+    const afterHeading = headingEnd + 1;
+    // Find the next structural ## heading or EOF. Scan from the heading's own
+    // trailing newline (afterHeading - 1), not past it — otherwise a structural
+    // heading on the immediately following line (no blank line between, as in
+    // hand-edited files) is invisible and mutators swallow the next section.
+    const nextHeading = findNextStructuralHeading(body, Math.max(0, afterHeading - 1));
     const end = nextHeading === -1 ? body.length : nextHeading;
     const rawContent = body.slice(afterHeading, end);
     const content = rawContent.replace(/^\n+/, '').replace(/\n+$/, '');
-    return { start, end, content };
+    return { start, headingEnd, end, content };
 }
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/**
+ * Split a body into preamble + structural sections. Non-structural `## `
+ * headings stay inside the enclosing section's content — sections are
+ * atomic units of authored content, never split at user headings.
+ * Headings and content come back trimmed; reassemble with
+ * `## ${heading}\n\n${content}` joined by blank lines.
+ */
+export function splitStructural(body) {
+    const marks = [];
+    const re = /(^|\n)## ([^\n]*)/g;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const heading = m[2].trim();
+        if (!STRUCTURAL_SECTIONS.has(heading))
+            continue;
+        marks.push({ start: m.index + m[1].length, contentStart: m.index + m[0].length, heading });
+    }
+    if (marks.length === 0)
+        return { preamble: body.trim(), sections: [] };
+    const preamble = body.slice(0, marks[0].start).trim();
+    const sections = marks.map((mk, i) => ({
+        heading: mk.heading,
+        content: body.slice(mk.contentStart, i + 1 < marks.length ? marks[i + 1].start : body.length).trim(),
+    }));
+    return { preamble, sections };
+}
+// --- Generic section mutation ---
+/**
+ * Replace a structural section's content, or create the section: before
+ * `insertBefore` when that section exists, at EOF otherwise.
+ */
+export function setSection(body, heading, content, insertBefore) {
+    const existing = findSection(body, heading);
+    if (existing) {
+        return body.slice(0, existing.start) + `## ${heading}\n\n${content}\n` + body.slice(existing.end);
+    }
+    if (insertBefore) {
+        const target = findSection(body, insertBefore);
+        if (target) {
+            return body.slice(0, target.start) + `## ${heading}\n\n${content}\n\n` + body.slice(target.start);
+        }
+    }
+    return body + `\n\n## ${heading}\n\n${content}\n`;
+}
+/** Append content at the end of a structural section (creating it at EOF if absent). */
+export function appendToSection(body, heading, content) {
+    const section = findSection(body, heading);
+    if (!section)
+        return body + `\n\n## ${heading}\n\n${content}\n`;
+    if (section.end === body.length)
+        return body + '\n' + content + '\n';
+    return body.slice(0, section.end) + '\n' + content + body.slice(section.end);
+}
+/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
+export function prependSessionLogEntry(body, entry) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return body + `\n\n## Session Log\n\n${entry}\n`;
+    const insertPos = section.headingEnd;
+    return body.slice(0, insertPos) + '\n\n' + entry + '\n' + body.slice(insertPos);
+}
+/** Body up to the real Session Log section — the `summary` read depth. */
+export function bodyBeforeSessionLog(body) {
+    const section = findSection(body, 'Session Log');
+    return section ? body.slice(0, section.start).trim() : body;
+}
+// --- Session log parsing ---
+const HEADING_RE = /^### (\d{4}-\d{2}-\d{2}) (?:—|--) (.+?)(?:\s+\[(\w+)\])?$/;
+export function parseSessionLogHeading(line) {
+    const match = line.match(HEADING_RE);
+    if (!match)
+        return null;
+    return {
+        date: match[1],
+        agent: match[2],
+        type: match[3] || 'progress'
+    };
+}
+export function formatSessionLogEntry(entry) {
+    const today = new Date().toISOString().slice(0, 10);
+    const lines = [`### ${today} — ${entry.agent} [${entry.type}]`, `Summary: ${entry.summary}`];
+    if (entry.body)
+        lines.push(entry.body);
+    return lines.join('\n');
+}
+/** Entries inside the real Session Log section only — entry-shaped lines
+ * elsewhere in the body (e.g. quoted in a Brief) do not count. */
+export function countSessionLogEntries(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return 0;
+    return (section.content.match(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm) || []).length;
+}
+export function parseSessionLog(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return [];
+    const entries = [];
+    const lines = section.content.split('\n');
+    let current = null;
+    let summaryLine = null;
+    for (const line of lines) {
+        const heading = parseSessionLogHeading(line);
+        if (heading) {
+            if (current && summaryLine) {
+                entries.push({ ...current, summary: summaryLine });
+            }
+            current = heading;
+            summaryLine = null;
+        }
+        else if (current && !summaryLine && line.startsWith('Summary: ')) {
+            summaryLine = line.slice('Summary: '.length);
+        }
+    }
+    if (current && summaryLine) {
+        entries.push({ ...current, summary: summaryLine });
+    }
+    return entries;
+}
+export function extractOldestSessionLogEntry(body) {
+    const section = findSection(body, 'Session Log');
+    if (!section)
+        return null;
+    // Work on the raw slice between the heading and the section's structural
+    // end, so the extracted entry can never swallow a following section
+    // (e.g. an auto-appended Related) into the archive.
+    const contentStart = section.headingEnd;
+    const region = body.slice(contentStart, section.end);
+    const entryStarts = [...region.matchAll(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm)];
+    if (entryStarts.length < 2)
+        return null;
+    // Entries are newest-first in the file, so the oldest is the last match
+    const oldestStart = entryStarts[entryStarts.length - 1].index;
+    const entry = region.slice(oldestStart).trim();
+    const remaining = body.slice(0, contentStart) + region.slice(0, oldestStart) + body.slice(section.end);
+    return { entry, remaining };
+}
+// --- Section removal / insertion helpers (Brief, Next Actions) ---
 /**
  * Remove a section (heading + content) from body, cleaning up extra whitespace.
  */
@@ -121,9 +270,9 @@ function insertSectionAfter(body, heading, content, after, beforeFallbacks) {
 function normalizeForMatch(s) {
     return s
         .trim()
-        .replace(/[\u2018\u2019]/g, "'")
-        .replace(/[\u201C\u201D]/g, '"')
-        .replace(/\u2014/g, '-');
+        .replace(/[‘’]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/—/g, '-');
 }
 /**
  * Match an action by case-insensitive substring against unchecked items.
@@ -251,9 +400,11 @@ export function deriveSummary(kind, fm, body) {
     }
     return firstNonEmptyLine(findSection(body, 'Summary')?.content);
 }
-// --- Related section functions ---
-/** Matches [[slug]] or [[slug|display text]], capturing slug in group 1. Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
-export const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/;
+// --- Wiki-links ---
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
+export const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/;
 export function syncRelatedSection(body, frontmatter) {
     const targets = [];
     if (frontmatter.parent)

package/dist/export-okf.js

@@ -7,24 +7,12 @@
 // regenerated indexes) until the bundle directory is deleted and re-exported.
 import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve, sep, basename } from 'path';
-import { parseFilePath, serializeFile } from './vault.js';
-import { deriveSummary } from './sections.js';
-const KIND_DIRS = [
-    { dir: 'entities', kind: 'entity' },
-    { dir: 'knowledge', kind: 'knowledge' },
-    { dir: 'sessions', kind: 'session' },
-];
-// Local capturing variant of the shared WIKI_LINK_RE — captures display text in
-// group 2, which the shared regex's consumers don't need.
-const OKF_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
-function scanDir(dirPath) {
-    try {
-        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
-    }
-    catch {
-        return [];
-    }
-}
+import { parseFilePath, serializeFile, scanVaultDir, kindDir } from './vault.js';
+import { deriveSummary, WIKI_LINK_RE } from './document.js';
+const SOURCE_KINDS = ['entity', 'knowledge', 'session'];
+const KIND_DIRS = SOURCE_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
+// The shared wiki-link syntax (document.ts) — group 1 slug, group 2 display.
+const OKF_LINK_RE = new RegExp(WIKI_LINK_RE.source, 'g');
 function mapFrontmatter(doc) {
     const { fm, kind, body } = doc;
     const mapped = {};
@@ -88,7 +76,7 @@ export function exportOkf(vaultPath, outDir) {
     // Enumerate and parse. Sessions are not in SQLite — disk enumeration is required.
     const docs = [];
     for (const { dir, kind } of KIND_DIRS) {
-        for (const filePath of scanDir(join(resolvedVault, dir))) {
+        for (const filePath of scanVaultDir(join(resolvedVault, dir))) {
             const slug = basename(filePath, '.md');
             const relFile = `${dir}/${slug}.md`;
             let fm, body;
@@ -160,9 +148,9 @@ export function exportOkf(vaultPath, outDir) {
     }
     // Root index.md — the only place okf_version may appear
     const counts = [
-        ['entities', report.entities],
-        ['knowledge', report.knowledge],
-        ['sessions', report.sessions],
+        [kindDir('entity'), report.entities],
+        [kindDir('knowledge'), report.knowledge],
+        [kindDir('session'), report.sessions],
     ];
     const rootLines = ['# Vault Export', ''];
     for (const [dir, count] of counts) {

package/dist/git.d.ts

@@ -1,4 +1,4 @@
-import { type GitConfig, type ChangelogEntry } from './types.js';
+import { type GitConfig, type ChangelogEntry, type Journal } from './types.js';
 /**
  * Bidirectional sync: pull remote changes, push local commits.
  * All work must be committed before calling — no file save/restore needed.
@@ -8,12 +8,18 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
+export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
 /**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ * Latest git time per file (repo-relative, forward-slash paths). Used to
+ * break day-granularity frontmatter ties in stats recents. `modified` maps
+ * each file to its most recent commit; `added` to the commit that added it.
+ * Files with no history (not yet committed) are absent from the map.
  */
-export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
-export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
+export declare function gitFileTimes(vaultPath: string, mode: 'modified' | 'added'): Promise<Map<string, string>>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export declare function createGitJournal(vaultPath: string, config?: GitConfig): Journal;

package/dist/git.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { simpleGit } from 'simple-git';
 import { mergeVaultContent } from './merge.js';
+import { VAULT_FILE_RE, INDEXED_DIR_PATHSPECS, classifyIndexedRelPath } from './vault.js';
 import { HafezError } from './types.js';
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
@@ -40,7 +41,6 @@ async function ensureCleanState(git, vaultPath) {
         }
     }
 }
-const VAULT_FILE_RE = /^(?:entities|knowledge|sessions)\/.+\.md$/;
 /**
  * True if the vault repo has an `origin` remote. A local-only vault (the
  * default the README setup produces) has none — every pull/push must be
@@ -253,12 +253,13 @@ export async function gitSync(vaultPath) {
     return { pulled, pushed: true, remote: true };
 }
 /**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ * Unstage files (best effort). Used by the journal adapter's commit-failure
+ * repair: a commit that fails after `git add` leaves the new blobs staged in
+ * .git/index, and the next successful commit would publish rolled-back
+ * content under the wrong message. Clearing the index entries restores
+ * worktree/HEAD/index agreement.
  */
-export async function gitUnstage(vaultPath, files) {
+async function gitUnstage(vaultPath, files) {
     try {
         await simpleGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
     }
@@ -281,11 +282,16 @@ const FILE_STATUS_MAP = {
 };
 export async function gitChangelog(vaultPath, since) {
     const git = simpleGit(vaultPath);
+    // git approxidate fills a date-only --since with the *current* time of
+    // day, so `--since <today>` means "since right now" and silently returns
+    // nothing — the obvious "what happened today" query was the one that
+    // failed. Normalise bare dates to local midnight.
+    const normalizedSince = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
     let output;
     try {
         output = await git.raw([
-            'log', `--since=${since}`, '--name-status',
-            '--pretty=format:%H|%aI|%s', '--', 'entities/', 'knowledge/',
+            'log', `--since=${normalizedSince}`, '--name-status',
+            '--pretty=format:%H|%aI|%s', '--', ...INDEXED_DIR_PATHSPECS,
         ]);
     }
     catch {
@@ -311,24 +317,49 @@ export async function gitChangelog(vaultPath, since) {
             const operation = FILE_STATUS_MAP[statusChar];
             if (!operation)
                 continue;
-            let kind;
-            let slug;
-            if (filePath.startsWith('entities/')) {
-                kind = 'entity';
-                slug = filePath.replace('entities/', '').replace('.md', '');
-            }
-            else if (filePath.startsWith('knowledge/')) {
-                kind = 'knowledge';
-                slug = filePath.replace('knowledge/', '').replace('.md', '');
-            }
-            else {
+            // Only vault documents — scaffold files (.gitkeep) live in the same
+            // dirs and would otherwise surface as changelog rows.
+            if (!filePath.endsWith('.md'))
                 continue;
-            }
-            entries.push({ slug, kind, operation, timestamp, commit_message });
+            const classified = classifyIndexedRelPath(filePath);
+            if (!classified)
+                continue;
+            entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
         }
     }
     return entries;
 }
+/**
+ * Latest git time per file (repo-relative, forward-slash paths). Used to
+ * break day-granularity frontmatter ties in stats recents. `modified` maps
+ * each file to its most recent commit; `added` to the commit that added it.
+ * Files with no history (not yet committed) are absent from the map.
+ */
+export async function gitFileTimes(vaultPath, mode) {
+    const git = simpleGit(vaultPath);
+    let output;
+    try {
+        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', ...INDEXED_DIR_PATHSPECS];
+        if (mode === 'added')
+            args.splice(1, 0, '--diff-filter=A');
+        output = await git.raw(args);
+    }
+    catch {
+        return new Map(); // no git history
+    }
+    const times = new Map();
+    let current = '';
+    for (const line of output.split('\n')) {
+        if (line.startsWith('\0')) {
+            current = line.slice(1);
+            continue;
+        }
+        const file = line.trim();
+        if (file && !times.has(file))
+            times.set(file, current); // first hit = newest
+    }
+    return times;
+}
 export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
     const git = simpleGit(vaultPath);
     // If a previous run crashed mid-rebase/merge, the repo is stuck.
@@ -365,3 +396,30 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
         return;
     await pushResolving(git, vaultPath, (conflictFiles) => `Git conflict with remote (files: ${conflictFiles.join(', ')}). Changes saved locally.`, `Git push failed after ${MAX_PUSH_RETRIES} attempts. Changes saved locally.`);
 }
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export function createGitJournal(vaultPath, config = {}) {
+    return {
+        async commit(written, deleted, message) {
+            const files = [...written, ...deleted];
+            try {
+                await gitCommitAndPush(vaultPath, files, message, config);
+            }
+            catch (err) {
+                // Commit-stage failure: nothing landed, but `git add` may have staged
+                // the new blobs — clean up our own partial state before rethrowing.
+                // Push-stage failure keeps the local commit (GIT_PUSH_FAILED).
+                if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
+                    await gitUnstage(vaultPath, files);
+                }
+                throw err;
+            }
+        },
+        sync: () => gitSync(vaultPath),
+        changelog: (since) => gitChangelog(vaultPath, since),
+        fileTimes: (mode) => gitFileTimes(vaultPath, mode),
+    };
+}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import type { Hafez, HafezConfig } from './types.js';
 export declare function createHafez(config: HafezConfig): Hafez;
 export { HafezError } from './types.js';
-export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
-export { getBrief, getNextActions, findSection } from './sections.js';
-export { parseSessionLogHeading, parseSessionLog } from './parser.js';
-export { formatStats, formatChangelog, formatValidation } from './cli/format.js';
+export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, Journal, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
+export { getBrief, getNextActions, findSection } from './document.js';
+export { parseSessionLogHeading, parseSessionLog } from './document.js';