@kontourai/flow-agents 2.2.0 → 2.4.0

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) => {
@@ -486,12 +496,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}`);

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -16,7 +16,7 @@ const ACTIVE_STATUSES = new Set([
 const KNOWN_LEARNING_STATUSES = new Set(["pending", "learned", "followup_required", "blocked"]);
 const KNOWN_LEARNING_ROUTE_TARGETS = new Set(["rule", "skill", "power", "agent", "eval", "doc", "backlog", "knowledge", "none"]);
 const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["completed", "open", "deferred", "accepted", "rejected"]);
-const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
 function printHelp() {
     console.log("Usage: flow-agents workflow-artifact-cleanup-audit [--artifact-root <path>] [--json]");
@@ -24,7 +24,7 @@ function printHelp() {
     console.log("Read-only dry-run audit for local workflow artifact directories.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents, with .flow-agents read fallback)");
+    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents)");
     console.log("  --json                  Print stable JSON buckets instead of text");
     console.log("  --help                  Show this help");
     console.log("");
@@ -148,6 +148,34 @@ function invalidItem(slug, workflowPath, reason) {
         reasons: [reason],
     };
 }
+// Promote-then-archive gate (issue #312). A delivered session's durable residue
+// (decisions, vocabulary, learnings, doc updates) must be PROMOTED before the session
+// is archived. Promotion is recorded as a session-local promotion claim in the session
+// trust.bundle (workflow-sidecar promote), detectable here via claim.metadata.promotion
+// — no new manifest entry required. A delivered/accepted session that reached a terminal
+// shape WITHOUT that claim is a cleanup_candidate (blocked from archive) with a remedy
+// naming the promote step. Already-`archived` sessions are past the gate and are never
+// re-flagged (issue #312 non-goal: do not backfill already-archived sessions).
+const PROMOTE_REMEDY = "run `flow-agents workflow-sidecar promote <dir> --evidence-path <durable-doc> ...`" +
+    " (or `promote --none --reason \"<why nothing durable>\"`) to record the promotion claim before archiving";
+function hasPromotionClaim(workflowDir) {
+    const bundlePath = path.join(workflowDir, "trust.bundle");
+    if (!fs.existsSync(bundlePath))
+        return false;
+    const parsed = readJson(bundlePath, "trust.bundle");
+    if (!parsed.ok)
+        return false;
+    const bundle = objectValue(parsed.value);
+    if (!bundle || !Array.isArray(bundle.claims))
+        return false;
+    return bundle.claims.some((entry) => {
+        const claim = objectValue(entry);
+        if (!claim)
+            return false;
+        const meta = objectValue(claim.metadata);
+        return meta !== null && objectValue(meta.promotion) !== null;
+    });
+}
 function classifyWorkflow(slug, workflowPath) {
     const statePath = path.join(workflowPath, "state.json");
     if (!fs.existsSync(statePath))
@@ -185,9 +213,15 @@ function classifyWorkflow(slug, workflowPath) {
         return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
     }
     if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
+        if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+            return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };
+        }
         return { ...base, classification: "terminal_done", reasons: [`${status} workflow is in phase done`] };
     }
     if ((status === "accepted" || status === "archived") && learning.reasons.length === 0) {
+        if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+            return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow has closed learning routing but no promotion claim; ${PROMOTE_REMEDY}`] };
+        }
         return { ...base, classification: "terminal_done", reasons: [`${status} workflow has no open learning routing`] };
     }
     return { ...base, classification: "invalid", reasons: [`unrecognized lifecycle shape: status=${status}, phase=${phase}, next_action.status=${nextStatus ?? "missing"}`] };

package/build/src/cli/workflow-sidecar.d.ts

@@ -80,7 +80,7 @@ type SurfaceModule = {
         status: string;
         policyId: string | undefined;
     };
-    generateClaimId: (subjectId: string, surface: string, fieldOrBehavior: string) => string;
+    generateClaimId: (subjectId: string, facet: string, fieldOrBehavior: string) => string;
     statusFunctionVersion: string;
     resolveInquiry: (bundle: Record<string, unknown>, inquiry: SurfaceInquiry, options?: {
         now?: Date;
@@ -208,10 +208,17 @@ export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt:
  * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
  * session artifact dir to <repoRoot>/delivery/.
  *
- * Fail-soft: if trust.bundle is absent, returns without throwing.
+ * Fail-soft on a missing bundle: if trust.bundle is absent, returns without throwing.
+ * Fail-CLOSED on repo-root resolution: repoRoot must be a real, resolved kits/ ancestor
+ * (see findRepoRootFromDirStrict) — null (no ancestor found) skips the publish with a
+ * visible warning instead of writing to whatever process.cwd() happens to be. This
+ * prevents a scratch/test session dir (no kits/ ancestor) from silently clobbering an
+ * unrelated real repo's delivery/trust.bundle when invoked with that repo as cwd (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings at
+ * .kontourai/flow-agents/ws5-governance-kit-slice1 for the root cause this fixes).
  * Idempotent: overwrites on re-delivery.
  */
-export declare function publishDelivery(dir: string, repoRoot: string): Promise<void>;
+export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;
 export declare function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj;
 /** Shape of a claim from the trust.bundle */
@@ -219,7 +226,7 @@ export interface TrustClaim {
     id: string;
     subjectType: string;
     subjectId: string;
-    surface: string;
+    facet?: string;
     claimType: string;
     fieldOrBehavior: string;
     value: string;
@@ -236,7 +243,7 @@ export interface BundleFile {
     events: AnyObj[];
     policies: AnyObj[];
 }
-/** The gate block signal read from .flow-agents/.goal-fit-block-streak.json */
+/** The gate block signal read from .kontourai/flow-agents/.goal-fit-block-streak.json */
 export interface GateBlockSignal {
     /** True when the streak file exists AND count >= 1 */
     blocked: boolean;
@@ -251,13 +258,13 @@ export interface GateBlockSignal {
  */
 export type GateCalibration = "correct" | "false_block" | "missed_block";
 /**
- * Read the gate block signal from .flow-agents/.goal-fit-block-streak.json
+ * Read the gate block signal from .kontourai/flow-agents/.goal-fit-block-streak.json
  * (written by scripts/hooks/stop-goal-fit.js when block mode fires).
  * The file sits at <artifact-root>/.goal-fit-block-streak.json — one level
  * above the session artifact dir. Fail-open: returns { blocked: false } when
  * the file is absent or unreadable.
  *
- * @param artifactRoot  The .flow-agents root dir (parent of session slug dir).
+ * @param artifactRoot  The runtime artifact root dir (parent of session slug dir).
  */
 export declare function readGateBlockSignal(artifactRoot: string): GateBlockSignal;
 /**