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

package/dist/commands/knowledge.command.js

@@ -1,19 +1,119 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join as nodePathJoin, resolve as nodePathResolve } from 'node:path';
-import { buildAnchorUpdatePlan, buildKnowledgeStaleReport, buildRenameFilePlan, buildRenameSymbolPlan, inspectSharkcraft, ReferenceCheckOutcome, resolveChangedFiles, } from '@shrkcrft/inspector';
-import { ALL_KNOWLEDGE_TYPES, formatEntryCompact, formatEntryFull, isKnowledgeType, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
-import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { buildAnchorUpdatePlan, buildKnowledgeRefResolver, buildKnowledgeStaleReport, buildRenameFilePlan, buildRenameSymbolPlan, ContributionKind, describeInspectionDiscovery, inspectSharkcraft, KnowledgeAdvisoryCode, KnowledgeEntryVerdict, ReferenceAssetKind, ReferenceCheckOutcome, resolveChangedFiles, } from '@shrkcrft/inspector';
+import { ALL_KNOWLEDGE_TYPES, formatEntryCompact, formatEntryFull, formatKnowledgeReference, isKnowledgeType, isValidVerifiedOn, parseStaleAfterDays, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
+import { writeRejectedEntriesNote } from "../output/rejected-entries-note.js";
+/** Every contribution kind the knowledge loader reads (knowledge, rules, paths, docs). */
+const KNOWLEDGE_FAMILY_KINDS = [
+    ContributionKind.Knowledge,
+    ContributionKind.Rule,
+    ContributionKind.Path,
+    ContributionKind.PathConvention,
+    ContributionKind.Docs,
+];
+import { flagBool, flagNumber, flagString, flagList, requireInputSelector, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { renderFailureHints, staleKnowledgeHints } from "../output/failure-hints.js";
-function renderStaleCheckMarkdown(p) {
+import { ExitCode } from "../exit-codes.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { evaluateKnowledgeStaleGate, formatPct, KNOWLEDGE_FAIL_ON_CATEGORIES, knowledgeStaleGateInput, knowledgeStaleWindowProblem, parseMinReferenced, } from "../knowledge/knowledge-stale-gate.js";
+/** Unverifiable ids shown in text / markdown before the rest are summarised. */
+const UNVERIFIABLE_SHOWN = 50;
+/**
+ * The three buckets, with the unverifiable share — on the line where a bare
+ * `0 stale` used to sit, so a corpus checked a quarter of the way can never
+ * summarise as healthy.
+ */
+function bucketLine(r) {
+    const c = r.coverage;
+    const pct = c.entriesInScope > 0 ? formatPct(c.unverifiable / c.entriesInScope) : '0%';
+    return `entries in scope: ${c.entriesInScope} · verified: ${c.verified} · stale: ${c.stale} · unverifiable: ${c.unverifiable} (${pct})`;
+}
+/** Unverifiable entry ids grouped by the file that declares them — the file to edit. */
+function unverifiableGroups(r) {
+    const by = new Map();
+    for (const v of r.entryVerdicts) {
+        if (v.verdict !== KnowledgeEntryVerdict.Unverifiable)
+            continue;
+        const list = by.get(v.source) ?? [];
+        list.push(v.entryId);
+        by.set(v.source, list);
+    }
+    return [...by.entries()].map(([source, ids]) => ({ source, ids }));
+}
+/** `sharkcraft/rules.ts (7): a, b, …` lines, capped across groups. */
+function unverifiableLines(r, indent) {
+    const out = [];
+    let shown = 0;
+    for (const g of unverifiableGroups(r)) {
+        const room = UNVERIFIABLE_SHOWN - shown;
+        if (room <= 0)
+            break;
+        const ids = g.ids.slice(0, room);
+        shown += ids.length;
+        out.push(`${indent}${g.source} (${g.ids.length}): ${ids.join(', ')}${ids.length < g.ids.length ? ', …' : ''}`);
+    }
+    const rest = r.unverifiableIds.length - shown;
+    if (rest > 0)
+        out.push(`${indent}… ${rest} more (--json for all)`);
+    return out;
+}
+/** Load failures listed in text / markdown before the rest are summarised. */
+const LOAD_FAILURES_SHOWN = 50;
+/**
+ * `LOAD FAILED (N)` — the knowledge-bearing files whose entries never reached
+ * the corpus. Printed at ANY corpus size: a clean sweep of the rest is not a
+ * verdict over these.
+ */
+function loadFailureLines(d, indent) {
+    const failed = d.knowledgeLoadFailures;
+    if (failed.length === 0)
+        return [];
+    const out = [
+        `LOAD FAILED (${failed.length} of ${Math.max(d.knowledgeFilesAttempted, failed.length)} knowledge files) — their entries were never checked:`,
+    ];
+    for (const f of failed.slice(0, LOAD_FAILURES_SHOWN)) {
+        out.push(`${indent}${f.status.toUpperCase().padEnd(14)}${f.kind.padEnd(10)}${f.file}${f.packName ? ` (pack ${f.packName})` : ''} — ${f.message}`);
+    }
+    if (failed.length > LOAD_FAILURES_SHOWN)
+        out.push(`${indent}… ${failed.length - LOAD_FAILURES_SHOWN} more (--json for all)`);
+    out.push('');
+    return out;
+}
+/**
+ * The per-kind table. A kind the sweep never visited says so in words — a row
+ * of zeros cannot tell "clean" from "never looked".
+ */
+function kindTableLines(r) {
+    const cols = (b) => [b.scanned, b.zeroReferences, b.referencesChecked, b.verified, b.stale, b.unverifiable]
+        .map((n, i) => String(n).padStart(i === 0 ? 7 : i === 1 ? 10 : i === 2 ? 5 : i === 3 ? 9 : i === 4 ? 6 : 13))
+        .join('');
+    const row = (label, b, empty) => b.scanned === 0 ? `  ${label.padEnd(22)}${empty}` : `  ${label.padEnd(22)}${cols(b)}`;
+    const lines = [`  ${'kind'.padEnd(22)}scanned zero-refs refs verified stale unverifiable`];
+    lines.push(row('knowledge', r.byAssetKind[ReferenceAssetKind.Knowledge], 'none in scope'));
+    for (const type of Object.keys(r.byEntryType).sort()) {
+        lines.push(row(`  type:${type}`, r.byEntryType[type], 'none in scope'));
+    }
+    lines.push(row('boundary-rule', r.byAssetKind[ReferenceAssetKind.BoundaryRule], 'none declared'));
+    lines.push(r.policySweep.loaded
+        ? row('policy', r.byAssetKind[ReferenceAssetKind.Policy], 'none declared')
+        : `  ${'policy'.padEnd(22)}not in sweep (policy registry not loaded)`);
+    return lines;
+}
+function refLabel(c) {
+    return formatKnowledgeReference(c.reference);
+}
+function renderStaleCheckMarkdown(p, verdict) {
     const out = [];
     out.push(`# Knowledge stale-check`);
     out.push('');
-    out.push(`- entries: ${p.entries}`);
+    out.push(`- ${bucketLine(p)}`);
     out.push(`- references: ${p.totalReferences}`);
     out.push(`- anchors: ${p.totalAnchors}`);
-    out.push(`- counts: ok=${p.counts.ok}, stale=${p.counts.stale}, missing=${p.counts.missing}, unknown=${p.counts.unknown}`);
+    out.push(`- counts: ok=${p.counts.ok}, stale=${p.counts.stale}, missing=${p.counts.missing}, unknown=${p.counts.unknown}, invalid=${p.counts.invalid}`);
     if (p.ci.ci || p.ci.strict || p.ci.failOn.length > 0) {
         out.push(`- required failing: ${p.ci.totalRequiredFailing} (stale=${p.ci.requiredStale}, missing=${p.ci.requiredMissing})`);
     }
@@ -21,34 +121,64 @@ function renderStaleCheckMarkdown(p) {
         out.push(`- baseline (${p.baselineComparison.baseline}): new-stale=${p.baselineComparison.newStale}, new-missing=${p.baselineComparison.newMissing}, resolved=${p.baselineComparison.resolved}`);
     }
     out.push('');
+    out.push('```');
+    for (const line of kindTableLines(p))
+        out.push(line);
+    out.push('```');
+    const loadFailed = loadFailureLines(p.discovery, '- ').filter((l) => l !== '');
+    if (loadFailed.length > 0) {
+        out.push('');
+        out.push(`## ${loadFailed[0]}`);
+        for (const line of loadFailed.slice(1))
+            out.push(line);
+    }
+    if (p.coverage.unverifiable > 0) {
+        out.push('');
+        out.push(`## Unverifiable entries (${p.coverage.unverifiable}) — declare references[]`);
+        for (const line of unverifiableLines(p, '- '))
+            out.push(line);
+    }
+    out.push('');
     out.push(`## Reference issues`);
-    for (const c of p.referenceChecks) {
+    for (const c of [...p.referenceChecks, ...p.assetReferenceChecks]) {
         if (c.outcome === 'ok')
             continue;
         const req = c.reference.required ? ' **(required)**' : '';
-        out.push(`- **${c.outcome.toUpperCase()}**${req} \`${c.entryId}\` → \`${c.reference.kind}:${c.reference.id ?? c.reference.path ?? c.reference.symbol ?? '?'}\` — ${c.message}`);
-    }
-    if (p.ci.exitNonZero && p.ci.exitReason) {
-        out.push('');
-        out.push(`> FAIL: ${p.ci.exitReason}`);
+        const kind = c.assetKind ? ` [${c.implicit ? 'implicit ' : ''}${c.assetKind}]` : '';
+        out.push(`- **${c.outcome.toUpperCase()}**${req}${kind} \`${c.entryId}\` → \`${refLabel(c)}\` — ${c.message}`);
     }
     out.push('');
+    for (const line of verdict.split('\n'))
+        out.push(`> ${line}`);
+    out.push('');
     return out.join('\n');
 }
-function renderStaleCheckHtml(p) {
+function renderStaleCheckHtml(p, verdict) {
     const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
     const rows = [];
-    for (const c of p.referenceChecks) {
+    for (const c of [...p.referenceChecks, ...p.assetReferenceChecks]) {
         if (c.outcome === 'ok')
             continue;
-        rows.push(`<tr><td>${esc(c.outcome.toUpperCase())}</td><td>${c.reference.required ? '✓' : ''}</td><td>${esc(c.entryId)}</td><td>${esc(c.reference.kind)}:${esc(c.reference.id ?? c.reference.path ?? c.reference.symbol ?? '?')}</td><td>${esc(c.message)}</td></tr>`);
+        rows.push(`<tr><td>${esc(c.outcome.toUpperCase())}</td><td>${c.reference.required ? '✓' : ''}</td><td>${esc(c.entryId)}</td><td>${esc(refLabel(c))}</td><td>${esc(c.message)}</td></tr>`);
     }
+    const unverifiable = unverifiableLines(p, '').map((l) => `<li>${esc(l)}</li>`).join('');
+    const loadFailedLines = loadFailureLines(p.discovery, '').filter((l) => l !== '');
+    const loadFailed = loadFailedLines.length > 0
+        ? `<h2>${esc(loadFailedLines[0])}</h2><ul>${loadFailedLines
+            .slice(1)
+            .map((l) => `<li>${esc(l)}</li>`)
+            .join('')}</ul>`
+        : '';
     return `<!doctype html><meta charset="utf-8"><title>Knowledge stale-check</title>
 <style>body{font:14px/1.4 sans-serif;margin:1rem}table{border-collapse:collapse;width:100%}td,th{border:1px solid #ccc;padding:.25rem .5rem;text-align:left}h1{margin-top:0}</style>
 <h1>Knowledge stale-check</h1>
-<p>entries=${p.entries}, references=${p.totalReferences}, anchors=${p.totalAnchors}, ok=${p.counts.ok}, stale=${p.counts.stale}, missing=${p.counts.missing}, unknown=${p.counts.unknown}</p>
+<p>${esc(bucketLine(p))}</p>
+<p>references=${p.totalReferences}, anchors=${p.totalAnchors}, ok=${p.counts.ok}, stale=${p.counts.stale}, missing=${p.counts.missing}, unknown=${p.counts.unknown}, invalid=${p.counts.invalid}</p>
+<pre>${esc(kindTableLines(p).join('\n'))}</pre>
+${loadFailed}
+${unverifiable ? `<h2>Unverifiable entries (${p.coverage.unverifiable})</h2><ul>${unverifiable}</ul>` : ''}
 <table><thead><tr><th>Outcome</th><th>Required</th><th>Entry</th><th>Reference</th><th>Message</th></tr></thead><tbody>${rows.join('')}</tbody></table>
-${p.ci.exitNonZero ? `<p style="color:#a40000;font-weight:bold">FAIL: ${esc(p.ci.exitReason ?? '')}</p>` : ''}
+<p style="font-weight:bold${p.exitCode === 0 ? '' : ';color:#a40000'}">${esc(verdict).replace(/\n/g, '<br>')}</p>
 `;
 }
 /**
@@ -106,22 +236,43 @@ export const knowledgeListCommand = {
                     // and would strip pack entries whose fields are getters/non-enumerable.
                     entries.map(projectKnowledgeEntryForJson);
             process.stdout.write(asJson(payload) + '\n');
+            await writeRejectedEntriesNote(inspection, KNOWLEDGE_FAMILY_KINDS, { json: true, next: 'shrk doctor' });
             return 0;
         }
+        if (inspection.knowledgeEntries.length === 0) {
+            // A query, not a gate — the exit stays 0 — but an empty corpus is almost
+            // always a wrong root, so say where discovery landed (as `knowledge lint`).
+            const d = describeInspectionDiscovery(inspection, resolveCwd(args));
+            process.stderr.write(`WARN  loaded 0 knowledge entries from ${d.resolvedRoot} (sharkcraft/ folder: ${d.sharkcraftDir ?? 'missing'}` +
+                `${d.configError !== undefined ? `; config failed to load — ${d.configError}` : ''}).` +
+                `${d.configuredAncestor ? ` A configured ancestor exists: rerun with --cwd ${d.configuredAncestor}.` : ''}\n`);
+        }
+        // A knowledge file that never loaded makes the list PARTIAL — say which.
+        const failedLoads = describeInspectionDiscovery(inspection, resolveCwd(args)).knowledgeLoadFailures;
+        if (failedLoads.length > 0) {
+            process.stderr.write(`WARN  ${failedLoads.length} knowledge file(s) never loaded — this list is partial: ${failedLoads
+                .map((f) => `${f.file} (${f.status})`)
+                .join(', ')}. Run \`shrk doctor\` for the error.\n`);
+        }
         process.stdout.write(header(`Knowledge (${entries.length})`));
         for (const e of entries)
             process.stdout.write(formatEntryCompact(e) + '\n');
+        // An array member meant as an entry that the loader refused (no `content`,
+        // a reused id) is named (round 12, 12.1) — it used to vanish silently.
+        // Load failures are the partial-list WARN above — never said twice.
+        await writeRejectedEntriesNote(inspection, KNOWLEDGE_FAMILY_KINDS, { next: 'shrk doctor', loadFailures: false });
         return 0;
     },
 };
 export const knowledgeGetCommand = {
     name: 'get',
-    description: 'Show full content of one knowledge entry.',
-    usage: 'shrk knowledge get <id> [--json]',
+    description: 'Show full content of one knowledge entry. A superseded entry opens with a banner naming its successor (resolved, with its title); `--follow` renders the current entry after it. Cross-reference ids print with the namespace they resolve into.',
+    usage: 'shrk knowledge get <id> [--follow] [--json]',
+    booleanFlags: new Set(['follow', 'json']),
     async run(args) {
         const id = args.positional[0];
         if (!id) {
-            process.stderr.write('Usage: shrk knowledge get <id>\n');
+            process.stderr.write('Usage: shrk knowledge get <id> [--follow] [--json]\n');
             return 2;
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
@@ -134,15 +285,69 @@ export const knowledgeGetCommand = {
             process.stdout.write(asJson(entry) + '\n');
             return 0;
         }
-        process.stdout.write(formatEntryFull(entry) + '\n');
+        // Warm first: a construct / playbook id is otherwise NOT VERIFIED, and a
+        // successor must be named with the registry that actually holds it.
+        await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
+        const resolveRef = buildKnowledgeRefResolver(inspection);
+        process.stdout.write(formatEntryFull(entry, { resolveRef }) + '\n');
+        if (flagBool(args, 'follow')) {
+            const followed = followSupersession(inspection.index, entry, inspection.knowledgeEntries.length);
+            if (followed.terminal) {
+                process.stdout.write(`\n--- following supersededBy: ${followed.path.join(' → ')} ---\n\n`);
+                process.stdout.write(formatEntryFull(followed.terminal, { resolveRef }) + '\n');
+            }
+            else {
+                process.stderr.write(`--follow: ${followed.reason}\n`);
+            }
+        }
         return 0;
     },
 };
+/**
+ * Walk `supersededBy` from `entry` to the ONE current entry, cycle-safe and
+ * bounded by the corpus size. Refuses (with the reason) on a fork, a successor
+ * that is not a knowledge entry, or a cycle — never guesses which branch.
+ */
+function followSupersession(index, entry, bound) {
+    const path = [entry.id];
+    const seen = new Set(path);
+    let cur = entry;
+    for (let step = 0; step <= bound; step += 1) {
+        const next = (cur.supersededBy ?? []).filter((s) => typeof s === 'string' && s.length > 0);
+        if (next.length === 0) {
+            return path.length > 1
+                ? { terminal: cur, path }
+                : { path, reason: `"${entry.id}" is not superseded — nothing to follow.` };
+        }
+        if (next.length > 1) {
+            return { path, reason: `"${cur.id}" names ${next.length} successors (${next.join(', ')}) — pick one: shrk knowledge get <id>` };
+        }
+        const successor = index.get(next[0] ?? '');
+        if (!successor)
+            return { path, reason: `successor "${next[0]}" of "${cur.id}" is not a knowledge entry.` };
+        if (seen.has(successor.id)) {
+            return { path: [...path, successor.id], reason: `supersededBy forms a cycle (${[...path, successor.id].join(' → ')}) — no entry in it is current.` };
+        }
+        seen.add(successor.id);
+        path.push(successor.id);
+        cur = successor;
+    }
+    return { path, reason: 'the supersededBy chain is longer than the corpus.' };
+}
 export const knowledgeSearchCommand = {
     name: 'search',
     description: 'Search knowledge by query.',
     usage: 'shrk knowledge search <query> [--type x,y] [--scope x,y] [--limit 10] [--json]',
     async run(args) {
+        // No query and no filter is "you gave me nothing to search" — a usage
+        // error (3), never `Results (0)` at exit 0 (round 11 §1.2#5).
+        const noSelector = requireInputSelector(args, {
+            flags: ['type', 'scope', 'tag', 'appliesWhen'],
+            positional: true,
+            usage: 'shrk knowledge search <query> [--type x,y] [--scope x,y] [--limit 10] [--json]',
+        });
+        if (noSelector !== null)
+            return noSelector;
         const query = args.positional.join(' ').trim();
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const types = flagList(args, 'type');
@@ -191,33 +396,126 @@ function readChangedScopeOptionsForKnowledge(args, projectRoot) {
         includeWorktree: changedOnly || !since,
     };
 }
+/** Boolean flags of the stale-check — none of them may swallow a following token. */
+const STALE_CHECK_BOOLEAN_FLAGS = new Set([
+    'json',
+    'ci',
+    'strict',
+    'report',
+    'changed-only',
+    'staged',
+    'watch',
+    'once',
+    'require-references',
+    ALLOW_EMPTY_FLAG,
+]);
+const STALE_CHECK_USAGE = 'shrk knowledge stale-check [--changed-only|--since <ref>|--staged|--files a,b,c] [--ci] [--strict] [--fail-on <category,...>] [--min-referenced <ratio|NN%>] [--require-references] [--allow-empty] [--stale-after <Nd|Nw|Nm|Ny> [--as-of YYYY-MM-DD]] [--baseline <file>] [--report] [--format text|markdown|html|json] [--output <path>] [--json] [--watch [--once] [--debounce N]]';
 export const knowledgeStaleCheckCommand = {
     name: 'stale-check',
-    description: 'Validate `references[]` + `anchors[]` on each knowledge entry against the workspace. CI flags and `--watch [--once] [--debounce N]` supported. Read-only.',
-    usage: 'shrk knowledge stale-check [--changed-only|--since <ref>|--staged|--files a,b,c] [--ci] [--strict] [--fail-on required|stale|missing|all] [--baseline <file>] [--report] [--format text|markdown|html|json] [--output <path>] [--json] [--watch [--once] [--debounce N]]',
+    description: 'Verify every knowledge entry against the workspace in three buckets — verified / stale / UNVERIFIABLE (no checkable reference). Strict by default: any unverifiable entry keeps the run at exit 2 unless accepted (--min-referenced). CI flags and `--watch [--once] [--debounce N]` supported. Read-only.',
+    usage: STALE_CHECK_USAGE,
+    booleanFlags: STALE_CHECK_BOOLEAN_FLAGS,
     async run(args) {
-        const watchExit = await maybeRunInWatchMode(args, knowledgeStaleCheckImpl);
-        if (watchExit !== null)
-            return watchExit;
-        return knowledgeStaleCheckImpl(args);
+        return runStaleCheck(args, 'knowledge stale-check');
     },
 };
-async function knowledgeStaleCheckImpl(args) {
+async function runStaleCheck(args, verb) {
+    const impl = (a) => knowledgeStaleCheckImpl(a, verb);
+    const watchExit = await maybeRunInWatchMode(args, impl);
+    if (watchExit !== null)
+        return watchExit;
+    return impl(args);
+}
+/** A malformed invocation: `3` (the gate never started) with the usage line. */
+function staleCheckUsageError(message) {
+    process.stderr.write(`${message}\nUsage: ${STALE_CHECK_USAGE}\n`);
+    return ExitCode.UsageError;
+}
+async function knowledgeStaleCheckImpl(args, verb) {
     const cwd = resolveCwd(args);
+    // ── Validate the request first: a bad flag value is `3`, never a verdict. ──
+    const failOnFlag = args.flags.get('fail-on');
+    if (failOnFlag === true) {
+        return staleCheckUsageError(`--fail-on needs a value: ${KNOWLEDGE_FAIL_ON_CATEGORIES.join(', ')}.`);
+    }
+    const failOnList = (typeof failOnFlag === 'string' ? failOnFlag : '')
+        .toLowerCase()
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const unknownFailOn = failOnList.filter((c) => !KNOWLEDGE_FAIL_ON_CATEGORIES.includes(c));
+    if (unknownFailOn.length > 0) {
+        return staleCheckUsageError(`Unknown --fail-on value(s): ${unknownFailOn.join(', ')}. Valid: ${KNOWLEDGE_FAIL_ON_CATEGORIES.join(', ')}.`);
+    }
+    const minFlag = args.flags.get('min-referenced');
+    let minReferenced;
+    if (minFlag !== undefined) {
+        const ratio = typeof minFlag === 'string' ? parseMinReferenced(minFlag) : null;
+        if (ratio === null) {
+            return staleCheckUsageError(`--min-referenced takes a ratio 0..1 or a percentage (0.8, 80%) — got ${JSON.stringify(minFlag)}.`);
+        }
+        minReferenced = { ratio, acceptedBy: `--min-referenced ${minFlag}` };
+    }
+    const staleAfterFlag = args.flags.get('stale-after');
+    let staleAfterDays;
+    if (staleAfterFlag !== undefined) {
+        const days = typeof staleAfterFlag === 'string' ? parseStaleAfterDays(staleAfterFlag) : null;
+        if (days === null) {
+            return staleCheckUsageError(`--stale-after takes a duration such as 90d, 12w, 6m or 1y — got ${JSON.stringify(staleAfterFlag)}.`);
+        }
+        staleAfterDays = days;
+    }
+    const asOfFlag = args.flags.get('as-of');
+    if (asOfFlag !== undefined && (typeof asOfFlag !== 'string' || !isValidVerifiedOn(asOfFlag))) {
+        return staleCheckUsageError(`--as-of takes a date written YYYY-MM-DD — got ${JSON.stringify(asOfFlag)}.`);
+    }
+    const asOf = typeof asOfFlag === 'string' ? asOfFlag : undefined;
+    // A category that can never fire is a malformed request (the `--fail-on
+    // bogus` class): `aged` / `--as-of` measure against a --stale-after window.
+    // (The same check runs again below over `knowledgeCheck.failOn`.)
+    const windowProblem = knowledgeStaleWindowProblem(new Set(failOnList), false, staleAfterDays, asOf);
+    if (windowProblem)
+        return staleCheckUsageError(windowProblem);
     const inspection = await inspectSharkcraft({ cwd });
+    // `command` references resolve against the live command index — injected
+    // here; without it they are NOT VERIFIED (never "Command available").
+    // The same call warms every async-filled registry (playbook / policy /
+    // construct / helper) before anything resolves.
+    await (await import("../surface/cli-command-resolver.js")).warmCliReferenceRegistries(inspection);
     const scopeOpts = readChangedScopeOptionsForKnowledge(args, cwd);
     const changedFiles = scopeOpts ? resolveChangedFiles(scopeOpts).files : undefined;
     const report = buildKnowledgeStaleReport(inspection, {
         ...(changedFiles ? { changedFiles } : {}),
+        ...(staleAfterDays !== undefined ? { staleAfterDays } : {}),
+        ...(asOf ? { asOf } : {}),
     });
-    // CI/preflight flags.
-    const ci = flagBool(args, 'ci');
-    const strict = flagBool(args, 'strict');
-    const failOnRaw = (flagString(args, 'fail-on') ?? '').toLowerCase();
-    const failOn = new Set(failOnRaw
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean));
+    // CI/preflight flags, folded over the config's `knowledgeCheck` block by
+    // THE input builder — `shrk quality` and release readiness build theirs
+    // there too, so a config-only request is one verdict on all three.
+    const discovery = describeInspectionDiscovery(inspection, cwd);
+    const gateInput = knowledgeStaleGateInput({
+        flags: {
+            ci: flagBool(args, 'ci'),
+            strict: flagBool(args, 'strict'),
+            failOn: failOnList,
+            ...(minReferenced ? { minReferenced } : {}),
+            requireReferences: flagBool(args, 'require-references'),
+            emptyAcceptance: allowEmptyValve(args, report.coverage.entriesInScope),
+            ...(staleAfterDays !== undefined ? { staleAfterDays } : {}),
+            ...(asOf ? { asOf } : {}),
+        },
+        knowledgeCheck: inspection.config?.knowledgeCheck,
+        discovery,
+        scoped: changedFiles !== undefined,
+    });
+    // `knowledgeCheck.failOn: ['aged']` with no --stale-after window: a
+    // category that can never fire is a malformed request, never a verdict.
+    if (gateInput.usageProblem)
+        return staleCheckUsageError(gateInput.usageProblem);
+    const ci = gateInput.ci;
+    const strict = gateInput.strict;
+    const effectiveFailOn = [...gateInput.failOn];
+    const requireReferences = gateInput.requireReferences;
     const baselineFile = flagString(args, 'baseline');
     const wantReport = flagBool(args, 'report');
     const formatRaw = (flagString(args, 'format') ?? '').toLowerCase();
@@ -225,58 +523,26 @@ async function knowledgeStaleCheckImpl(args) {
     const wantMarkdown = formatRaw === 'markdown' || formatRaw === 'md';
     const wantHtml = formatRaw === 'html';
     const output = flagString(args, 'output');
-    // Required-reference computation. A reference is "required" when its
-    // `required: true` (default false). Stale + missing are the same outcome
-    // family.
-    let requiredStale = 0;
-    let requiredMissing = 0;
-    for (const c of report.referenceChecks) {
-        const isRequired = c.reference.required === true;
-        if (isRequired && c.outcome === ReferenceCheckOutcome.Stale)
-            requiredStale++;
-        if (isRequired && c.outcome === ReferenceCheckOutcome.Missing)
-            requiredMissing++;
-    }
+    // ── Settle first, render second. ──
+    const gate = evaluateKnowledgeStaleGate(report, gateInput);
+    const env = buildGateEnvelope(verb, gate.proposed, gate.rules, gate.runCoverage);
+    const exit = env.exit;
+    const { verified, entriesInScope } = report.coverage;
+    // Round 13: the ✓ line never contradicts a STALE row printed above it — a
+    // failing reference this mode waives (`required: false` under --ci, …) is
+    // named here and printed as an acceptance below it.
+    const entriesVerified = `${verified} of ${entriesInScope} knowledge ${entriesInScope === 1 ? 'entry' : 'entries'} verified`;
+    const verdict = verdictLine(env, gate.waived > 0
+        ? `${entriesVerified} — ${gate.waived} failing reference(s) listed above do not block this mode (accepted below). ✓`
+        : `${entriesVerified} — no stale or missing references. ✓`, exit === ExitCode.NotVerified ? gate.notVerifiedLead : undefined);
+    const requiredStale = gate.requiredStale;
+    const requiredMissing = gate.requiredMissing;
     const totalRequiredFailing = requiredStale + requiredMissing;
-    // Decide exit code.
-    let exitNonZero = false;
-    let exitReason;
-    const considerFailOn = (cat) => failOn.has(cat) || failOn.has('all');
-    if (ci) {
-        // CI mode — required failing refs are blocking. Optional refs warn only.
-        if (totalRequiredFailing > 0) {
-            exitNonZero = true;
-            exitReason = `${totalRequiredFailing} required references failing in --ci mode`;
-        }
-    }
-    else if (strict) {
-        // Strict — any stale/missing required ref fails. Same as CI essentially.
-        if (totalRequiredFailing > 0) {
-            exitNonZero = true;
-            exitReason = `${totalRequiredFailing} required references failing in --strict mode`;
-        }
-    }
-    else if (failOn.size > 0) {
-        if (considerFailOn('required') && totalRequiredFailing > 0) {
-            exitNonZero = true;
-            exitReason = `${totalRequiredFailing} required reference issues (--fail-on=required)`;
-        }
-        if (considerFailOn('stale') && report.counts.stale > 0) {
-            exitNonZero = true;
-            exitReason = `${report.counts.stale} stale references (--fail-on=stale)`;
-        }
-        if (considerFailOn('missing') && report.counts.missing > 0) {
-            exitNonZero = true;
-            exitReason = `${report.counts.missing} missing references (--fail-on=missing)`;
-        }
-    }
-    else {
-        // Default — non-CI: only the legacy "any missing or stale" condition fails.
-        if (report.counts.missing + report.counts.stale > 0) {
-            exitNonZero = true;
-            exitReason = `${report.counts.missing + report.counts.stale} stale or missing references (legacy default)`;
-        }
-    }
+    const exitReason = gate.reasons.length > 0
+        ? gate.reasons.join('; ')
+        : exit === ExitCode.NotVerified
+            ? `not verified — ${env.shortfalls[0] ?? 'nothing was proved'}`
+            : undefined;
     // Baseline comparison (informational).
     let baselineComparison;
     if (baselineFile) {
@@ -335,14 +601,20 @@ async function knowledgeStaleCheckImpl(args) {
         ci: {
             ci,
             strict,
-            failOn: [...failOn],
+            // The EFFECTIVE categories (a --fail-on flag, else knowledgeCheck.failOn).
+            failOn: effectiveFailOn,
             requiredStale,
             requiredMissing,
             totalRequiredFailing,
-            exitNonZero,
-            exitReason,
+            exitNonZero: exit !== ExitCode.VerifiedPass,
+            ...(exitReason ? { exitReason } : {}),
+            ...(gateInput.minReferenced ? { minReferenced: gateInput.minReferenced.ratio } : {}),
+            requireReferences,
         },
-        baselineComparison,
+        ...(baselineComparison ? { baselineComparison } : {}),
+        discovery,
+        exitCode: exit,
+        gate: env,
     };
     // Optional report file.
     if (wantReport || output) {
@@ -358,59 +630,125 @@ async function knowledgeStaleCheckImpl(args) {
             process.stdout.write(`Wrote report → ${outPath}\n`);
         }
     }
-    // Format-specific output.
+    // Format-specific output — every format returns the SETTLED exit.
     if (wantJson) {
         process.stdout.write(asJson(ciPayload) + '\n');
-        return exitNonZero ? 1 : 0;
+        return exit;
     }
     if (wantMarkdown) {
-        process.stdout.write(renderStaleCheckMarkdown(ciPayload));
-        return exitNonZero ? 1 : 0;
+        process.stdout.write(renderStaleCheckMarkdown(ciPayload, verdict));
+        return exit;
     }
     if (wantHtml) {
-        process.stdout.write(renderStaleCheckHtml(ciPayload));
-        return exitNonZero ? 1 : 0;
-    }
-    // Default text output.
-    process.stdout.write(header('Knowledge stale-check'));
-    process.stdout.write(`entries=${report.entries} references=${report.totalReferences} anchors=${report.totalAnchors}\n`);
-    process.stdout.write(`ok=${report.counts.ok} stale=${report.counts.stale} missing=${report.counts.missing} unknown=${report.counts.unknown}\n`);
-    if (ci || strict || failOn.size > 0) {
-        process.stdout.write(`required: stale=${requiredStale} missing=${requiredMissing} (total failing: ${totalRequiredFailing})\n`);
-    }
-    if (baselineComparison) {
-        process.stdout.write(`baseline: new-stale=${baselineComparison.newStale} new-missing=${baselineComparison.newMissing} resolved=${baselineComparison.resolved}\n`);
-    }
-    process.stdout.write('\n');
-    for (const c of report.referenceChecks) {
-        if (c.outcome === ReferenceCheckOutcome.Ok)
-            continue;
-        const tag = c.outcome.toUpperCase().padEnd(7);
+        process.stdout.write(renderStaleCheckHtml(ciPayload, verdict));
+        return exit;
+    }
+    writeStaleCheckText(ciPayload, {
+        verdict,
+        reasons: gate.reasons,
+        showRequired: ci || strict || effectiveFailOn.length > 0,
+        allowEmptyHint: exit === ExitCode.NotVerified && entriesInScope === 0 && !gate.discoveryFailed,
+    });
+    return exit;
+}
+/** Advisories printed in text before the rest are summarised. */
+const ADVISORIES_SHOWN = 20;
+/** Aged entries printed in text before the rest are summarised. */
+const AGED_SHOWN = 50;
+function writeStaleCheckText(p, o) {
+    const w = (s) => void process.stdout.write(s);
+    w(header('Knowledge stale-check'));
+    const d = p.discovery;
+    if (d.entriesLoaded === 0) {
+        // Name where discovery landed, so a wrong root is visible on the screen
+        // that refuses to pass.
+        w('Loaded 0 knowledge entries.\n');
+        w(`  resolved root:       ${d.resolvedRoot}${d.rootMarkers.length > 0 ? ` (${d.rootMarkers.join(', ')})` : ' (no root marker)'}\n`);
+        w(`  sharkcraft/ folder:  ${d.sharkcraftDir ?? 'missing'}\n`);
+        w(`  config:              ${d.configError !== undefined ? `failed to load — ${d.configError}` : (d.configFile ?? '(none)')}\n`);
+        if (d.configuredAncestor) {
+            w(`  configured ancestor: ${d.configuredAncestor} — rerun with --cwd ${d.configuredAncestor}\n`);
+        }
+        w('\n');
+    }
+    for (const line of loadFailureLines(d, '  '))
+        w(`${line}\n`);
+    w(`${bucketLine(p)}\n`);
+    w(`references: ${p.totalReferences} · anchors: ${p.totalAnchors} · ok=${p.counts.ok} stale=${p.counts.stale} missing=${p.counts.missing} unknown=${p.counts.unknown} invalid=${p.counts.invalid}\n`);
+    const failures = Object.entries(p.failureCounts).filter(([, n]) => n > 0);
+    if (failures.length > 0)
+        w(`failures: ${failures.map(([k, n]) => `${k}=${n}`).join(' ')}\n`);
+    if (p.entriesInScope !== p.entries) {
+        w(`scope: ${p.entriesInScope} of ${p.entries} entries reference the changed files\n`);
+    }
+    if (o.showRequired) {
+        w(`required: stale=${p.ci.requiredStale} missing=${p.ci.requiredMissing} (total failing: ${p.ci.totalRequiredFailing})\n`);
+    }
+    if (p.baselineComparison) {
+        w(`baseline: new-stale=${p.baselineComparison.newStale} new-missing=${p.baselineComparison.newMissing} resolved=${p.baselineComparison.resolved}\n`);
+    }
+    if (p.age) {
+        w(`verifiedOn: ${p.age.aged.length} older than ${p.age.staleAfterDays}d, ${p.age.neverVerified.length} never verified (as of ${p.age.asOf})\n`);
+    }
+    w('\n');
+    for (const line of kindTableLines(p))
+        w(`${line}\n`);
+    if (p.coverage.unverifiable > 0) {
+        w(`\nUNVERIFIABLE (${p.coverage.unverifiable}) — never checked; declare references[] (or anchors[]):\n`);
+        for (const line of unverifiableLines(p, '  '))
+            w(`${line}\n`);
+    }
+    const issues = [...p.referenceChecks, ...p.assetReferenceChecks].filter((c) => c.outcome !== ReferenceCheckOutcome.Ok);
+    const badAnchors = p.anchorChecks.filter((c) => c.outcome !== ReferenceCheckOutcome.Ok);
+    if (issues.length + badAnchors.length > 0)
+        w('\n');
+    for (const c of issues) {
+        const tag = (c.implicit ? 'IMPLICIT' : c.outcome.toUpperCase()).padEnd(8);
         const req = c.reference.required === true ? '[REQ] ' : '      ';
-        process.stdout.write(`  ${tag} ${req}${c.entryId} → ${c.reference.kind}:${c.reference.id ?? c.reference.path ?? c.reference.symbol ?? '?'} — ${c.message}\n`);
+        const kind = c.assetKind ? `[${c.assetKind}] ` : '';
+        w(`  ${tag}${req}${kind}${c.entryId} → ${formatKnowledgeReference(c.reference)} — ${c.message}\n`);
+        if (c.expected !== undefined || c.actual !== undefined) {
+            w(`           expected: ${String(c.expected ?? '?')} · actual: ${String(c.actual ?? '?')}\n`);
+        }
         if (c.suggestion)
-            process.stdout.write(`           ↳ ${c.suggestion}\n`);
+            w(`           ↳ ${c.suggestion}\n`);
     }
-    for (const c of report.anchorChecks) {
-        if (c.outcome === ReferenceCheckOutcome.Ok)
-            continue;
-        const tag = c.outcome.toUpperCase().padEnd(7);
-        process.stdout.write(`  ${tag} ${c.entryId} anchor[${c.anchor.id}] (${c.anchor.kind}) — ${c.message}\n`);
+    for (const c of badAnchors) {
+        w(`  ${c.outcome.toUpperCase().padEnd(8)}${c.entryId} anchor[${c.anchor.id}] (${c.anchor.kind}) — ${c.message}\n`);
+    }
+    // Implicit boundary references were listed with the issues above.
+    const advisories = p.advisories.filter((a) => a.code !== KnowledgeAdvisoryCode.ImplicitPathMissing);
+    if (advisories.length > 0) {
+        w(`\nAdvisories (${advisories.length}) — reported, never gating:\n`);
+        for (const a of advisories.slice(0, ADVISORIES_SHOWN))
+            w(`  ${a.code}  ${a.subjectId} — ${a.message}\n`);
+        if (advisories.length > ADVISORIES_SHOWN) {
+            w(`  … ${advisories.length - ADVISORIES_SHOWN} more (--json for all)\n`);
+        }
     }
-    if (exitNonZero && exitReason) {
-        process.stdout.write(`\nFAIL: ${exitReason}\n`);
+    if (p.age && p.age.aged.length > 0) {
+        w(`\nAged — not verified within ${p.age.staleAfterDays}d (oldest first):\n`);
+        for (const a of p.age.aged.slice(0, AGED_SHOWN)) {
+            w(`  ${a.entryId}  verifiedOn ${a.verifiedOn} (${a.ageDays}d)  ${a.source}\n`);
+        }
+        if (p.age.aged.length > AGED_SHOWN)
+            w(`  … ${p.age.aged.length - AGED_SHOWN} more (--json for all)\n`);
     }
-    if (exitNonZero) {
-        process.stdout.write(renderFailureHints(staleKnowledgeHints()));
+    if (o.reasons.length > 0) {
+        w(`\nFAIL: ${o.reasons.join('; ')}\n`);
+        w(renderFailureHints(staleKnowledgeHints()));
     }
-    return exitNonZero ? 1 : 0;
+    if (o.allowEmptyHint)
+        w('\nPass --allow-empty to accept an empty scope explicitly.\n');
+    w(`\n${o.verdict}\n`);
 }
 export const knowledgeVerifyCommand = {
     name: 'verify',
-    description: 'Alias for `knowledge stale-check`. Read-only.',
-    usage: 'shrk knowledge verify [--changed-only|--since|--staged|--files] [--json]',
+    description: 'Alias for `knowledge stale-check` — the same three-bucket verdict, flags and exit codes. Read-only.',
+    usage: STALE_CHECK_USAGE.replace('knowledge stale-check', 'knowledge verify'),
+    booleanFlags: STALE_CHECK_BOOLEAN_FLAGS,
     run(args) {
-        return knowledgeStaleCheckCommand.run(args);
+        return runStaleCheck(args, 'knowledge verify');
     },
 };
 export const knowledgeReferencesCommand = {
@@ -447,7 +785,9 @@ export const knowledgeReferencesCommand = {
         if (data.references.length > 0) {
             process.stdout.write(`References (${data.references.length}):\n`);
             for (const r of data.references) {
-                const target = r.id ?? r.path ?? r.symbol ?? r.command ?? '?';
+                // One grammar: a pinned symbol renders `Name@path` (it used to render
+                // as its path, hiding the symbol it pins).
+                const target = formatKnowledgeReference(r).slice(r.kind.length + 1);
                 process.stdout.write(`  • ${r.kind}: ${target}${r.required ? ' [required]' : ''}\n`);
             }
         }