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

package/dist/commands/baseline.command.d.ts

@@ -0,0 +1,8 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const baselineListCommand: ICommandHandler;
+export declare const baselineCheckCommand: ICommandHandler;
+export declare const baselineDiffCommand: ICommandHandler;
+export declare const baselineUpdateCommand: ICommandHandler;
+export declare const baselineExplainCommand: ICommandHandler;
+export declare const baselineCommand: ICommandHandler;
+//# sourceMappingURL=baseline.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.command.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6ShC,eAAO,MAAM,mBAAmB,EAAE,eAyCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAyGlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA8BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAwDnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA2DpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAc7B,CAAC"}

package/dist/commands/baseline.command.js

@@ -0,0 +1,542 @@
+/**
+ * `shrk baseline` — the committed-baseline drift engine.
+ *
+ *   shrk baseline list                      # every declared baseline
+ *   shrk baseline check [--id X]            # recompute + diff vs committed
+ *   shrk baseline diff  [--id X]            # human-readable +added/−removed (never fails)
+ *   shrk baseline update [--id X]           # the explicit, reviewable bless step
+ *   shrk baseline explain --id X            # what it will run/extract, without judging
+ *
+ * Rules come from `sharkcraft.config.ts baselines[]`. A `compute.kind:
+ * "command"` baseline SPAWNS a shell command — which is why the pack-plane
+ * merge seam (`resolveProjectConfig`) drops any pack-contributed baseline that
+ * declares one. Everything reaching this command with a `run` therefore came
+ * from the repo's OWN config, the same trust boundary `verificationCommands`
+ * uses.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { failsWhenEmpty } from '@shrkcrft/core';
+import { baselineCount, baselineFails, computeBaselineFromExtractor, diffBaseline, matchesAny, } from '@shrkcrft/boundaries';
+import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
+import { asJson, header, kv } from "../output/format-output.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+const SCHEMA = 'sharkcraft.baseline/v1';
+const DEFAULT_TIMEOUT_MS = 60_000;
+async function loadBaselines(cwd) {
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return { ok: false, message: loaded.error.message };
+    const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+    return {
+        ok: true,
+        value: {
+            rules: loaded.value.config.baselines ?? [],
+            planeDiagnostics: loaded.value.planeDiagnostics,
+            sharkcraftDirRel: rel && !rel.startsWith('..') ? rel : '',
+        },
+    };
+}
+/** Narrow to `--id`, refusing an unknown id rather than silently selecting nothing. */
+function selectRules(rules, id) {
+    if (!id)
+        return { ok: true, rules };
+    const wanted = id.split(',').map((s) => s.trim()).filter(Boolean);
+    const known = new Set(rules.map((r) => r.id));
+    const unknown = wanted.filter((w) => !known.has(w));
+    if (unknown.length > 0) {
+        return {
+            ok: false,
+            message: `Unknown baseline id(s): ${unknown.join(', ')}. Declared: ${[...known].join(', ') || '(none)'}`,
+        };
+    }
+    return { ok: true, rules: rules.filter((r) => wanted.includes(r.id)) };
+}
+function computeCurrent(cwd, rule, excludeDirs) {
+    if (rule.compute.kind === 'extractor') {
+        const source = rule.compute.source;
+        if (!source)
+            return { text: '', error: 'compute.kind "extractor" but no `source` declared' };
+        const res = computeBaselineFromExtractor(cwd, source, excludeDirs);
+        return res.error
+            ? { text: '', error: res.error, filesScanned: res.filesScanned }
+            : { text: res.text, filesScanned: res.filesScanned };
+    }
+    const run = rule.compute.run;
+    if (!run || run.trim() === '') {
+        return { text: '', error: 'compute.kind "command" but no `run` declared' };
+    }
+    const child = spawnSync(run, {
+        cwd,
+        shell: true,
+        encoding: 'utf8',
+        timeout: rule.compute.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    if (child.error)
+        return { text: '', error: `compute command failed to start: ${child.error.message}` };
+    if (child.status !== 0) {
+        const tail = String(child.stderr ?? '').trim().split('\n').slice(-3).join(' | ');
+        return {
+            text: '',
+            error: `compute command exited ${child.status ?? 'null'}${tail ? ` — ${tail}` : ''}`,
+        };
+    }
+    return { text: String(child.stdout ?? '') };
+}
+function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
+    // --changed-only is honest about what it CANNOT scope: a command compute with
+    // no `watchFiles` has no file footprint, so it is reported as skipped rather
+    // than quietly passing.
+    if (changedFiles !== undefined) {
+        const globs = rule.watchFiles && rule.watchFiles.length > 0
+            ? rule.watchFiles
+            : rule.compute.kind === 'extractor'
+                ? (rule.compute.source?.files ?? [])
+                : undefined;
+        if (globs === undefined) {
+            return {
+                rule,
+                status: 'skipped',
+                committedCount: 0,
+                currentCount: 0,
+                skipReason: 'command compute with no `watchFiles` cannot be scoped to a changeset',
+            };
+        }
+        if (!changedFiles.some((f) => matchesAny(f, globs))) {
+            return {
+                rule,
+                status: 'skipped',
+                committedCount: 0,
+                currentCount: 0,
+                skipReason: 'no watched file changed',
+            };
+        }
+    }
+    const abs = nodePath.resolve(cwd, rule.baseline);
+    if (!existsSync(abs)) {
+        // No artifact yet. `check` must still fail (nothing to compare against),
+        // but the CURRENT side is knowable and is exactly what the author needs to
+        // see before blessing — so compute it rather than reporting a false `0`.
+        const first = computeCurrent(cwd, rule, excludeDirs);
+        return {
+            rule,
+            status: 'error',
+            committedCount: 0,
+            ...(first.error ? {} : { current: first.text }),
+            currentCount: first.error ? 0 : baselineCount(rule, first.text),
+            missingBaseline: true,
+            error: first.error ??
+                `committed baseline ${rule.baseline} does not exist — create it with \`shrk baseline update --id ${rule.id}\``,
+        };
+    }
+    let committed;
+    try {
+        committed = readFileSync(abs, 'utf8');
+    }
+    catch (e) {
+        return {
+            rule,
+            status: 'error',
+            committedCount: 0,
+            currentCount: 0,
+            error: `could not read ${rule.baseline}: ${e.message}`,
+        };
+    }
+    const computed = computeCurrent(cwd, rule, excludeDirs);
+    if (computed.error) {
+        return { rule, status: 'error', committed, committedCount: 0, currentCount: 0, error: computed.error };
+    }
+    const committedCount = baselineCount(rule, committed);
+    const currentCount = baselineCount(rule, computed.text);
+    // A recompute that produced NOTHING compared nothing — and left as a pass it
+    // would "match" an empty baseline forever, the silent-green this plane exists
+    // to prevent. But this only holds when the COMMITTED side is empty too: if
+    // the baseline has entries and the recompute has none, that is real drift
+    // (everything vanished) and must be reported as such, not swallowed as a skip.
+    if (currentCount === 0 && committedCount === 0) {
+        return {
+            rule,
+            status: failsWhenEmpty(rule) ? 'failed' : 'skipped',
+            committed,
+            current: computed.text,
+            committedCount,
+            currentCount,
+            skipReason: 'the recompute produced no entries (and the committed baseline is empty too)',
+        };
+    }
+    const diff = diffBaseline(rule, committed, computed.text);
+    return {
+        rule,
+        status: baselineFails(rule, diff) ? 'failed' : 'passed',
+        diff,
+        committed,
+        current: computed.text,
+        committedCount,
+        currentCount,
+        // A total wipe is far more often a broken compute than a real emptying —
+        // say so next to the diff so it is not blessed by reflex.
+        ...(currentCount === 0 ? { emptyCompute: true } : {}),
+    };
+}
+function hintFor(rule) {
+    return rule.hint ?? `review the diff, then bless it with \`shrk baseline update --id ${rule.id}\``;
+}
+function outcomeJson(o) {
+    return {
+        id: o.rule.id,
+        ...(o.rule.description ? { description: o.rule.description } : {}),
+        baseline: o.rule.baseline,
+        severity: o.rule.severity ?? 'error',
+        direction: o.rule.direction ?? 'two-way',
+        status: o.status,
+        committedCount: o.committedCount,
+        currentCount: o.currentCount,
+        ...(o.diff ? { diff: { added: o.diff.added, removed: o.diff.removed, mode: o.diff.mode, canonical: o.diff.canonical } } : {}),
+        ...(o.error ? { error: o.error } : {}),
+        ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+        ...(o.emptyCompute ? { emptyCompute: true } : {}),
+        ...(o.missingBaseline ? { missingBaseline: true } : {}),
+        hint: hintFor(o.rule),
+    };
+}
+/** Print one outcome's ±diff, capped so a huge drift stays readable. */
+function writeDiff(o, cap = 25) {
+    if (!o.diff)
+        return;
+    for (const a of o.diff.added.slice(0, cap))
+        process.stdout.write(`      + ${a}\n`);
+    if (o.diff.added.length > cap)
+        process.stdout.write(`      + … (${o.diff.added.length - cap} more)\n`);
+    for (const r of o.diff.removed.slice(0, cap))
+        process.stdout.write(`      - ${r}\n`);
+    if (o.diff.removed.length > cap)
+        process.stdout.write(`      - … (${o.diff.removed.length - cap} more)\n`);
+}
+/** Shared prologue: load config, select rules, resolve the changed scope. */
+async function prepare(args, opts) {
+    const cwd = resolveCwd(args);
+    const json = flagBool(args, 'json');
+    const loaded = await loadBaselines(cwd);
+    if (!loaded.ok) {
+        if (json)
+            process.stdout.write(asJson({ schema: SCHEMA, error: loaded.message }) + '\n');
+        else
+            process.stderr.write(`Could not load config: ${loaded.message}\n  Run \`shrk doctor\` for details.\n`);
+        return { ok: false, code: ExitCode.UsageError };
+    }
+    const selected = selectRules(loaded.value.rules, flagString(args, 'id') ?? undefined);
+    if (!selected.ok) {
+        process.stderr.write(selected.message + '\n');
+        return { ok: false, code: ExitCode.UsageError };
+    }
+    let changedFiles;
+    if (opts.changedAware) {
+        const since = flagString(args, 'since');
+        if (flagBool(args, 'changed-only') || since) {
+            changedFiles = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(since ? { since } : {}),
+                ...(!since ? { includeWorktree: true } : {}),
+            }).files;
+        }
+    }
+    return {
+        ok: true,
+        cwd,
+        rules: selected.rules,
+        all: loaded.value.rules,
+        excludeDirs: loaded.value.sharkcraftDirRel ? [loaded.value.sharkcraftDirRel] : [],
+        ...(changedFiles !== undefined ? { changedFiles } : {}),
+        planeDiagnostics: loaded.value.planeDiagnostics,
+    };
+}
+/** The "no baselines declared" landing, shared by every subverb. */
+function writeNoRules(json) {
+    if (json) {
+        process.stdout.write(asJson({ schema: SCHEMA, results: [], evaluated: 0, verdict: 'not-verified' }) + '\n');
+        return ExitCode.NotVerified;
+    }
+    process.stdout.write(header('Baselines'));
+    process.stdout.write('  No baselines declared. Add `baselines[]` to sharkcraft.config.ts to replace a\n' +
+        '  hand-rolled "committed file + recompute script + drift test" trio with one\n' +
+        '  two-way engine (see docs/baseline-drift.md).\n');
+    return ExitCode.NotVerified;
+}
+export const baselineListCommand = {
+    name: 'list',
+    description: 'List every declared baseline: what it pins, how it recomputes, which direction fails.',
+    usage: 'shrk baseline list [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args, { changedAware: false });
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.all.length === 0)
+            return writeNoRules(json);
+        if (json) {
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                baselines: prep.all.map((r) => ({
+                    id: r.id,
+                    description: r.description ?? null,
+                    baseline: r.baseline,
+                    compute: r.compute.kind,
+                    direction: r.direction ?? 'two-way',
+                    keyBy: r.keyBy ?? null,
+                    failOnEmpty: r.failOnEmpty === true,
+                })),
+                diagnostics: prep.planeDiagnostics,
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Baselines (${prep.all.length})`));
+        for (const r of prep.all) {
+            process.stdout.write(`  • ${r.id}  →  ${r.baseline}\n`);
+            process.stdout.write(`      compute ${r.compute.kind}${r.compute.kind === 'command' ? ` (${r.compute.run})` : ''}` +
+                `  ·  direction ${r.direction ?? 'two-way'}${r.keyBy ? `  ·  keyBy ${r.keyBy}` : ''}` +
+                `${r.failOnEmpty ? '  ·  failOnEmpty' : ''}\n`);
+            if (r.description)
+                process.stdout.write(`      ${r.description}\n`);
+        }
+        for (const d of prep.planeDiagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        return ExitCode.VerifiedPass;
+    },
+};
+export const baselineCheckCommand = {
+    name: 'check',
+    description: 'Recompute every declared baseline and fail on drift. Two-way by default — a LOST entry fails exactly like a gained one.',
+    usage: 'shrk baseline check [--id <ids>] [--changed-only] [--since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'changed-only']),
+    async run(args) {
+        const prep = await prepare(args, { changedAware: true });
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.rules.length === 0)
+            return writeNoRules(json);
+        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, prep.changedFiles));
+        const failed = outcomes.filter((o) => o.status === 'failed' || (o.status === 'error' && (o.rule.severity ?? 'error') === 'error'));
+        const evaluated = outcomes.filter((o) => o.status !== 'skipped').length;
+        // 0 only when a NON-EMPTY scope was actually compared; 2 when nothing was.
+        // A skipped baseline is "partially verified", never a green 0.
+        const skippedCount = outcomes.filter((o) => o.status === 'skipped').length;
+        const exit = failed.length > 0
+            ? ExitCode.Failure
+            : evaluated === 0 || skippedCount > 0
+                ? ExitCode.NotVerified
+                : ExitCode.VerifiedPass;
+        if (json) {
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                results: outcomes.map(outcomeJson),
+                evaluated,
+                skipped: outcomes.filter((o) => o.status === 'skipped').length,
+                verdict: failed.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
+                diagnostics: prep.planeDiagnostics,
+                gate: buildGateEnvelope('baseline check', exit, outcomes.map((o) => ({
+                    id: o.rule.id,
+                    type: 'baseline',
+                    status: o.status,
+                    severity: o.rule.severity ?? 'error',
+                    counts: { committed: o.committedCount, current: o.currentCount },
+                    violations: [
+                        ...(o.diff?.added ?? []).map((id) => ({ id, message: 'added', hint: hintFor(o.rule) })),
+                        ...(o.diff?.removed ?? []).map((id) => ({ id, message: 'removed', hint: hintFor(o.rule) })),
+                    ],
+                    ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+                    ...(o.error ? { error: o.error } : {}),
+                }))),
+            }) + '\n');
+            return exit;
+        }
+        process.stdout.write(header('Baseline drift'));
+        process.stdout.write(kv('evaluated', `${evaluated} of ${prep.rules.length}`) + '\n');
+        for (const o of outcomes) {
+            if (o.status === 'passed') {
+                process.stdout.write(`  ✓ ${o.rule.id}  (${o.currentCount} entries, no drift)\n`);
+                continue;
+            }
+            if (o.status === 'skipped') {
+                process.stdout.write(`  – ${o.rule.id}  SKIPPED — ${o.skipReason}\n`);
+                continue;
+            }
+            if (o.status === 'error') {
+                process.stdout.write(`  ! ${o.rule.id}  ${o.error}\n`);
+                if (o.missingBaseline && o.currentCount > 0) {
+                    process.stdout.write(`      the compute currently yields ${o.currentCount} entr${o.currentCount === 1 ? 'y' : 'ies'} — ` +
+                        `run \`shrk baseline update --id ${o.rule.id}\` to bless them.\n`);
+                }
+                continue;
+            }
+            const added = o.diff?.added.length ?? 0;
+            const removed = o.diff?.removed.length ?? 0;
+            process.stdout.write(`  ✗ ${o.rule.id}  DRIFT — ${added} added, ${removed} removed ` +
+                `(${o.committedCount} committed → ${o.currentCount} now, ${o.diff?.mode})\n`);
+            writeDiff(o);
+            if (o.emptyCompute) {
+                process.stdout.write('      ! the recompute produced 0 entries — check the compute before blessing this.\n');
+            }
+            process.stdout.write(`      → ${hintFor(o.rule)}\n`);
+        }
+        for (const d of prep.planeDiagnostics)
+            process.stdout.write(`  ! ${d}\n`);
+        if (exit === ExitCode.NotVerified) {
+            process.stdout.write('\nNothing was compared — this is NOT a pass. Every selected baseline was skipped.\n');
+        }
+        else if (exit === ExitCode.VerifiedPass) {
+            process.stdout.write('\nEvery baseline matches its committed artifact. ✓\n');
+        }
+        return exit;
+    },
+};
+export const baselineDiffCommand = {
+    name: 'diff',
+    description: 'Show the +added / −removed entries for each baseline without failing — the inspection verb (always exits 0 when it ran).',
+    usage: 'shrk baseline diff [--id <ids>] [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const prep = await prepare(args, { changedAware: false });
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        if (prep.rules.length === 0)
+            return writeNoRules(json);
+        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, undefined));
+        if (json) {
+            process.stdout.write(asJson({ schema: SCHEMA, results: outcomes.map(outcomeJson), inspection: true }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header('Baseline diff (inspection — never fails)'));
+        for (const o of outcomes) {
+            const added = o.diff?.added.length ?? 0;
+            const removed = o.diff?.removed.length ?? 0;
+            process.stdout.write(`\n${o.rule.id}  (${o.rule.baseline})  ${o.status === 'error' ? `! ${o.error}` : `+${added} / -${removed}`}\n`);
+            writeDiff(o, 100);
+        }
+        return ExitCode.VerifiedPass;
+    },
+};
+export const baselineUpdateCommand = {
+    name: 'update',
+    description: 'Rewrite the committed baseline from the current value — the explicit, reviewable bless step. Writes files.',
+    usage: 'shrk baseline update [--id <ids>] [--dry-run] [--json]',
+    booleanFlags: new Set(['json', 'dry-run']),
+    async run(args) {
+        const prep = await prepare(args, { changedAware: false });
+        if (!prep.ok)
+            return prep.code;
+        const json = flagBool(args, 'json');
+        const dryRun = flagBool(args, 'dry-run');
+        if (prep.rules.length === 0)
+            return writeNoRules(json);
+        const written = [];
+        const errors = [];
+        for (const rule of prep.rules) {
+            const computed = computeCurrent(prep.cwd, rule, prep.excludeDirs);
+            if (computed.error) {
+                errors.push({ id: rule.id, error: computed.error });
+                continue;
+            }
+            if (computed.text.trim() === '' && failsWhenEmpty(rule)) {
+                errors.push({
+                    id: rule.id,
+                    error: 'refusing to write an EMPTY baseline for a `failOnEmpty` rule — fix the compute first',
+                });
+                continue;
+            }
+            const abs = nodePath.resolve(prep.cwd, rule.baseline);
+            const previous = existsSync(abs) ? readFileSync(abs, 'utf8') : undefined;
+            const changed = previous !== computed.text;
+            if (!dryRun && changed) {
+                mkdirSync(nodePath.dirname(abs), { recursive: true });
+                writeFileSync(abs, computed.text, 'utf8');
+            }
+            written.push({ id: rule.id, path: rule.baseline, bytes: computed.text.length, changed });
+        }
+        if (json) {
+            process.stdout.write(asJson({ schema: SCHEMA, dryRun, written, errors }) + '\n');
+            return errors.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(dryRun ? 'Baseline update (dry run)' : 'Baseline update'));
+        for (const w of written) {
+            process.stdout.write(`  ${w.changed ? (dryRun ? 'would write' : 'wrote') : 'unchanged '} ${w.path}  (${w.bytes} bytes)\n`);
+        }
+        for (const e of errors)
+            process.stdout.write(`  ! ${e.id}: ${e.error}\n`);
+        if (written.some((w) => w.changed) && !dryRun) {
+            process.stdout.write('\nReview the diff before committing — this is the bless step.\n');
+        }
+        return errors.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+    },
+};
+export const baselineExplainCommand = {
+    name: 'explain',
+    description: 'Show what ONE baseline will compute and compare — the command or extractor, the canonical form, both entry counts and the diff — without turning it into a verdict.',
+    usage: 'shrk baseline explain --id <id> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = flagString(args, 'id') ?? args.positional[0];
+        if (!id) {
+            process.stderr.write('Usage: shrk baseline explain --id <id>\n');
+            return ExitCode.UsageError;
+        }
+        const prep = await prepare(args, { changedAware: false });
+        if (!prep.ok)
+            return prep.code;
+        const rule = prep.all.find((r) => r.id === id);
+        if (!rule) {
+            process.stderr.write(`No baseline "${id}". Declared: ${prep.all.map((r) => r.id).join(', ') || '(none)'}\n`);
+            return ExitCode.UsageError;
+        }
+        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, undefined);
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.baseline-explain/v1',
+                ...outcomeJson(outcome),
+                compute: rule.compute,
+                watchFiles: rule.watchFiles ?? null,
+            }) + '\n');
+            return ExitCode.VerifiedPass;
+        }
+        process.stdout.write(header(`Baseline: ${rule.id}`));
+        if (rule.description)
+            process.stdout.write(`  ${rule.description}\n`);
+        process.stdout.write(kv('committed', rule.baseline) + '\n');
+        process.stdout.write(kv('compute', rule.compute.kind === 'command' ? `command · ${rule.compute.run}` : `extractor · ${rule.compute.source?.extract ?? 'sugar'}`) + '\n');
+        process.stdout.write(kv('direction', rule.direction ?? 'two-way') + '\n');
+        process.stdout.write(kv('canonical', outcome.diff?.canonical ?? rule.compute.canonical ?? 'auto') + '\n');
+        if (rule.keyBy)
+            process.stdout.write(kv('keyBy', rule.keyBy) + '\n');
+        process.stdout.write(kv('entries', outcome.missingBaseline
+            ? `committed (none yet) → ${outcome.currentCount} now`
+            : `${outcome.committedCount} committed → ${outcome.currentCount} now`) + '\n');
+        process.stdout.write(kv('status', outcome.status) + '\n');
+        if (outcome.error)
+            process.stdout.write(`  ! ${outcome.error}\n`);
+        if (outcome.skipReason)
+            process.stdout.write(`  – ${outcome.skipReason}\n`);
+        if (outcome.diff && (outcome.diff.added.length > 0 || outcome.diff.removed.length > 0)) {
+            process.stdout.write('\n  diff:\n');
+            writeDiff(outcome, 100);
+        }
+        return ExitCode.VerifiedPass;
+    },
+};
+export const baselineCommand = {
+    name: 'baseline',
+    description: 'Committed-baseline drift engine: recompute a ledger/digest/allow-list and fail on drift in BOTH directions. Read-only except `update`.',
+    usage: 'shrk baseline list | check | diff | update | explain --id <id>',
+    booleanFlags: new Set(['json', 'changed-only', 'dry-run']),
+    async run(args) {
+        const sub = args.positional[0];
+        process.stderr.write((sub ? `Unknown subcommand "${sub}". ` : '') +
+            'Usage: shrk baseline list | check [--id X] | diff | update | explain --id <id>\n');
+        return ExitCode.UsageError;
+    },
+};

