@dzhechkov/harness-core 0.4.3 → 0.4.4

package/src/skills-verify.ts

@@ -443,6 +443,16 @@ export interface InitPlugin {
 export interface InitFacts {
   /** Registered skill names. `null` means the key was ABSENT (schema drift) — never "none". */
   readonly skills: readonly string[] | null;
+  /**
+   * Registered slash-command names, e.g. `loop-designer:init` (MEASURED on Claude Code 2.1.233: the
+   * `system/init` event carries a `slash_commands` array, and a plugin command registers under
+   * `<plugin>:<file basename>` — its frontmatter `name:` does NOT rename it).
+   *
+   * `null` means the key was ABSENT or not all strings — schema drift, never "no commands". A
+   * plugin whose commands silently failed to load and a Claude Code build that stopped emitting the
+   * key are indistinguishable from `[]`, so `[]` is never synthesised here.
+   */
+  readonly slashCommands: readonly string[] | null;
   readonly plugins: readonly InitPlugin[];
   /** False when the `plugins` key was absent or not an array — unreadable, not empty (QE6 #7). */
   readonly pluginsReadable: boolean;
@@ -508,6 +518,15 @@ function parseStream(streamText: string): StreamParse {
         : null
       : null;
 
+    // Same treatment as `skills`, for the same reason: an ABSENT key is unreadable schema, and a
+    // partially-unparseable array must not be narrowed to the strings it happens to contain.
+    const rawCommands = obj.slash_commands;
+    const slashCommands = Array.isArray(rawCommands)
+      ? rawCommands.every((s) => typeof s === 'string')
+        ? (rawCommands as string[])
+        : null
+      : null;
+
     const rawPlugins = obj.plugins;
     // An ABSENT or non-array `plugins` key is unreadable schema, not proof that nothing loaded —
     // with containers present that difference decides FAIL vs INCONCLUSIVE (QE6 #7).
@@ -529,6 +548,7 @@ function parseStream(streamText: string): StreamParse {
 
     found.push({
       skills,
+      slashCommands,
       plugins,
       pluginsReadable,
       // An empty or relative cwd testifies to nothing — `resolve("")` silently becomes the caller's
@@ -549,6 +569,8 @@ export interface RegistrationControls {
   readonly cwdMatched: boolean | null;
   /** Was the `skills` key present at all? A missing key is schema drift, not "nothing registered". */
   readonly skillsListPresent: boolean;
+  /** Same question for `slash_commands`. `false` when absent/unreadable — never "no commands". */
+  readonly commandsListPresent: boolean;
 }
 
 export interface RegistrationResult {
@@ -556,6 +578,10 @@ export interface RegistrationResult {
   readonly reason: string;
   readonly expected: readonly string[];
   readonly missing: readonly string[];
+  /** The `--expect-commands` set this verdict was measured against (empty when not asked). */
+  readonly expectedCommands: readonly string[];
+  /** Expected commands absent from the live `slash_commands` listing. */
+  readonly missingCommands: readonly string[];
   readonly registeredCount: number | null;
   readonly clientVersion: string | null;
   readonly plugins: readonly InitPlugin[];
@@ -583,6 +609,12 @@ export interface RegistrationEvidence {
   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[];
+  /**
+   * Explicit `--expect-commands` list, e.g. `loop-designer:init`. Absent/empty ⇒ commands are not
+   * part of this vehicle's expectation (a bare skill has no commands BY DESIGN — ADR-003 D-2 — so
+   * demanding them there would be a false FAIL, not a stronger gate).
+   */
+  readonly expectedCommands?: readonly string[];
 }
 
 export interface SkillsVerifyOptions {
@@ -603,11 +635,13 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
     reason,
     expected: [],
     missing: [],
+    expectedCommands: [],
+    missingCommands: [],
     registeredCount: null,
     clientVersion: null,
     plugins: [],
     advisories: [],
-    controls: { cwdMatched: null, skillsListPresent: false },
+    controls: { cwdMatched: null, skillsListPresent: false, commandsListPresent: false },
     layout: [],
   });
   if (!evidence || typeof evidence !== 'object') return bad('no evidence supplied');
@@ -632,6 +666,10 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
       }
     });
   const expected = evidence.expected ?? scan.registrable;
+  // Unlike `expected`, this has NO fallback to a discovered set: there is nothing on disk that
+  // proves which command names a session should surface, and a guessed expectation is how a gate
+  // starts passing for the wrong reason. Not asked ⇒ not checked, and the report says so.
+  const expectedCommands = evidence.expectedCommands ?? [];
   const layout = scan.findings;
 
   const fail = (
@@ -640,13 +678,15 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
     extra: Partial<RegistrationResult> = {},
   ): RegistrationResult => ({
     expected,
+    expectedCommands,
+    missingCommands: [],
     layout,
     advisories: scan.advisories,
     plugins: [],
     clientVersion: null,
     missing: [],
     registeredCount: null,
-    controls: { cwdMatched: null, skillsListPresent: false },
+    controls: { cwdMatched: null, skillsListPresent: false, commandsListPresent: false },
     ...extra,
     verdict,
     reason,
@@ -713,7 +753,7 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
     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 },
+      controls: { cwdMatched: false, skillsListPresent: facts.skills !== null, commandsListPresent: facts.slashCommands !== null },
     });
   }
 
@@ -721,14 +761,29 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
   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 },
+      controls: { cwdMatched: true, skillsListPresent: false, commandsListPresent: facts.slashCommands !== null },
     });
   }
 
