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/scripts/full-deploy.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# full-deploy.sh — Preflight checks + build + deploy + post-deploy smoke.
+#
+# Run this for first-time deploys or after an outage to validate cluster state.
+# For routine redeploys, use scripts/deploy.sh.
+
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+AGENT_DIR=$(cd "${SCRIPT_DIR}/.." && pwd)
+
+APP_NAME="<agent-name>"
+NAMESPACE="agents"
+SA_NAME="agents-sa"
+SPC_NAME="agents-kv-spc"
+PORT=8000
+
+fail() { echo "preflight FAIL: $1" >&2; exit 1; }
+ok()   { echo "preflight  OK : $1"; }
+
+# ─── Preflight ──────────────────────────────────────────────────────────
+echo "─── Preflight ──────────────────────────────────────────"
+
+command -v kubectl >/dev/null || fail "kubectl not on PATH"
+ok "kubectl on PATH"
+
+command -v az >/dev/null || fail "az CLI not on PATH"
+ok "az CLI on PATH"
+
+kubectl cluster-info >/dev/null 2>&1 || fail "kubectl can't reach a cluster"
+ok "cluster reachable: $(kubectl config current-context)"
+
+kubectl get namespace "${NAMESPACE}" >/dev/null 2>&1 \
+  || fail "namespace ${NAMESPACE} missing"
+ok "namespace ${NAMESPACE} exists"
+
+kubectl -n "${NAMESPACE}" get serviceaccount "${SA_NAME}" >/dev/null 2>&1 \
+  || fail "ServiceAccount ${NAMESPACE}/${SA_NAME} missing"
+ok "ServiceAccount ${SA_NAME} exists"
+
+kubectl -n "${NAMESPACE}" get secretproviderclass "${SPC_NAME}" >/dev/null 2>&1 \
+  || fail "SecretProviderClass ${NAMESPACE}/${SPC_NAME} missing"
+ok "SecretProviderClass ${SPC_NAME} exists"
+
+echo ""
+
+# ─── Build & deploy ─────────────────────────────────────────────────────
+echo "─── Build & deploy ─────────────────────────────────────"
+"${SCRIPT_DIR}/deploy.sh" "$@"
+
+echo ""
+
+# ─── Post-deploy smoke ──────────────────────────────────────────────────
+echo "─── Post-deploy smoke ──────────────────────────────────"
+
+POD=$(kubectl -n "${NAMESPACE}" get pod -l "app=${APP_NAME}" \
+  -o jsonpath='{.items[0].metadata.name}')
+
+echo "Probing /health on ${POD}..."
+kubectl -n "${NAMESPACE}" exec "${POD}" -c "${APP_NAME}" -- \
+  curl -fs "http://localhost:${PORT}/health" \
+  | jq -e '.status == "healthy"' >/dev/null \
+  && ok "/health returns healthy" \
+  || fail "/health did not return healthy"
+
+echo "Probing /.well-known/agent.json on ${POD}..."
+kubectl -n "${NAMESPACE}" exec "${POD}" -c "${APP_NAME}" -- \
+  curl -fs "http://localhost:${PORT}/.well-known/agent.json" \
+  | jq -e '.name and .version and (.skills | type == "array")' >/dev/null \
+  && ok "/.well-known/agent.json valid" \
+  || fail "/.well-known/agent.json invalid"
+
+echo ""
+echo "Done. ${APP_NAME} is up and conforming to the harness spec."