@tanstack/intent 0.1.0 → 0.2.0

package/dist/{skill-paths-B-j0dWDA.mjs → skill-paths-Bm1P6IYe.mjs}

@@ -1,7 +1,6 @@
-import { u as toPosixPath } from "./utils-9fhWAVua.mjs";
+import { d as toPosixPath } from "./utils-6FtqhOYf.mjs";
 import { existsSync } from "node:fs";
 import { join, relative } from "node:path";
-
 //#region src/skill-paths.ts
 function isAbsolutePath(path) {
 	return path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(path);
@@ -28,6 +27,5 @@ function formatRuntimeSkillLookupComment(target) {
 function formatRuntimeSkillLookupHint(target) {
 	return `Lookup: ${formatRuntimeSkillLookupComment(target)}`;
 }
-
 //#endregion
-export { isStableLoadPath as n, rewriteSkillLoadPaths as r, formatRuntimeSkillLookupHint as t };
+export { isStableLoadPath as n, rewriteSkillLoadPaths as r, formatRuntimeSkillLookupHint as t };

package/dist/{skill-use-CUrNHf-u.mjs → skill-use-B2xRF1i9.mjs}

@@ -37,6 +37,5 @@ function formatSkillUseParseErrorMessage(code, value) {
 		case "empty-skill": return `Invalid skill use "${value}": skill is required.`;
 	}
 }
-
 //#endregion
-export { parseSkillUse as i, formatSkillUse as n, isSkillUseParseError as r, SkillUseParseError as t };
+export { parseSkillUse as i, formatSkillUse as n, isSkillUseParseError as r, SkillUseParseError as t };

package/dist/{source-policy-DaImacFt.mjs → source-policy-DkR80hkL.mjs}

@@ -1,7 +1,6 @@
-import { t as scanForIntents } from "./scanner-CRCZwhKS.mjs";
-import { t as resolveProjectContext } from "./project-context-DBSibDPb.mjs";
-import { a as isSkillExcluded, i as isPackageExcluded, n as getConfigDirs, o as warningMentionsPackage, r as getEffectiveExcludePatterns, s as readPackageJson, t as compileExcludePatterns } from "./excludes-DG83YEzb.mjs";
-
+import { t as scanForIntents } from "./scanner-qT_M6nV5.mjs";
+import { t as resolveProjectContext } from "./project-context-oi_m7paK.mjs";
+import { a as isSkillExcluded, i as isPackageExcluded, n as getConfigDirs, o as warningMentionsPackage, r as getEffectiveExcludePatterns, s as readPackageJson, t as compileExcludePatterns } from "./excludes-ByvSbmmj.mjs";
 //#region src/core/skill-sources.ts
 var SkillSourcesParseError = class extends Error {
 	constructor(issues) {
@@ -135,7 +134,6 @@ function describeType(value) {
 function formatIssues(issues) {
 	return ["Invalid intent.skills configuration:", ...issues.map((issue) => issue.raw === null ? `  - ${issue.message}` : `  - "${issue.raw}": ${issue.message}`)].join("\n");
 }
-
 //#endregion
 //#region src/core/source-policy.ts
 const ALLOW_ALL_NOTICE = "All skill sources allowed (intent.skills: [\"*\"]) — unvetted skills may be surfaced into agent guidance.";
@@ -242,6 +240,5 @@ function scanForPolicedIntents(params) {
 		excludePatterns
 	};
 }
-
 //#endregion
-export { checkLoadAllowed as a, applySourcePolicy as i, EMPTY_NOTE as n, readSkillSourcesConfig as o, MIGRATION_NOTICE as r, scanForPolicedIntents as s, ALLOW_ALL_NOTICE as t };
+export { checkLoadAllowed as a, applySourcePolicy as i, EMPTY_NOTE as n, readSkillSourcesConfig as o, MIGRATION_NOTICE as r, scanForPolicedIntents as s, ALLOW_ALL_NOTICE as t };

package/dist/source-policy-hMYcpIgm.mjs

@@ -0,0 +1,2 @@
+import { s as scanForPolicedIntents } from "./source-policy-DkR80hkL.mjs";
+export { scanForPolicedIntents };

package/dist/{stale-DxZyYibt.mjs → stale-DhjSTIt-.mjs}

@@ -1,5 +1,4 @@
-import { n as isCliFailure } from "./cli-error-BrMXlbtx.mjs";
-
+import { n as isCliFailure } from "./cli-error-DDAO6DIL.mjs";
 //#region src/commands/stale.ts
 async function runStaleCommand(targetDir, options, resolveStaleTargets) {
 	if (options.githubReview) {
@@ -35,7 +34,7 @@ async function runStaleCommand(targetDir, options, resolveStaleTargets) {
 	}
 }
 async function runGithubReview(targetDir, options, resolveStaleTargets) {
-	const { collectStaleReviewItems, createFailedStaleReviewItem, createWorkflowAdvisoryReviewItems, writeStaleReviewWorkflowFiles } = await import("./workflow-review-CtOR1bgh.mjs");
+	const { collectStaleReviewItems, createFailedStaleReviewItem, createWorkflowAdvisoryReviewItems, writeStaleReviewWorkflowFiles } = await import("./workflow-review-Bo2kPVXV.mjs");
 	const packageLabel = options.packageLabel ?? "workspace";
 	try {
 		const { reports, workflowAdvisories = [] } = await resolveStaleTargets(targetDir);
@@ -50,6 +49,5 @@ async function runGithubReview(targetDir, options, resolveStaleTargets) {
 		console.log("Wrote a review PR body so maintainers can inspect the logs.");
 	}
 }
-
 //#endregion
-export { runStaleCommand };
+export { runStaleCommand };

package/dist/staleness-B5Cqe77_.mjs

@@ -0,0 +1,2 @@
+import { n as checkStaleness, r as readPackageName, t as buildWorkspaceCoverageSignals } from "./staleness-DoZU3lzy.mjs";
+export { buildWorkspaceCoverageSignals, checkStaleness, readPackageName };

package/dist/{staleness-DVFARTES.mjs → staleness-DoZU3lzy.mjs}

@@ -1,9 +1,8 @@
-import { c as parseFrontmatter, r as findSkillFiles, u as toPosixPath } from "./utils-9fhWAVua.mjs";
-import { t as readIntentArtifacts } from "./artifact-coverage-nGwun1tt.mjs";
+import { c as parseFrontmatter, d as toPosixPath, l as readScalarField, r as findSkillFiles } from "./utils-6FtqhOYf.mjs";
+import { t as readIntentArtifacts } from "./artifact-coverage-DFtI6V_H.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import semver from "semver";
-
 //#region src/staleness.ts
 function classifyVersionDrift(oldVer, newVer) {
 	const oldVersion = normalizeVersion(oldVer);
@@ -126,10 +125,7 @@ function findMatchingSkill(artifact, skillMetas, packageDir, artifactRoot) {
 		if (match) return match;
 	}
 	const skillsByName = /* @__PURE__ */ new Map();
-	for (const skill of skillMetas) {
-		skillsByName.set(skill.name, skill);
-		skillsByName.set(skill.relName, skill);
-	}
+	for (const skill of skillMetas) skillsByName.set(skill.relName, skill);
 	return (artifact.slug ? skillsByName.get(artifact.slug) : void 0) ?? (artifact.name ? skillsByName.get(artifact.name) : void 0) ?? null;
 }
 function buildArtifactSignals({ artifactRoot, artifacts, library, packageDir, skillMetas }) {
@@ -167,7 +163,7 @@ function buildArtifactSignals({ artifactRoot, artifacts, library, packageDir, sk
 			reasons: ["artifact sources differ from SKILL.md frontmatter sources"],
 			needsReview: true,
 			artifactPath: artifact.artifactPath,
-			skill: matchingSkill.name
+			skill: matchingSkill.relName
 		});
 		const artifactVersion = artifactFiles.get(artifact.artifactPath)?.libraryVersion;
 		if (artifactVersion && matchingSkill.libraryVersion && artifactVersion !== matchingSkill.libraryVersion) signals.push({
@@ -177,7 +173,7 @@ function buildArtifactSignals({ artifactRoot, artifacts, library, packageDir, sk
 			reasons: [`artifact library.version (${artifactVersion}) differs from SKILL.md library_version (${matchingSkill.libraryVersion})`],
 			needsReview: true,
 			artifactPath: artifact.artifactPath,
-			skill: matchingSkill.name
+			skill: matchingSkill.relName
 		});
 	}
 	return signals;
@@ -217,12 +213,10 @@ async function checkStaleness(packageDir, packageName, artifactRoot = packageDir
 	const library = packageName ?? readPackageName(packageDir);
 	const skillMetas = findSkillFiles(skillsDir).map((filePath) => {
 		const fm = parseFrontmatter(filePath);
-		const relName = toPosixPath(relative(skillsDir, filePath)).replace(/[/\\]SKILL\.md$/, "");
 		return {
-			name: typeof fm?.name === "string" ? fm.name : relName,
-			relName,
+			relName: toPosixPath(relative(skillsDir, filePath)).replace(/[/\\]SKILL\.md$/, ""),
 			filePath,
-			libraryVersion: fm?.library_version,
+			libraryVersion: readScalarField(fm, "library_version"),
 			sources: Array.isArray(fm?.sources) ? fm.sources : void 0
 		};
 	});
@@ -239,12 +233,12 @@ async function checkStaleness(packageDir, packageName, artifactRoot = packageDir
 		skills: skillMetas.map((skill) => {
 			const reasons = [];
 			if (currentVersion && skill.libraryVersion && classifyVersionDrift(skill.libraryVersion, currentVersion) !== null) reasons.push(`version drift (${skill.libraryVersion} → ${currentVersion})`);
-			const storedShas = syncState?.skills?.[skill.name]?.sources_sha ?? {};
+			const storedShas = syncState?.skills?.[skill.relName]?.sources_sha ?? {};
 			if (skill.sources && Object.keys(storedShas).length > 0) {
 				for (const source of skill.sources) if (!storedShas[source]) reasons.push(`new source (${source})`);
 			}
 			return {
-				name: skill.name,
+				name: skill.relName,
 				reasons,
 				needsReview: reasons.length > 0
 			};
@@ -258,6 +252,5 @@ async function checkStaleness(packageDir, packageName, artifactRoot = packageDir
 		})
 	};
 }
-
 //#endregion
-export { checkStaleness as n, readPackageName as r, buildWorkspaceCoverageSignals as t };
+export { checkStaleness as n, readPackageName as r, buildWorkspaceCoverageSignals as t };

package/dist/{types-DhITOzhi.d.mts → types-P6UfPVdp.d.mts}

@@ -117,37 +117,5 @@ interface IntentArtifactWarning {
   artifactPath: string;
   message: string;
 }
-interface FeedbackPayload {
-  skill: string;
-  package: string;
-  skillVersion: string;
-  task: string;
-  whatWorked: string;
-  whatFailed: string;
-  missing: string;
-  selfCorrections: string;
-  userRating: 'good' | 'mixed' | 'bad';
-  userComments?: string;
-}
-type MetaSkillName = 'domain-discovery' | 'tree-generator' | 'generate-skill' | 'skill-staleness-check';
-type AgentName = 'claude-code' | 'cursor' | 'copilot' | 'codex' | 'other';
-interface MetaFeedbackPayload {
-  metaSkill: MetaSkillName;
-  library: string;
-  agentUsed: AgentName;
-  artifactQuality: 'good' | 'mixed' | 'bad';
-  interviewQuality?: 'good' | 'mixed' | 'bad' | 'skipped';
-  failureModeQuality?: 'good' | 'mixed' | 'bad' | 'not-applicable';
-  whatWorked: string;
-  whatFailed: string;
-  suggestions: string;
-  userRating: 'good' | 'mixed' | 'bad';
-}
-type FeedbackFrequency = 'always' | 'never' | `every-${number}`;
-interface IntentProjectConfig {
-  feedback: {
-    frequency: FeedbackFrequency;
-  };
-}
 //#endregion
-export { VersionConflict as S, ScanStats as _, IntentArtifactSet as a, StalenessReport as b, IntentConfig as c, MetaFeedbackPayload as d, MetaSkillName as f, ScanScope as g, ScanResult as h, IntentArtifactFile as i, IntentPackage as l, ScanOptions as m, FeedbackPayload as n, IntentArtifactSkill as o, PackageManager as p, IntentArtifactCoverageIgnore as r, IntentArtifactWarning as s, AgentName as t, IntentProjectConfig as u, SkillEntry as v, StalenessSignal as x, SkillStaleness as y };
+export { VersionConflict as _, IntentArtifactWarning as a, PackageManager as c, ScanScope as d, ScanStats as f, StalenessSignal as g, StalenessReport as h, IntentArtifactSkill as i, ScanOptions as l, SkillStaleness as m, IntentArtifactFile as n, IntentConfig as o, SkillEntry as p, IntentArtifactSet as r, IntentPackage as s, IntentArtifactCoverageIgnore as t, ScanResult as u };

package/dist/{utils-9fhWAVua.mjs → utils-6FtqhOYf.mjs}

@@ -3,7 +3,6 @@ import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, rea
 import { dirname, join, resolve, sep } from "node:path";
 import { execFileSync } from "node:child_process";
 import { parse } from "yaml";
-
 //#region src/utils.ts
 const nodeReadFs = {
 	existsSync,
@@ -230,6 +229,19 @@ function resolveDepDir(depName, parentDir) {
 	return null;
 }
 /**
+* Read a scalar string field from frontmatter, preferring `metadata.<key>` over
+* a top-level `<key>` (#159 back-compat for the frontmatter migration).
+*/
+function readScalarField(fm, key) {
+	const metadata = fm?.metadata;
+	if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+		const nested = metadata[key];
+		if (typeof nested === "string") return nested;
+	}
+	const top = fm?.[key];
+	return typeof top === "string" ? top : void 0;
+}
+/**
 * Parse YAML frontmatter from a file. Returns null if no frontmatter or on error.
 */
 function parseFrontmatter(filePath, fs = nodeReadFs) {
@@ -277,6 +289,5 @@ function readFrontmatterRegion(filePath, fs) {
 		return null;
 	}
 }
-
 //#endregion
-export { listNestedNodeModulesPackageDirs as a, parseFrontmatter as c, getDeps as i, resolveDepDir as l, detectGlobalNodeModules as n, listNodeModulesPackageDirs as o, findSkillFiles as r, nodeReadFs as s, createFsIdentityCache as t, toPosixPath as u };
+export { listNestedNodeModulesPackageDirs as a, parseFrontmatter as c, toPosixPath as d, getDeps as i, readScalarField as l, detectGlobalNodeModules as n, listNodeModulesPackageDirs as o, findSkillFiles as r, nodeReadFs as s, createFsIdentityCache as t, resolveDepDir as u };

package/dist/utils-BKBDYbCx.mjs

@@ -0,0 +1,2 @@
+import { a as listNestedNodeModulesPackageDirs, c as parseFrontmatter, d as toPosixPath, i as getDeps, l as readScalarField, n as detectGlobalNodeModules, o as listNodeModulesPackageDirs, r as findSkillFiles, s as nodeReadFs, t as createFsIdentityCache, u as resolveDepDir } from "./utils-6FtqhOYf.mjs";
+export { createFsIdentityCache, detectGlobalNodeModules, findSkillFiles, getDeps, listNestedNodeModulesPackageDirs, listNodeModulesPackageDirs, nodeReadFs, parseFrontmatter, readScalarField, resolveDepDir, toPosixPath };

package/dist/{validate-CnQBn6v9.mjs → validate-BSfTOq0v.mjs}

@@ -1,13 +1,29 @@
-import "./utils-9fhWAVua.mjs";
-import { n as findWorkspacePackages } from "./workspace-patterns-BffPlZ1D.mjs";
-import { t as resolveProjectContext } from "./project-context-DBSibDPb.mjs";
-import { n as isCliFailure, t as fail } from "./cli-error-BrMXlbtx.mjs";
-import { u as printWarnings } from "./cli-support-BevVu4gw.mjs";
-import { appendFileSync, existsSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-
+import { n as findWorkspacePackages } from "./workspace-patterns-BDoJIWk-.mjs";
+import { t as resolveProjectContext } from "./project-context-oi_m7paK.mjs";
+import { n as isCliFailure, t as fail } from "./cli-error-DDAO6DIL.mjs";
+import { u as printWarnings } from "./cli-support-BQSl7gAE.mjs";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 //#region src/commands/validate.ts
 const agentSkillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const specTopLevelKeys = new Set([
+	"name",
+	"description",
+	"license",
+	"compatibility",
+	"metadata",
+	"allowed-tools"
+]);
+const intentArrayKeys = new Set(["sources", "requires"]);
+const metadataScalarKeys = [
+	"type",
+	"library",
+	"library_version",
+	"framework"
+];
+function isScalarValue(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
 function buildValidationFailure(errors, warnings) {
 	const lines = [
 		"",
@@ -48,26 +64,60 @@ function formatWarning({ file, message }) {
 function isRecord(value) {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function collectAgentSkillSpecWarnings({ filePath, fm, rel }) {
-	const warnings = [];
-	if (typeof fm.name === "string") {
-		if (fm.name.length > 64) warnings.push({
-			file: rel,
-			message: `Agent Skills spec warning: name exceeds 64 characters (${fm.name.length} chars)`
-		});
-		for (const segment of fm.name.split("/")) if (!agentSkillNamePattern.test(segment)) {
-			warnings.push({
-				file: rel,
-				message: "Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only"
-			});
-			break;
+function collectFrontmatterFixPlan({ filePath, fm, rel }) {
+	const changes = [];
+	const parentDir = basename(dirname(filePath));
+	if (typeof fm.name === "string" && (fm.name.includes("/") || fm.name !== parentDir) && agentSkillNamePattern.test(parentDir)) changes.push(`rewrite name to "${parentDir}"`);
+	const metadata = fm.metadata;
+	if (metadata === void 0 || isRecord(metadata)) {
+		const metadataRecord = isRecord(metadata) ? metadata : void 0;
+		for (const key of metadataScalarKeys) {
+			if (typeof fm[key] !== "string") continue;
+			if (metadataRecord && key in metadataRecord) changes.push(`remove top-level "${key}"; metadata.${key} already exists`);
+			else changes.push(`move top-level "${key}" under metadata.${key}`);
 		}
-		const parentDir = basename(dirname(filePath));
-		if (!fm.name.includes("/") && fm.name !== parentDir) warnings.push({
-			file: rel,
-			message: "Agent Skills spec warning: name should match the parent directory name"
-		});
 	}
+	return changes.length > 0 ? {
+		file: rel,
+		filePath,
+		changes
+	} : null;
+}
+function normalizeLineEndings(value, lineEnding) {
+	return lineEnding === "\r\n" ? value.replace(/\r?\n/g, "\r\n") : value;
+}
+async function applyFrontmatterFixes(fixPlans) {
+	const { parseDocument } = await import("yaml");
+	for (const plan of fixPlans) {
+		const match = readFileSync(plan.filePath, "utf8").match(/^---(\r?\n)([\s\S]*?)(\r?\n)---(\r?\n?)([\s\S]*)/);
+		if (!match) continue;
+		const openingLineEnding = match[1];
+		const frontmatter = match[2];
+		const closingLineEnding = match[3];
+		const afterClose = match[4];
+		const body = match[5];
+		if (openingLineEnding === void 0 || frontmatter === void 0 || closingLineEnding === void 0 || afterClose === void 0 || body === void 0) continue;
+		const doc = parseDocument(frontmatter);
+		if (doc.errors.length > 0) continue;
+		const fm = doc.toJS();
+		const parentDir = basename(dirname(plan.filePath));
+		if (typeof fm.name === "string" && (fm.name.includes("/") || fm.name !== parentDir) && agentSkillNamePattern.test(parentDir)) doc.set("name", parentDir);
+		const metadata = fm.metadata;
+		if (metadata === void 0 || isRecord(metadata)) for (const key of metadataScalarKeys) {
+			const value = fm[key];
+			if (typeof value !== "string") continue;
+			if (!doc.hasIn(["metadata", key])) {
+				const valueNode = doc.get(key, true);
+				doc.setIn(["metadata", key], valueNode ?? value);
+			}
+			doc.delete(key);
+		}
+		const nextContent = `---${openingLineEnding}${normalizeLineEndings(doc.toString().replace(/\r?\n$/, ""), openingLineEnding)}${closingLineEnding}---${afterClose}${body}`;
+		writeFileSync(plan.filePath, nextContent);
+	}
+}
+function collectAgentSkillSpecWarnings({ fm, rel }) {
+	const warnings = [];
 	if (fm.license !== void 0 && (typeof fm.license !== "string" || fm.license.trim().length === 0)) warnings.push({
 		file: rel,
 		message: "Agent Skills spec warning: license should be a non-empty string"
@@ -82,16 +132,6 @@ function collectAgentSkillSpecWarnings({ filePath, fm, rel }) {
 			message: `Agent Skills spec warning: compatibility exceeds 500 characters (${fm.compatibility.length} chars)`
 		});
 	}
-	if (fm.metadata !== void 0) {
-		if (!isRecord(fm.metadata)) warnings.push({
-			file: rel,
-			message: "Agent Skills spec warning: metadata should be a mapping"
-		});
-		else if (Object.values(fm.metadata).some((value) => typeof value !== "string")) warnings.push({
-			file: rel,
-			message: "Agent Skills spec warning: metadata values should be strings"
-		});
-	}
 	if (fm["allowed-tools"] !== void 0 && typeof fm["allowed-tools"] !== "string") warnings.push({
 		file: rel,
 		message: "Agent Skills spec warning: allowed-tools should be a space-separated string"
@@ -99,12 +139,13 @@ function collectAgentSkillSpecWarnings({ filePath, fm, rel }) {
 	return warnings;
 }
 async function runValidateCommand(dir, options = {}) {
+	if (options.fix && options.check) fail("Cannot combine --fix and --check");
 	if (!options.githubSummary) {
-		await runValidateCommandInternal(dir);
+		await runValidateCommandInternal(dir, options);
 		return;
 	}
 	try {
-		await runValidateCommandInternal(dir);
+		await runValidateCommandInternal(dir, options);
 		writeGithubValidationSummary({ ok: true });
 	} catch (err) {
 		writeGithubValidationSummary({
@@ -114,8 +155,8 @@ async function runValidateCommand(dir, options = {}) {
 		throw err;
 	}
 }
-async function runValidateCommandInternal(dir) {
-	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-CSPzvaFu.mjs")]);
+async function runValidateCommandInternal(dir, options = {}) {
+	const [{ parse: parseYaml }, { findSkillFiles, readScalarField }] = await Promise.all([import("yaml"), import("./utils-BKBDYbCx.mjs")]);
 	const context = resolveProjectContext({
 		cwd: process.cwd(),
 		targetPath: dir
@@ -125,6 +166,7 @@ async function runValidateCommandInternal(dir) {
 	if (explicitDir && !existsSync(skillsDirs[0])) fail(`Skills directory not found: ${skillsDirs[0]}`);
 	const errors = [];
 	const warnings = [];
+	const fixPlans = [];
 	let validatedCount = 0;
 	if (explicitDir && findSkillFiles(skillsDirs[0]).length === 0) fail("No SKILL.md files found");
 	if (skillsDirs.length === 0) {
@@ -166,6 +208,12 @@ async function runValidateCommandInternal(dir) {
 				});
 				continue;
 			}
+			const fixPlan = collectFrontmatterFixPlan({
+				filePath,
+				fm,
+				rel
+			});
+			if (fixPlan) fixPlans.push(fixPlan);
 			if (!fm.name) errors.push({
 				file: rel,
 				message: "Missing required field: name"
@@ -175,22 +223,49 @@ async function runValidateCommandInternal(dir) {
 				message: "Missing required field: description"
 			});
 			if (typeof fm.name === "string") {
-				const expectedPath = relative(skillsDir, filePath).replace(/[/\\]SKILL\.md$/, "").split(sep).join("/");
-				if (fm.name !== expectedPath) errors.push({
+				const parentDir = basename(dirname(filePath));
+				if (fm.name.length > 64) errors.push({
 					file: rel,
-					message: `name "${fm.name}" does not match directory path "${expectedPath}"`
+					message: `name exceeds 64 characters (${fm.name.length} chars)`
+				});
+				if (fm.name.includes("/")) errors.push({
+					file: rel,
+					message: `name "${fm.name}" must be a single leaf segment matching its parent directory "${parentDir}" — the namespace is carried by the directory path, not the name`
+				});
+				else {
+					if (fm.name !== parentDir) errors.push({
+						file: rel,
+						message: `name "${fm.name}" does not match parent directory "${parentDir}"`
+					});
+					if (!agentSkillNamePattern.test(fm.name)) errors.push({
+						file: rel,
+						message: `name "${fm.name}" must use only lowercase letters, numbers, and hyphens`
+					});
+				}
+			}
+			for (const [key, value] of Object.entries(fm)) if (!specTopLevelKeys.has(key) && !intentArrayKeys.has(key) && isScalarValue(value)) errors.push({
+				file: rel,
+				message: `non-spec top-level key "${key}" — move client-specific scalar fields under "metadata"`
+			});
+			if (fm.metadata !== void 0) {
+				if (!isRecord(fm.metadata)) errors.push({
+					file: rel,
+					message: "metadata must be a mapping"
+				});
+				else if (Object.values(fm.metadata).some((value) => typeof value !== "string")) errors.push({
+					file: rel,
+					message: "metadata values must be strings"
 				});
 			}
 			if (typeof fm.description === "string" && fm.description.length > 1024) errors.push({
 				file: rel,
 				message: `Description exceeds 1024 character limit (${fm.description.length} chars)`
 			});
-			if (fm.type === "framework" && !Array.isArray(fm.requires)) errors.push({
+			if (readScalarField(fm, "type") === "framework" && !Array.isArray(fm.requires)) errors.push({
 				file: rel,
 				message: "Framework skills must have a \"requires\" field"
 			});
 			warnings.push(...collectAgentSkillSpecWarnings({
-				filePath,
 				fm,
 				rel
 			}).map(formatWarning));
@@ -235,6 +310,19 @@ async function runValidateCommandInternal(dir) {
 		validatedCount += skillFiles.length;
 		warnings.push(...collectPackagingWarnings(validateContext));
 	}
+	if (options.check) for (const plan of fixPlans) errors.push({
+		file: plan.file,
+		message: `fixable frontmatter migration pending: ${plan.changes.join("; ")}`
+	});
+	if (options.fix && fixPlans.length > 0) {
+		await applyFrontmatterFixes(fixPlans);
+		console.log(`✅ Fixed ${fixPlans.length} skill files`);
+		await runValidateCommandInternal(dir, {
+			...options,
+			fix: false
+		});
+		return;
+	}
 	if (errors.length > 0) fail(buildValidationFailure(errors, warnings));
 	console.log(`✅ Validated ${validatedCount} skill files — all passed`);
 	if (warnings.length > 0) console.log();
@@ -266,6 +354,5 @@ function collectDefaultSkillsDirs(context, findSkillFiles) {
 	addSkillsDir(context.targetSkillsDir ?? (context.packageRoot ? join(context.packageRoot, "skills") : resolve(context.cwd, "skills")));
 	return skillsDirs;
 }
-
 //#endregion
-export { runValidateCommand };
+export { runValidateCommand };

package/dist/{workflow-review-wL1Iu2Sf.mjs → workflow-review-B4AfwtHH.mjs}

@@ -1,5 +1,4 @@
 import { appendFileSync, writeFileSync } from "node:fs";
-
 //#region src/workflow-review.ts
 function collectStaleReviewItems(reports) {
 	const items = [];
@@ -148,6 +147,5 @@ function writeStaleReviewWorkflowFiles(items, options = {}) {
 	if (hasReview) writeFileSync(prBodyPath, summary);
 	if (summaryPath) appendFileSync(summaryPath, summary);
 }
-
 //#endregion
-export { writeStaleReviewWorkflowFiles as a, createWorkflowAdvisoryReviewItems as i, collectStaleReviewItems as n, createFailedStaleReviewItem as r, buildStaleReviewBody as t };
+export { writeStaleReviewWorkflowFiles as a, createWorkflowAdvisoryReviewItems as i, collectStaleReviewItems as n, createFailedStaleReviewItem as r, buildStaleReviewBody as t };

package/dist/{workflow-review-CtOR1bgh.mjs → workflow-review-Bo2kPVXV.mjs}

@@ -1,3 +1,2 @@
-import { a as writeStaleReviewWorkflowFiles, i as createWorkflowAdvisoryReviewItems, n as collectStaleReviewItems, r as createFailedStaleReviewItem, t as buildStaleReviewBody } from "./workflow-review-wL1Iu2Sf.mjs";
-
-export { collectStaleReviewItems, createFailedStaleReviewItem, createWorkflowAdvisoryReviewItems, writeStaleReviewWorkflowFiles };
+import { a as writeStaleReviewWorkflowFiles, i as createWorkflowAdvisoryReviewItems, n as collectStaleReviewItems, r as createFailedStaleReviewItem } from "./workflow-review-B4AfwtHH.mjs";
+export { collectStaleReviewItems, createFailedStaleReviewItem, createWorkflowAdvisoryReviewItems, writeStaleReviewWorkflowFiles };

package/dist/{workspace-patterns-BffPlZ1D.mjs → workspace-patterns-BDoJIWk-.mjs}

@@ -1,9 +1,8 @@
-import { r as findSkillFiles } from "./utils-9fhWAVua.mjs";
+import { r as findSkillFiles } from "./utils-6FtqhOYf.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";
 import { parse as parse$1 } from "jsonc-parser";
-
 //#region src/workspace-patterns.ts
 function normalizeWorkspacePattern(pattern) {
 	return pattern.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
@@ -189,6 +188,5 @@ function findPackagesWithSkills(root) {
 function findWorkspacePackages(root) {
 	return readWorkspacePackageDirs(root) ?? [];
 }
-
 //#endregion
-export { readWorkspacePatterns as a, getWorkspaceInfo as i, findWorkspacePackages as n, resolveWorkspacePackages as o, findWorkspaceRoot as r, findPackagesWithSkills as t };
+export { readWorkspacePatterns as a, getWorkspaceInfo as i, findWorkspacePackages as n, resolveWorkspacePackages as o, findWorkspaceRoot as r, findPackagesWithSkills as t };

package/dist/workspace-patterns-CrL8hAbd.mjs

@@ -0,0 +1,2 @@
+import { i as getWorkspaceInfo, r as findWorkspaceRoot } from "./workspace-patterns-BDoJIWk-.mjs";
+export { findWorkspaceRoot, getWorkspaceInfo };

package/meta/domain-discovery/SKILL.md

@@ -572,7 +572,7 @@ Include the full draft domain_map.yaml in your message so the maintainer
 can review it. Also include a checklist of all docs files you read.
 
 **── STOP ── Do not proceed to Phase 4 until the maintainer has
-reviewed the draft and responded. Their feedback on the draft informs
+reviewed the draft and responded. Their response to the draft informs
 the detail interview questions.**
 
 ---