concept-integrity

Files (15)

• SKILL.md
• apply_master_repair.py · scripts/
• apply_t6_fixes.py · scripts/
• audit_granularity.py · scripts/
• concept_dedup_detector.py · scripts/
• concept_proposer_judge.py · scripts/
• concept_repair.py · scripts/
• flatten_master_tree.py · scripts/
• generate_master_repair_manifest.py · scripts/
• llm_full_tree_hierarchy_validator.py · scripts/
• llm_semantic_validator.py · scripts/
• llm_t6_judge.py · scripts/
• run_granularity.py · scripts/
• translate_master_tree.py · scripts/
• verify_with_cs2023.py · scripts/

SKILL.md (first lines)

# Concept Integrity

> **Goal:** You are the `@concept-integrity-validator`. Your job is to ensure every Concept node in the Knowledge Graph is unique, well-bounded, and correctly referenced across all downstream artifacts (LOs, prerequisites, Supabase).

## Why This Skill Exists

Existing validation (`validate_tree.py`, `detect_gaps.py`) checks **structural** integrity (referential links, code format, orphans). This skill fills the **semantic** integrity gap:

1. Two concepts with different codes but overlapping meaning (e.g. `KEY_VALUE_STORAGE` vs `DICTIONARY`)
2. A concept that should be a "resource" (product/vendor) rather than a learning unit
3. A concept that is too broad (should be split) or too narrow (should be merged)
4. Local TSV ↔ Supabase DB drift after repairs

## Architecture: Retrieve → Propose → Judge → Repair

```
                                ┌──────────────┐
   candidate phrase ──────────▶ │ 1. Retrieval │ (embedding neighbors from Master Tree)
                                └──────┬───────┘
                                       ▼
                                ┌──────────────┐
   neighbors + source_excerpt ▶ │ 2. Proposer  │ (LLM: reuse/create/split/merge/resource)
                                └──────┬───────┘
                                       ▼
                                ┌──────────────┐
   proposer output ────────────▶│ 3. Judge     │ (LLM: independent rule-by-rule audit)
                                └──────┬───────┘
                                       ▼
                              approve / request_revision (max 3) / reject
                                       ▼
                                ┌──────────────┐
   repair manifest ────────────▶│ 4. Repair    │ (cascade rename/merge across TSVs)
                                └──────────────┘
```

## Scripts

| Script | Purpose |
|--------|---------|
| `concept_dedup_detector.py` | Detect semantic duplicates + boundary conflicts across Master Tree and project concepts |
| `concept_proposer_judge.py` | 2-agent (Proposer + Judge) architecture for concept splitting decisions |
| `concept_repair.py` | Cascade repair (rename/merge/delete) across project TSVs + Supabase drift detection |

## Workflow

```bash
# Detect-only (default)
/validate-concepts --project <slug>

# Detect + repair (with approval gate)
/validate-concepts --project <slug> --fix

# Include Supabase drift check
/validate-concepts --project <slug> --check-supabase
```

## When to Run

- **After `/build-tree`** — validate concept selection before generating LOs
- **After `/escalate-concepts`** — validate new concept proposals against existing graph
- **Before `/sync-supabase`** — ensure no semantic duplicates will be pushed
- **Periodic maintenance** — detect drift accumulated over multiple project runs

## Integration Points

| Existing Tool | Integration |
|---|---|
| `detect_gaps.py` | Gap F (SEMANTIC_DUPLICATE) added, calls `concept_dedup_detector` as module |
| `agent_as_judge.py` | Concept Judge reuses same LLM call infrastructure |
| `semantic_search_master.py` | Retrieval step reuses embedding search logic |
| `validate_tree.py` | Structural integrity must PASS before running concept integrity |

## Rules

- **Never auto-merge** concepts without approval (Gate §4, §10)
- **Dry-run first**: All repair operations default to `--dry-run`
- **Backup before write**: Every TSV modification creates `.bak` file
- **Max 3 revision rounds** in Proposer↔Judge loop; after that → manual queue
- **Supabase writes require explicit approval** (Gate §8)

From orchable/knowledge-graph-public, MIT.

More from orchable/knowledge-graph-public