pi-dev-team 0.2.0

package/skills/code-review/scripts/repo_invariants.py

@@ -0,0 +1,1066 @@
+#!/usr/bin/env python3
+"""Deterministic pre-pass for repo-specific "every X has a Y" invariants (#1608).
+
+`/code-review`'s final panel round on PR #1600 independently rediscovered the
+same mechanically-checkable fact in four separate agent dispatches
+(`doc-review`, `structure-review`, `ai-provenance-review`, `test-review`):
+a newly-added script module under a `scripts/` directory had no corresponding
+row in its skill's own documentation. That shape — "every module under
+SCRIPTS_DIR should be named at least once in its skill's docs" — is a glob
+check, not a semantic judgment call, but nothing stopped the full panel from
+re-deriving it once per agent per round.
+
+This module is a small, growable registry of such checks. Each check takes an
+optional `changed_files` list (repo-relative paths for this review's
+changeset, or `None` for "check everything") and returns a list of finding
+dicts:
+
+    {"invariant": <str>, "file": <repo-relative str>, "message": <str>}
+
+`changed_files` exists because some invariants are **required going forward
+but explicitly not retrofitted** — the `_calibration` convention in
+`evals/README.md` is the motivating case ("Required for every NEW fixture
+going forward. Do not retrofit the ~140 existing fixtures — that is pure
+churn with no discovered provenance to record"). Scoping such a check to the
+changeset enforces it on exactly the fixtures being authored right now, which
+is also where #1629 wants it: the author gets the finding **before** round 1
+instead of from it. A check that applies corpus-wide simply ignores the
+argument.
+
+**Not Python-specific — a check operates on whatever file types the
+invariant it's proving is about.** The one shipped here happens to walk a
+directory that is entirely `.py` today only because this repo's own shipped
+scripts are Python-only by convention (ADR 0014/0015); the glob itself
+matches every file in that directory regardless of extension, and a future
+check is free to target `.ts`/`.cs`/`.java`/`.go`/anything else this repo or
+a downstream project's own conventions call for — `/code-review` runs
+against projects in every language this plugin supports (see
+`skills/static-analysis-integration/references/tool-configs.md`'s
+per-language tool tiers), so new checks should not assume a Python target
+just because the first one did. Add new checks by writing a function and
+appending it to `CHECKS` below. Start narrow — this ships with exactly one
+check (mutation-testing scripts documented) — and expand opportunistically
+as more "N agents rediscovered the same mechanical fact" cases turn up (see
+the issue for the intended pattern).
+
+Wired into `/code-review` step 2b (see `skills/code-review/SKILL.md`):
+findings are injected into agent context the same way static-analysis
+findings already are — "detected by static analysis, do not re-report,
+focus on semantic concerns" — so agents stop spending tokens re-deriving
+facts this script already proved.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# skills/code-review/scripts -> skills/code-review -> skills -> plugin root
+_PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+
+# The `agents/` directory root and its *-review.md glob are the shared,
+# resolved single source of truth in hooks/lib (#1904 item 3) — scripts/ ->
+# hooks/lib/ is the correct dependency direction (see
+# review_agent_registry.py's own docstring). Import rather than re-deriving
+# `_PLUGIN_ROOT / "agents"` locally.
+sys.path.insert(0, str(_PLUGIN_ROOT / "hooks" / "lib"))
+import boundary_events
+import review_dispatch_ledger
+from review_agent_registry import (
+    default_agents_dir,
+    find_review_agent_files,
+)
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+_IGNORED_SCRIPT_NAMES = frozenset({"__init__.py", "__pycache__"})
+
+
+#: Skills whose `scripts/` modules must each be named in that skill's own
+#: documentation. A registry rather than one function per skill: the second
+#: skill needing this check arrived (#1981) and copying the first would have
+#: reproduced the duplication the review lenses exist to flag.
+#:
+#: Each entry: (skill name, extra doc paths relative to the plugin root). The
+#: skill's own `SKILL.md` and every `references/**/*.md` under it are always
+#: part of the doc set; `extra` is for docs that live outside the skill dir.
+_DOCUMENTED_SCRIPT_SKILLS = (
+    ("mutation-testing", ("agents/mutation-kill.md",), "mutation-kill-scripts-documented"),
+    ("code-review", (), "code-review-scripts-documented"),
+)
+
+
+def _skill_doc_text(skill: str, extra: tuple) -> str:
+    skill_dir = _PLUGIN_ROOT / "skills" / skill
+    doc_files = [skill_dir / "SKILL.md"]
+    doc_files.extend(_PLUGIN_ROOT / rel for rel in extra)
+    for sub in ("references", ""):
+        target = skill_dir / sub if sub else skill_dir
+        if target.is_dir():
+            doc_files.extend(sorted(target.rglob("*.md")))
+    return "\n".join(_read_text(p) for p in doc_files)
+
+
+def check_skill_scripts_documented(changed_files=None) -> list[dict]:
+    """Every module under a registered skill's scripts/ dir must be named at
+    least once in that skill's own documentation, so a reviewer can find a
+    script's purpose without re-deriving it from source.
+
+    This is the invariant that created this module: on PR #1600 four separate
+    agents (`doc-review`, `structure-review`, `ai-provenance-review`,
+    `test-review`) independently rediscovered that a newly-added script had no
+    documentation row. It shipped covering `mutation-testing` alone.
+
+    #1981 is the second report of the same class, in a different directory:
+    `skills/code-review/scripts/` had gained `review_value_coverage.py` (from
+    #2020) with no mention in its own skill's docs. Under this repo's ratchet
+    rule a twice-reported mechanical class becomes a check, so the hardcoded
+    single-skill form became this registry.
+
+    Matches every file regardless of extension — these directories happen to
+    be all-Python today (ADR 0014/0015), but "every module is documented" is
+    language-agnostic and must keep holding if a differently-extensioned file
+    lands.
+
+    Corpus-wide by design: `changed_files` is ignored. An undocumented script
+    is a standing gap whether or not this changeset touched it, and the whole
+    point is that the panel is told about it once instead of N agents each
+    finding it.
+    """
+    findings = []
+    for skill, extra, invariant in _DOCUMENTED_SCRIPT_SKILLS:
+        scripts_dir = _PLUGIN_ROOT / "skills" / skill / "scripts"
+        if not scripts_dir.is_dir():
+            continue
+        combined = _skill_doc_text(skill, extra)
+        for script in sorted(scripts_dir.iterdir()):
+            if not script.is_file() or script.name in _IGNORED_SCRIPT_NAMES:
+                continue
+            if script.name in combined:
+                continue
+            findings.append(
+                {
+                    "invariant": invariant,
+                    "file": str(script.relative_to(_PLUGIN_ROOT)),
+                    "message": (
+                        f"{script.name} is not named anywhere in the {skill} "
+                        "skill's own documentation set (its SKILL.md or "
+                        "references/**/*.md). Add a mention so reviewers "
+                        "don't have to re-derive its purpose from source."
+                    ),
+                }
+            )
+    return findings
+
+
+# --- #1629: churn generators observed in PR #1619 -------------------------
+#
+# Of #1619's 8 follow-up review rounds, at least 4 were triggered by defect
+# classes that never needed an opus reviewer to catch. Each check below
+# encodes one of them, so the author sees it at edit time and the panel gets
+# "already detected — do not re-report" framing instead of N agents
+# rediscovering the same mechanical fact.
+
+_REPO_ROOT = _PLUGIN_ROOT.parents[1]
+
+
+def _repo_relative(path: Path) -> str:
+    """Repo-relative path as a forward-slash string, matching `_changed_set`'s
+    own normalization. On Windows, `str(Path(...))` renders native
+    backslashes — comparing that directly against `_changed_set`'s
+    forward-slash-normalized entries (`rel not in changed`, used by every
+    changed-file-scoped check below) never matches, silently emptying every
+    finding on Windows regardless of what actually changed."""
+    try:
+        rel = str(path.relative_to(_REPO_ROOT))
+    except ValueError:
+        rel = str(path)
+    return rel.replace("\\", "/")
+
+
+def _changed_set(changed_files):
+    if changed_files is None:
+        return None
+    out = set()
+    for raw in changed_files:
+        name = str(raw or "").strip().replace("\\", "/")
+        while name.startswith("./"):
+            name = name[2:]
+        if name:
+            out.add(name)
+    return out
+
+
+def _load_json(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _expectation_entries(spec: dict):
+    """Yield `(target_name, entry_dict)` for every agent/skill expectation."""
+    for section in ("agents", "skills"):
+        block = spec.get(section)
+        if isinstance(block, dict):
+            for name, entry in block.items():
+                if isinstance(entry, dict):
+                    yield name, entry
+
+
+def _declares_tolerance_window(entry: dict) -> bool:
+    """True when this expectation carries a `min`/`max` tolerance window —
+    the precondition `evals/README.md` attaches the `_calibration`
+    requirement to. An expectation with only `expectedStatus` and keyword
+    lists has no bounds whose provenance could be recorded."""
+    count = entry.get("issueCount")
+    if isinstance(count, dict) and ("min" in count or "max" in count):
+        return True
+    severities = entry.get("severities")
+    if isinstance(severities, dict):
+        for bounds in severities.values():
+            if isinstance(bounds, dict) and ("min" in bounds or "max" in bounds):
+                return True
+    return False
+
+
+def check_eval_calibration_blocks(changed_files=None) -> list[dict]:
+    """Every NEW `evals/expected/*.json` expectation that declares a `min`/
+    `max` tolerance window must carry the `_calibration` block
+    `evals/README.md` requires.
+
+    #1619's round 1 lost a full `correctness-review` dispatch to exactly this
+    — a mechanically checkable convention miss.
+
+    **Scoped to `changed_files` when given.** The README explicitly forbids
+    retrofitting the ~140 pre-existing fixtures, so a corpus-wide sweep would
+    emit ~140 findings the convention says not to act on. With no changeset
+    the check reports nothing rather than every legacy fixture.
+    """
+    changed = _changed_set(changed_files)
+    if changed is None:
+        return []
+
+    expected_dir = _REPO_ROOT / "evals" / "expected"
+    findings = []
+    for name in sorted(changed):
+        if not (name.startswith("evals/expected/") and name.endswith(".json")):
+            continue
+        path = _REPO_ROOT / name
+        if not path.is_file():
+            continue
+        spec = _load_json(path)
+        if not isinstance(spec, dict):
+            continue
+        for target, entry in _expectation_entries(spec):
+            if not _declares_tolerance_window(entry):
+                continue
+            calibration = entry.get("_calibration")
+            if isinstance(calibration, dict) and calibration.get("source"):
+                continue
+            findings.append(
+                {
+                    "invariant": "eval-calibration-block-required",
+                    "file": _repo_relative(path),
+                    "message": (
+                        f"expectation for {target!r} declares a min/max tolerance "
+                        "window but carries no `_calibration` block. "
+                        "evals/README.md requires one on every new fixture with "
+                        "bounds: {\"source\": \"measured\"|\"estimated-by-analogy\", "
+                        '"note": "<one-line rationale>"}. Without it, a later '
+                        "\"tidy up the ranges\" pass can silently widen a bound that "
+                        "was tuned against this fixture's own measured behavior."
+                    ),
+                }
+            )
+    _ = expected_dir  # documented location; findings are keyed off changed paths
+    return findings
+
+
+def check_must_not_mention_terms_appear_in_fixture(changed_files=None) -> list[dict]:
+    """Every `mustNotMention` term should actually appear somewhere in its
+    paired fixture — otherwise the guard is vacuous.
+
+    `mustNotMention` is an all-of "none of these may appear in the agent's
+    output" assertion. If a forbidden term does not occur in the fixture at
+    all, the agent had no reason to emit it and the assertion passes
+    trivially, proving nothing while reading like coverage. This is the
+    corpus-level half of the negation-blindness trap `docs/eval-maintenance.md`
+    documents (#1622).
+
+    Coordinates with, rather than duplicates, `scripts/eval_grade.py
+    --check-corpus`: if that gate grows this rule, delete this check and let
+    the pre-pass call the grader instead. Today `--check-corpus` has no
+    `mustNotMention` rule, so this is the only place it is enforced.
+
+    **Scoped to `changed_files`**, like the calibration check and for the same
+    reason: the corpus carries ~31 pre-existing hits (measured 2026-07-31),
+    some of which are deliberate — `security-review`'s hardcoded-secrets
+    fixture forbids "environment variable" to stop the agent recommending a
+    weak fix, and that term legitimately isn't in the fixture. Sweeping
+    corpus-wide inside every `/code-review` pre-pass would bury each panel in
+    unrelated legacy findings, the exact opposite of this slice's purpose.
+    Run with `--all` to triage that backlog deliberately.
+    """
+    changed = _changed_set(changed_files)
+    if changed is None:
+        return []
+    expected_dir = _REPO_ROOT / "evals" / "expected"
+    fixtures_dir = _REPO_ROOT / "evals" / "fixtures"
+    if not expected_dir.is_dir() or not fixtures_dir.is_dir():
+        return []
+
+    fixture_text_by_stem = {}
+    for path in fixtures_dir.iterdir():
+        stem = path.name if path.is_dir() else path.stem
+        if path.is_file():
+            fixture_text_by_stem[stem] = _read_text(path).lower()
+
+    findings = []
+    for path in sorted(expected_dir.glob("*.json")):
+        rel = _repo_relative(path)
+        if changed is not None and rel not in changed:
+            continue
+        spec = _load_json(path)
+        if not isinstance(spec, dict):
+            continue
+        fixture_text = fixture_text_by_stem.get(path.stem)
+        if fixture_text is None:
+            # No readable paired fixture (a directory fixture, or a missing
+            # one --check-corpus already warns about). Nothing to prove here.
+            continue
+        for target, entry in _expectation_entries(spec):
+            for term in entry.get("mustNotMention") or []:
+                if not isinstance(term, str) or not term.strip():
+                    continue
+                if term.lower() in fixture_text:
+                    continue
+                findings.append(
+                    {
+                        "invariant": "must-not-mention-term-absent-from-fixture",
+                        "file": rel,
+                        "message": (
+                            f"{target!r} forbids {term!r} via mustNotMention, but that "
+                            "string never appears in the paired fixture — the agent had "
+                            "no reason to emit it, so the assertion passes trivially and "
+                            "proves nothing. Either drop the term (see "
+                            "docs/eval-maintenance.md's negation-blindness trap) or point "
+                            "it at something the fixture actually contains."
+                        ),
+                    }
+                )
+    return findings
+
+
+#: `Scope:` glob extensions vs. the prose Skip rule's extension list. A
+#: review agent that declares `**/*.{js,mjs,cjs,ts}` in `Scope:` but whose
+#: Skip section only names `.js`/`.ts` self-skips on files the resolver
+#: correctly routed to it — the `.mjs`/`.cjs` mismatch class from #1622.
+_SCOPE_BLOCK_RE = re.compile(r"^\s*Scope\s*:\s*(.*)$", re.MULTILINE)
+_EXT_RE = re.compile(r"\.([a-z0-9]{1,6})\b", re.IGNORECASE)
+_BRACE_RE = re.compile(r"\{([^}]*)\}")
+
+
+def _scope_extensions(body: str) -> set:
+    """Extensions named by an agent's `Scope:` glob list, expanding brace
+    alternation (`*.{js,mjs}`)."""
+    match = _SCOPE_BLOCK_RE.search(body)
+    if not match:
+        return set()
+    # A Scope: block may be a scalar on one line or a following YAML-ish list.
+    start = match.end()
+    lines = [match.group(1)]
+    for line in body[start:].splitlines():
+        if line.startswith(("-", " ", "\t")) and line.strip():
+            lines.append(line)
+        elif line.strip():
+            break
+    text = "\n".join(lines)
+    exts = set()
+    for group in _BRACE_RE.findall(text):
+        for part in group.split(","):
+            part = part.strip().lstrip(".")
+            if part and re.fullmatch(r"[a-z0-9]{1,6}", part, re.IGNORECASE):
+                exts.add("." + part.lower())
+    text = _BRACE_RE.sub(" ", text)
+    exts.update(m.group(0).lower() for m in _EXT_RE.finditer(text))
+    return exts
+
+
+def _skip_section_extensions(body: str) -> set:
+    """Extensions named in the agent's prose `## Skip` section."""
+    match = re.search(r"^##\s+Skip\s*$", body, re.MULTILINE)
+    if not match:
+        return set()
+    rest = body[match.end() :]
+    end = re.search(r"^##\s+", rest, re.MULTILINE)
+    section = rest[: end.start()] if end else rest
+    return {m.group(0).lower() for m in _EXT_RE.finditer(section)}
+
+
+def check_scope_glob_matches_skip_prose(changed_files=None) -> list[dict]:
+    """A review agent's `Scope:` globs and its prose `## Skip` rule must name
+    the same file extensions.
+
+    When `Scope:` routes `.mjs`/`.cjs` to an agent whose Skip section only
+    lists `.js`/`.ts`, the agent self-skips files the resolver deliberately
+    sent it — a silent coverage hole no runtime check catches, and the
+    mismatch class #1622 found. Only extensions the Skip section could
+    plausibly be enumerating are compared: a Skip section naming no
+    extensions at all is not making a claim about file types.
+
+    **Scoped to `changed_files`** for consistency with the two checks above.
+    Three pre-existing hits exist as of 2026-07-31 — `js-fp-review`
+    (`.mjs`/`.cjs`, the original #1622 case), `angular-reactivity-review`,
+    and `component-architecture-review` — all real, none fixed by this slice,
+    which adds the detector rather than the corrections. `--all` surfaces
+    them for deliberate triage.
+    """
+    changed = _changed_set(changed_files)
+    if changed is None:
+        return []
+    agents_dir = default_agents_dir()
+    if not agents_dir.is_dir():
+        return []
+
+    findings = []
+    for path in find_review_agent_files(agents_dir):
+        rel = _repo_relative(path)
+        if changed is not None and rel not in changed:
+            continue
+        body = _read_text(path)
+        scope_exts = _scope_extensions(body)
+        skip_exts = _skip_section_extensions(body)
+        if not scope_exts or not skip_exts:
+            continue
+        missing = sorted(scope_exts - skip_exts)
+        if not missing:
+            continue
+        findings.append(
+            {
+                "invariant": "scope-glob-skip-prose-extension-drift",
+                "file": rel,
+                "message": (
+                    f"Scope: routes {', '.join(missing)} to this agent, but its "
+                    "## Skip section never names those extensions. The agent will "
+                    "self-skip files the resolver deliberately sent it — a silent "
+                    "coverage hole. Add them to the Skip prose, or narrow the "
+                    "Scope: globs so the two agree."
+                ),
+            }
+        )
+    return findings
+
+
+def check_contract_failure_shapes_documented(changed_files=None) -> list[dict]:
+    """`telemetry-schema.md`'s `contract-failures.jsonl` `shape` table row
+    must enumerate exactly `validate_review_output.FAILURE_SHAPES` (#1998).
+
+    Two independent review agents (doc-review in wave 1, domain-review in
+    wave 2 — same PR) rediscovered the same drift: prose enumerating the
+    loggable failure shapes disagreeing with the module's actual behavior.
+    `SKILL.md` no longer re-enumerates the set itself (it now points at
+    `telemetry-schema.md` instead), so only one doc can drift from the code
+    now — this check pins that one doc to the module's exported set rather
+    than trusting prose to stay in sync by hand.
+    """
+    telemetry_schema = _PLUGIN_ROOT / "knowledge" / "telemetry-schema.md"
+    text = _read_text(telemetry_schema)
+    match = re.search(r"\|\s*`shape`\s*\|\s*string enum\s*\|([^\n]*)", text)
+    if not match:
+        return [
+            {
+                "invariant": "contract-failure-shapes-documented",
+                "file": "knowledge/telemetry-schema.md",
+                "message": (
+                    "Could not find the contract-failures.jsonl `shape` table row to "
+                    "check against validate_review_output.FAILURE_SHAPES — has the "
+                    "table row been reworded or removed?"
+                ),
+            }
+        ]
+    cell = match.group(1).split(" — ", 1)[0]
+    documented = frozenset(re.findall(r"`([a-z-]+)`", cell))
+
+    from validate_review_output import FAILURE_SHAPES
+
+    if documented == FAILURE_SHAPES:
+        return []
+    return [
+        {
+            "invariant": "contract-failure-shapes-documented",
+            "file": "knowledge/telemetry-schema.md",
+            "message": (
+                f"telemetry-schema.md's contract-failures.jsonl `shape` row documents "
+                f"{sorted(documented)}, but validate_review_output.FAILURE_SHAPES is "
+                f"{sorted(FAILURE_SHAPES)} — keep the table row and the module's "
+                "exported set in sync."
+            ),
+        }
+    ]
+
+
+# --- #2048: a second transcript parser must not reappear -------------------
+#
+# ADR 0036 records that both `structure-review` and `arch-review` raised the
+# same duplication independently while reviewing #1991 -- two scripts each
+# carrying their own copy of transcript-record and usage-block parsing,
+# already drifted twice on the same defect class (#1990/#1991/#1994).
+# Epic #2040 unified both into `session_log/` + one entry point
+# (`session_report.py`). This check is the ratchet that keeps a THIRD
+# independent copy from growing back once the two originals are gone.
+
+#: Any file outside `plugins/dev-team/scripts/lib/session_log/` that
+#: references one of these identifiers is either genuinely parsing a raw
+#: transcript record / usage block (a real second implementation) or reading
+#: an already-extracted usage dict's known numeric fields (not the same
+#: failure mode) -- `_TRANSCRIPT_PARSING_ALLOWLIST` below distinguishes the
+#: two per-file, with a reason each. `cache_creation_input_tokens` and
+#: `cache_read_input_tokens` are usage-block field names; `isSidechain` and
+#: `attributionAgent` are raw-record top-level fields no usage-only consumer
+#: would ever need, so their presence is the stronger of the two signals.
+_TRANSCRIPT_FIELD_RE = re.compile(
+    r"\b(cache_creation_input_tokens|cache_read_input_tokens|isSidechain|attributionAgent)\b"
+)
+
+#: Directories (repo-root-relative) this check scans -- everywhere a
+#: transcript-parsing module has actually turned up historically (the
+#: shipped plugin tree, and the monorepo's own repo-root `scripts/`, where
+#: `measure_full_file_duplication.py` and the eval/experiment harnesses
+#: live). Repo-root `tests/` is deliberately not a scan root: fixture
+#: literals constructing synthetic usage dicts are not "parsing," and
+#: scanning them would bury the real findings in noise.
+_TRANSCRIPT_SCAN_ROOTS = ("plugins/dev-team", "scripts")
+
+#: Shrink-only (docs/adr/0032's "mechanically, not by comment alone"
+#: pattern, mirrored here for #2048's invariant). Each entry states WHY the
+#: match is not the failure mode this check targets. Two shapes:
+#:   - "the sanctioned entry point" -- composes session_log's own shared
+#:     primitives rather than reimplementing them independently;
+#:   - "reads a pre-extracted usage dict" -- consumes a `usage` mapping a
+#:     caller already extracted (a handful of known numeric field names),
+#:     never a raw transcript record (no isSidechain/attributionAgent
+#:     access) -- a materially different, much narrower concern than
+#:     parsing a transcript.
+#: A "migrated in #2050" entry is a real, temporary exception: that slice's
+#: job is to fold it onto session_log.records and delete it from this list.
+_TRANSCRIPT_PARSING_ALLOWLIST = {
+    "plugins/dev-team/scripts/lib/session_report_maintainer.py": (
+        "the maintainer half of the one sanctioned entry point over "
+        "session_log (#2046/#2047), relocated from session_report.py "
+        "itself in issue #2098's layering split -- not a second, "
+        "independently-drifting implementation; it composes session_log's "
+        "own shared primitives (records.usage_of/usage_fields, "
+        "signals.CONTEXT_TOKEN_FIELDS, discovery.*) for its remaining "
+        "attribution/threading logic, mirroring exactly what its two "
+        "now-retired predecessors did"
+    ),
+    "plugins/dev-team/scripts/lib/session_report_downstream.py": (
+        "the downstream half of the one sanctioned entry point over "
+        "session_log (#2046/#2047), relocated from session_report.py "
+        "itself in issue #2098's layering split -- same rationale as "
+        "session_report_maintainer.py's entry above"
+    ),
+    "plugins/dev-team/hooks/lib/cost_meter.py": (
+        "migrated onto session_log.records in #2050 (join-map, sidechain, "
+        "and attribution logic all now delegate to _records.*); the four "
+        "identifiers remain on this file's own module docstring and inline "
+        "comments, which document the harness fields this hook's DECISIONS "
+        "are still based on -- prose, not a second parsing implementation"
+    ),
+    "scripts/measure_full_file_duplication.py": (
+        "migrated onto session_log.records in #2050 -- the join-map "
+        "algorithm this file's own docstring once conceded duplicating is "
+        "now imported (session_log_records.join_dispatch_agent_ids), and "
+        "the local _usage_from_record/_join_dispatch_agent_ids copies are "
+        "deleted; the identifiers remain in this file's module docstring "
+        "(Privacy boundary section) describing which fields it reads"
+    ),
+    "plugins/dev-team/hooks/subagent_completion_guard.py": (
+        "reads only message.stop_reason and message.content off the LAST "
+        "JSON row of a subagent's own transcript file -- never "
+        "isSidechain/attributionAgent/cache_*_input_tokens; the two "
+        "'isSidechain' occurrences are both in this file's own module "
+        "docstring, recording issue #2188's Step 2.1a research finding "
+        "(a subagent's own transcript file is isSidechain:true by "
+        "construction, so no sidechain filtering is needed). This file "
+        "DOES carry its own small last-row reader (_tail_lines/_last_row) "
+        "rather than session_log.records.iter_file_records -- deliberately: "
+        "iter_file_records silently skips an undecodable line and "
+        "continues, while this hook needs 'the trailing line is malformed "
+        "JSON' to classify as its own distinct outcome ('unreadable'), "
+        "which a streaming skip-and-continue reader cannot express. A "
+        "narrower concern than the four-identifier duplication this "
+        "invariant targets, not zero"
+    ),
+    "plugins/dev-team/hooks/review_verdict_recorder.py": (
+        "attributionAgent is read only through session_log.records "
+        "(attribution_agent_of); the 'attributionAgent' occurrences this "
+        "check's own regex matches are all in this file's own module "
+        "docstring, recording #2166 Step 2.3's own pre-implementation spike "
+        "finding against 124 real subagent transcripts (mirrors "
+        "cost_meter.py's entry above: prose documenting the harness field "
+        "this hook's decisions are based on, not a second parsing "
+        "implementation). `agentId` is NOT one of this check's own scanned "
+        "identifiers (see _TRANSCRIPT_FIELD_RE above) and is read directly "
+        "as a plain top-level field (`_own_agent_id`'s `rec.get(\"agentId\")`) "
+        "rather than through session_log -- correcting this entry's prior, "
+        "inaccurate 'never a raw field access' claim about it (#2166 Fix "
+        "#9, correctness review). This file's own transcript reader, "
+        "`_read_transcript_records`, delegates to "
+        "session_log.records.iter_file_records (Fix #9) rather than "
+        "carrying a second whole-file reader"
+    ),
+    "plugins/dev-team/hooks/lib/pricing.py": (
+        "reads a pre-extracted usage dict's known numeric fields "
+        "(cache_creation_input_tokens/cache_read_input_tokens) for cost "
+        "computation -- never a raw transcript record (no isSidechain/"
+        "attributionAgent access), so this is not the duplication this "
+        "invariant targets"
+    ),
+    "plugins/dev-team/skills/headless-run/scripts/isolated_dispatch.py": (
+        "reads a pre-extracted usage dict's cache-token fields for its own "
+        "cost estimate -- never a raw transcript record"
+    ),
+    "scripts/run_integration_eval.py": (
+        "reads a pre-extracted usage dict's known token fields to sum "
+        "eval-harness cost -- never a raw transcript record"
+    ),
+    "scripts/run_refactor_experiment.py": (
+        "reads a pre-extracted usage dict's known token fields to sum "
+        "experiment-harness cost -- never a raw transcript record"
+    ),
+    "scripts/run_tdd_experiment.py": (
+        "reads a pre-extracted usage dict's known token fields to sum "
+        "experiment-harness cost -- never a raw transcript record"
+    ),
+    "scripts/measure_rereview_duplication.py": (
+        "#2165's empirical leg composes measure_full_file_duplication.py's "
+        "own sanctioned collect_agent_dispatches/filter_since (already "
+        "migrated onto session_log.records in #2050) rather than "
+        "reimplementing transcript parsing -- never a raw transcript "
+        "record read directly by this file; the four identifiers remain "
+        "in this file's own module docstring (Privacy boundary section) "
+        "documenting which fields the empirical leg's output is limited to"
+    ),
+}
+
+
+def check_transcript_parsing_confined_to_session_log(changed_files=None) -> list[dict]:
+    """No module outside `plugins/dev-team/scripts/lib/session_log/` may
+    parse a transcript record or a usage block (#2048).
+
+    ADR 0036: both `structure-review` and `arch-review` independently
+    raised the same duplication while reviewing #1991 -- that is the
+    "second report" this repo's own ratchet rule converts into a check.
+    Without it, nothing stops a third independent transcript parser from
+    growing back the moment the two the epic just unified are gone.
+
+    Corpus-wide by design, like `check_skill_scripts_documented`:
+    `changed_files` is ignored. A stray transcript-parsing module is a
+    standing architectural gap whether or not this changeset touched it.
+    """
+    findings = []
+    session_log_prefix = "plugins/dev-team/scripts/lib/session_log/"
+    self_rel = _repo_relative(Path(__file__).resolve())
+    for root_name in _TRANSCRIPT_SCAN_ROOTS:
+        root = _REPO_ROOT / root_name
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*.py")):
+            rel = _repo_relative(path)
+            if rel.startswith(session_log_prefix):
+                continue
+            if "/tests/" in f"/{rel}" or Path(rel).name.startswith("test_"):
+                continue
+            # This module's own source names the four identifiers to detect
+            # them and to explain each allowlist entry's reason -- that is
+            # the check's own text, not a transcript parser.
+            if rel == self_rel:
+                continue
+            if rel in _TRANSCRIPT_PARSING_ALLOWLIST:
+                continue
+            if _TRANSCRIPT_FIELD_RE.search(_read_text(path)):
+                findings.append(
+                    {
+                        "invariant": "transcript-parsing-confined-to-session-log",
+                        "file": rel,
+                        "message": (
+                            f"{rel} references a raw transcript-record or "
+                            "usage-block field (cache_creation_input_tokens / "
+                            "cache_read_input_tokens / isSidechain / "
+                            "attributionAgent) outside "
+                            "plugins/dev-team/scripts/lib/session_log/. Move "
+                            "the parsing onto session_log's shared "
+                            "primitives, or add this path to "
+                            "repo_invariants._TRANSCRIPT_PARSING_ALLOWLIST "
+                            "with a stated reason (see ADR 0036 / issue #2048)."
+                        ),
+                    }
+                )
+    return findings
+
+
+# --- #2108: churn_recurrence.py / churn_coupling_report.py render_text()
+# `report["window"]` access must stay safe -----------------------------------
+#
+# Session-digest churn analysis (issue #2108) traced repeated review-round
+# rework on the #2085 PR (bash-failure taxonomy + churn baselines slice) to
+# the SAME bug recurring in two structurally-parallel renderers. Round 2's
+# review fixed churn_recurrence.py's render_text(): it unconditionally read
+# report["window"], a key only churn_coupling_report.py's CLI caller
+# injects, so a caller rendering rank_all_files()'s own output directly hit
+# a raw KeyError; fixed via report.get("window", "unknown"). Round 3's very
+# next review pass found the IDENTICAL bug in churn_coupling_report.py's own
+# render_text() -- same key, same failure mode, in the sibling file --
+# because nothing pinned "these two report shapes agree on how this
+# caller-optional key is read." A second occurrence of the same
+# mechanically-checkable fact is this repo's own trigger to ratchet it into
+# a check, applied one round late.
+
+_CHURN_REPORT_WINDOW_KEY_FILES = (
+    "scripts/lib/churn_recurrence.py",
+    "scripts/churn_coupling_report.py",
+)
+_WINDOW_KEY_RE = re.compile(r"""report\s*\[\s*['"]window['"]\s*\]""")
+_WINDOW_KEY_ASSIGNMENT_RE = re.compile(
+    r"""report\s*\[\s*['"]window['"]\s*\]\s*=(?!=)"""
+)
+
+
+def check_churn_report_window_key_safe_access(changed_files=None) -> list[dict]:
+    """`churn_recurrence.py` and `churn_coupling_report.py`'s `render_text()`
+    must read `report["window"]` via `.get("window", "unknown")`, never a
+    bare index — see the section comment above for the twice-recurring bug
+    this pins (#2108). Assignment (`report["window"] = ...`, the CLI
+    caller's own injection site) is a different operation and is not
+    flagged. Corpus-wide by design, like the checks above: a regression on
+    either file is a standing gap whether or not this changeset touched it.
+    """
+    findings = []
+    for rel in _CHURN_REPORT_WINDOW_KEY_FILES:
+        text = _read_text(_REPO_ROOT / rel)
+        if not text:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            if not _WINDOW_KEY_RE.search(line):
+                continue
+            if _WINDOW_KEY_ASSIGNMENT_RE.search(line):
+                continue  # a write (the CLI's own injection site), not a read
+            if ".get(" in line:
+                continue  # already safe
+            findings.append(
+                {
+                    "invariant": "churn-report-window-key-safe-access",
+                    "file": rel,
+                    "message": (
+                        f"{rel}:{lineno} reads report['window'] via a bare "
+                        "index. A caller rendering a report shape that never "
+                        "sets this key (e.g. rank_all_files()'s own output) "
+                        "raises KeyError — this exact bug already recurred "
+                        "once, in the sibling renderer (#2085 round 2, then "
+                        "round 3). Use report.get('window', 'unknown') "
+                        "instead."
+                    ),
+                }
+            )
+    return findings
+
+
+# --- #2126: internal-collaborator-doubling.md must stay single-sourced ------
+#
+# Epic #2123's own design note: "cite, don't restate" cannot be an
+# acceptance criterion someone eyeballs; it needs a mechanism. Distinctive
+# fragments copied verbatim from the normative file — chosen for
+# distinctiveness (a short generic phrase like "setup is easier" would be a
+# plausible false positive anywhere in testability prose) rather than
+# derived programmatically, since the source is prose, not a table this
+# script can parse structurally like `check_contract_failure_shapes_documented`
+# does. A dedicated staleness self-check (test_repo_invariants.py) keeps
+# this list honest against the home file it was copied from.
+
+_NORMATIVE_CONTENT_HOME_FILE = "plugins/dev-team/knowledge/internal-collaborator-doubling.md"
+
+_NORMATIVE_CONTENT_FRAGMENTS = (
+    "Out-of-process handle",
+    "Prohibitive real cost",
+    "the project's own first-party source stays real",
+    "\"It's an injected interface\" — and the type's name",
+)
+# Deliberately excluded, per correctness-review (#2126):
+# - "Ambient state" -- too generic (plausible in unrelated testability prose,
+#   contradicting this list's own distinctiveness rule).
+# - "double-waiver: B" -- not restated *content*, it's the syntax convention
+#   every consumer is instructed to demonstrate; flagging it would punish
+#   agents/skills for correctly teaching the waiver marker, and "paraphrase
+#   the quote" makes no sense for a literal required syntax string.
+
+#: Directories (plugin-root-relative) a citing consumer could plausibly live
+#: in — matches where #2124/#2125's own citations actually landed
+#: (knowledge/, agents/, skills/). Anything outside these (plans/, docs/,
+#: tests/) is out of scope by design: this check targets consumers of the
+#: rule, not every place its literal words could theoretically appear.
+_NORMATIVE_CONTENT_SCAN_DIRS = ("knowledge", "agents", "skills")
+
+
+def check_normative_content_single_sourced(changed_files=None) -> list[dict]:
+    """`internal-collaborator-doubling.md` (#2124) is the single normative
+    source for the internal-collaborator doubling rule; every consumer must
+    cite it by path rather than restate its content (#2126).
+
+    Corpus-wide by design, like `check_transcript_parsing_confined_to_session_log`:
+    a restatement is a standing gap whether or not this changeset touched it.
+
+    A match is a match regardless of attribution — quoting a fragment
+    verbatim next to a citation to the home file still creates a second copy
+    that can drift from the original once either side is edited. The fix for
+    a consumer that needs to reference specific wording is to paraphrase or
+    drop the verbatim quote, not to attribute it.
+    """
+    home_path = _REPO_ROOT / _NORMATIVE_CONTENT_HOME_FILE
+    findings = []
+    for dirname in _NORMATIVE_CONTENT_SCAN_DIRS:
+        scan_root = _PLUGIN_ROOT / dirname
+        if not scan_root.is_dir():
+            continue
+        for path in sorted(scan_root.rglob("*.md")):
+            if path.resolve() == home_path.resolve():
+                continue
+            text = _read_text(path)
+            if not text:
+                continue
+            rel = _repo_relative(path)
+            for fragment in _NORMATIVE_CONTENT_FRAGMENTS:
+                if fragment in text:
+                    findings.append(
+                        {
+                            "invariant": "normative-content-single-sourced",
+                            "file": rel,
+                            "message": (
+                                f"{rel} restates a fragment of "
+                                f"{_NORMATIVE_CONTENT_HOME_FILE} verbatim "
+                                f"({fragment!r}) instead of citing it by path. "
+                                "This creates a second copy that can silently "
+                                "drift from the normative source — replace the "
+                                "restatement with a pointer."
+                            ),
+                        }
+                    )
+    return findings
+
+
+def check_ledger_filename_single_sourced(changed_files=None) -> list[dict]:
+    """`boundary-events.jsonl`'s filename must stay single-sourced from
+    `hooks/lib/boundary_events.LOG_NAME` — the module that actually writes
+    the ledger and therefore owns its name.
+
+    Backstop review against #2166 + #2171 found this filename independently
+    hand-rolled in three homes (`boundary_events._LOG_NAME`,
+    `review_dispatch_ledger.LEDGER_STREAM`, and
+    `boundary_events_write_guard.py`'s own import), reported by 4 of 8
+    reviewers (arch, domain, naming, structure) — clearing this repo's own
+    ratchet rule ("a mechanical finding reported twice becomes a check")
+    decisively. `review_dispatch_ledger.LEDGER_STREAM` is now an alias of
+    `boundary_events.LOG_NAME`, not a fresh literal — this check asserts
+    that stays an *identity*, not just an equal value, so a future edit
+    can't silently reintroduce a fourth independent copy with a green test
+    suite.
+
+    Corpus-wide by design: this is a standing structural invariant, not a
+    changeset-scoped one.
+    """
+    if review_dispatch_ledger.LEDGER_STREAM is not boundary_events.LOG_NAME:
+        return [
+            {
+                "invariant": "ledger-filename-single-sourced",
+                "file": "plugins/dev-team/hooks/lib/review_dispatch_ledger.py",
+                "message": (
+                    "review_dispatch_ledger.LEDGER_STREAM must remain the "
+                    "identical object as boundary_events.LOG_NAME (an alias, "
+                    "not a fresh literal) — boundary_events.py is the module "
+                    "that actually writes the boundary-events ledger and "
+                    "owns its filename."
+                ),
+            }
+        ]
+    return []
+
+
+# --- #2177: the context-ceiling hook and its report script are gone ----------
+#
+# ADR 0043 replaced the forced-handoff hook with harness autocompact and
+# deleted the hook, its report script and the docs around them. A stale
+# reference to either name is a dangling pointer to a file that no longer
+# exists. History (the changelog, superseded ADRs) legitimately keeps the
+# names; tests that assert the files stay gone must spell them out.
+
+_CEILING_REF_RE = re.compile(
+    rb"context_ceiling_(?:guard|report)|context-ceiling-validation|"
+    rb"DEV_TEAM_CONTEXT_ABS_CEILING"
+)
+_CEILING_REF_EXEMPT_PREFIXES = ("docs/adr/",)
+_CEILING_REF_EXEMPT_FILES = frozenset(
+    {
+        "plugins/dev-team/CHANGELOG.md",
+        # Tests that pin the removal, so they name what must stay absent.
+        "tests/hooks/test_autocompact_hook_registration.py",
+        "tests/scripts/test_no_ceiling_event_consumers.py",
+        "tests/repo/test_no_live_ceiling_refs.py",
+        "tests/skills/test_handoff_manual_only.py",
+    }
+)
+_CEILING_REF_MAX_BYTES = 2_000_000
+
+
+def _tracked_files() -> list[str] | None:
+    """Repo-relative tracked paths via `git ls-files`, or None when git is
+    unavailable or fails (the caller then skips rather than walking the tree)."""
+    try:
+        out = subprocess.run(
+            ["git", "ls-files", "-z"],
+            cwd=_REPO_ROOT,
+            capture_output=True,
+            check=True,
+            timeout=30,
+        ).stdout.decode("utf-8", "replace")
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return [p for p in out.split("\0") if p]
+
+
+def _is_marketplace_checkout() -> bool:
+    """True only in this repo's own checkout. The check ships in the plugin,
+    so downstream it runs from the plugin cache, where `_REPO_ROOT` is not a
+    repo this invariant governs."""
+    return (_REPO_ROOT / ".claude-plugin" / "marketplace.json").is_file()
+
+
+def check_no_live_ceiling_refs(changed_files=None) -> list[dict]:
+    """No tracked file outside history may reference the removed context-
+    ceiling hook or report script by name (#2177, ADR 0043).
+
+    Corpus-wide by design: a dangling pointer is wrong whether or not this
+    changeset touched it, so `changed_files` is ignored. Returns [] outside
+    this repo's own checkout and when git cannot list files.
+    """
+    if not _is_marketplace_checkout():
+        return []
+    tracked = _tracked_files()
+    if tracked is None:
+        return []
+    findings = []
+    self_rel = _repo_relative(Path(__file__).resolve())
+    for rel in sorted(tracked):
+        if (
+            rel == self_rel
+            or rel in _CEILING_REF_EXEMPT_FILES
+            or rel.startswith(_CEILING_REF_EXEMPT_PREFIXES)
+        ):
+            continue
+        path = _REPO_ROOT / rel
+        try:
+            if not path.is_file() or path.stat().st_size > _CEILING_REF_MAX_BYTES:
+                continue
+            data = path.read_bytes()  # bytes: tracked binaries are not UTF-8
+        except OSError:
+            continue
+        if _CEILING_REF_RE.search(data):
+            findings.append(
+                {
+                    "invariant": "no-live-ceiling-refs",
+                    "file": rel,
+                    "message": (
+                        f"{rel} references the removed context-ceiling hook, "
+                        "report script, validation doc or env var. All were "
+                        "removed by #2177 (ADR 0043); point at "
+                        "docs/adr/0043-replace-the-context-ceiling-guard-with-"
+                        "harness-autocompact.md or drop the reference."
+                    ),
+                }
+            )
+    return findings
+
+
+# Registered checks. Each entry takes an optional `changed_files` list and
+# returns findings. See the module docstring for why that argument exists.
+CHECKS = [
+    check_skill_scripts_documented,
+    check_eval_calibration_blocks,
+    check_must_not_mention_terms_appear_in_fixture,
+    check_scope_glob_matches_skip_prose,
+    check_contract_failure_shapes_documented,
+    check_transcript_parsing_confined_to_session_log,
+    check_churn_report_window_key_safe_access,
+    check_normative_content_single_sourced,
+    check_ledger_filename_single_sourced,
+    check_no_live_ceiling_refs,
+]
+
+
+def run_all(changed_files=None) -> list[dict]:
+    findings = []
+    for check in CHECKS:
+        findings.extend(check(changed_files))
+    return findings
+
+
+def _sweep_all() -> list[dict]:
+    """Backlog triage (`--all`): re-run the changeset-scoped checks against
+    every file they could apply to, so a maintainer can see the pre-existing
+    findings each convention chose not to retrofit. Never used by the
+    `/code-review` pre-pass."""
+    every_expected = [
+        _repo_relative(p) for p in sorted((_REPO_ROOT / "evals" / "expected").glob("*.json"))
+    ]
+    every_agent = [
+        _repo_relative(p) for p in find_review_agent_files(default_agents_dir())
+    ]
+    return run_all(every_expected + every_agent)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--files",
+        nargs="*",
+        default=None,
+        help=(
+            "Repo-relative changed files for this review. Checks scoped to new "
+            "content (e.g. the _calibration convention, which evals/README.md "
+            "forbids retrofitting) only fire for these paths."
+        ),
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        dest="sweep_all",
+        help=(
+            "Deliberate backlog triage: run every changeset-scoped check across "
+            "the whole corpus. Not for the /code-review pre-pass — it surfaces "
+            "pre-existing findings the convention that introduced each check "
+            "explicitly does not require retrofitting."
+        ),
+    )
+    args = parser.parse_args(argv)
+    if args.sweep_all:
+        findings = _sweep_all()
+    else:
+        findings = run_all(args.files)
+    print(json.dumps({"findings": findings}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))