@ecoma-io/archkeep 0.23.0 → 0.24.1

package/src/commands/evaluation-primitives.mjs

@@ -195,7 +195,7 @@ export function buildDecisionImpact(root, constraintImpact, config) {
  *   not available.
  * @returns {{evaluated: boolean, findings: object[], count: number}}
  */
-export function evaluateFindingsImpact(affectedProjects, availableFindings) {
+function evaluateFindingsImpact(affectedProjects, availableFindings) {
   if (!availableFindings || availableFindings.length === 0) {
     return { evaluated: false, findings: [], count: 0 };
   }
@@ -221,7 +221,7 @@ export function evaluateFindingsImpact(affectedProjects, availableFindings) {
  *   entry's associated project.
  * @returns {{evaluated: boolean, debt: object[], count: number}}
  */
-export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
+function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
   if (!availableDebt || availableDebt.length === 0) {
     return { evaluated: false, debt: [], count: 0 };
   }
@@ -247,7 +247,7 @@ export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProje
  * @param {string} targetProject The target of the impact analysis.
  * @returns {{boundaries: object[], evaluated: boolean}}
  */
-export function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
+function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
   if (!constraintImpact || constraintImpact.length === 0) {
     return { boundaries: [], evaluated: false };
   }
@@ -339,7 +339,7 @@ export function decisionProvenanceCoverage(decisions) {
  * @param {object} evaluation.evolutionAlignment Evolution alignment.
  * @returns {object} Evidence gate values for buildEvidenceComplete.
  */
-export function deriveEvidenceGates(evaluation) {
+function deriveEvidenceGates(evaluation) {
   const { completeness, constraintImpact, decisionImpact } = evaluation;
 
   // domainCoverage: ratio of evaluated required domains

package/src/commands/evolution.mjs

@@ -138,6 +138,7 @@ function shortSha(sha) {
  *   and a shallow clone whose cut-off sits below the requested revision.
  */
 export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
+  // used by its own test
   if (typeof rev !== "string" || rev.length === 0) {
     throw new Error(`archkeep: ${flag} needs a revision — a commit, branch, tag, or HEAD~n.`);
   }
@@ -190,6 +191,7 @@ export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
  *   head's ancestry, or a merge commit inside the range.
  */
 export function selectLinearRange(root, { base, head }, { run = runProcess } = {}) {
+  // used by its own test
   const baseSha = resolveRevision(root, base, "--base", { run });
   const headSha = resolveRevision(root, head ?? "HEAD", "--head", { run });
 

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";
@@ -114,6 +111,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
  * @throws {UsageError} when the site string is malformed.
  */
 export function parseSite(site) {
+  // used by its own test
   const lastColon = site.lastIndexOf(":");
   if (lastColon === -1 || lastColon === 0) {
     throw new UsageError(
@@ -160,6 +158,7 @@ export function parseSite(site) {
  * @returns {object|null} The matching record, or `null`.
  */
 export function findSite(parsed, imports) {
+  // used by its own test
   return (
     imports.find(
       (site) =>
@@ -369,18 +368,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 +431,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 +446,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         command: "explain",
         context,
         status,
-        exitCode: complete ? 0 : 3,
+        exitCode,
         coverage,
         result,
       });
@@ -579,7 +578,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

@@ -151,24 +151,26 @@ export function buildDependencies(dependencies) {
  * config comparison logic.
  *
  * The fingerprint is SHA-256 of the canonicalized JSON for `depConstraints`,
- * `options`, `suppressions` and — when the policy declares them — `fitness`
- * and `customRules`. Those are every field of a loaded policy that states
- * law: the first three decide which violations `evaluate` produces, the
- * fourth decides which fitness functions `check` folds into the same exit
- * code (`../governance/fitness-registry.mjs`), and the fifth names the rule
+ * `options`, `suppressions` and — when the policy declares them — the
+ * `fitness`, `customRules`, `coverage` and `markdown` blocks, plus the
+ * selected profile's NAME when the law was selected by name. Those are every
+ * field of a loaded policy that states law: the first three decide which
+ * violations `evaluate` produces, the fourth decides which fitness functions
+ * `check` folds into the same exit code
+ * (`../governance/fitness-registry.mjs`), and the fifth names the rule
  * artifacts a workspace declared, each pinned to the bytes its `sha256` claims
  * (`../config.mjs`'s `customRuleRowViolations`) — swap one row's hash or its
- * `params` and the policy says something different. A field that can fail a
- * build and is not in the hash is a law that can be rewritten while `diff`
- * reports the policy unchanged — the silent direction, and the reason the list
- * here and `policyFrom`'s return shape (`../config.mjs`) are revisited
- * together.
+ * `params` and the policy says something different. The three after those are
+ * argued at their keys below. A field that can fail a build and is not in the
+ * hash is a law that can be rewritten while `diff` reports the policy
+ * unchanged — the silent direction, and the reason the list here and
+ * `policyFrom`'s return shape (`../config.mjs`) are revisited together.
  *
- * `fitness` and `customRules` are included only when they are DECLARED, and
- * the absent case contributes no key rather than an empty array. A policy that
- * declares neither therefore fingerprints exactly as it did before those
- * fields were covered, so extending the hash did not move every existing
- * snapshot's value — only those whose law it was failing to describe.
+ * The conditional fields are included only when they are DECLARED, and the
+ * absent case contributes no key rather than an empty array. A policy that
+ * declares none therefore fingerprints exactly as it did before those fields
+ * were covered, so extending the hash did not move every existing snapshot's
+ * value — only those whose law it was failing to describe.
  *
  * @param {object} config The loaded boundary config.
  * @returns {string} A hex-encoded SHA-256 fingerprint.
@@ -180,6 +182,33 @@ export function computePolicyFingerprint(config) {
     suppressions: config.suppressions ?? [],
     ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
     ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
+    // The acceptance channel is law the same way the blocks above are: a
+    // `coverage.unowned` row withdraws an unclaimed file's whole-file failure
+    // as a recorded acceptance (`../config.mjs`'s `findCoverageViolations`
+    // owns the shape, `../commands/coverage-acceptance.mjs` matches it), so a
+    // policy that records or removes an acceptance must not share a
+    // fingerprint with one that does not — `diff`'s policy-changed warning
+    // reads this hash (#709: the one block `policyFrom` sets that the hash
+    // skipped). Conditional, like the three above, so a policy recording no
+    // acceptance hashes exactly as it did before this key existed.
+    ...(config.coverage === undefined ? {} : { coverage: config.coverage }),
+    // The document track is law the same way the 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
+    // three above, so a policy declaring no block hashes exactly as it did
+    // before this key existed.
+    ...(config.markdown === undefined ? {} : { markdown: config.markdown }),
+    // The named selection is law identity the same way the blocks above are:
+    // `profilePolicy` (`../governance/profile-registry.mjs`) sets this key
+    // when the workspace selects a profile by name, and two profiles whose
+    // resolved blocks converge are still two different named laws. Only
+    // `check`'s report names the selection, so a hash blind to it would let a
+    // `delta` across a switch report the law unchanged with nothing anywhere
+    // saying it moved. Conditional, like the four above, so a policy
+    // selected by file or inline — no `profile` key at all — hashes exactly
+    // as it did before the selection was covered.
+    ...(config.profile === undefined ? {} : { profile: config.profile }),
   };
   // 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/history.mjs

@@ -229,6 +229,7 @@ export function readSnapshots(dir, root) {
  * @returns {string} First 8 hex characters.
  */
 export function shortId(id) {
+  // used by its own test
   return id.slice(0, 8);
 }
 
@@ -248,6 +249,7 @@ export function shortId(id) {
  * @returns {string} Zero-padded sequence, at least four digits.
  */
 export function nextSequence(read) {
+  // used by its own test
   let max = 0;
   for (const file of read.files) {
     const match = /^(\d+)-/.exec(file.name);

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

@@ -87,7 +87,7 @@ import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/a
 import { formatPlanContextReport } from "../report/plan-context-text.mjs";
 
 /** How many dependents are listed before an explicit overflow note. */
-export const DEPENDENT_CAP = 10;
+export const DEPENDENT_CAP = 10; // used by its own test
 
 /**
  * The projects a change touches: the target project, plus every project whose
@@ -100,6 +100,7 @@ export const DEPENDENT_CAP = 10;
  * @returns {string[]} Distinct affected project names, sorted.
  */
 export function collectAffectedProjects(commandContext, paths) {
+  // used by its own test
   const affected = new Set();
   for (const { file, project } of commandContext.owned ?? []) {
     for (const p of paths) {
@@ -124,6 +125,7 @@ export function collectAffectedProjects(commandContext, paths) {
  * @returns {object[]}
  */
 export function collectImpact(projectName, affected, graph) {
+  // used by its own test
   const targets = [...new Set([projectName, ...affected])].sort((a, b) =>
     a < b ? -1 : a > b ? 1 : 0,
   );
@@ -172,6 +174,7 @@ function scopedFiles(commandContext, affected) {
  * @returns {{goWork: object|null, tsconfigPaths: object|null, failures: object[]}}
  */
 export function collectDrift(commandContext) {
+  // used by its own test
   const { root, tracked, workspace } = commandContext;
   const failures = [];
 
@@ -501,10 +504,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

@@ -26,7 +26,7 @@ import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
  * @param {object} options The resolved options from `resolveCommandContext`.
  * @returns {boolean}
  */
-export function hasProfiles(options) {
+function hasProfiles(options) {
   return typeof options?.profiles === "string" && options.profiles !== "";
 }
 
@@ -86,10 +86,13 @@ 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[], profile?: 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`).
+ *   `profile` is present only when the law was selected by name, set by the
+ *   profiles arm (`../governance/profile-registry.mjs`'s `profilePolicy`) so
+ *   the selection the policy was resolved by travels with it.
  * @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 };

package/src/commands/scenario-evaluation.mjs

@@ -55,7 +55,7 @@ import {
 // ---------------------------------------------------------------------------
 
 /** The supported scenario change types. */
-export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]);
+export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]); // used by its own test
 
 // ---------------------------------------------------------------------------
 // Input schema types

package/src/commands/trajectory.mjs

@@ -107,7 +107,7 @@ const OBSERVATION_BASIS = "graph_snapshots";
  * constant in the envelope, so a consumer branches on a documented value
  * rather than on prose.
  */
-export const INSUFFICIENT_HISTORY = "insufficient_history";
+export const INSUFFICIENT_HISTORY = "insufficient_history"; // used by its own test
 
 /**
  * The derived-number block for one structural axis (projects keyed by name,
@@ -187,6 +187,7 @@ export const INSUFFICIENT_HISTORY = "insufficient_history";
  *   trends: TrajectoryTrends|null}}
  */
 export function computeTrajectory(files) {
+  // used by its own test
   const n = files.length;
   const available = n >= 2;
 

package/src/config.mjs

@@ -639,6 +639,155 @@ function findCoverageViolations(value) {
   return violations;
 }
 
+/**
+ * The one edge kind a markdown marker row can declare. The name is the claim
+ * the row makes about the graph: the captured symbol is resolved to the project
+ * that exports it, and the edge runs from the document's own project to that
+ * project. Kept as data rather than inlined at the check site so a second kind
+ * (`docs/reference/policy-schema.md`, "markdown") extends this list and nothing
+ * else — and so a row naming a kind this reader cannot draw is refused at load,
+ * where a law that would silently never run belongs.
+ *
+ * @type {Readonly<string[]>}
+ */
+const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
+
+/**
+ * One markdown marker row's problems, prefixed with its index.
+ *
+ * `pattern` is a regular-expression SOURCE matched against one line of a
+ * matched document at a time — never a glob, and never a whole-document
+ * match — because the position a violation reports must be a real
+ * `file:line:column` a developer can open. Its FIRST capture group must name
+ * the exported symbol the marker claims; a pattern with no capture group can
+ * match every line it is aimed at and still resolve nothing, which is a law
+ * that reads as enforced while testing nothing — refused here for the reason
+ * every dead shape in this file is refused.
+ *
+ * @param {object} row
+ * @param {number} index
+ * @returns {string[]}
+ */
+function markdownMarkerRowViolations(row, index) {
+  const at = `markdown.markers[${index}]`;
+  if (!isPlainObject(row)) return [`${at}: must be an object, got ${describe(row)}`];
+
+  const violations = [];
+  if (typeof row.pattern !== "string" || row.pattern === "") {
+    violations.push(
+      `${at}.pattern: must be a non-empty regular-expression source matched against one line of ` +
+        `a matched document, got ${describe(row.pattern)}`,
+    );
+  } else {
+    let compiled = null;
+    try {
+      compiled = new RegExp(row.pattern, "u");
+    } catch (cause) {
+      violations.push(
+        `${at}.pattern: '${row.pattern}' is not a valid regular expression under the 'u' flag ` +
+          `(${cause?.message ?? cause})`,
+      );
+    }
+    if (compiled !== null) {
+      // The capture count, read off the standard `pattern|` trick: matching the
+      // empty string yields one element per capture group plus the whole match,
+      // so a pattern that cannot capture anything reports `length === 1` here.
+      // Compiled in its own try, because the appended `|` can fail on a source
+      // the pattern alone accepted; the compile violation above is already
+      // reported in that case, and a second one would name the same row twice.
+      let captures;
+      try {
+        captures = (new RegExp(`${row.pattern}|`, "u").exec("")?.length ?? 1) - 1;
+      } catch {
+        captures = 1; // already refused above by the pattern's own compile check
+      }
+      if (captures < 1) {
+        violations.push(
+          `${at}.pattern: '${row.pattern}' has no capture group — the first capture group must ` +
+            `name the exported symbol the marker claims, and a pattern that captures nothing ` +
+            `resolves nothing while reading as enforced`,
+        );
+      }
+    }
+  }
+  if (!MARKDOWN_EDGE_KINDS.includes(row.edge)) {
+    violations.push(
+      `${at}.edge: ${describe(row.edge)} is not an edge kind this reader can draw — expected ` +
+        `${MARKDOWN_EDGE_KINDS.map((kind) => `"${kind}"`).join(", ")} (the captured symbol is ` +
+        `resolved to the project exporting it, and the edge runs there from the document's own ` +
+        `project)`,
+    );
+  }
+  for (const key of Object.keys(row)) {
+    if (key !== "pattern" && key !== "edge") {
+      violations.push(`${at}.${key}: not a markdown marker field — expected 'pattern' and 'edge'`);
+    }
+  }
+  return violations;
+}
+
+/**
+ * The markdown document track's problems, as messages; empty when it is
+ * well-formed. Pure, so a test drives it without a file on disk.
+ *
+ * `include` names the documents the track reads, by workspace-relative glob —
+ * the same glob machinery `boundarySuppressions` rows and `coverage.unowned`
+ * rows match with (`./rules/match.mjs`'s `safeMatchesGlob`), complexity-checked
+ * here at load for the reason a suppression's `path` is. An ABSOLUTE pattern is
+ * refused rather than left to match nothing forever: it can never match a
+ * workspace-relative document path, so declaring one is a law aimed outside
+ * the tree it governs (the family test is `ABSOLUTE_ARTIFACT_PATH`'s — the same
+ * "absolute in either path family" question, asked of a glob instead of a file).
+ *
+ * @param {unknown} value The parsed `markdown` value.
+ * @returns {string[]}
+ */
+function findMarkdownViolations(value) {
+  if (!isPlainObject(value)) {
+    return [`markdown: must be an object carrying 'include' and 'markers', got ${describe(value)}`];
+  }
+  const violations = [];
+  if (!Array.isArray(value.include) || value.include.length === 0) {
+    violations.push(
+      `markdown.include: must be a non-empty array of workspace-relative glob patterns naming ` +
+        `the documents the track reads, got ${describe(value.include)}`,
+    );
+  } else {
+    value.include.forEach((pattern, index) => {
+      const at = `markdown.include[${index}]`;
+      if (typeof pattern !== "string" || pattern === "") {
+        violations.push(
+          `${at}: must be a non-empty workspace-relative glob, got ${describe(pattern)}`,
+        );
+      } else if (ABSOLUTE_ARTIFACT_PATH.test(pattern)) {
+        violations.push(
+          `${at}: '${pattern}' is an absolute path — an include glob is matched against ` +
+            `workspace-relative document paths, so an absolute one can never match`,
+        );
+      } else {
+        const problem = globComplexityError(pattern);
+        if (problem) violations.push(`${at}: '${pattern}' ${problem}`);
+      }
+    });
+  }
+  if (!Array.isArray(value.markers) || value.markers.length === 0) {
+    violations.push(
+      `markdown.markers: must be a non-empty array of {pattern, edge} rows, got ` +
+        `${describe(value.markers)}`,
+    );
+  } else {
+    value.markers.forEach((row, index) =>
+      violations.push(...markdownMarkerRowViolations(row, index)),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "include" && key !== "markers") {
+      violations.push(`markdown.${key}: not a markdown field — expected 'include' and 'markers'`);
+    }
+  }
+  return violations;
+}
+
 /**
  * The grammar a custom rule's `name` is written in: lowercase letters and
  * digits, single `-` separators, nothing else.
@@ -945,6 +1094,7 @@ export function findBoundaryConfigViolations(module, io = {}) {
     fitness,
     customRules,
     coverage,
+    markdown,
   } = module;
   // F05: the resolution half of the governance block (`row-schema.mjs`'s
   // `io.resolve`) was validator-only until now — no production caller passed
@@ -1000,6 +1150,19 @@ export function findBoundaryConfigViolations(module, io = {}) {
     violations.push(...findCoverageViolations(coverage));
   }
 
+  // The markdown document track — the seventh top-level law, declared here and
+  // executed at graph level (`../analysis/markdown.mjs`): machine-readable
+  // markers inside tracked markdown documents, each resolved to an edge from
+  // the document's own project to the project that exports the named symbol.
+  // Absent means "no document track" — the workspace decision this key exists
+  // to state, and the state every config-absent run must stay byte-identical
+  // to. Present and malformed is refused here, loudly, for the reason the two
+  // blocks above state: a row this reader cannot understand is a document law
+  // that would not run while the policy still says it does.
+  if (markdown !== undefined) {
+    violations.push(...findMarkdownViolations(markdown));
+  }
+
   // Absent means "nothing is suppressed", which is the only default that fails
   // toward reporting — unlike the eight options above, where a missing value
   // would be a second copy of something ESLint also reads and this module has
@@ -1095,7 +1258,10 @@ export function findBoundaryConfigViolations(module, io = {}) {
  * `coverage.exempt` is that provider's one channel for the same decision —
  * and the refusal lives in `./commands/policy.mjs`'s `resolvePolicy` and
  * `./providers/native/model.mjs`'s inline-policy check, because only they
- * know which provider is reading.
+ * know which provider is reading. `markdown` is the seventh: the document
+ * track (`findMarkdownViolations` above owns the shape), read into the graph
+ * by `../analysis/markdown.mjs` on every provider, because documents belong
+ * to projects under all three.
  *
  * The name says `.json` and the list binds both file dialects: `loadModulePolicy`
  * runs the same check over an ES module's exports, which is what makes a
@@ -1109,6 +1275,7 @@ const JSON_POLICY_KEYS = [
   "fitness",
   "customRules",
   "coverage",
+  "markdown",
 ];
 
 /**
@@ -1185,7 +1352,7 @@ export function policyKeyViolations(parsed, { allowSchema }) {
  *   inline one.
  * @param {string[]} [extraViolations] Violations the caller already found that
  *   `findBoundaryConfigViolations` does not check on its own.
- * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }}
+ * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: object }}
  *   `fitness` and `customRules` are present only when the config declares
  *   them — a workspace without one carries no key, the same "absent is a
  *   decision" posture `cli.mjs`'s `check` uses for a missing
@@ -1209,6 +1376,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
     ...(parsed.fitness === undefined ? {} : { fitness: parsed.fitness }),
     ...(parsed.customRules === undefined ? {} : { customRules: parsed.customRules }),
     ...(parsed.coverage === undefined ? {} : { coverage: parsed.coverage }),
+    ...(parsed.markdown === undefined ? {} : { markdown: parsed.markdown }),
   };
 }
 

package/src/custom-rules/host.mjs

@@ -124,17 +124,17 @@ export const CUSTOM_RULE_TIMEOUT_MS = 10_000;
  * bundle for a large workspace is smaller — and it is what stops a claimed
  * length from being an allocation instruction.
  */
-export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024;
+export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024; // used by its own test
 
 /**
  * The most linear memory a rule may hold at the two boundaries the worker
  * measures. 256 MiB is far past what reading an evidence bundle needs and far
  * short of what a workspace's CI runner can absorb without noticing.
  */
-export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024;
+export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024; // used by its own test
 
 /** The four ABI symbols a rule module must export, and the kind each must be. */
-export const REQUIRED_EXPORTS = Object.freeze({
+const REQUIRED_EXPORTS = Object.freeze({
   memory: "memory",
   archkeep_alloc: "function",
   archkeep_describe: "function",