@open-agent-toolkit/cli 0.2.63 → 0.2.65

package/dist/drift/skill-view-diagnostic.js

@@ -0,0 +1,343 @@
+import { join } from 'node:path';
+const CANONICAL_SKILL_DIR = join('.agents', 'skills');
+function skillMappingFor(registration, scope) {
+    const mappings = scope === 'project'
+        ? registration.adapter.projectMappings
+        : registration.adapter.userMappings;
+    return mappings.find(({ contentType }) => contentType === 'skill');
+}
+/**
+ * Builds the expected provider path for one canonical skill, per registered
+ * adapter that maps skills in this scope.
+ *
+ * Mirrors the engine's own derivation (`providerDir` + entry name in
+ * `computeSyncPlan`). A canonical skill is a directory, and the engine applies
+ * `providerExtension` only to file entries, so the directory name is carried
+ * through unchanged.
+ *
+ * `allowedCanonicalPaths` mirrors `computeSyncPlan`'s filter of the same name:
+ * a targeted sync narrows the plan to specific canonical paths. No durable
+ * config excludes a canonical skill today, so the `oat tools info` wiring
+ * passes nothing; the parameter exists so that a filtered projection is
+ * reported as `excluded` rather than as a projection gap.
+ */
+export function resolveExpectedSkillProjections(input) {
+    const canonicalPath = join(CANONICAL_SKILL_DIR, input.skillName);
+    const excluded = input.allowedCanonicalPaths !== undefined &&
+        !input.allowedCanonicalPaths.includes(canonicalPath);
+    const projections = [];
+    for (const registration of input.registrations) {
+        const mapping = skillMappingFor(registration, input.scope);
+        if (!mapping)
+            continue;
+        projections.push({
+            provider: registration.adapter.name,
+            providerPath: join(mapping.providerDir, input.skillName),
+            contentKind: 'skill',
+            nativeRead: mapping.nativeRead,
+            ...(excluded
+                ? {
+                    excludedReason: `targeted sync filter does not include ${canonicalPath}`,
+                }
+                : {}),
+        });
+    }
+    return projections;
+}
+function driftReasonText(state) {
+    return state.status === 'drifted' ? state.reason : state.status;
+}
+function versionNote(strategy) {
+    if (strategy === 'symlink') {
+        return ' The view is a symlink to the canonical file, so it has no separate version.';
+    }
+    if (strategy === 'collection') {
+        return ' The view is inherited from a collection alias, so it has no separate version.';
+    }
+    return '';
+}
+/** Names a version declaration the resolver could not take at face value. */
+function projectedVersionNote(projected, withheld) {
+    if (!projected)
+        return '';
+    if (projected.state === 'conflict' && projected.conflict) {
+        const declaration = `The projected SKILL.md declares metadata.version ${projected.conflict.metadata} and top-level version ${projected.conflict.topLevel}; reconcile the two fields.`;
+        // The resolver is deterministic — it takes `metadata.version` — so a
+        // conflicting copy can genuinely be stale. When the comparison is
+        // withheld, say the check was skipped rather than implying the view is
+        // fine; when the resolved value agrees with canonical, nothing was
+        // withheld and claiming otherwise would be its own falsehood.
+        return withheld
+            ? ` ${declaration} A self-contradicting declaration is not usable as evidence, so the version comparison was skipped: a real difference from canonical would not be reported here.`
+            : ` ${declaration} The shared resolver takes metadata.version, which is the version compared above.`;
+    }
+    if (projected.state === 'unusable') {
+        return ' The projected SKILL.md declares a version that cannot be read, so no version comparison is made.';
+    }
+    if (projected.state === 'malformed') {
+        return ' The projected SKILL.md frontmatter does not parse, so no version comparison is made.';
+    }
+    return '';
+}
+/**
+ * Says which path this row is really about when the manifest disagrees with the
+ * adapter.
+ *
+ * The manifest is keyed by `(canonicalPath, provider)` and never by path, so an
+ * entry can point somewhere other than the adapter's expected projection while a
+ * healthy file sits at the expected path — reachable after a `providerDir`
+ * change or from a manifest written under an older layout. Attaching the drift
+ * verdict for the tracked path to a row labelled with the expected path made the
+ * row state something false about a file that exists, so the row names the
+ * tracked path and this note says what the expected path looks like instead.
+ */
+function divergentPathNote(observation) {
+    const tracked = observation.manifestEntry?.providerPath;
+    if (tracked === undefined ||
+        tracked === observation.projection.providerPath) {
+        return '';
+    }
+    // `viewPresent` is only evidence when the observation succeeded: a failed
+    // read leaves it at its default, and reporting that default as absence would
+    // replace one false claim about the expected path with another.
+    const expectedPathNote = observation.unavailableReason !== undefined
+        ? 'Whether anything exists at the expected path was not established.'
+        : observation.viewPresent
+            ? 'Something does exist at the expected path, and this row says nothing about it.'
+            : 'Nothing exists at the expected path either.';
+    return ` The manifest tracks this view at ${tracked}, which is not the expected projection path ${observation.projection.providerPath}; the state, path, and version above all describe the tracked path. ${expectedPathNote} Syncing this scope re-projects the skill to the expected path.`;
+}
+function classify(observation, isActive) {
+    const { projection, manifestEntry, drift, viewPresent } = observation;
+    if (!isActive) {
+        return {
+            viewClass: 'inactive',
+            detail: 'Provider is not active in this scope, so nothing is projected.',
+        };
+    }
+    if (observation.unavailableReason !== undefined) {
+        // `unverified` is the honest class: a read failure is not evidence of a
+        // projection gap, and reporting one as `missing-additive` or `removed`
+        // would send the user to a sync that fixes nothing.
+        return {
+            viewClass: 'unverified',
+            detail: `The diagnostic could not read this view, so its state is unverified: ${observation.unavailableReason}`,
+        };
+    }
+    if (projection.excludedReason !== undefined) {
+        return {
+            viewClass: 'excluded',
+            detail: `Excluded from this scope's projection: ${projection.excludedReason}.`,
+        };
+    }
+    if (projection.nativeRead) {
+        return {
+            viewClass: 'in-sync',
+            detail: 'Provider reads the canonical skill in place; there is no separate view to sync or version to compare.',
+        };
+    }
+    if (!manifestEntry) {
+        if (viewPresent) {
+            return {
+                viewClass: 'untracked',
+                detail: 'An untracked file occupies the expected path. Stray detection skips provider entries whose name matches a canonical entry, so "oat status" does not report it as a stray; it reports the untracked projection as missing instead. Inspect the path and remove it if it is not wanted, then sync the scope; no repair is suggested here because a sync could overwrite content OAT does not own.',
+            };
+        }
+        return {
+            viewClass: 'missing-additive',
+            detail: 'Canonical skill has never been projected to this view: no manifest entry and nothing at the expected path.',
+        };
+    }
+    if (!drift) {
+        // A tracked entry must never be labelled `untracked`: the same record
+        // reports `tracked: true`, and the two together are self-contradictory.
+        return {
+            viewClass: 'unverified',
+            detail: 'A manifest entry tracks this view but no drift observation accompanied it, so its state is unverified.',
+        };
+    }
+    if (drift.state.status === 'missing') {
+        return {
+            viewClass: 'removed',
+            detail: 'The manifest tracks this view but the provider file is gone from disk.',
+        };
+    }
+    if (drift.state.status === 'drifted') {
+        return {
+            viewClass: 'modified',
+            detail: `The tracked view diverged from the canonical skill (${driftReasonText(drift.state)}).`,
+        };
+    }
+    if (drift.state.status === 'in_sync') {
+        return {
+            viewClass: 'in-sync',
+            // A copy is only known to match the content recorded at its last sync:
+            // `detectDrift` compares it against the manifest hash, so a canonical
+            // edit that was never re-synced leaves both sides agreeing. Say exactly
+            // that rather than claiming canonical equality the check cannot support.
+            detail: manifestEntry.strategy === 'copy'
+                ? 'The tracked copy still matches the content recorded at its last sync; a canonical edit that was never re-synced is not visible in the manifest hash.'
+                : 'The tracked view matches the canonical skill.',
+        };
+    }
+    // `detectDrift` never returns `stray` for a keyed entry; treat any such
+    // report as unmanaged rather than inventing a projection gap.
+    return {
+        viewClass: 'untracked',
+        detail: 'The provider file is reported as an unmanaged stray.',
+    };
+}
+const REPAIRABLE = [
+    'missing-additive',
+    'removed',
+    'modified',
+];
+/**
+ * Maps one canonical skill onto one diagnostic per registered provider for a
+ * single concrete scope. Pure: every filesystem, manifest, and drift fact is
+ * supplied by the caller.
+ */
+export function diagnoseSkillViews(input) {
+    if (!input.canonicalPresent) {
+        return {
+            skill: input.skillName,
+            scope: input.scope,
+            result: 'unknown-skill',
+            views: [],
+        };
+    }
+    const active = new Set(input.providerScopeContext.activeProviders);
+    const byProvider = new Map(input.observations.map((observation) => [
+        observation.projection.provider,
+        observation,
+    ]));
+    const views = [];
+    for (const registration of input.providerScopeContext.registrations) {
+        const provider = registration.adapter.name;
+        const observation = byProvider.get(provider);
+        if (!observation) {
+            views.push({
+                skill: input.skillName,
+                scope: input.scope,
+                provider,
+                viewClass: 'unsupported',
+                driftState: null,
+                providerPath: null,
+                tracked: false,
+                strategy: null,
+                nativeRead: false,
+                canonicalVersion: input.canonicalVersion,
+                viewVersion: null,
+                versionComparable: false,
+                suggestion: null,
+                detail: `Provider has no ${input.scope} skill mapping, so no view is expected.`,
+            });
+            continue;
+        }
+        const isActive = active.has(provider);
+        const classification = classify(observation, isActive);
+        const strategy = observation.manifestEntry?.strategy ?? null;
+        const nativeRead = observation.projection.nativeRead;
+        // A drift verdict computed for the manifest's path may only appear on a row
+        // that names that path. The divergence is reported wherever the manifest
+        // entry is what drives the row: an inactive, excluded, or natively read
+        // provider has no drift verdict to misattribute.
+        const trackedPath = observation.manifestEntry?.providerPath;
+        const pathDiverges = trackedPath !== undefined &&
+            trackedPath !== observation.projection.providerPath &&
+            isActive &&
+            !nativeRead &&
+            observation.projection.excludedReason === undefined;
+        const copyViewReadable = strategy === 'copy' &&
+            !nativeRead &&
+            (classification.viewClass === 'modified' ||
+                classification.viewClass === 'in-sync');
+        const projected = observation.projectedVersion;
+        const resolvedViewVersion = copyViewReadable
+            ? (projected?.version ?? null)
+            : null;
+        const versionState = projected?.state ?? 'absent';
+        // A declaration the resolver could not read, or one that contradicts
+        // itself while disagreeing with canonical, is not usable as evidence of
+        // divergence. Report no comparable version instead of a stale claim.
+        const untrustworthyVersion = versionState === 'unusable' ||
+            versionState === 'malformed' ||
+            (versionState === 'conflict' &&
+                resolvedViewVersion !== input.canonicalVersion);
+        const viewVersion = untrustworthyVersion ? null : resolvedViewVersion;
+        const versionComparable = copyViewReadable && viewVersion !== null;
+        // `detectDrift` compares a copy against the hash recorded at the last
+        // sync, so a copy that was never re-synced after a canonical edit matches
+        // its own manifest entry and reads as `in_sync`. Two different versions
+        // are proof the view is not the canonical content, whatever the manifest
+        // agrees with. `driftState` still reports exactly what the detector said.
+        const staleCopy = versionComparable &&
+            versionState === 'resolved' &&
+            classification.viewClass === 'in-sync' &&
+            input.canonicalVersion !== null &&
+            viewVersion !== null &&
+            viewVersion !== input.canonicalVersion;
+        // The mirror case: the detector reports a copy as drifted while its
+        // version matches canonical. That is the expected state after a
+        // copy-strategy sync, because the OAT-managed banner and `.oat-generated`
+        // sentinel are not accounted for in the manifest hash
+        // (BL-260908-make-copy-strategy-skill), and no sync clears it.
+        //
+        // Suppressing the repair here is a conservative heuristic, not a proof:
+        // equal versions do not establish equal bodies, so an edit to either side
+        // that kept the version reaches this branch too, and a sync would fix
+        // that one. The detail therefore says which case it cannot distinguish
+        // and names the concrete scope command, rather than claiming the content
+        // is current.
+        const unrepairableCopy = versionComparable &&
+            classification.viewClass === 'modified' &&
+            input.canonicalVersion !== null &&
+            viewVersion === input.canonicalVersion;
+        const { viewClass, detail } = staleCopy
+            ? {
+                viewClass: 'modified',
+                detail: `The tracked copy still matches the hash recorded at its last sync, but its version (${viewVersion}) differs from the canonical version (${input.canonicalVersion}), so the view is stale.`,
+            }
+            : unrepairableCopy
+                ? {
+                    viewClass: 'modified',
+                    detail: `The detector reports this copy as drifted while its version still matches canonical (${input.canonicalVersion}). That is expected after a copy-strategy sync until BL-260908-make-copy-strategy-skill lands: the OAT-managed banner and ".oat-generated" sentinel are not accounted for in the manifest hash, and no sync clears it. Equal versions do not prove the bodies match, so if either side was edited without a version change, compare them and run "oat sync --scope ${input.scope}" yourself.`,
+                }
+                : classification;
+        views.push({
+            skill: input.skillName,
+            scope: input.scope,
+            provider,
+            viewClass,
+            driftState: observation.drift?.state ?? null,
+            providerPath: pathDiverges
+                ? trackedPath
+                : observation.projection.providerPath,
+            ...(pathDiverges
+                ? { expectedProviderPath: observation.projection.providerPath }
+                : {}),
+            tracked: observation.manifestEntry !== null,
+            strategy,
+            nativeRead,
+            canonicalVersion: input.canonicalVersion,
+            viewVersion,
+            versionComparable,
+            ...(copyViewReadable ? { versionEvidence: versionState } : {}),
+            // The narrowest safe repair is the single concrete scope where the gap
+            // was observed. `--scope all` would widen a one-scope repair into a
+            // two-scope write.
+            suggestion: REPAIRABLE.includes(viewClass) && !unrepairableCopy
+                ? `oat sync --scope ${input.scope}`
+                : null,
+            detail: `${versionComparable ? detail : `${detail}${versionNote(strategy)}`}${copyViewReadable
+                ? projectedVersionNote(projected, untrustworthyVersion)
+                : ''}${pathDiverges ? divergentPathNote(observation) : ''}`,
+        });
+    }
+    return {
+        skill: input.skillName,
+        scope: input.scope,
+        result: 'diagnosed',
+        views,
+    };
+}