-  const controls: RegistrationControls = { cwdMatched: true, skillsListPresent: true };
+  // 5b. …and so must the COMMAND listing, whenever commands were expected. An absent
+  //     `slash_commands` key is schema drift, exactly like an absent `skills` key: treating it as
+  //     `[]` would report "your five commands did not register" on a Claude Code build that simply
+  //     stopped emitting the key, and treating it as "fine" would pass a plugin whose commands
+  //     really are missing. Neither is observable ⇒ inconclusive.
+  if (expectedCommands.length > 0 && facts.slashCommands === null) {
+    return fail(
+      'inconclusive',
+      'the init listing has no readable `slash_commands` array (absent or not all strings) — command registration cannot be observed',
+      { ...withFacts, controls: { cwdMatched: true, skillsListPresent: true, commandsListPresent: false } },
+    );
+  }
+
+  const controls: RegistrationControls = { cwdMatched: true, skillsListPresent: true, commandsListPresent: facts.slashCommands !== null };
   const registered = new Set(facts.skills);
   const missing = expected.filter((name) => !registered.has(name));
-  const common = { ...withFacts, registeredCount: facts.skills.length, controls };
+  const registeredCommands = new Set(facts.slashCommands ?? []);
+  const missingCommands = expectedCommands.filter((name) => !registeredCommands.has(name));
+  const common = { ...withFacts, expectedCommands, missingCommands, 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) {
@@ -832,7 +887,12 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
   }));
   const allAdvisories = [...scan.advisories, ...containerAdvisories];
 
-  if (missing.length > 0) {
+  if (missing.length > 0 || missingCommands.length > 0) {
+    const parts: string[] = [];
+    if (missing.length > 0) parts.push(`${missing.length} of ${expected.length} expected skill(s) did NOT register`);
+    if (missingCommands.length > 0) {
+      parts.push(`${missingCommands.length} of ${expectedCommands.length} expected command(s) did NOT register (${missingCommands.join(', ')})`);
+    }
     return {
       expected,
       layout,
@@ -840,7 +900,7 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
       ...common,
       missing,
       verdict: 'fail',
-      reason: `${missing.length} of ${expected.length} expected skill(s) did NOT register`,
+      reason: parts.join('; '),
     };
   }
 
@@ -852,9 +912,11 @@ export function verifyRegistration(evidence: RegistrationEvidence, options: Skil
     missing: [],
     verdict: 'pass',
     reason:
-      expected.length === 0
+      expected.length === 0 && expectedCommands.length === 0
         ? 'nothing was expected to register; the session listing was read successfully'
-        : `all ${expected.length} expected skill(s) are registered`,
+        : `all ${expected.length} expected skill(s)` +
+          (expectedCommands.length > 0 ? ` and all ${expectedCommands.length} expected command(s)` : '') +
+          ' are registered',
   };
 }
 
@@ -892,6 +954,13 @@ export function renderRegistrationReport(result: RegistrationResult, scan?: Stat
     out.push('  MISSING (expected but not registered):');
     for (const name of result.missing) out.push(`    - ${name}`);
   }
+  if (result.expectedCommands.length) {
+    out.push(
+      `  commands: ${result.expectedCommands.length} expected` +
+        (result.controls.commandsListPresent ? '' : ' · slash_commands listing UNREADABLE'),
+    );
+    for (const name of result.missingCommands) out.push(`    - MISSING ${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}`);
@@ -906,6 +975,35 @@ export function renderRegistrationReport(result: RegistrationResult, scan?: Stat
   return out.join('\n');
 }
 
+/**
+ * The names a plugin's OWN manifest says its commands and skills should register under, so a
+ * `--plugin-dir` gate run can default its expectation to the manifest instead of to a hand-typed
+ * list that drifts from it.
+ *
+ * The naming rules are MEASURED, not assumed (Claude Code 2.1.233, fixture probe 2026-08-17):
+ *   · a command registers as `<plugin>:<file basename without .md>` — its frontmatter `name:` does
+ *     NOT rename it (a fixture declaring `name: renamed-second` registered as `probeplug:second`);
+ *   · a skill registers as `<plugin>:<directory basename>` — likewise not its frontmatter name.
+ *
+ * Returns `null` when the manifest is missing/unreadable/nameless: an unreadable manifest must not
+ * silently become an EMPTY expectation, which is the shape that passes without checking anything.
+ */
+export function declaredPluginSurface(pluginDir: string): { name: string; skills: string[]; commands: string[] } | null {
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(readFileSync(join(pluginDir, '.claude-plugin', 'plugin.json'), 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  const name = typeof obj.name === 'string' && obj.name ? obj.name : null;
+  if (name === null) return null;
+  const list = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((x): x is string => typeof x === 'string') : [];
+  const skills = list(obj.skills).map((rel) => `${name}:${basename(rel.replace(/\/+$/, ''))}`);
+  const commands = list(obj.commands).map((rel) => `${name}:${basename(rel).replace(/\.md$/i, '')}`);
+  return { name, skills, commands };
+}
+
 // ── The publish-time guard fact ─────────────────────────────────────
 
 /**

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dzhechko
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.