@wirecat/cli-base 0.50.3 → 0.51.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.51.0 — 24.10.2026
+
+### Added
+
+- **Comparison pages live in the site repository, and our marks are re-checked at each release** (`WC-CMP-11`, [Comparisons](docs/standards/comparisons.md)). The page is written in `cli-docs` (wirecat.dev) because a comparison changes when other tools change, not when we release; the CLI repository keeps a short `docs/compare.md` that links to it. The release report lists the compare page as checked. Nothing changes in code.
+
+### Changed — may break callers
+
+- **Shared command contracts require explicit overrides before host edits.** `sharedCommand`, `assertSharedContracts`, `overrideSharedContract` and `customizeSharedCommand` live in `/commands`; original definitions and exact accepted edits remain available for audits. Independent shell replacements must supply static, exact before/after declarations; a new Core default or a changed provider builder fails until those declarations are reviewed. Provider additions are allowed; inherited subcommands cannot disappear silently. `/commands` now loads Commander at runtime.
+
+- **Cross-CLI contract drift cannot be accepted through a lint baseline.** Declare intentional differences with
+  their exact expected values and a specific reason; a changed or stale exemption fails. `audit --complete`
+  collects actual schemas and error reasons from `commands info --json` and refuses missing coverage. Canonical capability manifests and validated inherited definitions distinguish explicit provider variants from drift. Global
+  options satisfy matching command-local controls, so their placement alone is no longer a divergence.
+
+### Fixed
+
+- **Complete audits keep runtime availability separate from static contracts.** A currently denied or available command retains the same protected grammar and output definition.
+
+- **Command lint distinguishes list filters from computation and output controls.** Ranking weights, timezone, output context and byte pagination remain controls even when an answer exposes similarly named fields; singleton targets are not list filters. Native query fields and id/time filtering remain checked.
+
+## 0.50.4 — 24.10.2026
+
+### Added
+
+- **The shared vocabulary covers knowledge-work resources and receipt delivery.** Registers agents,
+  reminders, key documents, evidence answers and the mail archive, with distinct assignment, decision reversal,
+  evidence invalidation and receipt acknowledgement actions. Registers the four missing stored meeting
+  selector ID flags with target roles. Existing canonical verbs still replace overlapping Memo spellings;
+  forum `--topic <id>` keeps its existing meaning, while meeting tags/topics use native query terms.
+
+- **A standard for comparison pages** ([Comparisons](docs/standards/comparisons.md), `WC-CMP-1` to `WC-CMP-10`). A CLI's `docs/compare.md` compares it with the tools a reader would pick for the same job, lists user tasks rather than implementation details, always has an "Agents and safety" group and says where another tool is better (owner, 2026-10-24). Nothing changes in code.
+
+### Fixed
+
+- **Denied commands remain discoverable.** The MCP and permission standards require current availability metadata instead of hiding denied commands. CLI help retains the same capabilities; execution still enforces the permission. This records the owner's discovery rule for every CLI.
+
+
+- **`sync` covers a two-way mirror.** The vocabulary's meaning of `sync` now says a mirror syncs both ways, so drive's `mirrors sync`, which also writes changes back to Google, uses the verb as defined (owner, 2026-10-24). Nothing changes for one-way syncs.
+
+- **Release checks reject high production dependency findings and audit a fresh npm resolution.** The lockfile-only
+  critical gate missed high findings and newer transitive resolutions. Update the reusable workflow pin to adopt
+  the checks; fix high findings before releasing. Package packing and resolution disable lifecycle scripts.
+
 ## 0.50.3 — 23.10.2026
 
 ### Added

package/README.md

@@ -24,8 +24,8 @@ the command tree as data — the parts every CLI needs and nobody should write t
 | [Shared tooling](docs/TOOLING.md) | The TypeScript, Biome, lefthook, docs and CI setup a CLI takes from here, and `cli-dev` |
 | [Testing](docs/dev/TESTING.md) | The checks, and what each one is for |
 | [Conventions](docs/dev/CONVENTIONS.md) | How code here is written |
