happyskills 1.13.0 → 1.14.0

package/src/constants.js

@@ -51,6 +51,7 @@ const COMMANDS = [
 	'visibility',
 	'list',
 	'search',
+	'match',
 	'resolve',
 	'star',
 	'unstar',

package/src/match/diff.js

@@ -0,0 +1,41 @@
+'use strict'
+// Manifest diff (spec 260629-03 §4.7). Joins a local manifest against a catalog
+// manifest on `path` with ZERO blob downloads — both sides are just
+// [{ 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").
+
+// local_files / catalog_files: [{ path, blob_sha }]
+const diff_manifests = (local_files, catalog_files) => {
+	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()])
+
+	const identical = []
+	const modified = []
+	const added = []   // present locally, absent in the catalog skill
+	const removed = [] // present in the catalog skill, absent locally
+
+	for (const p of all) {
+		const l = local.get(p)
+		const c = catalog.get(p)
+		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
+	const similarity = total === 0 ? 1 : identical.length / total
+	const differing = [...modified, ...added, ...removed].sort()
+
+	return {
+		similarity,
+		identical: identical.sort(),
+		modified: modified.sort(),
+		added: added.sort(),
+		removed: removed.sort(),
+		differing,
+	}
+}
+
+module.exports = { diff_manifests }

package/src/match/funnel.js

