@kontourai/flow-agents 2.2.0 → 2.4.0

package/kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// readiness-to-trust-bundle.mjs — Veritas Governance Kit adapter (slice 1).
+//
+// PURPOSE (the "trust-bundle format gap" fix, kept in the KIT adapter layer — NOT in
+// @kontourai/veritas). `veritas readiness --check evidence --working-tree` writes a legacy
+// evidence-report record (`.kontourai/veritas/evidence/veritas-<runId>.json`). The Flow gate
+// in flows/readiness-check.flow.json expects `kind: "trust.bundle"` — a Hachure trust.bundle
+// carrying a `software-readiness-verdict` claim whose Surface-derived status the gate checks.
+// This adapter projects Veritas's own recorded readiness record into that trust.bundle using
+// @kontourai/surface (the same open-format bundle vocabulary Flow Agents' own delivery bundle
+// and kits/builder/flows/build.flow.json use). It does NOT re-evaluate Repo Standards — Veritas
+// already did that; the adapter only reads Veritas's recorded per-check results and aggregates
+// the blocking-failure signal, so no Veritas rule/claim logic is forked or reimplemented.
+//
+// BLOCKING-FAILURE definition (SETTLED — owner-ratified + investigation-confirmed, see
+// .kontourai/flow-agents/ws5-governance-kit-slice1 session findings). This adapter derives the
+// readiness gate verdict from the readiness record's blocking failures: a Require-enforcement
+// policy failure, an uncovered-path `fail`, a failed selected evidence check, or a blocking
+// external-tool `fail`/`missing` (mirrors veritas/src/surface/readiness.mjs's own PRIVATE
+// `readinessHasBlockingFailure` helper, and matches Surface's `buildTrustReport` weakest-link
+// derivation, which downgrades a readiness claim to `rejected` on any rejected Require —
+// tests/surface/readiness-derived-claim.test.mjs:256-278). It intentionally does NOT apply
+// Veritas's EXPORTED `promotion_allowed` short-circuit (readinessSurfaceStatus/readinessVerdict
+// treat promotion_allowed===true as verified/ready regardless of blocking Require failures):
+// promotion_allowed is a workstream-routing hint from src/repo/routing.mjs `resolveWorkstream()`
+// (file-pattern lane resolution), not a safety signal — it never reads policy_results, evidence
+// checks, uncovered paths, or external tools, so it cannot account for blocking failures. This is
+// a filed Veritas bug, not a legitimate alternate reading: kontourai/veritas#106
+// (https://github.com/kontourai/veritas/issues/106) — "promotion_allowed short-circuit bypasses
+// blocking Require failures" — recommends veritas fix readiness.mjs to check
+// readinessHasBlockingFailure() before the promotion_allowed short-circuit. Conclusion: the
+// adapter's stricter derivation is correct today and will agree with veritas's own exported
+// functions once #106 lands; it is not a fork of Veritas's intended semantics, and the
+// Governance Kit's blocking-failure semantics are the successor the wider system is moving
+// toward (this adapter's independent CLI wrap was for reversibility while that landed). Ready
+// (no blocking failure) -> Surface derives `verified` -> gate passes. Not-ready -> Surface
+// derives a non-`verified` status -> gate blocks.
+//
+// Usage: node readiness-to-trust-bundle.mjs --report <veritas-evidence-report.json> \
+//          --out <bundle.json> [--subject-id <id>]
+// Exit: 0 on success (bundle written), 2 on bad args, 3 on unreadable/invalid report.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import * as surface from "@kontourai/surface";
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--report") out.report = argv[++i];
+    else if (a === "--out") out.out = argv[++i];
+    else if (a === "--subject-id") out.subjectId = argv[++i];
+  }
+  return out;
+}
+
+// Mirrors veritas/src/surface/readiness.mjs's PRIVATE readinessHasBlockingFailure — reads
+// Veritas's OWN recorded results; does not evaluate standards. Does NOT apply promotion_allowed
+// (see header comment above): that short-circuit is a filed veritas bug (kontourai/veritas#106),
+// not a safety signal — this stricter derivation is the settled-correct semantics.
+export function hasBlockingFailure(record) {
+  if (record.uncovered_path_result === "fail") return true;
+  if ((record.policy_results ?? []).some((r) => r.passed === false && r.enforcementLevel === "Require")) return true;
+  if ((record.selected_evidence_checks ?? []).some((c) => c.evidence_check_result?.passed === false)) return true;
+  if ((record.external_tool_results ?? []).some((r) => r.blocking !== false && ["fail", "missing"].includes(r.verdict))) return true;
+  return false;
+}
+
+export function buildReadinessTrustBundle(record, opts = {}) {
+  const { deriveClaimStatus, generateClaimId } = surface;
+  const ts = record.timestamp || new Date().toISOString();
+  const runId = record.run_id || "veritas-run";
+  const sourceRef = record.integrity?.sourceRef ?? record.source_ref ?? runId;
+  const subjectId = opts.subjectId || sourceRef;
+  const blocking = hasBlockingFailure(record);
+  const ready = !blocking;
+
+  const claimType = "software-readiness-verdict";
+  const surfaceName = "veritas.readiness";
+  const claimId = generateClaimId(subjectId, surfaceName, "mergeReadiness");
+  const evId = `ev:${claimId}`;
+  const evidenceType = "policy_rule"; // readiness is a governance/policy result (auditability)
+
+  const policy = {
+    id: `policy:${claimType}`,
+    claimType,
+    requiredEvidence: [evidenceType],
+    acceptanceCriteria: ["A verified Veritas readiness evidence event supports the readiness verdict."],
+    reviewAuthority: "system",
+    validityRule: { kind: "manual" },
+    stalenessTriggers: [],
+    conflictRules: [],
+    impactLevel: "high",
+  };
+
+  const failedRules = (record.policy_results ?? [])
+    .filter((r) => r.passed === false && r.enforcementLevel === "Require")
+    .map((r) => r.rule_id);
+  const failedChecks = (record.selected_evidence_checks ?? [])
+    .filter((c) => c.evidence_check_result?.passed === false)
+    .map((c) => c.id);
+  const summary = ready
+    ? `Veritas readiness verdict is ready (run ${runId}); no blocking requirements or evidence failed.`
+    : `Veritas readiness verdict is not ready (run ${runId}). Blocking: ${[...failedRules, ...failedChecks].join(", ") || record.uncovered_path_result}.`;
+
+  const evItem = {
+    id: evId,
+    claimId,
+    evidenceType,
+    method: "auditability",
+    sourceRef: `veritas:readiness:${runId}`,
+    excerptOrSummary: summary,
+    observedAt: ts,
+    collectedBy: "veritas-governance-kit/readiness-adapter",
+    passing: ready,
+  };
+  const evt = {
+    id: `evt:${claimId}`,
+    claimId,
+    status: ready ? "verified" : "disputed",
+    actor: "veritas-governance-kit/readiness-adapter",
+    method: "auditability",
+    evidenceIds: [evId],
+    createdAt: ts,
+    verifiedAt: ts,
+  };
+  const claim = {
+    id: claimId,
+    subjectType: "repository-change",
+    subjectId,
+    facet: surfaceName,
+    claimType,
+    fieldOrBehavior: "mergeReadiness",
+    value: { verdict: ready ? "ready" : "not-ready", sourceRef, blocking: { failedRequirements: failedRules, failedEvidenceChecks: failedChecks } },
+    createdAt: ts,
+    updatedAt: ts,
+    impactLevel: "high",
+    verificationPolicyId: policy.id,
+    currentIntegrityRef: sourceRef,
+    metadata: { producer: "veritas", source: "readiness", runId },
+  };
+  const { status } = deriveClaimStatus({ claim, evidence: [evItem], events: [evt], policies: [policy] });
+
+  return {
+    bundle: {
+      schemaVersion: 5,
+      source: "veritas-governance-kit/readiness-adapter",
+      claims: [{ ...claim, status }],
+      evidence: [evItem],
+      events: [evt],
+      policies: [policy],
+    },
+    verdict: ready ? "ready" : "not-ready",
+    derivedStatus: status,
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.report || !args.out) {
+    process.stderr.write("usage: readiness-to-trust-bundle.mjs --report <veritas-evidence-report.json> --out <bundle.json> [--subject-id <id>]\n");
+    return 2;
+  }
+  let record;
+  try {
+    record = JSON.parse(readFileSync(args.report, "utf8"));
+  } catch (err) {
+    process.stderr.write(`cannot read Veritas evidence report: ${err && err.message ? err.message : String(err)}\n`);
+    return 3;
+  }
+  const { bundle, verdict, derivedStatus } = buildReadinessTrustBundle(record, { subjectId: args.subjectId });
+  writeFileSync(args.out, `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
+  process.stdout.write(`readiness verdict: ${verdict}; software-readiness-verdict claim status: ${derivedStatus}; bundle: ${args.out}\n`);
+  return 0;
+}
+
+const isEntry = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isEntry) process.exitCode = main();

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

@@ -0,0 +1,75 @@
+# 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.
+
+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
+reimplement Veritas's Repo Standards / evidence-check evaluation — Veritas evaluates; the kit
+only projects Veritas's own recorded verdict into the Flow trust.bundle vocabulary.
+
+## What it contains
+
+| Asset | Path | Purpose |
+| --- | --- | --- |
+| 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. |
+
+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
+satisfies it. `claimType: "software-readiness-verdict"` is taken directly from Veritas's own
+Surface projection (`veritas/src/surface/projected-claims.mjs`, surface `veritas.readiness`).
+
+## How to run the gate
+
+```bash
+# 1. Produce a real Veritas readiness report for your change.
+veritas readiness --check evidence --working-tree
+#    -> writes .kontourai/veritas/evidence/veritas-<runId>.json
+
+# 2. Project that report into a trust.bundle.
+node kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs \
+  --report .kontourai/veritas/evidence/veritas-<runId>.json \
+  --out readiness.bundle
+
+# 3. Gate it (agentless, CI-callable — @kontourai/flow >= 1.3).
+flow init
+flow start kits/veritas-governance/flows/readiness-check.flow.json --run-id readiness
+flow attach-evidence readiness --gate gate-check-gate --file readiness.bundle --bundle
+flow evaluate readiness --gate gate-check-gate --exit-code
+#    exit 0 when readiness is ready (claim verified); exit 1 (block) otherwise.
+```
+
+## Semantics
+
+**Settled** (owner-ratified + investigation-confirmed; see
+`.kontourai/flow-agents/ws5-governance-kit-slice1` session findings). The adapter derives the
+readiness gate verdict from **blocking failures** in Veritas's own recorded results: a
+`Require`-enforcement policy failure, an uncovered-path `fail`, a failed selected evidence check,
+or a blocking external-tool `fail`/`missing` makes the verdict **not-ready** → the
+`software-readiness-verdict` claim derives a non-`verified` status → the gate **blocks**. A ready
+verdict derives `verified` → the gate **passes**.
+
+This matches Veritas's own `readinessHasBlockingFailure` helper (`veritas/src/surface/readiness.mjs`)
+and Surface's weakest-link claim derivation (`buildTrustReport` downgrades a readiness claim to
+`rejected` on any rejected Require). The adapter intentionally does **not** apply Veritas's
+`promotion_allowed` short-circuit — `promotion_allowed` is a workstream-routing hint (set by
+file-pattern lane resolution in `src/repo/routing.mjs`), not a safety signal, and applying it as
+one lets a record with blocking Require failures read as ready. That short-circuit is a filed
+Veritas bug, [kontourai/veritas#106](https://github.com/kontourai/veritas/issues/106), not a
+legitimate alternate reading. Investigation conclusion: the adapter's stricter blocking-failure
+derivation is correct today and will agree with Veritas's own exported functions once #106 lands.
+
+## 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).
+
+## Not in slice 1
+
+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.