@kontourai/flow-agents 3.2.0 → 3.4.0

package/kits/veritas-governance/skills/exemption-usage-review/review-exemptions.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// review-exemptions.mjs — Veritas Governance Kit exemption-usage-review helper (ADR 0022 §3).
+//
+// PURPOSE. A periodic audit tool that lists every standing `delivery/DECLARED` exemption
+// (scope, reason, approver, age since declared_at) and flags stale/overdue entries against a
+// configurable threshold, for owner re-confirmation. This is PROCESS VISIBILITY, not
+// enforcement: it is read-only, writes nothing outside its own stdout/report output, and its
+// own findings never feed back into `scripts/ci/trust-reconcile.js`'s exit code or into
+// `delivery/DECLARED` itself. See ADR 0022 §3: "a periodic audit skill/flow that walks
+// delivery/DECLARED history (git log --follow -- delivery/DECLARED) merged in a review window
+// and surfaces every standing exemption (scope, reason, approver, age) for owner
+// re-confirmation — process visibility, not enforcement."
+//
+// WHAT THIS DOES VERIFY:
+//   - Every entry currently present in the live `delivery/DECLARED` JSON array/object is
+//     listed with its `scope`, `reason`, `approved_by`, `declared_at`, computed `age_days`,
+//     and a `stale` boolean (age_days > --stale-days).
+//   - The `git log --follow -- delivery/DECLARED` commit history for the file (within
+//     --window-days when given, else full history) is walked and reported as
+//     `history_commits` (sha, author, date, subject) — this is a supplementary "how did this
+//     file change over time" view, separate from the "what's standing today" listing.
+//
+// WHAT THIS DOES NOT VERIFY (state plainly, per this kit's honesty convention):
+//   - It does NOT verify that any `approved_by` value corresponds to a real, authenticated
+//     human approver — that field is free text in `delivery/DECLARED` itself (see
+//     docs/README.md "Human-approval evidence: what is and is not enforced"); this tool only
+//     reports what the field says, never authenticates it.
+//   - It does NOT re-evaluate whether a scope's `ref:`/`commit:`/`author:`/`branch-prefix:`
+//     condition currently matches any particular change — that is
+//     `scripts/ci/trust-reconcile.js`'s `matchesScope`/`matchesScopeCondition` job (a
+//     "does this exemption apply to THIS change" question). This tool answers a different
+//     question — "what exemptions are standing at all, and how old are they" — for every
+//     entry, regardless of whether any given entry's scope currently matches anything.
+//   - It does NOT reconstruct a full point-in-time list of entries that existed at each
+//     historical commit and diff them against each other (e.g. it does not detect "entry X
+//     was removed then silently re-added with a different reason") — `history_commits` gives
+//     the commit-level trail (who changed the file, when) for a human reviewer to inspect
+//     with `git show <sha>:delivery/DECLARED` themselves; this tool does not do that
+//     per-commit content diffing itself.
+//   - It does NOT mutate `delivery/DECLARED`, does not attach evidence, does not run a Flow
+//     gate, and has no exit-code-driven pass/fail: this script's own process exit code is 0
+//     on any clean parse, regardless of how many entries are flagged stale — staleness is
+//     informational output, not a script failure condition.
+//
+// NO-FORK NOTE: this script intentionally does NOT reuse trust-reconcile.js's
+// `matchesScope`/`matchesScopeCondition`/`parseDeclaredMarker` functions. The review lists ALL
+// entries unconditionally (it has no "does this scope match the current context" question to
+// answer), so it needs only a much simpler "parse the JSON array, compute age" routine, not
+// the reconciler's scope-matching engine. This is a deliberate scope difference, not a missed
+// reuse opportunity — see SKILL.md.
+//
+// Usage:
+//   node review-exemptions.mjs [--declared-path <path>] [--repo-root <path>]
+//     [--stale-days <n>] [--window-days <n>] [--as-of <ISO8601>] [--json]
+//
+// Exit: 0 on a clean run (parse succeeded, report printed) — even when entries are flagged
+// stale. Exit 2 on bad args. Exit 3 when delivery/DECLARED is missing or not valid JSON
+// (nothing to review — this is a tool-usage failure, not a staleness finding).
+
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const DEFAULT_STALE_DAYS = 90;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function parseArgs(argv) {
+  const out = {
+    declaredPath: undefined,
+    repoRoot: process.cwd(),
+    staleDays: DEFAULT_STALE_DAYS,
+    windowDays: undefined,
+    asOf: undefined,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--declared-path") out.declaredPath = argv[++i];
+    else if (a === "--repo-root") out.repoRoot = argv[++i];
+    else if (a === "--stale-days") out.staleDays = Number(argv[++i]);
+    else if (a === "--window-days") out.windowDays = Number(argv[++i]);
+    else if (a === "--as-of") out.asOf = argv[++i];
+    else if (a === "--json") out.json = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+function usage() {
+  return "usage: review-exemptions.mjs [--declared-path <path>] [--repo-root <path>] "
+    + "[--stale-days <n>] [--window-days <n>] [--as-of <ISO8601>] [--json]\n";
+}
+
+/**
+ * Read and parse the live delivery/DECLARED file into a flat array of raw entries.
+ * Mirrors trust-reconcile.js's tolerant single-object-or-array shape (a single {scope,...}
+ * object OR a JSON array of such objects) WITHOUT reusing its parseDeclaredMarker() function
+ * (see NO-FORK NOTE above) — this parse is deliberately simpler: no well-formed/malformed
+ * bucketing, no scope-matching, just "read the array, keep what looks like an entry object".
+ */
+export function readDeclaredEntries(declaredPath) {
+  const raw = readFileSync(declaredPath, "utf8");
+  const parsed = JSON.parse(raw);
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+  return entries.filter((e) => e && typeof e === "object");
+}
+
+/** Age in whole days between an ISO8601 `declared_at` and an ISO8601 `asOfIso` "now". */
+export function ageDays(declaredAtIso, asOfIso) {
+  const declared = new Date(declaredAtIso).getTime();
+  const asOf = new Date(asOfIso).getTime();
+  if (Number.isNaN(declared) || Number.isNaN(asOf)) return null;
+  return Math.floor((asOf - declared) / MS_PER_DAY);
+}
+
+/**
+ * Build the standing-exemption report rows: one row per delivery/DECLARED entry, with
+ * computed age_days and a stale boolean (age_days > staleDays). Entries with an unparsable
+ * declared_at get age_days: null, stale: null (never silently coerced to fresh or stale).
+ */
+export function buildReport(entries, { staleDays, asOfIso }) {
+  return entries.map((entry) => {
+    const declaredAt = typeof entry.declared_at === "string" ? entry.declared_at : null;
+    const age = declaredAt ? ageDays(declaredAt, asOfIso) : null;
+    return {
+      scope: typeof entry.scope === "string" ? entry.scope : null,
+      reason: typeof entry.reason === "string" ? entry.reason : null,
+      approved_by: typeof entry.approved_by === "string" ? entry.approved_by : null,
+      declared_at: declaredAt,
+      age_days: age,
+      stale: age === null ? null : age > staleDays,
+    };
+  });
+}
+
+/**
+ * Walk `git log --follow -- <declaredRelPath>` history for delivery/DECLARED, optionally
+ * bounded to a review window (--window-days before asOfIso). Read-only (`git log`, no
+ * mutation). Never throws — a git failure (no repo, no history, shallow clone) degrades to
+ * an empty list plus a diagnostic note, never a crash.
+ */
+export function walkDeclaredHistory(repoRoot, declaredRelPath, { windowDays, asOfIso }) {
+  const args = ["log", "--follow", "--date=iso-strict", "--format=%H%x1f%an%x1f%ad%x1f%s"];
+  if (windowDays && Number.isFinite(windowDays) && windowDays > 0) {
+    const since = new Date(new Date(asOfIso).getTime() - windowDays * MS_PER_DAY).toISOString();
+    args.push(`--since=${since}`);
+  }
+  args.push("--", declaredRelPath);
+  try {
+    const res = spawnSync("git", args, { cwd: repoRoot, encoding: "utf8" });
+    if (!res || res.error || res.status !== 0) {
+      return { commits: [], diagnostic: "git log --follow unavailable or failed; history_commits is empty (no historical trail could be walked)" };
+    }
+    const lines = res.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+    const commits = lines.map((line) => {
+      const [sha, author, date, subject] = line.split("\x1f");
+      return { sha, author, date, subject };
+    });
+    return { commits, diagnostic: null };
+  } catch (err) {
+    return { commits: [], diagnostic: `git log --follow threw: ${err && err.message ? err.message : String(err)}` };
+  }
+}
+
+function renderHuman(report, history, opts) {
+  const lines = [];
+  lines.push(`Exemption usage review — as-of ${opts.asOfIso}, stale threshold ${opts.staleDays} day(s)`);
+  lines.push(`PROCESS-ONLY: read-only report. Does not modify delivery/DECLARED or scripts/ci/trust-reconcile.js's behavior.`);
+  lines.push("");
+  lines.push(`Standing exemptions (${report.length}):`);
+  if (report.length === 0) lines.push("  (none)");
+  for (const row of report) {
+    const staleTag = row.stale === null ? "UNKNOWN-AGE" : row.stale ? "STALE — needs owner re-confirmation" : "fresh";
+    lines.push(`  - scope: ${row.scope ?? "(missing)"}`);
+    lines.push(`    reason: ${row.reason ?? "(missing)"}`);
+    lines.push(`    approved_by: ${row.approved_by ?? "(missing)"}`);
+    lines.push(`    declared_at: ${row.declared_at ?? "(missing)"} | age_days: ${row.age_days ?? "n/a"} | ${staleTag}`);
+  }
+  lines.push("");
+  lines.push(`History (git log --follow -- delivery/DECLARED)${opts.windowDays ? ` — last ${opts.windowDays} day(s)` : " — full history"}:`);
+  if (history.diagnostic) lines.push(`  NOTE: ${history.diagnostic}`);
+  if (history.commits.length === 0 && !history.diagnostic) lines.push("  (no commits found)");
+  for (const c of history.commits) {
+    lines.push(`  - ${c.sha.slice(0, 12)} ${c.date} ${c.author} — ${c.subject}`);
+  }
+  return lines.join("\n");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(usage());
+    return 0;
+  }
+  const repoRoot = path.resolve(args.repoRoot);
+  const declaredPath = args.declaredPath
+    ? path.resolve(args.declaredPath)
+    : path.join(repoRoot, "delivery", "DECLARED");
+  const staleDays = Number.isFinite(args.staleDays) ? args.staleDays : DEFAULT_STALE_DAYS;
+  const asOfIso = args.asOf || new Date().toISOString();
+
+  let entries;
+  try {
+    entries = readDeclaredEntries(declaredPath);
+  } catch (err) {
+    process.stderr.write(`cannot read/parse delivery/DECLARED at ${declaredPath}: ${err && err.message ? err.message : String(err)}\n`);
+    return 3;
+  }
+
+  const report = buildReport(entries, { staleDays, asOfIso });
+  const declaredRelPath = path.relative(repoRoot, declaredPath) || "delivery/DECLARED";
+  const history = walkDeclaredHistory(repoRoot, declaredRelPath, { windowDays: args.windowDays, asOfIso });
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({
+      as_of: asOfIso,
+      stale_days: staleDays,
+      window_days: args.windowDays ?? null,
+      declared_path: declaredPath,
+      entries: report,
+      history_commits: history.commits,
+      history_diagnostic: history.diagnostic,
+    }, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${renderHuman(report, history, { asOfIso, staleDays, windowDays: args.windowDays })}\n`);
+  }
+  return 0;
+}
+
+const isEntry = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (isEntry) process.exitCode = main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -149,7 +149,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^2.0.0"
+    "@kontourai/flow": "^3.0.0"
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",

package/packaging/manifest.json

@@ -56,6 +56,13 @@
     "excluded_agents": [
       "dev"
     ],
+    "allowed_agent_models": [
+      "gpt-5.3-codex-spark",
+      "gpt-5.4-mini",
+      "gpt-5.5",
+      "gpt-5.6-sol",
+      "gpt-5.6-terra"
+    ],
     "profiles": {
       "builder": {
         "model": "gpt-5.5",
@@ -114,6 +121,28 @@
     "agi-nova-beta-1m": "medium",
     "default": "medium"
   },
+  "codex_agent_map": {
+    "tool-planner": {
+      "model": "gpt-5.6-sol",
+      "reasoning_effort": "high"
+    },
+    "tool-worker": {
+      "model": "gpt-5.6-terra",
+      "reasoning_effort": "high"
+    },
+    "tool-code-reviewer": {
+      "model": "gpt-5.6-sol",
+      "reasoning_effort": "high"
+    },
+    "tool-security-reviewer": {
+      "model": "gpt-5.6-sol",
+      "reasoning_effort": "high"
+    },
+    "tool-verifier": {
+      "model": "gpt-5.6-sol",
+      "reasoning_effort": "high"
+    }
+  },
   "target_substitutions": {
     "common": [],
     "claude_code": [

package/schemas/backlog-provider-settings.schema.json

@@ -8,6 +8,7 @@
   "properties": {
     "$schema": { "type": "string" },
     "schema_version": { "const": "1.0" },
+    "workspace": { "$ref": "#/$defs/workspace" },
     "defaults": { "$ref": "#/$defs/backlog_settings" },
     "projects": {
       "type": "array",
@@ -22,6 +23,18 @@
         { "type": "object", "required": ["project"] }
       ]
     },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repos"],
+      "properties": {
+        "repos": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
     "backlog_settings": {
       "type": "object",
       "additionalProperties": false,

package/schemas/workflow-state.schema.json

@@ -59,6 +59,36 @@
       },
       "uniqueItems": true
     },
+    "work_item_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Provider-neutral work item references anchoring this workflow session."
+    },
+    "flow_run": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id", "definition_id", "definition_version", "status", "current_step", "run_ref", "open_gate_ids"],
+      "properties": {
+        "run_id": { "type": "string", "minLength": 1 },
+        "definition_id": { "type": "string", "minLength": 1 },
+        "definition_version": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "current_step": { "type": "string", "minLength": 1 },
+        "run_ref": { "type": "string", "minLength": 1 },
+        "open_gate_ids": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "route_back_attempt": { "type": "integer", "minimum": 1 },
+        "route_back_max_attempts": { "type": "integer", "minimum": 1 }
+      }
+    },
     "next_action": {
       "type": "object",
       "additionalProperties": false,
@@ -78,6 +108,20 @@
         },
         "target_artifact": {
           "type": "string"
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "operations": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1
         }
       }
     }

package/scripts/README.md

@@ -69,9 +69,11 @@ renamed, or changes category, update the table and the validator together.
 | `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
 | `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Shared runtime-agnostic actor identity resolver (`resolveActor`) consumed by `workflow-steering.js` and `workflow-sidecar.js` to retire the shared `"local"` liveness-actor default (issue #287). |
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
+| `lib/codex-exit-code.js` | shared hook library | `evals/acceptance/prove-capture-teeth.sh` | Shared codex-only host-banner exit-code extraction (`extractExitCodeFromBanner`, `readExitCodeFromRollout`) — parses the `Process exited with code N` prose the codex CLI writes into a `function_call_output` payload or session rollout so `codex-hook-adapter.js` can inject a structured exit code before `evidence-capture.js` observes (issue #470). |
 | `lib/config-protection-remedies.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Sanctioned-remedy table for `config-protection.js` (WS8/ADR 0020 extraction). |
 | `lib/current-pointer.js` | shared hook library | `evals/integration/test_current_json_per_actor.sh` | Shared per-actor "current" pointer reader/writer (`readCurrentPointer`, `writePerActorCurrent`) — the compat-shim fallback (per-actor `current/<actor>.json` first, legacy global `current.json` fallback) every actor-aware consumer routes through (issue #291). |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
+| `lib/kit-catalog.js` | shared hook library | `evals/integration/test_workflow_steering_hook.sh` | Build-free kit catalog reader used by `workflow-steering.js` to load kit-declared workflow triggers while hooks remain fail-open and independent of compiled TypeScript output. |
 | `lib/liveness-heartbeat.js` | shared hook library | `evals/integration/test_liveness_heartbeat.sh` | Shared tool-activity liveness heartbeat (`maybeEmitHeartbeat`); rides `postToolUse` across all four telemetry hook wrappers, throttled and fail-open (issue #288). |
 | `lib/liveness-policy.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness on/off predicate (`isLivenessEnabled`, default-on/opt-out) and TTL/heartbeat-throttle default resolution (issue #288). |
 | `lib/liveness-read.js` | shared hook library | `evals/integration/test_session_resume_roundtrip.sh` | Shared liveness event reader + freshness check (`readLivenessEvents`, `freshHolders`); consumed by the reground hook and `workflow-sidecar liveness status`. |
@@ -79,6 +81,8 @@ renamed, or changes category, update the table and the validator together.
 | `lib/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers for CJS hooks. |
 | `lib/patterns.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared shell pattern constants. |
 | `lib/resolve-formatter.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared formatter resolution helper. |
+| `lib/runnable-command.js` | shared hook library | `evals/integration/test_goal_fit_hook.sh` | Shared runnable-command-text heuristic (`isRunnableCommandText`) consumed by `stop-goal-fit.js` and `workflow-sidecar.js` so record-time and Stop-time checks never drift (issue #412). |
+| `lib/skill-drift.js` | shared hook library | `evals/integration/test_skill_drift_check.sh` | Shared installed-Claude-Code-skill manifest builder and drift classifier (`buildManifest`, `compareSkillDrift`) — the single choke point the `init --global` manifest writer, the `flow-agents skill-drift-check` CLI, and the SessionStart advisory all route through so they never disagree on drift classification (issue #439). |
 
 ## Telemetry
 

package/scripts/check-content-boundary.cjs

@@ -37,6 +37,11 @@ function trackedFiles() {
   return output.split("\0").filter(Boolean);
 }
 
+function untrackedFiles() {
+  const output = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], { encoding: "utf8" });
+  return output.split("\0").filter(Boolean);
+}
+
 function isIgnoredPath(filePath) {
   return filePath === SELF || ignoredPathPatterns.some((pattern) => pattern.test(filePath));
 }
@@ -51,7 +56,9 @@ function lineNumberFor(content, index) {
 
 const findings = [];
 
-for (const filePath of trackedFiles()) {
+const allFiles = new Set([...trackedFiles(), ...untrackedFiles()]);
+
+for (const filePath of allFiles) {
   if (isWorkflowRuntimeArtifact(filePath)) {
     findings.push({
       filePath,