@kontourai/flow-agents 1.2.0 → 1.4.0

package/build/src/flow-kit/validate.d.ts

@@ -0,0 +1,81 @@
+export type KitTargetConsumer = "flow" | "flow-agents" | string;
+export interface KitConformanceLevel {
+    /** K0: valid core Flow Kit container with at least one flow (gates evaluable agentlessly). */
+    k0: boolean;
+    /** K1: K0 + at least one Flow Agents extension asset class present (skills/docs/adapters/evals/assets). */
+    k1: boolean;
+    /** K2: K1 + evals present (live evidence layer). */
+    k2: boolean;
+}
+/**
+ * Kit trust level — WHO vouches for a kit, orthogonal to the K-level capability axis.
+ *
+ * - "first-party": the kit is authored and published by Kontour (kontourai); its id is in the
+ *   FIRST_PARTY_KIT_IDS allowlist maintained in this repository. These kits are built, tested,
+ *   and distributed with the flow-agents package.
+ * - "verified": reserved for a future third-party verification process (e.g. self-certification
+ *   via the conformance kit + cryptographic attestation / Veritas claims). Not yet implemented.
+ * - "unverified": default for all kits not in the first-party allowlist. This says nothing about
+ *   the kit's quality — it only means Kontour has not vouched for it.
+ *
+ * The v2 path for "verified": cryptographic signing / attestation against the conformance kit
+ * and Veritas claims substrate is the natural next step and is intentionally deferred.
+ */
+export type KitTrustLevel = "first-party" | "verified" | "unverified";
+/**
+ * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
+ *
+ * Criteria for inclusion:
+ *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
+ *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
+ *   3. Kontour owns and maintains the kit's content and release lifecycle.
+ *
+ * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
+ * Third-party forks or community kits published elsewhere are NOT first-party, even if they
+ * share a similar id — first-party is tied to provenance in this specific repository.
+ */
+export declare const FIRST_PARTY_KIT_IDS: ReadonlySet<string>;
+/**
+ * Derive the trust level for a kit id.
+ *
+ * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
+ * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ */
+export declare function deriveKitTrust(kitId: string): KitTrustLevel;
+export interface KitTargetsResult {
+    kit_id: string;
+    kit_name: string;
+    conformance: KitConformanceLevel;
+    /** Derived consumer targets based on observable asset classes. */
+    targets: KitTargetConsumer[];
+    /** Extension field namespaces that are not Flow or Flow Agents-owned. */
+    third_party_extensions: string[];
+    /**
+     * Trust level: who vouches for this kit. Orthogonal to the K-level capability axis.
+     * "first-party" = Kontour-published; "verified" = reserved (future); "unverified" = default.
+     */
+    trust: KitTrustLevel;
+}
+/**
+ * Derives the consumer-target level (K0/K1/K2), target audience list, and trust level from
+ * observable asset classes in the kit manifest. Does not require file I/O.
+ *
+ * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
+ *  - K0: valid core container (schema_version, id, name, flows non-empty).
+ *  - K1: K0 + any Flow Agents extension field present (skills/docs/adapters/evals/assets).
+ *  - K2: K1 + evals present.
+ *  - targets.flow: always present when K0 (any Flow consumer can evaluate gates).
+ *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
+ *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
+ *
+ * Trust derivation (from kontourai/flow-agents#79):
+ *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
+ *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ *
+ * @param manifest  The kit.json manifest object.
+ * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
+ *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
+ */
+export declare function deriveKitTargets(manifest: Record<string, unknown>, kitDir?: string): Promise<KitTargetsResult>;
+export declare function validateKitRepository(kitDir: string): Promise<string[]>;
+export declare function assertKitRepository(kitDir: string): Promise<Record<string, unknown>>;

package/build/src/flow-kit/validate.js

@@ -7,6 +7,30 @@ const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"
 // agent-extension fields are skills, docs, adapters, evals, assets.
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
 const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
