@ecoma-io/archkeep 0.22.2 → 0.23.0

package/src/report/evidence.mjs

@@ -1,170 +1,13 @@
 /**
- * The decision builder: turns a command's verdict counts into the `decision`
- * the envelope optionally carries, enforcing the five evidence invariants
- * (`../governance/verdict.mjs` states them) in code rather than leaving them
- * to a docs page a later command author might not read.
- *
- * This module decides nothing about whether a finding IS one — the command
- * that built the envelope owns that. What it decides is whether the verdict
- * and its evidence AGREE, and it throws when they do not, the same posture
- * `jsonEnvelope` takes for the three consistency rules it enforces: a
- * mismatch here is a bug in the command, not a fact about the workspace.
- *
- * The shape it produces:
- *
- *   {
- *     verdict: "pass" | "fail" | "unknown" | "not_applicable",
- *     reason?: string,                // always present for unknown
- *     notApplicableReason?: string,   // always present for not_applicable
- *     sampleTime?: string             // opt-in, never on a deterministic envelope
- *   }
- *
- * A caller may pass `reason` for `unknown` — it names WHICH could-not-look
- * condition fired (coverage incomplete, an unresolved intent boundary, a
- * thrown analysis). Without it, `buildDecision` states the generic one. The
- * reason field itself is always present on an `unknown` decision (I3).
- *
- * ## Determinism is the default
- *
- * The envelope this decision rides on is byte-deterministic
- * (`docs/reference/json-output.md`: no timestamp, no random identifier). So
- * `sampleTime` is OPT-IN by construction: a command passes it explicitly when
- * it is an age/count capability (waivers, debt, health — the features
- * `../governance/clock.mjs` serves), and a command whose verdict must stay
- * reproducible over an unchanged tree emits a decision with no time at all.
- * That is how the determinism↔time tension is resolved — the clock is
- * injectable (a test drives the same code with a fixed time), never asserted
- * from the wall clock.
- *
- * ## The invariants, executable
- *
- * I1. `pass` requires complete coverage. A run that could not fully read the
- *     tree can never pass — the same refusal `jsonEnvelope` makes for
- *     `status: "ok"` over incomplete coverage, at the verdict layer.
- * I2. `fail` requires at least one finding. A failing verdict that names no
- *     finding leaves the reader guessing what failed.
- * I3. `unknown` requires a reason. `unknown` is a claim that something could
- *     not be determined, and the reader has to be able to tell what.
- * I4. `not_applicable` requires `notApplicableReason`. "Did not apply" and
- *     "did not run" are indistinguishable without it.
- * I5. The cardinal rule: a failed analysis or an unresolved question must
- *     emit `unknown`, NEVER `pass` — enforced here by I1's first check
- *     (pass + not-complete throws) and by every caller choosing `unknown`
- *     wherever the run did not reach a verdict.
- *
- * `not_applicable` has no envelope status, so `buildDecision` reaches it only
- * through an explicit `verdict` — the route a Fitness or Waiver capability
- * (a later governance wave) takes. Engine behavior today never passes it:
- * `jsonEnvelope` refuses a `decision.verdict` that contradicts the envelope's
- * `status`, and no status maps to `not_applicable`, so the state is locked
- * out of every envelope this release builds.
+ * Re-export only. `buildDecision` lives in `../governance/verdict.mjs`,
+ * beside the four-state vocabulary it enforces (#650) — this file used to
+ * hold it, which made the core verdict module (`../verdict.mjs`) import the
+ * presentation layer, the one import direction the report layer must never
+ * own. The path stays for the render-side callers — `src/commands/*` build a
+ * decision while composing the payload they render — and importing the
+ * governance module directly is equivalent and welcome. What must never
+ * reappear here is a second implementation: `evidence.test.mjs` asserts the
+ * re-export by identity, so a copy that drifts from the vocabulary's
+ * enforcer fails loudly instead of silently disagreeing with it.
  */
