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)

template/README.md

@@ -0,0 +1,77 @@
+# Reference template — `<your-agent-name>`
+
+> **Spec version:** 1.0.0 — see [`../SPEC.md`](../SPEC.md)
+
+A working, copy-and-fill skeleton for a new Python/Starlette agent that conforms to the harness spec.
+
+## Quickstart
+
+```bash
+# 1. Copy the template
+cp -r template/ ../my-new-agent/
+cd ../my-new-agent
+
+# 2. Rename placeholders
+git grep -l '<agent-name>\|<agent_name>\|<AgentName>\|<role>' | xargs sed -i \
+  -e 's/<agent-name>/my-new-agent/g' \
+  -e 's/<agent_name>/my_new_agent/g' \
+  -e 's/<AgentName>/MyNewAgent/g' \
+  -e 's/<role>/my-new-agent/g'
+
+# 3. Pin the initial version
+echo "0.1.0" > .image-version
+
+# 4. Add your domain code
+#    - Replace the `/echo` route in app/agent.py with your endpoints
+#    - Add your skills to app/skills.py
+#    - Add custom metrics to app/metrics.py
+
+# 5. Configure local dev
+cp .env.local.example .env.local
+# edit .env.local with your secrets
+
+# 6. Run locally
+./scripts/deploy-local.sh
+
+# 7. Build & deploy to the cluster
+./scripts/full-deploy.sh
+```
+
+## What's in the box
+
+```
+template/
+├── .env.local.example       # all env vars the agent reads, with safe defaults
+├── .gitignore
+├── .image-version           # 0.1.0
+├── Dockerfile               # python:3.12-slim, non-root, HEALTHCHECK
+├── README.md                # (this file)
+├── requirements.txt         # harness floor + LLM stack
+├── app/
+│   ├── __init__.py
+│   ├── agent.py             # Starlette entry point, all required routes,
+│   │                        #   lifespan + self-registration, _skill_dict helper
+│   ├── logging_setup.py     # OTel log bridge (copy verbatim — do not edit)
+│   ├── metrics.py           # Meter + example counter/histogram
+│   └── skills.py            # AGENT_SKILLS list + AGENT_CONFIG dict
+├── k8s/
+│   ├── configmap.yaml       # REGISTRY_URL, AGENT_SELF_URL, LOG_LEVEL, PORT
+│   └── deployment.yaml      # Deployment + Service, OTel annotations + env block
+└── scripts/
+    ├── deploy.sh            # az acr build + kubectl apply + rollout
+    ├── deploy-local.sh      # docker/podman + .env.local
+    └── full-deploy.sh       # preflight + deploy.sh + post-deploy smoke
+```
+
+## Editing rules
+
+| Touch freely | Touch carefully | Do not edit |
+|---|---|---|
+| `app/skills.py` | `app/agent.py` (keep lifespan + registration + manifest intact) | `app/logging_setup.py` |
+| `app/metrics.py` (rename instruments to your domain) | `k8s/deployment.yaml` env vars (only change `OTEL_*` values, not keys) | The `_skill_dict` helper in `app/agent.py` |
+| `requirements.txt` (add your domain deps) | `Dockerfile` (only change `EXPOSE` and the uvicorn port) | `scripts/deploy.sh` flow |
+| `k8s/configmap.yaml` data section | `k8s/deployment.yaml` probes (only `initialDelaySeconds` for slow startup) | OTel annotations on the pod template |
+
+## Conformance
+
+Before opening a PR for your new agent, walk the [conformance checklist](../SPEC.md#conformance-checklist) in `SPEC.md`. The reference template ticks every box out of the box; you should only need to verify your domain-specific additions don't regress anything.