@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.32

package/dist/knowledge-stale-gate.js

@@ -0,0 +1,501 @@
+import { ruleVerdictRecords, settleVerdict } from '@shrkcrft/core';
+import { formatKnowledgeReference } from '@shrkcrft/knowledge';
+import { declaredReferenceCoverage } from "./declared-reference-coverage.js";
+import { KnowledgeEntryVerdict } from "./knowledge-entry-verdict.js";
+import { ReferenceCheckOutcome } from "./knowledge-stale.js";
+import { KnowledgeMinReferencedValve } from "./knowledge-min-referenced-valve.js";
+import { REJECTED_AT_LOAD } from "./knowledge-entry-rejections.js";
+import { unverifiableEntryRemedy, unverifiableRemedy } from "./knowledge-unverifiable-remedy.js";
+import { ReferenceFailure } from "./reference-failure.js";
+/** The stale-check rule of the knowledge entries the loader refused (round 15 follow-up, F3). */
+export const KNOWLEDGE_REJECTED_RULE_ID = 'knowledge-rejected-entries';
+/** The proposed exits (the CLI's `ExitCode` values; the inspector cannot import the CLI). */
+const VERIFIED_PASS = 0;
+const FAILURE = 1;
+const NOT_VERIFIED = 2;
+/**
+ * Every `--fail-on` category. `all` keeps its historical meaning (any stale or
+ * missing reference); the round-11 categories are opt-in BY NAME, so no
+ * existing `--fail-on all` pipeline changes behaviour. (A MALFORMED reference
+ * is never a pass in any mode — it is a coverage shortfall, exit 2;
+ * `--fail-on invalid` makes it a failure, exit 1.)
+ */
+export const KNOWLEDGE_FAIL_ON_CATEGORIES = [
+    'required',
+    'stale',
+    'missing',
+    'all',
+    'unverifiable',
+    'invalid',
+    'path-missing',
+    'anchor-missing',
+    'content',
+    'count',
+    'aged',
+    'implicit',
+];
+/** Unexamined entry ids carried on the coverage record (the full list is in the JSON). */
+const COVERAGE_LABEL_CAP = 20;
+/** Parse `--min-referenced`: a ratio `0..1` or a percentage `NN%`. `null` when malformed. */
+export function parseMinReferenced(raw) {
+    const s = raw.trim();
+    const pct = /^(\d+(?:\.\d+)?)%$/.exec(s);
+    const n = pct ? Number(pct[1]) / 100 : /^(?:\d+(?:\.\d*)?|\.\d+)$/.test(s) ? Number(s) : Number.NaN;
+    return Number.isFinite(n) && n >= 0 && n <= 1 ? n : null;
+}
+/** `0.266…` → `26.7%`, `1` → `100%`. */
+export function formatPct(ratio) {
+    const v = Math.round(ratio * 1000) / 10;
+    return `${Number.isInteger(v) ? v.toFixed(0) : v.toFixed(1)}%`;
+}
+function isFailing(o) {
+    return o === ReferenceCheckOutcome.Stale || o === ReferenceCheckOutcome.Missing;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** Load failures named in prose before the rest are summarised. */
+const LOAD_FAILURES_NAMED = 3;
+/** `sharkcraft/rules.ts (failed: SyntaxError …)` / `sharkcraft/k.ts (missing)`. */
+function loadFailureLabel(f) {
+    return `${f.file} (${f.status === 'missing' ? 'missing' : `${f.status}: ${f.message}`})`;
+}
+/** The first few failed knowledge files, `; `-joined, with `(+N more)`. */
+function loadFailureList(failures) {
+    const named = failures.slice(0, LOAD_FAILURES_NAMED).map(loadFailureLabel).join('; ');
+    return failures.length > LOAD_FAILURES_NAMED ? `${named} (+${failures.length - LOAD_FAILURES_NAMED} more)` : named;
+}
+/** Why the scope is empty — the run coverage's reason, in the reader's terms. */
+function emptyScopeReason(report, input) {
+    const d = input.discovery;
+    if (d.sharkcraftDir === null) {
+        return d.configuredAncestor
+            ? `no sharkcraft/ folder at the resolved root — ${d.configuredAncestor} has one: rerun with --cwd ${d.configuredAncestor}`
+            : 'no sharkcraft/ folder at the resolved root';
+    }
+    if (d.configError !== undefined) {
+        return `sharkcraft.config.ts failed to load (${d.configError}), so no knowledge was loaded`;
+    }
+    const failed = d.knowledgeLoadFailures;
+    if (report.entries === 0 && failed.length > 0) {
+        return `${plural(failed.length, 'knowledge file', 'knowledge files')} never loaded — ${loadFailureList(failed)} — so no knowledge was loaded`;
+    }
+    // Round 15 follow-up (F3): entries WERE declared — the loader refused them all.
+    if (report.entries === 0 && report.rejectedEntries.length > 0) {
+        return `every declared knowledge entry (${report.rejectedEntries.length}) was rejected at load, so none was checked`;
+    }
+    if (report.entries === 0)
+        return 'no knowledge entries are declared';
+    const alsoFailed = failed.length > 0 ? `, and ${plural(failed.length, 'knowledge file', 'knowledge files')} never loaded (${loadFailureList(failed)})` : '';
+    return `none of the ${report.entries} knowledge entries references the changed files${alsoFailed}`;
+}
+/**
+ * Decide the stale-check verdict inputs. Pure: the report, the flags, the
+ * discovery — nothing else.
+ */
+export function evaluateKnowledgeStaleGate(report, input) {
+    const cov = report.coverage;
+    const failOn = input.failOn;
+    const consider = (cat) => failOn.has(cat) || failOn.has('all');
+    let requiredStale = 0;
+    let requiredMissing = 0;
+    for (const c of report.referenceChecks) {
+        if (c.reference.required !== true)
+            continue;
+        if (c.outcome === ReferenceCheckOutcome.Stale)
+            requiredStale += 1;
+        if (c.outcome === ReferenceCheckOutcome.Missing)
+            requiredMissing += 1;
+    }
+    const requiredFailing = requiredStale + requiredMissing;
+    // Declared references on boundary rules / policy checks count like a
+    // knowledge entry's. Implicit ones (a scope glob's dead prefix) are advisory
+    // unless `--fail-on implicit`.
+    const assetFailing = report.assetReferenceChecks.filter((c) => !c.implicit && isFailing(c.outcome));
+    const implicitFailing = report.assetReferenceChecks.filter((c) => c.implicit === true && isFailing(c.outcome));
+    // Every DECLARED reference (knowledge, anchor, boundary rule, policy) is one
+    // population: checkable ones were examined, malformed ones never were.
+    const declaredRefs = [...report.referenceChecks, ...report.assetReferenceChecks.filter((c) => !c.implicit)];
+    const invalidRefs = declaredRefs.filter((c) => c.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidAnchors = report.anchorChecks.filter((a) => a.outcome === ReferenceCheckOutcome.Invalid);
+    const invalidCount = invalidRefs.length + invalidAnchors.length;
+    // Round 15 follow-up (F3): entries the LOADER refused. INVALID-class: never
+    // in scope, never checked — a coverage shortfall of their own rule (exit 2),
+    // a failure under `--fail-on invalid` (exit 1). No valve accepts them:
+    // `--min-referenced` accepts the run's unverifiable remainder and
+    // `--allow-empty` an empty scope, never this rule.
+    const rejected = report.rejectedEntries;
+    const reasons = [];
+    // The historical modes, unchanged (they are mutually exclusive by design).
+    if (input.ci) {
+        if (requiredFailing > 0)
+            reasons.push(`${requiredFailing} required references failing in --ci mode`);
+    }
+    else if (input.strict) {
+        if (requiredFailing > 0)
+            reasons.push(`${requiredFailing} required references failing in --strict mode`);
+    }
+    else if (failOn.size > 0) {
+        if (consider('required') && requiredFailing > 0) {
+            reasons.push(`${requiredFailing} required reference issues (--fail-on=required)`);
+        }
+        if (consider('stale') && report.counts.stale > 0) {
+            reasons.push(`${report.counts.stale} stale references (--fail-on=stale)`);
+        }
+        if (consider('missing') && report.counts.missing > 0) {
+            reasons.push(`${report.counts.missing} missing references (--fail-on=missing)`);
+        }
+        if (failOn.has('all') && assetFailing.length > 0) {
+            reasons.push(`${assetFailing.length} stale boundary-rule / policy references (--fail-on=all)`);
+        }
+    }
+    else {
+        const n = report.counts.missing + report.counts.stale + assetFailing.length;
+        if (n > 0)
+            reasons.push(`${n} stale or missing references (legacy default)`);
+    }
+    // The round-11 categories — each opt-in by name.
+    const byFailure = (f) => report.failureCounts[f] ?? 0;
+    if (failOn.has('path-missing') && byFailure(ReferenceFailure.PathMissing) > 0) {
+        reasons.push(`${byFailure(ReferenceFailure.PathMissing)} path-missing references (--fail-on=path-missing)`);
+    }
+    if (failOn.has('anchor-missing') && byFailure(ReferenceFailure.AnchorMissing) > 0) {
+        reasons.push(`${byFailure(ReferenceFailure.AnchorMissing)} anchor-missing references (--fail-on=anchor-missing)`);
+    }
+    if (failOn.has('content') && byFailure(ReferenceFailure.ContentMismatch) > 0) {
+        reasons.push(`${byFailure(ReferenceFailure.ContentMismatch)} content assertions no longer hold (--fail-on=content)`);
+    }
+    if (failOn.has('count') && byFailure(ReferenceFailure.CountMismatch) > 0) {
+        reasons.push(`${byFailure(ReferenceFailure.CountMismatch)} counts re-derived to a different number (--fail-on=count)`);
+    }
+    if (failOn.has('aged') && (report.age?.aged.length ?? 0) > 0) {
+        reasons.push(`${report.age.aged.length} entries not verified within ${report.age.staleAfterDays}d (--fail-on=aged)`);
+    }
+    if (failOn.has('implicit') && implicitFailing.length > 0) {
+        reasons.push(`${implicitFailing.length} boundary-rule scope globs point at nothing (--fail-on=implicit)`);
+    }
+    if (failOn.has('invalid') && invalidCount > 0) {
+        reasons.push(`${plural(invalidCount, 'malformed reference', 'malformed references')} (--fail-on=invalid)`);
+    }
+    if (failOn.has('invalid') && rejected.length > 0) {
+        reasons.push(`${plural(rejected.length, 'knowledge entry', 'knowledge entries')} rejected at load (--fail-on=invalid)`);
+    }
+    const requireRefs = input.requireReferences || failOn.has('unverifiable');
+    if (requireRefs && cov.unverifiable > 0) {
+        reasons.push(`${plural(cov.unverifiable, 'entry declares', 'entries declare')} no checkable reference (--require-references)`);
+    }
+    if (input.minReferenced && cov.entriesInScope > 0 && cov.referencedRatio < input.minReferenced.ratio) {
+        reasons.push(`reference coverage ${formatPct(cov.referencedRatio)} < ${formatPct(input.minReferenced.ratio)} (${input.minReferenced.acceptedBy})`);
+    }
+    const d = input.discovery;
+    const loadFailures = d.knowledgeLoadFailures;
+    // A load failure is a discovery failure at ANY corpus size: the entries of a
+    // file that never loaded were never checked, so neither a clean sweep of the
+    // rest nor `--allow-empty` can make the run a pass.
+    const discoveryFailed = (d.entriesLoaded === 0 && (d.sharkcraftDir === null || d.configError !== undefined)) || loadFailures.length > 0;
+    const examined = cov.verified + cov.stale;
+    // Propose from what was found. An EMPTY scope proposes 0 and lets the run
+    // coverage (expected 0) settle it — that is what keeps `--allow-empty`
+    // reachable. A non-empty scope that examined nothing proposes 2 outright.
+    const proposed = reasons.length > 0
+        ? FAILURE
+        : cov.entriesInScope > 0 && examined === 0
+            ? NOT_VERIFIED
+            : VERIFIED_PASS;
+    const acceptance = cov.entriesInScope === 0
+        ? discoveryFailed
+            ? {}
+            : input.emptyAcceptance
+        : input.minReferenced
+            ? { acceptedBy: input.minReferenced.acceptedBy, acceptedRatio: input.minReferenced.ratio }
+            : {};
+    const runCoverage = {
+        unit: 'knowledge entries',
+        expected: cov.entriesInScope,
+        examined,
+        ...(report.unverifiableIds.length > 0
+            ? {
+                unexamined: report.unverifiableIds.slice(0, COVERAGE_LABEL_CAP),
+                unexaminedTotal: report.unverifiableIds.length,
+            }
+            : {}),
+        root: d.resolvedRoot,
+        reason: cov.entriesInScope === 0
+            ? emptyScopeReason(report, input)
+            : 'declare no checkable references[] or anchors[], so they were never checked',
+        ...acceptance,
+    };
+    // THE waiver (round 13): references that FAIL (stale / missing) but block
+    // nothing in this mode — `required: false` under --ci / --strict (they fail on
+    // required references only), or outside the chosen --fail-on categories. They
+    // are printed as STALE / MISSING rows, and the ✓ line used to stand over them
+    // in silence ("no stale or missing references"). Recorded as an acceptance
+    // next to the rule's coverage, so it is printed in `accepted` at exit 0 —
+    // never a shortfall, never a failure.
+    const failingLabels = [
+        ...[...report.referenceChecks, ...assetFailing]
+            .filter((c) => isFailing(c.outcome))
+            .map((c) => `${c.entryId} → ${formatKnowledgeReference(c.reference)}`),
+        ...report.anchorChecks.filter((a) => isFailing(a.outcome)).map((a) => `${a.entryId} anchor ${a.anchor.id}`),
+    ];
+    const waivedBy = reasons.length > 0 || failingLabels.length === 0
+        ? undefined
+        : input.ci
+            ? 'required: false (--ci fails on required references only)'
+            : input.strict
+                ? 'required: false (--strict fails on required references only)'
+                : failOn.size > 0
+                    ? `the fail-on categories (${[...failOn].join(', ')})`
+                    : 'the legacy default (it fails on stale or missing references, not on anchors)';
+    const waiver = waivedBy === undefined
+        ? undefined
+        : {
+            unit: 'failing references',
+            expected: failingLabels.length,
+            examined: 0,
+            unexamined: failingLabels.slice(0, COVERAGE_LABEL_CAP),
+            unexaminedTotal: failingLabels.length,
+            reason: 'stale or missing, and waived — this mode does not fail on them',
+            acceptedBy: waivedBy,
+        };
+    const rules = [];
+    if (cov.entriesInScope > 0) {
+        const violations = [];
+        // The file declaring each knowledge entry — a violation names the file to
+        // edit (round 15: a Markdown entry's, its .md).
+        const declaredIn = new Map(report.entryVerdicts.map((v) => [v.entryId, v.source]));
+        for (const c of [...report.referenceChecks, ...assetFailing, ...(failOn.has('implicit') ? implicitFailing : [])]) {
+            if (!isFailing(c.outcome))
+                continue;
+            const file = c.assetKind ? undefined : declaredIn.get(c.entryId);
+            violations.push({
+                id: c.entryId,
+                ...(file !== undefined ? { file } : {}),
+                message: `${formatKnowledgeReference(c.reference)} — ${c.message}`,
+                ...(c.suggestion ? { hint: c.suggestion } : {}),
+            });
+        }
+        for (const a of report.anchorChecks) {
+            if (!isFailing(a.outcome))
+                continue;
+            violations.push({ id: a.entryId, message: `anchor ${a.anchor.id} (${a.anchor.kind}) — ${a.message}` });
+        }
+        if (failOn.has('invalid')) {
+            for (const c of invalidRefs) {
+                violations.push({ id: c.entryId, message: `MALFORMED ${formatKnowledgeReference(c.reference)} — ${c.message}` });
+            }
+            for (const a of invalidAnchors) {
+                violations.push({ id: a.entryId, message: `MALFORMED anchor ${a.anchor.id} — ${a.message}` });
+            }
+        }
+        if (requireRefs) {
+            for (const v of report.entryVerdicts) {
+                if (v.verdict !== KnowledgeEntryVerdict.Unverifiable)
+                    continue;
+                violations.push({
+                    id: v.entryId,
+                    file: v.source,
+                    // THE per-entry remedy (round 15 closing, A4): an entry whose
+                    // references exist but are malformed read "declare references[]".
+                    message: `UNVERIFIABLE (${v.reason ?? 'no checkable reference'}) — ${unverifiableEntryRemedy(v)}`,
+                });
+            }
+        }
+        rules.push({
+            id: 'knowledge-references',
+            type: 'knowledge',
+            status: reasons.length > 0 ? 'failed' : examined === 0 ? 'skipped' : 'passed',
+            severity: 'error',
+            counts: {
+                entries: cov.entriesInScope,
+                verified: cov.verified,
+                stale: cov.stale,
+                unverifiable: cov.unverifiable,
+                references: report.totalReferences,
+                anchors: report.totalAnchors,
+            },
+            violations,
+            ...(examined === 0
+                ? {
+                    skipReason: `no entry in scope declares a checkable reference (${plural(cov.unverifiable, 'entry', 'entries')} unverifiable)`,
+                }
+                : {}),
+            // THE declared-reference fold (`declaredReferenceCoverage`, shared with
+            // the `shrk gate` knowledge-symbol gate): a malformed reference was
+            // declared to be checked and never was — expected, not examined — so a
+            // run with one is never a clean pass.
+            coverage: declaredReferenceCoverage({ references: declaredRefs, anchors: report.anchorChecks }),
+            ...(waiver !== undefined ? { unitAcceptance: waiver } : {}),
+        });
+    }
+    // Round 15 follow-up (F3): knowledge entries the loader REFUSED — their own
+    // rule, pushed at ANY scope and corpus size (a clean sweep of the rest, a
+    // changeset, `--allow-empty` or `--min-referenced` never covers them). By
+    // default `skipped` — nothing was checked, the shortfall settles the run to
+    // 2 — and `failed` under `--fail-on invalid`, the INVALID-class contract of a
+    // malformed reference.
+    if (rejected.length > 0) {
+        const failing = failOn.has('invalid');
+        rules.push({
+            id: KNOWLEDGE_REJECTED_RULE_ID,
+            type: 'knowledge',
+            status: failing ? 'failed' : 'skipped',
+            severity: 'error',
+            counts: { rejected: rejected.length },
+            violations: failing
+                ? rejected.map((r) => ({
+                    id: r.label,
+                    file: r.source,
+                    message: `REJECTED AT LOAD${r.pack !== undefined ? ` (pack ${r.pack})` : ''} — ${r.message}`,
+                }))
+                : [],
+            ...(failing
+                ? {}
+                : { skipReason: `${plural(rejected.length, 'knowledge entry was', 'knowledge entries were')} rejected at load — never checked` }),
+            coverage: {
+                unit: 'knowledge entries',
+                expected: rejected.length,
+                examined: 0,
+                unexamined: rejected.slice(0, COVERAGE_LABEL_CAP).map((r) => r.label),
+                unexaminedTotal: rejected.length,
+                reason: `${REJECTED_AT_LOAD} — the loader refused them (\`shrk self-config doctor\` names why); no valve accepts them`,
+            },
+        });
+    }
+    // Knowledge-bearing files that never loaded: their own rule, so the envelope
+    // names each one and the shortfall rides into the settled verdict whatever
+    // the rest of the corpus proved. `error` — a source that could not be read is
+    // never `evaluated`.
+    if (loadFailures.length > 0) {
+        const attempted = Math.max(d.knowledgeFilesAttempted, loadFailures.length);
+        rules.push({
+            id: 'knowledge-files',
+            type: 'knowledge',
+            status: 'error',
+            severity: 'error',
+            counts: { files: attempted, loaded: attempted - loadFailures.length, failed: loadFailures.length },
+            violations: loadFailures.map((f) => ({
+                id: f.file,
+                file: f.file,
+                message: `${f.kind} file ${f.status === 'missing' ? 'MISSING' : 'FAILED TO LOAD'}${f.packName ? ` (pack ${f.packName})` : ''} — ${f.message}`,
+            })),
+            error: `${plural(loadFailures.length, 'knowledge file', 'knowledge files')} never loaded: ${loadFailureList(loadFailures)}`,
+            coverage: {
+                unit: 'knowledge files',
+                expected: attempted,
+                examined: attempted - loadFailures.length,
+                unexamined: loadFailures.slice(0, COVERAGE_LABEL_CAP).map((f) => f.file),
+                unexaminedTotal: loadFailures.length,
+                reason: 'failed to load (or are declared and missing), so their entries were never checked',
+            },
+        });
+    }
+    // A refused entry's sentence rides next to whichever lead the run has — it is
+    // never the whole story, and never dropped from it (round 15 follow-up, F3).
+    const rejectedLead = rejected.length > 0
+        ? `${plural(rejected.length, 'knowledge entry was', 'knowledge entries were')} rejected at load and never checked (listed above as INVALID): ${rejected
+            .slice(0, LOAD_FAILURES_NAMED)
+            .map((r) => r.label)
+            .join(', ')}${rejected.length > LOAD_FAILURES_NAMED ? ` (+${rejected.length - LOAD_FAILURES_NAMED} more)` : ''} — fix each (\`shrk self-config doctor\` names why); \`--fail-on invalid\` makes this a failure, and no valve accepts it.`
+        : undefined;
+    const loadLead = loadFailures.length > 0
+        ? `${plural(loadFailures.length, 'knowledge file', 'knowledge files')} never loaded, so ${loadFailures.length === 1 ? 'its entries were' : 'their entries were'} never checked: ${loadFailureList(loadFailures)}. Fix the file (\`shrk doctor\` names the error) — --allow-empty never accepts a load failure.`
+        : undefined;
+    const restLead = loadFailures.length > 0
+        ? undefined
+        : discoveryFailed
+            ? `Loaded 0 knowledge entries from ${d.resolvedRoot} — nothing was checked.`
+            : cov.entriesInScope > 0 && cov.unverifiable > 0
+                ? `${plural(cov.unverifiable, 'entry', 'entries')} of ${cov.entriesInScope} (${formatPct(cov.unverifiable / cov.entriesInScope)}) ${cov.unverifiable === 1 ? 'declares' : 'declare'} no checkable reference, so ${cov.unverifiable === 1 ? 'it was' : 'they were'} never checked. ${unverifiableRemedy(report.entryVerdicts, KnowledgeMinReferencedValve.Flag)}`
+                : invalidCount > 0
+                    ? `${plural(invalidCount, 'reference is', 'references are')} MALFORMED (listed above as INVALID) and ${invalidCount === 1 ? 'was' : 'were'} never checked — fix the kind or the missing field; \`--fail-on invalid\` makes this a failure.`
+                    : undefined;
+    const leads = [loadLead, rejectedLead, restLead].filter((l) => l !== undefined);
+    const notVerifiedLead = leads.length > 0 ? leads.join(' ') : undefined;
+    return {
+        proposed,
+        reasons,
+        requiredStale,
+        requiredMissing,
+        rules,
+        runCoverage,
+        discoveryFailed,
+        waived: cov.entriesInScope > 0 && waiver !== undefined ? waiver.expected : 0,
+        ...(notVerifiedLead ? { notVerifiedLead } : {}),
+    };
+}
+/**
+ * A request whose `aged` category (or `--as-of`) has no `--stale-after` window
+ * to measure against can never fire — the vacuous-category class `--fail-on
+ * bogus` is refused for. `undefined` when the request is well-formed.
+ */
+export function knowledgeStaleWindowProblem(failOn, agedFromConfig, staleAfterDays, asOf) {
+    if (staleAfterDays !== undefined)
+        return undefined;
+    if (asOf !== undefined) {
+        return '--as-of dates the --stale-after window; without --stale-after <Nd|Nw|Nm|Ny> it measures nothing.';
+    }
+    if (!failOn.has('aged'))
+        return undefined;
+    return agedFromConfig
+        ? "knowledgeCheck.failOn includes 'aged', which needs a --stale-after <Nd|Nw|Nm|Ny> window — without one no entry can be aged, so the category could never fail. Pass --stale-after, or drop 'aged' from knowledgeCheck.failOn."
+        : '--fail-on aged needs --stale-after <Nd|Nw|Nm|Ny>: without a window no entry can be aged, so the category could never fail.';
+}
+/**
+ * THE stale-check input — the verb's flags folded over the config's
+ * `knowledgeCheck` block. `shrk knowledge stale-check`, `shrk quality`, `shrk
+ * release readiness` and `buildQualityReport` all build their input here, so
+ * for a config-only request the verb's exit, the quality gate and
+ * `knowledgeCheck.ready` are one answer (they used to read the block three
+ * different ways).
+ *
+ * Precedence (a flag wins):
+ *   - `--fail-on` replaces `knowledgeCheck.failOn` wholesale;
+ *   - `knowledgeCheck.strict: true` ("promote any stale to a failure") adds
+ *     `all` to the config's list; the verb's `--strict` / `--ci` (the R30
+ *     required-only modes) take precedence over any `failOn`;
+ *   - `--min-referenced` over `knowledgeCheck.minReferenced` (each printed as
+ *     its own acceptance);
+ *   - `--require-references` OR `knowledgeCheck.requireReferences`;
+ *   - `--allow-empty` is a flag only — never read from config.
+ */
+export function knowledgeStaleGateInput(o) {
+    const f = o.flags;
+    const cfg = o.knowledgeCheck;
+    const flagFailOn = f.failOn ?? [];
+    const fromConfig = flagFailOn.length === 0;
+    const configFailOn = cfg?.failOn ?? [];
+    const failOn = new Set(fromConfig ? configFailOn : flagFailOn);
+    if (fromConfig && cfg?.strict === true)
+        failOn.add('all');
+    const minReferenced = f.minReferenced ??
+        (cfg?.minReferenced !== undefined
+            ? { ratio: cfg.minReferenced, acceptedBy: `knowledgeCheck.minReferenced: ${cfg.minReferenced}` }
+            : undefined);
+    const usageProblem = knowledgeStaleWindowProblem(failOn, fromConfig && configFailOn.includes('aged'), f.staleAfterDays, f.asOf);
+    return {
+        ci: f.ci === true,
+        strict: f.strict === true,
+        failOn,
+        ...(minReferenced ? { minReferenced } : {}),
+        requireReferences: f.requireReferences === true || cfg?.requireReferences === true,
+        emptyAcceptance: f.emptyAcceptance ?? {},
+        scoped: o.scoped,
+        discovery: o.discovery,
+        ...(usageProblem ? { usageProblem } : {}),
+    };
+}
+/**
+ * Settle a stale-check verdict WITHOUT an envelope (`shrk quality`, `shrk
+ * release readiness`, `buildQualityReport`) — exactly the fold
+ * `buildGateEnvelope` applies for the verb: the run coverage plus every rule's
+ * coverage, subject = rule id.
+ */
+export function settleKnowledgeStaleGate(gate) {
+    return settleVerdict(gate.proposed, [
+        gate.runCoverage,
+        // THE fold the envelope applies (round 13): a rule's acceptance rides next
+        // to its coverage (`ruleVerdictRecords`), so quality prints the same waiver.
+        ...gate.rules.flatMap((r) => ruleVerdictRecords(r.coverage, r.unitAcceptance).map((c) => ({ ...c, subject: c.subject ?? r.id }))),
+    ]);
+}

package/dist/knowledge-stale-quality-gate.d.ts

@@ -0,0 +1,26 @@
+import type { IQualityGateResult } from './quality-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/** The quality-bundle gate id of the knowledge stale-check. */
+export declare const KNOWLEDGE_STALE_GATE_ID = "knowledge-stale";
+/**
+ * The knowledge stale-check as ONE quality gate — decided by THE gate the verb
+ * settles (`evaluateKnowledgeStaleGate` + `settleKnowledgeStaleGate`), with the
+ * config's `knowledgeCheck` block standing in for the verb's flags.
+ *
+ * `buildQualityReport` pushes it for every consumer (MCP `get_quality_report`,
+ * the dashboard, the report site), and `shrk quality` maps this same row onto
+ * its bundle item instead of re-deriving it — so the MCP report can no longer
+ * read `pass` over a stale corpus `shrk quality` fails.
+ *
+ *   - an empty corpus, or a changeset no entry references → a DELIBERATE skip
+ *     (`examinedNothing`, non-blocking; `data.skip` names which);
+ *   - a request that can never be evaluated as configured, or a throw →
+ *     `executed: false` (never a pass);
+ *   - settled 1 → blocking failure; settled 2 → `data.partial` (NOT VERIFIED);
+ *     settled 0 → pass.
+ *
+ * `data.settledExit` carries the settled exit so the CLI item's status is the
+ * repro command's exit, by construction.
+ */
+export declare function knowledgeStaleQualityGate(inspection: ISharkcraftInspection, changedFiles?: readonly string[]): Promise<IQualityGateResult>;
+//# sourceMappingURL=knowledge-stale-quality-gate.d.ts.map

package/dist/knowledge-stale-quality-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-quality-gate.d.ts","sourceRoot":"","sources":["../src/knowledge-stale-quality-gate.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAQzD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,qBAAqB,EACjC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CA2G7B"}

package/dist/knowledge-stale-quality-gate.js

@@ -0,0 +1,140 @@
+import { describeInspectionDiscovery } from "./inspection-discovery.js";
+import { knowledgeRejectedEntries } from "./knowledge-entry-rejections.js";
+import { buildKnowledgeStaleReport } from "./knowledge-stale.js";
+import { evaluateKnowledgeStaleGate, formatPct, knowledgeStaleGateInput, settleKnowledgeStaleGate, } from "./knowledge-stale-gate.js";
+import { KnowledgeMinReferencedValve } from "./knowledge-min-referenced-valve.js";
+import { unverifiableFileRemedies, unverifiableRemedy } from "./knowledge-unverifiable-remedy.js";
+import { warmReferenceRegistries } from "./reference-registry.js";
+/** The quality-bundle gate id of the knowledge stale-check. */
+export const KNOWLEDGE_STALE_GATE_ID = 'knowledge-stale';
+/** Unverifiable entry ids carried in the gate's data (the verb's JSON has all of them). */
+const UNVERIFIABLE_IDS_SHOWN = 20;
+/** Refused entries named in the notes before the rest are summarised. */
+const REJECTED_NOTES_SHOWN = 5;
+/**
+ * The knowledge stale-check as ONE quality gate — decided by THE gate the verb
+ * settles (`evaluateKnowledgeStaleGate` + `settleKnowledgeStaleGate`), with the
+ * config's `knowledgeCheck` block standing in for the verb's flags.
+ *
+ * `buildQualityReport` pushes it for every consumer (MCP `get_quality_report`,
+ * the dashboard, the report site), and `shrk quality` maps this same row onto
+ * its bundle item instead of re-deriving it — so the MCP report can no longer
+ * read `pass` over a stale corpus `shrk quality` fails.
+ *
+ *   - an empty corpus, or a changeset no entry references → a DELIBERATE skip
+ *     (`examinedNothing`, non-blocking; `data.skip` names which);
+ *   - a request that can never be evaluated as configured, or a throw →
+ *     `executed: false` (never a pass);
+ *   - settled 1 → blocking failure; settled 2 → `data.partial` (NOT VERIFIED);
+ *     settled 0 → pass.
+ *
+ * `data.settledExit` carries the settled exit so the CLI item's status is the
+ * repro command's exit, by construction.
+ */
+export async function knowledgeStaleQualityGate(inspection, changedFiles) {
+    const base = { id: KNOWLEDGE_STALE_GATE_ID, label: 'Knowledge stale-check', runsShell: false };
+    const discovery = describeInspectionDiscovery(inspection);
+    // A knowledge file that failed to load is never a deliberate skip — the
+    // corpus is partial (or gone), and the gate says so. Neither is a corpus
+    // whose entries the loader REFUSED (round 15 follow-up, F3): they were
+    // declared, and nothing they claim was checked.
+    const loadFailed = discovery.knowledgeLoadFailures.length > 0;
+    const refused = knowledgeRejectedEntries(inspection).length > 0;
+    if (inspection.knowledgeEntries.length === 0 && !loadFailed && !refused) {
+        return {
+            ...base,
+            passed: true,
+            blocking: false,
+            executed: true,
+            notes: ['no knowledge entries declared — nothing to check'],
+            data: { examinedNothing: true, skip: 'empty-corpus' },
+        };
+    }
+    try {
+        // A bare warm keeps any command resolver a CLI caller already injected.
+        await warmReferenceRegistries(inspection);
+        const report = buildKnowledgeStaleReport(inspection, changedFiles ? { changedFiles } : {});
+        if (changedFiles && report.entriesInScope === 0 && !loadFailed && report.rejectedEntries.length === 0) {
+            return {
+                ...base,
+                passed: true,
+                blocking: false,
+                executed: true,
+                notes: ['no knowledge entry references the changeset'],
+                data: { examinedNothing: true, skip: 'out-of-changeset' },
+            };
+        }
+        const gateInput = knowledgeStaleGateInput({
+            flags: {},
+            knowledgeCheck: inspection.config?.knowledgeCheck,
+            discovery,
+            scoped: changedFiles !== undefined,
+        });
+        if (gateInput.usageProblem) {
+            return {
+                ...base,
+                passed: false,
+                blocking: false,
+                executed: false,
+                notes: [`could not run as configured: ${gateInput.usageProblem}`],
+            };
+        }
+        const gate = evaluateKnowledgeStaleGate(report, gateInput);
+        const settled = settleKnowledgeStaleGate(gate);
+        const c = report.coverage;
+        const share = c.entriesInScope > 0 ? formatPct(c.unverifiable / c.entriesInScope) : '0%';
+        const rejected = report.rejectedEntries;
+        return {
+            ...base,
+            // 1 fails; 2 "passed" over PART of its scope (`partial`), which the one
+            // classification (`examineQualityGate`) reads as unexamined — never a pass.
+            passed: settled.exit !== 1,
+            blocking: true,
+            executed: true,
+            notes: [
+                `entries in scope ${c.entriesInScope} · verified ${c.verified} · stale ${c.stale} · unverifiable ${c.unverifiable} (${share})${rejected.length > 0 ? ` · rejected at load ${rejected.length}` : ''}`,
+                ...gate.reasons,
+                ...settled.shortfalls.map((s) => `NOT VERIFIED — ${s}`),
+                // Round 15 follow-up (F3): each entry the loader refused, named with the
+                // file to fix — the same wording as the stale-check's INVALID row.
+                ...rejected
+                    .slice(0, REJECTED_NOTES_SHOWN)
+                    .map((r) => `${r.label} (${r.source}${r.pack !== undefined ? `, pack ${r.pack}` : ''}) — ${r.message}`),
+                ...(rejected.length > REJECTED_NOTES_SHOWN
+                    ? [`… ${rejected.length - REJECTED_NOTES_SHOWN} more rejected at load (\`shrk knowledge stale-check\` lists all)`]
+                    : []),
+                // Round 15: the fix, in THIS surface's terms — quality refuses
+                // `--min-referenced`, so the valve it names is the config key.
+                ...(settled.exit === 2 && c.unverifiable > 0
+                    ? [
+                        `remedy: ${unverifiableRemedy(report.entryVerdicts, KnowledgeMinReferencedValve.Config)}`,
+                        ...unverifiableFileRemedies(report.entryVerdicts),
+                    ]
+                    : []),
+                ...settled.accepted,
+            ],
+            data: {
+                coverage: c,
+                unverifiableIds: report.unverifiableIds.slice(0, UNVERIFIABLE_IDS_SHOWN),
+                // Round 15 follow-up (F3): refused entries, capped like the ids above.
+                rejectedEntries: rejected.slice(0, UNVERIFIABLE_IDS_SHOWN),
+                failureCounts: report.failureCounts,
+                settledExit: settled.exit,
+                shortfalls: settled.shortfalls,
+                // What an explicit valve accepted (`knowledgeCheck.minReferenced`, a
+                // waiver) — `shrk quality` hoists it into the run's `accepted`.
+                accepted: settled.accepted,
+                ...(settled.exit === 2 ? { partial: true } : {}),
+            },
+        };
+    }
+    catch (e) {
+        return {
+            ...base,
+            passed: false,
+            blocking: false,
+            executed: false,
+            notes: [`could not run: ${e.message}`],
+        };
+    }
+}