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

@@ -0,0 +1,75 @@
+#!/bin/bash
+# deploy.sh — Build <agent-name> image in ACR and deploy to AKS.
+#
+# Usage:
+#   ./scripts/deploy.sh                  # auto-bump patch version
+#   ./scripts/deploy.sh --tag 1.2.3      # use an explicit tag (does not bump)
+#
+# Conforms to platform agent-harness-spec §10.
+
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+AGENT_DIR=$(cd "${SCRIPT_DIR}/.." && pwd)
+
+ACR_NAME="bstagecjotdevacr"
+APP_NAME="<agent-name>"
+NAMESPACE="agents"
+VERSION_FILE="${AGENT_DIR}/.image-version"
+TAG=""
+
+# ─── Parse args ─────────────────────────────────────────────────────────
+while [[ "$#" -gt 0 ]]; do
+  case $1 in
+    --tag)
+      TAG="$2"
+      shift
+      ;;
+    -h|--help)
+      sed -n '2,8p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+# ─── Auto-bump patch version if --tag not given ─────────────────────────
+if [ -z "$TAG" ]; then
+  if [ -f "$VERSION_FILE" ]; then
+    CURRENT_VERSION=$(cat "$VERSION_FILE")
+  else
+    CURRENT_VERSION="0.1.0"
+  fi
+  IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+  PATCH=$((PATCH + 1))
+  TAG="${MAJOR}.${MINOR}.${PATCH}"
+  echo "$TAG" > "$VERSION_FILE"
+fi
+
+IMAGE="${ACR_NAME}.azurecr.io/${APP_NAME}:${TAG}"
+IMAGE_LATEST="${ACR_NAME}.azurecr.io/${APP_NAME}:latest"
+
+echo "======================================================================"
+echo "  ${APP_NAME} — build & deploy"
+echo "  Image: ${IMAGE}"
+echo "======================================================================"
+
+# ─── Build & push in ACR ────────────────────────────────────────────────
+az acr build --registry "$ACR_NAME" \
+  --image "${APP_NAME}:${TAG}" \
+  --image "${APP_NAME}:latest" \
+  "${AGENT_DIR}"
+
+# ─── Apply manifests ────────────────────────────────────────────────────
+kubectl apply -f "${AGENT_DIR}/k8s/configmap.yaml"
+kubectl apply -f "${AGENT_DIR}/k8s/deployment.yaml"
+
+# ─── Wait for rollout ───────────────────────────────────────────────────
+kubectl -n "${NAMESPACE}" rollout status "deployment/${APP_NAME}" --timeout=180s
+
+echo ""
+echo "Deployed ${IMAGE} to ${NAMESPACE}/${APP_NAME}"