@ecoma-io/archkeep 0.22.2 → 0.23.0

package/package.json

@@ -1,22 +1,49 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.22.2",
-  "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
+  "version": "0.23.0",
+  "description": "Architecture authority for human and agentic software development — deterministic, evidence-backed enforcement of declared architecture.",
   "keywords": [
     "architecture",
-    "enforcement",
+    "software-architecture",
+    "architecture-governance",
+    "architecture-enforcement",
+    "architecture-as-code",
+    "architecture-drift",
+    "architecture-compliance",
+    "architecture-rules",
+    "dependency-analysis",
+    "dependency-governance",
     "dependency-graph",
-    "monorepo",
-    "module-boundaries",
-    "polyglot",
     "static-analysis",
-    "language-server",
-    "nx",
-    "nx-plugin",
-    "golang",
-    "rust",
-    "python",
-    "typescript"
+    "code-analysis",
+    "code-governance",
+    "architecture-fitness",
+    "fitness-functions",
+    "architecture-decision",
+    "architecture-decision-record",
+    "adr",
+    "architecture-evidence",
+    "evidence-based",
+    "deterministic-analysis",
+    "deterministic-verdicts",
+    "drift-detection",
+    "change-impact-analysis",
+    "architecture-debt",
+    "architecture-health",
+    "architecture-discovery",
+    "architecture-reconciliation",
+    "polyglot",
+    "monorepo",
+    "multi-repo",
+    "cross-repo",
+    "coding-agents",
+    "ai-agents",
+    "agentic-development",
+    "developer-tools",
+    "developer-experience",
+    "software-governance",
+    "engineering-governance",
+    "continuous-compliance"
   ],
   "type": "module",
   "license": "Apache-2.0",

package/src/analysis/jvm/packages.mjs

@@ -190,20 +190,3 @@ export function resolveJvmPackagePrefix(specifier, index) {
   }
   return null;
 }
-
-/**
- * The owning project of a resolved prefix, when exactly one project claims
- * the matched name.
- *
- * @param {{ owners: { project: string }[], prefix: string }} resolution
- * @returns {{ target: string, ambiguous?: undefined } |
- *            { target: null, ambiguous: true, projects: string[] }} A single
- *   target when the owners agree; otherwise every distinct claimant, for the
- *   caller's failure record.
- */
-export function projectOfResolution(resolution) {
-  const projects = [...new Set(resolution.owners.map((owner) => owner.project))];
-  return projects.length === 1
-    ? { target: projects[0] }
-    : { target: null, ambiguous: true, projects };
-}

package/src/analysis/manifest-util.mjs

@@ -67,8 +67,12 @@ export function resolveWithinWorkspace(baseDir, relative) {
   return segments.join("/");
 }
 
