feat: initial harness spec v1.0.0 + reference template

Adds the normative contract every platform agent must conform to, plus a
working reference template under template/ that ticks every box out of
the box.

Spec is derived from the production agents shipped in
cjot-backstage-az/agents/ on branch sandbox/jonathan:
  - agent-registry, agent-factory, decomposer, discovery-agent,
    golden-path, modernization-factory, modernization-factory-v2,
    policy-transformer, scaffold-agent, support-intake-agent, the-watcher

Contents:
  - SPEC.md          normative contract (13 sections + conformance checklist)
  - CHANGELOG.md     spec versioning (1.0.0)
  - docs/
      registration.md   self-registration with the agent-gateway
      observability.md  OTel logs/metrics/traces wiring
      manifest.md       /.well-known/agent.json schema + AgentSkill
                        serialisation (pydantic vs protobuf)
      kubernetes.md     k8s deployment shape, mandatory cross-refs,
                        per-namespace agents, resource sizing
      deployment.md     .image-version, ACR build, deploy scripts, rollback
      deviations.md     tracked debts against the spec
  - template/
      .env.local.example, .gitignore, .image-version (0.1.0),
      Dockerfile (python:3.12-slim, non-root UID 1001, HEALTHCHECK),
      requirements.txt (harness floor + optional LLM stack),
      app/agent.py (Starlette entry, lifespan + self-registration,
                    defensive _skill_dict for pydantic vs protobuf),
      app/logging_setup.py (canonical OTel log bridge — copy verbatim),
      app/metrics.py (meter + example counter/histogram),
      app/skills.py (AGENT_CONFIG + AgentSkill list),
      k8s/configmap.yaml + deployment.yaml (Deployment + Service,
                                            OTel annotations + 6-var env block,
                                            agents-sa + agents-kv-spc bindings),
      scripts/deploy.sh (auto-bump + az acr build + apply + rollout),
      scripts/full-deploy.sh (preflight + deploy + post-deploy smoke),
      scripts/deploy-local.sh (docker/podman + .env.local)

docs/deviations.md

@@ -0,0 +1,24 @@
+# Known deviations
+
+This file tracks where existing agents in `cjot-backstage-az/agents/` deviate from the [SPEC](../SPEC.md). Each row is a tracked debt; deviations should converge over time.
+
+| Agent | Deviation | Spec clause | Notes |
+|---|---|---|---|
+| `agent-registry` | Uses FastAPI, not Starlette | §3.2 | Grandfathered — registry pre-dates the spec. |
+| `support-intake-agent` | Uses FastAPI, not Starlette | §3.2 | Grandfathered. |
+| `agent-factory` | Uses `agent-factory-sa` ServiceAccount | §9.3 | Has its own Key Vault binding (`agent-factory-kv-spc`) for build-time credentials. |
+| `sonarqube-mcp` | Uses `sonarqube-mcp-kv-spc` SecretProviderClass | §9 (Mandatory cross-references) | Domain-specific Key Vault for SonarQube tokens. |
+| `golden-path` | Listens on port 8000 (not 8080) | §3.5 (allowed) | Port 8000 is permitted; flagged here only for awareness. |
+| `modernization-factory-v2` | Runs in namespace `modernization-factory` | §9.2 | Namespace separation by domain; `service.namespace` and `AGENT_SELF_URL` are correctly aligned. |
+| `documentor-agent` | Skeleton only (no `app/` shipped) | All | Placeholder; not yet a deployable agent. |
+
+## How to add a row
+
+When you knowingly merge an agent that violates a spec clause, add a row here with:
+
+- The agent's directory name.
+- A one-line description of the deviation.
+- The clause number(s) in `SPEC.md`.
+- A short rationale or follow-up plan.
+
+When you fix a deviation, remove the row in the same PR that closes it.