@kontourai/flow-agents 4.0.0 → 4.1.0

package/dist/base/schemas/workflow-waves.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-waves.schema.json",
+  "title": "Flow Agents Workflow Waves",
+  "description": "Fan-out wave manifest for a workflow session. Each wave declares its expected workers (M) before dispatch; every worker lands exactly one terminal status record; the orchestrator reconciles worker_results against expected_workers at wave close and records an explicit 'N of M reported' reconciliation. A worker that never reported is recorded as not_reported — visible data, never silently absorbed. This sidecar is additive: a session without waves.json declares no fan-out and is unaffected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "waves"
+  ],
+  "$defs": {
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "source",
+            "command",
+            "artifact",
+            "provider",
+            "external"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "source"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "file",
+              "line_start",
+              "line_end",
+              "excerpt"
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "artifact"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "file"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "url"
+                    ]
+                  }
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "summary"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "excerpt"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "command"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "excerpt"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "summary"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "url"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "enum": [
+                  "provider",
+                  "external"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        }
+      ]
+    },
+    "expected_worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "task"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owned_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "worker_result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "status",
+        "summary",
+        "recorded_at"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "completed",
+            "failed",
+            "blocked",
+            "not_reported"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recorded_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence_ref"
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "expected_count",
+        "reported_count",
+        "summary",
+        "reconciled_at"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "expected_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reported_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reconciled_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "wave": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "wave_id",
+        "step",
+        "declared_at",
+        "expected_workers"
+      ],
+      "properties": {
+        "wave_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "step": {
+          "type": "string",
+          "minLength": 1
+        },
+        "declared_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expected_workers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/expected_worker"
+          }
+        },
+        "worker_results": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/worker_result"
+          }
+        },
+        "reconciliation": {
+          "$ref": "#/$defs/reconciliation"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/wave"
+      }
+    }
+  }
+}

package/dist/base/scripts/check-layer-boundary.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * check-layer-boundary — kit/engine layer-doctrine ratchet.
+ *
+ * Doctrine (veritas docs/architecture/engine-surface-seam.md, Invariant 3; ADR 0008/0016):
+ * kits distribute by copy/activate/CLI and consume a product engine via CLI + artifacts, NEVER
+ * as an npm library import. A kit that `import`s the veritas evaluation engine would fork the
+ * layer boundary — the kit must wrap the engine's CLI, not link its code. This is the executable
+ * enforcement of that invariant (flow-agents#651).
+ *
+ * FAILS if any tracked file under kits/ imports `@kontourai/veritas` (or its `/engine` subpath),
+ * or if any kit.json declares it as a dependency. The kit's trust-bundle adapter may import
+ * `@kontourai/surface` (the open trust format, Layer 3) — that is the sanctioned channel and is
+ * NOT matched here. No allowlist: the count is zero today and must stay zero.
+ *
+ * Not a violation (and not matched — import-syntax-scoped): the many descriptive strings naming
+ * "@kontourai/veritas" in kit.json descriptions, docs, and recorded CLI-output fixtures are prose
+ * and data, not code imports.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// Match import/require/dynamic-import of the veritas package (root or /engine subpath) only, so
+// prose/fixture mentions of the package name can never trip it — only an actual code link does.
+const PKG = String.raw`@kontourai/veritas(?:/[A-Za-z0-9_./-]+)?`;
+const IMPORT_PATTERNS = [
+  new RegExp(String.raw`from\s+['"](?:${PKG})['"]`),
+  new RegExp(String.raw`require(?:\.resolve)?\(\s*['"](?:${PKG})['"]\s*\)`),
+  new RegExp(String.raw`import\(\s*['"](?:${PKG})['"]\s*\)`),
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+// Strip comments so an import-SHAPED example inside a doc comment (e.g. a JSDoc `* import ...`
+// line) is not a false positive. A real import statement never starts a line with `//` or `*`,
+// so this only removes prose, never a genuine dependency edge. (Line-scoped — not a full parser;
+// a package name inside a string literal remains matchable, which is intentional.)
+function codeOnly(line) {
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) return "";
+  return line.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*$/, "");
+}
+
+function trackedFiles(dir) {
+  return execFileSync("git", ["ls-files", dir], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const violations = [];
+
+// 1. Source imports under kits/.
+for (const file of trackedFiles("kits").filter((f) => SOURCE_EXT.test(f))) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(codeOnly(line)))) {
+      violations.push(`${file}:${index + 1}  imports @kontourai/veritas — kits wrap the engine via CLI, not as a library`);
+    }
+  });
+}
+
+// 2. kit.json dependency declarations.
+for (const file of trackedFiles("kits").filter((f) => f.endsWith("kit.json"))) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    continue;
+  }
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const decl = manifest[field];
+    if (decl && typeof decl === "object" && !Array.isArray(decl)) {
+      for (const name of ["@kontourai/veritas"]) {
+        if (Object.prototype.hasOwnProperty.call(decl, name)) {
+          violations.push(`${file} ${field}.${name} — a kit must not declare the engine as an npm dependency`);
+        }
+      }
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-layer-boundary] FAILED — a kit imports/depends on the veritas engine as a library (engine/surface seam, Invariant 3):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nKits distribute by copy/activate/CLI and consume the engine via its CLI + recorded artifacts,\n" +
+      "never as an npm library import. The trust-bundle adapter may import @kontourai/surface (the open\n" +
+      "trust format); it must not import @kontourai/veritas. See veritas docs/architecture/engine-surface-seam.md.",
+  );
+  process.exitCode = 1;
+} else {
+  console.log("[check-layer-boundary] OK — no kit imports or declares the veritas engine as a library.");
+}

