@kontourai/flow-agents 2.3.0 → 3.0.0

package/kits/knowledge/providers/work-item/index.js

@@ -0,0 +1,204 @@
+/**
+ * work-item knowledge-store provider (source/sink adapter, not storage).
+ *
+ * Maps a GitHub issue backlog into the typed graph so backlog hygiene becomes a
+ * knowledge-health pass:
+ *   - issues                         -> `issue` nodes (state / labels / title).
+ *   - flow-agents:work-item-metadata `blockers` -> `blocks` edges.
+ *   - prose "blocked by #N"          -> `blocks` edges; other #N refs -> `relates`.
+ *
+ * Reads via an INJECTABLE runner so tests drive it from recorded fixtures and
+ * never touch the real board. Write side is proposals-only: proposeWrite renders
+ * a draft issue comment / label change for an operator to file — it never calls
+ * a mutating gh command.
+ *
+ * @module providers/work-item
+ */
+
+import { execFile } from "node:child_process";
+import { node, edge, proposal, provenance } from "../lib/model.js";
+
+const PROVIDER_ID = "work-item";
+
+/** Default runner: shells out to `gh` (read-only list). */
+function defaultRunner(args) {
+  return new Promise((resolve, reject) => {
+    execFile("gh", args, { maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(`gh ${args.join(" ")} failed: ${stderr || err.message}`));
+      resolve(stdout);
+    });
+  });
+}
+
+/** Parse the flow-agents:work-item-metadata JSON block from an issue body. */
+export function parseWorkItemMetadata(body) {
+  if (!body) return null;
+  const start = body.indexOf("flow-agents:work-item-metadata");
+  if (start === -1) return null;
+  const jsonStart = body.indexOf("{", start);
+  const end = body.indexOf("-->", jsonStart);
+  if (jsonStart === -1 || end === -1) return null;
+  try {
+    return JSON.parse(body.slice(jsonStart, end).trim());
+  } catch {
+    return null;
+  }
+}
+
+/** Extract a blocker issue number from a metadata blocker entry. */
+function blockerNumber(entry) {
+  if (typeof entry === "number") return entry;
+  if (typeof entry === "string") {
+    const m = entry.match(/#?(\d+)/);
+    return m ? Number(m[1]) : null;
+  }
+  if (entry && typeof entry === "object") {
+    if (typeof entry.number === "number") return entry.number;
+    if (typeof entry.issue === "number") return entry.issue;
+    if (typeof entry.ref === "string") {
+      const m = entry.ref.match(/#?(\d+)/);
+      return m ? Number(m[1]) : null;
+    }
+  }
+  return null;
+}
+
+export class WorkItemProvider {
+  constructor({ repo, runner, agent } = {}) {
+    this.repo = repo || "";
+    this.runner = runner || defaultRunner;
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+    this._cache = null;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["issue"],
+      edge_types: ["blocks", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["comment", "label"],
+      source_of_truth: "GitHub issues (read via gh; write = draft comments/labels)",
+    };
+  }
+
+  async _issues() {
+    if (this._cache) return this._cache;
+    const args = ["issue", "list"];
+    if (this.repo) args.push("--repo", this.repo);
+    args.push("--state", "all", "--json", "number,title,state,labels,body", "--limit", "200");
+    const out = await this.runner(args);
+    const parsed = JSON.parse(out);
+    this._cache = Array.isArray(parsed) ? parsed : [];
+    return this._cache;
+  }
+
+  async readNodes(options = {}) {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const nodes = issues.map((iss) =>
+      node({
+        id: `issue:${iss.number}`,
+        type: "issue",
+        title: iss.title || `issue #${iss.number}`,
+        body: iss.body || "",
+        attributes: {
+          number: iss.number,
+          state: iss.state || "OPEN",
+          labels: (iss.labels || []).map((l) => (typeof l === "string" ? l : l.name)),
+        },
+        provenance: provenance({
+          provider: PROVIDER_ID,
+          source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`,
+          retrievedAt: now,
+          agent: this.agent,
+        }),
+      }),
+    );
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const edges = [];
+    const seen = new Set();
+    const push = (e) => {
+      if (seen.has(e.id)) return;
+      seen.add(e.id);
+      edges.push(e);
+    };
+
+    for (const iss of issues) {
+      const self = `issue:${iss.number}`;
+      const prov = (loc) => provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`, locator: loc, retrievedAt: now, agent: this.agent });
+
+      // metadata blockers -> blocks (blocker blocks this)
+      const md = parseWorkItemMetadata(iss.body);
+      for (const b of (md && Array.isArray(md.blockers) ? md.blockers : [])) {
+        const n = blockerNumber(b);
+        if (n == null) continue;
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "metadata" }, provenance: prov("metadata.blockers") }));
+      }
+
+      const body = iss.body || "";
+      // prose "blocked by #N" / "depends on #N" -> blocks
+      for (const m of body.matchAll(/\b(?:blocked by|depends on|blocker:)\s*#(\d+)/gi)) {
+        const n = Number(m[1]);
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+      // other bare #N prose refs -> relates
+      for (const m of body.matchAll(/(?<![\w/])#(\d+)\b/g)) {
+        const n = Number(m[1]);
+        if (n === iss.number) continue;
+        const bid = `issue:${iss.number}--relates--${n}`;
+        if (seen.has(`issue:${n}--blocks--${iss.number}`)) continue; // already a stronger blocks edge
+        push(edge({ id: bid, type: "relates", from: self, to: `issue:${n}`, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+    }
+    return edges;
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Propose an issue comment or label change. Renders the draft an operator
+   * would file with gh — the provider never runs a mutating gh command.
+   */
+  async proposeWrite(intent = {}) {
+    const { issue, kind = "comment", commentBody, labels = [] } = intent;
+    if (issue == null) throw new Error("work-item proposeWrite requires intent.issue (number)");
+    if (kind === "label") {
+      return proposal({
+        provider: PROVIDER_ID,
+        kind: "label",
+        target: { repo: this.repo, issue },
+        payload: { labels },
+        rendered: `gh issue edit ${issue}${this.repo ? ` --repo ${this.repo}` : ""} ${labels.map((l) => `--add-label ${JSON.stringify(l)}`).join(" ")}`,
+        rationale: intent.rationale || "Proposed label change (draft — operator files it).",
+        provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+      });
+    }
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "comment",
+      target: { repo: this.repo, issue },
+      payload: { body: commentBody || "" },
+      rendered: `gh issue comment ${issue}${this.repo ? ` --repo ${this.repo}` : ""} --body ${JSON.stringify(commentBody || "")}`,
+      rationale: intent.rationale || "Proposed issue comment (draft — operator files it).",
+      provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+    });
+  }
+}
+
+export default WorkItemProvider;

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.