@dzhechkov/harness-core 0.3.129 → 0.3.130

package/src/skills-verify.ts

@@ -0,0 +1,710 @@
+/**
+ * `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';
+
+// ── Layer 1: static layout scan ─────────────────────────────────────
+
+/** The three non-registrable shapes, all observed in the health-advisor 1.2.0 defect. */
+export type SkillIssueKind =
+  | 'no-skill-md'          // a skill dir with no SKILL.md at depth 1 → never registers
+  | 'buried-skill-md'      // a SKILL.md at depth >= 2 → the loader does not scan that deep
+  | 'plugin-manifest-trap'; // .claude-plugin/plugin.json under .claude/skills → does NOT auto-register
+
+export interface SkillLayoutFinding {
+  readonly dir: string;
+  readonly kind: SkillIssueKind;
+  readonly detail: string;
+}
+
+export interface StaticScan {
+  /** The project this scan describes — evidence from another project must not be believed (QE4 #4). */
+  readonly projectDir: string;
+  readonly skillsRoot: string;
+  readonly exists: boolean;
+  /** Names that CAN register: a dir with SKILL.md exactly one level deep. */
+  readonly registrable: readonly string[];
+  /** Load-blocking problems: these make the verdict FAIL. */
+  readonly findings: readonly SkillLayoutFinding[];
+  /**
+   * Reported but NOT failing. A `.claude-plugin/plugin.json` under `.claude/skills` did not register
+   * in measured practice (MEASURED — reproducer: `dz skills-verify` against the published
+   * health-advisor 1.2.0, whose skills were absent from a live session listing), but the layout class
+   * may be supported under conditions this gate cannot observe (workspace trust). Telling the user is
+   * right; failing their build over it is over-claiming.
+   */
+  readonly advisories: readonly SkillLayoutFinding[];
+  /**
+   * Plugin-shaped containers and the skill names they would provide. The layout alone cannot say
+   * whether such a container loads (that depends on client support and workspace trust), so the
+   * verdict ASKS THE SESSION: if none of a container's candidate names appear in the live listing,
+   * it did not register and that is a failure (QE4 #1 — without this, making the container advisory
+   * re-opened the vacuous pass and the gate stopped catching health-advisor 1.2.0).
+   */
+  readonly containers: readonly { readonly dir: string; readonly candidates: readonly string[] }[];
+  /**
+   * Set when the scan could not complete (unreadable dir, `.claude/skills` is a file, …). A failed
+   * scan must NOT read as "a clean empty project" — the classifier turns this into `inconclusive`
+   * (Codex QE #4).
+   */
+  readonly scanError?: string;
+}
+
+const MAX_BURIED_DEPTH = 4; // enough to catch extended/<name>/SKILL.md without walking the world
+
+function findBuriedSkillMd(dir: string, depth: number, acc: string[], errors: string[]): void {
+  if (depth > MAX_BURIED_DEPTH) return;
+  let entries: string[];
+  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: string): boolean {
+  return existsSync(join(dir, '.claude-plugin', 'plugin.json'));
+}
+
+/**
+ * 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: string): boolean {
+  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: string): StaticScan {
+  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: ReturnType<typeof lstatSync> | null = 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 as NodeJS.ErrnoException).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 as NodeJS.ErrnoException).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: string[] = [];
+  const findings: SkillLayoutFinding[] = [];
+  const advisories: SkillLayoutFinding[] = [];
+  const containers: { dir: string; candidates: string[] }[] = [];
+  const scanErrors: string[] = [];
+
+  let entries: string[] = [];
+  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 {
+      bucket.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`
+          : `no SKILL.md at ${name}/SKILL.md — this directory cannot 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: string[] = [];
+      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: string[] = [];
+      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('; ') } : {}),
+  };
+}
+
+// ── Layer 2: the authoritative init-event listing ───────────────────
+
+export interface InitPlugin {
+  readonly name: string;
+  readonly version?: string;
+}
+
+export interface InitFacts {
+  /** Registered skill names. `null` means the key was ABSENT (schema drift) — never "none". */
+  readonly skills: readonly string[] | null;
+  readonly plugins: readonly InitPlugin[];
+  /** The project the session actually read — the built-in control. */
+  readonly cwd: string | null;
+  readonly clientVersion: string | null;
+}
+
+/**
+ * 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: string): InitFacts | null {
+  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: string): InitFacts[] {
+  return parseStream(streamText).events;
+}
+
+/** What a stream actually contained — facts, cardinality AND parse integrity, produced together. */
+export interface StreamParse {
+  readonly events: InitFacts[];
+  /** A line that LOOKED like a JSON object but did not parse — possibly a truncated init (QE3 #2). */
+  readonly malformedObjectLines: number;
+}
+
+function parseStream(streamText: string): StreamParse {
+  const found: InitFacts[] = [];
+  let malformed = 0;
+  for (const raw of streamText.split('\n')) {
+    const line = raw.trim();
+    if (!line || line[0] !== '{') continue;
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } 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 as string[])
+        : null
+      : null;
+
+    const rawPlugins = obj.plugins;
+    const plugins: InitPlugin[] = Array.isArray(rawPlugins)
+      ? rawPlugins
+          .filter((p): p is Record<string, unknown> => !!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 };
+}
+
+// ── Verdict ─────────────────────────────────────────────────────────
+
+export type RegistrationVerdict = 'pass' | 'fail' | 'inconclusive';
+
+export interface RegistrationControls {
+  /** Did the session read the target project? `null` when unknown (no init / no cwd). */
+  readonly cwdMatched: boolean | null;
+  /** Was the `skills` key present at all? A missing key is schema drift, not "nothing registered". */
+  readonly skillsListPresent: boolean;
+}
+
+export interface RegistrationResult {
+  readonly verdict: RegistrationVerdict;
+  readonly reason: string;
+  readonly expected: readonly string[];
+  readonly missing: readonly string[];
+  readonly registeredCount: number | null;
+  readonly clientVersion: string | null;
+  readonly plugins: readonly InitPlugin[];
+  readonly controls: RegistrationControls;
+  readonly layout: readonly SkillLayoutFinding[];
+  /** Reported, never fatal — see StaticScan.advisories. Rendering them is the policy (QE4 #5). */
+  readonly advisories: readonly SkillLayoutFinding[];
+}
+
+/**
+ * The complete evidence bundle. Every piece is REQUIRED and travels together: the previous shape let
+ * a caller omit the scan error, the layout, the provenance check or the event count and get a free
+ * PASS (Codex QE3 #1/#2/#4/#5). There is exactly one door into the verdict, and it is this one.
+ */
+export interface RegistrationEvidence {
+  readonly projectDir: string;
+  /** The WHOLE static scan (carries its own scanError + findings) — not hand-picked fields. */
+  readonly scan: StaticScan;
+  /** The probe outcome: either the raw stream, or the reason there is none. */
+  readonly probe: { readonly ok: true; readonly stream: string } | { readonly ok: false; readonly error: string };
+  /**
+   * Did we actually look for same-named skills OUTSIDE this project, and what did we find?
+   * `checked: false` ⇒ inconclusive: unperformed provenance discovery is not evidence of uniqueness.
+   */
+  readonly provenance: { readonly checked: boolean; readonly ambiguous: readonly string[] };
+  /** Explicit `--expect` list; when absent the expectation is the scan's registrable set. */
+  readonly expected?: readonly string[];
+}
+
+export interface SkillsVerifyOptions {
+  /** Must CANONICALISE (realpath) so symlinked project paths compare equal; may throw. */
+  readonly resolvePath?: (p: string) => string;
+}
+
+/**
+ * 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: RegistrationEvidence, options: SkillsVerifyOptions = {}): RegistrationResult {
+  // A JavaScript caller can hand us an incomplete object; a crash is not a verdict (QE4 #7).
+  const bad = (reason: string): RegistrationResult => ({
+    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: string) => {
+      try {
+        return realpathSync(p);
+      } catch {
+        return resolve(p);
+      }
+    });
+  const expected = evidence.expected ?? scan.registrable;
+  const layout = scan.findings;
+
+  const fail = (
+    verdict: RegistrationVerdict,
+    reason: string,
+    extra: Partial<RegistrationResult> = {},
+  ): RegistrationResult => ({
+    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: boolean;
+  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: boolean;
+  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: RegistrationControls = { 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: RegistrationVerdict, strict = false): number {
+  if (verdict === 'pass') return 0;
+  if (verdict === 'fail') return 1;
+  return strict ? 1 : 2;
+}
+
+const VERDICT_LABEL: Record<RegistrationVerdict, string> = {
+  pass: 'PASS',
+  fail: 'FAIL',
+  inconclusive: 'INCONCLUSIVE',
+};
+
+export function renderRegistrationReport(result: RegistrationResult, scan?: StaticScan): string {
+  const out: string[] = [];
+  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');
+}