@kontourai/flow-agents 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.4.0](https://github.com/kontourai/flow-agents/compare/v1.3.0...v1.4.0) (2026-06-16)
+
+
+### Features
+
+* **#100:** require block reasons to reach the model ([#102](https://github.com/kontourai/flow-agents/issues/102)) ([5007c63](https://github.com/kontourai/flow-agents/commit/5007c63906aa78028477ffd2da31142ed4c3d0a8))
+* **#99:** export the workflow sidecar writer/validator as a library ([#101](https://github.com/kontourai/flow-agents/issues/101)) ([5baa294](https://github.com/kontourai/flow-agents/commit/5baa294486b09e0e64a9fb5a029155c53775f477))
+
 ## [1.3.0](https://github.com/kontourai/flow-agents/compare/v1.2.0...v1.3.0) (2026-06-16)
 
 

package/build/src/cli/console-learning-projection.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/effective-backlog-settings.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/fixture-retirement-audit.d.ts

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

package/build/src/cli/init.d.ts

@@ -0,0 +1,17 @@
+export declare const COLLISION_MARKER = "Recording Flow Agents telemetry";
+/**
+ * Check whether a user-level Claude Code settings file already contains
+ * Flow Agents hook commands. If it does, print a WARNING explaining that
+ * Claude Code merges user-level and project-level settings and runs ALL
+ * matching hooks, so having flow-agents in both places causes duplicate
+ * hook execution (double telemetry, double policy enforcement).
+ *
+ * The check does NOT block the install; it is advisory only.
+ *
+ * @param userSettingsFile Path to inspect (defaults to $HOME/.claude/settings.json;
+ *   overridable via FLOW_AGENTS_USER_CLAUDE_SETTINGS env var for testability).
+ * @returns true if a collision was detected, false otherwise.
+ */
+export declare function checkScopeCollision(userSettingsFile?: string): boolean;
+export declare function main(argv?: string[]): Promise<number>;
+export declare function mainDogfood(argv?: string[]): Promise<number>;

package/build/src/cli/kit.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/promote-workflow-artifact.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/publish-change-helper.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/pull-work-provider.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/runtime-adapter.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/telemetry-doctor.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/usage-feedback.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/utterance-check.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/validate-hook-influence.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

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

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;

package/build/src/cli/validate-workflow-artifacts.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/src/cli/veritas-governance.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/workflow-artifact-cleanup-audit.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

package/build/src/cli/workflow-sidecar.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+type AnyObj = Record<string, any>;
+export declare const statuses: Set<string>;
+export declare const phases: string[];
+export declare const checkKinds: Set<string>;
+export declare const checkStatuses: Set<string>;
+export declare const verdicts: Set<string>;
+export declare function writeJson(file: string, payload: AnyObj): void;
+export declare function loadJson(file: string, fallback?: AnyObj): AnyObj;
+export declare function appendJsonl(file: string, payload: AnyObj): void;
+/**
+ * Validate a Hachure trust.bundle against the canonical trust-bundle schema.
+ * Returns `{ valid, errors, available }`. When the optional `hachure` dependency
+ * is not installed, validation is unavailable and this returns
+ * `{ valid: true, errors: [], available: false }` (fail-open) so callers can
+ * choose to treat unvalidated bundles as acceptable or gate on `available`.
+ * This is the same validator the sidecar writer uses for trust-backed evidence.
+ */
+export declare function validateTrustBundle(bundle: unknown): {
+    valid: boolean;
+    errors: string[];
+    available: boolean;
+};
+export declare function sidecarBase(slug: string): AnyObj;
+export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
+export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
+export declare function normalizeCheck(raw: AnyObj): AnyObj;
+export declare function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next?: string): void;
+export declare function normalizeFinding(raw: AnyObj): AnyObj;
+export declare function validateLearningCorrection(record: AnyObj): void;
+export declare function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj;
+export {};

package/build/src/cli/workflow-sidecar.js

