@nimiplatform/nimi-coding 0.4.0 → 0.5.0

package/cli/commands/authority.mjs

@@ -6,39 +6,36 @@ import {
   refuseAnchorsOutputBudget,
 } from "../lib/authority/anchors.mjs";
 import { auditAuthorityPath } from "../lib/authority/audit.mjs";
+import {
+  CHANGE_CANDIDATE_CHANNELS,
+  changeCandidatesAuthorityPaths,
+} from "../lib/authority/change-candidates.mjs";
 import { checkAuthorityPath, compileAuthorityPath } from "../lib/authority/compile.mjs";
 import { closedSetsAuthorityRepository } from "../lib/authority/closed-sets.mjs";
 import { consumersAuthorityRepository } from "../lib/authority/consumers.mjs";
 import { diffAuthorityPaths } from "../lib/authority/diff.mjs";
 import { discoverAuthorityPath } from "../lib/authority/discover.mjs";
-import { evidenceAuthorityRepository } from "../lib/authority/evidence.mjs";
 import { AuthorityInputError, formatAuthorityFile } from "../lib/authority/format.mjs";
 import { pathAuthorityPath, refsAuthorityPath, subgraphAuthorityPath } from "../lib/authority/graph.mjs";
 import { impactAuthorityPaths } from "../lib/authority/impact.mjs";
 import { contextAuthorityPath, queryAuthorityPath } from "../lib/authority/query.mjs";
 import { reviewAuthorityRepository } from "../lib/authority/review.mjs";
 import { authorityAuditResultToSarif } from "../lib/authority/sarif.mjs";
-import { loadAuthorityContract } from "../lib/authority/source-yaml.mjs";
 import { AUTHORING_SURFACE, AUTHORITY_SURFACE, integerFlagAdmission, booleanFlagAdmission } from "../lib/authority/surface.mjs";
 import { AUTHORITY_TERM_GRAMMAR_HELP, termsAuthorityRepository } from "../lib/authority/terms.mjs";
 
