@kontourai/flow-agents 1.3.0 → 2.0.0

package/build/src/cli.d.ts

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

package/build/src/cli.js

@@ -14,18 +14,17 @@ import { main as veritasGovernance } from "./cli/veritas-governance.js";
 import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
 import { main as buildBundles } from "./tools/build-universal-bundles.js";
 import { main as contextMap } from "./tools/generate-context-map.js";
-import { main as filterInstalledPacks } from "./tools/filter-installed-packs.js";
 import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
 import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
 import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
 import { main as utteranceCheck } from "./cli/utterance-check.js";
+import { main as verify } from "./cli/verify.js";
 const availableCommands = new Map([
     ["build-bundles", () => buildBundles()],
     ["console-learning-projection", consoleLearningProjection],
     ["context-map", contextMap],
     ["effective-backlog-settings", effectiveBacklogSettings],
-    ["filter-installed-packs", filterInstalledPacks],
     ["fixture-retirement-audit", fixtureRetirementAudit],
     ["kit", kit],
     ["init", init],
@@ -39,6 +38,7 @@ const availableCommands = new Map([
     ["veritas-governance", veritasGovernance],
     ["validate-package", validatePackage],
     ["validate-hook-influence", validateHookInfluence],
+    ["verify", verify],
     ["validate-source", validateSource],
     ["workflow-artifact-cleanup-audit", workflowArtifactCleanupAudit],
 ]);
@@ -47,7 +47,6 @@ const aliases = new Map([
     ["flow-agents-console-learning-projection", "console-learning-projection"],
     ["flow-agents-context-map", "context-map"],
     ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
-    ["flow-agents-filter-installed-packs", "filter-installed-packs"],
     ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
     ["flow-agents-kit", "kit"],
     ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],

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/flow-resolver.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Flow-Definition resolver — ADR 0016 Abstraction A (Option B), Phase P-a.
+ *
+ * Shared resolver consumed by both the producer (workflow-sidecar.ts) and,
+ * later, the enforcer (stop-goal-fit.js via P-c). This is the SINGLE source
+ * of truth for (active_flow_id, active_step_id) → FlowDefinition gate
+ * expects[] resolution. Neither consumer duplicates this logic.
+ *
+ * Design:
+ *   - Pure and synchronous — no async, no throws.
+ *   - Returns null on ENOENT, parse error, or missing gate (fail-open).
+ *   - Kit-agnostic: kitId = flowId.split(".")[0]; no hardcoded kit list.
+ *   - Honors FLOW_AGENTS_FLOW_DEFS_DIR env-var override for custom installs.
+ */
+/**
+ * Build and validate the FlowDefinition file path.
+ *
+ * Returns the validated absolute file path, or null when:
+ *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
+ *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - The resolved path escapes the expected root (belt-and-suspenders)
+ *
+ * When the override is unsafe (points into .flow-agents), falls back silently
+ * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ */
+export declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string): string | null;
+/** A single gate expectation from a FlowDefinition expects[] entry. */
+export type GateExpectation = {
+    id: string;
+    kind: string;
+    required: boolean;
+    bundle_claim: {
+        claimType: string;
+        subjectType: string;
+        accepted_statuses: string[];
+    };
+};
+/** The resolved result from the active flow step. */
+export type ActiveFlowStep = {
+    flowId: string;
+    stepId: string;
+    gateId: string;
+    gateExpects: GateExpectation[];
+};
+/**
+ * Resolve the gate expects[] for a specific (flowId, stepId) pair.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is extracted as the prefix before the first ".".
+ * @param stepId   e.g. "verify" — matched against gate.step values in the FlowDefinition.
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
+ */
+export declare function resolveFlowStep(flowId: string, stepId: string, repoRoot: string): ActiveFlowStep | null;
+/**
+ * Resolve the phase→step mapping from a FlowDefinition's phase_map field.
+ *
+ * Returns the phase_map object (e.g. {"execution":"execute","planning":"plan",...})
+ * or null when the flow file cannot be loaded, the phase_map field is absent, or
+ * the field is not a plain Record<string,string>.
+ *
+ * Pure and synchronous — no throws, fail-open on any error.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns Record<string,string> phase→stepId map, or null on absence/error.
+ */
+export declare function resolvePhaseMap(flowId: string, repoRoot: string): Record<string, string> | null;
+/**
+ * Resolve the active flow step from current.json.
+ *
+ * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
+ * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
+ * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
+ * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
+ * subproject layouts without hardcoding the repo structure.
+ *
+ * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @returns ActiveFlowStep or null when fields are absent or resolution fails.
+ */
+export declare function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null;

package/build/src/lib/flow-resolver.js

@@ -0,0 +1,237 @@
+/**
+ * Flow-Definition resolver — ADR 0016 Abstraction A (Option B), Phase P-a.
+ *
+ * Shared resolver consumed by both the producer (workflow-sidecar.ts) and,
+ * later, the enforcer (stop-goal-fit.js via P-c). This is the SINGLE source
+ * of truth for (active_flow_id, active_step_id) → FlowDefinition gate
+ * expects[] resolution. Neither consumer duplicates this logic.
+ *
+ * Design:
+ *   - Pure and synchronous — no async, no throws.
+ *   - Returns null on ENOENT, parse error, or missing gate (fail-open).
+ *   - Kit-agnostic: kitId = flowId.split(".")[0]; no hardcoded kit list.
+ *   - Honors FLOW_AGENTS_FLOW_DEFS_DIR env-var override for custom installs.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ─── Security: Layer 1 traversal defense ─────────────────────────────────────
+//
+// Both kitId and flowName originate from agent-writable sources (active_flow_id
+// in current.json, and FLOW_AGENTS_FLOW_DEFS_DIR set by the runtime). A crafted
+// value like "builder.../../../.flow-agents/slug/fake-flow" produces:
+//   kitId = "builder"
+//   flowName = "../../../.flow-agents/slug/fake-flow"
+// which resolves OUTSIDE kits/ via path.join traversal.
+//
+// SLUG_RE closes this: it rejects any value containing path separators, dots,
+// or characters outside the safe identifier alphabet. Only [a-zA-Z0-9_-] is
+// allowed, making traversal sequences impossible.
+//
+// Belt-and-suspenders: after building the path we also confirm the resolved
+// absolute path stays inside the expected root directory.
+/** Strict slug pattern — allows only URL-safe identifier chars. */
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Returns true when the given resolved absolute path falls within a .flow-agents
+ * directory (an agent-writable area). Used to reject FLOW_AGENTS_FLOW_DEFS_DIR
+ * overrides that point into agent-controlled storage.
+ */
+function isAgentWritableDir(resolvedDir) {
+    return resolvedDir.split(path.sep).includes(".flow-agents");
+}
+/**
+ * Build and validate the FlowDefinition file path.
+ *
+ * Returns the validated absolute file path, or null when:
+ *  - kitId or flowName contains chars outside SLUG_RE (rejects traversal)
+ *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a .flow-agents directory
+ *  - The resolved path escapes the expected root (belt-and-suspenders)
+ *
+ * When the override is unsafe (points into .flow-agents), falls back silently
+ * to the repoRoot/kits/ path so the resolver still works for legit flows.
+ */
+export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
+    // Primary defense: reject any slug containing traversal chars or non-identifier chars.
+    if (!SLUG_RE.test(kitId) || !SLUG_RE.test(flowName))
+        return null;
+    const override = process.env["FLOW_AGENTS_FLOW_DEFS_DIR"];
+    let expectedRoot;
+    let flowFilePath;
+    if (override) {
+        const resolvedOverride = path.resolve(override);
+        if (isAgentWritableDir(resolvedOverride)) {
+            // Override targets an agent-writable .flow-agents path — reject it and
+            // fall back to the kit root.  The session will resolve the real kit flow.
+            expectedRoot = path.resolve(repoRoot, "kits");
+            flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+        }
+        else {
+            expectedRoot = resolvedOverride;
+            // flowId = kitId + "." + flowName; after slug validation this contains only
+            // [a-zA-Z0-9_-.] — no slashes, no traversal.
+            flowFilePath = path.join(resolvedOverride, `${flowId}.flow.json`);
+        }
+    }
+    else {
+        expectedRoot = path.resolve(repoRoot, "kits");
+        flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+    }
+    // Belt-and-suspenders: confirm the resolved path stays within the expected root.
+    // After slug validation this is theoretically unreachable, but defense-in-depth
+    // verifies the invariant rather than merely asserting it.
+    const resolvedPath = path.resolve(flowFilePath);
+    if (!resolvedPath.startsWith(expectedRoot + path.sep) && resolvedPath !== expectedRoot) {
+        return null; // traversal still detected — paranoid fallback
+    }
+    return resolvedPath;
+}
+/**
+ * Resolve the gate expects[] for a specific (flowId, stepId) pair.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is extracted as the prefix before the first ".".
+ * @param stepId   e.g. "verify" — matched against gate.step values in the FlowDefinition.
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
+ */
+export function resolveFlowStep(flowId, stepId, repoRoot) {
+    if (!flowId || !stepId)
+        return null;
+    const dotIdx = flowId.indexOf(".");
+    if (dotIdx < 1)
+        return null; // flowId must have at least one "." to derive kitId
+    const kitId = flowId.slice(0, dotIdx);
+    // The flow filename is the part after the first "." (e.g. "build" from "builder.build")
+    const flowName = flowId.slice(dotIdx + 1);
+    if (!kitId || !flowName)
+        return null;
+    // Layer 1 defense: validate stepId too — it is matched against gate.step values but
+    // still originates from agent-writable current.json active_step_id.
+    if (!SLUG_RE.test(stepId))
+        return null;
+    // Determine the FlowDefinition file path with slug validation + path containment check.
+    // Returns null for traversal attempts (e.g. flowName = "../../../.flow-agents/fake").
+    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+    if (!flowFilePath)
+        return null;
+    let flowDef;
+    try {
+        const raw = fs.readFileSync(flowFilePath, "utf8");
+        flowDef = JSON.parse(raw);
+    }
+    catch {
+        return null; // ENOENT, permission error, or parse error → fail-open
+    }
+    if (!flowDef || typeof flowDef !== "object" || !flowDef.gates)
+        return null;
+    // Find the gate whose .step matches stepId.
+    for (const [gateId, gate] of Object.entries(flowDef.gates)) {
+        if (!gate || gate.step !== stepId)
+            continue;
+        const expects = Array.isArray(gate.expects) ? gate.expects : [];
+        return { flowId, stepId, gateId, gateExpects: expects };
+    }
+    return null; // no gate matched the given stepId
+}
+/**
+ * Resolve the phase→step mapping from a FlowDefinition's phase_map field.
+ *
+ * Returns the phase_map object (e.g. {"execution":"execute","planning":"plan",...})
+ * or null when the flow file cannot be loaded, the phase_map field is absent, or
+ * the field is not a plain Record<string,string>.
+ *
+ * Pure and synchronous — no throws, fail-open on any error.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns Record<string,string> phase→stepId map, or null on absence/error.
+ */
+export function resolvePhaseMap(flowId, repoRoot) {
+    if (!flowId)
+        return null;
+    const dotIdx = flowId.indexOf(".");
+    if (dotIdx < 1)
+        return null;
+    const kitId = flowId.slice(0, dotIdx);
+    const flowName = flowId.slice(dotIdx + 1);
+    if (!kitId || !flowName)
+        return null;
+    // Layer 1 defense: same slug validation + path containment as resolveFlowStep.
+    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+    if (!flowFilePath)
+        return null;
+    let flowDef;
+    try {
+        const raw = fs.readFileSync(flowFilePath, "utf8");
+        flowDef = JSON.parse(raw);
+    }
+    catch {
+        return null; // ENOENT, permission error, or parse error → fail-open
+    }
+    if (!flowDef || typeof flowDef !== "object")
+        return null;
+    const pm = flowDef.phase_map;
+    if (!pm || typeof pm !== "object" || Array.isArray(pm))
+        return null;
+    // Validate: all values must be strings
+    for (const v of Object.values(pm)) {
+        if (typeof v !== "string")
+            return null;
+    }
+    return pm;
+}
+/**
+ * Find the repository root from a starting directory by walking upward to locate
+ * the nearest ancestor that contains a `kits/` subdirectory. If none is found,
+ * falls back to `process.cwd()` so the default "run from repo root" case still works.
+ *
+ * This is required because the .flow-agents directory can live anywhere (temp dirs,
+ * subprojects, CI workspaces) while the kits/ directory is always at the repo root.
+ */
+function findRepoRoot(startDir) {
+    // Walk up from startDir looking for a kits/ directory
+    let dir = startDir;
+    for (let i = 0; i < 16; i++) {
+        if (fs.existsSync(path.join(dir, "kits")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    // Fallback: process.cwd() covers the common "run from repo root" case
+    return process.cwd();
+}
+/**
+ * Resolve the active flow step from current.json.
+ *
+ * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
+ * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
+ * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
+ * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
+ * subproject layouts without hardcoding the repo structure.
+ *
+ * @param flowAgentsDir Path to the .flow-agents directory (contains current.json).
+ * @returns ActiveFlowStep or null when fields are absent or resolution fails.
+ */
+export function resolveActiveFlowStep(flowAgentsDir) {
+    if (!flowAgentsDir)
+        return null;
+    const currentFile = path.join(flowAgentsDir, "current.json");
+    let current;
+    try {
+        const raw = fs.readFileSync(currentFile, "utf8");
+        current = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
+    const stepId = typeof current["active_step_id"] === "string" ? current["active_step_id"] : null;
+    if (!flowId || !stepId)
+        return null;
+    // Find repoRoot: walk up from flowAgentsDir to find kits/, fallback to cwd
+    const repoRoot = findRepoRoot(path.dirname(flowAgentsDir));
+    return resolveFlowStep(flowId, stepId, repoRoot);
+}

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;