hafez 1.3.0 → 2.0.0

package/dist/surfaces/surfaces.js

@@ -0,0 +1,230 @@
+// src/surfaces/surfaces.ts
+//
+// Surfaces of the Agent Contract and how the static ones compose Items. A
+// static Surface is text the binary writes out (the Block, the two skill
+// files); a binary Surface is command output whose Items carry a render
+// function. Every Surface has the label the owner table names it by.
+//
+// Hashes (onboard decision #58): first 12 hex of SHA-256. The Block's begin
+// marker hashes the text between the marker lines; a skill file's `hash:`
+// frontmatter line hashes everything after the closing `---`.
+import { createHash } from 'crypto';
+import { ITEMS } from './items.js';
+export const SURFACES = {
+    block: {
+        label: 'Block',
+        compose: place => [
+            '## Hafez',
+            '',
+            'Hafez is this user\'s vault: what they are working on (entities) and what they have learned (knowledge). You reach it only through the `hafez` command.',
+            '',
+            `**Load.** ${place('loadTriggers')}`,
+            '',
+            '**Write as it happens.** Each of these is due the moment it occurs:',
+            '',
+            place('writeTriggers'),
+            '',
+            place('createLines'),
+            '',
+            '**Rules.**',
+            '',
+            `- ${place('neverAsk')}`,
+            `- ${place('readBeforeWrite')}`,
+            `- ${place('oneCommand')}`,
+            `- ${place('openActions')}`,
+            `- ${place('neverEditByHand')}`,
+            `- ${place('neverSaveUnprompted')}`,
+            '',
+        ].join('\n'),
+    },
+    hafezSkillDescription: {
+        label: '`hafez` skill description',
+        compose: () => 'Hafez vault: the less common operations and the tool itself. Use when the user asks what is in the vault ("what am I working on?", "what\'s stale?"), wants to promote, link, unlink, delete, change a status or validate, or wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez"). Also the reference to read when no Hafez block is in your instructions.',
+    },
+    hafezSkillBody: {
+        label: '`hafez` skill body',
+        compose: place => [
+            '',
+            '# Hafez',
+            '',
+            '- Update an entity or note: `hafez read <slug>`. The end of its output shows the write command.',
+            '- Create an entity or a knowledge note: the two `hafez create` lines below.',
+            '- Save the session: the `hafez-save` skill. No skill: `hafez schema digest`.',
+            '',
+            place('neverAsk'),
+            place('readBeforeWrite'),
+            place('openActions'),
+            '',
+            '## Create',
+            '',
+            place('createLines'),
+            '',
+            '## Find',
+            '',
+            place('find'),
+            '',
+            '## Less common operations',
+            '',
+            place('rareOps'),
+            '',
+            `${place('batchShape')} Machine-readable shape of any op: \`hafez schema <op>\`, with \`--examples\` for a sample.`,
+            '',
+            '## The tool itself',
+            '',
+            place('upgradeReconfigure'),
+            '',
+        ].join('\n'),
+    },
+    hafezSaveDescription: {
+        label: '`hafez-save` description',
+        compose: place => place('saveTrigger'),
+    },
+    hafezSaveBody: {
+        label: '`hafez-save` body',
+        compose: place => ['', '# Save the session', '', place('saveMechanics'), ''].join('\n'),
+    },
+    read: { label: 'Binary: `read`' },
+    readHeader: { label: 'Binary: `read` header' },
+    readFooter: { label: 'Binary: `read` Footer' },
+    readMiss: { label: 'Binary: `read` miss' },
+    updateSuccess: { label: 'Binary: `update` success output' },
+    updateMisuse: { label: 'Binary: `update` misuse error' },
+    createKnowledge: { label: 'Binary: `create knowledge` output' },
+    digestError: { label: 'Binary: `digest` error' },
+    batchMisuse: { label: 'Binary: `batch` misuse error' },
+    mechanised: { label: 'Binary, mechanised' },
+    schema: { label: '`schema`' },
+    onboard: { label: '`onboard`' },
+};
+export const contentHash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
+/** Compose a static Surface, placing each Item's text in the form its role
+ * (Owner or fallback) calls for. `onPlace` sees every placement, nested ones
+ * included. */
+function composeWith(items, surfaceId, surface, onPlace = () => { }) {
+    const place = (id) => {
+        onPlace(id);
+        const item = items[id];
+        if (!item)
+            throw new Error(`${surfaceId} places unknown Item ${id}`);
+        const text = item.text;
+        if (typeof text === 'function')
+            return text(place, item.owner === surfaceId ? 'owner' : 'fallback');
+        if (text === undefined)
+            throw new Error(`${surfaceId} places ${id}, which has no text`);
+        return text;
+    };
+    if (!surface.compose)
+        throw new Error(`${surfaceId} is not a static surface`);
+    return surface.compose(place);
+}
+const compose = (id) => composeWith(ITEMS, id, SURFACES[id]);
+/** An Item's text as a binary Surface places it at run time, in the form its
+ * role there (Owner or fallback) calls for. */
+export function placeIn(surfaceId, id) {
+    const item = ITEMS[id];
+    if (surfaceId !== item.owner && surfaceId !== item.fallback) {
+        throw new Error(`${surfaceId} places ${id}, which is neither its owner nor its fallback`);
+    }
+    return composeWith(ITEMS, surfaceId, { label: SURFACES[surfaceId].label, compose: place => place(id) });
+}
+/** YAML folded scalar lines: greedy wrap at 76 columns, two-space indent. */
+function fold(text) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line && 2 + line.length + 1 + word.length > 76) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    lines.push(line);
+    return lines.map(l => `  ${l}`).join('\n');
+}
+function skillFile(name, description, body) {
+    const text = compose(body);
+    return `---\nname: ${name}\ndescription: >\n${fold(compose(description))}\nhash: ${contentHash(text)}\n---\n${text}`;
+}
+export function renderBlock() {
+    const inner = compose('block');
+    return `<!-- hafez:begin ${contentHash(inner)} -->\n${inner}<!-- hafez:end -->\n`;
+}
+/** `onboard --block`, what the SessionStart hook prints: the Block, then the
+ * read line for each entity matching the folder. */
+export function renderBlockHook(matches) {
+    return matches.length === 0 ? renderBlock() : `${renderBlock()}\n${ITEMS.folderMatch.render(matches)}\n`;
+}
+export const renderHafezSkill = () => skillFile('hafez', 'hafezSkillDescription', 'hafezSkillBody');
+/** `help --agent`: the `hafez` skill body, the one text, without the blank
+ * line that parts it from the skill file's frontmatter or the newline that
+ * ends the file (the CLI adds one to every output). */
+export const renderAgentHelp = () => compose('hafezSkillBody').replace(/^\n/, '').replace(/\n$/, '');
+export const renderHafezSaveSkill = () => skillFile('hafez-save', 'hafezSaveDescription', 'hafezSaveBody');
+// --- The owner table, rendered into a marked region of the contract README ---
+export const OWNER_TABLE_BEGIN = '<!-- owner-table:begin (rendered from src/surfaces/items.ts; edit the Item, then run scripts/render-surfaces.ts) -->';
+export const OWNER_TABLE_END = '<!-- owner-table:end -->';
+export function renderOwnerTable() {
+    const rows = Object.values(ITEMS).map((item) => {
+        const fallback = item.fallback ? SURFACES[item.fallback].label : '—';
+        return `| ${item.label} | ${SURFACES[item.owner].label} | ${fallback} | ${item.invokeOnly} |`;
+    });
+    return ['| Item | Owner | Fallback | Invoke-only |', '|---|---|---|---|', ...rows, ''].join('\n');
+}
+/** Replace the marked owner-table region of `doc` with a fresh render. */
+export function spliceOwnerTable(doc) {
+    const begin = doc.indexOf(OWNER_TABLE_BEGIN);
+    const end = doc.indexOf(OWNER_TABLE_END, begin);
+    if (begin < 0 || end < 0)
+        throw new Error('owner table markers missing or out of order');
+    if (doc.indexOf(OWNER_TABLE_BEGIN, begin + 1) >= 0 || doc.indexOf(OWNER_TABLE_END, end + 1) >= 0) {
+        throw new Error('owner table markers appear more than once');
+    }
+    return doc.slice(0, begin + OWNER_TABLE_BEGIN.length) + '\n' + renderOwnerTable() + doc.slice(end);
+}
+// --- Drift check 2: the typed Item table ---
+/** Every problem with the Item table: an Item with no Owner or no evidence
+ * pointer, an Item its Owner or static fallback never places, or one placed more than once in a
+ * Surface or in a Surface that is neither its Owner nor its declared fallback.
+ * Placement is checked for static Surfaces only; binary ones place at run time. */
+export function itemProblems(items, surfaces) {
+    const problems = [];
+    const placed = {};
+    for (const [sid, surface] of Object.entries(surfaces)) {
+        if (!surface.compose)
+            continue;
+        const counts = (placed[sid] = {});
+        try {
+            composeWith(items, sid, surface, id => { counts[id] = (counts[id] ?? 0) + 1; });
+        }
+        catch (err) {
+            problems.push(err.message);
+        }
+    }
+    for (const [id, item] of Object.entries(items)) {
+        if (!item.owner)
+            problems.push(`${id}: no owner`);
+        else if (!surfaces[item.owner])
+            problems.push(`${id}: unknown owner ${item.owner}`);
+        if (item.fallback && !surfaces[item.fallback])
+            problems.push(`${id}: unknown fallback ${item.fallback}`);
+        if (!item.evidence?.trim())
+            problems.push(`${id}: no evidence pointer`);
+        for (const [sid, counts] of Object.entries(placed)) {
+            const n = counts[id] ?? 0;
+            if (n > 0 && sid !== item.owner && sid !== item.fallback) {
+                problems.push(`${id}: placed in ${sid}, which is neither its owner nor its fallback`);
+            }
+            if (n > 1)
+                problems.push(`${id}: placed ${n} times in ${sid}`);
+        }
+        if (item.owner && surfaces[item.owner]?.compose && !placed[item.owner]?.[id]) {
+            problems.push(`${id}: not placed in its owner ${item.owner}`);
+        }
+        if (item.fallback && surfaces[item.fallback]?.compose && !placed[item.fallback]?.[id]) {
+            problems.push(`${id}: not placed in its fallback ${item.fallback}`);
+        }
+    }
+    return problems;
+}

