@intentius/chant 0.78.0 → 0.80.0

package/src/cli/main.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, expect } from "vitest";
 import { EventEmitter } from "node:events";
-import { parseArgs, waitForStreamDrain } from "./main";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { commandRegistry, parseArgs, waitForStreamDrain } from "./main";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 
 describe("parseArgs", () => {
@@ -298,6 +300,12 @@ describe("parseArgs", () => {
 
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
+  test("--promote-to <env> sets promoteTo, and a missing value is refused (#2575)", () => {
+    expect(parseArgs(["build", "--components", "--generate", "github", "--promote-to", "prod"]).promoteTo).toBe("prod");
+    expect(() => parseArgs(["build", "--components", "--generate", "github", "--promote-to"])).toThrow(/--promote-to needs an environment/);
+    expect(() => parseArgs(["build", "--promote-to", "--env", "x"])).toThrow(/--promote-to needs an environment/);
+  });
+
   test("parses --no-release-record for run --components", () => {
     const result = parseArgs(["run", "--components", "search-service", "--env", "staging", "--no-release-record"]);
     expect(result.components).toBe(true);
@@ -633,6 +641,30 @@ describe("parseArgs — run flags", () => {
   });
 });
 
+describe("workspace records (#2546)", () => {
+  test("parses --kind, --current, --at and --json", () => {
+    const args = parseArgs(["workspace", "records", "--kind", "docs/k.kind.mjs", "--current", "--at", "HEAD~1", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "records", kind: "docs/k.kind.mjs", current: true, at: "HEAD~1", json: true });
+    expect(parseArgs(["workspace", "records", "--kind=docs/k.kind.mjs"]).kind).toBe("docs/k.kind.mjs");
+    expect(parseArgs(["workspace", "records"]).current).toBeUndefined();
+    expect(() => parseArgs(["workspace", "records", "--kind"])).toThrow(/--kind needs a kind file/);
+    expect(() => parseArgs(["workspace", "records", "--kind", "--json"])).toThrow(/--kind needs a kind file/);
+  });
+
+  test("resolves to the records command, and anything else under workspace to its fallback", () => {
+    expect(resolveCommand(parseArgs(["workspace", "records", "--kind", "k.mjs"]), commandRegistry)?.def.name).toBe("workspace records");
+    expect(resolveCommand(parseArgs(["workspace", "ls"]), commandRegistry)?.def.name).toBe("workspace");
+  });
+
+  // #2525 rule 5: the workspace code loads only when a workspace command runs.
+  // The level-0 goldens catch it at run time; this catches it in review.
+  test("main.ts never imports workspace code statically", () => {
+    const source = readFileSync(join(import.meta.dirname, "main.ts"), "utf-8");
+    expect(source).not.toMatch(/^import[^;]*from\s+["'][^"']*workspace/m);
+    expect(source).toMatch(/await import\("\.\.\/workspace\/records-cli"\)/);
+  });
+});
+
 describe("waitForStreamDrain", () => {
   // Minimal writable stub — just the surface waitForStreamDrain reads.
   function fakeStream(len: number): NodeJS.WriteStream & { writableLength: number } {

package/src/cli/main.ts

@@ -27,6 +27,7 @@ import { runCarveStatus } from "./handlers/carve-status";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
 import { runComponentsFanOut } from "./handlers/fan-out";
+import { runComponentsPromote, runComponentsRollback } from "./handlers/promote";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
@@ -51,6 +52,7 @@ import type { LexiconPlugin } from "../lexicon";
 const BOOLEAN_FLAGS = new Set([
   "--help",
   "--agents",
+  "--agent",
   "--all-projects",
   "--force",
   "--fix",
@@ -92,6 +94,7 @@ const BOOLEAN_FLAGS = new Set([
   "--fail-on-drift",
   "--durable-requests",
   "--skip-mcp",
+  "--current",
 ]);
 
 /**
@@ -204,8 +207,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (v !== "source" && v !== "live") throw new Error(`--overlay-anchor must be 'source' or 'live', got '${v}'`);
       result.overlayAnchor = v;
     } else if (arg === "--from") {
-      // Shared by `migrate --from <lexicon>` and `import --from <env>`; the
-      // two commands never run together, so one field carries both.
+      // Shared by `migrate --from <lexicon>`, `import --from <env>` and
+      // `components promote --from <env>`; the commands never run together,
+      // so one field carries all three.
       result.migrateFrom = args[++i];
     } else if (arg === "--kustomize") {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
@@ -264,6 +268,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.src = args[++i];
     } else if (arg === "--env") {
       result.env = args[++i];
+    } else if (arg === "--promote-to") {
+      result.promoteTo = args[++i];
+      if (!result.promoteTo || result.promoteTo.startsWith("-")) throw new Error("--promote-to needs an environment: --promote-to <env>");
     } else if (arg === "--tier") {
       result.tier = args[++i];
     } else if (arg === "--agents") {
@@ -276,6 +283,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.runtime = args[++i];
     } else if (arg === "--fail-on") {
       result.failOn = args[++i];
+    } else if (arg === "--max-files") {
+      // Validated by the audit handler, like `--limit` below.
+      result.maxFiles = Number(args[++i]);
     } else if (arg === "--theme") {
       result.theme = args[++i];
     } else if (arg === "--stacks") {
@@ -284,6 +294,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.components = true;
     } else if (arg === "--generate") {
       result.generate = args[++i];
+    } else if (arg === "--spec") {
+      result.opsSpec = args[++i];
     } else if (arg === "--dump-outputs") {
       result.dumpOutputs = args[++i];
     } else if (arg === "--seed-outputs") {
@@ -341,6 +353,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.deep = true;
     } else if (arg === "--at") {
       result.at = args[++i];
+    } else if (arg === "--kind") {
+      // `chant workspace records --kind <kind file>` (#2546)
+      result.kind = args[++i];
+      if (!result.kind || result.kind.startsWith("-")) throw new Error("--kind needs a kind file: --kind <path>");
+    } else if (arg === "--current") {
+      result.current = true;
     } else if (arg === "--ambient") {
       result.ambient = true;
     } else if (arg === "--check-live") {
@@ -419,6 +437,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.note = args[++i];
     } else if (arg === "--expire") {
       result.expire = true;
+    } else if (arg === "--role") {
+      // #2508 — a role the approver holds, for a gate whose quorum names
+      // roles. Repeatable, and a comma list works too.
+      const value = args[++i] ?? "";
+      result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
+    } else if (arg === "--agent") {
+      // #2508 — record the approval as an agent's rather than a person's.
+      result.agent = true;
     } else if (arg === "--allow-same-origin") {
       // chant#2384 — record a resolution the same-origin rule would refuse,
       // deliberately. Flagged on the record, not just accepted quietly.
@@ -482,10 +508,11 @@ Commands:
   init                  Initialize a new chant project
   init lexicon <name>   Scaffold a new lexicon plugin project
   build                 Build infrastructure from specification files
-                        (--components --generate gitlab: generate mode (#563) —
-                         synthesize a thin .gitlab-ci.yml that triggers each
-                         discovered component's own deploy in wave order,
-                         instead of a normal lexicon build)
+                        (--components --generate github|gitlab|forgejo:
+                         generate mode (#563), which synthesizes a thin CI
+                         pipeline that triggers each discovered component's
+                         own deploy in wave order, instead of a normal
+                         lexicon build)
   lint                  Check specifications for issues
   list                  List discovered entities
   describe              Show the effective config for one component
@@ -500,7 +527,8 @@ Commands:
   audit [path|url]      Audit a repo's CI YAML for security issues
                         (--format stylish|json|sarif|markdown|html, -o <file>,
                          --tier merge-worthy|all, --fail-on merge-worthy|warning|error|none,
-                         --template <file> / --theme <file> for the html report)
+                         --template <file> / --theme <file> for the html report,
+                         --max-files <n> to walk more than 1000 files)
                         --agents audits this machine's agent configuration —
                         instruction files, MCP servers, skills, plugins,
                         permissions — instead of a repository
@@ -547,6 +575,11 @@ Ops:
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run --generate <provider>  Write one CI pipeline file per scheduled Op for
+                        github, gitlab or forgejo (#2533), from every Op that
+                        declares a schedule or from --spec <file.json>.
+                        Files go to the forge's own directory unless
+                        --output <dir>; --format json prints them instead
   run --components <name|all>  Run discovered Component(s) through the interpret
                         driver on the local executor (--env <env>; #585).
                         On success, auto-emits a release-ledger record per
@@ -606,6 +639,13 @@ Ops:
                         predicts the account. The level reaches the engine
                         verbatim; without the flag nothing is asked (#2377)
 
+Workspace (first-test slice, #2546):
+  workspace records --kind <kind file> [--current] [--at <rev>] [--json]
+                        Read the records a record kind locates, validated
+                        against its schema, with reason codes for invalid
+                        ones. --current leaves out superseded records; --at
+                        reads a commit's git objects. Needs no workspace file
+
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
                             --deep: also record each resource's property tree,
@@ -661,6 +701,15 @@ Component release ledger + status:
                             [--digest <manifestDigest>] -o <dir> [--json]);
                             copies every image/template/asset/sbom entry
                             byte-for-byte plus a self-describing manifest.json
+  components promote        Deploy the digests one environment's release
+                            ledger records to another, without a build
+                            (--from <env> --to <env> [--component <name>
+                             [--digest <sha256:...>]]; --dry-run prints the
+                             plan; the target's gates still apply)
+  components rollback <env> Redeploy an earlier release of an environment
+                            from its recorded digest (--component <name>
+                            [--digest <sha256:...>]; defaults to the release
+                            before the current one; --dry-run prints the plan)
 
 Lexicon development:
   dev generate          Generate lexicon artifacts (+ validate + coverage)
@@ -735,9 +784,14 @@ Options:
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
                         lexicon resources (list, describe, graph, build, run)
-  --generate <lexicon>  Generate mode (build --components only): synthesize CI
-                        YAML for <lexicon> instead of running a normal build.
-                        Only "gitlab" is implemented for v1.
+  --generate <lexicon>  Generate mode: synthesize CI YAML for <lexicon> (github,
+                        gitlab or forgejo) instead of running. build
+                        --components: one pipeline for the components; run:
+                        one pipeline file per scheduled Op
+  --spec <file>         (run --generate) JSON Op specs: an array, or
+                        { ops, options }
+  --promote-to <env>    (build --components --generate) Add a job that
+                        promotes the deployed releases to <env>
   --no-release-record   Skip auto-emitting a release-ledger record after a
                         successful \`run --components\` deploy (default: on;
                         also settable via chant.config.ts's
@@ -769,18 +823,18 @@ Options:
                         project source; network egress is NOT blocked (see
                         docs). Default: off (also settable via
                         chant.config.ts's build.sandbox: true; #1045)
-  --param <name=value>  (build, graph, run --components, components fan-out)
-                        Bind a declared
-                        build-time parameter (chant.config.ts's buildParams)
+  --param <name=value>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback) Bind a
+                        declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
                         Distinct from the AWS lexicon's deploy-time
                         Parameter(): this resolves before synthesis, so it
                         can change which resources are produced at all.
                         Highest precedence.
-  --params-file <path>  (build, graph, run --components, components fan-out)
-                        JSON file of
-                        { "name": value } build-time parameter values
+  --params-file <path>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback) JSON file
+                        of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
 
 Examples:
@@ -791,6 +845,7 @@ Examples:
   chant build ./infra/ --fold
   chant build ./infra/ --components --generate gitlab
   chant build ./infra/ --components --generate gitlab --output .gitlab-ci.yml
+  chant run --generate github
   chant run --components search-service --env staging
   chant run --components all --env production
   chant components export prod --component search-service -o ./dist/search-service
@@ -985,6 +1040,10 @@ export const commandRegistry: CommandDef[] = [
   { name: "graph", handler: runGraph },
   { name: "vendor", handler: runVendor },
 
+  // Workspace reads (#2524). Imported on first use, so a level-0 command never
+  // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).
+  { name: "workspace records", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceRecords(ctx) },
+
   // State subcommands
   { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },
   { name: "lifecycle show", handler: runLifecycleShow },
@@ -1006,6 +1065,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },
+  { name: "components promote", handler: runComponentsPromote },
+  { name: "components rollback", handler: runComponentsRollback },
 
   // Local emulators of configured lexicons (#920). Compound so the action word
   // lands in args.path (not consumed as a project dir) and projectPath is forced ".".
@@ -1025,6 +1086,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
   { name: "components", handler: runComponentsUnknown },
+  { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceUnknown(ctx) },
 ];
 
 /**

package/src/cli/mcp/op-tools.ts

@@ -14,6 +14,7 @@
  * run.
  */
 
+import { lexiconNames } from "../../lexicon-module";
 import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
@@ -39,7 +40,7 @@ async function runtimeFor(name: unknown): Promise<OpRuntimeProvider> {
   }
 
   const configured = await loadChantConfig(resolve("."))
-    .then(({ config }) => config.lexicons ?? [])
+    .then(({ config }) => lexiconNames(config.lexicons ?? []))
     .catch(() => [] as string[]);
   if (!configured.includes(wanted)) {
     throw new Error(

package/src/cli/path-lexicon-messages.test.ts

@@ -0,0 +1,152 @@
+/**
+ * chant#2578 — init, onboard, audit and import-agents name a lexicon declared
+ * by path (#2520) by that path, and print no install line for it. A lexicon
+ * named by package keeps its package name and `npm i` line.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  lexiconPackagesToInstall,
+  lexiconSourceLabel,
+  registerLexiconDeclarations,
+  resetLexiconModules,
+} from "../lexicon-module";
+import { initCommand } from "./commands/init";
+import { onboardCommand } from "./commands/onboard";
+import { installLine } from "./commands/audit";
+import { importAgentsCommand } from "./commands/import-agents";
+import { auditFiles, MissingLexiconError, type AuditInput } from "../audit/core";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-2578-")));
+  resetLexiconModules();
+});
+
+afterEach(() => {
+  resetLexiconModules();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("the shared helpers", () => {
+  test("a path lexicon is labelled by its path and has no package to install", () => {
+    registerLexiconDeclarations(["aws", { name: "site", module: "./lexicon/index.ts" }], dir);
+    expect(lexiconSourceLabel("site", dir)).toBe("./lexicon/index.ts");
+    expect(lexiconSourceLabel("aws", dir)).toBe("@intentius/chant-lexicon-aws");
+    expect(lexiconPackagesToInstall(["aws", "site"])).toEqual(["@intentius/chant-lexicon-aws"]);
+  });
+
+  test("a path outside the directory is shown absolute", () => {
+    registerLexiconDeclarations([{ name: "site", module: "/elsewhere/site.ts" }], dir);
+    expect(lexiconSourceLabel("site", dir)).toBe("/elsewhere/site.ts");
+  });
+});
+
+describe("init", () => {
+  function writeConfig(entry: string): void {
+    writeFileSync(join(dir, "chant.config.ts"), `export default { lexicons: [${entry}] };\n`);
+  }
+
+  test("a lexicon the existing config declares by path gets no dependency and no type stub", async () => {
+    writeConfig(`{ name: "site", module: "./lexicon/index.ts" }`);
+    const result = await initCommand({ path: dir, lexicon: "site", force: true, skipMcp: true, skipInstall: true });
+
+    expect(result.success).toBe(true);
+    expect(result.lexiconModule).toBe("./lexicon/index.ts");
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant"]);
+    expect(existsSync(join(dir, ".chant", "types", "lexicon-site"))).toBe(false);
+  });
+
+  test("a package lexicon is unchanged", async () => {
+    writeConfig(`"aws"`);
+    const result = await initCommand({ path: dir, lexicon: "aws", force: true, skipMcp: true, skipInstall: true });
+
+    expect(result.success).toBe(true);
+    expect(result.lexiconModule).toBeUndefined();
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant", "@intentius/chant-lexicon-aws"]);
+    expect(existsSync(join(dir, ".chant", "types", "lexicon-aws", "package.json"))).toBe(true);
+  });
+});
+
+describe("onboard", () => {
+  test("a lexicon declared by path is named by its path, with nothing patched", () => {
+    registerLexiconDeclarations([{ name: "site", module: "./lexicon/index.ts" }], process.cwd());
+    const result = onboardCommand({ name: "site", root: dir });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("./lexicon/index.ts");
+    expect(result.error).not.toMatch(/npm (i|install)\b/);
+    expect(result.patched).toEqual([]);
+  });
+
+  test("a package lexicon still patches", () => {
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "root", dependencies: {} }));
+    const result = onboardCommand({ name: "site", root: dir });
+
+    expect(result.success).toBe(true);
+    expect(result.patched.some((p) => p.startsWith("package.json"))).toBe(true);
+  });
+});
+
+describe("audit", () => {
+  test("the npx line leaves out a lexicon declared by path", () => {
+    registerLexiconDeclarations([{ name: "github", module: "./gh/index.ts" }], dir);
+    expect(installLine(["github", "gitlab"], ".")).toBe(
+      "npx -p @intentius/chant -p @intentius/chant-lexicon-gitlab chant audit .",
+    );
+  });
+
+  test("a path lexicon that fails to load is named by its path, with no npm line", async () => {
+    registerLexiconDeclarations([{ name: "helm", module: join(dir, "missing.ts") }], dir);
+    const input = { lexicon: "helm", path: "Chart.yaml", content: "" } as AuditInput;
+
+    const error = await auditFiles([input]).then(
+      () => undefined,
+      (err: unknown) => err,
+    );
+    expect(error).toBeInstanceOf(MissingLexiconError);
+    expect((error as Error).message).toContain(join(dir, "missing.ts"));
+    expect((error as Error).message).not.toContain("npm i");
+  });
+});
+
+describe("import-agents", () => {
+  function seedAgentConfig(home: string): void {
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(join(home, ".claude", "mcp.json"), JSON.stringify({ mcpServers: { a: { command: "x" } } }));
+  }
+
+  test("a path lexicon that fails to load is named by its path, with no npm line", async () => {
+    const home = join(dir, "home");
+    seedAgentConfig(home);
+    registerLexiconDeclarations([{ name: "fountain", module: "./agents/missing.ts" }], dir);
+
+    const result = await importAgentsCommand({ home, platform: "linux", projectRoots: [], output: join(dir, "out") });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("declared by path");
+    expect(result.error).toContain("missing.ts");
+    expect(result.error).not.toContain("npm i");
+  });
+
+  test("a package lexicon still gets its npm line", async () => {
+    const home = join(dir, "home");
+    seedAgentConfig(home);
+
+    const result = await importAgentsCommand({
+      home,
+      platform: "linux",
+      projectRoots: [],
+      output: join(dir, "out"),
+      lexicon: "no-such-lexicon",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("npm i @intentius/chant-lexicon-no-such-lexicon");
+  });
+});

package/src/cli/plugins.ts

@@ -1,10 +1,30 @@
+import { importLexiconModule, lexiconModulePath, lexiconNames } from "../lexicon-module";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
-import { loadChantConfigUpward } from "../config";
+import { loadChantConfig, loadChantConfigUpward } from "../config";
+import { findProjectConfig } from "../project-root";
 import { findInfraFiles, detectLexicons } from "../index";
-import { checkConflicts } from "./conflict-check";
+import { checkConflicts, describeConflict } from "./conflict-check";
+
+/**
+ * chant#2578 — load the chant.config nearest `dir` (walking up) so the
+ * lexicons it declares by path are recorded (../lexicon-module.ts), for a
+ * command that does not otherwise read the config. With no config there is
+ * nothing to record. A config that fails to load records nothing either, and
+ * the command keeps its package behaviour; the commands that need a valid
+ * config report its errors themselves.
+ */
+export async function recordProjectLexicons(dir: string): Promise<void> {
+  const { dir: projectDir, configPath } = findProjectConfig(dir);
+  if (configPath === undefined) return;
+  try {
+    await loadChantConfig(projectDir);
+  } catch {
+    // See above: an unloadable config changes nothing here.
+  }
+}
 
 /**
  * Load a single lexicon plugin by lexicon name.
@@ -13,6 +33,23 @@ import { checkConflicts } from "./conflict-check";
  * LexiconPlugin export. Falls back to wrapping a raw Serializer export.
  */
 export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
+  // chant #2520 — a lexicon declared by module path loads from that module.
+  const modulePath = lexiconModulePath(lexiconName);
+  if (modulePath !== undefined) {
+    const mod = (await importLexiconModule(lexiconName))!;
+    for (const value of Object.values(mod)) {
+      if (isLexiconPlugin(value)) {
+        if (value.name !== lexiconName) {
+          throw new Error(
+            `lexicon "${lexiconName}" is declared with module ${modulePath}, but the plugin it exports is named "${value.name}"`,
+          );
+        }
+        return value;
+      }
+    }
+    throw new Error(`Module ${modulePath} (lexicon "${lexiconName}") does not export a LexiconPlugin`);
+  }
+
   const packageName = `@intentius/chant-lexicon-${lexiconName}`;
   const mod = await import(packageName);
 
@@ -67,6 +104,9 @@ export function resolveLexiconVersions(lexiconNames: readonly string[]): Record<
   const versions: Record<string, string> = {};
 
   for (const name of lexiconNames) {
+    // chant #2520 — a lexicon declared by module path is not an installed
+    // package, so it has no package version to report.
+    if (lexiconModulePath(name) !== undefined) continue;
     const packageName = `@intentius/chant-lexicon-${name}`;
     try {
       let dir = dirname(require_.resolve(packageName));
@@ -177,9 +217,7 @@ export async function loadPlugins(lexiconNames: string[]): Promise<LexiconPlugin
   }
 
   if (report.conflicts.length > 0) {
-    const details = report.conflicts
-      .map((c) => `  ${c.type} "${c.key}" from: ${c.plugins.join(", ")}`)
-      .join("\n");
+    const details = report.conflicts.map(describeConflict).join("\n");
     throw new Error(
       `Cross-lexicon conflicts detected:\n${details}`,
     );
@@ -222,7 +260,7 @@ export async function resolveProjectLexicons(projectPath: string): Promise<strin
   const { config } = await loadChantConfigUpward(projectPath);
 
   if (config.lexicons && config.lexicons.length > 0) {
-    return config.lexicons;
+    return lexiconNames(config.lexicons);
   }
 
   // Fallback: detect from source imports — a pure text scan, no execution.

package/src/cli/registry.ts

@@ -145,6 +145,8 @@ export interface ParsedArgs {
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source
    * re-evaluates for that environment (`build` + `graph`), and drives policy. */
   env?: string;
+  /** `chant build --components --generate <lexicon> --promote-to <env>` (#2575) — add a promote job to the generated pipeline. */
+  promoteTo?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
   /** `chant graph --live --overlay` — classify the provisioned graph against
@@ -175,8 +177,13 @@ export interface ParsedArgs {
   components?: boolean;
   /** `chant build --components --generate <lexicon>` — generate mode (#563):
    * synthesize CI YAML from discovered components instead of running a normal
-   * lexicon build. Only "gitlab" is implemented for v1. */
+   * lexicon build. Also `chant run --generate <provider>` (#2533): one CI
+   * pipeline file per scheduled Op, through `generateOpsPipeline`. */
   generate?: string;
+  /** `chant run --generate <provider> --spec <file>` (#2533): a JSON file of
+   * `ScheduledOpSpec`s (or `{ ops, options }`) to generate instead of every
+   * discovered Op that declares a `schedule`. */
+  opsSpec?: string;
   /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
   detail?: number;
   /** `chant graph --lens <kind>:<target>` — focus the graph IR on a slice */
@@ -242,6 +249,8 @@ export interface ParsedArgs {
   allProjects?: boolean;
   /** `chant audit --fail-on merge-worthy|warning|error|none` */
   failOn?: string;
+  /** `chant audit --max-files <n>` (#2528) — files the local walk takes before it stops (default 1000). */
+  maxFiles?: number;
   /** `chant audit --theme <file>` — JSON theme knobs for the HTML report */
   theme?: string;
   /** `chant dev surface-diff --update-snapshot` — write the fresh snapshot as the new baseline */
@@ -270,6 +279,10 @@ export interface ParsedArgs {
    * should win.
    */
   at?: string;
+  /** `chant workspace records --kind <path>` (#2546): the record kind file to read records through. */
+  kind?: string;
+  /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
+  current?: boolean;
   /**
    * `chant search "<q>" --ambient --live --env <name>` (#1278) — also report
    * resources of a kind this estate manages that exist in the account without
@@ -364,6 +377,10 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, for a gate whose quorum counts only some roles. Repeatable; a comma list also works. */
+  roles?: string[];
+  /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
+  agent?: boolean;
   /** `chant approve <op> <gate> --plan <digest>` (#2300) — the plan this approval is for, as `sha256:<64 hex>`. Omitted, the digest is taken from the gate's standing pending fact, which is the plan the run that stopped at the gate actually produced; pass it to approve a plan explicitly, or to approve one before any run has recorded a pending fact. */
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */

package/src/components/__fixtures__/alb-ecs-service.json

@@ -39,13 +39,5 @@
         { "kind": "health-gate", "path": "/healthz" }
       ]
     }
-  ],
-  "rollback": [
-    {
-      "phase": "Rollback",
-      "steps": [
-        { "kind": "rollback-previous", "service": "search", "cluster": "$env.cluster" }
-      ]
-    }
   ]
 }

package/src/components/capability-plugin-loader.ts

@@ -22,6 +22,7 @@
  */
 
 import { CapabilityRegistry } from "./capability";
+import { lexiconModulePath } from "../lexicon-module";
 import type { CapabilityPlugin } from "./capability-plugin";
 import { isCapabilityPlugin } from "./capability-plugin";
 import { starterCapabilityPlugin } from "./starter-plugin";
@@ -113,7 +114,8 @@ export async function loadCapabilityPlugins(names: string[]): Promise<Capability
  * where the package's whole reason to exist is the plugin.
  */
 export async function loadCapabilityPluginFromLexicon(name: string): Promise<CapabilityPlugin | null> {
-  const packageName = `@intentius/chant-lexicon-${name}`;
+  // chant #2520 — a lexicon declared by module path is imported from that path.
+  const packageName = lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`;
   let mod: Record<string, unknown>;
   try {
     mod = (await import(packageName)) as Record<string, unknown>;

package/src/components/cli-support.ts

@@ -22,6 +22,7 @@
  *    executor, the CLI entrypoint the driver (#556) never had.
  */
 
+import { lexiconModulePath, lexiconNames } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
 import { projectToJson, type Archetype } from "./component";
@@ -237,7 +238,7 @@ export interface GenerateComponentsResult {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }
@@ -550,7 +551,7 @@ export async function runComponents(
     options.registry ??
     (await buildCapabilityRegistry({
       plugins: options.capabilityPlugins ?? config.capabilities,
-      lexicons: config.lexicons,
+      lexicons: lexiconNames(config.lexicons),
     }));
   const env = options.env ?? "local";
   const selected = targets.map((c) => c.name);