@theglitchking/hit-em-with-the-docs 2.1.1 → 2.3.0

package/dist/core/domains/classifier.js

@@ -2,7 +2,38 @@
  * Document tier classification system.
  * Classifies documents into 5 tiers based on content structure.
  */
-export const TIERS = ['guide', 'standard', 'example', 'reference', 'admin'];
+export const TIERS = [
+    'guide',
+    'standard',
+    'example',
+    'reference',
+    'admin',
+    'plan',
+    'fact',
+    'incident-narrative',
+    'incident-facts',
+];
+/**
+ * Tiers that use lifecycle status (status field) instead of semver versioning.
+ * These tiers have `version` relaxed to optional in the MetadataSchema and
+ * accept tier-specific status enums in addition to (or instead of) the
+ * doc-tier status enum.
+ *
+ * - plan: phase/task/atom planning artifacts (added in 2.2.0)
+ * - fact: atomic knowledge claims, tracked via `last_verified` + confidence
+ * - incident-narrative: postmortem story (date-stamped, immutable)
+ * - incident-facts: bridge doc linking incidents to facts they produced
+ */
+export const LIFECYCLE_TRACKED_TIERS = [
+    'plan',
+    'fact',
+    'incident-narrative',
+    'incident-facts',
+];
+export function isLifecycleTrackedTier(tier) {
+    return (typeof tier === 'string' &&
+        LIFECYCLE_TRACKED_TIERS.includes(tier));
+}
 export const TIER_DEFINITIONS = {
     guide: {
         id: 'guide',
@@ -83,6 +114,70 @@ export const TIER_DEFINITIONS = {
             /^#+\s*(troubleshooting|debugging)/i,
         ],
     },
+    plan: {
+        id: 'plan',
+        name: 'Plan',
+        description: 'Phase/task/atom planning artifacts (added in 2.2.0 for persistent-planning lg-mode interop). Plans typically carry tier: plan in frontmatter; auto-classification is a fallback.',
+        sizeRange: { min: 1, max: 200 },
+        indicators: [
+            'phase', 'task', 'atom', 'milestone', 'deliverable',
+            'plan', 'roadmap', 'blocker', 'dependency', 'next concrete action',
+        ],
+        headingPatterns: [
+            /^#+\s*(goal|scope|status)/i,
+            /^#+\s*(phases?|tasks?|atoms?)/i,
+            /^#+\s*(decisions? made|errors? encountered)/i,
+            /^#+\s*(implementation notes|key questions)/i,
+        ],
+    },
+    fact: {
+        id: 'fact',
+        name: 'Fact',
+        description: 'Atomic, single-claim, citable unit of knowledge (added in 2.3.0). Facts use last_verified + confidence instead of semver versioning. Facts typically carry tier: fact in frontmatter; auto-classification is a fallback.',
+        sizeRange: { min: 1, max: 5 },
+        indicators: [
+            'claim', 'confidence', 'verify', 'last verified', 'provenance',
+            'citation', 'fact', 'hypothesis', 'invalidated by', 'consequence',
+        ],
+        headingPatterns: [
+            /^#+\s*(claim|the claim)/i,
+            /^#+\s*(how to verify|verification)/i,
+            /^#+\s*(consequences?|implications?)/i,
+            /^#+\s*(cited by|provenance)/i,
+        ],
+    },
+    'incident-narrative': {
+        id: 'incident-narrative',
+        name: 'Incident narrative',
+        description: 'Immutable postmortem story (added in 2.3.0). Lives at <vault-root>/incidents/<date-slug>/narrative.md. Date-stamped; uses lifecycle status (open/partial/resolved/planned) not semver.',
+        sizeRange: { min: 2, max: 50 },
+        indicators: [
+            'postmortem', 'incident', 'outage', 'severity', 'resolution',
+            'timeline', 'root cause', 'remediation', 'symptoms', 'on-call',
+        ],
+        headingPatterns: [
+            /^#+\s*(timeline|sequence of events)/i,
+            /^#+\s*(root cause|cause)/i,
+            /^#+\s*(impact|severity)/i,
+            /^#+\s*(remediation|resolution|fix)/i,
+            /^#+\s*(lessons learned|action items|follow[-\s]ups?)/i,
+        ],
+    },
+    'incident-facts': {
+        id: 'incident-facts',
+        name: 'Incident facts bridge',
+        description: 'Bridge document linking an incident to the facts it produced, strengthened, or weakened (added in 2.3.0). Lives at <vault-root>/incidents/<date-slug>/facts.md.',
+        sizeRange: { min: 1, max: 10 },
+        indicators: [
+            'produced', 'strengthened', 'weakened', 'facts from',
+            'incident facts', 'bridges to', 'derived from',
+        ],
+        headingPatterns: [
+            /^#+\s*(produced|new facts)/i,
+            /^#+\s*(strengthened)/i,
+            /^#+\s*(weakened|invalidated)/i,
+        ],
+    },
 };
 /**
  * Classify document content into a tier
@@ -94,6 +189,10 @@ export function classifyTier(content) {
         example: 0,
         reference: 0,
         admin: 0,
+        plan: 0,
+        fact: 0,
+        'incident-narrative': 0,
+        'incident-facts': 0,
     };
     const reasoning = [];
     const lowerContent = content.toLowerCase();

package/dist/core/domains/classifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../../src/core/domains/classifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../../src/core/domains/classifier.ts"],"names":[],"mappings":"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"}

package/dist/core/knowledge-base/audit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Stale-fact detection + verify-command execution (2.3.0 PR3).
+ *
+ * `auditFacts()` is the writer side of `hewtd audit-facts` — pure-data,
+ * easy to unit-test with date injection. `runFactVerify()` actually
+ * shells out and updates `last_verified` on success.
+ *
+ * Working-dir resolution (locked in during planning):
+ *   - Default: `<vault-root>/facts/`
+ *   - Override: a fact's optional `working_dir:` frontmatter field
+ */
+import type { FactRef, CiterIndex } from './citers.js';
+export interface StaleFact {
+    id: string;
+    path: string;
+    relPath: string;
+    title: string;
+    confidence: string | undefined;
+    lastVerified: string;
+    daysSinceVerified: number;
+}
+export interface AuditFactsOptions {
+    index: CiterIndex;
+    /** Reference date for "now". Defaults to today. Tests inject a fixed date. */
+    now?: Date;
+    /** Stale threshold in days. Defaults to 90. */
+    auditWindowDays?: number;
+}
+export interface AuditFactsResult {
+    stale: StaleFact[];
+    /** Facts whose last_verified is malformed or absent. Reported but not "stale". */
+    unverifiable: FactRef[];
+}
+export declare function auditFacts(options: AuditFactsOptions): AuditFactsResult;
+export interface RunVerifyOptions {
+    fact: FactRef;
+    /** Absolute vault root (used to compute default CWD). */
+    vaultRoot: string;
+    /** Override CWD (test seam). */
+    cwdOverride?: string;
+    /** Inject a fake date for the `last_verified` rewrite. */
+    now?: Date;
+    /** Skip the actual shell-out (test seam). Returns success without running. */
+    skipExec?: boolean;
+}
+export interface RunVerifyResult {
+    factId: string;
+    executed: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** True iff the fact's `last_verified` was updated. */
+    updated: boolean;
+    /** YYYY-MM-DD that was written. */
+    newLastVerified: string | undefined;
+}
+/**
+ * Execute a fact's `verify_command` and update `last_verified` on success.
+ * Returns a typed result describing what happened.
+ *
+ * The verify command runs in a child shell (bash via `-c`). CWD resolution:
+ *   1. `cwdOverride` (test seam)
+ *   2. Fact's frontmatter `working_dir:` field, resolved relative to vaultRoot
+ *   3. `<vaultRoot>/facts/` default
+ */
+export declare function runFactVerify(options: RunVerifyOptions): Promise<RunVerifyResult>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/core/knowledge-base/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,kFAAkF;IAClF,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CA2CvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAuE1B"}

