@kontourai/flow-agents 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.0.1](https://github.com/kontourai/flow-agents/compare/v1.0.0...v1.0.1) (2026-06-12)
+
+
+### Fixes
+
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55) [#56](https://github.com/kontourai/flow-agents/issues/56) [#57](https://github.com/kontourai/flow-agents/issues/57)) ([3350cb1](https://github.com/kontourai/flow-agents/commit/3350cb15f44bff92d8d9c57f447761d0e1a1b20c))
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55), [#56](https://github.com/kontourai/flow-agents/issues/56), [#57](https://github.com/kontourai/flow-agents/issues/57)) ([13bf732](https://github.com/kontourai/flow-agents/commit/13bf732ff365efa84423e9ea46042e501d202db8))
+
 ## [1.0.0](https://github.com/kontourai/flow-agents/compare/v0.4.0...v1.0.0) (2026-06-12)
 
 

package/build/src/cli/flow-kit.js

@@ -1,6 +1,9 @@
+import * as child_process from "node:child_process";
 import * as crypto from "node:crypto";
 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, 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";
@@ -27,6 +30,22 @@ function contentHash(root) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
+/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+function kitContentHash(root) {
+    const EXCLUDE_DIRS = new Set([".git", "__pycache__", ".pytest_cache"]);
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(root)) {
+        const parts = path.relative(root, file).split(path.sep);
+        if (parts.some((p) => EXCLUDE_DIRS.has(p)))
+            continue;
+        const rel = parts.join("/");
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
 function installLocal(argv) {
     const args = parseArgs(argv);
     const source = path.resolve(args.positionals[0] ?? "");
@@ -36,13 +55,11 @@ function installLocal(argv) {
         manifest = assertKitRepository(source);
     }
     catch (error) {
-        console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
         console.log("Flow Kit repository validation failed:");
         for (const diagnostic of (error.diagnostics ?? [error.message]))
             console.log(` - ${diagnostic}`);
         return 1;
     }
-    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
     const kitId = String(manifest.id);
     const hash = contentHash(source);
     const registry = loadRegistry(dest);
@@ -163,10 +180,107 @@ function inspect(argv) {
     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) {
+    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 = 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.stderr
+                ? err.stderr.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;
+        try {
+            manifest = assertKitRepository(tmpBase);
+        }
+        catch (error) {
+            console.log("Flow Kit repository validation failed:");
+            for (const diagnostic of (error.diagnostics ?? [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 = {
+            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)) {
     const [command, ...rest] = argv;
     if (command === "install-local")
         return installLocal(rest);
+    if (command === "install-git")
+        return installGit(rest);
     if (command === "list")
         return list(rest);
     if (command === "status")
@@ -175,8 +289,24 @@ export function main(argv = process.argv.slice(2)) {
         return activate(rest);
     if (command === "inspect")
         return inspect(rest);
-    console.error("usage: flow-kit <install-local|list|status|activate|inspect> ...");
+    console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
     return 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/build/src/cli/validate-source-tree.js

@@ -27,5 +27,22 @@ export function main(argv = process.argv.slice(2)) {
     console.log("Source tree validation passed");
     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).
+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();
+}

package/build/src/runtime-adapters.js

@@ -74,7 +74,7 @@ export function readKitInventory(sourceRoot, dest) {
     const assets = [];
     const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
     if (!fs.existsSync(catalogPath))
-        errors.push(`${catalogPath}: missing Kit Catalog`);
+        warnings.push(`${catalogPath}: built-in Kit Catalog not found; skipping built-in kits (this is normal when running outside a flow-agents checkout)`);
     else {
         const catalog = readJson(catalogPath);
         const kits = catalog.kits;

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

@@ -84,7 +84,7 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
-    ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
+    ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
     ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
     ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
     ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],

package/docs/fixture-ownership.md

@@ -16,7 +16,7 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |
-| `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
+| `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/integration/test_activate_npx_context.sh`, `evals/integration/test_flow_kit_install_git.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
 | `evals/fixtures/kit-conformance-levels` | K-level conformance and consumer-target derivation fixtures | `evals/integration/test_kit_conformance_levels.sh` | Keep while K-level derivation, degradation invariant, and consumer-target badge rules are tested. |
 | `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |

package/evals/integration/test_activate_npx_context.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# test_activate_npx_context.sh — Verify that activate exits 0 in an npx-like context
+# where there is no kits/catalog.json at the source-root.
+# Implements acceptance criteria for kontourai/flow-agents#57.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+CLI="$ROOT/scripts/flow-kit.js"
+MIXED_SRC="$ROOT/evals/fixtures/flow-kit-repository/mixed-runtime-kit"
+
+echo "=== activate npx-context Checks (Issue #57) ==="
+
+# Simulate the npx context: an empty source-root (no kits/catalog.json present).
+NPX_SIMULATED_ROOT="$TMP_DIR/simulated-npx-root"
+mkdir -p "$NPX_SIMULATED_ROOT"
+DEST="$TMP_DIR/dest"
+mkdir -p "$DEST"
+
+# Install a kit into the destination workspace first.
+install_out="$TMP_DIR/install.out"
+if flow_agents_node "$CLI" install-local "$MIXED_SRC" --dest "$DEST" >"$install_out" 2>&1; then
+  pass "mixed-runtime-kit installs into workspace"
+else
+  fail "install failed (prerequisite step)"
+  sed -n '1,80p' "$install_out"
+fi
+
+# --- Test 1: activate with no catalog.json at source-root exits 0 ---
+# This simulates the npx context: source-root points at an npm cache dir with no kits/catalog.json.
+activate_out="$TMP_DIR/activate-npx.out"
+if flow_agents_node "$CLI" activate --dest "$DEST" --source-root "$NPX_SIMULATED_ROOT" >"$activate_out" 2>&1; then
+  pass "activate exits 0 when source-root has no catalog.json (npx context)"
+else
+  fail "activate exits non-zero when source-root has no catalog.json — false failure in npx context"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 2: missing catalog warning appears but not as an error ---
+if node - "$activate_out" <<'NODE'
+const fs = require("node:fs");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+// errors must be empty — missing catalog is not an error
+if (Array.isArray(data.errors) && data.errors.length > 0) {
+  throw new Error(`activate reported errors: ${JSON.stringify(data.errors)}`);
+}
+// warnings may mention catalog (but must not be errors)
+const catalogWarning = Array.isArray(data.warnings) && data.warnings.some((w) => w.includes("catalog") || w.includes("Catalog"));
+// It's fine either way — the key invariant is errors=[].
+console.log(`warnings: ${JSON.stringify(data.warnings)}`);
+console.log(`catalog mentioned in warnings: ${catalogWarning}`);
+console.log("ok");
+NODE
+then
+  pass "activate with missing catalog produces no errors (warnings only)"
+else
+  fail "activate diagnostic structure incorrect"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 3: user-installed kits ARE activated even without catalog.json ---
+if node - "$activate_out" "$DEST" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+const dest = process.argv[3];
+// mixed-runtime-kit has a flow with id "mixed.runtime" — it should be in generated_runtime_files
+const ids = new Set(data.generated_runtime_files.map((item) => item.asset_id));
+if (!ids.has("mixed.runtime")) {
+  throw new Error(`user-installed kit flow not activated; generated ids: ${[...ids].join(", ")}`);
+}
+// The generated file must exist on disk
+for (const item of data.generated_runtime_files) {
+  if (item.asset_class === "activation-manifest") continue;
+  const generatedPath = path.join(dest, item.path);
+  if (!fs.existsSync(generatedPath)) throw new Error(`generated file missing on disk: ${generatedPath}`);
+}
+console.log("ok");
+NODE
+then
+  pass "user-installed kits are activated correctly even without catalog.json"
+else
+  fail "user-installed kit flows missing from activation output"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 4: built-in kits also activate when catalog.json IS present (regression guard) ---
+activate_builtin_out="$TMP_DIR/activate-builtin.out"
+if flow_agents_node "$CLI" activate --dest "$DEST" --source-root "$ROOT" >"$activate_builtin_out" 2>&1; then
+  pass "activate with catalog.json present still exits 0 (regression guard)"
+else
+  fail "activate with catalog.json present failed (regression)"
+  sed -n '1,120p' "$activate_builtin_out"
+fi
+
+if node - "$activate_builtin_out" <<'NODE'
+const fs = require("node:fs");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+if (Array.isArray(data.errors) && data.errors.length > 0) {
+  throw new Error(`regression: activate with catalog.json reported errors: ${JSON.stringify(data.errors)}`);
+}
+// Should have builder kit flows from catalog
+const ids = new Set(data.generated_runtime_files.map((item) => item.asset_id));
+if (!ids.has("builder.shape") && !ids.has("builder.build")) {
+  throw new Error(`built-in kit flows missing when catalog.json is present`);
+}
+console.log("ok");
+NODE
+then
+  pass "built-in kit flows present when catalog.json is available (regression)"
+else
+  fail "built-in kit flows missing — regression introduced"
+  sed -n '1,120p' "$activate_builtin_out"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "activate npx-context checks passed."
+  exit 0
+fi
+
+echo "activate npx-context checks failed: $errors issue(s)."
+exit 1

package/evals/integration/test_flow_kit_install_git.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# test_flow_kit_install_git.sh — Exercise flow-kit install-git with a file:// git URL fixture.
+# No network required: the fixture is a bare git repo created from the existing valid-local-kit.
+# Implements acceptance criteria for kontourai/flow-agents#56.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+CLI="$ROOT/scripts/flow-kit.js"
+VALID_SRC="$ROOT/evals/fixtures/flow-kit-repository/valid-local-kit"
+DEST="$TMP_DIR/install-dest"
+mkdir -p "$DEST"
+
+echo "=== install-git Checks (Issue #56) ==="
+
+# --- Fixture setup: create a bare git repo from the valid-local-kit fixture ---
+FIXTURE_REPO="$TMP_DIR/fixture-bare-repo"
+FIXTURE_WORKING="$TMP_DIR/fixture-working"
+cp -R "$VALID_SRC" "$FIXTURE_WORKING"
+(cd "$FIXTURE_WORKING" && git init -q && git config user.email "test@test.local" && git config user.name "test" && git add -A && git commit -q -m "init")
+git clone -q --bare "$FIXTURE_WORKING" "$FIXTURE_REPO"
+FILE_URL="file://$FIXTURE_REPO"
+
+echo "  (fixture repo: $FILE_URL)"
+
+# --- Test 1: basic install-git from file:// URL ---
+install_out="$TMP_DIR/install-git.out"
+if flow_agents_node "$CLI" install-git "$FILE_URL" --dest "$DEST" >"$install_out" 2>&1; then
+  pass "install-git from file:// URL succeeds"
+else
+  fail "install-git from file:// URL failed"
+  sed -n '1,80p' "$install_out"
+fi
+
+REGISTRY="$DEST/kits/local/installed-kits.json"
+if [[ -f "$REGISTRY" ]]; then
+  pass "install-git writes registry file"
+else
+  fail "install-git did not write registry file"
+fi
+
+if node - "$REGISTRY" "$FILE_URL" <<'NODE'
+const fs = require("node:fs");
+const registry = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const entry = registry.kits[0];
+if (!entry) throw new Error("no kits in registry");
+for (const key of ["id", "source", "hash", "installed_at", "installed_path", "state"]) {
+  if (!(key in entry)) throw new Error(`missing metadata key: ${key}`);
+}
+if (entry.id !== "example-kit") throw new Error(`unexpected id: ${entry.id}`);
+if (!entry.hash.startsWith("sha256:")) throw new Error("hash should include sha256 prefix");
+if (Number.isNaN(Date.parse(entry.installed_at))) throw new Error("installed_at should be ISO parseable");
+if (!fs.existsSync(entry.installed_path + "/kit.json")) throw new Error("installed kit copy missing kit.json");
+const expectedSource = process.argv[3];
+if (!entry.source.startsWith(expectedSource.replace(/\/$/, ""))) throw new Error(`source mismatch: ${entry.source}`);
+console.log("ok");
+NODE
+then
+  pass "install-git records correct provenance metadata"
+else
+  fail "install-git metadata is incomplete"
+fi
+
+# --- Test 2: idempotent re-install from same URL ---
+idempotent_out="$TMP_DIR/idempotent.out"
+registry_hash_before="$(shasum -a 256 "$REGISTRY" | awk '{print $1}')"
+if flow_agents_node "$CLI" install-git "$FILE_URL" --dest "$DEST" >"$idempotent_out" 2>&1 \
+  && grep -q "already installed" "$idempotent_out" \
+  && [[ "$registry_hash_before" == "$(shasum -a 256 "$REGISTRY" | awk '{print $1}')" ]]; then
+  pass "install-git same-URL reinstall is idempotent"
+else
+  fail "install-git same-URL reinstall was not idempotent"
+  sed -n '1,80p' "$idempotent_out"
+fi
+
+# --- Test 3: #ref fragment syntax ---
+ref_out="$TMP_DIR/ref.out"
+DEST2="$TMP_DIR/dest-with-ref"
+mkdir -p "$DEST2"
+# Re-create fixture repo with a tagged commit so we can test #ref
+FIXTURE_WORKING2="$TMP_DIR/fixture-working2"
+FIXTURE_REPO2="$TMP_DIR/fixture-bare-repo2"
+cp -R "$VALID_SRC" "$FIXTURE_WORKING2"
+(cd "$FIXTURE_WORKING2" && git init -q && git config user.email "test@test.local" && git config user.name "test" && git add -A && git commit -q -m "init" && git tag v1.0)
+git clone -q --bare "$FIXTURE_WORKING2" "$FIXTURE_REPO2"
+FILE_URL2="file://$FIXTURE_REPO2"
+
+if flow_agents_node "$CLI" install-git "${FILE_URL2}#v1.0" --dest "$DEST2" >"$ref_out" 2>&1; then
+  pass "install-git with #ref fragment succeeds"
+else
+  fail "install-git with #ref fragment failed"
+  sed -n '1,80p' "$ref_out"
+fi
+
+if node - "$DEST2/kits/local/installed-kits.json" "${FILE_URL2}#v1.0" <<'NODE'
+const fs = require("node:fs");
+const registry = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const entry = registry.kits.find((e) => e.id === "example-kit");
+if (!entry) throw new Error("kit not found in registry");
+const expectedSource = process.argv[3];
+if (entry.source !== expectedSource) throw new Error(`source mismatch: expected ${expectedSource}, got ${entry.source}`);
+console.log("ok");
+NODE
+then
+  pass "install-git #ref stored in source metadata"
+else
+  fail "install-git #ref not stored correctly in source metadata"
+fi
+
+# --- Test 4: --ref flag syntax ---
+ref_flag_out="$TMP_DIR/ref-flag.out"
+DEST3="$TMP_DIR/dest-with-ref-flag"
+mkdir -p "$DEST3"
+if flow_agents_node "$CLI" install-git "$FILE_URL2" --ref v1.0 --dest "$DEST3" >"$ref_flag_out" 2>&1; then
+  pass "install-git with --ref flag succeeds"
+else
+  fail "install-git with --ref flag failed"
+  sed -n '1,80p' "$ref_flag_out"
+fi
+
+# --- Test 5: missing git URL exits non-zero ---
+missing_url_out="$TMP_DIR/missing-url.out"
+if flow_agents_node "$CLI" install-git --dest "$DEST" >"$missing_url_out" 2>&1; then
+  fail "install-git with no URL should exit non-zero"
+  sed -n '1,40p' "$missing_url_out"
+else
+  pass "install-git with no URL exits non-zero with usage message"
+fi
+
+# --- Test 6: invalid git URL exits non-zero ---
+invalid_url_out="$TMP_DIR/invalid-url.out"
+if flow_agents_node "$CLI" install-git "file:///nonexistent-repo-that-does-not-exist" --dest "$DEST" >"$invalid_url_out" 2>&1; then
+  fail "install-git with invalid URL should exit non-zero"
+  sed -n '1,40p' "$invalid_url_out"
+else
+  pass "install-git with invalid URL exits non-zero"
+fi
+
+# --- Test 7: catalog.json not mutated ---
+CATALOG_HASH_BEFORE="$(shasum -a 256 "$ROOT/kits/catalog.json" | awk '{print $1}')"
+# (all operations above have already run)
+if [[ "$CATALOG_HASH_BEFORE" == "$(shasum -a 256 "$ROOT/kits/catalog.json" | awk '{print $1}')" ]]; then
+  pass "install-git does not mutate source kits/catalog.json"
+else
+  fail "source kits/catalog.json changed during install-git test"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "install-git checks passed."
+  exit 0
+fi
+
+echo "install-git checks failed: $errors issue(s)."
+exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/src/cli/flow-kit.ts

@@ -1,6 +1,9 @@
+import * as child_process from "node:child_process";
 import * as crypto from "node:crypto";
 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, 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";
@@ -31,6 +34,22 @@ function contentHash(root: string): string {
   return `sha256:${hash.digest("hex")}`;
 }
 
+/** 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");
+  for (const file of walkFiles(root)) {
+    const parts = path.relative(root, file).split(path.sep);
+    if (parts.some((p) => EXCLUDE_DIRS.has(p))) continue;
+    const rel = parts.join("/");
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
 function installLocal(argv: string[]): number {
   const args = parseArgs(argv);
   const source = path.resolve(args.positionals[0] ?? "");
@@ -39,12 +58,10 @@ function installLocal(argv: string[]): number {
   try {
     manifest = assertKitRepository(source);
   } catch (error) {
-    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
     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;
   }
-  console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
   const kitId = String(manifest.id);
   const hash = contentHash(source);
   const registry = loadRegistry(dest);
@@ -169,15 +186,117 @@ function inspect(argv: string[]): number {
   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 {
   const [command, ...rest] = argv;
   if (command === "install-local") return installLocal(rest);
+  if (command === "install-git") return installGit(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|list|status|activate|inspect> ...");
+  console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
   return 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/validate-source-tree.ts

@@ -27,4 +27,10 @@ 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).
+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(); }

package/src/runtime-adapters.ts

@@ -86,7 +86,7 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
   const errors: string[] = [];
   const assets: KitAsset[] = [];
   const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
-  if (!fs.existsSync(catalogPath)) errors.push(`${catalogPath}: missing Kit Catalog`);
+  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)`);
   else {
     const catalog = readJson(catalogPath) as Record<string, unknown>;
     const kits = catalog.kits;

package/src/tools/validate-source-tree.ts

@@ -84,7 +84,7 @@ const fixtureOwnerPolicies = new Map<string, { owners: string[]; classification:
   ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
   ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
   ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
-  ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
+  ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
   ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
   ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
   ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],