-import { verdictForStatus } from "../governance/verdict.mjs";
-
-/**
- * Builds the `decision` a verdict's counts produce.
- *
- * @param {{
- *   verdict?: "pass"|"fail"|"unknown"|"not_applicable",
- *   status?: "ok"|"findings"|"no-verdict",
- *   coverageComplete: boolean,
- *   findings: number,
- *   reason?: string|null,
- *   notApplicableReason?: string|null,
- *   sampleTime?: string
- * }} run
- * @returns {{verdict: string, reason?: string, notApplicableReason?: string,
- *   sampleTime?: string}}
- * @throws {Error} on any invariant violation (I1–I4).
- */
-export function buildDecision(run) {
-  if (run.verdict === undefined && run.status === undefined) {
-    // No status, no explicit verdict — a builder called with neither is a
-    // programming error, not a fact about the workspace.
-    throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
-  }
-  const verdict = run.verdict ?? verdictForStatus(run.status);
-  if (
-    run.verdict !== undefined &&
-    run.status !== undefined &&
-    run.verdict !== verdictForStatus(run.status)
-  ) {
-    throw new Error(
-      `archkeep: refusing to build a decision where verdict "${run.verdict}" contradicts status ` +
-        `"${run.status}" — status implies ${verdictForStatus(run.status)}, and a decision that ` +
-        `disagrees with its own status would make one of the two a lie. ` +
-        `This is a bug in the command that built the decision.`,
-    );
-  }
-
-  // The `findings` count is the cardinal evidence number — a non-negative
-  // integer that the I1–I5 invariants all rely on. A missing, non-numeric, or
-  // negative value would silently falsify every comparison (`undefined > 0` is
-  // `false`), producing a clean verdict over a run whose counts were never set
-  // or are logically impossible — the exact silent direction this module exists
-  // to refuse.
-  if (typeof run.findings !== "number" || !Number.isFinite(run.findings) || run.findings < 0) {
-    throw new Error(
-      `archkeep: refusing to build a decision where findings is ${JSON.stringify(run.findings)} ` +
-        `— findings must be a non-negative number, or the verdict invariants cannot be enforced. ` +
-        `This is a bug in the command that built the decision.`,
-    );
-  }
-  if (verdict === "pass") {
-    if (run.coverageComplete !== true) {
-      throw new Error(
-        `archkeep: refusing to emit a "pass" decision over incomplete coverage ` +
-          `(coverage.complete: ${run.coverageComplete}) — a run that could not fully read the ` +
-          `tree can never pass. This is a bug in the command that built the decision.`,
-      );
-    }
-    if (run.findings > 0) {
-      throw new Error(
-        `archkeep: refusing to emit a "pass" decision with ${run.findings} finding(s) — ` +
-          `"pass" and "fail" cannot both be true of the same run. This is a bug in the command.`,
-      );
-    }
-    return withSampleTime({ verdict }, run.sampleTime);
-  }
-
-  if (verdict === "fail") {
-    if (run.findings < 1) {
-      throw new Error(
-        `archkeep: refusing to emit a "fail" decision with no findings — a failing verdict ` +
-          `must name what failed. This is a bug in the command that built the decision.`,
-      );
-    }
-    return withSampleTime({ verdict }, run.sampleTime);
-  }
-
-  if (verdict === "unknown") {
-    const reason =
-      run.reason ??
-      (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
-    return withSampleTime({ verdict, reason }, run.sampleTime);
-  }
-
-  // verdict === "not_applicable" (I4).
-  if (!run.notApplicableReason) {
-    throw new Error(
-      `archkeep: refusing to emit a "not_applicable" decision without notApplicableReason — ` +
-        `"did not apply" and "did not run" must never be indistinguishable. ` +
-        `This is a bug in the command that built the decision.`,
-    );
-  }
-  return withSampleTime({ verdict, notApplicableReason: run.notApplicableReason }, run.sampleTime);
-}
-
-/**
- * Adds `sampleTime` to the decision only when the caller opted into time —
- * the determinism rule in this module's header. Absent `sampleTime`, the
- * decision object carries exactly the invariant-bearing fields and nothing
- * more.
- *
- * @param {object} decision
- * @param {string|undefined} sampleTime
- * @returns {object}
- */
-function withSampleTime(decision, sampleTime) {
-  return sampleTime === undefined ? decision : { ...decision, sampleTime };
-}
+export { buildDecision } from "../governance/verdict.mjs";

package/src/report/json.mjs

@@ -37,6 +37,7 @@
  * does not opt in), which is what keeps SCHEMA_VERSION at 2: additive,
  * byte-compatible with every consumer that reads the envelope today.
  */
