@open-agent-toolkit/cli 0.2.66 → 0.2.68

package/dist/validation/skills.js

@@ -491,16 +491,81 @@ function unusableVersionFinding(file) {
         message: 'Frontmatter declares a version that cannot be read; use a quoted semver string (unquoted, version: 1.10 is the number 1.1)',
     };
 }
+const MISSING_FRONTMATTER_BLOCK_MESSAGE = 'Missing frontmatter block (--- ... ---)';
+/**
+ * The file carries no `--- … ---` block at all, so there is no position a
+ * version could be declared in.
+ *
+ * Reported rather than skipped: a changed file with no frontmatter used to
+ * fall through the bump gate's `continue`, which meant a canonical skill or
+ * agent role could drop its frontmatter and pass the version contract by
+ * omission. The structural pass reports the same state for every skill
+ * directory, so `pushUniqueFinding` keeps it to one finding per file.
+ */
+function missingFrontmatterFinding(file) {
+    return {
+        file,
+        code: 'skill-frontmatter-missing',
+        severity: 'error',
+        message: `${MISSING_FRONTMATTER_BLOCK_MESSAGE}; a changed canonical skill or agent role must declare a version`,
+    };
+}
+/**
+ * Frontmatter is present and readable but declares no version anywhere — the
+ * `metadata:` map with no `version` child is the shape that made this state
+ * common once bundled skills moved off the top-level alias.
+ *
+ * Distinct from `skill-version-unusable`: there the author wrote a version
+ * OAT cannot read, here no version was written at all. Both disable version
+ * enforcement, so both are errors.
+ */
+/**
+ * True when some pass already reported that this file has no frontmatter
+ * block.
+ *
+ * The `oat-*` structural loop reports the state with its own long-standing
+ * message and no `code`, so `pushUniqueFinding` cannot dedupe it against the
+ * coded finding. `validateOatSkills` runs the structural loop, the
+ * version-source pass, and (when a `baseRef` is given) the bump collector into
+ * one findings array, and all three can see the same file.
+ */
+function hasMissingFrontmatterReport(findings, file) {
+    return findings.some((finding) => finding.file === file &&
+        (finding.code === 'skill-frontmatter-missing' ||
+            finding.message === MISSING_FRONTMATTER_BLOCK_MESSAGE));
+}
+function missingVersionFinding(file) {
+    return {
+        file,
+        code: 'skill-version-missing',
+        severity: 'error',
+        message: 'Frontmatter declares no resolvable version; declare metadata.version (a canonical agent role under .agents/agents may declare a top-level version: instead)',
+    };
+}
+const UNCOMPARABLE_BASE_CODES = {
+    unreadable: 'skill-frontmatter-unreadable',
+    unusable: 'skill-version-unusable',
+    'missing-frontmatter': 'skill-frontmatter-missing',
+    'missing-version': 'skill-version-missing',
+};
+const UNCOMPARABLE_BASE_REASONS = {
+    unreadable: 'the base frontmatter is not a valid YAML mapping with unique keys',
+    unusable: 'the base frontmatter declares a version that cannot be read',
+    'missing-frontmatter': 'the base file has no frontmatter block (--- ... ---)',
+    'missing-version': 'the base frontmatter declares no resolvable version',
+};
+/**
+ * The base side is deliberately asymmetric with the current side: a base that
+ * cannot be read is a comparison problem, not a defect in the file the author
+ * just changed, so the message says the base cannot be compared rather than
+ * accusing the current file.
+ */
 function uncomparableBaseFinding(file, baseRef, reason) {
     return {
         file,
-        code: reason === 'unreadable'
-            ? 'skill-frontmatter-unreadable'
-            : 'skill-version-unusable',
+        code: UNCOMPARABLE_BASE_CODES[reason],
         severity: 'error',
-        message: reason === 'unreadable'
-            ? `Changed canonical skill cannot be version-checked against ${baseRef}: the base frontmatter is not a valid YAML mapping with unique keys`
-            : `Changed canonical skill cannot be version-checked against ${baseRef}: the base frontmatter declares a version that cannot be read`,
+        message: `Changed canonical skill cannot be version-checked against ${baseRef}: ${UNCOMPARABLE_BASE_REASONS[reason]}`,
     };
 }
 function uncomparableBaseConflictFinding(file, baseRef, conflict) {
@@ -618,23 +683,130 @@ async function collectGateabilityFindings(skillsRoot, gateSkillNames, findings)
         }
     }
 }
