@thinkingsage/kanon 0.8.0

package/src/validate.ts

@@ -0,0 +1,1093 @@
+import { exists, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import chalk from "chalk";
+import { CAPABILITY_MATRIX, validateMatrixSync } from "./adapters/capabilities";
+import { adapterRegistry } from "./adapters/index";
+import { resolveKiroInclusion } from "./adapters/kiro-inclusion";
+import {
+	ASSET_CONVENTION_RULES,
+	ASSET_CONVENTIONS,
+	documentsAgentLoop,
+} from "./asset-conventions";
+import { generateCatalog } from "./catalog";
+import { loadCollections, validateArtifactCollectionRefs } from "./collections";
+import { HARNESS_FORMAT_REGISTRY, resolveFormat } from "./format-registry";
+import {
+	BUILTIN_PREDICATES,
+	ExpressionSyntaxError,
+	type ParsedExpression,
+	parseExpression,
+	validateReferences,
+} from "./hooks/expression";
+import { aggregateOutcomes, runRegistryCheck } from "./outcomes/registry";
+import {
+	isParseError,
+	parseHooksYaml,
+	parseKnowledgeMd,
+	parseMcpServersYaml,
+} from "./parser";
+import {
+	type CanonicalHook,
+	isStdioServer,
+	type Outcome,
+	SUPPORTED_HARNESSES,
+	type ValidationError,
+	type ValidationResult,
+	type ValidationWarning,
+} from "./schemas";
+import { loadWorkspaceConfig, validateWorkspaceConfig } from "./workspace";
+
+export type { ValidationError, ValidationResult, ValidationWarning };
+
+// ── Security validation ───────────────────────────────────────────────────────
+
+/** Prompt injection and override patterns — errors, not warnings. */
+const PROMPT_INJECTION_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+	{
+		pattern: /ignore\s+(previous|prior|all)\s+instructions/i,
+		message:
+			'Contains prompt injection pattern: "ignore previous instructions"',
+	},
+	{
+		pattern:
+			/disregard\s+(your|all)\s+(guidelines|rules|training|instructions)/i,
+		message: 'Contains prompt injection pattern: "disregard your guidelines"',
+	},
+	{
+		pattern: /you\s+are\s+now\s+(?!a\s+(?:skill|power|workflow|agent|prompt))/i,
+		message: 'Contains identity override pattern: "you are now"',
+	},
+	{
+		pattern: /act\s+as\s+(?:if\s+you\s+have\s+no|without)\s+restrictions/i,
+		message:
+			'Contains restriction bypass pattern: "act as if you have no restrictions"',
+	},
+	{
+		pattern: /\[SYSTEM\]/,
+		message: "Contains fake system prompt marker: [SYSTEM]",
+	},
+	{
+		pattern: /\bDAN\b|\bDo Anything Now\b/i,
+		message: "Contains known jailbreak marker: DAN / Do Anything Now",
+	},
+];
+
+/** Hook command patterns that suggest exfiltration or remote code execution. */
+const DANGEROUS_HOOK_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+	{
+		pattern: /curl\s+.*(?:\$\{?[A-Z_]{3,}\}?|\$\()/,
+		message:
+			"Hook command uses curl with an environment variable or command substitution — potential exfiltration",
+	},
+	{
+		pattern: /wget\s+.*https?:\/\//,
+		message: "Hook command makes outbound request via wget",
+	},
+	{
+		pattern: /\bnc\b.*\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/,
+		message: "Hook command uses netcat with a remote IP address",
+	},
+	{
+		pattern: /python.*-c.*(?:exec|eval|__import__)/,
+		message: "Hook command runs inline Python with exec/eval",
+	},
+	{
+		pattern: /node\s+-e\s+/,
+		message: "Hook command runs inline Node.js code",
+	},
+	{
+		pattern: /bash\s+-c\s+.*base64/,
+		message: "Hook command runs base64-encoded payload via bash",
+	},
+];
+
+/** MCP server command patterns that indicate risky execution. */
+const DANGEROUS_MCP_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+	{
+		pattern: /^(?:bash|sh|zsh|fish)$/,
+		message:
+			"MCP server uses a shell interpreter as its command — high-risk execution surface",
+	},
+	{
+		pattern: /^python\d*$|^node$|^ruby$|^perl$/,
+		message:
+			"MCP server uses a language runtime as its command without a specific script path",
+	},
+];
+
+/** Hidden/obfuscated content patterns — warnings. */
+const OBFUSCATION_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+	{
+		pattern: /[\u200B-\u200D\uFEFF\u2060]/,
+		message: "Body contains zero-width or invisible Unicode characters",
+	},
+	{
+		pattern: /[A-Za-z0-9+/]{80,}={0,2}/,
+		message:
+			"Body contains a long base64-like string that may encode hidden instructions",
+	},
+];
+
+/**
+ * SPDX license identifiers (or families) whose terms require attribution be
+ * preserved. Kept small and explicit (ADR-0064); `CC-BY*` matches by prefix.
+ * Used only to raise an advisory under-credited warning, never to fail a build.
+ */
+const ATTRIBUTION_REQUIRED_LICENSES = new Set([
+	"MPL-2.0",
+	"Apache-2.0",
+	"BSD-3-Clause",
+	"BSD-2-Clause",
+]);
+
+function isAttributionRequiredLicense(license: string): boolean {
+	const id = license.trim();
+	if (id.length === 0) return false;
+	if (/^CC-BY/i.test(id)) return true;
+	return ATTRIBUTION_REQUIRED_LICENSES.has(id);
+}
+
+/**
+ * Run security-focused checks on an artifact.
+ * Returns additional errors and warnings to merge into the validation result.
+ */
+export async function validateArtifactSecurity(
+	artifactPath: string,
+): Promise<{ errors: ValidationError[]; warnings: ValidationWarning[] }> {
+	const errors: ValidationError[] = [];
+	const warnings: ValidationWarning[] = [];
+	const knowledgeMdPath = join(artifactPath, "knowledge.md");
+	const hooksPath = join(artifactPath, "hooks.yaml");
+	const mcpPath = join(artifactPath, "mcp-servers.yaml");
+
+	// ── knowledge.md body ───────────────────────────────────────────────────────
+	const mdResult = await parseKnowledgeMd(knowledgeMdPath);
+	if (!isParseError(mdResult)) {
+		const body = mdResult.data.body;
+
+		for (const { pattern, message } of PROMPT_INJECTION_PATTERNS) {
+			if (pattern.test(body)) {
+				errors.push({ field: "body", message, filePath: knowledgeMdPath });
+			}
+		}
+
+		for (const { pattern, message } of OBFUSCATION_PATTERNS) {
+			if (pattern.test(body)) {
+				warnings.push({ field: "body", message, filePath: knowledgeMdPath });
+			}
+		}
+	}
+
+	// ── hooks.yaml ──────────────────────────────────────────────────────────────
+	if (await exists(hooksPath)) {
+		const hooksResult = await parseHooksYaml(hooksPath);
+		if (!isParseError(hooksResult)) {
+			for (const hook of hooksResult.data) {
+				if (hook.action.type === "run_command") {
+					const cmd = hook.action.command;
+					for (const { pattern, message } of DANGEROUS_HOOK_PATTERNS) {
+						if (pattern.test(cmd)) {
+							errors.push({
+								field: `hooks[${hook.name}].action.command`,
+								message,
+								filePath: hooksPath,
+							});
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// ── mcp-servers.yaml ────────────────────────────────────────────────────────
+	if (await exists(mcpPath)) {
+		const mcpResult = await parseMcpServersYaml(mcpPath);
+		if (!isParseError(mcpResult)) {
+			for (const server of mcpResult.data) {
+				if (isStdioServer(server)) {
+					for (const { pattern, message } of DANGEROUS_MCP_PATTERNS) {
+						if (pattern.test(server.command)) {
+							warnings.push({
+								field: `mcp-servers[${server.name}].command`,
+								message,
+								filePath: mcpPath,
+							});
+						}
+					}
+				}
+				// Flag servers with env vars that look like credentials
+				for (const [key] of Object.entries(server.env)) {
+					if (/(?:key|secret|token|password|credential)/i.test(key)) {
+						warnings.push({
+							field: `mcp-servers[${server.name}].env.${key}`,
+							message: `MCP server references a credential-like env var "${key}" — ensure this is not hardcoded`,
+							filePath: mcpPath,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	return { errors, warnings };
+}
+
+/**
+ * Detect cycles in a dependency graph using DFS.
+ * @param graph - Map from artifact name to its direct dependencies
+ * @returns Array of cycles, each cycle is an array of artifact names forming a loop
+ */
+export function detectDependencyCycles(
+	graph: Map<string, string[]>,
+): string[][] {
+	const cycles: string[][] = [];
+	const visited = new Set<string>();
+	const inStack = new Set<string>();
+
+	function dfs(node: string, path: string[]): void {
+		if (inStack.has(node)) {
+			// Found a cycle — extract the cycle portion
+			const cycleStart = path.indexOf(node);
+			cycles.push(path.slice(cycleStart));
+			return;
+		}
+		if (visited.has(node)) return;
+
+		visited.add(node);
+		inStack.add(node);
+		path.push(node);
+
+		for (const dep of graph.get(node) ?? []) {
+			dfs(dep, [...path]);
+		}
+
+		inStack.delete(node);
+	}
+
+	for (const node of graph.keys()) {
+		if (!visited.has(node)) {
+			dfs(node, []);
+		}
+	}
+
+	return cycles;
+}
+
+/**
+ * Hook gate/postcondition reference validation (Req 3.7).
+ *
+ * For a parsed `hooks.yaml`, collect the union of all declared `state` keys
+ * across every hook in the file, then for each hook's `gate` and
+ * `postcondition` expression parse it and run {@link validateReferences}
+ * against that declared-key set. Any undefined state key or unknown predicate
+ * (not in {@link BUILTIN_PREDICATES}) yields a {@link ValidationError}
+ * identifying the hook name and the offending field. Malformed expressions are
+ * reported as validation errors too, so a broken gate/postcondition rejects the
+ * hook file rather than throwing.
+ *
+ * Pure: takes the already-parsed hooks and returns errors; no I/O.
+ */
+export function validateHookReferences(
+	hooks: CanonicalHook[],
+	filePath: string,
+): ValidationError[] {
+	const errors: ValidationError[] = [];
+
+	// Union of all declared state keys across every hook in the file (Req 3.7).
+	const declaredStateKeys = new Set<string>();
+	for (const hook of hooks) {
+		if (hook.state) {
+			for (const key of Object.keys(hook.state)) {
+				declaredStateKeys.add(key);
+			}
+		}
+	}
+
+	const checkField = (
+		hook: CanonicalHook,
+		field: "gate" | "postcondition",
+		expr: string | undefined,
+	): void => {
+		if (!expr) return;
+
+		let parsed: ParsedExpression;
+		try {
+			parsed = parseExpression(expr);
+		} catch (err) {
+			errors.push({
+				field: `hooks[${hook.name}].${field}`,
+				message:
+					err instanceof ExpressionSyntaxError
+						? err.message
+						: `Failed to parse ${field} expression "${expr}"`,
+				filePath,
+			});
+			return;
+		}
+
+		const { undefinedStateKeys, undefinedPredicates } = validateReferences(
+			parsed,
+			declaredStateKeys,
+		);
+		for (const key of undefinedStateKeys) {
+			errors.push({
+				field: `hooks[${hook.name}].${field}`,
+				message: `${field} references undefined state key "state.${key}". Declare it in a hook's "state" field.`,
+				filePath,
+			});
+		}
+		for (const pred of undefinedPredicates) {
+			errors.push({
+				field: `hooks[${hook.name}].${field}`,
+				message: `${field} references unknown predicate "${pred}". Built-in predicates are: ${BUILTIN_PREDICATES.join(", ")}.`,
+				filePath,
+			});
+		}
+	};
+
+	for (const hook of hooks) {
+		checkField(hook, "gate", hook.gate);
+		checkField(hook, "postcondition", hook.postcondition);
+	}
+
+	return errors;
+}
+
+export async function validateArtifact(
+	artifactPath: string,
+): Promise<ValidationResult> {
+	const errors: ValidationError[] = [];
+	const artifactName = artifactPath.split("/").pop() || artifactPath;
+
+	// Check knowledge.md exists
+	const knowledgeMdPath = join(artifactPath, "knowledge.md");
+	if (!(await exists(knowledgeMdPath))) {
+		errors.push({
+			field: "knowledge.md",
+			message: "Missing required knowledge.md file",
+			filePath: knowledgeMdPath,
+		});
+		return { artifactName, valid: false, errors };
+	}
+
+	// Validate frontmatter
+	const warnings: ValidationWarning[] = [];
+	const mdResult = await parseKnowledgeMd(knowledgeMdPath);
+	if (isParseError(mdResult)) {
+		errors.push(...mdResult.errors);
+	} else {
+		// Validate harness names
+		const fm = mdResult.data.frontmatter;
+		for (const h of fm.harnesses) {
+			if (!(SUPPORTED_HARNESSES as readonly string[]).includes(h)) {
+				errors.push({
+					field: "harnesses",
+					message: `Unrecognized harness name: "${h}"`,
+					filePath: knowledgeMdPath,
+				});
+			}
+		}
+
+		// Validate harness-config keys reference harnesses in the list
+		const harnessConfig = mdResult.data.harnessConfig;
+		if (harnessConfig && typeof harnessConfig === "object") {
+			for (const key of Object.keys(harnessConfig)) {
+				const harnessKey = key as (typeof fm.harnesses)[number];
+				if (!fm.harnesses.includes(harnessKey)) {
+					// This is a warning, not an error — but we track it as a non-fatal error
+					errors.push({
+						field: "harness-config",
+						message: `harness-config key "${key}" references a harness not in the harnesses list`,
+						filePath: knowledgeMdPath,
+					});
+				}
+			}
+		}
+
+		// Lifecycle: deprecated assets must declare a successor (promoted to error in Phase 3)
+		if (fm.maturity === "deprecated" && !fm.successor) {
+			errors.push({
+				field: "successor",
+				message: `Asset has maturity "deprecated" but no "successor" field. Set "successor" to point to the replacement artifact.`,
+				filePath: knowledgeMdPath,
+			});
+		}
+
+		// Governance lane rules
+		if ((fm.trust === "official" || fm.trust === "partner") && !fm.license) {
+			warnings.push({
+				field: "license",
+				message: `Artifacts with trust "${fm.trust}" should declare a "license" field (e.g. MIT, Apache-2.0).`,
+				filePath: knowledgeMdPath,
+			});
+		}
+
+		if (fm["risk-level"] === "high" && !fm.trust) {
+			warnings.push({
+				field: "trust",
+				message: `Artifact has risk-level "high" but no "trust" lane set. Set "trust" to signal governance oversight.`,
+				filePath: knowledgeMdPath,
+			});
+		}
+
+		// ── Attribution warnings (ADR-0064; advisory, never fail the build) ──────
+		// 1. Un-credited import: has machine provenance but no human attribution.
+		const attribution = fm.attribution;
+		if (fm.provenance && !attribution?.upstream?.length) {
+			warnings.push({
+				field: "attribution",
+				message: `Artifact "${artifactName}" has a provenance record (imported) but no "attribution.upstream" credit. Run the import wizard or backfill to record upstream authorship.`,
+				filePath: knowledgeMdPath,
+			});
+		}
+		// 2. Under-credited attribution-required license: an upstream work under an
+		//    attribution-required license with neither per-entry authors nor a
+		//    block-level notice.
+		if (attribution?.upstream?.length) {
+			for (const [i, u] of attribution.upstream.entries()) {
+				if (
+					u.license &&
+					isAttributionRequiredLicense(u.license) &&
+					u.authors.length === 0 &&
+					!attribution.notice
+				) {
+					warnings.push({
+						field: `attribution.upstream[${i}]`,
+						message: `Upstream work "${u.work}" is under attribution-required license "${u.license}" but has no authors and no block-level notice. Add authors or a notice to satisfy the license.`,
+						filePath: knowledgeMdPath,
+					});
+				}
+			}
+		}
+
+		// Asset-type-aware validation rules
+		const convention = ASSET_CONVENTIONS[fm.type];
+		if (convention) {
+			for (const ruleKey of convention.validationRuleKeys) {
+				switch (ruleKey) {
+					case "reference-pack-must-be-manual":
+						if (fm.inclusion !== "manual") {
+							warnings.push({
+								field: "inclusion",
+								message: ASSET_CONVENTION_RULES[ruleKey],
+								filePath: knowledgeMdPath,
+							});
+						}
+						break;
+
+					case "workflow-should-have-workflows-dir": {
+						const workflowsDir = join(artifactPath, "workflows");
+						if (!(await exists(workflowsDir))) {
+							warnings.push({
+								field: "workflows",
+								message: ASSET_CONVENTION_RULES[ruleKey],
+								filePath: knowledgeMdPath,
+							});
+						} else {
+							const wfEntries = await readdir(workflowsDir);
+							const mdFiles = wfEntries.filter((f) => f.endsWith(".md"));
+							if (mdFiles.length === 0) {
+								warnings.push({
+									field: "workflows",
+									message: ASSET_CONVENTION_RULES[ruleKey],
+									filePath: knowledgeMdPath,
+								});
+							}
+						}
+						break;
+					}
+
+					case "type-power-deprecated":
+						warnings.push({
+							field: "type",
+							message: ASSET_CONVENTION_RULES[ruleKey],
+							filePath: knowledgeMdPath,
+						});
+						break;
+
+					case "prompt-body-too-short":
+					case "agent-should-document-loop":
+						// body is checked separately after parsing knowledge.md
+						break;
+				}
+			}
+		}
+	}
+
+	// Prompt body length check (needs body from parse result, outside the if block)
+	if (!isParseError(mdResult)) {
+		const fm = mdResult.data.frontmatter;
+		if (fm.type === "prompt" && mdResult.data.body.length < 50) {
+			warnings.push({
+				field: "body",
+				message: ASSET_CONVENTION_RULES["prompt-body-too-short"],
+				filePath: knowledgeMdPath,
+			});
+		}
+	}
+
+	// Agent loop documentation check (needs body from parse result, outside the if block)
+	if (!isParseError(mdResult)) {
+		const fm = mdResult.data.frontmatter;
+		if (fm.type === "agent" && !documentsAgentLoop(mdResult.data.body)) {
+			warnings.push({
+				field: "body",
+				message: ASSET_CONVENTION_RULES["agent-should-document-loop"],
+				filePath: knowledgeMdPath,
+			});
+		}
+	}
+
+	// ── Kiro Progressive Steering validation ────────────────────────────────────
+	if (!isParseError(mdResult)) {
+		const fm = mdResult.data.frontmatter;
+		if (fm.harnesses.includes("kiro")) {
+			// Construct a minimal artifact-like object for resolveKiroInclusion
+			const artifactForResolver = {
+				frontmatter: fm as Record<string, unknown> & { inclusion: string },
+			} as Parameters<typeof resolveKiroInclusion>[0];
+
+			const resolved = resolveKiroInclusion(artifactForResolver);
+
+			// Access kiro harness-config for cross-field checks
+			const harnessConfig = fm["harness-config"] as
+				| Record<string, Record<string, unknown>>
+				| undefined;
+			const kiroConfig = harnessConfig?.kiro;
+
+			// Req 1.4: fileMatch with absent/empty fileMatchPattern → error
+			if (kiroConfig && typeof kiroConfig === "object") {
+				const hcInclusion = kiroConfig.inclusion;
+				if (hcInclusion === "fileMatch") {
+					const fmp = kiroConfig.fileMatchPattern;
+					if (!fmp || (typeof fmp === "string" && fmp.length === 0)) {
+						errors.push({
+							field: "harness-config.kiro.fileMatchPattern",
+							message:
+								'fileMatchPattern is required when harness-config.kiro.inclusion is "fileMatch"',
+							filePath: knowledgeMdPath,
+						});
+					}
+				}
+
+				// Req 1.5: always/manual with non-empty fileMatchPattern → warning
+				if (
+					(hcInclusion === "always" || hcInclusion === "manual") &&
+					typeof kiroConfig.fileMatchPattern === "string" &&
+					kiroConfig.fileMatchPattern.length > 0
+				) {
+					warnings.push({
+						field: "harness-config.kiro.fileMatchPattern",
+						message:
+							'fileMatchPattern is ignored unless harness-config.kiro.inclusion is "fileMatch"',
+						filePath: knowledgeMdPath,
+					});
+				}
+			}
+
+			// Req 4.1: reference-pack + resolved always → warning
+			if (fm.type === "reference-pack" && resolved.mode === "always") {
+				warnings.push({
+					field: "harness-config.kiro.inclusion",
+					message: ASSET_CONVENTION_RULES["reference-pack-must-be-manual"],
+					filePath: knowledgeMdPath,
+				});
+			}
+
+			// Req 4.2 & 4.3: power-format + resolved always → warning(s)
+			const kiroFormat = resolveFormat(
+				"kiro",
+				kiroConfig as Record<string, unknown> | undefined,
+			);
+			if (kiroFormat.format === "power" && resolved.mode === "always") {
+				warnings.push({
+					field: "harness-config.kiro.inclusion",
+					message: ASSET_CONVENTION_RULES["kiro-power-should-be-progressive"],
+					filePath: knowledgeMdPath,
+				});
+
+				// Req 4.3: additionally warn if the artifact ships workflow files
+				const workflowsDir = join(artifactPath, "workflows");
+				if (await exists(workflowsDir)) {
+					const wfEntries = await readdir(workflowsDir);
+					const mdFiles = wfEntries.filter((f) => f.endsWith(".md"));
+					if (mdFiles.length > 0) {
+						warnings.push({
+							field: "harness-config.kiro.inclusion",
+							message:
+								ASSET_CONVENTION_RULES[
+									"kiro-power-workflow-should-be-progressive"
+								],
+							filePath: knowledgeMdPath,
+						});
+					}
+				}
+			}
+
+			// Req 8.2: default inclusion → informational warning (suppressed by explicit "always" per Req 8.3)
+			if (resolved.source === "default") {
+				warnings.push({
+					field: "harness-config.kiro.inclusion",
+					message:
+						ASSET_CONVENTION_RULES["kiro-default-inclusion-informational"],
+					filePath: knowledgeMdPath,
+				});
+			}
+		}
+	}
+
+	// Validate hooks.yaml if present
+	const hooksPath = join(artifactPath, "hooks.yaml");
+	if (await exists(hooksPath)) {
+		const hooksResult = await parseHooksYaml(hooksPath);
+		if (isParseError(hooksResult)) {
+			errors.push(...hooksResult.errors);
+		} else {
+			// Reference validation for gate/postcondition expressions (Req 3.7):
+			// every state key and predicate must be declared/built-in.
+			errors.push(...validateHookReferences(hooksResult.data, hooksPath));
+		}
+	}
+
+	// Validate mcp-servers.yaml if present
+	const mcpPath = join(artifactPath, "mcp-servers.yaml");
+	if (await exists(mcpPath)) {
+		const mcpResult = await parseMcpServersYaml(mcpPath);
+		if (isParseError(mcpResult)) {
+			errors.push(...mcpResult.errors);
+		}
+	}
+
+	const result: ValidationResult = {
+		artifactName,
+		valid: errors.length === 0,
+		errors,
+	};
+	if (warnings.length > 0) {
+		result.warnings = warnings;
+	}
+	return result;
+}
+
+/**
+ * Collect all {artifactPath, artifactName} pairs from one or more source dirs.
+ * Mirrors the layout detection logic in catalog.ts and build.ts.
+ */
+async function collectArtifactPaths(
+	sourceDirs: string[],
+): Promise<Array<{ path: string; name: string }>> {
+	const artifacts: Array<{ path: string; name: string }> = [];
+
+	for (const sourceDir of sourceDirs) {
+		if (!(await exists(sourceDir))) continue;
+
+		const dirEntries = await readdir(sourceDir, { withFileTypes: true });
+		const subdirs = dirEntries
+			.filter((e) => e.isDirectory())
+			.sort((a, b) => a.name.localeCompare(b.name));
+
+		for (const subdir of subdirs) {
+			const subdirPath = join(sourceDir, subdir.name);
+
+			if (await exists(join(subdirPath, "knowledge.md"))) {
+				artifacts.push({ path: subdirPath, name: subdir.name });
+			} else {
+				// Namespaced layout — recurse one level
+				const inner = await readdir(subdirPath, { withFileTypes: true });
+				const innerDirs = inner
+					.filter((e) => e.isDirectory())
+					.sort((a, b) => a.name.localeCompare(b.name));
+				for (const innerDir of innerDirs) {
+					const artifactPath = join(subdirPath, innerDir.name);
+					if (await exists(join(artifactPath, "knowledge.md"))) {
+						artifacts.push({ path: artifactPath, name: innerDir.name });
+					}
+				}
+			}
+		}
+	}
+
+	return artifacts;
+}
+
+/**
+ * Cross-artifact outcomes collision detection (Req 2F).
+ *
+ * Aggregates every `outcomes` declaration across all artifacts and runs the
+ * pure `runRegistryCheck` from the outcomes registry. This function is the thin
+ * I/O shell described in ADR-0041: it reads frontmatter, delegates all
+ * comparison logic to the pure core, and maps the resulting findings to
+ * validation errors and warnings.
+ *
+ *   - `collision` (non-acknowledged) -> {@link ValidationError} including both
+ *     outcome ids, both artifact names, the matched normalized shapes, and the
+ *     keyword Jaccard score (Req 2F.2).
+ *   - `duplicate-id` -> {@link ValidationError} (ids must be globally unique,
+ *     Req 2F.4).
+ *   - `ambiguous` -> {@link ValidationWarning} (does not block validation,
+ *     Req 2F.3).
+ *   - `acknowledged-overlap` -> no finding.
+ *
+ * Returns a single synthetic {@link ValidationResult} (artifact name
+ * `[outcomes-registry]`) when any finding is produced, or `null` when there is
+ * nothing to report. Errors mark the result invalid, which drives the existing
+ * non-zero exit path in {@link validateCommand} (Req 2F.2).
+ */
+async function validateOutcomes(
+	artifactList: Array<{ path: string; name: string }>,
+): Promise<ValidationResult | null> {
+	// Aggregate outcomes from each artifact's (already schema-validated)
+	// frontmatter, and remember each artifact's knowledge.md path for diagnostics.
+	const artifactsWithOutcomes: Array<{ name: string; outcomes: Outcome[] }> =
+		[];
+	const knowledgeMdByName = new Map<string, string>();
+
+	for (const { path: artifactPath, name } of artifactList) {
+		const knowledgeMdPath = join(artifactPath, "knowledge.md");
+		knowledgeMdByName.set(name, knowledgeMdPath);
+
+		const mdResult = await parseKnowledgeMd(knowledgeMdPath);
+		if (isParseError(mdResult)) continue;
+
+		const outcomes = mdResult.data.frontmatter.outcomes ?? [];
+		if (outcomes.length > 0) {
+			artifactsWithOutcomes.push({ name, outcomes });
+		}
+	}
+
+	const report = runRegistryCheck(aggregateOutcomes(artifactsWithOutcomes));
+	if (report.findings.length === 0) return null;
+
+	const errors: ValidationError[] = [];
+	const warnings: ValidationWarning[] = [];
+
+	for (const finding of report.findings) {
+		const filePath =
+			knowledgeMdByName.get(finding.a.artifactName) ?? "knowledge.md";
+		const aId = finding.a.outcome.id;
+		const bId = finding.b.outcome.id;
+		const aArtifact = finding.a.artifactName;
+		const bArtifact = finding.b.artifactName;
+
+		switch (finding.kind) {
+			case "duplicate-id":
+				errors.push({
+					field: "outcomes",
+					message: `Duplicate outcome id "${aId}" declared in both "${aArtifact}" and "${bArtifact}". Outcome ids must be globally unique.`,
+					filePath,
+				});
+				break;
+
+			case "collision":
+				errors.push({
+					field: "outcomes",
+					message: `Outcome collision: "${aId}" (${aArtifact}) and "${bId}" (${bArtifact}) share normalized shapes ("${finding.inputShape}" → "${finding.outputShape}") with keyword Jaccard ${finding.jaccard?.toFixed(2)}. Acknowledge intentional overlap by adding each id to the other's "related" field.`,
+					filePath,
+				});
+				break;
+
+			case "ambiguous":
+				warnings.push({
+					field: "outcomes",
+					message: `Ambiguous outcome overlap: "${aId}" (${aArtifact}) and "${bId}" (${bArtifact}) match on exactly one tier (keyword Jaccard ${finding.jaccard?.toFixed(2)}). Review whether these outcomes overlap.`,
+					filePath,
+				});
+				break;
+
+			// "acknowledged-overlap" is intentional — no finding reported.
+		}
+	}
+
+	const result: ValidationResult = {
+		artifactName: "[outcomes-registry]",
+		valid: errors.length === 0,
+		errors,
+	};
+	if (warnings.length > 0) {
+		result.warnings = warnings;
+	}
+	return result;
+}
+
+export async function validateAll(
+	knowledgeDirs: string | string[],
+): Promise<ValidationResult[]> {
+	const sourceDirs = Array.isArray(knowledgeDirs)
+		? knowledgeDirs
+		: [knowledgeDirs];
+	const results: ValidationResult[] = [];
+
+	const artifactList = await collectArtifactPaths(sourceDirs);
+
+	for (const { path: artifactPath } of artifactList) {
+		const result = await validateArtifact(artifactPath);
+		results.push(result);
+	}
+
+	// Cross-artifact dependency reference resolution across all source dirs
+	const artifactNames = new Set<string>(artifactList.map((a) => a.name));
+
+	for (const { path: artifactPath, name: artifactName } of artifactList) {
+		const knowledgeMdPath = join(artifactPath, "knowledge.md");
+		const mdResult = await parseKnowledgeMd(knowledgeMdPath);
+
+		if (isParseError(mdResult)) continue;
+
+		const fm = mdResult.data.frontmatter;
+		const warnings: ValidationWarning[] = [];
+
+		for (const dep of fm.depends) {
+			if (!artifactNames.has(dep)) {
+				warnings.push({
+					field: "depends",
+					message: `Unresolved dependency reference: "${dep}"`,
+					filePath: knowledgeMdPath,
+				});
+			}
+		}
+
+		for (const enh of fm.enhances) {
+			if (!artifactNames.has(enh)) {
+				warnings.push({
+					field: "enhances",
+					message: `Unresolved enhances reference: "${enh}"`,
+					filePath: knowledgeMdPath,
+				});
+			}
+		}
+
+		if (warnings.length > 0) {
+			const matchingResult = results.find(
+				(r) => r.artifactName === artifactName,
+			);
+			if (matchingResult) {
+				matchingResult.warnings = [
+					...(matchingResult.warnings ?? []),
+					...warnings,
+				];
+			}
+		}
+	}
+
+	// Cycle detection across the depends graph
+	const dependsMap = new Map<string, string[]>();
+	for (const { path: artifactPath, name: artifactName } of artifactList) {
+		const knowledgeMdPath = join(artifactPath, "knowledge.md");
+		const mdResult = await parseKnowledgeMd(knowledgeMdPath);
+		if (!isParseError(mdResult)) {
+			dependsMap.set(artifactName, mdResult.data.frontmatter.depends);
+		}
+	}
+	const cycles = detectDependencyCycles(dependsMap);
+	if (cycles.length > 0) {
+		for (const cycle of cycles) {
+			const cycleStr = [...cycle, cycle[0]].join(" → ");
+			// Attach the error to the first artifact in the cycle
+			const matchingResult = results.find((r) => r.artifactName === cycle[0]);
+			if (matchingResult) {
+				matchingResult.valid = false;
+				matchingResult.errors = [
+					...matchingResult.errors,
+					{
+						field: "depends",
+						message: `Dependency cycle detected: ${cycleStr}`,
+						filePath: join(
+							artifactList.find((a) => a.name === cycle[0])?.path ?? "",
+							"knowledge.md",
+						),
+					},
+				];
+			}
+		}
+	}
+
+	// Cross-artifact outcomes collision detection (Req 2F). Aggregates all
+	// declared outcomes and runs the pure registry check; collisions and
+	// duplicate ids surface as errors, ambiguous overlaps as warnings.
+	const outcomesResult = await validateOutcomes(artifactList);
+	if (outcomesResult) {
+		results.push(outcomesResult);
+	}
+
+	// Collection cross-check: warn if artifacts declare unknown collection names
+	const collectionsDir = "collections";
+	const collectionManifests = await loadCollections(collectionsDir);
+	if (collectionManifests.length > 0) {
+		// Build lightweight CatalogEntry-like objects from the validate results
+		const catalogEntries = await generateCatalog(sourceDirs);
+		const collectionWarnings = validateArtifactCollectionRefs(
+			catalogEntries,
+			collectionManifests,
+		);
+		for (const w of collectionWarnings) {
+			// Map to the matching result by artifact path prefix
+			const matchingResult = results.find((r) =>
+				w.filePath.includes(r.artifactName),
+			);
+			if (matchingResult) {
+				matchingResult.warnings = [...(matchingResult.warnings ?? []), w];
+			}
+		}
+	}
+
+	// Capability matrix validation: ensure matrix harnesses match adapter registry and format registry
+	const matrixSync = validateMatrixSync(
+		Object.keys(CAPABILITY_MATRIX),
+		Object.keys(adapterRegistry),
+		Object.keys(HARNESS_FORMAT_REGISTRY),
+	);
+	if (matrixSync.missing.length > 0 || matrixSync.extra.length > 0) {
+		// Create a synthetic validation result for the capability matrix
+		const matrixErrors: ValidationError[] = [];
+		for (const h of matrixSync.missing) {
+			matrixErrors.push({
+				field: "CAPABILITY_MATRIX",
+				message: `Missing capability matrix entry for harness: "${h}"`,
+				filePath: "src/adapters/capabilities.ts",
+			});
+		}
+		for (const h of matrixSync.extra) {
+			matrixErrors.push({
+				field: "CAPABILITY_MATRIX",
+				message: `Extra capability matrix entry for unknown harness: "${h}"`,
+				filePath: "src/adapters/capabilities.ts",
+			});
+		}
+		results.push({
+			artifactName: "[capability-matrix]",
+			valid: false,
+			errors: matrixErrors,
+		});
+	}
+
+	// Workspace config validation: validate workspace config if present
+	try {
+		const wsResult = await loadWorkspaceConfig(process.cwd());
+		if (wsResult) {
+			const wsErrors = await validateWorkspaceConfig(
+				wsResult.config,
+				process.cwd(),
+				artifactNames,
+			);
+			if (wsErrors.length > 0) {
+				const prefixedErrors: ValidationError[] = wsErrors.map((e) => ({
+					...e,
+					message: `kanon.config.yaml: ${e.message}`,
+				}));
+				results.push({
+					artifactName: "[workspace-config]",
+					valid: false,
+					errors: prefixedErrors,
+				});
+			}
+		}
+	} catch {
+		// If workspace config loading fails (e.g., parse error), report it
+		results.push({
+			artifactName: "[workspace-config]",
+			valid: false,
+			errors: [
+				{
+					field: "workspace-config",
+					message: "kanon.config.yaml: Failed to load workspace configuration",
+					filePath: "kanon.config.yaml",
+				},
+			],
+		});
+	}
+
+	return results;
+}
+
+export const SOURCE_DIRS = ["knowledge", "packages"] as const;
+
+export async function validateCommand(
+	artifactPath?: string,
+	options: { security?: boolean } = {},
+): Promise<void> {
+	let results: ValidationResult[];
+
+	if (artifactPath) {
+		const result = await validateArtifact(artifactPath);
+		results = [result];
+	} else {
+		results = await validateAll([...SOURCE_DIRS]);
+	}
+
+	// Overlay security checks if --security flag is set
+	if (options.security) {
+		const sourceDirs = artifactPath ? [] : [...SOURCE_DIRS];
+		const artifactPaths: string[] = [];
+
+		if (artifactPath) {
+			artifactPaths.push(artifactPath);
+		} else {
+			for (const dir of sourceDirs) {
+				if (!(await exists(dir))) continue;
+				const entries = await readdir(dir, { withFileTypes: true });
+				for (const entry of entries.filter((e) => e.isDirectory())) {
+					artifactPaths.push(join(dir, entry.name));
+				}
+			}
+		}
+
+		for (const aPath of artifactPaths) {
+			const aName = aPath.split("/").pop() ?? aPath;
+			const secResult = await validateArtifactSecurity(aPath);
+			const matching = results.find((r) => r.artifactName === aName);
+			if (matching) {
+				if (secResult.errors.length > 0) {
+					matching.errors.push(...secResult.errors);
+					matching.valid = false;
+				}
+				if (secResult.warnings.length > 0) {
+					matching.warnings = [
+						...(matching.warnings ?? []),
+						...secResult.warnings,
+					];
+				}
+			}
+		}
+	}
+
+	if (results.length === 0) {
+		console.error(chalk.yellow("No artifacts found to validate."));
+		process.exit(0);
+	}
+
+	let hasErrors = false;
+	let totalWarnings = 0;
+	for (const result of results) {
+		if (result.valid) {
+			console.error(chalk.green(`✓ ${result.artifactName}`));
+		} else {
+			hasErrors = true;
+			console.error(chalk.red(`✗ ${result.artifactName}`));
+			for (const err of result.errors) {
+				console.error(
+					chalk.red(`  ${err.field}: ${err.message} (${err.filePath})`),
+				);
+			}
+		}
+		if (result.warnings && result.warnings.length > 0) {
+			totalWarnings += result.warnings.length;
+			for (const warn of result.warnings) {
+				console.error(
+					chalk.yellow(`  ⚠ ${warn.field}: ${warn.message} (${warn.filePath})`),
+				);
+			}
+		}
+	}
+
+	const passed = results.filter((r) => r.valid).length;
+	const failed = results.filter((r) => !r.valid).length;
+	let summary = `\n${passed} passed, ${failed} failed out of ${results.length} artifacts`;
+	if (totalWarnings > 0) {
+		summary += `, ${totalWarnings} warning${totalWarnings === 1 ? "" : "s"}`;
+	}
+	console.error(summary);
+
+	if (hasErrors) {
+		process.exit(1);
+	}
+}