@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/commands/registry.command.js

@@ -10,63 +10,42 @@
  *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
  *   shrk registry <name> duplicates [--json]    # ids declared in more than one place
  *
+ * An inventory that matched 0 ids answers NO query: `list` / `exists` / `where`
+ * / `duplicates` all exit 2 (not verified) — 1 when the registry sets
+ * `failOnEmpty` — whatever guard flag was passed.
+ *
  * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
  * deterministic multi-root scan that answers "is this id taken / where is it"
  * without an agent re-running a fragile grep.
  */
-import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
-import { scanRegistry, registryDuplicates, registryExists, registryWhere, } from '@shrkcrft/boundaries';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { resolveProjectConfig } from '@shrkcrft/inspector';
+import { REGISTRY_LIFECYCLE_FLAGS_USAGE, runRegistryLifecycle } from "./registry-lifecycle-run.js";
+import { ALLOW_EMPTY_FLAG } from "../gates/allow-empty.js";
+import { planeScanExcludeDirs, scanRegistry, registryDuplicates, registryExists, registryWhere, } from '@shrkcrft/boundaries';
+import { failsWhenEmpty, RuleEmptiness, settleRuleEmptiness, } from '@shrkcrft/core';
+import { registryLiveness } from "../gates/registry-liveness.js";
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { ExitCode } from "../exit-codes.js";
 import { asJson } from "../output/format-output.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { qualifyCleanForUnits } from "../gates/qualify-clean-for-units.js";
+import { unitStateNotes } from "../gates/unit-state-notes.js";
+import { answerIncompleteInventory } from "../gates/incomplete-registry-inventory.js";
+import { seamRejectedRules } from "../gates/seam-rejected-rules.js";
 import { resolveRegistryNoun } from "./registry-resolve.js";
 /** The inventory verbs, used to detect (and forgive) a verb-first invocation. */
 const INVENTORY_VERBS = new Set(['list', 'exists', 'where', 'duplicates']);
 export const registryLifecycleCommand = {
     name: 'lifecycle',
     description: 'Scan the workspace for register/remove symmetry. Read-only.',
-    usage: 'shrk registry lifecycle [--scope <dir>] [--changed-only] [--since <ref>] [--json]',
-    async run(args) {
-        const cwd = resolveCwd(args);
-        const scope = flagString(args, 'scope');
-        const changedOnly = flagBool(args, 'changed-only');
-        const since = flagString(args, 'since');
-        let files;
-        if (changedOnly || since) {
-            const changed = resolveChangedFiles({
-                projectRoot: cwd,
-                ...(since ? { since } : {}),
-                ...(changedOnly && !since ? { includeWorktree: true } : {}),
-            });
-            files = changed.files;
-        }
-        // Full-tree walk honors the project's skipDirs override.
-        let skipDirs;
-        if (files === undefined) {
-            const loaded = await resolveProjectConfig(cwd);
-            if (loaded.ok)
-                skipDirs = loaded.value.config.registryLifecycle?.skipDirs;
-        }
-        const report = buildRegistryLifecycleReport({
-            projectRoot: cwd,
-            ...(files !== undefined ? { files } : {}),
-            ...(scope ? { scope } : {}),
-            ...(skipDirs ? { skipDirs } : {}),
-        });
-        // Honest exit-code contract (a25 §1 / §2.5): a wedged/timed-out scan OR a
-        // scope with zero registrations to check is NOT verified (`2`), never a
-        // green `0` an agent's `&& next` would march past.
-        const exit = report.timedOut || report.registersFound === 0
-            ? ExitCode.NotVerified
-            : report.missingRemovers.length === 0
-                ? ExitCode.VerifiedPass
-                : ExitCode.Failure;
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(report) + '\n');
-            return exit;
-        }
-        process.stdout.write(renderRegistryLifecycleReportText(report));
-        return exit;
+    usage: `shrk registry lifecycle ${REGISTRY_LIFECYCLE_FLAGS_USAGE}`,
+    booleanFlags: new Set(['json', 'changed-only', ALLOW_EMPTY_FLAG]),
+    // The same body as `check registry-lifecycle` (registry-lifecycle-run.ts):
+    // one settled verdict, not a second copy of the exit derivation.
+    run(args) {
+        return runRegistryLifecycle(args, 'registry lifecycle');
     },
 };
 async function loadRegistries(cwd) {
@@ -77,11 +56,100 @@ async function loadRegistries(cwd) {
         ok: true,
         registries: loaded.value.config.registries ?? [],
         planeDiagnostics: loaded.value.planeDiagnostics,
+        excludeDirs: planeScanExcludeDirs(cwd, loaded.value.sharkcraftDir),
+        rejected: seamRejectedRules(loaded.value, ['registry']),
     };
 }
 function findRegistry(registries, name) {
     return registries.find((r) => r.name === name);
 }
