validate-kb-extension

name	validate-kb-extension
description	Walk every feature in every domain-taxonomy markdown file and assert the 5 required KB extension sections (Inclusion, Success Criteria, Failure Scenarios, Cross-Tree Refs, Experiential) are present and non-empty. Also validates that cross-tree constraints reference real feature IDs.
user-invocable	false
model	haiku
allowed-tools	Read, Glob, Grep, Bash
deprecated	true
deprecated_note	#434 ProductOS realignment — superseded by the command model; retained for Phase E reference, not installed

validate-kb-extension

Model-invocable skill for verifying the KB domain-taxonomy catalog conforms to the extension conventions defined in core/components/memory/standards/rules/kb-extension.md. Invoked by the specify play's pre-flight (214.5) and as the 214.4 T22 acceptance check.

Purpose

Prevent shallow / incomplete KB entries from reaching the pipeline. A capability catalog with missing sections or dangling cross-tree constraint references produces downstream failures in configure-capabilities, enrich-capabilities, and generate-intent-epics. This skill is the single gate that enforces the contract.

Input

Receive from the calling agent:

• kb_root (string, required) — path to core/components/memory/knowledge/domain/ or the deployed equivalent
• constraints_path (string, required) — path to _cross-tree-constraints.yaml inside kb_root
• conventions_path (string, required) — path to core/components/memory/standards/rules/kb-extension.md (the contract)

Process

1. Enumerate domain-taxonomy files

Glob {kb_root}/*.md excluding _index.md and any file beginning with an underscore. Each matched file is a domain (user-management, commerce, payments, personalization, search, plus any new domains added later).

2. For each domain file, extract features

Features are headed by ### {PREFIX}-F\d+: where the prefix is domain-specific (UM, CM, PM, PS, SR, or any new prefix). Collect all feature IDs into an ordered list. A file with zero features is a structural failure — report and continue.

3. For each feature, validate the 5 required sections

Each feature must have these five H3 subsections nested under it, in any order:

• ### Inclusion
• ### Success Criteria
• ### Failure Scenarios
• ### Cross-Tree Refs
• ### Experiential

For each section, apply the section-specific rules from kb-extension-conventions.md:

Inclusion

• Exactly one line starting with - Default: containing one of mandatory, optional, or conditional (wrapped in bold markers **...** is allowed).
• Mandatory when, Conditional when, and Exclude when lines are optional but if present must reference project_profile.* expressions.

Success Criteria

• Minimum 2 bullet entries.
• Each entry must contain QUANTIFIED content. Heuristic: match at least one of:
  • Number + unit (e.g., 500ms, 5 seconds, 10GB, 95%, 10K concurrent)
  • Explicit comparison operator (<, >, <=, >=, =)
  • Named standard (WCAG 2.1 AA, SOC2, HIPAA, PCI-DSS, NIST)
• Vague entries like fast, secure, reliable (without a number or standard) are violations.

Failure Scenarios

• Minimum 2 bullet entries.
• Each entry must contain all three sub-fields in order: Scenario:, Impact:, Mitigation:. The sub-fields are indented bullets under the top-level entry.
• An entry missing any sub-field is a violation.

Cross-Tree Refs

• Either a list of entries matching CTC-\d+ (with a human-readable parenthetical) OR the literal text (none).
• Each CTC-NNN reference must exist in {constraints_path}. Dangling refs are violations.

Experiential

• Must contain Usage count: and Last promoted: fields at minimum.
• Scenarios observed and Common mistakes are optional but recommended.
• Bootstrap values are allowed: Usage count: 0, Last promoted: never.

4. Validate _cross-tree-constraints.yaml

• YAML must parse cleanly (use python3 -c 'import yaml; yaml.safe_load(open(path))').
• Top-level key must be constraints, a list.
• Each constraint must have: id (format CTC-\d+), description, condition, at least one action (implies_include / implies_exclude / implies_include_depth / implies_exclude_depth), and rationale.
• Every feature ID referenced in implies_include or implies_exclude must resolve to a real feature found in step 2. Dangling refs are violations.

5. Aggregate results

Build a validation report grouped by file and feature:

status: completed | failed
summary:
  total_files: <int>
  total_features: <int>
  passed_features: <int>
  failed_features: <int>
  constraint_count: <int>
  dangling_constraint_refs: <int>
files:
  user-management.md:
    status: pass | fail
    feature_count: <int>
    features:
      UM-F001:
        status: pass | fail
        violations:
          - section: "<section name>"
            rule: "<rule id>"
            detail: "<one-sentence explanation>"
      UM-F002: ...
  commerce.md: ...
constraints:
  status: pass | fail
  parse_ok: true | false
  dangling_refs:
    - constraint_id: "CTC-099"
       
       

Output

Return the validation report as the skill's output contract. On ANY failure (any feature missing a section, any dangling constraint ref, any YAML parse error), the top-level status is failed. On clean validation, status is completed.

The calling agent treats status: failed as a structured failure — the parent play halts and cycles back to the KB-editing author with the report.

Constraints

• NEVER modify any file. This skill is READ-ONLY.
• NEVER invoke other skills or agents. It operates directly on file contents.
• ALWAYS return a structured YAML report, even on success.
• ALWAYS read conventions_path first so the rules are checked against the contract — do not hard-code rules in skill logic.
• On YAML parse error in _cross-tree-constraints.yaml, abort the constraint-check phase and report the parse error. Feature validation continues independently.

Version

Field	Value
Version	0.1.0
Category	validation
Created	2026-04-14
Related	core/components/memory/standards/rules/kb-extension.md, core/components/memory/standards/schemas/intent-epic.yaml, core/components/memory/knowledge/domain/_cross-tree-constraints.yaml