@kontourai/flow-agents 2.3.0 → 3.0.0

package/build/src/runtime-adapters.js

@@ -1,6 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readJson, relPath, writeJson } from "./lib/fs.js";
+import { flowAgentsArtifactRoot } from "./lib/local-artifact-root.js";
+import { parseKitDependencies } from "./flow-kit/validate.js";
 const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
 function assetPath(root, value) {
     if (path.isAbsolute(value))
@@ -13,7 +15,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 [];
+        return { kit_id: "", assets: [], dependencies: [] };
     }
     let manifest;
     try {
@@ -21,13 +23,13 @@ function loadKitAssets(kitRoot, sourceKind, warnings, errors) {
     }
     catch (error) {
         errors.push(`${manifestPath}: ${error.message}`);
-        return [];
+        return { kit_id: "", assets: [], dependencies: [] };
     }
     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 [];
+        return { kit_id: "", assets: [], dependencies: [] };
     }
     const assets = [];
     for (const assetClass of ASSET_CLASSES) {
@@ -66,12 +68,20 @@ function loadKitAssets(kitRoot, sourceKind, warnings, errors) {
             assets.push({ kit_id: kitId, kit_name: kitName, asset_class: assetClass, asset_id: assetId, relative_path: rel, source_path: source, source_kind: sourceKind, description });
         }
     }
