@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/compose/ops-report-schema.js

@@ -16,19 +16,33 @@ export const opsReportSectionSchema = z
         });
     }
 });
+const finiteNumber = z.number().finite();
+const cellValue = z.union([z.string(), finiteNumber]);
 export const opsReportMetricSchema = z
     .object({
     label: z.string().min(1),
-    value: z.union([z.string(), z.number()]),
+    value: cellValue,
 })
     .strict();
 export const opsReportTableSchema = z
     .object({
     title: z.string().optional(),
     headers: z.array(z.string()).min(1),
-    rows: z.array(z.array(z.union([z.string(), z.number()]))),
+    rows: z.array(z.array(cellValue)),
 })
-    .strict();
+    .strict()
+    .superRefine((table, ctx) => {
+    const expected = table.headers.length;
+    for (const [rowIndex, row] of table.rows.entries()) {
+        if (row.length !== expected) {
+            ctx.addIssue({
+                code: "custom",
+                message: `row has ${row.length} cell(s); expected ${expected} to match headers`,
+                path: ["rows", rowIndex],
+            });
+        }
+    }
+});
 /**
  * Minimal ops-report IR. Not a general page AST.
  * Nesting under sections is rejected by the section schema (flat only).

package/dist/esm/compose/registry-resolve.d.ts

@@ -1,4 +1,10 @@
 import { z } from "zod";
+/**
+ * Local reader capability floor for project registries (agent-kit consumer).
+ * Bump in the same PR as catalog/compose/admin-blocks-registry.json major/minor
+ * advances. Does not import @webpresso/schema (SEA / nondeterminism lock).
+ */
+export declare const READER_REGISTRY_VERSION: "1.0.0";
 export declare const blockRegistrySchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     version: z.ZodString;
@@ -30,6 +36,17 @@ export interface ResolvedBlockRegistry {
     readonly webpressoPresentWithoutRegistry: boolean;
 }
 export declare function defaultSnapshotPath(): string;
+/**
+ * Whether a loaded project registry is readable by this agent-kit consumer.
+ * - registry.version major must match the reader major
+ * - if registry.minVersion is set, reader must be >= that floor (semver order)
+ */
+export declare function isProjectRegistryCompatibleWithReader(registry: BlockRegistry, readerVersion?: string): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
 /**
  * Two-tier registry resolution (v0):
  * 1. Nearest project `.webpresso/` (within git/webpressorc boundary) — if it has

package/dist/esm/compose/registry-resolve.js

@@ -5,6 +5,12 @@ import { resolvePackageAssetPreferred } from "#utils/package-assets.js";
 import { z } from "zod";
 const REGISTRY_RELATIVE = join("generated", "frontend", "blocks", "registry.json");
 const MAX_WALK = 48;
+/**
+ * Local reader capability floor for project registries (agent-kit consumer).
+ * Bump in the same PR as catalog/compose/admin-blocks-registry.json major/minor
+ * advances. Does not import @webpresso/schema (SEA / nondeterminism lock).
+ */
+export const READER_REGISTRY_VERSION = "1.0.0";
 /** Stop climbing past these markers (mirrors project-root clamps elsewhere). */
 function isProjectBoundary(dir) {
     return existsSync(join(dir, ".git")) || existsSync(join(dir, ".webpressorc.json"));
@@ -82,6 +88,53 @@ function loadRegistryFile(path) {
         throw new Error(`Failed to load block registry at ${path}: ${detail}`, { cause: error });
     }
 }