package/dist/core/knowledge-base/audit.js

@@ -0,0 +1,158 @@
+/**
+ * Stale-fact detection + verify-command execution (2.3.0 PR3).
+ *
+ * `auditFacts()` is the writer side of `hewtd audit-facts` — pure-data,
+ * easy to unit-test with date injection. `runFactVerify()` actually
+ * shells out and updates `last_verified` on success.
+ *
+ * Working-dir resolution (locked in during planning):
+ *   - Default: `<vault-root>/facts/`
+ *   - Override: a fact's optional `working_dir:` frontmatter field
+ */
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { spawn } from 'child_process';
+import { resolve } from 'path';
+import matter from 'gray-matter';
+export function auditFacts(options) {
+    const { index, now = new Date(), auditWindowDays = 90 } = options;
+    const cutoffMs = now.getTime() - auditWindowDays * 24 * 60 * 60 * 1000;
+    const stale = [];
+    const unverifiable = [];
+    for (const fact of index.facts.values()) {
+        if (!fact.lastVerified) {
+            unverifiable.push(fact);
+            continue;
+        }
+        const verifiedMs = new Date(`${fact.lastVerified}T00:00:00Z`).getTime();
+        if (Number.isNaN(verifiedMs)) {
+            unverifiable.push(fact);
+            continue;
+        }
+        if (verifiedMs < cutoffMs) {
+            const daysSinceVerified = Math.floor((now.getTime() - verifiedMs) / (24 * 60 * 60 * 1000));
+            stale.push({
+                id: fact.id,
+                path: fact.path,
+                relPath: fact.relPath,
+                title: fact.title,
+                confidence: fact.confidence,
+                lastVerified: fact.lastVerified,
+                daysSinceVerified,
+            });
+        }
+    }
+    // Deterministic order: by daysSinceVerified desc (oldest first), id asc.
+    stale.sort((a, b) => {
+        if (a.daysSinceVerified !== b.daysSinceVerified) {
+            return b.daysSinceVerified - a.daysSinceVerified;
+        }
+        return a.id.localeCompare(b.id);
+    });
+    unverifiable.sort((a, b) => a.id.localeCompare(b.id));
+    return { stale, unverifiable };
+}
+/**
+ * Execute a fact's `verify_command` and update `last_verified` on success.
+ * Returns a typed result describing what happened.
+ *
+ * The verify command runs in a child shell (bash via `-c`). CWD resolution:
+ *   1. `cwdOverride` (test seam)
+ *   2. Fact's frontmatter `working_dir:` field, resolved relative to vaultRoot
+ *   3. `<vaultRoot>/facts/` default
+ */
+export async function runFactVerify(options) {
+    const { fact, vaultRoot, cwdOverride, now = new Date(), skipExec = false } = options;
+    // Read the fact file fresh — we need the full frontmatter (verify_command,
+    // working_dir) which isn't in the lightweight CiterIndex FactRef.
+    const factContent = await readFile(fact.path, 'utf-8');
+    const parsed = matter(factContent);
+    const verifyCommand = parsed.data.verify_command;
+    const workingDir = parsed.data.working_dir;
+    if (typeof verifyCommand !== 'string' || verifyCommand.trim().length === 0) {
+        return {
+            factId: fact.id,
+            executed: false,
+            exitCode: null,
+            stdout: '',
+            stderr: 'no verify_command defined',
+            updated: false,
+            newLastVerified: undefined,
+        };
+    }
+    const cwd = cwdOverride ??
+        (typeof workingDir === 'string'
+            ? resolve(vaultRoot, workingDir)
+            : resolve(vaultRoot, 'facts'));
+    if (skipExec) {
+        return finalize({
+            success: true,
+            exitCode: 0,
+            stdout: '[skipExec=true]',
+            stderr: '',
+        });
+    }
+    const result = await execShell(verifyCommand, cwd);
+    return finalize(result);
+    async function finalize(r) {
+        if (!r.success) {
+            return {
+                factId: fact.id,
+                executed: true,
+                exitCode: r.exitCode,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                updated: false,
+                newLastVerified: undefined,
+            };
+        }
+        const newDate = now.toISOString().slice(0, 10);
+        parsed.data.last_verified = newDate;
+        const rewritten = matter.stringify(parsed.content, parsed.data);
+        await writeFile(fact.path, rewritten, 'utf-8');
+        return {
+            factId: fact.id,
+            executed: true,
+            exitCode: r.exitCode,
+            stdout: r.stdout,
+            stderr: r.stderr,
+            updated: true,
+            newLastVerified: newDate,
+        };
+    }
+}
+function execShell(command, cwd) {
+    return new Promise((resolvePromise) => {
+        if (!existsSync(cwd)) {
+            resolvePromise({
+                success: false,
+                exitCode: -1,
+                stdout: '',
+                stderr: `working dir does not exist: ${cwd}`,
+            });
+            return;
+        }
+        const child = spawn('bash', ['-c', command], { cwd });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => (stdout += chunk.toString()));
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+        child.on('close', (code) => {
+            resolvePromise({
+                success: code === 0,
+                exitCode: code ?? -1,
+                stdout,
+                stderr,
+            });
+        });
+        child.on('error', (err) => {
+            resolvePromise({
+                success: false,
+                exitCode: -1,
+                stdout: '',
+                stderr: err.message,
+            });
+        });
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/knowledge-base/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/core/knowledge-base/audit.ts"],"names":[],"mappings":"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"}

package/dist/core/knowledge-base/cite.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Frontmatter mutation for `hewtd cite` (2.3.0 PR3).
+ *
+ * Inserts a `cites:` entry into the nearest `symptoms:` block in a playbook,
+ * or creates a new top-level `symptoms:` block if one doesn't exist.
+ * Idempotent: re-citing the same fact in the same symptom entry is a no-op.
+ *
+ * Round-trip safety: uses gray-matter to preserve body content. Frontmatter
+ * key order is preserved for keys that already existed; new keys (symptoms)
+ * append at the end.
+ */
+export interface CiteOptions {
+    /** Absolute path to the playbook file. */
+    playbookPath: string;
+    /** Fact id to insert into the symptoms block. */
+    factId: string;
+    /**
+     * Optional symptom identifier — if present, adds the citation to the
+     * matching entry. If absent, adds to the FIRST symptoms entry (or creates
+     * a single placeholder symptom).
+     */
+    symptomMatch?: {
+        alert_name?: string;
+        user_phrase?: string;
+        error_pattern?: string;
+    };
+    /** If true, returns the proposed content without writing the file. */
+    dryRun?: boolean;
+}
+export interface CiteResult {
+    playbookPath: string;
+    factId: string;
+    /** What we did: inserted, already_present (no-op), or created_block. */
+    action: 'inserted' | 'already_present' | 'created_block';
+    /** Index of the symptoms entry the citation was added to. */
+    symptomIndex: number;
+    /** The full new file content. */
+    newContent: string;
+}
+export declare function cite(options: CiteOptions): Promise<CiteResult>;
+//# sourceMappingURL=cite.d.ts.map

package/dist/core/knowledge-base/cite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cite.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/cite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,CAAC,EAAE;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,UAAU,GAAG,iBAAiB,GAAG,eAAe,CAAC;IACzD,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA2DpE"}

package/dist/core/knowledge-base/cite.js

@@ -0,0 +1,82 @@
+/**
+ * Frontmatter mutation for `hewtd cite` (2.3.0 PR3).
+ *
+ * Inserts a `cites:` entry into the nearest `symptoms:` block in a playbook,
+ * or creates a new top-level `symptoms:` block if one doesn't exist.
+ * Idempotent: re-citing the same fact in the same symptom entry is a no-op.
+ *
+ * Round-trip safety: uses gray-matter to preserve body content. Frontmatter
+ * key order is preserved for keys that already existed; new keys (symptoms)
+ * append at the end.
+ */
+import { readFile, writeFile } from 'fs/promises';
+import matter from 'gray-matter';
+export async function cite(options) {
+    const { playbookPath, factId, symptomMatch, dryRun = false } = options;
+    const content = await readFile(playbookPath, 'utf-8');
+    const parsed = matter(content);
+    const data = (parsed.data ?? {});
+    const symptoms = Array.isArray(data.symptoms)
+        ? data.symptoms
+        : [];
+    let action;
+    let symptomIndex;
+    if (symptoms.length === 0) {
+        // No symptoms block — create one with a single placeholder entry.
+        symptoms.push({
+            alert_name: '<TODO: specify alert_name, user_phrase, or error_pattern>',
+            target: '<TODO: anchor>',
+            cites: [factId],
+        });
+        symptomIndex = 0;
+        action = 'created_block';
+    }
+    else {
+        // Find the target entry. If symptomMatch is provided, look for a match;
+        // otherwise default to the first entry.
+        let targetIdx = 0;
+        if (symptomMatch) {
+            const matched = symptoms.findIndex((s) => matchesSymptom(s, symptomMatch));
+            if (matched >= 0)
+                targetIdx = matched;
+        }
+        const entry = symptoms[targetIdx];
+        const cites = Array.isArray(entry.cites) ? entry.cites : [];
+        if (cites.includes(factId)) {
+            action = 'already_present';
+        }
+        else {
+            cites.push(factId);
+            entry.cites = cites;
+            action = 'inserted';
+        }
+        symptomIndex = targetIdx;
+    }
+    data.symptoms = symptoms;
+    const newContent = matter.stringify(parsed.content, data);
+    if (!dryRun && action !== 'already_present') {
+        await writeFile(playbookPath, newContent, 'utf-8');
+    }
+    return {
+        playbookPath,
+        factId,
+        action,
+        symptomIndex,
+        newContent,
+    };
+}
+function matchesSymptom(entry, match) {
+    if (match.alert_name && entry.alert_name === match.alert_name)
+        return true;
+    if (match.error_pattern && entry.error_pattern === match.error_pattern)
+        return true;
+    if (match.user_phrase) {
+        const ep = entry.user_phrase;
+        if (typeof ep === 'string' && ep === match.user_phrase)
+            return true;
+        if (Array.isArray(ep) && ep.includes(match.user_phrase))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=cite.js.map

package/dist/core/knowledge-base/cite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cite.js","sourceRoot":"","sources":["../../../src/core/knowledge-base/cite.ts"],"names":[],"mappings":"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"}

package/dist/core/knowledge-base/citers.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Citation graph walker for knowledge-base primitives (2.3.0).
+ *
+ * Builds the per-fact citation index from three source kinds:
+ *   - Facts (`<vault>/facts/<id>.md`) — the canonical fact corpus.
+ *   - Incident-facts bridges (`<vault>/incidents/<slug>/facts.md`) — produced /
+ *     strengthened / weakened edges.
+ *   - Playbooks (any file with `symptoms: [...]` frontmatter) — `cites` edges
+ *     from each symptom entry to the facts the playbook step depends on.
+ *
+ * Used by:
+ *   - `facts/INDEX.md` generator (PR2) — to compute citer counts per fact.
+ *   - `hewtd find-citers <fact-id>` CLI command (PR3) — typed structure output.
+ *   - Dangling-citation linting (future PR) — flags `cites:` pointing at
+ *     non-existent facts.
+ */
+export interface FactRef {
+    /** Fact id (from frontmatter `id:`). */
+    id: string;
+    /** Absolute path to the fact's markdown file. */
+    path: string;
+    /** Path relative to the project root (for stable, diff-friendly indexes). */
+    relPath: string;
+    /** Frontmatter title. */
+    title: string;
+    /** Confidence enum value, if present. */
+    confidence: string | undefined;
+    /** YYYY-MM-DD or null if missing/malformed. */
+    lastVerified: string | undefined;
+    /** Tags from frontmatter. */
+    tags: string[];
+}
+export interface IncidentRef {
+    /** Incident id (from narrative.md frontmatter `id:`). */
+    id: string;
+    /** Absolute path to the incident folder. */
+    folderPath: string;
+    /** Project-relative folder path. */
+    relFolderPath: string;
+    /** Frontmatter title from narrative.md. */
+    title: string;
+    /** YYYY-MM-DD. */
+    date: string | undefined;
+    severity: string | undefined;
+    resolution_status: string | undefined;
+    components: string[];
+    /** Fact ids produced by this incident (from facts.md). */
+    produced: string[];
+    strengthened: string[];
+    weakened: string[];
+}
+export interface PlaybookCitation {
+    /** Project-relative path to the playbook. */
+    relPath: string;
+    /** Absolute path. */
+    path: string;
+    /** Frontmatter title. */
+    title: string;
+    /** Anchor within the playbook (e.g. `#vault-down-auth-staging`). */
+    target: string;
+    /** Symptom kind that triggered the citation. */
+    kind: 'alert_name' | 'user_phrase' | 'error_pattern';
+    /** The matching key (string or array, depending on kind). */
+    key: string | string[];
+    severity: string | undefined;
+}
+export interface CiterIndex {
+    /** All discovered facts, keyed by id. */
+    facts: Map<string, FactRef>;
+    /** All discovered incident folders, keyed by id. */
+    incidents: Map<string, IncidentRef>;
+    /**
+     * Citation edges per fact id. A fact id appearing here may not have a
+     * matching entry in `facts` — that's a dangling citation, detected by
+     * the caller.
+     */
+    citers: Map<string, PlaybookCitation[]>;
+}
+/**
+ * Typed structure returned by `findCiters(factId)`. Matches the shape the
+ * `hewtd find-citers` CLI command will print and the structure documented
+ * in `docs/knowledge-base-primitives.md`.
+ */
+export interface FindCitersResult {
+    fact_id: string;
+    fact_exists: boolean;
+    citers: string[];
+    incidents_produced_in: string[];
+    incidents_strengthened_by: string[];
+    incidents_weakened_by: string[];
+}
+export interface BuildCiterIndexOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** Absolute path to the vault root (default config: <root>/.documentation/knowledge-base/). */
+    vaultRoot: string;
+    /**
+     * Glob patterns (absolute, project-rooted) used to scan playbooks for
+     * `symptoms:` frontmatter blocks. The walker filters by frontmatter
+     * presence — files without a `symptoms:` block are skipped quickly.
+     */
+    playbookGlobs: string[];
+}
+/**
+ * Walk the corpus and build a citer index. Designed to be cheap on no-vault
+ * trees: if the vault root doesn't exist, returns an empty index without
+ * scanning playbooks for symptoms (no point — no facts to cite).
+ */
+export declare function buildCiterIndex(options: BuildCiterIndexOptions): Promise<CiterIndex>;
+/**
+ * Public lookup: typed structure for one fact id. Matches the shape the
+ * `hewtd find-citers` CLI command prints.
+ */
+export declare function findCitersInIndex(index: CiterIndex, factId: string): FindCitersResult;
+/**
+ * Count distinct citers for a fact id. Used by the facts-index generator.
+ */
+export declare function citerCount(index: CiterIndex, factId: string): number;
+//# sourceMappingURL=citers.d.ts.map

package/dist/core/knowledge-base/citers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citers.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/citers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,OAAO;IACtB,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,eAAe,CAAC;IACrD,6DAA6D;IAC7D,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC;;;;OAIG;IACH,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAMD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAuDrB;AAiJD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,GACb,gBAAgB,CAyBlB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQpE"}