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

package/dist/core/metadata/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/metadata/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqDxB;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKE,CAAC;AAE9B,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA2B,CAAC;AAC9D,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,eAAe,4EAOlB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAC,gBAAgB,CAI9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,+EAKxB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,mBAAmB,mTA4BtB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,CAYA;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,uBAAuB,CAAC;CAChC,CAYA;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,EAAE,CAIV;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAY5C;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,GACnB,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,gBAAgB,GAAG,MAAM,CAiB3E"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/metadata/schema.ts"],"names":[],"mappings":"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"}

package/dist/core/metadata/schema.js

@@ -1,10 +1,29 @@
 import { z } from 'zod';
-import { TIERS } from '../domains/classifier.js';
+import { TIERS, LIFECYCLE_TRACKED_TIERS, isLifecycleTrackedTier, } from '../domains/classifier.js';
+import { KB_ERROR_CODES, formatKbError } from './errors.js';
 /**
- * 22-field metadata schema for documentation files.
- * This schema validates the YAML frontmatter of documentation files.
+ * Metadata schema for documentation files (the YAML frontmatter contract).
+ *
+ * Universal fields: 22 across six groups (core / status / discovery / ownership
+ * / implementation / auto). Plus tier-specific extensions for the lifecycle-
+ * tracked tiers introduced in 2.2.0 (plan) and 2.3.0 (fact, incident-narrative,
+ * incident-facts), and an optional `symptoms:` field for playbook documents.
+ *
+ * Conditional rules (enforced by .refine() on the merged MetadataSchema):
+ *
+ *   1. `version` is optional in the base schema; required for tiers that
+ *      AREN'T in LIFECYCLE_TRACKED_TIERS. Lifecycle-tracked tiers (plan, fact,
+ *      incident-narrative, incident-facts) use status/last_verified, not semver.
+ *   2. `status` accepts any string in the base schema; conditionally restricted
+ *      to the doc-tier enum (draft|active|deprecated|archived) for tiers that
+ *      aren't lifecycle-tracked. Each lifecycle-tracked tier uses its own
+ *      status enum.
+ *   3. Each lifecycle-tracked tier has its own required-fields contract
+ *      (e.g. fact requires id+confidence+last_verified+provenance).
+ *   4. The optional `symptoms:` field, when present on any tier, must be an
+ *      array of valid symptom entries.
  */
