@theglitchking/hit-em-with-the-docs 2.2.0 → 2.4.0

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"}

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

@@ -0,0 +1,249 @@
+/**
+ * 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.
+ */
+import { readFile } from 'fs/promises';
+import { join, relative, resolve } from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+const isString = (v) => typeof v === 'string';
+const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+/**
+ * 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 async function buildCiterIndex(options) {
+    const { projectRoot, vaultRoot, playbookGlobs } = options;
+    const facts = new Map();
+    const incidents = new Map();
+    const citers = new Map();
+    // ----- Facts -----
+    const factFiles = await glob(join(vaultRoot, 'facts/*.md'), {
+        nodir: true,
+        absolute: true,
+    });
+    for (const factPath of factFiles) {
+        const ref = await readFactRef(factPath, projectRoot);
+        if (ref)
+            facts.set(ref.id, ref);
+    }
+    // ----- Incidents -----
+    const narrativeFiles = await glob(join(vaultRoot, 'incidents/*/narrative.md'), { nodir: true, absolute: true });
+    for (const narrativePath of narrativeFiles) {
+        const ref = await readIncidentRef(narrativePath, projectRoot);
+        if (ref)
+            incidents.set(ref.id, ref);
+    }
+    // Short-circuit: if no facts and no incidents, no point scanning playbooks.
+    if (facts.size === 0 && incidents.size === 0) {
+        return { facts, incidents, citers };
+    }
+    // ----- Playbook citations -----
+    // Cheap pre-filter: read each candidate file and skip if frontmatter has
+    // no `symptoms` key. Avoids paying for full YAML parse on every doc.
+    const playbookCandidates = new Set();
+    for (const pattern of playbookGlobs) {
+        const matches = await glob(pattern, { nodir: true, absolute: true });
+        for (const m of matches)
+            playbookCandidates.add(m);
+    }
+    for (const playbookPath of playbookCandidates) {
+        const cits = await extractPlaybookCitations(playbookPath, projectRoot);
+        for (const c of cits) {
+            // Each citation has a list of fact ids implicit in the symptoms entry.
+            const factIds = c.factIds;
+            for (const factId of factIds) {
+                const existing = citers.get(factId) ?? [];
+                existing.push(c.citation);
+                citers.set(factId, existing);
+            }
+        }
+    }
+    return { facts, incidents, citers };
+}
+async function readFactRef(path, projectRoot) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        const { data } = matter(content);
+        if (data.tier !== 'fact' || !isString(data.id))
+            return null;
+        const tags = isStringArray(data.tags) ? data.tags : [];
+        const lastVerified = normalizeDate(data.last_verified);
+        return {
+            id: data.id,
+            path,
+            relPath: relative(projectRoot, path),
+            title: isString(data.title) ? data.title : data.id,
+            confidence: isString(data.confidence) ? data.confidence : undefined,
+            lastVerified,
+            tags,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function readIncidentRef(narrativePath, projectRoot) {
+    try {
+        const narrativeContent = await readFile(narrativePath, 'utf-8');
+        const { data: narrative } = matter(narrativeContent);
+        if (narrative.tier !== 'incident-narrative' || !isString(narrative.id)) {
+            return null;
+        }
+        const folderPath = resolve(narrativePath, '..');
+        const factsMdPath = join(folderPath, 'facts.md');
+        let produced = [];
+        let strengthened = [];
+        let weakened = [];
+        try {
+            const factsContent = await readFile(factsMdPath, 'utf-8');
+            const { data: facts } = matter(factsContent);
+            if (facts.tier === 'incident-facts') {
+                if (isStringArray(facts.produced))
+                    produced = facts.produced;
+                if (isStringArray(facts.strengthened))
+                    strengthened = facts.strengthened;
+                if (isStringArray(facts.weakened))
+                    weakened = facts.weakened;
+            }
+        }
+        catch {
+            // facts.md missing — incident has no produced/strengthened/weakened edges
+        }
+        return {
+            id: narrative.id,
+            folderPath,
+            relFolderPath: relative(projectRoot, folderPath),
+            title: isString(narrative.title) ? narrative.title : narrative.id,
+            date: normalizeDate(narrative.date),
+            severity: isString(narrative.severity) ? narrative.severity : undefined,
+            resolution_status: isString(narrative.resolution_status)
+                ? narrative.resolution_status
+                : undefined,
+            components: isStringArray(narrative.components) ? narrative.components : [],
+            produced,
+            strengthened,
+            weakened,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function extractPlaybookCitations(playbookPath, projectRoot) {
+    try {
+        const content = await readFile(playbookPath, 'utf-8');
+        const { data } = matter(content);
+        if (!Array.isArray(data.symptoms) || data.symptoms.length === 0) {
+            return [];
+        }
+        const title = isString(data.title) ? data.title : playbookPath;
+        const results = [];
+        for (const sym of data.symptoms) {
+            const s = sym;
+            if (!isString(s.target) || !isStringArray(s.cites))
+                continue;
+            let kind;
+            let key;
+            if (isString(s.alert_name)) {
+                kind = 'alert_name';
+                key = s.alert_name;
+            }
+            else if (isStringArray(s.user_phrase) || isString(s.user_phrase)) {
+                kind = 'user_phrase';
+                key = s.user_phrase;
+            }
+            else if (isString(s.error_pattern)) {
+                kind = 'error_pattern';
+                key = s.error_pattern;
+            }
+            else {
+                continue; // malformed — caught by audit-strict, ignored here
+            }
+            results.push({
+                citation: {
+                    relPath: relative(projectRoot, playbookPath),
+                    path: playbookPath,
+                    title,
+                    target: s.target,
+                    kind,
+                    key,
+                    severity: isString(s.severity) ? s.severity : undefined,
+                },
+                factIds: s.cites,
+            });
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeDate(value) {
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString().slice(0, 10);
+    }
+    return undefined;
+}
+/**
+ * Public lookup: typed structure for one fact id. Matches the shape the
+ * `hewtd find-citers` CLI command prints.
+ */
+export function findCitersInIndex(index, factId) {
+    // Dedup citers by playbook relPath — multiple symptoms entries in the same
+    // playbook citing the same fact count as ONE citer.
+    const citerSet = new Set();
+    for (const c of index.citers.get(factId) ?? []) {
+        citerSet.add(c.relPath);
+    }
+    const incidents_produced_in = [];
+    const incidents_strengthened_by = [];
+    const incidents_weakened_by = [];
+    for (const inc of index.incidents.values()) {
+        if (inc.produced.includes(factId))
+            incidents_produced_in.push(inc.id);
+        if (inc.strengthened.includes(factId))
+            incidents_strengthened_by.push(inc.id);
+        if (inc.weakened.includes(factId))
+            incidents_weakened_by.push(inc.id);
+    }
+    return {
+        fact_id: factId,
+        fact_exists: index.facts.has(factId),
+        citers: [...citerSet].sort(),
+        incidents_produced_in: incidents_produced_in.sort(),
+        incidents_strengthened_by: incidents_strengthened_by.sort(),
+        incidents_weakened_by: incidents_weakened_by.sort(),
+    };
+}
+/**
+ * Count distinct citers for a fact id. Used by the facts-index generator.
+ */
+export function citerCount(index, factId) {
+    const list = index.citers.get(factId);
+    if (!list)
+        return 0;
+    // Distinct by playbook relPath (multiple symptoms in the same playbook
+    // citing the same fact count once).
+    const seen = new Set();
+    for (const c of list)
+        seen.add(c.relPath);
+    return seen.size;
+}
+//# sourceMappingURL=citers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"citers.js","sourceRoot":"","sources":["../../../src/core/knowledge-base/citers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,MAAM,MAAM,aAAa,CAAC;AA+FjC,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;AACpE,MAAM,aAAa,GAAG,CAAC,CAAU,EAAiB,EAAE,CAClD,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B;IAE/B,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAE1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;IAErD,oBAAoB;IACpB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE;QAC1D,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACrD,IAAI,GAAG;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,wBAAwB;IACxB,MAAM,cAAc,GAAG,MAAM,IAAI,CAC/B,IAAI,CAAC,SAAS,EAAE,0BAA0B,CAAC,EAC3C,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAChC,CAAC;IACF,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;QAC9D,IAAI,GAAG;YAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,4EAA4E;IAC5E,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;IAED,iCAAiC;IACjC,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACrE,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,MAAM,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,wBAAwB,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACvE,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,uEAAuE;YACvE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;YAC1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC1C,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC1B,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,IAAY,EACZ,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAEvD,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI;YACJ,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;YACpC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE;YAClD,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACnE,YAAY;YACZ,IAAI;SACL,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,aAAqB,EACrB,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,gBAAgB,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrD,IAAI,SAAS,CAAC,IAAI,KAAK,oBAAoB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAChD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAEjD,IAAI,QAAQ,GAAa,EAAE,CAAC;QAC5B,IAAI,YAAY,GAAa,EAAE,CAAC;QAChC,IAAI,QAAQ,GAAa,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC1D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;gBACpC,IAAI,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;oBAAE,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;gBAC7D,IAAI,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC;oBAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;gBACzE,IAAI,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC;oBAAE,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;YAC/D,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;QAED,OAAO;YACL,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,UAAU;YACV,aAAa,EAAE,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;YAChD,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE;YACjE,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC;YACnC,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YACvE,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CAAC,iBAAiB,CAAC;gBACtD,CAAC,CAAC,SAAS,CAAC,iBAAiB;gBAC7B,CAAC,CAAC,SAAS;YACb,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;YAC3E,QAAQ;YACR,YAAY;YACZ,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAOD,KAAK,UAAU,wBAAwB,CACrC,YAAoB,EACpB,WAAmB;IAEnB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACtD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;QAC/D,MAAM,OAAO,GAAgC,EAAE,CAAC;QAEhD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,GAA8B,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC;gBAAE,SAAS;YAE7D,IAAI,IAA8B,CAAC;YACnC,IAAI,GAAsB,CAAC;YAC3B,IAAI,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3B,IAAI,GAAG,YAAY,CAAC;gBACpB,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC;YACrB,CAAC;iBAAM,IAAI,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnE,IAAI,GAAG,aAAa,CAAC;gBACrB,GAAG,GAAG,CAAC,CAAC,WAAgC,CAAC;YAC3C,CAAC;iBAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC;gBACrC,IAAI,GAAG,eAAe,CAAC;gBACvB,GAAG,GAAG,CAAC,CAAC,aAAa,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,mDAAmD;YAC/D,CAAC;YAED,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE;oBACR,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;oBAC5C,IAAI,EAAE,YAAY;oBAClB,KAAK;oBACL,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,IAAI;oBACJ,GAAG;oBACH,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;iBACxD;gBACD,OAAO,EAAE,CAAC,CAAC,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,MAAc;IAEd,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,MAAM,yBAAyB,GAAa,EAAE,CAAC;IAC/C,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtE,IAAI,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9E,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QACpC,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE;QAC5B,qBAAqB,EAAE,qBAAqB,CAAC,IAAI,EAAE;QACnD,yBAAyB,EAAE,yBAAyB,CAAC,IAAI,EAAE;QAC3D,qBAAqB,EAAE,qBAAqB,CAAC,IAAI,EAAE;KACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,uEAAuE;IACvE,oCAAoC;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1,61 @@
+/**
+ * Fact-extraction writer (2.3.0 PR3).
+ *
+ * The CLI side of `hewtd extract-facts <incident-folder>`. Takes accepted
+ * fact specs and writes them to `<vault>/facts/<id>.md` with provenance
+ * auto-populated to the source incident folder. Idempotent — re-running
+ * with an already-committed fact spec is a no-op.
+ *
+ * The LLM proposal step (read narrative → suggest fact specs) lives in the
+ * `/hit-em-with-the-docs:extract-facts` slash command, NOT here. This
+ * module is the deterministic writer that the slash command invokes after
+ * the user accepts proposals.
+ */
+export interface FactSpec {
+    id: string;
+    title: string;
+    confidence: 'high' | 'medium' | 'low' | 'hypothesis';
+    verifyCommand?: string;
+    /** Claim paragraph (will be inserted as `## Claim`). */
+    claim: string;
+    /** Optional how-to-verify paragraph. */
+    howToVerify?: string;
+    /** Optional consequences paragraph. */
+    consequences?: string;
+    /** Optional tags (will be merged with auto-derived tags). */
+    tags?: string[];
+    /** Optional domains. Defaults to ['knowledge-base'] if not specified. */
+    domains?: string[];
+}
+export interface ExtractFactsOptions {
+    /** Absolute path to the incident folder (must contain narrative.md). */
+    incidentFolder: string;
+    /** Absolute path to the vault root. Facts go into `<vault>/facts/`. */
+    vaultRoot: string;
+    /** Project root for provenance relpath computation. */
+    projectRoot: string;
+    /** Accepted fact specs (already curated by the LLM proposer + user). */
+    accept: FactSpec[];
+    /** If true, returns the plan without writing files. */
+    dryRun?: boolean;
+}
+export interface ExtractedFact {
+    id: string;
+    factPath: string;
+    action: 'created' | 'already_exists';
+    content: string;
+}
+export interface ExtractFactsResult {
+    incidentId: string;
+    incidentFolder: string;
+    extractedFacts: ExtractedFact[];
+    /** Whether the incident's facts.md was updated. */
+    factsMdUpdated: boolean;
+    factsMdPath: string;
+}
+export declare function extractFacts(options: ExtractFactsOptions): Promise<ExtractFactsResult>;
+/**
+ * Re-export the resolved vault root so callers don't have to recompute it.
+ */
+export declare function defaultVaultRoot(projectRoot: string): string;
+//# sourceMappingURL=extract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAC;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,mDAAmD;IACnD,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAqG7B;AAsBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D"}

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

@@ -0,0 +1,132 @@
+/**
+ * Fact-extraction writer (2.3.0 PR3).
+ *
+ * The CLI side of `hewtd extract-facts <incident-folder>`. Takes accepted
+ * fact specs and writes them to `<vault>/facts/<id>.md` with provenance
+ * auto-populated to the source incident folder. Idempotent — re-running
+ * with an already-committed fact spec is a no-op.
+ *
+ * The LLM proposal step (read narrative → suggest fact specs) lives in the
+ * `/hit-em-with-the-docs:extract-facts` slash command, NOT here. This
+ * module is the deterministic writer that the slash command invokes after
+ * the user accepts proposals.
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { basename, dirname, join, relative, resolve } from 'path';
+import matter from 'gray-matter';
+export async function extractFacts(options) {
+    const { incidentFolder, vaultRoot, projectRoot, accept, dryRun = false } = options;
+    const narrativePath = join(incidentFolder, 'narrative.md');
+    const narrativeRaw = await readFile(narrativePath, 'utf-8');
+    const narrative = matter(narrativeRaw);
+    const incidentId = typeof narrative.data.id === 'string'
+        ? narrative.data.id
+        : basename(incidentFolder);
+    const provenanceRelPath = relative(projectRoot, incidentFolder).replace(/\\/g, '/');
+    const factsDir = join(vaultRoot, 'facts');
+    const today = new Date().toISOString().slice(0, 10);
+    const extractedFacts = [];
+    for (const spec of accept) {
+        const factPath = join(factsDir, `${spec.id}.md`);
+        if (existsSync(factPath)) {
+            extractedFacts.push({
+                id: spec.id,
+                factPath,
+                action: 'already_exists',
+                content: await readFile(factPath, 'utf-8'),
+            });
+            continue;
+        }
+        const frontmatter = {
+            title: spec.title,
+            tier: 'fact',
+            domains: spec.domains ?? ['knowledge-base'],
+            status: 'active',
+            last_updated: today,
+            id: spec.id,
+            confidence: spec.confidence,
+            last_verified: today,
+            provenance: [provenanceRelPath + '/'],
+            tags: spec.tags ?? [],
+        };
+        if (spec.verifyCommand) {
+            frontmatter.verify_command = spec.verifyCommand;
+        }
+        const body = renderFactBody(spec);
+        const content = matter.stringify(body, frontmatter);
+        if (!dryRun) {
+            await mkdir(dirname(factPath), { recursive: true });
+            await writeFile(factPath, content, 'utf-8');
+        }
+        extractedFacts.push({
+            id: spec.id,
+            factPath,
+            action: 'created',
+            content,
+        });
+    }
+    // Update incident's facts.md `produced:` list (idempotent — only adds new
+    // ids, never removes existing ones).
+    const factsMdPath = join(incidentFolder, 'facts.md');
+    let factsMdUpdated = false;
+    if (existsSync(factsMdPath)) {
+        const factsMdRaw = await readFile(factsMdPath, 'utf-8');
+        const factsMd = matter(factsMdRaw);
+        // Important: gray-matter caches parse results keyed by content. Mutating
+        // factsMd.data leaks across calls with identical input strings (notably
+        // in tests). Always build a fresh data object.
+        const existing = Array.isArray(factsMd.data.produced)
+            ? [...factsMd.data.produced]
+            : [];
+        const newIds = extractedFacts
+            .filter((e) => e.action === 'created')
+            .map((e) => e.id);
+        const toAdd = newIds.filter((id) => !existing.includes(id));
+        if (toAdd.length > 0) {
+            const newData = {
+                ...factsMd.data,
+                produced: [...existing, ...toAdd],
+                last_updated: today,
+            };
+            const newContent = matter.stringify(factsMd.content, newData);
+            if (!dryRun) {
+                await writeFile(factsMdPath, newContent, 'utf-8');
+            }
+            factsMdUpdated = true;
+        }
+    }
+    return {
+        incidentId,
+        incidentFolder,
+        extractedFacts,
+        factsMdUpdated,
+        factsMdPath,
+    };
+}
+function renderFactBody(spec) {
+    const sections = [];
+    sections.push(`# ${spec.title}`);
+    sections.push('');
+    sections.push('## Claim');
+    sections.push(spec.claim.trim());
+    sections.push('');
+    if (spec.howToVerify) {
+        sections.push('## How to verify');
+        sections.push(spec.howToVerify.trim());
+        sections.push('');
+    }
+    if (spec.consequences) {
+        sections.push('## Consequences');
+        sections.push(spec.consequences.trim());
+        sections.push('');
+    }
+    return '\n' + sections.join('\n');
+}
+/**
+ * Re-export the resolved vault root so callers don't have to recompute it.
+ */
+export function defaultVaultRoot(projectRoot) {
+    return resolve(projectRoot, '.documentation/knowledge-base');
+}
+//# sourceMappingURL=extract.js.map

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

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

package/dist/core/knowledge-base/fix-legacy-layout.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Migrate 2.3.0-buggy incident folders into the canonical layout (2.4.0).
+ *
+ * In 2.3.0, `hewtd migrate-incident <flat-file>` wrote the new folder
+ * AS A SIBLING of the flat file. When the flat file lived at the vault
+ * root (the documented example), the resulting folder ended up at
+ * `<vault-root>/<slug>/` instead of `<vault-root>/incidents/<slug>/`.
+ * The `incidents/INDEX.md` generator scans only the canonical path, so
+ * those folders were silently absent from the index.
+ *
+ * This module:
+ *   1. Detects legacy folders — anything matching `<vault-root>/<slug>/`
+ *      that contains a valid `narrative.md` AND isn't already under the
+ *      canonical `<vault-root>/incidents/` parent.
+ *   2. Moves them into `<vault-root>/incidents/<slug>/` (preserving any
+ *      `facts.md` / `evidence/` contents).
+ *   3. Rewrites `provenance:` references in any `<vault-root>/facts/*.md`
+ *      files that pointed at the old folder paths.
+ *
+ * Idempotent: re-running on a clean vault is a no-op with a status report.
+ */
+export interface FixLegacyLayoutOptions {
+    /** Absolute vault root. */
+    vaultRoot: string;
+    /** Project root — used for relative-path provenance rewrites. */
+    projectRoot: string;
+    /** If true, returns the plan without writing. */
+    dryRun?: boolean;
+}
+export interface MovedFolder {
+    /** Slug (folder basename), e.g. `2026-04-23-keycloak-idle-session`. */
+    slug: string;
+    /** Absolute source path (legacy). */
+    from: string;
+    /** Absolute destination path (canonical). */
+    to: string;
+}
+export interface RewrittenProvenance {
+    /** Absolute fact file path. */
+    factPath: string;
+    /** Old provenance string that was replaced. */
+    oldRef: string;
+    /** New provenance string. */
+    newRef: string;
+}
+export interface FixLegacyLayoutResult {
+    vaultRoot: string;
+    moved: MovedFolder[];
+    rewrittenProvenance: RewrittenProvenance[];
+    /** Paths that LOOKED like incident folders but were ambiguous. Reported but not moved. */
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    action: 'fixed' | 'no_op' | 'dry_run';
+}
+/**
+ * Discover and (optionally) relocate 2.3.0-layout incident folders.
+ */
+export declare function fixLegacyLayout(options: FixLegacyLayoutOptions): Promise<FixLegacyLayoutResult>;
+//# sourceMappingURL=fix-legacy-layout.d.ts.map

package/dist/core/knowledge-base/fix-legacy-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-legacy-layout.d.ts","sourceRoot":"","sources":["../../../src/core/knowledge-base/fix-legacy-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,MAAM,WAAW,sBAAsB;IACrC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,mBAAmB,EAAE,mBAAmB,EAAE,CAAC;IAC3C,0FAA0F;IAC1F,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAgKhC"}