package/dist/validation/skills.d.ts

@@ -2,6 +2,7 @@ export interface ValidationFinding {
     file: string;
     message: string;
     severity?: 'error' | 'warning';
+    code?: string;
 }
 export interface ValidateOatSkillsResult {
     validatedSkillCount: number;

package/dist/validation/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/validation/skills.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,uCAAuC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sCAAsC;IACrD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,KAChD,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,UAAU,6BAA6B;IACrC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AA04BD,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uCAAuC,EAChD,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,sCAAsC,CAAC,CAoBjD;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,wBAA6B,EACtC,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,CAqIlC"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/validation/skills.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,uCAAuC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sCAAsC;IACrD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,KAChD,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7B,UAAU,6BAA6B;IACrC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAwhCD,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uCAAuC,EAChD,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,sCAAsC,CAAC,CAoBjD;AAyED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,wBAA6B,EACtC,YAAY,GAAE,6BAAkC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,CAyIlC"}

package/dist/validation/skills.js

@@ -2,7 +2,7 @@ import { execFile as execFileCallback } from 'node:child_process';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
-import { getFrontmatterBlock } from '../commands/shared/frontmatter.js';
+import { getFrontmatterBlock, parseSkillFrontmatter, resolveSkillVersion, } from '../commands/shared/frontmatter.js';
 const execFileAsync = promisify(execFileCallback);
 async function isDirectory(path) {
     try {
@@ -459,6 +459,66 @@ function hasTrueFrontmatterValue(frontmatter, key) {
     return (frontmatterHasKey(frontmatter, key) &&
         getFrontmatterScalar(frontmatter, key) === 'true');
 }
+function unreadableFrontmatterFinding(file) {
+    return {
+        file,
+        code: 'skill-frontmatter-unreadable',
+        severity: 'error',
+        message: 'Frontmatter must be a valid YAML mapping with unique keys (version could not be read)',
+    };
+}
+function pushUniqueFinding(findings, finding) {
+    const duplicate = findings.some((existing) => existing.file === finding.file &&
+        existing.code === finding.code &&
+        existing.message === finding.message);
+    if (!duplicate) {
+        findings.push(finding);
+    }
+}
+/**
+ * A `version` key is present but carries no usable value (empty, or a
+ * non-string scalar such as `1.10`, which YAML reads as the number 1.1).
+ *
+ * This is reported rather than skipped: the value the author wrote is a
+ * version OAT cannot read, and letting it resolve to nothing would silently
+ * disable both the semver check and bump enforcement for that skill.
+ */
+function unusableVersionFinding(file) {
+    return {
+        file,
+        code: 'skill-version-unusable',
+        severity: 'error',
+        message: 'Frontmatter declares a version that cannot be read; use a quoted semver string (unquoted, version: 1.10 is the number 1.1)',
+    };
+}
+function uncomparableBaseFinding(file, baseRef, reason) {
+    return {
+        file,
+        code: reason === 'unreadable'
+            ? 'skill-frontmatter-unreadable'
+            : 'skill-version-unusable',
+        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`,
+    };
+}
+function uncomparableBaseConflictFinding(file, baseRef, conflict) {
+    return {
+        file,
+        code: 'skill-version-conflict',
+        severity: 'error',
+        message: `Changed canonical skill cannot be version-checked against ${baseRef}: the base frontmatter metadata.version (${conflict.metadata}) and top-level version (${conflict.topLevel}) differ`,
+    };
+}
+function versionConflictFinding(file, conflict) {
+    return {
+        file,
+        code: 'skill-version-conflict',
+        severity: 'error',
+        message: `Frontmatter metadata.version (${conflict.metadata}) and top-level version (${conflict.topLevel}) differ; a conflicting skill has no resolvable version`,
+    };
+}
 function isValidSemver(value) {
     return /^\d+\.\d+\.\d+$/.test(value);
 }
@@ -597,14 +657,52 @@ async function collectChangedSkillVersionBumpFindings(repoRoot, baseRef, changed
         if (baseContent === null || baseContent === currentContent) {
             continue;
         }
-        const currentFrontmatter = getFrontmatterBlock(currentContent);
-        const baseFrontmatter = getFrontmatterBlock(baseContent);
-        const currentVersion = currentFrontmatter
-            ? getFrontmatterScalar(currentFrontmatter, 'version')
-            : null;
-        const baseVersion = baseFrontmatter
-            ? getFrontmatterScalar(baseFrontmatter, 'version')
-            : null;
+        const currentBlock = getFrontmatterBlock(currentContent);
+        const parsedCurrent = currentBlock === null ? null : parseSkillFrontmatter(currentBlock);
+        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.
+        // `validateOatSkills` runs the structural version-source pass before this
+        // collector, so the same file can already carry the current-side finding.
+        if (parsedCurrent?.malformed) {
+            pushUniqueFinding(findings, unreadableFrontmatterFinding(skillPath));
+            continue;
+        }
+        if (parsedCurrent?.unusableVersionDeclaration) {
+            pushUniqueFinding(findings, unusableVersionFinding(skillPath));
+            continue;
+        }
+        if (parsedBase?.malformed) {
+            findings.push(uncomparableBaseFinding(skillPath, baseRef, 'unreadable'));
+            continue;
+        }
+        if (parsedBase?.unusableVersionDeclaration) {
+            findings.push(uncomparableBaseFinding(skillPath, baseRef, 'unusable'));
+            continue;
+        }
+        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.
+        if (resolvedCurrent?.conflict) {
+            findings.push(versionConflictFinding(skillPath, resolvedCurrent.conflict));
+            continue;
+        }
+        // A conflicting base has no single version to compare against either:
+        // silently taking its metadata side would accept a downgrade relative to
+        // the top-level version the base also declares.
+        if (resolvedBase?.conflict) {
+            findings.push(uncomparableBaseConflictFinding(skillPath, baseRef, resolvedBase.conflict));
+            continue;
+        }
+        const currentVersion = resolvedCurrent?.version ?? null;
+        const baseVersion = resolvedBase?.version ?? null;
         if (!currentVersion || !baseVersion) {
             continue;
         }
@@ -634,6 +732,67 @@ export async function validateChangedSkillVersionBumps(repoRoot, options, depend
         findings,
     };
 }
+/**
+ * Report where each bundled skill keeps its version.
+ *
+ * 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.
+ */
+async function collectSkillVersionSourceFindings(skillsRoot, skillDirs, findings) {
+    for (const dir of skillDirs) {
+        const skillPath = join(skillsRoot, dir, 'SKILL.md');
+        let content;
+        try {
+            content = await readFile(skillPath, 'utf8');
+        }
+        catch {
+            // A missing SKILL.md is reported by the structural pass for oat-*
+            // skills and is not this pass's concern.
+            continue;
+        }
+        const block = getFrontmatterBlock(content);
+        if (block === null) {
+            continue;
+        }
+        const parsed = parseSkillFrontmatter(block);
+        if (parsed.malformed) {
+            // Reported for every skill, not just `oat-*` ones: unreadable
+            // frontmatter is exactly the state that would otherwise make a version
+            // silently unreadable everywhere.
+            findings.push(unreadableFrontmatterFinding(skillPath));
+            continue;
+        }
+        // Declaration usability is checked here, before the unresolved bail, so it
+        // covers every bundled skill. Inside the `oat-*` loop it could never fire
+        // for the 18 skills that are not named `oat-*`, which is how an unusable
+        // declaration became invisible to validation.
+        if (parsed.unusableVersionDeclaration) {
+            findings.push(unusableVersionFinding(skillPath));
+            continue;
+        }
+        const resolved = resolveSkillVersion(parsed);
+        if (!resolved) {
+            continue;
+        }
+        if (resolved.conflict) {
+            findings.push(versionConflictFinding(skillPath, resolved.conflict));
+            continue;
+        }
+        if (resolved.source === 'top-level') {
+            findings.push({
+                file: skillPath,
+                code: 'skill-version-alias',
+                severity: 'warning',
+                message: `Frontmatter version ${resolved.version} uses the deprecated top-level alias; move it to metadata.version (metadata.version wins when both are present)`,
+            });
+        }
+    }
+}
 export async function validateOatSkills(repoRoot, options = {}, dependencies = {}) {
     const skillsRoot = join(repoRoot, '.agents', 'skills');
     const findings = [];
@@ -641,10 +800,11 @@ export async function validateOatSkills(repoRoot, options = {}, dependencies = {
         throw new Error(`skills directory not found: ${skillsRoot}`);
     }
     const entries = await readdir(skillsRoot, { withFileTypes: true });
-    const oatSkillDirs = entries
-        .filter((entry) => entry.isDirectory() && entry.name.startsWith('oat-'))
+    const allSkillDirs = entries
+        .filter((entry) => entry.isDirectory())
         .map((entry) => entry.name)
         .sort();
+    const oatSkillDirs = allSkillDirs.filter((name) => name.startsWith('oat-'));
     for (const dir of oatSkillDirs) {
         const skillPath = join(skillsRoot, dir, 'SKILL.md');
         let content;
@@ -707,14 +867,15 @@ export async function validateOatSkills(repoRoot, options = {}, dependencies = {
                 }
             }
         }
-        if (frontmatterHasKey(fm, 'version')) {
-            const version = getFrontmatterScalar(fm, 'version') ?? '';
-            if (!isValidSemver(version)) {
-                findings.push({
-                    file: skillPath,
-                    message: 'Frontmatter version must be valid semver (e.g., 1.0.0)',
-                });
-            }
+        // Malformed frontmatter and unusable version declarations are reported
+        // once, for every skill, by collectSkillVersionSourceFindings; this is the
+        // `oat-*` structural rule for a version that does resolve.
+        const resolvedVersion = resolveSkillVersion(parseSkillFrontmatter(fm));
+        if (resolvedVersion !== null && !isValidSemver(resolvedVersion.version)) {
+            findings.push({
+                file: skillPath,
+                message: 'Frontmatter version must be valid semver (e.g., 1.0.0)',
+            });
         }
         if (!hasProgressIndicatorsSection(content)) {
             findings.push({
@@ -732,6 +893,7 @@ export async function validateOatSkills(repoRoot, options = {}, dependencies = {
             validateQuickStartSemantics(skillPath, content, findings);
         }
     }
+    await collectSkillVersionSourceFindings(skillsRoot, allSkillDirs, findings);
     await collectSyncedSafetyFindings(repoRoot, oatSkillDirs, findings);
     await collectGateabilityFindings(skillsRoot, options.gateSkillNames, findings);
     if (options.baseRef) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "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.63"
+    "@open-agent-toolkit/control-plane": "0.2.65"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",