Priorities 3, 4 & 7: MCP/skill governance, agent permissions, readiness benchmark

[JRS1986]

Summary

Implements priorities 3, 4, and 7 from the maintainer's brief. Priorities 5 (worktree) and 6 (memory) remain explicitly out of scope.

Priority 4 — Machine-readable permissions

`coding-scaffold permissions write` generates `.coding-scaffold/agent-permissions.json` with the canonical shape from the brief (filesystem read/write/deny, shell allowed + requires_approval, network=disabled_by_default, mcp policy defaults). Project-aware: Python repos get `pytest`/`ruff` in the allowed list, Node gets `npm test`, etc. Idempotent — `--force` to regenerate.

Priority 3 — MCP governance

Command	Effect
`mcp policy init`	Write team policy at `.coding-scaffold/mcp-policy.json` (approved/denied lists, package-pinning default, review-required capabilities).
`mcp scan`	Inspect `opencode.json` and `.claude/settings.json`, parse server definitions, flag remote / unpinned / risky-launcher / broad-fs-arg / unapproved / denied / review-required-capability.
`mcp snapshot`	Write `.coding-scaffold/mcp-snapshot.json` recording the current server set with stable per-server fingerprints.
`mcp diff`	Compare current scan with snapshot; report added / removed / changed; exit non-zero on any drift (CI-gate-friendly).

No commands are executed. No network calls. Pure JSON config parsing.

Priority 3 — Reviewable skill packs

Command	Effect
`skills new `	Scaffold `.coding-scaffold/skills//` with `SKILL.md`, `manifest.json`, `README.md`, `scripts/`, `tests/`.
`skills lint`	Flag broad-usage language (`always use this`), hidden-instruction phrases (`do not tell the user` — error severity), undeclared capabilities, missing required sections / manifest fields, invalid `risk_level`, placeholder owner, drift since CHECKSUM.
`skills approve `	Compute `sha256(SKILL.md
`skills export `	Bundle the skill directory into a `tar.gz` for inter-team sharing.

Priority 7 — Readiness benchmark

Command	Effect
`eval init`	Write `.coding-scaffold/eval-config.json` with per-check toggles. Optional — `eval run` works without it.
`eval run`	Run all enabled checks; write `.coding-scaffold/eval-report.json`; exit non-zero when any check fails.
`eval report --cached`	Re-print the most recent report without re-running.

Checks (deterministic, no shell, no LLM): build/test/lint signals, agent instructions exist, policy pack present, non-empty deny list, PR template present, MCP policy present when MCP is detected, session-trace location, context lint clean, context budget under limit.

The benchmark scores readiness — it does not measure model intelligence. The point is to confirm the repo gives the agent enough to work with.

Architecture & constraints honored

• Four new modules, each with a clear responsibility (`permissions.py`, `mcp.py`, `skills.py`, `eval_harness.py`). `cli.py` stays a dispatcher.
• Deterministic output everywhere (sorted findings, stable fingerprints, sorted JSON).
• Zero new dependencies, zero LLM calls, zero network calls, zero telemetry.
• Backwards compatible: every existing command and generated file is unchanged.
• All 12 new commands ship with both plain-text and `--json` output.
• `mcp diff`, `mcp scan` (on error), `skills lint` (on error), `eval run`, `eval report` exit non-zero so they can gate CI.

Tests

• `tests/test_permissions.py` — 8 new tests.
• `tests/test_mcp.py` — 17 new tests (policy / scan flags / snapshot / diff / CLI).
• `tests/test_skills.py` — 17 new tests (new / lint flags / approve / export / CLI).
• `tests/test_eval_harness.py` — 13 new tests (well-configured project passes basics; empty project fails most; MCP-detected-but-no-policy fails; cached/JSON output).

Total: 266 passing (was 205, +61). Ruff clean.

Docs

• New "Machine-Readable Permissions Artifact", "MCP Governance", and "Skill Pack Governance" sections in Security.md.
• New "Readiness Benchmark" section in Team-Rollout.md.
• CHANGELOG `[Unreleased]` covers all 12 commands.

Known limitations

• MCP scanner only reads `opencode.json` and `.claude/settings.json` in v1. Adding `.codex/config.toml` requires a TOML parser; deferred.
• Skill checksum covers `SKILL.md` + `manifest.json` only; `scripts/` and `tests/` aren't fingerprinted in v1 (rationale: those are reviewed by code-review, not by approval gate).
• Readiness benchmark is a static check — it does not run a real agent session.

Out of scope (per the brief)

• Priority 5 — Git worktree / checkpoint mode.
• Priority 6 — Memory governance (MemPalace remains a backend choice for the knowledge base; structured memory classes / capture / promote / expire / audit are not in this PR).