-    return assets;
+    // Parse cross-kit dependency declarations (extension-layer metadata; see
+    // 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
+        .map((dep) => ({ from_kit_id: kitId, kit_id: dep.kit_id, ...(dep.reason ? { reason: dep.reason } : {}) }));
+    return { kit_id: kitId, assets, dependencies };
 }
 export function readKitInventory(sourceRoot, dest) {
     const warnings = [];
     const errors = [];
     const assets = [];
+    const dependencies = [];
+    const presentKitIds = new Set();
     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)`);
@@ -88,8 +98,13 @@ export function readKitInventory(sourceRoot, dest) {
                 const kitRoot = assetPath(sourceRoot, rel);
                 if (!kitRoot || !fs.existsSync(kitRoot))
                     warnings.push(`${catalogPath}: kits[${index}].path unavailable: ${rel}`);
-                else
-                    assets.push(...loadKitAssets(kitRoot, "builtin", warnings, errors));
+                else {
+                    const loaded = loadKitAssets(kitRoot, "builtin", warnings, errors);
+                    assets.push(...loaded.assets);
+                    dependencies.push(...loaded.dependencies);
+                    if (loaded.kit_id)
+                        presentKitIds.add(loaded.kit_id);
+                }
             });
         }
     }
@@ -108,11 +123,24 @@ export function readKitInventory(sourceRoot, dest) {
                 const kitRoot = path.join(dest, "kits", "local", "repositories", id);
                 if (!fs.existsSync(kitRoot))
                     warnings.push(`${id}: installed kit copy missing at ${kitRoot}; skipping`);
-                else
-                    assets.push(...loadKitAssets(kitRoot, "local", warnings, errors));
+                else {
+                    const loaded = loadKitAssets(kitRoot, "local", warnings, errors);
+                    assets.push(...loaded.assets);
+                    dependencies.push(...loaded.dependencies);
+                    if (loaded.kit_id)
+                        presentKitIds.add(loaded.kit_id);
+                }
             });
         }
     }
+    // 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).
+    for (const dep of dependencies) {
+        if (!presentKitIds.has(dep.kit_id)) {
+            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 };
 }
 function safeSegment(value) {
@@ -125,7 +153,7 @@ function safeSegment(value) {
 const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
 export function activateCodexLocal(sourceRoot, dest) {
     const inventory = readKitInventory(sourceRoot, dest);
-    const runtimeDir = path.join(dest, ".flow-agents", "runtime", "codex");
+    const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "codex");
     const generated = [];
     const skipped = [];
     for (const asset of inventory.assets) {
@@ -144,7 +172,13 @@ export function activateCodexLocal(sourceRoot, dest) {
             // agent's guidance index (AGENTS.md) can reference them and they are co-located
             // with flow definitions for the same kit.
             const filename = path.basename(asset.source_path);
-            const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+            // Namespace skills by BOTH kit id AND the skill's own directory name: every skill
+            // file is literally named SKILL.md, so keying only on kit id collides all of a
+            // kit's skills onto one .../<kit-id>/SKILL.md file. Docs keep the flat
+            // <kit-id>/<filename> layout (no per-directory collision found).
+            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);
             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("/") });
@@ -169,11 +203,11 @@ export function activateCodexLocal(sourceRoot, dest) {
 // layout knowledge. The Strands steering layer then reads the written runtime files.
 export function activateStrandsLocal(sourceRoot, dest) {
     const inventory = readKitInventory(sourceRoot, dest);
-    // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+    // 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 .flow-agents/runtime/strands/skills/<kit-id>/<filename> and
-    // docs at .flow-agents/runtime/strands/docs/<kit-id>/<filename> for system-prompt injection.
-    const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+    // 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 generated = [];
     const skipped = [];
     for (const asset of inventory.assets) {
@@ -190,9 +224,15 @@ export function activateStrandsLocal(sourceRoot, dest) {
         else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
             // Mirror the codex-local layout: strands/<class>/<kit-id>/<filename>.
             // The Strands system-prompt injection layer can glob for all *.md files under
-            // .flow-agents/runtime/strands/skills/ to include agent guidance in the context.
+            // .kontourai/flow-agents/projections/strands/skills/ to include agent guidance in the context.
             const filename = path.basename(asset.source_path);
-            const output = path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
+            // Namespace skills by BOTH kit id AND the skill's own directory name: every skill
+            // file is literally named SKILL.md, so keying only on kit id collides all of a
+            // kit's skills onto one .../<kit-id>/SKILL.md file. Docs keep the flat
+            // <kit-id>/<filename> layout (no per-directory collision found).
+            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);
             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("/") });

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

@@ -3,11 +3,19 @@ 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 { 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"));
 const pkgVersion = loadJson(path.join(root, "package.json"))["version"] ?? "0.0.0";
+const runtimeTaskDir = FLOW_AGENTS_RUNTIME_DIR;
+const durableInstallRecordRel = `${DURABLE_FLOW_AGENTS_DIR}/install.json`;
 const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", ".toml", ".txt", ".yaml", ".yml", ".ts"]);
 const dropDiagnostics = [];
+// Set by collectAllSkills() when two kits (or a kit and the top-level skills/
+// dir) declare the same skill directory name. Reported via the same
+// console.error + process.exitCode diagnostic idiom as the rest of this file
+// (see main()) instead of an uncaught thrown Error / stack trace.
+let skillCollisionDiagnostic = null;
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
 /**
  * Collect all skill source paths across skills/ and kit-owned skills.
@@ -18,16 +26,28 @@ const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_
  */
 function collectAllSkills() {
     const results = [];
-    const seen = new Set();
+    const seen = new Map(); // skill name -> source description of first declaration
+    const collisions = [];
+    // Compiled host bundles ship skills flat at .claude/skills/<name>/SKILL.md etc., so
+    // the install name (skill directory name) must be globally unique across skills/ and
+    // every kit. A duplicate is a build-FAILING collision, never a silent drop — the
+    // previous Set-based dedupe silently kept only the first and discarded the rest.
+    const recordSkill = (name, src, source) => {
+        const prior = seen.get(name);
+        if (prior !== undefined) {
+            collisions.push(`  - '${name}' is declared by both ${prior} and ${source}`);
+            return;
+        }
+        seen.set(name, source);
+        results.push({ name, src });
+    };
     // 1. Top-level skills/ directory (tools pending reclassification).
     const skillsDir = path.join(root, "skills");
     if (fs.existsSync(skillsDir)) {
         for (const skill of fs.readdirSync(skillsDir).sort()) {
             const skillPath = path.join(skillsDir, skill, "SKILL.md");
-            if (fs.existsSync(skillPath) && !seen.has(skill)) {
-                seen.add(skill);
-                results.push({ name: skill, src: skillPath });
-            }
+            if (fs.existsSync(skillPath))
+                recordSkill(skill, skillPath, "skills/");
         }
     }
     // 2. Kit-owned skills declared in kits/<kit>/kit.json `skills` arrays.
@@ -55,13 +75,18 @@ function collectAllSkills() {
                 // Derive install name from the directory containing SKILL.md (one level up).
                 const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
                 const skillName = path.basename(path.dirname(absPath));
-                if (fs.existsSync(absPath) && !seen.has(skillName)) {
-                    seen.add(skillName);
-                    results.push({ name: skillName, src: absPath });
-                }
+                if (fs.existsSync(absPath))
+                    recordSkill(skillName, absPath, `kits/${kitName}`);
             }
         }
     }
+    if (collisions.length) {
+        skillCollisionDiagnostic =
+            "flow-agents: skill name collision — skill directory names must be unique across " +
+                "skills/ and all kits/*/kit.json:\n" +
+                collisions.join("\n") +
+                "\nRename one of the colliding skill directories so every compiled bundle skill has a unique install name.";
+    }
     return results.sort((a, b) => a.name.localeCompare(b.name));
 }
 function resetDir(dir) {
@@ -190,7 +215,7 @@ function generatedAgentsSummary(agents) {
 function exportRootAgentsMd(label, agents, taskDir) {
     return `# Universal Agent Bundle (${label})\n\nThis bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.\n\n## Shared Conventions\n\n- \`skills/\`, \`context/\`, \`powers/\`, \`prompts/\`, \`scripts/\`, and \`evals/\` were copied from the canonical source.\n- Cross-session task artifacts should live under \`${taskDir}\`.\n- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.\n\n## Exported Agents\n\n${generatedAgentsSummary(agents)}\n`;
 }