-async function listChangedSkillFiles(repoRoot, baseRef, dependencies) {
+const SKILLS_PATH_PREFIX = '.agents/skills/';
+const AGENTS_PATH_PREFIX = '.agents/agents/';
+/**
+ * Map a diffed path to the versioned files that must bump for it, or an empty
+ * list when nothing owns it.
+ *
+ * Everything a skill directory ships is owned by that skill's `SKILL.md`,
+ * because `bundle-assets.sh` copies the directory with `cp -RL` and then
+ * removes `tests`. `tests` is therefore the one excluded entry: it does not
+ * reach consumers, and demanding a bump for it would train maintainers to bump
+ * reflexively. The exclusion matches a plain `tests` path as well as the
+ * `tests/` subtree because `rm -rf .../tests` removes either one.
+ *
+ * A path can map to two files. The previous pathspec was a `*` wildcard
+ * between `.agents/skills/` and `SKILL.md`, and a Git pathspec `*` crosses
+ * `/`, so it also matched a *nested* `SKILL.md` such as
+ * `.agents/skills/foo/references/example/SKILL.md` and validated that file's
+ * own version. Mapping such a path only to the outer skill would drop a
+ * finding this gate already emitted, which the weaker-anywhere rule forbids.
+ * A nested `SKILL.md` therefore maps to itself (preserving the old half
+ * exactly) *and* to its owning skill (adding the new coverage).
+ */
+async function resolveOwningVersionedFiles(repoRoot, changedPath) {
+    if (changedPath.startsWith(SKILLS_PATH_PREFIX)) {
+        const rest = changedPath.slice(SKILLS_PATH_PREFIX.length);
+        const separator = rest.indexOf('/');
+        if (separator <= 0) {
+            // A file directly under `.agents/skills` belongs to no skill.
+            return [];
+        }
+        const withinSkill = rest.slice(separator + 1);
+        if (withinSkill === 'tests' || withinSkill.startsWith('tests/')) {
+            // Deliberate, including for a `SKILL.md` nested under `tests/`, which
+            // the old wildcard pathspec also matched. Excluding it narrows that
+            // pathspec by exactly one shape, and that is the intended trade: a
+            // fixture `SKILL.md` under `tests/` is test data, it never reaches a
+            // consumer, and demanding a version bump for it is the reflexive
+            // bumping the `tests/` boundary exists to prevent. No such file exists
+            // in the bundled tree; every `SKILL.md` sits at the skill root.
+            return [];
+        }
+        const candidates = [
+            `${SKILLS_PATH_PREFIX}${rest.slice(0, separator)}/SKILL.md`,
+        ];
+        if (changedPath.endsWith('/SKILL.md') &&
+            !candidates.includes(changedPath)) {
+            candidates.push(changedPath);
+        }
+        const owners = [];
+        for (const candidate of candidates) {
+            // A candidate that is not on disk was removed or renamed away, so there
+            // is nothing left to bump and nothing to read.
+            if (await isFile(join(repoRoot, candidate))) {
+                owners.push(candidate);
+            }
+        }
+        return owners;
+    }
+    if (changedPath.startsWith(AGENTS_PATH_PREFIX)) {
+        const rest = changedPath.slice(AGENTS_PATH_PREFIX.length);
+        // Git pathspec `*` crosses `/`, so the nested-directory bound the pathspec
+        // implies is enforced here rather than assumed of the pathspec.
+        if (rest.length === 0 || rest.includes('/') || !rest.endsWith('.md')) {
+            return [];
+        }
+        return [changedPath];
+    }
+    return [];
+}
+/**
+ * List the canonical files whose version must move, given everything that
+ * changed under `.agents/skills` and `.agents/agents`.
+ *
+ * The pathspec is deliberately wider than the files that carry a version: a
+ * skill's `scripts/` and `references/` ship to every `oat tools install`
+ * consumer, so a change to one is a change to that skill even when `SKILL.md`
+ * is untouched. Agent roles are diffed for the first time here; per
+ * `DR-260908-bundled-skills-declare` they still declare a top-level `version:`
+ * and are deliberately not migrated, so the gate accepts either declaration
+ * shape rather than demanding `metadata.version` of them.
+ */
+async function listChangedVersionedFiles(repoRoot, baseRef, dependencies) {
     const execFile = dependencies.gitExecFile ?? execFileAsync;
     const { stdout } = await execFile('git', [
         'diff',
         '--name-only',
+        // NUL-delimited: without `-z`, Git C-quotes any path containing a tab,
+        // quote, backslash, or (under the default `core.quotePath`) a non-ASCII
+        // byte. The old pathspec only ever produced plain `SKILL.md` paths, but
+        // this one lists every shipped file, so a quoted name would no longer
+        // match the prefixes below and would silently escape the gate.
+        '-z',
         '--diff-filter=ACMR',
         `${baseRef}...HEAD`,
         '--',
-        '.agents/skills/*/SKILL.md',
+        '.agents/skills',
+        '.agents/agents/*.md',
     ], {
         cwd: repoRoot,
         env: dependencies.env ?? process.env,
     });
-    return stdout
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0);
+    // No trimming: with `-z` each entry is the exact path, and a Git path may
+    // legitimately begin or end with a space. The trailing empty entry after the
+    // final NUL is what the length filter removes.
+    const changedPaths = stdout.split('\0').filter((entry) => entry.length > 0);
+    const grouped = new Map();
+    for (const changedPath of changedPaths) {
+        const owningFiles = await resolveOwningVersionedFiles(repoRoot, changedPath);
+        for (const owningFile of owningFiles) {
+            const owned = grouped.get(owningFile);
+            if (owned === undefined) {
+                grouped.set(owningFile, [changedPath]);
+            }
+            else if (!owned.includes(changedPath)) {
+                owned.push(changedPath);
+            }
+        }
+    }
+    // Plain code-unit ordering, not `localeCompare`: findings order is part of
+    // this command's observable output, and a locale-aware comparison would make
+    // it depend on the ICU data of whatever machine ran the gate.
+    return [...grouped.entries()]
+        .map(([file, owned]) => ({ file, changedPaths: [...owned].sort() }))
+        .sort((left, right) => left.file < right.file ? -1 : left.file > right.file ? 1 : 0);
 }
 async function readFileAtGitRef(repoRoot, ref, filePath, dependencies) {
     const execFile = dependencies.gitExecFile ?? execFileAsync;
@@ -649,22 +821,64 @@ async function readFileAtGitRef(repoRoot, ref, filePath, dependencies) {
         return null;
     }
 }