-| [Standards handbook](docs/standards/README.md) | The rules every WireCat CLI follows, one page per area (a skeleton for now) |
-| [CLI standard](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md) | The rules every WireCat CLI follows; this package holds them as data |
+| [Standards handbook](docs/standards/README.md) | The rules every WireCat CLI follows, one page per area and a new-CLI checklist |
+| [CLI standard](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md) | The messenger-specific rules for tg, max and wa |
 | [Roadmap](docs/roadmap.md) | What is being built next for developers on this package |
 | [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
 
@@ -113,12 +113,13 @@ record — live in `/standards` as Valibot schemas that also emit JSON Schema 20
 
 - **The whole command tree as data.** `describeProgram` walks the live Commander tree, like `rails routes`: every
   command, option, default, conflict and whether it writes. `commands --json` gives it to an agent instead of `--help`.
-- **A linter for command trees.** `cli-dev lint` checks a CLI's tree against 15 rules — unknown verbs, filter flags
+- **A linter for command trees.** `cli-dev lint` checks a CLI's tree against 19 rules — unknown verbs, filter flags
   that should be query fields, examples that do not run, key casing and more. Known violations live in a baseline
   that may only shrink.
 - **An audit across CLIs.** `cli-dev audit` reads several CLIs' command trees and checks them against each other:
   the commands every CLI must have, the same options and output where two CLIs share a path, the same meaning for the
-  same flag, the same entity schemas and error reasons. A weekly workflow runs it over the published CLIs.
+  same flag. Entity-schema and error-reason comparisons require additional inputs; the weekly published-CLI
+  run does not supply them and reports `n/a` for those checks.
 
 ### One query language for every list
 

package/dist/commands/contracts.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+export interface SharedContractOverride {
+    command: readonly string[];
+    field: string;
+    before: unknown;
+    after: unknown;
+    reason: string;
+}
+export declare const hasSharedContract: (command: Command) => boolean;
+export declare const assertSharedContracts: (root: Command) => void;
+/** The callback names the deliberate edit; an already changed contract cannot be acknowledged after the fact. */
+export declare const overrideSharedContract: <T extends Command>(command: T, reason: string, change: (command: T) => void) => T;
+export declare const sharedContractOverrides: (root: Command) => SharedContractOverride[];
+/** The original core definitions remain available independently of each host's accepted edits. */
+export declare const sharedContracts: (root: Command) => Record<string, unknown>;
+/** Preserve the factory signature while recording the definition before host composition can edit it. */
+export declare const sharedCommand: <Args extends unknown[], Result>(factory: (...args: Args) => Result) => (...args: Args) => Result;
+/** Bind a provider shell only when its exact, reviewed differences still match Core. */
+export declare const customizeSharedCommand: (reference: Command, reason: string, build: () => Command, expectedOverrides: readonly SharedContractOverride[]) => Command;

package/dist/commands/contracts.js

@@ -0,0 +1,207 @@
+import { isDeepStrictEqual } from "node:util";
+import { Command } from "commander";
+import { CliError } from "../errors.js";
+import { describeProgram } from "./registry.js";
+const protectedCommands = new WeakMap();
+export const hasSharedContract = (command) => protectedCommands.has(command);
+const snapshot = (command, children) => {
+    const root = new Command("contract");
+    const parent = command.parent;
+    root.addCommand(command);
+    const described = describeProgram(root)[0];
+    command.parent = parent;
+    if (!described)
+        throw new Error("a hidden command cannot own a shared contract");
+    const { commands: _, usage: __, path: ___, ...contract } = described;
+    return structuredClone({
+        ...contract,
+        aliases: [...command.aliases()],
+        children: (children ?? protectedCommands.get(command)?.originalChildren ?? command.commands)
+            .filter((child) => command.commands.includes(child) && !child._hidden)
+            .map((child) => child.name()),
+    });
+};
+const same = isDeepStrictEqual;
+const visit = (root, fn) => {
+    fn(root);
+    for (const child of root.commands)
+        visit(child, fn);
+};
+const pathOf = (command) => {
+    const path = [command.name()];
+    for (let at = command.parent; at?.parent; at = at.parent)
+        path.unshift(at.name());
+    return path;
+};
+const differences = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((field) => !same(before[field], after[field]));
+export const assertSharedContracts = (root) => {
+    const changed = [];
+    visit(root, (command) => {
+        const protectedContract = protectedCommands.get(command);
+        if (!protectedContract)
+            return;
+        const fields = differences(protectedContract.contract, snapshot(command));
+        if (fields.length)
+            changed.push({ command: pathOf(command).join(" "), fields });
+    });
+    if (changed.length)
+        throw new CliError("configuration_error", `shared contract changed without an explicit override: ${changed.map((one) => `${one.command} (${one.fields.join(", ")})`).join("; ")}; use overrideSharedContract before changing it`, { reason: "contract.unacknowledged-override", contracts: changed });
+};
+/** The callback names the deliberate edit; an already changed contract cannot be acknowledged after the fact. */
+export const overrideSharedContract = (command, reason, change) => {
+    if (reason.trim().length < 10)
+        throw new Error("a shared contract override needs a specific reason");
+    const protectedContract = protectedCommands.get(command);
+    if (!protectedContract)
+        throw new Error("only a core-owned command contract can be overridden");
+    assertSharedContracts(command);
+    const before = snapshot(command);
+    change(command);
+    const after = snapshot(command);
+    const fields = differences(before, after);
+    if (fields.length === 0)
+        throw new Error("a shared contract override must change its named command");
+    for (const field of fields)
+        protectedContract.overrides.push({
+            command: pathOf(command),
+            field,
+            before: before[field] ?? null,
+            after: after[field] ?? null,
+            reason: reason.trim(),
+        });
+    protectedContract.contract = after;
+    return command;
+};
+export const sharedContractOverrides = (root) => {
+    assertSharedContracts(root);
+    const result = [];
+    visit(root, (command) => {
+        for (const override of protectedCommands.get(command)?.overrides ?? [])
+            result.push({ ...structuredClone(override), command: pathOf(command) });
+    });
+    return result;
+};
+/** The original core definitions remain available independently of each host's accepted edits. */
+export const sharedContracts = (root) => {
+    assertSharedContracts(root);
+    const result = {};
+    visit(root, (command) => {
+        const contract = protectedCommands.get(command);
+        if (contract)
+            result[pathOf(command).join(" ")] = structuredClone(contract.reference);
+    });
+    return result;
+};
+/** Preserve the factory signature while recording the definition before host composition can edit it. */
+export const sharedCommand = (factory) => (...args) => {
+    const first = args[0];
+    const before = new Set();
+    if (first instanceof Command)
+        visit(first, (command) => {
+            before.add(command);
+        });
+    const result = factory(...args);
+    const roots = [];
+    if (result instanceof Command)
+        roots.push(result);
+    else if (Array.isArray(result))
+        for (const item of result)
+            if (item instanceof Command)
+                roots.push(item);
+    if (first instanceof Command)
+        visit(first, (command) => {
+            if (!before.has(command) && command.parent && before.has(command.parent) && !roots.includes(command))
+                roots.push(command);
+        });
+    for (const shared of roots) {
+        visit(shared, (command) => {
+            const first = command.description().split("\n")[0] ?? "";
+            if (!command.summary() && first.length > 80)
+                command.summary(`${first.slice(0, 77).replace(/\s+\S*$/, "")}…`);
+        });
+        visit(shared, (command) => {
+            if (!command._hidden && !protectedCommands.has(command))
+                protectedCommands.set(command, {
+                    contract: snapshot(command),
+                    reference: snapshot(command),
+                    overrides: [],
+                    originalChildren: [...command.commands],
+                });
+        });
+        shared.hook("preAction", () => {
+            let root = shared;
+            while (root.parent)
+                root = root.parent;
+            assertSharedContracts(root);
+        });
+    }
+    return result;
+};
+/** Bind a provider shell only when its exact, reviewed differences still match Core. */
+export const customizeSharedCommand = (reference, reason, build, expectedOverrides) => {
+    if (reason.trim().length < 10)
+        throw new Error("a shared contract override needs a specific reason");
+    assertSharedContracts(reference);
+    if (!hasSharedContract(reference))
+        throw new Error("a provider shell needs a protected shared definition");
+    const command = build();
+    assertSharedContracts(command);
+    const pending = [];
+    const edits = [];
+    const bindingPath = (own) => {
+        const path = [own.name()];
+        for (let at = own.parent; at && own !== command; at = at.parent) {
+            path.unshift(at.name());
+            if (at === command)
+                break;
+        }
+        return path;
+    };
+    const adopt = (shared, own) => {
+        const inherited = protectedCommands.get(shared);
+        if (!inherited)
+            return;
+        if (!protectedCommands.has(own)) {
+            const originalChildren = own.commands.filter((child) => inherited.reference.children.includes(child.name()));
+            const actual = snapshot(own, originalChildren);
+            const overrides = differences(inherited.contract, actual).map((field) => ({
+                command: bindingPath(own),
+                field,
+                before: inherited.contract[field] ?? null,
+                after: actual[field] ?? null,
+                reason: reason.trim(),
+            }));
+            for (const edit of overrides)
+                edits.push(edit);
+            pending.push({
+                command: own,
+                record: {
+                    reference: structuredClone(inherited.reference),
+                    contract: actual,
+                    overrides: [...structuredClone(inherited.overrides), ...overrides],
+                    originalChildren,
+                },
+            });
+        }
+        for (const child of shared.commands) {
+            const actual = own.commands.find((one) => one.name() === child.name());
+            if (actual)
+                adopt(child, actual);
+        }
+    };
+    adopt(reference, command);
+    const ordered = (records) => [...records].sort((a, b) => JSON.stringify([a.command, a.field]).localeCompare(JSON.stringify([b.command, b.field])));
+    if (!Array.isArray(expectedOverrides) || !same(ordered(edits), ordered(expectedOverrides)))
+        throw new CliError("configuration_error", `provider shell ${command.name()} differs from its reviewed shared contract overrides; review Core and provider definitions before updating the explicit declarations`, { reason: "contract.unacknowledged-override", expected: expectedOverrides ?? null, actual: edits });
+    for (const { command: own, record } of pending) {
+        protectedCommands.set(own, record);
+        own.hook("preAction", () => {
+            let root = own;
+            while (root.parent)
+                root = root.parent;
+            assertSharedContracts(root);
+        });
+    }
+    assertSharedContracts(command);
+    return command;
+};

package/dist/commands/index.d.ts

@@ -6,7 +6,7 @@
  * a command came from, whether it changes anything, whether it is on its way out — is attached with
  * `annotate`, and to an option with `annotateOption`.
  *
- * Behind its own entry point for the same reason `/http` is: Commander is only a type here, and the
+ * Behind its own entry point for the same reason `/http` is: Commander is loaded by contract guards here, and the
  * root of this package stays free of any command-line framework.
  */
 import type { Command } from "commander";
@@ -20,3 +20,4 @@ export * from "./registry.js";
  * `prefix` keeps those caller-supplied words between the tool name and path in the hint.
  */
 export declare const refuseJoinedPath: (root: Command, args: readonly string[], prefix?: readonly string[]) => void;
+export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, type SharedContractOverride, sharedCommand, sharedContractOverrides, sharedContracts, } from "./contracts.js";

