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/k8s/configmap.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: <agent-name>-config
+  namespace: agents
+data:
+  # ─── Self-registration (docs/registration.md) ─────────────────────────
+  REGISTRY_URL: "http://agent-gateway.agents.svc.cluster.local"
+  AGENT_SELF_URL: "http://<agent-name>.agents.svc.cluster.local"
+
+  # ─── Server ───────────────────────────────────────────────────────────
+  LOG_LEVEL: "INFO"
+  PORT: "8000"
+
+  # ─── LLM (delete if your agent does not call an LLM) ──────────────────
+  AZURE_OPENAI_DEPLOYMENT: "gpt-4o"
+  AZURE_OPENAI_API_VERSION: "2024-08-01-preview"

template/k8s/deployment.yaml

@@ -0,0 +1,117 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: <agent-name>
+  namespace: agents
+  labels:
+    app: <agent-name>
+    component: agent
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: <agent-name>
+  template:
+    metadata:
+      labels:
+        app: <agent-name>
+        azure.workload.identity/use: "true"
+      annotations:
+        # ─── OTel SDK injection ─────────────────────────────────────────
+        instrumentation.opentelemetry.io/inject-python: "monitoring/otel-instrumentation"
+        instrumentation.opentelemetry.io/container-names: "<agent-name>"
+    spec:
+      serviceAccountName: agents-sa
+      containers:
+        - name: <agent-name>
+          image: bstagecjotdevacr.azurecr.io/<agent-name>:latest
+          imagePullPolicy: Always
+          ports:
+            - name: http
+              containerPort: 8000
+              protocol: TCP
+          envFrom:
+            - configMapRef:
+                name: <agent-name>-config
+          env:
+            # ─── OTel (mandatory — keep these keys verbatim) ───────────
+            - name: OTEL_SERVICE_NAME
+              value: "<agent-name>"
+            - name: OTEL_RESOURCE_ATTRIBUTES
+              value: "service.namespace=agents,service.version=0.1.0,deployment.environment=prod,agent.type=<role>"
+            - name: OTEL_LOGS_EXPORTER
+              value: "otlp"
+            - name: OTEL_METRICS_EXPORTER
+              value: "otlp"
+            - name: OTEL_METRIC_EXPORT_INTERVAL
+              value: "15000"
+            - name: OTEL_SEMCONV_STABILITY_OPT_IN
+              value: "http"
+
+            # ─── Secrets from agents-kv-sync (sync'd from Key Vault) ───
+            - name: AZURE_OPENAI_ENDPOINT
+              valueFrom:
+                secretKeyRef:
+                  name: agents-kv-sync
+                  key: azure-openai-endpoint
+            - name: AZURE_OPENAI_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: agents-kv-sync
+                  key: azure-openai-api-key
+
+          resources:
+            requests:
+              memory: "512Mi"
+              cpu: "250m"
+            limits:
+              memory: "1Gi"
+              cpu: "500m"
+
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 20
+            periodSeconds: 15
+            timeoutSeconds: 5
+            failureThreshold: 3
+
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 3
+
+          volumeMounts:
+            - name: secrets-store
+              mountPath: "/mnt/secrets-store"
+              readOnly: true
+
+      volumes:
+        - name: secrets-store
+          csi:
+            driver: secrets-store.csi.k8s.io
+            readOnly: true
+            volumeAttributes:
+              secretProviderClass: agents-kv-spc
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: <agent-name>
+  namespace: agents
+  labels:
+    app: <agent-name>
+spec:
+  selector:
+    app: <agent-name>
+  ports:
+    - name: http
+      port: 80
+      targetPort: 8000
+      protocol: TCP
+  type: ClusterIP