Flow AgentsEvidence-gated workflows for coding agents, carried into the agent tools you already use

Migrations#

Unreleased#

  • workflow-evidence now uses schema_version: "2.0". Every command check requires the capture-time observed_at_commit and boolean worktree_clean fields. Migrate repository-owned producers and accepted fixtures atomically; version 1 records are rejected and must be re-recorded, and v2 command checks missing either field are invalid and non-confirming. Do not copy current HEAD into historical evidence: Git provenance is captured only after the command result settles. worktree_clean: false is valid for an audited provisional result, but it must be not_verified (or a non-passing status) and cannot satisfy a gate. Consumers must use the runtime-authoritative trust.bundle for gate decisions; workflow-evidence v2 is the consumer-facing v2 projection. A command's trusted-ancestor check is necessary but does not prove byte identity, so passing evidence also requires the exact observation-time Git-worktree snapshot.
  • Economics records produced from runtime telemetry now use version: "0.2". Version 0.2 requires exact run correlation, declared observation semantics, and producer authority. Its verification verdict comes only from the canonical Builder workflow_outcome; legacy artifact or critique status no longer supplies a runtime verification verdict. The bundled validator continues to accept historical 0.1 records.
  • Telemetry lifecycle clocks are now keyed by native runtime name and session id. Runtime adapters must pass the same native session identity at start and stop; they no longer fall back to the newest session file, which could join elapsed time across concurrent agents.
  • Effective Flow compilation now removes any referenced, ungated terminal sentinel, regardless of its step name. The preceding gated step therefore completes the run directly instead of leaving a workflow active at a no-gate terminal marker.
  • record-agent-event --artifact-dir now also requires the owning --artifact-root, and the current runtime actor must still be bound to that session. Late or copied-directory appends are rejected instead of becoming unauthenticated delegation facts. record-agent-event no longer accepts --actor; identity is derived from the runtime environment, and nested agent-event directories must be regular non-symlink directories. Economics commands that pass explicit sidecar paths are now fixture-only: set FLOW_AGENTS_ECONOMICS_FIXTURE_MODE=true; those records are marked producer_authority: "fixture_input" and can never relay to Console. Hosted economics now also requires an authenticated terminal binding and a run-scoped transcript baseline; unbound or session-scoped observations remain local.
  • Gate-action envelopes now use schema_version: "3.0". action.declared_artifacts and stop_condition.required.artifact_refs contain typed targets instead of strings. A file target names its project-relative path and whether it is directly writable or must be produced through a declared operation; a trust_slice target is explicitly non-writable and names the public interface that records it. action.artifact_bindings maps each typed target to the gate expectation ids it satisfies, so consumers can derive the exact required target set from unresolved required expectations without private kit metadata. The bindings are product-owned gate semantics, not grader hints or consumer-authored guidance. Empty expectation ownership on a file represents a declared optional artifact that is never gate-required; trust slices must own an expectation so their recording interface can be derived. Structured evidence parameters reference the canonical public_interfaces.schemas.evidence_ref_json JSON Schema. There is no legacy envelope fallback; adapters must require version 3.0 and stop treating trust.bundle#<slice> as a filesystem path.
  • Gate-action envelope version 2.0 added the originating gate_id to each gate.requirements entry, allowing consumers to verify accepted exceptions without private Flow-definition knowledge. There was no legacy version 1.0 fallback.
  • Workflow runtime artifacts now live under .kontourai/flow-agents/ instead of earlier runtime roots such as .flow-agents/ or .agents/flow-agents/. Move any local session directories, sidecars, or current.json pointers you want to keep into the new root. Runtime readers do not fall back to old roots. Runtime state remains ignored; promote durable outcomes into docs, source, schemas, or provider records before merge.
  • Flow Agents setup no longer accepts Console bearer tokens as CLI arguments. Replace --console-token TOKEN with --console-token-file PATH for headless installs, or use the prompted flow-agents init flow. Interactive setup hides token input and passes it to installers through a temporary 0600 token file that is deleted after install.
  • Telemetry setup now uses named sinks. Local file telemetry remains the default. Add --telemetry-sink local-kontour-console, --telemetry-sink kontour-hosted-console, or --telemetry-sink user-hosted-console --console-url ... to mirror local telemetry into a Console API. Legacy kontour-cloud and hosted-kontour-console names still work as aliases.
  • Flow Agents now owns and ships console.telemetry.json. Console should load the descriptor from the Flow Agents product root rather than owning Flow Agents-specific telemetry facets or sidecar mappings.

Evidence Reference Migration#

Flow Agents sidecars now treat structured evidence reference objects as the schema contract. Legacy string refs in acceptance.json and evidence.json must be converted before validation.

Convert old strings like:

"evidence_refs": ["npm run eval:static --silent"]

to objects like:

"evidence_refs": [
  {
    "kind": "command",
    "excerpt": "npm run eval:static --silent",
    "summary": "Static eval suite passed."
  }
]

For source evidence, include file and line data:

{
  "kind": "source",
  "url": "https://github.com/OWNER/REPO/blob/COMMIT_SHA/path/to/file.ts#L12-L24",
  "file": "path/to/file.ts",
  "line_start": 12,
  "line_end": 24,
  "excerpt": "Short excerpt that supports the acceptance claim."
}

Use immutable GitHub blob URLs pinned to a commit SHA when the commit/provider URL is available. Before publication, omit url and keep file, line_start, line_end, and excerpt as a local fallback. Upgrade local refs before provider closure whenever practical.

Source: docs/migrations.md