@event4u/agent-config 1.24.0 → 1.26.0

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/schemas/rule.schema.json

@@ -9,7 +9,8 @@
   "properties": {
     "type": {
       "type": "string",
-      "enum": ["always", "auto"]
+      "enum": ["always", "auto", "manual"],
+      "description": "`always` = injected verbatim every turn (kernel). `auto` = description stub injected, body loaded on trigger match. `manual` = no auto-injection (zero workspace-budget cost); file remains as a reference document linkable from skills/contexts. Introduced by ADR-004 to demote thin pointer-rules without breaking cross-references."
     },
     "source": {
       "type": "string",

package/scripts/skill_linter.py

@@ -115,7 +115,7 @@ ORDERED_STEP_PATTERN = re.compile(r"^(?:\s*|\#{1,4}\s*)(\d+)\.\s+", re.MULTILINE
 SECTION_PATTERN = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
 FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
 DESCRIPTION_PATTERN = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
-TYPE_PATTERN = re.compile(r'^type:\s*"?(always|auto)"?\s*$', re.MULTILINE)
+TYPE_PATTERN = re.compile(r'^type:\s*"?(always|auto|manual)"?\s*$', re.MULTILINE)
 SOURCE_PATTERN = re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE)
 STATUS_PATTERN = re.compile(r'^status:\s*"?(active|deprecated|superseded)"?\s*$', re.MULTILINE)
 REPLACED_BY_PATTERN = re.compile(r'^replaced_by:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
@@ -133,7 +133,7 @@ SENIOR_OUTPUT_PATTERN = re.compile(r"^##\s+Output\s*$", re.MULTILINE)
 H1_PATTERN = re.compile(r"^# .+", re.MULTILINE)
 DOUBLE_BLANK_PATTERN = re.compile(r"\n{3,}")
 
-VALID_RULE_TYPES = {"always", "auto"}
+VALID_RULE_TYPES = {"always", "auto", "manual"}
 VALID_RULE_SOURCES = {"package", "project"}
 VALID_STATUSES = {"active", "deprecated", "superseded"}
 
@@ -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:
@@ -683,6 +797,12 @@ def lint_router_frontmatter(rule_id: str, frontmatter: str,
     triggers = _parse_yaml_list(frontmatter, "triggers")
     routes_to = _parse_yaml_list(frontmatter, "routes_to")
 
+    # Manual rules are reference-only — not auto-injected, not router-routed
+    # (ADR-004). Skip router validation so legacy triggers/routes_to fields
+    # remain documented in the rule body without forcing maintenance.
+    if rule_type == "manual":
+        return issues
+
     is_kernel = rule_id in KERNEL_RULE_IDS or rule_type == "always"
 
     if is_kernel:
@@ -961,9 +1081,9 @@ def lint_rule(path: Path, text: str) -> LintResult:
         # type field
         rule_type = extract_frontmatter_field(frontmatter, TYPE_PATTERN)
         if rule_type is None:
-            issues.append(Issue("error", "missing_type", "Frontmatter missing 'type' field (must be 'always' or 'auto')"))
+            issues.append(Issue("error", "missing_type", "Frontmatter missing 'type' field (must be 'always', 'auto', or 'manual')"))
         elif rule_type not in VALID_RULE_TYPES:
-            issues.append(Issue("error", "invalid_type", f"Invalid type '{rule_type}'; must be 'always' or 'auto'"))
+            issues.append(Issue("error", "invalid_type", f"Invalid type '{rule_type}'; must be 'always', 'auto', or 'manual'"))
 
         # source field
         rule_source = extract_frontmatter_field(frontmatter, SOURCE_PATTERN)
@@ -1015,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:
@@ -1171,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"):

package/scripts/spotcheck_thin_root.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Phase 6.6 platform spot-check via AI council.
+
+Sends the refactored package-root AGENTS.md and the consumer template
+to Sonnet 4.5 + gpt-4o, asks each member to answer five questions
+that simulate a fresh agent landing on the file. Records qualitative
+verdicts in agents/reports/thin-root-platform-spotcheck.md.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from scripts.ai_council.clients import (  # noqa: E402
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+)
+from scripts.ai_council.orchestrator import (  # noqa: E402
+    CostBudget,
+    CouncilQuestion,
+    consult,
+)
+from scripts.ai_council.pricing import load_prices  # noqa: E402
+
+QUESTIONS = """
+You are evaluating whether the AGENTS.md file below is a sufficient
+entry point for an AI coding agent landing on this repository for
+the first time. You see only the AGENTS.md content; you do NOT have
+file-system access. Answer the following five questions in JSON
+shape `{"q1": {...}, ..., "q5": {...}}` where each value is
+`{"answer": <string>, "confidence": "high"|"medium"|"low",
+"pointer_used": <one of the linked paths from AGENTS.md, or null>}`.
+
+Q1. Where do I edit content in this repo / project? (a path)
+Q2. What command do I run to verify everything is green before opening a PR?
+Q3. Where would I find the always-active behavioural rules?
+Q4. If only this file is reachable, what five things must I assume to be true to act safely? (cite the emergency-triage block)
+Q5. What outboard target document would I open to learn the package-self-orientation / the consumer-fill-out guide? (a path)
+
+After the JSON, add a short prose verdict (≤ 5 sentences) on:
+- Whether the pointer-following worked (could you cite a path for Q1, Q3, Q5?)
+- Whether the emergency-triage block answered Q4 unambiguously.
+- One concrete improvement you'd make to the AGENTS.md.
+
+Do not invent file paths. If a question cannot be answered from the
+file alone, set `"pointer_used": null` and lower confidence.
+""".strip()
+
+
+def main() -> int:
+    package_root = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+    consumer_template = (
+        ROOT / ".agent-src.uncompressed" / "templates" / "AGENTS.md"
+    ).read_text(encoding="utf-8")
+
+    artefact = (
+        "## Artefact A — package-root AGENTS.md\n\n"
+        f"```markdown\n{package_root}\n```\n\n"
+        "## Artefact B — consumer-template AGENTS.md\n\n"
+        f"```markdown\n{consumer_template}\n```\n\n"
+        f"{QUESTIONS}\n"
+    )
+
+    members = [
+        AnthropicClient(model="claude-sonnet-4-5", api_key=load_anthropic_key()),
+        OpenAIClient(model="gpt-4o", api_key=load_openai_key()),
+    ]
+
+    question = CouncilQuestion(
+        mode="files",
+        user_prompt=artefact,
+        max_tokens=1500,
+    )
+    budget = CostBudget(max_total_usd=2.00, max_calls=4)
+    table = load_prices()
+
+    print("Running spot-check council …", file=sys.stderr)
+    responses = consult(members, question, budget, table=table, rounds=1)
+
+    out_dir = ROOT / "agents" / "reports"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    md_path = out_dir / "thin-root-platform-spotcheck.md"
+    json_path = out_dir / "thin-root-platform-spotcheck.json"
+
+    md_lines = [
+        "# Thin-Root platform spot-check (Phase 6.6)",
+        "",
+        "> AI-council proxy for the manual platform spot-check. Two",
+        "> external reviewers (Sonnet 4.5, gpt-4o) simulate a fresh",
+        "> agent landing on the refactored AGENTS.md and answer five",
+        "> orientation questions from the file alone.",
+        "",
+        "## Verdicts",
+        "",
+    ]
+
+    raw = []
+    for r in responses:
+        body = r.text or f"<error: {r.error}>"
+        raw.append({
+            "provider": r.provider,
+            "model": r.model,
+            "tokens_in": r.input_tokens,
+            "tokens_out": r.output_tokens,
+            "latency_ms": r.latency_ms,
+            "error": r.error,
+            "text": body,
+        })
+        md_lines.append(f"### {r.provider} ({r.model})")
+        md_lines.append("")
+        md_lines.append(f"- tokens in: {r.input_tokens} · out: {r.output_tokens} · latency: {r.latency_ms}ms")
+        if r.error:
+            md_lines.append(f"- error: `{r.error}`")
+        md_lines.append("")
+        md_lines.append("```")
+        md_lines.append(body[:8000])
+        md_lines.append("```")
+        md_lines.append("")
+
+    md_path.write_text("\n".join(md_lines), encoding="utf-8")
+    json_path.write_text(json.dumps(raw, indent=2), encoding="utf-8")
+    print(f"✅  Wrote {md_path}", file=sys.stderr)
+    print(f"✅  Wrote {json_path}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/update_counts.py

@@ -67,16 +67,12 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
             # the raw file count this script computes.
         ],
     ),
-    (
-        "AGENTS.md",
-        [
-            (r"(skills/\s+\()(\d+)( skills\))", "skills"),
-            (r"(rules/\s+\()(\d+)( rules\))", "rules"),
-            (r"(commands/\s+\()(\d+)( commands\))", "commands"),
-            (r"(guidelines/\s+\()(\d+)( guidelines\))", "guidelines"),
-            (r"(personas/\s+\()(\d+)( personas\))", "personas"),
-        ],
-    ),
+    # Note: AGENTS.md previously held the per-directory count annotations
+    # (`skills/ (N skills)`, `rules/ (N rules)`, ...). The Thin-Root
+    # refactor (Phase 6, road-to-augment-limit-fit, 2026-05-08) made
+    # AGENTS.md a navigation-only surface — counts now live in README.md
+    # and docs/architecture.md. The corresponding pytest sentinel lives
+    # in tests/test_readme_hero_counts.py::test_agents_md_is_thin_root_navigation_surface.
     (
         "docs/getting-started.md",
         [