+function parseSemver(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/**
+ * Whether a loaded project registry is readable by this agent-kit consumer.
+ * - registry.version major must match the reader major
+ * - if registry.minVersion is set, reader must be >= that floor (semver order)
+ */
+export function isProjectRegistryCompatibleWithReader(registry, readerVersion = READER_REGISTRY_VERSION) {
+    const reader = parseSemver(readerVersion);
+    if (!reader) {
+        return { ok: false, reason: `reader version "${readerVersion}" is not semver` };
+    }
+    const produced = parseSemver(registry.version);
+    if (!produced) {
+        return { ok: false, reason: `registry version "${registry.version}" is not semver` };
+    }
+    if (produced.major !== reader.major) {
+        return {
+            ok: false,
+            reason: `registry major ${produced.major} incompatible with reader major ${reader.major} (${readerVersion})`,
+        };
+    }
+    if (registry.minVersion !== undefined) {
+        const min = parseSemver(registry.minVersion);
+        if (!min) {
+            return { ok: false, reason: `registry minVersion "${registry.minVersion}" is not semver` };
+        }
+        const belowMin = reader.major < min.major ||
+            (reader.major === min.major && reader.minor < min.minor) ||
+            (reader.major === min.major && reader.minor === min.minor && reader.patch < min.patch);
+        if (belowMin) {
+            return {
+                ok: false,
+                reason: `reader ${readerVersion} is below registry minVersion ${registry.minVersion}`,
+            };
+        }
+    }
+    return { ok: true };
+}
 /**
  * Two-tier registry resolution (v0):
  * 1. Nearest project `.webpresso/` (within git/webpressorc boundary) — if it has
@@ -103,20 +156,34 @@ export function resolveBlockRegistry(options = {}) {
     if (webpressoRoot) {
         const projectPath = join(webpressoRoot, REGISTRY_RELATIVE);
         if (existsSync(projectPath)) {
-            const registry = loadRegistryFile(projectPath);
-            return {
-                registry,
-                source: "project",
-                registryVersion: registry.version,
-                path: projectPath,
-                warnings,
-                webpressoPresentWithoutRegistry: false,
-            };
+            try {
+                const registry = loadRegistryFile(projectPath);
+                const compat = isProjectRegistryCompatibleWithReader(registry);
+                if (!compat.ok) {
+                    warnings.push(`Project registry at ${projectPath} incompatible with reader ${READER_REGISTRY_VERSION} (${compat.reason}); using catalog snapshot.`);
+                }
+                else {
+                    return {
+                        registry,
+                        source: "project",
+                        registryVersion: registry.version,
+                        path: projectPath,
+                        warnings,
+                        webpressoPresentWithoutRegistry: false,
+                    };
+                }
+            }
+            catch (error) {
+                // Producer codegen can advance ahead of this consumer's schema; prefer
+                // snapshot over hard-failing MCP tools on version skew.
+                const detail = error instanceof Error ? error.message : String(error);
+                warnings.push(`Project registry at ${projectPath} failed validation (${detail}); using catalog snapshot. Regenerate or align registry schema.`);
+            }
         }
     }
     const snapshotPath = options.snapshotPath ?? defaultSnapshotPath();
     const registry = loadRegistryFile(snapshotPath);
-    if (webpressoRoot) {
+    if (webpressoRoot && warnings.length === 0) {
         warnings.push(`Project has .webpresso/ at ${webpressoRoot} but no ${join(".webpresso", REGISTRY_RELATIVE)}; using catalog snapshot ${registry.version}. Run schema frontend codegen / converge to materialize a project registry.`);
     }
     return {
@@ -125,7 +192,7 @@ export function resolveBlockRegistry(options = {}) {
         registryVersion: registry.version,
         path: snapshotPath,
         warnings,
-        webpressoPresentWithoutRegistry: webpressoRoot !== null,
+        webpressoPresentWithoutRegistry: webpressoRoot !== null && !existsSync(join(webpressoRoot, REGISTRY_RELATIVE)),
     };
 }
 export function blockNamesForView(registry, view) {

package/dist/esm/config/oxlint/graphql-conventions.js

@@ -7,6 +7,7 @@
 // causes runtime errors: "field 'user' not found in type: 'query_root'"
 //
 // This rule scans template literals and string literals for known singular patterns and reports them.
+import { isWebAppSurface, normalizeFilename } from "./path-roles.js";
 // Mapping of singular table patterns to their correct plural/actual GraphQL field names.
 // Format: [singular, correct, description]
 const SINGULAR_TABLE_RULES = [
@@ -76,9 +77,6 @@ const INLINE_GRAPHQL_EXEMPT_PATH_SEGMENTS = [
     "/packages/sdk/schema-engine/src/emitters/",
     "/packages/feature/app-core/src/daemon/",
 ];
-function normalizeFilename(filename) {
-    return typeof filename === "string" ? filename.replaceAll("\\", "/") : "";
-}
 function getFilename(context) {
     if (typeof context.getFilename === "function") {
         return normalizeFilename(context.getFilename());
@@ -92,9 +90,8 @@ function isClientQuerySurface(filename) {
     if (INLINE_GRAPHQL_EXEMPT_PATH_SEGMENTS.some((segment) => normalized.includes(segment))) {
         return false;
     }
-    const isWebAppSurface = normalized.includes("/apps/web/") && normalized.includes("/app/");
     const isFeatureSurface = normalized.includes("/packages/feature/") && normalized.includes("/src/");
-    return isWebAppSurface || isFeatureSurface;
+    return isWebAppSurface(normalized) || isFeatureSurface;
 }
 function getNodeStart(node) {
     if (Array.isArray(node?.range) && typeof node.range[0] === "number") {

package/dist/esm/config/oxlint/import-hygiene.js

@@ -4,6 +4,8 @@
 // - no-src-path-imports
 // - no-relative-mock-paths
 // - no-forbidden-package-imports
+import { isAgentKitSeaTreeFile, isPlatformAppFile, isSdkPackageFile, normalizeFilename, } from "./path-roles.js";
+export { isAgentKitSeaTreeFile, isPlatformAppFile, isSdkPackageFile, normalizeFilename, } from "./path-roles.js";
 const CROSS_PACKAGE_SEGMENT = /(?:^|\/)(packages|apps|tooling|infra|webpresso)\//;
 function isRelativeParentPath(source) {
     return typeof source === "string" && source.includes("../");
@@ -32,9 +34,6 @@ function reportCrossPackageImport(context, node) {
         message: "Do not reach into another package/app with a relative filesystem import. Add a proper package export and import it via the package name.",
     });
 }
-function normalizeFilename(filename) {
-    return typeof filename === "string" ? filename.replaceAll("\\", "/") : "";
-}
 function getFilename(context) {
     if (typeof context.getFilename === "function") {
         return normalizeFilename(context.getFilename());
@@ -46,12 +45,16 @@ function checkStaticModuleSource(node, callback) {
         return;
     callback(node.source.value, node.source);
 }
-function isPlatformAppFile(filename) {
-    return filename.includes("/apps/workers/") || filename.includes("/apps/web/");
-}
-function isSdkPackageFile(filename) {
-    return filename.includes("/packages/sdk/");
+/** Package imports forbidden in agent-kit SEA surfaces (schema + ui paint kits). */
+export function isSeaForbiddenPackageImport(source) {
+    if (typeof source !== "string")
+        return false;
+    return (source === "@webpresso/schema" ||
+        source.startsWith("@webpresso/schema/") ||
+        source === "@webpresso/ui" ||
+        source.startsWith("@webpresso/ui/"));
 }
+export const SEA_FORBIDDEN_IMPORT_MESSAGE = "Agent-kit SEA surfaces (compose / wp_ui_*) must not import `@webpresso/schema` or `@webpresso/ui`. Use the two-tier block registry snapshot/project file and local Zod/HTML paint instead (offline / nondeterminism lock).";
 function isSchemaEngineImport(source) {
     return typeof source === "string" && source.startsWith("@webpresso/schema/engine/");
 }
@@ -147,6 +150,16 @@ const noForbiddenPackageImports = {
         function checkImport(source, node) {
             if (typeof source !== "string")
                 return;
+            // Agent-kit SEA / offline compose — ban before monorepo platform allow rules.
+            // Consumers still get this rule via shipped oxlintrc; monorepo apps do not match
+            // isAgentKitSeaTreeFile so public schema imports remain allowed there.
+            if (isAgentKitSeaTreeFile(filename) && isSeaForbiddenPackageImport(source)) {
+                context.report({
+                    node,
+                    message: SEA_FORBIDDEN_IMPORT_MESSAGE,
+                });
+                return;
+            }
             if (isPlatformAppFile(filename) &&
                 isSchemaEngineImport(source) &&
                 source !== "@webpresso/schema/engine/api") {

package/dist/esm/config/oxlint/oxlint-config.fixture.d.ts

@@ -1,2 +1,2 @@
-import { config } from "./index.js";
+import { config } from "@webpresso/agent-config/oxlint";
 export default config;

package/dist/esm/config/oxlint/oxlint-config.fixture.js

@@ -1,4 +1,3 @@
-import { config } from "./index.js";
-// Consumer repos can use the same shape from the public subpath:
-// import { config } from 'webpresso/oxlint'
+import { config } from "@webpresso/agent-config/oxlint";
+// Shape parity for folded config consumers (agent-config is the SSOT).
 export default config;

package/dist/esm/config/oxlint/oxlintrc.d.ts

@@ -1,16 +1,13 @@
 /**
  * Compiled plugin module basenames shipped next to the generated oxlintrc.json.
- * Kept in lockstep with the plugin set in `index.ts` (guarded by the parity
- * test in `oxlintrc.test.ts`, which asserts one entry per registered plugin).
+ * SSOT: `@webpresso/agent-config/oxlint` `OXLINT_POLICY_PLUGIN_BASENAMES`.
  */
 export declare const OXLINT_PLUGIN_BASENAMES: readonly ["code-safety", "foundation-purity", "graphql-conventions", "import-hygiene", "monorepo-paths", "query-patterns", "testing-quality", "tier-boundaries"];
 /** jsPlugins specifiers, sibling-relative to the shipped oxlintrc.json. */
 export declare const OXLINT_JS_PLUGIN_FILES: readonly string[];
 /**
  * Standard ignore patterns for every webpresso consumer: build output, vendored
- * deps, generated reports, and the regenerated agent-surface directories. These
- * are project-relative. Truly repo-specific extras belong in a consumer-local
- * `.oxlintignore`, never here.
+ * deps, generated reports, and the regenerated agent-surface directories.
  */
 export declare const STANDARD_IGNORE_PATTERNS: readonly string[];
 export interface ResolvedOxlintRc {
@@ -18,9 +15,10 @@ export interface ResolvedOxlintRc {
     readonly rules: Readonly<Record<string, "error">>;
     readonly ignorePatterns: readonly string[];
 }
+/** Rule map from agent-config SSOT (error severity for inject). */
+export declare const rules: Readonly<Record<string, "error">>;
 /**
  * Build the resolved oxlint config object that ships as `oxlintrc.json`. Pure:
- * the build-time generator serializes this return value verbatim, and the
- * parity test asserts it against the live `rules`/`plugins` exports.
+ * the build-time generator serializes this return value verbatim.
  */
 export declare function buildOxlintrc(): ResolvedOxlintRc;

package/dist/esm/config/oxlint/oxlintrc.js

@@ -1,44 +1,31 @@
 /**
  * Resolved, consumer-ready oxlint configuration (Tier-1 DRY model).
  *
- * agent-kit ships ONE resolved `.oxlintrc.json` — generated from this builder
- * at build time into `dist/esm/config/oxlint/oxlintrc.json` — and `wp lint`
- * points oxlint at it via `--config`. Consumers therefore carry no
- * `oxlint.config.ts` and no `oxlint` dependency; the linter version, plugins,
- * rules, and standard ignores are all gated to @webpresso/agent-kit.
+ * agent-kit ships ONE resolved `.oxlintrc.json` — generated at build time into
+ * `dist/esm/config/oxlint/oxlintrc.json` — and `wp lint` points oxlint at it via
+ * `--config` for consumers without a local oxlint config.
  *
- * Two oxlint resolution facts (verified against oxlint 1.67) make this work:
- * - `jsPlugins` are resolved relative to the CONFIG FILE's directory, so the
- *   specifiers below are sibling-relative (`./<plugin>.js`) to the shipped JSON
- *   — zero package-resolution machinery, no dependency on @webpresso/agent-kit
- *   being resolvable from the config's location.
- * - `ignorePatterns` are applied relative to the LINTED project (cwd), not the
- *   config-file directory, so `dist`/`node_modules`/etc. ignore the consumer's
- *   tree even though the config lives inside node_modules.
+ * Plugin *bodies* are authored in `@webpresso/agent-config/oxlint/*` (consumer
+ * SSOT). Build vendors compiled sibling `.js` next to oxlintrc.json so inject
+ * needs no runtime agent-config dependency. Monorepos with their own lint
+ * config load `@webpresso/agent-config/oxlint/*` package names directly.
+ *
+ * Two oxlint resolution facts (verified against oxlint 1.67) make inject work:
+ * - `jsPlugins` are resolved relative to the CONFIG FILE's directory
+ *   (`./<plugin>.js` siblings of the shipped JSON).
+ * - `ignorePatterns` apply relative to the LINTED project (cwd).
  */
-import { rules } from "./index.js";
+import { OXLINT_POLICY_PLUGIN_BASENAMES, rules as agentConfigRules, } from "@webpresso/agent-config/oxlint";
 /**
  * Compiled plugin module basenames shipped next to the generated oxlintrc.json.
- * Kept in lockstep with the plugin set in `index.ts` (guarded by the parity
- * test in `oxlintrc.test.ts`, which asserts one entry per registered plugin).
+ * SSOT: `@webpresso/agent-config/oxlint` `OXLINT_POLICY_PLUGIN_BASENAMES`.
  */
-export const OXLINT_PLUGIN_BASENAMES = [
-    "code-safety",
-    "foundation-purity",
-    "graphql-conventions",
-    "import-hygiene",
-    "monorepo-paths",
-    "query-patterns",
-    "testing-quality",
-    "tier-boundaries",
-];
+export const OXLINT_PLUGIN_BASENAMES = OXLINT_POLICY_PLUGIN_BASENAMES;
 /** jsPlugins specifiers, sibling-relative to the shipped oxlintrc.json. */
 export const OXLINT_JS_PLUGIN_FILES = OXLINT_PLUGIN_BASENAMES.map((name) => `./${name}.js`);
 /**
  * Standard ignore patterns for every webpresso consumer: build output, vendored
- * deps, generated reports, and the regenerated agent-surface directories. These
- * are project-relative. Truly repo-specific extras belong in a consumer-local
- * `.oxlintignore`, never here.
+ * deps, generated reports, and the regenerated agent-surface directories.
  */
 export const STANDARD_IGNORE_PATTERNS = [
     "dist",
@@ -53,10 +40,11 @@ export const STANDARD_IGNORE_PATTERNS = [
     ".opencode",
     ".runtime",
 ];
+/** Rule map from agent-config SSOT (error severity for inject). */
+export const rules = agentConfigRules;
 /**
  * Build the resolved oxlint config object that ships as `oxlintrc.json`. Pure:
- * the build-time generator serializes this return value verbatim, and the
- * parity test asserts it against the live `rules`/`plugins` exports.
+ * the build-time generator serializes this return value verbatim.
  */
 export function buildOxlintrc() {
     return {

package/dist/esm/config/oxlint/path-roles.js

@@ -0,0 +1,53 @@
+// @ts-nocheck
+/**
+ * Shared path classifiers for webpresso oxlint policy plugins.
+ * Pure functions only — no AST. Consumers resolve plugins from
+ * `@webpresso/agent-config/oxlint/*`; these markers must match real trees.
+ */
+/** Normalize Windows paths for substring role checks. */
+export function normalizeFilename(filename) {
+    return typeof filename === "string" ? filename.replaceAll("\\", "/") : "";
+}
+/**
+ * Offline / SEA-shaped agent-kit surfaces (compose + UI MCP tools).
+ * Monorepo apps never use these path segments.
+ */
+export function isAgentKitSeaTreeFile(filename) {
+    const n = normalizeFilename(filename);
+    if (n.includes("/node_modules/"))
+        return false;
+    return n.includes("/src/compose/") || n.includes("/src/mcp/tools/wp-ui-");
+}
+/** Platform web apps: real monorepo layout + legacy `/apps/web/`. */
+export function isPlatformWebFile(filename) {
+    const n = normalizeFilename(filename);
+    if (n.includes("/node_modules/"))
+        return false;
+    return n.includes("/apps/platform/web/") || n.includes("/apps/web/");
+}
+/** Platform workers: real monorepo layout + legacy `/apps/workers/`. */
+export function isPlatformWorkerFile(filename) {
+    const n = normalizeFilename(filename);
+    if (n.includes("/node_modules/"))
+        return false;
+    return n.includes("/apps/platform/workers/") || n.includes("/apps/workers/");
+}
+/** Platform apps (web or worker) for import-hygiene schema-surface rules. */
+export function isPlatformAppFile(filename) {
+    return isPlatformWebFile(filename) || isPlatformWorkerFile(filename);
+}
+/**
+ * Client UI surfaces for GraphQL/query-pattern rules.
+ * Real monorepo: apps/platform/web/.../app/; legacy apps/web/.../app/.
+ */
+export function isWebAppSurface(filename) {
+    const n = normalizeFilename(filename);
+    if (n.includes("/node_modules/"))
+        return false;
+    if (!n.includes("/app/"))
+        return false;
+    return n.includes("/apps/platform/web/") || n.includes("/apps/web/");
+}
+export function isSdkPackageFile(filename) {
+    return normalizeFilename(filename).includes("/packages/sdk/");
+}

package/dist/esm/config/oxlint/query-patterns.js

@@ -1,8 +1,6 @@
 // @ts-nocheck
+import { isWebAppSurface, normalizeFilename } from "./path-roles.js";
 const QUERY_HOOK_NAMES = new Set(["useQuery", "useSuspenseQuery", "useInfiniteQuery"]);
-function normalizeFilename(filename) {
-    return typeof filename === "string" ? filename.replaceAll("\\", "/") : "";
-}
 function getFilename(context) {
     if (typeof context.getFilename === "function") {
         return normalizeFilename(context.getFilename());
@@ -15,9 +13,8 @@ function isClientQuerySurface(filename) {
         return false;
     if (normalized.includes("/.webpresso/generated/"))
         return false;
-    const isWebAppSurface = normalized.includes("/apps/web/") && normalized.includes("/app/");
     const isFeatureSurface = normalized.includes("/packages/feature/") && normalized.includes("/src/");
-    return isWebAppSurface || isFeatureSurface;
+    return isWebAppSurface(normalized) || isFeatureSurface;
 }
 function getCalleeName(callee) {
     if (!callee)

package/dist/esm/content/dispatch.js

@@ -12,6 +12,10 @@ import { loadContent } from "./loader.js";
 const CONSUMER_DIR_BY_KIND = {
     rule: "agent-rules",
     skill: "agent-skills",
+    // Not reachable today (no `wp agent` CRUD command dispatches here), kept
+    // only to satisfy Record<ContentKind, string> exhaustiveness now that
+    // "agent" is a ContentKind for the unified-sync projection pipeline.
+    agent: "agent-agents",
 };
 function todayIsoDate() {
     return new Date().toISOString().slice(0, 10);

package/dist/esm/content/loader.d.ts

@@ -14,7 +14,7 @@
  * gray-matter object in both `rawFrontmatter` and `parsedFrontmatter` so the
  * shape stays stable for downstream callers writing tests against it.
  */
-export type ContentKind = "rule" | "skill";
+export type ContentKind = "rule" | "skill" | "agent";
 export type ContentSource = "canonical" | "consumer";
 /**
  * Stub raw frontmatter type. Replaced with schema output in Task 2.x.

package/dist/esm/content/loader.js

@@ -21,10 +21,12 @@ const DEFAULT_KINDS = ["rule", "skill"];
 const CONSUMER_DIR_BY_KIND = {
     rule: "agent-rules",
     skill: "agent-skills",
+    agent: "agent-agents",
 };
 const CATALOG_DIR_BY_KIND = {
     rule: "rules",
     skill: "skills",
+    agent: "agents",
 };
 export function loadContent(options) {
     const { catalogDir, consumerRoot, kinds = DEFAULT_KINDS } = options;
@@ -83,9 +85,11 @@ function readKind(args) {
     const stat = statSync(root);
     if (!stat.isDirectory())
         return [];
-    return kind === "rule" ? readRules(root, source) : readSkills(root, source);
+    // agent kind shares the rule shape: flat `<slug>.md` files, README.md
+    // excluded. Only `skill` is directory-shaped (`<slug>/SKILL.md`).
+    return kind === "skill" ? readSkills(root, source) : readFlatMarkdown(kind, root, source);
 }
-function readRules(root, source) {
+function readFlatMarkdown(kind, root, source) {
     const out = [];
     for (const entry of readdirSync(root, { withFileTypes: true })) {
         if (!entry.isFile())
@@ -93,9 +97,9 @@ function readRules(root, source) {
         if (!entry.name.endsWith(".md"))
             continue;
         // Skip directory-documentation files. README.md exists in both the
-        // canonical catalog and the consumer-owned agent-rules/ scaffolder
-        // surface; treating it as a rule would produce a spurious slug
-        // collision and would also try to project it into per-IDE surfaces.
+        // canonical catalog and the consumer-owned agent-rules/ (or agent-agents/)
+        // scaffolder surface; treating it as content would produce a spurious
+        // slug collision and would also try to project it into per-IDE surfaces.
         if (entry.name === "README.md")
             continue;
         const filePath = realpathSync(join(root, entry.name));
@@ -103,7 +107,7 @@ function readRules(root, source) {
         const parsed = matter(readFileSync(filePath, "utf8"));
         const raw = { ...parsed.data };
         out.push({
-            kind: "rule",
+            kind,
             slug,
             source,
             filePath,

package/dist/esm/content/skill-policy.d.ts

@@ -1,6 +1,17 @@
 export declare const DEFAULT_PACKAGED_SKILL_SLUGS: readonly ["verify", "fix", "investigate", "ai-deslop", "plan-refine", "ralplan", "best-practice-research", "testing-philosophy", "tph", "claude", "codex", "grok", "opencode-go", "plan-eng-review", "plan-ceo-review", "plan-design-review", "plan-devex-review", "browse", "devex-review", "design-review", "hooks-doctor", "tech-debt", "lore-protocol", "deep-interview", "deep-research", "autoresearch", "ultragoal", "autopilot", "team"];
 export type DefaultPackagedSkillSlug = (typeof DEFAULT_PACKAGED_SKILL_SLUGS)[number];
 export declare const DEFAULT_PACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export declare const UNPACKAGED_SKILL_SLUGS: Readonly<Record<string, string>>;
+export declare const UNPACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+export declare function isUnpackagedSkillSlug(slug: string): boolean;
 export declare const MERGED_DELETED_SKILL_SLUGS: readonly ["autoplan", "health", "systematic-debugging", "test-driven-development"];
 export declare const MERGED_DELETED_SKILL_SLUG_SET: ReadonlySet<string>;
 /**

package/dist/esm/content/skill-policy.js

@@ -30,6 +30,39 @@ export const DEFAULT_PACKAGED_SKILL_SLUGS = [
     "team",
 ];
 export const DEFAULT_PACKAGED_SKILL_SLUG_SET = new Set(DEFAULT_PACKAGED_SKILL_SLUGS);
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export const UNPACKAGED_SKILL_SLUGS = {
+    qa: "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    "qa-only": "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    review: "listed as a default workflow skill in workflow-skills-routing.md but not yet added to DEFAULT_PACKAGED_SKILL_SLUGS",
+    pll: "ultragoal's parallel-execute companion (ready-queue/worktrees driver); not independently default-packaged",
+    "frontend-design": "opt-in design-guidance skill, not part of the default packaged workflow set",
+    "monorepo-navigation": "tier-3 opt-in preset (wp setup --with monorepo-navigation), not default-packaged",
+    "tanstack-query": "tier-3 opt-in preset (wp setup --with tanstack-query), not default-packaged",
+    "react-doctor": "opt-in framework best-practice skill, not default-packaged",
+    "better-auth-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "logging-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "vercel-react-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "web-design-guidelines": "opt-in best-practice reference skill, not default-packaged",
+    deepseek: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    glm: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    hy3: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    kimi: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    mimo: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    minimax: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    qwen: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+};
+export const UNPACKAGED_SKILL_SLUG_SET = new Set(Object.keys(UNPACKAGED_SKILL_SLUGS));
+export function isUnpackagedSkillSlug(slug) {
+    return UNPACKAGED_SKILL_SLUG_SET.has(slug);
+}
 export const MERGED_DELETED_SKILL_SLUGS = [
     "autoplan",
     "health",