@kontourai/flow-agents 1.0.1 → 1.2.0

package/packaging/packs.json

@@ -7,13 +7,6 @@
       "description": "Small default surface for reliable coding and workflow execution.",
       "skills": [
         "search-first",
-        "plan-work",
-        "execute-plan",
-        "review-work",
-        "verify-work",
-        "evidence-gate",
-        "feedback-loop",
-        "knowledge-capture",
         "browser-test"
       ],
       "agents": [
@@ -32,23 +25,10 @@
       "default": false,
       "description": "Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work.",
       "skills": [
-        "builder-shape",
-        "idea-to-backlog",
-        "pull-work",
-        "design-probe",
-        "pickup-probe",
-        "deliver",
-        "fix-bug",
-        "tdd-workflow",
-        "release-readiness",
-        "learning-review",
         "dependency-update",
         "eval-rebuild",
-        "explore",
         "github-cli",
-        "frontend-design",
-        "agentic-engineering",
-        "context-budget"
+        "agentic-engineering"
       ],
       "agents": [
         "dev",

package/scripts/README.md

@@ -11,7 +11,7 @@ These files are stable launchers for TypeScript code compiled under `build/src/`
 | `build-universal-bundles.js` | `build/src/tools/build-universal-bundles.js` |
 | `filter-installed-packs.js` | `build/src/tools/filter-installed-packs.js` |
 | `generate-context-map.js` | `build/src/tools/generate-context-map.js` |
-| `flow-kit.js` | `build/src/cli/flow-kit.js` |
+| `kit.js` | `build/src/cli/kit.js` |
 | `pull-work-provider.js` | `build/src/cli/pull-work-provider.js` |
 | `effective-backlog-settings.js` | `build/src/cli/effective-backlog-settings.js` |
 | `publish-change-helper.js` | `build/src/cli/publish-change-helper.js` |

package/scripts/kit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));

package/scripts/telemetry/console-presets.sh

