@kontourai/flow-agents 3.1.0 → 3.3.0

package/kits/knowledge/evals/supersede-propagation/suite.test.js

@@ -0,0 +1,384 @@
+/**
+ * Knowledge Kit — Supersede/Retire Propagation Eval Suite  (#342)
+ *
+ * knowledge.flag-superseded-citers enumerates the first-degree inbound citers of
+ * a superseded / retired record and emits one flag per citer, each carrying the
+ * superseding context. Two citer sources:
+ *   - store records — the reverse-link index (store contract §5, getLinks.reverse)
+ *   - docs          — the #340 inbound-reference citation index (byRecord), scanned
+ *                     from caller-configured doc globs (opt-in)
+ *
+ * The operation is READ-ONLY (mutates no record, appends no mutation-log entry —
+ * the existing gated supersede/retire ops are untouched) and FAIL-CLOSED on the
+ * evidence guarantee: a flag can never be emitted without superseding context, so
+ * a record with no supersession evidence yields zero flags (no false flags).
+ *
+ * Field motivation (ops design partner, record 0e439c57): a "sell the
+ * combination" decision was superseded/lost in a store restructure and four docs
+ * cited it invisibly for weeks. Supersession preserves the record and surfaces
+ * store citers via reverse links, but doc citers stayed invisible — this op
+ * closes that loop.
+ *
+ * PARAMETERIZED by adapter module — set KNOWLEDGE_ADAPTER to an adapter's
+ * absolute path, or pass --adapter=<path>. Defaults to the bundled default-store
+ * adapter. AC4 runs this file for the default adapter AND the obsidian adapter.
+ *
+ * AC map (issue #342):
+ *   AC1 (R1) — a record with one store-record citer + one doc citer: the
+ *              enumeration returns both, sourced from the reverse-link index and
+ *              the citation index respectively.
+ *   AC2 (R2) — after supersede(newId,[oldId]) each flag carries citerRef + citedId
+ *              + newId; a superseded record with no citers yields an empty flag
+ *              list; a non-superseded record yields zero flags (no false flags);
+ *              retire-with-supersededByRef carries the retire evidence.
+ *   AC3 (R3) — read-only invariant (byte-identical store before/after).
+ *   AC4 (R4) — parameterized across adapters (this file, run per KNOWLEDGE_ADAPTER);
+ *              contract addendum documents the operation + flag shape.
+ *
+ * Run:
+ *   node --test kits/knowledge/evals/supersede-propagation/suite.test.js
+ *   KNOWLEDGE_ADAPTER=kits/knowledge/adapters/obsidian-store/index.js \
+ *     node --test kits/knowledge/evals/supersede-propagation/suite.test.js
+ */
+
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = path.resolve(__dirname, "../..");
+const REPO_ROOT = path.resolve(KIT_ROOT, "../..");
+
+// ---------------------------------------------------------------------------
+// Adapter resolution — same convention as evals/inbound-references/suite.test.js
+// ---------------------------------------------------------------------------
+
+function resolveAdapterPath() {
+  const flag = process.argv.find((a) => a.startsWith("--adapter="));
+  if (flag) return path.resolve(flag.slice("--adapter=".length));
+  if (process.env.KNOWLEDGE_ADAPTER) return path.resolve(process.env.KNOWLEDGE_ADAPTER);
+  return path.join(KIT_ROOT, "adapters/default-store/index.js");
+}
+
+const adapterPath = resolveAdapterPath();
+const adapterModule = await import(adapterPath);
+const AdapterClass = adapterModule.default || adapterModule.DefaultKnowledgeStore;
+const ADAPTER_LABEL = path.relative(REPO_ROOT, adapterPath);
+
+const runnerPath = path.join(KIT_ROOT, "adapters/flow-runner/index.js");
+const { KnowledgeFlowRunner, flagSupersededCiters } = await import(runnerPath);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTempDir(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `knowledge-supersede-prop-${tag}-`));
+}
+
+function makeStore(dir) {
+  return new AdapterClass({ storeRoot: dir });
+}
+
+// The runner's workspace (telemetry sink) is kept SEPARATE from the store dir so
+// gate telemetry never lands inside the store — letting AC3 assert the whole
+// store tree is byte-identical, not just its record files.
+function makeRunner(store, workspaceDir) {
+  return new KnowledgeFlowRunner({
+    store,
+    workspace: workspaceDir,
+    agent: "supersede-prop-test-runner",
+    sessionId: "supersede-prop-session-001",
+  });
+}
+
+function writeDoc(root, rel, body) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, body, "utf8");
+}
+
+/** Recursive { relPath -> content } snapshot of every file under a dir. */
+function snapshotTree(root) {
+  const out = {};
+  const walk = (abs, rel) => {
+    for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(abs, e.name), r);
+      else if (e.isFile()) out[r] = fs.readFileSync(path.join(abs, e.name), "utf8");
+    }
+  };
+  walk(root, "");
+  return out;
+}
+
+// Deterministic, valid-hex UUIDs.
+const OLD = "aaaaaaaa-1111-4111-8111-111111111111"; // the superseded decision
+const NEW = "bbbbbbbb-2222-4222-8222-222222222222"; // the superseding decision
+const CITER = "cccccccc-3333-4333-8333-333333333333"; // a store record that cites OLD
+const LONE = "dddddddd-4444-4444-8444-444444444444"; // superseded, no citers
+const LONE_NEW = "eeeeeeee-5555-4555-8555-555555555555"; // supersedes LONE
+const LIVE = "ffffffff-6666-4666-8666-666666666666"; // never superseded, but cited
+const LIVE_CITER = "abababab-7777-4777-8777-777777777777"; // cites LIVE
+const RET = "cdcdcdcd-8888-4888-8888-888888888888"; // retired-with-supersededByRef
+const RET_CITER = "efefefef-9999-4999-8999-999999999999"; // cites RET
+
+async function record(store, id, title, category) {
+  await store.create({
+    id, type: "compiled", title, body: `Body of ${title}`,
+    category, provenance: { agent: "fixture" },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe(`Knowledge Kit Supersede/Retire Propagation Suite (#342) [adapter: ${ADAPTER_LABEL}]`, () => {
+  let storeDir;
+  let workspaceDir;
+  let store;
+  let runner;
+
+  beforeEach(() => {
+    storeDir = makeTempDir("store");
+    workspaceDir = makeTempDir("ws");
+    store = makeStore(storeDir);
+    runner = makeRunner(store, workspaceDir);
+  });
+
+  afterEach(() => {
+    if (storeDir) fs.rmSync(storeDir, { recursive: true, force: true });
+    if (workspaceDir) fs.rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  test("AC1: a record with one store-record citer + one doc citer enumerates BOTH, from the two indexes", async () => {
+    const docsRoot = makeTempDir("ac1-docs");
+    try {
+      await record(store, OLD, "Sell the combination (6/17 decision)", "decision.strategy");
+      await record(store, NEW, "GTM direction (7/3)", "decision.strategy");
+      await record(store, CITER, "Vision doc mirror", "decision.strategy");
+      // Store-record citer: CITER --related--> OLD (reverse-link index, §5).
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      // Supersede OLD with NEW (Addendum A.5).
+      await store.supersede(NEW, [OLD], {
+        agent: "fixture",
+        rationale: "GTM direction supersedes the 6/17 sell-the-combination decision.",
+      });
+      // Doc citer: NOW.md cites OLD by full UUID (#340 citation index).
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\nAnchored on decision ${OLD}.\n`);
+
+      const result = await runner.flagSupersededCiters(OLD, {
+        docGlobs: ["NOW.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.superseded, true, "OLD is superseded");
+      assert.equal(result.storeCiters, 1, "one store-record citer from the reverse-link index");
+      assert.equal(result.docCiters, 1, "one doc citer from the #340 citation index");
+      assert.equal(result.flags.length, 2, "both citers flagged");
+
+      const recordFlag = result.flags.find((f) => f.citerKind === "record");
+      const docFlag = result.flags.find((f) => f.citerKind === "doc");
+      assert.ok(recordFlag, "a store-record citer flag is present");
+      assert.equal(recordFlag.citerRef, CITER, "record flag names the citing record id");
+      assert.equal(recordFlag.linkKind, "related", "record flag carries the reverse link kind (index-sourced)");
+
+      assert.ok(docFlag, "a doc citer flag is present");
+      assert.equal(docFlag.doc, "NOW.md", "doc flag names the citing doc path");
+      assert.equal(docFlag.token, OLD, "doc flag names the cited token (citation index)");
+      assert.equal(typeof docFlag.line, "number", "doc flag names a line");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("AC2: every emitted flag carries citerRef + citedId + the superseding record id (newId)", async () => {
+    const docsRoot = makeTempDir("ac2-ctx-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "strategy/vision.md", `# Vision\n\nSee ${OLD}.\n`);
+
+      const result = await runner.flagSupersededCiters(OLD, {
+        docGlobs: ["strategy/*.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.flags.length, 2);
+      for (const f of result.flags) {
+        assert.ok(f.citerRef, "flag carries a citer ref");
+        assert.equal(f.citedId, OLD, "flag names the cited (superseded) id");
+        assert.ok(
+          Array.isArray(f.supersededByIds) && f.supersededByIds.includes(NEW),
+          "flag carries the superseding record id (newId) as evidence"
+        );
+      }
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("AC2: a superseded record with NO citers yields an empty flag list (no false flags)", async () => {
+    await record(store, LONE, "Lonely superseded decision", "decision.pricing");
+    await record(store, LONE_NEW, "Replacement decision", "decision.pricing");
+    await store.supersede(LONE_NEW, [LONE], { agent: "fixture", rationale: "replaced." });
+
+    const result = await runner.flagSupersededCiters(LONE, {});
+    assert.equal(result.superseded, true, "record is superseded");
+    assert.deepEqual(result.flags, [], "no citers → no flags");
+    assert.equal(result.storeCiters, 0, "the superseding record itself is not counted as a citer");
+    assert.equal(result.docCiters, 0);
+  });
+
+  test("AC2: a NON-superseded record emits ZERO flags even when it has citers (evidence guarantee, fail closed)", async () => {
+    const docsRoot = makeTempDir("ac2-live-docs");
+    try {
+      await record(store, LIVE, "Live decision", "decision.strategy");
+      await record(store, LIVE_CITER, "Citer of live decision", "decision.strategy");
+      await store.link(LIVE_CITER, [{ target_id: LIVE, kind: "related" }], { agent: "fixture" });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\nCurrent authority ${LIVE}.\n`);
+
+      const result = await runner.flagSupersededCiters(LIVE, {
+        docGlobs: ["NOW.md"],
+        docsRoot,
+      });
+
+      assert.equal(result.superseded, false, "record shows no supersession evidence");
+      assert.deepEqual(result.supersededByIds, [], "no superseding record ids");
+      assert.equal(result.supersededByRef, null, "no retire supersededByRef");
+      assert.deepEqual(result.flags, [], "no supersession evidence → no flag can be emitted");
+      // The inbound edges are still visible via the counts (enumeration is R1),
+      // even though gating (R2) suppresses the flags.
+      assert.equal(result.storeCiters, 1, "enumeration still surfaces the store citer");
+      assert.equal(result.docCiters, 1, "enumeration still surfaces the doc citer");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("R2: retire-with-supersededByRef flags citers carrying the retire evidence", async () => {
+    await record(store, RET, "Retired-and-superseded decision", "decision.ops");
+    await record(store, RET_CITER, "Citer of retired decision", "decision.ops");
+    await store.link(RET_CITER, [{ target_id: RET, kind: "related" }], { agent: "fixture" });
+    // Retire RET pointing at a superseding artifact ref (Addendum B.4).
+    await store.retire(RET, "retired", {
+      agent: "fixture",
+      rationale: "Superseded by the new GTM record; archiving.",
+      supersededByRef: NEW,
+    });
+
+    const result = await runner.flagSupersededCiters(RET, {});
+    assert.equal(result.superseded, true, "retire-with-supersededByRef counts as supersession");
+    assert.equal(result.supersededByRef, NEW, "the retire supersededByRef is surfaced");
+    assert.equal(result.retiredStatus, "retired", "retired status is surfaced");
+    assert.equal(result.flags.length, 1, "the store citer is flagged");
+    const [f] = result.flags;
+    assert.equal(f.citerRef, RET_CITER);
+    assert.equal(f.citedId, RET);
+    assert.equal(f.supersededByRef, NEW, "flag carries the retire evidence");
+  });
+
+  test("AC3: read-only invariant — the store is byte-identical before and after the enumeration", async () => {
+    const docsRoot = makeTempDir("ac3-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\n${OLD}\n`);
+
+      const before = snapshotTree(storeDir);
+      await runner.flagSupersededCiters(OLD, { docGlobs: ["NOW.md"], docsRoot });
+      const after = snapshotTree(storeDir);
+
+      assert.deepEqual(after, before, "no store file is created, deleted, or mutated by the enumeration");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("opt-in: with no doc globs the enumeration returns store citers only (no doc scan)", async () => {
+    await record(store, OLD, "Old decision", "decision.strategy");
+    await record(store, NEW, "New decision", "decision.strategy");
+    await record(store, CITER, "Citer record", "decision.strategy");
+    await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+    await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+
+    const result = await runner.flagSupersededCiters(OLD, {});
+    assert.equal(result.storeCiters, 1, "store citer enumerated");
+    assert.equal(result.docCiters, 0, "no doc scan when globs are unconfigured");
+    assert.equal(result.flags.length, 1);
+    assert.equal(result.flags[0].citerKind, "record");
+  });
+
+  test("gate telemetry: collect-gate and flag-gate events are emitted", async () => {
+    await record(store, OLD, "Old decision", "decision.strategy");
+    await record(store, NEW, "New decision", "decision.strategy");
+    await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+
+    const result = await runner.flagSupersededCiters(OLD, {});
+    const names = result.telemetryEvents.map((e) => e.gate || (e.data && e.data.gate)).filter(Boolean);
+    assert.ok(
+      result.telemetryEvents.length >= 4,
+      "collect-gate + flag-gate produce at least 4 in/out events"
+    );
+    assert.ok(names.includes("collect-gate") || result.telemetryEvents.length >= 4, "collect-gate present");
+  });
+
+  test("module-level flagSupersededCiters export delegates to the runner", async () => {
+    const docsRoot = makeTempDir("mod-docs");
+    try {
+      await record(store, OLD, "Old decision", "decision.strategy");
+      await record(store, NEW, "New decision", "decision.strategy");
+      await record(store, CITER, "Citer record", "decision.strategy");
+      await store.link(CITER, [{ target_id: OLD, kind: "related" }], { agent: "fixture" });
+      await store.supersede(NEW, [OLD], { agent: "fixture", rationale: "superseded." });
+      writeDoc(docsRoot, "NOW.md", `# NOW\n\n${OLD}\n`);
+
+      const result = await flagSupersededCiters(OLD, {
+        store, workspace: workspaceDir, agent: "supersede-prop-test-runner",
+        docGlobs: ["NOW.md"], docsRoot,
+      });
+      assert.equal(result.superseded, true);
+      assert.equal(result.flags.length, 2, "delegated call enumerates both citers");
+    } finally {
+      fs.rmSync(docsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("missing record fails closed (never a silent empty pass)", async () => {
+    await assert.rejects(
+      () => runner.flagSupersededCiters("deadbeef-0000-4000-8000-000000000000", {}),
+      /record not found/,
+      "an unknown record id throws, not returns an empty flag list"
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC4 (doc claim) — the contract addendum is committed. Adapter-independent, so
+// run once (only under the default adapter to avoid duplicate reporting).
+// ---------------------------------------------------------------------------
+
+describe("Supersede/Retire Propagation — contract doc addendum (#342)", () => {
+  test("AC4: store-contract.md documents the operation as Addendum K", () => {
+    if (!ADAPTER_LABEL.includes("default-store")) return; // adapter-independent
+    const contract = fs.readFileSync(
+      path.join(KIT_ROOT, "docs/store-contract.md"), "utf8"
+    );
+    assert.match(contract, /## Addendum K —.*Supersede/i, "Addendum K heading present");
+    assert.match(contract, /flagSupersededCiters/, "documents the flow-runner operation name");
+    assert.match(contract, /supersededByIds/, "documents the flag superseding-context shape");
+    assert.match(contract, /read-only|read only/i, "documents the read-only invariant");
+    assert.match(contract, /no false flags|fail closed|fail-closed/i, "documents the evidence guarantee");
+    assert.match(contract, /byRecord|citation index/i, "documents the doc-citer citation-index source");
+  });
+});

package/kits/veritas-governance/docs/README.md

@@ -1,8 +1,10 @@
 # Veritas Governance Kit
 
 Turns a repo's **Veritas-governed Repo Standards** into deterministic, agentless **gate
-evidence**. Slice 1 ships the thinnest useful surface: one flow, one gate, that gates a real
-`veritas readiness` verdict.
+evidence**, and gives operators a documented, gated path to **issue** the human-approval
+exemptions ADR 0022 §2/§3 lets `delivery/DECLARED` carry. Slice 1 shipped the thinnest useful
+surface: one flow, one gate, that gates a real `veritas readiness` verdict. This slice adds a
+second, agentless flow for exemption issuance.
 
 This kit **wraps** [`@kontourai/veritas`](https://www.npmjs.com/package/@kontourai/veritas) via
 CLI invocation plus a small kit-local trust.bundle adapter. It does **not** fork, vendor, or
@@ -16,6 +18,7 @@ only projects Veritas's own recorded verdict into the Flow trust.bundle vocabula
 | Flow | `flows/readiness-check.flow.json` | Single-gate agentless flow `readiness -> gate-check`. The gate requires a **verified** `software-readiness-verdict` trust.bundle claim. |
 | Adapter | `adapter/readiness-to-trust-bundle.mjs` | Projects a `veritas readiness --check evidence --working-tree` evidence report into a Hachure `trust.bundle` (via `@kontourai/surface`), deriving the claim status from Veritas's own blocking-failure signal. |
 | Fixtures | `fixtures/readiness/*.readiness-report.json` | Captured **real** Veritas readiness reports (a ready clean tree, and a not-ready tree with a required CLI artifact deleted) used by the eval. |
+| Flow | `flows/exemption-issuance.flow.json` | Single-gate agentless flow `request -> human-approval-gate -> issue`. The gate requires a **verified** `no-agent-delivery-exemption-approval` trust.bundle claim (`subjectType: "delivery-scope"`) before the `issue` step's write is flow-sanctioned. Issues a `delivery/DECLARED` exemption entry per ADR 0022 §2/§3. |
 
 The gate uses provider-neutral Flow vocabulary (`kind: "trust.bundle"`, `bundle_claim`) — the
 same vocabulary `kits/builder/flows/build.flow.json` uses. Veritas is simply the producer that
@@ -42,6 +45,79 @@ flow evaluate readiness --gate gate-check-gate --exit-code
 #    exit 0 when readiness is ready (claim verified); exit 1 (block) otherwise.
 ```
 
+## How to issue a no-agent-delivery exemption
+
+`flows/exemption-issuance.flow.json` (ADR 0022 §3, "the kit issues, the anchor enforces") gives
+an operator who needs to declare a `no-agent-delivery` exemption — e.g. dependabot,
+release-please, or another non-agent actor class — a documented, gated path instead of
+hand-writing `delivery/DECLARED` JSON blind. See `delivery/README.md` for how `delivery/`
+itself is used by CI, and ADR 0022 §3 for why issuance/audit live in this kit while enforcement
+stays anchor-side (`scripts/ci/trust-reconcile.js`, unmodified and unaware of this kit).
+
+```bash
+# 1. A human approver authors a Hachure trust.bundle asserting the exemption approval.
+#    (No adapter script exists for this slice -- the bundle is hand-authored or produced
+#    by whatever approval tooling records the decision; see "Human-approval evidence: what
+#    is and is not enforced" below for why this is convention, not a structural human-only
+#    guarantee.)
+#    Minimal bundle shape: {schemaVersion, source, claims:[{claimType:
+#    "no-agent-delivery-exemption-approval", subjectType: "delivery-scope",
+#    status: "verified", ...}], evidence:[...], policies:[...], events:[...]}
+
+# 2. Gate it (agentless, CI-callable).
+flow init
+flow start kits/veritas-governance/flows/exemption-issuance.flow.json --run-id exemption
+flow attach-evidence exemption --gate human-approval-gate --file approval.bundle --bundle
+flow evaluate exemption --gate human-approval-gate --exit-code
+#    exit 0 once the approval claim is verified; exit 1 (block) otherwise.
+
+# 3. Once the gate passes, append the approved entry to delivery/DECLARED (append, do NOT
+#    overwrite an existing array -- see delivery/DECLARED's current 2-entry file on main).
+#    All four fields are required: scope, reason, approved_by, declared_at. Compound scope
+#    forms (space-separated, ANDed -- e.g. "author:github-actions[bot]
+#    branch-prefix:release-please--") are supported by the reconciler's scope matcher; see
+#    ADR 0022's compound-scope addendum.
+```
+
+Example appended entry (third element of the existing `delivery/DECLARED` array — never a
+replacement of it):
+
+```json
+{
+  "scope": "author:some-bot[bot]",
+  "reason": "why this actor class needs the exemption",
+  "approved_by": "<human approver identity/decision reference>",
+  "declared_at": "<ISO 8601 timestamp>"
+}
+```
+
+## Human-approval evidence: what is and is not enforced
+
+The `human-approval-gate`'s `expects[]` entry only requires a **verified** trust.bundle claim
+of the right `claimType` (`no-agent-delivery-exemption-approval`) and `subjectType`
+(`delivery-scope`). **Flow's schema and CLI do not distinguish a human-authored bundle from an
+agent-authored one** — `trust-bundle.schema.json`'s `source` and `producerId` fields are
+free-text, with no enum, no cryptographic binding, and no CLI-side identity check.
+"Human-attached" is an **operating convention** this flow's `description`/`explore_hint` text
+encode (the gate's own copy tells an operator this evidence is meant to be authored by a human
+approver out-of-band), not a mechanism the gate itself enforces. Anyone who can run `flow
+attach-evidence --bundle` with a conforming bundle can satisfy this gate, exactly as anyone with
+commit access could already hand-author `delivery/DECLARED` directly.
+
+This is the same class of residual ADR 0022 already carries honestly for the marker file
+itself: `approved_by` on `delivery/DECLARED` is free text, not bound to an authenticated
+identity, mitigated by the loud, un-suppressible DECLARED line plus CODEOWNERS review on
+`/delivery/DECLARED` — not by identity attestation. This flow adds **guidance and an audit
+trail** (a named gate, a named claim type, a documented sequence) on top of that same
+mitigation, not a new authentication boundary. Structural producer authentication — binding
+gate satisfaction to an authenticated producer identity, rather than to a schema-valid claim
+attached by anyone with CLI access — is upstream **Flow trusted-producer** work
+(`docs/operating-layers.md`, `docs/flow-kit-repository-contract.md` in this repo describe the
+config surface; the config itself is Flow-core, tracked at #225/#293-family), not something
+this kit's `.flow.json` can itself express. Do not read a passing `human-approval-gate` as a
+structural guarantee that a human attached the evidence — read it as "a verified claim of the
+right shape was attached," full stop.
+
 ## Semantics
 
 **Settled** (owner-ratified + investigation-confirmed; see
@@ -72,4 +148,6 @@ decision deferred to a later slice (see the WS5 shaping's open decisions).
 
 Skills (`consult-standards`, `governance-evidence`), the fuller `merge-readiness` flow, the
 `standards-authoring` flow, and the `knowledge` dependency are later slices — see the WS5
-backlog.
+backlog. The `exemption-usage-review` periodic audit flow/skill named in ADR 0022 §3 (walks
+`delivery/DECLARED` history and surfaces standing exemptions for owner re-confirmation —
+process visibility, not enforcement) is also a separate, later slice, not shipped here.

package/kits/veritas-governance/fixtures/exemption/approved.trust-bundle.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 5,
+  "source": "veritas-governance-kit/exemption-fixture",
+  "claims": [
+    {
+      "id": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "subjectType": "delivery-scope",
+      "subjectId": "author:test-bot[bot]",
+      "facet": "veritas-governance.exemption",
+      "claimType": "no-agent-delivery-exemption-approval",
+      "fieldOrBehavior": "exemptionApproval",
+      "value": {
+        "scope": "author:test-bot[bot]",
+        "reason": "test-bot automation PR; no agent delivery involved",
+        "approved_by": "eval-fixture-approver"
+      },
+      "createdAt": "2026-07-01T00:00:00Z",
+      "updatedAt": "2026-07-01T00:00:00Z",
+      "impactLevel": "high",
+      "verificationPolicyId": "policy:no-agent-delivery-exemption-approval",
+      "metadata": {
+        "producer": "human-approver",
+        "source": "exemption-issuance-fixture"
+      },
+      "status": "verified"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "claimId": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "evidenceType": "policy_rule",
+      "method": "auditability",
+      "sourceRef": "human-approver:exemption-issuance-fixture",
+      "excerptOrSummary": "A human maintainer approved a no-agent-delivery exemption for scope author:test-bot[bot].",
+      "observedAt": "2026-07-01T00:00:00Z",
+      "collectedBy": "veritas-governance-kit/exemption-fixture",
+      "passing": true
+    }
+  ],
+  "events": [
+    {
+      "id": "evt:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "claimId": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "status": "verified",
+      "actor": "veritas-governance-kit/exemption-fixture",
+      "method": "auditability",
+      "evidenceIds": [
+        "ev:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot"
+      ],
+      "createdAt": "2026-07-01T00:00:00Z",
+      "verifiedAt": "2026-07-01T00:00:00Z"
+    }
+  ],
+  "policies": [
+    {
+      "id": "policy:no-agent-delivery-exemption-approval",
+      "claimType": "no-agent-delivery-exemption-approval",
+      "requiredEvidence": [
+        "policy_rule"
+      ],
+      "acceptanceCriteria": [
+        "A human maintainer has approved this delivery-scope exemption from Trust Reconcile's bundle-required enforcement."
+      ],
+      "reviewAuthority": "human",
+      "validityRule": {
+        "kind": "manual"
+      },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "high"
+    }
+  ]
+}

package/kits/veritas-governance/fixtures/exemption/not-approved.trust-bundle.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 5,
+  "source": "veritas-governance-kit/exemption-fixture",
+  "claims": [
+    {
+      "id": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "subjectType": "delivery-scope",
+      "subjectId": "author:test-bot[bot]",
+      "facet": "veritas-governance.exemption",
+      "claimType": "no-agent-delivery-exemption-approval",
+      "fieldOrBehavior": "exemptionApproval",
+      "value": {
+        "scope": "author:test-bot[bot]",
+        "reason": "test-bot automation PR; no agent delivery involved",
+        "approved_by": "eval-fixture-approver"
+      },
+      "createdAt": "2026-07-01T00:00:00Z",
+      "updatedAt": "2026-07-01T00:00:00Z",
+      "impactLevel": "high",
+      "verificationPolicyId": "policy:no-agent-delivery-exemption-approval",
+      "metadata": {
+        "producer": "human-approver",
+        "source": "exemption-issuance-fixture"
+      },
+      "status": "disputed"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "claimId": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "evidenceType": "policy_rule",
+      "method": "auditability",
+      "sourceRef": "human-approver:exemption-issuance-fixture",
+      "excerptOrSummary": "A no-agent-delivery exemption approval claim was attached but is not (yet) verified for scope author:test-bot[bot].",
+      "observedAt": "2026-07-01T00:00:00Z",
+      "collectedBy": "veritas-governance-kit/exemption-fixture",
+      "passing": false
+    }
+  ],
+  "events": [
+    {
+      "id": "evt:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "claimId": "exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot",
+      "status": "disputed",
+      "actor": "veritas-governance-kit/exemption-fixture",
+      "method": "auditability",
+      "evidenceIds": [
+        "ev:exemption-fixture.no-agent-delivery-exemption-approval.author-test-bot"
+      ],
+      "createdAt": "2026-07-01T00:00:00Z",
+      "verifiedAt": "2026-07-01T00:00:00Z"
+    }
+  ],
+  "policies": [
+    {
+      "id": "policy:no-agent-delivery-exemption-approval",
+      "claimType": "no-agent-delivery-exemption-approval",
+      "requiredEvidence": [
+        "policy_rule"
+      ],
+      "acceptanceCriteria": [
+        "A human maintainer has approved this delivery-scope exemption from Trust Reconcile's bundle-required enforcement."
+      ],
+      "reviewAuthority": "human",
+      "validityRule": {
+        "kind": "manual"
+      },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "high"
+    }
+  ]
+}