@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/overlap.ts

@@ -0,0 +1,340 @@
+/**
+ * Overlap between in-flight work items (#4025, policy from #4016).
+ *
+ * A work lease locks one item, and nothing compares two items with each
+ * other. This report does, after the fact: it says which in-flight work items
+ * changed the same files, and which entries of a planned change set more than
+ * one of them reaches. It never blocks anything. Two people or agents read it
+ * and sort the overlap out between them.
+ *
+ * ## In flight
+ *
+ * A work item is a current record of a declared work kind. It is in flight
+ * unless it implements at least one decision and every decision it implements
+ * is confirmed, as #4024 defines confirmed ({@link decisionConfirmed}: in one
+ * of the decision kind's closed states and superseded by nothing). The item's
+ * own state does not matter: work marked done whose decision is not settled
+ * can still collide.
+ *
+ * ## Linked commits
+ *
+ * The commits of a work item are the commits linked to it as #4029 defines
+ * linked ({@link judgeCommits}): a `Chant-Record: <work kind>:<id>` trailer,
+ * or a `Chant-Lease` trailer that resolves to the item. A window match does
+ * not link. The walk covers every local branch, every remote-tracking branch
+ * and HEAD, so work pushed to a branch and fetched shows before it is merged.
+ * The ledger branches under `chant/` hold no work and are left out. Merge
+ * commits carry no work of their own and are skipped. Nothing is fetched.
+ *
+ * ## Files
+ *
+ * An item's files are the paths its linked commits add, change or delete,
+ * from the repository root, with renames read as a delete and an add. Two
+ * items overlap by file when both touch one path.
+ *
+ * ## Change-set entries
+ *
+ * A change set is planned from many commits, and a release bundles many work
+ * items, so an entry belongs to no single item on its face. An entry is
+ * attributed to a work item when:
+ *
+ * 1. the entry has a `source`: the file that declares its graph node, from
+ *    the repository root, recorded when the change set was stored
+ *    (`../change-set-graph.ts`);
+ * 2. a commit linked to the item changed that file; and
+ * 3. that commit is in the history the change set was planned from: an
+ *    ancestor of (or equal to) the commit its graph was read at, else the
+ *    commit the gate was reached at. When neither is known, or the commit is
+ *    not in this repository, the third test is skipped.
+ *
+ * An entry can be attributed to several items, and two items overlap by
+ * address when one entry is attributed to both. An entry with no `source`
+ * (stored by an older chant, mapped onto no node, or a node with no source
+ * location) is attributed to none and counted in `unattributed`.
+ *
+ * The change sets read are the ones `workspace status` lists on a gate that
+ * is pending or approved: the plans still waiting to apply.
+ */
+
+import { execFileSync } from "node:child_process";
+import { dirname } from "node:path";
+import type { ChangeSetDocument } from "../change-set";
+import { judgeCommits, hasLeaseLedger, type WorkIndex } from "./commit-links";
+import { declaredRecordKinds, type Declaration } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { decisionConfirmed } from "./flags";
+import { loadRecordKind } from "./records";
+import { readRecordsFor } from "./records-cli";
+import { LEASE_TRAILER, RECORD_TRAILER } from "./trailers";
+
+/** One in-flight work item with at least one linked commit. */
+export interface OverlapItem {
+  /** `<work kind>:<id>`, as a `Chant-Record` trailer names it. */
+  item: string;
+  /** The work record file, from the repository root. */
+  path: string;
+  state: string | null;
+  /** The commits linked to the item, newest first. */
+  commits: string[];
+}
+
+/** One change-set entry two items both reach. */
+export interface OverlapAddress {
+  /** The change set's digest, as `chant change-set show` takes it. */
+  changeSet: string;
+  /** The workspace member whose ledger stores the change set, or null for the flat ledger. */
+  ledgerMember: string | null;
+  /** The entry's change-set member and planner address. */
+  member: string;
+  address: string;
+  /** The entry's graph node, or null. */
+  node: string | null;
+  /** The source file the attribution went through, from the repository root. */
+  source: string;
+}
+
+/** Two in-flight work items that changed the same thing. */
+export interface OverlapPair {
+  /** The two items, `<work kind>:<id>`, in sorted order. */
+  items: [string, string];
+  /** The files both items' linked commits touch, sorted. */
+  files: string[];
+  /** The change-set entries attributed to both items, by change set then address. */
+  addresses: OverlapAddress[];
+}
+
+/** What `workspace status` reports as `overlap`. */
+export interface OverlapReport {
+  /** The in-flight work items with a linked commit, by item. */
+  items: OverlapItem[];
+  /** Each pair of items that share a file or an entry, by the first item then the second. */
+  pairs: OverlapPair[];
+  /** The digests of the change sets read, sorted. */
+  changeSets: string[];
+  /** Entries of those change sets with no `source`, so attributed to no item. */
+  unattributed: number;
+}
+
+/** A change set to attribute: one a pending or approved gate binds. */
+export interface OverlapChangeSetRef {
+  digest: string;
+  /** A directory whose ledger stores it: the member's directory. */
+  cwd: string;
+  ledgerMember: string | null;
+  /** The commit the gate was reached at, when the pending fact records one. */
+  gitSha: string | null;
+}
+
+/** Reads a stored change set; the lifecycle store unless a test swaps it. */
+export type StoredChangeSetReader = (digest: string, cwd: string) => Promise<ChangeSetDocument | null>;
+
+const defaultReadChangeSet: StoredChangeSetReader = async (digest, cwd) => {
+  const { readStoredChangeSet } = await import("../lifecycle/change-set-store");
+  const read = await readStoredChangeSet(digest, { cwd });
+  return read.status === "found" ? read.document : null;
+};
+
+function git(top: string, args: string[], input?: string): string {
+  return execFileSync("git", ["-c", "core.quotepath=off", ...args], {
+    cwd: top,
+    encoding: "utf-8",
+    stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
+    maxBuffer: 512 * 1024 * 1024,
+    ...(input !== undefined ? { input } : {}),
+  });
+}
+
+/** The work items of every declared work kind, with the index commits are judged against and the ones in flight. */
+async function readWorkItems(declaration: Declaration, root: string, top: string): Promise<{ index: WorkIndex; inFlight: Map<string, { path: string; state: string | null }> } | null> {
+  const kinds = new Map<string, Set<string>>();
+  const inFlight = new Map<string, { path: string; state: string | null }>();
+  for (const d of declaredRecordKinds(declaration)) {
+    const file = declaredKindFile(d, root);
+    const loaded = await loadRecordKind(file, root);
+    if (!loaded.kind.work) continue;
+    const decisionKind = await loadRecordKind(loaded.kind.work.decisions, dirname(loaded.file));
+    const closed = new Set(decisionKind.kind.closedStates ?? []);
+    const read = await readRecordsFor({ kind: file, cwd: root });
+    const decisions = new Map((read.result.decisions ?? []).map((x) => [x.id, x]));
+    const ids = kinds.get(loaded.kind.name) ?? new Set<string>();
+    for (const r of read.result.records) {
+      if (r.id === null) continue;
+      ids.add(r.id);
+      if (r.supersededBy !== null) continue;
+      const implemented = r.implements ?? [];
+      const settled = implemented.length > 0 && implemented.every((x) => decisionConfirmed(decisions.get(x.id), closed));
+      const key = `${loaded.kind.name}:${r.id}`;
+      if (!settled && !inFlight.has(key)) inFlight.set(key, { path: r.path, state: r.state });
+    }
+    kinds.set(loaded.kind.name, ids);
+  }
+  if (kinds.size === 0) return null;
+  return { index: { kinds, ledger: hasLeaseLedger(top) }, inFlight };
+}
+
+/**
+ * The non-merge commits on every local and remote-tracking branch and HEAD
+ * that carry a `Chant-Record` or `Chant-Lease` trailer, newest first. The
+ * ledger branches under `chant/` are left out.
+ */
+export function trailerCommits(top: string): string[] {
+  let text: string;
+  try {
+    text = git(top, [
+      "log",
+      "--no-merges",
+      `--format=%H%x1f%(trailers:key=${RECORD_TRAILER},key=${LEASE_TRAILER},valueonly,separator=%x1e)%x1d`,
+      "--exclude=chant/*",
+      "--branches",
+      "--exclude=*/chant/*",
+      "--remotes",
+      "HEAD",
+      "--",
+    ]);
+  } catch {
+    // An unborn HEAD has no history to read.
+    return [];
+  }
+  const out: string[] = [];
+  for (const chunk of text.split("\x1d")) {
+    const [sha, trailers] = chunk.trim().split("\x1f");
+    if (sha && trailers && trailers.trim() !== "") out.push(sha);
+  }
+  return out;
+}
+
+/** The paths each commit adds, changes or deletes, from the repository root, renames read as a delete and an add. */
+export function commitFiles(top: string, shas: string[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  if (shas.length === 0) return out;
+  const text = git(top, ["log", "--no-walk=unsorted", "--stdin", "--no-renames", "--name-only", "--format=%x1e%H"], `${shas.join("\n")}\n`);
+  for (const block of text.split("\x1e")) {
+    const lines = block.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (lines.length === 0) continue;
+    out.set(lines[0], lines.slice(1));
+  }
+  return out;
+}
+
+/** Every commit reachable from `rev`, or null when `rev` is not in the repository. */
+function reachable(top: string, rev: string): Set<string> | null {
+  try {
+    return new Set(git(top, ["rev-list", rev, "--"]).split("\n").filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The work items a change-set entry is attributed to, sorted: each item with
+ * a linked commit that changed the entry's `source` and is in `within`, the
+ * history the change set was planned from (null when that is unknown, so
+ * every linked commit counts). An entry with no source has none.
+ *
+ * `commitsOf` maps each in-flight item to its linked commits, and `files`
+ * each commit to the paths it touches.
+ */
+export function attributeEntry(
+  source: string | undefined,
+  commitsOf: ReadonlyMap<string, readonly string[]>,
+  files: ReadonlyMap<string, readonly string[]>,
+  within: ReadonlySet<string> | null,
+): string[] {
+  if (source === undefined) return [];
+  const out: string[] = [];
+  for (const [item, commits] of commitsOf) {
+    if (commits.some((sha) => (files.get(sha) ?? []).includes(source) && (within === null || within.has(sha)))) out.push(item);
+  }
+  return out.sort(byString);
+}
+
+/**
+ * The overlap report for the workspace declared at `root` in the repository
+ * at `top`. Null when the declaration names no work kind. Throws when a work
+ * kind or its records can't be read, or git fails; `workspace status` writes
+ * null then.
+ */
+export async function readOverlap(input: {
+  declaration: Declaration;
+  root: string;
+  top: string;
+  changeSets: OverlapChangeSetRef[];
+  readChangeSet?: StoredChangeSetReader;
+}): Promise<OverlapReport | null> {
+  const { top } = input;
+  const work = await readWorkItems(input.declaration, input.root, top);
+  if (work === null) return null;
+
+  // The commits of each in-flight item, newest first.
+  const commitsOf = new Map<string, string[]>();
+  if (work.inFlight.size > 0) {
+    const candidates = trailerCommits(top);
+    const links = judgeCommits(top, candidates, work.index);
+    for (const sha of candidates) {
+      for (const id of links.get(sha)?.ids ?? []) {
+        if (!work.inFlight.has(id)) continue;
+        const list = commitsOf.get(id) ?? [];
+        if (!list.includes(sha)) list.push(sha);
+        commitsOf.set(id, list);
+      }
+    }
+  }
+  const items = [...commitsOf.keys()].sort(byString);
+  const files = commitFiles(top, [...new Set([...commitsOf.values()].flat())]);
+  const filesOf = new Map(items.map((id) => [id, new Set(commitsOf.get(id)!.flatMap((sha) => files.get(sha) ?? []))]));
+
+  // Each change-set entry with a source, attributed to the items whose linked commits changed it within the change set's history.
+  const read = input.readChangeSet ?? defaultReadChangeSet;
+  const seen = new Set<string>();
+  const changeSets: string[] = [];
+  let unattributed = 0;
+  const addressesOf = new Map<string, OverlapAddress[]>();
+  const history = new Map<string, Set<string> | null>();
+  for (const ref of input.changeSets) {
+    const key = `${ref.ledgerMember ?? ""}\0${ref.digest}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const doc = await read(ref.digest, ref.cwd);
+    if (doc === null) continue;
+    if (!changeSets.includes(doc.digest)) changeSets.push(doc.digest);
+    const at = doc.graph?.at ?? ref.gitSha;
+    for (const e of doc.entries) {
+      if (e.source === undefined) {
+        unattributed++;
+        continue;
+      }
+      // Only an entry two items could share needs the change set's history.
+      if (attributeEntry(e.source, commitsOf, files, null).length < 2) continue;
+      if (at && !history.has(at)) history.set(at, reachable(top, at));
+      const owners = attributeEntry(e.source, commitsOf, files, at ? history.get(at)! : null);
+      if (owners.length < 2) continue;
+      const address: OverlapAddress = { changeSet: doc.digest, ledgerMember: ref.ledgerMember, member: e.member, address: e.address, node: e.node ?? null, source: e.source };
+      for (const id of owners) addressesOf.set(id, [...(addressesOf.get(id) ?? []), address]);
+    }
+  }
+  changeSets.sort(byString);
+
+  const pairs: OverlapPair[] = [];
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      const a = items[i];
+      const b = items[j];
+      const fb = filesOf.get(b)!;
+      const shared = [...filesOf.get(a)!].filter((f) => fb.has(f)).sort(byString);
+      const ab = addressesOf.get(b) ?? [];
+      const addresses = (addressesOf.get(a) ?? [])
+        .filter((x) => ab.includes(x))
+        .sort((x, y) => byString(x.changeSet, y.changeSet) || byString(x.member, y.member) || byString(x.address, y.address));
+      if (shared.length > 0 || addresses.length > 0) pairs.push({ items: [a, b], files: shared, addresses });
+    }
+  }
+
+  return {
+    items: items.map((id) => ({ item: id, path: work.inFlight.get(id)!.path, state: work.inFlight.get(id)!.state, commits: commitsOf.get(id)! })),
+    pairs,
+    changeSets,
+    unattributed,
+  };
+}

package/src/workspace/promotion-order.ts

@@ -0,0 +1,97 @@
+/**
+ * A member's promotion order (#4030): the literal entries of the `environments`
+ * array in its `chant.config.ts`, in the order written. A release moves from
+ * each environment to the next, so `chant components promote --to <env>` can
+ * default `--from` to the step before, and `chant workspace status --json`
+ * lists the order for a reader such as behold's lane.
+ *
+ * A pattern entry such as `pr-*` names no environment, so it is not a step.
+ * A component's own `environments` (`component.schema.json`) say where its
+ * release is hosted in each environment and never set the order.
+ *
+ * `canary` marks a step as the canary step. It is declared and surfaced only:
+ * no chant command acts on it yet.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { environmentName, isEnvironmentPattern, type EnvironmentDeclaration } from "../config";
+
+/** One step of a member's promotion order. */
+export interface PromotionStep {
+  name: string;
+  /** True when the entry sets `canary: true`. */
+  canary: boolean;
+}
+
+/** The member's promotion order from its config's `environments`; `[]` when it declares none. A repeated name keeps its first place. */
+export function promotionOrder(declared: readonly EnvironmentDeclaration[] | null | undefined): PromotionStep[] {
+  const out: PromotionStep[] = [];
+  for (const entry of declared ?? []) {
+    const name = environmentName(entry);
+    if (isEnvironmentPattern(name) || out.some((s) => s.name === name)) continue;
+    out.push({ name, canary: typeof entry !== "string" && entry.canary === true });
+  }
+  return out;
+}
+
+const STRING = String.raw`(?:"[^"\\\n\[\]{}]*"|'[^'\\\n\[\]{}]*')`;
+const PROP = String.raw`(?:(?:name|endpoint)\s*:\s*${STRING}|canary\s*:\s*(?:true|false))`;
+const ENTRY = String.raw`(?:${STRING}|\{\s*(?:${PROP}\s*,?\s*)*\})`;
+const ARRAY = new RegExp(String.raw`^\[\s*(?:${ENTRY}\s*,?\s*)*\]$`);
+
+/**
+ * The promotion order a `chant.config.ts` writes as literals, read from its
+ * text without running it, or `undefined` when the text is not that simple.
+ * Evaluating a TypeScript config loads tsx, and `workspace status` reads every
+ * member without that cost (#3976), so the plain cases are read here and the
+ * rest fall back to loading the config. The plain cases are a config with no
+ * `environments` and no spread, and one whose only `environments` is an array
+ * of string entries and `{ name, endpoint, canary }` entries with literal values.
+ */
+export function staticPromotionOrder(source: string): PromotionStep[] | undefined {
+  const text = source.replace(/("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`)|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "$1");
+  const mentions = text.match(/\benvironments\b/g)?.length ?? 0;
+  if (mentions === 0) return /export\s+default\s*\{/.test(text) && !text.includes("...") ? [] : undefined;
+  if (mentions > 1 || text.includes("...")) return undefined;
+  const start = text.match(/\benvironments\s*:\s*(\[)/);
+  if (!start || start.index === undefined) return undefined;
+  const open = start.index + start[0].length - 1;
+  const close = text.indexOf("]", open);
+  if (close < 0) return undefined;
+  const array = text.slice(open, close + 1);
+  if (!ARRAY.test(array)) return undefined;
+  const entries: EnvironmentDeclaration[] = [];
+  for (const m of array.matchAll(new RegExp(`${STRING}|\\{[^}]*\\}`, "g"))) {
+    const raw = m[0];
+    if (raw.startsWith("{")) {
+      const name = raw.match(/\bname\s*:\s*(?:"([^"]*)"|'([^']*)')/);
+      if (!name) return undefined;
+      entries.push({ name: name[1] ?? name[2], canary: /\bcanary\s*:\s*true\b/.test(raw) });
+    } else {
+      entries.push(raw.slice(1, -1));
+    }
+  }
+  return promotionOrder(entries);
+}
+
+/**
+ * One member's promotion order from its directory's config: `[]` when it has
+ * none or declares no environments, and null when the config can't be read.
+ * A TypeScript config is read as text when it is plain ({@link staticPromotionOrder}),
+ * and loaded otherwise.
+ */
+export async function readMemberPromotionOrder(dir: string): Promise<PromotionStep[] | null> {
+  try {
+    const ts = join(dir, "chant.config.ts");
+    if (existsSync(ts)) {
+      const plain = staticPromotionOrder(readFileSync(ts, "utf-8"));
+      if (plain) return plain;
+    }
+    const { loadChantConfig } = await import("../config");
+    const { config } = await loadChantConfig(dir);
+    return promotionOrder(config.environments);
+  } catch {
+    return null;
+  }
+}

package/src/workspace/read-contract.e2e.test.ts

@@ -22,6 +22,7 @@ import { describe, expect, test } from "vitest";
 import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
 import ciLastGreenSchema from "./ci-last-green.schema.json";
+import ciListSchema from "./ci-list.schema.json";
 import { workspaceComposites } from "./composites";
 import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
@@ -43,13 +44,16 @@ import { queryRecordsSince } from "./records-since";
 import recordsSinceSchema from "./records-since.schema.json";
 import { workspacePoints } from "./points-cli";
 import pointsSchema from "./points.schema.json";
+import releasesSchema from "./releases.schema.json";
+import changeSetShowSchema from "./change-set-show.schema.json";
+import deliveryMetricsSchema from "./delivery-metrics.schema.json";
 import { workspaceStatus } from "./status";
 import statusSchema from "./status.schema.json";
 
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema, "ci-last-green": ciLastGreenSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema, "ci-last-green": ciLastGreenSchema, "ci-list": ciListSchema, releases: releasesSchema, "change-set-show": changeSetShowSchema, "delivery-metrics": deliveryMetricsSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {

package/src/workspace/reason-codes.test.ts

@@ -9,7 +9,7 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
-import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES } from "./changes";
+import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES, COMMIT_LINK_FINDING_CODES } from "./changes";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
@@ -34,6 +34,7 @@ import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
 import { PATCH_ERROR_CODES } from "./patch";
@@ -50,6 +51,7 @@ import { CI_GREEN_ERROR_CODES } from "./ci-green";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
+import { METRICS_ERROR_CODES, METRICS_REASON_CODES } from "./delivery-metrics";
 
 const HERE = import.meta.dirname;
 
@@ -85,6 +87,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_REASON_CODES,
   INTENT_WHY_CODES,
   CHANGES_FINDING_CODES,
+  COMMIT_LINK_FINDING_CODES,
   CHANGES_ERROR_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
@@ -100,6 +103,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RUN_STATEMENT_FAILURE_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
+  FLAG_WARNING_CODES,
   ANSWER_WARNING_CODES,
   POINTS_ERROR_CODES,
   POINTS_SOURCE_REASON_CODES,
@@ -120,6 +124,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   ROTATION_REFUSAL_CODES,
   SIGNERS_ERROR_CODES,
   EVIDENCE_ERROR_CODES,
+  METRICS_ERROR_CODES,
+  METRICS_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -95,6 +95,9 @@ export const REASONS = {
   "work-contract-unknown": "A work record names a contract that no record of its kind's contract kind has.",
   "work-contract-undecided": "A work record names a contract whose state is not approved, such as a draft.",
   "work-tier-unknown": "A work record names a builder tier that its kind's work.tier.tiers does not list.",
+  // A feature flag that is valid but warned about (records, check, #4024).
+  "flag-work-unknown": "A flag record names a work item that no record of its kind's work kind has.",
+  "flag-stale": "Every decision a flag's work item implements is confirmed, so the flag is due for removal. check reports it (WSP118).",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
@@ -205,6 +208,9 @@ export const REASONS = {
   // The forward coverage check (check --changes, #2773): findings, one per changed path.
   "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
   "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
+  // The commit link check (check --changes, #4029): findings, one per trunk commit.
+  "commit-unlinked": "A trunk commit in the range names no work item: it has no Chant-Record trailer of a work kind and no Chant-Lease trailer.",
+  "commit-wrongly-linked": "A trunk commit in the range names a work item that is not there: a Chant-Record whose id no work kind has or whose kind is not a work kind, a malformed Chant-Record, or a Chant-Lease that resolves to no work item, and no other trailer links it.",
   // The patch read (workspace patch): a read that fails.
   "patch-path-invalid": "workspace patch --path names a path that is not relative and inside the workspace.",
   // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
@@ -283,7 +289,7 @@ export const REASONS = {
   "wip-race": "Another writer moved refs/chant/wip/<branch> between this command's read and its write.",
   "wip-policy-none": "wip push or wip fetch was run, and no box block declares replicate, so there is no remote.",
   "wip-remote-unknown": "The replicate policy names a git remote the checkout does not have; the host adds it, with its credential, before chant pushes.",
-  // Which commits passed CI (ci last-green and ci tick, #3573): why nothing was read.
+  // Which commits passed CI (ci last-green, ci list and ci tick, #3573): why nothing was read.
   "ci-green-undeclared": "The declaration has no ci.green block, so chant does not know which check runs make a commit green.",
   "ci-branch-unknown": "The checkout has no ref for the branch ci.green names: neither the remote-tracking branch nor a local one.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.

package/src/workspace/record-assets.test.ts

@@ -19,6 +19,7 @@ import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
 import { parseFrontMatter, RECORD_WARNING_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
 import recordsSchema from "./records.schema.json";
@@ -172,7 +173,7 @@ describe("chant workspace records checks each pin", () => {
   test("the schema lists exactly the warning codes", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
     // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES, ...FLAG_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

package/src/workspace/records-contract.e2e.test.ts

@@ -14,6 +14,7 @@ import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type
 import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, recordTextDigest, REVIEW_REASON_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { ANSWER_WARNING_CODES } from "./points";
+import { FLAG_WARNING_CODES } from "./flags";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
 
@@ -152,7 +153,7 @@ describe("records output schema", () => {
   test("lists exactly the warning codes the code can return", () => {
     // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686),
     // an answer kind's the answer warnings (ws-058), and records adds record-unattested for an author seal under a signers file at base (#2688).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES]);
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...ANSWER_WARNING_CODES, ...SEAL_WARNING_CODES, ...FLAG_WARNING_CODES]);
   });
 
   test("every failure validates with its code", async () => {

package/src/workspace/records.schema.json

@@ -254,7 +254,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer, or (added by #3147) a work record's contract that no record has or nobody approved, or a builder tier its kind does not list, or (added by #4024) a flag record's work item that no record has, or a flag due for removal. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
@@ -322,6 +322,23 @@
           "description": "Added in contract 1 by #3147, on every parsed record of a work kind whose work block names a contract kind. The contract record the item builds, by the id in the work block's contract field, with that record's state now; state is null when no record of the contract kind has the id. Null when the item names no contract.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }]
         },
+        "flag": {
+          "description": "Added in contract 1 by #4024, on every parsed record of a flag kind (a kind with a flag block). work is the work item the flag hides, with that item's state (null when no record of the flag kind's work kind has it), or null when the record names none. implements lists each decision the item implements, with its state and confirmed: true when it is in one of its kind's closed states and nothing supersedes it. stale is true when the item implements at least one decision and every one is confirmed: the flag is due for removal, warned flag-stale, and chant workspace check reports it as WSP118.",
+          "type": "object",
+          "required": ["work", "implements", "stale"],
+          "properties": {
+            "work": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLink" }] },
+            "implements": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "state", "confirmed"],
+                "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] }, "confirmed": { "type": "boolean" } }
+              }
+            },
+            "stale": { "type": "boolean" }
+          }
+        },
         "answers": {
           "description": "Added in contract 1 by #3147, on every record with an id of a work kind whose work block names an answer kind. The decision-point answers about the item: each answer record whose constrains names the item's id, in path order, joined by id and never copied onto the item. Read at the same revision; in the working tree, with the answers a steward keeps on the lifecycle ledger laid over it. Absent when the answer kind can't be read.",
           "type": "array",
@@ -414,7 +431,9 @@
             "answer-point-unknown",
             "answer-point-changed",
             "record-unattested",
-            "record-ratified-below-quorum"
+            "record-ratified-below-quorum",
+            "flag-work-unknown",
+            "flag-stale"
           ]
         },
         "message": { "type": "string" }