-const AUTHORITY_SOURCE_CONTRACT = await loadAuthorityContract();
-const ADMITTED_AUTHORITY_FORMATS = new Set([
-  AUTHORITY_SOURCE_CONTRACT.format,
-  AUTHORITY_SOURCE_CONTRACT.migration_inputs?.format,
-].filter((format) => typeof format === "string"));
-
 // The single source for the authority command list; the root help renders it
 // rather than keeping a second copy that drifts.
 export const AUTHORITY_COMMAND_USAGE = [
-  "nimicoding authority fmt <file> [--check] [--upgrade] [--json]",
-  "nimicoding authority check <path> [--scope-bindings <file>] [--require-format <format>] [--json]",
+  "nimicoding authority fmt <file> [--check] [--json]",
+  "nimicoding authority check <path> [--scope-bindings <file>] [--json]",
   "nimicoding authority compile <path> [--json]",
   "nimicoding authority anchors <repository-path> --spec <corpus-path> [--scope-bindings <file>] [--embedded-paths] --max-units <positive-safe-integer> --max-anchors <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority consumers <repository-path> --spec <corpus-path> [--external-root <scheme>=<path>]... --max-files <positive-safe-integer> --max-refs <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority closed-sets <repository-path> --spec <corpus-path> --max-units <positive-safe-integer> --max-sets <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority terms <repository-path> --spec <corpus-path> [--term <t>] [--code] --max-units <positive-safe-integer> --max-terms <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority discover <path> <query> [--kind <definition|rule>] [--owner <exact-owner>] [--scope <exact-scope>] [--lifecycle <active|removed>] --max-candidates <positive-safe-integer> --max-snippet-terms <positive-safe-integer> --max-bytes <positive-safe-integer> [--preview-direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --max-edges <positive-safe-integer>] [--json]",
+  "nimicoding authority change-candidates <before-path> <after-path> --channels <comma-separated-closed-set> --max-candidates <positive-safe-integer> --max-reasons <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority query <path> <id> --max-bytes <positive-integer> [--json]",
   "nimicoding authority context <path> <id> --max-units <positive-integer> --max-bytes <positive-integer> [--json]",
   "nimicoding authority refs <path> <id> --direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
@@ -46,9 +43,8 @@ export const AUTHORITY_COMMAND_USAGE = [
   "nimicoding authority subgraph <path> <id> --direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --depth <positive-safe-integer> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
   "nimicoding authority audit <path> --bindings <file> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json|--sarif]",
   "nimicoding authority diff <before-path> <after-path> --max-bytes <positive-integer> [--json]",
-  "nimicoding authority impact <before-path> <after-path> --dispositions <file> --max-bytes <positive-integer> [--json]",
-  "nimicoding authority review <repository-path> --base <git-ref> --bindings <file> --dispositions <file> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
-  "nimicoding authority evidence <repository-path> --bindings <tracked-.nimi/config-path> [--probe-results <.nimi/local-path>] --max-units <positive-safe-integer> --max-bindings <positive-safe-integer> --max-locators <positive-safe-integer> --max-edges <positive-safe-integer> --max-input-bytes <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
+  "nimicoding authority impact <before-path> <after-path> --max-bytes <positive-integer> [--json]",
+  "nimicoding authority review <repository-path> --base <git-ref> --bindings <file> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]",
 ];
 
 const USAGE = [
@@ -62,26 +58,27 @@ const USAGE = [
 const AUTHORITY_IDENTIFIER = /^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z](?:[a-z0-9-]*[a-z0-9])?)+$/;
 
 function parseOptions(subcommand, args) {
-  const options = { json: false, sarif: false, check: false, upgrade: false, embeddedPaths: false, code: false, path: null, repositoryPath: null, spec: null, term: null, requireFormat: null, base: null, id: null, fromId: null, toId: null, query: null, beforePath: null, afterPath: null, dispositions: null, bindings: null, scopeBindings: null, probeResults: null, kind: null, owner: null, scope: null, lifecycle: null, direction: null, previewDirection: null, traversal: null, relations: null, depth: null, maxHops: null, maxCandidates: null, maxSnippetTerms: null, maxUnits: null, maxTerms: null, maxSets: null, maxAnchors: null, maxFiles: null, maxRefs: null, maxBindings: null, maxLocators: null, maxEdges: null, maxInputBytes: null, maxBytes: null, externalRoots: [] };
+  const options = { json: false, sarif: false, check: false, embeddedPaths: false, code: false, path: null, repositoryPath: null, spec: null, term: null, base: null, id: null, fromId: null, toId: null, query: null, beforePath: null, afterPath: null, bindings: null, scopeBindings: null, kind: null, owner: null, scope: null, lifecycle: null, direction: null, previewDirection: null, traversal: null, relations: null, channels: null, depth: null, maxHops: null, maxCandidates: null, maxReasons: null, maxSnippetTerms: null, maxUnits: null, maxTerms: null, maxSets: null, maxAnchors: null, maxFiles: null, maxRefs: null, maxEdges: null, maxBytes: null, externalRoots: [] };
   const graphCommands = ["refs", "path", "subgraph"];
   const reportIntegerAdmission = integerFlagAdmission();
   const reportIntegerCommands = (flag) => reportIntegerAdmission[flag] ?? [];
+  const surfaceValueCommands = (flag) => Object.entries(AUTHORITY_SURFACE)
+    .filter(([, entry]) => entry.valueFlags.includes(flag))
+    .map(([command]) => command);
   const integerOptions = {
-    "--max-candidates": ["maxCandidates", ["discover"]],
+    "--max-candidates": ["maxCandidates", ["discover", "change-candidates"]],
+    "--max-reasons": ["maxReasons", ["change-candidates"]],
     "--max-snippet-terms": ["maxSnippetTerms", ["discover"]],
     // The report products' integer flags come from the enforced surface table,
     // so the parser and the product contracts cannot drift apart silently.
-    "--max-units": ["maxUnits", ["context", "audit", "review", "evidence", ...reportIntegerCommands("--max-units"), ...graphCommands]],
+    "--max-units": ["maxUnits", ["context", "review", ...reportIntegerCommands("--max-units"), ...graphCommands]],
     "--max-terms": ["maxTerms", reportIntegerCommands("--max-terms")],
     "--max-sets": ["maxSets", reportIntegerCommands("--max-sets")],
     "--max-anchors": ["maxAnchors", reportIntegerCommands("--max-anchors")],
     "--max-files": ["maxFiles", reportIntegerCommands("--max-files")],
     "--max-refs": ["maxRefs", reportIntegerCommands("--max-refs")],
-    "--max-bindings": ["maxBindings", ["evidence"]],
-    "--max-locators": ["maxLocators", ["evidence"]],
-    "--max-edges": ["maxEdges", ["audit", "review", "evidence", "discover", ...graphCommands]],
-    "--max-input-bytes": ["maxInputBytes", ["evidence"]],
-    "--max-bytes": ["maxBytes", ["discover", "query", "context", "audit", "diff", "impact", "review", "evidence", "anchors", "consumers", "terms", "closed-sets", ...graphCommands]],
+    "--max-edges": ["maxEdges", ["review", "discover", ...reportIntegerCommands("--max-edges"), ...graphCommands]],
+    "--max-bytes": ["maxBytes", ["discover", "change-candidates", "query", "context", "diff", "impact", "review", ...reportIntegerCommands("--max-bytes"), ...graphCommands]],
     "--max-hops": ["maxHops", ["path"]],
     "--depth": ["depth", ["subgraph"]],
   };
@@ -94,14 +91,13 @@ function parseOptions(subcommand, args) {
       continue;
     }
     if (!terminated && arg.startsWith("--")) {
-      if (arg === "--json" && !options.json) {
+      if (arg === "--json" && !options.json && (AUTHORITY_SURFACE[subcommand]?.booleanFlags ?? ["json"]).includes("json")) {
         if (options.sarif) return { ok: false, error: "authority audit requires --json and --sarif to be mutually exclusive" };
         options.json = true;
-      } else if (arg === "--sarif" && subcommand === "audit" && !options.sarif) {
+      } else if (arg === "--sarif" && AUTHORITY_SURFACE[subcommand]?.booleanFlags.includes("sarif") && !options.sarif) {
         if (options.json) return { ok: false, error: "authority audit requires --json and --sarif to be mutually exclusive" };
         options.sarif = true;
       } else if (arg === "--check" && AUTHORING_SURFACE[subcommand]?.booleanFlags.includes("check") && !options.check) options.check = true;
-      else if (arg === "--upgrade" && AUTHORING_SURFACE[subcommand]?.booleanFlags.includes("upgrade") && !options.upgrade) options.upgrade = true;
       else if (arg === "--embedded-paths" && booleanFlagAdmission("embedded-paths").includes(subcommand) && !options.embeddedPaths) options.embeddedPaths = true;
       else if (arg === "--code" && booleanFlagAdmission("code").includes(subcommand) && !options.code) options.code = true;
       else if (arg === "--external-root" && (AUTHORITY_SURFACE[subcommand]?.repeatableFlags ?? []).includes("external-root")) {
@@ -156,6 +152,18 @@ function parseOptions(subcommand, args) {
         if (!["directed", "incidence"].includes(value)) return { ok: false, error: "authority path requires --traversal directed or incidence" };
         options.traversal = value;
         index += 1;
+      } else if (arg === "--channels" && subcommand === "change-candidates" && options.channels === null) {
+        const value = args[index + 1];
+        const channels = value?.split(",") ?? [];
+        if (
+          channels.length === 0
+          || channels.some((entry) => entry.length === 0 || !CHANGE_CANDIDATE_CHANNELS.includes(entry))
+          || new Set(channels).size !== channels.length
+        ) {
+          return { ok: false, error: `authority change-candidates requires a non-empty unique closed --channels set containing only ${CHANGE_CANDIDATE_CHANNELS.join(", ")}` };
+        }
+        options.channels = channels;
+        index += 1;
       } else if (arg === "--relations" && [...graphCommands, "discover"].includes(subcommand) && options.relations === null) {
         const value = args[index + 1];
         const relations = value?.split(",") ?? [];
@@ -164,12 +172,7 @@ function parseOptions(subcommand, args) {
         }
         options.relations = relations.sort();
         index += 1;
-      } else if (arg === "--dispositions" && ["impact", "review"].includes(subcommand) && options.dispositions === null) {
-        const value = args[index + 1];
-        if (!value || value.startsWith("--")) return { ok: false, error: `authority ${subcommand} requires --dispositions followed by one file` };
-        options.dispositions = value;
-        index += 1;
-      } else if (arg === "--bindings" && ["audit", "review", "evidence"].includes(subcommand) && options.bindings === null) {
+      } else if (arg === "--bindings" && ["review", ...surfaceValueCommands("bindings")].includes(subcommand) && options.bindings === null) {
         const value = args[index + 1];
         if (!value || value.startsWith("--")) return { ok: false, error: `authority ${subcommand} requires --bindings followed by one file` };
         options.bindings = value;
@@ -179,13 +182,6 @@ function parseOptions(subcommand, args) {
         if (!value || value.startsWith("--")) return { ok: false, error: `authority ${subcommand} requires --scope-bindings followed by one file` };
         options.scopeBindings = value;
         index += 1;
-      } else if (arg === "--require-format" && subcommand === "check" && options.requireFormat === null) {
-        const value = args[index + 1];
-        if (!ADMITTED_AUTHORITY_FORMATS.has(value)) {
-          return { ok: false, error: `authority check requires --require-format followed by an admitted source format: ${[...ADMITTED_AUTHORITY_FORMATS].join(" or ")}` };
-        }
-        options.requireFormat = value;
-        index += 1;
       } else if (arg === "--spec" && ["anchors", "consumers", "terms", "closed-sets"].includes(subcommand) && options.spec === null) {
         const value = args[index + 1];
         if (!value || value.startsWith("--")) return { ok: false, error: `authority ${subcommand} requires --spec followed by one corpus path` };
@@ -196,11 +192,6 @@ function parseOptions(subcommand, args) {
         if (!value || value.startsWith("--") || /[\0\r\n]/u.test(value)) return { ok: false, error: "authority terms requires --term followed by one non-empty single-line term" };
         options.term = value;
         index += 1;
-      } else if (arg === "--probe-results" && subcommand === "evidence" && options.probeResults === null) {
-        const value = args[index + 1];
-        if (!value || value.startsWith("--")) return { ok: false, error: "authority evidence requires --probe-results followed by one repository-relative file" };
-        options.probeResults = value;
-        index += 1;
       } else if (arg === "--base" && subcommand === "review" && options.base === null) {
         const value = args[index + 1];
         if (!value || value.startsWith("-")) return { ok: false, error: "authority review requires --base followed by one non-option Git ref" };
@@ -211,17 +202,17 @@ function parseOptions(subcommand, args) {
     }
     positionals.push(arg);
   }
-  const expected = subcommand === "path" ? 3 : ["discover", "query", "context", "refs", "subgraph", "diff", "impact"].includes(subcommand) ? 2 : 1;
+  const expected = subcommand === "path" ? 3 : ["discover", "change-candidates", "query", "context", "refs", "subgraph", "diff", "impact"].includes(subcommand) ? 2 : 1;
   if (positionals.length !== expected) {
     const requirement = subcommand === "discover"
       ? "one path and one query"
-      : ["diff", "impact"].includes(subcommand)
+      : ["change-candidates", "diff", "impact"].includes(subcommand)
         ? "one before path and one after path"
-        : subcommand === "path" ? "one path, one exact from ID, and one exact to ID" : ["review", "evidence", "anchors", "consumers", "terms", "closed-sets"].includes(subcommand) ? "one repository path" : expected === 1 ? "one path" : "one path and one exact ID";
+        : subcommand === "path" ? "one path, one exact from ID, and one exact to ID" : ["review", "anchors", "consumers", "terms", "closed-sets"].includes(subcommand) ? "one repository path" : expected === 1 ? "one path" : "one path and one exact ID";
     return { ok: false, error: `authority ${subcommand} requires exactly ${requirement}` };
   }
-  if (["diff", "impact"].includes(subcommand)) [options.beforePath, options.afterPath] = positionals;
-  else if (["review", "evidence", "anchors", "consumers", "terms", "closed-sets"].includes(subcommand)) [options.repositoryPath] = positionals;
+  if (["change-candidates", "diff", "impact"].includes(subcommand)) [options.beforePath, options.afterPath] = positionals;
+  else if (["review", "anchors", "consumers", "terms", "closed-sets"].includes(subcommand)) [options.repositoryPath] = positionals;
   else if (subcommand === "path") [options.path, options.fromId, options.toId] = positionals;
   else [options.path, options.id] = positionals;
   if (subcommand === "discover") {
@@ -235,29 +226,24 @@ function parseOptions(subcommand, args) {
     const provided = previewOptions.filter((value) => value !== null).length;
     if (provided !== 0 && provided !== previewOptions.length) return { ok: false, error: "authority discover requires --preview-direction, --relations, and --max-edges together" };
   }
+  if (subcommand === "change-candidates" && options.channels === null) return { ok: false, error: "authority change-candidates requires --channels followed by a non-empty closed comma-separated set" };
+  if (subcommand === "change-candidates" && options.maxCandidates === null) return { ok: false, error: "authority change-candidates requires --max-candidates followed by a positive integer" };
+  if (subcommand === "change-candidates" && options.maxReasons === null) return { ok: false, error: "authority change-candidates requires --max-reasons followed by a positive integer" };
   if (["context", "anchors", "terms", "closed-sets", ...graphCommands].includes(subcommand) && options.maxUnits === null) return { ok: false, error: `authority ${subcommand} requires --max-units followed by a positive integer` };
   if (graphCommands.includes(subcommand) && options.maxEdges === null) return { ok: false, error: `authority ${subcommand} requires --max-edges followed by a positive integer` };
-  if (["discover", "query", "context", "audit", "diff", "impact", "review", "evidence", "anchors", "consumers", "terms", "closed-sets", ...graphCommands].includes(subcommand) && options.maxBytes === null) return { ok: false, error: `authority ${subcommand} requires --max-bytes followed by a positive integer` };
+  if (["discover", "change-candidates", "query", "context", "audit", "diff", "impact", "review", "anchors", "consumers", "terms", "closed-sets", ...graphCommands].includes(subcommand) && options.maxBytes === null) return { ok: false, error: `authority ${subcommand} requires --max-bytes followed by a positive integer` };
   if (["refs", "subgraph"].includes(subcommand) && options.direction === null) return { ok: false, error: `authority ${subcommand} requires --direction` };
   if (subcommand === "path" && options.traversal === null) return { ok: false, error: "authority path requires --traversal" };
   if (graphCommands.includes(subcommand) && options.relations === null) return { ok: false, error: `authority ${subcommand} requires --relations` };
   if (subcommand === "path" && options.maxHops === null) return { ok: false, error: "authority path requires --max-hops followed by a positive integer" };
   if (subcommand === "subgraph" && options.depth === null) return { ok: false, error: "authority subgraph requires --depth followed by a positive integer" };
-  if (subcommand === "impact" && options.dispositions === null) return { ok: false, error: "authority impact requires --dispositions followed by one file" };
   if (subcommand === "audit" && options.bindings === null) return { ok: false, error: "authority audit requires --bindings followed by one file" };
   if (subcommand === "audit" && options.maxUnits === null) return { ok: false, error: "authority audit requires --max-units followed by a positive integer" };
   if (subcommand === "audit" && options.maxEdges === null) return { ok: false, error: "authority audit requires --max-edges followed by a positive integer" };
   if (subcommand === "review" && options.base === null) return { ok: false, error: "authority review requires --base followed by one Git ref" };
   if (subcommand === "review" && options.bindings === null) return { ok: false, error: "authority review requires --bindings followed by one file" };
-  if (subcommand === "review" && options.dispositions === null) return { ok: false, error: "authority review requires --dispositions followed by one file" };
   if (subcommand === "review" && options.maxUnits === null) return { ok: false, error: "authority review requires --max-units followed by a positive integer" };
   if (subcommand === "review" && options.maxEdges === null) return { ok: false, error: "authority review requires --max-edges followed by a positive integer" };
-  if (subcommand === "evidence" && options.bindings === null) return { ok: false, error: "authority evidence requires --bindings followed by one repository-relative file" };
-  if (subcommand === "evidence" && options.maxUnits === null) return { ok: false, error: "authority evidence requires --max-units followed by a positive integer" };
-  if (subcommand === "evidence" && options.maxBindings === null) return { ok: false, error: "authority evidence requires --max-bindings followed by a positive integer" };
-  if (subcommand === "evidence" && options.maxLocators === null) return { ok: false, error: "authority evidence requires --max-locators followed by a positive integer" };
-  if (subcommand === "evidence" && options.maxEdges === null) return { ok: false, error: "authority evidence requires --max-edges followed by a positive integer" };
-  if (subcommand === "evidence" && options.maxInputBytes === null) return { ok: false, error: "authority evidence requires --max-input-bytes followed by a positive integer" };
   if (subcommand === "anchors" && options.spec === null) return { ok: false, error: "authority anchors requires --spec followed by one corpus path" };
   if (subcommand === "anchors" && options.maxAnchors === null) return { ok: false, error: "authority anchors requires --max-anchors followed by a positive integer" };
   if (subcommand === "consumers" && options.spec === null) return { ok: false, error: "authority consumers requires --spec followed by one corpus path" };
@@ -284,19 +270,17 @@ function humanAuditLocation(location) {
 function formatAuditHuman(report) {
   const audit = report.audit;
   const operationStatus = audit?.operationStatus ?? report.semantic_status;
-  const policyStatus = audit?.policyStatus ?? "indeterminate";
-  const complete = audit?.complete ?? false;
+  const blockingStatus = audit?.blockingStatus ?? "not_evaluated";
   const lines = [
-    `nimicoding authority audit: operation=${operationStatus}; policy=${policyStatus}; complete=${complete}`,
+    `nimicoding authority audit: operation=${operationStatus}; blocking=${blockingStatus}`,
     `files: ${report.summary.files}; units: ${report.summary.units}; diagnostics: ${report.summary.diagnostics}`,
     `audit bytes: ${report.audit_bytes}`,
   ];
   if (audit) {
-    lines.push(`bindings: required=${audit.counts.bindings.required}; configured=${audit.counts.bindings.configured}; evaluated=${audit.counts.bindings.evaluated}`);
-    lines.push(`returned: observations=${audit.counts.returned.observations}; findings=${audit.counts.returned.findings}; gaps=${audit.counts.returned.gaps}`);
+    lines.push(`bindings: configured=${audit.counts.bindings.configured}; evaluated=${audit.counts.bindings.evaluated}`);
+    lines.push(`returned: findings=${audit.counts.returned.findings}`);
     lines.push(`traversal: units=${audit.counts.traversal.units}; edges=${audit.counts.traversal.edges}`);
     for (const finding of audit.findings) lines.push(`finding ${finding.code} ${finding.fingerprint} at ${humanAuditLocation(finding.primaryLocation)}: ${finding.message}`);
-    for (const gap of audit.gaps) lines.push(`gap ${gap.code} ${gap.fingerprint} at ${humanAuditLocation(gap.primaryLocation)}: ${gap.message}`);
   } else lines.push("counts: unavailable (audit refused before evaluation)");
   for (const diagnostic of report.diagnostics) lines.push(humanDiagnostic(diagnostic));
   return `${lines.join("\n")}\n`;
@@ -310,6 +294,7 @@ function outputReport(report, json) {
     if (report.changed !== undefined) process.stdout.write(`changed: ${report.changed}\n`);
     if (report.packet_bytes !== undefined) process.stdout.write(`packet bytes: ${report.packet_bytes}\n`);
     if (report.discovery_bytes !== undefined) process.stdout.write(`discovery bytes: ${report.discovery_bytes}\n`);
+    if (report.candidate_bytes !== undefined) process.stdout.write(`change-candidate bytes: ${report.candidate_bytes}\n`);
     if (report.payload_bytes !== undefined) process.stdout.write(`semantic payload bytes: ${report.payload_bytes}\n`);
     if (report.graph_bytes !== undefined) process.stdout.write(`graph bytes: ${report.graph_bytes}\n`);
     if (report.packet) {
@@ -321,6 +306,12 @@ function outputReport(report, json) {
       process.stdout.write(`candidates: ${report.discovery.candidates.map((candidate) => candidate.id).join(", ")}\n`);
       if (report.discovery.relationPreview) process.stdout.write(`relation preview: units=${report.discovery.relationPreview.counts.units}; edges=${report.discovery.relationPreview.counts.edges}; complete=${report.discovery.relationPreview.complete}\n`);
     }
+    if (report.change_candidates) {
+      const product = report.change_candidates;
+      process.stdout.write(`requested channels: ${product.requestedChannels.join(", ")}\n`);
+      process.stdout.write(`changed roots: ${product.counts.changedRoots}; eligible survivors: ${product.counts.eligibleAfterUnits}; recalled candidates: ${product.counts.candidates}; reasons: ${product.counts.reasons}\n`);
+      process.stdout.write(`candidates: ${product.candidates.map((candidate) => candidate.id).join(", ")}\n`);
+    }
     if (report.diff) process.stdout.write(`semantic changes: ${report.diff.summary.changes}\n`);
     if (report.impact) process.stdout.write(`impacted units: ${report.impact.impactedUnits.map((unit) => unit.id).join(", ")}\n`);
     if (report.graph) {
@@ -348,19 +339,18 @@ function outputAuditReport(report, output) {
 function formatReviewHuman(report) {
   const review = report.review;
   const lines = [
-    `nimicoding authority review: operation=${review?.operationStatus ?? "refused"}; policy=${review?.policyStatus ?? "indeterminate"}; complete=${review?.complete ?? false}`,
+    `nimicoding authority review: operation=${review?.operationStatus ?? "refused"}; analysis-complete=${review?.analysisComplete ?? false}; configured-audit-blocking=${review?.audit?.blockingStatus ?? "not_evaluated"}`,
   ];
   if (review) {
     const base = review.snapshots.base;
     const worktree = review.snapshots.worktree;
-    const unresolved = review.impact.obligations.filter((obligation) => obligation.disposition === null).length;
     lines.push(`base: commit=${base.commitOid}; identity=${base.contentIdentity}; files=${base.counts.files}; units=${base.counts.units}`);
     lines.push(`worktree: identity=${worktree.contentIdentity}; files=${worktree.counts.files}; units=${worktree.counts.units}`);
-    lines.push(`semantic changes: ${review.diff.summary.changes}; impacted units: ${review.impact.impactedUnits.length}; unresolved obligations: ${unresolved}`);
-    lines.push(`current audit: policy=${review.audit.policyStatus}; findings=${review.audit.findings.length}; gaps=${review.audit.gaps.length}`);
+    lines.push(`semantic changes: ${review.diff.summary.changes}; impacted units: ${review.impact.impactedUnits.length}; declared obligations: ${review.impact.obligations.length}`);
+    lines.push(`current configured audit: blocking=${review.audit.blockingStatus}; findings=${review.audit.findings.length}`);
+    lines.push(`business semantics: ${review.businessSemanticStatus}; implementation conformance: ${review.implementationConformanceStatus}`);
     lines.push(`review bytes: ${report.review_bytes}`);
     for (const finding of review.audit.findings) lines.push(`finding ${finding.code} ${finding.fingerprint} at ${humanAuditLocation(finding.primaryLocation)}: ${finding.message}`);
-    for (const gap of review.audit.gaps) lines.push(`gap ${gap.code} ${gap.fingerprint} at ${humanAuditLocation(gap.primaryLocation)}: ${gap.message}`);
   } else {
     lines.push("review unavailable; partial=false");
   }
@@ -373,32 +363,6 @@ function outputReviewReport(report, json) {
   else process.stdout.write(formatReviewHuman(report));
 }
 
-function formatEvidenceHuman(report) {
-  const evidence = report.evidence;
-  const lines = [
-    `nimicoding authority evidence: operation=${evidence?.operationStatus ?? "refused"}; evidence=${evidence?.evidenceStatus ?? "indeterminate"}; complete=${evidence?.complete ?? false}; conformance=${evidence?.conformanceStatus ?? "not_evaluated"}`,
-  ];
-  if (evidence) {
-    lines.push(`snapshot: head=${evidence.identities.headCommitOid}; authority=${evidence.identities.authorityContentIdentity}; repository-input=${evidence.identities.repositoryInputIdentity}`);
-    lines.push(`bindings: required=${evidence.counts.bindings.required}; configured=${evidence.counts.bindings.configured}; evaluated=${evidence.counts.bindings.evaluated}`);
-    lines.push(`returned: observations=${evidence.counts.returned.observations}; findings=${evidence.counts.returned.findings}; gaps=${evidence.counts.returned.gaps}`);
-    lines.push(`evidence bytes: ${report.evidence_bytes}`);
-    for (const binding of evidence.bindings) {
-      lines.push(`binding ${binding.id}: required=${binding.required}; reachability=${binding.packageProbe.reachability}; execution=${binding.packageProbe.execution}; conformance=${binding.packageProbe.conformance}`);
-      if (binding.externalProbe) lines.push(`  external ${binding.externalProbe.id}@${binding.externalProbe.version}: ${binding.externalProbe.status}${binding.externalProbe.reportedOutcome ? `/${binding.externalProbe.reportedOutcome}` : ""}; package-attestation=false`);
-    }
-    for (const finding of evidence.findings) lines.push(`finding ${finding.code} ${finding.fingerprint} at ${humanAuditLocation(finding.primaryLocation)}: ${finding.message}`);
-    for (const gap of evidence.gaps) lines.push(`gap ${gap.code} ${gap.fingerprint} at ${humanAuditLocation(gap.primaryLocation)}: ${gap.message}`);
-  } else lines.push("evidence unavailable; partial=false");
-  for (const diagnostic of report.diagnostics) lines.push(humanDiagnostic(diagnostic));
-  return `${lines.join("\n")}\n`;
-}
-
-function outputEvidenceReport(report, json) {
-  if (json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  else process.stdout.write(formatEvidenceHuman(report));
-}
-
 function formatAnchorsReport(report, json) {
   if (json) return `${JSON.stringify(report, null, 2)}\n`;
   const lines = [
@@ -544,7 +508,7 @@ export async function runAuthority(args) {
     process.stdout.write(`${USAGE}\n`);
     return 0;
   }
-  if (!["fmt", "check", "compile", "anchors", "consumers", "terms", "closed-sets", "discover", "query", "context", "refs", "path", "subgraph", "audit", "diff", "impact", "review", "evidence"].includes(subcommand)) {
+  if (!["fmt", "check", "compile", "anchors", "consumers", "terms", "closed-sets", "discover", "change-candidates", "query", "context", "refs", "path", "subgraph", "audit", "diff", "impact", "review"].includes(subcommand)) {
     process.stderr.write(`nimicoding authority refused unknown subcommand: ${subcommand}\n${USAGE}\n`);
     return 2;
   }
@@ -555,15 +519,14 @@ export async function runAuthority(args) {
   }
   try {
     if (subcommand === "fmt") {
-      const result = await formatAuthorityFile(parsed.options.path, { check: parsed.options.check, upgrade: parsed.options.upgrade });
-      const report = makeReport("fmt", result, "not_evaluated", { changed: result.changed, check: parsed.options.check, upgrade: parsed.options.upgrade });
+      const result = await formatAuthorityFile(parsed.options.path, { check: parsed.options.check });
+      const report = makeReport("fmt", result, "not_evaluated", { changed: result.changed, check: parsed.options.check });
       outputReport(report, parsed.options.json);
       return result.ok ? 0 : 1;
     }
     if (subcommand === "check") {
       const result = await checkAuthorityPath(parsed.options.path, {
         scopeBindings: parsed.options.scopeBindings,
-        requireFormat: parsed.options.requireFormat,
       });
       const report = makeReport("check", result, result.ok ? "valid" : "invalid");
       outputReport(report, parsed.options.json);
@@ -592,6 +555,21 @@ export async function runAuthority(args) {
       outputReport(report, parsed.options.json);
       return result.ok ? 0 : 1;
     }
+    if (subcommand === "change-candidates") {
+      const result = await changeCandidatesAuthorityPaths(parsed.options.beforePath, parsed.options.afterPath, {
+        channels: parsed.options.channels,
+        maxCandidates: parsed.options.maxCandidates,
+        maxReasons: parsed.options.maxReasons,
+        maxBytes: parsed.options.maxBytes,
+      });
+      const report = makeReport("change-candidates", result, result.ok ? "completed" : "refused", {
+        candidate_bytes: result.candidateBytes,
+        change_candidates: result.changeCandidates,
+        partial: result.partial,
+      });
+      outputReport(report, parsed.options.json);
+      return result.ok ? 0 : 1;
+    }
     if (subcommand === "query") {
       const result = await queryAuthorityPath(parsed.options.path, parsed.options.id, { maxBytes: parsed.options.maxBytes });
       const report = makeReport("query", result, result.ok ? "valid" : "invalid", { packet_bytes: result.packetBytes, packet: result.packet });
@@ -635,17 +613,17 @@ export async function runAuthority(args) {
         });
         outputAuditReport(report, parsed.options.json ? "json" : "human");
       }
-      return result.audit?.operationStatus === "completed" && result.audit.policyStatus === "passed" ? 0 : 1;
+      return result.audit?.operationStatus === "completed" && result.audit.blockingStatus === "clear" ? 0 : 1;
     }
     if (subcommand === "diff") {
       const result = await diffAuthorityPaths(parsed.options.beforePath, parsed.options.afterPath, { maxBytes: parsed.options.maxBytes });
-      const report = makeReport("diff", result, result.ok ? "valid" : "invalid", { payload_bytes: result.payloadBytes, diff: result.diff });
+      const report = makeReport("diff", result, result.ok ? "valid" : "invalid", { payload_bytes: result.payloadBytes, diff: result.diff, partial: result.partial });
       outputReport(report, parsed.options.json);
       return result.ok ? 0 : 1;
     }
     if (subcommand === "impact") {
-      const result = await impactAuthorityPaths(parsed.options.beforePath, parsed.options.afterPath, parsed.options.dispositions, { maxBytes: parsed.options.maxBytes });
-      const report = makeReport("impact", result, result.ok ? "valid" : "invalid", { payload_bytes: result.payloadBytes, diff: result.diff, impact: result.impact });
+      const result = await impactAuthorityPaths(parsed.options.beforePath, parsed.options.afterPath, { maxBytes: parsed.options.maxBytes });
+      const report = makeReport("impact", result, result.ok ? "valid" : "invalid", { payload_bytes: result.payloadBytes, diff: result.diff, impact: result.impact, partial: result.partial });
       outputReport(report, parsed.options.json);
       return result.ok ? 0 : 1;
     }
@@ -803,33 +781,10 @@ export async function runAuthority(args) {
       outputClosedSetsReport(report, parsed.options.json);
       return result.ok ? 0 : 1;
     }
-    if (subcommand === "evidence") {
-      const result = await evidenceAuthorityRepository(
-        parsed.options.repositoryPath,
-        parsed.options.bindings,
-        parsed.options.probeResults,
-        {
-          maxUnits: parsed.options.maxUnits,
-          maxBindings: parsed.options.maxBindings,
-          maxLocators: parsed.options.maxLocators,
-          maxEdges: parsed.options.maxEdges,
-          maxInputBytes: parsed.options.maxInputBytes,
-          maxBytes: parsed.options.maxBytes,
-        },
-      );
-      const report = makeReport("evidence", result, result.evidence?.operationStatus ?? "refused", {
-        evidence_bytes: result.evidenceBytes,
-        evidence: result.evidence,
-        partial: result.partial,
-      });
-      outputEvidenceReport(report, parsed.options.json);
-      return result.evidence?.complete && result.evidence.evidenceStatus === "available" ? 0 : 1;
-    }
     const result = await reviewAuthorityRepository(
       parsed.options.repositoryPath,
       parsed.options.base,
       parsed.options.bindings,
-      parsed.options.dispositions,
       { maxUnits: parsed.options.maxUnits, maxEdges: parsed.options.maxEdges, maxBytes: parsed.options.maxBytes },
     );
     const report = makeReport("review", result, result.review?.operationStatus ?? "refused", {
@@ -838,7 +793,7 @@ export async function runAuthority(args) {
       partial: result.partial,
     });
     outputReviewReport(report, parsed.options.json);
-    return result.review?.complete && result.review.policyStatus === "passed" ? 0 : 1;
+    return result.review?.analysisComplete === true && result.review.audit.blockingStatus === "clear" ? 0 : 1;
   } catch (error) {
     const message = error instanceof AuthorityInputError ? error.message : `authority ${subcommand} could not evaluate input: ${error.message}`;
     process.stderr.write(`${message}\n`);

package/cli/constants.mjs

@@ -1,4 +1,4 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";
 export const PACKAGE_NAME = "@nimiplatform/nimi-coding";
 export const LOCAL_GITIGNORE_ENTRIES = [".nimi/local/"];
 export const AUTHORITY_GITATTRIBUTES_ENTRIES = [

package/cli/dev/check-authority-surface.mjs

@@ -12,12 +12,18 @@ import { fileURLToPath } from "node:url";
 
 import YAML from "yaml";
 
+import { AUTHORITY_COMMAND_USAGE } from "../commands/authority.mjs";
 import { PNPM_BUILTIN_SUBCOMMANDS } from "../lib/authority/anchors.mjs";
-import { AUTHORING_SURFACE, AUTHORITY_SURFACE, REPOSITORY_BOUND_COMMANDS } from "../lib/authority/surface.mjs";
+import {
+  AUTHORING_SURFACE,
+  AUTHORITY_SURFACE,
+  ENFORCED_AUTHORITY_COMMANDS,
+} from "../lib/authority/surface.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 const CONTRACT_FILES = {
+  audit: "spec/authority-audit.yaml",
   anchors: "spec/authority-anchors.yaml",
   consumers: "spec/authority-consumers.yaml",
   terms: "spec/authority-terms.yaml",
@@ -42,7 +48,7 @@ export function checkAuthoritySurface(root = packageRoot) {
   const failures = [];
   const contractIds = new Map();
 
-  for (const command of REPOSITORY_BOUND_COMMANDS) {
+  for (const command of ENFORCED_AUTHORITY_COMMANDS) {
     const relative = CONTRACT_FILES[command];
     if (relative === undefined) {
       failures.push(`command ${command} is in the enforced surface but has no product contract file`);
@@ -109,6 +115,13 @@ export function checkAuthoritySurface(root = packageRoot) {
         `${command} command line flags ${JSON.stringify(commandFlags)} != declared surface ${JSON.stringify(surfaceFlags)}`,
       );
     }
+    const usagePrefix = `nimicoding authority ${command} `;
+    const helpUsages = AUTHORITY_COMMAND_USAGE.filter((usage) => usage.startsWith(usagePrefix));
+    if (helpUsages.length !== 1 || helpUsages[0] !== contract.command) {
+      failures.push(
+        `${command} help usage ${JSON.stringify(helpUsages)} != contract command ${JSON.stringify(contract.command)}`,
+      );
+    }
   }
 
   // fmt and the source schema: the authoring contract has to describe the
@@ -135,10 +148,6 @@ export function checkAuthoritySurface(root = packageRoot) {
     if (authoring.fields?.format !== source.format) {
       failures.push(`authoring format ${authoring.fields?.format} != source schema format ${source.format}`);
     }
-    const authoringMigration = authoring.fields?.migration_inputs?.format;
-    if (authoringMigration !== source.migration_inputs?.format) {
-      failures.push(`migration input format: authoring ${authoringMigration} != source schema ${source.migration_inputs?.format}`);
-    }
     if (!sameSet(authoring.profiles?.yaml?.container_fields ?? [], source.yaml_document?.allowed_fields ?? [])) {
       failures.push(
         `container fields: authoring ${JSON.stringify(sorted(authoring.profiles?.yaml?.container_fields ?? []))} `
@@ -152,7 +161,7 @@ export function checkAuthoritySurface(root = packageRoot) {
 
   // The other direction: a contract that no enforced command claims.
   for (const [command, relative] of Object.entries(CONTRACT_FILES)) {
-    if (!REPOSITORY_BOUND_COMMANDS.includes(command)) {
+    if (!ENFORCED_AUTHORITY_COMMANDS.includes(command)) {
       failures.push(`${relative} declares command ${command}, which the enforced surface does not admit`);
     }
   }
@@ -168,6 +177,6 @@ if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith
   for (const failure of failures) process.stderr.write(`authority-surface: ${failure}\n`);
   if (failures.length > 0) process.exit(1);
   process.stdout.write(
-    `authority-surface: ${REPOSITORY_BOUND_COMMANDS.length} repository-bound commands match their product contracts\n`,
+    `authority-surface: ${ENFORCED_AUTHORITY_COMMANDS.length} public command surfaces match their product contracts\n`,
   );
 }

package/cli/dev/check-product-conformance.mjs

@@ -335,18 +335,6 @@ function createClassification(contracts) {
   return leaves;
 }
 
-function addAuthoringClassification(leaves, authoring) {
-  const values = authoring?.commands?.check?.require_format?.admitted_values;
-  if (!Array.isArray(values) || values.length === 0) throw new Error("authoring contract declares no admitted check formats");
-  values.forEach((value, index) => leaves.set(`authoring:commands.check.require_format.admitted_values[${index}]`, {
-    contract: "authoring",
-    path: `commands.check.require_format.admitted_values[${index}]`,
-    value,
-    status: "unmapped",
-    details: [],
-  }));
-}
-
 function classify(leaves, contract, leafPath, matches, detail) {
   const leaf = leaves.get(`${contract}:${leafPath}`);
   if (!leaf) throw new Error(`behavioural check names no classified leaf: ${contract}:${leafPath}`);
@@ -431,7 +419,7 @@ async function exerciseParserSurface(cliPath, fixture, contracts, leaves) {
   return validReports;
 }
 
-async function exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves) {
+async function exerciseRequiredCombinations(cliPath, fixture, contracts, leaves) {
   const codeWithoutTerm = await runCli(cliPath, fixture.root, [
     ...requiredArgs("terms", fixture).filter((entry) => entry !== "--json"),
     "--code", "--json",
@@ -442,20 +430,6 @@ async function exerciseRequiredCombinations(cliPath, fixture, contracts, authori
     classify(leaves, "terms", leafPath, refusedCode, `required --code/--term combination exited ${codeWithoutTerm.code}`);
   }
 
-  const admitted = authoring.commands.check.require_format.admitted_values;
-  const invalidFormat = await runCli(cliPath, fixture.root, [
-    "authority", "check", fixture.spec, "--require-format", "nimicoding.authority/invalid", "--json",
-  ]);
-  const formatRefusal = invalidFormat.code === 2
-    && invalidFormat.stdout === ""
-    && admitted.every((format) => invalidFormat.stderr.includes(format));
-  admitted.forEach((_, index) => classify(
-    leaves,
-    "authoring",
-    `commands.check.require_format.admitted_values[${index}]`,
-    formatRefusal,
-    `invalid --require-format exited ${invalidFormat.code} and named admitted formats`,
-  ));
 }
 
 async function independentFixtureOracle(fixture) {
@@ -479,7 +453,7 @@ async function independentFixtureOracle(fixture) {
     units: 3,
     files: 6,
     refs: 2,
-    terms: 2,
+    terms: 5,
     sets: 2,
     consumersInputBytes: nonCorpusBytes,
     termsInputBytes: authorityBytes + nonCorpusBytes,
@@ -682,7 +656,7 @@ async function exerciseCoreClosure(cliPath, fixture, contracts, leaves, validRep
     consumers: validReports.consumers.report?.summary?.filesScanned === 6
       && validReports.consumers.report?.summary?.references === 2,
     terms: validReports.terms.report?.summary?.units === 3
-      && validReports.terms.report?.summary?.distinctTerms === 2,
+      && validReports.terms.report?.summary?.distinctTerms === 5,
     "closed-sets": validReports["closed-sets"].report?.summary?.sets?.total === 2,
   };
   for (const command of Object.keys(contracts)) {
@@ -841,13 +815,11 @@ async function runConformanceLane({ contractDirectory, cliPath, lane }) {
   for (const [command, file] of Object.entries(PRODUCT_CONTRACTS)) {
     contracts[command] = YAML.parse(await readFile(path.join(contractDirectory, file), "utf8"));
   }
-  const authoring = YAML.parse(await readFile(path.join(contractDirectory, "authority-authoring.yaml"), "utf8"));
   const leaves = createClassification(contracts);
-  addAuthoringClassification(leaves, authoring);
   const fixture = await createRepositoryFixture();
   try {
     const validReports = await exerciseParserSurface(cliPath, fixture, contracts, leaves);
-    await exerciseRequiredCombinations(cliPath, fixture, contracts, authoring, leaves);
+    await exerciseRequiredCombinations(cliPath, fixture, contracts, leaves);
     await exerciseCompleteAndBudgets(cliPath, fixture, contracts, leaves, validReports);
     await exerciseGrammar(cliPath, fixture, leaves, validReports);
     await addAnchorFinding(fixture);