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

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

@@ -1 +1 @@
-{"version":3,"file":"checks.command.d.ts","sourceRoot":"","sources":["../../src/commands/checks.command.ts"],"names":[],"mappings":"AAiCA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eA6C/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA+BjC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAgD9B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAkCtC,CAAC;AAwCF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA8DjC,CAAC;AAUF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eA0CpC,CAAC;AAyBF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAsCjC,CAAC;AA0EF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,eA6ClC,CAAC"}
+{"version":3,"file":"checks.command.d.ts","sourceRoot":"","sources":["../../src/commands/checks.command.ts"],"names":[],"mappings":"AA2CA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2EhC,eAAO,MAAM,iBAAiB,EAAE,eAoF/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAyEjC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAiE9B,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAoCtC,CAAC;AAwCF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAUF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eA0CpC,CAAC;AAyBF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAsCjC,CAAC;AA0EF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,eA6ClC,CAAC"}

package/dist/commands/checks.command.js

@@ -13,33 +13,123 @@
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { buildCheckAggregate, buildCheckResult, buildCustomChecksRegistry, CHECK_AGGREGATE_SCHEMA, CHECK_RESULT_SCHEMA, CheckResultStatus, convertBiomeToCheckResult, convertEslintToCheckResult, CustomCheckScope, doctorCustomChecks, inspectSharkcraft, parseCheckResult, parseCustomCheckReportFromFile, runCustomCheck, } from '@shrkcrft/inspector';
+import { buildCheckAggregate, buildCheckResult, buildCustomChecksRegistry, CHECK_AGGREGATE_SCHEMA, CHECK_RESULT_SCHEMA, CheckResultStatus, convertBiomeToCheckResult, convertEslintToCheckResult, CustomCheckKind, CustomCheckScope, customCheckScanSurface, doctorCustomChecks, inspectSharkcraft, nearestIds, parseCheckResult, parseCustomCheckReportFromFile, referenceIdExists, referenceIdPool, referenceKindsOf, runCustomCheck, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { ExitCode } from "../exit-codes.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { asJson, header } from "../output/format-output.js";
 const CHECKS_DIR_REL = '.sharkcraft/checks';
+/** THE registry build for every `checks` verb — sources project-relative. */
+function loadCustomChecks(inspection) {
+    return buildCustomChecksRegistry(inspection.knowledgeEntries, { projectRoot: inspection.projectRoot });
+}
+/** Every declaration that can never run, one line each, with its file and why. */
+function droppedDeclarationLines(registry) {
+    const lines = [];
+    for (const i of registry.invalid) {
+        const check = i.checkId ? ` [${i.checkId}]` : '';
+        lines.push(`  ✗ ${i.ruleId}${check}${i.source ? `  (${i.source})` : ''} — ${i.reason}`);
+    }
+    for (const i of registry.ignored) {
+        const checks = i.checkIds.length > 0 ? ` checks: ${i.checkIds.join(', ')}` : '';
+        lines.push(`  ✗ ${i.entryId} [type:${i.entryType}]${checks}${i.source ? `  (${i.source})` : ''} — ${i.reason}`);
+    }
+    return lines;
+}
+/** The concrete surface the registry scans — what an empty state names. */
+function scanSurfaceLines(surface, scannedRules) {
+    const lines = [
+        "  Custom checks are read from metadata.checks[] on type:'rule' entries in TypeScript rule / knowledge files:",
+    ];
+    if (surface.files.length === 0) {
+        lines.push('    (none — no TypeScript ruleFiles / knowledgeFiles in sharkcraft.config.ts, and no pack contributes one)');
+    }
+    for (const f of surface.files)
+        lines.push(`    ${f.via.padEnd(16)} ${f.file}`);
+    const md = surface.markdownRules > 0
+        ? ` — ${surface.markdownRules} of the rules scanned are Markdown`
+        : surface.markdownFiles.length > 0
+            ? ` (Markdown sources: ${surface.markdownFiles.join(', ')})`
+            : '';
+    lines.push(`  Scanned ${scannedRules} type:'rule' ${scannedRules === 1 ? 'entry' : 'entries'}. Markdown rules cannot carry metadata${md}.`);
+    return lines;
+}
+/**
+ * `--rule` must name a RULE — resolved through the one reference registry, so
+ * a typo is a usage error with a did-you-mean, never an empty listing that
+ * reads as "nothing declared".
+ */
+function unknownRuleFilter(inspection, id, usage, wantJson) {
+    const kinds = referenceKindsOf(inspection, id).filter((k) => k !== 'rule');
+    const near = nearestIds(id, referenceIdPool(inspection, ['rule'])).map((n) => n.id);
+    const why = kinds.length > 0
+        ? `"${id}" is a ${kinds.join(' | ')} id, not a type:'rule' entry — custom checks are declared on rules only.`
+        : `no type:'rule' entry has the id "${id}".`;
+    process.stderr.write(`--rule ${id}: ${why}${near.length > 0 ? ` Did you mean: ${near.join(', ')}?` : ''}\nUsage: ${usage}\n`);
+    if (wantJson) {
+        process.stdout.write(asJson({ error: 'unknown-rule', rule: id, resolvedAs: kinds, didYouMean: near, exitCode: ExitCode.UsageError }) + '\n');
+    }
+    return ExitCode.UsageError;
+}
+const CHECKS_LIST_USAGE = 'shrk checks list [--rule <ruleId>] [--kind <k>] [--json]';
 export const checksListCommand = {
     name: 'list',
-    description: 'List custom checks declared by rules (metadata.checks[]). Read-only.',
-    usage: 'shrk checks list [--rule <ruleId>] [--kind <k>] [--json]',
+    description: "List custom checks declared on type:'rule' entries (metadata.checks[] in TypeScript rule / knowledge files, local or pack). Every declaration that can never run (on a non-rule entry, in a Markdown rule, a non-array value) is named with its file and reason. Exit 0 · 1 a dropped declaration · 3 --rule names no rule. Read-only.",
+    usage: CHECKS_LIST_USAGE,
+    booleanFlags: new Set(['json']),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const registry = buildCustomChecksRegistry(inspection.knowledgeEntries);
+        const registry = loadCustomChecks(inspection);
         const ruleFilter = flagString(args, 'rule');
         const kindFilter = flagString(args, 'kind');
+        const wantJson = flagBool(args, 'json');
+        if (ruleFilter && !referenceIdExists(inspection, 'rule', ruleFilter)) {
+            return unknownRuleFilter(inspection, ruleFilter, CHECKS_LIST_USAGE, wantJson);
+        }
         let entries = registry.entries;
         if (ruleFilter)
             entries = entries.filter((e) => e.ruleId === ruleFilter);
         if (kindFilter)
             entries = entries.filter((e) => e.descriptor.kind === kindFilter);
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ ...registry, entries }) + '\n');
-            return 0;
+        const filterLabel = [ruleFilter ? `--rule ${ruleFilter}` : '', kindFilter ? `--kind ${kindFilter}` : '']
+            .filter(Boolean)
+            .join(' ');
+        const dropped = registry.invalid.length + registry.ignored.length;
+        // One data path: the exit, the JSON and the text all read these numbers.
+        const exit = dropped > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+        const surface = customCheckScanSurface(inspection);
+        if (wantJson) {
+            process.stdout.write(asJson({
+                ...registry,
+                entries,
+                declared: registry.entries.length,
+                ...(filterLabel ? { filters: { rule: ruleFilter ?? null, kind: kindFilter ?? null } } : {}),
+                surface,
+                exitCode: exit,
+            }) + '\n');
+            return exit;
+        }
+        process.stdout.write(header(`Custom checks (${entries.length}${filterLabel ? ` of ${registry.entries.length}` : ''})`));
+        if (entries.length === 0 && registry.entries.length > 0) {
+            // Filters excluded everything — which is not "nothing declared".
+            const n = registry.entries.length;
+            process.stdout.write(`  ${n} ${n === 1 ? 'check' : 'checks'} declared, 0 match ${filterLabel}\n`);
+            const knownKinds = Object.values(CustomCheckKind);
+            if (kindFilter && !knownKinds.includes(kindFilter)) {
+                process.stdout.write(`  (known kinds: ${knownKinds.join(', ')})\n`);
+            }
         }