package/dist/commands/changelog-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAwGjE,CAAC"}
+{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAkJjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -112,4 +112,46 @@ export const RELEASE_SURFACE_DELTAS = [
         ],
         removed: [],
     },
+    {
+        version: '0.1.0-alpha.28',
+        title: "The plane the compiler can't see — six data-defined gate planes on one extraction DSL",
+        added: [
+            '`shrk gates list | coverage | explain <id>` — the rule-authoring trust layer across EVERY data-defined plane (wiring / policy / registry / registration / baseline / generated). `coverage` is the stale-selector detector: it reports what each rule actually MATCHED and flags every rule matching 0, so a rule quietly dying is itself a CI failure.',
+            '`shrk baseline list | check | diff | update | explain` — the committed-ledger drift engine (`baselines[]`). TWO-WAY by default: a silently LOST entry fails exactly like a gained one. `update` is a separate, explicit bless verb.',
+            '`shrk generated list | check | update | explain` — generated-artifact drift + provenance (`generatedArtifacts[]`). Regenerates into a temp dir and diffs BOTH ways (hand-edited file AND a regen that writes a subset), plus the "do not edit" header contract. `--headers-only` never spawns.',
+            '`shrk policy-lint explain <ruleId>` — every hit with file:line, INCLUDING the hits an exemption or the scan zone dropped, each labelled with which one applied.',
+            '`shrk registry <name> duplicates` — ids declared in more than one place, with every declaration site (load-order roulette the compiler cannot see).',
+            'Extraction DSL on every rule source: `extract` with 9 kinds (`regex-capture`, `array-members`, `object-keys`, `enum-members`, `export-names`, `call-args`, `decorator-args`, `string-union-members`, `json-path`) plus `anchor` / `argIndex` / `capture` and the `match` + `exclude` allow/deny pair.',
+            'Wiring relations: `mode: disjoint`, `registeredMode: intersection`, multi-hop `chain`, `{id}` message templating, and `failOnEmpty` / `selfTest` on every plane.',
+            'Policy rules: `scan: all|code|strings|comments` (lexical zone classifier), `exemptFiles`, `exemptLines`.',
+        ],
+        changed: [
+            'Loud-skip contract: a rule whose SOURCE side matches 0 files / extracts 0 ids is `skipped` and the check exits `2` (NOT verified), never a green `0`; `failOnEmpty: true` promotes it to `1`. An empty SINK is deliberately NOT a skip — it stays a failure, annotated `emptySink`, so a real total-miss is never downgraded.',
+            '`shrk policy-lint` exits `2` when it evaluated nothing, and reports exemption-suppressed hits as a count instead of silently deleting them.',
+            "`shrk finish`'s import sub-gate lists only the findings that DRIVE the verdict — allowlisted (`info`) entries no longer pad the capped fix-list and push a real error out of view.",
+            'MCP: the pack-helper tool is now `get_pack_helper` (was `get_helper`, which collided with the helper-registry tool and made one of the two unreachable via `tools/call`). Completes the dedup that already renamed `list_helpers` → `list_pack_helpers`.',
+            'Pack safety: `baselines[]` / `generatedArtifacts[]` are pack-distributable, but the merge seam DROPS any pack-contributed element declaring a shell command (`compute.run` / `regen`) — mirroring the "pack-contributed verification commands are NOT auto-run" contract.',
+        ],
+        removed: [],
+    },
+    {
+        version: '0.1.0-alpha.29',
+        title: 'The exit code has to agree with the sentence',
+        added: [
+            '`shrk check wiring --fix` — deterministic autofix for the mechanically-unambiguous `declared-but-not-registered` case: append the missing id to its sink array. Dry-run by default, `--write` applies. Refuses ambiguity (N sinks, non-array sink, non-unique file/array, chain rules, parity violations) and lists what it left alone WITH the reason — it never guesses.',
+            '`shrk explain <ruleId>` resolves a rule id across ALL planes and dispatches to the right explainer; a non-rule token still gets the original topic search. The per-plane forms remain.',
+            'A shared `gate` envelope (`sharkcraft.gate/v1`) inside every gate verb\'s `--json`: `verb` / `exit` / normalized per-rule `{id,type,status,severity,counts,violations,skipReason}`. Additive — the per-plane payloads are unchanged. See docs/gate-json.md.',
+            'Global `--no-hints` silences the advisory piped-exit note (the structured `--exit-trailer` channel is unaffected).',
+            'Exit code `3` = usage error (unloadable config / unknown rule id / bad flag value) on the gate verbs, split out of `2` so "the gate proved nothing" and "the gate never started" are distinguishable.',
+        ],
+        changed: [
+            'A SKIPPED rule is no longer masked by a passing sibling. `failOnEmpty` now defaults to TRUE for `error`-severity rules (an error rule matching zero subjects is a bug in the rule, not a pass) and any skip with no failures exits `2`, never `0`. `warning`-severity rules still default to `false`. BEHAVIOUR CHANGE: an error-severity rule that matches nothing now exits `1` — fix the selector or set `failOnEmpty: false`.',
+            '`shrk help <multi-word verb>` resolves catalog-documented paths (`check wiring`, `wiring unprovided`, …) that are dispatched from a parent handler and therefore never appear in the command trie; it also lists sibling verbs. Previously answered "Unknown command".',
+            '`shrk baseline explain` always computes the CURRENT side, so a rule with no committed artifact yet reports `committed (none yet) → N now` instead of a false `0 now`. `baseline check` names what would be blessed.',
+            '`shrk registry` accepts both argument orders — `registry list <name>` now works alongside `registry <name> list`; a verb-first call with an unknown name names the correct grammar.',
+            '`shrk policy-lint` returns `3` (usage) rather than `1` (violations) when the config cannot be loaded, and `2` when it scanned nothing.',
+            'The piped-exit note is emitted at most once per process.',
+        ],
+        removed: [],
+    },
 ];

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

@@ -1 +1 @@
-{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAu4BhC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}
+{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2iChC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}