+import { EXIT_FOR_STATUS } from "../verdict.mjs";
 import { verdictForStatus } from "../governance/verdict.mjs";
 import { createRequire } from "node:module";
 
@@ -56,9 +57,6 @@ const { name: TOOL_NAME, version: TOOL_VERSION } = require("../../package.json")
  */
 export const SCHEMA_VERSION = 2;
 
-/** The one `status`↔`exitCode` mapping every command's envelope must agree with. */
-const EXIT_CODE_FOR_STATUS = Object.freeze({ ok: 0, findings: 1, "no-verdict": 3 });
-
 /**
  * Builds the envelope, asserting the three invariants that keep it from ever
  * claiming more than a run actually established.
@@ -86,10 +84,14 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
         `workspace being judged.`,
     );
   }
-  if (EXIT_CODE_FOR_STATUS[status] !== exitCode) {
+  // The `status`↔`exitCode` agreement reads `EXIT_FOR_STATUS` (`../verdict.mjs`)
+  // — the one status-keyed view of the process's exit-code table — so this
+  // assertion and `verdictFor`'s own encoding cannot become two independent
+  // copies of the same contract.
+  if (EXIT_FOR_STATUS[status] !== exitCode) {
     throw new Error(
       `archkeep: refusing to build a JSON envelope where status "${status}" and exitCode ${exitCode} ` +
-        `disagree — status "${status}" must carry exitCode ${EXIT_CODE_FOR_STATUS[status]}. A ` +
+        `disagree — status "${status}" must carry exitCode ${EXIT_FOR_STATUS[status]}. A ` +
         `consumer reading a file written by --output has only these two fields to trust; letting ` +
         `them disagree would make one of them a lie.`,
     );
@@ -149,8 +151,9 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
           `This is a bug in the command that built the envelope.`,
       );
     }
-    // I3, enforced again at this boundary — `src/governance/evidence.mjs`
-    // already guarantees it for the engine path, but a hand-built decision
+    // I3, enforced again at this boundary — `buildDecision`
+    // (`../governance/verdict.mjs`) already guarantees it for the engine
+    // path, but a hand-built decision
     // would otherwise ship an "unknown" without the reason I3 requires and
     // only this boundary would ever see the mistake. I2 (findings on "fail")
     // gets no latch here for the same reason I4 gets none: the other

package/src/report/sarif.mjs

@@ -421,7 +421,7 @@ export function sarifTsconfigPathsResult(finding) {
  * `messageId` is one of the same three `depConstraints` ids `sarifResult`
  * already catalogues (`onlyTagsConstraintViolation`,
  * `notTagsConstraintViolation`, `projectWithoutTagsCannotHaveDependencies`) —
- * `judgeEdge` (`../commands/edge-constraints.mjs`) reuses the identical
+ * `judgeEdge` (`../rules/edge-constraints.mjs`) reuses the identical
  * tag-matching functions `evaluate()`'s import-site path does, so the rule IS
  * the same rule and needs no second entry in `sarifRules()`; only the
  * `ruleIndex` lookup is shared, via `MESSAGE_IDS` rather than a second table.
@@ -440,7 +440,7 @@ export function sarifTsconfigPathsResult(finding) {
  * function learned the provider, which is a file a Moon tree is refused for
  * carrying at all.
  *
- * @param {object} finding A finding from `../commands/edge-constraints.mjs`'s
+ * @param {object} finding A finding from `../rules/edge-constraints.mjs`'s
  *   `declaredEdgeViolationsForCheck`, extended with `file` — workspace-relative.
  * @returns {object}
  */
@@ -705,6 +705,30 @@ export function sarifCoverageGapNotification(gap) {
       },
     };
   }