package/dist/templates.d.ts

@@ -6,3 +6,9 @@ export declare function bodyTemplate(type: EntityType, fields?: {
 export declare function knowledgeBodyTemplate(subtype?: KnowledgeSubtype, fields?: {
     synthesis?: string;
 }): string;
+/** Session bodies. Sessions have no TypeContract, but their headings are
+ * structural for Document splitting — so the list lives in contracts with
+ * every other section set, and this renders it. */
+export declare function sessionBodyTemplate(fields?: {
+    synthesis?: string;
+}): string;

package/dist/templates.js

@@ -1,39 +1,39 @@
-import { SUBTYPE_SECTIONS } from './contracts.js';
-const ITEM_TEMPLATES = {
-    capture: ['## Notes'],
-    entity: ['## Context', '## Session Log'],
-    project: ['## Purpose', '## Goals', '## Session Log'],
-};
-export function bodyTemplate(type, fields) {
-    const sections = ITEM_TEMPLATES[type];
-    if (!sections)
-        throw new Error(`Unknown item type: ${type}`);
+import { SUBTYPE_SECTIONS, DEFAULT_KNOWLEDGE_SUBTYPE, SESSION_SECTIONS, ENTITY_TYPES, getContract } from './contracts.js';
+/** Render a body from a section list, injecting each field's text under the
+ * section that field writes into (contracts.CREATE_FIELD_SECTIONS names the
+ * pairs; a field whose section this template lacks is rejected upstream by
+ * `unreachableFields`, so an unplaced value never reaches here). */
+function render(sections, content) {
     const lines = [];
     for (const section of sections) {
-        lines.push(section);
-        if (section === '## Purpose' && fields?.purpose) {
-            lines.push('', fields.purpose);
-        }
-        if (section === '## Notes' && fields?.notes) {
-            lines.push('', fields.notes);
-        }
+        lines.push(`## ${section}`);
+        const text = content[section];
+        if (text)
+            lines.push('', text);
         lines.push('');
     }
     return lines.join('\n');
 }
+export function bodyTemplate(type, fields) {
+    // The template IS the contract's default sections — the Document module
+    // derives its structural set from the same place, so the two can't drift.
+    if (!ENTITY_TYPES.includes(type))
+        throw new Error(`Unknown item type: ${type}`);
+    return render(getContract(type).defaultSections, { Purpose: fields?.purpose, Notes: fields?.notes });
+}
 export function knowledgeBodyTemplate(subtype, fields) {
     if (subtype === 'session') {
         throw new Error("subtype 'session' is no longer supported for knowledge notes. " +
             "Use batch kind: 'session' instead. See knowledge-v2 migration.");
     }
-    const sections = SUBTYPE_SECTIONS[subtype ?? 'insight'];
-    const lines = [];
-    for (const section of sections) {
-        lines.push(`## ${section}`);
-        if ((section === 'Synthesis' || section === 'Summary') && fields?.synthesis) {
-            lines.push('', fields.synthesis);
-        }
-        lines.push('');
-    }
-    return lines.join('\n');
+    // 'Summary' was a second injection target here until sessions stopped being
+    // a knowledge subtype; no SUBTYPE_SECTIONS entry has carried it since — the
+    // session body is its own template below.
+    return render(SUBTYPE_SECTIONS[subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE], { Synthesis: fields?.synthesis });
+}
+/** Session bodies. Sessions have no TypeContract, but their headings are
+ * structural for Document splitting — so the list lives in contracts with
+ * every other section set, and this renders it. */
+export function sessionBodyTemplate(fields) {
+    return render([...SESSION_SECTIONS], { Summary: fields?.synthesis });
 }

package/dist/types.d.ts

@@ -1,23 +1,31 @@
-export type EntityType = 'capture' | 'entity' | 'project';
-export type EntityStatus = 'active' | 'paused' | 'done';
-export type ConfidenceLevel = 'observation' | 'pattern' | 'principle';
-export type SessionLogType = 'progress' | 'decision' | 'blocker' | 'research';
+import type { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES } from './contracts.js';
+export type EntityType = typeof ENTITY_TYPES[number];
+export type EntityStatus = typeof ENTITY_STATUSES[number];
+export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[number];
+export type SessionLogType = typeof SESSION_LOG_TYPES[number];
 export type ReadDepth = 'frontmatter' | 'summary' | 'full';
-export type QueryFilter = 'active' | 'paused' | 'done' | 'all' | 'stale' | 'capture';
+export type QueryFilter = EntityStatus | 'all' | 'stale' | 'capture';
 export type LinkRelation = 'parent' | 'related';
-export type KnowledgeSubtype = 'insight' | 'plan';
+export type KnowledgeSubtype = typeof VALID_SUBTYPES[number];
+/** Plans are the one knowledge subtype with a lifecycle (see PLAN_STATUSES). */
+export type PlanStatus = typeof PLAN_STATUSES[number];
+/** Sort fields, and the two an entity query cannot honour — reinforcement
+ * lives on knowledge notes only. Asking for one on the entity branch is a
+ * validation error, not a silent fall back to recency, so the entity opts
+ * type declares only what that branch can actually sort by. */
+export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count'>;
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
     parent?: string;
     domain?: string;
-    confidence?: ConfidenceLevel;
     since?: string;
     before?: string;
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: EntitySortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
@@ -26,12 +34,36 @@ export interface KnowledgeQueryOpts {
     domain?: string;
     confidence?: ConfidenceLevel;
     subtype?: KnowledgeSubtype;
+    since?: string;
+    before?: string;
+    createdSince?: string;
+    createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: SortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
+/** `kind: 'all'` (or unset): reaches both sides, so it takes opts from both
+ * and can honour every sort field. Status filters narrow the entity side only
+ * — knowledge notes carry no status and are never excluded by one. */
+export interface AllQueryOpts extends Omit<EntityQueryOpts, 'sort_by'> {
+    kind?: 'all';
+    confidence?: ConfidenceLevel;
+    subtype?: KnowledgeSubtype;
+    sort_by?: SortField;
+}
+/** The unified query, discriminated on `kind`. Naming a single kind narrows
+ * this query to that kind's opts, because a narrowed branch maps no more than
+ * the dedicated one does: an out-of-scope condition would land on a column the
+ * selected kind leaves NULL and silently exclude every row. The read surface
+ * rejects those at runtime for callers without types; the union is what makes
+ * them a compile error first. */
+export type UnifiedQueryOpts = AllQueryOpts | (EntityQueryOpts & {
+    kind: 'entity';
+}) | (KnowledgeQueryOpts & {
+    kind: 'knowledge';
+});
 export interface EntityFrontmatter {
     name: string;
     type: EntityType;
@@ -58,7 +90,7 @@ export interface KnowledgeFrontmatter {
     'reinforcement-count'?: number;
     tags?: string[];
     'session-date'?: string;
-    status?: 'active' | 'done';
+    status?: PlanStatus;
     'last-touched'?: string;
 }
 export interface SessionFrontmatter {
@@ -82,12 +114,11 @@ export type ParsedVaultFile = {
     frontmatter: SessionFrontmatter;
     body: string;
 };
-export interface ParsedFile<T = EntityFrontmatter | KnowledgeFrontmatter> {
-    /** Populated by read(): which side of the vault the slug resolved to. */
-    kind?: 'entity' | 'knowledge';
-    frontmatter: T;
-    body: string;
-}
+/** What read() returns: the indexed arms of ParsedVaultFile (a session slug is
+ * never resolvable through read()), so consumers narrow on `kind`. */
+export type ParsedFile = Extract<ParsedVaultFile, {
+    kind: 'entity' | 'knowledge';
+}>;
 export interface SessionLogEntry {
     type: SessionLogType;
     summary: string;
@@ -105,12 +136,14 @@ export interface UpdateFields {
     status?: EntityStatus;
     current_state?: string;
     session_log?: SessionLogEntry;
+    agent?: string;
     brief?: string | null;
     add_action?: string;
     add_actions?: string[];
     complete_action?: string;
     remove_action?: string;
     clear_actions?: boolean;
+    parent?: string;
     description?: string | null;
     resource?: string | null;
     domain?: string[];
@@ -118,11 +151,14 @@ export interface UpdateFields {
     tags?: string[];
     related?: string[];
     synthesis?: string;
+    insight?: string;
     add_evidence?: string;
     add_source?: string;
 }
 export interface UpdateResult {
-    matched_action?: string;
+    completed_action?: string;
+    removed_action?: string;
+    logged?: true;
 }
 export interface CreateEntityFields {
     type: EntityType;
@@ -139,7 +175,10 @@ export interface CreateEntityFields {
 }
 export interface CreateKnowledgeFields {
     subtype?: KnowledgeSubtype;
+    status?: PlanStatus;
+    confidence?: ConfidenceLevel;
     synthesis?: string;
+    insight?: string;
     description?: string;
     domain?: string[];
     related?: string[];
@@ -191,7 +230,6 @@ export interface ValidationIssue {
 export interface ValidationReport {
     broken_slugs: ValidationIssue[];
     orphaned_knowledge: string[];
-    oversized_related: ValidationIssue[];
     missing_fields: ValidationIssue[];
     total_entities: number;
     total_knowledge: number;
@@ -241,8 +279,16 @@ export interface ChangelogEntry {
 export interface BatchResult {
     op: string;
     slug: string;
-    status: 'ok' | 'error';
+    /** 'skipped' = the Op Spec green-lit the op but there was nothing to do
+     * (today: a duplicate session note) — no write, no error, batch continues.
+     * Dry-run reports the same disposition as a warning. */
+    status: 'ok' | 'error' | 'skipped';
     error?: string;
+    /** Why an op was skipped — same text the dry-run warning carries. */
+    warning?: string;
+    /** Error class when the failure — or the skip — maps to a specific HafezError
+     * code, so a single-op caller unwrapping this result keeps the right exit code. */
+    code?: 'SLUG_EXISTS';
     created?: boolean;
 }
 export type BatchOperation = {
@@ -282,7 +328,13 @@ export type BatchOperation = {
     op: 'promote';
     slug: string;
     target: 'entity' | 'project' | 'knowledge';
+} | {
+    op: 'delete';
+    slug: string;
 };
+/** What `delete` may remove. An entity is never deleted: it is retired with
+ * `status: done`. */
+export type DeletableKind = 'knowledge' | 'session';
 export interface BatchOpValidation {
     index: number;
     op: string;
@@ -290,6 +342,10 @@ export interface BatchOpValidation {
     created?: boolean;
     errors: string[];
     warning?: string;
+    /** Error class of the primary failure (NOT_FOUND / SLUG_EXISTS) when it
+     * maps to a specific HafezError code; single-op callers surface it as that
+     * code, batch-level failures stay VALIDATION_FAILED. */
+    primaryCode?: 'NOT_FOUND' | 'SLUG_EXISTS';
 }
 export interface BatchValidationReport {
     valid: boolean;
@@ -341,9 +397,7 @@ export interface Hafez {
         items: QueryResult[];
         total: number;
     }>;
-    queryUnified(opts?: EntityQueryOpts & {
-        kind?: 'entity' | 'knowledge' | 'all';
-    }): Promise<{
+    queryUnified(opts?: UnifiedQueryOpts): Promise<{
         items: UnifiedResult[];
         total: number;
     }>;
@@ -353,6 +407,8 @@ export interface Hafez {
     link(slug: string, target: string, relation: LinkRelation): Promise<void>;
     unlink(slug: string, target: string, relation: LinkRelation): Promise<void>;
     promote(slug: string, target: 'entity' | 'project' | 'knowledge'): Promise<string>;
+    /** Delete a knowledge or session note; resolves to the kind deleted. */
+    delete(slug: string): Promise<DeletableKind>;
     batch(operations: BatchOperation[]): Promise<BatchResult[]>;
     validateBatch(operations: BatchOperation[]): Promise<BatchValidationReport>;
     sync(): Promise<{

package/dist/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationReport } from './types.js';
+/** The vault integrity scan. Deliberately independent of the SQLite index:
+ * this is the one operation that does not trust the index, so it reads the
+ * files directly. Re-implementing it as an index query was considered and
+ * rejected — an integrity checker that reads the index is checking the
+ * index's model of the vault, not the vault. */
+export declare function validateVault(vaultPath: string): ValidationReport;

package/dist/validate.js

@@ -0,0 +1,109 @@
+import { join, basename } from 'path';
+import { parseFilePath, scanVaultDir, kindDir, vaultFileExists } from './vault.js';
+import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
+import { parentCycle } from './batch-ops.js';
+/** The vault integrity scan. Deliberately independent of the SQLite index:
+ * this is the one operation that does not trust the index, so it reads the
+ * files directly. Re-implementing it as an index query was considered and
+ * rejected — an integrity checker that reads the index is checking the
+ * index's model of the vault, not the vault. */
+export function validateVault(vaultPath) {
+    const exists = (slug) => vaultFileExists(vaultPath, slug);
+    const report = {
+        broken_slugs: [],
+        orphaned_knowledge: [],
+        missing_fields: [],
+        total_entities: 0,
+        total_knowledge: 0,
+    };
+    const knowledgeSlugs = new Set();
+    const referencedKnowledge = new Set();
+    const parents = new Map();
+    // Scan entities
+    const entDir = join(vaultPath, kindDir('entity'));
+    {
+        const files = scanVaultDir(entDir);
+        report.total_entities = files.length;
+        for (const filePath of files) {
+            const slug = basename(filePath, '.md');
+            let fm;
+            try {
+                fm = parseFilePath(filePath).frontmatter;
+            }
+            catch {
+                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
+                continue;
+            }
+            const errors = validateEntityFrontmatter(fm);
+            for (const e of errors)
+                report.missing_fields.push({ slug, field: '', issue: e });
+            if (fm.parent) {
+                parents.set(slug, fm.parent);
+                if (!exists(fm.parent))
+                    report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
+            }
+            if (fm.related && Array.isArray(fm.related)) {
+                for (const r of fm.related) {
+                    if (!exists(r))
+                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
+                    // Track referenced knowledge
+                    referencedKnowledge.add(r);
+                }
+            }
+        }
+    }
+    // Parent cycles: reported once each, under the first member found
+    const inCycle = new Set();
+    for (const [slug, parent] of parents) {
+        if (inCycle.has(slug))
+            continue;
+        const cycle = parentCycle(slug, parent, s => parents.get(s));
+        if (!cycle)
+            continue;
+        for (const s of cycle)
+            inCycle.add(s);
+        report.broken_slugs.push({ slug, field: 'parent', issue: `parent cycle: ${cycle.join(' → ')}` });
+    }
+    // Scan knowledge
+    const knDir = join(vaultPath, kindDir('knowledge'));
+    {
+        const files = scanVaultDir(knDir);
+        report.total_knowledge = files.length;
+        for (const filePath of files) {
+            const slug = basename(filePath, '.md');
+            knowledgeSlugs.add(slug);
+            let fm;
+            try {
+                fm = parseFilePath(filePath).frontmatter;
+            }
+            catch {
+                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
+                continue;
+            }
+            const errors = validateKnowledgeFrontmatter(fm);
+            for (const e of errors)
+                report.missing_fields.push({ slug, field: '', issue: e });
+            if (fm.related && Array.isArray(fm.related)) {
+                for (const r of fm.related) {
+                    if (!exists(r))
+                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
+                }
+            }
+        }
+    }
+    // Find orphaned knowledge: no related, and not referenced by any entity
+    for (const slug of knowledgeSlugs) {
+        let fm;
+        try {
+            fm = parseFilePath(join(knDir, `${slug}.md`)).frontmatter;
+        }
+        catch {
+            continue; // already reported above
+        }
+        const hasRelated = fm.related && Array.isArray(fm.related) && fm.related.length > 0;
+        if (!hasRelated && !referencedKnowledge.has(slug)) {
+            report.orphaned_knowledge.push(slug);
+        }
+    }
+    return report;
+}