-        process.stdout.write(header(`Custom checks (${entries.length})`));
-        if (entries.length === 0) {
-            process.stdout.write('  (no checks declared — add metadata.checks[] to a rule)\n');
-            return 0;
+        else if (entries.length === 0 && dropped === 0) {
+            process.stdout.write('  No checks declared.\n');
+            for (const line of scanSurfaceLines(surface, registry.scannedRules))
+                process.stdout.write(`${line}\n`);
+        }
+        else if (entries.length === 0) {
+            process.stdout.write(`  0 checks registered — every declaration below was dropped.\n`);
         }
         for (const e of entries) {
             const d = e.descriptor;
@@ -65,60 +155,114 @@ export const checksListCommand = {
                 process.stdout.write(`    ${d.id}: ${d.ruleIds.join(', ')}\n`);
             }
         }
-        return 0;
+        if (dropped > 0) {
+            process.stdout.write(`\n  Dropped declarations (${dropped}) — declared, but can never run:\n`);
+            for (const line of droppedDeclarationLines(registry))
+                process.stdout.write(`${line}\n`);
+            process.stdout.write('\n  Fix each declaration above (`shrk checks doctor` validates the rest).\n');
+        }
+        return exit;
     },
 };
 export const checksDoctorCommand = {
     name: 'doctor',
-    description: 'Validate custom-check descriptors. Reports missing fields, duplicate ids, etc.',
-    usage: 'shrk checks doctor [--json] [--strict]',
+    description: 'Validate custom-check descriptors — missing fields, duplicate ids, and every declaration that can never run (on a non-rule entry, in a Markdown rule, a non-array value). Exit 0 validated · 1 errors (or warnings under --strict) · 2 nothing declared (--allow-empty accepts that explicitly). Read-only.',
+    usage: 'shrk checks doctor [--strict] [--allow-empty] [--json]',
+    booleanFlags: new Set(['json', 'strict', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const registry = buildCustomChecksRegistry(inspection.knowledgeEntries);
+        const registry = loadCustomChecks(inspection);
         const report = doctorCustomChecks(registry);
+        const surface = customCheckScanSurface(inspection);
+        const expected = report.declaredChecks;
+        const ignoredLabels = registry.ignored.map((i) => `${i.entryId}${i.source ? ` (${i.source})` : ''}`);
+        // Declared checks are the unit: registered and invalid ones were validated
+        // (an invalid one failed); an ignored one was never read. Nothing declared
+        // is expected 0 — "validated nothing" is never a ✓.
+        const coverage = {
+            unit: 'declared checks',
+            expected,
+            examined: registry.entries.length + registry.invalid.length,
+            root: inspection.projectRoot,
+            reason: expected === 0
+                ? `no type:'rule' entry declares metadata.checks[] (${registry.scannedRules} rule${registry.scannedRules === 1 ? '' : 's'} scanned)`
+                : 'declared where the registry does not read them, so never validated',
+            ...(ignoredLabels.length > 0 ? { unexamined: ignoredLabels.slice(0, 20), unexaminedTotal: ignoredLabels.length } : {}),
+            ...allowEmptyValve(args, expected),
+        };
+        const strict = flagBool(args, 'strict');
+        const settled = settleVerdict(report.errors > 0 || (strict && report.warnings > 0) ? 1 : 0, [coverage]);
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(report) + '\n');
-        }
-        else {
-            process.stdout.write(header('Custom checks doctor'));
-            process.stdout.write(`  total      ${report.totalChecks}\n`);
-            process.stdout.write(`  errors     ${report.errors}\n`);
-            process.stdout.write(`  warnings   ${report.warnings}\n`);
-            if (report.details.length === 0) {
-                process.stdout.write('\nNo descriptor issues. ✓\n');
-            }
-            else {
-                process.stdout.write('\nDetails:\n');
-                for (const d of report.details) {
-                    process.stdout.write(`  ${d.severity.padEnd(7)} [${d.checkId}] (${d.ruleId}) — ${d.message}\n`);
-                }
+            process.stdout.write(asJson({
+                ...report,
+                coverage,
+                surface,
+                exitCode: settled.exit,
+                verdict: settled.verdict,
+                shortfalls: settled.shortfalls,
+                accepted: settled.accepted,
+            }) + '\n');
+            return settled.exit;
+        }
+        process.stdout.write(header('Custom checks doctor'));
+        process.stdout.write(`  declared   ${report.declaredChecks}\n`);
+        process.stdout.write(`  registered ${report.totalChecks}\n`);
+        process.stdout.write(`  errors     ${report.errors}\n`);
+        process.stdout.write(`  warnings   ${report.warnings}\n`);
+        process.stdout.write(`  scanned    ${report.scannedRules} type:'rule' ${report.scannedRules === 1 ? 'entry' : 'entries'}\n`);
+        if (report.details.length > 0) {
+            process.stdout.write('\nDetails:\n');
+            for (const d of report.details) {
+                process.stdout.write(`  ${d.severity.padEnd(7)} [${d.checkId}] (${d.ruleId})${d.source ? ` ${d.source}` : ''} — ${d.message}\n`);
             }
         }
-        if (report.errors > 0)
-            return 1;
-        if (flagBool(args, 'strict') && report.warnings > 0)
-            return 1;
-        return 0;
+        const clean = expected === 0
+            ? 'No checks declared — accepted.'
+            : report.warnings > 0
+                ? `No blocking descriptor issues — ${report.warnings} warning(s) reported above.`
+                : `${report.totalChecks} check descriptor(s) validated — no issues. ✓`;
+        const line = verdictLine(settled, clean, expected === 0 ? 'No checks declared — nothing validated.' : undefined);
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+        if (settled.exit === ExitCode.NotVerified && expected === 0) {
+            for (const l of scanSurfaceLines(surface, registry.scannedRules))
+                process.stdout.write(`${l}\n`);
+            process.stdout.write('Pass --allow-empty to accept a project with no custom checks explicitly.\n');
+        }
+        return settled.exit;
     },
 };
 export const checksRunCommand = {
     name: 'run',
-    description: 'Run a custom check. Read-only by default — pass --execute to actually invoke the command.',
+    description: 'Run a custom check. Read-only by default — pass --execute to actually invoke the command. A check declared where the registry does not read it (a non-rule entry, a Markdown rule) is named, with why.',
     usage: 'shrk checks run <checkId> [--execute] [--report-path <path>] [--changed-only|--staged|--all] [--json]',
     async run(args) {
         const checkId = args.positional[0];
         if (!checkId) {
             process.stderr.write('Usage: shrk checks run <checkId> [--execute]\n');
-            return 2;
+            return ExitCode.UsageError;
         }
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
-        const registry = buildCustomChecksRegistry(inspection.knowledgeEntries);
+        const registry = loadCustomChecks(inspection);
         const entry = registry.entries.find((e) => e.descriptor.id === checkId);
         if (!entry) {
-            process.stderr.write(`No custom check with id "${checkId}".\n`);
-            return 1;
+            // Declared but not registered: say where it is and why, instead of
+            // "no such check" next to a declaration the author can see.
+            const ignored = registry.ignored.find((i) => i.checkIds.includes(checkId));
+            const invalid = registry.invalid.find((i) => i.checkId === checkId);
+            if (ignored) {
+                process.stderr.write(`Custom check "${checkId}" is declared on ${ignored.entryId} (type:'${ignored.entryType}'${ignored.source ? `, ${ignored.source}` : ''}) but is not registered: ${ignored.reason}.\n`);
+            }
+            else if (invalid) {
+                process.stderr.write(`Custom check "${checkId}" is declared on rule ${invalid.ruleId}${invalid.source ? ` (${invalid.source})` : ''} but is invalid: ${invalid.reason}.\n`);
+            }
+            else {
+                const near = nearestIds(checkId, registry.entries.map((e) => e.descriptor.id)).map((n) => n.id);
+                process.stderr.write(`No custom check with id "${checkId}".${near.length > 0 ? ` Did you mean: ${near.join(', ')}?` : ''} (\`shrk checks list\` shows every declared check.)\n`);
+            }
+            return ExitCode.Failure;
         }
         const result = runCustomCheck(entry.descriptor, {
             cwd,
@@ -155,6 +299,8 @@ export const checksRunCommand = {
 };
 export const checksParseReportCommand = {
     name: 'parse-report',
+    // positional[0] is the report FILE; a verb-shaped non-file is refused.
+    positionals: PositionalMode.Path,
     description: 'Parse a sharkcraft.custom-check/v1 JSON report file (or text fallback) and validate its shape.',
     usage: 'shrk checks parse-report <path> [--check-id <id>] [--json]',
     async run(args) {
@@ -230,6 +376,8 @@ function listImportedResults(cwd) {
  */
 export const checksImportCommand = {
     name: 'import',
+    // positional[0] is the result FILE; a verb-shaped non-file is refused.
+    positionals: PositionalMode.Path,
     description: 'Import a sharkcraft.check-result/v1 JSON file (or auto-convert from ESLint JSON) and store it under .sharkcraft/checks/.',
     usage: 'shrk checks import <file> [--tool <name>] [--as eslint|biome|v1] [--json] [--dry-run]',
     async run(args) {

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

@@ -1 +1 @@
-{"version":3,"file":"ci.command.d.ts","sourceRoot":"","sources":["../../src/commands/ci.command.ts"],"names":[],"mappings":"AAeA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAsehC,eAAO,MAAM,SAAS,EAAE,eAsKvB,CAAC"}
+{"version":3,"file":"ci.command.d.ts","sourceRoot":"","sources":["../../src/commands/ci.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyehC,eAAO,MAAM,SAAS,EAAE,eAuMvB,CAAC"}

package/dist/commands/ci.command.js

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { auditCiWorkflow, buildCiIntegrityReport, GateStatus, renderAzureCiWorkflow, renderBitbucketCiWorkflow, renderCiIntegrityHtml, renderCiIntegrityMarkdown, renderGitlabCiWorkflow, renderJenkinsCiWorkflow, } from '@shrkcrft/inspector';
+import { auditCiWorkflow, buildCiIntegrityReport, detectSharkcraftRepo, GateStatus, renderAzureCiWorkflow, renderBitbucketCiWorkflow, renderCiIntegrityHtml, renderCiIntegrityMarkdown, renderGitlabCiWorkflow, renderJenkinsCiWorkflow, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { asJson, header, kv } from "../output/format-output.js";
 function detectRepoAssetState(cwd) {
     const dir = nodePath.join(cwd, 'sharkcraft');
@@ -46,7 +47,9 @@ function buildSteps(inputs) {
         steps.push({ name: 'Drift report', command: 'bun run shrk drift --json > drift.json', artifact: 'drift.json' });
     }
     if (inputs.withBaseline) {
-        steps.push({ name: 'Quality baseline compare', command: 'bun run shrk quality baseline-compare --fail-on-regression --json > baseline-compare.json', artifact: 'baseline-compare.json' });
+        // `quality baseline …` was removed; the committed-ledger drift gate is
+        // `baseline check` (two-way: a lost entry fails like a gained one).
+        steps.push({ name: 'Baseline check', command: 'bun run shrk baseline check --json > baseline-check.json', artifact: 'baseline-check.json' });
     }
     if (inputs.withPolicy) {
         steps.push({ name: 'Policy check', command: 'bun run shrk policy check --json > policy.json', artifact: 'policy.json' });
@@ -404,6 +407,26 @@ function buildGateExplanations(inputs, state) {
 }
 export const ciCommand = {
     name: 'ci',
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: 'scaffold',
+            description: 'Scaffold a CI workflow for a provider (dry-run unless --write).',
+            usage: 'shrk ci scaffold <provider> [--with-quality] [--with-review] [--with-boundaries] [--with-coverage] [--with-drift-gate] [--with-drift] [--with-baseline] [--with-policy] [--with-owners] [--with-test-impact] [--with-dashboard-e2e] [--with-node-compat] [--with-safety-audit] [--with-command-doctor] [--with-pack-tests --pack-paths <p1,p2>] [--with-knowledge-check] [--with-template-drift] [--with-integrity] [--output <path>] [--write] [--force] [--json]',
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: 'permissions',
+            description: 'Audit a CI workflow file’s permissions.',
+            usage: 'shrk ci permissions <workflow-file> [--provider github-actions|gitlab|bitbucket|azure|jenkins] [--json]',
+            positionals: PositionalMode.Path,
+        },
+        {
+            name: 'report',
+            description: 'Aggregate CI reports into one verdict.',
+            usage: 'shrk ci report [--reports-dir <dir>] [--format text|markdown|html|json] [--fail-on error|warning|none]',
+        },
+    ],
     description: 'Scaffold CI configurations for SharkCraft (github-actions, gitlab, circleci, bitbucket, azure-pipelines, jenkins, azure). `shrk ci permissions` audits a workflow file. Supports --with-knowledge-check / --with-template-drift / --with-integrity.',
     usage: 'shrk ci scaffold <provider> [--with-quality] [--with-review] [--with-boundaries] [--with-coverage] [--with-drift-gate] [--with-drift] [--with-baseline] [--with-policy] [--with-owners] [--with-test-impact] [--with-dashboard-e2e] [--with-node-compat] [--with-safety-audit] [--with-command-doctor] [--with-pack-tests --pack-paths <p1,p2>] [--with-knowledge-check] [--with-template-drift] [--with-integrity] [--output <path>] [--write] [--force] [--json]\n  shrk ci permissions <workflow-file> [--provider github-actions|gitlab|bitbucket|azure|jenkins] [--json]',
     async run(args) {
@@ -425,6 +448,16 @@ export const ciCommand = {
             return 2;
         }
         const cwd = resolveCwd(args);
+        // `--with-command-doctor` emits `shrk commands doctor`, which maintains
+        // SharkCraft itself: outside SharkCraft's own repository it exits 78 through
+        // the surface gate, so the generated step would fail every CI run. THE host
+        // authority (`detectSharkcraftRepo`, the one the surface gate reads) decides.
+        if (flagBool(args, 'with-command-doctor') && !detectSharkcraftRepo(cwd)) {
+            process.stderr.write('--with-command-doctor adds `shrk commands doctor`, which maintains SharkCraft itself and does not apply to ' +
+                'this repository — it exits 78 here, so the generated step would fail every CI run. Drop the flag ' +
+                '(it is for the SharkCraft repository only).\n');
+            return 2;
+        }
         const packPathsList = flagList(args, 'pack-paths');
         const withIntegrity = flagBool(args, 'with-integrity');
         // Quickstart / preset auto / pr-checks all expand into the

package/dist/commands/code-intel.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAuE9B,CAAC"}
+{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA+E9B,CAAC"}

package/dist/commands/code-intel.command.js

@@ -1,5 +1,7 @@
 import { buildCodeIntelligenceChecks, DoctorSeverity, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
+import { detectGraphFreshness } from '@shrkcrft/graph';
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk code-intel` — one-shot view of the 14 code-intelligence
@@ -18,6 +20,8 @@ import { asJson, header, kv } from "../output/format-output.js";
  */
 export const codeIntelCommand = {
     name: 'code-intel',
+    // Flag-driven: a bare token used to be ignored at exit 0.
+    positionals: PositionalMode.None,
     description: 'One-shot view of code-intelligence doctor checks (graph, rule-graph, api-surface, quality-gate, migrations, architecture, impact, framework, structural-search, context-planner). Read-only.',
     usage: 'shrk [--cwd <dir>] code-intel [--json] [--markdown] [--only ok,warning,error,info] [--check <id>] [--stale-days N]',
     async run(args) {
@@ -28,7 +32,10 @@ export const codeIntelCommand = {
         const checkId = flagString(args, 'check');
         const staleDaysRaw = flagString(args, 'stale-days');
         const staleDays = staleDaysRaw ? Number.parseInt(staleDaysRaw, 10) : undefined;
-        const options = {};
+        // Divergence against the working tree — the SAME check `shrk graph status`
+        // reports, so the two surfaces cannot contradict each other. Injected
+        // because `@shrkcrft/graph` sits above inspector in the layer order.
+        const options = { graphDivergence: detectGraphFreshness(cwd) };
         if (typeof staleDays === 'number' && Number.isFinite(staleDays) && staleDays > 0) {
             options.staleThresholdDays = staleDays;
         }

package/dist/commands/command-catalog.d.ts

@@ -27,7 +27,17 @@ export declare enum CommandAudience {
     Agent = "agent",
     Ci = "ci",
     PackAuthor = "pack-author",
-    Maintainer = "maintainer"
+    Maintainer = "maintainer",
+    /**
+     * The command's OBJECT is SharkCraft itself — its own docs set, examples
+     * tree, release artifacts, command catalog, round snapshots (round 11
+     * §5.1). Outside SharkCraft's own repository (`detectSharkcraftRepo`, the
+     * one host authority) such a command is gated: tier source
+     * `tool-maintenance`, hidden from `--help`, and invoking it exits 78 through
+     * the surface gate — never a check failure. `surface.enabled` is the escape
+     * hatch.
+     */
+    ToolMaintenance = "tool-maintenance"
 }
 /**
  * User-journey role. Distinct from {@link SafetyLevel} and from the
@@ -220,6 +230,11 @@ export declare function r46Overlay(command: string): IR46OverlayEntry | undefine
 export declare function commandSurface(e: ICommandCatalogEntry): CommandSurface;
 /** Default audience: humans, plus agents if `mcpAvailable`. */
 export declare function commandAudience(e: ICommandCatalogEntry): readonly CommandAudience[];
+/**
+ * True when the row maintains SharkCraft itself ({@link CommandAudience.ToolMaintenance}).
+ * The tier resolver gates such a row outside the tool's own repository.
+ */
+export declare function isToolMaintenance(e: ICommandCatalogEntry): boolean;
 /** Task role (or `undefined` when not classified). */
 export declare function commandTaskRole(e: ICommandCatalogEntry): CommandTaskRole | undefined;
 /**
@@ -256,6 +271,13 @@ export declare function defaultShowInHelp(e: ICommandCatalogEntry): boolean;
  * R46-pruned are excluded), sorted by command.
  */
 export declare function listExplainFamily(): readonly ICommandCatalogEntry[];
+/**
+ * Membership in the explain / dry-run family ({@link listExplainFamily}).
+ * `--full-help` lists the family in its own section, so the surface summary's
+ * `visibleInHelp` counts it too: the one visibility authority and the help
+ * renderer must answer "is X in --help" identically.
+ */
+export declare function isExplainFamily(e: ICommandCatalogEntry): boolean;
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

package/dist/commands/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}