Code: Executable Documentation Governance

λο.τ :: Vibecode → ExecutableDocumentation
     where τ ∈ {compiles, validates, runs, passes}

compound :: Knowledge → Response → Knowledge
compound K τ = K ∪ crystallize(assess(τ))

Metaschema

This skill is homoiconic: it enforces the same patterns it describes. The structure mirrors the content; the DAG below governs both skill loading and project governance.

┌─────────────────────────────────────────────────────────────────────┐
│                     PROGRESSIVE LOADING DAG                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  L0: SKILL.md (this file)                                          │
│      │  • Core laws, routing, quick patterns                       │
│      │  • Compound engineering integration                         │
│      │  • Always loaded (~500 lines)                               │
│      │                                                             │
│      ├──► L1: references/laws.md                                   │
│      │        • Seven Laws complete specification                  │
│      │        • Load when: implementing governance                 │
│      │                                                             │
│      ├──► L1: references/executable-doc.md                         │
│      │        • Tier hierarchy, conversion methodology             │
│      │        • Load when: converting docs to code                 │
│      │                                                             │
│      ├──► L1: references/patterns.md                               │
│      │        • TODO management, type documentation                │
│      │        • Load when: establishing patterns                   │
│      │                                                             │
│      ├──► L1: references/compound-engineering.md                   │
│      │        • K' = K ∪ crystallize(assess(τ))                   │
│      │        • Load when: crystallizing learnings                 │
│      │                                                             │
│      ├──► L1: references/abductive-learning.md                     │
│      │        • OHPT protocol for debugging                        │
│      │        • Load when: systematic debugging needed             │
│      │                                                             │
│      ├──► L2: scripts/preflight.py                                 │
│      │        • Execute directly for validation                    │
│      │        • Load when: customizing checks                      │
│      │                                                             │
│      ├──► L2: scripts/validate-skill.py                            │
│      │        • Self-validation (homoiconic)                       │
│      │        • Load when: validating this or other skills         │
│      │                                                             │
│      ├──► L2: hooks/*                                              │
│      │        • Hookify rules for governance + compound learning   │
│      │        • Install via: scripts/install-hooks.sh              │
│      │                                                             │
│      └──► L3: templates/*                                          │
│               • CI/CD configs                                      │
│               • Copy when: initializing projects                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

The Seven Laws

-- Core invariants (see references/laws.md for complete spec)
LAW_1: ∀f ∈ Features. deployed(f) ⟹ e2e_verified(f)
LAW_2: ∀e ∈ Executions. observable(e) ∧ traceable(e)
LAW_3: ∀r ∈ CriticalRules. script_enforced(r)
LAW_4: ∀pr ∈ PRs. merged(pr) ⟹ human_reviewed(pr)
LAW_5: ∀d ∈ AuthoritativeDoc. d ⊂ Codebase
LAW_6: compiles(d) ∨ validates(d) ⟹ current(d)
LAW_7: ∀plan ∈ Plans. expressed_as_todos(plan) ∧ in_code(plan)

Routing

def route(task: Task) -> Pipeline:
    """Route task to appropriate governance level."""
    
    if task.type == "simple_change":
        return R1_SINGLE  # Preflight only
    
    if task.type == "feature":
        return R2_COMPOSE  # Preflight → E2E → Log review
    
    if task.type in ["architecture", "governance", "release"]:
        return R3_FULL  # Full Seven Laws verification
    
    return R0_DIRECT  # No governance (rare)

Quick Start

1. Initialize Project Governance

# Copy governance templates to project
cp templates/ci.yml ./.github/workflows/

# Run preflight to verify setup
python scripts/preflight.py --init

# Install governance hooks (optional)
bash scripts/install-hooks.sh

2. Establish Executable Documentation

# BAD: External documentation (will drift)
# docs/api.md: "User endpoint returns JSON with name and email"

# GOOD: Type as documentation (compiles = current)
@dataclass
class UserResponse:
    """User endpoint response. If this compiles, docs are current."""
    name: str
    email: EmailStr
    created_at: datetime

3. Plan with TODOs

# Instead of external implementation plan, use in-code TODOs:

# TODO(auth-1,required): Implement password hashing
# Context: Security requirement SR-101
# Acceptance: bcrypt cost factor 12, no plaintext storage

# TODO(auth-2): Add rate limiting
# Context: Prevent brute force per SR-102
# Approach: Redis sliding window, 5 attempts/minute

async def login(credentials: LoginCredentials) -> AuthResult:
    # Implementation replaces TODOs as work completes
    pass

4. Validate Before Merge

# Run preflight (automatically runs in CI)
python scripts/preflight.py

# Check remaining TODOs
grep -rn "TODO(.*required" --include="*.py" --include="*.ts" src/

# Generate architecture diagram (from code, not hand-drawn)
npx madge --image docs/deps.svg src/

Executable Documentation Hierarchy

Governing Principle:

IF    types check       (T1)
AND   schemas validate  (T2)
AND   specs generate    (T3)
AND   migrations run    (T4)
AND   linters pass      (T5)
AND   todos resolved    (T7)
THEN  documentation IS current

Conversion Methodology

When documentation is needed, convert to code-based form:

def document_in_code(need: str) -> CodeDoc:
    """Convert documentation need to executable form."""
    
    # Priority order: higher tier = more trustworthy
    if can_express_as_type(need):
        return TypeDefinition(need)  # T1
    
    if can_express_as_schema(need):
        return SchemaDefinition(need)  # T2
    
    if can_express_as_linter_rule(need):
        return LinterRule(need)  # T5
    
    if can_express_as_test(need):
        return TestCase(need)  # T6, with tautology caveat
    
    if can_express_as_todo(need):
        return TODO(need)  # T7
    
    # Last resort: inline comment (T8)
    # NEVER external doc (T9)
    return InlineComment(need)

For complete conversion patterns, load: references/executable-doc.md

Preflight Script

Core validation that runs before every commit:

#!/bin/bash
# Minimal preflight example — run python scripts/preflight.py for full version

set -e

echo "=== PREFLIGHT: Executable Documentation Verification ==="

# T1: Types compile
npm run typecheck || { echo "❌ Types invalid"; exit 1; }

# T2: Schemas validate  
npm run validate:schemas || { echo "❌ Schemas invalid"; exit 1; }

# T5: Linting passes
npm run lint || { echo "❌ Linting failed"; exit 1; }

# T7: Required TODOs resolved
grep -rn "TODO(.*required" src/ && { echo "❌ Required TODOs remain"; exit 1; }

echo "✅ Preflight passed"

For complete preflight implementation, run: python scripts/preflight.py

TODO Categories

# Standard categories for TODO-based planning:

# TODO(feature-id): Standard task
# TODO(feature-id,required): Must complete before merge (blocks CI)
# TODO(feature-id,blocked:other): Waiting on dependency
# TODO(tech-debt): Known improvement needed
# TODO(security): Security-related (high priority)
# FIXME: Known bug requiring fix
# HACK: Temporary solution needing proper implementation

Lifecycle:

PLAN → Write TODOs at implementation points
DEVELOP → Implement, remove TODO when done
VERIFY → grep for remaining TODOs
COMPLETE → Zero required TODOs = feature complete

For TODO management, use: grep -rn "TODO(.*required" --include="*.py" --include="*.ts" src/

Unit Test Skepticism (LAW_3 Caveat)

# WARNING: AI writes tautological tests
# Test documents what code DOES, not what code SHOULD DO

# REQUIREMENT: "Users can log in with valid credentials"

# AI IMPLEMENTATION (buggy):
def authenticate(user, password):
    return True  # BUG: Always succeeds

# AI TEST (tautological):
def test_authenticate():
    assert authenticate("user", "pass") == True  # ✓ PASSES!
    # Test verifies implementation, not requirement

Mitigation:

• E2E tests verify actual behavior (LAW_1)
• Human review verifies intent (LAW_4)
• Unit tests provide regression protection only
• Trust hierarchy: E2E (0.9) > Review (0.75) > Unit (0.3)

Diagram Generation

Generate diagrams from code, never hand-draw:

# Dependency graph from imports
npx madge --image docs/deps.svg src/

# Type relationships
npx ts-diagram src/ > docs/types.mmd

# Database schema from migrations
pg_dump --schema-only | sqlt-graph > docs/schema.svg

# OpenAPI from annotations (generated = current)
npm run generate:openapi

Use standard tools: npx madge, npx ts-diagram, pg_dump | sqlt-graph

Self-Validation (Homoiconicity)

This skill validates itself using the same rules it prescribes:

# scripts/validate-skill.py validates:
# 1. SKILL.md under 500 lines ✓
# 2. References progressively loaded ✓
# 3. Scripts executable ✓
# 4. No external docs (only code-based) ✓
# 5. DAG structure maintained ✓

Run: python scripts/validate-skill.py code/

Compound Engineering

The self-improvement loop that makes knowledge recursive:

compound :: Knowledge → Response → Knowledge
compound K τ = K ∪ crystallize(assess(τ))

-- K grows monotonically; never loses valid knowledge
-- Crystallization compresses: raw experience → reusable pattern

The Compound Loop

Plan(K) → Execute → Assess → Compound(K→K')
   ↑                              |
   └────────── K' ────────────────┘

Each iteration makes the next easier, not harder.

Trigger Detection

Compound when resolution patterns detected:

Learning Crystallization

# Required schema for compounded learnings
date: YYYY-MM-DD
trigger: "what initiated learning"
domain: "coding|debugging|architecture|..."
observation: "what was observed"
hypothesis: "best explanation"
root_cause: "fundamental cause (not surface)"
solution: "what worked"
why_works: "mechanistic explanation"
prevention: "how to avoid in future"
vertices:
  - "[[shared concept 1]]"
  - "[[shared concept 2]]"
confidence: 0.85

Validation before adding to K:

• Has >=2 shared vertices with existing K
• Root cause is fundamental (not surface symptom)
• Solution is generalizable (not one-off)
• Prevention is actionable

For complete compound engineering spec, load: references/compound-engineering.md

Abductive Learning (OHPT Protocol)

Inference to the best explanation for systematic debugging:

O (Observation) → H (Hypothesis) → P (Prediction) → T (Test)

Quick Template

"""
O: [What was observed - be specific]
H: [Best explanation - testable, parsimonious]
P: [If H true, then... - observable consequences]
T: [Test result - confirms/refutes H]
"""

For complete OHPT protocol, load: references/abductive-learning.md

Hookify Integration

Governance enforcement through hookify rules:

Install hooks: bash scripts/install-hooks.sh

Integration Points

File Structure

code/
├── SKILL.md                    # This file (L0)
├── references/
│   ├── laws.md                 # Seven Laws complete spec (L1)
│   ├── executable-doc.md       # Tier system, conversion (L1)
│   ├── patterns.md             # TODO, types, diagrams (L1)
│   ├── compound-engineering.md # K' = K ∪ crystallize(assess(τ)) (L1)
│   └── abductive-learning.md   # OHPT debugging protocol (L1)
├── scripts/
│   ├── preflight.py            # Validation orchestration (L2)
│   ├── validate-skill.py       # Self-validation (L2)
│   └── install-hooks.sh        # Install governance hooks (L2)
├── templates/
│   └── ci.yml                  # GitHub Actions template (L3)
└── hooks/                      # Hookify governance + compound rules
    ├── hookify.law1-e2e-deploy.local.md
    ├── hookify.law2-observability.local.md
    ├── hookify.law5-external-docs.local.md
    ├── hookify.law6-compile-current.local.md
    ├── hookify.law7-required-todos.local.md
    ├── hookify.stop-checklist.local.md
    ├── hookify.tautological-tests.local.md
    ├── hookify.compound-learning.local.md      # Crystallize before stop
    ├── hookify.abductive-hypothesis.local.md   # OHPT in tests
    ├── hookify.knowledge-monotonicity.local.md # K never shrinks
    ├── hookify.vertex-sharing.local.md         # Require connections
    ├── hookify.inference-chain.local.md        # Complete reasoning
    └── hookify.pattern-crystallization.local.md # Extract on commit

Holarchic Structure

Every component is a complete holon:

SKILL (this file)
  ├── Contains: Complete governance framework
  ├── Validates: Itself via scripts/validate-skill.py
  └── Holons:
        ├── preflight.py
        │   ├── Contains: Complete validation pipeline
        │   ├── Validates: Project code
        │   └── Holons: Individual check functions
        │
        ├── hooks/*
        │   ├── Contains: Seven Laws enforcement rules
        │   ├── Validates: Via hookify plugin
        │   └── Holons: Individual law-specific rules
        │
        └── templates/*
            ├── Contains: Complete project setup
            ├── Validates: Via instantiation
            └── Holons: Individual config files

Scale invariance: λο.τ applies at every level—skill, script, function, line.

┌─────────────────────────────────────────────────────────────────┐
│  SEVEN LAWS          │  TRUST HIERARCHY    │  VERIFICATION     │
├──────────────────────┼─────────────────────┼───────────────────┤
│  1. E2E verified     │  Types (0.95)       │  Compiles         │
│  2. Observable       │  Schemas (0.95)     │  Validates        │
│  3. Script enforced  │  E2E (0.90)         │  Passes           │
│  4. Human reviewed   │  Review (0.75)      │  Approved         │
│  5. Code is doc      │  Unit (0.30)        │  (Low trust)      │
│  6. Compile=current  │  External (0.10)    │  (Will drift)     │
│  7. TODOs are plans  │                     │                   │
└──────────────────────┴─────────────────────┴───────────────────┘