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

package/dist/search-tuning-registry.js

@@ -1,18 +1,115 @@
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { importModuleViaLoader } from '@shrkcrft/core';
+import { describeEntryValue, importModuleViaLoader, indexListPath, isMarkerObject, MARKABLE_UNIT_LISTS, MarkableUnitList, normalizeUnitMap, readContributionExport, RejectionCause, stampUnitMarks, unitProblemsOf, } from '@shrkcrft/core';
+import { isSearchDocumentPrefix, parseSearchDocumentId, SEARCH_DOCUMENT_PREFIXES, searchKindForPrefix, } from "./search-document-id.js";
 export const SEARCH_TUNING_SCHEMA = 'sharkcraft.search-tuning-registry/v1';
 const CACHE = new Map();
 const MAX_BOOST = 5;
-async function importDefault(file) {
-    const mod = (await importModuleViaLoader(file));
-    if (Array.isArray(mod.default))
-        return mod.default;
-    if (mod.default && typeof mod.default === 'object')
-        return [mod.default];
-    if (Array.isArray(mod.searchTuning))
-        return mod.searchTuning;
-    return [];
+/** The per-boost clamp: every single boost value is clamped to ±this. */
+export const SEARCH_TUNING_BOOST_CLAMP = MAX_BOOST;
+/** The global cap: the total tuning delta on ONE document is clamped to ±this. */
+export const SEARCH_TUNING_TOTAL_CAP = MAX_BOOST * 2;
+async function importTunings(file) {
+    return readContributionExport(await importModuleViaLoader(file), { namedKeys: ['searchTuning'] });
+}
+/** THE list paths of the markable boost maps — the loader's marks and the lint's observations share them. */
+export const SEARCH_TUNING_BOOST_IDS = MARKABLE_UNIT_LISTS[MarkableUnitList.SearchTuningBoostIds].listPath;
+const TASK_HINT_BOOST_IDS = MARKABLE_UNIT_LISTS[MarkableUnitList.SearchTuningTaskHintBoostIds].listPath;
+/** `taskHints[<i>].boostIds` — THE path a task hint's marks and observations are keyed by. */
+export function searchTuningTaskHintBoostIdsPath(index) {
+    return indexListPath(TASK_HINT_BOOST_IDS, index);
+}
+/**
+ * A markable boost map (`boostIds`, `taskHints[i].boostIds`): THE core parser's
+ * problems (a value neither a number nor a `{ weight, expectEmpty: true }`
+ * marker — alpha.30 silently clamped such a value to 0), plus a marker on a key
+ * that can NEVER fire (no `<kind>:` search-document prefix, or a kind the
+ * entry's `appliesToKinds` excludes): those are defects, and an expectEmpty
+ * marker accepts only a target that does not exist yet.
+ */
+function markableBoostProblems(record, listPath, appliesToKinds) {
+    const n = normalizeUnitMap(record, listPath);
+    if (!n.ok)
+        return [...unitProblemsOf(n.error)];
+    const out = [];
+    for (const m of n.value.marks) {
+        const at = `${listPath}[${JSON.stringify(m.unit)}]`;
+        const parsed = parseSearchDocumentId(m.unit);
+        if (!parsed || !isSearchDocumentPrefix(parsed.prefix)) {
+            out.push(`${at}: an expectEmpty marker on a key that can never fire — a boost key is a search-document id \`<kind>:<id>\` (${SEARCH_DOCUMENT_PREFIXES.join(', ')}); fix the key (a marker accepts only a target that does not exist yet)`);
+            continue;
+        }
+        const kind = searchKindForPrefix(parsed.prefix) ?? parsed.prefix;
+        if (Array.isArray(appliesToKinds) && !appliesToKinds.includes(kind)) {
+            out.push(`${at}: an expectEmpty marker on a ${kind} key its entry's appliesToKinds [${appliesToKinds.join(', ')}] excludes, so the boost can never fire — fix the key or appliesToKinds`);
+        }
+    }
+    return out;
+}
+/** A plain boost map (`boostTags`, `boostSources`, `taskHints[i].boostTags|boostKinds`): numbers only. */
+function plainBoostProblems(record, field) {
+    if (!isMarkerObject(record))
+        return [`${field}: must be a map of name → number (got ${describeEntryValue(record)})`];
+    const out = [];
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === 'number')
+            continue;
+        out.push(`${field}[${JSON.stringify(key)}]: must be a number (got ${describeEntryValue(value)})${isMarkerObject(value)
+            ? ' — an expectEmpty marker is accepted only in boostIds and taskHints[].boostIds, whose keys name documents'
+            : ''}`);
+    }
+    return out;
+}
+/**
+ * THE search-tuning acceptance predicate (round 12, 12.1; round 13): a
+ * non-empty string `id`, and — so an older engine's silent clamp-to-0 can never
+ * recur here — every boost value a number (or, in `boostIds` /
+ * `taskHints[].boostIds`, a well-formed `{ weight, expectEmpty: true, reason? }`
+ * marker on a key that can fire), `taskHints` an array of objects with string
+ * `whenTokens`, and no authored `expectEmptyUnits` (the loader derives it).
+ * `[]` means accepted.
+ */
+export function searchTuningRejectionReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['(entry): must be an object'];
+    const o = raw;
+    const out = [];
+    if (!(typeof o.id === 'string' && o.id.length > 0))
+        out.push('id: must be a non-empty string');
+    if ('expectEmptyUnits' in o) {
+        out.push(`expectEmptyUnits: derived by the loader — mark the boost itself: boostIds: { '<kind>:<id>': { weight, expectEmpty: true } }`);
+    }
+    if (o.boostIds !== undefined)
+        out.push(...markableBoostProblems(o.boostIds, SEARCH_TUNING_BOOST_IDS, o.appliesToKinds));
+    for (const field of ['boostTags', 'boostSources']) {
+        if (o[field] !== undefined)
+            out.push(...plainBoostProblems(o[field], field));
+    }
+    if (o.taskHints !== undefined) {
+        if (!Array.isArray(o.taskHints)) {
+            out.push(`taskHints: must be an array (got ${describeEntryValue(o.taskHints)})`);
+        }
+        else {
+            o.taskHints.forEach((h, i) => {
+                if (!isMarkerObject(h)) {
+                    out.push(`taskHints[${i}]: must be an object (got ${describeEntryValue(h)})`);
+                    return;
+                }
+                const tokens = h['whenTokens'];
+                if (tokens !== undefined && (!Array.isArray(tokens) || tokens.some((t) => typeof t !== 'string'))) {
+                    out.push(`taskHints[${i}].whenTokens: must be an array of strings (got ${describeEntryValue(tokens)})`);
+                }
+                if (h['boostIds'] !== undefined) {
+                    out.push(...markableBoostProblems(h['boostIds'], searchTuningTaskHintBoostIdsPath(i), o.appliesToKinds));
+                }
+                for (const field of ['boostTags', 'boostKinds']) {
+                    if (h[field] !== undefined)
+                        out.push(...plainBoostProblems(h[field], `taskHints[${i}].${field}`));
+                }
+            });
+        }
+    }
+    return out;
 }
 function localTuningFiles(inspection) {
     const out = [];
@@ -24,10 +121,9 @@ function localTuningFiles(inspection) {
         if (existsSync(full))
             out.push(full);
     }
-    const cfg = inspection.config;
-    for (const rel of cfg?.searchTuningFiles ?? []) {
-        out.push(nodePath.join(dir, rel));
-    }
+    // More tuning files come from pack manifests (`contributions.searchTuningFiles`,
+    // loaded below; docs/search-tuning.md) — there is no local-config key for
+    // them; the strict config schema rejects one, so a local read could never run.
     return out;
 }
 function clampBoost(value) {
@@ -39,14 +135,62 @@ function clampBoost(value) {
         return -MAX_BOOST;
     return value;
 }
-function sanitize(raw, source, packageName, sourceFile, issues) {
-    if (typeof raw.id !== 'string' || raw.id.length === 0) {
+function sanitize(input, source, packageName, sourceFile, issues, rejected, at) {
+    const reasons = searchTuningRejectionReasons(input);
+    if (reasons.length > 0) {
+        // `search tuning doctor` keeps its `missing-id` warning; THE rejection
+        // channel carries the structured record every other surface reads. An
+        // entry refused for anything else (round 13: a boost value that is neither
+        // a number nor a well-formed marker, a marker on a key that can never
+        // fire) is an ERROR — it used to load with the value clamped to 0.
+        const rawId = input.id;
+        const entryId = typeof rawId === 'string' && rawId.length > 0 ? rawId : undefined;
+        const where = `${sourceFile} (${at.exportName ?? 'default'}[${at.index}])`;
+        issues.push(entryId === undefined
+            ? { severity: 'warning', code: 'missing-id', message: `Tuning entry ${where} has no id; skipped.`, source: sourceFile }
+            : {
+                severity: 'error',
+                code: 'invalid-entry',
+                message: `Tuning entry "${entryId}" in ${where} was rejected — ${reasons.join('; ')}.`,
+                tuningId: entryId,
+                source: sourceFile,
+            });
+        rejected.push({ ...at, ...(entryId !== undefined ? { entryId } : {}), reasons, cause: RejectionCause.Invalid });
+        return null;
+    }
+    const raw = input;
+    // THE value-form parser BEFORE the clamp (round 13): a `{ weight, expectEmpty }`
+    // value keeps its weight and joins the ledger — it is never clamped to 0 again.
+    const marks = [];
+    const idMaps = [];
+    const idMapProblems = [];
+    for (const [record, listPath] of [
+        [raw.boostIds, SEARCH_TUNING_BOOST_IDS],
+        ...(raw.taskHints ?? []).map((h, i) => [h.boostIds, searchTuningTaskHintBoostIdsPath(i)]),
+    ]) {
+        if (record === undefined) {
+            idMaps.push(undefined);
+            continue;
+        }
+        const n = normalizeUnitMap(record, listPath);
+        if (!n.ok) {
+            idMapProblems.push(...unitProblemsOf(n.error));
+            idMaps.push(undefined);
+            continue;
+        }
+        marks.push(...n.value.marks);
+        idMaps.push({ ...n.value.values });
+    }
+    if (idMapProblems.length > 0) {
+        // Unreachable past the predicate; a refusal, never a silent clamp.
         issues.push({
-            severity: 'warning',
-            code: 'missing-id',
-            message: 'Tuning entry has no id; skipped.',
+            severity: 'error',
+            code: 'invalid-entry',
+            message: `Tuning entry "${raw.id}" in ${sourceFile} was rejected — ${idMapProblems.join('; ')}.`,
+            tuningId: raw.id,
             source: sourceFile,
         });
+        rejected.push({ ...at, entryId: raw.id, reasons: idMapProblems, cause: RejectionCause.Invalid });
         return null;
     }
     const out = {
@@ -55,12 +199,17 @@ function sanitize(raw, source, packageName, sourceFile, issues) {
         ...(packageName ? { packageName } : {}),
         sourceFile,
     };
+    const stamped = stampUnitMarks(marks, packageName);
+    if (stamped.length > 0)
+        out.expectEmptyUnits = stamped;
     if (raw.appliesToKinds)
         out.appliesToKinds = raw.appliesToKinds;
     if (raw.mergeStrategy === 'sum' || raw.mergeStrategy === 'max') {
         out.mergeStrategy = raw.mergeStrategy;
     }
-    const sanitizeRecord = (rec) => {
+    // `field` names the map a clamped key came from, so a consumer can tell a
+    // search-document id (`boostIds`) from a tag / source / kind name.
+    const sanitizeRecord = (rec, field) => {
         if (!rec)
             return undefined;
         const result = {};
@@ -73,28 +222,35 @@ function sanitize(raw, source, packageName, sourceFile, issues) {
                     message: `Boost for "${k}" clamped to ${clamped} (was ${v}).`,
                     tuningId: raw.id,
                     source: sourceFile,
+                    key: k,
+                    field,
+                    original: v,
+                    clamped,
                 });
             }
             result[k] = clamped;
         }
         return result;
     };
-    const boostTags = sanitizeRecord(raw.boostTags);
+    const boostTags = sanitizeRecord(raw.boostTags, 'boostTags');
     if (boostTags)
         out.boostTags = boostTags;
-    const boostIds = sanitizeRecord(raw.boostIds);
+    const boostIds = sanitizeRecord(idMaps[0], SEARCH_TUNING_BOOST_IDS);
     if (boostIds)
         out.boostIds = boostIds;
-    const boostSources = sanitizeRecord(raw.boostSources);
+    const boostSources = sanitizeRecord(raw.boostSources, 'boostSources');
     if (boostSources)
         out.boostSources = boostSources;
     if (raw.taskHints) {
-        out.taskHints = raw.taskHints.map((h) => ({
-            ...(h.whenTokens ? { whenTokens: h.whenTokens.map((t) => t.toLowerCase()) } : {}),
-            ...(h.boostTags ? { boostTags: sanitizeRecord(h.boostTags) } : {}),
-            ...(h.boostKinds ? { boostKinds: sanitizeRecord(h.boostKinds) } : {}),
-            ...(h.boostIds ? { boostIds: sanitizeRecord(h.boostIds) } : {}),
-        }));
+        out.taskHints = raw.taskHints.map((h, i) => {
+            const ids = idMaps[i + 1];
+            return {
+                ...(h.whenTokens ? { whenTokens: h.whenTokens.map((t) => t.toLowerCase()) } : {}),
+                ...(h.boostTags ? { boostTags: sanitizeRecord(h.boostTags, `taskHints[${i}].boostTags`) } : {}),
+                ...(h.boostKinds ? { boostKinds: sanitizeRecord(h.boostKinds, `taskHints[${i}].boostKinds`) } : {}),
+                ...(ids ? { boostIds: sanitizeRecord(ids, searchTuningTaskHintBoostIdsPath(i)) } : {}),
+            };
+        });
     }
     return out;
 }
@@ -104,18 +260,25 @@ export async function loadSearchTuning(inspection) {
         .join(',')}`;
     const cached = CACHE.get(inspection.projectRoot);
     if (cached && cached.cacheKey === cacheKey) {
-        return { entries: cached.entries, issues: cached.issues };
+        return { entries: cached.entries, issues: cached.issues, rejected: cached.rejected };
     }
     const entries = [];
     const issues = [];
+    const rejected = [];
+    const ingestAll = (exp, file, source, packageName, sourceFile) => {
+        exp.items.forEach((raw, i) => {
+            const ent = sanitize(raw, source, packageName, sourceFile, issues, rejected, {
+                file,
+                index: exp.single ? -1 : i,
+                ...(exp.exportName ? { exportName: exp.exportName } : {}),
+            });
+            if (ent)
+                entries.push(ent);
+        });
+    };
     for (const file of localTuningFiles(inspection)) {
         try {
-            const list = await importDefault(file);
-            for (const raw of list) {
-                const ent = sanitize(raw, 'local', undefined, nodePath.relative(inspection.projectRoot, file), issues);
-                if (ent)
-                    entries.push(ent);
-            }
+            ingestAll(await importTunings(file), file, 'local', undefined, nodePath.relative(inspection.projectRoot, file));
         }
         catch (e) {
             issues.push({
@@ -140,12 +303,7 @@ export async function loadSearchTuning(inspection) {
                 continue;
             }
             try {
-                const list = await importDefault(file);
-                for (const raw of list) {
-                    const ent = sanitize(raw, 'pack', pack.packageName, rel, issues);
-                    if (ent)
-                        entries.push(ent);
-                }
+                ingestAll(await importTunings(file), file, 'pack', pack.packageName, rel);
             }
             catch (e) {
                 issues.push({
@@ -157,8 +315,8 @@ export async function loadSearchTuning(inspection) {
             }
         }
     }
-    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues });
-    return { entries, issues };
+    CACHE.set(inspection.projectRoot, { cacheKey, entries, issues, rejected });
+    return { entries, issues, rejected };
 }
 export function listSearchTuning(inspection) {
     const cached = CACHE.get(inspection.projectRoot);
@@ -286,10 +444,17 @@ export function tuningBoostFor(doc, tokens, entries) {
             reasons.push(`tuning:${c.tuningId} ${key} ${c.value > 0 ? '+' : ''}${c.value}${contributors.length > 1 ? ' (strategy=' + strategy + ')' : ''}`);
         }
     }
-    // Global cap so tuning can't dominate the natural signal.
-    if (delta > MAX_BOOST * 2)
-        delta = MAX_BOOST * 2;
-    if (delta < -MAX_BOOST * 2)
-        delta = -MAX_BOOST * 2;
+    // Global cap so tuning can't dominate the natural signal — reported, never
+    // silent: the reason names what was discarded.
+    const raw = delta;
+    if (delta > SEARCH_TUNING_TOTAL_CAP)
+        delta = SEARCH_TUNING_TOTAL_CAP;
+    if (delta < -SEARCH_TUNING_TOTAL_CAP)
+        delta = -SEARCH_TUNING_TOTAL_CAP;
+    if (delta !== raw) {
+        const signed = (n) => `${n > 0 ? '+' : ''}${n}`;
+        reasons.push(`tuning-cap: raw ${signed(raw)} -> ${signed(delta)}`);
+        return { delta, reasons, composition, capped: { raw, applied: delta } };
+    }
     return { delta, reasons, composition };
 }

package/dist/self-audit.d.ts

@@ -35,6 +35,18 @@ export interface ISelfAuditReport {
     findings: readonly ISelfAuditFinding[];
     ok: boolean;
 }
+/**
+ * THE host authority: is `projectRoot` SharkCraft's OWN repository? Every
+ * "is this the tool repo" decision reads it — `self audit`, `install smoke`,
+ * the MCP self-audit tool, and the surface tier resolver that gates
+ * tool-maintenance commands (round 11 §5.1) everywhere else.
+ *
+ * The tool's identity is its CLI package: `packages/cli/package.json` named
+ * `@shrkcrft/cli`, plus either the root package named `sharkcraft` or the
+ * sibling inspector + mcp-server packages. Directory markers alone would
+ * misfire on any consumer monorepo that happens to have `packages/cli`,
+ * `packages/inspector` and `packages/mcp-server`.
+ */
 export declare function detectSharkcraftRepo(projectRoot: string): boolean;
 export interface ISelfAuditInput {
     /** Caller can pass pre-computed verdicts. */

package/dist/self-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-audit.d.ts","sourceRoot":"","sources":["../src/self-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAajE;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,qBAAqB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,eAAoB,GAAG,gBAAgB,CAgIjG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAWpE"}
+{"version":3,"file":"self-audit.d.ts","sourceRoot":"","sources":["../src/self-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,EAAE,EAAE,OAAO,CAAC;CACb;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAYjE;AAYD,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,qBAAqB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,eAAoB,GAAG,gBAAgB,CAkIjG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAWpE"}

package/dist/self-audit.js

@@ -21,20 +21,44 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 export const SELF_AUDIT_SCHEMA = 'sharkcraft.self-audit/v1';
+/** The package name of the CLI inside SharkCraft's own repository. */
+const TOOL_CLI_PACKAGE = '@shrkcrft/cli';
+/**
+ * THE host authority: is `projectRoot` SharkCraft's OWN repository? Every
+ * "is this the tool repo" decision reads it — `self audit`, `install smoke`,
+ * the MCP self-audit tool, and the surface tier resolver that gates
+ * tool-maintenance commands (round 11 §5.1) everywhere else.
+ *
+ * The tool's identity is its CLI package: `packages/cli/package.json` named
+ * `@shrkcrft/cli`, plus either the root package named `sharkcraft` or the
+ * sibling inspector + mcp-server packages. Directory markers alone would
+ * misfire on any consumer monorepo that happens to have `packages/cli`,
+ * `packages/inspector` and `packages/mcp-server`.
+ */
 export function detectSharkcraftRepo(projectRoot) {
     const pkgFile = nodePath.join(projectRoot, 'package.json');
     if (!existsSync(pkgFile))
         return false;
     try {
         const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+        if (!hasToolCliPackage(projectRoot))
+            return false;
         if (pkg.name === 'sharkcraft')
             return true;
-        // Heuristic: monorepo with packages/cli + packages/inspector + packages/mcp-server.
-        const markers = ['packages/cli', 'packages/inspector', 'packages/mcp-server'];
-        if (markers.every((m) => existsSync(nodePath.join(projectRoot, m))))
-            return true;
+        const markers = ['packages/inspector', 'packages/mcp-server'];
+        return markers.every((m) => existsSync(nodePath.join(projectRoot, m)));
+    }
+    catch {
         return false;
     }
+}
+function hasToolCliPackage(projectRoot) {
+    const cliPkg = nodePath.join(projectRoot, 'packages', 'cli', 'package.json');
+    if (!existsSync(cliPkg))
+        return false;
+    try {
+        return JSON.parse(readFileSync(cliPkg, 'utf8')).name === TOOL_CLI_PACKAGE;
+    }
     catch {
         return false;
     }
@@ -52,8 +76,10 @@ export function buildSelfAudit(projectRoot, input = {}) {
                     id: 'not-sharkcraft-repo',
                     title: 'Self audit applies only to the SharkCraft monorepo',
                     status: 'skipped',
-                    message: 'Run `shrk release readiness` instead for a generic readiness verdict.',
-                    nextCommand: 'shrk release readiness',
+                    // `release readiness` is itself a tool-maintenance command (gated
+                    // outside the tool repo); `quality` is the consumer's own gate.
+                    message: 'Run `shrk quality` instead for this repository\'s own pre-push verdict.',
+                    nextCommand: 'shrk quality',
                 },
             ],
             ok: true,
@@ -129,8 +155,8 @@ export function buildSelfAudit(projectRoot, input = {}) {
             id: 'mcp-audit',
             title: 'MCP audit — no write tools',
             status: 'skipped',
-            message: 'No verdict supplied — run `shrk mcp audit`.',
-            nextCommand: 'shrk mcp audit',
+            message: 'No verdict supplied — run `shrk safety audit`.',
+            nextCommand: 'shrk safety audit',
         });
     }
     else if (input.mcpAuditWriteToolCount === 0) {
@@ -147,7 +173,7 @@ export function buildSelfAudit(projectRoot, input = {}) {
             title: 'MCP audit — no write tools',
             status: 'fail',
             message: `${input.mcpAuditWriteToolCount} MCP tool(s) report write capability — this breaks the safety contract.`,
-            nextCommand: 'shrk mcp audit',
+            nextCommand: 'shrk safety audit',
         });
     }
     const flag = (id, title, ok, nextCommand) => {
@@ -166,7 +192,7 @@ export function buildSelfAudit(projectRoot, input = {}) {
     flag('runtime-doctor', 'Runtime doctor', input.runtimeDoctorOk ?? null, 'shrk runtime doctor');
     flag('compat-node', 'compat:node', input.compatNodeOk ?? null, 'bun run compat:node');
     flag('packs-doctor', 'Packs doctor', input.packsDoctorOk ?? null, 'shrk packs doctor --release');
-    flag('demo-package-validate', 'Demo package validate', input.demoPackageValidateOk ?? null, 'shrk demo package --validate');
+    flag('demo-package-validate', 'Demo package validate', input.demoPackageValidateOk ?? null, 'shrk release smoke');
     const ok = findings.filter((f) => f.status === 'fail').length === 0;
     return {
         schema: SELF_AUDIT_SCHEMA,

package/dist/self-config-doctor-v2.d.ts

@@ -1,3 +1,9 @@
+import { RejectionCause, type IUnitLiveness } from '@shrkcrft/core';
+import { ContributionKind } from './contribution-kind.js';
+import type { IUnresolvableReference } from './i-unresolvable-reference.js';
+import type { IUnresolvableReferenceScan } from './i-unresolvable-reference-scan.js';
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IDeclaredXrefReport } from './i-declared-xref-report.js';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
 export declare const SELF_CONFIG_DOCTOR_V2_SCHEMA = "sharkcraft.self-config-doctor/v2";
 export declare enum SelfConfigSeverityV2 {
@@ -7,9 +13,23 @@ export declare enum SelfConfigSeverityV2 {
 }
 /**
  * Source / target kind taxonomy. Open string for forward-compat with
- * pack-contributed kinds, but the engine emits one of these values.
+ * pack-contributed kinds, but the engine emits one of these values:
+ *
+ *   - every reference kind maps onto ITSELF (THE table behind `selfKindOf`);
+ *   - `search-document` — a `<prefix>:<id>` search document whose prefix has no
+ *     id registry (`doc:README.md`), or the cap summary's "N more document(s)":
+ *     it exists (or cannot be checked) — it is never "unknown";
+ *   - `schema` — a declaration-shape finding (relation `validates`) whose target
+ *     id is the field path (`taskHints[1].whenTokens`, `facets.bad-kind[k1]`);
+ *   - `self-config` — the doctor itself (its own probe summaries);
+ *   - every contribution kind maps onto a finding kind (THE table behind
+ *     `rejectionFindingOf`), so a rejected entry of any loader-backed slot —
+ *     a construct facet, a feedback rule, a gate-plane rule — has a kind;
+ *   - `unknown` — RESERVED for a target id that resolves in NO registry, as THE
+ *     id resolver / THE key resolver answered. Only `selfKindOf(undefined)`
+ *     produces it (a source lock holds that; round 12, 12.4).
  */
-export type SelfConfigKind = 'knowledge' | 'command' | 'helper' | 'template' | 'playbook' | 'pipeline' | 'policy' | 'rule' | 'path' | 'convention' | 'registration-hint' | 'routing-hint' | 'agent-test' | 'decision' | 'profile' | 'migration-profile' | 'contract-template' | 'pack' | 'schema' | 'file' | 'unknown';
+export type SelfConfigKind = 'knowledge' | 'command' | 'helper' | 'template' | 'playbook' | 'pipeline' | 'policy' | 'rule' | 'path' | 'convention' | 'registration-hint' | 'routing-hint' | 'agent-test' | 'decision' | 'construct' | 'preset' | 'migration-profile' | 'workspace-profile' | 'contract-template' | 'pack' | 'schema' | 'file' | 'directory' | 'symbol' | 'package' | 'url' | 'path-convention' | 'boundary-rule' | 'scaffold-pattern' | 'search-tuning' | 'search-document' | 'self-config' | 'construct-facet' | 'feedback-rule' | 'context-test' | 'docs' | 'delegate-recipe' | 'framework-extractor' | 'wiring-rule' | 'registry' | 'registration-idiom' | 'policy-rule' | 'reuse-primitive' | 'baseline' | 'generated-artifact' | 'doc-reference' | 'unknown';
 /**
  * Edge relation taxonomy. Open string to allow future relations.
  */
@@ -34,6 +54,11 @@ export interface ISelfConfigFindingV2 {
      *   - low    — derived from regex / fallback parsing
      */
     readonly confidence: 'high' | 'medium' | 'low';
+    /**
+     * How many times the same (source, relation, target, code) was found — one
+     * finding per repeat, never N identical ones sharing a "unique" id.
+     */
+    readonly occurrences?: number;
 }
 export interface ISelfConfigDoctorReportV2 {
     readonly schema: typeof SELF_CONFIG_DOCTOR_V2_SCHEMA;
@@ -48,10 +73,127 @@ export interface ISelfConfigDoctorReportV2 {
         bySourceKind: Readonly<Record<string, number>>;
         byTargetKind: Readonly<Record<string, number>>;
     }>;
-    readonly verdict: 'ok' | 'warnings' | 'errors';
+    /**
+     * `errors` when any error finding; else `unverified` when any `coverage`
+     * record has a shortfall (a dead or unverifiable unit — the CLI exits 2);
+     * else `warnings` / `ok`.
+     */
+    readonly verdict: 'ok' | 'warnings' | 'errors' | 'unverified';
     readonly nextCommands: readonly string[];
+    /**
+     * Per-unit coverage of every probe family — the ONE list both the verdict
+     * above and the CLI's settled exit are derived from (core's
+     * `coverageShortfall`): `command strings`, `search tuning` boost keys and
+     * task hints, `routing hints` and their recommended ids, `registration
+     * hints` discovery selectors and related ids, `scaffold patterns` globs and
+     * patterns. A family with no units contributes no record.
+     */
+    readonly coverage: readonly IVerdictCoverage[];
+    /** Every UNMARKED dead unit (a selector that matches nothing, a boost that never fires), labelled — THE families' settled `dead`. */
+    readonly deadUnits: readonly string[];
+    /**
+     * Round 13: every selector unit THE families' settles did not find live —
+     * dead, intended-empty (its acceptance rides in {@link coverage}), went-live
+     * (a stale `expectEmpty` marker) or unproven — with its state and marker.
+     * What `--fail-on-dead-units` decides on (`selectorUnitFails`, through
+     * `assetDoctorProposedExit`), so a stale LOCAL marker fails there too.
+     */
+    readonly selectorUnits: readonly IUnitLiveness[];
+    /**
+     * Every declared reference the REFERENCE probes could not check — its kind's
+     * registry is empty here (`registry-empty`), or nothing can ever fill it
+     * (`undeclarable-kind`) — attributed to its file and field (round 12,
+     * ONE-CHANGE). Each is an unexamined unit of a coverage record above; `shrk
+     * packs contributions` groups the same list per contributed file.
+     */
+    readonly unresolvableReferences: readonly IUnresolvableReference[];
+    /**
+     * What the probe passes looked at. `command` covers every command string an
+     * asset prescribes (agent tests, routing / registration hints, pipeline
+     * steps, playbooks, constructs, presets, knowledge action hints and
+     * references, decisions), deduped per (asset, command), each resolved
+     * through the injected command resolver. `unverified > 0` means no resolver
+     * was injected (outside the CLI): those strings were NOT checked.
+     */
+    readonly probes: Readonly<{
+        command: Readonly<{
+            probed: number;
+            /** Resolved to a real command (`ok`). */
+            exists: number;
+            /** Verb proven, internally-dispatched tail not provable — counted, never flagged. */
+            prefixOnly: number;
+            /** Not a command this engine checks (git, tsc, …) — skipped, counted. */
+            notShrk: number;
+            /** Did not resolve — one `unknown-command` finding each. */
+            unknown: number;
+            /** Not checked: no command resolver injected. */
+            unverified: number;
+        }>;
+        /**
+         * Distinct search-tuning boost keys (`<kind>:<id>` search-document ids),
+         * resolved within the named kind through THE key resolver.
+         */
+        'search-tuning-target': Readonly<{
+            probed: number;
+            resolved: number;
+            missing: number;
+            unprefixed: number;
+            unknownKind: number;
+            unverified: number;
+        }>;
+        /** Non-command routing-hint `recommends` ids, one per (hint, channel, id). */
+        'routing-hint-target': Readonly<{
+            probed: number;
+            resolved: number;
+            missing: number;
+            unverified: number;
+        }>;
+    }>;
+    /**
+     * The declared cross-reference pass (round 11, 4.2): every id in a
+     * `related`-style asset field, resolved through the reference registry by
+     * THE collector (`declared-cross-references.ts`). What it examined is
+     * reported even when nothing dangles, so a pass over zero ids never reads as
+     * a clean one; its coverage record rides in {@link coverage}.
+     */
+    readonly crossReferences?: Readonly<{
+        examined: IDeclaredXrefReport['examined'];
+        counts: IDeclaredXrefReport['counts'];
+        summary: string;
+    }>;
 }
+/** A rejected entry's finding kind and code — THE table above, never a fallback. */
+export declare function rejectionFindingOf(kind: ContributionKind, cause: RejectionCause): {
+    readonly kind: SelfConfigKind;
+    readonly code: string;
+    readonly doctor: string;
+};
+/**
+ * THE "this finding reports a reference that resolved nowhere" predicate: a
+ * `*-missing` code (an id, or a referenced file), any severity — the family
+ * r73 reads as "unknown id". The CLI's exit-0 line counts the INFO-severity
+ * ones instead of certifying "every checked probe resolved" over them.
+ */
+export declare function isUnresolvedReferenceFinding(finding: Pick<ISelfConfigFindingV2, 'code'>): boolean;
+/**
+ * THE "this reference resolved, but only as a kind its field does not accept"
+ * predicate: a `*-wrong-kind` code (`xref-wrong-kind`, a pipeline step naming a
+ * construct). Not unresolved — `unknown:` is reserved for that — and not a
+ * clean resolution either, so the CLI's exit-0 line counts an info-severity one
+ * instead of certifying "every checked probe resolved".
+ */
+export declare function isWrongKindReferenceFinding(finding: Pick<ISelfConfigFindingV2, 'code'>): boolean;
 export declare function buildSelfConfigDoctorReportV2(inspection: ISharkcraftInspection): Promise<ISelfConfigDoctorReportV2>;
+/**
+ * Every declared reference that could not be resolved because its kind's
+ * registry is empty here, or can never be filled (round 12, ONE-CHANGE) —
+ * running EXACTLY the doctor's reference probes (template metadata, routing
+ * `recommends`, registration-hint and convention id fields, declared
+ * cross-references) over a warmed inspection, without the rest of the doctor.
+ * `buildSelfConfigDoctorReportV2` carries the same list, so the doctor and
+ * `shrk packs contributions` cannot disagree.
+ */
+export declare function collectUnresolvableReferences(inspection: ISharkcraftInspection): Promise<IUnresolvableReferenceScan>;
 export declare function renderSelfConfigDoctorV2Text(report: ISelfConfigDoctorReportV2): string;
 export declare function renderSelfConfigDoctorV2Markdown(report: ISelfConfigDoctorReportV2): string;
 //# sourceMappingURL=self-config-doctor-v2.d.ts.map