-/** A pattern carrying any of these is a glob; anything else is a literal. */
-const GLOB_METACHARACTERS = /[*?[{\\]/;
+/**
+ * A pattern carrying any of these is routed to the glob matcher; everything
+ * else compares equal. `(` rides for extglob — `+(x).txt` matches `x.txt`
+ * (measured on Node v24) — the character #671 proved the table was missing.
+ */
+const GLOB_METACHARACTERS = /[*?[{(\\]/;
 
 /**
  * Does a file's basename match any of a manifest-name pattern list — the
@@ -82,9 +86,14 @@ const GLOB_METACHARACTERS = /[*?[{\\]/;
  * the equality scan it replaced was nanoseconds, because each call compiles
  * its pattern again. The matcher is injected so `../../providers/native/
  * model.mjs`'s validated one and raw `path.posix.matchesGlob` ride the same
- * fast path without this module reaching for either; semantics are
- * unchanged, because a metacharacter-free pattern answers identically
- * either way and every other pattern still reaches the glob.
+ * fast path without this module reaching for either. The rule the table has
+ * to hold: every pattern carrying a character that can alter the glob's
+ * answer is routed to it, and everything else compares equal — a pattern
+ * the table does not carry is literal outside constructs the table already
+ * routes, so the two answers agree, and routing a literal anyway (an
+ * unbalanced `a(b`) costs only the matcher call. #671: `(` was missing
+ * from the table, so an extglob manifest pattern like `+(x).csproj` was
+ * compared by equality and missed every file the pattern named.
  *
  * @param {string} base The basename under test.
  * @param {readonly string[]} patterns

package/src/architecture-intent/judge.mjs

@@ -129,7 +129,7 @@ function directEdges(graph) {
  * three copies of the same filter is how one of them drifts.
  *
  * `../../src/rules/reachability.mjs`'s `buildReachability` itself stays
- * type-agnostic on purpose: `../../src/commands/edge-constraints.mjs`'s
+ * type-agnostic on purpose: `../rules/edge-constraints.mjs`'s
  * `declaredEdgeViolationsForCheck` and `../../src/rules/index.mjs`'s
  * `evaluate()` both deliberately hand it the UNFILTERED graph, because
  * `depConstraints`' `notDependOnLibsWithTags` is a different, tag-based

package/src/architecture-intent/model.mjs

@@ -43,6 +43,7 @@ import { resolve } from "node:path";
 import { containmentViolation } from "../containment.mjs";
 
 import { isValidSelector, splitSelector } from "./selectors.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "../governance/row-schema.mjs";
 
 /** The base name of the root file this module reads. */
@@ -121,17 +122,6 @@ const ROW_KEYS = Object.freeze(["from", "to", "reason", "optional", "decisionRef
 /** A boundary `name`, matched exactly by the loaders — names can never contain `:`, so a name can never collide with a `name:`-prefixed selector. */
 const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/u;
 
-/** A value's type, for an error message that shows what was actually there. */
-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)})`;
-}
-
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
 /** `key` on `obj` that is not one of `allowed` — for the reject-by-name rule. */
 function unknownKeys(obj, allowed) {
   return Object.keys(obj).filter((key) => !allowed.includes(key));

package/src/commands/README.md

@@ -377,10 +377,19 @@ the resolution order.
   `check` folds into the fitness exit lanes plus the finding catalogue SARIF's
   descriptors are built from; it prints nothing and decides no exit code.
 
-- **`edge-constraints.mjs`** — edge-constraint analysis shared by `diff` and
-  `impact`. Judges a single graph edge against the `depConstraints` table,
-  producing violations with their constraint rows. Checks only tag-based rules
-  (`onlyDependOnLibsWithTags`, `notDependOnLibsWithTags`,
-  `projectWithoutTagsCannotHaveDependencies`); npm/circular/lazy-load rules
-  need import-site details that graph edges do not carry. A consumer who needs
-  the complete verdict should run `check`.
+- **`impact-reachability.mjs`** — reverse reachability (`computeImpact`: a
+  project's direct and transitive dependents) shared by the `impact`,
+  `scenario` and `context --plan` commands and the canonical evaluator
+  (`./evaluation-primitives.mjs`). It lives apart from `./impact.mjs` rather
+  than inside it because that module drives `./impact-statement.mjs`, which
+  drives the evaluator — holding the walk in the command module is what made
+  `evaluation-primitives → impact → impact-statement → evaluation-primitives`
+  the engine's only import cycle (#644). `./impact.mjs` re-exports
+  `computeImpact`, so its existing importers keep resolving; new code imports
+  this module.
+
+The edge-constraint analysis `diff`, `impact` and `check` share is not one of
+these modules: it judges graph edges, so it lives in the rules layer whose
+constraint table and tag matching it reads (`../rules/edge-constraints.mjs`) —
+which is also what lets `../lsp/diagnose.mjs` share it without importing from
+this application layer (#649).

package/src/commands/change-intent.mjs

@@ -41,6 +41,8 @@
 
 import { readFile as readFileFromDisk } from "node:fs/promises";
 
+import { describe, isPlainObject } from "../values.mjs";
+
 /** The only `version` this module accepts. A different value is a load error. */
 export const CHANGE_INTENT_VERSION = "1";
 
@@ -108,17 +110,6 @@ export function edgePairKey({ from, to }) {
   return `${from}\u0000${to}`;
 }
 
-/** A value's type, for an error message that shows what was actually there. */
-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)})`;
-}
-
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
 /** `key` on `obj` that is not one of `allowed` — the reject-by-name rule. */
 function unknownKeys(obj, allowed) {
   return Object.keys(obj).filter((key) => !allowed.includes(key));

package/src/commands/check.mjs

@@ -23,11 +23,15 @@ import { stripTrailingSlashes } from "../path-util.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
-import { resolveCommandContext, unownedGapWithoutRunConfiguration } from "./context.mjs";
+import {
+  resolveCommandContext,
+  unownedGapWithoutRunConfiguration,
+  untrackedOwnedFiles,
+} from "./context.mjs";
 import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
-import { declaredEdgeViolationsForCheck } from "./edge-constraints.mjs";
+import { declaredEdgeViolationsForCheck } from "../rules/edge-constraints.mjs";
 import { customRulesForCheck, declaresCustomRules } from "./custom-rules.mjs";
 import { driftForCheck } from "./drift.mjs";
 import { fitnessForCheck } from "./fitness.mjs";
@@ -44,7 +48,7 @@ import { evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
 import { orphanedNotDependOnTags, unmatchedConstraintRows } from "../rules/tags.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
 import { verdictFor } from "../verdict.mjs";
-import { listTrackedFiles } from "../workspace.mjs";
+import { listTrackedFiles, listUntrackedFiles } from "../workspace.mjs";
 
 /**
  * A total order over violations, so a report's byte sequence is an invariant
@@ -184,10 +188,21 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  * readers: a test drives the real analysis, the real rules and the real
  * report over a fixture tree, and pins the exact `file:line:column` a
  * developer would act on, without an Nx installation or a git repository.
+ * `listUntracked` is the third git seam, the one the tracked universe is
+ * audited against (#675): it answers with the worktree files the universe
+ * left out (`../workspace.mjs`'s `listUntrackedFiles`). It is injected
+ * separately rather than derived from `listFiles` because the two are only
+ * paired when BOTH are git's — a caller that injected a tracked universe has
+ * already decided what the whole tree is, and asking git what else exists
+ * would answer a different tree than the one `listFiles` named. That is why
+ * the default below resolves the real listing only when `listFiles` is also
+ * the real one, and treats an injected universe as the whole story: its
+ * untracked complement is empty by construction, not by claim.
  *
  * @param {{format: string, config: string|null, paths: string[],
  *   evidenceOut?: string|null}} options
- * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} context
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function,
+ *   listUntracked?: Function}} context
  * @returns {Promise<{report: string, violations: number, declaredEdgeFindings: number,
  *   goWorkDrift: number, tsconfigPathsDead: number, intentFindings: number,
  *   intentUnresolved: number, intentUnresolvedDecisionRefs: number, fitnessFail: number,
@@ -195,7 +210,10 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  *   customRuleEvidence: {rule: string, bytes: Uint8Array}[], customRulesDeclared: boolean,
  *   analyzed: number, unchecked: number, blindSpots: number, waived?: number}>}
  */
-export async function check(options, { cwd, readGraph, listFiles = listTrackedFiles }) {
+export async function check(
+  options,
+  { cwd, readGraph, listFiles = listTrackedFiles, listUntracked },
+) {
   const commandContext = resolveCommandContext(
     { cwd, paths: options.paths },
     { readGraph, listFiles },
@@ -791,6 +809,45 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     ...(unconstrainedImportNote === null ? [] : [unconstrainedImportNote]),
   ];
 
+  // The tracked-universe boundary, audited (#675): every file a project owns,
+  // that an analyzer could judge, and that this run never read because git
+  // does not track it yet. The universe above is `listFiles(root)` —
+  // `git ls-files` verbatim — so a file that was never `git add`-ed never
+  // entered it, and before this audit a run over such a tree printed the same
+  // clean verdict as a run over the whole tree, byte for byte, with nothing
+  // anywhere naming what the universe had left out. `untrackedOwnedFiles`
+  // (`./context.mjs`) narrows the complement to the files whose absence can
+  // change what the verdict claims; the ownership and language tests are the
+  // two this module already runs over the tracked list, reused rather than
+  // re-derived.
+  //
+  // The verdict posture is the `unowned-files` bargain, and the completeness
+  // law decides it: the three no-verdict axes (`verdictFor`'s `unchecked`,
+  // `blindSpots`, `analyzed`) are all about files the universe CONTAINED —
+  // a whole-file failure, an unjudged site, a run that judged nothing —
+  // and the precedent for withholding (zero analysis, #619/#620/#634) is a
+  // verdict that was VACUOUS, not one that was scoped. This run judged every
+  // file its universe held, so the verdict over that universe stands — exit
+  // code and `coverage.complete` unchanged, exactly as the `coverageGaps`
+  // channel's contract states (`../../../../docs/reference/json-output.md`:
+  // "no kind changes `complete`, `status`, or the exit code") — but the clean
+  // verdict over a partial universe is now distinguishable from a clean
+  // verdict over the whole one, in both faces, with the full list a parser
+  // can act on. What is forbidden here is not exit 0; it is silence.
+  //
+  // Workspace-wide on purpose, the same posture `unownedGap` holds: a
+  // `check <path>` run must not be able to hide an unread file elsewhere in
+  // the tree by naming a path that excludes it. And resolved through the
+  // `listUntracked` seam's conditional default — an injected universe is the
+  // whole story (see this function's doc), so the audit asks git only when
+  // git also built the universe.
+  const untrackedListing =
+    listUntracked ?? (listFiles === listTrackedFiles ? listUntrackedFiles : null);
+  const untrackedOwned = untrackedOwnedFiles({
+    untracked: untrackedListing === null ? [] : untrackedListing(root),
+    projects: commandContext.workspace.projects,
+  });
+
   // A polyglot coverage gap: the Nx graph carries no polyglot edges because
   // the plugin is not registered, but polyglot manifests exist under project
   // roots. The checker still judged every import it found — this is not a
@@ -864,6 +921,13 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     ...(unsupportedLanguageFiles.length > 0
       ? [{ kind: "unsupported-language", files: [...unsupportedLanguageFiles].sort() }]
       : []),
+    // The universe audit above (#675): project-owned, analyzable files the
+    // worktree holds that this run never read, because the universe is the
+    // tracked set. Contributed only when the list is non-empty, so a tree
+    // with nothing beyond its index reports exactly the bytes it reported
+    // before; sorted already, by the one function that built it, so the row's
+    // bytes cannot vary with git's worktree-traversal order (E-F10).
+    ...(untrackedOwned.length > 0 ? [{ kind: "untracked-files", files: untrackedOwned }] : []),
   ];
 
   // One verdict computation for both faces: the JSON envelope spreads it and

package/src/commands/completeness.mjs

@@ -491,38 +491,6 @@ export function buildEvidenceComplete({
   };
 }
 
-/**
- * Asserts that the Evidence-Complete contract is satisfied.
- * Throws with a detailed message listing every failing gate.
- *
- * @param {EvidenceCompleteContract} ec The Evidence-Complete contract to verify.
- * @returns {void}
- * @throws {Error} When any gate fails.
- */
-export function assertEvidenceComplete(ec) {
-  if (ec.overallComplete) return;
-
-  const contractType = ec.contractType || EVALUATION_CONTRACT_TYPES.SCENARIO;
-  const failures = [];
-  for (const gate of EVIDENCE_COMPLETE_GATES) {
-    const g = ec.gates[gate.key];
-    // Skip non-required gates for this contract type
-    if (g.required === false) continue;
-    if (!g.pass) {
-      failures.push(`${gate.label}: ${JSON.stringify(g.value)} (expected pass)`);
-    }
-  }
-
-  if (failures.length === 0) return;
-
-  throw new Error(
-    `Evidence-Complete contract not satisfied.\n` +
-      `  Contract type: ${contractType}\n` +
-      `  Overall: ${ec.overallStatus}\n` +
-      `  Failed gates:\n    ${failures.join("\n    ")}`,
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Governance completeness
 // ---------------------------------------------------------------------------

package/src/commands/context-command.mjs

@@ -38,7 +38,7 @@ import {
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
-import { judgeEdge } from "./edge-constraints.mjs";
+import { judgeEdge } from "../rules/edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatContextReport } from "../report/context-text.mjs";

package/src/commands/context.mjs

@@ -35,7 +35,7 @@ import { jvmIndexFailures } from "../analysis/jvm/packages.mjs";
 import { languageOf } from "../analysis/registry.mjs";
 import { pythonUnmodelledFailures } from "../analysis/python.mjs";
 import { rustManifestFailures } from "../analysis/rust.mjs";
-import { dedupeWholeFileFailures, fileFailure } from "../analysis/source-util.mjs";
+import { dedupeWholeFileFailures, fileFailure, projectOwning } from "../analysis/source-util.mjs";
 import {
   DEFAULT_OPTIONS,
   NX_CONFIG_FILE,
@@ -54,6 +54,7 @@ import {
 } from "../providers/moon.mjs";
 import { nativeProvider } from "../providers/native/index.mjs";
 import { mergeDeclaredEdges } from "../providers/native/graph.mjs";
+import { requireSingleProjectModel } from "../providers/model-gate.mjs";
 import {
   resolveDeclaredManifestEdges,
   resolveDeclaredManifestFailures,
@@ -119,7 +120,8 @@ function readFileAbsolute(path) {
 
 /**
  * Which Moon directory marks `root` — or none. Presence facts only; see
- * `requireSingleProjectModel` below for the one-decision gate.
+ * `requireSingleProjectModel` (`../providers/model-gate.mjs`) for the
+ * one-decision gate.
  *
  * @param {string} root
  * @returns {{hasNx: boolean, hasNative: boolean, hasMoon: boolean}}
@@ -132,48 +134,6 @@ export function markersAt(root) {
   };
 }
 
-/**
- * The one gate deciding whether `root` may be judged at all: more than ONE
- * project-model marker present is refused, naming what conflicts.
- *
- * Every entry point that picks a provider must answer this identically —
- * `resolveCommandContext` below reads it before any command runs, and
- * `../lsp/workspace-index.mjs`'s index build reads it before choosing a
- * branch. A second copy of the condition was exactly how the faces drifted
- * apart once: the CLI refused a tree carrying a Moon directory beside
- * `nx.json`/`archkeep.json` while the editor indexed it anyway — a clean
- * diagnostic list over a tree nobody agreed could be judged (#223's silent
- * shape, one level up). Moon-versus-Moon coexistence (`.moon/` AND
- * `.config/moon/`) is refused inside `../providers/moon.mjs`'s
- * `moonMarkerAt`, which this gate calls first; the cross-family pairs are
- * refused here, all in the same terms: which model to judge against is a
- * decision nobody made, not one this tool can make for them.
- *
- * @param {string} root
- * @param {{exists?: (path: string) => boolean}} [io] Injectable existence
- *   test (absolute paths), so a test drives this without a filesystem.
- * @returns {{hasNx: boolean, hasNative: boolean, moonMarker: string|null}}
- *   The facts a provider choice needs; `moonMarker` names whichever Moon
- *   directory is present, `null` when neither spelling is.
- * @throws {Error} when more than one marker is present.
- */
-export function requireSingleProjectModel(root, { exists = existsSync } = {}) {
-  const moonMarker = moonMarkerAt(root, { exists });
-  const hasNx = exists(join(root, NX_CONFIG_FILE));
-  const hasNative = exists(join(root, ARCHKEEP_MODEL_FILE));
-  const refusal = (a, b) =>
-    new Error(
-      `archkeep: ${root} declares both ${a} and ${b} — this tool judges a workspace ` +
-        `against exactly one project model, and a tree carrying both is a decision nobody made ` +
-        `rather than one this tool can make for them. Remove whichever one is not the ` +
-        `workspace's real source of truth for projects and tags.`,
-    );
-  if (moonMarker !== null && hasNx) throw refusal(moonMarker, NX_CONFIG_FILE);
-  if (moonMarker !== null && hasNative) throw refusal(moonMarker, ARCHKEEP_MODEL_FILE);
-  if (hasNx && hasNative) throw refusal(NX_CONFIG_FILE, ARCHKEEP_MODEL_FILE);
-  return { hasNx, hasNative, moonMarker };
-}
-
 /**
  * Every marker a workspace root may be recognised by, as one list.
  *
@@ -191,7 +151,8 @@ export function requireSingleProjectModel(root, { exists = existsSync } = {}) {
  * selected the user's home directory as a workspace through `~/.moon`,
  * moonrepo's user-level state directory (#339). A bare `.moon` beside an
  * `nx.json` at a root already chosen is a different question, and stays with
- * `requireSingleProjectModel`'s directory-presence gate below.
+ * `requireSingleProjectModel`'s directory-presence gate
+ * (`../providers/model-gate.mjs`).
  *
  * @type {string[]}
  */
@@ -485,6 +446,43 @@ export function unownedGapWithoutRunConfiguration(gap, configNames) {
   };
 }
 
+/**
+ * The population a tracked-file universe silently leaves out (#675): files
+ * present in the worktree that git does not track, that a project owns, and
+ * that an analyzer could have judged — the exact complement of the universe
+ * `listTrackedFiles` cuts, narrowed to the files whose absence changes what a
+ * verdict can claim.
+ *
+ * Ownership is decided by `projectOwning` — the same predicate
+ * `createWorkspace` attributed the tracked list with, so a file cannot be
+ * "owned" here and unowned there — and the language test is the same one
+ * `unownedAnalyzableFiles` above applies: a file no analyzer claims (a
+ * README, a manifest, an image) could never have entered a verdict, so naming
+ * it would be a gap that fires on every work-in-progress tree and teaches a
+ * reader to skip the line it is written on. Both filters reuse existing
+ * answers; neither re-derives a judgment this module already owns.
+ *
+ * Sorted by plain string comparison, because the caller renders the list as
+ * report bytes: `git ls-files --others` answers in worktree-traversal order,
+ * and a row whose order varied with the order files happened to be created
+ * would break the byte-identity contract (`../../../../docs/reference/json-output.md`)
+ * for a tree that never changed.
+ *
+ * @param {{untracked: string[], projects: {name: string, root: string}[]}} args
+ *   `untracked` is `listUntrackedFiles`' answer (`../workspace.mjs`),
+ *   `projects` the workspace's `{name, root}` list — the same array
+ *   `createWorkspace` attributed the tracked files with.
+ * @returns {string[]} Sorted, deduplicated by construction (git lists a path
+ *   once), and empty exactly when the universe omitted nothing a verdict
+ *   could have reached.
+ */
+export function untrackedOwnedFiles({ untracked, projects }) {
+  const files = untracked.filter(
+    (file) => projectOwning(projects, file) !== null && languageOf(file) !== null,
+  );
+  return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /**
  * Resolves everything a command needs before it can ask its own question:
  * which workspace, which provider, which files, and what analyzing them
@@ -531,8 +529,9 @@ export function resolveCommandContext(
     );
   }
   // Which provider may judge at all — the one gate
-  // (`requireSingleProjectModel` above) every entry point shares, CLI and
-  // language server alike. Moon-versus-Moon rides it through `moonMarkerAt`.
+  // (`requireSingleProjectModel`, `../providers/model-gate.mjs`) every entry
+  // point shares, CLI and language server alike. Moon-versus-Moon rides it
+  // through `moonMarkerAt`.
   const { hasNative, moonMarker } = requireSingleProjectModel(root);
   const hasMoon = moonMarker !== null;
 

package/src/commands/diff.mjs

@@ -41,7 +41,7 @@
 import { readFileSync } from "node:fs";
 
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
-import { computeRuleImpact } from "./edge-constraints.mjs";
+import { computeRuleImpact } from "../rules/edge-constraints.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";

package/src/commands/discover.mjs

@@ -14,9 +14,13 @@
  * - **`--propose`** — computes the candidate architecture over those same
  *   observations (`src/governance/discovery-proposal.mjs`'s
  *   `evaluateDiscovery`) and emits it with `proposed: true` and
- *   `notAuthoritative: true` on every candidate. It never writes
- *   `architecture-intent.json`, never mutates the workspace, and never hands
- *   a candidate the authority of a decision.
+ *   `notAuthoritative: true` on every candidate. This layer performs no
+ *   write: the evaluator is pure, and the one route from a proposal to
+ *   `architecture-intent.json` is the CLI's own `--write-intent <file>` flag
+ *   (`cli.mjs`'s `runDiscover`, serialized through `proposalToIntent`
+ *   below) — explicit, named by the operator, and refused when a file
+ *   already stands at the target. The command never hands a candidate the
+ *   authority of a decision.
  *
  * ## The empty-result invariant
  *

package/src/commands/evaluation-primitives.mjs

@@ -25,8 +25,12 @@ import {
   computeDomainCoverage,
   REQUIRED_DOMAINS,
 } from "./completeness.mjs";
-import { computeImpact } from "./impact.mjs";
-import { computeImpactConstraints } from "./edge-constraints.mjs";
+// The reachability walk comes from `./impact-reachability.mjs`, not from
+// `./impact.mjs`: that module drives `./impact-statement.mjs`, which drives
+// this one, so importing the walk from there closed the engine's only import
+// cycle (#644).
+import { computeImpact } from "./impact-reachability.mjs";
+import { computeImpactConstraints } from "../rules/edge-constraints.mjs";
 // ---------------------------------------------------------------------------
 // Decision resolution
 // ---------------------------------------------------------------------------