@kontourai/flow-agents 3.2.0 → 3.4.0

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,8 @@ 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. |
+| Skill | `skills/exemption-usage-review/SKILL.md` | Periodic audit skill (ADR 0022 §3): walks `delivery/DECLARED` + its `git log --follow` history and reports every standing exemption (scope, reason, approver, age since `declared_at`), flagging entries overdue for owner re-confirmation against a configurable staleness threshold. Process visibility, not enforcement — read-only, never mutates `delivery/DECLARED` or the reconciler. |
 
 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 +46,104 @@ 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>"
+}
+```
+
+## How to run the review
+
+`skills/exemption-usage-review/SKILL.md` (ADR 0022 §3, "the kit issues, the anchor
+enforces... and the kit audits") gives an operator a periodic, read-only way to see every
+`delivery/DECLARED` exemption currently standing, how old each one is, and which are overdue
+for owner re-confirmation. This is **process visibility, not enforcement** — it never
+modifies `delivery/DECLARED` and never changes `scripts/ci/trust-reconcile.js`'s
+reconciliation decision or exit code.
+
+```bash
+# Human-readable report against this repo's real delivery/DECLARED, default 90-day threshold.
+node kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs
+
+# Machine-readable, with a deterministic "now" and a tighter threshold.
+node kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs \
+  --as-of 2026-07-05T00:00:00Z --stale-days 30 --json
+```
+
+Each standing exemption is reported as `{scope, reason, approved_by, declared_at, age_days,
+stale}`; a `git log --follow -- delivery/DECLARED` history walk is reported alongside it as a
+supplementary commit-level trail. See the skill's own SKILL.md for the full "what this review
+does and does not verify" statement (it does not authenticate `approved_by`, does not
+re-evaluate whether any scope currently matches a given change — that remains
+`trust-reconcile.js`'s job — and does not schedule itself; an operator runs it periodically).
+
+## 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
@@ -64,12 +166,16 @@ derivation is correct today and will agree with Veritas's own exported functions
 
 ## Trust status
 
-Slice 1 ships **unverified** (like `kits/release-evidence`); it is not on the first-party
-allowlist (`src/flow-kit/validate.ts` `FIRST_PARTY_KIT_IDS`). First-party promotion is an owner
-decision deferred to a later slice (see the WS5 shaping's open decisions).
+Slice 1 ships **unverified** (like all current kits). Official catalog placement is marketplace
+metadata only and grants no runtime privilege. Verified promotion is an owner decision deferred
+to a later slice (see the WS5 shaping's open decisions).
 
 ## Not in slice 1
 
-Skills (`consult-standards`, `governance-evidence`), the fuller `merge-readiness` flow, the
+Skills `consult-standards` and `governance-evidence`, the fuller `merge-readiness` flow, the
 `standards-authoring` flow, and the `knowledge` dependency are later slices — see the WS5
-backlog.
+backlog. `exemption-usage-review` (ADR 0022 §3's periodic audit skill, walking
+`delivery/DECLARED` history and surfacing standing exemptions for owner re-confirmation —
+process visibility, not enforcement) **has now shipped** — see "What it contains" above and
+"How to run the review". Nothing schedules it automatically; an operator runs it periodically
+(see the skill's own "Accepted gap" note) — that scheduling surface remains out of scope.

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"
+    }
+  ]
+}

package/kits/veritas-governance/fixtures/exemption-review/mixed-fresh-stale.DECLARED.json

@@ -0,0 +1,14 @@
+[
+  {
+    "scope": "author:dependabot[bot]",
+    "reason": "dependabot dependency-update PRs; no agent delivery involved",
+    "approved_by": "example-approver (fixture-only)",
+    "declared_at": "2026-06-20T00:00:00Z"
+  },
+  {
+    "scope": "author:example-legacy-bot[bot]",
+    "reason": "example fixture: a legacy exemption overdue for owner re-confirmation",
+    "approved_by": "example-approver (fixture-only)",
+    "declared_at": "2026-01-01T00:00:00Z"
+  }
+]

package/kits/veritas-governance/flows/exemption-issuance.flow.json

@@ -0,0 +1,35 @@
+{
+  "id": "veritas-governance.exemption-issuance",
+  "version": "1.0",
+  "steps": [
+    { "id": "request", "next": "issue" },
+    { "id": "issue", "next": null }
+  ],
+  "gates": {
+    "human-approval-gate": {
+      "step": "issue",
+      "expects": [
+        {
+          "id": "exemption-approval",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "A human maintainer has approved this delivery-scope exemption from Trust Reconcile's bundle-required enforcement (ADR 0022 §1/§2), recorded as a verified no-agent-delivery-exemption-approval trust.bundle claim.",
+          "explore_hint": "A human approver authors a Hachure trust.bundle carrying a no-agent-delivery-exemption-approval / delivery-scope claim with status verified, then `flow attach-evidence <run> --gate human-approval-gate --file <bundle> --bundle`.",
+          "bundle_claim": {
+            "claimType": "no-agent-delivery-exemption-approval",
+            "subjectType": "delivery-scope",
+            "accepted_statuses": ["verified"]
+          }
+        }
+      ],
+      "on_route_back": {
+        "missing_evidence": "issue",
+        "default": "issue"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      }
+    }
+  }
+}

package/kits/veritas-governance/kit.json

@@ -8,6 +8,25 @@
       "id": "veritas-governance.readiness-check",
       "path": "flows/readiness-check.flow.json",
       "description": "Single-gate agentless flow: requires a verified software-readiness-verdict trust.bundle claim (projected from `veritas readiness --check evidence --working-tree`) before the gate-check step can pass. CI-callable, K0."
+    },
+    {
+      "id": "veritas-governance.exemption-issuance",
+      "path": "flows/exemption-issuance.flow.json",
+      "description": "Agentless K0 flow issuing a delivery/DECLARED no-agent-delivery exemption (ADR 0022 §2/§3): step request -> gate human-approval-gate (requires a verified no-agent-delivery-exemption-approval trust.bundle claim, satisfiable only by a human-authored approval bundle by convention -- see docs/README.md) -> step issue, which appends the approved entry to delivery/DECLARED. CI-callable."
+    }
+  ],
+  "skills": [
+    {
+      "id": "veritas-governance.exemption-usage-review",
+      "path": "skills/exemption-usage-review/SKILL.md",
+      "description": "Periodic audit skill (ADR 0022 §3): walks delivery/DECLARED + its git log --follow history and reports every standing no-agent-delivery exemption (scope, reason, approver, age since declared_at), flagging entries overdue for owner re-confirmation against a configurable staleness threshold. Process visibility, not enforcement -- read-only, never mutates delivery/DECLARED or scripts/ci/trust-reconcile.js's behavior."
+    }
+  ],
+  "assets": [
+    {
+      "id": "veritas-governance.exemption-usage-review-helper",
+      "path": "skills/exemption-usage-review/review-exemptions.mjs",
+      "description": "Dependency-free ESM helper script the exemption-usage-review skill documents/invokes: reads delivery/DECLARED, computes age/staleness per entry, walks git log --follow -- delivery/DECLARED for a supplementary history trail. Read-only; never mutates delivery/DECLARED or scripts/ci/trust-reconcile.js's behavior."
     }
   ],
   "docs": [

package/kits/veritas-governance/skills/exemption-usage-review/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: "exemption-usage-review"
+description: "Periodic audit of standing delivery/DECLARED no-agent-delivery exemptions (ADR 0022 §3): lists every current exemption's scope, reason, approver, and age since declared_at, flags entries overdue for owner re-confirmation against a configurable staleness threshold, and walks the file's git history for a supplementary commit-level trail. Use when periodically reviewing which no-agent-delivery exemptions are still standing and whether any need re-confirmation."
+---
+
+# Exemption Usage Review
+
+Read `delivery/DECLARED`, list every standing exemption with its age, and flag which ones
+are overdue for owner re-confirmation — **process visibility, not enforcement** (ADR 0022
+§3). This skill never changes `delivery/DECLARED` and never changes
+`scripts/ci/trust-reconcile.js`'s reconciliation/exit-code behavior.
+
+## Contract
+
+- Read-only against `delivery/DECLARED` and its git history — no write, no mutation, no
+  append, no delete, anywhere in this repo.
+- Never gates anything: this is a **skill**, not a flow. It has no `expects[]` claim to
+  evaluate and attaches no evidence. There is no pass/fail verdict — only a report.
+- Never influences `scripts/ci/trust-reconcile.js`'s reconciliation decision or exit code.
+  The reconciler is unaware this skill exists, exactly as it is unaware of the rest of this
+  kit (ADR 0022 §3, "uninstalling `veritas-governance` must never weaken enforcement").
+- Does not reimplement `scripts/ci/trust-reconcile.js`'s `matchesScope` /
+  `matchesScopeCondition` / `parseDeclaredMarker` functions. The review lists **every**
+  standing entry unconditionally — it has no "does this scope match the current change"
+  question to answer (that is the reconciler's job, evaluated per-change at CI time). This
+  skill answers a different question — "what exemptions exist at all, and how old are they" —
+  so it needs only a much simpler parse-and-age routine, not the reconciler's scope-matching
+  engine. See `review-exemptions.mjs`'s header comment for the same note in code.
+- No `.kontourai/flow-agents/<slug>/` session artifact contract applies here: this skill
+  produces a standalone report (stdout, human-readable or `--json`), not a workflow sidecar
+  artifact. State this plainly rather than inventing an artifact contract this tool does not
+  need.
+
+## What this review does and does not verify
+
+**Does verify:**
+- Every entry currently present in the live `delivery/DECLARED` file is listed with its
+  `scope`, `reason`, `approved_by`, `declared_at`, a computed `age_days` (now, or `--as-of`,
+  minus `declared_at`), and a `stale` boolean (`age_days > --stale-days`, default 90).
+- The `git log --follow -- delivery/DECLARED` commit history for the file — optionally
+  bounded to a `--window-days` review window — is walked and reported as a supplementary
+  commit-level trail (sha, author, date, subject).
+
+**Does not verify:**
+- Whether any `approved_by` value names a real, authenticated human approver.
+  `approved_by` is free text on `delivery/DECLARED` itself (see this kit's own
+  `docs/README.md`, "Human-approval evidence: what is and is not enforced") — this tool
+  reports what the field says, it does not authenticate it.
+- Whether any entry's `scope` (`ref:`/`commit:`/`author:`/`branch-prefix:`, or a
+  compound-AND combination) currently matches any particular change. That is
+  `scripts/ci/trust-reconcile.js`'s job at reconciliation time — a "does this exemption
+  apply to THIS change" question this review never asks. This review lists every entry
+  regardless of whether it currently matches anything.
+- A full point-in-time reconstruction and diff of every historical version of
+  `delivery/DECLARED` (e.g. "entry X was removed then silently re-added with a different
+  reason"). `history_commits` gives the commit-level trail a human reviewer can inspect
+  further with `git show <sha>:delivery/DECLARED`; this tool does not do that per-commit
+  content diffing itself.
+- Anything about whether the exemption is still *needed* — that is an owner judgment call
+  this review surfaces evidence for, not a decision it makes.
+
+## Inputs
+
+- `delivery/DECLARED` (default; override via `--declared-path <path>` for a fixture or a
+  different repo layout).
+- `--repo-root <path>` (default: current working directory) — the git repository whose
+  history is walked.
+- `--stale-days <n>` (default: `90`) — the configurable age threshold. Entries with
+  `age_days > stale-days` are flagged `stale: true`.
+- `--window-days <n>` (optional; default: full history) — bounds the `git log --follow`
+  history walk to commits within the last `<n>` days of `--as-of`. Does not affect which
+  *current* entries are listed — the live file's entries are always listed in full; this
+  only bounds the supplementary history trail.
+- `--as-of <ISO8601>` (default: `new Date().toISOString()`, i.e. wall-clock now) —
+  deterministic override for "now", so a scheduled/periodic invocation or an eval is not
+  wall-clock-flaky. Mirrors this repo's `TRUST_RECONCILE_SHA`/`_REF`/`_ACTOR` override
+  convention in `scripts/ci/trust-reconcile.js`.
+- `--json` (optional) — emit a machine-readable JSON report instead of the human-readable
+  table.
+
+## How to run the review
+
+```bash
+# Human-readable report against this repo's real delivery/DECLARED, default 90-day threshold.
+node kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs
+
+# Machine-readable, with an explicit deterministic "now" and a tighter threshold.
+node kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs \
+  --as-of 2026-07-05T00:00:00Z --stale-days 30 --json
+
+# Bound the supplementary history walk to the last 180 days.
+node kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs \
+  --window-days 180
+```
+
+Exit code: `0` on a clean run — even when one or more entries are flagged `stale`. Staleness
+is informational output for a human owner to act on, never a script failure condition. Exit
+`2` on bad arguments; exit `3` when `delivery/DECLARED` is missing or not valid JSON (nothing
+to review — a tool-usage failure, not a staleness finding).
+
+## Output shape
+
+Each standing-exemption row: `{scope, reason, approved_by, declared_at, age_days, stale}`.
+`age_days`/`stale` are `null` (never silently coerced to `true`/`false`) when `declared_at`
+is missing or unparsable — an honest "unknown", not a guessed verdict.
+
+The history section separately reports `{sha, author, date, subject}` per commit found by
+`git log --follow -- delivery/DECLARED` in the (optionally windowed) range. A git failure
+(no repository, no history, shallow clone) degrades to an empty history list plus a
+diagnostic note — never a crash and never a fabricated commit.
+
+## What happens with a stale entry
+
+A `stale: true` entry means: this exemption has been standing longer than the configured
+threshold without a recorded re-confirmation. This review does not renew, revoke, or modify
+the entry itself — it surfaces the finding for an owner to act on: re-confirm the exemption
+is still needed (e.g. re-run the kit's exemption-issuance flow to record a fresh
+`declared_at` with the same or updated `reason`/`approved_by`), or remove it from
+`delivery/DECLARED` by direct, CODEOWNERS-reviewed edit. Both of those actions are outside
+this skill's scope by design — this skill only reports.
+
+## Accepted gap: nothing schedules this review
+
+ADR 0022 §3 asks for the review tool to exist, not for automated scheduling. This skill has
+no CI job, cron trigger, or scheduled invocation wired to it — an operator must run it
+periodically themselves (see "How to run the review" above). This is an accepted,
+explicitly-named scope boundary, not a silent gap: building a scheduling/CI-trigger surface
+was not requested and is not part of this slice.