-const CODEX_LIVE_HOOKS_README = `\n## Running with hooks active (live)\n\n\`install.sh\` lays the bundle into a workspace, but a live Codex session needs a \`CODEX_HOME\` that has both the bundle's hooks/scripts AND your real credentials. Use the dedicated installer, which flattens the config to the home root and copies your auth from \`~/.codex\`:\n\n\`\`\`bash\nbash scripts/install-codex-home.sh "$HOME/.flow-agents/codex"\nCODEX_HOME="$HOME/.flow-agents/codex" codex exec --dangerously-bypass-hook-trust -C /path/to/project "<prompt>"\n\`\`\`\n\nThe goal-fit Stop hook then enforces by default (\`FLOW_AGENTS_GOAL_FIT_MODE=block\`); set it to \`warn\` or \`off\` to override.\n`;
+const CODEX_LIVE_HOOKS_README = `\n## Running with hooks active (live)\n\n\`install.sh\` lays the bundle into a workspace, but a live Codex session needs a \`CODEX_HOME\` that has both the bundle's hooks/scripts AND your real credentials. Use the dedicated installer, which defaults to \`CODEX_HOME\` when set and otherwise \`~/.codex\`, flattens the config to the home root, and copies your auth from \`~/.codex\` when installing elsewhere:\n\n\`\`\`bash\nbash scripts/install-codex-home.sh\ncodex exec --dangerously-bypass-hook-trust -C /path/to/project \"<prompt>\"\n\`\`\`\n\nPass a positional destination to install into an explicit alternate Codex home.\n\nThe goal-fit Stop hook then enforces by default (\`FLOW_AGENTS_GOAL_FIT_MODE=block\`); set it to \`warn\` or \`off\` to override.\n`;
 function exportTargetReadme(label, installHint, extra = "") {
     return `# ${label} Bundle\n\nGenerated from the canonical source in this repository.\n\n## Install\n\n\`\`\`bash\n${installHint}\n\`\`\`\n\nThe install ships the full standalone base (skills, agents, powers) plus the\nFlow Kits. Kit depth is activated through the Kit Catalog, not at install time.\n\n## Contents\n\n- Harness-specific agents\n- Shared skills\n- Shared context, powers, prompts, scripts, and evals\n${extra}`;
 }
