@kontourai/flow-agents 3.2.0 → 3.4.0

package/build/src/runtime-adapters.js

@@ -1,9 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { readJson, relPath, writeJson } from "./lib/fs.js";
+import { atomicCopyFile, atomicWriteJson, ensureSafeDirectory, readJson, relPath } from "./lib/fs.js";
 import { flowAgentsArtifactRoot } from "./lib/local-artifact-root.js";
-import { parseKitDependencies } from "./flow-kit/validate.js";
+import { parseKitDependencies, parseKitHookInfluenceExpectations, parseKitWorkflowTriggers } from "./flow-kit/validate.js";
 const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
 function assetPath(root, value) {
     if (path.isAbsolute(value))
         return null;
@@ -15,7 +16,7 @@ function loadKitAssets(kitRoot, sourceKind, warnings, errors) {
     const manifestPath = path.join(kitRoot, "kit.json");
     if (!fs.existsSync(manifestPath)) {
         errors.push(`${kitRoot}: missing kit.json`);
-        return { kit_id: "", assets: [], dependencies: [] };
+        return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
     }
     let manifest;
     try {
@@ -23,13 +24,13 @@ function loadKitAssets(kitRoot, sourceKind, warnings, errors) {
     }
     catch (error) {
         errors.push(`${manifestPath}: ${error.message}`);
-        return { kit_id: "", assets: [], dependencies: [] };
+        return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
     }
     const kitId = typeof manifest.id === "string" ? manifest.id : "";
     const kitName = typeof manifest.name === "string" ? manifest.name : kitId;
-    if (!kitId) {
-        errors.push(`${manifestPath}: missing kit id`);
-        return { kit_id: "", assets: [], dependencies: [] };
+    if (!KIT_ID_RE.test(kitId)) {
+        errors.push(`${manifestPath}: kit id must be a kebab-case id (^[a-z][a-z0-9-]*$)`);
+        return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
     }
     const assets = [];
     for (const assetClass of ASSET_CLASSES) {
@@ -72,16 +73,55 @@ function loadKitAssets(kitRoot, sourceKind, warnings, errors) {
     // docs/adr/0019-kit-dependency-ownership.md). Shape errors surface at
     // install/inspect/validate time via validateKitRepository; here we only collect
     // the edges so activation can enforce presence against the full inventory.
-    const dependencies = parseKitDependencies(manifest, manifestPath).entries
+    const dependencyResult = parseKitDependencies(manifest, manifestPath);
+    if (dependencyResult.errors.length) {
+        errors.push(...dependencyResult.errors);
+        warnings.push(`${kitId}: invalid dependencies metadata; skipping dependencies`);
+    }
+    const dependencies = dependencyResult.errors.length ? [] : dependencyResult.entries
         .map((dep) => ({ from_kit_id: kitId, kit_id: dep.kit_id, ...(dep.reason ? { reason: dep.reason } : {}) }));
-    return { kit_id: kitId, assets, dependencies };
+    const workflowTriggerResult = parseKitWorkflowTriggers(manifest, manifestPath);
+    if (workflowTriggerResult.errors.length) {
+        errors.push(...workflowTriggerResult.errors);
+        warnings.push(`${kitId}: invalid workflow_triggers metadata; skipping workflow_triggers`);
+    }
+    const workflow_triggers = workflowTriggerResult.errors.length ? [] : workflowTriggerResult.entries
+        .map((trigger) => ({ kit_id: kitId, source_kind: sourceKind, ...trigger }));
+    const hookInfluenceResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
+    if (hookInfluenceResult.errors.length) {
+        errors.push(...hookInfluenceResult.errors);
+        warnings.push(`${kitId}: invalid hook_influence_expectations metadata; skipping hook_influence_expectations`);
+    }
+    const hook_influence_expectations = hookInfluenceResult.errors.length ? [] : hookInfluenceResult.entries
+        .map((expectation) => ({ kit_id: kitId, source_kind: sourceKind, ...expectation }));
+    return { kit_id: kitId, assets, dependencies, workflow_triggers, hook_influence_expectations };
 }
-export function readKitInventory(sourceRoot, dest) {
+function expandKitIdFilter(requested, dependencies, presentKitIds) {
+    if (!requested)
+        return undefined;
+    const selected = new Set(requested);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const dep of dependencies) {
+            if (!selected.has(dep.from_kit_id) || selected.has(dep.kit_id) || !presentKitIds.has(dep.kit_id))
+                continue;
+            selected.add(dep.kit_id);
+            changed = true;
+        }
+    }
+    return selected;
+}
+export function readKitInventory(sourceRoot, dest, options = {}) {
     const warnings = [];
     const errors = [];
     const assets = [];
     const dependencies = [];
+    const workflow_triggers = [];
+    const hook_influence_expectations = [];
+    const loadedKits = [];
     const presentKitIds = new Set();
+    const kitIdFilter = options.kitIdFilter ? new Set(options.kitIdFilter) : undefined;
     const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
     if (!fs.existsSync(catalogPath))
         warnings.push(`${catalogPath}: built-in Kit Catalog not found; skipping built-in kits (this is normal when running outside a flow-agents checkout)`);
@@ -100,8 +140,7 @@ export function readKitInventory(sourceRoot, dest) {
                     warnings.push(`${catalogPath}: kits[${index}].path unavailable: ${rel}`);
                 else {
                     const loaded = loadKitAssets(kitRoot, "builtin", warnings, errors);
-                    assets.push(...loaded.assets);
-                    dependencies.push(...loaded.dependencies);
+                    loadedKits.push(loaded);
                     if (loaded.kit_id)
                         presentKitIds.add(loaded.kit_id);
                 }
@@ -125,14 +164,23 @@ export function readKitInventory(sourceRoot, dest) {
                     warnings.push(`${id}: installed kit copy missing at ${kitRoot}; skipping`);
                 else {
                     const loaded = loadKitAssets(kitRoot, "local", warnings, errors);
-                    assets.push(...loaded.assets);
-                    dependencies.push(...loaded.dependencies);
+                    loadedKits.push(loaded);
                     if (loaded.kit_id)
                         presentKitIds.add(loaded.kit_id);
                 }
             });
         }
     }
+    const allDependencies = loadedKits.flatMap((kit) => kit.dependencies);
+    const selectedKitIds = expandKitIdFilter(kitIdFilter, allDependencies, presentKitIds);
+    for (const loaded of loadedKits) {
+        if (selectedKitIds && !selectedKitIds.has(loaded.kit_id))
+            continue;
+        assets.push(...loaded.assets);
+        dependencies.push(...loaded.dependencies);
+        workflow_triggers.push(...loaded.workflow_triggers);
+        hook_influence_expectations.push(...loaded.hook_influence_expectations);
+    }
     // Activation-time cross-kit dependency enforcement: any declared dependency whose
     // kit_id is not present among the union of built-in catalog kits and locally-installed
     // kits is a hard error (feeds the errors[] -> activation-manifest -> non-zero exit path).
@@ -141,7 +189,7 @@ export function readKitInventory(sourceRoot, dest) {
             errors.push(`${dep.from_kit_id}: declares a dependency on kit '${dep.kit_id}'${dep.reason ? ` (${dep.reason})` : ""} which is not installed or activated. Install it with 'flow-agents kit install <source>' and re-activate, or remove the dependency declaration if it is no longer needed.`);
         }
     }
-    return { assets, warnings, errors };
+    return { assets, dependencies, workflow_triggers, hook_influence_expectations, warnings, errors };
 }
 function safeSegment(value) {
     return value.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[.-]+|[.-]+$/g, "") || "asset";
@@ -151,9 +199,11 @@ function safeSegment(value) {
 // skills: agent guidance markdown copied to skills/<kit-id>/ for agent discovery.
 // docs: documentation markdown copied to docs/<kit-id>/ for agent reference.
 const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
-export function activateCodexLocal(sourceRoot, dest) {
-    const inventory = readKitInventory(sourceRoot, dest);
+export function activateCodexLocal(sourceRoot, dest, options = {}) {
+    const inventory = readKitInventory(sourceRoot, dest, options);
     const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "codex");
+    const writeRoot = path.resolve(runtimeDir, "../../..");
+    ensureSafeDirectory(writeRoot, runtimeDir);
     const generated = [];
     const skipped = [];
     for (const asset of inventory.assets) {
@@ -163,8 +213,7 @@ export function activateCodexLocal(sourceRoot, dest) {
                 continue;
             }
             const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-            fs.mkdirSync(path.dirname(output), { recursive: true });
-            fs.copyFileSync(asset.source_path, output);
+            atomicCopyFile(writeRoot, asset.source_path, output);
             generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
         }
         else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
@@ -179,19 +228,17 @@ export function activateCodexLocal(sourceRoot, dest) {
             const output = asset.asset_class === "skills"
                 ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
                 : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
-            fs.mkdirSync(path.dirname(output), { recursive: true });
-            fs.copyFileSync(asset.source_path, output);
+            atomicCopyFile(writeRoot, asset.source_path, output);
             generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
         }
         else {
             skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by codex-local" });
         }
     }
-    fs.mkdirSync(runtimeDir, { recursive: true });
     const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
     const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
     const manifestPath = path.join(runtimeDir, "activation.json");
-    writeJson(manifestPath, manifest);
+    atomicWriteJson(writeRoot, manifestPath, manifest);
     generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
     return { selected_adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
@@ -201,13 +248,15 @@ export function activateCodexLocal(sourceRoot, dest) {
 // Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
 // mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
 // layout knowledge. The Strands steering layer then reads the written runtime files.
-export function activateStrandsLocal(sourceRoot, dest) {
-    const inventory = readKitInventory(sourceRoot, dest);
+export function activateStrandsLocal(sourceRoot, dest, options = {}) {
+    const inventory = readKitInventory(sourceRoot, dest, options);
     // Runtime flows land at .kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json
     // so the Strands steering context can glob for *.flow.json under this path.
     // Runtime skills land at .kontourai/flow-agents/projections/strands/skills/<kit-id>/<filename> and
     // docs at .kontourai/flow-agents/projections/strands/docs/<kit-id>/<filename> for system-prompt injection.
     const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "strands");
+    const writeRoot = path.resolve(runtimeDir, "../../..");
+    ensureSafeDirectory(writeRoot, runtimeDir);
     const generated = [];
     const skipped = [];
     for (const asset of inventory.assets) {
@@ -217,8 +266,7 @@ export function activateStrandsLocal(sourceRoot, dest) {
                 continue;
             }
             const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-            fs.mkdirSync(path.dirname(output), { recursive: true });
-            fs.copyFileSync(asset.source_path, output);
+            atomicCopyFile(writeRoot, asset.source_path, output);
             generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
         }
         else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
@@ -233,19 +281,17 @@ export function activateStrandsLocal(sourceRoot, dest) {
             const output = asset.asset_class === "skills"
                 ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
                 : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
-            fs.mkdirSync(path.dirname(output), { recursive: true });
-            fs.copyFileSync(asset.source_path, output);
+            atomicCopyFile(writeRoot, asset.source_path, output);
             generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
         }
         else {
             skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by strands-local" });
         }
     }
-    fs.mkdirSync(runtimeDir, { recursive: true });
     const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
     const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
     const manifestPath = path.join(runtimeDir, "activation.json");
-    writeJson(manifestPath, manifest);
+    atomicWriteJson(writeRoot, manifestPath, manifest);
     generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
     return { selected_adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }

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

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
+import { CODEX_REASONING_EFFORTS, codexAgentRoutingErrors } from "./codex-agent-routing.js";
 import { DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR } from "../lib/local-artifact-root.js";
 const dist = process.env.FLOW_AGENTS_DIST_DIR ? path.resolve(process.env.FLOW_AGENTS_DIST_DIR) : path.join(root, "dist");
 const manifest = loadJson(path.join(root, "packaging/manifest.json"));
@@ -196,8 +197,39 @@ function mapped(mapName, value) {
     const map = manifest[mapName];
     return map[modelPrefix(String(value ?? ""))] ?? map.default;
 }
+function codexAgentOverride(spec) {
+    const override = manifest.codex_agent_map?.[spec.name];
+    if (override === undefined)
+        return undefined;
+    if (!override || typeof override !== "object" || Array.isArray(override)) {
+        throw new Error(`packaging/manifest.json: codex_agent_map.${spec.name} must be an object`);
+    }
+    const keys = Object.keys(override).sort();
+    if (keys.join(",") !== "model,reasoning_effort") {
+        throw new Error(`packaging/manifest.json: codex_agent_map.${spec.name} must contain exactly model and reasoning_effort`);
+    }
+    return override;
+}
+function validateCodexModel(model, context) {
+    const allowed = new Set(manifest.codex?.allowed_agent_models ?? []);
+    if (!allowed.has(model))
+        throw new Error(`packaging/manifest.json: ${context} uses unsupported Codex agent model '${model}'`);
+    return model;
+}
 function resolveCodexModel(spec) {
-    return ["tool-agent-delegate", "tool-agent-handoff"].includes(spec.name) ? "gpt-5.4-mini" : mapped("codex_model_map", spec.model);
+    const override = codexAgentOverride(spec)?.model;
+    if (typeof override === "string" && override)
+        return validateCodexModel(override, `codex_agent_map.${spec.name}.model`);
+    const fallback = ["tool-agent-delegate", "tool-agent-handoff"].includes(spec.name) ? "gpt-5.4-mini" : mapped("codex_model_map", spec.model);
+    return validateCodexModel(fallback, `resolved model for ${spec.name}`);
+}
+function resolveCodexReasoningEffort(spec) {
+    const override = codexAgentOverride(spec)?.reasoning_effort;
+    const effort = typeof override === "string" && override ? override : mapped("codex_reasoning_map", spec.model);
+    if (!CODEX_REASONING_EFFORTS.has(effort)) {
+        throw new Error(`packaging/manifest.json: resolved reasoning effort for ${spec.name} is invalid: '${effort}'`);
+    }
+    return effort;
 }
 function normalizeCodexText(text) {
     const replacements = { "—": "-", "–": "-", "→": "->", "←": "<-", "’": "'", "“": '"', "”": '"', "⚡": "[quick]", "🖥️": "[interactive]" };
@@ -239,7 +271,7 @@ function codexNicknames(agentName) {
 function exportCodexAgent(spec) {
     const prompt = appendExportNote(normalizeCodexText(sanitizeText(spec.prompt, "codex", "<bundle-root>")), "Exported from a Kiro agent spec. Hooks, resource auto-loading, and tool allowlists were converted into prompt guidance only. Any explicit Kiro scheduler commands are preserved as optional shell workflows.");
     const description = normalizeCodexText(String(spec.description ?? "")).replace(/"/g, "'");
-    return `# exported from agents/${spec.name}.json\nname = "${spec.name}"\nnickname_candidates = ${JSON.stringify(codexNicknames(spec.name))}\ndescription = "${description}"\nmodel = "${resolveCodexModel(spec)}"\nmodel_reasoning_effort = "${mapped("codex_reasoning_map", spec.model)}"\ndeveloper_instructions = ${JSON.stringify(prompt)}\n`;
+    return `# exported from agents/${spec.name}.json\nname = "${spec.name}"\nnickname_candidates = ${JSON.stringify(codexNicknames(spec.name))}\ndescription = "${description}"\nmodel = "${resolveCodexModel(spec)}"\nmodel_reasoning_effort = "${resolveCodexReasoningEffort(spec)}"\ndeveloper_instructions = ${JSON.stringify(prompt)}\n`;
 }
 function tomlValue(value) {
     if (typeof value === "boolean")
@@ -763,6 +795,12 @@ export function main() {
         return 1;
     }
     const agents = fs.readdirSync(path.join(root, "agents")).filter((name) => name.endsWith(".json")).sort().map((name) => loadJson(path.join(root, "agents", name)));
+    const routingErrors = codexAgentRoutingErrors(manifest, agents.map((agent) => agent.name));
+    if (routingErrors.length) {
+        for (const error of routingErrors)
+            console.error(`flow-agents: packaging/manifest.json: ${error}`);
+        return 1;
+    }
     buildBase(agents);
     buildKiro(agents);
     buildClaudeCode(agents);

package/build/src/tools/codex-agent-routing.d.ts

@@ -0,0 +1,2 @@
+export declare const CODEX_REASONING_EFFORTS: Set<string>;
+export declare function codexAgentRoutingErrors(manifest: any, agentNames: Iterable<string>): string[];

package/build/src/tools/codex-agent-routing.js

@@ -0,0 +1,49 @@
+export const CODEX_REASONING_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max", "ultra"]);
+export function codexAgentRoutingErrors(manifest, agentNames) {
+    const errors = [];
+    const knownAgents = new Set(agentNames);
+    const allowedModels = manifest.codex?.allowed_agent_models;
+    if (!Array.isArray(allowedModels) || allowedModels.length === 0) {
+        errors.push("codex.allowed_agent_models must be a non-empty list");
+    }
+    const allowedModelSet = new Set(Array.isArray(allowedModels) ? allowedModels : []);
+    for (const model of allowedModelSet) {
+        if (typeof model !== "string" || !model)
+            errors.push("codex.allowed_agent_models entries must be non-empty strings");
+    }
+    if (allowedModelSet.size !== (Array.isArray(allowedModels) ? allowedModels.length : 0)) {
+        errors.push("codex.allowed_agent_models must not contain duplicates");
+    }
+    for (const [family, model] of Object.entries(manifest.codex_model_map ?? {})) {
+        if (!allowedModelSet.has(model))
+            errors.push(`codex_model_map.${family} uses unsupported model '${String(model)}'`);
+    }
+    for (const [family, effort] of Object.entries(manifest.codex_reasoning_map ?? {})) {
+        if (!CODEX_REASONING_EFFORTS.has(String(effort)))
+            errors.push(`codex_reasoning_map.${family} uses invalid reasoning effort '${String(effort)}'`);
+    }
+    const agentMap = manifest.codex_agent_map;
+    if (!agentMap || typeof agentMap !== "object" || Array.isArray(agentMap)) {
+        errors.push("codex_agent_map must be an object");
+        return errors;
+    }
+    for (const [agentName, override] of Object.entries(agentMap)) {
+        if (!knownAgents.has(agentName))
+            errors.push(`codex_agent_map agent '${agentName}' does not exist`);
+        if (!override || typeof override !== "object" || Array.isArray(override)) {
+            errors.push(`codex_agent_map.${agentName} must be an object`);
+            continue;
+        }
+        const entry = override;
+        if (Object.keys(entry).sort().join(",") !== "model,reasoning_effort") {
+            errors.push(`codex_agent_map.${agentName} must contain exactly model and reasoning_effort`);
+        }
+        if (!allowedModelSet.has(entry.model)) {
+            errors.push(`codex_agent_map.${agentName}.model uses unsupported model '${String(entry.model)}'`);
+        }
+        if (!CODEX_REASONING_EFFORTS.has(String(entry.reasoning_effort))) {
+            errors.push(`codex_agent_map.${agentName}.reasoning_effort is invalid: '${String(entry.reasoning_effort)}'`);
+        }
+    }
+    return errors;
+}

package/build/src/tools/generate-context-map.js

@@ -27,6 +27,7 @@ const commands = [
     ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
     ["Context map drift", "npm run context-map:check"],
     ["Bundle build", "npm run build:bundles"],
+    ["Skill drift check", "flow-agents skill-drift-check"],
 ];
 function frontmatter(text) {
     if (!text.startsWith("---"))

package/build/src/tools/validate-source-tree.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { validateKitRepository as validateFlowKitRepository } from "../flow-kit/validate.js";
+import { codexAgentRoutingErrors } from "./codex-agent-routing.js";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
 class Reporter {
     errors = [];
@@ -31,6 +32,8 @@ const mirroredFiles = new Map([
     // fails `npm run validate:source` instead of silently accumulating.
     ["scripts/hooks/config-protection.js", { mirror: "context/scripts/hooks/config-protection.js", allowedDifferences: [] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { mirror: "context/scripts/hooks/lib/config-protection-remedies.js", allowedDifferences: [] }],
+    ["scripts/hooks/lib/kit-catalog.js", { mirror: "context/scripts/hooks/lib/kit-catalog.js", allowedDifferences: [] }],
+    ["scripts/hooks/lib/runnable-command.js", { mirror: "context/scripts/hooks/lib/runnable-command.js", allowedDifferences: [] }],
     ["scripts/hooks/stop-goal-fit.js", { mirror: "context/scripts/hooks/stop-goal-fit.js", allowedDifferences: [] }],
     ["scripts/hooks/run-hook.js", { mirror: "context/scripts/hooks/run-hook.js", allowedDifferences: [] }],
     ["scripts/hooks/workflow-steering.js", { mirror: "context/scripts/hooks/workflow-steering.js", allowedDifferences: [] }],
@@ -82,9 +85,11 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
     ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
+    ["scripts/hooks/lib/codex-exit-code.js", { category: "shared hook library", requiredNeedles: ["extractExitCodeFromBanner", "readExitCodeFromRollout"] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
     ["scripts/hooks/lib/current-pointer.js", { category: "shared hook library", requiredNeedles: ["readCurrentPointer", "perActorCurrentFile"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
+    ["scripts/hooks/lib/kit-catalog.js", { category: "shared hook library", requiredNeedles: ["readKitManifests", "workflowTriggersFor"] }],
     ["scripts/hooks/lib/liveness-heartbeat.js", { category: "shared hook library", requiredNeedles: ["maybeEmitHeartbeat", "resolveHeartbeatThrottleSeconds"] }],
     ["scripts/hooks/lib/liveness-policy.js", { category: "shared hook library", requiredNeedles: ["isLivenessEnabled", "resolveTtlSeconds"] }],
     ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
@@ -92,20 +97,26 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/local-artifact-paths.js", { category: "shared hook library", requiredNeedles: ["flowAgentsArtifactRoot", "defaultArtifactRootForRead"] }],
     ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
+    ["scripts/hooks/lib/runnable-command.js", { category: "shared hook library", requiredNeedles: ["isRunnableCommandText"] }],
+    ["scripts/hooks/lib/skill-drift.js", { category: "shared hook library", requiredNeedles: ["compareSkillDrift", "buildManifest"] }],
 ]);
 const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh", "evals/integration/test_ensure_session_ownership_guard.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290); hostile-effective-state.json is the #291 ensure-session ownership guard's AC9 sanitization fixture" }],
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
+    ["evals/fixtures/economics", { owners: ["evals/integration/test_economics_record.sh"], classification: "per-run kit-economics record fixtures (#349): a transcript with .message.usage blocks, state.json/acceptance.json/critique.json join sources, a session.usage event, and the golden expected kontour.console.economics record" }],
     ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
     ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
     ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
+    ["evals/fixtures/learning-review-proposals", { owners: ["evals/integration/test_learning_review_proposals.sh"], classification: "learning-review kit/gate tuning proposal fixtures (#352): pattern-present (engineered cost-inflation + gate false-block-rate pattern, with sessions/ trust.bundle + gate-review.inquiries.json joins and a hand-computed expected-aggregates.json), balanced (proportional cost/findings movement -> zero proposals), under-threshold (below LR_MIN_WINDOW_SAMPLE), repeat-window (idempotency), and effect-follow-up (later-window effect-fill pass for a ratified proposal)" }],
     ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
     ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
     ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
-    ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions)" }],
-    ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture" }],
+    ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end" }],
+    ["evals/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
+    ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies)" }],
+    ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],
     ["evals/fixtures/trust-reconcile-ws3", { owners: ["evals/integration/test_trust_reconcile_negatives.sh"], classification: "WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle" }],
     ["evals/fixtures/usage-feedback", { owners: ["evals/integration/test_usage_feedback_import.sh", "evals/integration/test_usage_feedback_outcomes.sh", "evals/integration/test_usage_feedback_report.sh"], classification: "usage feedback import/outcome fixtures" }],
     ["evals/fixtures/veritas-governance-adapter", { owners: ["evals/integration/test_veritas_governance_adapter.sh"], classification: "Veritas governance adapter fixtures" }],
@@ -129,6 +140,9 @@ const allowedPythonCommandFiles = [
     // as prose). These are literal recognizer tokens, NOT a flow-agents Python dependency — no
     // .py file is ever invoked — so the two byte-identical mirror copies are exempt here.
     /^(context\/)?scripts\/hooks\/stop-goal-fit\.js$/,
+    // #412: the recognizer allowlist itself now lives in scripts/hooks/lib/runnable-command.js
+    // (single source of truth), so the same literal-token exemption applies there too.
+    /^(context\/)?scripts\/hooks\/lib\/runnable-command\.js$/,
 ];
 function tryLoadJson(file, reporter) {
     try {
@@ -216,6 +230,8 @@ function validateManifest(reporter, manifest, agentNames) {
             console.log(`warning: ${rel(manifestPath)} optional_copy_dirs entry absent: ${dir}`);
     for (const agent of manifest.codex?.excluded_agents ?? [])
         reporter.check(agentNames.has(agent), `${rel(manifestPath)}: codex excluded agent '${agent}' does not exist`);
+    for (const error of codexAgentRoutingErrors(manifest, agentNames))
+        reporter.fail(`${rel(manifestPath)}: ${error}`);
 }
 async function validateKitRepository(kitDir, reporter) {
     if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
@@ -273,6 +289,16 @@ function validateLegacyRefs(reporter) {
     // Collect all kit-owned asset relative paths so legacy-ref scanning can skip matches
     // that are subpaths of kit-owned assets. E.g. legacyRefRe matches "skills/plan-work/SKILL.md"
     // within "kits/builder/skills/plan-work/SKILL.md"; the kit declares and validates these.
+    //
+    // Deliberately NO directory-level exemption: a ref must be an exact registered path, or a
+    // parent directory of one, to be skipped. A kit that ships a helper file living alongside a
+    // registered asset (e.g. a skill's own script next to its SKILL.md) must register that
+    // helper as its own kit.json entry (e.g. under an "assets" section) rather than relying on
+    // sibling-directory proximity — widening the exemption to "any file in the same directory
+    // as a registered path" would silence real missing-path detection for every OTHER file that
+    // happens to sit next to a registered asset, not just the intended one. See
+    // kits/veritas-governance/kit.json's "assets" section for the registration this exact case
+    // uses.
     const kitOwnedSubPaths = new Set();
     const kitsDir = path.join(root, "kits");
     if (fs.existsSync(kitsDir)) {
@@ -311,7 +337,8 @@ function validateLegacyRefs(reporter) {
                 continue;
             // Skip refs that are declared kit-owned asset paths or their parent directories
             // (e.g. "skills/plan-work/SKILL.md" or "skills/plan-work" matched inside
-            // "kits/builder/skills/plan-work/SKILL.md" in eval files).
+            // "kits/builder/skills/plan-work/SKILL.md" in eval files). No directory-level
+            // exemption — see the kitOwnedSubPaths comment above.
             if (kitOwnedSubPaths.has(ref) || [...kitOwnedSubPaths].some((p) => p.startsWith(ref + "/")))
                 continue;
             const candidates = [path.join(root, ref), ...(ref.startsWith("evals/") ? [] : [path.join(root, "evals", ref)])];

package/context/contracts/artifact-contract.md

@@ -44,8 +44,7 @@ candidate selector — do not build new discovery logic. `active_wip`,
 `active_learning_followup`, `cleanup_candidate`, and `invalid` sessions are **never**
 archival candidates on age alone.
 
-Procedure (documented; archival itself remains a deliberate, non-automated move — the audit
-tool "does not delete, archive," by design):
+Procedure (manual, hand-driven):
 
 1. `node build/src/cli/workflow-artifact-cleanup-audit.js <artifact-root>` to classify.
 2. From the `terminal_done` bucket, select those whose `state.json` `updatedAt` predates the
@@ -53,6 +52,21 @@ tool "does not delete, archive," by design):
 3. Move each selected `<artifact-root>/<slug>/` to `<artifact-root>/archive/<slug>/`
    (a human-reviewed or explicitly-invoked move — not a silent background job).
 
+Automated `--apply` mode: `workflow-artifact-cleanup-audit --apply` (see
+`docs/workflow-artifact-lifecycle.md`'s "Apply Mode" section) automates the
+`cleanup_candidate`/aged-`terminal_done` selection above, but archive-moves to a
+*different*, sibling destination — `.kontourai/flow-agents-archive/<date>-<runid>/<slug>/`,
+next to the artifact root, not `<artifact-root>/archive/<slug>/`. The run-scoped,
+sibling root keeps two same-day `--apply` runs from colliding and keeps the artifact
+root's own scan set stable while a run is in progress; it is not a replacement for the
+in-tree `<artifact-root>/archive/<slug>/` convention above, which remains the right
+destination for a manual, hand-driven move. `--apply` never deletes anything (archive-move
+only) and is gated by hard safety rails (never `active_wip`/`active_learning_followup`,
+never a held liveness claim, never inside the freshness window, never an infrastructure
+directory, never a substantive session misclassified `invalid` by a schema nit) — see the
+doc section for the full model, including the `--apply-ambiguous` second gate and the
+`MANIFEST.md`/`--confirm` evidence record.
+
 ## Persistence Integrity
 
 Writing a durable artifact must **fail loud, never fail-open.** If a record (state, evidence, a