@@ -6,7 +6,7 @@ flow_agents_local_kontour_console_url() {
 }
 
 flow_agents_kontour_cloud_console_url() {
-  printf '%s\n' "${FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL:-https://console.kontourai.com}"
+  printf '%s\n' "${FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL:-https://console.kontourai.io}"
 }
 
 flow_agents_kontour_hosted_console_url() {

package/skills/README.md

@@ -0,0 +1,23 @@
+# skills/
+
+This directory contains standalone skills that are **not yet claimed by a specific kit**.
+
+## Status: Pending Tool Reclassification
+
+The 6 items here are currently classified as TOOLS pending formal reclassification in a follow-up ADR pass (tracking: #62 follow-up, ADR 0007).
+
+| Skill | Notes |
+| --- | --- |
+| agentic-engineering | Pending reclassification as a tool or context doc |
+| browser-test | Pending reclassification — closely tied to Playwright power |
+| dependency-update | Pending reclassification — tooling-oriented |
+| eval-rebuild | Pending reclassification — project-specific build hook |
+| github-cli | Pending reclassification — CLI tool wrapper |
+| search-first | Pending reclassification — research heuristic |
+
+## Kit-owned skills
+
+Builder Kit skills now live in `kits/builder/skills/`.
+Knowledge Kit skills now live in `kits/knowledge/skills/`.
+
+See `docs/adr/0007-skill-audit.md` for the full audit table and disposition rationale.

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

@@ -1,4 +1,5 @@
 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 { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
@@ -137,4 +138,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/effective-backlog-settings.ts

@@ -96,4 +96,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/fixture-retirement-audit.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 
 type FixtureAuditItem = {
@@ -151,4 +152,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/init.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -458,4 +459,9 @@ export async function mainDogfood(argv = process.argv.slice(2)): Promise<number>
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(await main());
+// 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 = await main(); }

package/src/cli/{flow-kit.ts → kit.ts}

@@ -34,7 +34,7 @@ function contentHash(root: string): string {
   return `sha256:${hash.digest("hex")}`;
 }
 
-/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+/** Content hash that excludes .git and other VCS/cache directories (for install git clones). */
 function kitContentHash(root: string): string {
   const EXCLUDE_DIRS = new Set([".git", "__pycache__", ".pytest_cache"]);
   const hash = crypto.createHash("sha256");
@@ -50,13 +50,40 @@ function kitContentHash(root: string): string {
   return `sha256:${hash.digest("hex")}`;
 }
 
-function installLocal(argv: string[]): number {
+/**
+ * install <source> [--dest <path>] [--force] [--update] [--ref <branch|tag|sha>]
+ *
+ * Installs a Flow Kit from a local path or a git URL.
+ *
+ * - Local path: validates then copies the kit into the destination registry.
+ * - Git URL (http://, https://, git+, ssh://, file://): shallow-clones the repository,
+ *   validates the kit container with @kontourai/flow, then delegates to the install path.
+ *   Supports an optional #ref fragment in the URL or a separate --ref flag.
+ */
+async function install(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  const source = args.positionals[0] ?? "";
+  if (!source) {
+    console.error("install: missing <source> argument");
+    console.error("usage: flow-agents kit install <path-or-git-url> [--dest <path>] [--ref <ref>] [--force] [--update]");
+    return 2;
+  }
+
+  // Detect git URL: starts with http(s)://, git+, ssh://, file://, or ends with .git
+  const isGitUrl = /^(https?:\/\/|git\+|ssh:\/\/|file:\/\/)/.test(source) || source.endsWith(".git");
+
+  if (isGitUrl) {
+    return await installGitSource(source, argv);
+  }
+  return await installLocalSource(path.resolve(source), argv);
+}
+
+async function installLocalSource(source: string, argv: string[]): Promise<number> {
   const args = parseArgs(argv);
-  const source = path.resolve(args.positionals[0] ?? "");
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
   let manifest: Record<string, unknown>;
   try {
-    manifest = assertKitRepository(source);
+    manifest = await assertKitRepository(source);
   } catch (error) {
     console.log("Flow Kit repository validation failed:");
     for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) console.log(` - ${diagnostic}`);
@@ -93,6 +120,86 @@ function installLocal(argv: string[]): number {
   return 0;
 }
 
+async function installGitSource(rawUrl: string, argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+
+  // Parse ref: #fragment in URL takes precedence over --ref flag.
+  let repoUrl = rawUrl;
+  let ref: string | null = null;
+  const hashIdx = rawUrl.indexOf("#");
+  if (hashIdx !== -1) {
+    repoUrl = rawUrl.slice(0, hashIdx);
+    ref = rawUrl.slice(hashIdx + 1) || null;
+  }
+  if (!ref) ref = flagString(args.flags, "ref") ?? null;
+
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const force = flagBool(args.flags, "force") ?? false;
+  const update = flagBool(args.flags, "update") ?? false;
+
+  // Shallow-clone into a temporary directory.
+  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "flow-kit-git-"));
+  try {
+    const cloneArgs = ["clone", "--depth", "1"];
+    if (ref) cloneArgs.push("--branch", ref);
+    cloneArgs.push("--", repoUrl, tmpBase);
+    try {
+      child_process.execFileSync("git", cloneArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      const msg = err instanceof Error && (err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr
+        ? ((err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr as Buffer).toString().trim()
+        : String(err);
+      console.error(`install: git clone failed: ${msg}`);
+      return 1;
+    }
+
+    // Validate the cloned kit using the same logic as install local.
+    let manifest: Record<string, unknown>;
+    try {
+      manifest = await assertKitRepository(tmpBase);
+    } catch (error) {
+      console.log("Flow Kit repository validation failed:");
+      for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) {
+        console.log(` - ${diagnostic}`);
+      }
+      return 1;
+    }
+
+    // Delegate to the shared install logic (copy + registry update).
+    const kitId = String(manifest.id);
+    const hash = kitContentHash(tmpBase);
+    const registry = loadRegistry(dest);
+    const existing = registry.kits.find((entry) => entry.id === kitId);
+    const target = installedPath(dest, kitId);
+    assertPathContained(dest, target);
+    const sourceText = repoUrl + (ref ? `#${ref}` : "");
+    if (existing && existing.source !== sourceText && !update) {
+      console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
+      return 2;
+    }
+    if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !force) {
+      console.log(`kit '${kitId}' is already installed from ${sourceText}`);
+      return 0;
+    }
+    copyDir(tmpBase, target);
+    const entry: Record<string, unknown> = {
+      id: kitId,
+      source: sourceText,
+      hash,
+      installed_at: existing && existing.source === sourceText && !update ? existing.installed_at : isoNow(),
+      installed_path: target,
+      state: "installed",
+    };
+    if (typeof manifest.version === "string" && manifest.version) entry.version = manifest.version;
+    registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
+    writeJson(registryPath(dest), registry);
+    console.log(`${existing ? "updated" : "installed"} git kit '${kitId}' from ${sourceText} at ${target}`);
+    return 0;
+  } finally {
+    fs.rmSync(tmpBase, { recursive: true, force: true });
+  }
+}
+
 function list(argv: string[]): number {
   const args = parseArgs(argv);
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
@@ -153,7 +260,8 @@ function activate(argv: string[]): number {
  * inspect <kit-dir> [--json]
  *
  * Derives conformance level (K0/K1/K2) and consumer targets from a kit's
- * observable asset classes. Exits 1 if the kit fails core container validation.
+ * observable asset classes. Delegates core container validation to @kontourai/flow.
+ * Exits 1 if the kit fails core container validation.
  * Outputs stable JSON suitable for use by catalog tooling and CI.
  *
  * K-levels (issue #52):
@@ -166,7 +274,7 @@ function activate(argv: string[]): number {
  *   flow-agents   present at K1+ (Flow Agents extension activated)
  *   <namespace>   unknown top-level keys list verbatim as third-party consumer targets
  */
-function inspect(argv: string[]): number {
+async function inspect(argv: string[]): Promise<number> {
   const args = parseArgs(argv);
   const kitDir = path.resolve(args.positionals[0] ?? ".");
   const manifestPath = path.join(kitDir, "kit.json");
@@ -181,116 +289,23 @@ function inspect(argv: string[]): number {
     console.error(`inspect: invalid JSON in ${manifestPath}: ${(err as Error).message}`);
     return 1;
   }
-  const result = deriveKitTargets(manifest);
+  // Pass the real kitDir so @kontourai/flow can validate flow file existence for K0.
+  const result = await deriveKitTargets(manifest, kitDir);
   console.log(JSON.stringify(result, null, 2));
   return result.conformance.k0 ? 0 : 1;
 }
 
-
-/**
- * install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>] [--force] [--update]
- *
- * Shallow-clones a remote git repository to a temporary directory, validates the kit
- * container with the same logic used by install-local, then delegates to the existing
- * install path. Supports an optional #ref fragment in the URL or a separate --ref flag.
- *
- * Implements kontourai/flow-agents#56 (git-ref install surface).
- */
-function installGit(argv: string[]): number {
-  const args = parseArgs(argv);
-  const rawUrl = args.positionals[0] ?? "";
-  if (!rawUrl) {
-    console.error("install-git: missing <repo-url> argument");
-    console.error("usage: flow-kit install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>]");
-    return 2;
-  }
-
-  // Parse ref: #fragment in URL takes precedence over --ref flag.
-  let repoUrl = rawUrl;
-  let ref: string | null = null;
-  const hashIdx = rawUrl.indexOf("#");
-  if (hashIdx !== -1) {
-    repoUrl = rawUrl.slice(0, hashIdx);
-    ref = rawUrl.slice(hashIdx + 1) || null;
-  }
-  if (!ref) ref = flagString(args.flags, "ref") ?? null;
-
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
-  const force = flagBool(args.flags, "force") ?? false;
-  const update = flagBool(args.flags, "update") ?? false;
-
-  // Shallow-clone into a temporary directory.
-  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "flow-kit-git-"));
-  try {
-    const cloneArgs = ["clone", "--depth", "1"];
-    if (ref) cloneArgs.push("--branch", ref);
-    cloneArgs.push("--", repoUrl, tmpBase);
-    try {
-      child_process.execFileSync("git", cloneArgs, { stdio: ["ignore", "pipe", "pipe"] });
-    } catch (err) {
-      const msg = err instanceof Error && (err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr
-        ? ((err as NodeJS.ErrnoException & { stderr?: Buffer }).stderr as Buffer).toString().trim()
-        : String(err);
-      console.error(`install-git: git clone failed: ${msg}`);
-      return 1;
-    }
-
-    // Validate the cloned kit using the same logic as install-local.
-    let manifest: Record<string, unknown>;
-    try {
-      manifest = assertKitRepository(tmpBase);
-    } catch (error) {
-      console.log("Flow Kit repository validation failed:");
-      for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) {
-        console.log(` - ${diagnostic}`);
-      }
-      return 1;
-    }
-
-    // Delegate to the shared install logic (copy + registry update).
-    const kitId = String(manifest.id);
-    const hash = kitContentHash(tmpBase);
-    const registry = loadRegistry(dest);
-    const existing = registry.kits.find((entry) => entry.id === kitId);
-    const target = installedPath(dest, kitId);
-    assertPathContained(dest, target);
-    const sourceText = repoUrl + (ref ? `#${ref}` : "");
-    if (existing && existing.source !== sourceText && !update) {
-      console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
-      return 2;
-    }
-    if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !force) {
-      console.log(`kit '${kitId}' is already installed from ${sourceText}`);
-      return 0;
-    }
-    copyDir(tmpBase, target);
-    const entry: Record<string, unknown> = {
-      id: kitId,
-      source: sourceText,
-      hash,
-      installed_at: existing && existing.source === sourceText && !update ? existing.installed_at : isoNow(),
-      installed_path: target,
-      state: "installed",
-    };
-    if (typeof manifest.version === "string" && manifest.version) entry.version = manifest.version;
-    registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
-    writeJson(registryPath(dest), registry);
-    console.log(`${existing ? "updated" : "installed"} git kit '${kitId}' from ${sourceText} at ${target}`);
-    return 0;
-  } finally {
-    fs.rmSync(tmpBase, { recursive: true, force: true });
-  }
-}
-
-export function main(argv = process.argv.slice(2)): number {
+export async function main(argv = process.argv.slice(2)): Promise<number> {
   const [command, ...rest] = argv;
-  if (command === "install-local") return installLocal(rest);
-  if (command === "install-git") return installGit(rest);
+  if (command === "install") return await install(rest);
+  // Legacy sub-subcommands forwarded for backward compatibility within the kit subcommand.
+  if (command === "install-local") return await installLocalSource(path.resolve(rest[0] ?? ""), rest);
+  if (command === "install-git") return await installGitSource(rest[0] ?? "", rest);
   if (command === "list") return list(rest);
   if (command === "status") return status(rest);
   if (command === "activate") return activate(rest);
-  if (command === "inspect") return inspect(rest);
-  console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
+  if (command === "inspect") return await inspect(rest);
+  console.error("usage: flow-agents kit <install|activate|inspect|list|status> ...");
   return 2;
 }
 
@@ -299,4 +314,4 @@ export function main(argv = process.argv.slice(2)): number {
 // 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(); }
+if (_selfRealPath === _argv1RealPath) { main().then((code) => { process.exitCode = code; }).catch((err) => { console.error(err); process.exitCode = 1; }); }

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { isoNow, relPath } from "../lib/fs.js";
@@ -61,4 +62,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/publish-change-helper.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { readJson } from "../lib/fs.js";
@@ -140,4 +141,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/pull-work-provider.ts

@@ -1,4 +1,5 @@
 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;
@@ -478,4 +479,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/runtime-adapter.ts

@@ -1,3 +1,5 @@
+import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
@@ -26,4 +28,9 @@ export function main(argv = process.argv.slice(2)): number {
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/usage-feedback.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+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";
@@ -415,4 +416,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/utterance-check.ts

@@ -1,4 +1,5 @@
 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";
 
@@ -321,4 +322,9 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
   return runCheck(rest);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(await main());
+// 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 = await main(); }

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const validTiers = new Set(["adapter", "design-target", "installed-command", "live-acceptance", "documented-runtime-gap"]);
 const validRuntimes = new Set(["codex", "claude-code", "kiro-cli"]);
@@ -116,4 +117,9 @@ export function main(argv = process.argv.slice(2)): number {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/validate-source-tree.ts

@@ -2,11 +2,11 @@ import * as path from "node:path";
 import { parseArgs } from "../lib/args.js";
 import { validateKitRepository } from "../flow-kit/validate.js";
 
-export function main(argv = process.argv.slice(2)): number {
+export async function main(argv = process.argv.slice(2)): Promise<number> {
   const args = parseArgs(argv);
   const kit = args.flags.kit;
   if (typeof kit === "string") {
-    const errors = validateKitRepository(path.resolve(kit));
+    const errors = await validateKitRepository(path.resolve(kit));
     if (errors.length) {
       console.log("Flow Kit repository validation failed:");
       for (const error of errors) console.log(` - ${error}`);
@@ -17,7 +17,7 @@ export function main(argv = process.argv.slice(2)): number {
   }
   const root = path.resolve(".");
   const builder = path.join(root, "kits", "builder");
-  const errors = validateKitRepository(builder);
+  const errors = await validateKitRepository(builder);
   if (errors.length) {
     console.log("Source tree validation failed:");
     for (const error of errors) console.log(` - ${error}`);
@@ -33,4 +33,4 @@ import * as _fsVST from "node:fs";
 import { fileURLToPath as _ftpVST } from "node:url";
 const _selfVST = (() => { try { return _fsVST.realpathSync(_ftpVST(import.meta.url)); } catch { return _ftpVST(import.meta.url); } })();
 const _argv1VST = (() => { try { return _fsVST.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
-if (_selfVST === _argv1VST) { process.exitCode = main(); }
+if (_selfVST === _argv1VST) { main().then((code) => { process.exitCode = code; }).catch((err) => { console.error(err); process.exitCode = 1; }); }

package/src/cli/veritas-governance.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
@@ -319,4 +320,9 @@ export function main(argv = process.argv.slice(2)): number {
   return options ? runEvidence(options) : 2;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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/src/cli/workflow-artifact-cleanup-audit.ts

@@ -1,4 +1,5 @@
 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";
 
@@ -278,4 +279,9 @@ export function main(argv = process.argv.slice(2)): number {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());
+// 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(); }