@@ -0,0 +1,179 @@
+'use strict'
+// The match funnel + tier classification (spec 260629-03 §4.7).
+//
+// 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`.
+//
+// Closed tier set: certified · near · likely · possible · unmatched.
+
+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`.
+const DEFAULT_THRESHOLD = 0.5
+// Mirror of the server cap (MATCH_MAX_MANIFESTS) so we chunk manifest requests.
+const MANIFEST_CHUNK = 50
+
+const key_of = (c) => `${String(c.workspace).toLowerCase()}/${c.name}@${c.version}`
+
+const local_view = (skill) => ({
+	name: skill.name,
+	dir: skill.dir,
+	file_count: skill.file_count,
+	skill_md_sha: skill.skill_md_sha,
+	tree_sha: skill.tree_sha,
+})
+
+const match_view = (c) => ({
+	workspace: c.workspace,
+	name: c.name,
+	version: c.version,
+	tree_sha: c.tree_sha,
+	is_source_of_truth: !!c.is_source_of_truth,
+})
+
+// deps: { match(hashes,names), manifests(repo_versions), semantic_search?(query) }
+// opts: { threshold, concurrency }
+const run_funnel = (skills, deps, opts = {}) =>
+	catch_errors('Match funnel failed', async () => {
+		const threshold = typeof opts.threshold === 'number' ? opts.threshold : DEFAULT_THRESHOLD
+		const concurrency = opts.concurrency || DEFAULT_CONCURRENCY
+		const buckets = { certified: [], near: [], likely: [], possible: [], unmatched: [] }
+		const warnings = []
+
+		if (!skills.length) return { buckets, warnings }
+
+		// ── 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)
+		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 || []]))
+
+		// ── 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()
+
+		for (const skill of skills) {
+			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) })
+				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' })
+				continue
+			}
+			none.push(skill)
+		}
+
+		// ── Stage 3: bounded manifest fetch (chunked to the server cap) ──────
+		const manifest_by_key = new Map()
+		const needs = [...manifest_needs.values()]
+		if (needs.length) {
+			const chunks = []
+			for (let i = 0; i < needs.length; i += MANIFEST_CHUNK) chunks.push(needs.slice(i, i + MANIFEST_CHUNK))
+			const results = await bounded(chunks.map(chunk => () => deps.manifests(chunk)), concurrency)
+			for (const r of results) {
+				if (r && r.error) { warnings.push({ code: 'MANIFEST_FETCH_FAILED', message: String((r.error && r.error.message) || r.error) }); continue }
+				const [err, data] = r || [null, null]
+				if (err || !data) { warnings.push({ code: 'MANIFEST_FETCH_FAILED', message: 'A manifest batch could not be fetched.' }); continue }
+				for (const m of (data.manifests || [])) manifest_by_key.set(key_of(m), m)
+				for (const w of (data.warnings || [])) warnings.push(w)
+			}
+		}
+
+		// ── finalize the hash/name candidates with their diffs ───────────────
+		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,
+			}
+			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)
+			} else {
+				buckets.likely.push(entry)
+			}
+		}
+
+		// ── Stage 4: semantic fallback for the rest (bounded) ────────────────
+		// deps.semantic_search returns the api-client tuple [err, hits] (hits is
+		// an array, or { results: [...] }); a failure degrades the skill to
+		// `unmatched` with a surfaced warning — never a silent drop.
+		if (none.length && typeof deps.semantic_search === 'function') {
+			// The thunk ALWAYS resolves (carrying its skill), so a search that
+			// rejects can't strand the skill — it still lands in `unmatched` with a
+			// surfaced warning, never silently dropped from `data`.
+			const results = await bounded(
+				none.map(skill => () =>
+					deps.semantic_search(skill.name).then(res => ({ skill, res })).catch(error => ({ skill, error }))),
+				concurrency
+			)
+			for (const r of results) {
+				const { skill, res, error } = r || {}
+				if (!skill) continue // defensive: bounded never yields a bare {error} here
+				const tuple_err = Array.isArray(res) ? res[0] : null
+				if (error || tuple_err) {
+					warnings.push({ code: 'SEMANTIC_SEARCH_FAILED', message: String((error && error.message) || 'A semantic lookup failed.') })
+					buckets.unmatched.push({ local: local_view(skill) })
+					continue
+				}
+				const data = Array.isArray(res) ? res[1] : res
+				const hits = Array.isArray(data) ? data : (data && Array.isArray(data.results) ? data.results : [])
+				if (hits[0]) buckets.possible.push({ local: local_view(skill), match: semantic_match_view(hits[0]) })
+				else buckets.unmatched.push({ local: local_view(skill) })
+			}
+		} else {
+			for (const skill of none) buckets.unmatched.push({ local: local_view(skill) })
+		}
+
+		return { buckets, warnings }
+	})
+
+// A semantic hit shape varies by search response; normalize the fields the
+// match report cares about, leaving missing ones null.
+const semantic_match_view = (hit) => ({
+	workspace: hit.workspace_slug || hit.workspace || null,
+	name: hit.name || null,
+	version: hit.version || null,
+	score: typeof hit.score === 'number' ? hit.score : null,
+})
+
+module.exports = { run_funnel, DEFAULT_THRESHOLD, MANIFEST_CHUNK }

package/src/match/funnel.test.js

@@ -0,0 +1,157 @@
+'use strict'
+// Spec 260629-03 §4.7 — the match funnel + tier classification. Network is
+// mocked (deps injected). The four "done when" guarantees:
+//   - identical → certified with ZERO blob fetches (the funnel never fetches
+//     blob content at all; classification is hash/tree/manifest only)
+//   - LICENSE-only diff → near, listing LICENSE as the sole differing file
+//   - SKILL.md differs (name-only, low similarity) → demoted to likely
+//   - semantic-only → possible
+
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { run_funnel } = require('./funnel')
+const { diff_manifests } = require('./diff')
+
+const skill = (over) => ({
+	name: 'webapp-testing', dir: '/local/webapp-testing', file_count: 2,
+	skill_md_sha: 'h_skillmd', tree_sha: 't_local',
+	files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'LICENSE', blob_sha: 'b_lic_local' }],
+	...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 }
+	return {
+		calls,
+		match: async () => { calls.match++; return [null, { results, name_results }] },
+		manifests: async () => { calls.manifests++; return [null, { manifests, warnings: [] }] },
+		...(semantic ? { semantic_search: async (q) => { calls.semantic++; return semantic(q) } } : {}),
+	}
+}
+
+test('identical content → certified, with zero manifest/blob fetches', async () => {
+	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.workspace, 'anthropics')
+	assert.equal(deps.calls.manifests, 0, 'certified needs no manifest fetch')
+	assert.equal(deps.calls.blob, 0, 'the funnel never fetches blob content')
+})
+
+test('hash match, only LICENSE differs → near, listing LICENSE as the sole differing file', async () => {
+	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: 'LICENSE', blob_sha: 'b_lic_remote' }] }],
+	})
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 0)
+	assert.equal(out.buckets.near.length, 1)
+	assert.deepEqual(out.buckets.near[0].differing_files, ['LICENSE'])
+	assert.equal(deps.calls.manifests, 1)
+})
+
+test('name-only match with low similarity (SKILL.md differs) → likely', async () => {
+	// No hash candidate; a name candidate whose manifest shares almost nothing.
+	const local = skill({ skill_md_sha: 'h_local_only', tree_sha: 't_local', files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'x2' }] })
+	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: 'y1' }, { path: 'b.md', blob_sha: 'y2' }, { path: 'c.md', blob_sha: 'y3' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
+	assert.equal(err, null)
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.likely.length, 1)
+	assert.equal(out.buckets.likely[0].match.name, 'webapp-testing')
+})
+
+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' }] })
+	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' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
+	assert.equal(err, null)
+	assert.equal(out.buckets.near.length, 1)
+})
+
+test('no hash/name match, semantic hit → possible', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({ semantic: async () => [null, [{ workspace_slug: 'someone', name: 'similar-thing', version: '2.1.0', score: 0.7 }]] })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.possible.length, 1)
+	assert.equal(out.buckets.possible[0].match.workspace, 'someone')
+	assert.equal(deps.calls.semantic, 1)
+})
+
+test('no match at all (no semantic dep) → unmatched', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({}) // no semantic_search
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.unmatched.length, 1)
+	assert.equal(out.buckets.possible.length, 0)
+})
+
+test('Stage 1 is ONE batched call regardless of skill count (no N+1)', async () => {
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	await run_funnel([skill(), skill({ dir: '/b' }), skill({ dir: '/c' })], deps)
+	assert.equal(deps.calls.match, 1, 'the whole folder resolves in one /repos:match call')
+})
+
+test('a failed manifest batch becomes a warning, not a thrown error', async () => {
+	const deps = {
+		calls: {},
+		match: async () => [null, { results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_remote' })] }], name_results: [] }],
+		manifests: async () => { throw new Error('network boom') },
+	}
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null, 'one bad batch does not abort the run')
+	assert.ok(out.warnings.some(w => w.code === 'MANIFEST_FETCH_FAILED'))
+	// hash match still lands in near, just without a differing-file list.
+	assert.equal(out.buckets.near.length, 1)
+	assert.equal(out.buckets.near[0].differing_files, null)
+})
+
+test('certified is tree-SHA equality even via a NAME match (skill has no SKILL.md → null hash)', async () => {
+	// A skill.json-only local skill (no SKILL.md) → skill_md_sha null, so it can
+	// only be found by name — but if its tree is byte-identical it is still certified.
+	const local = skill({ name: 'no-skillmd', skill_md_sha: null, tree_sha: 't_local', files: [{ path: 'skill.json', blob_sha: 'sj' }] })
+	const deps = make_deps({ name_results: [{ name: 'no-skillmd', candidates: [cand({ name: 'no-skillmd', tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'byte-identical (tree equal) is certified even when matched by name')
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.likely.length, 0)
+})
+
+test('a semantic search that REJECTS still lands the skill in unmatched (never silently dropped)', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({ semantic: async () => { throw new Error('search exploded') } })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null, 'a rejecting semantic lookup does not abort the run')
+	assert.equal(out.buckets.unmatched.length, 1, 'the skill is reported as unmatched, not dropped from data')
+	assert.equal(out.buckets.unmatched[0].local.name, 'novel-skill')
+	assert.ok(out.warnings.some(w => w.code === 'SEMANTIC_SEARCH_FAILED'))
+})
+
+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' }],
+		[{ path: 'SKILL.md', blob_sha: 'b' }, { path: 'keep', blob_sha: 'k' }, { path: 'remote-only', blob_sha: 'r' }],
+	)
+	assert.deepEqual(d.modified, ['SKILL.md'])
+	assert.deepEqual(d.identical, ['keep'])
+	assert.deepEqual(d.added, ['local-only'])
+	assert.deepEqual(d.removed, ['remote-only'])
+	assert.deepEqual(d.differing, ['SKILL.md', 'local-only', 'remote-only'].sort())
+	assert.equal(d.similarity, 1 / 4)
+})

package/src/match/scanner.js

@@ -0,0 +1,129 @@
+'use strict'
+// Local skill scanner + fileset normalization (spec 260629-03 §4.6).
+//
+// Walks a folder, discovers each skill (a dir containing SKILL.md and/or
+// skill.json), and fingerprints it the SAME way the publish path does — so the
+// locally-computed tree_sha lines up byte-for-byte with the catalog's stored
+// tree_sha and a byte-identical skill matches as `certified`.
+//
+// Normalization is the #1 correctness risk (spec §6 #2): a globally-installed
+// skill carries install cruft (.DS_Store, .git, agent lock files) and is often
+// a symlink (multi-agent installs share one copy). If the local fileset differs
+// from what the push path includes, the tree_sha never matches and identical
+// skills look "different". So we reuse `collect_files` / the EXCLUDE rules the
+// push path uses, and we resolve symlinked skill roots to their real content.
+
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { collect_files } = require('../utils/file_collector')
+const { hash_tree } = require('../utils/git_hash')
+
+const has_manifest = (dir) =>
+	fs.existsSync(path.join(dir, 'SKILL.md')) || fs.existsSync(path.join(dir, 'skill.json'))
+
+// Directories we never descend into while hunting for skill roots — the same
+// install/VCS cruft the push fileset excludes, plus any dotdir.
+const SKIP_DIRS = new Set(['node_modules', '.git'])
+
+// Discover skill roots under `root`. A skill root is the FIRST directory on a
+// path that has a SKILL.md/skill.json — we do NOT descend past it, so a skill's
+// own references/ subdir is never mistaken for a separate skill. `fs.statSync`
+// follows symlinks, so a symlinked skill dir (the multi-agent install case)
+// resolves to its real target; we dedupe by realpath so a symlink + its target
+// don't both count.
+const find_skill_roots = (root) => {
+	const roots = []
+	const seen_real = new Set()
+
+	const add = (dir) => {
+		let real
+		try { real = fs.realpathSync(dir) } catch { real = dir }
+		if (seen_real.has(real)) return
+		seen_real.add(real)
+		roots.push(dir)
+	}
+
+	const walk = (dir) => {
+		if (has_manifest(dir)) { add(dir); return }
+		let entries
+		try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+		for (const ent of entries) {
+			if (SKIP_DIRS.has(ent.name) || ent.name.startsWith('.')) continue
+			const full = path.join(dir, ent.name)
+			let st
+			try { st = fs.statSync(full) } catch { continue } // follows symlinks; skip broken
+			if (st.isDirectory()) walk(full)
+		}
+	}
+
+	walk(root)
+	return roots
+}
+
+// Read the skill's declared name from skill.json (the field the catalog matches
+// on); fall back to the directory basename when absent or unreadable.
+const read_skill_name = (skill_dir) => {
+	const fallback = path.basename(skill_dir)
+	try {
+		const raw = fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf8')
+		const json = JSON.parse(raw)
+		return (json && typeof json.name === 'string' && json.name.trim()) ? json.name.trim() : fallback
+	} catch {
+		return fallback
+	}
+}
+
+// Fingerprint one skill root into the shape the funnel consumes.
+const fingerprint_skill = (skill_dir) =>
+	catch_errors(`Failed to fingerprint skill at ${skill_dir}`, async () => {
+		const [err, files] = await collect_files(skill_dir)
+		if (err) throw e(`Failed to read skill files at ${skill_dir}`, err)
+
+		// Normalize separators to '/' so the fingerprint is identical to the
+		// stored (POSIX-path) tree regardless of the host OS.
+		const norm = files.map(f => ({ path: f.path.split(path.sep).join('/'), blob_sha: f.sha }))
+
+		// Manifest: [{ path, blob_sha }], sorted for stable comparison/diff.
+		const manifest = norm
+			.map(f => ({ path: f.path, blob_sha: f.blob_sha }))
+			.sort((a, b) => a.path.localeCompare(b.path))
+
+		// skill_md_sha = the blob hash of the ROOT SKILL.md (case-insensitive
+		// match, exactly like the server's compute_skill_md_sha). Null when the
+		// skill has no SKILL.md (it can then only name/semantic-match).
+		const skill_md_entry = manifest.find(f => f.path.toLowerCase() === 'skill.md')
+		const skill_md_sha = skill_md_entry ? skill_md_entry.blob_sha : null
+
+		// tree_sha = the whole-skill fingerprint, computed with the EXACT server
+		// algorithm (git_hash.hash_tree mirrors api/app/utils/git_objects).
+		const tree_sha = hash_tree(norm.map(f => ({ path: f.path, sha: f.blob_sha })))
+
+		return {
+			dir: skill_dir,
+			name: read_skill_name(skill_dir),
+			skill_md_sha,
+			tree_sha,
+			files: manifest,
+			file_count: manifest.length,
+		}
+	})
+
+// Scan a folder → fingerprints for every skill found. Returns
+// { skills: [...], errored: [{ dir, error }] } — a single unreadable skill never
+// aborts the scan (CLAUDE.md no-silent-failures: failures are surfaced, not
+// dropped).
+const scan_folder = (folder) =>
+	catch_errors(`Failed to scan folder ${folder}`, async () => {
+		const roots = find_skill_roots(folder)
+		const skills = []
+		const errored = []
+		for (const dir of roots) {
+			const [err, skill] = await fingerprint_skill(dir)
+			if (err) errored.push({ dir, error: err })
+			else skills.push(skill)
+		}
+		return { skills, errored }
+	})
+
+module.exports = { scan_folder, fingerprint_skill, find_skill_roots, has_manifest, read_skill_name }

package/src/match/scanner.test.js

@@ -0,0 +1,93 @@
+'use strict'
+// Spec 260629-03 §4.6 — local skill scanner + fileset normalization.
+//
+// The load-bearing assertion (§6 #2): the scanner's locally-computed tree_sha
+// must equal what the PUSH path produces for the same content — otherwise a
+// byte-identical skill shows as "different" and the `certified` tier is broken.
+// We prove that by computing the expected tree_sha/skill_md_sha with the
+// SERVER's canonical git_objects (imported across the monorepo), independent of
+// the CLI's mirror. We also prove cruft (.DS_Store) is excluded and a symlinked
+// skill resolves to its real content (deduped).
+
+const { test, before, after } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { scan_folder, find_skill_roots, fingerprint_skill } = require('./scanner')
+// The canonical server algorithm — the reference the CLI mirror must match.
+const { hash_tree: canon_tree, hash_blob: canon_blob } = require('../../../api/app/utils/git_objects')
+
+let root
+const w = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content) }
+
+before(() => {
+	root = fs.mkdtempSync(path.join(os.tmpdir(), 'match-scan-'))
+
+	// alpha — a clean skill: SKILL.md + a nested reference file.
+	w(path.join(root, 'skills/alpha/SKILL.md'), '# Alpha\nDoes alpha things.\n')
+	w(path.join(root, 'skills/alpha/references/guide.md'), 'detailed guide\n')
+	w(path.join(root, 'skills/alpha/skill.json'), JSON.stringify({ name: 'alpha-skill', version: '1.0.0', type: 'skill' }))
+
+	// beta — carries install cruft that MUST be excluded from the fingerprint.
+	w(path.join(root, 'skills/beta/SKILL.md'), '# Beta\n')
+	w(path.join(root, 'skills/beta/.DS_Store'), 'macos cruft\n')
+
+	// gamma-real + a symlink to it — the multi-agent install shape.
+	w(path.join(root, 'links/gamma-real/SKILL.md'), '# Gamma\n')
+	w(path.join(root, 'links/gamma-real/extra.txt'), 'x\n')
+	fs.symlinkSync(path.join(root, 'links/gamma-real'), path.join(root, 'links/gamma'), 'dir')
+})
+
+after(() => { try { fs.rmSync(root, { recursive: true, force: true }) } catch {} })
+
+// Expected fingerprint computed from a known fileset using the SERVER algorithm.
+// canon_tree returns { sha, buffer } — we compare the hex sha.
+const expected_tree = (entries) => canon_tree(entries.map(en => ({ path: en.path, sha: canon_blob(Buffer.from(en.content)) }))).sha
+
+test('discovers each skill root and does not descend past it (references/ is not a separate skill)', () => {
+	const roots = find_skill_roots(path.join(root, 'skills'))
+	const names = roots.map(r => path.basename(r)).sort()
+	assert.deepEqual(names, ['alpha', 'beta'])
+})
+
+test('alpha: tree_sha + skill_md_sha equal the values the PUSH path would produce (server algorithm)', async () => {
+	const [err, skill] = await fingerprint_skill(path.join(root, 'skills/alpha'))
+	assert.equal(err, null)
+	assert.equal(skill.name, 'alpha-skill', 'name comes from skill.json')
+
+	const files = [
+		{ path: 'SKILL.md', content: '# Alpha\nDoes alpha things.\n' },
+		{ path: 'references/guide.md', content: 'detailed guide\n' },
+		{ path: 'skill.json', content: JSON.stringify({ name: 'alpha-skill', version: '1.0.0', type: 'skill' }) },
+	]
+	assert.equal(skill.tree_sha, expected_tree(files), 'CLI tree_sha must match the server hash_tree byte-for-byte')
+	assert.equal(skill.skill_md_sha, canon_blob(Buffer.from('# Alpha\nDoes alpha things.\n')), 'skill_md_sha = git-blob hash of SKILL.md')
+	assert.deepEqual([...skill.files.map(f => f.path)].sort(), ['SKILL.md', 'references/guide.md', 'skill.json'].sort())
+})
+
+test('beta: .DS_Store cruft is excluded from the manifest and the tree_sha', async () => {
+	const [err, skill] = await fingerprint_skill(path.join(root, 'skills/beta'))
+	assert.equal(err, null)
+	assert.ok(!skill.files.some(f => f.path.includes('.DS_Store')), '.DS_Store must not be in the manifest')
+	// tree_sha matches a tree of ONLY SKILL.md — proving the cruft never entered the hash.
+	assert.equal(skill.tree_sha, expected_tree([{ path: 'SKILL.md', content: '# Beta\n' }]))
+})
+
+test('a symlinked skill resolves to real content and is counted once (dedupe by realpath)', async () => {
+	const [err, result] = await scan_folder(path.join(root, 'links'))
+	assert.equal(err, null)
+	assert.equal(result.skills.length, 1, 'symlink + its target must not both count')
+	assert.equal(result.skills[0].tree_sha, expected_tree([
+		{ path: 'SKILL.md', content: '# Gamma\n' },
+		{ path: 'extra.txt', content: 'x\n' },
+	]), 'fingerprint reflects the real (symlink-followed) content')
+})
+
+test('scan_folder surfaces all skills with no false errors', async () => {
+	const [err, result] = await scan_folder(path.join(root, 'skills'))
+	assert.equal(err, null)
+	assert.equal(result.skills.length, 2)
+	assert.equal(result.errored.length, 0)
+})

package/src/utils/concurrency.js

@@ -0,0 +1,28 @@
+'use strict'
+// Bounded-concurrency wrapper over core-async's `throttle` — the ONE place the
+// match pipeline (and any future fan-out) imports concurrency from (spec
+// 260629-03 §4.5). `throttle` keeps at most `limit` task thunks in flight and
+// pulls the next the instant a slot frees (no fixed-batch head-of-line
+// blocking). Crucially, a FAILED task resolves to `{ error }` instead of
+// throwing — so one bad skill never aborts the whole scan. Callers MUST
+// partition the `{ error }` results and surface them (never drop them silently
+// — CLAUDE.md no-silent-failures).
+//
+// Bounded concurrency is also rate-limit safety: an unbounded fan-out of ~70
+// manifest/blob fetches can trip the API RateLimited alarm (see memory
+// project_rate_limit_observability_and_nudge). Keep the default modest.
+
+const { throttle } = require('core-async')
+
+const DEFAULT_CONCURRENCY = 6
+
+// Deliberately NOT catch_errors-wrapped: it returns throttle's results array
+// verbatim (order-preserving; a failed task is `{ error }`, not a throw) so
+// callers keep the per-task error partition. Wrapping it would collapse that to
+// a single [errors, result] and lose which task failed.
+const bounded = (tasks, limit = DEFAULT_CONCURRENCY) => {
+	const n = Number.isInteger(limit) && limit > 0 ? limit : DEFAULT_CONCURRENCY
+	return throttle(Array.isArray(tasks) ? tasks : [], n)
+}
+
+module.exports = { bounded, DEFAULT_CONCURRENCY }