+/**
+ * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
+ *
+ * Criteria for inclusion:
+ *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
+ *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
+ *   3. Kontour owns and maintains the kit's content and release lifecycle.
+ *
+ * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
+ * Third-party forks or community kits published elsewhere are NOT first-party, even if they
+ * share a similar id — first-party is tied to provenance in this specific repository.
+ */
+export const FIRST_PARTY_KIT_IDS = new Set(["builder", "knowledge"]);
+/**
+ * Derive the trust level for a kit id.
+ *
+ * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
+ * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ */
+export function deriveKitTrust(kitId) {
+    if (FIRST_PARTY_KIT_IDS.has(kitId))
+        return "first-party";
+    return "unverified";
+}
 let _validateKitContainerCache = null;
 async function loadValidateKitContainer() {
     if (_validateKitContainerCache)
@@ -49,7 +73,7 @@ async function delegateCoreContainerValidation(kitDir, manifest) {
         .map((d) => `${d.path}: ${d.message}`);
 }
 /**
- * Derives the consumer-target level (K0/K1/K2) and target audience list from
+ * Derives the consumer-target level (K0/K1/K2), target audience list, and trust level from
  * observable asset classes in the kit manifest. Does not require file I/O.
  *
  * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
@@ -60,6 +84,10 @@ async function delegateCoreContainerValidation(kitDir, manifest) {
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
  *
+ * Trust derivation (from kontourai/flow-agents#79):
+ *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
+ *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ *
  * @param manifest  The kit.json manifest object.
  * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
  *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
@@ -87,12 +115,15 @@ export async function deriveKitTargets(manifest, kitDir = "") {
         targets.push("flow-agents");
     for (const ns of thirdPartyExtensions)
         targets.push(ns);
+    // Derive trust level orthogonally to the K-level capability axis.
+    const trust = deriveKitTrust(kitId);
     return {
         kit_id: kitId,
         kit_name: kitName,
         conformance: { k0, k1, k2 },
         targets,
         third_party_extensions: thirdPartyExtensions,
+        trust,
     };
 }
 export async function validateKitRepository(kitDir) {

package/build/src/index.d.ts

@@ -0,0 +1,5 @@
+export { validateTrustBundle, normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, loadJson, writeJson, appendJsonl, sidecarBase, writeState, statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
+/** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */
+export declare function readSidecar(dir: string, name: string): Record<string, any>;
+/** Write a sidecar JSON file into a workflow artifact directory (pretty-printed, trailing newline). */
+export declare function writeSidecar(dir: string, name: string, payload: Record<string, any>): void;

package/build/src/index.js

@@ -0,0 +1,36 @@
+/**
+ * Public library surface for `@kontourai/flow-agents`.
+ *
+ * Native orchestration hosts can import the canonical workflow-sidecar
+ * writer/validator here instead of shelling out to the
+ * `flow-agents-workflow-sidecar` CLI or reimplementing validated
+ * read / merge / write of workflow evidence. This is the same code the CLI
+ * runs — importing it does not execute the CLI.
+ *
+ * The sidecar JSON Schemas ship under `schemas/` and can be validated against
+ * directly; the helpers below are the canonical writer/validator that produce
+ * and check conforming artifacts.
+ *
+ * @module
+ */
+import * as path from "node:path";
+import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+export { 
+// Trust-bundle (Hachure) validation — the same validator the writer uses.
+validateTrustBundle, 
+// Evidence / check / learning validation + normalization. These throw on
+// invalid input (with the same messages the CLI surfaces) and return the
+// normalized object on success.
+normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, 
+// Sidecar read / merge / write primitives.
+loadJson, writeJson, appendJsonl, sidecarBase, writeState, 
+// Schema vocabularies (the allowed status/phase/kind values).
+statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
+/** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */
+export function readSidecar(dir, name) {
+    return _loadJson(path.join(dir, name));
+}
+/** Write a sidecar JSON file into a workflow artifact directory (pretty-printed, trailing newline). */
+export function writeSidecar(dir, name, payload) {
+    _writeJson(path.join(dir, name), payload);
+}

package/build/src/lib/args.d.ts

@@ -0,0 +1,8 @@
+export type ParsedArgs = {
+    positionals: string[];
+    flags: Record<string, string | boolean | string[]>;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function flagString(flags: ParsedArgs["flags"], key: string, fallback?: string): string | undefined;
+export declare function flagBool(flags: ParsedArgs["flags"], key: string): boolean;
+export declare function flagList(flags: ParsedArgs["flags"], key: string): string[];

package/build/src/lib/fs.d.ts

@@ -0,0 +1,7 @@
+export declare function readJson(file: string): unknown;
+export declare function writeJson(file: string, value: unknown): void;
+export declare function copyDir(src: string, dest: string): void;
+export declare function assertPathContained(root: string, target: string): void;
+export declare function walkFiles(root: string): string[];
+export declare function relPath(root: string, file: string): string;
+export declare function isoNow(): string;

package/build/src/lib/workflow-learning-projection.d.ts

@@ -0,0 +1,132 @@
+export type WorkflowLearningStatus = "pending" | "learned" | "followup_required" | "blocked";
+export type WorkflowLearningOutcome = "success" | "failure" | "mixed" | "unknown";
+export type WorkflowLearningRouteTarget = "rule" | "skill" | "power" | "agent" | "eval" | "doc" | "backlog" | "knowledge" | "none";
+export type WorkflowLearningRouteStatus = "open" | "completed" | "accepted" | "deferred" | "rejected";
+export type WorkflowLearningCorrectionType = "workflow" | "skill" | "agent" | "tooling" | "test" | "doc" | "process" | "product" | "provider" | "none";
+export type WorkflowLearningRoute = {
+    target: WorkflowLearningRouteTarget;
+    status: WorkflowLearningRouteStatus;
+    ref?: string;
+};
+export type WorkflowLearningCorrection = {
+    needed: boolean;
+    type?: WorkflowLearningCorrectionType;
+    recurrence_key?: string;
+    intended_behavior?: string;
+    observed_behavior?: string;
+    gap?: string;
+    evidence?: string;
+    no_change_rationale?: string;
+    prevention?: WorkflowLearningRoute;
+};
+export type WorkflowLearningRecord = {
+    id: string;
+    recorded_at: string;
+    source_refs: string[];
+    outcome: WorkflowLearningOutcome;
+    facts: string[];
+    interpretation: string;
+    routing: WorkflowLearningRoute[];
+    correction?: WorkflowLearningCorrection;
+};
+export type WorkflowLearningSidecar = {
+    schema_version: "1.0";
+    task_slug: string;
+    status: WorkflowLearningStatus;
+    updated_at: string;
+    records: WorkflowLearningRecord[];
+};
+export type WorkflowLearningSource = {
+    path: string;
+    relativePath: string;
+    slug: string;
+    learning: WorkflowLearningSidecar;
+};
+export type ConsoleProjectionRef = {
+    product: string;
+    kind: string;
+    id: string;
+    label?: string;
+};
+export type ConsoleProjectionScope = {
+    kind: string;
+    id: string;
+};
+export type ConsoleLearningProjection = {
+    id: string;
+    family: "workflow";
+    nonAuthority: true;
+    subjectRef: ConsoleProjectionRef;
+    sourceRef: ConsoleProjectionRef;
+    summary: string;
+    extensions: {
+        "flow-agents": {
+            task_slug: string;
+            record_id: string;
+            source_refs: string[];
+            routing: {
+                count: number;
+                open: number;
+                completed: number;
+                accepted: number;
+                deferred: number;
+                rejected: number;
+                targets: WorkflowLearningRouteTarget[];
+                statuses: WorkflowLearningRouteStatus[];
+                refs: string[];
+            };
+            correction: {
+                needed: boolean;
+                type?: WorkflowLearningCorrectionType;
+                recurrence_key?: string;
+                prevention?: {
+                    target: WorkflowLearningRouteTarget;
+                    status: WorkflowLearningRouteStatus;
+                    ref?: string;
+                };
+            };
+            outcome: WorkflowLearningOutcome;
+            learning_status: WorkflowLearningStatus;
+            recorded_at: string;
+            updated_at: string;
+            source_path: string;
+        };
+    };
+};
+export type ConsoleLearningProjectionEnvelope = {
+    schema: "kontour.console.projection";
+    version: "0.1";
+    generatedAt: string;
+    scope: ConsoleProjectionScope;
+    producer: {
+        id: string;
+        product: "flow-agents";
+    };
+    derivedFrom: {
+        mode: "direct_snapshot";
+        eventHistory: "unavailable";
+        directSnapshot: {
+            id: string;
+            emittedAt: string;
+            producer: {
+                id: string;
+                product: "flow-agents";
+            };
+            reason: string;
+            sourceRef: ConsoleProjectionRef;
+        };
+    };
+    learnings: ConsoleLearningProjection[];
+};
+export type BuildWorkflowLearningProjectionOptions = {
+    scope: string | ConsoleProjectionScope;
+    generatedAt?: string;
+    producer?: {
+        id?: string;
+        product?: "flow-agents";
+    };
+};
+export declare function readWorkflowLearningSources(artifactRoot: string): WorkflowLearningSource[];
+export declare function buildWorkflowLearningProjection(sources: WorkflowLearningSource[], options: BuildWorkflowLearningProjectionOptions): ConsoleLearningProjectionEnvelope;
+export declare function validateWorkflowLearningProjectionSourceShape(value: unknown, label?: string): WorkflowLearningSidecar;
+export declare const validateWorkflowLearningSidecar: typeof validateWorkflowLearningProjectionSourceShape;

package/build/src/runtime-adapters.d.ts

@@ -0,0 +1,18 @@
+export type KitAsset = {
+    kit_id: string;
+    kit_name: string;
+    asset_class: string;
+    asset_id: string | null;
+    relative_path: string;
+    source_path: string;
+    source_kind: string;
+    description?: string;
+};
+export type KitInventory = {
+    assets: KitAsset[];
+    warnings: string[];
+    errors: string[];
+};
+export declare function readKitInventory(sourceRoot: string, dest: string): KitInventory;
+export declare function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown>;
+export declare function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown>;

package/build/src/tools/build-universal-bundles.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): number;

package/build/src/tools/build-universal-bundles.js

@@ -470,6 +470,7 @@ function exportOpencodePlugin() {
 
 import { spawnSync } from 'node:child_process';
 import { join, basename } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
 
 // opencode runs plugins inside its own compiled (Bun-based) binary, so
 // process.execPath points at opencode itself — spawning it with a script
@@ -480,6 +481,19 @@ const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPat
 export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
   const root = directory || process.cwd();
 
+  // Deterministic load marker. opencode invokes this factory at startup but
+  // does not reliably surface plugin console output to its log file, and its
+  // internal "loading plugin" message was dropped in opencode 1.17.x. Write a
+  // marker into the workspace telemetry dir so acceptance tests can confirm the
+  // plugin loaded without depending on opencode internals. Best-effort only.
+  try {
+    const telemetryDir = join(root, '.telemetry');
+    mkdirSync(telemetryDir, { recursive: true });
+    writeFileSync(join(telemetryDir, 'opencode-plugin.loaded'), 'flow-agents');
+  } catch (_err) {
+    // Marker is diagnostic only; never block plugin load on a write failure.
+  }
+
   // The hook scripts read the event payload from stdin; an empty stdin makes
   // the telemetry pipeline silently skip the emit (fail-open), so every spawn
   // must pass a payload (caught by live acceptance smoke 2026-06-11).

package/build/src/tools/common.d.ts

@@ -0,0 +1,9 @@
+export declare const root: string;
+export declare function rel(file: string): string;
+export declare function readText(file: string): string;
+export declare function writeText(file: string, text: string): void;
+export declare function loadJson<T = unknown>(file: string): T;
+export declare function exists(file: string): boolean;
+export declare function walkFiles(dir: string): string[];
+export declare function oneLine(value: string, limit?: number): string;
+export declare function markdownTable(headers: string[], rows: string[][]): string[];

package/build/src/tools/filter-installed-packs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/build/src/tools/generate-context-map.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/build/src/tools/validate-package.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/build/src/tools/validate-source-tree.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;

package/console.telemetry.json

@@ -49,7 +49,7 @@
     },
     {
       "id": "flow-agents-evidence",
-      "label": "Verification evidence",
+      "label": "Verification evidence (trust-backed refs use Hachure trust.bundle format when present)",
       "root": "product:flow-agents:.flow-agents",
       "files": [
         "evidence.json"

package/docs/adr/0004-gates-expect-surface-claims.md

@@ -1,15 +1,15 @@
 ---
-title: ADR 0004: Gates Expect Surface Claims
+title: ADR 0004: Gates Expect Hachure Trust Bundles
 ---
 
-# ADR 0004: Gates Expect Surface Claims
+# ADR 0004: Gates Expect Hachure Trust Bundles
 
-Flow-backed kits will model rich gate evidence as claim expectations rather than provider-specific requirements. A gate expectation can require `kind: "surface.claim"`, a Surface claim type such as `repo.policy_compliance`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.
+Flow-backed kits will model rich gate evidence as claim expectations using the Hachure trust.bundle format rather than provider-specific requirements. A gate expectation can require `kind: "trust.bundle"`, a domain claim type such as `builder.verify.tests`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.
 
-**Status**: Accepted
+**Status**: Accepted (updated: vocabulary aligned to Hachure trust.bundle in hachure-align)
 
-**Considered Options**: Provider-aware gate rules were rejected because they would make Flow Definitions know too much about individual tools. Plain evidence strings such as `tests` or `veritas` were rejected because they cannot represent claim type, accepted status, producer authority, transparency gaps, or project-level enforcement overrides cleanly.
+**Considered Options**: Provider-aware gate rules were rejected because they would make Flow Definitions know too much about individual tools. Plain evidence strings such as `tests` or `veritas` were rejected because they cannot represent claim type, accepted status, producer authority, transparency gaps, or project-level enforcement overrides cleanly. An earlier version used `kind: "surface.claim"` and `artifact_kind: "TrustReport"/"Trust Snapshot"` — those have been renamed to `kind: "trust.bundle"` and `artifact_kind: "trust.bundle"` to align with the Hachure schema standard that Flow now ships.
 
-**Consequences**: Trusted producer mappings belong upstream in Flow project configuration, not Flow Agents runtime configuration. Flow Agents can help author, install, and adapt that configuration for agent runtimes, but CI, framework agents, local CLIs, and humans should all evaluate gates against the same Flow-owned authority model.
+**Consequences**: Trusted producer mappings belong upstream in Flow project configuration, not Flow Agents runtime configuration. Flow Agents can help author, install, and adapt that configuration for agent runtimes, but CI, framework agents, local CLIs, and humans should all evaluate gates against the same Flow-owned authority model. When hachure is installed as an optional dependency, referenced trust artifacts are validated against hachure's trust-bundle.schema.json at evidence-recording time.
 
-**Initial Shape**: Gate expectations should use `expects` entries with `id`, `kind: "surface.claim"`, `required`, `claim.type`, optional `claim.subject`, `claim.accepted_statuses`, `description`, and optional `explore_hint`. The Builder Kit should use intuitive subject strings such as `flow-run`, `flow-step`, `work-item`, `change`, `pull-request`, `release`, `decision`, and `artifact`, while the schema remains open to other subject values.
+**Initial Shape**: Gate expectations should use `expects` entries with `id`, `kind: "trust.bundle"`, `required`, `claim.type`, optional `claim.subject`, `claim.accepted_statuses`, `description`, and optional `explore_hint`. The Builder Kit should use intuitive subject strings such as `flow-run`, `flow-step`, `work-item`, `change`, `pull-request`, `release`, `decision`, and `artifact`, while the schema remains open to other subject values.

package/docs/developer-architecture.md

@@ -108,6 +108,20 @@ flowchart TB
 
 **Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
 
+**Programmatic API (for native hosts):** The canonical sidecar writer/validator is importable as a library, not only via the `flow-agents-workflow-sidecar` CLI. A host that records workflow evidence natively should import the package root rather than reimplement validated read / merge / write:
+
+```js
+import {
+  validateTrustBundle,   // Hachure trust.bundle validation (the writer's validator)
+  normalizeCheck,        // validate + normalize an evidence check (throws on invalid)
+  normalizeLearning,     // validate + normalize a learning record
+  validateEvidenceRef,   // validate a structured evidence reference
+  readSidecar, writeSidecar, sidecarBase, writeState,
+} from "@kontourai/flow-agents";
+```
+
+This is the same code the CLI runs; importing it does not execute the CLI. The sidecar JSON Schemas under `schemas/` remain the normative shape.
+
 **Future direction:** Durable workflow state should converge toward Kontour Resource Contracts with versioned identity, desired state, observed status, and condition summaries. That convergence should preserve local files and provider-backed records as first-class surfaces.
 
 ## Local Workflow Roles

package/docs/kit-authoring-guide.md

@@ -74,12 +74,12 @@ A Flow Definition at minimum needs `id`, `version`, `steps`, and `gates`. Steps
       "expects": [
         {
           "id": "review-finding",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "The change was reviewed and findings were recorded.",
-          "claim": {
-            "type": "my-kit.review.finding",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "my-kit.review.finding",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -270,7 +270,7 @@ Version constraints (e.g. minimum `flow-agents` version) are the only case where
 
 ### Evidence layering: Surface and Veritas
 
-Kit gates reference evidence using `"kind": "surface.claim"`. This is **Flow-native vocabulary**: Flow is built on Surface, so Surface claims are the expected evidence substrate at the Flow level. Surface claims are not a Flow Agents coupling.
+Kit gates reference evidence using `"kind": "trust.bundle"` with a `bundle_claim` selector (`claimType`, optional `subjectType`, `accepted_statuses`). This is **Flow-native vocabulary** in the Hachure open trust-bundle format: Flow is built on Surface, so trust bundles are the expected evidence substrate at the Flow level, validated against Hachure's `trust-bundle.schema.json`. They are not a Flow Agents coupling. (Earlier Flow releases used `kind: "surface.claim"` with a `claim` selector; Flow 1.3.0 replaced that with `trust.bundle`, kontourai/flow#84.)
 
 Veritas is an **optional claim family** — a developer-repo specialization for evidence that has been through a trust pipeline. Kits may be opinionated about requiring Veritas-class evidence. Builder Kit requiring Veritas-class evidence is the kit's own policy choice, defined by Kontour as the kit author, not a platform requirement. Other kits may not require Veritas at all.
 
@@ -299,7 +299,8 @@ Output is stable JSON:
     "k2": false
   },
   "targets": ["flow", "flow-agents"],
-  "third_party_extensions": []
+  "third_party_extensions": [],
+  "trust": "unverified"
 }
 ```
 
@@ -307,6 +308,98 @@ Exit code 0 when the kit is at least K0 (valid core container); exit code 1 when
 
 The `inspect` command is read-only and safe to run before install.
 
+## Trust axis: who vouches for a kit
+
+The **trust axis** is a separate, orthogonal classification from the K-level capability axis. It answers the question "who vouches for this kit?" rather than "what does this kit contain?".
+
+### Two orthogonal axes
+
+Every kit carries two independent badges:
+
+| Axis | Values | Question answered |
+|---|---|---|
+| **Capability** (K-level) | K0 / K1 / K2 | What does the kit CONTAIN? (derived from assets) |
+| **Trust** | first-party / verified / unverified | WHO vouches for it? (derived from provenance) |
+
+A K2 kit can be `unverified`. A K0 kit can be `first-party`. The levels are independent.
+
+**Marketplace listing format**: `Works with: Flow (gates-only) | K1 | ✓ First-party`
+
+### Trust levels
+
+| Level | Meaning | How it is assigned (v1) |
+|---|---|---|
+| `first-party` | Kontour authored, tested, and ships this kit in the `@kontourai/flow-agents` package. | Kit id is in the internal FIRST_PARTY_KIT_IDS allowlist in `src/flow-kit/validate.ts`. |
+| `verified` | Reserved for a future third-party verification process. | Not yet implemented; the value is reserved but not granted to any kit today. |
+| `unverified` | Default for all kits not explicitly vouched for. | All other kits, including third-party community kits. |
+
+`unverified` says nothing about the quality of a kit — it only means Kontour has not vouched for it through one of the above channels.
+
+### First-party kits (v1)
+
+The first-party allowlist in v1 contains the kits authored by Kontour and distributed with the flow-agents package:
+
+- `builder` — Builder Kit (shape, build, and deliver work)
+- `knowledge` — Knowledge Kit (durable gated knowledge store)
+
+Criteria for a kit to be first-party:
+1. Its directory lives under `kits/` in the `kontourai/flow-agents` repository.
+2. It is published as part of the `@kontourai/flow-agents` npm package.
+3. Kontour owns and maintains the kit's content and release lifecycle.
+
+Third-party forks, community kits, or kits published under a different npm package are NOT first-party even if they share a similar id. First-party is tied to provenance in this specific repository and package.
+
+### Deferred: verified trust and cryptographic attestation (v2)
+
+The `verified` value is reserved for a future verification process. The intended v2 path:
+
+- Third-party kit authors can apply for `verified` status.
+- Verification evidence: the kit passes the conformance kit self-certification + a cryptographic signature or Veritas attestation.
+- The [conformance kit](https://github.com/kontourai/flow) and [Veritas claims](veritas-integration.md) are the natural substrate for this attestation layer.
+- The signature or attestation would be checked by `flow-agents kit inspect` at derivation time.
+
+v1 deliberately omits the signing/attestation mechanism and the verification process. The `verified` value is reserved so consuming tools can handle it when it arrives without a breaking schema change.
+
+### Inspecting trust
+
+The `trust` field appears in `flow-agents kit inspect` output alongside `conformance`:
+
+```bash
+npm run kit -- inspect kits/builder
+```
+
+```json
+{
+  "kit_id": "builder",
+  "kit_name": "Builder Kit",
+  "conformance": {
+    "k0": true,
+    "k1": true,
+    "k2": false
+  },
+  "targets": ["flow", "flow-agents"],
+  "third_party_extensions": [],
+  "trust": "first-party"
+}
+```
+
+A third-party kit inspected before verification:
+
+```json
+{
+  "kit_id": "my-custom-kit",
+  "kit_name": "My Custom Kit",
+  "conformance": {
+    "k0": true,
+    "k1": true,
+    "k2": false
+  },
+  "targets": ["flow", "flow-agents"],
+  "third_party_extensions": [],
+  "trust": "unverified"
+}
+```
+
 ## Direction
 
 Flow Kits are designed to be shareable workflow units — authored once, carried across teams and workspaces. The intended growth path is distribution from git remotes and a curated Kontour kit catalog of Kontour-authored kits covering work modes beyond software delivery. Today install is local-path only; remote fetch is explicitly a non-goal in this version.

package/docs/operating-layers.md

@@ -49,7 +49,7 @@ Governance tools such as Veritas belong at the Evidence boundary. Flow Agents sh
 
 ## Flow Kit Coordination
 
-Flow owns Flow Definition semantics: gates use typed `expects` entries, Surface requirements use `kind: "surface.claim"`, and project configuration owns trusted producer mappings plus gate overrides. Flow Agents should author, install, adapt, and control those assets for local runtimes; it should not become the authority source for claim trust or override semantics.
+Flow owns Flow Definition semantics: gates use typed `expects` entries, Surface requirements use `kind: "trust.bundle"` (the Hachure-aligned gate kind), and project configuration owns trusted producer mappings plus gate overrides. Flow Agents should author, install, adapt, and control those assets for local runtimes; it should not become the authority source for claim trust or override semantics.
 
 The Kit Catalog is the Flow Agents index of installable Flow Kits. A Flow Kit can contain Flow Definitions, skills, docs, adapters, and evals, but the catalog points at those assets instead of defining gate behavior itself. Builder Kit is the first Kontour-authored kit and proves the path from shaping through build, verification, merge readiness, and learning.
 
@@ -65,7 +65,7 @@ Builder Kit vocabulary should be used in public and internal guidance:
 - Builder Kit: the coding/building kit shipped by this repo.
 - Probe: question-driven design and context challenge step, surfaced as `design-probe`.
 
-Builder Kit evidence gates can reference Surface trust state without naming a provider. A trust-backed gate may attach a TrustReport or Trust Snapshot ref for the relevant Surface claim, while Flow keeps authority over gate evaluation, trusted producer mapping, and route-back behavior. Surface remains the portable trust-state layer, and Veritas remains an optional producer rather than a required Builder Kit dependency.
+Builder Kit evidence gates can reference Surface trust state without naming a provider. A trust-backed gate may attach a Hachure trust.bundle ref for the relevant Surface claim, while Flow keeps authority over gate evaluation, trusted producer mapping, and route-back behavior. Surface remains the portable trust-state layer, and Veritas remains an optional producer rather than a required Builder Kit dependency.
 
 ## Placement Rules