@dzhechkov/harness-core 0.3.129 → 0.3.131

package/dist/skills-verify.js

@@ -0,0 +1,645 @@
+/**
+ * `dz skills-verify` — does a project's `.claude/skills/` actually REGISTER?
+ *
+ * Origin (feature skills-verify, ADR-001): `@dzhechkov/health-advisor` 1.2.0 shipped to npm with zero
+ * skills registering while its layout test was green — the test asserted a PROXY (files on disk), not
+ * the PROPERTY (registration). This module makes the property observable.
+ *
+ * Two layers:
+ *   L1 `scanSkillsLayout`  — instant, no Claude session: which names CAN register, plus the three
+ *                            layout shapes that produced the 1.2.0 defect.
+ *   L2 `parseInitFacts`    — the authoritative listing, parsed from the `system/init` event of
+ *      + `classifyRegistration`  `claude -p --output-format stream-json --verbose`. No model prose.
+ *
+ * FAIL-CLOSED: anything that prevents an honest observation yields `inconclusive`, never `pass`.
+ */
+import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+const MAX_BURIED_DEPTH = 4; // enough to catch extended/<name>/SKILL.md without walking the world
+function findBuriedSkillMd(dir, depth, acc, errors) {
+    if (depth > MAX_BURIED_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (error) {
+        // A subtree we cannot read is unknown territory, not proven-clean territory (QE2 #1).
+        errors.push(`cannot read ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    for (const name of entries) {
+        if (name === 'node_modules' || name === '__pycache__' || name.startsWith('.'))
+            continue;
+        const full = join(dir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch (error) {
+            errors.push(`cannot stat ${full}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (isDir) {
+            findBuriedSkillMd(full, depth + 1, acc, errors);
+        }
+        else if (name === 'SKILL.md' && depth >= 2) {
+            acc.push(full);
+        }
+    }
+}
+function hasPluginManifest(dir) {
+    return existsSync(join(dir, '.claude-plugin', 'plugin.json'));
+}
+/**
+ * Does this directory look like it was INTENDED as a skill? A dir with no markdown at all is
+ * ordinary content (`scripts/`, `bin/`, `templates/`) — calling it a failed skill is a false FAIL
+ * (Codex QE5 #7). MEASURED: naively flagging every dir marked ~40 healthy directories across 9
+ * npx-toolkit packages (reproducer: the pack survey in features/skills-verify/08_qe_report.md).
+ */
+export function looksLikeSkillDir(dir) {
+    const walk = (d, depth) => {
+        if (depth > 2)
+            return false;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return false;
+        }
+        for (const name of entries) {
+            if (name.startsWith('.') || name === 'node_modules')
+                continue;
+            const full = join(d, name);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                // A DIRECTORY named SKILL.md is a botched skill file, not ordinary content — clear intent.
+                if (name === 'SKILL.md')
+                    return true;
+                if (walk(full, depth + 1))
+                    return true;
+            }
+            else if (name.toLowerCase().endsWith('.md')) {
+                return true;
+            }
+        }
+        return false;
+    };
+    return walk(dir, 1);
+}
+/**
+ * A directory registers only if `SKILL.md` is a regular FILE. `existsSync` also answers true for a
+ * DIRECTORY named SKILL.md, which registers nothing yet suppressed every other check (QE2 #4).
+ */
+function hasSkillFile(dir) {
+    try {
+        return statSync(join(dir, 'SKILL.md')).isFile();
+    }
+    catch {
+        return false; // ENOENT, or a dangling symlink: either way it cannot register
+    }
+}
+/**
+ * Walk `<projectDir>/.claude/skills/` and report what can register and what cannot.
+ * Deterministic, needs no Claude session — safe for CI.
+ */
+export function scanSkillsLayout(projectDir) {
+    const skillsRoot = join(resolve(projectDir), '.claude', 'skills');
+    // `existsSync` also answers false for a DANGLING SYMLINK — that is a broken tree, not an absent
+    // one, and must not scan as "clean" (QE2 #1). lstat distinguishes the two.
+    let rootLink = null;
+    try {
+        rootLink = lstatSync(skillsRoot);
+    }
+    catch (error) {
+        // Only ENOENT means "genuinely absent". ENOTDIR/EACCES mean the tree is BROKEN or unreadable —
+        // reporting that as an empty-and-clean project is a route to a false PASS (QE3 #3).
+        const code = error.code;
+        if (code !== 'ENOENT') {
+            return {
+                skillsRoot, projectDir: resolve(projectDir), exists: true, registrable: [], findings: [], advisories: [], containers: [],
+                scanError: `cannot stat ${skillsRoot}: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        // ENOENT on .claude/skills can also mean .claude itself is a FILE or unreadable — check it.
+        const claudeDir = join(resolve(projectDir), '.claude');
+        try {
+            const st = lstatSync(claudeDir);
+            // A SYMLINK must be followed: a dangling `.claude` link is a broken tree, not an absent one.
+            if (st.isSymbolicLink() && !existsSync(claudeDir)) {
+                return {
+                    skillsRoot, projectDir: resolve(projectDir), exists: true, registrable: [], findings: [], advisories: [], containers: [],
+                    scanError: `${claudeDir} is a dangling symlink`,
+                };
+            }
+            if (!st.isDirectory() && !st.isSymbolicLink()) {
+                return {
+                    skillsRoot, projectDir: resolve(projectDir), exists: true, registrable: [], findings: [], advisories: [], containers: [],
+                    scanError: `${claudeDir} is not a directory`,
+                };
+            }
+        }
+        catch (claudeError) {
+            const cCode = claudeError.code;
+            if (cCode !== 'ENOENT') {
+                return {
+                    skillsRoot, projectDir: resolve(projectDir), exists: true, registrable: [], findings: [], advisories: [], containers: [],
+                    scanError: `cannot stat ${claudeDir}: ${claudeError instanceof Error ? claudeError.message : String(claudeError)}`,
+                };
+            }
+        }
+        return { skillsRoot, projectDir: resolve(projectDir), exists: false, registrable: [], findings: [], advisories: [], containers: [] }; // genuinely absent
+    }
+    if (rootLink.isSymbolicLink() && !existsSync(skillsRoot)) {
+        return {
+            skillsRoot,
+            projectDir: resolve(projectDir),
+            exists: true,
+            registrable: [],
+            findings: [],
+            advisories: [],
+            containers: [],
+            scanError: `${skillsRoot} is a dangling symlink`,
+        };
+    }
+    // `.claude/skills` must BE a directory. A file there scans as "empty and clean" otherwise (QE #4).
+    try {
+        if (!statSync(skillsRoot).isDirectory()) {
+            return { skillsRoot, projectDir: resolve(projectDir), exists: true, registrable: [], findings: [], advisories: [], containers: [], scanError: `${skillsRoot} is not a directory` };
+        }
+    }
+    catch (error) {
+        return {
+            skillsRoot,
+            projectDir: resolve(projectDir),
+            exists: true,
+            registrable: [],
+            findings: [],
+            advisories: [],
+            containers: [],
+            scanError: `cannot stat ${skillsRoot}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const registrable = [];
+    const findings = [];
+    const advisories = [];
+    const containers = [];
+    const scanErrors = [];
+    let entries = [];
+    try {
+        entries = readdirSync(skillsRoot);
+    }
+    catch (error) {
+        // An unreadable root is NOT an empty project — say so, so the verdict can be inconclusive.
+        return {
+            skillsRoot,
+            projectDir: resolve(projectDir),
+            exists: true,
+            registrable: [],
+            findings: [],
+            advisories: [],
+            containers: [],
+            scanError: `cannot read ${skillsRoot}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue; // hidden/backup dirs are not skills
+        const dir = join(skillsRoot, name);
+        let isDir = false;
+        try {
+            isDir = statSync(dir).isDirectory();
+        }
+        catch (error) {
+            // An entry we cannot stat is unknown, not absent — record it so the verdict stays honest.
+            scanErrors.push(`cannot stat ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (!isDir) {
+            // A SKILL.md dropped directly into .claude/skills/ registers nothing — it is a real defect,
+            // not something to skip silently (QE #4).
+            if (name === 'SKILL.md') {
+                findings.push({
+                    dir: '.',
+                    kind: 'no-skill-md',
+                    detail: 'SKILL.md sits directly in .claude/skills/ — a skill must live in its own directory to register',
+                });
+            }
+            continue;
+        }
+        const registers = hasSkillFile(dir);
+        // A manifest-backed CONTAINER (`<dir>/.claude-plugin/plugin.json`) is a plugin-shaped layout.
+        // It did not register in measured practice, but the class may be supported under workspace
+        // trust — so the WHOLE container is advisory. Emitting the generic `no-skill-md` /
+        // `buried-skill-md` findings for it killed the layout anyway, which was the over-claim (QE4 #1).
+        const isPluginContainer = !registers && hasPluginManifest(dir);
+        const bucket = isPluginContainer ? advisories : findings;
+        if (registers) {
+            registrable.push(name);
+        }
+        else {
+            // A dir with no markdown was never meant to be a skill — advisory, not a failure (QE5 #7).
+            const intended = looksLikeSkillDir(dir);
+            (isPluginContainer || !intended ? advisories : findings).push({
+                dir: name,
+                kind: 'no-skill-md',
+                detail: isPluginContainer
+                    ? `${name}/ is a plugin-shaped container (advisory): it has no depth-1 SKILL.md, so it registers only if the client loads it as a plugin`
+                    : intended
+                        ? `no SKILL.md at ${name}/SKILL.md — this directory cannot register`
+                        : `${name}/ holds no markdown (advisory): it looks like ordinary content, not a skill that failed to register`,
+            });
+        }
+        // A plugin manifest under .claude/skills does NOT auto-register (plugins load from the
+        // marketplace only). This is the exact false premise that shipped health-advisor 1.2.0.
+        // Only a report when the dir registers NOTHING: a dir with its own depth-1 SKILL.md registers
+        // fine and a stray manifest beside it is inert, not a blocker (Codex QE #8).
+        if (isPluginContainer) {
+            // What would this container provide? The dir name of every nested SKILL.md.
+            const inner = [];
+            findBuriedSkillMd(dir, 1, inner, scanErrors);
+            const candidates = [...new Set(inner.map((f) => basename(join(f, '..'))))];
+            containers.push({ dir: name, candidates });
+            advisories.push({
+                dir: name,
+                kind: 'plugin-manifest-trap',
+                detail: `${name}/.claude-plugin/plugin.json did not register in measured practice (advisory, not a failure) — a plugin normally loads from the marketplace; if you meant these to register, install it as a plugin or use bare skills`,
+            });
+        }
+        // SKILL.md files buried too deep never register (health-advisor 1.2.0: extended/<name>/SKILL.md).
+        //
+        // FALSE-POSITIVE GUARD (found by dogfooding this gate on a healthy project): a dir that DOES
+        // register may legitimately bundle nested SKILL.md files as its own resources — health-advisor
+        // 1.2.1 co-locates its base deps under the master exactly so they do NOT register. Only a dir
+        // that registers NOTHING while hiding SKILL.md files inside is the 1.2.0 defect shape.
+        if (!registers) {
+            const buried = [];
+            findBuriedSkillMd(dir, 1, buried, scanErrors);
+            for (const path of buried) {
+                bucket.push({
+                    dir: name,
+                    kind: 'buried-skill-md',
+                    detail: `${path.slice(skillsRoot.length + 1)} is 2+ levels deep in a directory that registers nothing — the loader scans one level, so it never registers`,
+                });
+            }
+        }
+    }
+    return {
+        skillsRoot,
+        projectDir: resolve(projectDir),
+        exists: true,
+        registrable: registrable.sort(),
+        findings,
+        advisories,
+        containers,
+        ...(scanErrors.length ? { scanError: scanErrors.join('; ') } : {}),
+    };
+}
+/**
+ * Parse the `system/init` event out of a `--output-format stream-json` stream. PURE: takes the raw
+ * text, returns facts, does no IO. Returns `null` when no init event is present (→ inconclusive).
+ */
+/**
+ * The first init event's facts. Use ONLY for "has the event arrived yet?" during streaming —
+ * `classifyRegistration` deliberately does NOT accept bare facts, because the count must travel
+ * with them (a caller that forgot to pass `initEventCount` got a free PASS — QE2 #2).
+ */
+export function parseInitFacts(streamText) {
+    return parseAllInitFacts(streamText)[0] ?? null;
+}
+/**
+ * Every `system/init` event in the stream. More than one means the observations may CONTRADICT each
+ * other (Codex QE #7) — the classifier refuses to pick a winner and returns `inconclusive`.
+ */
+export function parseAllInitFacts(streamText) {
+    return parseStream(streamText).events;
+}
+function parseStream(streamText) {
+    const found = [];
+    let malformed = 0;
+    for (const raw of streamText.split('\n')) {
+        const line = raw.trim();
+        if (!line || line[0] !== '{')
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            // A truncated `{"type":"system","subtype":"init",…` silently disappeared here, so a
+            // contradictory second event could be dropped and the first one believed (QE3 #2).
+            malformed += 1;
+            continue;
+        }
+        if (obj.type !== 'system' || obj.subtype !== 'init')
+            continue;
+        // The listing is authoritative or it is nothing: a partially-unparseable `skills` array (a
+        // non-string element) must NOT be silently narrowed to the strings it happens to contain —
+        // that turned an unreadable listing into a PASS (Codex QE #1). ABSENT key ≠ empty list (ADR SP-3).
+        const rawSkills = obj.skills;
+        const skills = Array.isArray(rawSkills)
+            ? rawSkills.every((s) => typeof s === 'string')
+                ? rawSkills
+                : null
+            : null;
+        const rawPlugins = obj.plugins;
+        const plugins = Array.isArray(rawPlugins)
+            ? rawPlugins
+                .filter((p) => !!p && typeof p === 'object')
+                .map((p) => {
+                const name = typeof p.name === 'string' ? p.name : '(unnamed)';
+                // exactOptionalPropertyTypes: omit `version` rather than set it to undefined.
+                return typeof p.version === 'string' ? { name, version: p.version } : { name };
+            })
+            : [];
+        found.push({
+            skills,
+            plugins,
+            // An empty or relative cwd testifies to nothing — `resolve("")` silently becomes the caller's
+            // own cwd and can forge a match (Codex QE #6). Only an absolute path counts as evidence.
+            cwd: typeof obj.cwd === 'string' && obj.cwd !== '' && isAbsolute(obj.cwd) ? obj.cwd : null,
+            clientVersion: typeof obj.claude_code_version === 'string' ? obj.claude_code_version : null,
+        });
+    }
+    return { events: found, malformedObjectLines: malformed };
+}
+/**
+ * The single entry point. PURE apart from the injected resolver. Fail-closed by construction: `pass`
+ * is reachable only from a completed scan, a probe that produced EXACTLY ONE well-formed init event
+ * from THIS project, a fully-readable skills listing, a performed provenance check with no ambiguity,
+ * and zero load-blocking layout findings.
+ */
+export function verifyRegistration(evidence, options = {}) {
+    // A JavaScript caller can hand us an incomplete object; a crash is not a verdict (QE4 #7).
+    const bad = (reason) => ({
+        verdict: 'inconclusive',
+        reason,
+        expected: [],
+        missing: [],
+        registeredCount: null,
+        clientVersion: null,
+        plugins: [],
+        advisories: [],
+        controls: { cwdMatched: null, skillsListPresent: false },
+        layout: [],
+    });
+    if (!evidence || typeof evidence !== 'object')
+        return bad('no evidence supplied');
+    if (!evidence.scan || !evidence.probe || !evidence.provenance || typeof evidence.projectDir !== 'string') {
+        return bad('incomplete evidence (scan, probe, provenance and projectDir are all required)');
+    }
+    const { projectDir, scan, probe, provenance } = evidence;
+    // The contract is CANONICAL identity: a lexical `resolve` alone reports a symlinked project as a
+    // different one and turns a correct registration into `inconclusive` (QE4 #3).
+    const resolvePath = options.resolvePath ??
+        ((p) => {
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return resolve(p);
+            }
+        });
+    const expected = evidence.expected ?? scan.registrable;
+    const layout = scan.findings;
+    const fail = (verdict, reason, extra = {}) => ({
+        expected,
+        layout,
+        advisories: scan.advisories,
+        plugins: [],
+        clientVersion: null,
+        missing: [],
+        registeredCount: null,
+        controls: { cwdMatched: null, skillsListPresent: false },
+        ...extra,
+        verdict,
+        reason,
+    });
+    // 1. The scan must describe THIS project, and must have completed.
+    let scanIsOurs;
+    try {
+        scanIsOurs = resolvePath(scan.projectDir) === resolvePath(projectDir);
+    }
+    catch {
+        scanIsOurs = scan.projectDir === projectDir;
+    }
+    if (!scanIsOurs) {
+        return fail('inconclusive', `the layout scan describes ${scan.projectDir}, not ${projectDir} — evidence from another project`);
+    }
+    if (scan.scanError !== undefined)
+        return fail('inconclusive', `layout scan failed: ${scan.scanError}`);
+    // 2. The probe must have produced a stream.
+    if (!probe.ok)
+        return fail('inconclusive', `probe failed: ${probe.error}`);
+    // 3. Parsing must be intact and the evidence must be singular.
+    const parsed = parseStream(probe.stream);
+    if (parsed.malformedObjectLines > 0) {
+        return fail('inconclusive', `${parsed.malformedObjectLines} malformed JSON line(s) in the stream — a truncated event may be hiding contradictory evidence`);
+    }
+    if (parsed.events.length !== 1) {
+        return fail('inconclusive', parsed.events.length === 0
+            ? 'no system/init event in the stream — could not observe registration'
+            : `${parsed.events.length} init events in one stream — contradictory observations, refusing to pick one`);
+    }
+    const facts = parsed.events[0];
+    const withFacts = { plugins: facts.plugins, clientVersion: facts.clientVersion };
+    // 4. The cwd control: the session must have read THIS project.
+    if (facts.cwd === null) {
+        return fail('inconclusive', 'init event carried no usable absolute cwd — cannot confirm the session read this project', withFacts);
+    }
+    let cwdMatched;
+    try {
+        cwdMatched = resolvePath(facts.cwd) === resolvePath(projectDir);
+    }
+    catch (error) {
+        return fail('inconclusive', `cannot resolve the paths to compare (${error instanceof Error ? error.message : String(error)}) — the cwd control could not run`, withFacts);
+    }
+    if (!cwdMatched) {
+        return fail('inconclusive', `session read ${facts.cwd}, not ${projectDir} — its listing does not describe this project`, {
+            ...withFacts,
+            registeredCount: facts.skills?.length ?? null,
+            controls: { cwdMatched: false, skillsListPresent: facts.skills !== null },
+        });
+    }
+    // 5. The listing must be readable in full.
+    if (facts.skills === null) {
+        return fail('inconclusive', 'the init listing has no readable `skills` array (absent or not all strings) — cannot read it', {
+            ...withFacts,
+            controls: { cwdMatched: true, skillsListPresent: false },
+        });
+    }
+    const controls = { cwdMatched: true, skillsListPresent: true };
+    const registered = new Set(facts.skills);
+    const missing = expected.filter((name) => !registered.has(name));
+    const common = { ...withFacts, registeredCount: facts.skills.length, controls };
+    // 6. Load-blocking layout problems fail on their own — one healthy skill must not mask them.
+    if (layout.length > 0) {
+        return {
+            expected,
+            layout,
+            advisories: scan.advisories,
+            ...common,
+            missing,
+            verdict: 'fail',
+            reason: expected.length === 0
+                ? `nothing can register: ${layout.length} layout problem(s) and no registrable skill directory`
+                : `${layout.length} layout problem(s) can never register (alongside ${expected.length} expected skill(s))`,
+        };
+    }
+    // 6b. A plugin-shaped container is forgiven ONLY if the SESSION says that plugin loaded.
+    //     Matching on skill NAMES was wrong: one incidental collision with an unrelated plugin's skill
+    //     (e.g. `deep-research`) forgave the whole container, and the gate PASSED the broken
+    //     health-advisor 1.2.0 (MEASURED — reproducer: `dz skills-verify` against that published
+    //     install). `init.plugins` names what actually loaded, so ask that instead.
+    const loadedPlugins = new Set(facts.plugins.map((p) => p.name));
+    // Only the LOADED-PLUGIN list counts. A namespaced-name fallback (`<dir>:<skill>` present in the
+    // listing) was still name-based evidence — the very class that made the gate pass a broken install
+    // — and `init.plugins` already covers every legitimate case.
+    const deadContainers = scan.containers.filter((c) => c.candidates.length > 0 && !loadedPlugins.has(c.dir));
+    if (deadContainers.length > 0) {
+        return {
+            expected,
+            layout,
+            advisories: scan.advisories,
+            ...common,
+            missing,
+            verdict: 'fail',
+            reason: `${deadContainers.length} plugin-shaped container(s) did not load — ` +
+                deadContainers
+                    .map((c) => `${c.dir}/ (${c.candidates.length} skill(s) inside, but no such plugin in the session)`)
+                    .join('; '),
+        };
+    }
+    // 7. Provenance must have been CHECKED, and must be unambiguous.
+    if (!provenance.checked) {
+        return fail('inconclusive', 'provenance was not checked — a same-named skill outside this project would forge a pass', {
+            ...common,
+        });
+    }
+    const ambiguousExpected = expected.filter((name) => provenance.ambiguous.includes(name) && registered.has(name));
+    if (ambiguousExpected.length > 0 && missing.length === 0) {
+        return fail('inconclusive', `${ambiguousExpected.length} expected name(s) also exist outside this project (${ambiguousExpected.join(', ')}) — ` +
+            'the listing carries names, not provenance, so registration cannot be attributed to this project', { ...common });
+    }
+    if (missing.length > 0) {
+        return {
+            expected,
+            layout,
+            advisories: scan.advisories,
+            ...common,
+            missing,
+            verdict: 'fail',
+            reason: `${missing.length} of ${expected.length} expected skill(s) did NOT register`,
+        };
+    }
+    return {
+        expected,
+        layout,
+        advisories: scan.advisories,
+        ...common,
+        missing: [],
+        verdict: 'pass',
+        reason: expected.length === 0
+            ? 'nothing was expected to register; the session listing was read successfully'
+            : `all ${expected.length} expected skill(s) are registered`,
+    };
+}
+/** Exit code contract: pass=0, fail=1, inconclusive=2 (distinct so CI can treat it separately). */
+export function registrationExitCode(verdict, strict = false) {
+    if (verdict === 'pass')
+        return 0;
+    if (verdict === 'fail')
+        return 1;
+    return strict ? 1 : 2;
+}
+const VERDICT_LABEL = {
+    pass: 'PASS',
+    fail: 'FAIL',
+    inconclusive: 'INCONCLUSIVE',
+};
+export function renderRegistrationReport(result, scan) {
+    const out = [];
+    out.push(`dz skills-verify: ${VERDICT_LABEL[result.verdict]} — ${result.reason}`);
+    if (scan) {
+        out.push(`  layout: ${scan.registrable.length} registrable skill dir(s) under ${scan.skillsRoot}` +
+            (scan.exists ? '' : ' (missing)'));
+    }
+    if (result.registeredCount !== null) {
+        out.push(`  session: ${result.registeredCount} skill(s) registered` +
+            (result.clientVersion ? ` · client ${result.clientVersion}` : '') +
+            (result.plugins.length ? ` · ${result.plugins.length} plugin(s) loaded` : ''));
+    }
+    if (result.missing.length) {
+        out.push('  MISSING (expected but not registered):');
+        for (const name of result.missing)
+            out.push(`    - ${name}`);
+    }
+    if (result.layout.length) {
+        out.push('  layout problems (these can never register):');
+        for (const f of result.layout)
+            out.push(`    [${f.kind}] ${f.detail}`);
+    }
+    if (result.advisories.length) {
+        out.push('  advisories (reported, not failures):');
+        for (const f of result.advisories)
+            out.push(`    [${f.kind}] ${f.detail}`);
+    }
+    if (result.verdict === 'inconclusive') {
+        out.push('  (inconclusive is never a pass — it means registration could not be observed honestly)');
+    }
+    return out.join('\n');
+}
+// ── The publish-time guard fact ─────────────────────────────────────
+/**
+ * Scan a PACKAGE directory for skill dirs that could never register.
+ *
+ * Discriminator (MEASURED before it was chosen — a naive "every dir needs SKILL.md" rule flagged ~40
+ * healthy directories across 9 npx-toolkit packages, and a markdown-based one still flagged `docs/`):
+ *   1. a package counts as a SKILL PACK only if it already has at least one `<dir>/SKILL.md`;
+ *   2. inside it, a dir is broken only when a `SKILL.md` EXISTS somewhere inside but not at depth 1.
+ * That second rule is unambiguous — the skill file is there, just where nothing will load it (exactly
+ * health-advisor 1.2.0). A dir with no SKILL.md anywhere is ordinary content, not a failed skill.
+ */
+export function findNonRegistrableSkillDirs(packDir) {
+    let entries;
+    try {
+        entries = readdirSync(packDir);
+    }
+    catch {
+        return [];
+    }
+    const dirs = [];
+    for (const name of entries) {
+        if (name.startsWith('.') || name === 'node_modules')
+            continue;
+        const full = join(packDir, name);
+        try {
+            if (statSync(full).isDirectory())
+                dirs.push(name);
+        }
+        catch {
+            /* unreadable entries are not evidence of a defect */
+        }
+    }
+    const isSkillPack = dirs.some((d) => hasSkillFile(join(packDir, d)));
+    if (!isSkillPack)
+        return [];
+    return dirs
+        .filter((d) => {
+        const full = join(packDir, d);
+        if (hasSkillFile(full))
+            return false; // registers fine
+        const buried = [];
+        findBuriedSkillMd(full, 1, buried, []);
+        return buried.length > 0; // a SKILL.md exists, but nothing will load it from there
+    })
+        .sort();
+}
+//# sourceMappingURL=skills-verify.js.map