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

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for hit-em-with-the-docs - Self-managing documentation system",
-    "version": "2.1.1"
+    "version": "2.3.0"
   },
   "plugins": [
     {
       "name": "hit-em-with-the-docs",
       "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
-      "version": "2.1.1",
+      "version": "2.3.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hit-em-with-the-docs",
   "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/README.md

@@ -9,6 +9,11 @@
 > [!IMPORTANT]
 > You still need to remember to use this plugin when creating documentation! As projects grow, documentation needs to be created and maintained. You'll need to invoke this plugin or ask an LLM to create documentation for your features, workflows, or infrastructure. This plugin must be invoked to create, update, or maintain your docs.
 
+> [!NOTE]
+> **New in 2.3.0:** the knowledge-base primitives layer. Three new tiers (`fact`, `incident-narrative`, `incident-facts`) for citable atomic claims and immutable postmortems, plus an optional `symptoms:` frontmatter field on any-tier playbooks for symptom→playbook routing with `cites:` to facts. Three new deterministic indexes (`facts/INDEX.md`, `incidents/INDEX.md`, `symptoms/INDEX.md`) auto-generate on `hewtd maintain` when a vault root exists. Five new CLI commands: `find-citers`, `audit-facts [--run-verify]`, `extract-facts`, `cite`, `migrate-incident`. New `audit --strict` flag for CI gating. New `/hit-em-with-the-docs:help` slash command for LLM orientation. Four authoring templates at `templates/knowledge-base/`. Full reference: [`docs/knowledge-base-primitives.md`](./docs/knowledge-base-primitives.md). Agent guide: [`docs/LLM-GUIDE.md`](./docs/LLM-GUIDE.md).
+>
+> **New in 2.2.0:** the `tier` enum gains a `"plan"` value for [persistent-planning](https://github.com/TheGlitchKing/persistent-planning) lg-mode artifacts (phase / task / atom / notes documents), and the `version` and `status` fields are now conditionally relaxed for plan-tier docs (plans use lifecycle status, not semver). Existing tiers (guide / standard / example / reference / admin) are unchanged. See [`docs/plan-tier-frontmatter.md`](./docs/plan-tier-frontmatter.md) for the full reference.
+
 ---
 
 ## Summary

package/commands/audit-facts.md

@@ -0,0 +1,25 @@
+---
+description: Audit knowledge-base facts for staleness; optionally re-verify a specific fact
+allowed-tools: Bash(npx:*)
+argument-hint: "[fact-id-to-verify]"
+---
+
+Arguments: $ARGUMENTS
+
+If `$ARGUMENTS` is empty:
+- Run `npx --no @theglitchking/hit-em-with-the-docs audit-facts --json` and parse the result.
+- Report to the user: list of stale facts (with how many days overdue) and any unverifiable facts (malformed `last_verified`).
+- For each stale fact, suggest one of three actions:
+  1. Re-verify it: `/hit-em-with-the-docs:audit-facts <fact-id>`
+  2. Mark it weakened (if the user knows it's no longer reliable): edit the fact's frontmatter `status: weakened`
+  3. Open an incident to investigate the divergence (use `/hit-em-with-the-docs:migrate-incident` or create a new incident folder)
+
+If `$ARGUMENTS` is a fact id:
+- Run `npx --no @theglitchking/hit-em-with-the-docs audit-facts --run-verify "$ARGUMENTS" --json` and parse the result.
+- If `updated` is `true`, confirm the new `last_verified` date to the user.
+- If the verify command failed (`exit_code != 0`), show the stdout and stderr, then ask the user how to proceed:
+  - Re-run the verify command after fixing the issue
+  - Mark the fact weakened
+  - Open an incident to track the divergence
+
+Wait for the user's decision before taking any further action.

package/commands/cite.md

@@ -0,0 +1,17 @@
+---
+description: Insert a cites: entry for a fact into a playbook's symptoms block
+allowed-tools: Bash(npx:*), Read
+argument-hint: "<fact-id> <playbook-path>"
+---
+
+Arguments: $ARGUMENTS
+
+Parse `$ARGUMENTS` as `<fact-id> <playbook-path>`.
+
+- If either is missing, ask the user for the missing one.
+- Confirm the fact exists by running `npx --no @theglitchking/hit-em-with-the-docs find-citers <fact-id> --json` and checking `fact_exists`. If the fact doesn't exist, tell the user and stop.
+- Read the playbook file to see its current `symptoms:` block (if any).
+- If the playbook has multiple `symptoms:` entries, ask the user which one to add the citation to. Offer them by alert_name / user_phrase / error_pattern.
+- Run `npx --no @theglitchking/hit-em-with-the-docs cite <fact-id> --file <playbook-path> --dry-run` first to show the proposed change. Get the user's confirmation.
+- On confirmation, re-run without `--dry-run` to write the change.
+- Suggest the user run `npx --no @theglitchking/hit-em-with-the-docs audit --strict` afterward to confirm the cited fact is valid.

package/commands/extract-facts.md

@@ -0,0 +1,66 @@
+---
+description: Propose 5-10 atomic facts from an incident narrative; user accepts/edits/rejects; commit accepted facts
+allowed-tools: Bash(npx:*), Read
+argument-hint: "<path-to-incident-folder>"
+---
+
+Arguments: $ARGUMENTS
+
+This is the **LLM-driven proposer** for the `hewtd extract-facts` workflow. Your job in this turn is to:
+
+1. **Read the incident narrative.** Open `<incident-folder>/narrative.md`. Skim the Timeline, Root Cause, Resolution, and Lessons Learned sections.
+2. **Propose 5-10 candidate facts.** Each candidate is a single atomic citable claim. Look for things like:
+   - "X reads/writes/depends-on Y under condition Z"
+   - "X fails when Y, but appears successful at the surface level"
+   - "X requires Y in order to Z"
+   - Specific timing windows, retry behaviors, exact log signatures, configuration gotchas
+   - Things that were SURPRISING during the incident (those make the best facts)
+3. **For each candidate, produce a FactSpec:**
+
+   ```json
+   {
+     "id": "<kebab-case-slug>",
+     "title": "<short human-readable claim>",
+     "confidence": "high | medium | low | hypothesis",
+     "claim": "<one-paragraph stating the atomic claim>",
+     "howToVerify": "<one paragraph on how to confirm it>",
+     "consequences": "<one paragraph on what this means in practice>",
+     "verifyCommand": "<optional one-line shell command that proves the claim>",
+     "tags": ["<tag-1>", "<tag-2>"],
+     "domains": ["<domain>"]
+   }
+   ```
+
+4. **Present the candidates to the user.** For each one, include:
+   - The proposed id, title, confidence
+   - A quote from the narrative justifying the fact
+   - The proposed verify_command (with caveat: it's LLM-derived, may need refinement)
+
+5. **Let the user accept / edit / reject each.** Don't proceed to step 6 until the user has signed off on the final list.
+
+6. **Commit accepted facts.** Construct a JSON array of the accepted FactSpec objects. Then run:
+
+   ```bash
+   npx --no @theglitchking/hit-em-with-the-docs extract-facts "<incident-folder>" --accept '<JSON-array>'
+   ```
+
+   The CLI is the **deterministic writer** — it writes the fact files with provenance auto-populated, and updates the incident's `facts.md` `produced:` list (idempotent).
+
+7. **Suggest next steps.** After commit, suggest:
+   - Run `npx --no @theglitchking/hit-em-with-the-docs audit --strict` to confirm the new facts validate cleanly
+   - Enrich relevant playbooks with `cites:` for the new facts via `/hit-em-with-the-docs:cite`
+
+## Quality bar for fact proposals
+
+Reject your own first instinct if any of these are true:
+- The proposed fact has "and" / "also" in the title — split into two facts
+- The proposed fact restates something obvious (e.g. "Vault is a secrets manager")
+- The proposed fact has no actionable consequences for future on-calls
+- The proposed verify_command would require an SSH'd shell on a remote host the LLM can't reach — flag it for the user as "verify manually" rather than including in `verify_command`
+
+## What NOT to do
+
+- **Do not commit facts without user sign-off.** Even if a fact looks obvious, the user accepts each one.
+- **Do not fabricate provenance or sources.** The CLI auto-populates `provenance` with the incident folder path; you don't need to set it.
+- **Do not propose more than 10 facts in one pass.** If the incident is rich, propose the top 10 and offer a second pass.
+- **Do not start writing `<vault>/facts/*.md` directly.** Always go through the `hewtd extract-facts --accept` CLI.

package/commands/find-citers.md

@@ -0,0 +1,16 @@
+---
+description: Show all playbooks and incidents that cite a given fact id
+allowed-tools: Bash(npx:*)
+argument-hint: "<fact-id>"
+---
+
+Arguments: $ARGUMENTS
+
+- If `$ARGUMENTS` is empty, ask the user which fact id to look up.
+- Otherwise, run `npx --no @theglitchking/hit-em-with-the-docs find-citers "$ARGUMENTS" --json` and parse the JSON output.
+
+Present the result to the user in a readable format:
+- If `fact_exists` is `false`, tell the user the fact id wasn't found and suggest running `/hit-em-with-the-docs:audit-facts` to see all known facts.
+- Otherwise, list the citers (playbook paths), incidents that produced it, and incidents that strengthened/weakened it.
+
+If any of the playbook paths look suspicious or out of place, flag them for the user.

package/commands/help.md

@@ -0,0 +1,86 @@
+---
+description: Brief the LLM on hit-em-with-the-docs' surface (commands, primitives, frontmatter contract, knowledge-base workflow) and orient the user.
+allowed-tools: Bash(npx:*), Read
+argument-hint: "[topic]"
+---
+
+Arguments: $ARGUMENTS
+
+You are working in a project that uses **`@theglitchking/hit-em-with-the-docs`** (hewtd) — a self-managing documentation system. Your job in this turn is to orient the user (and yourself) on hewtd's surface and offer a next step.
+
+## When the user invokes this command
+
+If `$ARGUMENTS` is empty, give a tight orientation (what hewtd does, the 5 most common workflows, the commands available). Don't dump everything — focus on what's actionable in this project's current state. End with a question: "What would you like to do?"
+
+If `$ARGUMENTS` matches one of the topics below, focus the orientation on that topic specifically:
+- `frontmatter` — explain the 22-field schema, the 9 tiers, and per-tier required fields
+- `knowledge-base` / `kb` — explain the 3 KB tiers + symptoms field; point at `docs/knowledge-base-primitives.md` and `templates/knowledge-base/`
+- `commands` — list every `hewtd` CLI command with a one-line purpose
+- `audit` — explain `hewtd audit` + `--strict`; explain when to use each
+- `integrate` — explain `hewtd integrate <file>` and when to use it
+- `templates` — list available templates with paths
+
+## What hewtd does (the one-paragraph brief)
+
+`hewtd` manages a `.documentation/` tree organized into 15 domains (security, devops, database, api, standards, testing, architecture, features, quickstart, procedures, workflows, agents, backups, troubleshooting, plans). Every document carries YAML frontmatter validated against a 22-field schema with 9 tiers (`guide`, `standard`, `example`, `reference`, `admin`, `plan`, `fact`, `incident-narrative`, `incident-facts`). It also generates auto-indexes, audits docs for compliance, checks links, and as of 2.3.0 manages a knowledge-base subtree at `.documentation/knowledge-base/` with citable facts, postmortem incidents, and playbook-symptom mappings.
+
+## The 5 most common workflows
+
+1. **Adding a new doc** — write the markdown with the right frontmatter, place it in the appropriate domain folder, run `hewtd maintain` to update indexes. Use `hewtd integrate <file>` if you have a raw markdown file that needs auto-classification first.
+2. **Checking doc health** — `hewtd audit` (errors + warnings) or `hewtd audit --strict` (KB-coded errors fail CI).
+3. **Creating a fact in the knowledge base (2.3.0+)** — copy `templates/knowledge-base/fact.template.md` into `<vault-root>/facts/<kebab-id>.md`, fill in required fields (`id`, `confidence`, `last_verified`, `provenance`).
+4. **Documenting an incident (2.3.0+)** — create `<vault-root>/incidents/YYYY-MM-DD-slug/` with both `narrative.md` and `facts.md` from the templates.
+5. **Enriching a playbook (2.3.0+)** — add a `symptoms:` block to a playbook's frontmatter; cite the facts the playbook depends on.
+
+## Commands available
+
+CLI (via `npx --no @theglitchking/hit-em-with-the-docs <cmd>` or `hewtd <cmd>` if globally installed):
+
+- `init` — scaffold a `.documentation/` tree
+- `maintain` — full maintenance pass (sync metadata, check links, audit, generate KB indexes)
+- `audit [--strict]` — compliance check
+- `link-check` — internal link validation
+- `metadata-sync` — backfill missing frontmatter fields
+- `integrate <file>` — auto-classify and place a raw markdown file
+- `discover patterns|anti-patterns|standards|dependencies` — extract conventions from source code
+- `report health|audit|links` — generate detailed reports
+- `list` — list all 15 domains
+- `search <query>` — search documentation
+
+Slash commands (Claude Code):
+- `/hit-em-with-the-docs:status` — installed version, update policy, hook state
+- `/hit-em-with-the-docs:policy [auto|nudge|off]` — get/set update policy
+- `/hit-em-with-the-docs:update` — pull the latest version
+- `/hit-em-with-the-docs:relink` — re-run skill linker
+- `/hit-em-with-the-docs:help` — this command
+
+## Frontmatter contract (the short version)
+
+**Required for every doc:** `title`, `tier`, `domains` (array, ≥1), `status`, `last_updated` (YYYY-MM-DD), `version` (semver).
+
+**Exception — lifecycle-tracked tiers** (`plan`, `fact`, `incident-narrative`, `incident-facts`): `version` is **optional**, and `status` is free-form. These tiers have their own required-field extensions:
+- `fact`: `id`, `confidence`, `last_verified`, `provenance` (≥1 entry)
+- `incident-narrative`: `id`, `date`, `severity`, `resolution_status`, `components`
+- `incident-facts`: `incident_id`, `produced` (may be empty)
+
+Full reference: `docs/knowledge-base-primitives.md` and `docs/plan-tier-frontmatter.md`.
+
+## Templates
+
+For knowledge-base authoring, four templates ship at `templates/knowledge-base/`:
+- `fact.template.md`
+- `incident-narrative.template.md`
+- `incident-facts.template.md`
+- `playbook-symptoms.template.md` (frontmatter snippet)
+
+When asked to create one of these, **read the template first**, replace every `<placeholder>` with concrete content, and run `hewtd audit --strict` on the parent dir to confirm.
+
+## Where to find more
+
+- **README.md** — full reference (long; use the index)
+- **docs/LLM-GUIDE.md** — concise agent-facing guide (this is the cheat sheet)
+- **docs/knowledge-base-primitives.md** — KB schema reference + error codes table
+- **docs/plan-tier-frontmatter.md** — plan-tier reference (added in 2.2.0)
+- **CHANGELOG.md** — recent changes, version history
+
+After giving the orientation, ask the user: "What would you like to do next?" and wait. Don't speculatively run commands.

package/commands/migrate-incident.md

@@ -0,0 +1,18 @@
+---
+description: Convert a legacy flat-file incident into the 2.3.0 folder form
+allowed-tools: Bash(npx:*), Read
+argument-hint: "<path-to-flat-incident.md>"
+---
+
+Arguments: $ARGUMENTS
+
+- If `$ARGUMENTS` is empty, ask the user for the path to the flat-file incident.
+- Read the flat file to understand its content and frontmatter.
+- Run `npx --no @theglitchking/hit-em-with-the-docs migrate-incident "$ARGUMENTS" --dry-run` to see the proposed migration plan (target folder, narrative.md content, facts.md skeleton).
+- Show the user the proposed plan:
+  - Where the new folder will live
+  - What the narrative.md frontmatter will look like (especially `severity`, `resolution_status`, `components` — these are required and may need user input if the original lacks them)
+  - That the facts.md will be a skeleton with empty `produced:` (the user will use `/hit-em-with-the-docs:extract-facts` after migration to populate it)
+- Ask the user to confirm or adjust any defaults (especially severity / components if they look wrong).
+- On confirmation, re-run without `--dry-run`. The original file is renamed to `<name>.md.migrated` for rollback safety.
+- After migration, suggest the user run `/hit-em-with-the-docs:extract-facts <target-folder>` to extract atomic facts from the narrative.

package/dist/action/core/audit/auditor.d.ts

@@ -1,8 +1,16 @@
+import { type KbErrorCode } from '../metadata/errors.js';
 export interface AuditOptions {
     docsPath: string;
     domain?: string;
     issuesOnly?: boolean;
     silent?: boolean;
+    /**
+     * Strict mode: when true, the `audit` CLI command will exit non-zero on
+     * ANY error-severity issue, including the warning-only knowledge-base
+     * checks (e.g. FACT_VERIFY_COMMAND_MULTILINE_SHEBANG). Has no effect on
+     * the AuditResult itself — it's a flag the CLI inspects.
+     */
+    strict?: boolean;
 }
 export interface AuditResult {
     totalFiles: number;
@@ -19,6 +27,12 @@ export interface AuditIssue {
     message: string;
     fixable: boolean;
     suggestion?: string;
+    /**
+     * Knowledge-base error code (2.3.0+), populated when this issue came from
+     * a KB-specific validator (fact / incident / symptoms). Lets tooling switch
+     * on specific violation kinds without substring-matching the message.
+     */
+    code?: KbErrorCode;
 }
 export interface AuditStats {
     metadataCompliance: number;

package/dist/action/core/audit/auditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/audit/auditor.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA4IpF;AA+ID;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAQ3B"}
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/audit/auditor.ts"],"names":[],"mappings":"AAWA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAM5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA4IpF;AA+JD;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAQ3B"}

package/dist/action/core/domains/classifier.d.ts

@@ -2,8 +2,22 @@
  * Document tier classification system.
  * Classifies documents into 5 tiers based on content structure.
  */
-export declare const TIERS: readonly ["guide", "standard", "example", "reference", "admin"];
+export declare const TIERS: readonly ["guide", "standard", "example", "reference", "admin", "plan", "fact", "incident-narrative", "incident-facts"];
 export type Tier = (typeof TIERS)[number];
+/**
+ * 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 declare const LIFECYCLE_TRACKED_TIERS: readonly ["plan", "fact", "incident-narrative", "incident-facts"];
+export type LifecycleTrackedTier = (typeof LIFECYCLE_TRACKED_TIERS)[number];
+export declare function isLifecycleTrackedTier(tier: unknown): tier is LifecycleTrackedTier;
 export interface TierDefinition {
     id: Tier;
     name: string;

package/dist/action/core/domains/classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/domains/classifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,KAAK,iEAAkE,CAAC;AACrF,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,CAgFzD,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,CA+GtE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAE5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAErD"}
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/domains/classifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,KAAK,yHAUR,CAAC;AACX,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,mEAKA,CAAC;AACrC,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAKlF;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,CAgJzD,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,CAmHtE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAE5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAErD"}

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

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

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

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