npm - commandmate - Versions diffs - 0.15.0 → 0.16.0 - Mend

commandmate 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (537) hide show

package/dist/server/src/lib/db/migrations/v48-skill-operations-audit-index.js ADDED Viewed

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Migration v48: audit version transition and feed indexes (Issue #1248).
+ *
+ * Two things the applied-state dashboard needs that v44 does not provide.
+ *
+ * **`from_version` / `to_version`.** v44 records a single `skill_version`, which
+ * answers "what version was this operation about" but not "what replaced what".
+ * An update is exactly a transition, and reading one out of two adjacent audit
+ * rows is guesswork the log should not require. Both columns are nullable
+ * because the ends of the timeline are genuinely open: an install onto an empty
+ * target has no `from`, an uninstall has no `to`.
+ *
+ * **Feed indexes.** The existing `idx_skill_operations_target` leads with
+ * `worktree_id`, so it cannot serve the dashboard's cross-worktree "newest
+ * first" query, and the "show me only the failures" filter has no index at all.
+ * Both are added here rather than left to a full scan that grows with history —
+ * the table is append-only, so it only ever gets longer.
+ *
+ * `ALTER TABLE ... ADD COLUMN` is DDL and does not fire the v44 append-only
+ * triggers, so existing rows are preserved and read back with NULL transitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v48_migrations = void 0;
+exports.v48_migrations = [
+    {
+        version: 48,
+        name: 'add-skill-operations-audit-index',
+        up: (db) => {
+            db.exec('ALTER TABLE skill_operations ADD COLUMN from_version TEXT;');
+            db.exec('ALTER TABLE skill_operations ADD COLUMN to_version TEXT;');
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_skill_operations_recent
+          ON skill_operations(recorded_at DESC, id DESC);
+      `);
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_skill_operations_result
+          ON skill_operations(result, recorded_at DESC);
+      `);
+        },
+        down: (db) => {
+            db.exec('DROP INDEX IF EXISTS idx_skill_operations_result;');
+            db.exec('DROP INDEX IF EXISTS idx_skill_operations_recent;');
+            // SQLite < 3.35 cannot DROP COLUMN; rebuild without the two columns. The
+            // append-only triggers are recreated afterwards: DROP TABLE removes the
+            // triggers bound to the old table, and a log without them is not the log.
+            db.exec('DROP TRIGGER IF EXISTS skill_operations_no_delete;');
+            db.exec('DROP TRIGGER IF EXISTS skill_operations_no_update;');
+            db.exec(`
+        CREATE TABLE skill_operations__v47 (
+          id TEXT PRIMARY KEY,
+          operation_id TEXT NOT NULL,
+          idempotency_key TEXT NOT NULL,
+          binding_hash TEXT NOT NULL,
+          operation TEXT NOT NULL,
+          state TEXT NOT NULL,
+          result TEXT NOT NULL,
+          actor_type TEXT NOT NULL,
+          actor_id TEXT,
+          worktree_id TEXT NOT NULL,
+          skill_id TEXT NOT NULL,
+          skill_version TEXT,
+          source_origin TEXT,
+          source_repository TEXT,
+          source_ref TEXT,
+          source_commit TEXT,
+          artifact_sha256 TEXT,
+          error_code TEXT,
+          error_message TEXT,
+          recorded_at INTEGER NOT NULL
+        );
+      `);
+            db.exec(`
+        INSERT INTO skill_operations__v47 (
+          id, operation_id, idempotency_key, binding_hash, operation, state, result,
+          actor_type, actor_id, worktree_id, skill_id, skill_version,
+          source_origin, source_repository, source_ref, source_commit, artifact_sha256,
+          error_code, error_message, recorded_at
+        )
+        SELECT
+          id, operation_id, idempotency_key, binding_hash, operation, state, result,
+          actor_type, actor_id, worktree_id, skill_id, skill_version,
+          source_origin, source_repository, source_ref, source_commit, artifact_sha256,
+          error_code, error_message, recorded_at
+        FROM skill_operations;
+      `);
+            db.exec('DROP TABLE skill_operations;');
+            db.exec('ALTER TABLE skill_operations__v47 RENAME TO skill_operations;');
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_skill_operations_operation_id
+          ON skill_operations(operation_id);
+      `);
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_skill_operations_idempotency_key
+          ON skill_operations(idempotency_key);
+      `);
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_skill_operations_target
+          ON skill_operations(worktree_id, skill_id, recorded_at);
+      `);
+            db.exec(`
+        CREATE TRIGGER IF NOT EXISTS skill_operations_no_update
+        BEFORE UPDATE ON skill_operations
+        BEGIN
+          SELECT RAISE(ABORT, 'skill_operations is append-only');
+        END;
+      `);
+            db.exec(`
+        CREATE TRIGGER IF NOT EXISTS skill_operations_no_delete
+        BEFORE DELETE ON skill_operations
+        BEGIN
+          SELECT RAISE(ABORT, 'skill_operations is append-only');
+        END;
+      `);
+        },
+    },
+];

package/dist/server/src/lib/skills/compatibility-matrix.js ADDED Viewed

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Measured Agent discovery matrix (Issue #1246)
+ *
+ * What a Skill package *declares* about an Agent and what CommandMate has
+ * actually *measured* are different claims. `compatibility.ts` carries the
+ * declaration; this module carries the measurement, so the UI can show both and
+ * never present one as the other.
+ *
+ * Two axes, not one. A single `native`/`unsupported` value cannot describe
+ * Codex CLI 0.145.0, which discovers a Skill from `.agents/skills` but does not
+ * expose it as a slash command. Collapsing that into one value would either
+ * promise an invocation route that does not exist or deny a discovery that does.
+ * So discovery and invocation are recorded separately and only discovery feeds
+ * the support verdict; invocation becomes a stated limitation.
+ *
+ * Pure data and pure functions: no filesystem, no network, no clock. `now` is
+ * always an explicit argument so a staleness verdict is reproducible.
+ *
+ * Evidence provenance: the 2026-07-26 measurements were taken in an isolated
+ * environment (dedicated port, dedicated database, a fresh repository with no
+ * Skills installed) against CommandMate 0.15.0. They are recorded here rather
+ * than re-derived at runtime — CommandMate does not drive a CLI to answer a
+ * catalog request.
+ *
+ * @module lib/skills/compatibility-matrix
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_LIMITATION_MESSAGE_KEYS = exports.AGENT_RELOAD_MESSAGE_KEYS = exports.SKILL_EVIDENCE_MAX_AGE_DAYS = exports.AGENT_EVIDENCE_KIND_LABEL_KEYS = exports.AGENT_AXIS_OUTCOME_LABEL_KEYS = exports.AGENT_AXIS_LABEL_KEYS = exports.SKILL_EVIDENCE_KINDS = exports.SKILL_AGENT_AXIS_OUTCOMES = void 0;
+exports.getSkillAgentMatrix = getSkillAgentMatrix;
+exports.findSkillAgentMatrixEntry = findSkillAgentMatrixEntry;
+exports.isAgentMeasured = isAgentMeasured;
+exports.deriveMatrixAgentSupport = deriveMatrixAgentSupport;
+exports.evidenceAgeInDays = evidenceAgeInDays;
+exports.isEvidenceStale = isEvidenceStale;
+exports.unmeasuredAgents = unmeasuredAgents;
+exports.agentsMissingFromMatrix = agentsMissingFromMatrix;
+const types_1 = require("../../lib/cli-tools/types");
+const constants_1 = require("../../lib/skills/constants");
+exports.SKILL_AGENT_AXIS_OUTCOMES = [
+    'verified',
+    'unsupported',
+    'unknown',
+];
+exports.SKILL_EVIDENCE_KINDS = [
+    'mechanical',
+    'self_report',
+    'not_measured',
+];
+/** i18n keys naming each axis, shared by UI and CLI (UX-05). */
+exports.AGENT_AXIS_LABEL_KEYS = {
+    discovery: 'skills.compatibility.axis.discovery',
+    invocation: 'skills.compatibility.axis.invocation',
+};
+exports.AGENT_AXIS_OUTCOME_LABEL_KEYS = {
+    verified: 'skills.compatibility.axisOutcome.verified',
+    unsupported: 'skills.compatibility.axisOutcome.unsupported',
+    unknown: 'skills.compatibility.axisOutcome.unknown',
+};
+exports.AGENT_EVIDENCE_KIND_LABEL_KEYS = {
+    mechanical: 'skills.compatibility.evidenceKind.mechanical',
+    self_report: 'skills.compatibility.evidenceKind.selfReport',
+    not_measured: 'skills.compatibility.evidenceKind.notMeasured',
+};
+/**
+ * How long a measurement stays quotable before the UI flags it.
+ *
+ * Agent CLIs ship far faster than CommandMate re-measures them, so evidence
+ * that is merely old is presented as old rather than silently trusted.
+ */
+exports.SKILL_EVIDENCE_MAX_AGE_DAYS = 180;
+const NOT_MEASURED_AXIS = {
+    outcome: 'unknown',
+    evidenceKind: 'not_measured',
+    labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.unknown,
+    evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.not_measured,
+    limitationKey: null,
+};
+const NOT_MEASURED_SKIP_REASON_KEY = 'skills.compatibility.skipReason.notMeasured';
+/** Reload guidance keys. Keyed by behavior, not by Agent, so they stay reusable. */
+exports.AGENT_RELOAD_MESSAGE_KEYS = {
+    SESSION_RESTART: 'skills.compatibility.reload.sessionRestart',
+    SESSION_RESTART_NO_SLASH: 'skills.compatibility.reload.sessionRestartNoSlash',
+    UNKNOWN: 'skills.compatibility.reload.unknown',
+};
+/** Known limitation keys attached to an axis outcome. */
+exports.AGENT_LIMITATION_MESSAGE_KEYS = {
+    NO_SLASH_COMMAND: 'skills.compatibility.limitation.noSlashCommand',
+};
+/** Evidence reference for the 2026-07-26 isolated-environment measurement. */
+const G4_EVIDENCE_SOURCE = 'https://github.com/Kewton/CommandMate/issues/1513#issuecomment-5083878264';
+const MEASURED_DATE_2026_07_26 = '2026-07-26';
+function unmeasuredEntry(agent) {
+    return {
+        agent,
+        discoveryRoots: [],
+        discovery: NOT_MEASURED_AXIS,
+        invocation: NOT_MEASURED_AXIS,
+        testedVersion: null,
+        testedDate: null,
+        evidenceSource: null,
+        reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.UNKNOWN,
+        skipReasonKey: NOT_MEASURED_SKIP_REASON_KEY,
+    };
+}
+// =============================================================================
+// The matrix
+// =============================================================================
+/**
+ * Every Agent CommandMate knows about, measured or not.
+ *
+ * The unmeasured entries are listed rather than omitted: an Agent missing from
+ * the table would render as no statement at all, which a reader completes as
+ * "presumably fine". An explicit `unknown` with a skip reason is the honest
+ * shape of "we did not test this".
+ */
+const AGENT_DISCOVERY_MATRIX = [
+    {
+        agent: 'claude',
+        // Measured to read `.claude/skills` and *not* `.agents/skills`. The official
+        // catalog's older entries credited `.agents/skills` for Claude support; the
+        // conclusion was right and the reason was wrong — it works because #1460
+        // installs into `.claude/skills` too.
+        discoveryRoots: [constants_1.SKILL_CLAUDE_INSTALL_ROOT_PREFIX],
+        discovery: {
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        invocation: {
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        testedVersion: '2.1.220',
+        testedDate: MEASURED_DATE_2026_07_26,
+        evidenceSource: G4_EVIDENCE_SOURCE,
+        reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.SESSION_RESTART,
+        skipReasonKey: null,
+    },
+    {
+        agent: 'codex',
+        discoveryRoots: [constants_1.SKILL_INSTALL_ROOT_PREFIX],
+        discovery: {
+            // The Agent named the absolute SKILL.md path under `.agents/skills` when
+            // asked without tools. That is evidence, and it is the Agent describing
+            // itself, so it is recorded as a self report rather than as a match.
+            outcome: 'verified',
+            evidenceKind: 'self_report',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.self_report,
+            limitationKey: null,
+        },
+        invocation: {
+            // Ruled out as a placement problem by control: `/mo` matched `/model`, so
+            // the palette works, and a Skill already sitting in `~/.codex/skills` did
+            // not match either. This CLI version does not expose Skills as slash
+            // commands wherever they are placed.
+            outcome: 'unsupported',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.unsupported,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: exports.AGENT_LIMITATION_MESSAGE_KEYS.NO_SLASH_COMMAND,
+        },
+        testedVersion: '0.145.0',
+        testedDate: MEASURED_DATE_2026_07_26,
+        evidenceSource: G4_EVIDENCE_SOURCE,
+        reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.SESSION_RESTART_NO_SLASH,
+        skipReasonKey: null,
+    },
+    unmeasuredEntry('gemini'),
+    unmeasuredEntry('vibe-local'),
+    unmeasuredEntry('opencode'),
+    unmeasuredEntry('copilot'),
+    // CommandMate's own slash palette serves `.agents/skills` entries to
+    // antigravity sessions (#1504). That is CommandMate injecting a command, not
+    // the Agent discovering a Skill, so it is not evidence for this table.
+    unmeasuredEntry('antigravity'),
+];
+/** The measured matrix, in CLI-tool declaration order. */
+function getSkillAgentMatrix() {
+    return AGENT_DISCOVERY_MATRIX;
+}
+/** The entry for one Agent, or null when the id is not a known CLI tool. */
+function findSkillAgentMatrixEntry(agent) {
+    return AGENT_DISCOVERY_MATRIX.find((entry) => entry.agent === agent) ?? null;
+}
+/** Whether CommandMate has any measurement at all for this Agent. */
+function isAgentMeasured(entry) {
+    return entry.discovery.evidenceKind !== 'not_measured';
+}
+/**
+ * The four-valued support verdict implied by the measurement.
+ *
+ * Only the discovery axis decides it. An Agent that finds and can run a Skill
+ * supports it natively even when its palette does not list it, so a failed
+ * invocation axis is reported as a limitation instead of demoting the verdict
+ * to `unsupported` — which would read as "this will not work".
+ *
+ * `commandmate_runtime` is never produced here: the Runtime is not shipped, and
+ * inventing that verdict would promise a fallback that does not exist.
+ */
+function deriveMatrixAgentSupport(entry) {
+    switch (entry.discovery.outcome) {
+        case 'verified':
+            return 'native';
+        case 'unsupported':
+            return 'unsupported';
+        case 'unknown':
+            return 'unknown';
+    }
+}
+// =============================================================================
+// Staleness
+// =============================================================================
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MEASURED_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Whole days between the measurement and `now`, or null when unmeasured or when
+ * the recorded date is unusable. A measurement dated in the future yields 0
+ * rather than a negative age.
+ */
+function evidenceAgeInDays(entry, now) {
+    if (entry.testedDate === null || !MEASURED_DATE_PATTERN.test(entry.testedDate))
+        return null;
+    const measured = Date.parse(`${entry.testedDate}T00:00:00Z`);
+    const current = now.getTime();
+    if (Number.isNaN(measured) || Number.isNaN(current))
+        return null;
+    return Math.max(0, Math.floor((current - measured) / MS_PER_DAY));
+}
+/**
+ * Whether the measurement is old enough to warn about.
+ *
+ * An unmeasured Agent is not stale — it is unknown, which the UI already states
+ * more strongly. Marking it stale as well would imply a measurement had expired.
+ */
+function isEvidenceStale(entry, now, maxAgeDays = exports.SKILL_EVIDENCE_MAX_AGE_DAYS) {
+    const age = evidenceAgeInDays(entry, now);
+    return age !== null && age > maxAgeDays;
+}
+// =============================================================================
+// Coverage
+// =============================================================================
+/** CLI tools with no measurement, in matrix order. */
+function unmeasuredAgents() {
+    return AGENT_DISCOVERY_MATRIX.filter((entry) => !isAgentMeasured(entry)).map((entry) => entry.agent);
+}
+/** CLI tool ids the matrix does not mention. Empty in a consistent build. */
+function agentsMissingFromMatrix() {
+    return types_1.CLI_TOOL_IDS.filter((id) => findSkillAgentMatrixEntry(id) === null);
+}

package/dist/server/src/lib/skills/compatibility.js CHANGED Viewed

@@ -3,8 +3,8 @@
  * CommandMate compatibility judgement and version resolution (Issue #1231)
  *
  * Pure functions: no filesystem, no network, no process state. The host version
- * is always an explicit argument so UI, API and CLI can evaluate the same
- * Catalog against the same rules and reach the same verdict.
+ * and the current instant are always explicit arguments so UI, API and CLI can
+ * evaluate the same Catalog against the same rules and reach the same verdict.
  *
  * Every verdict carries a stable machine code *and* a human-readable message
  * (受入条件: "互換性NGの理由がmachine-readable codeとhuman-readable messageで返る").
@@ -14,16 +14,19 @@
  * @module lib/skills/compatibility
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SkillRecommendationReason = exports.UNKNOWN_HOST_VERSION_SENTINEL = exports.SKILL_COMPATIBILITY_MESSAGE_KEYS = exports.SkillCompatibilityReason = void 0;
+exports.SkillRecommendationReason = exports.SKILL_AGENT_VERIFICATION_MESSAGE_KEYS = exports.SkillAgentVerification = exports.UNKNOWN_HOST_VERSION_SENTINEL = exports.SKILL_COMPATIBILITY_MESSAGE_KEYS = exports.SkillCompatibilityReason = void 0;
 exports.normalizeHostVersion = normalizeHostVersion;
 exports.evaluateCommandMateCompatibility = evaluateCommandMateCompatibility;
 exports.evaluateVersionCompatibility = evaluateVersionCompatibility;
+exports.capSupportByMeasurement = capSupportByMeasurement;
+exports.reconcileAgentSupport = reconcileAgentSupport;
 exports.describeAgentCompatibility = describeAgentCompatibility;
 exports.resolveSkillVersions = resolveSkillVersions;
 exports.findSkillCatalogEntry = findSkillCatalogEntry;
 // Sibling modules of the same package are imported directly rather than through
 // the `@/lib/skills` barrel, so adding this module to the barrel later can never
 // introduce an import cycle. External callers still go through the barrel.
+const compatibility_matrix_1 = require("../../lib/skills/compatibility-matrix");
 const constants_1 = require("../../lib/skills/constants");
 const semver_1 = require("../../lib/skills/semver");
 /** Stable reason codes for a CommandMate compatibility verdict. */
@@ -122,14 +125,132 @@ function evaluateCommandMateCompatibility(requiredRange, currentVersion) {
 function evaluateVersionCompatibility(version, currentVersion) {
     return evaluateCommandMateCompatibility(version.compatibility.commandmate, currentVersion);
 }
-/** Attach the shared i18n label key to each Agent support claim. */
-function describeAgentCompatibility(agents) {
-    return agents.map((entry) => ({
-        agent: entry.agent,
-        support: entry.support,
-        labelKey: constants_1.AGENT_SUPPORT_LABEL_KEYS[entry.support],
-        evidence: entry.evidence,
-    }));
+// =============================================================================
+// Agent compatibility
+// =============================================================================
+/**
+ * How the publisher's declaration stands up against what CommandMate measured
+ * (Issue #1246).
+ */
+exports.SkillAgentVerification = {
+    /** Declaration and measurement agree. */
+    CONFIRMED: 'SKILL_AGENT_EVIDENCE_CONFIRMED',
+    /** Measurement is weaker than the declaration, so the declaration is capped. */
+    RESTRICTED: 'SKILL_AGENT_EVIDENCE_RESTRICTED',
+    /** Measurement is stronger than the declaration; the manifest has fallen behind. */
+    STALE_DECLARATION: 'SKILL_AGENT_EVIDENCE_STALE_DECLARATION',
+    /** CommandMate has never measured this Agent. */
+    UNVERIFIED: 'SKILL_AGENT_EVIDENCE_UNVERIFIED',
+};
+exports.SKILL_AGENT_VERIFICATION_MESSAGE_KEYS = {
+    [exports.SkillAgentVerification.CONFIRMED]: 'skills.compatibility.verification.confirmed',
+    [exports.SkillAgentVerification.RESTRICTED]: 'skills.compatibility.verification.restricted',
+    [exports.SkillAgentVerification.STALE_DECLARATION]: 'skills.compatibility.verification.staleDeclaration',
+    [exports.SkillAgentVerification.UNVERIFIED]: 'skills.compatibility.verification.unverified',
+};
+/**
+ * Ordering used to cap a declaration by a measurement. Higher is stronger.
+ *
+ * `unknown` outranks `unsupported` because "we could not tell" leaves more room
+ * than "we established it does not work".
+ */
+const AGENT_SUPPORT_RANK = {
+    unsupported: 0,
+    unknown: 1,
+    commandmate_runtime: 2,
+    native: 3,
+};
+/**
+ * Cap a publisher's declaration by what CommandMate measured.
+ *
+ * Downward only. A weaker measurement wins, which is what keeps an
+ * evidence-free `native` off the screen. A stronger one does not: raising a
+ * package's own claim is the publisher's call, so the mismatch is reported as
+ * a declaration that has fallen behind.
+ */
+function capSupportByMeasurement(declared, measured) {
+    const declaredRank = AGENT_SUPPORT_RANK[declared];
+    const measuredRank = AGENT_SUPPORT_RANK[measured];
+    if (measuredRank < declaredRank) {
+        return { support: measured, verification: exports.SkillAgentVerification.RESTRICTED };
+    }
+    if (measuredRank > declaredRank) {
+        return { support: declared, verification: exports.SkillAgentVerification.STALE_DECLARATION };
+    }
+    return { support: declared, verification: exports.SkillAgentVerification.CONFIRMED };
+}
+function toAxisView(axis, evidence) {
+    return {
+        axis,
+        axisKey: compatibility_matrix_1.AGENT_AXIS_LABEL_KEYS[axis],
+        outcome: evidence.outcome,
+        outcomeKey: evidence.labelKey,
+        evidenceKind: evidence.evidenceKind,
+        evidenceKindKey: evidence.evidenceKindKey,
+        limitationKey: evidence.limitationKey,
+    };
+}
+function toMeasuredView(entry, now) {
+    return {
+        discovery: toAxisView('discovery', entry.discovery),
+        invocation: toAxisView('invocation', entry.invocation),
+        discoveryRoots: [...entry.discoveryRoots],
+        testedVersion: entry.testedVersion,
+        testedDate: entry.testedDate,
+        evidenceSource: entry.evidenceSource,
+        ageDays: (0, compatibility_matrix_1.evidenceAgeInDays)(entry, now),
+        stale: (0, compatibility_matrix_1.isEvidenceStale)(entry, now),
+    };
+}
+/**
+ * Reconcile one declared Agent claim with the measured discovery matrix.
+ *
+ * The declaration is never rewritten upward: a measurement stronger than the
+ * manifest is reported as a stale declaration, not silently promoted, because
+ * the publisher is the one who decides what their package claims to support.
+ * It *is* capped downward, which is what keeps "evidence-free native" off the
+ * screen when a manifest asserts an Agent CommandMate measured as unsupported.
+ */
+function reconcileAgentSupport(declared, now) {
+    const entry = (0, compatibility_matrix_1.findSkillAgentMatrixEntry)(declared.agent);
+    const base = {
+        agent: declared.agent,
+        evidence: declared.evidence,
+        declaredSupport: declared.support,
+        declaredLabelKey: constants_1.AGENT_SUPPORT_LABEL_KEYS[declared.support],
+    };
+    if (entry === null || !(0, compatibility_matrix_1.isAgentMeasured)(entry)) {
+        return {
+            ...base,
+            support: declared.support,
+            labelKey: constants_1.AGENT_SUPPORT_LABEL_KEYS[declared.support],
+            verification: exports.SkillAgentVerification.UNVERIFIED,
+            verificationKey: exports.SKILL_AGENT_VERIFICATION_MESSAGE_KEYS[exports.SkillAgentVerification.UNVERIFIED],
+            measured: null,
+            skipReasonKey: entry?.skipReasonKey ?? null,
+            reloadKey: entry?.reloadKey ?? compatibility_matrix_1.AGENT_RELOAD_MESSAGE_KEYS.UNKNOWN,
+        };
+    }
+    const { support, verification } = capSupportByMeasurement(declared.support, (0, compatibility_matrix_1.deriveMatrixAgentSupport)(entry));
+    return {
+        ...base,
+        support,
+        labelKey: constants_1.AGENT_SUPPORT_LABEL_KEYS[support],
+        verification,
+        verificationKey: exports.SKILL_AGENT_VERIFICATION_MESSAGE_KEYS[verification],
+        measured: toMeasuredView(entry, now),
+        skipReasonKey: null,
+        reloadKey: entry.reloadKey,
+    };
+}
+/**
+ * Attach the shared i18n label key and the measured evidence to each claim.
+ *
+ * @param now - Evaluated against for evidence staleness. Passed explicitly by
+ *   tests so a verdict never depends on when the suite runs.
+ */
+function describeAgentCompatibility(agents, now = new Date()) {
+    return agents.map((entry) => reconcileAgentSupport(entry, now));
 }
 // =============================================================================
 // Version resolution