+/** Why an empty inventory proves nothing, in the words every inventory verb prints. */
+const EMPTY_INVENTORY_REASON = 'the source selector matched nothing — it is probably stale (see `shrk gates coverage`)';
+/**
+ * THE rule-emptiness settle of an inventory that matched 0 ids (round 13,
+ * `settleRuleEmptiness`), over the registry's glob liveness
+ * (`registryLiveness`, the one `gates check` reads) and THE failOnEmpty
+ * authority (`failsWhenEmpty`; a registry is warning-severity, so an explicit
+ * `failOnEmpty: true` is what makes it block). Every source inclusion glob
+ * marked `expectEmpty` and no source file matched → an inventory over a
+ * planned directory: INTENDED-empty, so a membership question has a real
+ * answer (nothing is registered yet) and the acceptance is printed.
+ */
+function settleInventoryEmptiness(decl, inventory, liveness) {
+    return settleRuleEmptiness({
+        subject: decl.name,
+        unitLabel: 'ids',
+        filesMatched: inventory.readScope.read,
+        unitsMatched: inventory.entries.length,
+        unread: false,
+        liveness,
+        primaryLists: ['source.files'],
+        failOnEmpty: failsWhenEmpty({
+            ...(decl.failOnEmpty !== undefined ? { failOnEmpty: decl.failOnEmpty } : {}),
+            severity: 'warning',
+        }),
+        noFilesReason: EMPTY_INVENTORY_REASON,
+        noUnitsReason: EMPTY_INVENTORY_REASON,
+    });
+}
+/**
+ * The printed `expectEmpty` acceptance of the registry's glob units — settle
+ * record B of THE settle `gates check` reads (`registryLiveness`), from the
+ * settled verdict, never hand-built. It rides on every exit-0 answer (round 13
+ * review): an inventory over a planned directory (where it IS the inventory's
+ * emptiness record), AND a live inventory with a planned sibling glob — which
+ * `gates check` accepted in print while every registry verb was silent.
+ */
+function acceptedUnitLines(liveness) {
+    if (liveness?.acceptance === undefined)
+        return [];
+    return settleVerdict(ExitCode.VerifiedPass, [liveness.acceptance]).accepted;
+}
+/**
+ * Answer a query over an inventory that matched NOTHING.
+ *
+ * An empty inventory cannot answer a membership question: `exists X` would say
+ * "no" (1) for an id that IS declared — only the glob went stale — and `exists
+ * X --fail-if-taken` would say "free" (0), so the documented duplicate guard
+ * `exists X --fail-if-taken && <author>` marched on over a scan that saw
+ * nothing. Every inventory verb therefore answers the empty inventory itself,
+ * whatever guard flag was passed: not verified (2), or a failure (1) when the
+ * registry sets `failOnEmpty`. Settled through the one coverage guard, so the
+ * exit and the printed verdict cannot disagree.
+ */
+function answerEmptyInventory(inventory, emptiness, json, payload, diagnostics = []) {
+    const failOnEmpty = emptiness.fails;
+    const settled = settleVerdict(failOnEmpty ? ExitCode.Failure : ExitCode.VerifiedPass, [
+        {
+            unit: 'ids',
+            expected: 0,
+            examined: 0,
+            subject: `registry "${inventory.name}"`,
+            reason: emptiness.skipReason ?? EMPTY_INVENTORY_REASON,
+        },
+    ]);
+    if (json) {
+        process.stdout.write(asJson({
+            ...payload,
+            verified: false,
+            exitCode: settled.exit,
+            verdict: settled.verdict,
+            shortfalls: settled.shortfalls,
+        }) + '\n');
+        return settled.exit;
+    }
+    process.stdout.write(`Registry "${inventory.name}" matched 0 ids — nothing was checked. This is NOT a pass;\n` +
+        '  the source selector is probably stale (see `shrk gates coverage`).\n');
+    for (const d of diagnostics)
+        process.stdout.write(`  ! ${d}\n`);
+    if (failOnEmpty) {
+        process.stdout.write('  The registry sets `failOnEmpty: true`, so an empty inventory is a failure.\n');
+    }
+    const line = verdictLine(settled, '');
+    if (line)
+        process.stdout.write(`${line}\n`);
+    return settled.exit;
+}
 /** Run a `list | exists | where` query against a declared registry. */
 async function runRegistryInventory(args, name) {
     const cwd = resolveCwd(args);
@@ -90,13 +158,32 @@ async function runRegistryInventory(args, name) {
     const id = args.positional[2];
     const loaded = await loadRegistries(cwd);
     if (!loaded.ok) {
-        if (json)
-            process.stdout.write(asJson({ error: loaded.message }) + '\n');
-        else
+        // The registry is declared in the config that did not load: the query never
+        // STARTED — a usage error (3), never the `1` that reads "missing" / "taken".
+        if (json) {
+            process.stdout.write(asJson({ error: loaded.message, exitCode: ExitCode.UsageError, verdict: 'usage-error' }) + '\n');
+        }
+        else {
             process.stderr.write(`Could not load config: ${loaded.message}\n  Run \`shrk doctor\` for details.\n`);
-        return 1;
+        }
+        return ExitCode.UsageError;
     }
     const decl = findRegistry(loaded.registries, name);
+    const rejectedDecl = decl ? undefined : loaded.rejected.find((r) => r.id === name);
+    if (rejectedDecl) {
+        // Declared by a pack, refused by the merge seam: the inventory was never
+        // scanned, so no query over it can be answered — a failure (1), never the
+        // "unknown registry" usage error (round 12 review, R12-X1).
+        const message = rejectedDecl.error ?? 'failed validation';
+        if (json) {
+            process.stdout.write(asJson({ name, rejected: true, error: message, exitCode: ExitCode.Failure, verdict: 'fail' }) + '\n');
+        }
+        else {
+            process.stdout.write(`Registry "${name}" was contributed by a pack and REJECTED — nothing was scanned, and that is a failure:\n` +
+                `  ${message}\n  \`shrk packs contributions\` names every rejected entry.\n`);
+        }
+        return ExitCode.Failure;
+    }
     if (!decl) {
         const names = loaded.registries.map((r) => r.name);
         const avail = names.length > 0 ? `Declared registries: ${names.join(', ')}.` : 'No registries declared in sharkcraft.config.ts `registries[]`.';
@@ -115,13 +202,49 @@ async function runRegistryInventory(args, name) {
         }
         return ExitCode.UsageError;
     }
-    const inventory = scanRegistry(cwd, decl);
+    const inventory = scanRegistry(cwd, decl, { excludeDirs: loaded.excludeDirs });
+    // A source file the reader could not read (over the read cap): only a
+    // positive finding is verified; any other answer settles NOT VERIFIED (2).
+    const incomplete = answerIncompleteInventory(inventory, decl, action, id, json);
+    if (incomplete !== undefined)
+        return incomplete;
+    // An inventory that matched 0 ids is decided by THE rule-emptiness settle
+    // (round 13). STALE (a dead or unmarked selector): no query over it can be
+    // answered — 2, or 1 under failOnEmpty. INTENDED-empty (every source glob
+    // marked `expectEmpty`, no source file matched): nothing is registered yet,
+    // so every verb answers as over any inventory, and prints the acceptance.
+    //
+    // The registry's glob units are settled with their `expectEmpty` markers —
+    // THE settle `gates check` reads (`registryLiveness`) — when a unit is marked
+    // (its acceptance rides on every exit-0 answer, round 13 review) or the
+    // inventory is empty (what the empty inventory is decided from).
+    const marked = [decl.source, decl.consumer].some((s) => (s?.expectEmptyUnits?.length ?? 0) > 0);
+    const liveness = marked || inventory.entries.length === 0 ? registryLiveness(cwd, decl, loaded.excludeDirs) : undefined;
+    const emptiness = inventory.entries.length === 0 && liveness !== undefined
+        ? settleInventoryEmptiness(decl, inventory, liveness)
+        : undefined;
+    const stale = emptiness !== undefined && emptiness.state !== RuleEmptiness.IntendedEmpty ? emptiness : undefined;
+    const accepted = acceptedUnitLines(liveness);
+    const acceptedField = accepted.length > 0 ? { accepted } : {};
+    const writeAccepted = () => {
+        for (const a of accepted)
+            process.stdout.write(`  ${a}\n`);
+    };
     if (action === 'list' || action === undefined) {
         // Fold pack-plane merge notes (missing/invalid pack registry files, dropped
         // collisions) into the inventory's own scan diagnostics.
         const diagnostics = [...inventory.diagnostics, ...loaded.planeDiagnostics];
+        if (stale !== undefined) {
+            return answerEmptyInventory(inventory, stale, json, { name: inventory.name, count: 0, ids: [], diagnostics }, diagnostics);
+        }
         if (json) {
-            process.stdout.write(asJson({ name: inventory.name, count: inventory.entries.length, ids: inventory.entries.map((e) => e.id), diagnostics }) + '\n');
+            process.stdout.write(asJson({
+                name: inventory.name,
+                count: inventory.entries.length,
+                ids: inventory.entries.map((e) => e.id),
+                diagnostics,
+                ...acceptedField,
+            }) + '\n');
             return 0;
         }
         process.stdout.write(`Registry "${inventory.name}"${inventory.description ? ' — ' + inventory.description : ''}\n`);
@@ -131,6 +254,12 @@ async function runRegistryInventory(args, name) {
         }
         for (const d of diagnostics)
             process.stdout.write(`  ! ${d}\n`);
+        // THE shared unit-state block (round 13, K2): a LOCAL expectEmpty marker
+        // whose target appeared, or a dead source / consumer glob, is listed; a
+        // pack marker is INFO. (`registry` settles the globs the way `gates check`
+        // does — `registryLiveness`.)
+        process.stdout.write(unitStateNotes([{ id: inventory.name, unitLiveness: (liveness ?? registryLiveness(cwd, decl, loaded.excludeDirs)).units }]).text);
+        writeAccepted();
         return 0;
     }
     if (action === 'exists') {
@@ -144,6 +273,11 @@ async function runRegistryInventory(args, name) {
             process.stderr.write('Pass at most one of --fail-if-taken / --fail-if-missing.\n');
             return ExitCode.UsageError;
         }
+        // Neither "taken" nor "free" can be read off an inventory that saw nothing
+        // — unless it is intended-empty (round 13): then nothing is taken yet.
+        if (stale !== undefined) {
+            return answerEmptyInventory(inventory, stale, json, { name: inventory.name, id, exists: null });
+        }
         // `--resolve` maps a human noun to the canonical registered id before the
         // existence test — via the registry's declared `aliases` map AND generic
         // normalization (case-fold, singular/plural, suffix strip/append) — so a
@@ -162,6 +296,7 @@ async function runRegistryInventory(args, name) {
         //   --fail-if-missing → non-zero when the id is NOT registered (the consume-side check).
         //   neither           → the historical query convention (taken → 0, free → 1).
         const code = failIfTaken ? (exists ? 1 : 0) : exists ? 0 : 1;
+        // The acceptance rides on a PASSING answer only (settleVerdict's rule).
         if (json) {
             process.stdout.write(asJson({
                 name: inventory.name,
@@ -169,6 +304,7 @@ async function runRegistryInventory(args, name) {
                 ...(resolved ? { resolvedId: canonical, resolvedVia: resolution?.via } : {}),
                 exists,
                 exitCode: code,
+                ...(code === 0 ? acceptedField : {}),
             }) + '\n');
             return code;
         }
@@ -176,6 +312,8 @@ async function runRegistryInventory(args, name) {
             process.stdout.write(`resolved "${id}" → "${canonical}" (${resolution?.via})\n`);
         }
         process.stdout.write(`${exists ? 'yes' : 'no'} — "${canonical}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
+        if (code === 0)
+            writeAccepted();
         return code;
     }
     if (action === 'duplicates') {
@@ -183,22 +321,30 @@ async function runRegistryInventory(args, name) {
         // at runtime is an accident of load order. Every site is printed so the
         // duplicate can be resolved, not merely detected.
         const dupes = registryDuplicates(inventory);
+        const diagnostics = [...inventory.diagnostics, ...loaded.planeDiagnostics];
+        if (stale !== undefined) {
+            return answerEmptyInventory(inventory, stale, json, { name: inventory.name, scanned: 0, duplicates: [], diagnostics }, diagnostics);
+        }
         if (json) {
             process.stdout.write(asJson({
                 name: inventory.name,
                 scanned: inventory.entries.length,
                 duplicates: dupes,
-                diagnostics: [...inventory.diagnostics, ...loaded.planeDiagnostics],
+                diagnostics,
+                ...acceptedField,
             }) + '\n');
-            return inventory.entries.length === 0 ? 2 : dupes.length > 0 ? 1 : 0;
-        }
-        if (inventory.entries.length === 0) {
-            process.stdout.write(`Registry "${inventory.name}" matched 0 ids — nothing was checked. This is NOT a pass;\n` +
-                '  the source selector is probably stale (see `shrk gates coverage`).\n');
-            return 2;
+            return dupes.length > 0 ? 1 : 0;
         }
         if (dupes.length === 0) {
-            process.stdout.write(`No duplicate ids in registry "${inventory.name}" (${inventory.entries.length} scanned). ✓\n`);
+            // THE shared unit-state block (round 13, K2): a LOCAL expectEmpty marker
+            // whose target appeared (or a dead glob) is listed and withholds the ✓;
+            // a pack marker is INFO.
+            const unitNotes = unitStateNotes([
+                { id: inventory.name, unitLiveness: (liveness ?? registryLiveness(cwd, decl, loaded.excludeDirs)).units },
+            ]);
+            process.stdout.write(unitNotes.text);
+            process.stdout.write(`${qualifyCleanForUnits(`No duplicate ids in registry "${inventory.name}" (${inventory.entries.length} scanned). ✓`, unitNotes)}\n`);
+            writeAccepted();
             return 0;
         }
         process.stdout.write(`Duplicate ids in registry "${inventory.name}" (${dupes.length}):\n`);
@@ -214,9 +360,18 @@ async function runRegistryInventory(args, name) {
             process.stderr.write(`Usage: shrk registry ${name} where <id>\n`);
             return ExitCode.UsageError;
         }
+        if (stale !== undefined) {
+            return answerEmptyInventory(inventory, stale, json, { name: inventory.name, id, found: null, entry: null });
+        }
         const entry = registryWhere(inventory, id);
         if (json) {
-            process.stdout.write(asJson({ name: inventory.name, id, found: entry !== undefined, entry: entry ?? null }) + '\n');
+            process.stdout.write(asJson({
+                name: inventory.name,
+                id,
+                found: entry !== undefined,
+                entry: entry ?? null,
+                ...(entry !== undefined ? acceptedField : {}),
+            }) + '\n');
             return entry ? 0 : 1;
         }
         if (!entry) {
@@ -228,6 +383,7 @@ async function runRegistryInventory(args, name) {
             process.stdout.write(`  declared  ${s.file}:${s.line}\n`);
         for (const s of entry.consumerSites ?? [])
             process.stdout.write(`  consumed  ${s.file}:${s.line}\n`);
+        writeAccepted();
         return 0;
     }
     process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id> | duplicates\n`);
@@ -235,12 +391,28 @@ async function runRegistryInventory(args, name) {
 }
 export const registryCommand = {
     name: 'registry',
+    // Free: positional[0] is a declared registry NAME (`registry <name> list`).
+    // The inventory verbs are also accepted verb-first (`registry list <name>`).
+    positionals: PositionalMode.Free,
+    subverbs: [
+        {
+            name: 'lifecycle',
+            description: 'Registry lifecycle symmetry (register ↔ unregister) across the tree.',
+            usage: 'shrk registry lifecycle [--scope <glob>] [--changed-only | --since <ref>] [--limit N] [--offset N] [--budget-ms N] [--allow-empty] [--json]',
+        },
+        ...[...INVENTORY_VERBS].map((verb) => ({
+            name: verb,
+            description: `The verb-first spelling of \`registry <name> ${verb}\`.`,
+            usage: `shrk registry ${verb} <name>${verb === 'exists' || verb === 'where' ? ' <id>' : ''} [--json]`,
+            positionals: PositionalMode.Free,
+        })),
+    ],
     description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
     usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id> | <name> duplicates',
     // Guard-mode + query flags take no value — declare them so `exists <id>
     // --fail-if-taken` (flag last) and `exists --resolve <id>` (flag first) both
     // keep the id as a positional instead of swallowing it.
-    booleanFlags: new Set(['json', 'resolve', 'fail-if-taken', 'fail-if-missing']),
+    booleanFlags: new Set(['json', 'resolve', 'fail-if-taken', 'fail-if-missing', 'changed-only', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'lifecycle') {
@@ -255,7 +427,8 @@ export const registryCommand = {
             const second = args.positional[1];
             if (INVENTORY_VERBS.has(sub) && second !== undefined && second.length > 0) {
                 const loaded = await loadRegistries(resolveCwd(args));
-                const known = loaded.ok && findRegistry(loaded.registries, second) !== undefined;
+                const known = loaded.ok &&
+                    (findRegistry(loaded.registries, second) !== undefined || loaded.rejected.some((r) => r.id === second));
                 if (known) {
                     // [verb, name, ...rest] → [name, verb, ...rest]
                     args.positional = [second, sub, ...args.positional.slice(2)];

package/dist/commands/release.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.command.d.ts","sourceRoot":"","sources":["../../src/commands/release.command.ts"],"names":[],"mappings":"AA2BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2pBhC,eAAO,MAAM,cAAc,EAAE,eAY5B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC"}
+{"version":3,"file":"release.command.d.ts","sourceRoot":"","sources":["../../src/commands/release.command.ts"],"names":[],"mappings":"AA6BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAotBhC,eAAO,MAAM,cAAc,EAAE,eAkC5B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC"}

package/dist/commands/release.command.js

@@ -2,8 +2,9 @@ import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import * as nodePath from 'node:path';
-import { buildReleaseReadiness, inspectSharkcraft, ReleaseReadinessSeverity, renderReleaseReadinessHtml, pickScenarios, createFixtureRoot, collectFixtureFiles, assertSafeWrites, renderSmokeReport, evaluateSmokeAssertion, getInstallSmokePlan, } from '@shrkcrft/inspector';
+import { buildReleaseReadiness, detectSharkcraftRepo, inspectSharkcraft, ReleaseReadinessSeverity, renderReleaseReadinessHtml, pickScenarios, createFixtureRoot, collectFixtureFiles, assertSafeWrites, renderSmokeReport, evaluateSmokeAssertion, getInstallSmokePlan, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const SMOKE_SCENARIO_IDS = [
     'unconfigured-repo',
@@ -446,8 +447,10 @@ async function runInstallSmoke(args) {
         return runInstallSmokeTarball(args);
     }
     const cwd = resolveCwd(args);
+    // `cliEntry` is only WHERE the in-repo CLI lives; whether this IS the tool
+    // repo is decided by the one host authority (round 11 §5.1).
     const cliEntry = nodePath.join(cwd, 'packages', 'cli', 'src', 'main.ts');
-    const isRepo = existsSync(cliEntry);
+    const isRepo = detectSharkcraftRepo(cwd);
     const stepResults = [];
     for (const step of getInstallSmokePlan()) {
         const start = Date.now();
@@ -544,31 +547,88 @@ async function runReadiness(args) {
         }
     }
     // Knowledge stale-check.
-    const cfgKnowledge = inspection.config
-        ?.knowledgeCheck;
+    const cfgKnowledge = inspection.config?.knowledgeCheck;
     if (includeKnowledgeCheck || cfgKnowledge?.enabled) {
-        const { buildKnowledgeStaleReport, ReferenceCheckOutcome } = await import('@shrkcrft/inspector');
+        const { buildKnowledgeStaleReport, describeInspectionDiscovery } = await import('@shrkcrft/inspector');
+        const { evaluateKnowledgeStaleGate, knowledgeStaleGateInput, settleKnowledgeStaleGate } = await import("../knowledge/knowledge-stale-gate.js");
+        // Warm (with the CLI command index) before resolving — the same warm the
+        // stale-check verb does, so readiness cannot read a correct playbook /
+        // policy / helper id as broken.
+        await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
         const staleReport = buildKnowledgeStaleReport(inspection);
-        let requiredFailing = 0;
-        for (const c of staleReport.referenceChecks) {
-            const isRequired = c.reference.required === true;
-            if (isRequired &&
-                (c.outcome === ReferenceCheckOutcome.Stale || c.outcome === ReferenceCheckOutcome.Missing)) {
-                requiredFailing++;
-            }
-        }
-        const knowledgeStrict = cfgKnowledge?.strict ?? strict;
-        const knowledgeReady = requiredFailing === 0 &&
-            (!knowledgeStrict || staleReport.counts.stale === 0);
-        report.knowledgeCheck = {
+        // THE stale-check verdict — the verb's own input builder, gate and settle.
+        // `knowledgeCheck.ready` is exactly `shrk knowledge stale-check` exiting 0:
+        // an unexamined corpus (unverifiable entries, a file that never loaded) is
+        // never ready, and a stale reference fails it as the verb does.
+        const gateInput = knowledgeStaleGateInput({
+            flags: {},
+            knowledgeCheck: cfgKnowledge,
+            discovery: describeInspectionDiscovery(inspection, cwd),
+            scoped: false,
+        });
+        const cov = staleReport.coverage;
+        const common = {
             enabled: true,
-            strict: knowledgeStrict,
+            strict: cfgKnowledge?.strict === true,
+            failOn: [...gateInput.failOn],
             counts: staleReport.counts,
-            requiredFailing,
-            ready: knowledgeReady,
+            coverage: cov,
+            unverifiableIds: staleReport.unverifiableIds,
+            ...(gateInput.minReferenced ? { minReferenced: gateInput.minReferenced.ratio } : {}),
+            requireReferences: gateInput.requireReferences,
+            repro: 'shrk knowledge stale-check',
         };
+        let knowledgeReady;
+        let knowledgeMessage;
+        if (gateInput.usageProblem) {
+            knowledgeReady = false;
+            knowledgeMessage = gateInput.usageProblem;
+            report.knowledgeCheck = {
+                ...common,
+                exit: 3,
+                verdict: 'usage-error',
+                reasons: [gateInput.usageProblem],
+                shortfalls: [],
+                accepted: [],
+                ready: false,
+            };
+        }
+        else {
+            const gate = evaluateKnowledgeStaleGate(staleReport, gateInput);
+            const settled = settleKnowledgeStaleGate(gate);
+            knowledgeReady = settled.exit === 0;
+            knowledgeMessage =
+                gate.reasons.length > 0
+                    ? gate.reasons.join('; ')
+                    : settled.shortfalls.length > 0
+                        ? `NOT VERIFIED — ${settled.shortfalls.slice(0, 3).join('; ')}`
+                        : `${cov.verified} of ${cov.entriesInScope} knowledge entries verified`;
+            report.knowledgeCheck = {
+                ...common,
+                requiredFailing: gate.requiredStale + gate.requiredMissing,
+                reasons: gate.reasons,
+                exit: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+                ready: knowledgeReady,
+            };
+        }
         if (!knowledgeReady) {
             report.ready = false;
+            // Name the blocker: a NOT READY with no blocker listed sends the reader
+            // hunting for the cause.
+            report.blockers = [
+                ...report.blockers,
+                {
+                    id: 'knowledge-check',
+                    title: 'Knowledge stale-check',
+                    status: 'fail',
+                    severity: ReleaseReadinessSeverity.Error,
+                    message: knowledgeMessage,
+                    suggestion: 'shrk knowledge stale-check',
+                },
+            ];
         }
     }
     const wantHtml = flagBool(args, 'html');
@@ -619,6 +679,19 @@ async function runReadiness(args) {
 }
 export const releaseCommand = {
     name: 'release',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'readiness',
+            description: 'Release readiness aggregator — docs, changelog, examples, preflight.',
+            usage: 'shrk release readiness [--strict] [--preflight <file|dir|auto>] [--html] [--report] [--json] [--with-docs-check] [--with-examples-check]',
+        },
+        {
+            name: 'smoke',
+            description: 'Release smoke harness (writes only into temp fixtures).',
+            usage: 'shrk release smoke [--scenario all|<id>] [--temp-dir <path>] [--keep-temp] [--json] [--report] [--html]',
+        },
+    ],
     description: 'Release readiness aggregator + smoke harness. Read-only verdicts; smoke writes only into temp fixtures.',
     usage: 'shrk release readiness [--strict] [--preflight <file|dir|auto>] [--html] [--report] [--json] [--with-docs-check] [--with-examples-check]\n  shrk release smoke [--scenario all|<id>] [--temp-dir <path>] [--keep-temp] [--json] [--report] [--html]',
     async run(args) {
@@ -628,6 +701,12 @@ export const releaseCommand = {
         if (sub === 'readiness')
             return runReadiness({ ...args, positional: args.positional.slice(1) });
         process.stderr.write('Usage: shrk release readiness | smoke\n');
+        // Both subverbs maintain SharkCraft itself (the surface gate refuses them
+        // with 78 elsewhere) — outside its repository say so, and name the gate that
+        // does apply, instead of a usage line listing only refused verbs.
+        if (!detectSharkcraftRepo(resolveCwd(args))) {
+            process.stderr.write("  Both maintain SharkCraft itself and do not apply to this repository (they exit 78 here). This repository's own gate: `shrk quality`.\n");
+        }
         return 2;
     },
 };

package/dist/commands/report.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.command.d.ts","sourceRoot":"","sources":["../../src/commands/report.command.ts"],"names":[],"mappings":"AAgCA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,aAAa,EAAE,eAwC3B,CAAC"}
+{"version":3,"file":"report.command.d.ts","sourceRoot":"","sources":["../../src/commands/report.command.ts"],"names":[],"mappings":"AAgCA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAehC,eAAO,MAAM,aAAa,EAAE,eA2E3B,CAAC"}