+  // Files a project owns that git does not track (#675) — present in the
+  // worktree, absent from the `git ls-files` universe this run was built
+  // from. Bounded the same way the two unowned arms above bound their own
+  // lists, and for the same reason: the count is the fact an uploader acts
+  // on, the paths its sample, and the remainder is named rather than dropped.
+  if (gap.kind === "untracked-files") {
+    const files = gap.files ?? [];
+    const shown = files.slice(0, UNOWNED_SAMPLE_LIMIT);
+    const remaining = files.length - shown.length;
+    const listed =
+      shown.length > 0
+        ? `: ${shown.join(", ")}${remaining > 0 ? `, and ${remaining} more` : ""}`
+        : "";
+    return {
+      level: "warning",
+      message: {
+        text:
+          `${files.length} project-owned file${files.length === 1 ? "" : "s"} ` +
+          `${files.length === 1 ? "is" : "are"} not tracked by git — never read by this run, ` +
+          `so no boundary verdict in this run covers ` +
+          `${files.length === 1 ? "it" : "them"}${listed}`,
+      },
+    };
+  }
   return {
     level: "warning",
     message: {
@@ -793,8 +817,9 @@ export function sarifDecisionRefNotification(decisionRef) {
  *   `check` exiting 3 on an intent it could not establish uploaded SARIF
  *   byte-identical to a clean run's.
  * - `coverageGaps` — coverage this run knows it did not provide: the polyglot
- *   edges nothing in the workspace covers, and the tracked analyzable files no
- *   project owns (`sarifCoverageGapNotification`).
+ *   edges nothing in the workspace covers, the tracked analyzable files no
+ *   project owns, and the project-owned files git does not track that this
+ *   run therefore never read (`sarifCoverageGapNotification`).
  * - `unresolvedDecisionRefs` — every citation no ADR, rule, or fitness record
  *   answers (`sarifDecisionRefNotification`), sorted, which is the order
  *   `../../cli.mjs`'s JSON envelope lists the same set in: two faces of one

package/src/report/text.mjs

@@ -630,6 +630,7 @@ function formatCoverageGap(gap) {
   if (gap.kind === "unregistered-plugin") return formatUnregisteredPluginGap(gap);
   if (gap.kind === "unowned-files") return formatUnownedFilesGap(gap);
   if (gap.kind === "accepted-unowned-files") return formatAcceptedUnownedFilesGap(gap);
+  if (gap.kind === "untracked-files") return formatUntrackedFilesGap(gap);
   return `⚠ coverage gap "${gap.kind}" — part of this workspace is outside what this run covered`;
 }
 
@@ -732,6 +733,44 @@ function formatAcceptedUnownedFilesGap(gap) {
   );
 }
 
+/**
+ * The untracked-files gap (#675): files a project owns that git does not
+ * track — present in the worktree, analyzable, and absent from the
+ * `git ls-files` universe this run was built from, so no analyzer ever read
+ * them. They are not failures and they change no exit code: the verdict over
+ * the tracked universe stands (`../../commands/check.mjs` states the whole
+ * argument beside the row's construction). What this section exists for is
+ * the difference between "checked, and clean" and "checked the tracked tree,
+ * and clean" — before this section existed those two printed the same bytes.
+ *
+ * The count leads and the paths follow, bounded by the same sample limit the
+ * two unowned gaps above print — the identical shape of list, so the
+ * identical bound (`UNOWNED_SAMPLE_LIMIT`, whose rule this face owns once).
+ *
+ * @param {{files?: string[]}} gap
+ * @returns {string}
+ */
+function formatUntrackedFilesGap(gap) {
+  // Read as defensively as its siblings: `./check.mjs` contributes this entry
+  // only when the list is non-empty, but `formatCoverageGaps` is exported and
+  // a heading with nothing under it reads as a truncation, not as "none".
+  const files = gap.files ?? [];
+  const count = files.length;
+  const shown = files.slice(0, UNOWNED_SAMPLE_LIMIT);
+  const remaining = count - shown.length;
+  const lines = shown.map((file) => `${CONTINUED}${file}`);
+  if (remaining > 0) {
+    lines.push(`${CONTINUED}… and ${remaining} more — the full list is in --format json`);
+  }
+  const them = count === 1 ? "it" : "them";
+  return (
+    `⚠ ${count} project-owned file${count === 1 ? "" : "s"} ${count === 1 ? "is" : "are"} ` +
+    `not tracked by git — never read by this run, so no boundary verdict here covers ${them}\n` +
+    `${lines.join("\n")}\n` +
+    `${DETAIL}git add ${them} so the next run reads ${them}, or let git ignore ${them}`
+  );
+}
+
 /**
  * The policy-identity line — which law this run enforced — rendered FIRST,
  * ahead of every verdict below it: a reader has to know WHICH law produced a

package/src/rules/README.md

@@ -36,15 +36,24 @@ weaker analyzer. That purity is what lets the CLI and the language server share
 one verdict, and what lets all fifteen rules be driven from fixtures with no
 workspace at all.
 
-| module             | what it owns                                                                                                            |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `index.mjs`        | the pipeline, in upstream's order; `allow`; the `Violation` record                                                      |
-| `tags.mjs`         | only / not / empty-only, and which constraints a source is held to                                                      |
-| `topology.mjs`     | circular, self-circular, apps, e2e, buildable, lazy, transitive                                                         |
-| `specifiers.mjs`   | relative-across, relative-externals, banned and nested-banned externals                                                 |
-| `messages.mjs`     | the fifteen message templates, copied verbatim from upstream                                                            |
-| `match.mjs`        | Nx's three pattern dialects (none of them minimatch), plus the brace-expansion cap in front of `path.posix.matchesGlob` |
-| `reachability.mjs` | who reaches whom: the cycle check and the transitive tag check share it                                                 |
+`edge-constraints.mjs` is this layer's second judgment surface, and deliberately
+not a rule: it judges GRAPH EDGES against the `depConstraints` table — the
+`implicit`-typed declarations `evaluate()` structurally cannot reach, because
+they have no import site behind them — reusing this directory's tag matching and
+reachability rather than re-deriving them. It reads records and nothing else,
+like everything here; `src/commands/` and `src/lsp/diagnose.mjs` both reach it
+as a downward import.
+
+| module                 | what it owns                                                                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `index.mjs`            | the pipeline, in upstream's order; `allow`; the `Violation` record                                                               |
+| `tags.mjs`             | only / not / empty-only, and which constraints a source is held to                                                               |
+| `topology.mjs`         | circular, self-circular, apps, e2e, buildable, lazy, transitive                                                                  |
+| `specifiers.mjs`       | relative-across, relative-externals, banned and nested-banned externals                                                          |
+| `messages.mjs`         | the fifteen message templates, copied verbatim from upstream                                                                     |
+| `match.mjs`            | Nx's three pattern dialects (none of them minimatch), plus the brace-expansion cap in front of `path.posix.matchesGlob`          |
+| `reachability.mjs`     | who reaches whom: the cycle check and the transitive tag check share it                                                          |
+| `edge-constraints.mjs` | graph-edge judgment: `judgeEdge` against the constraint table, the `implicit`-edge pass `check` shares, and the diff/impact fold |
 
 ## Read these before changing anything here
 

package/src/{commands → rules}/edge-constraints.mjs

@@ -2,12 +2,13 @@
  * Edge-constraint analysis: which boundary-rule violations an edge introduces
  * or removes, and which constraint rows govern a given edge.
  *
- * This is the bridge between the structural commands (`diff`, `impact`) and the
- * boundary rules. Both commands operate on graph edges — not on import sites —
- * so they cannot call `evaluate` directly. Instead, this module provides a
- * narrower function that judges a single edge against the `depConstraints`
- * table, which is the part of the boundary rules that depends only on project
- * tags (not on npm imports, circular dependencies, lazy loading, etc.).
+ * The rules layer's counterpart to `./index.mjs`'s import-site judgment:
+ * `evaluate` judges import sites, and the structural commands (`diff`,
+ * `impact`) operate on graph edges — not on import sites — so they cannot call
+ * `evaluate` directly. Instead, this module provides a narrower function that
+ * judges a single edge against the `depConstraints` table, which is the part
+ * of the boundary rules that depends only on project tags (not on npm imports,
+ * circular dependencies, lazy loading, etc.).
  *
  * `check` is a third caller, through `declaredEdgeViolationsForCheck` below —
  * not for every edge, only the ones `evaluate()` structurally cannot reach: an
@@ -16,7 +17,9 @@
  * `evaluate()` to iterate. Without this, `check` could report a clean tree
  * while `context`/`impact` showed the exact same edge as a tag violation — the
  * "empty result is a claim, not a shrug" invariant (`../../../AGENTS.md`)
- * broken by omission rather than by a wrong answer.
+ * broken by omission rather than by a wrong answer. The language server rides
+ * the same function (`../lsp/diagnose.mjs`), so an editor paints the same
+ * declared-edge verdict `check` exits 1 over.
  *
  * ## What it checks and what it does not
  *
@@ -34,23 +37,26 @@
  * edge with no import site cannot gain one by being judged from `check` rather
  * than `impact`. A consumer who needs the full verdict should run `check`.
  *
- * ## Why this lives here and not in `src/rules/`
+ * ## Why a separate module, and not part of `./tags.mjs` or `./index.mjs`
  *
  * `src/rules/` judges import sites; this module judges graph edges. They share
  * the tag-matching functions (`findConstraintsFor`, `onlyTagsViolation`,
  * `notTagsViolation`, `emptyOnlyTagsViolation`) but the input is different
- * enough that merging them would blur the layer boundary the AGENTS.md guards.
+ * enough that merging them would put two input contracts in one module — the
+ * boundary this file exists to keep legible. A sibling module in the same
+ * layer, reached by `commands/` and `lsp/` as a downward import, keeps the
+ * shared tag matching in one place without blurring the two judgments.
  */
 
 import { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
-import { renderMessage } from "../rules/messages.mjs";
-import { buildReachability } from "../rules/reachability.mjs";
+import { renderMessage } from "./messages.mjs";
+import { buildReachability } from "./reachability.mjs";
 import {
   emptyOnlyTagsViolation,
   findConstraintsFor,
   notTagsViolation,
   onlyTagsViolation,
-} from "../rules/tags.mjs";
+} from "./tags.mjs";
 
 /**
  * Judges a single edge against the `depConstraints` table.

package/src/values.mjs

@@ -0,0 +1,49 @@
+/**
+ * The value side of a refusal, shared by every layer that validates: the two
+ * shape guards a validator refuses with, and the describer that names the
+ * value a refusal is about.
+ *
+ * **They live at the floor of the package because every layer above needs
+ * them and none of them may reach up to get them.** The one pre-existing home
+ * for a shared guard was `./custom-rules/values.mjs`, but `custom-rules/`
+ * sits above its own dependencies — `./custom-rules/host.mjs` imports
+ * `./config.mjs` and `./governance/verdict.mjs` — so a validator in
+ * `src/config.mjs` or `src/governance/` importing the guard from there would
+ * point a foundational module up into a directory that depends back on it.
+ * The definitions are here instead, `custom-rules/values.mjs` re-exports the
+ * guard so its own importers keep their spelling, and the layer direction
+ * stays one-way.
+ *
+ * **Two describers deliberately live elsewhere**, and this module is not the
+ * place to finish the job:
+ *
+ * - `./commands/delta-classify.mjs` and `./commands/delta-snapshot.mjs`
+ *   render a refused primitive BARELY — `typeof` alone, no JSON dump —
+ *   because their refusals name shapes, not contents.
+ * - `./governance/clock.mjs` omits the array branch; its only call site
+ *   checks `typeof` before describing, so an array is never rendered.
+ *
+ * Each is pinned by its own test file, and converging any of them onto the
+ * rendering below would change the sentence an unchanged workspace is told —
+ * a semantic change, not a cleanup.
+ */
+
+/** @type {(value: unknown) => value is Record<string, any>} */
+export const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** @type {(value: unknown) => value is string[]} */
+export const isStringArray = (value) =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+/**
+ * A value's type, for an error message that shows what was actually there.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function describe(value) {
+  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
+  if (value === null) return "null";
+  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
+}

package/src/verdict.mjs

@@ -8,9 +8,15 @@
  * `../cli.mjs`'s `runCheck` takes the process's exit code from the same call.
  * `../cli.mjs` re-exports `EXIT` under its own name, so every importer that
  * already reads it from there keeps working.
+ *
+ * `EXIT` is the one place a status→exit-code number is written. The
+ * status-keyed view of it, `EXIT_FOR_STATUS`, is derived from `EXIT` and is
+ * what the envelope's consistency check (`./report/json.mjs`) asserts against,
+ * so a consumer-facing status and the process's own exit code can never drift
+ * into two encodings of one contract.
  */
 
-import { buildDecision } from "./report/evidence.mjs";
+import { buildDecision } from "./governance/verdict.mjs";
 
 export const EXIT = Object.freeze({
   ok: 0,
@@ -18,6 +24,20 @@ export const EXIT = Object.freeze({
   usage: 2,
   error: 3,
 });
+
+/**
+ * The envelope `status`→`exitCode` view of `EXIT` — the one mapping
+ * `jsonEnvelope` asserts every command's envelope against. Derived from
+ * `EXIT` rather than restated, so the numbers are written exactly once;
+ * `usage` has no status because a usage error never reaches an envelope.
+ *
+ * @type {Readonly<Record<"ok"|"findings"|"no-verdict", 0|1|3>>}
+ */
+export const EXIT_FOR_STATUS = Object.freeze({
+  ok: EXIT.ok,
+  findings: EXIT.violations,
+  "no-verdict": EXIT.error,
+});
 /**
  * The coverage clauses of a no-verdict reason, spelled once — the strings
  * `verdictFor` joins into `decision.reason` and `check`'s text report renders
@@ -57,7 +77,7 @@ export function coverageIncompleteReasons({ unchecked, blindSpots, analyzed }) {
  * "checked, and fine".
  *
  * The `decision` is the canonical 4-state verb of the same verdict
- * (`./report/evidence.mjs`), built from the same counts so the envelope's
+ * (`./governance/verdict.mjs`), built from the same counts so the envelope's
  * `status` and its `decision.verdict` cannot disagree: `ok`→`pass`,
  * `findings`→`fail`, `no-verdict`→`unknown`. `buildDecision` throws on any
  * invariant the counts violate (a `pass` over incomplete coverage, a `fail`
@@ -103,7 +123,7 @@ export function verdictFor({
   ) {
     return {
       status: "findings",
-      exitCode: EXIT.violations,
+      exitCode: EXIT_FOR_STATUS.findings,
       reasons: coverageReasons,
       decision: buildDecision({
         status: "findings",
@@ -164,7 +184,7 @@ export function verdictFor({
     ].filter(Boolean);
     return {
       status: "no-verdict",
-      exitCode: EXIT.error,
+      exitCode: EXIT_FOR_STATUS["no-verdict"],
       reasons,
       decision: buildDecision({
         status: "no-verdict",
@@ -176,7 +196,7 @@ export function verdictFor({
   }
   return {
     status: "ok",
-    exitCode: EXIT.ok,
+    exitCode: EXIT_FOR_STATUS.ok,
     reasons: [],
     decision: buildDecision({
       status: "ok",

package/src/workspace.mjs

@@ -177,6 +177,35 @@ export function listTrackedFiles(workspaceRoot, { run = runProcess } = {}) {
   return out.split("\0").filter((path) => path !== "");
 }
 
+/**
+ * Every file present in the worktree that git does NOT track, workspace-
+ * relative — the complement of `listTrackedFiles` above, and the answer to
+ * the only question that pair can ask: what exists in the tree the tracked
+ * universe was cut from, but never entered it (#675).
+ *
+ * `--exclude-standard` is what keeps this answer a git answer and not a walk
+ * of our own: ignored files — build outputs, dependency installs, anything a
+ * `.gitignore`, `.git/info/exclude` or `core.excludesFile` names — are not
+ * part of the workspace's population, exactly as for the tracked list. The
+ * header's argument for `git ls-files` over a tree walk applies here with one
+ * more clause: walking the tree for the untracked half would need those ignore
+ * rules reimplemented, and the copy would drift from `.gitignore` the first
+ * time a build directory was added.
+ *
+ * The order is git's worktree-traversal order, not a sorted order — every
+ * consumer of this list sorts before it renders (a file list in a report must
+ * not vary with git's traversal), the same discipline
+ * `../commands/check.mjs`'s `sortViolations` states for the tracked list.
+ *
+ * @param {string} workspaceRoot
+ * @param {{ run?: typeof runProcess }} [io]
+ * @returns {string[]}
+ */
+export function listUntrackedFiles(workspaceRoot, { run = runProcess } = {}) {
+  const out = run("git", ["ls-files", "--others", "--exclude-standard", "-z"], workspaceRoot);
+  return out.split("\0").filter((path) => path !== "");
+}
+
 /**
  * The `Workspace` the analysis contract defines — `{ root, projects, filesOf,
  * readFile, tsConfig }` — plus the per-project file index it is built from,