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

package/dist/action/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/action/core/knowledge-base/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/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/action/core/knowledge-base/migrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Flat-file incident → folder migration (2.3.0 PR3).
+ *
+ * Reads a legacy flat-file incident (e.g. `knowledge-base/2026-04-23-foo.md`)
+ * and converts it into the folder form:
+ *
+ *   <flat-file>.md  →  <slug>/narrative.md
+ *                      <slug>/facts.md (skeleton)
+ *                      <slug>/evidence/ (empty, ready for artifacts)
+ *
+ * Idempotent: re-running on an already-migrated incident detects the folder
+ * exists and warns + no-ops.
+ */
+export interface MigrateIncidentOptions {
+    /** Absolute path to the flat-file incident markdown. */
+    flatFilePath: string;
+    /** If true, returns the migration plan without writing. */
+    dryRun?: boolean;
+}
+export interface MigrateIncidentResult {
+    flatFilePath: string;
+    targetFolder: string;
+    action: 'migrated' | 'already_migrated' | 'dry_run';
+    narrativePath: string;
+    factsPath: string;
+    evidencePath: string;
+    /** What the narrative.md content will be. */
+    narrativeContent: string;
+    /** What the facts.md content will be. */
+    factsContent: string;
+}
+export declare function migrateIncident(options: MigrateIncidentOptions): Promise<MigrateIncidentResult>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/action/core/knowledge-base/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/knowledge-base/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAwGhC"}

package/dist/action/core/maintain/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/maintain/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAI3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA0JtF;AA4OD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAoBD"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/maintain/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAa3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,kBAAkB,CAAC;IACjC,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAoKtF;AAwRD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC,CAoBD"}

package/dist/action/core/metadata/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Error codes for knowledge-base primitive validation (introduced in 2.3.0).
+ *
+ * The schema's .refine() rules prefix their messages with one of these codes
+ * in square brackets, e.g. `[FACT_MISSING_ID] id is required when tier is "fact"`.
+ * The audit layer parses the code out of the message to populate AuditIssue.code,
+ * which lets CI and tooling switch on specific violation types without
+ * substring-matching prose.
+ *
+ * Codes are namespaced by primitive:
+ *   FACT_*       — facts
+ *   INCIDENT_*   — incident folders (narrative + facts.md)
+ *   PLAYBOOK_*   — playbook symptoms blocks (the symptoms: frontmatter field)
+ */
+export declare const KB_ERROR_CODES: {
+    readonly FACT_MISSING_ID: "FACT_MISSING_ID";
+    readonly FACT_ID_FILENAME_MISMATCH: "FACT_ID_FILENAME_MISMATCH";
+    readonly FACT_MISSING_PROVENANCE: "FACT_MISSING_PROVENANCE";
+    readonly FACT_INVALID_CONFIDENCE: "FACT_INVALID_CONFIDENCE";
+    readonly FACT_MISSING_LAST_VERIFIED: "FACT_MISSING_LAST_VERIFIED";
+    readonly FACT_VERIFY_COMMAND_MULTILINE_SHEBANG: "FACT_VERIFY_COMMAND_MULTILINE_SHEBANG";
+    readonly INCIDENT_FOLDER_MISSING_NARRATIVE: "INCIDENT_FOLDER_MISSING_NARRATIVE";
+    readonly INCIDENT_FOLDER_MISSING_FACTS: "INCIDENT_FOLDER_MISSING_FACTS";
+    readonly INCIDENT_NARRATIVE_MISSING_DATE: "INCIDENT_NARRATIVE_MISSING_DATE";
+    readonly INCIDENT_NARRATIVE_MISSING_SEVERITY: "INCIDENT_NARRATIVE_MISSING_SEVERITY";
+    readonly INCIDENT_NARRATIVE_INVALID_SEVERITY: "INCIDENT_NARRATIVE_INVALID_SEVERITY";
+    readonly INCIDENT_NARRATIVE_MISSING_RESOLUTION_STATUS: "INCIDENT_NARRATIVE_MISSING_RESOLUTION_STATUS";
+    readonly INCIDENT_NARRATIVE_INVALID_RESOLUTION_STATUS: "INCIDENT_NARRATIVE_INVALID_RESOLUTION_STATUS";
+    readonly INCIDENT_NARRATIVE_MISSING_COMPONENTS: "INCIDENT_NARRATIVE_MISSING_COMPONENTS";
+    readonly INCIDENT_FACTS_MISSING_INCIDENT_ID: "INCIDENT_FACTS_MISSING_INCIDENT_ID";
+    readonly INCIDENT_FACTS_MISSING_PRODUCED: "INCIDENT_FACTS_MISSING_PRODUCED";
+    readonly INCIDENT_FACTS_DANGLING_REF: "INCIDENT_FACTS_DANGLING_REF";
+    readonly PLAYBOOK_SYMPTOM_MISSING_KEY: "PLAYBOOK_SYMPTOM_MISSING_KEY";
+    readonly PLAYBOOK_SYMPTOM_MISSING_TARGET: "PLAYBOOK_SYMPTOM_MISSING_TARGET";
+    readonly PLAYBOOK_SYMPTOM_MISSING_CITES: "PLAYBOOK_SYMPTOM_MISSING_CITES";
+    readonly PLAYBOOK_SYMPTOM_DANGLING_CITE: "PLAYBOOK_SYMPTOM_DANGLING_CITE";
+};
+export type KbErrorCode = (typeof KB_ERROR_CODES)[keyof typeof KB_ERROR_CODES];
+/**
+ * Severity for each KB error code.
+ *
+ * Most violations are `error`. The shebang check on verify_command is `warning`
+ * because the spec calls it out as "warning only — multi-line is fine, shebang
+ * missing is OK". Dangling refs (facts referencing non-existent fact-ids, or
+ * playbook citations to non-existent fact-ids) are `error`.
+ */
+export declare const KB_ERROR_SEVERITY: Record<KbErrorCode, 'error' | 'warning'>;
+/**
+ * Format a code-prefixed error message. The audit layer parses the leading
+ * `[CODE]` to populate `AuditIssue.code` without losing the human-readable
+ * description.
+ */
+export declare function formatKbError(code: KbErrorCode, message: string): string;
+/**
+ * Extract a KB error code from a refine() message, if present. Returns null
+ * for messages that don't begin with `[CODE] `.
+ */
+export declare function parseKbErrorCode(message: string): {
+    code: KbErrorCode;
+    message: string;
+} | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/action/core/metadata/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/metadata/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,CAsBtE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAExE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS/C"}