@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/lexicon-outputs.ts

@@ -24,17 +24,24 @@
  *
  * Under `--at` the revision's files are not on disk to fold, so a member
  * whose lexicons report outputs gets a gap instead.
+ *
+ * The consumer side works the same way (#4397): a lexicon's `workspaceLinks`
+ * hook names the outputs of other members its declarations read, such as
+ * the tables an otel `clickhouse` exporter writes. {@link gatherLexiconLinks}
+ * folds every member whose lexicons have the hook and hands back what they
+ * report, in the shape a kind's link reader returns (`./kind-link-readers.ts`),
+ * so `resolveLinks` checks those links like a dbt project's sources.
  */
 
 import { join, posix } from "node:path";
 import type { StaticFieldsRead } from "../config-static";
 import { isDeclarable, type Declarable } from "../declarable";
-import type { LexiconUnreadSource, LexiconWorkspaceOutput } from "../graph-ir";
+import type { LexiconUnreadSource, LexiconWorkspaceLinks, LexiconWorkspaceOutput } from "../graph-ir";
 import type { BuildRootContext, BuildRootContribution, IntrinsicDef } from "../lexicon";
 import type { Declaration, ResolvedGroup } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { kindHandles } from "./links";
-import { readKindLinks } from "./kind-link-readers";
+import { readKindLinks, type KindLinkRead } from "./kind-link-readers";
 import { memberExcludes, sourceFiles } from "./member-handles";
 import { memberDirOnDisk } from "./lexicon-symbols";
 import type { WorkspaceTree } from "./tree";
@@ -51,6 +58,7 @@ export interface OutputsPlugin {
   intrinsics?: () => IntrinsicDef[];
   buildRoots?: (ctx: BuildRootContext) => Promise<BuildRootContribution>;
   workspaceOutputs?: (entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]) => { outputs: LexiconWorkspaceOutput[]; gaps?: string[] } | undefined;
+  workspaceLinks?: (entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]) => LexiconWorkspaceLinks | undefined;
 }
 
 /** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
@@ -60,6 +68,8 @@ export interface GatherLexiconOutputsOptions {
   /** Read under `--at`: the member's files are a revision's, not on disk, so nothing is folded. */
   atRevision?: boolean;
   load?: OutputsPluginLoader;
+  /** Links the members' lexicons read (#4397), from {@link gatherLexiconLinks}: the members they target are read too. */
+  lexiconLinks?: ReadonlyMap<string, KindLinkRead>;
 }
 
 const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
