phase2-attest-baseline: drift-aware --baseline diff for azureclaw attest (Phase 2 S11.1)

CHANGELOG.md

@@ -292,6 +292,76 @@ floor compare-and-block, model-preference selection).
 - The runtime gate `inference-router::routes::inference_policy::check`
   (Phase 1) is **not modified in this slice**.
 
+### S11.1 `phase2-attest-baseline` — drift-aware `--baseline` diff
+
+Outcome-shaped follow-up to S11. Turns `azureclaw attest` from a
+"print attestation JSON" command into a CI-gate / change-control
+primitive: pass `--baseline <file>` and the command compares the live
+sandbox against a previously-saved attestation, surfaces typed deltas,
+and exits **2 on drift** / **3 on missing-baseline-file** so a
+pipeline step can `set -e` against it.
+
+**Real-world workflow this unlocks:**
+
+```bash
+# Day 0 — capture approved posture
+$ azureclaw attest demo --format json > approved.json
+$ git add approved.json && git commit -m "approved: demo posture"
+
+# Every PR / nightly job — fail the build on drift
+$ azureclaw attest demo --baseline approved.json || exit $?
+✗ ToolPolicy 'tp-prod' versionHash drifted (sha256:abc1234… → sha256:def5678…)
+✗ new SSA manager touched the object: 'kubectl-edit'
+DRIFT: 2 delta(s) — exit code 2
+```
+
+**What deltas are surfaced (one human-meaningful change per delta):**
+
+- `specHash` — the `ClawSandbox.spec` itself changed (the most
+  important signal; all other deltas are downstream of this *or* of
+  a referenced policy).
+- `phase` — sandbox moved between Running / Overlay / Degraded.
+- `policyVersionHash` — a referenced ToolPolicy / InferencePolicy /
+  A2AAgent has a new `status.versionHash` (controller recompiled it).
+- `policyAdded` / `policyRemoved` — the spec now references a
+  different policy CR set.
+- `fieldOwnerAdded` / `fieldOwnerRemoved` — a new (or removed) SSA
+  manager touched the object since the baseline.
+
+**Set-comparison, not count-comparison, on field owners:** SSA bumps
+the per-field count on every controller reconcile (noisy), but the
+*set* of managers is what a CI gate actually wants to flag — "did a
+human or a tool that wasn't here before edit this object?". The diff
+deliberately ignores `fieldsOwned` count fluctuation when the manager
+set is unchanged. Asserted directly in tests.
+
+**Pure-function design:** `diffAttestations(baseline, current)` is the
+only new logic; it has no IO, no time, no kubectl. The CLI orchestrator
+calls it after `buildReport` (which is what shells out). Means the
+diff is unit-testable without a cluster, and a future Phase 3
+`azureclaw verify <bundle>` companion can reuse `diffAttestations`
+unchanged.
+
+**Exit codes (CI-friendly):**
+
+- `0` — match (no deltas, baseline matches current).
+- `2` — drift (one or more deltas; reported in human + JSON output).
+- `3` — baseline file missing (CLI prints to stderr + exits before
+  any `kubectl get`).
+
+**JSON output:** when `--baseline` is set, the report grows a
+`baselineDiff` field with `{ baseline, current, deltas, drift }`.
+The base envelope (`apiVersion`, `kind`, all S11 fields) is unchanged
+so existing consumers continue to parse without modification.
+
+**Surface:** `cli/src/commands/attest.ts` adds `diffAttestations`,
+`loadBaseline`, `describeDelta`, `--baseline` flag, exit-code
+handling; `cli/src/commands/attest.test.ts` adds 11 new cases (no
+drift, every delta variant, set-comparison, missing/invalid baseline
+file). CLI workspace 304 → 315 (+11).
+
+**Audit:** `docs/security-audits/2026-04-28-phase2-attest-baseline.md`.
+
 ### S11 `phase2-attest-cli` — `azureclaw attest <name>` read surface
 
 This slice ships the **read consumer** half of implementation-plan §15.2

cli/src/commands/attest.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { __test } from "./attest.js";
 
 describe("attestCommand — canonicalJson", () => {
@@ -160,3 +163,205 @@ describe("attestCommand — formatters", () => {
     expect(out).toContain("(Phase 3)");
   });
 });