@@ -282,7 +307,7 @@ function claudePolicy(event, script, envPrefix = "") {
     return `bash -lc 'root="\${CLAUDE_PROJECT_DIR:-$(pwd)}"; ${envPrefix}node "$root/scripts/hooks/claude-hook-adapter.js" ${event} ${script.replace(/\.js$/, "")} ${script} default'`;
 }
 function codexRoot(scriptPath) {
-    return `root="\${CODEX_HOME:-}"; if [ -z "$root" ] || [ ! -f "$root/${scriptPath}" ]; then root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); fi`;
+    return `root="\${CODEX_HOME:-}"; if [ -z "$root" ] || [ ! -f "$root/${scriptPath}" ]; then root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); fi; if [ ! -f "$root/${scriptPath}" ] && [ -f "$HOME/.codex/${scriptPath}" ]; then root="$HOME/.codex"; fi; if [ ! -f "$root/${scriptPath}" ]; then echo "flow-agents: hook script not found at $root/${scriptPath} (checked \\$CODEX_HOME, git toplevel/cwd, and \\$HOME/.codex) - skipping hook" >&2; exit 0; fi`;
 }
 function codexTelemetry(event) {
     if (event === "PermissionRequest")
@@ -358,9 +383,9 @@ function installScript(label, defaultDestDisplay, token, destFallbackShell, merg
     const requiredCheck = destRequired ? `if [[ -z "$DEST" ]]; then\n  usage\n  exit 2\nfi\n` : "";
     const usageDest = destRequired ? "/path/to/workspace" : defaultDestDisplay;
     const mergeBlock = mergeConfig
-        ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --config "$DEST/${mergeConfig.configRelPath}" --managed-hooks "$SRC/${mergeConfig.managedConfigRelPath}" --version "${mergeConfig.version}" --install-record "$DEST/.flow-agents/install.json" --runtime "${mergeConfig.runtime}" || true\nfi`
+        ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --config "$DEST/${mergeConfig.configRelPath}" --managed-hooks "$SRC/${mergeConfig.managedConfigRelPath}" --version "${mergeConfig.version}" --install-record "$DEST/${durableInstallRecordRel}" --runtime "${mergeConfig.runtime}" || true\nfi`
         : stampConfig
-            ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --stamp-only --version "${stampConfig.version}" --install-record "$DEST/.flow-agents/install.json" --runtime "${stampConfig.runtime}" || true\nfi`
+            ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --stamp-only --version "${stampConfig.version}" --install-record "$DEST/${durableInstallRecordRel}" --runtime "${stampConfig.runtime}" || true\nfi`
             : "";
     return `#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nusage: bash install.sh ${usageDest} [options]\n\nOptions:\n  --telemetry-sink NAME   local-files, local-kontour-console,\n                          kontour-hosted-console, user-hosted-console,\n                          or legacy aliases. May be repeated.\n  --console-url URL       Persist Console telemetry base URL.\n  --console-endpoint URL  Persist full Console telemetry records endpoint URL.\n  --console-token-file PATH\n                          Read Console telemetry bearer token from a file.\n  --console-tenant ID     Persist Console tenant identifier.\nEOF\n}\n\nDEST=""\nDEST_SET=0\nCONSOLE_CONFIG_ARGS=()\nwhile [[ $# -gt 0 ]]; do\n  case "$1" in\n    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)\n      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }\n      CONSOLE_CONFIG_ARGS+=("$1" "$2")\n      shift 2\n      ;;\n    --help|-h)\n      usage\n      exit 0\n      ;;\n    -*)\n      echo "install.sh: unknown option: $1" >&2\n      usage\n      exit 2\n      ;;\n    *)\n      if [[ "$DEST_SET" -eq 1 ]]; then\n        echo "install.sh: unexpected argument: $1" >&2\n        usage\n        exit 2\n      fi\n      DEST="$1"\n      DEST_SET=1\n      shift\n      ;;\n  esac\ndone${destFallback}\n${requiredCheck}SRC="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"\n\nmkdir -p "$DEST"\nrsync -a ${token ? "--delete " : ""}${mergeConfig ? `--exclude="${mergeConfig.configRelPath}" ` : ""}"$SRC"/ "$DEST"/${replaceBlock}${mergeBlock}\nif [[ \${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "\${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "\${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "\${FLOW_AGENTS_CONSOLE_URL:-}" || -n "\${CONSOLE_TELEMETRY_URL:-}" || -n "\${CONSOLE_URL:-}" || -n "\${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "\${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then\n  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "\${CONSOLE_CONFIG_ARGS[@]}"\nfi\necho "Installed ${label} bundle ${token ? "to" : "into"} $DEST"\n`;
 }
@@ -368,8 +393,8 @@ function buildBase(agents) {
     const bundle = path.join(dist, "base");
     resetDir(bundle);
     copySharedContent(bundle, "base", "<bundle-root>");
-    writeText(path.join(bundle, ".flow-agents", ".gitkeep"), "");
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Base", agents, ".flow-agents"));
+    writeText(path.join(bundle, runtimeTaskDir, ".gitkeep"), "");
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Base", agents, runtimeTaskDir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Base", "bash install.sh /path/to/workspace"));
     writeText(path.join(bundle, "install.sh"), installScript("Base", "/path/to/workspace", undefined, undefined, undefined, { runtime: "base", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
@@ -381,7 +406,7 @@ function buildKiro(agents) {
     copySharedContent(bundle, "kiro", token);
     for (const spec of agents)
         writeText(path.join(bundle, "agents", `${spec.name}.json`), sanitizeText(`${JSON.stringify(sanitizeAgentJson(spec), null, 2)}\n`, "kiro", token));
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Kiro", agents, ".flow-agents"));
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Kiro", agents, runtimeTaskDir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Kiro", "bash install.sh $HOME/.flow-agents"));
     writeText(path.join(bundle, "install.sh"), installScript("Kiro", "$HOME/.flow-agents", token, '${FLOW_AGENTS_DEST:-$HOME/.flow-agents}', undefined, { runtime: "kiro", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
@@ -729,6 +754,14 @@ function buildCatalog(agents) {
 }
 export function main() {
     fs.mkdirSync(dist, { recursive: true });
+    // Populate (and, on collision, set) skillCollisionDiagnostic before any
+    // build step writes output -- fail fast with a clear diagnostic instead of
+    // partially building bundles from a deduped/ambiguous skill set.
+    collectAllSkills();
+    if (skillCollisionDiagnostic) {
+        console.error(skillCollisionDiagnostic);
+        return 1;
+    }
     const agents = fs.readdirSync(path.join(root, "agents")).filter((name) => name.endsWith(".json")).sort().map((name) => loadJson(path.join(root, "agents", name)));
     buildBase(agents);
     buildKiro(agents);

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

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { exists, loadJson, markdownTable, oneLine, readText, rel, root, writeText } from "./common.js";
+import { DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR } from "../lib/local-artifact-root.js";
 const defaultOutput = path.join(root, "docs/context-map.md");
 const dirDescriptions = {
     agents: "Canonical agent specs and routing prompts.",
@@ -21,7 +22,7 @@ const commands = [
     ["Source tree", "npm run validate:source"],
     ["Static suite", "bash evals/run.sh static"],
     ["Integration suite", "bash evals/run.sh integration"],
-    ["Workflow artifacts", "npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug>"],
+    ["Workflow artifacts", `npm run workflow:validate-artifacts -- --require-sidecars --require-critique ${FLOW_AGENTS_RUNTIME_DIR}/<slug>`],
     ["Workflow sidecars", "npm run workflow:sidecar -- --help"],
     ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
     ["Context map drift", "npm run context-map:check"],
@@ -73,7 +74,8 @@ function repoShape(manifest) {
         rows.push([dir, "optional", "Optional local/user pack copied when present."]);
     }
     rows.push(["dist", "generated", "Generated bundle exports. Do not edit by hand."]);
-    rows.push([".flow-agents", "runtime", "Cross-session workflow artifacts and sidecars. Not committed by default."]);
+    rows.push([FLOW_AGENTS_RUNTIME_DIR, "runtime", "Non-durable workflow artifacts, sidecars, and generated projections. Not committed by default."]);
+    rows.push([DURABLE_FLOW_AGENTS_DIR, "durable local state", "Explicit Flow Agents config/install state. Not a runtime artifact fallback."]);
     return rows;
 }
 /** Collect all skill {name, absPath} pairs from skills/ and kit-owned skills. */
@@ -159,15 +161,15 @@ function latestRuntimeStates(includeRuntime) {
     if (!includeRuntime) {
         return [
             "Runtime workflow state is excluded from the committed map.",
-            "Regenerate locally with `npm run context-map -- --include-runtime` to include recent `.flow-agents` state.",
+            `Regenerate locally with \`npm run context-map -- --include-runtime\` to include recent \`${FLOW_AGENTS_RUNTIME_DIR}\` state.`,
         ];
     }
-    const workflowDir = path.join(root, ".flow-agents");
+    const workflowDir = path.join(root, FLOW_AGENTS_RUNTIME_DIR);
     if (!exists(workflowDir))
-        return ["No local workflow state found under `.flow-agents`."];
+        return [`No local workflow state found under \`${FLOW_AGENTS_RUNTIME_DIR}\`.`];
     const states = fs.readdirSync(workflowDir).map((name) => path.join(workflowDir, name, "state.json")).filter(exists).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
     if (!states.length)
-        return ["No local workflow state found under `.flow-agents`."];
+        return [`No local workflow state found under \`${FLOW_AGENTS_RUNTIME_DIR}\`.`];
     const rows = states.slice(0, 8).map((file) => {
         const data = loadJson(file);
         const next = typeof data.next_action === "object" && data.next_action ? data.next_action : {};
@@ -184,11 +186,11 @@ function render(includeRuntime) {
         "## How To Use This", "",
         "- Start here when a session is long, resumed, or context-constrained.",
         "- Load only the specific skill, contract, schema, or doc that matches the task.",
-        "- Treat `.flow-agents` as runtime state and `dist/` as generated output.", "",
+        `- Treat \`${FLOW_AGENTS_RUNTIME_DIR}\` as runtime state and \`dist/\` as generated output.`, "",
         "## Repository Shape", "", ...markdownTable(["Path", "Role", "Purpose"], repoShape(manifest)), "",
         "## Core Commands", "", ...markdownTable(["Use", "Command"], commands), "",
         "## Workflow Sidecars", "",
-        "Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents/<slug>/`.", "",
+        `Machine-readable workflow state lives beside Markdown artifacts in \`${FLOW_AGENTS_RUNTIME_DIR}/<slug>/\`.`, "",
         ...markdownTable(["Schema", "Title", "ID"], schemas()), "",
         "Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`.", "",
         "## Workflow Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], workflowRows), "",

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

@@ -25,6 +25,15 @@ const mirroredFiles = new Map([
     ["scripts/telemetry/console-presets.sh", { mirror: "context/scripts/telemetry/console-presets.sh", allowedDifferences: [] }],
     ["scripts/telemetry/install-console-config.sh", { mirror: "context/scripts/telemetry/install-console-config.sh", allowedDifferences: [] }],
     ["scripts/discover-agents.sh", { mirror: "context/scripts/discover-agents.sh", allowedDifferences: [['ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"', 'ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"']] }],
+    // WS8 (AC9): scripts/hooks/* is the actively-maintained source of truth; context/ holds
+    // the exported mirror. These four hooks (and the config-protection remedy lib) had drifted
+    // silently because nothing validated them. Enforce byte-identical mirrors so future drift
+    // 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/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: [] }],
 ]);
 const publicScriptWrappers = new Map([
     ["scripts/build-universal-bundles.js", { target: "../build/src/tools/build-universal-bundles.js", significantLines: [
@@ -71,14 +80,20 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/utterance-check.js", { category: "policy hook", requiredNeedles: ["Utterance Check Hook", "FLOW_AGENTS_UTTERANCE_CHECK_ENABLED"] }],
     ["scripts/hooks/workflow-steering.js", { category: "policy hook", requiredNeedles: ["Workflow Steering Hook"] }],
     ["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/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
+    ["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"] }],
+    ["scripts/hooks/lib/liveness-write.js", { category: "shared hook library", requiredNeedles: ["appendLivenessEvent", "livenessStreamFile"] }],
     ["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"] }],
 ]);
 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"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290)" }],
     ["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" }],
@@ -88,6 +103,9 @@ const fixtureOwnerPolicies = new Map([
     ["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/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" }],
 ]);
@@ -98,13 +116,18 @@ const requiredUsageFeedbackFiles = [
 const fixtureOwnershipSelfAuditRefs = new Set([
     "evals/integration/test_fixture_retirement_audit.sh",
 ]);
-const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build", "integrations"]);
+const pythonInventoryExcludes = new Set([".git", ".flow-agents", ".kontourai", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build", "integrations"]);
 const pythonCommandScanRoots = ["README.md", "docs", "context", "skills", "prompts", "agents", "evals", "scripts", "packaging", "package.json"];
 const allowedPythonCommandFiles = [
     /^agents\/tool-explore-deps\.json$/,
     /^evals\/results\//,
     /^evals\/lib\/python\.sh$/,
     /(^|\/)telemetry\/lib\/enrich\.sh$/,
+    // WS8 (AC10b): stop-goal-fit.js lists python/python3 in its first-token command-RECOGNIZER
+    // allowlist (so honest command evidence from a polyglot adopter project is not misclassified
+    // 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$/,
 ];
 function tryLoadJson(file, reporter) {
     try {

package/console.telemetry.json

@@ -217,6 +217,28 @@
       },
       "limit": 10
     },
+    {
+      "id": "builder.publish-learn",
+      "label": "Builder publish and learn",
+      "match": {
+        "attribute": "flow",
+        "includes": "builder.publish-learn"
+      },
+      "titleAttribute": "title",
+      "detailAttributes": {
+        "Project": "project",
+        "Repository": "repo",
+        "Task": "taskSlug",
+        "Status": "status",
+        "Outcome": "outcome",
+        "Phase": "phase",
+        "Skill": "skill",
+        "Agent": "agent",
+        "Model": "model",
+        "Observed": "observedAt"
+      },
+      "limit": 10
+    },
     {
       "id": "delivery",
       "label": "Delivery workflows",

package/context/contracts/artifact-contract.md

@@ -1,14 +1,16 @@
 # Workflow Artifact Contract
 
-Workflow artifacts are the durable handoff surface between orchestrators, workers, verifiers, hooks, evals, and future sessions.
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Workflow artifacts are the resumable local handoff surface between orchestrators, workers, verifiers, hooks, evals, and future sessions.
 
 ## Artifact Root
 
-Use the task artifact root defined by the active distribution's bundle instructions. This source repo has a historical default task root, but distributions may substitute their own root during export.
+Use the task artifact root defined by the active distribution's bundle instructions. This source repo writes and discovers non-durable task artifacts under `.kontourai/flow-agents/<slug>/` by default.
 
 Do not hard-code a different root inside a skill or agent when the distribution has already defined one.
 
-In this source tree, `.flow-agents/<slug>/` is the local runtime/session state root by default. Exported agent bundles may map the runtime root to a distribution-specific path through their bundle instructions; treat those paths as local runtime roots, not durable product documentation.
+In this source tree, `.kontourai/flow-agents/<slug>/` is the local runtime/session state root by default. `.flow-agents/` is reserved for Flow Agents-owned durable config/install state; do not put non-durable workflow sessions there. Exported agent bundles may map the runtime root to a distribution-specific path through their bundle instructions; treat those paths as local runtime roots, not durable product documentation.
 
 The artifact root is local working memory unless a workflow explicitly promotes or publishes it:
 
@@ -17,8 +19,39 @@ The artifact root is local working memory unless a workflow explicitly promotes
 - Archive completed local records under `<artifact-root>/<slug>/archive/<date>/` when they are useful for audit or recovery but should not remain the active session.
 - Promote stable decisions, usage guidance, release notes, and accepted architecture changes into durable docs such as `docs/`, ADRs, changelogs, or provider-backed descriptions/comments.
 - Publish provider records only through the provider adapter or explicit publish-change step. Provider records may link back to local artifacts, but they do not make local runtime files durable by themselves.
-- Do not commit local workflow runtime roots such as `.flow-agents/<slug>/` as durable policy unless a repository-specific contract explicitly says that artifact is promoted.
-- Do not commit local workflow runtime roots such as `.flow-agents/<slug>/`; final acceptance must promote durable content before merge.
+- Do not commit local workflow runtime roots such as `.kontourai/flow-agents/<slug>/` as durable policy unless a repository-specific contract explicitly says that artifact is promoted.
+- Do not commit local workflow runtime roots such as `.kontourai/flow-agents/<slug>/`; final acceptance must promote durable content before merge.
+
+## Session Archival Policy
+
+Two archive locations exist and serve distinct purposes — do not conflate them:
+
+- **Per-session, in-place history:** `<artifact-root>/<slug>/archive/<date>/` (above) holds
+  point-in-time snapshots of an *active* session's own records for audit/recovery while the
+  session remains in the active listing.
+- **Whole-session archival (canonical):** `<artifact-root>/archive/<slug>/` is where an
+  entire terminal session is *moved out of the active listing*. This is the root-level
+  `archive/` that `src/cli/workflow-artifact-cleanup-audit.ts` already treats as a skipped
+  root entry (`SKIPPED_ROOT_ENTRIES`), so an archived session is not re-scanned as active
+  WIP. Use this location when relocating a completed session; do not invent a third path.
+
+Retention rule (selection, not automatic deletion): a session is an **archival candidate**
+when `workflow-artifact-cleanup-audit` classifies it `terminal_done` (a `delivered`/
+`accepted`/`archived` session in phase `done`, or an `accepted`/`archived` session with no
+open learning routing) **and** its `state.json` `updatedAt` is older than a retention
+window (default 30 days). Use the audit tool's existing read-only classification as the
+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):
+
+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
+   retention window.
+3. Move each selected `<artifact-root>/<slug>/` to `<artifact-root>/archive/<slug>/`
+   (a human-reviewed or explicitly-invoked move — not a silent background job).
 
 ## Persistence Integrity
 
@@ -34,7 +67,7 @@ records under concurrency.)
 
 ### Structured Sidecars
 
-Markdown artifacts remain the human-readable handoff surface. JSON sidecars are the machine-readable recovery and gate surface. When a workflow creates or updates the corresponding information, write the sidecar beside the Markdown artifacts in `.flow-agents/<slug>/`.
+Markdown artifacts remain the human-readable handoff surface. JSON sidecars are the machine-readable recovery and gate surface. When a workflow creates or updates the corresponding information, write the sidecar beside the Markdown artifacts in `.kontourai/flow-agents/<slug>/`.
 
 Draft sidecars:
 
@@ -51,7 +84,7 @@ Sidecar rules:
 - Keep `schema_version` at `1.0` until the schema changes incompatibly.
 - Keep `task_slug` stable across all sidecars for a workflow.
 - Prefer `npm run workflow:sidecar --` for creating and updating sidecars. If a harness cannot run the writer, produce equivalent JSON and validate it with `npm run workflow:validate-artifacts --`.
-- Use `npm run workflow:sidecar -- ensure-session` when available to create or select the current `.flow-agents/<slug>/` session artifact before substantial work starts.
+- Use `npm run workflow:sidecar -- ensure-session` when available to create or select the current `.kontourai/flow-agents/<slug>/` session artifact before substantial work starts.
 - Update `state.json` at phase transitions.
 - Create or update `acceptance.json` when planning defines or changes acceptance criteria.
 - Create or update `evidence.json` when verification or evidence-gate records proof.