-async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changedSkillFiles, findings, dependencies) {
-    for (const relativeSkillPath of changedSkillFiles) {
+/**
+ * Name the sibling paths that changed, relative to the owning file's
+ * directory, when the owning file itself is not one of them.
+ *
+ * Without this a scripts-only failure would point at a `SKILL.md` whose bytes
+ * the author never touched and say nothing about why it is being asked to
+ * bump.
+ */
+function changedSiblingSuffix(entry) {
+    if (entry.changedPaths.includes(entry.file)) {
+        return '';
+    }
+    const directory = entry.file.slice(0, entry.file.lastIndexOf('/') + 1);
+    const relativePaths = entry.changedPaths.map((path) => path.startsWith(directory) ? path.slice(directory.length) : path);
+    return ` [changed: ${relativePaths.join(', ')}]`;
+}
+const VERSION_DECLARATION_HINT = 'declare metadata.version (a canonical agent role under .agents/agents may declare a top-level version: instead)';
+async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changedVersionedFiles, findings, dependencies) {
+    for (const entry of changedVersionedFiles) {
+        const relativeSkillPath = entry.file;
         const skillPath = join(repoRoot, relativeSkillPath);
         const currentContent = await readFile(skillPath, 'utf8');
         const baseContent = await readFileAtGitRef(repoRoot, baseRef, relativeSkillPath, dependencies);
-        if (baseContent === null || baseContent === currentContent) {
+        if (baseContent === null) {
+            continue;
+        }
+        // Identical bytes are skipped only when the owning file is the *whole* of
+        // what changed — a rename or mode change, which the original skip was
+        // written for. When a sibling under the skill directory changed, identical
+        // `SKILL.md` bytes are exactly the failure to report: the bundled skill
+        // shipped new content under an unchanged version.
+        if (baseContent === currentContent &&
+            entry.changedPaths.length === 1 &&
+            entry.changedPaths[0] === relativeSkillPath) {
             continue;
         }
+        // Falsy, not `=== null`: `getFrontmatterBlock` returns `""` for an empty
+        // `---` / `---` pair and `null` only when there is no pair at all. Both
+        // declare nothing, and the pre-existing `oat-*` structural loop already
+        // treats them alike, so matching it here keeps one file to one diagnosis.
         const currentBlock = getFrontmatterBlock(currentContent);
-        const parsedCurrent = currentBlock === null ? null : parseSkillFrontmatter(currentBlock);
+        const parsedCurrent = currentBlock
+            ? parseSkillFrontmatter(currentBlock)
+            : null;
         const baseBlock = getFrontmatterBlock(baseContent);
-        const parsedBase = baseBlock === null ? null : parseSkillFrontmatter(baseBlock);
-        // Frontmatter that carries no readable version must never fall through to
-        // the `continue` below: a value the resolver cannot read would otherwise
-        // disable bump enforcement for that skill entirely. Both sides are
-        // guarded, because either one being uncomparable defeats the comparison.
+        const parsedBase = baseBlock ? parseSkillFrontmatter(baseBlock) : null;
+        // Every state that leaves this collector without a version comparison now
+        // reports. The closed set is: malformed frontmatter, an unusable version
+        // declaration, a version conflict, no frontmatter block at all, and
+        // frontmatter that declares no version anywhere — on either side. Nothing
+        // reaches a silent `continue`, because "no version found, so skip" is the
+        // state that let a changed file pass the version contract by omission.
+        //
+        // The guards below run in a fixed order and the four uncomparable-state
+        // guards and the two conflict guards come first, so their specific
+        // diagnoses are never masked by the generic missing-block or
+        // missing-version message added at the tail. Both sides are guarded,
+        // because either one being uncomparable defeats the comparison.
         // `validateOatSkills` runs the structural version-source pass before this
         // collector, so the same file can already carry the current-side finding.
         if (parsedCurrent?.malformed) {
@@ -686,10 +900,11 @@ async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changed
         const resolvedCurrent = parsedCurrent === null ? null : resolveSkillVersion(parsedCurrent);
         const resolvedBase = parsedBase === null ? null : resolveSkillVersion(parsedBase);
         // A conflicting skill has no resolvable version, so it cannot be bump
-        // checked. This is the only version-source finding the bump validator
-        // emits: `validate-skill-version-bumps.ts` fails the gate on any finding
-        // regardless of severity, so the top-level alias deprecation warning stays
-        // in structural validation and never reaches this result.
+        // checked. `validate-skill-version-bumps.ts` fails the gate on any finding
+        // regardless of severity, so the one version-source finding deliberately
+        // kept out of this collector is the top-level alias — an error since step
+        // 1 of the retirement schedule — which stays in structural validation and
+        // never reaches this result.
         if (resolvedCurrent?.conflict) {
             findings.push(versionConflictFinding(skillPath, resolvedCurrent.conflict));
             continue;
@@ -703,13 +918,32 @@ async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changed
         }
         const currentVersion = resolvedCurrent?.version ?? null;
         const baseVersion = resolvedBase?.version ?? null;
-        if (!currentVersion || !baseVersion) {
+        // The current-state defects come before the base-side comparison problems,
+        // matching the order the guards above already use, and both come after
+        // every specific diagnosis so neither can mask one.
+        if (!currentBlock) {
+            if (!hasMissingFrontmatterReport(findings, skillPath)) {
+                pushUniqueFinding(findings, missingFrontmatterFinding(skillPath));
+            }
+            continue;
+        }
+        if (!currentVersion) {
+            pushUniqueFinding(findings, missingVersionFinding(skillPath));
             continue;
         }
+        if (!baseBlock) {
+            findings.push(uncomparableBaseFinding(skillPath, baseRef, 'missing-frontmatter'));
+            continue;
+        }
+        if (!baseVersion) {
+            findings.push(uncomparableBaseFinding(skillPath, baseRef, 'missing-version'));
+            continue;
+        }
+        const changedSuffix = changedSiblingSuffix(entry);
         if (currentVersion === baseVersion) {
             findings.push({
                 file: skillPath,
-                message: `Changed canonical skill must bump frontmatter version relative to ${baseRef} (still ${currentVersion})`,
+                message: `Changed canonical skill or agent role must bump its version relative to ${baseRef} (still ${currentVersion})${changedSuffix}; ${VERSION_DECLARATION_HINT}`,
             });
             continue;
         }
@@ -718,17 +952,19 @@ async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changed
             compareSemver(currentVersion, baseVersion) <= 0) {
             findings.push({
                 file: skillPath,
-                message: `Changed canonical skill version must increase relative to ${baseRef} (base ${baseVersion}, current ${currentVersion})`,
+                message: `Changed canonical skill or agent role version must increase relative to ${baseRef} (base ${baseVersion}, current ${currentVersion})${changedSuffix}; ${VERSION_DECLARATION_HINT}`,
             });
         }
     }
 }
 export async function validateChangedSkillVersionBumps(repoRoot, options, dependencies = {}) {
     const findings = [];
-    const changedSkillFiles = await listChangedSkillFiles(repoRoot, options.baseRef, dependencies);
-    await collectChangedSkillVersionBumpFindings(repoRoot, options.baseRef, changedSkillFiles, findings, dependencies);
+    const changedVersionedFiles = await listChangedVersionedFiles(repoRoot, options.baseRef, dependencies);
+    await collectChangedSkillVersionBumpFindings(repoRoot, options.baseRef, changedVersionedFiles, findings, dependencies);
     return {
-        validatedSkillCount: changedSkillFiles.length,
+        // The count is owning files, not diffed paths: a skill whose `scripts/`
+        // and `references/` both changed is one file that must bump.
+        validatedSkillCount: changedVersionedFiles.length,
         findings,
     };
 }
@@ -738,10 +974,28 @@ export async function validateChangedSkillVersionBumps(repoRoot, options, depend
  * This pass deliberately iterates every skill directory, not just `oat-*`:
  * the top-level `version` alias is deprecated across the whole bundle, so a
  * pass that inherited the `oat-*` filter used by the other structural checks
- * could never fire for the 18 non-`oat-*` skills. `skill-version-alias` is a
- * warning (`validate-oat-skills.ts` treats warnings as non-blocking) and
- * `skill-version-conflict` is an error. Neither finding is produced by the
- * bump validator, whose wrapper fails on any finding at all.
+ * could never fire for the 18 non-`oat-*` skills.
+ *
+ * `skill-version-alias` is an **error**. That is step 1 of the retirement
+ * schedule fixed by `DR-260908-bundled-skills-declare`: the deprecated
+ * top-level alias becomes blocking in the first validator-changing release
+ * after CLI 0.2.65 (0.2.66 shipped without one). The promotion was safe to
+ * make because the bundled tree was verified clean immediately before it —
+ * `oat internal validate-oat-skills` returned 65 skills and zero findings — so
+ * no bundled skill trips it. A corpus case in `skills.test.ts` keeps that
+ * true. Step 2, removing the top-level read from
+ * `resolveSkillVersion`, is owned by `BL-260908-remove-the-top-level-skill`,
+ * must land a release later, and must not be done here: the bump gate now
+ * enforces `.agents/agents/*.md`, whose roles still declare the top-level
+ * field by design.
+ *
+ * `skill-version-alias` is never produced by the bump validator, whose wrapper
+ * fails on any finding at all regardless of severity. That separation is what
+ * keeps a third-party skill that still declares the alias from failing
+ * `check:skill-bumps` for a reason unrelated to bumping, and the promotion
+ * above does not change it. `skill-version-conflict` is not isolated that way:
+ * the bump collector emits it for a current or base conflict, because a
+ * conflicting file has no single version to compare.
  */
 async function collectSkillVersionSourceFindings(skillsRoot, skillDirs, findings) {
     for (const dir of skillDirs) {
@@ -756,7 +1010,14 @@ async function collectSkillVersionSourceFindings(skillsRoot, skillDirs, findings
             continue;
         }
         const block = getFrontmatterBlock(content);
-        if (block === null) {
+        if (!block) {
+            // The `oat-*` structural loop above already reports a missing block with
+            // its own wording, so only skills it does not cover are reported here.
+            // Without this, a non-`oat-*` skill could drop its frontmatter and be
+            // reported by neither validator.
+            if (!hasMissingFrontmatterReport(findings, skillPath)) {
+                pushUniqueFinding(findings, missingFrontmatterFinding(skillPath));
+            }
             continue;
         }
         const parsed = parseSkillFrontmatter(block);
@@ -777,6 +1038,10 @@ async function collectSkillVersionSourceFindings(skillsRoot, skillDirs, findings
         }
         const resolved = resolveSkillVersion(parsed);
         if (!resolved) {
+            // Readable frontmatter that declares no version at all — a `metadata:`
+            // map with no `version` child is the common shape. Skipping it silently
+            // disabled the semver check and bump enforcement for that skill.
+            pushUniqueFinding(findings, missingVersionFinding(skillPath));
             continue;
         }
         if (resolved.conflict) {
@@ -787,7 +1052,7 @@ async function collectSkillVersionSourceFindings(skillsRoot, skillDirs, findings
             findings.push({
                 file: skillPath,
                 code: 'skill-version-alias',
-                severity: 'warning',
+                severity: 'error',
                 message: `Frontmatter version ${resolved.version} uses the deprecated top-level alias; move it to metadata.version (metadata.version wins when both are present)`,
             });
         }
@@ -819,7 +1084,7 @@ export async function validateOatSkills(repoRoot, options = {}, dependencies = {
         if (!fm) {
             findings.push({
                 file: skillPath,
-                message: 'Missing frontmatter block (--- ... ---)',
+                message: MISSING_FRONTMATTER_BLOCK_MESSAGE,
             });
             continue;
         }
@@ -897,8 +1162,8 @@ export async function validateOatSkills(repoRoot, options = {}, dependencies = {
     await collectSyncedSafetyFindings(repoRoot, oatSkillDirs, findings);
     await collectGateabilityFindings(skillsRoot, options.gateSkillNames, findings);
     if (options.baseRef) {
-        const changedSkillFiles = await listChangedSkillFiles(repoRoot, options.baseRef, dependencies);
-        await collectChangedSkillVersionBumpFindings(repoRoot, options.baseRef, changedSkillFiles, findings, dependencies);
+        const changedVersionedFiles = await listChangedVersionedFiles(repoRoot, options.baseRef, dependencies);
+        await collectChangedSkillVersionBumpFindings(repoRoot, options.baseRef, changedVersionedFiles, findings, dependencies);
     }
     return { validatedSkillCount: oatSkillDirs.length, findings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.66",
+  "version": "0.2.68",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.66"
+    "@open-agent-toolkit/control-plane": "0.2.68"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",