Harden repo for coding agents

Harden Repo for Coding Agents

Core principle: make the repository legible to a stateless, context-bound LLM that must rediscover the project every session. Four named moves recur across every surface: progressive disclosure — on-demand beats on-trigger beats always-loaded, because token budget is the dominant scarcity (W6); hard gates beat soft prose — a hook holds at 100%, an instruction sentence at ~70% (W3); hand-curate, never /init — autogenerated instruction files drop task success ~3% and inflate cost >20% (W9); and defense-in-depth — harness hook, CI branch protection, and sandbox compose; none alone suffices (W10). W2–W10 live in references/empirical-warnings.md.

Run to completion from the request and the repo, stating assumptions in the output. Ask only on genuine blockers — chiefly, which harnesses the team uses when neither the request nor the repo says and the work emits per-harness output.

Out of scope (capabilities, not files): promoting observed agent failures into durable rules from a failure log, and designing or operating an LLM product's eval loops.

Invariants

• Never infer the harness set from dotfiles. .claude/ proves Claude Code is used, not that it is the only harness in play. Emit per-harness equivalents for every harness named in the inventory — not just the one whose dotfile exists.
• Hand-curate instruction files from project knowledge — stack, layout, build/test commands, invariants. Never autogenerate; no placeholder prose. The quality bar is "specific to this project, verifiable by reading the file."
• Forbidden-tier actions get a hard gate — a PreToolUse hook that exits 2 plus a mirroring CI/branch-protection rule — never prose alone.
• A deny-list hook ships with its variant-matrix test fixture as one artifact, never two (the bypass categories are enumerated in references/playbooks/gates.md H5).
• A PR evidence contract ships as template plus enforcing required check together — a PR template alone is prose (~70%), not a proof-of-work gate (references/playbooks/operations.md).

Workflow

1. Classify the request as assess, harden, scaffold, or diagnose, and name the surfaces in play. If ambiguous, pick the closest reading and say so in the output.
2. Inventory the harness set (from the request, or ask once — see Invariants) and the project knowledge the artifacts must encode: stack, repo layout and scope, build/test/lint commands, invariants the agent must not break.
3. Load the matching references: references/playbooks/gates.md (hooks, action tiers, per-harness gate primitives), instruction-surface.md (root instruction files), sandbox.md (isolation, egress, secrets), context-surfaces.md (skills, docs index, specs, tools/MCP), operations.md (CI runner trust, PR evidence contracts, evals, telemetry, governance). Load only what the surfaces need.
4. Apply the loaded playbooks. Assess: findings, each with severity 0–4 (4 = an agent can take an irreversible or destructive action today; 3 = a safety rule exists only as prose; 2 and below = cost, drift, or quality) and a concrete verification step. Harden: recommendations ranked by severity closed per token spent, each naming the artifact to change and how to verify. Scaffold: write the artifacts per the playbooks' scaffold notes. Diagnose: ranked hypotheses, each with a check that confirms or kills it; fix the top confirmed one and state the prevention.
5. Audit scaffolds against the playbook. After writing, re-read the actual diff and report every scaffold heuristic in the loaded playbooks as applied, skipped-because-X, or deferred. Fix gaps and re-audit at most twice, then stop and report what remains open.
6. Report in chat — findings/recommendations with severities, assumptions made, and verification steps. Write report files only when asked, at a path the user names.