@ecoma-io/archkeep 0.23.0 → 0.24.0

package/src/commands/check.mjs

@@ -12,6 +12,7 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
 
+import { foldMarkdownTrack } from "../analysis/markdown.mjs";
 import {
   blindSpotRows,
   fileFailure,
@@ -31,7 +32,7 @@ import {
 import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
-import { declaredEdgeViolationsForCheck } from "../rules/edge-constraints.mjs";
+import { declaredEdgeViolationsForCheck, judgeEdge } from "../rules/edge-constraints.mjs";
 import { customRulesForCheck, declaresCustomRules } from "./custom-rules.mjs";
 import { driftForCheck } from "./drift.mjs";
 import { fitnessForCheck } from "./fitness.mjs";
@@ -40,14 +41,16 @@ import { resolvePolicy } from "./policy.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { compareGoWork, parseGoWorkUse } from "../go-work.mjs";
+import { mergeDeclaredEdges } from "../providers/native/graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatSarif } from "../report/sarif.mjs";
 import { formatReport } from "../report/text.mjs";
 import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
-import { evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { applySuppressionTable, evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { buildReachability } from "../rules/reachability.mjs";
 import { orphanedNotDependOnTags, unmatchedConstraintRows } from "../rules/tags.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
-import { verdictFor } from "../verdict.mjs";
+import { coverageComplete, verdictFor } from "../verdict.mjs";
 import { listTrackedFiles, listUntrackedFiles } from "../workspace.mjs";
 
 /**
@@ -453,6 +456,41 @@ export async function check(
     }
   }
 
+  // The markdown document track, keyed by presence like every fold above it:
+  // a policy that declares no `markdown` block reaches nothing here and hears
+  // nothing anywhere — no edges, no failures, no envelope key — so a
+  // config-absent run is byte-identical to one this fold never existed for
+  // (`../../../../AGENTS.md`, "a change to what is reported on an unchanged
+  // workspace is a breaking change"). A policy that DOES declare one has its
+  // documents read (`../analysis/markdown.mjs`'s `foldMarkdownTrack`), the
+  // resolved pairings folded into the graph the way the declared manifest
+  // track's edges already are (`mergeDeclaredEdges`, the same dedup key), and
+  // every whole-file failure the read earned pushed into the same `failures`
+  // funnel the analysis uses — an unresolvable marker is an `unchecked` file,
+  // never a clean one.
+  //
+  // The fold runs BEFORE the walk below on purpose: a document pairing is a
+  // project-to-project dependency claim, and from here on this run's graph
+  // carries it exactly as it carries a csproj's `ProjectReference` — the tag
+  // rows, the circularity walk and the reachability behind them all read one
+  // graph, so a pairing cannot be legal here and violating in `context`.
+  // What it does not join is the twelve non-tag import-site rules: those need
+  // a specifier, a file and a resolution, and a document marker has none of
+  // them — it is judged as the EDGE it drew, the same 3-of-15 limit
+  // `declaredEdgeViolationsForCheck` documents for `implicit` edges.
+  let markdownTrack = null;
+  if (config !== null && config.markdown !== undefined) {
+    markdownTrack = foldMarkdownTrack({
+      tracked,
+      owned: commandContext.owned,
+      readFile: (file) => workspace.readFile(file),
+      workspace,
+      markdown: config.markdown,
+    });
+    mergeDeclaredEdges(graph, markdownTrack.edges);
+    failures.push(...markdownTrack.failures);
+  }
+
   // Both faces of one walk: the run's verdict, and the raw superset it was
   // picked from — every candidate up to each site's surviving group, including
   // the verdicts the suppression table removed to get there. `evaluate` alone
@@ -462,8 +500,66 @@ export async function check(
   // the gate's waiver-expiry judgement below and the engine's are the same
   // judgement, not two reads of the clock a boundary instant could split.
   const now = referenceTime();
-  const { violations: judged, rawViolations } = evaluateRun(imports, graph, { ...config, now });
-  const violations = sortViolations(judged);
+  const { violations: judged, rawViolations: judgedRaw } = evaluateRun(imports, graph, {
+    ...config,
+    now,
+  });
+
+  // The document pairings' own verdicts, judged by the machinery that already
+  // existed: `judgeEdge` — the same function `declaredEdgeViolationsForCheck`
+  // runs `implicit` edges through, so a doc pairing and a declared manifest
+  // edge can never disagree about the same boundary — over the graph the fold
+  // above already joined, with reachability built once for the whole claim
+  // list. The same empty-table exit `declaredEdgeViolationsForCheck` takes: a
+  // workspace declaring no `depConstraints` has opted out of tag enforcement
+  // entirely, and folding `projectWithoutTagsCannotHaveDependencies` onto
+  // every marker anyway would flag an opted-out workspace for a reason its
+  // import sites are never flagged for. Each verdict is then reshaped into the
+  // exact `Violation` record `violationOf` builds — position and specifier
+  // from the MARKER (the line a reader edits is the document's), project and
+  // constraint from the edge — so suppression, waiver annotation, sorting and
+  // the SARIF face all treat it as the ordinary violation it is.
+  /** @type {object[]} */
+  const markdownRaw = [];
+  if (config !== null && markdownTrack !== null && config.depConstraints.length > 0) {
+    const reachability = buildReachability(graph);
+    for (const claim of markdownTrack.claims) {
+      for (const verdict of judgeEdge(
+        { source: claim.source, target: claim.target },
+        graph.nodes,
+        graph.dependencies,
+        config.depConstraints,
+        reachability,
+      )) {
+        markdownRaw.push({
+          sourceFile: claim.file,
+          line: claim.line,
+          column: claim.column,
+          specifier: claim.name,
+          kind: claim.type,
+          messageId: verdict.messageId,
+          message: verdict.message,
+          sourceProject: verdict.source,
+          targetProject: verdict.target,
+          constraint: verdict.constraint,
+          data: verdict.data,
+        });
+      }
+    }
+  }
+  // The same table, the same behaviour: a suppression row whose glob covers a
+  // document removes that document's verdict (or waives it, with the same
+  // expiry evidence an import-site waiver carries), and the RAW records join
+  // `rawViolations` below so a row covering only document verdicts still
+  // counts as alive — a table that is doing its job must not read as dead
+  // because the violations it removes live in a different fold.
+  const markdownViolations =
+    config !== null && markdownTrack !== null
+      ? applySuppressionTable(config.suppressions, markdownRaw, now)
+      : [];
+
+  const rawViolations = [...judgedRaw, ...markdownRaw];
+  const violations = sortViolations([...judged, ...markdownViolations]);
   // An ACTIVE waiver keeps the violation it accepts in the findings list,
   // marked `waivedBy` — the run is still non-zero (waiving does not flip
   // exit 1 → 0), and this count is the additive "accepted violations" number
@@ -704,7 +800,10 @@ export async function check(
     config !== null &&
     options.paths.length === 0 &&
     failures.length === 0 &&
-    (config.suppressions.length > 0 || config.depConstraints.length > 0 || coverageRows.length > 0)
+    (config.suppressions.length > 0 ||
+      config.depConstraints.length > 0 ||
+      coverageRows.length > 0 ||
+      config.markdown !== undefined)
   ) {
     const deadRows = [];
     // The third dead table: a `coverage.unowned` row matching no unowned file
@@ -755,6 +854,34 @@ export async function check(
         );
       }
     }
+    // The document track's two dead tables, measured against what the fold
+    // actually selected (`markdownTrack.includeCounts`/`rowMatches` — the
+    // same counts the fold's own selection is built from, not a re-derivation
+    // that could disagree): an include glob matching no tracked document, and
+    // a marker row matching no line in any included document, both govern
+    // nothing while reading as enforced — every pairing the workspace meant
+    // to declare goes unjudged and the run stays green. A whole-file failure
+    // above already disabled this gate, so reaching here with a row that
+    // matched nothing means the tree genuinely has no such line.
+    if (markdownTrack !== null && config.markdown !== undefined) {
+      markdownTrack.includeCounts.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.include[${index}]: '${config.markdown.include[index]}' matches no tracked ` +
+            `document — the document track reads nothing, so every marker row below it governs ` +
+            `nothing while reading as enforced. Either the path was never right, or the ` +
+            `documents are not tracked`,
+        );
+      });
+      markdownTrack.rowMatches.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.markers[${index}]: the pattern matches no line in any included document — ` +
+            `this row extracts no pairing, so it enforces nothing while reading as enforced. ` +
+            `Either the documents do not carry the marker, or the pattern was never right`,
+        );
+      });
+    }
     if (deadRows.length > 0) {
       throw new Error(
         `archkeep: ${policySource ?? "the boundary config"} describes a workspace that does not ` +
@@ -977,8 +1104,14 @@ export async function check(
               // Complete means the run judged everything in scope: no
               // whole-file failure (unchecked), no unresolvable site (#595),
               // and at least one file analyzed (#599 — a run that judged
-              // nothing has no verdict to claim).
-              complete: unchecked === 0 && blindSpotCount === 0 && analyzed > 0,
+              // nothing has no verdict to claim). Read from the one predicate
+              // `verdictFor`'s decision face reads, so this field and the
+              // envelope's `decision.coverageComplete` are one derivation —
+              // the counts are this command's (the go.work/tsconfig failures
+              // pushed above and the accepted files withdrawn above make the
+              // universe wider than `commandContext.analysis`), the law is
+              // not.
+              complete: coverageComplete({ unchecked, blindSpotCount, analyzed }),
               projects: Object.keys(graph.nodes).length,
               analyzedFiles: analyzed,
               imports: imports.length,
@@ -1029,6 +1162,31 @@ export async function check(
                       judged: declaredEdges.judged,
                       findings: declaredEdges.findings,
                     },
+              // The document track is a policy DECLARATION, so it takes the
+              // same omitted-key-not-null discipline the intent/fitness/
+              // customRules blocks below state: a workspace whose policy
+              // declares no `markdown` block gets no key at all, and its
+              // envelope is byte-identical to the one it got before this
+              // section existed. The findings themselves are NOT restated
+              // here — they are members of `violations` above (sorted with,
+              // suppressible by, and counted into the verdict exactly like
+              // every import-site violation), so an array here would be one
+              // fact counted in two places; the block states what the track
+              // DID: how many documents the globs selected, how many markers
+              // they carried, where each resolution went.
+              ...(markdownTrack === null
+                ? {}
+                : {
+                    markdown: {
+                      checked: true,
+                      documents: markdownTrack.documents,
+                      judged: markdownTrack.judged,
+                      resolved: markdownTrack.resolved,
+                      ...(markdownTrack.selfPaired > 0
+                        ? { selfPaired: markdownTrack.selfPaired }
+                        : {}),
+                    },
+                  }),
               // Intent is a governance DECLARATION, absent when the workspace
               // chose not to make one: the key is omitted, never written as
               // null — the design contract `docs/reference/json-output.md` will

package/src/commands/context-command.mjs

@@ -32,16 +32,12 @@
  * than explaining constraints from a graph whose edges silently under-represent
  * the real architecture.
  */
-import {
-  blindSpotRows,
-  isWholeFileFailure,
-  unresolvableLiteralCount,
-} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.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";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
@@ -150,27 +146,23 @@ export function contextCommand(projectName, commandContext, config) {
     );
   }
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // The same completeness `check` claims (#595, #599): unjudged sites and
-  // a zero-analyzed run defeat it here exactly as they do there, so a
-  // context report cannot look complete over a tree the run could not
-  // fully read.
-  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
-  const complete =
-    notAnalyzed.length === 0 && blindSpotCount === 0 && commandContext.analysis.analyzed > 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The completeness verdict is the shared constructor's, not this file's —
+  // the same law `graph`/`discover` run (#595, #599): unjudged sites and a
+  // zero-analyzed run defeat it here exactly as they do there, so a context
+  // report cannot look complete over a tree the run could not fully read
+  // while the faces beside it refuse the same tree. The restatement this
+  // replaces carried all three axes, so composing it moves no byte on any
+  // input.
+  const verdict = coverageVerdict(commandContext);
+  const { complete, status, exitCode } = verdict;
 
   const coverage = {
     complete,
     projects: Object.keys(graph.nodes).length,
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
-    notAnalyzed,
-    blindSpots: blindSpotRows(commandContext.analysis.failures),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependency with no violations here may still violate npm-ban, circular-dependency, " +

package/src/commands/coverage-verdict.mjs

@@ -49,7 +49,7 @@ import {
   isWholeFileFailure,
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
-import { EXIT, coverageIncompleteReasons } from "../verdict.mjs";
+import { EXIT, coverageComplete, coverageIncompleteReasons } from "../verdict.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatCoverageIncomplete } from "../report/text.mjs";
@@ -96,7 +96,17 @@ export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
   const blindSpots = blindSpotRows(analysis.failures);
   const blindSpotCount = unresolvableLiteralCount(analysis.failures);
-  const complete = notAnalyzed.length === 0 && blindSpotCount === 0 && analysis.analyzed > 0;
+  // The conjunction is `../verdict.mjs`'s `coverageComplete` — the same
+  // predicate `verdictFor`'s decision face reads, so `check`'s envelope
+  // cannot carry a `coverage.complete` and a `decision.coverageComplete`
+  // that disagree about one run. The predicate is defined there, not here,
+  // because `verdictFor` needs it and this module already imports from that
+  // one: the reverse import would be a cycle.
+  const complete = coverageComplete({
+    unchecked: notAnalyzed.length,
+    blindSpotCount,
+    analyzed: analysis.analyzed,
+  });
   return {
     notAnalyzed,
     blindSpots,

package/src/commands/delta-snapshot.mjs

@@ -48,6 +48,7 @@
 import { readFileSync } from "node:fs";
 
 import { canonicalJsonReplacer } from "../canonical.mjs";
+import { isPlainObject } from "../values.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 
 /** The only snapshot schemaVersion this module writes and reads. */
@@ -518,11 +519,6 @@ export function providerMismatch(baselineProvider, currentProvider) {
   );
 }
 
-/** Non-empty plain-object guard used across validation. */
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 /** Describes a value for error messages without dumping it. */
 function describe(value) {
   if (value === null) return "null";

package/src/commands/explain.mjs

@@ -79,16 +79,13 @@
  * was: the field, and its rendered lines, exist only when the comparison was
  * requested.
  */
-import {
-  blindSpotRows,
-  isWholeFileFailure,
-  unresolvableLiteralCount,
-} from "../analysis/source-util.mjs";
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { evaluate } from "../rules/index.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { findProjectForPath, createProjectRootMappings } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { formatExplainReport } from "../report/explain-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
@@ -369,18 +366,18 @@ export function explainCommand(site, commandContext, config, options = {}) {
   // Normalize backslash separators (Windows paths) to forward slashes.
   parsed.sourceFile = sep === "\\" ? normalizedFile.replaceAll("\\", "/") : normalizedFile;
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // An unresolvable site was seen but never judged (#595): the graph is
-  // missing whatever edge that site would have drawn, and rules that judge
-  // the whole graph (circularity, lazy loading) would answer over a gap. The
-  // explanation still reports — status no-verdict — naming the site in
-  // `coverage.blindSpots`, the same contract `graph`/`discover` run.
-  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
-  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
-  const status = complete ? "ok" : "no-verdict";
+  // The completeness verdict is the shared constructor's, not this file's —
+  // the same contract `graph`/`discover` run: an unresolvable site was seen
+  // but never judged (#595), the graph is missing whatever edge it would have
+  // drawn, and rules that judge the whole graph (circularity, lazy loading)
+  // would answer over a gap. The explanation still reports — status
+  // no-verdict — naming the site in `coverage.blindSpots`. The restatement
+  // this replaces carried two of the constructor's three axes; the third
+  // (`analyzed > 0`, #599) moves no byte here, because every lane below that
+  // builds an envelope already implies a read file — an import record or a
+  // positioned failure exists only for a file the run analyzed — so the axis
+  // is carried by composition, not changed by it.
+  const { notAnalyzed, blindSpots, complete, status, exitCode } = coverageVerdict(commandContext);
 
   // Find the import record at this site.
   const record = findSite(parsed, commandContext.analysis.imports);
@@ -432,7 +429,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         analyzedFiles: commandContext.analysis.analyzed,
         imports: commandContext.analysis.imports.length,
         notAnalyzed,
-        blindSpots: blindSpotRows(commandContext.analysis.failures),
+        blindSpots,
         notes: [],
       };
 
@@ -447,7 +444,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         command: "explain",
         context,
         status,
-        exitCode: complete ? 0 : 3,
+        exitCode,
         coverage,
         result,
       });
@@ -579,7 +576,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
     notAnalyzed,
-    blindSpots: blindSpotRows(commandContext.analysis.failures),
+    blindSpots,
     notes: [],
   };
 

package/src/commands/graph.mjs

@@ -180,6 +180,13 @@ export function computePolicyFingerprint(config) {
     suppressions: config.suppressions ?? [],
     ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
     ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
+    // The document track is law the same way the two blocks above are: it
+    // decides what this run judges, so a policy that adds or edits a
+    // `markdown` block must not share a fingerprint with one that does not —
+    // `diff`'s policy-changed warning reads this hash. Conditional, like the
+    // two above, so a policy declaring no block hashes exactly as it did
+    // before this key existed.
+    ...(config.markdown === undefined ? {} : { markdown: config.markdown }),
   };
   // Canonicalise: sort object keys at every depth so insertion order does not
   // affect the hash. Semantic equality, not construction order, is the claim —

package/src/commands/health.mjs

@@ -112,10 +112,14 @@ export function healthCommand(commandContext, io = {}) {
   const edges = buildDependencies(graph.dependencies);
 
   // The run's coverage facts, the same shape every command's envelope carries.
+  // A run that analyzed nothing judged nothing (#599, #694): judging nothing
+  // is not finding nothing, so it defeats completeness the way a whole-file
+  // failure does.
   // An unresolvable site is a fact the run saw but never judged (#595) —
   // metrics measured over it would read precision the run does not have,
   // so it defeats file completeness the way a whole-file failure does.
   const fileComplete =
+    analysis.analyzed > 0 &&
     analysis.failures.filter(isWholeFileFailure).length === 0 &&
     unresolvableLiteralCount(analysis.failures) === 0;
   // The graph is complete only when the files are AND the graph actually sees

package/src/commands/plan-context-command.mjs

@@ -501,10 +501,14 @@ export async function planContextCommand(
         (a.messageId < b.messageId ? -1 : a.messageId > b.messageId ? 1 : 0),
     );
 
+  // A run that analyzed nothing judged nothing (#599, #694): judging nothing
+  // is not finding nothing, so it defeats completeness the way a whole-file
+  // failure does.
   // An unresolvable literal site is work the run saw but never judged
   // (#595, narrowed): a plan over it would present edges the run does not
   // hold, so it defeats completeness the way a whole-file failure does.
-  const complete = notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
+  const complete =
+    wholeTree.analyzed > 0 && notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 

package/src/commands/policy.mjs

@@ -86,10 +86,10 @@ export function hasProfiles(options) {
  * @param {string} cwd The process's working directory a relative `--config`
  *   resolves against — kept separate from the workspace root for the reason
  *   above.
- * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[]}|null, profile: string|null, source: string|null}>}
- *   `fitness` and `customRules` are present only when the resolved policy
- *   declares them — an absent key is the workspace's decision not to declare
- *   that law, never an empty one (`../config.mjs`'s `policyFrom`).
+ * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[]}|null, profile: string|null, source: string|null}>}
+ *   `fitness`, `customRules` and `markdown` are present only when the resolved
+ *   policy declares them — an absent key is the workspace's decision not to
+ *   declare that law, never an empty one (`../config.mjs`'s `policyFrom`).
  * @throws {Error} when a named profile, a `--config` file, or an inline
  *   policy cannot be resolved or is malformed — every arm's existing failure
  *   mode, unchanged by the extraction.

package/src/commands/provenance.mjs

@@ -114,8 +114,14 @@ export function resolveProvenance(root) {
 
   // Dirty: any uncommitted change to tracked files means the working tree
   // does not match the commit. A baseline from a dirty tree is not a
-  // reproducible claim about that commit.
-  const status = runProcess("git", ["status", "--porcelain"], root).trim();
+  // reproducible claim about that commit. `--untracked-files=no` is what
+  // makes the code agree with that sentence: bare `--porcelain` includes
+  // untracked paths, and an untracked file is not an uncommitted change to a
+  // tracked file — the analysis reads `git ls-files`-tracked files only, so a
+  // tree whose only dirt is an editor swap, a scratch file, or an unignored
+  // build output has an unchanged analyzed input and must produce an
+  // unchanged envelope (#683).
+  const status = runProcess("git", ["status", "--porcelain", "--untracked-files=no"], root).trim();
   const dirty = status.length > 0;
 
   return { commit, remote, dirty };