happyskills 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-07-01
+
+### Changed
+
+- Make `happyskills match` recognise a local skill as `certified` when its **functional content matches any published version** — not just a byte-identical head. For every hash/name candidate, `match` now enumerates the repo's whole version history (`GET /refs`) and fetches each version's per-file manifest (path + blob SHA only, never content), then runs a **cross-version containment check**: a version is a match when all of its functional files (everything except `skill.json` and `CHANGELOG.md`) are present locally with the same SHA. `SKILL.md` is the identity anchor — containment can't hold unless the local `SKILL.md` equals that version's. The **earliest** contained version is certified (`match.version`) — where the content originated, so a metadata-only re-release doesn't shift the reported version — carrying `match.latest_version` + `match.is_latest` so a behind-by copy is clear. This is what lets a raw local folder with **no `skill.json` at all** — whose content reproduces v0.3.1 — report `certified @ 0.3.1` even though head is v0.3.2, instead of misreporting as `near`/`likely` against head. **Extra local files are tolerated** (a stray `__pycache__/*.pyc`, an editor swap) — they can't block identity — but are surfaced in `local_only_files` so a genuine fork isn't hidden. `skill.json`/`CHANGELOG.md` are excluded from the containment check, `differing_files`, and the similarity denominator (root-level, case-insensitive; `LICENSE` still counts). Purely client-side — no API or registry change. The text output gains "Certified to an older published version" and "Certified, with extra local-only files" lines. (Spec 260629-03 §4.9/§4.10.)
+
+## [1.15.0] - 2026-06-30
+
+### Changed
+
+- Make `happyskills match` **version-precise**: it now matches each local skill against **all** published versions of a skill, not just the latest. A local copy that is byte-identical to an *older* release is reported as `certified` at that exact version (the result carries `match.version`, `match.latest_version`, and `match.is_latest`) — instead of being diffed against head and misreported as `likely`/drift just because you're a few versions behind. The text output gains an "identical to an older published version (you are behind)" line listing each such skill as `name → owner/skill @ <version> (latest <latest>)`. Mechanically, the match funnel now also sends the whole-skill `tree_sha`s in the same batched `POST /repos:match` call and certifies on a cross-version tree match (with a fallback to the previous head-only behavior for older API servers). Requires API ≥ 5.18.0 (the `tree_shas` axis on `POST /repos:match`). (Spec 260629-03 §4.8.)
+
 ## [1.14.0] - 2026-06-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.14.0",
+	"version": "1.16.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/repos.js

@@ -84,6 +84,18 @@ const get_refs = (owner, repo) => catch_errors(`Get refs for ${owner}/${repo} fa
 	return data
 })
 
+// Published version strings for a repo, newest-agnostic (the funnel sorts).
+// Parses `refs/tags/v<semver>` tags from the refs list — used by `happyskills
+// match` to scan every version for a cross-version containment match.
+const list_versions = (owner, repo) => catch_errors(`List versions for ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.get(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/refs`)
+	if (errors) throw errors[errors.length - 1]
+	const refs = Array.isArray(data) ? data : (data && (data.results || data.refs)) || []
+	return refs
+		.map(r => { const m = String((r && r.name) || r).match(/^refs\/tags\/v?(.+)$/); return m ? m[1] : null })
+		.filter(Boolean)
+})
+
 const get_repo = (owner, repo, options = {}) => catch_errors(`Get repo ${owner}/${repo} failed`, async () => {
 	const [errors, data] = await client.get(`/repos/${owner}/${repo}`, { auth: options.auth || false })
 	if (errors) throw errors[errors.length - 1]
@@ -214,11 +226,14 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 })
 
 // POST /repos:match — catalog matching for `happyskills match` (spec 260629-03).
-// ONE batch call for the whole folder's hashes + names. Returns
-// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }] }
-// (two keys, so the client's single-key unwrap leaves it intact).
-const match = (hashes, names) => catch_errors('Catalog match lookup failed', async () => {
-	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [] })
+// ONE batch call for the whole folder's hashes + names + tree shas. Returns
+// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }],
+//   tree_results: [{ tree_sha, candidates }] } — multi-key, so the client's
+// single-key unwrap leaves it intact. `tree_results` (spec §4.8) matches the
+// whole-skill content address across ALL versions, so a local copy identical to
+// an older release is pinned to that exact version instead of drifting vs head.
+const match = (hashes, names, tree_shas) => catch_errors('Catalog match lookup failed', async () => {
+	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [], tree_shas: tree_shas || [] })
 	if (errors) throw errors[errors.length - 1]
 	return data
 })
@@ -235,4 +250,4 @@ const manifests = (repo_versions) => catch_errors('Manifests lookup failed', asy
 	}
 })
 
-module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree, match, manifests }
+module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, list_versions, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree, match, manifests }

package/src/commands/match.js