+
+describe("attestCommand — diffAttestations", () => {
+  const baseReport = (overrides: Record<string, unknown> = {}) =>
+    ({
+      apiVersion: "azureclaw.azure.com/v1alpha1-attest" as const,
+      kind: "Attestation" as const,
+      generatedAt: "2026-04-01T00:00:00Z",
+      sandbox: {
+        name: "demo",
+        namespace: "azureclaw-system",
+        generation: 1,
+        observedGeneration: 1,
+        phase: "Running",
+        specHash: "sha256:" + "a".repeat(64),
+        specHashAlgorithm: "sha256-canonical-json" as const,
+      },
+      fieldOwners: [{ manager: "azureclaw-controller", fieldsOwned: 5 }],
+      policyVersions: [
+        {
+          kind: "ToolPolicy",
+          name: "tp",
+          namespace: "azureclaw-demo",
+          versionHash: "sha256:" + "b".repeat(64),
+          bindingConfigMap: "tp-bind",
+        },
+      ],
+      reconcileTraceId: null,
+      agtAuditReceiptId: null,
+      signature: null,
+      ...overrides,
+    });
+
+  it("returns drift=false when reports match", () => {
+    const a = baseReport();
+    const b = baseReport({ generatedAt: "2026-04-02T00:00:00Z" });
+    const diff = __test.diffAttestations(a, b);
+    expect(diff.drift).toBe(false);
+    expect(diff.deltas).toEqual([]);
+  });
+
+  it("detects spec hash drift", () => {
+    const a = baseReport();
+    const b = baseReport({
+      sandbox: { ...a.sandbox, specHash: "sha256:" + "c".repeat(64) },
+    });
+    const diff = __test.diffAttestations(a, b);
+    expect(diff.drift).toBe(true);
+    expect(diff.deltas).toEqual([
+      {
+        type: "specHash",
+        before: a.sandbox.specHash,
+        after: "sha256:" + "c".repeat(64),
+      },
+    ]);
+  });
+
+  it("detects phase change", () => {
+    const a = baseReport();
+    const b = baseReport({ sandbox: { ...a.sandbox, phase: "Degraded" } });
+    const diff = __test.diffAttestations(a, b);
+    expect(diff.deltas.find((d) => d.type === "phase")).toEqual({
+      type: "phase",
+      before: "Running",
+      after: "Degraded",
+    });
+  });
+
+  it("detects policy versionHash drift", () => {
+    const a = baseReport();
+    const b = baseReport({
+      policyVersions: [
+        {
+          ...a.policyVersions[0],
+          versionHash: "sha256:" + "d".repeat(64),
+        },
+      ],
+    });
+    const diff = __test.diffAttestations(a, b);
+    const policyDelta = diff.deltas.find((d) => d.type === "policyVersionHash");
+    expect(policyDelta).toMatchObject({
+      type: "policyVersionHash",
+      kind: "ToolPolicy",
+      name: "tp",
+      after: "sha256:" + "d".repeat(64),
+    });
+  });
+
+  it("detects added/removed policies", () => {
+    const a = baseReport();
+    const b = baseReport({
+      policyVersions: [
+        {
+          kind: "InferencePolicy",
+          name: "ip",
+          namespace: "azureclaw-demo",
+          versionHash: "sha256:" + "e".repeat(64),
+          bindingConfigMap: null,
+        },
+      ],
+    });
+    const diff = __test.diffAttestations(a, b);
+    const types = diff.deltas.map((d) => d.type).sort();
+    expect(types).toEqual(["policyAdded", "policyRemoved"]);
+  });
+
+  it("detects new SSA manager (set-comparison; counts ignored)", () => {
+    const a = baseReport();
+    const b = baseReport({
+      fieldOwners: [
+        { manager: "azureclaw-controller", fieldsOwned: 99 },
+        { manager: "kubectl-edit", fieldsOwned: 1 },
+      ],
+    });
+    const diff = __test.diffAttestations(a, b);
+    expect(diff.deltas).toContainEqual({
+      type: "fieldOwnerAdded",
+      manager: "kubectl-edit",
+    });
+    expect(diff.deltas.find((d) => d.type === "fieldOwnerRemoved")).toBeUndefined();
+  });
+
+  it("ignores field count fluctuation when manager set is identical", () => {
+    const a = baseReport();
+    const b = baseReport({
+      fieldOwners: [{ manager: "azureclaw-controller", fieldsOwned: 99 }],
+    });
+    const diff = __test.diffAttestations(a, b);
+    expect(diff.deltas).toEqual([]);
+  });
+
+  it("describeDelta produces a human sentence for every variant", () => {
+    const variants: Array<Parameters<typeof __test.describeDelta>[0]> = [
+      { type: "specHash", before: "sha256:aaaaaaaaaa", after: "sha256:bbbbbbbbbb" },
+      { type: "phase", before: "Running", after: "Degraded" },
+      {
+        type: "policyVersionHash",
+        kind: "ToolPolicy",
+        name: "tp",
+        before: "sha256:aa",
+        after: "sha256:bb",
+      },
+      { type: "policyAdded", kind: "InferencePolicy", name: "ip" },
+      { type: "policyRemoved", kind: "A2AAgent", name: "a" },
+      { type: "fieldOwnerAdded", manager: "kubectl-edit" },
+      { type: "fieldOwnerRemoved", manager: "azureclaw-controller" },
+    ];
+    for (const v of variants) {
+      const out = __test.describeDelta(v);
+      expect(out.length).toBeGreaterThan(0);
+      expect(typeof out).toBe("string");
+    }
+  });
+});
+
+describe("attestCommand — loadBaseline", () => {
+  it("returns null for missing file", async () => {
+    const result = await __test.loadBaseline("/no/such/file/anywhere/xyz.json");
+    expect(result).toBeNull();
+  });
+
+  it("loads a valid attestation file", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "attest-test-"));
+    try {
+      const path = join(dir, "baseline.json");
+      const valid = {
+        apiVersion: "azureclaw.azure.com/v1alpha1-attest",
+        kind: "Attestation",
+        generatedAt: "2026-04-01T00:00:00Z",
+        sandbox: {
+          name: "demo",
+          namespace: "azureclaw-system",
+          generation: 1,
+          observedGeneration: 1,
+          phase: "Running",
+          specHash: "sha256:" + "a".repeat(64),
+          specHashAlgorithm: "sha256-canonical-json",
+        },
+        fieldOwners: [],
+        policyVersions: [],
+        reconcileTraceId: null,
+        agtAuditReceiptId: null,
+        signature: null,
+      };
+      writeFileSync(path, JSON.stringify(valid));
+      const loaded = await __test.loadBaseline(path);
+      expect(loaded?.sandbox.specHash).toBe(valid.sandbox.specHash);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects a file missing the apiVersion sentinel", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "attest-test-"));
+    try {
+      const path = join(dir, "bad.json");
+      writeFileSync(path, JSON.stringify({ kind: "Attestation" }));
+      await expect(__test.loadBaseline(path)).rejects.toThrow(/not a valid AzureClaw attestation/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});