Skip to content

Structural Enforcement

NON-NORMATIVE.

Most governance tools check if your policies are correct. Morphism checks if your repository actually matches those policies.

The 125/125 Blind Spot

Morphism's maturity scorer awarded a perfect 125/125 — governance docs present, CI wired, hooks installed, SSOT atoms hashed, functor laws verified, kappa gating active. By every semantic metric, the repository was fully compliant.

Then a manual audit found 10 structural issues hiding underneath that score:

  • 7 directories declared in SSOT scope that didn't exist on disk
  • Config references to a deleted skills/ directory
  • 225KB of stale audit artifacts referenced by nothing
  • A .gitlab-ci.yml left over from a previous CI system
  • Agent definitions using enum values not in their own schema

None of these violated any governance rule. The rules were correct. The repository just didn't match them.

What Structural Enforcement Catches

Semantic governance asks: "Are the policies well-formed?" Structural enforcement asks: "Does the filesystem match the policies?"

Layer Tool What it checks
Root layout layout_check.py Every file/dir at repo root is in an explicit allowlist. SSOT scope directories exist. Config globs resolve.
Orphan detection orphan_scan.py Scripts referenced by nothing. Docs linked from nowhere. Large files accumulating silently.
Config integrity config_integrity.py Agent definitions validate against their schema. State dimensions match the engine. Orchestrator kappa equals the product of its dependencies.
Temporal freshness governance_freshness.py Governance docs reviewed within 90 days. Handoff state current when branch is active.
Dependency health dependency_health.py No circular workspace deps. Every workspace:* resolves. Python/TS import boundaries respected.

Case Studies

Phantom Config References

The .morphism/config.json discovery section listed ".morphism/workflows/orchestrations/*.md" as a glob. The directory existed but had been reorganized — the orchestrations were moved into a flat structure. The glob matched zero files, silently.

layout_check.py catches this: every discovery glob must resolve to at least one file.

The Invisible Schema Violation

The orchestrator agent definition used "status": "beta" — a reasonable value that wasn't in the agent schema's enum (active, inactive, experimental, deprecated). No tool caught it because no tool validated agent JSON against its own schema.

config_integrity.py catches this: every .morphism/agents/*.json is validated against agent.schema.json using a minimal stdlib-only validator that checks required fields, types, enums, and numeric bounds.

225KB of Stale Inventory

Thirteen files in .morphism/ and docs/ totaling 225KB were referenced by nothing — no config, no docs, no scripts. They accumulated over weeks of iteration, each individually reasonable, collectively invisible.

orphan_scan.py catches this: files in .morphism/ not in the structural set or config are flagged. Docs not referenced by mkdocs.yml or other docs are flagged. Large files outside exclusion zones are flagged.

Dead CI Config

A .gitlab-ci.yml from the repository's pre-GitHub era survived migration. It defined stages, jobs, and artifacts for a CI system that no longer ran. It wasn't harmful — just confusing, and a sign that cleanup processes had gaps.

layout_check.py catches this: root-level files not in the allowlist are flagged immediately.

Integration

All five scripts run in CI via the drift-check.yml workflow. The pre-commit hook gates new root-level files against the layout allowlist. All scripts are stdlib-only Python, following the same patterns as existing governance scripts.

# Run all structural checks
python scripts/layout_check.py --check
python scripts/orphan_scan.py --check
python scripts/config_integrity.py --check
python scripts/governance_freshness.py --check
python scripts/dependency_health.py --check

Design Principles

  1. Stdlib-only. No pip install required. Same constraint as every other governance script.
  2. Exit 0/1. CI-friendly. --check mode returns 0 on pass, 1 on failure.
  3. Known exceptions. Pre-existing items are in explicit allowlists, not silently ignored. New violations are caught immediately.
  4. Composable. Each script checks one concern. They compose in CI and pre-commit without coupling.
  5. Grounded. Every check verifies filesystem state against a declared policy — not abstract rules, but concrete paths, files, and schemas.