feat(drift): tangle_ratio hygiene gate — the antisymmetry half of health (#186) (#241)

Adds tangle_ratio = Σ Mᵢ·tᵢ / 3 (normalized transpose-fixed mutual-motif mass)
as a hygiene gate, the symmetric partner of cycle_ratio — closing the
antisymmetry half of health = acyclicity + antisymmetry. Pure gate (weight 0 in
drift_score), default max=0.25 (empirically bracketed: cgis 0.036 / owner-api
0.078 / mesh ~1.0), ratchet-able via hygiene_baseline. Exposed in the cgis_drift
MCP payload; self-parsing guard hardened to fail on any hygiene gate_failed.

Follow-up #244: discount the CALLS layer by (1 - unresolved_ratio).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: zaebee

docs/architecture/PATTERNS_AND_TRIADS.md

@@ -67,6 +67,24 @@ A macro-graph whose census mass sits in this tail (e.g. a frontend where
 `store ↔ components ↔ hooks`) is genuinely **meshed**, not layered — a signal no
 fan-out/fan-in/chain template can represent (see Part 3 and issue #186).
 
+### `tangle_ratio` — the antisymmetry gate
+
+The total mass of this tail is captured by one hygiene number,
+**`tangle_ratio` = `Σ Mᵢ · tᵢ / 3`**, where `Mᵢ` is the MAN mutual-dyad count of
+class `i` (the first digit: `111*`/`120*` → 1, `201`/`210` → 2, `300` → 3) and
+`tᵢ` is its normalized census fraction. A mutual dyad `A ↔ B` is its own
+*transpose*; `300` is the maximal fixed point. So `tangle_ratio` is the
+**transpose-fixed mass**: an *antisymmetric* graph — no mutual dyads, i.e. only
+`021*`/`030T`/`030C` (cycles included — acyclicity is `cycle_ratio`'s job,
+orthogonal to tangle) — scores 0, a pure mesh (`300`) scores 1. It is measured as `max` over the IMPORTS and CALLS layers
+(the worst layer breaches).
+
+It is the symmetric partner of `cycle_ratio`. Together they complete the health
+predicate **`health = acyclicity + antisymmetry`**: `cycle_ratio` rejects the
+cyclic back-edge (`030C`), `tangle_ratio` rejects mutual coupling (`M ≥ 1`). It is
+a hard hygiene gate (`tangle_ratio: {max: …}` under `hygiene:`), ratchet-able per
+domain via `hygiene_baseline: {tangle_ratio: …}` (#151).
+
 ### How it's computed
 
 `triad_census(node_ids, edges, edge_type)` walks every connected triple, encodes
@@ -126,8 +144,8 @@ A domain's **drift score** combines, per the active profile's weights
    pattern's `imports` ideal.
 2. **`calls` layer** — same over CALLS, discounted by `(1 − unresolved_ratio)`
    (a domain whose calls are mostly unresolved gets its calls-evidence faded).
-3. **`gates` layer** — hygiene invariants (`cycle_ratio`, `unresolved_ratio`)
-   and template constraints (`dag_depth`, …).
+3. **`gates` layer** — hygiene invariants (`cycle_ratio`, `unresolved_ratio`,
+   `tangle_ratio`) and template constraints (`dag_depth`, …).
 
 **Total-variation (TV) distance** between two 13-vectors `p`, `q` is
 `½ · Σ wᵢ · |pᵢ − qᵢ|` — where `wᵢ` are per-triad weights from the profile's

docs/ontology/patterns.yaml

@@ -52,6 +52,7 @@ profiles:
 hygiene:
   cycle_ratio:      {max: 0.0}
   unresolved_ratio: {max: 0.2}
+  tangle_ratio:     {max: 0.25}
 
 # ── The closed alphabet: five templates (spec §2.1, §3.3) ────────────────────
 # ideal: hand-authored points in 13-triad space, one per layer, each summing

docs/specs/2026-06-13-tangle-anti-pattern-design.md

@@ -0,0 +1,148 @@
+# `tangle_ratio` hygiene gate — design (#186)
+
+**Status:** approved (2026-06-13)
+**Issue:** #186 (recursive-quotient / pattern-algebra macro track), deliverable 1 of 3
+**Lane:** A (drift / ontology / query)
+
+## Goal
+
+Add a `tangle_ratio` hygiene invariant — the normalized mass of transpose-fixed
+(mutual) triad motifs — as the symmetric partner of the existing `cycle_ratio`
+gate, closing the **antisymmetry** half of the health predicate
+`health = acyclicity + antisymmetry`.
+
+## Motivation
+
+The drift subsystem enforces **acyclicity** via the `cycle_ratio` gate (catches
+`030C` back-edge loops). It does **not** enforce **antisymmetry**: a domain made
+entirely of mutual coupling (`M ≥ 1` triads — `111*`, `120*`, `201`, `210`, `300`)
+passes every gate today. The #186 9-repo census found `rider-web` is ~100% tangle
+and sails through clean. That is an unnamed product gap.
+
+Pattern algebra (validated on #186): the 13-triad space partitions under the
+transpose operator `ᵀ`. **Patterns** are the antisymmetric part (`ᵀ` flips
+`021D↔021U`, fixes acyclic `021C`/`030T`). **Anti-patterns** are the
+transpose-*fixed* mutual mass — a dyad `A↔B` is its own transpose; `300` is the
+maximal fixed point. Scoring that fixed mass `Σ M·triad` is the direct
+operationalization of the antisymmetry half of the predicate.
+
+## The metric
+
+Per layer, from the normalized 13-triad census vector `t` (already carried on
+`PatternFingerprint` as `t_imports` / `t_calls`):
+
+```
+tangle_mass(t) = ( Σ_i  M_i · t_i ) / 3
+```
+
+- `M_i` = the MAN first digit (mutual-dyad count) of triad `i`, aligned to
+  `TRIAD_ORDER`:
+
+  | M | triads |
+  |---|--------|
+  | 0 | `021D`, `021U`, `021C`, `030T`, `030C` |
+  | 1 | `111D`, `111U`, `120D`, `120U`, `120C` |
+  | 2 | `201`, `210` |
+  | 3 | `300` |
+
+- `÷3` normalizes to `[0, 1]` so thresholds read on the same scale as
+  `cycle_ratio`.
+
+Reference points: pure DAG → `0`; a single mutual dyad (`201`) → `≈0.67`;
+pure mesh (`300`) → `1.0`. Healthy `030T` (transitive triangle, `M = 0`) does
+**not** count — only mutual coupling does.
+
+**Both layers** combine via the worst layer (a hard gate takes the worst case,
+not a weighted distance):
+
+```
+tangle_ratio = max( tangle_mass(t_imports), tangle_mass(t_calls) )
+```
+
+## Where it lives (all append-only)
+
+| File | Change |
+|------|--------|
+| `src/cgis/query/triads.py` | new pure `tangle_mass(census: tuple[float, ...]) -> float` + module-level `_TANGLE_WEIGHTS` aligned to `TRIAD_ORDER` |
+| `src/cgis/query/fingerprint.py` | computed `@property tangle_ratio` on `PatternFingerprint` = `max(tangle_mass(t_imports), tangle_mass(t_calls))` — derived from the census vectors, so it needs no constructor change and cannot drift from them |
+| `src/cgis/query/drift.py` | add `"tangle_ratio"` to `_COMPONENT_NAMES` (the constraint-recognition whitelist `_parse_constraints` iterates); `_hygiene_check` reads `actual.tangle_ratio` automatically — no gate-logic change |
+| `docs/ontology/patterns.yaml` | add `tangle_ratio: {max: <default>}` to the `hygiene:` block |
+| `src/cgis/query/ontology_init.py` | mirror the same line in `_DEFAULT_ONTOLOGY_HEADER` (staleness pin-test keeps the two parse-identical) |
+| `src/cgis/api/mcp_server.py` | append-only `tangle_ratio` in the `cgis_drift` payload (enriched explicitly — `dataclasses.asdict` skips the property) |
+
+**CLI is intentionally not touched.** An early draft listed an append-only
+`tangle` column in the `cgis drift` table, but a breach already surfaces through
+the existing `gate_failed` status plus the hygiene-violation note, and a 7th
+column reintroduces the #177 note-wrapping width pressure. The numeric value is
+exposed via the MCP payload for programmatic consumers; the human table stays as
+is. (YAGNI.)
+
+The `hygiene_baseline` ratchet (#151) works for free: `tangle_ratio` is a valid
+hygiene key like any other, so acknowledged debt is declared per-domain via
+`hygiene_baseline: {tangle_ratio: <relaxed>}`.
+
+## Default threshold — empirical, not invented
+
+The default `max` is chosen at plan time by **measuring** `tangle_ratio` on three
+anchors, not picked a priori:
+
+- **rider-web** (~1.0 mesh) — the gate MUST fire here.
+- **cgis-self** (clean → micro) — the self-drift gate MUST stay green (the
+  drift-rebaseline lesson: a refactor/feature that reddens the self-gate means
+  re-negotiate the metric, not ship a red default).
+- **owner-api** (~0.21 macro mass, moderately coupled) — the borderline that
+  calibrates where "coupled-but-shipping" sits relative to the threshold.
+
+Expected landing zone `0.15–0.25`, but the committed number is whatever the
+measurement supports while keeping cgis-self green. If no single default
+separates rider-web from cgis-self, fall back to a conservative default that
+only fires on near-mesh and document the gap.
+
+## Error / edge handling
+
+- **Empty census** (`ZERO_TRIADS`, no data): `tangle_mass` returns `0.0` by
+  construction (`Σ 0·M = 0`). A no-data domain is not tangled.
+- **Hygiene-only domains** (no `expected_pattern`): already run the gate path;
+  `tangle_ratio` applies to them too — desirable (mesh with no declared template
+  should still fail).
+- **Quotient level**: scored by the same `PatternFingerprint` + gate, so the
+  project-level binding gets `tangle_ratio` automatically (cross-domain mutual
+  coupling is exactly the macro-tangle the research flagged on owner-api).
+
+## Testing
+
+1. **`tangle_mass` unit table** (`tests/unit/test_triads.py` or new
+   `test_tangle.py`): DAG-only census → `0.0`; pure `300` → `1.0`; pure `201`
+   → `≈0.667`; pure `030T` → `0.0`; empty → `0.0`. Weight-alignment assertion:
+   `_TANGLE_WEIGHTS` length == 13 and matches `TRIAD_ORDER` first-digit mapping.
+2. **`PatternFingerprint.tangle_ratio`**: a synthetic mesh domain (mutual edges)
+   yields high `tangle_ratio`; a synthetic DAG domain yields `0.0`; `max` picks
+   the worse of imports/calls.
+3. **Gate integration** (`tests/unit/test_drift*.py`): a mesh domain with
+   `tangle_ratio` over the default → status `gate_failed`; a clean domain →
+   `clean`; `hygiene_baseline: {tangle_ratio: ...}` relaxes a known breach back
+   to `clean` (ratchet path).
+4. **Staleness pin**: the existing patterns.yaml ↔ ontology_init header
+   parse-identity test must still pass after adding the line to both.
+5. **Self-drift safety**: cgis-self drift run stays green with the chosen
+   default. The self-parsing guard (`tests/self_parsing/test_drift.py::
+   _assert_within_tolerance`) now asserts `status != "gate_failed"` per domain,
+   so a future hygiene regression — including a `tangle_ratio` rise — fails CI
+   rather than passing silently (tangle has weight 0 in `drift_score`, so the
+   tolerance check alone would miss it).
+
+## Known follow-ups (separate issues)
+
+- **#244 — discount calls-layer tangle by `(1 − unresolved_ratio)`.** The
+  drift-distance path fades the CALLS layer by the resolution confidence; the
+  gate does not, and `max(imports, calls)` picks the worse layer. A domain with
+  mostly-unresolved calls plus one resolved mutual triple can read a high
+  calls-tangle on thin evidence → a false `gate_failed`. The imports layer
+  (always resolved) carries the reliable signal; deferred so this PR ships the
+  metric and the empirical threshold without re-opening the measurement.
+
+## Out of scope (other #186 deliverables, separate PRs)
+
+- `closure-gap` coupling metric (reachability saturation on the
+  `[micro ↔ closure(micro)]` spectrum).
+- `cgis_fractal` tool (entropy + collapse-ratio per structural tier, 2D verdict).

src/cgis/api/mcp_server.py

@@ -257,9 +257,17 @@ def cgis_drift(
         payload = {
             "any_critical": analysis.any_critical,
             "max_drift": max_drift,
-            "domains": [dataclasses.asdict(r) for r in analysis.reports],
+            "domains": [
+                {**dataclasses.asdict(r), "tangle_ratio": round(r.actual.tangle_ratio, 4)}
+                for r in analysis.reports
+            ],
             "quotient": [
-                {**dataclasses.asdict(r), "enforce": b.enforce} for b, r in analysis.quotient
+                {
+                    **dataclasses.asdict(r),
+                    "enforce": b.enforce,
+                    "tangle_ratio": round(r.actual.tangle_ratio, 4),
+                }
+                for b, r in analysis.quotient
             ],
             "coverage": analysis.coverage,
         }

src/cgis/query/drift.py

@@ -19,6 +19,7 @@
     "router_count",
     "cycle_ratio",
     "unresolved_ratio",
+    "tangle_ratio",
 )
 
 _CALLS_LAYER = frozenset({"hub_count", "star_count", "chain_len", "router_count"})

src/cgis/query/fingerprint.py

@@ -6,7 +6,7 @@
 from cgis.core.models import Edge, EdgeType, Node, NodeType
 from cgis.query._scc import build_adjacency, tarjan_scc
 from cgis.query.health import HealthScorer
-from cgis.query.triads import ZERO_TRIADS, normalized_census, triad_census
+from cgis.query.triads import ZERO_TRIADS, normalized_census, tangle_mass, triad_census
 from cgis.storage.sqlite_store import SQLiteStore
 
 RAW_CALL_PREFIX = "raw_call:"
@@ -44,6 +44,21 @@ class PatternFingerprint:
     node_count: int = 1
     edge_count: int = 1
 
+    @property
+    def tangle_ratio(self) -> float:
+        """Worst-layer normalized mutual-motif mass, in [0, 1] (spec #186).
+
+        max over the IMPORTS and CALLS census of tangle_mass — a hard hygiene
+        signal: a breach in either layer is a breach. 0 for empty or
+        antisymmetric (no-mutual-dyad) layers.
+
+        NOTE(#244): the CALLS layer is not yet faded by (1 - unresolved_ratio)
+        as the drift-distance path is, so a sparse/mostly-unresolved call graph
+        can over-report calls-tangle. The IMPORTS layer (always resolved) is the
+        reliable signal until that discount lands.
+        """
+        return max(tangle_mass(self.t_imports), tangle_mass(self.t_calls))
+
 
 def _in_domain(fqn: str, prefix: str) -> bool:
     """Return True iff fqn is the prefix itself or a child of it (segment-boundary aware)."""

src/cgis/query/ontology_init.py

@@ -72,6 +72,7 @@
 hygiene:
   cycle_ratio:      {max: 0.0}
   unresolved_ratio: {max: 0.2}
+  tangle_ratio:     {max: 0.25}
 
 # ── The closed alphabet: five templates (spec §2.1, §3.3) ────────────────────
 # ideal: hand-authored points in 13-triad space, one per layer, each summing

src/cgis/query/triads.py

@@ -210,3 +210,25 @@ def tv_distance(
         for name, a, b, w in zip(TRIAD_ORDER, t, ideal, weights, strict=True)
     ]
     return sum((c for _, c in contribs), 0.0), contribs
+
+
+#: MAN mutual-dyad count (M, the first digit of the MAN code) for each class,
+#: aligned index-for-index with TRIAD_ORDER. Transpose-fixed mutual mass is the
+#: anti-pattern signal (spec: health = acyclicity + antisymmetry).
+_TANGLE_WEIGHTS: tuple[int, ...] = (0, 0, 0, 1, 1, 0, 0, 2, 1, 1, 1, 2, 3)
+
+#: Max single-class weight (pure 300), used to normalize tangle into [0, 1].
+_TANGLE_MAX_M = 3.0
+
+
+def tangle_mass(census: tuple[float, ...]) -> float:
+    """Normalized transpose-fixed (mutual) motif mass of a census, in [0, 1].
+
+    Weights each normalized triad fraction by its MAN mutual-dyad count M and
+    divides by the maximal M (3, pure 300). An antisymmetric graph — no mutual
+    dyads, i.e. only 021*/030T/030C (cycles included; acyclicity is cycle_ratio's
+    job, orthogonal to tangle) — scores 0; a pure mutual mesh (300) scores 1.
+    The empty census scores 0.
+    """
+    weighted = sum(w * t for w, t in zip(_TANGLE_WEIGHTS, census, strict=True))
+    return weighted / _TANGLE_MAX_M

tests/self_parsing/test_drift.py

@@ -37,6 +37,16 @@ def _assert_within_tolerance(store: SQLiteStore, patterns_path: str, graph: str)
     for domain in _selected_domains(scorer, graph):
         fp = extractor.extract(domain.fqn_prefix)
         report = scorer.score(fp, domain)
+        # Hygiene breaches (cycle_ratio, unresolved_ratio, tangle_ratio) force
+        # gate_failed independently of drift_score, so the tolerance check below
+        # would miss them. Assert the gate explicitly so a future hygiene
+        # regression on the self-graph — e.g. a tangle_ratio rise (#186) — fails
+        # CI rather than passing silently with weight 0 in the score.
+        if report.status == "gate_failed":
+            failures.append(
+                f"[gate] {domain.name} ({domain.fqn_prefix}): hygiene gate_failed\n"
+                + ("\n".join(f"  - {v}" for v in report.violations) or "  (none)")
+            )
         if report.drift_score > domain.drift_tolerance:
             failures.append(
                 _EXCEEDED.format(

tests/unit/test_drift.py

@@ -23,6 +23,7 @@
 hygiene:
   cycle_ratio:      {max: 0.0}
   unresolved_ratio: {max: 0.2}
+  tangle_ratio:     {max: 0.25}
 patterns:
   pure_utility:
     description: "Hub pattern"
@@ -1598,3 +1599,64 @@ def test_fit_templates_sorted_and_deterministic(repo_scorer: DriftScorer) -> Non
     assert [r for _, r in fits] == sorted(r for _, r in fits)
     assert fits[0][0] == "pipeline_stage"
     assert repo_scorer.fit_templates(fp, "python") == fits
+
+
+# ── tangle_ratio hygiene gate (#186) ──────────────────────────────────────────
+
+
+def _hygiene_only_config(name: str) -> DomainConfig:
+    return DomainConfig(name=name, fqn_prefix=name, expected_pattern=None)
+
+
+def _tangle_fp(
+    domain: str,
+    t_imports: tuple[float, ...] | None = None,
+    t_calls: tuple[float, ...] | None = None,
+) -> PatternFingerprint:
+    zeros = tuple(0.0 for _ in TRIAD_ORDER)
+    return PatternFingerprint(
+        domain=domain,
+        hub_count=0,
+        star_count=0,
+        chain_len=0.0,
+        dag_depth=0,
+        router_count=0,
+        cycle_ratio=0.0,
+        unresolved_ratio=0.0,
+        t_imports=t_imports if t_imports is not None else zeros,
+        t_calls=t_calls if t_calls is not None else zeros,
+        node_count=10,
+        edge_count=10,
+    )
+
+
+def _onehot(name: str) -> tuple[float, ...]:
+    return tuple(1.0 if t == name else 0.0 for t in TRIAD_ORDER)
+
+
+def test_tangle_gate_fails_mesh_domain(scorer: DriftScorer) -> None:
+    """A pure-mesh (300) CALLS layer breaches the tangle_ratio hygiene gate."""
+    fp = _tangle_fp("dom", t_calls=_onehot("300"))
+    report = scorer.score(fp, _hygiene_only_config("dom"))
+    assert report.status == "gate_failed"
+    assert any("tangle_ratio" in v for v in report.violations)
+
+
+def test_tangle_gate_passes_clean_domain(scorer: DriftScorer) -> None:
+    """A pure-DAG (021C) domain stays under the tangle bound."""
+    clean = _onehot("021C")
+    fp = _tangle_fp("dom", t_imports=clean, t_calls=clean)
+    report = scorer.score(fp, _hygiene_only_config("dom"))
+    assert report.status != "gate_failed"
+
+
+def test_tangle_baseline_ratchet_acknowledges_breach(scorer: DriftScorer) -> None:
+    """hygiene_baseline relaxes a known tangle breach back to non-failing."""
+    cfg = DomainConfig(
+        name="dom",
+        fqn_prefix="dom",
+        expected_pattern=None,
+        hygiene_baseline={"tangle_ratio": 1.0},
+    )
+    report = scorer.score(_tangle_fp("dom", t_calls=_onehot("300")), cfg)
+    assert report.status != "gate_failed"