vm-gap-matrix

# vm-gap-matrix

## When to Use This Skill

- After every RE pipeline phase transition (mandatory gate check)
- In the QA-RETRY loop to determine which phases need re-processing
- When resuming an incremental run to assess current state
- Any time the orchestrator needs to know what is incomplete in checklist.json

## Unitary Function

**ONE responsibility:** Read checklist.json, count per-phase statuses, compute completion percentages against configurable thresholds, report pass/fail, and list gap files.

## NOT RESPONSIBLE FOR

- Fixing gaps (that is the orchestrator's retry loop)
- Validating artifact content quality (that is 3e Cross-Linker)
- Modifying checklist.json (read-only)
- Any AI analysis

## Input

```json
{
  "checklist_path": "docs/codebase-analysis/checklist.json",
  "output_path": "docs/codebase-analysis/intermediate/gap-matrix.json",
  "thresholds": {
    "discovery": 100,
    "signature_extraction": 95,
    "dependency_mapping": 90,
    "file_analysis": 80
  }
}
```

## Thresholds

| Phase Field | Default Threshold | Rationale |
|---|---|---|
| `discovery` | 100% | Every file must be classified |
| `signature_extraction` | 95% | Allows for non-extractable edge cases |
| `dependency_mapping` | 90% | Config/style files may not have deps |
| `file_analysis` | 80% | Deep-analysis target for actionable files; deterministic fallback covers rest |

## Script

Cross-platform Python script. No external dependencies.

```python
#!/usr/bin/env python3
"""
vm-gap-matrix: Deterministic quality gate for RE pipeline.
Reads checklist.json, computes per-phase completion %, writes gap-matrix.json.
Exit code 0 = all gates pass, 1 = gaps remain.
"""
import json, codecs, os, sys
from collections import Counter

def run_gap_matrix(checklist_path, output_path, thresholds=None):
    if thresholds is None:
        thresholds = {
            "discovery": 100,
            "signature_extraction": 95,
            "dependency_mapping": 90,
            "file_analysis": 80,
        }

    with codecs.open(checklist_path, "r", "utf-8-sig") as f:
        checklist = json.load(f)

    files = checklist.get("files", [])
    total = len(files)

    phases = {}
    overall_pass = True

    for phase_field, threshold in thresholds.items():
        counts = Counter(f.get(phase_field, "missing") for f in files)

        completed = counts.get("completed", 0) + counts.get("completed-deterministic", 0)
        not_started = counts.get("not-started", 0) + counts.get("missing", 0)
        error = counts.get("error", 0)
        not_applicable = counts.get("not-applicable", 0)
        actionable = total - not_applicable

        if actionable == 0:
            completion_pct = 100.0
        else:
            completion_pct = round(completed / actionable * 100, 1)

        status = "PASS" if completion_pct >= threshold else "FAIL"
        if status == "FAIL":
            overall_pass = False

        # Collect gap file IDs (files still needing work)
        gap_file_ids =