@kontourai/flow-agents 3.3.0 → 3.4.1

package/kits/builder/kit.json

@@ -27,6 +27,126 @@
       "reason": "learning-review invokes knowledge-capture (kits/knowledge/skills/knowledge-capture/SKILL.md) for durable knowledge storage"
     }
   ],
+  "first_party": true,
+  "workflow_triggers": [
+    {
+      "id": "builder-build-work",
+      "when": "implementation-work-detected",
+      "target_flow_id": "builder.build",
+      "default_skill": "deliver",
+      "conditional_skills": [
+        {
+          "when": "user-requested-tdd",
+          "skill": "tdd-workflow"
+        }
+      ],
+      "required_sequence": ["plan-work", "execute-plan", "review-work", "verify-work"],
+      "post_verify_targets": ["release-readiness", "learning-review"]
+    }
+  ],
+  "flow_step_actions": [
+    {
+      "flow_id": "builder.build",
+      "step_id": "pull-work",
+      "skills": ["pull-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "design-probe",
+      "skills": ["pickup-probe"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "plan",
+      "skills": ["plan-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "execute",
+      "skills": ["execute-plan"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "verify",
+      "skills": ["review-work", "verify-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "merge-ready",
+      "skills": ["evidence-gate"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "pr-open",
+      "skills": [],
+      "operations": ["publish-change"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "merge-ready-ci",
+      "skills": ["release-readiness"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "learn",
+      "skills": ["learning-review"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "done",
+      "skills": []
+    }
+  ],
+  "hook_influence_expectations": [
+    {
+      "id": "dev-builder-build-requires-pickup-probe-before-plan",
+      "description": "missing pickup Probe before plan",
+      "tier": "design-target",
+      "must_include_guidance": [
+        "design-probe",
+        "accepted gaps",
+        "provider_state",
+        "conflict_risks"
+      ],
+      "must_include_actions": [
+        "route decision_gap back to design-probe/pickup Probe"
+      ]
+    },
+    {
+      "id": "dev-builder-review-before-verify-after-execute",
+      "description": "review-before-verify after execute",
+      "tier": "adapter",
+      "event": "PostToolUse",
+      "must_include_guidance": [
+        "Next: review",
+        "then verify",
+        "report only"
+      ],
+      "must_include_actions": [
+        "review-work for report-only critique before verify-work",
+        "not count critique.json as verification evidence"
+      ]
+    },
+    {
+      "id": "dev-builder-route-fresh-coding-prompt",
+      "description": "fresh coding prompt routes into Builder workflow",
+      "tier": "adapter",
+      "event": "UserPromptSubmit",
+      "must_include_guidance": [
+        "KIT WORKFLOW ROUTE",
+        "activate `deliver`",
+        "--flow-id builder.build",
+        "plan-work -> execute-plan -> review-work -> verify-work",
+        "release-readiness and learning-review"
+      ],
+      "must_include_actions": [
+        "use the `builder` kit's `builder.build` workflow before source edits",
+        "use deliver by default for coding/build work",
+        "do not bypass plan-work -> execute-plan -> review-work -> verify-work",
+        "publish, release readiness, and learning feedback"
+      ]
+    }
+  ],
   "skills": [
     {
       "id": "builder.builder-shape",

package/kits/builder/skills/deliver/SKILL.md

@@ -266,6 +266,48 @@ After review, verification, evidence, and Goal Fit are clean for the same diff:
    npm run workflow:sidecar -- reconcile-preflight .kontourai/flow-agents/<slug>
    ```
 
+   **#381 — manifest-lane constraint: which commands may be `kind:"command"` checks.** A check/claim
+   is only CI-reconcilable as `kind:"command"` (Surface's `test_output` evidence type) if its
+   command is a registered entry in the **trust-reconcile manifest** — the same
+   `{"id":..,"command":..,"lanes":[..]}` list `evals/ci/run-baseline.sh --manifest-json` emits
+   from its `CHECKS` array (source of truth: `evals/ci/run-baseline.sh` lines 12-67 for the
+   array, 166-182 for `emit_manifest_json`). `scripts/ci/trust-reconcile.js` resolves this same
+   manifest (`resolveManifest`/`manifestByCmd`, lines 292-370, 1101-1104) and reconciles a
+   `kind:"command"` claim's `execution.label` ONLY against it — a command not in the manifest
+   can never reconcile, and CI's reconciler names it exactly this way: `trust divergence: agent
+   claimed '<cmd>' passed; command is not in the reconcile manifest — a test_output claim must
+   name a manifest/required-lane command (CI cannot self-declare an arbitrary command)`. An
+   honest capture-backed check recorded against a real, passing, non-manifest command still
+   becomes this `not-run` divergence at CI reconcile time — it is not a shape bug to route
+   around, it is the manifest boundary working as designed. Anything that is not a registered
+   manifest command records as `kind:"external"` (a session-local attestation — e.g. a manual
+   code-review judgment) or `kind:"policy"` (a policy/compliance attestation — e.g. `promote`'s
+   claim, which carries no `command`/`execution.label` and therefore can never require a
+   manifest entry). This matters at every writer call that can produce a `kind:"command"`
+   check — `record-evidence`, `record-gate-claim --command`, and `record-check` — and again at
+   the `publish-delivery`/`reconcile-preflight` step above, which is where a non-manifest
+   command surfaces as a refusal before CI ever sees it. Gate claims recorded earlier in a
+   session are not special-cased here: the compose-safe writer path keeps every prior gate
+   claim's declared claim type intact across later `record-evidence`/`record-critique`/
+   `record-learning` calls, so a gate claim never needs to be the last write of a session to
+   survive.
+
+   - `kind:"command"` (manifest-backed) example — a real, currently-registered manifest entry
+     ("Source tree validation" → `npm run validate:source --`):
+
+     ```bash
+     npm run workflow:sidecar -- record-check .kontourai/flow-agents/<slug> -- npm run validate:source --
+     ```
+
+   - `kind:"external"` (non-manifest attestation) example — no `--command`, so nothing is
+     ever executed; the prose lives in `--summary`:
+
+     ```bash
+     npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+       --status pass \
+       --summary "Manual code review confirmed no regressions in the affected module."
+     ```
+
    **#379 — per-session delivery paths.** `publishDelivery()` writes to a PER-SESSION path
    `delivery/<slug>/trust.bundle` (+ `trust.checkpoint.json` companions), where `<slug>` is
    your session artifact dir's basename — NOT the old shared flat `delivery/trust.bundle`.

package/kits/builder/skills/evidence-gate/SKILL.md

@@ -208,4 +208,16 @@ explicitly accepts them as unrelated residual risk.
 
 Evidence passes only when acceptance criteria, scope integrity, CI/runtime evidence, and residual risk are sufficient for the risk class.
 
+For an active Builder Flow run, record merge readiness only after this skill reaches `PASS`:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+  --expectation merge-readiness \
+  --status pass \
+  --summary "Evidence gate passed: verified scope, acceptance evidence, review findings, and unresolved risks support provider review." \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/evidence.json","summary":"Structured evidence verdict and acceptance coverage."}'
+```
+
+Record `fail` or `not_verified` when the verdict is not `PASS`. The resulting trust bundle is evaluated by Flow and may route back to verification, execution, planning, or Probe according to the canonical definition.
+
 After `PASS`, hand off to `publish-change` when the work is still local, or to `release-readiness` when the verified commit, pushed branch, provider change record or no-provider-change reason, provider checks, closing refs, structured evidence refs, and `Acceptance Evidence` table are available. After `FAIL` or `NOT_VERIFIED`, stop and name the missing work or evidence.

package/kits/builder/skills/execute-plan/SKILL.md

@@ -79,6 +79,15 @@ This skill owns orchestration between waves. The contracts own artifact continui
    - **Checkpoint**: update session file with completed tasks and next wave
    - Record worker progress with `npm run workflow:sidecar -- record-agent-event --artifact-dir <artifact-dir> --agent-id <worker-id> --kind evidence --status active|done --summary ...`
 9. After all waves: set session file `status: executed` and update `state.json` / `handoff.json` with `advance-state`
+10. For an active Builder Flow run, record the `implementation-scope` gate claim only after the changed-file scope and acceptance mapping are complete:
+    ```bash
+    npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+      --expectation implementation-scope \
+      --status pass \
+      --summary "Implementation completed within the planned scope; changed files and supported acceptance criteria are recorded." \
+      --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--execute-plan.md","summary":"Execution record with changed files, acceptance mapping, and worker evidence."}'
+    ```
+    Use `fail` or `not_verified` when scope integrity is unresolved. The sidecar writer synchronizes Flow; it does not declare the execute gate passed itself.
 
 The orchestrator is responsible for keeping root `state.json` current, and performs that update **exclusively** through `npm run workflow:sidecar -- advance-state` — never through a direct Write/Edit tool call against the sidecar path. `config-protection.js` blocks direct tool-mediated writes to `state.json` by design; that block is expected and correct, not a bug to route around. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
 

package/kits/builder/skills/learning-review/SKILL.md

@@ -20,6 +20,8 @@ Turn delivery outcomes into durable learning and follow-up work.
 ## Inputs
 
 - Release-readiness artifact, evidence-gate artifact, PR/issue links, deploy notes, incidents, telemetry, user feedback, and reviewer/verifier notes.
+- **Delegation routing telemetry** — the per-run economics records (`.kontourai/telemetry/economics.jsonl`) carry `delegations[]` with each sub-agent's `(role, resolved_model, outcome)`. Feed them to the routing-efficiency review (step 2a) to judge whether the model each role routes to is actually efficient.
+- **Kit/gate economics proposal ledger** — the same economics records, turned into a durable, idempotent per-kit/per-gate proposal ledger (`.kontourai/telemetry/learning-review-proposals.jsonl`) by `scripts/telemetry/learning-review-proposals.sh`. Feed it to the kit/gate economics review (step 2b).
 
 ## Artifact Contract
 
@@ -89,6 +91,55 @@ Before identifying durable learnings, write down the intended behavior, observed
 
 Classify learnings as product, technical, operational, workflow, test, documentation, eval, or agent-behavior learning.
 
+### 2a. Review Delegation Routing Efficiency
+
+Run the routing-efficiency analyzer over the run's economics records and review its proposals — the
+internal mirror of the #409 small-model value proof, applied to our own agent fan-out:
+
+```bash
+bash scripts/telemetry/routing-efficiency.sh .kontourai/telemetry/economics.jsonl
+```
+
+It emits ADVISORY per-`(role, model)` proposals (`escalate-minimum-tier`, `keep-tier`, `monitor`,
+`insufficient-signal`) with rationales, computed only from **measurable** outcomes — `unavailable`
+outcomes are excluded (a missing verdict is neither success nor failure; see
+`docs/specs/harness-capability-matrix.md`). Fold any actionable proposal into `learning.json`:
+
+- an `escalate-minimum-tier` / demote proposal → a `routing` entry (`target: "rule"`, naming the
+  `.datum/config.json` role→model change to consider) or `correction` with `type: "agent"`.
+- **These are proposals, never auto-applied.** A human ratifies the `.datum/config.json` change, which
+  then travels the normal deliver loop (ADR 0003 call 5). `insufficient-signal` proposals are recorded
+  as coverage notes, not routing changes.
+
+### 2b. Review Kit/Gate Economics Proposals
+
+Run the kit/gate economics analyzer over a window of economics records whenever enough new
+records have piled up since the last ledger entry — cadenced during a learning-review pass, not
+on a scheduler (see `--help` for the full flag set):
+
+```bash
+bash scripts/telemetry/learning-review-proposals.sh --since <last-run-until> --until <now>
+```
+
+It emits ADVISORY per-kit (`kit-review-cost-inflation`) and per-gate (`gate-false-block-review`,
+`gate-well-calibrated`) proposals, each citing paired `evidence.cost` + `evidence.defect` — never
+cost alone. `insufficient-data` is a valid, reportable outcome, not a bar to lower; never propose
+from noise. Surface every new (non-`already_proposed`) proposal to the human with its evidence,
+then record the ratify/reject/defer decision BEFORE any follow-on work exists:
+
+```bash
+bash scripts/telemetry/learning-review-decide.sh <ledger> <proposal-id> \
+  --ratify|--reject|--defer --decided-by <name> --rationale "<why>"
+```
+
+- **These are proposals, never auto-applied.** Nothing here writes to `kits/**`,
+  `.datum/config.json`, or any gate/flow config file.
+- Only on `--ratify`, create the ordinary follow-on backlog item and record it back onto the
+  proposal with `--follow-on-ref <ref>` — a follow-on may never cite an unratified proposal. A
+  later pass's effect-fill shows whether the ratified change actually moved the numbers.
+
+See `docs/specs/learning-review-proposals-contract.md` for the full contract.
+
 ### 3. Route Follow-Up
 
 Route raw ideas or ambiguous improvements to `idea-to-backlog`. Create GitHub issues only for executable follow-up. Use `evidence-gate` again when unresolved trust questions remain.

package/kits/builder/skills/plan-work/SKILL.md

@@ -137,8 +137,17 @@ The `tool-planner` prompt context must include the latest-base confirmation and
 4. Read the plan artifact
 5. Update session file: paste plan summary into `## Plan`, set `status: planned`
 6. Update `state.json` (`status: planned`, phase `planning`, next action) via `npm run workflow:sidecar -- advance-state` — never through a direct Write/Edit tool call (`config-protection.js` blocks that by design)
-7. Present the plan to the user
-8. If the user wants changes, re-delegate to tool-planner with feedback
+7. For an active Builder Flow run, record the `implementation-plan` gate claim after the plan and structured sidecars are complete:
+   ```bash
+   npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+     --expectation implementation-plan \
+     --status pass \
+     --summary "Implementation plan records files, sequencing, acceptance criteria, and required evidence." \
+     --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<session-basename>-plan.md","summary":"Structured implementation plan with acceptance and evidence traceability."}'
+   ```
+   Use `fail` or `not_verified` instead of `pass` when the plan contract is not satisfied. The sidecar writer synchronizes Flow; Flow, not this skill, decides whether execution is now active.
+8. Present the plan to the user
+9. If the user wants changes, re-delegate to tool-planner with feedback
 
 Never rely on conversational memory for the slug. Resolve the active artifact with `npm run workflow:sidecar -- current --format path` and pass that path to delegated agents.
 
@@ -198,22 +207,10 @@ Copied from the plan artifact. This is the stop condition for delivery.
 
 {context?}
 
-## Ad-hoc Direct Entry (Planning-Only or Non-`pull-work` Sessions)
-
-`ensure-session --flow-id <id>` without `--step-id` defaults `active_step_id` to the
-flow's FIRST step (`pull-work` for `builder.build`). For a session that legitimately
-enters mid-flow — e.g. planning directly from a portfolio work item without a
-`pull-work`/pickup artifact — pass the sanctioned override:
-
-```
-npm run workflow:sidecar -- ensure-session \
-  --flow-id builder.build --task-slug <slug> --step-id plan \
-  [--ad-hoc-reason "planning a directly-issued work item; no pull-work artifact"]
-```
+## Workflow Entry
 
-When `--step-id` names a step other than the flow's first step, `ensure-session` records
-`ad_hoc_entry: true` + `ad_hoc_reason` in `current.json`. This is the sanctioned way to
-enter a flow mid-stream: the explicit marker lets `stop-goal-fit` / `gate-review`
-distinguish an intentional direct entry from a stale or mis-stamped `active_step_id`,
-instead of silently defaulting to the first step and looking like a normal `pull-work`
-start.
+Do not create or restamp a `builder.build` run from this planning primitive. A Builder
+run enters through `pull-work`, then `design-probe`; Flow advances it to `plan` only after
+the declared upstream gates pass. When `plan-work` is invoked directly outside that
+product workflow, run it as a standalone primitive without `--flow-id builder.build` and
+do not report the omitted Builder prefix as complete.

package/kits/builder/skills/pull-work/SKILL.md

@@ -96,6 +96,8 @@ Use `github-cli` / `gh` when available to inspect issues, labels, milestones, pr
 
 Treat GitHub Issues as a `WorkItemProvider` and GitHub Projects as a `BoardProvider`, mapped through `context/contracts/work-item-contract.md`. Preserve provider-specific values in the artifact when useful, but use the contract's neutral fields for selection, grouping, and handoff.
 
+When a `BoardProvider` is configured, read the board Ready queue as the primary cross-repo selection input, ordered by configured priority and board position. Per-repo `WorkItemProvider` issue listing is the intake-gap detector: use it to surface open issues missing from the board, not as a silent fallback when the board has no ready items. If the configured board returns zero ready items, record and surface that warning as a dead readiness source before selecting or asking for alignment.
+
 Classify issues:
 
 - ready
@@ -115,6 +117,15 @@ npm run pull-work-provider -- \
 
 The helper preserves provider refs, project fields, blockers, PR links, and source artifact refs, then emits the work item contract fields plus readiness evidence. Use live provider state for final decisions; fixture output is only test evidence.
 
+When board state is available, read the Ready queue and intake gaps through the same helper:
+
+```bash
+npm run pull-work-provider -- \
+  --settings-json context/settings/backlog-provider-settings.json
+```
+
+For fixture-backed evaluation or cached provider JSON, pass `--items-json /path/to/project-items-and-open-issues.json`. The board output includes `ready_queue`, `intake_gaps`, and `warnings`; select from `ready_queue` first when it is populated.
+
 Before classifying provider-backed work as ready for pickup, fetch the latest target ref when network access and provider credentials are available, then compare the current target SHA to the work item's `planned_base_sha`. Record the current target ref/SHA, planned base ref/SHA, `commits-since`, planned age, changed files since the planned base, and changed-file intersections with `planning_scope_refs` in the pull-work artifact or helper output.
 
 Classify revision freshness as:
@@ -458,6 +469,14 @@ After a merge, automatic continuation may inspect the queue and write a new pull
 
 When the Pickup Gate passes and work is selected (not just a shepherding scan or WIP-only audit), record the gate claim for the Builder Kit `pull-work` step before handing off to `design-probe` or `plan-work`. This satisfies the `builder.pull-work.selected` gate expectation.
 
+Start the canonical Flow run before recording the first gate claim. This is idempotent for an existing run and projects Flow's current step and gate requirements into the sidecar:
+
+```bash
+flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
+```
+
+Do not start at a later step. Flow owns advancement from `pull-work` after it evaluates the recorded evidence.
+
 Use the `selected_item_ids` as the evidence artifact ref and confirm that scope and acceptance criteria are present in the pull-work artifact:
 
 ```bash
@@ -468,6 +487,8 @@ npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with selected_item_ids, scope, and acceptance criteria."}'
 ```
 
+The sidecar writer synchronizes an existing canonical Flow run after writing the trust bundle. If synchronization was interrupted, recover with the exact `next_action.command` from `state.json`; do not edit Flow state or restamp the active step.
+
 Use `--status fail` when the gate fails (blocker recorded but no selection made). Use `--status not_verified` only when the session has no active flow step (non-Builder-Kit usage).
 
 Record `--status fail` with a summary naming the blocker when stopping before selection. Do not record `pass` until `selected_item_ids` are confirmed and the pickup gate criteria above are met.

package/kits/builder/skills/release-readiness/SKILL.md

@@ -58,6 +58,18 @@ Use additional `--gate-json` and `--post-deploy-json` values for release, deploy
 
 After writing `release.json`, run artifact validation when available. If `record-release` is unavailable or blocked, keep the release decision as `HOLD` in the Markdown artifact and record the sidecar-write or validation blocker as a `NOT_VERIFIED` evidence gap until the structured release record can be written or the gap is explicitly accepted.
 
+For an active Builder Flow run, record the CI merge-readiness claim only for a `MERGE`, `RELEASE`, or `DEPLOY` decision backed by current provider checks:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+  --expectation ci-merge-readiness \
+  --status pass \
+  --summary "Provider checks are current and passing; release-readiness decision and residual risks are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/release.json","summary":"Release-readiness decision with provider checks, rollback, and observability evidence."}'
+```
+
+Use `fail` or `not_verified` for `HOLD` and unresolved provider evidence. Flow owns the transition to learning after it verifies this claim.
+
 ## Workflow
 
 ### 1. Confirm Evidence

package/kits/knowledge/kit.json

@@ -4,6 +4,7 @@
   "name": "Knowledge Kit",
   "product_name": "Knowledge Kit",
   "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules — plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
+  "first_party": true,
   "flows": [
     {
       "id": "knowledge.store-contract",
@@ -66,6 +67,14 @@
       "description": "Knowledge promote sub-flow (issue #313, the codebase-facing 'flow within a flow'): ingest a delivered session's artifacts -> distill schema-valid DRAFT decision/vocabulary/learning deltas per the decision-registry contract -> link provenance (PR, merge SHA, session archive, touched topics) -> health-check the registry for contradictions (overlapping subject nouns + divergent content) and propose merge-repair. Invokable standalone AND composable from the Builder promote step via uses_flow. PROPOSALS-ONLY: outputs land under <session>/proposals/ for the promote step to apply; the sub-flow never writes docs directly. Executable logic: promote/index.js."
     }
   ],
+  "workflow_triggers": [
+    {
+      "id": "knowledge-capture-work",
+      "when": "knowledge-capture-detected",
+      "target_flow_id": "knowledge.ingest",
+      "default_skill": "knowledge.knowledge-capture"
+    }
+  ],
   "docs": [
     {
       "id": "knowledge.readme",

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

@@ -19,6 +19,7 @@ only projects Veritas's own recorded verdict into the Flow trust.bundle vocabula
 | 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
@@ -91,6 +92,31 @@ replacement of it):
 }
 ```
 
+## 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
@@ -140,14 +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. 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.
+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-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/kit.json

@@ -15,6 +15,20 @@
       "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": [
     { "id": "veritas-governance.readme", "path": "docs/README.md" }
   ]