@kontourai/flow-agents 2.3.0 → 3.0.0

package/build/src/cli/console-learning-projection.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
 const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
 function printHelp() {
@@ -10,7 +11,7 @@ function printHelp() {
     console.log("Build an inert Console learning projection from local workflow learning sidecars.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .flow-agents)");
+    console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .kontourai/flow-agents)");
     console.log("  --kontour-root <path>   Local Kontour root to write under (default: .kontour)");
     console.log("  --scope <id>            Projection scope id (default: current directory name)");
     console.log("  --scope-kind <kind>     Projection scope kind (default: repo)");
@@ -84,7 +85,7 @@ export function main(argv = process.argv.slice(2)) {
         return 0;
     }
     try {
-        const artifactRoot = path.resolve(flagString(flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+        const artifactRoot = path.resolve(flagString(flags, "artifact-root") ?? defaultArtifactRootForRead());
         const kontourRoot = path.resolve(flagString(flags, "kontour-root", ".kontour") ?? ".kontour");
         const producer = requireSafeSegment(flagString(flags, "producer", "flow-agents-learning") ?? "flow-agents-learning", "--producer");
         const scope = {

package/build/src/cli/effective-assignment-provider-settings.d.ts

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

package/build/src/cli/effective-assignment-provider-settings.js

@@ -0,0 +1,125 @@
+import * as child_process from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagBool } from "../lib/args.js";
+import { readJson } from "../lib/fs.js";
+// Mirrors src/cli/effective-backlog-settings.ts's loadSettings/currentRepo/merge/findProject/
+// effective structure and its ask_user/configured result envelope exactly, pointed at the
+// AssignmentProvider settings schema/example instead of the backlog equivalents (#290 Wave 2
+// Task B). Deliberately NOT extracted into a shared helper with effective-backlog-settings.ts —
+// see the #290 plan artifact's Unresolved Questions #3 for the recorded rationale (duplicating
+// this file's small merge/repo-detection logic is lower-risk than refactoring a file outside
+// this issue's declared scope).
+const PROJECT_SETTINGS_RELATIVE_PATH = path.join("context", "settings", "assignment-provider-settings.json");
+function loadSettings(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const data = readJson(file);
+    if (data.schema_version !== "1.0")
+        throw new Error(`${file}: unsupported schema_version ${String(data.schema_version)}`);
+    return data;
+}
+function repoFromText(text) {
+    const match = text.trim().match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+    return match ? { owner: match[1], name: match[2] } : null;
+}
+function currentRepo(repoPath) {
+    try {
+        const out = child_process.execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const repo = repoFromText(out);
+        if (repo)
+            return repo;
+    }
+    catch { }
+    const packagePath = path.join(repoPath, "package.json");
+    if (fs.existsSync(packagePath)) {
+        const data = readJson(packagePath);
+        const repository = data.repository;
+        const url = typeof repository === "object" && repository !== null ? repository.url : repository;
+        if (typeof url === "string")
+            return repoFromText(url);
+    }
+    return null;
+}
+function merge(base, override) {
+    if (!base && !override)
+        return null;
+    if (!base)
+        return structuredClone(override);
+    if (!override)
+        return structuredClone(base);
+    const out = structuredClone(base);
+    for (const [key, value] of Object.entries(override)) {
+        out[key] = typeof value === "object" && value !== null && typeof out[key] === "object" && out[key] !== null && !Array.isArray(value)
+            ? merge(out[key], value)
+            : structuredClone(value);
+    }
+    return out;
+}
+function findProject(settings, repo) {
+    const projects = settings?.projects;
+    if (!Array.isArray(projects))
+        return null;
+    return projects.find((project) => {
+        const projectRepo = (project.project?.repo ?? {});
+        return projectRepo.owner === repo.owner && projectRepo.name === repo.name;
+    }) ?? null;
+}
+function defaultProjectSettingsPath() {
+    let cursor = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(cursor, PROJECT_SETTINGS_RELATIVE_PATH);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return path.resolve(PROJECT_SETTINGS_RELATIVE_PATH);
+        cursor = parent;
+    }
+}
+function effective(repoPath, projectSettings, globalSettings) {
+    const repo = currentRepo(repoPath);
+    const projectDoc = loadSettings(projectSettings);
+    const globalDoc = loadSettings(globalSettings);
+    if (!repo)
+        return [{ status: "ask_user", reason: "could_not_identify_current_repo", message: "Ask the user which assignment AssignmentProvider to use for this workspace.", resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings } }, 2];
+    const effectiveSettings = merge(merge(merge(globalDoc?.defaults, findProject(globalDoc, repo)), projectDoc?.defaults), findProject(projectDoc, repo));
+    if (!effectiveSettings)
+        return [{ status: "ask_user", reason: "no_assignment_provider_settings", message: "Ask the user which assignment AssignmentProvider to use before claiming work.", current_repo: repo, resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings, checked: ["project", "global"] } }, 2];
+    return [{ status: "configured", current_repo: repo, source: findProject(projectDoc, repo) || projectDoc?.defaults ? "project" : "global", precedence: ["project.projects match", "project.defaults", "global.projects match", "global.defaults"], settings: effectiveSettings }, 0];
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    try {
+        const [result, code] = effective(path.resolve(flagString(args.flags, "repo-path", ".") ?? "."), path.resolve(flagString(args.flags, "project-settings", defaultProjectSettingsPath()) ?? ""), path.resolve(flagString(args.flags, "global-settings", path.join(os.homedir(), ".config", "flow-agents", "assignment-provider-settings.json")) ?? ""));
+        if (flagBool(args.flags, "json"))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(`status: ${String(result.status)}`);
+        return code;
+    }
+    catch (error) {
+        console.error(`error: ${error.message}`);
+        return 1;
+    }
+}
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/init.js

@@ -10,6 +10,7 @@ import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
 import { activateCodexLocal } from "../runtime-adapters.js";
 import { main as buildBundles } from "../tools/build-universal-bundles.js";
 import { root } from "../tools/common.js";
+import { defaultCodexHome, durableInstallRecordPath } from "../lib/local-artifact-root.js";
 const runtimeBundles = {
     base: "base",
     codex: "codex",
@@ -82,8 +83,8 @@ Options:
                           Honors FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation.
                         opencode: merges opencode.json into ~/.config/opencode/opencode.json
                           (honors XDG_CONFIG_HOME; test isolation via FLOW_AGENTS_USER_OPENCODE_CONFIG).
-                        codex: runs install-codex-home.sh into ~/.flow-agents/codex
-                          (the isolated Codex HOME; hooks merged, not overwritten).
+                        codex: runs install-codex-home.sh into CODEX_HOME or ~/.codex
+                          (hooks merged, not overwritten).
                         pi: NOT_VERIFIED (no documented global dir); warns and falls back to workspace default.
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
@@ -174,9 +175,8 @@ function globalDest(runtime) {
         return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
     }
     if (runtime === "codex") {
-        // codex --global routes to the isolated Codex HOME at ~/.flow-agents/codex.
-        // This is the same path used by install-codex-home.sh; --dest overrides it for sandbox testing.
-        return path.join(os.homedir(), ".flow-agents", "codex");
+        // codex --global routes to the standard Codex home. --dest remains an explicit override.
+        return defaultCodexHome();
     }
     if (runtime === "pi") {
         // pi has no documented global config dir.
@@ -268,6 +268,75 @@ function ensureBundle(runtime) {
         throw new Error(`bundle installer missing: ${bundle}`);
     return bundle;
 }
+// The bundle's hook commands resolve the flow-agents scripts directory via
+// ${CLAUDE_PROJECT_DIR:-$(pwd)}. That is correct for a project-scoped install
+// (installBundle rsyncs scripts/ alongside .claude/, so CLAUDE_PROJECT_DIR ==
+// the install destination). It is NOT correct for a --global install: there
+// is no per-destination copy of scripts/, and CLAUDE_PROJECT_DIR varies with
+// whichever project happens to be open, so the hook resolves to a path that
+// exists in at most one project (and never for most sessions). Global
+// installs need an absolute, session-independent path instead.
+const GLOBAL_INSTALL_PROJECT_DIR_PREFIX = /root="\$\{CLAUDE_PROJECT_DIR:-\$\(pwd\)\}";\s*/g;
+const GLOBAL_INSTALL_PROJECT_DIR_VAR = /"\$root\//g;
+function rewriteCommandForGlobalInstall(command, sourceRoot) {
+    return command
+        .replace(GLOBAL_INSTALL_PROJECT_DIR_PREFIX, "")
+        .replace(GLOBAL_INSTALL_PROJECT_DIR_VAR, `"${sourceRoot}/`);
+}
+/** Recursively rewrite every `command` string found under `value` in place. */
+function rewriteCommandsForGlobalInstall(value, sourceRoot) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            rewriteCommandsForGlobalInstall(item, sourceRoot);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    const obj = value;
+    for (const key of Object.keys(obj)) {
+        if (key === "command" && typeof obj[key] === "string") {
+            obj[key] = rewriteCommandForGlobalInstall(obj[key], sourceRoot);
+            continue;
+        }
+        rewriteCommandsForGlobalInstall(obj[key], sourceRoot);
+    }
+}
+/**
+ * Additively copy every file under srcDir into destDir, creating directories
+ * as needed and overwriting files whose content changed. Never deletes files
+ * in destDir that srcDir does not own — destDir may contain unrelated content
+ * (other kits, other tools) that this sync must not touch.
+ */
+function copyDirMerge(srcDir, destDir) {
+    let added = 0;
+    let updated = 0;
+    if (!fs.existsSync(srcDir))
+        return { added, updated };
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = copyDirMerge(srcPath, destPath);
+            added += nested.added;
+            updated += nested.updated;
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const content = fs.readFileSync(srcPath);
+        if (fs.existsSync(destPath)) {
+            if (Buffer.compare(fs.readFileSync(destPath), content) === 0)
+                continue;
+            updated += 1;
+        }
+        else {
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            added += 1;
+        }
+        fs.writeFileSync(destPath, content);
+    }
+    return { added, updated };
+}
 function installBundle(bundle, options) {
     const args = ["install.sh", options.dest];
     for (const sink of options.telemetrySinks)
@@ -334,10 +403,13 @@ export async function main(argv = process.argv.slice(2)) {
             if (!options.global)
                 checkScopeCollision();
         }
-        // --global for claude-code: merge only into the global/user-level settings dir.
-        // This writes only the hook-wiring config (merge into ~/.claude/settings.json),
-        // not the full workspace bundle. The global settings dir is the claude config root,
-        // so the settings.json lives directly in dest (not dest/.claude/).
+        // --global for claude-code: merge hook-wiring into the global/user-level
+        // settings dir, plus additively sync skills/agents so a global install
+        // does not silently go stale as new Builder Kit skills ship. This does
+        // NOT rsync the full workspace bundle (no context/, powers/, prompts/,
+        // etc.) — only the parts a global Claude Code user-config needs. The
+        // global settings dir is the claude config root, so the settings.json
+        // lives directly in dest (not dest/.claude/).
         if (options.global && options.runtime === "claude-code") {
             const bundle = ensureBundle(options.runtime);
             // For --global, dest is ~/.claude/ (the global settings dir).
@@ -353,6 +425,10 @@ export async function main(argv = process.argv.slice(2)) {
             // Remove permissive defaults (not appropriate for global user settings).
             delete managed["permissions"];
             delete managed["skipDangerousModePermissionPrompt"];
+            // See rewriteCommandsForGlobalInstall: bundle hook commands assume
+            // CLAUDE_PROJECT_DIR points at this package; a global install must not
+            // depend on which project is currently open, so pin to an absolute path.
+            rewriteCommandsForGlobalInstall(managed, root);
             fs.mkdirSync(options.dest, { recursive: true });
             const destSettingsPath = path.join(options.dest, "settings.json");
             const installMergePath = path.join(root, "scripts", "install-merge.js");
@@ -371,16 +447,21 @@ export async function main(argv = process.argv.slice(2)) {
             const tmp = `${destSettingsPath}.tmp.${process.pid}`;
             fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
             fs.renameSync(tmp, destSettingsPath);
+            // Additive skills/agents sync: adds new files and updates changed ones,
+            // never deletes — dest may hold unrelated content from other kits/tools.
+            const skillsSync = copyDirMerge(path.join(bundle, ".claude", "skills"), path.join(options.dest, "skills"));
+            const agentsSync = copyDirMerge(path.join(bundle, ".claude", "agents"), path.join(options.dest, "agents"));
             // Write version stamp.
-            const installRecordDir = path.join(options.dest, ".flow-agents");
+            const recordPath = durableInstallRecordPath(options.dest);
+            const installRecordDir = path.dirname(recordPath);
             fs.mkdirSync(installRecordDir, { recursive: true });
             const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
             const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code", global: true };
-            const recordPath = path.join(installRecordDir, "install.json");
             const recordTmp = `${recordPath}.tmp.${process.pid}`;
             fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
             fs.renameSync(recordTmp, recordPath);
             console.log(`Flow Agents global hooks merged for claude-code in ${options.dest}`);
+            console.log(`Synced skills (+${skillsSync.added} new, ~${skillsSync.updated} updated) and agents (+${agentsSync.added} new, ~${agentsSync.updated} updated) in ${options.dest}`);
             return 0;
         }
         // --global for opencode: merge FA opencode.json into the global opencode config dir.
@@ -415,11 +496,11 @@ export async function main(argv = process.argv.slice(2)) {
 `, "utf8");
             fs.renameSync(tmp, destConfigPath);
             // Write version stamp.
-            const installRecordDir = path.join(options.dest, ".flow-agents");
+            const recordPath = durableInstallRecordPath(options.dest);
+            const installRecordDir = path.dirname(recordPath);
             fs.mkdirSync(installRecordDir, { recursive: true });
             const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
             const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "opencode", global: true };
-            const recordPath = path.join(installRecordDir, "install.json");
             const recordTmp = `${recordPath}.tmp.${process.pid}`;
             fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
 `, "utf8");
@@ -427,9 +508,8 @@ export async function main(argv = process.argv.slice(2)) {
             console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
             return 0;
         }
-        // --global for codex: run install-codex-home.sh to install into the isolated Codex HOME.
-        // The codex --global path is ~/.flow-agents/codex (the isolated home IS codex's global).
-        // Pass through telemetry/console args and honor --dest override for sandbox testing.
+        // --global for codex: run install-codex-home.sh to install into the Codex home.
+        // Defaults to CODEX_HOME or ~/.codex. --dest remains an explicit override.
         if (options.global && options.runtime === "codex") {
             const codexHomeScript = path.join(root, "scripts", "install-codex-home.sh");
             if (!fs.existsSync(codexHomeScript)) {
@@ -452,7 +532,10 @@ export async function main(argv = process.argv.slice(2)) {
                 console.error(`flow-agents init: unable to run install-codex-home.sh: ${result.error.message}`);
                 return 1;
             }
-            return result.status ?? 1;
+            const installed = result.status ?? 1;
+            if (installed !== 0)
+                return installed;
+            return activateKits(options);
         }
         // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
         if (options.global && options.runtime === "pi") {
@@ -541,11 +624,11 @@ function dogfoodClaudeCode(bundleRoot, dest) {
     fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
     fs.renameSync(tmp, destSettingsPath);
     // Write version stamp.
-    const installRecordDir = path.join(dest, ".flow-agents");
+    const recordPath = durableInstallRecordPath(dest);
+    const installRecordDir = path.dirname(recordPath);
     fs.mkdirSync(installRecordDir, { recursive: true });
     const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
     const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code" };
-    const recordPath = path.join(installRecordDir, "install.json");
     const recordTmp = `${recordPath}.tmp.${process.pid}`;
     fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     fs.renameSync(recordTmp, recordPath);
@@ -584,11 +667,11 @@ function dogfoodCodex(bundleRoot, dest) {
     fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
     fs.renameSync(tmp, destHooksPath);
     // Write version stamp.
-    const installRecordDir = path.join(dest, ".flow-agents");
+    const recordPath = durableInstallRecordPath(dest);
+    const installRecordDir = path.dirname(recordPath);
     fs.mkdirSync(installRecordDir, { recursive: true });
     const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
     const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "codex" };
-    const recordPath = path.join(installRecordDir, "install.json");
     const recordTmp = `${recordPath}.tmp.${process.pid}`;
     fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
     fs.renameSync(recordTmp, recordPath);

package/build/src/cli/kit.js

@@ -6,12 +6,17 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
-import { assertKitRepository, deriveKitTargets } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+import { defaultCodexHome } from "../lib/local-artifact-root.js";
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
 function registryPath(dest) { return path.join(dest, REGISTRY_REL); }
 function installedPath(dest, kitId) { return path.join(dest, REPOSITORIES_REL, kitId); }
+function resolveDest(flags) {
+    const explicit = flagString(flags, "dest");
+    return path.resolve(explicit ?? defaultCodexHome());
+}
 function loadRegistry(dest) {
     const file = registryPath(dest);
     if (!fs.existsSync(file))
@@ -19,6 +24,28 @@ function loadRegistry(dest) {
     const data = readJson(file);
     return { schema_version: data.schema_version ?? "1.0", kits: Array.isArray(data.kits) ? data.kits.filter((item) => typeof item === "object" && item !== null) : [] };
 }
+/**
+ * Emit a non-blocking warning for each declared kit dependency that is not present
+ * in the destination's LOCAL registry.
+ *
+ * Scope limitation (v1, accepted): this check only sees the local installed-kits
+ * registry at `dest`, NOT the built-in Kit Catalog. A dependency satisfied solely by
+ * a built-in catalog kit will still warn here. Presence is enforced authoritatively
+ * (hard error) at activation time against the full discovered inventory
+ * (built-in catalog + local registry) — see src/runtime-adapters.ts.
+ */
+function warnUninstalledDependencies(manifest, manifestPath, dest) {
+    const { entries } = parseKitDependencies(manifest, manifestPath);
+    if (!entries.length)
+        return;
+    const installed = new Set(loadRegistry(dest).kits.map((entry) => String(entry.id ?? "")));
+    const kitId = String(manifest.id);
+    for (const dep of entries) {
+        if (!installed.has(dep.kit_id)) {
+            console.log(`warning: kit '${kitId}' declares a dependency on '${dep.kit_id}'${dep.reason ? ` (${dep.reason})` : ""} which is not installed at ${dest}; install it first with 'flow-agents kit install <source>' or activation will fail`);
+        }
+    }
+}
 function contentHash(root) {
     const hash = crypto.createHash("sha256");
     for (const file of walkFiles(root)) {
@@ -73,7 +100,7 @@ async function install(argv) {
 }
 async function installLocalSource(source, argv) {
     const args = parseArgs(argv);
-    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const dest = resolveDest(args.flags);
     let manifest;
     try {
         manifest = await assertKitRepository(source);
@@ -85,10 +112,12 @@ async function installLocalSource(source, argv) {
         return 1;
     }
     const kitId = String(manifest.id);
+    warnUninstalledDependencies(manifest, path.join(source, "kit.json"), dest);
     const hash = contentHash(source);
     const registry = loadRegistry(dest);
     const existing = registry.kits.find((entry) => entry.id === kitId);
     const target = installedPath(dest, kitId);
+    fs.mkdirSync(dest, { recursive: true });
     assertPathContained(dest, target);
     const sourceText = source;
     if (existing && existing.source !== sourceText && !flagBool(args.flags, "update")) {
@@ -127,7 +156,7 @@ async function installGitSource(rawUrl, argv) {
     }
     if (!ref)
         ref = flagString(args.flags, "ref") ?? null;
-    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const dest = resolveDest(args.flags);
     const force = flagBool(args.flags, "force") ?? false;
     const update = flagBool(args.flags, "update") ?? false;
     // Shallow-clone into a temporary directory.
@@ -161,10 +190,12 @@ async function installGitSource(rawUrl, argv) {
         }
         // Delegate to the shared install logic (copy + registry update).
         const kitId = String(manifest.id);
+        warnUninstalledDependencies(manifest, path.join(tmpBase, "kit.json"), dest);
         const hash = kitContentHash(tmpBase);
         const registry = loadRegistry(dest);
         const existing = registry.kits.find((entry) => entry.id === kitId);
         const target = installedPath(dest, kitId);
+        fs.mkdirSync(dest, { recursive: true });
         assertPathContained(dest, target);
         const sourceText = repoUrl + (ref ? `#${ref}` : "");
         if (existing && existing.source !== sourceText && !update) {
@@ -197,7 +228,7 @@ async function installGitSource(rawUrl, argv) {
 }
 function list(argv) {
     const args = parseArgs(argv);
-    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const dest = resolveDest(args.flags);
     const entries = loadRegistry(dest).kits;
     if (!entries.length) {
         console.log("No local Flow Kits installed.");
@@ -210,7 +241,7 @@ function list(argv) {
 }
 function status(argv) {
     const args = parseArgs(argv);
-    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const dest = resolveDest(args.flags);
     let entries = loadRegistry(dest).kits;
     const kitId = args.positionals[0];
     if (kitId) {
@@ -233,7 +264,7 @@ function status(argv) {
 const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 function activate(argv) {
     const args = parseArgs(argv);
-    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const dest = resolveDest(args.flags);
     const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
     const adapter = flagString(args.flags, "adapter");
     if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {

package/build/src/cli/pull-work-provider.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
-const FLOW_ARTIFACT_PATTERN = /(?<path>\.flow-agents\/[^\s`'")]+)/g;
+const FLOW_ARTIFACT_PATTERN = /(?<path>\.kontourai\/flow-agents\/[^\s`'")]+)/g;
 const GITHUB_ISSUE_PATTERN = /(?:(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+))?#(?<number>\d+)/g;
 const GITHUB_URL_PATTERN = /https:\/\/github\.com\/(?<owner>[^/\s]+)\/(?<repo>[^/\s]+)\/(?:issues|pull)\/(?<number>\d+)/g;
 const BLOCKER_PATTERN = /\b(?:blocked by|depends on|waiting on|requires|should follow|coordinate with)\b[:\s-]*(?<refs>[^\n]+)/gi;

package/build/src/cli/usage-feedback.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
-import { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, telemetryDataDir, flowAgentsArtifactRoot, legacyFlowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
+import { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, telemetryDataDir, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 const VALID_RESULTS = new Set(["success", "partial", "failure", "not_verified"]);
 function telemetryDir(flags) {
     const explicit = flagString(flags, "telemetry-dir") ?? process.env.TELEMETRY_DATA_DIR;
@@ -152,7 +152,7 @@ function syncArtifacts(argv) {
     const dir = telemetryDir(flags);
     ensureSafeDir(dir);
     const artifacts = flagList(flags, "artifact-dir");
-    const records = (artifacts.length ? artifacts : [flowAgentsArtifactRoot(), legacyFlowAgentsArtifactRoot()]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
+    const records = (artifacts.length ? artifacts : [flowAgentsArtifactRoot()]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
     writeJsonlUpsert(path.join(dir, "outcomes.jsonl"), records, "outcome_id");
     if (!flagBool(flags, "quiet"))
         console.log(`synced ${records.length} artifact outcome(s) to ${path.join(dir, "outcomes.jsonl")}`);
@@ -382,7 +382,7 @@ function discoverProjects(root) {
     if (!fs.existsSync(root))
         return [];
     const candidates = [root, ...fs.readdirSync(root).map((name) => path.join(root, name))];
-    return candidates.filter((candidate) => fs.existsSync(flowAgentsArtifactRoot(candidate)) || fs.existsSync(legacyFlowAgentsArtifactRoot(candidate))).map((repoRoot) => {
+    return candidates.filter((candidate) => fs.existsSync(flowAgentsArtifactRoot(candidate))).map((repoRoot) => {
         const name = path.basename(repoRoot);
         return { name, repo: name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: "codex", skill_ids: [] };
     });

package/build/src/cli/validate-hook-influence.js

@@ -7,6 +7,7 @@ const validEvents = new Set(["UserPromptSubmit", "PostToolUse", "Stop"]);
 const requiredCases = {
     "dev-builder-build-requires-pickup-probe-before-plan": { description: "missing pickup Probe before plan", tier: "design-target", must_include: ["design-probe", "accepted gaps", "provider_state", "conflict_risks"], agent_must_do: ["route decision_gap back to design-probe/pickup Probe"] },
     "dev-builder-review-before-verify-after-execute": { description: "review-before-verify after execute", tier: "adapter", event: "PostToolUse", must_include: ["Next: review", "then verify", "report only"], agent_must_do: ["review-work for report-only critique before verify-work", "not count critique.json as verification evidence"] },
+    "dev-builder-route-fresh-coding-prompt": { description: "fresh coding prompt routes into Builder workflow", tier: "adapter", event: "UserPromptSubmit", must_include: ["BUILDER WORKFLOW ROUTE", "activate `deliver`", "--flow-id builder.build", "plan-work -> execute-plan -> review-work -> verify-work", "publish/release-readiness and learning-review"], agent_must_do: ["activate Builder Kit delivery workflow before source edits", "use deliver by default for coding/build work", "do not bypass plan-work -> execute-plan -> review-work -> verify-work", "publish, release readiness, and learning feedback"] },
     "dev-verify-fail-preserves-trace-before-rework": { description: "verify failure route-back with preserved FAIL evidence", tier: "design-target", must_include: ["If verdict=FAIL: record the FAIL artifact"], agent_must_do: ["write the FAIL artifact before routing back", "route to plan"] },
     "codex-claude-strict-stop-adapter-contract": { description: "Goal Fit stop adapter behavior", tier: "adapter", hook: "stop-goal-fit", event: "Stop", must_include: ["Goal Fit warning"], agent_must_do: ["treat strict Stop guidance as a blocker"] },
     "codex-live-context-gap": { description: "Codex documented runtime gap", tier: "documented-runtime-gap", must_include: ["STATE:", "not_verified"], agent_must_do: ["record NOT_VERIFIED for live influence"] },

package/build/src/cli/validate-workflow-artifacts.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
 import * as path from "node:path";
-const root = path.resolve(".");
+import { fileURLToPath } from "node:url";
+// Resolve bundled JSON Schemas relative to this compiled script's own package
+// location (build/src/cli/validate-workflow-artifacts.js -> ../../../schemas), NOT
+// process.cwd(), so `flow-agents-validate-artifacts` works from any repo (the artifact
+// paths to validate are still taken from argv/cwd). Mirrors the package-relative pattern
+// used for liveness-read.js in workflow-sidecar.ts.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 const statusRe = /\[(PASS|FAIL|NOT_VERIFIED|SKIP|PARTIAL)\]/i;
 const dateTimeRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const sidecarSchemas = {
@@ -311,11 +317,12 @@ function readJson(file) {
 }
 function validateSidecar(file) {
     const { value, issues } = readJson(file);
+    const warnings = [];
     if (value === undefined)
-        return issues;
+        return { issues, warnings };
     const schemaFile = sidecarSchemas[path.basename(file)];
     if (schemaFile) {
-        const schema = JSON.parse(readText(path.join(root, schemaFile)));
+        const schema = JSON.parse(readText(path.join(packageRoot, schemaFile)));
         validateSchemaValue(file, value, schema, path.basename(file), issues, schema);
     }
     if (path.basename(file) === "evidence.json") {
@@ -359,7 +366,10 @@ function validateSidecar(file) {
                 issues.push({ path: file, message: "deploy decision requires post_deploy_checks to be planned or pass" });
         }
     }
-    return issues;
+    if (path.basename(file) === "state.json" && value && typeof value === "object" && !Array.isArray(value) && !("branch" in value)) {
+        warnings.push({ path: file, message: "state.json has no branch field (legacy/pre-#289 session) — re-run `ensure-session` to backfill agent/<actor>/<slug>." });
+    }
+    return { issues, warnings };
 }
 function validateLearningCorrections(file, status, records, issues) {
     records.forEach((record, index) => {
@@ -457,7 +467,11 @@ function validateSidecarGroup(inputs, markdown, requireSidecars, requireCritique
                 if (bundleValue) {
                     const claims = Array.isArray(bundleValue.claims) ? bundleValue.claims : [];
                     const critiqueClaims = claims.filter((c) => c && c.claimType === "workflow.critique.review");
-                    if (critiqueClaims.some((c) => c.value === "fail" || c.status === "disputed"))
+                    // #282: a historical fail/disputed critique that has been explicitly superseded by a later
+                    // resolving write (metadata.superseded_by) is retained structurally as history and does NOT
+                    // block a top-level pass — only a LIVE (non-superseded) fail/disputed critique blocks.
+                    const isSuperseded = (c) => c && c.metadata && typeof c.metadata === "object" && c.metadata.superseded_by;
+                    if (critiqueClaims.some((c) => (c.value === "fail" || c.status === "disputed") && !isSuperseded(c)))
                         issues.push({ path: trustBundlePath, message: "required critique must pass" });
                 }
             }
@@ -486,12 +500,18 @@ function main() {
     const markdown = artifactPaths(pathsIn);
     const sidecars = sidecarPaths(pathsIn);
     const issues = [];
+    const warnings = [];
     if (!skipMarkdown)
         for (const file of markdown)
             issues.push(...validateArtifact(file));
-    for (const file of sidecars)
-        issues.push(...validateSidecar(file));
+    for (const file of sidecars) {
+        const result = validateSidecar(file);
+        issues.push(...result.issues);
+        warnings.push(...result.warnings);
+    }
     issues.push(...validateSidecarGroup(pathsIn, markdown, requireSidecars, requireCritique));
+    for (const w of warnings)
+        console.error(`WARN ${w.path}: ${w.message}`);
     if (issues.length) {
         for (const issue of issues)
             console.error(`${issue.path}: ${issue.message}`);