tree-validator

Files (11)

• SKILL.md
• audit_coverage.py · scripts/
• audit_lo_semantics.py · scripts/
• detect_gaps.py · scripts/
• fix_swift_cio_neutrality.py · scripts/
• generate_hierarchy_report.py · scripts/
• llm_auto_heal_master_tree.py · scripts/
• master_tree_parser.py · scripts/
• scaffold_tree.py · scripts/
• validate_master_tree.py · scripts/
• validate_tree.py · scripts/

SKILL.md (first lines)

## Repository Structure

```
repo-root/
├── projects/
│   └── <project-slug>/
│       ├── output/
│       │   ├── fields.tsv
│       │   ├── subjects.tsv
│       │   ├── categories.tsv
│       │   ├── topics.tsv
│       │   ├── concepts.tsv
│       │   └── learning-objectives.tsv
│       └── .tree-validator/            # auto-scaffolded by script, no manual creation needed
│           └── reports/<timestamp>/{validation_report.md, coverage_report.md}
├── skills/
│   └── skills/tree-validator/scripts/
│       ├── validate_tree.py            # Validates referential integrity
│       ├── audit_coverage.py           # Performs reverse coverage audit against syllabus
│       ├── detect_gaps.py              # Detects 5 types of gaps (A, B, C, D, E)
│       ├── validate_master_tree.py     # Validates Master Tree integrity
│       ├── scaffold_tree.py            # Initializes project structure + TSV headers
│       ├── master_tree_parser.py       # Shared parser for Master Tree TSV
│       └── fix_swift_cio_neutrality.py # Fixes T6 violations (Swift-specific)
└── status.yaml                          # active_project + status of the most recent run
```

## N:N (Many-to-Many) Referential Integrity Rules

The Knowledge Graph supports **N:N (Many-to-Many)** relationships across all 5 tiers (comma-separated `,` values are supported in `field_codes`, `subject_codes`, `category_codes`, `topic_codes`, `concept_codes`).

`validate_tree.py` automatically verifies that **every parent code in a comma-separated list** must exist in the corresponding parent table.

## Validation & Acceptance Workflow

1. **Referential Integrity Validation (`/validate-tree`)**:
   - Run `python3 skills/tree-validator/scripts/validate_tree.py --project <slug> --fix`
   - Ensure 100% no `BROKEN_REFERENCE`, `ORPHAN_NODE`, or format errors.

2. **Reverse Coverage Audit Against Syllabus (`/audit-coverage`)**:
   - Run `python3 skills/tree-validator/scripts/audit_coverage.py --project <slug>`
   - Ensure 100% of the items in the source syllabus (`projects/<slug>/context/` or PDF) are covered by LO codes.
   - Generate a report at `projects/<slug>/.tree-validator/reports/<timestamp>/coverage_report.md`.

3. **Gap Detection (`/detect-gaps`)**:
   - Run `python3 skills/tree-validator/scripts/detect_gaps.py --project <slug>`
   - Detect 4 types of gaps: **A** (Concept without an LO), **B** (CIO missing child SIOs), **C** (Master Candidate not yet selected), **D** (CIO violates Marr's Tri-Level Test).
   - Generate a report at `projects/<slug>/.tree-validator/reports/<stamp>/gap_report.md`.

4. **Master Tree Validation (`/validate-master-tree`)**:
   - Run `python3 skills/tree-validator/scripts/validate_master_tree.py`
   - Validate referential integrity and detect collisions in the Master Tree (`mlo-knowlege-tree.tsv`).
   - **MUST PASS** before `/map-taxonomy` or `/build-tree` reads from the Master Tree (Gate §7).

5. **Project Initialization (`/init`)**:
   - Run `python3 skills/tree-validator/scripts/scaffold_tree.py <slug>`
   - Scaffold the project directory structure and 6 TSV files with standard headers. Update `status.yaml`.

From orchable/knowledge-graph-public, MIT.

More from orchable/knowledge-graph-public