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`,
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

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.