@@ -134,7 +144,7 @@ export async function gatherLexiconOutputs(
   const targets = new Set(declaration.members.flatMap((m) => m.links.filter((l) => l.member !== m.name).map((l) => l.member)));
   // Links a kind's reader finds in a member's files target members too (#3932). One that names no
   // producer may be any other member's, so every other member is read.
-  for (const [consumer, read] of readKindLinks(declaration, tree, kinds)) {
+  for (const [consumer, read] of [...readKindLinks(declaration, tree, kinds), ...(options.lexiconLinks ?? new Map<string, KindLinkRead>())]) {
     for (const link of read.links) {
       if (link.member !== null) targets.add(link.member);
       else for (const m of declaration.members) if (m.name !== consumer) targets.add(m.name);
@@ -165,14 +175,36 @@ function importedLexicons(tree: WorkspaceTree, files: readonly string[]): string
   return [...names].sort();
 }
 
-async function readMemberLexiconOutputs(
+type Hook = "workspaceOutputs" | "workspaceLinks";
+
+/** A member's source folded for the lexicons that have `hook`, or why it wasn't. */
+type FoldedMember =
+  | { status: "none" }
+  | { status: "gaps"; gaps: string[] }
+  | {
+      status: "folded";
+      reporting: { name: string; plugin: OutputsPlugin }[];
+      entities: Map<string, Declarable>;
+      unread: LexiconUnreadSource[];
+      gaps: string[];
+      /** The tree-relative file that exports each entity, and that file's text. */
+      sourceOf: (entity: Declarable) => { file: string; text: string } | undefined;
+    };
+
+/**
+ * Fold one member's source for the lexicons that implement `hook`, never
+ * running it. "none" when no lexicon of the member's has the hook.
+ */
+async function foldMember(
   root: string,
   declaration: Declaration,
   tree: WorkspaceTree,
   groups: readonly ResolvedGroup[],
   m: Declaration["members"][number],
   options: GatherLexiconOutputsOptions,
-): Promise<MemberLexiconOutputs | undefined> {
+  hook: Hook,
+): Promise<FoldedMember> {
+  const what = hook === "workspaceOutputs" ? "outputs" : "links";
   const dir = memberDirOnDisk(root, m.dir);
   const { readConfigFieldsStatically } = await import("../config-static");
   const files = withinSourceDir(
@@ -188,7 +220,7 @@ async function readMemberLexiconOutputs(
     // source imports stand in for the ones it names.
     names = importedLexicons(tree, files);
   }
-  if (names.length === 0) return undefined;
+  if (names.length === 0) return { status: "none" };
   const load = options.load ?? ((await import("../cli/plugins")).loadPlugin as unknown as OutputsPluginLoader);
   const plugins: { name: string; plugin: OutputsPlugin }[] = [];
   const gaps: string[] = [];
@@ -196,13 +228,13 @@ async function readMemberLexiconOutputs(
     try {
       plugins.push({ name, plugin: await load(name) });
     } catch (err) {
-      gaps.push(`lexicon "${name}" could not be loaded, so the outputs it reads were not (${firstLine(err)})`);
+      gaps.push(`lexicon "${name}" could not be loaded, so the ${what} it reads were not (${firstLine(err)})`);
     }
   }
-  const reporting = plugins.filter((p) => typeof p.plugin.workspaceOutputs === "function");
-  if (reporting.length === 0) return gaps.length ? { outputs: [], gaps } : undefined;
+  const reporting = plugins.filter((p) => typeof p.plugin[hook] === "function");
+  if (reporting.length === 0) return gaps.length && hook === "workspaceOutputs" ? { status: "gaps", gaps } : { status: "none" };
   if (options.atRevision) {
-    return { outputs: [], gaps: [`the outputs of lexicon ${reporting.map((p) => p.name).join(", ")} are read from the working tree's files, not a revision's`] };
+    return { status: "gaps", gaps: [`the ${what} of lexicon ${reporting.map((p) => p.name).join(", ")} are read from the working tree's files, not a revision's`] };
   }
 
   // Fold the member's source, never run it.
@@ -216,15 +248,15 @@ async function readMemberLexiconOutputs(
   });
   let entities: Map<string, Declarable> = new Map();
   const unread: LexiconUnreadSource[] = [];
+  const folded: { file: string; rel: string; exports: Record<string, unknown> }[] = [];
   try {
     const { foldProject } = await import("../discovery/fold-import");
     const { collectEntities } = await import("../discovery/collect");
     const verdicts = await foldProject(files.map(abs), intrinsics, { lexicons: names, sandbox: true });
-    const folded: { file: string; exports: Record<string, unknown> }[] = [];
     for (const file of files) {
       const v = verdicts.get(abs(file));
       if (v?.verdict === "fold" && v.exports) {
-        folded.push({ file: abs(file), exports: ownExports(v.exports, names) });
+        folded.push({ file: abs(file), rel: file, exports: ownExports(v.exports, names) });
         continue;
       }
       let text = "";
@@ -238,7 +270,7 @@ async function readMemberLexiconOutputs(
     }
     entities = collectEntities(folded, dir);
   } catch (err) {
-    return { outputs: [], gaps: [...gaps, `${m.dir}: its source could not be folded, so its lexicons' outputs were not read (${firstLine(err)})`] };
+    return { status: "gaps", gaps: [...gaps, `${m.dir}: its source could not be folded, so its lexicons' ${what} were not read (${firstLine(err)})`] };
   }
 
   // A reporting lexicon's own build roots (the sql lexicon's `.sql` files) join
@@ -257,6 +289,32 @@ async function readMemberLexiconOutputs(
     }
   }
 
+  const sourceOf = (entity: Declarable) => {
+    const f = folded.find((x) => Object.values(x.exports).includes(entity));
+    if (!f) return undefined;
+    let text = "";
+    try {
+      text = tree.read(f.rel);
+    } catch {
+      // The line falls back to 1.
+    }
+    return { file: f.rel, text };
+  };
+  return { status: "folded", reporting, entities, unread, gaps, sourceOf };
+}
+
+async function readMemberLexiconOutputs(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  m: Declaration["members"][number],
+  options: GatherLexiconOutputsOptions,
+): Promise<MemberLexiconOutputs | undefined> {
+  const member = await foldMember(root, declaration, tree, groups, m, options, "workspaceOutputs");
+  if (member.status === "none") return undefined;
+  if (member.status === "gaps") return { outputs: [], gaps: member.gaps };
+  const { reporting, entities, unread, gaps } = member;
   const outputs: MemberLexiconOutputs["outputs"] = [];
   for (const { name, plugin } of reporting) {
     try {
@@ -270,3 +328,64 @@ async function readMemberLexiconOutputs(
   }
   return { outputs, gaps };
 }
+
+/** The line of `export const <name>` (or any declaration of it) in `text`, from 1; 1 when not found. */
+function declarationLine(text: string, name: string): number {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const at = text.search(new RegExp(`\\b(?:const|let|var|function|class)\\s+${escaped}\\b`));
+  return at < 0 ? 1 : text.slice(0, at).split("\n").length;
+}
+
+/**
+ * The links each `chant` member's lexicons read from its declarations
+ * (#4397), keyed by member name, in the shape a kind's link reader returns.
+ * Only members with a lexicon that has a `workspaceLinks` hook are folded. A
+ * link carries the file and line of the declaration that states it, and the
+ * reader is named `lexicon <name>`.
+ */
+export async function gatherLexiconLinks(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  kinds: KindRegistry,
+  options: GatherLexiconOutputsOptions = {},
+): Promise<Map<string, KindLinkRead>> {
+  const out = new Map<string, KindLinkRead>();
+  for (const m of declaration.members) {
+    const kind = kinds.get(m.kind);
+    if (!kind || kindHandles(m, kind) || tree.stat(memberDir(m.dir)) !== "dir") continue;
+    const member = await foldMember(root, declaration, tree, groups, m, options, "workspaceLinks");
+    if (member.status === "none") continue;
+    const where = memberDir(m.dir) || ".";
+    if (member.status === "gaps") {
+      out.set(m.name, { reader: "lexicon", links: [], gaps: member.gaps.map((message) => ({ file: where, line: 1, message })) });
+      continue;
+    }
+    for (const { name, plugin } of member.reporting) {
+      const read: KindLinkRead = { reader: `lexicon ${name}`, links: [], gaps: member.gaps.map((message) => ({ file: where, line: 1, message })) };
+      try {
+        const report = plugin.workspaceLinks!(member.entities, member.unread);
+        if (!report) continue;
+        for (const l of report.links) {
+          const entity = member.entities.get(l.entity);
+          const src = entity ? member.sourceOf(entity) : undefined;
+          read.links.push({
+            member: l.member ?? null,
+            output: l.output,
+            ...(l.anchor ? { anchor: l.anchor } : {}),
+            file: src?.file ?? where,
+            line: src ? declarationLine(src.text, l.entity.split(".").pop() ?? l.entity) : 1,
+          });
+        }
+        for (const g of report.gaps ?? []) read.gaps.push({ file: where, line: 1, message: g });
+      } catch (err) {
+        read.gaps.push({ file: where, line: 1, message: `lexicon "${name}" workspaceLinks threw, so its links were not read (${firstLine(err)})` });
+      }
+      if (read.links.length === 0 && read.gaps.length === 0) continue;
+      const prev = out.get(m.name);
+      out.set(m.name, prev ? { reader: prev.reader, links: [...prev.links, ...read.links], gaps: [...prev.gaps, ...read.gaps] } : read);
+    }
+  }
+  return out;
+}

package/src/workspace/lineage-check.ts

@@ -24,13 +24,14 @@
  * (`changes-cli.ts`, #2773), which prints a document of its own.
  */
 
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { formatError, formatSuccess } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import type { LintDiagnostic, LintRule } from "../lint/rule";
 import { findWorkspaceRoot } from "../project-root";
 import type { DeclarationCheckReport } from "./checks";
+import type { ForgeRepoList } from "./checks/org";
 import type { RecordFacts } from "./checks/records";
 import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
 import type { ReasonCode } from "./reason-codes";
@@ -91,7 +92,7 @@ export function findingKey(f: CheckFinding): string {
 }
 
 const USAGE =
-  "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+  "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>] [--forge-repos <file>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -141,7 +142,7 @@ export type CheckDocument =
       chant: string;
       at: string | null;
       /** The declaration's workspace, or null when there is none; `name` is null when it can't be read. */
-      workspace: { name: string | null; root: string } | null;
+      workspace: { name: string | null; root: string; repo: string | null } | null;
       declaration?: DeclarationCheckReport;
     })
   | { $schema: string; contract: number; chant: string; error: { code: CheckErrorCode; message: string; location: null } };
@@ -152,7 +153,11 @@ export type CheckDocument =
  * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
  * since the member facts describe the working tree, not the revision.
  */
-export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean; kind?: string; live?: { env: string; onStderr?: (text: string) => void } } = {}): Promise<CheckDocument> {
+export async function runChecks(
+  cwd: string,
+  at?: string,
+  options: { runGenerators?: boolean; kind?: string; live?: { env: string; onStderr?: (text: string) => void }; forgeRepos?: ForgeRepoList } = {},
+): Promise<CheckDocument> {
   // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
   const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
     import("./declaration"),
@@ -190,7 +195,7 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   }
 
   let declaration: DeclarationCheckReport | undefined;
-  let workspace: { name: string | null; root: string } | null = null;
+  let workspace: { name: string | null; root: string; repo: string | null } | null = null;
   if (found) {
     const { runDeclarationChecks } = await import("./checks");
     const { dir, tree } = found;
@@ -200,6 +205,7 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
       ...(commit !== null ? { tree } : {}),
       ...(records ? { records } : {}),
       ...(options.live ? { live: options.live } : {}),
+      ...(options.forgeRepos ? { forgeRepos: options.forgeRepos } : {}),
     });
     let name: string | null = null;
     try {
@@ -207,7 +213,8 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
     } catch {
       // The WSP001 finding already says why.
     }
-    workspace = { name, root: found.root };
+    const { repoIdentity } = await import("./repo-ref");
+    workspace = { name, root: found.root, repo: repoIdentity(dir) };
   }
   const ok = report.ok && (declaration?.ok ?? true);
   return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
@@ -267,7 +274,23 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     const handed = await handToRootChant(root, ctx.args.at);
     if (handed !== undefined) return handed;
   }
-  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}), ...(ctx.args.live && ctx.args.env ? { live: { env: ctx.args.env, onStderr: (text: string) => process.stderr.write(text) } } : {}) });
+  // The forge's repository list (#3168) is input a warden writes; chant never asks the forge itself.
+  let forgeRepos: ForgeRepoList | undefined;
+  if (ctx.args.forgeRepos !== undefined) {
+    const { parseForgeRepos } = await import("./checks/org");
+    try {
+      forgeRepos = parseForgeRepos(readFileSync(resolve(ctx.args.forgeRepos), "utf-8"), ctx.args.forgeRepos);
+    } catch (err) {
+      console.error(formatError({ message: `--forge-repos: ${(err as Error).message}`, hint: USAGE }));
+      return 1;
+    }
+  }
+  const doc = await runChecks(root, ctx.args.at, {
+    runGenerators: ctx.args.generated === true,
+    ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}),
+    ...(ctx.args.live && ctx.args.env ? { live: { env: ctx.args.env, onStderr: (text: string) => process.stderr.write(text) } } : {}),
+    ...(forgeRepos ? { forgeRepos } : {}),
+  });
   if ("error" in doc) {
     if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
     else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/lineage-upgrade.test.ts

@@ -497,6 +497,26 @@ describe("chant workspace upgrade", () => {
     expect(port.pending[0].approval).toEqual({ mode: "log-only", quorum: { count: 2, roles: ["maintainer"] } });
   });
 
+  test("a gate's quorum at HEAD in identity.gates is the one asked for, and the patch can't lower it (#4404)", async () => {
+    // The Op's own quorum is 2 at HEAD and 1 in the upgrade; the declaration at HEAD asks 3 of the gate.
+    const op = (overview: string, count: number): string =>
+      `export default { props: { name: "release", overview: ${JSON.stringify(overview)}, phases: [{ name: "Ship", steps: [{ kind: "gate", gate: "ship", approval: { quorum: { count: ${count} } } }] }] } };\n`;
+    release("v1.1.0", {
+      "chant.workspace.json": JSON.stringify({ name: "proj", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }], identity: { gates: { ship: { quorum: { count: 3 } } } } }, null, 2) + "\n",
+      "delivery/chant.config.ts": "export default {};\n",
+      "delivery/ops/release.op.ts": op("v1", 2),
+    });
+    proj = join(root, "members-4404");
+    expect((await initFromCommand({ from: `${tpl}@v1.1.0`, path: proj })).error).toBeUndefined();
+    git(proj, ["init", "-q", "-b", "main"]);
+    commitProject("init from v1.1");
+    release("v2.0.0", { "delivery/ops/release.op.ts": op("v2", 1) });
+    const port = ledger();
+    const result = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-09-23T10:00:00.000Z" });
+    expect(result.outcome).toBe("gated");
+    expect(result.staged!.governance).toMatchObject({ approval: { mode: "log-only", quorum: { count: 3 } } });
+  });
+
   test("refuses a scope with uncommitted changes, and a scope that does not exist", async () => {
     put(proj, "README.md", "dirty\n");
     await expect(stageUpgrade({ root: proj, to: "v1.0.0" })).rejects.toThrow(/uncommitted changes/);

package/src/workspace/lineage-upgrade.ts

@@ -573,16 +573,25 @@ export function isGovernancePath(path: string): boolean {
  * one. The Op files are read from the project's tree, which the upgrade
  * requires to match HEAD for every path the patch touches.
  *
+ * Both come from HEAD, never from the patch: the Op files are read from the
+ * clean project tree, and the declaration through `identityGatesAt(repo,
+ * head)` (`git show`). A change the upgrade itself makes to an Op or to
+ * `chant.workspace.json` cannot lower the approvals it asks for (#4404). A
+ * gate whose `identity.gates.<gate>.quorum` at HEAD sets one is asked for that
+ * quorum, as a run of the gate is (#4324), not the Op's own.
+ *
  * Discovery runs from each changed Op file's own directory, so it finds the
  * file under the project that owns it. Run from a workspace root, it would
  * skip every member's Op files (#2892).
  */
-async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateApproval> {
+async function rulesAtHead(repo: string, paths: string[], head: string): Promise<ResolvedGateApproval> {
   const opFiles = new Set(paths.filter((p) => GOVERNANCE[0].test(p)));
   let count = 1;
   let roles: string[] | undefined;
   if (opFiles.size > 0) {
     const { discoverOps } = await import("../op/discover");
+    const { identityGatesAt } = await import("../gate-decision");
+    const atBase = new Map(identityGatesAt(repo, head).map((g) => [g.gate, g.quorum]));
     const dirs = new Set([...opFiles].map((p) => dirname(join(repo, p))));
     for (const dir of dirs) {
       if (!existsSync(dir)) continue;
@@ -592,7 +601,7 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
         if (!opFiles.has(rel)) continue;
         // #4290: a quorum may be a list of rules; the strictest count is asked for.
         for (const approval of gateApprovals(config)) {
-          for (const rule of quorumRules(approval.quorum)) {
+          for (const rule of quorumRules(atBase.get(approval.gate) ?? approval.quorum)) {
             if (rule.count > count) {
               count = rule.count;
               roles = rule.roles;
@@ -605,12 +614,12 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
   return { mode: "log-only", quorum: { count, ...(roles && roles.length > 0 ? { roles } : {}) } };
 }
 
-type StepLike = { kind: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
+type StepLike = { kind: string; gate?: string; signalName?: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
 
-function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: GateQuorumSpec }> {
-  const out: Array<{ quorum?: GateQuorumSpec }> = [];
+function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ gate: string; quorum?: GateQuorumSpec }> {
+  const out: Array<{ gate: string; quorum?: GateQuorumSpec }> = [];
   const visit = (step: StepLike): void => {
-    if (step.kind === "gate") out.push(step.approval ?? {});
+    if (step.kind === "gate") out.push({ gate: step.gate ?? step.signalName ?? "", ...(step.approval?.quorum !== undefined ? { quorum: step.approval.quorum } : {}) });
     if (step.kind === "effect") (step.steps ?? []).forEach(visit);
   };
   for (const p of [...(config.phases ?? []), ...(config.onFailure ?? [])]) p.steps.forEach(visit);
@@ -865,7 +874,7 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
       if (touched.length > 0) {
         throw new UpgradeError(`the upgrade changes governance files that have uncommitted edits (${touched.map((l) => l.slice(3)).join(", ")}). Commit them first: their gates are read at HEAD.`);
       }
-      governance = { paths: governed, approval: await rulesAtHead(repo, governed), rules: head };
+      governance = { paths: governed, approval: await rulesAtHead(repo, governed, head), rules: head };
     }
 
     // 5. Checks.

package/src/workspace/links.ts

@@ -195,10 +195,11 @@ function nearNames(name: string, outputs: JoinHandle[]): string[] {
  */
 export function resolveLinks(
   declaration: Declaration,
-  handles: ReadonlyMap<string, MemberHandles>,
+  sourceHandles: ReadonlyMap<string, MemberHandles>,
   telemetry?: TelemetryTargets,
   readLinks?: ReadonlyMap<string, KindLinkRead>,
 ): LinkTableRow[] {
+  const handles = withReaderOutputs(sourceHandles, readLinks);
   const rows: LinkTableRow[] = [];
   const declaredTargets = new Map<string, Set<string>>();
 
@@ -311,6 +312,28 @@ export function resolveLinks(
   return [...rows, ...inferred];
 }
 
+/**
+ * `handles` with the outputs each member's kind reader found in its files
+ * (#3935) added to the member's own. The member stays complete unless a gap
+ * the reader flagged `outputs` left a name out. A member with no handles
+ * (its directory is missing, or its kind unknown) gets none.
+ */
+export function withReaderOutputs(handles: ReadonlyMap<string, MemberHandles>, reads: ReadonlyMap<string, KindLinkRead> | undefined): ReadonlyMap<string, MemberHandles> {
+  if (!reads) return handles;
+  let out: Map<string, MemberHandles> | undefined;
+  for (const [member, read] of reads) {
+    const base = handles.get(member);
+    const gaps = read.gaps.filter((g) => g.outputs);
+    if (!base || (!read.outputs?.length && gaps.length === 0)) continue;
+    const have = new Set(base.outputs.map((o) => o.name));
+    const added = (read.outputs ?? []).filter((o) => !have.has(o.name) && have.add(o.name)).map((o) => ({ name: o.name }));
+    const complete = base.complete && gaps.length === 0;
+    const why = base.why ?? (gaps.length === 0 ? null : gaps.length === 1 ? gaps[0].message : `${gaps[0].message}, and ${gaps.length - 1} more`);
+    (out ??= new Map(handles)).set(member, { ...base, outputs: [...base.outputs, ...added], complete, why: complete ? base.why : why, exposesNone: false });
+  }
+  return out ?? handles;
+}
+
 /** Match a declared or reader's output row against its producer's handles, setting its status and reason. */
 function resolveOutput(row: LinkRow, handles: ReadonlyMap<string, MemberHandles>): void {
   const producer = handles.get(row.producer);

package/src/workspace/ls-contract.test.ts

@@ -129,7 +129,7 @@ describe("chant workspace ls on built workspaces", () => {
       ["tools", false, "kind-probe-failed"],
       ["vendor", true, null],
     ]);
-    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, design, other, workspace/);
+    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, design, other, repo, workspace/);
     expect(doc.members[0].roles).toEqual([{ name: "frontend", path: "src" }]);
     expect(doc.groups[0].reason?.code).toBe("no-matches");
     expect(doc.summary).toEqual({ members: 5, unreadable: 3, groups: 1, matches: 0 });

package/src/workspace/ls.schema.json

@@ -51,6 +51,7 @@
           "required": ["name", "root", "file", "schema", "minReader", "pins"],
           "properties": {
             "name": { "type": "string", "description": "The declared name. With the revision, it identifies the workspace." },
+            "repo": { "type": ["string", "null"], "description": "Added in contract 1 by #3168. The repository the document came from: the URL of the remote origin of the git repository that holds the workspace, with any user name or password removed, or null when there is no origin or the workspace is outside git. With name, root and the revision, it says which repository's workspace a document describes, so a reader that gathers several repositories' documents, such as an org workspace's repo members, tells them apart." },
             "root": {
               "type": "string",
               "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
@@ -158,6 +159,12 @@
           "type": "array",
           "items": { "$ref": "#/$defs/generatedFile" }
         },
+        "repo": {
+          "description": "Added in contract 1 by #3168. For a member of kind repo, the other repository's workspace it names: url, the pinned rev and the workspace root inside that repository. Absent for every other kind. A repo member's dir is @repo/<name>, a marker that names no directory of this repository.",
+          "type": "object",
+          "required": ["url", "rev", "workspace"],
+          "properties": { "url": { "type": "string" }, "rev": { "type": "string" }, "workspace": { "type": "string" } }
+        },
         "agents": {
           "description": "Added in contract 1 by #3615. The names of the agent sessions the declaration binds to the member (agents[].member or agents[].members), in declaration order, read where workspace.agentsFrom says. Empty when none is. A session bound to several members is listed on each.",
           "type": "array",

package/src/workspace/ls.ts

@@ -39,7 +39,8 @@ import {
 } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { memberGenerated, type LsGenerated } from "./ls-generated";
-import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
+import { repoIdentity } from "./repo-ref";
+import { loadKindRegistry, probeKind, REPO_KIND, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
 import { declaredSessions } from "./write-scope";
@@ -117,6 +118,8 @@ export interface LsMember {
   generated: LsGenerated[];
   /** The agent sessions bound to the member, in declaration order (#3615); empty when none is. */
   agents: string[];
+  /** For a member of kind repo, the other repository's workspace it names (#3168). Absent for every other kind. */
+  repo?: { url: string; rev: string; workspace: string };
 }
 
 /**
@@ -168,6 +171,8 @@ export type LsDocument =
       at: string | null;
       workspace: {
         name: string;
+        /** The repository the document came from (#3168): its origin URL, redacted, or null. */
+        repo: string | null;
         /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
         root: string;
         file: string;
@@ -211,6 +216,8 @@ export interface LsQuery {
 
 /** A member's reason code, or null when its kind can read it. */
 export function memberReason(member: Member, tree: WorkspaceTree, kinds: KindRegistry): LsMember["reason"] {
+  // A repo member has no directory here (#3168); it is read from its own repository.
+  if (member.kind === REPO_KIND) return null;
   if (tree.stat(member.dir === "." ? "" : member.dir) !== "dir") {
     return { code: "dir-missing", message: `${member.dir} is not a directory${tree.label}` };
   }
@@ -283,6 +290,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
         records: unloaded(m.records),
         generated: memberGenerated(m, tree, repoPrefix),
         agents: sessions.agents.filter((a) => a.members.includes(m.name)).map((a) => a.name),
+        ...(m.repo ? { repo: { ...m.repo } } : {}),
         // The member's x- keys, as declared (#3595).
         ...extensionsAt(declaration, m.pointer),
       };
@@ -311,6 +319,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
       at,
       workspace: {
         name: declaration.name,
+        repo: repoIdentity(rootOnDisk),
         root: located.root,
         file: declaration.file,
         schema: declaration.schema,

package/src/workspace/member-commands.ts

@@ -241,6 +241,8 @@ export function planMembers(verb: WorkspaceVerb, root: string, options: PlanOpti
       const why =
         entry.kind === "workspace"
           ? "a nested workspace runs its own chant workspace commands"
+          : entry.kind === "repo"
+            ? "a repo member is another repository's workspace, which runs its own chant workspace commands; chant workspace graph reads it at its pinned revision"
           : entry.kind === "design"
             ? "a design member is data: chant reads its files for record pins and builds nothing"
             : `chant workspace ${verb} runs members of kind chant, and this one is kind ${entry.kind}`;
@@ -556,13 +558,17 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
   }
 
   const results = await executePlan(plan, args);
-  const anyFailed = results.some((r) => r.exitCode !== 0) || plan.unreadable.length > 0;
+  // #2549: the disagreement lint, over every member's graph, when asked for.
+  const cross = verb === "lint" && args.crossRoot ? await runCrossRoot(found.dir, args) : undefined;
+  const anyFailed = results.some((r) => r.exitCode !== 0) || plan.unreadable.length > 0 || cross?.failed === true;
   const workspace = { name: plan.workspace.name, root: plan.workspace.root };
 
   if (verb === "lint" && args.format === "sarif") {
     for (const r of results) if (r.stderr.trim()) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     const unreadable: MemberOutput[] = plan.unreadable.map((s) => ({ id: s.name, member: s.name, dir: s.dir ?? ".", exitCode: 1, stdout: "", stderr: `${s.reason.code}: ${s.reason.message}` }));
-    emitDocument(mergeSarif([...results, ...unreadable], plan.workspace.root), args.output);
+    const sarif = mergeSarif([...results, ...unreadable], plan.workspace.root) as { runs?: unknown[] };
+    if (cross) (sarif.runs ??= []).push(crossRootSarifRun(cross));
+    emitDocument(sarif, args.output);
     console.error(summaryLine(plan, results));
     return anyFailed ? 1 : 0;
   }
@@ -598,6 +604,7 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
           ...plan.unreadable.map((s) => ({ member: s.name, dir: s.dir, exitCode: 1, diagnostics: null, reason: s.reason })),
         ],
         skipped: plan.skipped,
+        ...(cross ? { crossRoot: crossRootJson(cross) } : {}),
       };
     }
     emitDocument(doc, args.output);
@@ -608,5 +615,56 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
   // Text: each member's own output under a heading. A build without -o prints
   // no templates, since several members' templates can't share one stdout.
   printSections(plan, results, verb !== "build" || args.output !== undefined);
+  if (cross) printCrossRoot(cross);
   return anyFailed ? 1 : 0;
 }
+
+// ── The disagreement lint (#2549) ────────────────────────────────────────────
+
+interface CrossRootRun {
+  result?: import("./cross-root-lint").CrossRootLintResult;
+  /** Why the members' graphs could not be read. */
+  error?: string;
+  /** An error finding, or a graph that could not be read. */
+  failed: boolean;
+}
+
+async function runCrossRoot(root: string, args: ParsedArgs): Promise<CrossRootRun> {
+  const { workspaceGraph } = await import("./graph-cli");
+  const { crossRootLint } = await import("./cross-root-lint");
+  const { doc, failed } = await workspaceGraph({ cwd: root, ...(args.members?.length ? { members: args.members } : {}), onStderr: (t) => process.stderr.write(t) });
+  if ("error" in doc) return { error: `${doc.error.code}: ${doc.error.message}`, failed: true };
+  const result = await crossRootLint(doc, args.env ? { env: args.env } : {});
+  return { result, failed: failed || result.findings.some((f) => f.severity === "error") };
+}
+
+function crossRootJson(cross: CrossRootRun): unknown {
+  return cross.result ? { findings: cross.result.findings, checks: cross.result.checks, unloaded: cross.result.unloaded } : { error: cross.error };
+}
+
+function crossRootSarifRun(cross: CrossRootRun): unknown {
+  const findings = cross.result?.findings ?? [];
+  return {
+    tool: { driver: { name: "chant", rules: [...new Set(findings.map((f) => f.checkId))].sort().map((id) => ({ id })) } },
+    automationDetails: { id: "cross-root/" },
+    properties: { crossRoot: true, checks: cross.result?.checks ?? [], unloaded: cross.result?.unloaded ?? [] },
+    results: findings.map((f) => ({
+      ruleId: f.checkId,
+      level: f.severity === "error" ? "error" : f.severity === "warning" ? "warning" : "note",
+      message: { text: f.message },
+      ...(f.root ? { properties: { member: f.root } } : {}),
+    })),
+    ...(cross.error ? { invocations: [{ executionSuccessful: false, toolExecutionNotifications: [{ message: { text: cross.error } }] }] } : {}),
+  };
+}
+
+function printCrossRoot(cross: CrossRootRun): void {
+  if (!cross.result) {
+    console.log(`── cross-root  (the members' graphs could not be read: ${cross.error})`);
+    return;
+  }
+  const { findings, checks, unloaded } = cross.result;
+  console.log(`── cross-root  (${checks.join(", ")}; ${findings.length} finding${findings.length === 1 ? "" : "s"})`);
+  for (const f of findings) console.log(`  ${f.severity.padEnd(7)} ${f.checkId}${f.root ? ` [${f.root}]` : ""} ${f.message}`);
+  for (const u of unloaded) console.log(`  (lexicon ${u.lexicon}: its cross-root checks could not be loaded: ${u.reason})`);
+}