@@ -3,17 +3,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
-const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
-const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
-const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
-const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+import { fileURLToPath } from "node:url";
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
+export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
+export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
+export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file) { return fs.readFileSync(file, "utf8"); }
-function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
+export function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
 function printJson(payload) { console.log(JSON.stringify(payload).replace(/":/g, '": ').replace(/,"/g, ', "')); }
-function loadJson(file, fallback = {}) { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
-function appendJsonl(file, payload) {
+export function loadJson(file, fallback = {}) { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
+export function appendJsonl(file, payload) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const line = JSON.stringify(payload, Object.keys(payload).sort()).replace(/":/g, '": ').replace(/,"/g, ', "');
     fs.appendFileSync(file, `${line}\n`);
@@ -65,6 +66,20 @@ function getHachureValidator() {
         _hachureValidator = tryLoadHachureValidator();
     return _hachureValidator;
 }
+/**
+ * Validate a Hachure trust.bundle against the canonical trust-bundle schema.
+ * Returns `{ valid, errors, available }`. When the optional `hachure` dependency
+ * is not installed, validation is unavailable and this returns
+ * `{ valid: true, errors: [], available: false }` (fail-open) so callers can
+ * choose to treat unvalidated bundles as acceptable or gate on `available`.
+ * This is the same validator the sidecar writer uses for trust-backed evidence.
+ */
+export function validateTrustBundle(bundle) {
+    const validate = getHachureValidator();
+    if (!validate)
+        return { valid: true, errors: [], available: false };
+    return { ...validate(bundle), available: true };
+}
 function safeRepoIdentifier(value) {
     const trimmed = value.trim().replace(/\.git$/, "");
     if (!trimmed || trimmed.length > 120)
@@ -119,7 +134,7 @@ function repoIdentifier() {
     }
     return safeRepoIdentifier(path.basename(process.cwd())) || "workspace";
 }
-function sidecarBase(slug) {
+export function sidecarBase(slug) {
     return { schema_version: "1.0", task_slug: slug, repo: repoIdentifier() };
 }
 function parseArgs(argv) {
@@ -428,7 +443,7 @@ function hasNonEmptyString(value) {
 function hasPositiveInteger(value) {
     return Number.isInteger(value) && Number(value) >= 1;
 }
-function validateEvidenceRef(ref, label) {
+export function validateEvidenceRef(ref, label) {
     if (!["source", "command", "artifact", "provider", "external"].includes(ref.kind))
         die(`${label} entry kind must be one of: source, command, artifact, provider, external`);
     for (const key of Object.keys(ref))
@@ -458,7 +473,7 @@ function validateEvidenceRef(ref, label) {
         die(`${label} ${ref.kind} refs require url`);
     return ref;
 }
-function normalizeEvidenceRefs(raw, label) {
+export function normalizeEvidenceRefs(raw, label) {
     if (!Array.isArray(raw))
         die(`${label} must be an array`);
     return raw.map((ref) => {
@@ -469,7 +484,7 @@ function normalizeEvidenceRefs(raw, label) {
         return validateEvidenceRef({ ...ref }, label);
     });
 }
-function normalizeCheck(raw) {
+export function normalizeCheck(raw) {
     const check = { ...raw };
     if (!check.id || !check.kind || !check.status || !check.summary)
         die("check requires id, kind, status, and summary");
@@ -578,7 +593,7 @@ function validateAcceptanceEvidenceRefs(dir) {
             normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
     });
 }
-function writeState(dir, slug, status, phase, timestamp, summary, next = "continue") {
+export function writeState(dir, slug, status, phase, timestamp, summary, next = "continue") {
     writeJson(path.join(dir, "state.json"), { ...loadJson(path.join(dir, "state.json")), ...sidecarBase(slug), status, phase, updated_at: timestamp, artifact_paths: relArtifacts(dir), next_action: { status: next, summary } });
 }
 function recordEvidence(p) {
@@ -637,7 +652,7 @@ function advanceState(p) {
     writeJson(path.join(dir, "handoff.json"), { ...loadJson(path.join(dir, "handoff.json")), ...sidecarBase(slug), summary: opt(p, "summary"), current_state_ref: "state.json", next_steps: [opt(p, "next-action")].filter(Boolean), blockers: [], warnings: [] });
     return 0;
 }
-function normalizeFinding(raw) {
+export function normalizeFinding(raw) {
     if (raw.file_refs !== undefined && !Array.isArray(raw.file_refs))
         die("file_refs must be an array");
     return raw;
@@ -704,7 +719,7 @@ function recordRelease(p) {
     writeState(dir, slug, "delivered", "release", payload.updated_at, stateSummary);
     return 0;
 }
-function validateLearningCorrection(record) {
+export function validateLearningCorrection(record) {
     const correction = record.correction;
     if (correction === undefined)
         return;
@@ -747,7 +762,7 @@ function validateLearningPrevention(prevention) {
     if (!["open", "completed", "accepted", "deferred", "rejected"].includes(value.status))
         die("correction.prevention.status must be one of: open, completed, accepted, deferred, rejected");
 }
-function normalizeLearning(raw, timestamp) {
+export function normalizeLearning(raw, timestamp) {
     if (!Array.isArray(raw.source_refs))
         die("source_refs must be an array");
     if (!Array.isArray(raw.facts))
@@ -878,4 +893,21 @@ async function main() {
         }
     });
 }
-main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+// Run the CLI only when executed directly, not when imported as a library.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+}

package/build/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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/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/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/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/spec/runtime-hook-surface.md

@@ -57,6 +57,20 @@ Canonical hook scripts in `scripts/hooks/` use the following exit code contract
 
 Adapters translate these exit codes into the host-native response format. The `claude-hook-adapter.js` and `codex-hook-adapter.js` wrappers perform this translation, and all errors fail open so hook runtime failures never block agent work.
 
+### Block Reason Channel
+
+A block (exit `2` → deny) is only useful if the agent learns *why* it was blocked and how to proceed. When a policy blocks, the hook script writes a human-readable reason — for example, config-protection's "Fix the source code … instead of weakening the config." The adapter **must surface that reason to the model** through the host's native deny-reason mechanism, **not only to a log or stderr**, where it dies before the agent sees it. A deny without a model-visible reason makes the agent retry the same blocked action instead of self-correcting.
+
+| Host surface | Model-facing reason channel |
+| --- | --- |
+| Claude Code | `hookSpecificOutput.permissionDecisionReason` (preToolUse); `reason` (stop) |
+| Codex | `hookSpecificOutput.permissionDecisionReason` (preToolUse); `reason` (stop) |
+| opencode | the thrown error message on the blocked `tool.execute.before` (surfaced as the tool result) |
+| pi | the `reason` field of the `{ block: true, reason }` tool-call result |
+| Native pre-dispatch host (e.g. an orchestration layer) | the blocked call's tool-result text |
+
+The reason text is the canonical steering message: it should tell the agent what to do *instead* (edit the source, not the generated artifact), so the agent can self-correct on the next turn. An adapter that denies the call but drops the reason to a log only is a **conformance gap** — record it in the adapter's conformance declaration.
+
 ---
 
 ## 2. Policy Classes
@@ -136,7 +150,7 @@ Flow Agents currently ships four canonical policy classes. Each policy class has
 - `SA_HOOK_INPUT_TRUNCATED` env var — whether input was truncated (truncated payloads are blocked unconditionally)
 - Protected file set: `.eslintrc*`, `eslint.config.*`, `.prettierrc*`, `prettier.config.*`, `biome.json`, `biome.jsonc`, `.ruff.toml`, `ruff.toml`, `.shellcheckrc`, `.stylelintrc*`, `.markdownlint*`
 
-**Decision contract**: Blocking (exits 2) when the target file basename is in the protected set. Writes a descriptive message to stderr directing the agent to fix source instead. Exits 0 (allow) otherwise.
+**Decision contract**: Blocking (exits 2) when the target file basename is in the protected set. Writes a descriptive message directing the agent to fix source instead, which the adapter surfaces to the model as the deny reason (see [Block Reason Channel](#block-reason-channel)). Exits 0 (allow) otherwise.
 
 **Degradation when host lacks trigger**: If the host has no `preToolUse`-equivalent blocking hook, config protection cannot veto tool calls. The agent may modify linter configs without interception. Log the gap as `preToolUse: no native blocking equivalent — config-protection policy unavailable`.
 
@@ -190,6 +204,7 @@ The adapter implements L1 plus all blocking policy classes.
 **Required**:
 - L1 steering and stop telemetry.
 - Config protection fires on `preToolUse` and can block (exit 2 translates to a deny response).
+- Every block surfaces its reason to the model through the host's deny-reason channel (see [Block Reason Channel](#block-reason-channel)), not only to a log.
 - Quality gate fires on `postToolUse`.
 - Stop-goal-fit fires on `stop` with `FLOW_AGENTS_GOAL_FIT_STRICT` configurable (default may be warning mode; strict mode must be possible to enable).
 

package/evals/integration/test_hook_category_behaviors.sh

@@ -63,9 +63,16 @@ if node "$ROOT/scripts/hooks/claude-hook-adapter.js" PreToolUse pre:config-prote
 {"hook_event_name":"PreToolUse","tool_input":{"path":"prettier.config.js"}}
 JSON
 then
+  claude_reason="$(run_json "$TMPDIR_EVAL/claude-block.json" "hookSpecificOutput.permissionDecisionReason")"
   if [[ "$(run_json "$TMPDIR_EVAL/claude-block.json" "continue")" == "false" ]] \
     && [[ "$(run_json "$TMPDIR_EVAL/claude-block.json" "hookSpecificOutput.permissionDecision")" == "deny" ]]; then
     pass "Claude runtime adapter translates PreToolUse policy block"
+    # Block Reason Channel: the deny must carry the steering reason to the model.
+    if [[ "$claude_reason" == *"Fix the source"* ]]; then
+      pass "Claude block surfaces the steer-to-source reason to the model"
+    else
+      fail "Claude block reason did not reach the model channel (permissionDecisionReason): $claude_reason"
+    fi
   else
     fail "Claude runtime adapter block contract mismatch"
   fi
@@ -77,8 +84,15 @@ if node "$ROOT/scripts/hooks/codex-hook-adapter.js" pre:config-protection config
 {"hook_event_name":"PreToolUse","tool_input":{"path":"biome.json"}}
 JSON
 then
+  codex_reason="$(run_json "$TMPDIR_EVAL/codex-block.json" "hookSpecificOutput.permissionDecisionReason")"
   if [[ "$(run_json "$TMPDIR_EVAL/codex-block.json" "hookSpecificOutput.permissionDecision")" == "deny" ]]; then
     pass "Codex runtime adapter translates PreToolUse policy block"
+    # Block Reason Channel: the deny must carry the steering reason to the model.
+    if [[ "$codex_reason" == *"Fix the source"* ]]; then
+      pass "Codex block surfaces the steer-to-source reason to the model"
+    else
+      fail "Codex block reason did not reach the model channel (permissionDecisionReason): $codex_reason"
+    fi
   else
     fail "Codex runtime adapter block contract mismatch"
   fi

package/evals/run.sh

@@ -135,6 +135,8 @@ run_static() {
   echo ""
   bash "$EVAL_DIR/static/test_evidence_refs.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/static/test_library_exports.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/static/test_console_presets.sh" || result=1
   echo ""
   bash "$EVAL_DIR/static/test_repo_hooks.sh" || result=1

package/evals/static/test_library_exports.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# test_library_exports.sh — the package exposes the canonical workflow-sidecar
+# writer/validator as an importable library (issue #99). Guards three things:
+#   1. package.json declares the library entry points (exports/main/types).
+#   2. importing the entry point does NOT execute the CLI (entry guard holds).
+#   3. the CLI still runs when invoked directly (entry guard regression).
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+cd "$ROOT"
+
+errors=0
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+echo "=== Library Export Surface (#99) ==="
+
+# Ensure the build exists (cheap no-op if already built).
+flow_agents_node node_modules/typescript/bin/tsc -p tsconfig.json >/dev/null 2>&1 || npm run build --silent >/dev/null 2>&1 || true
+
+# 1. package.json entry points
+if node -e '
+const p = require("./package.json");
+const fail = (m) => { console.error(m); process.exit(1); };
+if (p.main !== "build/src/index.js") fail("main must be build/src/index.js");
+if (p.types !== "build/src/index.d.ts") fail("types must be build/src/index.d.ts");
+if (!p.exports || !p.exports["."]) fail("exports must define the root entry");
+const root = p.exports["."];
+if (root.import !== "./build/src/index.js") fail("exports[.].import must be ./build/src/index.js");
+if (root.types !== "./build/src/index.d.ts") fail("exports[.].types must be ./build/src/index.d.ts");
+' 2>/tmp/lib-exports-pkg.err; then
+  pass "package.json declares library entry points (main/types/exports)"
+else
+  fail "package.json library entry points missing or wrong: $(cat /tmp/lib-exports-pkg.err)"
+fi
+
+# 2. built artifacts present
+if [[ -f "build/src/index.js" && -f "build/src/index.d.ts" ]]; then
+  pass "build emits index.js and index.d.ts"
+else
+  fail "build is missing index.js or index.d.ts (run npm run build)"
+fi
+
+# 3. importing the library does not run the CLI, and the public API is present.
+# If importing executed the CLI it would call process.exit before our marker prints.
+if node --input-type=module -e '
+import * as lib from "./build/src/index.js";
+const required = [
+  "validateTrustBundle", "normalizeCheck", "normalizeFinding", "normalizeLearning",
+  "normalizeEvidenceRefs", "validateEvidenceRef", "validateLearningCorrection",
+  "loadJson", "writeJson", "appendJsonl", "sidecarBase", "writeState",
+  "readSidecar", "writeSidecar",
+  "statuses", "phases", "checkKinds", "checkStatuses", "verdicts",
+];
+const missing = required.filter((name) => lib[name] === undefined);
+if (missing.length) { console.error("missing exports: " + missing.join(", ")); process.exit(1); }
+// Exercise a validator to prove it is the real implementation, not a stub.
+let threw = false;
+try { lib.normalizeCheck({ id: "x" }); } catch { threw = true; }
+if (!threw) { console.error("normalizeCheck should reject an invalid check"); process.exit(1); }
+const ok = lib.normalizeCheck({ id: "b", kind: "test", status: "pass", summary: "ok" });
+if (ok.id !== "b") { console.error("normalizeCheck should return the normalized check"); process.exit(1); }
+console.log("LIBRARY_IMPORT_OK");
+' 2>/dev/null | grep -q "LIBRARY_IMPORT_OK"; then
+  pass "importing the library exposes the public API without running the CLI"
+else
+  fail "library import failed, ran the CLI, or is missing public exports"
+fi
+
+# 4. the CLI still runs when invoked directly (entry guard regression guard).
+# A missing required flag must produce the CLI's own validation error, proving main() ran.
+cli_out="$(node build/src/cli/workflow-sidecar.js ensure-session --artifact-root /tmp/nonexistent-lib-test 2>&1 || true)"
+if echo "$cli_out" | grep -q "task-slug is required"; then
+  pass "CLI entry still executes when run directly"
+else
+  fail "CLI entry did not run as a script (entry guard regression): $cli_out"
+fi
+
+echo ""
+if [[ "$errors" -gt 0 ]]; then
+  echo "Library export checks failed: $errors issue(s)."
+  exit 1
+fi
+echo "Library export checks passed."

package/evals/static/test_universal_bundles.sh

@@ -411,6 +411,21 @@ else
   _fail "catalog metadata check failed"
 fi
 
+# Block Reason Channel (#100): the generated opencode/pi adapters must carry the
+# policy reason into their block path so the model learns why it was blocked.
+# claude/codex deny translation is covered in test_hook_category_behaviors.sh.
+BUILDER_SRC="$ROOT_DIR/src/tools/build-universal-bundles.ts"
+if grep -q "throw new Error(policyResult.reason" "$BUILDER_SRC"; then
+  _pass "opencode adapter surfaces the block reason to the model (thrown error)"
+else
+  _fail "opencode adapter block path dropped the policy reason"
+fi
+if grep -q "reason: result.reason" "$BUILDER_SRC"; then
+  _pass "pi adapter surfaces the block reason to the model (block result reason)"
+else
+  _fail "pi adapter block path dropped the policy reason"
+fi
+
 echo ""
 echo "==========================="
 total=$((pass + fail))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.3.0",
+  "version": "1.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",
@@ -22,6 +22,15 @@
     "access": "public"
   },
   "type": "module",
+  "main": "build/src/index.js",
+  "types": "build/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/src/index.d.ts",
+      "import": "./build/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kontourai/flow-agents.git"

package/src/cli/workflow-sidecar.ts

@@ -3,21 +3,22 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 type AnyObj = Record<string, any>;
 
-const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
-const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
-const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
-const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
-const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
+export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
+export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
+export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 
 function now(): string { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file: string): string { return fs.readFileSync(file, "utf8"); }
-function writeJson(file: string, payload: AnyObj): void { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
+export function writeJson(file: string, payload: AnyObj): void { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
 function printJson(payload: AnyObj): void { console.log(JSON.stringify(payload).replace(/":/g, '": ').replace(/,"/g, ', "')); }
-function loadJson(file: string, fallback: AnyObj = {}): AnyObj { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
-function appendJsonl(file: string, payload: AnyObj): void {
+export function loadJson(file: string, fallback: AnyObj = {}): AnyObj { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
+export function appendJsonl(file: string, payload: AnyObj): void {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const line = JSON.stringify(payload, Object.keys(payload).sort()).replace(/":/g, '": ').replace(/,"/g, ', "');
   fs.appendFileSync(file, `${line}\n`);
@@ -65,6 +66,20 @@ function getHachureValidator(): ReturnType<typeof tryLoadHachureValidator> {
   return _hachureValidator;
 }
 
+/**
+ * Validate a Hachure trust.bundle against the canonical trust-bundle schema.
+ * Returns `{ valid, errors, available }`. When the optional `hachure` dependency
+ * is not installed, validation is unavailable and this returns
+ * `{ valid: true, errors: [], available: false }` (fail-open) so callers can
+ * choose to treat unvalidated bundles as acceptable or gate on `available`.
+ * This is the same validator the sidecar writer uses for trust-backed evidence.
+ */
+export function validateTrustBundle(bundle: unknown): { valid: boolean; errors: string[]; available: boolean } {
+  const validate = getHachureValidator();
+  if (!validate) return { valid: true, errors: [], available: false };
+  return { ...validate(bundle), available: true };
+}
+
 function safeRepoIdentifier(value: string): string {
   const trimmed = value.trim().replace(/\.git$/, "");
   if (!trimmed || trimmed.length > 120) return "";
@@ -109,7 +124,7 @@ function repoIdentifier(): string {
   return safeRepoIdentifier(path.basename(process.cwd())) || "workspace";
 }
 
-function sidecarBase(slug: string): AnyObj {
+export function sidecarBase(slug: string): AnyObj {
   return { schema_version: "1.0", task_slug: slug, repo: repoIdentifier() };
 }
 
@@ -377,7 +392,7 @@ function hasNonEmptyString(value: unknown): boolean {
 function hasPositiveInteger(value: unknown): boolean {
   return Number.isInteger(value) && Number(value) >= 1;
 }
-function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
+export function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
   if (!["source", "command", "artifact", "provider", "external"].includes(ref.kind)) die(`${label} entry kind must be one of: source, command, artifact, provider, external`);
   for (const key of Object.keys(ref)) if (!["kind", "url", "file", "line_start", "line_end", "excerpt", "summary"].includes(key)) die(`${label} entries contain unsupported field: ${key}`);
   if (ref.url !== undefined && !hasNonEmptyString(ref.url)) die(`${label} entry url must be a non-empty string`);
@@ -393,7 +408,7 @@ function validateEvidenceRef(ref: AnyObj, label: string): AnyObj {
   if ((ref.kind === "provider" || ref.kind === "external") && !hasNonEmptyString(ref.url)) die(`${label} ${ref.kind} refs require url`);
   return ref;
 }
-function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
+export function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
   if (!Array.isArray(raw)) die(`${label} must be an array`);
   return raw.map((ref) => {
     if (typeof ref === "string") die(`${label} entries must be structured evidence reference objects; legacy string refs are not supported`);
@@ -401,7 +416,7 @@ function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[] {
     return validateEvidenceRef({ ...ref as AnyObj }, label);
   });
 }
-function normalizeCheck(raw: AnyObj): AnyObj {
+export function normalizeCheck(raw: AnyObj): AnyObj {
   const check = { ...raw };
   if (!check.id || !check.kind || !check.status || !check.summary) die("check requires id, kind, status, and summary");
   if (!checkKinds.has(check.kind)) die("kind must be one of: build, types, lint, test, security, diff, browser, runtime, policy, external");
@@ -484,7 +499,7 @@ function validateAcceptanceEvidenceRefs(dir: string): void {
     if (criterion.evidence_refs !== undefined) normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
   });
 }
-function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next = "continue"): void {
+export function writeState(dir: string, slug: string, status: string, phase: string, timestamp: string, summary: string, next = "continue"): void {
   writeJson(path.join(dir, "state.json"), { ...loadJson(path.join(dir, "state.json")), ...sidecarBase(slug), status, phase, updated_at: timestamp, artifact_paths: relArtifacts(dir), next_action: { status: next, summary } });
 }
 function recordEvidence(p: ReturnType<typeof parseArgs>): number {
@@ -537,7 +552,7 @@ function advanceState(p: ReturnType<typeof parseArgs>): number {
   return 0;
 }
 
-function normalizeFinding(raw: AnyObj): AnyObj {
+export function normalizeFinding(raw: AnyObj): AnyObj {
   if (raw.file_refs !== undefined && !Array.isArray(raw.file_refs)) die("file_refs must be an array");
   return raw;
 }
@@ -594,7 +609,7 @@ function recordRelease(p: ReturnType<typeof parseArgs>): number {
   writeState(dir, slug, "delivered", "release", payload.updated_at, stateSummary);
   return 0;
 }
-function validateLearningCorrection(record: AnyObj): void {
+export function validateLearningCorrection(record: AnyObj): void {
   const correction = record.correction;
   if (correction === undefined) return;
   if (!correction || typeof correction !== "object" || Array.isArray(correction)) die("correction must be an object");
@@ -624,7 +639,7 @@ function validateLearningPrevention(prevention: unknown): void {
   if (typeof value.status !== "string" || value.status.length === 0) die("correction.prevention.status is required");
   if (!["open", "completed", "accepted", "deferred", "rejected"].includes(value.status)) die("correction.prevention.status must be one of: open, completed, accepted, deferred, rejected");
 }
-function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj {
+export function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj {
   if (!Array.isArray(raw.source_refs)) die("source_refs must be an array");
   if (!Array.isArray(raw.facts)) die("facts must be an array");
   if (!Array.isArray(raw.routing)) die("routing must be an array");
@@ -731,4 +746,11 @@ async function main(): Promise<number> {
   });
 }
 
-main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+// Run the CLI only when executed directly, not when imported as a library.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) {
+  main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * 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: string, name: string): Record<string, any> {
+  return _loadJson(path.join(dir, name));
+}
+
+/** Write a sidecar JSON file into a workflow artifact directory (pretty-printed, trailing newline). */
+export function writeSidecar(dir: string, name: string, payload: Record<string, any>): void {
+  _writeJson(path.join(dir, name), payload);
+}

package/tsconfig.json

@@ -8,6 +8,7 @@
     "types": ["node"],
     "rootDir": ".",
     "outDir": "build",
+    "declaration": true,
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,