package/dist/catalog.json

@@ -20,6 +20,7 @@
     "agentic-engineering",
     "browser-test",
     "builder-shape",
+    "consult-standards",
     "continue-work",
     "deliver",
     "dependency-update",
@@ -40,6 +41,7 @@
     "release-readiness",
     "review-work",
     "search-first",
+    "standards-authoring",
     "tdd-workflow",
     "verify-work"
   ],

package/dist/claude-code/.claude/agents/tool-security-reviewer.md

@@ -78,7 +78,8 @@ Findings: <count by severity>
 ```
 
 ## Rules
-- No false positives without evidence. Show the vulnerable code.
+- No false positives without evidence: cite the exact `file:line` and a one-line description of the weakness as the evidence.
+- Do NOT reproduce exploit payloads, working attack strings, or large copied blocks of vulnerable code in the report. A precise `file:line` reference plus a short description IS the evidence — reproduction detail belongs in the fix pass, not the recorded finding. (This keeps security findings recordable through `workflow critique`, whose reviewer runtime's provider may content-filter exploit-shaped prose.)
 - Run dependency audit tools if available (npm audit, pip-audit, cargo audit).
 - If no security issues found, say so clearly — don't invent findings.
 - This is read-only analysis. Do not modify any files.

package/dist/claude-code/.claude/skills/consult-standards/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "consult-standards"
+description: "Get just-in-time Veritas governance guidance for a file or work area before editing it: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/examples, and the latest recorded surface status — then edit within those rules. Use before changing a governed repo's files, or when you want to know what standards apply to a path. Pull-based guidance; it does not block (the PreToolUse hook is the enforcement gate)."
+---
+
+# Consult Standards
+
+Before you edit a file in a Veritas-governed repo, ask Veritas what applies to it. `veritas
+explain` projects the repo's governance excerpt + the Repo Standards rules matching that file (or
+work area) + their latest surface status into one just-in-time briefing — so you edit *within* the
+rules instead of discovering a violation only when the PreToolUse hook blocks the write.
+
+**This skill wraps the `veritas` CLI. It reimplements no rule evaluation** — `veritas explain`
+does the matching and projection; the skill only tells you when and how to ask.
+
+## When to use this
+
+- **Before editing** a file in a repo that has a `.veritas/` governance config — especially a
+  file under a governed work area, or one you haven't touched before.
+- **When you want to know what standards apply** to a path or area without reading every rule in
+  `.veritas/repo-standards/` yourself.
+- Not a gate: this is **pull-based** guidance you invoke. Enforcement is separate and automatic —
+  the Veritas PreToolUse hook (engine-side; installed via the kit's governance hooks) evaluates
+  and can *block* a non-conforming write whether or not you consulted first. Consulting first
+  means you shape the edit to pass, rather than getting blocked and retrying.
+
+## How to consult
+
+```bash
+# For a specific file you're about to change:
+veritas explain --file src/path/to/file.ts
+
+# For a whole work area (a Repo Map graph node id):
+veritas explain --work-area <work-area-id>
+
+# Or pass a bare selector (auto-classified as a rule id, a file path if it contains '/', or a work-area token):
+veritas explain src/path/to/file.ts
+```
+
+`veritas explain` prints a **`Veritas JIT Context`** briefing:
+
+- **`Governance:`** — the leading lines of `.veritas/GOVERNANCE.md` (the repo's terse governance rules).
+- One block per **matching rule**: `Rule` / `Kind` / `Enforcement Level` (`Require` / `Guide` / …) /
+  `Summary` / `Do` / `Do not` / `Good` / `Bad` / `Context`.
+- **`Surface status:`** — the latest recorded status for that rule from the evidence artifacts
+  (e.g. `verified`), plus any `Surface fault:` transparency-gap lines.
+
+Read the matching rules, honor their `Do`/`Do not`, and keep the change inside the work area's
+guidance. `No matching requirement found.` means no additional Repo Standard applies to that path
+— proceed normally, it is not an error.
+
+## Source of truth
+
+`veritas explain` is a *projection* of the repo's own governance config. When you want the raw
+standards rather than the filtered view, read them directly — they are the source `explain` reads:
+
+- `.veritas/GOVERNANCE.md` — the terse agent-facing governance rules.
+- `.veritas/repo-standards/*.json` — the Repo Standards (each rule's `summary` / `mustDo` /
+  `mustNotDo` / `exampleGood` / `exampleBad` / `contextLinks`).
+- `.veritas/repo-map.json` — the work-area graph `--work-area` selects against.
+
+## Contract
+
+- **Read-only advisory.** This skill runs `veritas explain`, which reads config and evidence and
+  writes nothing. It never gates, never blocks, never attaches evidence, and has no pass/fail
+  verdict — it surfaces guidance, full stop. Enforcement stays the PreToolUse hook (engine-side).
+- **No MCP server.** Just-in-time guidance here is agent-invoked CLI (`veritas explain`), not a
+  standing MCP service. Per the flow-agents MCP posture (ADR 0011), MCP never carries the gate and
+  enforcement stays hooks; this skill is the deliberate agent-pull replacement for a guidance
+  server, not a new server.
+- **Wraps the engine; reimplements nothing.** All rule matching, governance projection, and
+  surface-status lookup live in `@kontourai/veritas` (`veritas explain` / `src/explain.mjs`). The
+  skill adds no evaluation logic.

package/dist/claude-code/.claude/skills/execute-plan/SKILL.md

@@ -11,7 +11,7 @@ Implement an approved plan while preserving scope, traceability, and recovery co
 
 - **Role:** canonical Builder build-step producer and standalone execution primitive.
 - **Binding:** `builder.build` step `execute`.
-- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, and `implementation-scope` for an active matching run.
+- **Produces:** the active session execution report (`<slug>--deliver.md`), `state.json`, the wave manifest (`waves.json`) for delegated waves, and `implementation-scope` for an active matching run.
 - **Standalone no-run behavior:** execute the supplied plan and return execution evidence. Do not start a Builder run, record Builder evidence, or imply that an inactive Builder flow advanced.
 
 ## Model Routing
@@ -33,8 +33,8 @@ Use `RepositoryAdapter` for repository, target revision, worktree, and changed-f
 
 1. Read the plan. Return it to `plan-work` when it lacks a Definition Of Done, stable acceptance criteria, task mapping, sandbox boundary, or usable execution scope.
 2. Before delegation, compare the current target revision with the plan's base through `RepositoryAdapter`. Re-ground the plan when changed scope intersects its assumptions; record missing confirmation as `NOT_VERIFIED` rather than treating it as fresh.
-3. Give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
-4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, collect results, resolve conflicts, and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
+3. Before dispatching a wave that delegates work, declare it in the session's wave manifest (`waves.json`, schema `schemas/workflow-waves.schema.json`): `wave_id`, owning step, and one `expected_workers` entry per worker, so the expected worker count (M) exists before any result arrives. Then give each worker its bounded task, owned files, relevant acceptance IDs, required evidence, sandbox/worktree constraints, rollback conditions, and plan reference.
+4. Run safe independent tasks concurrently and dependent tasks in order. Between waves, reconcile results against the wave manifest — never collect from memory or prose. Every declared worker must land exactly one terminal status record (`completed`, `failed`, or `blocked`). Record each declared worker that has no terminal record as `not_reported` — never silently absorb a missing worker — then record the wave's `reconciliation` with an explicit "N of M reported" summary naming the `not_reported` workers (for example "2 of 3 reported; worker-3 not_reported"). Treat the wave as complete only when N equals M; an incomplete wave is visible data that routes to re-dispatch, a blocker, or an explicit accepted gap. After reconciliation, resolve conflicts and update the execution record with completed work, remaining work, changed files, and supported acceptance criteria.
 5. For UI tasks, include the applicable frontend design guidance in the worker instruction.
 6. When implementation completes, record scope integrity: changed files, accepted deviations, task-to-criterion traceability, evidence, and outstanding gaps. Hand off to report-only review and verification; do not treat implementation as verification.
 7. Reconcile the execution report and `state.json` with the active session artifact directory.
@@ -49,6 +49,7 @@ The execution record must identify:
 - each completed task and its supported `AC*` identifiers
 - changed files and any scope deviation with approval or route-back reason
 - worker evidence, conflicts, rollback notes, remaining work, and next action
+- per-wave reconciliation against the manifest: "N of M reported" and any `not_reported` workers with their recovery route
 - current revision comparison and re-grounding decision
 
 ## Active Builder Evidence

package/dist/claude-code/.claude/skills/pull-work/SKILL.md

@@ -32,6 +32,18 @@ Select ready backlog work and prepare a bounded handoff without implementing it.
 
 An optional GitHub adapter may implement these interfaces. Do not require GitHub issue numbers, labels, Projects, pull requests, `gh`, or provider-native dependency APIs.
 
+### Readiness Source Integrity
+
+A configured `BoardProvider` is the canonical Backlog Readiness Source
+(`docs/decisions/backlog-readiness-source.md`). When the configured board
+yields zero ready items or cannot be read, record the provider warning
+(`zero_ready_items`, or the read failure) in the pull-work artifact and route
+to triage/intake for an explicit readiness decision. Never silently
+substitute `WorkItemProvider` issue-level listing for board-driven selection:
+a deliberate issue-listing pass must carry the `board_provider_bypassed`
+warning it received into the artifact, with the reason the board was
+bypassed.
+
 ## Model Routing
 
 For board scans, WIP assessment, dependency joins, and selection bookkeeping, resolve `delegate-mechanical` from `.datum/config.json`. If unavailable, inherit the session model and record the fallback.

package/dist/claude-code/.claude/skills/review-work/SKILL.md

@@ -58,6 +58,17 @@ fallback or escalation in the critique artifact.
      security-policy changes.
    - `tool-dependencies-updater` for dependency-manifest, lockfile, or dependency-tooling changes.
    - A configured domain or policy reviewer when the repository requires one.
+
+   When review fans out to delegated reviewer lanes, declare the fan-out in the
+   session's wave manifest (`waves.json`, schema
+   `schemas/workflow-waves.schema.json`, step `review`) with one
+   `expected_workers` entry per reviewer lane before dispatch. Reconcile against
+   that manifest at collection — "N of M reported" — instead of collecting from
+   memory: every declared reviewer lands exactly one terminal status record;
+   record a reviewer that never reports as `not_reported` in the manifest —
+   never silently absorb it — and carry that lane into the critique as
+   `not_verified` with the missing report named. A missing reviewer is never a
+   clean lane.
 3. Use repository-provided scanners and checks when applicable. Do not install
    a scanner, silently substitute a different one, or mark an unavailable
    required lane clean; record the lane as `NOT_VERIFIED` with the missing