pi-dev-team 0.2.0

package/scripts/verify_gherkin_quality_critic_isolation.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""verify_gherkin_quality_critic_isolation.py — runtime isolation check for
+the two-instance `gherkin-quality-critic` dispatch (issue #1465).
+
+`/gherkin-derive` and `/gherkin-public` both dispatch **two independent
+instances** of the `gherkin-quality-critic` agent in parallel — the whole
+point being ensemble/self-consistency corroboration on the same judgment
+call (see `knowledge/gherkin-quality-review-dispatch.md`). That mutual
+blindness — "one message, two calls, read neither result until both are
+issued" — is currently asserted only in prose and in content-guards that
+check the markdown *says* the right thing. Nothing runs two real dispatches
+and checks the isolation property held at runtime; a future refactor could
+accidentally thread one instance's output into the other's prompt and
+nothing would catch it.
+
+This script closes that gap with a cross-contamination canary: each
+instance's `.feature` fixture carries a distinct, randomly-generated marker
+string embedded in its own context (mirroring how a real dispatch's cited
+source text could carry incidental detail). Two fully independent `claude
+-p` subprocess calls dispatch the real `gherkin-quality-critic` agent (via
+the `/review-agent` skill) against each fixture — no shared mutable state, no
+piping one call's output into the other's input. If either transcript
+contains the *other* instance's canary, isolation was broken somewhere in the
+dispatch path and the script fails loudly.
+
+This intentionally diverges from production's "identical input to both
+instances" property (see the dispatch doc) — seeding a distinct marker per
+instance is what makes contamination observable at all. It does not change
+what the two instances are asked to review (the fixture's Gherkin content is
+otherwise identical); only the throwaway canary comment differs.
+
+**Opt-in, paid, fail-open.** Mirrors `evals/README.md`'s "CI gate (issue
+#99)" live-gate convention: this script dispatches the real `claude` CLI, so
+it costs tokens and must never block anyone without eval credentials. When
+the `claude` CLI is missing or `ANTHROPIC_API_KEY` is unset, it prints a
+skip message and exits 0 — never a failure. It is not wired into any CI
+workflow by this change; see `knowledge/gherkin-quality-review-dispatch.md`
+for how to run it locally (or gate it into CI the same way the existing live
+eval gate is: a label + `ANTHROPIC_API_KEY`).
+
+Stdlib only. (ADR 0014/0015).
+
+Usage:
+    python3 verify_gherkin_quality_critic_isolation.py
+    python3 verify_gherkin_quality_critic_isolation.py --model <model-id> --timeout 300
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+_DEFAULT_TIMEOUT_SECONDS = 300.0
+
+
+def _default_timeout() -> float:
+    """Per-dispatch subprocess timeout, overridable for local tuning."""
+    raw = os.environ.get("VERIFY_GHERKIN_ISOLATION_TIMEOUT")
+    if raw:
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    return _DEFAULT_TIMEOUT_SECONDS
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="model id passed to `claude -p --model` (default: omitted, so "
+        "`claude -p` uses its own configured default model — this script "
+        "does not pin a snapshot; see ADR 0026)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=_default_timeout(),
+        help="per-dispatch subprocess timeout in seconds "
+        "(default: $VERIFY_GHERKIN_ISOLATION_TIMEOUT or 300)",
+    )
+    return parser.parse_args(argv)
+
+
+def check_prerequisites() -> list[str]:
+    """Return missing-prerequisite messages (empty == ready to dispatch)."""
+    missing: list[str] = []
+    if shutil.which("claude") is None:
+        missing.append(
+            "the `claude` CLI (npm install -g @anthropic-ai/claude-code)"
+        )
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        missing.append("ANTHROPIC_API_KEY (required to dispatch a live agent call)")
+    return missing
+
+
+def build_fixture(canary: str) -> str:
+    """A minimal `.feature` file with one deliberate, known finding: two
+    success-path variants and no failure path at all — the exact
+    "unbalanced coverage" / "missing failure path" case
+    `gherkin-quality-critic` is documented to flag. `canary` is embedded as
+    a throwaway leading comment, not part of the scenario content."""
+    return textwrap.dedent(
+        f"""\
+        # isolation-canary: {canary}
+        Feature: Widget creation
+          As a user
+          I want to create a widget
+          So that I can use it later
+
+          Scenario: Create a widget with a valid name
+            Given I am authenticated
+            When I create a widget named "Anvil"
+            Then the widget is created successfully
+
+          Scenario: Create a widget with a valid name and a description
+            Given I am authenticated
+            When I create a widget named "Anvil" with description "Heavy"
+            Then the widget is created successfully
+        """
+    )
+
+
+def build_prompt(feature_path: Path, canary: str) -> str:
+    """Prompt for one dispatch. Asks the CLI to run gherkin-quality-critic
+    via the shipped /review-agent skill against exactly one fixture file,
+    mirroring how .github/workflows/agent-eval.yml's live gate dispatches a
+    named agent through its skill wrapper rather than hand-rolling the Agent
+    tool call."""
+    return textwrap.dedent(
+        f"""
+        Use the /review-agent skill to run gherkin-quality-critic against
+        exactly this one file: {feature_path}
+
+        Pass --path {feature_path.parent} --json so stdout carries ONLY the
+        agent's raw JSON result (per gherkin-quality-critic's documented
+        output format in agents/gherkin-quality-critic.md) — no other prose.
+
+        Context marker for this dispatch only: {canary}
+        This marker appears in the .feature file's opening comment purely to
+        verify this dispatch's isolation from any other concurrent dispatch.
+        It is not part of the scenario content to review — do not mention it
+        as a finding.
+        """
+    ).strip()
+
+
+def dispatch(prompt: str, model: str | None, timeout: float) -> str | None:
+    """Run one fully independent `claude -p` subprocess. Returns the raw
+    captured stdout (the "transcript"), or None on any infrastructure
+    problem (CLI crash, timeout, no output) — callers must treat None as
+    fail-open, never as a contamination finding. `model` is only appended to
+    the command when explicitly given — omitted, `claude -p` resolves its
+    own configured default rather than this script pinning a snapshot."""
+    cmd = [
+        "claude",
+        "-p",
+        prompt,
+        "--output-format",
+        "json",
+        "--max-turns",
+        "30",
+        "--allowedTools",
+        "Read",
+        "Glob",
+        "Grep",
+        "Skill(review-agent *)",
+        "Agent",
+    ]
+    if model:
+        cmd += ["--model", model]
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        print(
+            f"SKIP: dispatch could not run ({exc}) — treating as an "
+            "infrastructure problem, not a contamination finding.",
+            file=sys.stderr,
+        )
+        return None
+    if not proc.stdout.strip():
+        print(
+            f"SKIP: dispatch produced no output (exit {proc.returncode}); "
+            f"stderr: {proc.stderr.strip()[:300]}",
+            file=sys.stderr,
+        )
+        return None
+    return proc.stdout
+
+
+def check_cross_contamination(
+    transcript_a: str, transcript_b: str, canary_a: str, canary_b: str
+) -> list[str]:
+    """Return a list of contamination violations (empty == isolation held).
+
+    A violation is instance A's transcript containing instance B's canary
+    (or vice versa) — the marker seeded only into the OTHER instance's
+    fixture context. Either direction means output/context leaked across
+    the two supposedly-independent dispatches.
+    """
+    violations: list[str] = []
+    if canary_b in transcript_a:
+        violations.append(
+            f"instance A's transcript contains instance B's canary marker "
+            f"({canary_b}) — dispatch isolation broken"
+        )
+    if canary_a in transcript_b:
+        violations.append(
+            f"instance B's transcript contains instance A's canary marker "
+            f"({canary_a}) — dispatch isolation broken"
+        )
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+
+    missing = check_prerequisites()
+    if missing:
+        print(
+            "SKIP: gherkin-quality-critic isolation check requires a live "
+            "dispatch and cannot run here:"
+        )
+        for item in missing:
+            print(f"  - {item}")
+        print(
+            "This is an opt-in, paid, live check (mirrors evals/README.md's "
+            "CI gate) — skipping, not failing."
+        )
+        return 0
+
+    canary_a = f"ISOLATION-CANARY-A-{secrets.token_hex(8)}"
+    canary_b = f"ISOLATION-CANARY-B-{secrets.token_hex(8)}"
+
+    with tempfile.TemporaryDirectory(prefix="gherkin-isolation-") as tmp:
+        tmp_path = Path(tmp)
+        dir_a = tmp_path / "instance_a"
+        dir_b = tmp_path / "instance_b"
+        dir_a.mkdir()
+        dir_b.mkdir()
+        feature_a = dir_a / "widget_creation.feature"
+        feature_b = dir_b / "widget_creation.feature"
+        feature_a.write_text(build_fixture(canary_a))
+        feature_b.write_text(build_fixture(canary_b))
+
+        prompt_a = build_prompt(feature_a, canary_a)
+        prompt_b = build_prompt(feature_b, canary_b)
+
+        # Two fully independent subprocess calls — no shared mutable state,
+        # no piping one call's output into the other's prompt.
+        transcript_a = dispatch(prompt_a, args.model, args.timeout)
+        transcript_b = dispatch(prompt_b, args.model, args.timeout)
+
+    if transcript_a is None or transcript_b is None:
+        print(
+            "SKIP: one or both dispatches did not produce usable output — "
+            "treating as an infrastructure problem, not a contamination "
+            "finding."
+        )
+        return 0
+
+    violations = check_cross_contamination(
+        transcript_a, transcript_b, canary_a, canary_b
+    )
+    if violations:
+        print(
+            "FAIL: cross-contamination detected between mutually-blind "
+            "gherkin-quality-critic dispatches:"
+        )
+        for v in violations:
+            print(f"  - {v}")
+        return 1
+
+    print(
+        "OK: both gherkin-quality-critic dispatches completed with no "
+        "cross-contamination detected."
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/scripts/verify_tier.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Resolve a review agent's verification-mode model/effort tier (#1628).
+
+When a fix loop re-dispatches an agent to CONFIRM a fix, the task is far
+narrower than discovery — "here is the finding, here is the fix diff:
+resolved or not?" — but the dispatch costs the same. An agent may opt in to a
+cheaper tier for verification dispatches only, by declaring in its **body**:
+
+    Verify-model: haiku
+    Verify-effort: medium
+
+Body declarations, not frontmatter: issue #1333 reserves agent frontmatter
+for the official Claude Code sub-agent contract recorded in
+`plugins/marketplace-dev/knowledge/agent-contract.json` (a dated snapshot of
+upstream docs, not a schema this plugin may extend). `Scope:`, `Cites:`, and
+`Enforcement:` follow the same rule. Claude Code silently ignores unknown
+frontmatter keys, so a frontmatter typo would also have been invisible; a
+body declaration this script parses is checkable.
+
+**Declared, never inferred.** With no opt-in, the returned tier is the
+agent's own discovery tier — unchanged. That default is deliberate: #1619
+showed some confirmations genuinely need top-tier judgment (the ECMA-402
+receiver-binding call), so tiering down is opt-in per agent, never a blanket
+rule and never derived from a finding's severity.
+
+Full contract: `knowledge/verification-mode.md`.
+
+Usage:
+    python3 verify_tier.py --agent structure-review
+    python3 verify_tier.py --all
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# scripts/verify_tier.py -> scripts -> plugin root
+_PLUGIN_ROOT = Path(__file__).resolve().parents[1]
+_AGENTS_DIR = _PLUGIN_ROOT / "agents"
+
+_VERIFY_MODEL_RE = re.compile(r"^\s*Verify-model\s*:\s*(\S+)\s*$", re.IGNORECASE)
+_VERIFY_EFFORT_RE = re.compile(r"^\s*Verify-effort\s*:\s*(\S+)\s*$", re.IGNORECASE)
+_FM_MODEL_RE = re.compile(r"^\s*model\s*:\s*(\S+)\s*$")
+_FM_EFFORT_RE = re.compile(r"^\s*effort\s*:\s*(\S+)\s*$")
+
+#: Same closed enums the official contract declares for `model:`/`effort:`
+#: (agent-contract.json). A declaration outside these is a typo, not a new
+#: tier — reported as an error rather than passed through to a dispatch that
+#: would fail at runtime.
+VALID_MODELS = frozenset({"sonnet", "opus", "haiku", "fable", "inherit"})
+VALID_EFFORTS = frozenset({"low", "medium", "high", "xhigh", "max"})
+
+
+def _split(text: str) -> tuple[str, str]:
+    """Return `(frontmatter, body)`. A file without frontmatter is all body."""
+    if not text.startswith("---"):
+        return "", text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return "", text
+    after = text.find("\n", end + 1)
+    return text[3:end], (text[after + 1 :] if after != -1 else "")
+
+
+def resolve(text: str, agent: str = "") -> dict:
+    """Resolve the verification tier from one agent file's contents.
+
+    Returns `{"agent", "model", "effort", "opted_in", "errors"}`. `model` and
+    `effort` are the values to dispatch this agent at in verification mode —
+    already falling back to the frontmatter (discovery) values when no opt-in
+    is declared, so a caller never needs its own fallback logic.
+
+    An invalid declared value is reported in `errors` and **ignored** for that
+    field, which falls back to the discovery tier. Failing closed to the more
+    expensive tier is the right direction: a typo must never silently make a
+    review cheaper than intended.
+    """
+    frontmatter, body = _split(text)
+    errors = []
+
+    discovery_model = _first(_FM_MODEL_RE, frontmatter) or "inherit"
+    discovery_effort = _first(_FM_EFFORT_RE, frontmatter) or "inherit"
+
+    verify_model = _first(_VERIFY_MODEL_RE, body)
+    verify_effort = _first(_VERIFY_EFFORT_RE, body)
+
+    if verify_model is not None and verify_model.lower() not in VALID_MODELS:
+        errors.append(
+            f"Verify-model: {verify_model!r} is not one of {sorted(VALID_MODELS)}"
+        )
+        verify_model = None
+    if verify_effort is not None and verify_effort.lower() not in VALID_EFFORTS:
+        errors.append(
+            f"Verify-effort: {verify_effort!r} is not one of {sorted(VALID_EFFORTS)}"
+        )
+        verify_effort = None
+
+    opted_in = verify_model is not None or verify_effort is not None
+    return {
+        "agent": agent,
+        "model": (verify_model or discovery_model).lower(),
+        "effort": (verify_effort or discovery_effort).lower(),
+        "opted_in": opted_in,
+        "errors": errors,
+    }
+
+
+def _first(pattern, text: str):
+    for line in text.splitlines():
+        match = pattern.match(line)
+        if match:
+            return match.group(1)
+    return None
+
+
+def resolve_agent(name: str, agents_dir: Path | None = None) -> dict:
+    path = (agents_dir or _AGENTS_DIR) / f"{name}.md"
+    if not path.is_file():
+        return {
+            "agent": name,
+            "model": "inherit",
+            "effort": "inherit",
+            "opted_in": False,
+            "errors": [f"no such agent file: {path}"],
+        }
+    return resolve(path.read_text(encoding="utf-8"), name)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="Resolve verification-mode dispatch tiers.")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--agent", help="Agent name (without .md)")
+    group.add_argument("--all", action="store_true", help="Every review agent")
+    parser.add_argument("--agents-dir", type=Path, default=_AGENTS_DIR)
+    args = parser.parse_args(argv)
+
+    if args.agent:
+        result = resolve_agent(args.agent, args.agents_dir)
+        print(json.dumps(result, sort_keys=True))
+        return 1 if result["errors"] else 0
+
+    results = [
+        resolve_agent(path.stem, args.agents_dir)
+        for path in sorted(args.agents_dir.glob("*-review.md"))
+    ]
+    print(json.dumps({"agents": results}, sort_keys=True))
+    return 1 if any(r["errors"] for r in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/adr-tools/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: adr-tools
+description: Create and manage Architecture Decision Records using the npryce adr-tools CLI. Use when the user asks to "add an ADR", "record this decision", "create an ADR", "supersede ADR N", "link ADRs", "generate the ADR table of contents", or any request involving the `adr` command. Pairs with the adr-author agent — this skill is the mechanics (commands, files, links); adr-author is the decision framework (when an ADR is warranted) and the prose authoring.
+role: worker
+user-invocable: true
+---
+
+# ADR Tools
+
+Mechanics for working with [npryce/adr-tools](https://github.com/npryce/adr-tools) — the `adr` CLI that creates numbered Architecture Decision Records. Pairs with the [`adr-author`](../../agents/adr-author.md) agent: that agent decides *whether* an ADR is warranted and writes the prose; this skill drives the CLI correctly.
+
+## Pre-flight
+
+```bash
+command -v adr || echo "adr-tools not installed — see https://github.com/npryce/adr-tools"
+cat .adr-dir 2>/dev/null   # project's configured ADR directory
+ls "$(cat .adr-dir 2>/dev/null || echo docs/adr)/" 2>/dev/null | head -3
+```
+
+If the pre-flight reports `adr` missing, run `/project-init` to set up this repo's tooling — it installs the `adr` CLI as a capability tool (see its `${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/capability-tools.md`) — or install it directly: see [npryce/adr-tools](https://github.com/npryce/adr-tools) (the CLI link is the fallback).
+
+Project convention is `docs/adr/`. `adr-tools` stores the directory in `.adr-dir` at the project root — `adr` reads that file to find the ADRs no matter what subdirectory you're in. If `.adr-dir` is missing, run `adr init docs/adr` once. Do not init silently into a different path — confirm with the user if existing ADRs live somewhere unexpected.
+
+## Editor caveat — the most common failure
+
+`adr new` opens `$VISUAL` or `$EDITOR` (defaulting to `vi`). In a Claude Code shell this hangs the command and exits non-zero — the file is created but empty. Two workarounds:
+
+1. **Preferred — bypass the editor.** Run with a no-op editor, then write the body with the Write tool:
+
+   ```bash
+   EDITOR=true VISUAL=true adr new "<title>"
+   ```
+
+   The command prints the new file path to stdout. Read it, then replace the template Context/Decision/Consequences sections with the real content via Edit or Write.
+
+2. **Fallback — let it fail, then fill in.** `adr new "<title>"` will create the templated file and exit non-zero from the editor failure. Read the new file (it lives at `<adr-dir>/NNNN-<slugified-title>.md` — typically `docs/adr/`) and fill it in.
+
+The skill always prefers workaround 1.
+
+## Workflows
+
+### Create a new ADR
+
+```bash
+EDITOR=true VISUAL=true adr new "<title in plain words>"
+```
+
+Then Edit the generated file to fill in:
+
+- **Status** — `Accepted` (default) is fine for decisions already made. Use `Proposed` only if there is genuine open debate.
+- **Context** — what forces drove this decision (constraints, alternatives considered, prior art)
+- **Decision** — what we are doing (active voice, present tense: "Adopt X" not "We will adopt X")
+- **Consequences** — easier / harder / risks. Be specific. If you cannot name a concrete trade-off, the decision probably did not need an ADR.
+
+Commit the new ADR in the same commit (or PR) as the implementation it justifies.
+
+### Supersede an earlier ADR
+
+```bash
+EDITOR=true VISUAL=true adr new -s <N> "<new title>"
+```
+
+`adr-tools` automatically:
+
+- Inserts a "Supersedes [ADR N](N-old-title.md)" link in the new ADR's Status section.
+- Edits ADR N's Status to "Superseded by [ADR M](M-new-title.md)".
+
+Do not delete the old ADR. Its history is the point.
+
+### Link two ADRs without superseding
+
+```bash
+adr link <SOURCE> "<LINK>" <TARGET> "<REVERSE-LINK>"
+```
+
+Example: `adr link 12 "Amends" 10 "Amended by"`. Use this for relationships like Amends/Refines/Constrains. Multiple links are normal.
+
+### List all ADRs
+
+```bash
+adr list
+```
+
+Returns sorted file paths. Pipe through `xargs head -1` for a quick title scan.
+
+### Generate the table of contents
+
+```bash
+adr generate toc > docs/adr/README.md
+```
+
+Run this after creating or superseding any ADR, then commit the regenerated TOC alongside the ADR change. Without this, the index drifts.
+
+### Generate the dependency graph
+
+```bash
+adr generate graph | dot -Tpng > docs/adr/graph.png
+```
+
+Optional but useful when supersede/link chains get deep. Requires Graphviz (`dot`).
+
+## Anti-patterns to refuse
+
+- **Don't renumber ADRs.** `adr-tools` assigns sequential numbers; references in commits, PRs, and other ADRs depend on them being stable. If a number is wrong, supersede; never renumber.
+- **Don't edit ADR status with a text editor when superseding.** Use `adr new -s <N>` so the bidirectional link is automatic and consistent.
+- **Don't squash multiple decisions into one ADR.** One decision per file. If a "Decision" section has multiple bullets that are not facets of the same choice, split.
+- **Don't write Decision in future tense.** "We will adopt X" reads as a proposal; "Adopt X" reads as a decision. Use the latter for `Accepted` status.
+- **Don't omit Consequences.** An ADR without trade-offs is a note, not a decision record. If there genuinely are no consequences, the decision did not need an ADR — defer to the [`adr-author`](../../agents/adr-author.md) decision framework.
+
+## When to defer to adr-author
+
+This skill handles the CLI mechanics. Use the [`adr-author`](../../agents/adr-author.md) agent when:
+
+- It is unclear whether the change *warrants* an ADR (see its decision framework).
+- The decision has policy or architectural implications and you want prose with the right scope.
+- You need to maintain the ADR index README beyond what `adr generate toc` produces.
+
+A typical flow: the user asks "should we ADR this?" → adr-author decides yes/no and drafts the body → this skill runs the `adr new` / `adr link` commands and regenerates the TOC.

package/skills/agent-readiness/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: agent-readiness
+description: >-
+  Score how ready the current repository is for AI-assisted development against
+  the Agent-Readiness Scorecard. Use when the user asks "how agent-ready is this
+  repo", "score this repo for agents", "agent readiness", or wants a tiered
+  readiness report. Scores YOUR project repo's readiness — not the dev-team
+  plugin's own review agents and routing (for that, use /harness-audit).
+argument-hint: "[repo-path] [--json <file>] [--markdown <file>]"
+user-invocable: true
+allowed-tools: >-
+  Bash(python3 *), Read, Glob
+---
+
+# Agent-Readiness Scanner (MVP)
+
+Role: worker. Scores a **single local repository** against the Agent-Readiness
+Scorecard and reports a tier (Agent-Ready / Assisted / Limited / Hostile) with
+per-criterion evidence.
+
+> **Not `/harness-audit`.** This scores the **subject repository** (your
+> project's build, code quality, docs, and version-control hygiene) from a
+> static checkout. `/harness-audit` audits the **dev-team plugin's own harness**
+> (review-agent effectiveness, model tiers, orchestration) from accumulated
+> runtime metrics. Different subject, different input, different output.
+
+## Scope (MVP — issue #117)
+
+This MVP uses **file-presence/heuristic analyzers only** — no CI-platform APIs.
+It scores the criteria that can be judged from a checkout:
+
+- **Build & Env:** B2 reproducible env, B3 dependency lock files, B5 composite check command
+- **Code Quality:** C1 formatting, C2 linting, C4 module size (p90 line count)
+- **Documentation:** D1 README, D2 AI instructions, D3 architecture docs,
+  D5 CLAUDE.md size, D6 layered context
+- **Version Control:** V2 pre-commit hooks, V3 commit conventions, V4 dep scanning
+
+D5, D6, B5 (and the manual-review-only D7) implement the AI-friendly repository
+rubric in [`knowledge/ai-friendly-repo-guidelines.md`](../../knowledge/ai-friendly-repo-guidelines.md),
+the canonical source for the rationale; evidence strings link to its anchors.
+Colocated-test and directory-depth criteria are a deferred follow-up.
+
+**Score shift (scorecard 1.1-mvp).** Adding D5, D6 and B5 changes the
+documentation and build_env category percentages, and so the renormalized
+overall score, for repos scanned before this version. The shift is accepted;
+tier thresholds are unchanged. Compare scores only within one scorecard
+version (`scanner_version` in the JSON).
+
+Criteria that need CI-platform data (coverage, flaky rate, durations, branch
+policy — T1–T5, B1, B4, C5, S1–S4, V1) and the org-scale Azure DevOps / Jenkins
+discovery from the original plan are **deferred** to follow-up phases.
+Categories with no MVP criterion (test infrastructure, type safety) are reported
+as `deferred` and excluded from the renormalized overall score.
+
+## Evidence table
+
+Each scored criterion emits `score` (0-2), `max`, and an `evidence` string. The
+new criteria use `found X; threshold Y; to fix: Z (see <guide>#anchor)`.
+N/A results (`max` 0, e.g. D5 when no AI-instructions file exists; see D2) are
+exempt: they carry a plain-text reason and add nothing to the category score.
+
+| Criterion | Category | Scores on | Threshold (scorecard.yaml) |
+| --- | --- | --- | --- |
+| B2_reproducible_env | build_env | devcontainer/compose/nix/Dockerfile | presence |
+| B3_dependency_management | build_env | committed lock files | presence |
+| B5_composite_check_command | build_env | `check`/`verify`/`ci`/`all` target running lint and test | `check_target_names` |
+| C1_formatting | code_quality | formatter config + CI step | presence |
+| C2_linting | code_quality | linter config + CI step | presence |
+| C4_module_size | code_quality | p90 source-file line count | `file_size_p90_*` |
+| D1_readme | documentation | README words + setup/build/test | `readme_min_words` |
+| D2_ai_instructions | documentation | AI-instructions file present and detailed | `ai_instructions_min_words` |
+| D3_architecture_docs | documentation | ADRs / architecture docs | presence |
+| D5_claude_md_size | documentation | instructions-file line count (N/A when none; see D2) | `claude_md_max_lines`, `claude_md_hard_max_lines` |
+| D6_layered_context | documentation | non-empty nested CLAUDE.md or `.claude/rules/*.md` | presence |
+| V2_precommit_hooks | vcs_safety | pre-commit hook config | presence |
+| V3_commit_conventions | vcs_safety | commitlint tooling + enforcement | presence |
+| V4_dependency_scanning | vcs_safety | dependabot/renovate/snyk config | presence |
+
+Manual review only (never scored): C3, S3, D4, **D7_reference_implementation**
+(is a canonical reference implementation named in CLAUDE.md, and well chosen?).
+
+## Run
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-readiness/scanner.py" [REPO_PATH] \
+  [--json out.json] [--markdown out.md]
+```
+
+- `REPO_PATH` defaults to the current directory.
+- With no `--json`/`--markdown`, prints the JSON result and a Markdown summary.
+- Weights, tier thresholds, and per-criterion thresholds live in
+  `scorecard.yaml` next to the scanner — edit there to tune; no code change.
+
+## Steps
+
+1. Run the scanner against the target repo (default: current repo).
+2. Report the tier and overall score, then the per-criterion evidence table.
+3. Surface `manual_review_flags` (C3/S3/D4/D7 are heuristic-weak and need human
+   judgment) and the list of deferred categories, so the score is not
+   mistaken for a full assessment.
+4. If asked, suggest the highest-leverage improvements (lowest-scoring MVP
+   criteria first).
+
+Do not invent scores — report exactly what the scanner emits, including its
+evidence strings.