@@ -67,6 +67,7 @@ const run = (args) => catch_errors('Match failed', async () => {
 	const deps = {
 		match: repos_api.match,
 		manifests: repos_api.manifests,
+		versions: (workspace, name) => repos_api.list_versions(workspace, name),
 		semantic_search: (q) => repos_api.semantic_search(q, { limit: 3 }),
 	}
 	const [funnel_err, funnel] = await run_funnel(scanned.skills, deps, { threshold, concurrency })
@@ -129,7 +130,31 @@ const run = (args) => catch_errors('Match failed', async () => {
 const render_text = (data, warnings) => {
 	const s = data.summary
 	print_info(`Scanned ${s.total} skill${s.total === 1 ? '' : 's'}.`)
-	print_success(`✓ ${s.certified} already in HappySkills, unchanged · ≈ ${s.near} with small differences · ~ ${s.likely + s.possible} loosely matched · ✗ ${s.unmatched} not found`)
+	print_success(`✓ ${s.certified} certified (content matches a published version) · ≈ ${s.near} with small differences · ~ ${s.likely + s.possible} loosely matched · ✗ ${s.unmatched} not found`)
+
+	// A certified match to an OLDER version is still an exact match — surface the
+	// version gap so the principal knows it is the real skill, just behind.
+	const behind = data.certified.filter(en => en.match && en.match.latest_version && en.match.is_latest === false)
+	if (behind.length) {
+		print_info('\nCertified to an older published version (you are behind):')
+		for (const en of behind) {
+			const where = en.match ? `${en.match.workspace}/${en.match.name}` : '(catalog)'
+			print_info(`  ${en.local.name} → ${where} @ ${en.match.version} (latest ${en.match.latest_version})`)
+		}
+	}
+
+	// Certified, but the local copy carries extra files the published version
+	// does not (build cruft like __pycache__/*.pyc, or genuine local additions).
+	// Certification stands — the skill's content is fully present — but show the
+	// extras so a real fork isn't hidden as "identical".
+	const with_extras = data.certified.filter(en => en.local_only_files && en.local_only_files.length)
+	if (with_extras.length) {
+		print_info('\nCertified, with extra local-only files (not part of the published skill):')
+		for (const en of with_extras) {
+			const where = en.match ? `${en.match.workspace}/${en.match.name}@${en.match.version}` : '(catalog)'
+			print_info(`  ${en.local.name} → ${where} — local extras: ${en.local_only_files.join(', ')}`)
+		}
+	}
 
 	if (data.near.length) {
 		print_info('\nSkills with small differences:')

package/src/commands/match.test.js

@@ -27,6 +27,7 @@ require.cache[repos_path] = {
 	exports: {
 		match: async () => [null, { results: api_state.results, name_results: api_state.name_results }],
 		manifests: async () => [null, { manifests: api_state.manifests, warnings: [] }],
+		list_versions: async (ws, name) => [null, [...new Set(api_state.manifests.filter(m => m.workspace === ws && m.name === name).map(m => m.version))]],
 		semantic_search: async () => [null, api_state.semantic],
 	},
 }

package/src/integration/api_envelope.test.js

@@ -90,7 +90,13 @@ const run_cli = (args, env_override = {}) => new Promise((resolve) => {
 	const has_mode_flag = args.includes('--json') || args.includes('--text')
 	const final_args = has_mode_flag ? args : [...args, '--text']
 	const child = spawn(NODE, [CLI, ...final_args], {
-		env: { ...process.env, NO_COLOR: '1', CI: '', ...env_override },
+		// Isolate the CLI config dir so the spawned binary never reads the
+		// developer's real ~/.config/happyskills credentials. A stored (expired)
+		// token would otherwise make an authed command (e.g. a search POST)
+		// attempt a token refresh against the stub's missing /auth/refresh route
+		// and fail with NETWORK_ERROR — a machine-state-dependent flake. A test
+		// that needs a specific config dir overrides this via env_override (last).
+		env: { ...process.env, NO_COLOR: '1', CI: '', XDG_CONFIG_HOME: make_tmp(), ...env_override },
 	})
 	let stdout = ''
 	let stderr = ''

package/src/match/diff.js

@@ -4,9 +4,17 @@
 // [{ path, blob_sha }] lists. The differing-file list is the load-bearing
 // artifact (not the single similarity %): it's what tells the principal exactly
 // what changed (e.g. "only LICENSE differs").
+//
+// opts.ignore(path) → true marks a file as non-functional / platform-specific
+// (spec §4.9): it is EXCLUDED from the functional diff and the similarity
+// denominator, so it can never count toward "is this the same skill". Ignored
+// files that differ are reported separately as `ignored_differing`, so the
+// caller can flag a match as "metadata-only differs" rather than silently
+// dropping the fact. Omit opts.ignore for the original whole-tree behavior.
 
 // local_files / catalog_files: [{ path, blob_sha }]
-const diff_manifests = (local_files, catalog_files) => {
+const diff_manifests = (local_files, catalog_files, opts = {}) => {
+	const ignore = typeof opts.ignore === 'function' ? opts.ignore : () => false
 	const local = new Map((local_files || []).map(f => [f.path, f.blob_sha]))
 	const catalog = new Map((catalog_files || []).map(f => [f.path, f.blob_sha]))
 	const all = new Set([...local.keys(), ...catalog.keys()])
@@ -15,16 +23,22 @@ const diff_manifests = (local_files, catalog_files) => {
 	const modified = []
 	const added = []   // present locally, absent in the catalog skill
 	const removed = [] // present in the catalog skill, absent locally
+	const ignored_differing = [] // ignored files that differ (metadata-only deltas)
 
 	for (const p of all) {
 		const l = local.get(p)
 		const c = catalog.get(p)
+		if (ignore(p)) {
+			if (l !== c) ignored_differing.push(p) // present-both-modified, or added/removed
+			continue
+		}
 		if (l !== undefined && c !== undefined) (l === c ? identical : modified).push(p)
 		else if (l !== undefined) added.push(p)
 		else removed.push(p)
 	}
 
-	const total = all.size
+	// Similarity is over FUNCTIONAL files only (ignored files are out of the set).
+	const total = identical.length + modified.length + added.length + removed.length
 	const similarity = total === 0 ? 1 : identical.length / total
 	const differing = [...modified, ...added, ...removed].sort()
 
@@ -35,6 +49,7 @@ const diff_manifests = (local_files, catalog_files) => {
 		added: added.sort(),
 		removed: removed.sort(),
 		differing,
+		ignored_differing: ignored_differing.sort(),
 	}
 }
 

package/src/match/funnel.js

@@ -1,19 +1,26 @@
 'use strict'
-// The match funnel + tier classification (spec 260629-03 §4.7).
+// The match funnel + tier classification (spec 260629-03 §4.7 / §4.10).
 //
 // Stages, cheapest signal first, NO blob downloads to classify:
-//   1. hash + name — ONE batched POST /repos:match for ALL local skills.
-//   2. tree SHA    — local.tree_sha === a candidate's tree_sha ⇒ certified
-//                    (byte-identical, zero further work).
-//   3. manifest    — for non-certified hash/name candidates, fetch the narrowed
-//                    source-of-truth manifest (bounded fan-out, no blob content)
-//                    and diff per-file. A hash match means SKILL.md is identical
-//                    by construction → favor `near` and just list the differing
-//                    files. A name-only match is `near` above the similarity
-//                    threshold, else `likely`.
-//   4. semantic    — skills with no hash/name match fall back to the deployed
-//                    semantic search (bounded), labeled `possible` (clearly low
-//                    confidence), else `unmatched`.
+//   1. batch      — ONE POST /repos:match for the whole folder (hashes + names +
+//                   tree shas).
+//   2. tree SHA   — local.tree_sha === a candidate's tree_sha ⇒ certified,
+//                   byte-identical, at that EXACT version (even an older one),
+//                   zero further work.
+//   3. versions   — for every remaining hash/name candidate, enumerate ALL the
+//                   repo's versions and fetch each version's per-file manifest
+//                   (path + blob SHA only — never blob content; bounded + chunked).
+//   3.5 contain   — a version is a match when all its FUNCTIONAL files (everything
+//                   except skill.json / CHANGELOG.md) are present locally with the
+//                   same blob SHA (catalog ⊆ local). SKILL.md is the identity
+//                   anchor — it is functional, so containment can't hold unless the
+//                   local SKILL.md equals that version's. Extra local files (dirt
+//                   like __pycache__/*.pyc) are tolerated and surfaced as
+//                   `local_only_files`. Certify the EARLIEST contained version (where
+//                   the content originated); else near/likely against the closest
+//                   version by functional similarity.
+//   4. semantic   — skills with no hash/name match fall back to the deployed
+//                   semantic search (bounded), labeled `possible`, else `unmatched`.
 //
 // Closed tier set: certified · near · likely · possible · unmatched.
 
@@ -21,12 +28,34 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { bounded, DEFAULT_CONCURRENCY } = require('../utils/concurrency')
 const { diff_manifests } = require('./diff')
 
-// Identical-file fraction above which a NAME-only match is promoted to `near`.
+// Identical-file fraction above which a non-contained match counts as `near`.
 const DEFAULT_THRESHOLD = 0.5
 // Mirror of the server cap (MATCH_MAX_MANIFESTS) so we chunk manifest requests.
 const MANIFEST_CHUNK = 50
+// Safety bound on the cross-version scan — a repo with more tags than this has
+// its newest N scanned (surfaced as a warning; never a silent cap).
+const MAX_VERSIONS_PER_REPO = 50
 
-const key_of = (c) => `${String(c.workspace).toLowerCase()}/${c.name}@${c.version}`
+// Non-functional / platform-specific files that do NOT count toward skill
+// identity (spec 260629-03 §4.9). `skill.json` is HappySkills metadata — always
+// present, and its `version` bumps on every publish; `CHANGELOG.md` is
+// non-functional release history. Both are excluded from the containment check
+// and the similarity denominator. Matched on the lowercased path, so only the
+// ROOT files count (a `references/CHANGELOG.md` still counts as real content).
+const IGNORE_FILES = new Set(['skill.json', 'changelog.md'])
+const is_ignored_file = (p) => IGNORE_FILES.has(String(p).toLowerCase())
+
+const repo_key = (c) => `${String(c.workspace).toLowerCase()}/${c.name}`
+const key_of = (c) => `${repo_key(c)}@${c.version}`
+
+// Descending semver-ish compare (numeric, dot-separated) — surfaces the NEWEST
+// matching version first.
+const cmp_version_desc = (a, b) => {
+	const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0)
+	const pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0)
+	for (let i = 0; i < Math.max(pa.length, pb.length); i++) { const d = (pb[i] || 0) - (pa[i] || 0); if (d) return d }
+	return 0
+}
 
 const local_view = (skill) => ({
 	name: skill.name,
@@ -40,11 +69,18 @@ const match_view = (c) => ({
 	workspace: c.workspace,
 	name: c.name,
 	version: c.version,
-	tree_sha: c.tree_sha,
+	tree_sha: c.tree_sha || null,
 	is_source_of_truth: !!c.is_source_of_truth,
+	// The repo head, so a certified-but-older match can be surfaced as
+	// "certified @ 0.3.1 (latest 0.3.2)". `is_latest` compares the matched
+	// version to head. Null when the candidate came from a head-only path.
+	latest_version: c.latest_version || null,
+	is_latest: c.latest_version ? c.version === c.latest_version : null,
 })
 
-// deps: { match(hashes,names), manifests(repo_versions), semantic_search?(query) }
+// deps: { match(hashes,names,tree_shas), manifests(repo_versions),
+//         versions?(workspace,name), semantic_search?(query) } — each returns a
+//         puffy [err, data] tuple.
 // opts: { threshold, concurrency }
 const run_funnel = (skills, deps, opts = {}) =>
 	catch_errors('Match funnel failed', async () => {
@@ -58,46 +94,84 @@ const run_funnel = (skills, deps, opts = {}) =>
 		// ── Stage 1: one batched match for the whole folder ──────────────────
 		const hashes = [...new Set(skills.map(s => s.skill_md_sha).filter(Boolean))]
 		const names = [...new Set(skills.map(s => s.name).filter(Boolean))]
-		const [m_err, match_data] = await deps.match(hashes, names)
+		const tree_shas = [...new Set(skills.map(s => s.tree_sha).filter(Boolean))]
+		const [m_err, match_data] = await deps.match(hashes, names, tree_shas)
 		if (m_err) throw e('Stage 1 /repos:match failed', m_err)
 
 		const by_hash = new Map((match_data.results || []).map(r => [r.skill_md_sha, r.candidates || []]))
 		const by_name = new Map((match_data.name_results || []).map(r => [String(r.name).toLowerCase(), r.candidates || []]))
+		const by_tree = new Map((match_data.tree_results || []).map(r => [r.tree_sha, r.candidates || []]))
 
-		// ── Stage 2: classify; collect the narrowed manifest set ─────────────
-		const pending = []          // needs a manifest diff
-		const none = []             // no hash/name match → semantic stage
-		const manifest_needs = new Map()
+		// ── Stage 2: fast-path certify (byte-exact) + collect candidate repos ─
+		const pending = []           // { skill, cand } — needs a cross-version scan
+		const none = []              // no hash/name match → semantic stage
+		const repo_needs = new Map() // "ws/name" -> { workspace, name, head_version, is_source_of_truth }
 
 		for (const skill of skills) {
+			const tree_cands = (skill.tree_sha && by_tree.get(skill.tree_sha)) || []
 			const hash_cands = (skill.skill_md_sha && by_hash.get(skill.skill_md_sha)) || []
 			const name_cands = by_name.get(String(skill.name || '').toLowerCase()) || []
 
-			// Certified = tree SHA equal, by the spec's definition — regardless of
-			// whether the candidate was found by hash or name. (A SKILL.md-less
-			// skill has a null hash but can still be byte-identical to a name
-			// match; hash candidates are preferred since they are checked first.)
-			const certified = [...hash_cands, ...name_cands].find(c => c.tree_sha === skill.tree_sha)
-			if (certified) {
-				buckets.certified.push({ local: local_view(skill), match: match_view(certified) })
+			// Byte-identical to a published version (tree probe) → certified at that
+			// exact version, zero manifest fetches. Falls back to head tree-SHA
+			// equality for an older server that returns no tree_results.
+			const exact = tree_cands[0] || [...hash_cands, ...name_cands].find(c => c.tree_sha === skill.tree_sha)
+			if (exact) {
+				buckets.certified.push({ local: local_view(skill), match: match_view(exact) })
 				continue
 			}
-			if (hash_cands.length) {
-				const sot = hash_cands[0] // API returns source-of-truth first
-				manifest_needs.set(key_of(sot), { workspace: sot.workspace, name: sot.name, version: sot.version })
-				pending.push({ skill, cand: sot, via: 'hash' })
-				continue
-			}
-			if (name_cands.length) {
-				const sot = name_cands[0]
-				manifest_needs.set(key_of(sot), { workspace: sot.workspace, name: sot.name, version: sot.version })
-				pending.push({ skill, cand: sot, via: 'name' })
+
+			// A hash/name candidate points at a repo — scan ALL its versions for a
+			// functional-containment match. Prefer the source-of-truth repo (the
+			// API lists candidates SoT-first), which collapses cross-repo forks.
+			const cand = hash_cands[0] || name_cands[0]
+			if (cand) {
+				// `via: hash` means the local SKILL.md equals head's — a strong
+				// same-skill signal that keeps a non-contained match at `near` (not
+				// `likely`) even if a reference differs or the manifest can't be read.
+				const via = hash_cands[0] ? 'hash' : 'name'
+				repo_needs.set(repo_key(cand), { workspace: cand.workspace, name: cand.name, head_version: cand.version, is_source_of_truth: cand.is_source_of_truth })
+				pending.push({ skill, cand, via })
 				continue
 			}
 			none.push(skill)
 		}
 
-		// ── Stage 3: bounded manifest fetch (chunked to the server cap) ──────
+		// ── Stage 2.5: enumerate each candidate repo's versions ──────────────
+		const versions_by_repo = new Map()
+		if (repo_needs.size && typeof deps.versions === 'function') {
+			const reqs = [...repo_needs.values()]
+			// Promise.resolve wrapper so a synchronously-throwing versions dep is
+			// caught here (→ head-only fallback) rather than escaping the thunk.
+			const results = await bounded(reqs.map(r => () =>
+				Promise.resolve().then(() => deps.versions(r.workspace, r.name)).then(res => ({ r, res })).catch(error => ({ r, error }))), concurrency)
+			for (const { r, res, error } of results) {
+				const key = repo_key(r)
+				const [verr, vs] = Array.isArray(res) ? res : [error || null, null]
+				if (verr || error || !Array.isArray(vs) || !vs.length) {
+					if (verr || error) warnings.push({ code: 'VERSIONS_FETCH_FAILED', message: `Could not list versions for ${r.workspace}/${r.name}.` })
+					versions_by_repo.set(key, [r.head_version].filter(Boolean))
+					continue
+				}
+				let sorted = [...new Set(vs)].sort(cmp_version_desc)
+				if (sorted.length > MAX_VERSIONS_PER_REPO) {
+					warnings.push({ code: 'VERSIONS_TRUNCATED', message: `${r.workspace}/${r.name} has ${sorted.length} versions; scanning the newest ${MAX_VERSIONS_PER_REPO}.` })
+					sorted = sorted.slice(0, MAX_VERSIONS_PER_REPO)
+				}
+				versions_by_repo.set(key, sorted)
+			}
+		} else {
+			for (const [key, r] of repo_needs) versions_by_repo.set(key, [r.head_version].filter(Boolean))
+		}
+
+		// ── Stage 3: fetch manifests for EVERY candidate (repo, version) ─────
+		const manifest_needs = new Map()
+		for (const { cand } of pending) {
+			const key = repo_key(cand)
+			for (const v of (versions_by_repo.get(key) || [])) {
+				manifest_needs.set(`${key}@${v}`, { workspace: cand.workspace, name: cand.name, version: v })
+			}
+		}
 		const manifest_by_key = new Map()
 		const needs = [...manifest_needs.values()]
 		if (needs.length) {
@@ -113,23 +187,55 @@ const run_funnel = (skills, deps, opts = {}) =>
 			}
 		}
 
-		// ── finalize the hash/name candidates with their diffs ───────────────
+		// ── Stage 3.5: cross-version containment classification ──────────────
 		for (const { skill, cand, via } of pending) {
-			const m = manifest_by_key.get(key_of(cand))
-			const diff = m ? diff_manifests(skill.files, m.files) : null
-			const entry = {
-				local: local_view(skill),
-				match: match_view(cand),
-				differing_files: diff ? diff.differing : null,
-				similarity: diff ? diff.similarity : null,
+			const key = repo_key(cand)
+			const head = cand.version
+			let contained = null   // { version, tree_sha, local_only } — EARLIEST contained
+			let closest = null     // { version, tree_sha, diff } — best partial
+			for (const v of (versions_by_repo.get(key) || [])) { // newest first
+				const m = manifest_by_key.get(`${key}@${v}`)
+				if (!m) continue
+				const diff = diff_manifests(skill.files, m.files, { ignore: is_ignored_file })
+				// Contained = every FUNCTIONAL catalog file present locally, same SHA
+				// (no missing, no modified). Extra local files (diff.added) are dirt
+				// and don't block it. Report the EARLIEST contained version — where
+				// this content originated; a later metadata-only re-release ships the
+				// same content under a new number but doesn't redefine its identity.
+				// Iterating newest→oldest and overwriting leaves the oldest match.
+				if (diff.removed.length === 0 && diff.modified.length === 0) {
+					contained = { version: v, tree_sha: m.tree_sha, local_only: diff.added }
+				}
+				if (!closest || diff.similarity > closest.diff.similarity) closest = { version: v, tree_sha: m.tree_sha, diff }
 			}
-			if (via === 'hash') {
-				// SKILL.md identical by construction → the difference is ancillary.
-				buckets.near.push(entry)
-			} else if (diff && diff.similarity >= threshold) {
-				buckets.near.push(entry)
+
+			if (contained) {
+				const local_only = contained.local_only.filter(p => !is_ignored_file(p))
+				buckets.certified.push({
+					local: local_view(skill),
+					match: match_view({ workspace: cand.workspace, name: cand.name, version: contained.version, tree_sha: contained.tree_sha, is_source_of_truth: cand.is_source_of_truth, latest_version: head }),
+					...(local_only.length ? { local_only_files: local_only } : {}),
+				})
+				continue
+			}
+
+			if (closest) {
+				const entry = {
+					local: local_view(skill),
+					match: match_view({ workspace: cand.workspace, name: cand.name, version: closest.version, tree_sha: closest.tree_sha, is_source_of_truth: cand.is_source_of_truth, latest_version: head }),
+					differing_files: closest.diff.differing,
+					similarity: closest.diff.similarity,
+				}
+				// A hash match (SKILL.md identical to head) stays `near` regardless of
+				// similarity; a name match needs to clear the threshold.
+				if (via === 'hash' || closest.diff.similarity >= threshold) buckets.near.push(entry)
+				else buckets.likely.push(entry)
 			} else {
-				buckets.likely.push(entry)
+				// No manifest resolved at all (every fetch failed). A hash match is
+				// still `near` (SKILL.md identical); a name match degrades to `likely`.
+				const entry = { local: local_view(skill), match: match_view(cand), differing_files: null, similarity: null }
+				if (via === 'hash') buckets.near.push(entry)
+				else buckets.likely.push(entry)
 			}
 		}
 
@@ -176,4 +282,4 @@ const semantic_match_view = (hit) => ({
 	score: typeof hit.score === 'number' ? hit.score : null,
 })
 
-module.exports = { run_funnel, DEFAULT_THRESHOLD, MANIFEST_CHUNK }
+module.exports = { run_funnel, DEFAULT_THRESHOLD, MANIFEST_CHUNK, MAX_VERSIONS_PER_REPO }

package/src/match/funnel.test.js

@@ -20,13 +20,23 @@ const skill = (over) => ({
 })
 const cand = (over) => ({ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote', skill_md_sha: 'h_skillmd', is_source_of_truth: true, ...over })
 
-// A deps double that records calls.
-const make_deps = ({ results = [], name_results = [], manifests = [], semantic = null } = {}) => {
-	const calls = { match: 0, manifests: 0, semantic: 0, blob: 0 }
+// A deps double that records calls. `versions` is auto-derived from the
+// provided manifests per repo (override with a { "ws/name": [vers] } map or a
+// flat array) so a test just lists the version manifests it wants scanned.
+const make_deps = ({ results = [], name_results = [], tree_results = [], manifests = [], versions = null, semantic = null } = {}) => {
+	const calls = { match: 0, manifests: 0, versions: 0, semantic: 0, blob: 0 }
+	const derive_versions = (ws, name) => {
+		if (Array.isArray(versions)) return versions
+		if (versions && typeof versions === 'object') return versions[`${String(ws).toLowerCase()}/${name}`] || versions[name] || []
+		return [...new Set(manifests
+			.filter(m => String(m.workspace).toLowerCase() === String(ws).toLowerCase() && m.name === name)
+			.map(m => m.version))]
+	}
 	return {
 		calls,
-		match: async () => { calls.match++; return [null, { results, name_results }] },
+		match: async () => { calls.match++; return [null, { results, name_results, tree_results }] },
 		manifests: async () => { calls.manifests++; return [null, { manifests, warnings: [] }] },
+		versions: async (ws, name) => { calls.versions++; return [null, derive_versions(ws, name)] },
 		...(semantic ? { semantic_search: async (q) => { calls.semantic++; return semantic(q) } } : {}),
 	}
 }
@@ -71,15 +81,18 @@ test('name-only match with low similarity (SKILL.md differs) → likely', async
 })
 
 test('name-only match above the threshold → near', async () => {
-	const local = skill({ skill_md_sha: 'h_local_only', files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }] })
+	// Above the threshold but NOT identical — one functional file differs (2 of 3
+	// match → 0.67). A truly identical manifest would (correctly) certify instead.
+	const local = skill({ skill_md_sha: 'h_local_only', files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }, { path: 'b.md', blob_sha: 'b_local' }] })
 	const deps = make_deps({
 		name_results: [{ name: 'webapp-testing', candidates: [cand({ skill_md_sha: 'h_other', tree_sha: 't_remote' })] }],
 		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
-			files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }] }],
+			files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }, { path: 'b.md', blob_sha: 'b_remote' }] }],
 	})
 	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
 	assert.equal(err, null)
 	assert.equal(out.buckets.near.length, 1)
+	assert.deepEqual(out.buckets.near[0].differing_files, ['b.md'])
 })
 
 test('no hash/name match, semantic hit → possible', async () => {
@@ -107,6 +120,52 @@ test('Stage 1 is ONE batched call regardless of skill count (no N+1)', async ()
 	assert.equal(deps.calls.match, 1, 'the whole folder resolves in one /repos:match call')
 })
 
+// ── Tier 1: cross-version tree probe (spec 260629-03 §4.8) ───────────────────
+
+test('local tree byte-identical to an OLDER published version → certified at that exact version', async () => {
+	// HEAD is 0.3.2 (a DIFFERENT tree — this is the drift the bug surfaced); the
+	// local copy is byte-identical to 0.3.0. The cross-version tree probe must
+	// pin it to 0.3.0 and certify it — NOT diff it against head and call it likely.
+	const local = skill({ name: 'tiny-gemini-image', skill_md_sha: 'h_old', tree_sha: 't_v030' })
+	const deps = make_deps({
+		// hash/name discovery still points at HEAD (head's tree differs from local)
+		name_results: [{ name: 'tiny-gemini-image', candidates: [cand({ name: 'tiny-gemini-image', version: '0.3.2', tree_sha: 't_v032', skill_md_sha: 'h_head' })] }],
+		tree_results: [{ tree_sha: 't_v030', candidates: [
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.0', tree_sha: 't_v030', skill_md_sha: 'h_old', is_source_of_truth: true, latest_version: '0.3.2' },
+		] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'an older byte-identical version is certified, not likely')
+	assert.equal(out.buckets.likely.length, 0)
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.certified[0].match.version, '0.3.0', 'pinned to the EXACT matching version, not head')
+	assert.equal(out.buckets.certified[0].match.latest_version, '0.3.2', 'carries the latest version so the caller can show "behind by"')
+	assert.equal(out.buckets.certified[0].match.is_latest, false)
+	assert.equal(deps.calls.manifests, 0, 'an exact tree match needs no manifest diff')
+})
+
+test('the local tree probe is sent in the SAME batched match call (no extra round-trip)', async () => {
+	const deps = make_deps({ tree_results: [{ tree_sha: 't_local', candidates: [
+		{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_local', is_source_of_truth: true, latest_version: '1.0.0' },
+	] }] })
+	const [err, out] = await run_funnel([skill(), skill({ dir: '/b' })], deps)
+	assert.equal(err, null)
+	assert.equal(deps.calls.match, 1, 'hashes + names + tree_shas all ride one /repos:match call')
+	assert.equal(out.buckets.certified.length, 2)
+	assert.equal(out.buckets.certified[0].match.is_latest, true, 'matching head is is_latest:true')
+})
+
+test('backward-compat: a server with no tree_results still certifies a head-identical skill', async () => {
+	// Older server returns no tree_results; the funnel falls back to head tree
+	// equality from the hash/name candidate so existing behavior is preserved.
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].match.version, '1.0.0')
+})
+
 test('a failed manifest batch becomes a warning, not a thrown error', async () => {
 	const deps = {
 		calls: {},
@@ -143,6 +202,163 @@ test('a semantic search that REJECTS still lands the skill in unmatched (never s
 	assert.ok(out.warnings.some(w => w.code === 'SEMANTIC_SEARCH_FAILED'))
 })
 
+// ── Metadata files & cross-version containment (spec 260629-03 §4.9/§4.10) ───
+
+test('functionally identical to head (only skill.json differs) → certified, no functional extras', async () => {
+	const local = skill({
+		files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'skill.json', blob_sha: 'b_sj_local' }],
+	})
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'skill.json', blob_sha: 'b_sj_remote' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'only skill.json differs → functional content identical → certified')
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.certified[0].match.version, '1.0.0')
+	assert.equal(out.buckets.certified[0].match.is_latest, true, 'matches head → is_latest')
+	assert.equal(out.buckets.certified[0].local_only_files, undefined, 'skill.json is ignored, not a functional extra')
+})
+
+test('CHANGELOG.md is also ignored — a CHANGELOG-only difference is still certified (case-insensitive)', async () => {
+	const local = skill({
+		files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'CHANGELOG.md', blob_sha: 'b_cl_local' }],
+	})
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'CHANGELOG.md', blob_sha: 'b_cl_remote' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].local_only_files, undefined)
+})
+
+test('a real (SKILL.md) difference is NOT certified even when skill.json also differs; differing_files excludes the ignored file', async () => {
+	// Name match (SKILL.md changed → different hash). skill.json ALSO differs, but
+	// it must not count: the reported difference is the real one (SKILL.md), and
+	// skill.json is filtered out of differing_files + the similarity denominator.
+	const local = skill({
+		skill_md_sha: 'h_local', tree_sha: 't_local',
+		files: [{ path: 'SKILL.md', blob_sha: 'x_local' }, { path: 'skill.json', blob_sha: 'sj_local' }, { path: 'a.md', blob_sha: 'shared' }],
+	})
+	const deps = make_deps({
+		name_results: [{ name: 'webapp-testing', candidates: [cand({ skill_md_sha: 'h_other', tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'x_remote' }, { path: 'skill.json', blob_sha: 'sj_remote' }, { path: 'a.md', blob_sha: 'shared' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 0, 'SKILL.md differs → real difference → not certified')
+	const entry = out.buckets.near[0] || out.buckets.likely[0]
+	assert.ok(entry, 'lands in near or likely')
+	assert.deepEqual(entry.differing_files, ['SKILL.md'], 'skill.json excluded from differing_files (it does not count)')
+})
+
+test('cross-version: local matches an OLDER version by SKILL.md + files → certified at that version, not head', async () => {
+	// Head 0.3.2 has a newer SKILL.md; the local content equals 0.3.1. It's a NAME
+	// match (local SKILL.md != head SKILL.md), so only the cross-version scan finds it.
+	const local = skill({
+		name: 'tiny-gemini-image', skill_md_sha: 'h_v031', tree_sha: 't_local',
+		files: [{ path: 'SKILL.md', blob_sha: 'md_v031' }, { path: 'references/x.md', blob_sha: 'ref_v031' }],
+	})
+	const deps = make_deps({
+		name_results: [{ name: 'tiny-gemini-image', candidates: [
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.2', tree_sha: 't_v032', skill_md_sha: 'md_v032', is_source_of_truth: true }] }],
+		manifests: [
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.2', tree_sha: 't_v032',
+				files: [{ path: 'SKILL.md', blob_sha: 'md_v032' }, { path: 'references/x.md', blob_sha: 'ref_v032' }, { path: 'skill.json', blob_sha: 'sj_032' }] },
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.1', tree_sha: 't_v031',
+				files: [{ path: 'SKILL.md', blob_sha: 'md_v031' }, { path: 'references/x.md', blob_sha: 'ref_v031' }, { path: 'skill.json', blob_sha: 'sj_031' }] },
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.0', tree_sha: 't_v030',
+				files: [{ path: 'SKILL.md', blob_sha: 'md_v030' }, { path: 'references/x.md', blob_sha: 'ref_v030' }, { path: 'skill.json', blob_sha: 'sj_030' }] },
+		],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'local content == v0.3.1 → certified')
+	assert.equal(out.buckets.near.length + out.buckets.likely.length, 0)
+	assert.equal(out.buckets.certified[0].match.version, '0.3.1', 'pinned to the exact older version its content matches')
+	assert.equal(out.buckets.certified[0].match.latest_version, '0.3.2')
+	assert.equal(out.buckets.certified[0].match.is_latest, false)
+})
+
+test('when content matches several versions (metadata-only re-releases), certify the EARLIEST (origin)', async () => {
+	// Local content is functionally identical to BOTH 1.5.0 and 1.5.1 (1.5.1 only
+	// bumped CHANGELOG/skill.json). Report 1.5.0 — where the content originated.
+	const local = skill({
+		name: 'update-doc', skill_md_sha: 'h_md', tree_sha: 't_local',
+		files: [{ path: 'SKILL.md', blob_sha: 'md' }, { path: 'references/x.md', blob_sha: 'ref' }],
+	})
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_md', candidates: [
+			{ workspace: 'nicolasdao', name: 'update-doc', version: '1.9.0', tree_sha: 't_head', skill_md_sha: 'h_md', is_source_of_truth: true }] }],
+		manifests: [
+			{ workspace: 'nicolasdao', name: 'update-doc', version: '1.5.1', tree_sha: 't_151',
+				files: [{ path: 'SKILL.md', blob_sha: 'md' }, { path: 'references/x.md', blob_sha: 'ref' }, { path: 'CHANGELOG.md', blob_sha: 'cl_151' }, { path: 'skill.json', blob_sha: 'sj_151' }] },
+			{ workspace: 'nicolasdao', name: 'update-doc', version: '1.5.0', tree_sha: 't_150',
+				files: [{ path: 'SKILL.md', blob_sha: 'md' }, { path: 'references/x.md', blob_sha: 'ref' }, { path: 'CHANGELOG.md', blob_sha: 'cl_150' }, { path: 'skill.json', blob_sha: 'sj_150' }] },
+		],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].match.version, '1.5.0', 'both 1.5.0 and 1.5.1 match → report the earliest (origin)')
+	assert.equal(out.buckets.certified[0].match.latest_version, '1.9.0')
+	assert.equal(out.buckets.certified[0].match.is_latest, false)
+})
+
+test('dirt tolerance: local has an extra __pycache__/*.pyc (and no skill.json) → certified, with local_only_files', async () => {
+	const local = skill({
+		name: 'init-doc', skill_md_sha: 'h_md', tree_sha: 't_local',
+		files: [
+			{ path: 'SKILL.md', blob_sha: 'md1' },
+			{ path: 'scripts/build.py', blob_sha: 'py1' },
+			{ path: 'scripts/__pycache__/build.cpython-310.pyc', blob_sha: 'pyc1' }, // local dirt
+		],
+	})
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_md', candidates: [cand({ name: 'init-doc', tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'init-doc', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'md1' }, { path: 'scripts/build.py', blob_sha: 'py1' }, { path: 'skill.json', blob_sha: 'sj1' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'catalog functional files ⊆ local → certified despite the extra .pyc')
+	assert.equal(out.buckets.near.length, 0)
+	assert.deepEqual(out.buckets.certified[0].local_only_files, ['scripts/__pycache__/build.cpython-310.pyc'])
+})
+
+test('a local copy MISSING one of the version files is NOT certified (containment fails)', async () => {
+	const local = skill({
+		name: 'partial', skill_md_sha: 'h_md', tree_sha: 't_local',
+		files: [{ path: 'SKILL.md', blob_sha: 'md1' }], // missing references/x.md the version ships
+	})
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_md', candidates: [cand({ name: 'partial', tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'partial', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'md1' }, { path: 'references/x.md', blob_sha: 'ref1' }, { path: 'skill.json', blob_sha: 'sj1' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 0, 'missing a functional file → not fully contained → not certified')
+	assert.equal(out.buckets.near.length + out.buckets.likely.length, 1)
+})
+
+test('diff_manifests with an ignore predicate excludes ignored files from the functional diff + similarity', () => {
+	const d = diff_manifests(
+		[{ path: 'SKILL.md', blob_sha: 'a' }, { path: 'skill.json', blob_sha: 'v1' }, { path: 'keep', blob_sha: 'k' }],
+		[{ path: 'SKILL.md', blob_sha: 'a' }, { path: 'skill.json', blob_sha: 'v2' }, { path: 'keep', blob_sha: 'k' }],
+		{ ignore: (p) => p.toLowerCase() === 'skill.json' },
+	)
+	assert.deepEqual(d.differing, [], 'skill.json excluded → no functional differences')
+	assert.deepEqual(d.ignored_differing, ['skill.json'])
+	assert.equal(d.similarity, 1, 'similarity computed over functional files only (2/2 identical)')
+})
+
 test('diff_manifests classifies identical / modified / added / removed', () => {
 	const d = diff_manifests(
 		[{ path: 'SKILL.md', blob_sha: 'a' }, { path: 'keep', blob_sha: 'k' }, { path: 'local-only', blob_sha: 'z' }],