@event4u/agent-config 1.25.0 → 1.26.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.25.0"
+    "version": "1.26.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,20 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.26.0](https://github.com/event4u-app/agent-config/compare/1.25.0...1.26.0) (2026-05-08)
+
+### Features
+
+* **linter:** replace size heuristics with structural-density model ([95584ac](https://github.com/event4u-app/agent-config/commit/95584ac5e74948b71a9d13ff5ec6870c110be489))
+
+### Documentation
+
+* **contracts:** add linter structural model + update size-and-scope ([32fa8b2](https://github.com/event4u-app/agent-config/commit/32fa8b2b7cc65148f7bc28fb782f20670d6640bc))
+
+### Chores
+
+* gitignore density logs + archive completed structural-linter roadmap ([0a94ece](https://github.com/event4u-app/agent-config/commit/0a94ece8ac724386a5d49451b1e0d3058f2644cf))
+
 ## [1.25.0](https://github.com/event4u-app/agent-config/compare/1.24.0...1.25.0) (2026-05-08)
 
 ### Features

package/docs/contracts/linter-structural-model.md

@@ -0,0 +1,180 @@
+---
+stability: beta
+---
+
+# Linter Structural Model
+
+**Status:** LOCKED — shipped 2026-05-08 on
+`feat/road-to-structural-linter-reform`. The linter now applies the
+structural model to skills, rules, and commands.
+
+## Why a structural model
+
+Council convergence (Sonnet + GPT-4o, 2026-05-06): raw line / word
+counts produce ratchet drift. Three failure modes that the pure-size
+gate cannot distinguish:
+
+- A 500-line skill with **one** 10-step procedure (legitimate) vs a
+  500-line skill with **ten** independent procedures (split candidate).
+- A 1700-word command that **delegates** to a cluster (legitimate
+  orchestrator) vs a 1700-word command that **inlines** the work.
+- A 60-line rule whose body is a **verbatim Iron-Law block**
+  (legitimate) vs a 60-line rule that is **prose explanation**
+  (split candidate).
+
+The structural model replaces the size threshold with four primitives.
+
+## Primitives
+
+### 1. Density score (0.0 – 1.0)
+
+```
+density = structured_lines / total_non_blank_lines
+```
+
+`structured_lines` = lines inside fenced blocks + markdown-table rows
++ bullet-list lines + numbered-list lines + section-heading lines.
+Higher = more structured (catalogue, table, code, list); lower =
+prose-dominant.
+
+### 2. Multi-workflow detector (skills only)
+
+Skills with **≥ 2 `## Procedure`** (or `## Procedure: <name>`)
+sections ship multiple independently invocable procedures. Combined
+with size, this is the cluster-split signal.
+
+### 3. Delegation detector (commands only)
+
+Command has a delegation signal when **either** holds:
+
+- frontmatter declares `cluster:` or `routes_to:`
+- body contains ≥ 3 markdown links to other `.md` files
+
+Absence of both signals on a large command = inlined logic.
+
+### 4. Iron-Law block detector (rules only)
+
+A fenced block is an Iron-Law block when its body has **≥ 30
+alphabetical characters** with **≥ 60 % uppercase** across **≥ 1
+non-empty line**. The 30-character floor filters single ALL-CAPS
+markers (`OK`, `WIP`); the 60 % uppercase floor catches verbatim
+imperatives (`NEVER COMMIT.`).
+
+## Phase 1 calibration (2026-05-08)
+
+Sweep covered all 310 lintable artifacts via
+[`scripts/measure_density.py`](../../scripts/measure_density.py); raw
+data lives at `agents/.density-snapshot.jsonl` (local-only — re-run
+`python3 scripts/measure_density.py --root .agent-src --jsonl
+agents/.density-snapshot.jsonl` to regenerate).
+
+| Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |
+|---|---|---|---|---|---|
+| skill | 142 | 0.76 | 0.78 | 22 | 119 |
+| command | 103 | 0.59 | 0.57 | 46 | 45 |
+| rule | 58 | 0.47 | 0.48 | 25 | 11 |
+| persona | 7 | 0.38 | 0.38 | 1 | 0 |
+
+Iron-Law detector recall on 9 canonical Iron-Law rules: **8 / 9** (all
+except `agent-authority`, which uses a markdown-table index instead of
+a fenced block — correct miss).
+
+`quality-tools` (411 lines, single workflow): density **0.83**, single
+procedure → no warning under the new model. ✓ roadmap success criterion.
+
+`optimize/augmentignore.md` (1679 words): delegation signal **present**
+(frontmatter `routes_to:`) → no warning under the new model. ✓ roadmap
+success criterion.
+
+Of 13 commands ≥ 1000 words, only **2** lack a delegation signal —
+both are candidates for Phase 4.1 review (`compress.md`,
+`project-analyze.md`; the latter has density 0.86, exempt under the
+density-AND-delegation gate).
+
+## Warn rules (shipped Phase 3, 2026-05-08)
+
+| Artifact | Warn condition |
+|---|---|
+| **skill** | `lines > 400` AND (`density < 0.6` OR `procedures ≥ 2`) |
+| **command** | `words > 1000` AND no delegation signal AND `density < 0.65` |
+| **rule** | `lines > 60` AND `density < 0.5` AND `iron_law_blocks == 0` |
+
+The 200-line rule **error** stays unconditional. No new frontmatter
+keys ship — the four structural primitives are the contract.
+
+Calibration sweep on the 2026-05-08 corpus (310 artifacts):
+
+| Type | Old warns | New warns | New band | Δ |
+|---|---|---|---|---|
+| rule | 23 | 2 | 3.4 % | −91 % |
+| skill | 2 | 1 | 0.7 % | −50 % |
+| command | 9 | 1 | 1.0 % | −89 % |
+| **total** | **34** | **4** | **1.3 %** | **−88 %** |
+
+Pass rate: 186 → 209 (`pass`); 124 → 101 (`pass_with_warnings`); 0
+errors. Each remaining warning is a genuine structural defect:
+
+- `compress.md` (1569 words, density 0.58, no delegation signal) —
+  inlined logic in a non-orchestrator command.
+- `artifact-drafting-protocol.md` rule (65 lines, density 0.37, no
+  Iron-Law block) — prose-dominant long rule.
+- `minimal-safe-diff.md` rule (69 lines, density 0.41, no Iron-Law
+  block) — prose-dominant long rule.
+- `ai-council/SKILL.md` (525 lines, density 0.37) — orchestrator
+  skill below the density floor; refactor candidate.
+
+Roadmap target ≤ 10 % rule-warning band. ✓ (3.4 %)
+
+## Frontmatter contract — Phase 2 decisions (2026-05-08)
+
+AI Council run (Claude Sonnet 4.5 + GPT-4o, 2 rounds, $0.046; raw
+transcript local-only per the council-references convention).
+
+**Key 1 — `iron_law:` frontmatter — DECISION: Option A (auto-detect, no tag).**
+
+Both council members converged on Option A. The detector recall on
+the canonical 9-rule set is 8 / 9, and the one miss
+(`agent-authority`) uses a markdown-table priority index that is
+**not** an Iron-Law imperative — its body delegates to the rules it
+indexes. The detector is correct to skip it. No `iron_law:`
+frontmatter key is added.
+
+**Key 2 — `density_exempt:` frontmatter — DECISION: Option A (no flag).**
+
+Council split:
+
+- Sonnet 4.5: Reject any flag. Add **type-based density floors**
+  (orchestrators 0.35, executors 0.6, imperatives 0.4) so the
+  detector classifies structurally instead of relying on author
+  declarations.
+- GPT-4o: Adopt Option C (`density_exempt: true` + required
+  `density_exempt_reason:`) with periodic re-audit.
+
+Sonnet's structural argument carries: an escape hatch for a 1-in-142
+corpus case ships maintenance debt across every future artifact that
+brushes the boundary. The single failing skill (`ai-council`,
+density 0.36) is a documentation-heavy reference-orchestrator and is
+left as a Phase-4 review candidate — either restructure the skill or
+add orchestrator-aware type-floors as a follow-up. No
+`density_exempt:` key is added in Phase 3.
+
+The Phase-3 implementation therefore ships **zero new frontmatter
+keys** — the structural primitives are the contract.
+
+## Out of scope
+
+- Hard error thresholds beyond the 200-line rule cap.
+- Automatic refactoring of artifacts that fail the new model.
+- Cross-artifact dependency counts (a skill linking 4 other skills is
+  `routes_to` doing its job, not a defect).
+
+## References
+
+- `scripts/measure_density.py` — Phase 1.1 measurement tool.
+- `agents/.density-snapshot.jsonl` — full per-artifact metrics
+  (gitignored, re-run the measurement script to regenerate).
+- `scripts/skill_linter.py` — structural-model implementation
+  (`_density_score`, `_count_procedure_sections`,
+  `_command_delegation_signal`, `_iron_law_blocks`).
+- `docs/guidelines/agent-infra/size-and-scope.md` — guideline now
+  describes the structural model; Option 2 transition notes removed.

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -33,10 +33,14 @@ Size is a signal — not the goal.
 - Acceptable: **< 100–120 lines**
 - Hard limit: **< 200 lines**
 
-Linter (council review 2026-05-06): the > 40 / > 60 line warnings are
-**density-gated** — rules with ≥ 30 % fenced content (verbatim Iron-Law
-blocks, worked-example fences) are exempt from the line-count warning.
-The 200-line hard error stays unconditional.
+Linter (structural model, 2026-05-08 — see
+[`docs/contracts/linter-structural-model.md`](../../contracts/linter-structural-model.md)):
+the long-rule warning fires only when the rule is **> 60 non-empty
+lines AND density < 0.50 AND ships no Iron-Law block**. Rules whose
+body is a verbatim ALL-CAPS imperative (`commit-policy`,
+`ask-when-uncertain`, `direct-answers`) are auto-exempt — no
+frontmatter flag required. The 200-line hard error stays
+unconditional.
 
 Reason:
 - Loaded frequently
@@ -48,10 +52,11 @@ Reason:
 ## Skills
 
 - Target: **300–900 words**
-- Warning: **> 400 lines** (raised from 300, council review 2026-05-06)
-- Strong split signal: reference-rich skills (analyzer, quality-tool
-  catalog, council orchestration) may legitimately sit between 300 and
-  400 lines without being split-candidates
+- Warning: **> 400 lines AND (density < 0.60 OR ≥ 2 `## Procedure`
+  blocks)** — structural model, 2026-05-08
+- Reference-rich skills with high density (`quality-tools` at 0.83,
+  catalogue-style skills) pass without splitting; the multi-procedure
+  trigger flags genuine cluster-split candidates regardless of size
 
 Focus:
 - scanability
@@ -64,10 +69,11 @@ Focus:
 
 - Target: **200–600 words**
 - Acceptable: **up to ~1000 words**
-- Warning: **> 1000 words AND lacks delegation structure** (< 5
-  sub-sections OR < 3 code blocks). Well-factored orchestrators with ≥ 5
-  sub-sections AND ≥ 3 code blocks are exempt — the size reflects
-  dispatch breadth, not bloat (council review 2026-05-06).
+- Warning: **> 1000 words AND no delegation signal AND density < 0.65**
+  — structural model, 2026-05-08. A delegation signal is either
+  frontmatter (`cluster:` / `routes_to:`) OR ≥ 3 markdown links to
+  other `.md` files. Well-factored orchestrators pass automatically;
+  inlined logic in a non-orchestrator command warns.
 
 Commands orchestrate — not implement.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.25.0",
+    "version": "1.26.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/measure_density.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Measure structural density across the artifact corpus.
+
+Phase 1.1 of `agents/roadmaps/road-to-structural-linter-reform.md`.
+
+Density score = structured_lines / total_lines, where structured_lines
+sum lines inside fenced blocks + markdown-table rows + bullet lines +
+numbered/ordered-list lines + section-heading lines. Higher = more
+structured (catalogue, orchestrator, Iron-Law block); lower = prose-
+dominant.
+
+Companion signals collected per artifact (consumed by Phases 1.2-1.4):
+
+- ``multi_workflow``  ≥ 2 ``## Procedure`` (or ``## Procedure: …``)
+                     blocks in a skill — candidate for cluster split.
+- ``delegation``     command frontmatter has ``cluster:`` or
+                     ``routes_to:``, or the body links to ≥ 3 other
+                     commands/skills via ``](...md)``.
+- ``iron_law_block`` ≥ 1 fenced block whose body is ≥ 60 % ALL-CAPS
+                     across ≥ 3 non-empty lines.
+
+Output:
+- Default stdout: per-type distribution buckets + tail (lowest density).
+- ``--json`` deterministic JSON of every artifact.
+- ``--snapshot`` writes JSONL to ``agents/.density-snapshot.jsonl``.
+
+Stdlib only; no network. Re-runnable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from skill_linter import (  # noqa: E402
+    detect_artifact_type,
+    extract_frontmatter,
+    gather_all_candidate_files,
+)
+
+SNAPSHOT_FILE = REPO_ROOT / "agents" / ".density-snapshot.jsonl"
+
+_TABLE_ROW = re.compile(r"^\s*\|.*\|\s*$")
+_BULLET = re.compile(r"^\s*[-*]\s+\S")
+_NUMBERED = re.compile(r"^\s*\d+\.\s+\S")
+_HEADING = re.compile(r"^\s{0,3}#{1,6}\s+\S")
+_PROCEDURE = re.compile(r"^##\s+Procedure(\s*:.*)?\s*$", re.MULTILINE)
+_LINK_MD = re.compile(r"\]\([^)]+\.md[^)]*\)")
+_FRONTMATTER_KEY = re.compile(r"^(cluster|routes_to)\s*:", re.MULTILINE)
+_ALLCAPS_LINE = re.compile(r"[A-Z]")
+
+
+def _classify_lines(text: str) -> Dict[str, int]:
+    """Bucket every non-blank line into one structural category."""
+    inside_fence = False
+    counts = {
+        "total": 0,
+        "fenced": 0,
+        "table": 0,
+        "bullet": 0,
+        "numbered": 0,
+        "heading": 0,
+        "prose": 0,
+    }
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if stripped.startswith("```"):
+            inside_fence = not inside_fence
+            counts["total"] += 1
+            counts["fenced"] += 1
+            continue
+        if not stripped:
+            continue
+        counts["total"] += 1
+        if inside_fence:
+            counts["fenced"] += 1
+        elif _TABLE_ROW.match(raw):
+            counts["table"] += 1
+        elif _HEADING.match(raw):
+            counts["heading"] += 1
+        elif _BULLET.match(raw):
+            counts["bullet"] += 1
+        elif _NUMBERED.match(raw):
+            counts["numbered"] += 1
+        else:
+            counts["prose"] += 1
+    return counts
+
+
+def _detect_iron_law_blocks(text: str) -> int:
+    """Count fenced blocks that look like verbatim Iron-Law imperatives.
+
+    Heuristic: fenced block with ≥ 1 non-empty line whose alphabetical
+    body is ≥ 60 % uppercase AND has ≥ 30 letters total (filters single
+    short ALL-CAPS markers like ``OK``). Also matches blockquote-style
+    Iron Laws (``> NEVER COMMIT``).
+    """
+    blocks = 0
+    inside = False
+    body: list[str] = []
+    for raw in text.splitlines():
+        if raw.strip().startswith("```"):
+            if inside and body:
+                non_empty = [b for b in body if b.strip()]
+                letters = "".join(non_empty)
+                upper = sum(1 for c in letters if c.isalpha() and c.isupper())
+                total = sum(1 for c in letters if c.isalpha())
+                if total >= 30 and upper / total >= 0.6 and non_empty:
+                    blocks += 1
+            inside = not inside
+            body = []
+            continue
+        if inside:
+            body.append(raw)
+    return blocks
+
+
+def _count_procedures(text: str) -> int:
+    return len(_PROCEDURE.findall(text))
+
+
+def _delegation_signal(text: str, frontmatter: str | None) -> Dict[str, Any]:
+    fm_keys = bool(frontmatter and _FRONTMATTER_KEY.search(frontmatter))
+    md_links = len(_LINK_MD.findall(text))
+    return {"frontmatter_routes": fm_keys, "md_links": md_links,
+            "has_signal": fm_keys or md_links >= 3}
+
+
+def measure(path: Path) -> Dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    rel = path.relative_to(REPO_ROOT) if path.is_absolute() else path
+    artifact_type = detect_artifact_type(rel, text)
+    frontmatter = extract_frontmatter(text)
+    counts = _classify_lines(text)
+    structured = counts["fenced"] + counts["table"] + counts["bullet"] + \
+        counts["numbered"] + counts["heading"]
+    density = structured / counts["total"] if counts["total"] else 0.0
+    return {
+        "file": str(rel),
+        "type": artifact_type,
+        "lines": counts["total"],
+        "words": len(text.split()),
+        "density": round(density, 3),
+        "fenced": counts["fenced"],
+        "table": counts["table"],
+        "bullet": counts["bullet"],
+        "numbered": counts["numbered"],
+        "heading": counts["heading"],
+        "prose": counts["prose"],
+        "iron_law_blocks": _detect_iron_law_blocks(text),
+        "procedures": _count_procedures(text),
+        "delegation": _delegation_signal(text, frontmatter),
+    }
+
+
+def collect() -> List[Dict[str, Any]]:
+    paths = gather_all_candidate_files(REPO_ROOT)
+    return [measure(p) for p in paths]
+
+
+def _bucketize(values: List[float]) -> Dict[str, int]:
+    buckets = {"0.0-0.2": 0, "0.2-0.4": 0, "0.4-0.6": 0,
+               "0.6-0.8": 0, "0.8-1.0": 0}
+    for v in values:
+        if v < 0.2:
+            buckets["0.0-0.2"] += 1
+        elif v < 0.4:
+            buckets["0.2-0.4"] += 1
+        elif v < 0.6:
+            buckets["0.4-0.6"] += 1
+        elif v < 0.8:
+            buckets["0.6-0.8"] += 1
+        else:
+            buckets["0.8-1.0"] += 1
+    return buckets
+
+
+def report(results: List[Dict[str, Any]]) -> str:
+    by_type: Dict[str, List[Dict[str, Any]]] = {}
+    for r in results:
+        by_type.setdefault(r["type"], []).append(r)
+    lines: List[str] = ["# Structural Density Snapshot", "",
+                        f"Total artifacts: {len(results)}", ""]
+    for t in sorted(by_type):
+        rows = by_type[t]
+        densities = [r["density"] for r in rows]
+        avg = sum(densities) / len(densities) if densities else 0.0
+        med = sorted(densities)[len(densities) // 2] if densities else 0.0
+        buckets = _bucketize(densities)
+        lines.append(f"## {t} ({len(rows)} artifacts)")
+        lines.append(f"avg density={avg:.2f} median={med:.2f}")
+        lines.append("buckets " + " ".join(
+            f"[{k}]={v}" for k, v in buckets.items()))
+        tail = sorted(rows, key=lambda r: r["density"])[:5]
+        lines.append("lowest density:")
+        for r in tail:
+            lines.append(f"  {r['density']:.2f} {r['lines']:>4}L "
+                         f"proc={r['procedures']} "
+                         f"iron={r['iron_law_blocks']} "
+                         f"deleg={int(r['delegation']['has_signal'])} "
+                         f"{r['file']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--snapshot", action="store_true",
+                   help=f"write JSONL to {SNAPSHOT_FILE.relative_to(REPO_ROOT)}")
+    args = p.parse_args()
+    results = collect()
+    if args.snapshot:
+        SNAPSHOT_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with SNAPSHOT_FILE.open("w", encoding="utf-8") as fh:
+            for r in sorted(results, key=lambda x: x["file"]):
+                fh.write(json.dumps(r, sort_keys=True) + "\n")
+    if args.json:
+        print(json.dumps(results, sort_keys=True, indent=2))
+    else:
+        print(report(results))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/skill_linter.py

@@ -264,9 +264,9 @@ def _count_code_blocks(text: str) -> int:
 def _fenced_content_ratio(text: str) -> float:
     """Return the fraction of non-empty lines that sit inside fenced blocks.
 
-    Used as a structural signal: rules / files dominated by verbatim Iron-Law
-    blocks or worked examples score high and are exempted from raw line-count
-    warnings (council review 2026-05-06).
+    Retained as a helper for backwards compatibility; the size gates use
+    :func:`_density_score` from the structural model instead (Phase 3 of
+    road-to-structural-linter-reform).
     """
     inside = False
     fenced_lines = 0
@@ -287,6 +287,106 @@ def _fenced_content_ratio(text: str) -> float:
     return fenced_lines / non_empty
 
 
+# --- Structural-density model (docs/contracts/linter-structural-model.md) ---
+# Replaces the raw line/word/fenced-ratio gates with four primitives that
+# distinguish complexity from bloat. Calibrated 2026-05-08 against the full
+# 310-artefact corpus (agents/.density-snapshot.jsonl).
+
+PROCEDURE_HEADING_PATTERN = re.compile(
+    r"^##\s+Procedure(\s*[:\u2014\-].*)?\s*$", re.MULTILINE
+)
+COMMAND_FRONTMATTER_DELEGATION_KEYS = ("cluster:", "routes_to:")
+MD_LINK_PATTERN = re.compile(r"\[[^\]]+\]\(([^)]+\.md[^)]*)\)")
+
+
+def _density_score(text: str) -> float:
+    """Return structural density 0.0–1.0 — see docs/contracts/linter-structural-model.md.
+
+    density = structured_lines / non_blank_lines, where structured_lines =
+    fenced + table + bullet + numbered + heading. Higher = more structured
+    (catalogue, table, code, list); lower = prose-dominant.
+    """
+    inside_fence = False
+    structured = 0
+    non_blank = 0
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        non_blank += 1
+        if stripped.startswith("```"):
+            inside_fence = not inside_fence
+            structured += 1
+            continue
+        if inside_fence:
+            structured += 1
+            continue
+        if stripped.startswith("#"):
+            structured += 1
+            continue
+        if stripped.startswith("|") and stripped.endswith("|"):
+            structured += 1
+            continue
+        if stripped.startswith(("- ", "* ", "+ ")):
+            structured += 1
+            continue
+        if re.match(r"^\d+\.\s", stripped):
+            structured += 1
+            continue
+    if non_blank == 0:
+        return 0.0
+    return round(structured / non_blank, 3)
+
+
+def _count_procedure_sections(text: str) -> int:
+    """Count `## Procedure` (or `## Procedure: <name>`) blocks in *text*."""
+    return len(PROCEDURE_HEADING_PATTERN.findall(text))
+
+
+def _command_delegation_signal(text: str, frontmatter: Optional[str]) -> bool:
+    """Return True when a command has a delegation signal.
+
+    Signals: frontmatter declares ``cluster:`` or ``routes_to:`` — OR — the
+    body contains ≥ 3 markdown links to other ``.md`` files. Either signal
+    is sufficient (council review 2026-05-08).
+    """
+    if frontmatter:
+        for key in COMMAND_FRONTMATTER_DELEGATION_KEYS:
+            if re.search(rf"^{re.escape(key)}", frontmatter, re.MULTILINE):
+                return True
+    if len(MD_LINK_PATTERN.findall(text)) >= 3:
+        return True
+    return False
+
+
+def _iron_law_blocks(text: str) -> int:
+    """Count fenced blocks that look like verbatim Iron-Law imperatives.
+
+    Heuristic: fenced block whose body has ≥ 30 alphabetical chars and
+    ≥ 60 % uppercase across ≥ 1 non-empty line. The 30-char floor filters
+    short ALL-CAPS markers (``OK``, ``WIP``); the 60 %-uppercase floor
+    catches verbatim imperatives (``NEVER COMMIT.``).
+    """
+    blocks = 0
+    inside = False
+    body: list[str] = []
+    for raw in text.splitlines():
+        if raw.strip().startswith("```"):
+            if inside and body:
+                non_empty = [b for b in body if b.strip()]
+                letters = "".join(non_empty)
+                upper = sum(1 for c in letters if c.isalpha() and c.isupper())
+                total = sum(1 for c in letters if c.isalpha())
+                if total >= 30 and upper / total >= 0.6 and non_empty:
+                    blocks += 1
+            inside = not inside
+            body = []
+            continue
+        if inside:
+            body.append(raw)
+    return blocks
+
+
 def extract_description(text: str) -> Optional[str]:
     frontmatter = FRONTMATTER_PATTERN.search(text)
     if not frontmatter:
@@ -561,14 +661,28 @@ def lint_skill(path: Path, text: str) -> LintResult:
                               "Assisted skill has no validation/challenge step in procedure"))
             suggestions.append("Add a requirement-checking or validation step before implementation")
 
-    # --- Size check (see guidelines/agent-infra/size-and-scope.md) ---
-    # Threshold raised from 300 → 400 (council review 2026-05-06): reference-rich
-    # skills (quality-tools 411, ai-council 399, project-analyzer 341) legitimately
-    # exceed 300 lines without being split-candidates. Structural follow-up tracked
-    # in agents/roadmaps/road-to-structural-linter-reform.md.
+    # --- Size check (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces raw line count (Phase 3 of
+    # road-to-structural-linter-reform, 2026-05-08): warn only when the skill
+    # is *both* large AND prose-dominant OR ships ≥ 2 independently invocable
+    # procedures. Reference catalogues (quality-tools 411 L / density 0.83)
+    # pass; multi-procedure skills are flagged for split.
     total_lines = len(text.splitlines())
     if total_lines > 400:
-        issues.append(Issue("warning", "skill_too_large", f"Skill has {total_lines} lines; review for split (see size-and-scope guideline)"))
+        density = _density_score(text)
+        procedures = _count_procedure_sections(text)
+        if density < 0.6 or procedures >= 2:
+            reason = (
+                f"density {density:.2f} < 0.60"
+                if density < 0.6
+                else f"{procedures} ## Procedure blocks (≥ 2)"
+            )
+            issues.append(Issue(
+                "warning",
+                "skill_too_large",
+                f"Skill has {total_lines} lines and {reason}; review for split "
+                f"(see linter-structural-model contract)",
+            ))
 
     # --- Pointer-only / guideline-dependent skill detection ---
     if procedure_block:
@@ -1021,19 +1135,26 @@ def lint_rule(path: Path, text: str) -> LintResult:
     if DOUBLE_BLANK_PATTERN.search(text):
         issues.append(Issue("warning", "double_blank_lines", "File contains double or triple blank lines"))
 
-    # --- Content checks (see guidelines/agent-infra/size-and-scope.md) ---
-    # Length thresholds gated by fenced-content density (council review 2026-05-06):
-    # rules dominated by verbatim Iron-Law blocks / worked examples are protected
-    # from the > 40 / > 60 warnings. Hard error at 200 stays unconditional.
+    # --- Content checks (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces fenced-ratio + dual-threshold (Phase 3
+    # of road-to-structural-linter-reform, 2026-05-08): warn only when the
+    # rule is long, prose-dominant, AND ships no Iron-Law block. Hard error
+    # at 200 lines stays unconditional.
     line_count = len([line for line in text.splitlines() if line.strip()])
     total_lines = len(text.splitlines())
-    fenced_ratio = _fenced_content_ratio(text)
     if total_lines > 200:
         issues.append(Issue("error", "rule_too_large", f"Rule has {total_lines} lines (hard limit: 200); must split or move to guideline"))
-    elif line_count > 60 and fenced_ratio < 0.30:
-        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines (fenced-content {fenced_ratio:.0%}); prefer < 60 (see size-and-scope guideline)"))
-    elif line_count > 40 and fenced_ratio < 0.30:
-        issues.append(Issue("warning", "long_rule", f"Rule has {line_count} non-empty lines (fenced-content {fenced_ratio:.0%}); rules should be concise"))
+    elif line_count > 60:
+        density = _density_score(text)
+        iron_blocks = _iron_law_blocks(text)
+        if density < 0.5 and iron_blocks == 0:
+            issues.append(Issue(
+                "warning",
+                "long_rule",
+                f"Rule has {line_count} non-empty lines, density {density:.2f} < 0.50, "
+                f"no Iron-Law block; rules should be concise "
+                f"(see linter-structural-model contract)",
+            ))
 
     for bad_sign in RULE_BAD_SIGNS:
         if bad_sign in text:
@@ -1177,17 +1298,25 @@ def lint_command(path: Path, text: str) -> LintResult:
     if not has_steps and not has_numbered:
         issues.append(Issue("warning", "no_steps", "Command has no Steps section or numbered sub-headings"))
 
-    # --- Size check (see guidelines/agent-infra/size-and-scope.md) ---
-    # Word threshold (1000) gated by structural delegation signal (council review
-    # 2026-05-06): well-factored orchestrators with ≥ 5 sub-sections AND ≥ 3 code
-    # blocks are exempt — the size reflects dispatch breadth, not bloat.
+    # --- Size check (docs/contracts/linter-structural-model.md) ---
+    # Structural-density gate replaces sub-section + code-block heuristic
+    # (Phase 3 of road-to-structural-linter-reform, 2026-05-08): warn only
+    # when the command is large, lacks a delegation signal (frontmatter
+    # cluster:/routes_to: OR ≥ 3 markdown links to other .md files), AND
+    # has density < 0.65.
     word_count = len(text.split())
     if word_count > 1000:
-        section_count = len(sections)
-        code_block_count = _count_code_blocks(text)
-        delegation_signal = section_count >= 5 and code_block_count >= 3
-        if not delegation_signal:
-            issues.append(Issue("warning", "large_command", f"Command has {word_count} words (target: 200-600, max ~1000); {section_count} sub-sections, {code_block_count} code blocks — lacks delegation structure"))
+        density = _density_score(text)
+        delegated = _command_delegation_signal(text, frontmatter)
+        if not delegated and density < 0.65:
+            issues.append(Issue(
+                "warning",
+                "large_command",
+                f"Command has {word_count} words, density {density:.2f} < 0.65, "
+                f"no delegation signal (frontmatter cluster:/routes_to: or "
+                f"≥ 3 .md links); review for split or delegation "
+                f"(see linter-structural-model contract)",
+            ))
 
     # File must end with exactly one newline
     if not text.endswith("\n"):