package/dist/commands/index.js

@@ -24,3 +24,4 @@ export const refuseJoinedPath = (root, args, prefix = []) => {
         command = next;
     }
 };
+export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, sharedCommand, sharedContractOverrides, sharedContracts, } from "./contracts.js";

package/dist/dev/audit.d.ts

@@ -3,12 +3,16 @@ import { type AuditRule, type ParityGroup, type RequiredRoot } from "../standard
 import { type ErrorReason } from "../standards/errors.js";
 import { type Override } from "../standards/lint.js";
 import type { Vocabulary } from "../standards/vocabulary.js";
+import { type Capabilities } from "./capabilities.js";
+import { type ContractEdit } from "./shared-contracts.js";
 export interface AuditInput {
     document: CommandsDocument;
     /** As the CLI printed it, for `key-casing`. */
     raw: unknown;
     schemas?: Readonly<Record<string, unknown>>;
     reasons?: readonly ErrorReason[];
+    contracts?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    overrides?: readonly ContractEdit[];
     /** The CLI's own `lint/` baseline and overrides; its lint rules are then judged by them, not the audit's. */
     lint?: {
         baseline: Readonly<Record<string, readonly string[]>>;
@@ -41,6 +45,7 @@ export interface AuditOptions {
     vocabulary: Vocabulary;
     /** `audit/baseline/<rule>.json`, by rule. */
     baseline: Readonly<Record<string, readonly string[]>>;
+    capabilities?: Capabilities;
     blocks: "new" | "never";
     /** Only new findings that name this CLI block: the one being released. */
     only?: string;

package/dist/dev/audit.js

@@ -1,7 +1,17 @@
 import { AUDIT_RULES } from "../standards/audit.js";
 import { BASE_REASONS } from "../standards/errors.js";
 import { LINT_RULES, OVERRIDE_BUDGET } from "../standards/lint.js";
+import { capabilityDifference } from "./capabilities.js";
 import { judge, kindOf, lintCommands, longName, summaryOf, walk } from "./lint.js";
+import { sharedContractProblems } from "./shared-contracts.js";
+const STRICT_CONTRACT_RULES = new Set([
+    "shared-command-contract",
+    "same-path-contract",
+    "same-flag-meaning",
+    "same-entity-schema",
+    "same-error-reason",
+    "required-root",
+]);
 const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 const toSnake = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 const VALUE_KEYS = new Set(["default", "implies"]);
@@ -66,8 +76,16 @@ const samePathContract = (inputs, groups) => {
                     message: describe(values),
                 });
         };
-        const kinds = new Map([...commands].map(([cli, command]) => [cli, optionKinds(command.options)]));
-        const flags = [...new Set([...kinds.values()].flatMap((one) => [...one.keys()]))].sort(byText);
+        const kinds = new Map([...commands].map(([cli, command]) => [
+            cli,
+            optionKinds([
+                ...(inputs.find((input) => input.document.cli === cli)?.document.global_options ?? []),
+                ...command.options,
+            ]),
+        ]));
+        const flags = [
+            ...new Set([...commands.values()].flatMap((command) => [...optionKinds(command.options).keys()])),
+        ].sort(byText);
         for (const flag of flags)
             push(` ${flag}`, new Map([...kinds].map(([cli, one]) => [cli, shownKind(one.get(flag))])));
         push(": output", new Map([...commands].map(([cli, command]) => [
@@ -166,6 +184,14 @@ const sameErrorReason = (inputs) => {
     return found;
 };
 const CROSS = {
+    "shared-command-contract": (inputs) => inputs.flatMap((input) => input.contracts
+        ? sharedContractProblems(snakeKeys(input.raw).commands, input.contracts, input.overrides).map((problem) => ({
+            rule: "shared-command-contract",
+            clis: [input.document.cli],
+            target: `${input.document.cli} ${problem.path}`,
+            message: problem.message,
+        }))
+        : []),
     "required-root": (inputs, options) => requiredRoots(inputs, options.roots),
     "same-path-contract": (inputs, options) => samePathContract(inputs, options.groups),
     "same-flag-meaning": (inputs) => sameFlagMeaning(inputs),
@@ -173,6 +199,7 @@ const CROSS = {
     "same-error-reason": (inputs) => sameErrorReason(inputs),
 };
 const measuredBy = {
+    "shared-command-contract": (input) => input.contracts !== undefined,
     "same-entity-schema": (input) => input.schemas !== undefined,
     "same-error-reason": (input) => input.reasons !== undefined,
 };
@@ -208,15 +235,44 @@ export const auditClis = (inputs, options, rules = AUDIT_RULES) => {
             return check(inputs, options);
         }),
     ];
+    const protectedInputs = new Set(inputs
+        .filter((input) => input.contracts &&
+        sharedContractProblems(snakeKeys(input.raw).commands, input.contracts, input.overrides)
+            .length === 0)
+        .map((input) => input.document.cli));
+    const inheritedAccepted = new Set(findings
+        .filter((finding) => {
+        if (finding.rule !== "same-path-contract" || finding.target.endsWith(": presence"))
+            return false;
+        const path = finding.target.slice(finding.target.indexOf(" ") + 1).split(/ --|: /)[0] ?? "";
+        return finding.clis.every((cli) => protectedInputs.has(cli) && inputs.find((input) => input.document.cli === cli)?.contracts?.[path]);
+    })
+        .map((finding) => `${finding.rule} ${finding.target}`));
+    const capabilityAccepted = new Set(findings
+        .filter((finding) => finding.rule === "same-path-contract" &&
+        options.capabilities &&
+        capabilityDifference(finding.target, finding.clis, inputs.map((input) => input.document), options.capabilities))
+        .map((finding) => `${finding.rule} ${finding.target}`));
     const declared = new Map(options.groups.flatMap((group) => group.differences.map((entry) => [`${entry.rule} ${entry.target}`, group.name])));
     const found = new Set(findings.map((finding) => `${finding.rule} ${finding.target}`));
     for (const [key, group] of declared)
         if (!found.has(key))
             problems.push(`stale difference in ${group}, no such divergence — remove it: ${key}`);
+    for (const group of options.groups) {
+        for (const difference of group.differences) {
+            const finding = findings.find((one) => one.rule === difference.rule && one.target === difference.target);
+            if (finding && difference.expected !== finding.message) {
+                declared.delete(`${difference.rule} ${difference.target}`);
+                problems.push(`difference in ${group.name} must match the exact current values: ${difference.rule} ${difference.target}`);
+            }
+        }
+    }
     for (const group of options.groups)
         if (group.differences.length > OVERRIDE_BUDGET)
             problems.push(`${group.name} declares ${group.differences.length} differences; the budget is ${OVERRIDE_BUDGET}`);
-    const baselined = new Set(Object.entries(options.baseline).flatMap(([rule, targets]) => targets.map((target) => `${rule} ${target}`)));
+    const baselined = new Set(Object.entries(options.baseline)
+        .filter(([rule]) => !STRICT_CONTRACT_RULES.has(rule))
+        .flatMap(([rule, targets]) => targets.map((target) => `${rule} ${target}`)));
     // A cross-CLI entry names every CLI it compared; a run without one of them can neither see it nor fix it.
     const judged = (target) => clisOf(target).every((cli) => clis.includes(cli));
     const ownLint = (cli, rule) => lintIds.includes(rule) ? inputs.find((input) => input.document.cli === cli)?.lint : undefined;
@@ -245,7 +301,9 @@ export const auditClis = (inputs, options, rules = AUDIT_RULES) => {
                 blocking.push(...mine.filter((finding) => row.new_targets.includes(finding.target)));
             }
             else {
-                const open = mine.filter((finding) => !declared.has(`${rule} ${finding.target}`));
+                const open = mine.filter((finding) => !declared.has(`${rule} ${finding.target}`) &&
+                    !capabilityAccepted.has(`${rule} ${finding.target}`) &&
+                    !inheritedAccepted.has(`${rule} ${finding.target}`));
                 const fresh = open.filter((finding) => !baselined.has(`${rule} ${finding.target}`));
                 const here = new Set(mine.map((finding) => finding.target));
                 row = {
@@ -272,10 +330,13 @@ export const auditClis = (inputs, options, rules = AUDIT_RULES) => {
     const nextBaseline = Object.fromEntries([...lintIds, ...rules.map((rule) => rule.id)].map((rule) => {
         const kept = (options.baseline[rule] ?? []).filter((target) => !judged(target));
         const now = findings
-            .filter((finding) => finding.rule === rule && !declared.has(`${rule} ${finding.target}`))
+            .filter((finding) => finding.rule === rule &&
+            !declared.has(`${rule} ${finding.target}`) &&
+            !capabilityAccepted.has(`${rule} ${finding.target}`) &&
+            !inheritedAccepted.has(`${rule} ${finding.target}`))
             .filter((finding) => !(lintIds.includes(rule) && selfJudged.has(finding.clis[0] ?? "")))
             .map((finding) => finding.target);
-        return [rule, [...new Set([...kept, ...now])].sort(byText)];
+        return [rule, STRICT_CONTRACT_RULES.has(rule) ? kept : [...new Set([...kept, ...now])].sort(byText)];
     }));
     const unique = new Map(blocking.map((finding) => [`${finding.rule} ${finding.target}`, finding]));
     return {

package/dist/dev/capabilities.d.ts

@@ -0,0 +1,20 @@
+import * as v from "valibot";
+import type { CommandsDocument } from "../commands/index.js";
+declare const manifestSchema: v.ObjectSchema<{
+    readonly clis: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly commands: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly in: v.UnionSchema<[v.LiteralSchema<"all", undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>;
+        readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly planned: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+        readonly options: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.LiteralSchema<"all", undefined>, v.ObjectSchema<{
+            readonly in: v.UnionSchema<[v.LiteralSchema<"all", undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>;
+            readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly planned: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+        }, undefined>], undefined>, undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type Capabilities = v.InferOutput<typeof manifestSchema>;
+export declare const readCapabilities: (input: unknown) => Capabilities;
+/** Presence differences are accepted only when every observed value matches a declared provider capability. */
+export declare const capabilityDifference: (target: string, clis: readonly string[], documents: readonly CommandsDocument[], manifest: Capabilities) => boolean;
+export {};

package/dist/dev/capabilities.js

@@ -0,0 +1,48 @@
+import * as v from "valibot";
+import { kindOf, longName, walk } from "./lint.js";
+const availability = v.union([v.literal("all"), v.array(v.string())]);
+const entry = v.object({
+    in: availability,
+    reason: v.optional(v.string()),
+    planned: v.optional(v.record(v.string(), v.string())),
+});
+const option = v.union([v.literal("all"), entry]);
+const manifestSchema = v.object({
+    clis: v.array(v.string()),
+    commands: v.record(v.string(), v.object({ ...entry.entries, options: v.optional(v.record(v.string(), option)) })),
+});
+export const readCapabilities = (input) => v.parse(manifestSchema, input);
+/** Presence differences are accepted only when every observed value matches a declared provider capability. */
+export const capabilityDifference = (target, clis, documents, manifest) => {
+    if (clis.some((cli) => !manifest.clis.includes(cli)))
+        return false;
+    const words = target.slice(target.indexOf(" ") + 1);
+    if (words.endsWith(": presence")) {
+        const path = words.slice(0, -10);
+        const ancestor = path
+            .split(" ")
+            .map((_, index, parts) => parts.slice(0, parts.length - index).join(" "))
+            .find((name) => manifest.commands[name] !== undefined);
+        const policy = ancestor ? manifest.commands[ancestor] : undefined;
+        if (!policy || policy.in === "all" || (!policy.reason && !policy.planned))
+            return false;
+        return clis.every((cli) => walk(documents.find((doc) => doc.cli === cli)?.commands ?? []).some((command) => command.path.join(" ") === path) === policy.in.includes(cli));
+    }
+    const flagAt = words.lastIndexOf(" --");
+    if (flagAt < 0)
+        return false;
+    const path = words.slice(0, flagAt), flag = words.slice(flagAt + 1);
+    const policy = manifest.commands[path]?.options?.[flag];
+    if (!policy || policy === "all" || policy.in === "all" || (!policy.reason && !policy.planned))
+        return false;
+    const signatures = new Set();
+    const matches = clis.every((cli) => {
+        const doc = documents.find((doc) => doc.cli === cli);
+        const command = walk(doc?.commands ?? []).find((command) => command.path.join(" ") === path);
+        const option = [...(doc?.global_options ?? []), ...(command?.options ?? [])].find((option) => longName(option.flags) === flag);
+        if (option)
+            signatures.add(kindOf(option));
+        return (option !== undefined) === policy.in.includes(cli);
+    });
+    return matches && signatures.size <= 1;
+};

package/dist/dev/lint.js

@@ -173,14 +173,16 @@ const filteredBy = (flag) => {
         return { window: "id" };
     return { field: bare.replace(/-(time|id|n)$/, "").replaceAll("-", "_") };
 };
-/** An entity's fields: the query's, then its registered schema's properties; `time` for a date-time. */
+/** A declared query is authoritative; without one, scalar schema fields reveal legacy list filters. */
 const entityFields = (command, context) => {
     const fields = new Map((command.query?.fields ?? []).map((field) => [field.name, field.type]));
-    const entity = command.output?.entity ?? command.query?.entity;
+    if (command.query)
+        return fields;
+    const entity = command.output?.entity;
     const schema = entity === undefined ? undefined : context.schemas?.[entity];
     const properties = isObject(schema) && isObject(schema.properties) ? schema.properties : {};
     for (const [name, property] of Object.entries(properties))
-        if (!fields.has(name))
+        if (!fields.has(name) && !typesOf(property).includes("array"))
             fields.set(name, isObject(property) && property.format === "date-time" ? "time" : "other");
     return fields;
 };
@@ -299,11 +301,22 @@ const CHECKS = {
     "filter-flag": (document, vocabulary, context) => {
         const roles = new Map(vocabulary.flags.map((flag) => [flag.name, flag.role]));
         return walk(document.commands)
-            .filter((command) => command.origin === "handwritten" && !declaredWrite(command) && (command.query || command.output))
+            .filter((command) => command.origin === "handwritten" &&
+            !declaredWrite(command) &&
+            (command.query || (["list", "events", "runs"].includes(command.name) && command.output)))
             .flatMap((command) => {
             const fields = entityFields(command, context);
             return command.options
-                .filter((option) => roles.get(longName(option.flags)) !== "scope")
+                .filter((option) => {
+                const flag = longName(option.flags), role = roles.get(flag);
+                if (role === "scope")
+                    return false;
+                const { field, window } = filteredBy(flag);
+                const queryField = command.query?.fields.some((one) => one.name === field);
+                return (window !== undefined ||
+                    queryField ||
+                    !["paging", "output", "sort", "mode", "budget", "action"].includes(role ?? ""));
+            })
                 .flatMap((option) => {
                 const { field, window } = filteredBy(longName(option.flags));
                 const hit = window === "time"