@kontourai/flow-agents 1.1.0 → 1.3.0

package/build/src/cli/workflow-sidecar.js

@@ -2,6 +2,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
 const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
@@ -19,6 +20,51 @@ function appendJsonl(file, payload) {
 }
 function die(message) { throw new Error(message); }
 function slugify(value, fallback) { return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || fallback; }
+// Optional Hachure trust-bundle validation. No-ops gracefully when hachure is not installed.
+// Install hachure (^0.4.0) as an optional dependency to enable schema validation.
+function tryLoadHachureValidator() {
+    try {
+        const _require = createRequire(import.meta.url);
+        const hachureDir = path.dirname(_require.resolve("hachure"));
+        const schemasDir = path.join(hachureDir, "schemas");
+        const Ajv = _require("ajv/dist/2020");
+        const schemas = {};
+        for (const file of fs.readdirSync(schemasDir)) {
+            if (!file.endsWith(".schema.json"))
+                continue;
+            schemas[file] = JSON.parse(fs.readFileSync(path.join(schemasDir, file), "utf8"));
+        }
+        const ajv = new Ajv({ strict: false, allErrors: true });
+        for (const [filename, schema] of Object.entries(schemas)) {
+            if (filename === "trust-bundle.schema.json")
+                continue;
+            ajv.addSchema(schema, filename);
+        }
+        const trustBundleSchema = schemas["trust-bundle.schema.json"];
+        if (!trustBundleSchema)
+            return null;
+        const validate = ajv.compile(trustBundleSchema);
+        return (bundle) => {
+            const valid = validate(bundle);
+            if (valid)
+                return { valid: true, errors: [] };
+            const errors = (validate.errors ?? []).map((err) => {
+                const loc = err.instancePath || err.schemaPath || "";
+                return `${loc} ${err.message ?? "invalid"}`.trim();
+            });
+            return { valid: false, errors };
+        };
+    }
+    catch {
+        return null;
+    }
+}
+let _hachureValidator;
+function getHachureValidator() {
+    if (_hachureValidator === undefined)
+        _hachureValidator = tryLoadHachureValidator();
+    return _hachureValidator;
+}
 function safeRepoIdentifier(value) {
     const trimmed = value.trim().replace(/\.git$/, "");
     if (!trimmed || trimmed.length > 120)
@@ -444,14 +490,32 @@ function normalizeCheck(raw) {
 function normalizeSurfaceRefs(refs) {
     if (!Array.isArray(refs))
         die("surface_trust_refs must be an array");
+    const hachureValidate = getHachureValidator();
     return refs.map((ref) => {
         const keys = JSON.stringify(ref).match(/"([^"]+)":/g) ?? [];
         for (const key of keys.map((k) => k.slice(1, -2)))
             if (key.toLowerCase().includes("veritas"))
                 die(`unsupported field in Surface trust ref: ${key}`);
         const out = { ...ref };
-        if (!["TrustReport", "Trust Snapshot"].includes(out.artifact_kind))
-            die("artifact_kind must be one of");
+        // trust.bundle is the canonical Hachure-aligned artifact kind; TrustReport/Trust Snapshot are legacy aliases
+        if (!["trust.bundle", "TrustReport", "Trust Snapshot"].includes(out.artifact_kind))
+            die("artifact_kind must be one of: trust.bundle, TrustReport, Trust Snapshot");
+        // When hachure is installed, validate the referenced trust artifact if it is a local file
+        if (hachureValidate && out.artifact_ref && typeof out.artifact_ref === "string" && fs.existsSync(out.artifact_ref)) {
+            try {
+                const bundle = JSON.parse(fs.readFileSync(out.artifact_ref, "utf8"));
+                const result = hachureValidate(bundle);
+                if (!result.valid) {
+                    const errorSummary = result.errors.slice(0, 3).join("; ");
+                    die(`trust.bundle artifact at ${out.artifact_ref} failed Hachure schema validation: ${errorSummary}`);
+                }
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.includes("failed Hachure schema validation"))
+                    throw err;
+                // File read or parse errors are not re-thrown: the artifact_ref validation path is advisory
+            }
+        }
         const status = deriveSurfaceStatus(out);
         if (out.status === "pass" && status !== "pass")
             die("surface_trust_refs contradicts Surface trust facts");
@@ -474,17 +538,18 @@ function surfaceCheckFromArtifact(file, index) {
     const lower = JSON.stringify(raw).toLowerCase();
     let ref;
     if (lower.includes("provider") && lower.includes("absent")) {
-        ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
     }
     else if (lower.includes("artifact") && lower.includes("absent")) {
-        ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
     }
     else {
         const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
         const freshness = lower.includes("stale") ? "stale" : "fresh";
         const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
         const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
-        ref = { artifact_kind: file.includes("snapshot") ? "Trust Snapshot" : "TrustReport", artifact_ref: file, gate_id: "builder.surface.claim", claim_type: "surface.claim", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+        // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
+        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "builder.trust.bundle", claim_type: "builder.trust.bundle", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
         ref.status = deriveSurfaceStatus(ref);
         ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
     }

package/build/src/cli.js

@@ -2,7 +2,7 @@
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
-import { main as flowKit } from "./cli/flow-kit.js";
+import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
 import { main as init } from "./cli/init.js";
 import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
@@ -27,7 +27,7 @@ const availableCommands = new Map([
     ["effective-backlog-settings", effectiveBacklogSettings],
     ["filter-installed-packs", filterInstalledPacks],
     ["fixture-retirement-audit", fixtureRetirementAudit],
-    ["flow-kit", flowKit],
+    ["kit", kit],
     ["init", init],
     ["promote-workflow-artifact", promoteWorkflowArtifact],
     ["publish-change", publishChange],
@@ -49,7 +49,7 @@ const aliases = new Map([
     ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
     ["flow-agents-filter-installed-packs", "filter-installed-packs"],
     ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
-    ["flow-agents-flow-kit", "flow-kit"],
+    ["flow-agents-kit", "kit"],
     ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
     ["flow-agents-publish-change", "publish-change"],
     ["flow-agents-pull-work-provider", "pull-work-provider"],

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

@@ -1,52 +1,79 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readJson } from "../lib/fs.js";
-const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+// Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"];
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
 // agent-extension fields are skills, docs, adapters, evals, assets.
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
 const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
 /**
- * Validates that the manifest satisfies the core Flow Kit container contract
- * (as specified by kontourai/flow PR #67) with all agent-extension fields stripped.
- * Returns a list of violation messages (empty = valid).
+ * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
  *
- * The degradation invariant: every Flow Agents Kit MUST remain a valid core
- * Flow Kit container when agent-extension fields are ignored.
+ * Criteria for inclusion:
+ *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
+ *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
+ *   3. Kontour owns and maintains the kit's content and release lifecycle.
+ *
+ * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
+ * Third-party forks or community kits published elsewhere are NOT first-party, even if they
+ * share a similar id — first-party is tied to provenance in this specific repository.
  */
-export function validateCoreContainer(manifest, label) {
-    const errors = [];
-    if (manifest.schema_version !== "1.0") {
-        errors.push(`${label}: .schema_version must be "1.0"`);
-    }
-    if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
-        errors.push(`${label}: .id must be a stable kebab-case string`);
+export const FIRST_PARTY_KIT_IDS = new Set(["builder", "knowledge"]);
+/**
+ * Derive the trust level for a kit id.
+ *
+ * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
+ * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ */
+export function deriveKitTrust(kitId) {
+    if (FIRST_PARTY_KIT_IDS.has(kitId))
+        return "first-party";
+    return "unverified";
+}
+let _validateKitContainerCache = null;
+async function loadValidateKitContainer() {
+    if (_validateKitContainerCache)
+        return _validateKitContainerCache;
+    let mod;
+    try {
+        mod = await import("@kontourai/flow");
     }
-    if (typeof manifest.name !== "string" || !manifest.name.trim()) {
-        errors.push(`${label}: .name must be a non-empty string`);
+    catch (err) {
+        throw new Error("container validation requires @kontourai/flow; run from an npm-installed flow-agents workspace " +
+            `or use 'flow kit validate' (original error: ${err.message})`);
     }
-    if (!Array.isArray(manifest.flows) || manifest.flows.length === 0) {
-        errors.push(`${label}: .flows must be a non-empty list`);
+    if (typeof mod.validateKitContainer !== "function") {
+        throw new Error("@kontourai/flow did not export validateKitContainer");
     }
-    else {
-        manifest.flows.forEach((entry, index) => {
-            if (typeof entry !== "object" || entry === null) {
-                errors.push(`${label}: flows[${index}] must be an object`);
-                return;
-            }
-            const flow = entry;
-            if (typeof flow.id !== "string" || !flow.id) {
-                errors.push(`${label}: flows[${index}].id must be a string`);
-            }
-            if (typeof flow.path !== "string" || !flow.path) {
-                errors.push(`${label}: flows[${index}].path must be a string`);
-            }
-        });
-    }
-    return errors;
+    _validateKitContainerCache = mod.validateKitContainer;
+    return _validateKitContainerCache;
 }
 /**
- * Derives the consumer-target level (K0/K1/K2) and target audience list from
+ * Delegates core Flow Kit container validation to @kontourai/flow's validateKitContainer.
+ * The container contract lives once, in Flow. Returns a list of violation messages (empty = valid).
+ *
+ * The degradation invariant: every Flow Agents Kit MUST remain a valid core
+ * Flow Kit container when agent-extension fields are ignored.
+ *
+ * Loads @kontourai/flow lazily (on first call) so that runtime ops (list/status/activate)
+ * that never invoke validation can run in standalone installed bundles where
+ * @kontourai/flow is not present.
+ *
+ * @param kitDir  Real kit directory path for file-existence checks on flows[].path entries.
+ *                Pass the actual kit directory when available; pass "" for structural-only checks.
+ */
+async function delegateCoreContainerValidation(kitDir, manifest) {
+    const validateKitContainer = await loadValidateKitContainer();
+    const result = validateKitContainer(kitDir, manifest);
+    if (result.valid)
+        return [];
+    return result.diagnostics
+        .filter((d) => d.severity === "error")
+        .map((d) => `${d.path}: ${d.message}`);
+}
+/**
+ * Derives the consumer-target level (K0/K1/K2), target audience list, and trust level from
  * observable asset classes in the kit manifest. Does not require file I/O.
  *
  * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
@@ -56,11 +83,20 @@ export function validateCoreContainer(manifest, label) {
  *  - targets.flow: always present when K0 (any Flow consumer can evaluate gates).
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
+ *
+ * Trust derivation (from kontourai/flow-agents#79):
+ *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
+ *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ *
+ * @param manifest  The kit.json manifest object.
+ * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
+ *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
  */
-export function deriveKitTargets(manifest) {
+export async function deriveKitTargets(manifest, kitDir = "") {
     const kitId = typeof manifest.id === "string" ? manifest.id : "<unknown>";
     const kitName = typeof manifest.name === "string" ? manifest.name : "<unknown>";
-    const coreErrors = validateCoreContainer(manifest, "kit.json");
+    // Delegate core container validation to @kontourai/flow.
+    const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
     const k0 = coreErrors.length === 0;
     const hasAgentExtension = AGENT_EXTENSION_CLASSES.size > 0 &&
         [...AGENT_EXTENSION_CLASSES].some((cls) => Array.isArray(manifest[cls]) && manifest[cls].length > 0);
@@ -79,15 +115,18 @@ export function deriveKitTargets(manifest) {
         targets.push("flow-agents");
     for (const ns of thirdPartyExtensions)
         targets.push(ns);
+    // Derive trust level orthogonally to the K-level capability axis.
+    const trust = deriveKitTrust(kitId);
     return {
         kit_id: kitId,
         kit_name: kitName,
         conformance: { k0, k1, k2 },
         targets,
         third_party_extensions: thirdPartyExtensions,
+        trust,
     };
 }
-export function validateKitRepository(kitDir) {
+export async function validateKitRepository(kitDir) {
     const errors = [];
     const manifestPath = path.join(kitDir, "kit.json");
     let manifest;
@@ -98,27 +137,16 @@ export function validateKitRepository(kitDir) {
         errors.push(`${manifestPath}: invalid JSON: ${error.message}`);
         return errors;
     }
-    if (manifest.schema_version !== "1.0")
-        errors.push(`${manifestPath}: .schema_version must be "1.0"`);
-    if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
-        errors.push(`${manifestPath}: .id must be a stable kebab-case string`);
-    }
-    if (typeof manifest.name !== "string" || !manifest.name.trim())
-        errors.push(`${manifestPath}: .name must be a non-empty string`);
-    // Degradation invariant: every Flow Agents Kit must remain a valid core Flow Kit container
-    // when agent-extension fields are stripped. Strip extensions and re-validate core contract.
-    const coreManifest = {};
-    for (const key of Object.keys(manifest)) {
-        if (CORE_CONTAINER_FIELDS.has(key))
-            coreManifest[key] = manifest[key];
-    }
-    const coreErrors = validateCoreContainer(coreManifest, manifestPath);
-    for (const err of coreErrors) {
-        // Deduplicate: only add if not already covered by top-level checks above.
-        if (!errors.some((existing) => existing === err))
-            errors.push(err);
-    }
-    for (const section of ASSET_CLASSES) {
+    // Delegate core container validation (schema_version, id, name, flows including file
+    // existence) to @kontourai/flow — the container contract lives once, in Flow.
+    // This enforces the degradation invariant: a Flow Agents Kit must remain a valid
+    // core Flow Kit container when extension fields are stripped.
+    const coreErrors = await delegateCoreContainerValidation(kitDir, manifest);
+    for (const err of coreErrors)
+        errors.push(err);
+    // Flow Agents extension validation: skills, docs, adapters, evals, assets.
+    // Flows are validated above by @kontourai/flow; only extension classes are checked here.
+    for (const section of EXTENSION_ASSET_CLASSES) {
         const entries = manifest[section];
         if (entries === undefined)
             continue;
@@ -155,15 +183,14 @@ export function validateKitRepository(kitDir) {
                 return;
             }
             if (!fs.existsSync(resolved)) {
-                const noun = section === "flows" ? "Flow Definition" : "asset";
-                errors.push(`${manifestPath}: ${section}[${index}].path points at missing ${noun}: ${rel}`);
+                errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
             }
         });
     }
     return errors;
 }
-export function assertKitRepository(kitDir) {
-    const errors = validateKitRepository(kitDir);
+export async function assertKitRepository(kitDir) {
+    const errors = await validateKitRepository(kitDir);
     if (errors.length) {
         const error = new Error("Flow Kit repository validation failed");
         error.diagnostics = errors;

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

@@ -9,6 +9,61 @@ const packs = loadJson(path.join(root, "packaging/packs.json"));
 const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", ".toml", ".txt", ".yaml", ".yml", ".ts"]);
 const dropDiagnostics = [];
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
+/**
+ * Collect all skill source paths across skills/ and kit-owned skills.
+ * Returns an array of {name, src} pairs where name is the install name
+ * (same as the directory name) and src is the absolute SKILL.md path.
+ * Kit-owned skills are discovered by reading kit.json `skills` arrays;
+ * each entry's `path` is resolved relative to the kit directory.
+ */
+function collectAllSkills() {
+    const results = [];
+    const seen = new Set();
+    // 1. Top-level skills/ directory (tools pending reclassification).
+    const skillsDir = path.join(root, "skills");
+    if (fs.existsSync(skillsDir)) {
+        for (const skill of fs.readdirSync(skillsDir).sort()) {
+            const skillPath = path.join(skillsDir, skill, "SKILL.md");
+            if (fs.existsSync(skillPath) && !seen.has(skill)) {
+                seen.add(skill);
+                results.push({ name: skill, src: skillPath });
+            }
+        }
+    }
+    // 2. Kit-owned skills declared in kits/<kit>/kit.json `skills` arrays.
+    const kitsDir = path.join(root, "kits");
+    if (fs.existsSync(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir).sort()) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!fs.existsSync(kitJson))
+                continue;
+            let kitManifest;
+            try {
+                kitManifest = loadJson(kitJson);
+            }
+            catch {
+                continue;
+            }
+            const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] : [];
+            for (const entry of skills) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const skillEntry = entry;
+                const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+                if (!relPath)
+                    continue;
+                // Derive install name from the directory containing SKILL.md (one level up).
+                const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+                const skillName = path.basename(path.dirname(absPath));
+                if (fs.existsSync(absPath) && !seen.has(skillName)) {
+                    seen.add(skillName);
+                    results.push({ name: skillName, src: absPath });
+                }
+            }
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
 function resetDir(dir) {
     fs.rmSync(dir, { recursive: true, force: true });
     fs.mkdirSync(dir, { recursive: true });
@@ -327,10 +382,8 @@ function buildClaudeCode(agents) {
     writeText(path.join(bundle, manifest.claude_code.task_dir, ".gitkeep"), "");
     for (const spec of agents)
         writeText(path.join(bundle, ".claude/agents", `${spec.name}.md`), exportClaudeAgent(spec));
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".claude/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "claude-code", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".claude/skills", name, "SKILL.md"), sanitizeText(readText(src), "claude-code", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".claude/settings.json"), exportClaudeSettings());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Claude Code", agents, manifest.claude_code.task_dir));
@@ -352,10 +405,8 @@ function buildCodex(agents) {
     writeText(path.join(bundle, ".codex/hooks.json"), exportCodexHooks());
     for (const spec of targetAgents)
         writeText(path.join(bundle, ".codex/agents", `${spec.name}.toml`), exportCodexAgent(spec));
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".codex/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "codex", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
     }
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace"));
@@ -419,6 +470,7 @@ function exportOpencodePlugin() {
 
 import { spawnSync } from 'node:child_process';
 import { join, basename } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
 
 // opencode runs plugins inside its own compiled (Bun-based) binary, so
 // process.execPath points at opencode itself — spawning it with a script
@@ -429,6 +481,19 @@ const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPat
 export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
   const root = directory || process.cwd();
 
+  // Deterministic load marker. opencode invokes this factory at startup but
+  // does not reliably surface plugin console output to its log file, and its
+  // internal "loading plugin" message was dropped in opencode 1.17.x. Write a
+  // marker into the workspace telemetry dir so acceptance tests can confirm the
+  // plugin loaded without depending on opencode internals. Best-effort only.
+  try {
+    const telemetryDir = join(root, '.telemetry');
+    mkdirSync(telemetryDir, { recursive: true });
+    writeFileSync(join(telemetryDir, 'opencode-plugin.loaded'), 'flow-agents');
+  } catch (_err) {
+    // Marker is diagnostic only; never block plugin load on a write failure.
+  }
+
   // The hook scripts read the event payload from stdin; an empty stdin makes
   // the telemetry pipeline silently skip the emit (fail-open), so every spawn
   // must pass a payload (caught by live acceptance smoke 2026-06-11).
@@ -519,10 +584,8 @@ function buildOpencode(agents) {
     for (const spec of agents) {
         writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
     }
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".opencode/skills", name, "SKILL.md"), sanitizeText(readText(src), "opencode", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
     writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
@@ -632,10 +695,8 @@ function buildPi(agents) {
     writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
     // pi has no named-subagent registry; agents are left canonical/unexported.
     // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".pi/skills", name, "SKILL.md"), sanitizeText(readText(src), "pi", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
@@ -648,7 +709,7 @@ function buildCatalog(agents) {
     return {
         source_root: ".",
         agents: agents.slice().sort((a, b) => a.name.localeCompare(b.name)).map((spec) => spec.name),
-        skills: fs.readdirSync(path.join(root, "skills")).filter((name) => fs.existsSync(path.join(root, "skills", name, "SKILL.md"))).sort(),
+        skills: collectAllSkills().map(({ name }) => name),
         powers: fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "mcp.json"))).sort(),
         packs: packs.packs ?? [],
         kits: fs.existsSync(kitsCatalog) ? loadJson(kitsCatalog).kits ?? [] : [],

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

@@ -75,16 +75,58 @@ function repoShape(manifest) {
     rows.push([".flow-agents", "runtime", "Cross-session workflow artifacts and sidecars. Not committed by default."]);
     return rows;
 }
+/** Collect all skill {name, absPath} pairs from skills/ and kit-owned skills. */
+function allSkillPaths() {
+    const results = [];
+    const seen = new Set();
+    const skillsDir = path.join(root, "skills");
+    if (exists(skillsDir)) {
+        for (const name of fs.readdirSync(skillsDir).sort()) {
+            const absPath = path.join(skillsDir, name, "SKILL.md");
+            if (exists(absPath) && !seen.has(name)) {
+                seen.add(name);
+                results.push({ name, absPath });
+            }
+        }
+    }
+    const kitsDir = path.join(root, "kits");
+    if (exists(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir).sort()) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!exists(kitJson))
+                continue;
+            let kitManifest;
+            try {
+                kitManifest = loadJson(kitJson);
+            }
+            catch {
+                continue;
+            }
+            const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] : [];
+            for (const entry of skills) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const skillEntry = entry;
+                const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+                if (!relPath)
+                    continue;
+                const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+                const skillName = path.basename(path.dirname(absPath));
+                if (exists(absPath) && !seen.has(skillName)) {
+                    seen.add(skillName);
+                    results.push({ name: skillName, absPath });
+                }
+            }
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
 function listSkillRows() {
     const workflowRows = [];
     const supportRows = [];
-    const skillsDir = path.join(root, "skills");
-    for (const name of fs.readdirSync(skillsDir).sort()) {
-        const skillPath = path.join(skillsDir, name, "SKILL.md");
-        if (!exists(skillPath))
-            continue;
-        const meta = frontmatter(readText(skillPath));
-        const row = [meta.name ?? name, rel(skillPath), oneLine(meta.description ?? "")];
+    for (const { name, absPath } of allSkillPaths()) {
+        const meta = frontmatter(readText(absPath));
+        const row = [meta.name ?? name, rel(absPath), oneLine(meta.description ?? "")];
         if (workflowSkills.has(row[0]))
             workflowRows.push(row);
         else

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

@@ -37,7 +37,7 @@ const publicScriptWrappers = new Map([
             ] }],
     ["scripts/filter-installed-packs.js", { target: "../build/src/tools/filter-installed-packs.js", significantLines: ['import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/generate-context-map.js", { target: "../build/src/tools/generate-context-map.js", significantLines: ['import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
-    ["scripts/flow-kit.js", { target: "../build/src/cli/flow-kit.js", significantLines: ['import("../build/src/cli/flow-kit.js").then(({ main }) => process.exit(main()));'] }],
+    ["scripts/kit.js", { target: "../build/src/cli/kit.js", significantLines: ['import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));'] }],
     ["scripts/pull-work-provider.js", { target: "../build/src/cli/pull-work-provider.js", significantLines: ['import("../build/src/cli/pull-work-provider.js").then(({ main }) => process.exit(main()));'] }],
     ["scripts/effective-backlog-settings.js", { target: "../build/src/cli/effective-backlog-settings.js", significantLines: ['import("../build/src/cli/effective-backlog-settings.js").then(({ main }) => process.exit(main()));'] }],
     ["scripts/publish-change-helper.js", { target: "../build/src/cli/publish-change-helper.js", significantLines: ['import("../build/src/cli/publish-change-helper.js").then(({ main }) => process.exit(main()));'] }],
@@ -391,6 +391,32 @@ function validateAgentPaths(reporter, manifest) {
     }
 }
 function validateLegacyRefs(reporter) {
+    // Collect all kit-owned asset relative paths so legacy-ref scanning can skip matches
+    // that are subpaths of kit-owned assets. E.g. legacyRefRe matches "skills/plan-work/SKILL.md"
+    // within "kits/builder/skills/plan-work/SKILL.md"; the kit declares and validates these.
+    const kitOwnedSubPaths = new Set();
+    const kitsDir = path.join(root, "kits");
+    if (fs.existsSync(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir)) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!fs.existsSync(kitJson))
+                continue;
+            try {
+                const kitManifest = loadJson(kitJson);
+                for (const section of ["skills", "docs", "adapters", "evals", "assets"]) {
+                    const entries = Array.isArray(kitManifest[section]) ? kitManifest[section] : [];
+                    for (const entry of entries) {
+                        if (typeof entry !== "object" || entry === null)
+                            continue;
+                        const relPath = entry["path"];
+                        if (typeof relPath === "string" && relPath)
+                            kitOwnedSubPaths.add(relPath);
+                    }
+                }
+            }
+            catch { /* skip invalid kit.json */ }
+        }
+    }
     for (const file of walkFiles(path.join(root, "evals")).sort()) {
         if (!textRefExtensions.has(path.extname(file)))
             continue;
@@ -404,6 +430,11 @@ function validateLegacyRefs(reporter) {
                 continue;
             if (ref.split(/[\\/]/).includes("node_modules"))
                 continue;
+            // Skip refs that are declared kit-owned asset paths or their parent directories
+            // (e.g. "skills/plan-work/SKILL.md" or "skills/plan-work" matched inside
+            // "kits/builder/skills/plan-work/SKILL.md" in eval files).
+            if (kitOwnedSubPaths.has(ref) || [...kitOwnedSubPaths].some((p) => p.startsWith(ref + "/")))
+                continue;
             const candidates = [path.join(root, ref), ...(ref.startsWith("evals/") ? [] : [path.join(root, "evals", ref)])];
             if (!candidates.some(fs.existsSync))
                 reporter.fail(`${rel(file)}: references missing source path: ${ref}`);