-// Core Identity Fields (Required)
+// ----- Core schema groups (existing 22-field surface) -----
 const coreIdentitySchema = z.object({
     title: z.string().min(1, 'Title is required'),
     tier: z.enum(TIERS),
@@ -12,52 +31,230 @@ const coreIdentitySchema = z.object({
     audience: z.array(z.enum(['all', 'developers', 'devops', 'admin'])).default(['all']),
     tags: z.array(z.string()).default([]),
 });
-// Status & Lifecycle Fields (Required)
+const DOC_STATUS_VALUES = ['draft', 'active', 'deprecated', 'archived'];
+/**
+ * Date-shaped value preprocessor: js-yaml auto-converts unquoted `2026-05-14`
+ * style fields into Date objects. Real users writing markdown rarely quote
+ * their dates, so we accept both `Date` and string-formatted YYYY-MM-DD,
+ * normalizing to the latter. Added in 2.3.0 alongside the knowledge-base
+ * primitives; applied universally so existing tiers (with unquoted
+ * `last_updated:` fields) also benefit.
+ */
+const dateStringSchema = z.preprocess((v) => {
+    if (v instanceof Date && !Number.isNaN(v.getTime())) {
+        return v.toISOString().slice(0, 10);
+    }
+    return v;
+}, z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD format'));
 const statusSchema = z.object({
-    status: z.enum(['draft', 'active', 'deprecated', 'archived']),
-    last_updated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD format'),
-    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semver format (X.Y.Z)'),
+    status: z.string().min(1, 'status is required'),
+    last_updated: dateStringSchema,
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semver format (X.Y.Z)').optional(),
 });
-// Discovery & Navigation Fields (Optional)
 const discoverySchema = z.object({
     purpose: z.string().optional(),
     related_docs: z.array(z.string()).optional(),
     load_priority: z.number().min(1).max(10).optional(),
 });
-// Ownership & Maintenance Fields (Optional)
 const ownershipSchema = z.object({
     author: z.string().optional(),
     maintainer: z.string().optional(),
     review_frequency: z.enum(['weekly', 'monthly', 'quarterly', 'annually']).optional(),
 });
-// Implementation Fields (Optional)
 const implementationSchema = z.object({
     implementation_status: z.enum(['planned', 'in_progress', 'complete', 'deprecated']).optional(),
     tested: z.boolean().optional(),
     production_ready: z.boolean().optional(),
 });
-// Auto-generated Fields
 const autoGeneratedSchema = z.object({
     estimated_read_time: z.string().optional(),
     word_count: z.number().optional(),
-    last_validated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    last_validated: dateStringSchema.optional(),
     backlinks: z.array(z.string()).optional(),
 });
-/**
- * Complete 22-field metadata schema
- */
-export const MetadataSchema = coreIdentitySchema
+// ----- Knowledge-base extension fields (2.3.0) -----
+//
+// Every field below is optional at the type level — the conditional
+// .refine() rules on the merged MetadataSchema enforce per-tier requirements.
+const FACT_CONFIDENCE_VALUES = ['high', 'medium', 'low', 'hypothesis'];
+const INCIDENT_SEVERITY_VALUES = ['low', 'medium', 'high', 'critical'];
+const INCIDENT_RESOLUTION_VALUES = ['resolved', 'partial', 'open', 'planned'];
+const KEBAB_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const INCIDENT_ID_RE = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const knowledgeBaseSchema = z.object({
+    // Fact fields
+    id: z.string().min(1).optional(),
+    confidence: z.string().optional(),
+    last_verified: dateStringSchema.optional(),
+    verify_command: z.string().optional(),
+    provenance: z.array(z.string()).optional(),
+    sources: z.array(z.string()).optional(),
+    invalidated_by: z.array(z.string()).optional(),
+    working_dir: z.string().optional(),
+    // Incident-narrative fields
+    date: dateStringSchema.optional(),
+    severity: z.string().optional(),
+    resolution_status: z.string().optional(),
+    components: z.array(z.string()).optional(),
+    // Incident-facts fields
+    incident_id: z.string().optional(),
+    produced: z.array(z.string()).optional(),
+    strengthened: z.array(z.string()).optional(),
+    weakened: z.array(z.string()).optional(),
+    // Playbook symptoms (any tier may carry this)
+    symptoms: z
+        .array(z.object({
+        alert_name: z.string().optional(),
+        user_phrase: z.union([z.string(), z.array(z.string())]).optional(),
+        error_pattern: z.string().optional(),
+        severity: z.enum(INCIDENT_SEVERITY_VALUES).optional(),
+        target: z.string().min(1).optional(),
+        cites: z.array(z.string()).optional(),
+    }))
+        .optional(),
+});
+// ----- Merged base (no refinements yet) -----
+const _baseMergedSchema = coreIdentitySchema
     .merge(statusSchema)
     .merge(discoverySchema)
     .merge(ownershipSchema)
     .merge(implementationSchema)
-    .merge(autoGeneratedSchema);
+    .merge(autoGeneratedSchema)
+    .merge(knowledgeBaseSchema);
+// ----- Conditional refinements -----
 /**
- * Partial schema for documents that may have incomplete metadata
+ * `version` is required for any tier NOT in LIFECYCLE_TRACKED_TIERS.
  */
-export const PartialMetadataSchema = MetadataSchema.partial();
+const refineVersionRequired = (data) => isLifecycleTrackedTier(data.tier) || data.version !== undefined;
 /**
- * Required fields that must always be present
+ * `status` must be one of DOC_STATUS_VALUES for non-lifecycle-tracked tiers.
+ * Lifecycle-tracked tiers use their own status enums (free-form at this layer).
+ */
+const refineStatusEnum = (data) => isLifecycleTrackedTier(data.tier) ||
+    DOC_STATUS_VALUES.includes(data.status);
+/**
+ * Fact-tier required fields: id, confidence (enum), last_verified, provenance (≥1).
+ */
+const refineFactRequirements = (data) => {
+    if (data.tier !== 'fact')
+        return true;
+    const checks = [
+        typeof data.id === 'string' && data.id.length > 0,
+        typeof data.confidence === 'string' &&
+            FACT_CONFIDENCE_VALUES.includes(data.confidence),
+        typeof data.last_verified === 'string',
+        Array.isArray(data.provenance) && data.provenance.length > 0,
+    ];
+    return checks.every(Boolean);
+};
+/**
+ * Incident-narrative required fields: id, date, severity (enum),
+ * resolution_status (enum), components (array).
+ */
+const refineIncidentNarrativeRequirements = (data) => {
+    if (data.tier !== 'incident-narrative')
+        return true;
+    const checks = [
+        typeof data.id === 'string' && data.id.length > 0,
+        typeof data.date === 'string',
+        typeof data.severity === 'string' &&
+            INCIDENT_SEVERITY_VALUES.includes(data.severity),
+        typeof data.resolution_status === 'string' &&
+            INCIDENT_RESOLUTION_VALUES.includes(data.resolution_status),
+        Array.isArray(data.components),
+    ];
+    return checks.every(Boolean);
+};
+/**
+ * Incident-facts required fields: incident_id, produced (array, may be empty).
+ */
+const refineIncidentFactsRequirements = (data) => {
+    if (data.tier !== 'incident-facts')
+        return true;
+    const checks = [
+        typeof data.incident_id === 'string' && data.incident_id.length > 0,
+        Array.isArray(data.produced),
+    ];
+    return checks.every(Boolean);
+};
+/**
+ * Symptoms entries (any tier): each must have one of alert_name/user_phrase/
+ * error_pattern AND target AND non-empty cites array.
+ */
+const refineSymptomsEntries = (data) => {
+    if (!Array.isArray(data.symptoms))
+        return true;
+    for (const s of data.symptoms) {
+        const hasKey = s.alert_name !== undefined ||
+            s.user_phrase !== undefined ||
+            s.error_pattern !== undefined;
+        if (!hasKey)
+            return false;
+        if (typeof s.target !== 'string' || s.target.length === 0)
+            return false;
+        if (!Array.isArray(s.cites) || s.cites.length === 0)
+            return false;
+    }
+    return true;
+};
+// ----- Exported schema -----
+/**
+ * Complete metadata schema with all conditional refinements applied.
+ *
+ * Required fields by tier:
+ *   - Non-lifecycle-tracked (guide/standard/example/reference/admin):
+ *       title, tier, domains, status (enum), last_updated, version
+ *   - plan: title, tier, domains, status, last_updated (no version)
+ *   - fact: title, tier, domains, status, last_updated, id, confidence,
+ *       last_verified, provenance (no version)
+ *   - incident-narrative: title, tier, domains, status, last_updated,
+ *       id, date, severity, resolution_status, components (no version)
+ *   - incident-facts: title, tier, domains, status, last_updated,
+ *       incident_id, produced (no version)
+ */
+export const MetadataSchema = _baseMergedSchema
+    .refine(refineVersionRequired, {
+    message: 'version is required unless tier is plan, fact, incident-narrative, or incident-facts',
+    path: ['version'],
+})
+    .refine(refineStatusEnum, {
+    message: `status must be one of ${DOC_STATUS_VALUES.join('|')} for non-lifecycle-tracked tiers`,
+    path: ['status'],
+})
+    .refine(refineFactRequirements, {
+    message: formatKbError(KB_ERROR_CODES.FACT_MISSING_ID, 'fact tier requires id (kebab-case), confidence (high|medium|low|hypothesis), last_verified (YYYY-MM-DD), and provenance (≥1 entry)'),
+    path: ['fact'],
+})
+    .refine(refineIncidentNarrativeRequirements, {
+    message: formatKbError(KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_DATE, 'incident-narrative tier requires id, date (YYYY-MM-DD), severity (low|medium|high|critical), resolution_status (resolved|partial|open|planned), and components (array)'),
+    path: ['incident-narrative'],
+})
+    .refine(refineIncidentFactsRequirements, {
+    message: formatKbError(KB_ERROR_CODES.INCIDENT_FACTS_MISSING_INCIDENT_ID, 'incident-facts tier requires incident_id and produced (array, may be empty)'),
+    path: ['incident-facts'],
+})
+    .refine(refineSymptomsEntries, {
+    message: formatKbError(KB_ERROR_CODES.PLAYBOOK_SYMPTOM_MISSING_KEY, 'each symptoms[] entry requires one of alert_name|user_phrase|error_pattern AND a target AND a non-empty cites[] array'),
+    path: ['symptoms'],
+});
+/**
+ * Partial schema for documents that may have incomplete metadata.
+ * Built from the un-refined base so every field is optional regardless of
+ * tier — used by `hewtd fix` to identify incomplete docs.
+ */
+export const PartialMetadataSchema = _baseMergedSchema.partial();
+/**
+ * Required fields shared across all tiers.
+ *
+ * Note: `version` is conditionally required — it must be present for all
+ * tiers NOT in LIFECYCLE_TRACKED_TIERS. The list below preserves the
+ * historical 6-required-field contract for non-lifecycle docs; for lifecycle-
+ * tracked docs (plan/fact/incident-narrative/incident-facts), `version` is
+ * dropped and the per-tier extension fields are added by
+ * `getRequiredFieldsForTier()`.
+ *
+ * Prefer `getMissingRequiredFields(data)` for tier-aware checks rather than
+ * iterating REQUIRED_FIELDS directly.
  */
 export const REQUIRED_FIELDS = [
     'title',
@@ -68,16 +265,27 @@ export const REQUIRED_FIELDS = [
     'version',
 ];
 /**
- * Optional fields with their default values
+ * Tier-specific required-field extensions for lifecycle-tracked tiers.
+ *
+ * For each tier, these fields are required IN ADDITION to the universal
+ * five (title, tier, domains, status, last_updated). `version` is excluded.
  */
+const TIER_REQUIRED_EXTENSIONS = {
+    fact: ['id', 'confidence', 'last_verified', 'provenance'],
+    'incident-narrative': [
+        'id',
+        'date',
+        'severity',
+        'resolution_status',
+        'components',
+    ],
+    'incident-facts': ['incident_id', 'produced'],
+};
 export const OPTIONAL_FIELDS_DEFAULTS = {
     audience: ['all'],
     tags: [],
     backlinks: [],
 };
-/**
- * Auto-generated fields that should not be manually edited
- */
 export const AUTO_GENERATED_FIELDS = [
     'estimated_read_time',
     'word_count',
@@ -85,7 +293,9 @@ export const AUTO_GENERATED_FIELDS = [
     'backlinks',
 ];
 /**
- * All 22 field names
+ * All 22 universal field names (unchanged from 2.2.0). The 2.3.0 knowledge-
+ * base extension fields (id, confidence, etc.) are intentionally NOT in this
+ * list — they apply per-tier and would skew completeness calc on non-KB docs.
  */
 export const ALL_METADATA_FIELDS = [
     // Core Identity (5)
@@ -116,9 +326,6 @@ export const ALL_METADATA_FIELDS = [
     'last_validated',
     'backlinks',
 ];
-/**
- * Validate metadata against the schema
- */
 export function validateMetadata(data) {
     const result = MetadataSchema.safeParse(data);
     if (result.success) {
@@ -128,8 +335,212 @@ export function validateMetadata(data) {
     return { valid: false, errors };
 }
 /**
- * Validate partial metadata (for documents being fixed)
+ * Run all KB-specific validation predicates against a partial metadata object
+ * and return a typed error list. This is the entrypoint the audit layer uses
+ * for the knowledge-base primitives (fact / incident-narrative / incident-facts
+ * / symptoms).
+ *
+ * Unlike `validateMetadata()`, this does NOT require the base schema to pass
+ * first — it can run on partial / in-progress docs and surface ONLY the KB
+ * coded errors, which lets the auditor combine KB checks with its existing
+ * missing-required-fields reporting without duplicate output.
  */
+/**
+ * YAML dates (e.g. `date: 2026-05-14` unquoted) are auto-parsed by js-yaml
+ * into Date objects. We accept both `string` (YYYY-MM-DD) and `Date` as
+ * valid date-shaped values, so users don't have to quote dates manually.
+ */
+function isDateLike(value) {
+    if (typeof value === 'string')
+        return /^\d{4}-\d{2}-\d{2}$/.test(value);
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return true;
+    return false;
+}
+export function validateKnowledgeBaseFields(data) {
+    const errors = [];
+    const tier = typeof data.tier === 'string' ? data.tier : undefined;
+    // ----- Fact tier -----
+    if (tier === 'fact') {
+        if (typeof data.id !== 'string' || data.id.length === 0) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_MISSING_ID,
+                message: 'fact tier requires an id (kebab-case slug)',
+                path: 'id',
+            });
+        }
+        else if (!KEBAB_SLUG_RE.test(data.id)) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_MISSING_ID,
+                message: `fact id must be kebab-case (got: ${data.id})`,
+                path: 'id',
+            });
+        }
+        if (typeof data.confidence !== 'string') {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_INVALID_CONFIDENCE,
+                message: `fact tier requires confidence (one of ${FACT_CONFIDENCE_VALUES.join('|')})`,
+                path: 'confidence',
+            });
+        }
+        else if (!FACT_CONFIDENCE_VALUES.includes(data.confidence)) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_INVALID_CONFIDENCE,
+                message: `confidence must be one of ${FACT_CONFIDENCE_VALUES.join('|')} (got: ${data.confidence})`,
+                path: 'confidence',
+            });
+        }
+        if (data.last_verified === undefined || data.last_verified === null) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_MISSING_LAST_VERIFIED,
+                message: 'fact tier requires last_verified (YYYY-MM-DD)',
+                path: 'last_verified',
+            });
+        }
+        else if (!isDateLike(data.last_verified)) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_MISSING_LAST_VERIFIED,
+                message: `last_verified must be YYYY-MM-DD (got: ${String(data.last_verified)})`,
+                path: 'last_verified',
+            });
+        }
+        if (!Array.isArray(data.provenance) || data.provenance.length === 0) {
+            errors.push({
+                code: KB_ERROR_CODES.FACT_MISSING_PROVENANCE,
+                message: 'fact tier requires at least one provenance entry',
+                path: 'provenance',
+            });
+        }
+        // Warning: verify_command with TRULY multi-line content (multiple commands)
+        // but missing shebang. YAML's `|` block scalar leaves a trailing newline
+        // on single-line commands, so we trim first to avoid false positives.
+        if (typeof data.verify_command === 'string') {
+            const trimmed = data.verify_command.trim();
+            if (trimmed.includes('\n') && !trimmed.startsWith('#!')) {
+                errors.push({
+                    code: KB_ERROR_CODES.FACT_VERIFY_COMMAND_MULTILINE_SHEBANG,
+                    message: 'multi-line verify_command without a shebang line — fine, but consider adding `#!/usr/bin/env bash` for clarity',
+                    path: 'verify_command',
+                });
+            }
+        }
+    }
+    // ----- Incident-narrative tier -----
+    if (tier === 'incident-narrative') {
+        if (typeof data.id !== 'string' || data.id.length === 0) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_DATE,
+                message: 'incident-narrative tier requires an id (YYYY-MM-DD-slug)',
+                path: 'id',
+            });
+        }
+        else if (!INCIDENT_ID_RE.test(data.id)) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_DATE,
+                message: `incident id must match YYYY-MM-DD-<slug> (got: ${data.id})`,
+                path: 'id',
+            });
+        }
+        if (data.date === undefined || data.date === null) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_DATE,
+                message: 'incident-narrative tier requires date (YYYY-MM-DD)',
+                path: 'date',
+            });
+        }
+        else if (!isDateLike(data.date)) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_DATE,
+                message: `date must be YYYY-MM-DD (got: ${String(data.date)})`,
+                path: 'date',
+            });
+        }
+        if (typeof data.severity !== 'string') {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_SEVERITY,
+                message: `incident-narrative tier requires severity (${INCIDENT_SEVERITY_VALUES.join('|')})`,
+                path: 'severity',
+            });
+        }
+        else if (!INCIDENT_SEVERITY_VALUES.includes(data.severity)) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_INVALID_SEVERITY,
+                message: `severity must be one of ${INCIDENT_SEVERITY_VALUES.join('|')} (got: ${data.severity})`,
+                path: 'severity',
+            });
+        }
+        if (typeof data.resolution_status !== 'string') {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_RESOLUTION_STATUS,
+                message: `incident-narrative tier requires resolution_status (${INCIDENT_RESOLUTION_VALUES.join('|')})`,
+                path: 'resolution_status',
+            });
+        }
+        else if (!INCIDENT_RESOLUTION_VALUES.includes(data.resolution_status)) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_INVALID_RESOLUTION_STATUS,
+                message: `resolution_status must be one of ${INCIDENT_RESOLUTION_VALUES.join('|')} (got: ${data.resolution_status})`,
+                path: 'resolution_status',
+            });
+        }
+        if (!Array.isArray(data.components) || data.components.length === 0) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_NARRATIVE_MISSING_COMPONENTS,
+                message: 'incident-narrative tier requires at least one component',
+                path: 'components',
+            });
+        }
+    }
+    // ----- Incident-facts tier -----
+    if (tier === 'incident-facts') {
+        if (typeof data.incident_id !== 'string' || data.incident_id.length === 0) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_FACTS_MISSING_INCIDENT_ID,
+                message: 'incident-facts tier requires incident_id',
+                path: 'incident_id',
+            });
+        }
+        if (!Array.isArray(data.produced)) {
+            errors.push({
+                code: KB_ERROR_CODES.INCIDENT_FACTS_MISSING_PRODUCED,
+                message: 'incident-facts tier requires produced (array, may be empty)',
+                path: 'produced',
+            });
+        }
+    }
+    // ----- Symptoms entries (any tier) -----
+    if (Array.isArray(data.symptoms)) {
+        for (let i = 0; i < data.symptoms.length; i++) {
+            const s = data.symptoms[i];
+            const hasKey = typeof s.alert_name === 'string' ||
+                typeof s.user_phrase === 'string' ||
+                Array.isArray(s.user_phrase) ||
+                typeof s.error_pattern === 'string';
+            if (!hasKey) {
+                errors.push({
+                    code: KB_ERROR_CODES.PLAYBOOK_SYMPTOM_MISSING_KEY,
+                    message: `symptoms[${i}] must have one of alert_name, user_phrase, or error_pattern`,
+                    path: `symptoms[${i}]`,
+                });
+            }
+            if (typeof s.target !== 'string' || s.target.length === 0) {
+                errors.push({
+                    code: KB_ERROR_CODES.PLAYBOOK_SYMPTOM_MISSING_TARGET,
+                    message: `symptoms[${i}] requires a target (anchor or path)`,
+                    path: `symptoms[${i}].target`,
+                });
+            }
+            if (!Array.isArray(s.cites) || s.cites.length === 0) {
+                errors.push({
+                    code: KB_ERROR_CODES.PLAYBOOK_SYMPTOM_MISSING_CITES,
+                    message: `symptoms[${i}] requires at least one cite (fact id)`,
+                    path: `symptoms[${i}].cites`,
+                });
+            }
+        }
+    }
+    return errors;
+}
 export function validatePartialMetadata(data) {
     const result = PartialMetadataSchema.safeParse(data);
     if (result.success) {
@@ -139,30 +550,47 @@ export function validatePartialMetadata(data) {
     return { valid: false, errors };
 }
 /**
- * Get missing required fields
+ * Get missing required fields, respecting both the version-exemption for
+ * lifecycle-tracked tiers AND the tier-specific extension requirements.
+ *
+ *   - For non-lifecycle tiers: REQUIRED_FIELDS (all six, including version).
+ *   - For lifecycle-tracked tiers: REQUIRED_FIELDS minus 'version', plus
+ *     any tier-specific extensions from TIER_REQUIRED_EXTENSIONS.
  */
 export function getMissingRequiredFields(data) {
-    return REQUIRED_FIELDS.filter((field) => !(field in data) || data[field] === undefined || data[field] === null);
+    const tier = typeof data.tier === 'string' ? data.tier : undefined;
+    const isLifecycle = isLifecycleTrackedTier(tier);
+    const extensions = tier
+        ? (TIER_REQUIRED_EXTENSIONS[tier] ?? [])
+        : [];
+    const baseRequired = REQUIRED_FIELDS.filter((field) => {
+        if (field === 'version' && isLifecycle)
+            return false;
+        return true;
+    });
+    const allRequired = [...baseRequired, ...extensions];
+    return allRequired.filter((field) => {
+        const value = data[field];
+        if (value === undefined || value === null)
+            return true;
+        if (Array.isArray(value) && value.length === 0) {
+            // provenance and components are required to be non-empty arrays;
+            // produced (incident-facts) is allowed to be empty.
+            return field === 'provenance' || field === 'components';
+        }
+        return false;
+    });
 }
-/**
- * Get all missing fields (both required and optional)
- */
 export function getMissingFields(data) {
-    const required = REQUIRED_FIELDS.filter((field) => !(field in data) || data[field] === undefined);
+    const required = getMissingRequiredFields(data);
     const optional = ALL_METADATA_FIELDS.filter((field) => !REQUIRED_FIELDS.includes(field) &&
         !(field in data));
     return { required, optional };
 }
-/**
- * Calculate metadata completeness percentage
- */
 export function calculateMetadataCompleteness(data) {
     const presentFields = ALL_METADATA_FIELDS.filter((field) => field in data && data[field] !== undefined && data[field] !== null);
     return (presentFields.length / ALL_METADATA_FIELDS.length) * 100;
 }
-/**
- * Get field category
- */
 export function getFieldCategory(field) {
     if (['title', 'tier', 'domains', 'audience', 'tags'].includes(field)) {
         return 'core';
@@ -181,4 +609,6 @@ export function getFieldCategory(field) {
     }
     return 'auto';
 }
+// Re-export tier-related symbols that consumers (and the auditor) need.
+export { LIFECYCLE_TRACKED_TIERS, isLifecycleTrackedTier, DOC_STATUS_VALUES, FACT_CONFIDENCE_VALUES, INCIDENT_SEVERITY_VALUES, INCIDENT_RESOLUTION_VALUES, KEBAB_SLUG_RE, INCIDENT_ID_RE, TIER_REQUIRED_EXTENSIONS, };
 //# sourceMappingURL=schema.js.map