chore(harness): make repository agent-ready

Add concise routed context, task-aware agent roles, focused skills, and structured learning promotion.\n\nUnify local development and workspace tooling, add layered test and E2E verification, harden MCP authentication, and gate deployment behind verification and explicit production promotion.

docs/agents/learnings.md

@@ -0,0 +1,19 @@
+# Learning promotion
+
+Raw activity is not durable guidance. A lesson becomes agent context only after a
+reproducible observation is reviewed and promoted.
+
+## Lifecycle
+
+1. Record a structured observation in `.agents/learnings/inbox/`.
+2. Include symptom, reproduction, cause, remediation, evidence, and scope.
+3. `npm run learn:check` validates the record.
+4. A reviewer promotes it into exactly one maintained surface: documentation,
+   skill, test fixture, invariant lint, or scoped `AGENTS.md` rule.
+5. Move it to `.agents/learnings/promoted/` and include its destination.
+
+Do not promote speculation, transient provider failures, or one-off workarounds.
+Prefer executable enforcement over prose. Review guidance on its expiry date.
+
+`.ralph/runs` and activity logs are historical evidence and are not loaded into
+normal task context.

docs/agents/routing.md

@@ -0,0 +1,21 @@
+# Agent routing and effort
+
+Use one implementation agent by default. Add independent agents only when work is
+actually separable or a risk trigger requires independent judgment.
+
+| Role | Default effort | Trigger | Do not use for |
+|---|---|---|---|
+| `repo-scout` | low | locate ownership, callers, contracts | editing or design decisions |
+| `implementation` | medium | bounded product or harness change | broad architecture review |
+| `test-writer` | medium | focused regression or missing contract test | rubber-stamping green output |
+| `verifier` | medium | independently drive changed behavior | editing implementation |
+| `database-reviewer` | medium | migrations, RLS, function/query boundaries | ordinary UI changes |
+| `security-reviewer` | high | auth, RLS, crypto, secrets, payments, destructive operations | every routine change |
+| `architecture-reviewer` | high | cross-cutting or hard-to-reverse decisions | local refactors |
+
+Escalate effort only when uncertainty, blast radius, or irreversibility justifies
+it. “Proactively use” is not a trigger. Verification agents return evidence and a
+verdict; they do not make changes.
+
+Procedures belong in skills. Agents read the applicable skill and nearest
+`AGENTS.md`, then operate within the task's authorization.