@intentius/chant 0.124.31 → 0.124.32

package/src/lifecycle/work-dir.ts

@@ -0,0 +1,82 @@
+/**
+ * Where an Op that changes the checkout makes its work worktrees (#2893).
+ *
+ * A work item's worktree is `<checkout>/.chant/work/[<member>/]<item>`. It
+ * sits inside the checkout, so a coding agent whose project root is the
+ * checkout may write there, and `node_modules` above it still resolves. It
+ * used to be `<git-common-dir>/chant-work/...`, where Claude Code refuses
+ * every write. `/.chant/work/` goes in `<git-common-dir>/info/exclude`, so the
+ * checkout's `git status` never lists it, and the rest of `.chant/` (the
+ * workspace lock, the factory's check logs) stays tracked.
+ *
+ * This module imports nothing from the workspace or the Op runner, so the
+ * hand-written walkers can ask it which directory to skip.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+
+/** The work directory, relative to a checkout's top, `/`-separated. */
+export const WORK_DIR = ".chant/work";
+
+/** The line `<git-common-dir>/info/exclude` gets, anchored at each checkout's top. */
+export const WORK_DIR_EXCLUDE = `/${WORK_DIR}/`;
+
+/** The directory where earlier versions made work worktrees, under the git common directory. */
+export const LEGACY_WORK_DIR = "chant-work";
+
+/**
+ * Whether a directory, given as a `/`-separated path relative to the root a
+ * walker started from, is a work directory: `.chant/work` at that root or at
+ * any depth below it. A walker skips it, since each worktree in it is a whole
+ * copy of the checkout.
+ */
+export function isWorkDir(rel: string): boolean {
+  return rel === WORK_DIR || rel.endsWith(`/${WORK_DIR}`);
+}
+
+/** The worktree for `id` under the checkout whose top is `top`. */
+export function workWorktreePath(top: string, members: readonly string[], id: string): string {
+  return join(top, ...WORK_DIR.split("/"), ...members, id);
+}
+
+/** The worktree an earlier version made for `id`, under the git common directory. */
+export function legacyWorkWorktreePath(commonDir: string, members: readonly string[], id: string): string {
+  return join(commonDir, LEGACY_WORK_DIR, ...members, id);
+}
+
+/**
+ * Add {@link WORK_DIR_EXCLUDE} to `<commonDir>/info/exclude` unless the file
+ * already has it, or `ignored` says git already ignores the work directory
+ * (a `.gitignore` of the project's, or the global excludes file). Returns
+ * whether it wrote the line.
+ */
+export function excludeWorkDir(commonDir: string, ignored: boolean): boolean {
+  const file = join(commonDir, "info", "exclude");
+  const text = existsSync(file) ? readFileSync(file, "utf-8") : "";
+  if (text.split(/\r?\n/).some((l) => l.trim() === WORK_DIR_EXCLUDE)) return false;
+  if (ignored) return false;
+  mkdirSync(join(commonDir, "info"), { recursive: true });
+  appendFileSync(file, `${text === "" || text.endsWith("\n") ? "" : "\n"}${WORK_DIR_EXCLUDE}\n`);
+  return true;
+}
+
+/**
+ * After a work worktree is removed, remove the directories above it that are
+ * left empty, up to and including the checkout's `.chant`, so a run leaves
+ * nothing behind in a checkout that had no `.chant` before it.
+ */
+export function removeEmptyWorkDirs(worktree: string): void {
+  const marker = `${sep}${WORK_DIR.split("/").join(sep)}${sep}`;
+  const at = worktree.lastIndexOf(marker);
+  if (at < 0) return;
+  const stop = worktree.slice(0, at);
+  for (let dir = dirname(worktree); dir.length > stop.length; dir = dirname(dir)) {
+    try {
+      if (readdirSync(dir).length > 0) return;
+      rmdirSync(dir);
+    } catch {
+      return;
+    }
+  }
+}

package/src/lint/discover.test.ts

@@ -1,7 +1,9 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-import { discoverLintRules, discoverPostSynthChecks } from "./discover";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { discoverLintRules, discoverPostSynthChecks, listRuleFiles } from "./discover";
 
 const thisDir = dirname(fileURLToPath(import.meta.url));
 
@@ -67,3 +69,45 @@ describe("discoverPostSynthChecks", () => {
     expect(checks.length).toBe(0);
   });
 });
+
+describe("rule modules compiled to JS (#3981)", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    // A compiled rules directory: ES modules in a "type": "module" package, each with its declarations beside it.
+    dir = mkdtempSync(join(tmpdir(), "chant-discover-js-"));
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ type: "module" }));
+    writeFileSync(join(dir, "alpha.js"), `export const alpha = { id: "JS002", severity: "warning", category: "style", check: () => [] };\n`);
+    writeFileSync(join(dir, "alpha.d.ts"), `export declare const alpha: unknown;\n`);
+    writeFileSync(join(dir, "beta.js"), `export const beta = { id: "JS001", severity: "error", category: "security", check: () => [] };\n`);
+    writeFileSync(join(dir, "beta.d.ts"), `export declare const beta: unknown;\n`);
+    writeFileSync(join(dir, "gamma.js"), `export const gamma = { id: "JSP001", description: "a post-synth check", check: () => [] };\n`);
+    writeFileSync(join(dir, "index.js"), `export * from "./alpha.js";\n`);
+    writeFileSync(join(dir, "rule-helpers.js"), `export const helper = 1;\n`);
+    writeFileSync(join(dir, "alpha.test.js"), `throw new Error("a test is not a rule");\n`);
+  });
+
+  afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+  test("listRuleFiles lists .js modules and leaves out declarations, tests, helpers and the index", () => {
+    expect(listRuleFiles(dir).sort()).toEqual(["alpha.js", "beta.js", "gamma.js"]);
+  });
+
+  test("a source module and its compiled twin list once, as the source", () => {
+    const both = mkdtempSync(join(tmpdir(), "chant-discover-both-"));
+    try {
+      for (const f of ["one.ts", "one.js", "one.d.ts", "two.js"]) writeFileSync(join(both, f), "");
+      expect(listRuleFiles(both).sort()).toEqual(["one.ts", "two.js"]);
+    } finally {
+      rmSync(both, { recursive: true, force: true });
+    }
+  });
+
+  test("discoverLintRules loads compiled rules", () => {
+    expect(discoverLintRules(dir, import.meta.url).map((r) => r.id)).toEqual(["JS001", "JS002"]);
+  });
+
+  test("discoverPostSynthChecks loads compiled checks", () => {
+    expect(discoverPostSynthChecks(dir, import.meta.url).map((c) => c.id)).toEqual(["JSP001"]);
+  });
+});

package/src/lint/discover.ts

@@ -1,8 +1,11 @@
 /**
  * Auto-discovery for lint rules and post-synth checks.
  *
- * Scans directories for .ts files and loads exported rules/checks,
- * eliminating the need to manually list every rule in plugin.ts.
+ * Scans directories for rule modules and loads exported rules/checks,
+ * eliminating the need to manually list every rule in plugin.ts. A lexicon
+ * run from source has `.ts` rule modules; one run compiled has `.js` modules
+ * beside `.d.ts` declarations (#3981). Both are found, and tsx is registered
+ * only when a module found is TypeScript.
  */
 
 import { readdirSync } from "fs";
@@ -11,6 +14,7 @@ import { createRequire } from "module";
 import type { LintRule } from "./rule";
 import type { PostSynthCheck } from "./post-synth";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { isTypeScriptModule } from "../module-source";
 
 let cjsTypeScript = false;
 
@@ -22,7 +26,8 @@ let cjsTypeScript = false;
  * From source this runs when the module loads, as it always has: vitest and
  * the source CLI rely on tsx's CommonJS hook being in place from then on. The
  * compiled CLI imports this module on every start and most commands read no
- * rule directory, so there it waits for the first one (#3878).
+ * rule directory, so there it waits for the first directory that holds a
+ * TypeScript rule module (#3878, #3981).
  */
 function registerTypeScriptRequire(): void {
   if (cjsTypeScript) return;
@@ -40,82 +45,83 @@ function registerTypeScriptRequire(): void {
 if (!import.meta.url.endsWith(".js")) registerTypeScriptRequire();
 
 /**
- * Discover lint rules from a directory.
- *
- * Scans the directory for .ts files (excluding tests, helpers, and index files),
- * loads each module, and collects any exported objects that look like a LintRule
- * (has `id`, `severity`, `category`, and `check` function).
- *
- * @param dir - Absolute path to the rules directory
- * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ * Load every rule module in `dir` and collect the exports `accept` takes.
+ * Registers tsx first only when one of the modules is TypeScript.
  */
-export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
-  registerTypeScriptRequire();
+function discoverExports<T>(dir: string, importMetaUrl: string, accept: (value: unknown) => value is T): T[] {
+  const files = listRuleFiles(dir);
+  if (files.some(isTypeScriptModule)) registerTypeScriptRequire();
   const require = createRequire(importMetaUrl);
-  const rules: LintRule[] = [];
-
-  for (const file of listRuleFiles(dir)) {
+  const found: T[] = [];
+  for (const file of files) {
     try {
-      // Strip .ts extension — require() resolves without it
-      const modPath = join(dir, file.replace(/\.ts$/, ""));
-      const mod = require(modPath);
+      const mod = require(join(dir, file)) as Record<string, unknown>;
       for (const exp of Object.values(mod)) {
-        if (isLintRule(exp)) rules.push(exp);
+        if (accept(exp)) found.push(exp);
       }
     } catch {
       // Skip files that fail to load
     }
   }
+  return found;
+}
 
-  return rules.sort((a, b) => a.id.localeCompare(b.id));
+/**
+ * Discover lint rules from a directory.
+ *
+ * Scans the directory for rule modules (see {@link listRuleFiles}), loads
+ * each one, and collects any exported objects that look like a LintRule (has
+ * `id`, `severity`, `category`, and `check` function).
+ *
+ * @param dir - Absolute path to the rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
+  return discoverExports(dir, importMetaUrl, isLintRule).sort((a, b) => a.id.localeCompare(b.id));
 }
 
 /**
  * Discover post-synth checks from a directory.
  *
- * Scans the directory for .ts files (excluding tests, helpers, and index files),
- * loads each module, and collects any exported objects that look like a PostSynthCheck
- * (has `id`, `description`, and `check` function).
+ * Scans the directory for rule modules (see {@link listRuleFiles}), loads
+ * each one, and collects any exported objects that look like a
+ * PostSynthCheck (has `id`, `description`, and `check` function).
  *
  * @param dir - Absolute path to the post-synth rules directory
  * @param importMetaUrl - The caller's import.meta.url (for createRequire)
  */
 export function discoverPostSynthChecks(dir: string, importMetaUrl: string): PostSynthCheck[] {
-  registerTypeScriptRequire();
-  const require = createRequire(importMetaUrl);
-  const checks: PostSynthCheck[] = [];
-
-  for (const file of listRuleFiles(dir)) {
-    try {
-      // Strip .ts extension — require() resolves without it
-      const modPath = join(dir, file.replace(/\.ts$/, ""));
-      const mod = require(modPath);
-      for (const exp of Object.values(mod)) {
-        if (isPostSynthCheck(exp)) checks.push(exp);
-      }
-    } catch {
-      // Skip files that fail to load
-    }
-  }
+  return discoverExports(dir, importMetaUrl, isPostSynthCheck).sort((a, b) => a.id.localeCompare(b.id));
+}
 
-  return checks.sort((a, b) => a.id.localeCompare(b.id));
+/** A rule module's name without its extension: `foo` for `foo.ts` and `foo.js`. */
+export function ruleModuleBase(file: string): string {
+  return file.replace(/\.(?:ts|js)$/, "");
 }
 
 /**
- * List rule files in a directory (excluding tests, helpers, index).
+ * List rule modules in a directory: `.ts` source or compiled `.js`, leaving
+ * out declarations (`.d.ts`), tests, helpers and the index. A directory
+ * holding both `foo.ts` and `foo.js` lists `foo.ts` alone, so a rule is
+ * never loaded twice.
  */
 export function listRuleFiles(dir: string): string[] {
+  let entries: string[];
   try {
-    return readdirSync(dir).filter((f) => {
-      if (!f.endsWith(".ts")) return false;
-      if (f.endsWith(".test.ts")) return false;
-      if (f === "index.ts") return false;
-      if (f.includes("helper")) return false;
-      return true;
-    });
+    entries = readdirSync(dir);
   } catch {
     return [];
   }
+  const modules = entries.filter((f) => {
+    if (!f.endsWith(".ts") && !f.endsWith(".js")) return false;
+    if (f.endsWith(".d.ts")) return false;
+    if (/\.test\.[tj]s$/.test(f)) return false;
+    if (f === "index.ts" || f === "index.js") return false;
+    if (f.includes("helper")) return false;
+    return true;
+  });
+  const sources = new Set(modules.filter((f) => f.endsWith(".ts")).map(ruleModuleBase));
+  return modules.filter((f) => f.endsWith(".ts") || !sources.has(ruleModuleBase(f)));
 }
 
 function isLintRule(obj: unknown): obj is LintRule {

package/src/module-source.test.ts

@@ -0,0 +1,85 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { isJavaScriptModule, isTypeScriptModule, moduleSourceDir, moduleSourceUrl, SOURCE_EXPORT_CONDITIONS } from "./module-source";
+
+describe("module-source (#3981)", () => {
+  test("from source, chant's own resolution adds the development condition", () => {
+    expect(SOURCE_EXPORT_CONDITIONS).toEqual(["development"]);
+  });
+
+  const pkg = join(sep, "x", "node_modules", "@intentius", "chant-lexicon-aws");
+
+  test("moduleSourceDir maps a compiled module's directory to the source directory", () => {
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "dist", "lint", "post-synth", "ext001.js")).href)).toBe(join(pkg, "src", "lint", "post-synth"));
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "dist", "taggable.js")).href)).toBe(join(pkg, "src"));
+  });
+
+  test("moduleSourceDir leaves a source module's directory alone, even under a dist/ directory", () => {
+    expect(moduleSourceDir(pathToFileURL(join(pkg, "src", "taggable.ts")).href)).toBe(join(pkg, "src"));
+    const checkout = join(sep, "home", "dist", "chant", "lexicons", "aws", "src", "taggable.ts");
+    expect(moduleSourceDir(pathToFileURL(checkout).href)).toBe(join(sep, "home", "dist", "chant", "lexicons", "aws", "src"));
+  });
+
+  test("moduleSourceUrl is a URL in the source directory, for createRequire", () => {
+    const url = moduleSourceUrl(pathToFileURL(join(pkg, "dist", "lsp", "hover.js")).href);
+    expect(url).toBe(pathToFileURL(join(pkg, "src", "lsp", "hover.js")).href);
+    expect(new URL("../generated/lexicon-aws.json", url).href).toBe(pathToFileURL(join(pkg, "src", "generated", "lexicon-aws.json")).href);
+  });
+
+  test("isTypeScriptModule and isJavaScriptModule", () => {
+    expect(isTypeScriptModule("/p/src/index.ts")).toBe(true);
+    expect(isTypeScriptModule("file:///p/src/index.mts?x=1")).toBe(true);
+    expect(isTypeScriptModule("/p/dist/index.d.ts")).toBe(false);
+    expect(isTypeScriptModule("/p/dist/index.js")).toBe(false);
+    expect(isJavaScriptModule("file:///p/dist/index.js")).toBe(true);
+    expect(isJavaScriptModule("/p/dist/index.mjs")).toBe(true);
+    expect(isJavaScriptModule("/p/src/index.ts")).toBe(false);
+    // No extension: only tsx's resolver completes it, so it is not plain JavaScript.
+    expect(isJavaScriptModule("/p/lexicon/index")).toBe(false);
+  });
+});
+
+describe("package sources run under plain node ESM (#3981)", () => {
+  const repo = resolve(import.meta.dirname, "..", "..", "..");
+  const SKIP_DIRS = new Set(["node_modules", "generated", "testdata", "fixtures", "__fixtures__", "test-fixtures"]);
+
+  function sources(dir: string, out: string[] = []): string[] {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) sources(join(dir, entry.name), out);
+      } else if (/\.ts$/.test(entry.name) && !/\.(test|d)\.ts$/.test(entry.name)) {
+        out.push(join(dir, entry.name));
+      }
+    }
+    return out;
+  }
+
+  test("no lexicon or package source uses the CommonJS __dirname or __filename", () => {
+    // Both are undefined in an ES module under plain node, and under tsx too: a
+    // read built on one throws, and the catch around it hides the data.
+    // moduleSourceDir(import.meta.url) names the source directory from src/ and dist/ alike.
+    const roots = ["lexicons", "packages"].flatMap((top) =>
+      readdirSync(join(repo, top), { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => join(repo, top, e.name, "src")),
+    );
+    const offenders: string[] = [];
+    for (const root of roots) {
+      let files: string[];
+      try {
+        files = sources(root);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        const code = readFileSync(file, "utf-8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+        code.split("\n").forEach((line, i) => {
+          if (/\b__(?:dirname|filename)\b/.test(line)) offenders.push(`${relative(repo, file)}:${i + 1}: ${line.trim()}`);
+        });
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/module-source.ts

@@ -0,0 +1,112 @@
+/**
+ * #3981 — paths for a module that may run from `src/*.ts` or from compiled
+ * `dist/*.js`.
+ *
+ * A package compiles `src/` to `dist/` with the same layout (`rootDir: src`,
+ * `outDir: dist`), so a compiled module sits at the same relative path under
+ * `dist/` as its source does under `src/`. tsc compiles only the modules: a
+ * file a module reads beside itself (generated JSON, skills markdown,
+ * snapshots) stays under `src/`, which every package publishes. A module that
+ * reads such a file names it from {@link moduleSourceDir}, not from its own
+ * directory, and finds it from either layout.
+ *
+ * String arithmetic only, no filesystem access, so it is safe in a sandboxed
+ * child and costs nothing at module scope.
+ */
+
+import { dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DIST = `${sep}dist${sep}`;
+
+/**
+ * The path a module's source has: `path` itself for a source module, and the
+ * matching path under `<package>/src` for a module under `<package>/dist`.
+ */
+function sourcePathOf(path: string): string {
+  if (!/\.[cm]?js$/.test(path)) return path;
+  const at = path.lastIndexOf(DIST);
+  if (at < 0) return path;
+  return path.slice(0, at) + `${sep}src${sep}` + path.slice(at + DIST.length);
+}
+
+/**
+ * #3981 — the source file a compiled module was built from:
+ * `<package>/dist/x/y.js` is `<package>/src/x/y.ts` (`.mjs` from `.mts`, `.cjs`
+ * from `.cts`). `undefined` for a path that is not a compiled module under a
+ * `dist/`. The file is not checked for.
+ */
+export function compiledModuleSource(path: string): string | undefined {
+  const ext = /\.([cm]?)js$/.exec(path);
+  if (!ext || path.lastIndexOf(DIST) < 0) return undefined;
+  return sourcePathOf(path).slice(0, -ext[0].length) + `.${ext[1]}ts`;
+}
+
+/**
+ * The directory a module's source sits in: `dirname` of `moduleUrl` when it
+ * runs from source, and the matching directory under `<package>/src` when it
+ * runs compiled from `<package>/dist`.
+ */
+export function moduleSourceDir(moduleUrl: string): string {
+  return dirname(sourcePathOf(fileURLToPath(moduleUrl)));
+}
+
+/**
+ * A URL in the module's source directory, for `createRequire` to read a file
+ * that sits beside the source (`require("./generated/lexicon-aws.json")`). The
+ * file name keeps the compiled extension; only the directory matters to
+ * `createRequire`.
+ */
+export function moduleSourceUrl(moduleUrl: string): string {
+  return pathToFileURL(sourcePathOf(fileURLToPath(moduleUrl))).href;
+}
+
+/**
+ * Whether `pathOrUrl` names a TypeScript module, which plain node cannot
+ * import without a loader: `.ts`, `.mts`, `.cts` or `.tsx`, and not a
+ * declaration file. A query or hash is ignored.
+ */
+export function isTypeScriptModule(pathOrUrl: string): boolean {
+  const path = pathOrUrl.replace(/[?#].*$/, "");
+  return /\.(?:[cm]?ts|tsx)$/.test(path) && !/\.d\.[cm]?ts$/.test(path);
+}
+
+/**
+ * Whether plain node imports `pathOrUrl` with no loader: `.js`, `.mjs`,
+ * `.cjs` or `.json`. Anything else, a module with no extension included, is
+ * left to tsx, whose resolver completes an extensionless path.
+ */
+export function isJavaScriptModule(pathOrUrl: string): boolean {
+  return /\.(?:[cm]?js|json)$/.test(pathOrUrl.replace(/[?#].*$/, ""));
+}
+
+/**
+ * #3981 — whether this process resolves chant's packages through their
+ * `development` export condition: always when chant runs from source (the
+ * CLI's `main()` installs a resolve hook that does so, and vitest's resolver
+ * adds the condition outside production mode), and otherwise when node runs
+ * with `--conditions=development` (or `-C development`, on the command line
+ * or in `NODE_OPTIONS`). Not from the environment: a compiled CLI that a test
+ * spawns inherits vitest's variables.
+ */
+function resolvesDevelopment(): boolean {
+  if (isTypeScriptModule(import.meta.url)) return true;
+  if (typeof process === "undefined") return false;
+  const flags = [...process.execArgv, ...(process.env.NODE_OPTIONS ?? "").split(/\s+/)];
+  return flags.some(
+    (flag, i) =>
+      flag === "--conditions=development" ||
+      flag === "-C=development" ||
+      ((flag === "--conditions" || flag === "-C") && flags[i + 1] === "development"),
+  );
+}
+
+/**
+ * #3981 — the package export conditions chant adds to `import`, `node` and
+ * `default` when it resolves a package itself (fold's import resolution, the
+ * sandbox bundle), so it lands on the module this process's `import()` would.
+ * Each chant package maps `development` to `src/*.ts` and `default` to the
+ * compiled `dist/*.js` it publishes. `["development"]` when the process
+ * resolves with it ({@link resolvesDevelopment}), else empty.
+ */
+export const SOURCE_EXPORT_CONDITIONS: readonly string[] = resolvesDevelopment() ? ["development"] : [];

package/src/op/activities/factory.ts

@@ -357,7 +357,7 @@ function inWorktree(kindFile: string, checkout: string, worktree: string): strin
     }
   };
   const [file, top, tree] = [real(kindFile), real(checkout), real(worktree)];
-  // Read from the worktree already (it sits under the checkout's .git), or outside the checkout: as it is.
+  // Read from the worktree already (it sits in the checkout's .chant/work, #2893), or outside the checkout: as it is.
   if (file.startsWith(`${tree}/`) || !file.startsWith(`${top}/`)) return file;
   return join(tree, file.slice(top.length + 1));
 }

package/src/op/discover-root.test.ts

@@ -15,13 +15,15 @@ import { discoverOps } from "./discover";
  * with whatever the current test set (`realpath`ed, since macOS's tmpdir is a
  * symlink and the walk compares resolved paths).
  */
-let fakeGitRoot = "";
+let fakeGitRoot: string | undefined = "";
 vi.mock("../runtime-adapter", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../runtime-adapter")>()),
   getRuntime: () => ({
     spawn: async (cmd: string[]) =>
       cmd[0] === "git" && cmd[1] === "rev-parse"
-        ? { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
+        ? fakeGitRoot === undefined
+          ? { stdout: "", stderr: "fatal: not a git repository", exitCode: 128 }
+          : { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
         : { stdout: "", stderr: "", exitCode: 0 },
   }),
 }));
@@ -68,6 +70,33 @@ describe("discoverOps — the scan root is the project, not the checkout (#2058)
   });
 });
 
+describe("discoverOps outside a git repository (#2504)", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-op-nogit-")));
+    fakeGitRoot = undefined;
+    mkdirSync(join(dir, "demo", "ops"), { recursive: true });
+    writeFileSync(join(dir, "demo", "ops", "apply.op.ts"), OP_FILE("k3d-apply"));
+  });
+  afterEach(() => {
+    fakeGitRoot = "";
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a chant.config names the project root, so no git root is needed", async () => {
+    writeFileSync(join(dir, "demo", "chant.config.json"), JSON.stringify({ lexicons: ["k8s"] }));
+    const { ops, errors } = await discoverOps({ cwd: join(dir, "demo", "ops") });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["k3d-apply"]);
+  });
+
+  test("with neither a config nor a git root, discovery says both are missing", async () => {
+    await expect(discoverOps({ cwd: join(dir, "demo") })).rejects.toThrow(
+      /Not in a git repository, and no chant\.config/,
+    );
+  });
+});
+
 /**
  * #2171. An Op may be exported by name, not only as the file's default.
  *

package/src/op/discover.ts

@@ -25,10 +25,11 @@ export interface OpDiscoveryResult {
   errors: string[];
 }
 
-async function findGitRoot(cwd?: string): Promise<string> {
+/** The git root `cwd` is inside, or undefined when it is in no repository. */
+async function findGitRoot(cwd?: string): Promise<string | undefined> {
   const rt = getRuntime();
   const result = await rt.spawn(["git", "rev-parse", "--show-toplevel"], { cwd });
-  if (result.exitCode !== 0) throw new Error("Not in a git repository");
+  if (result.exitCode !== 0) return undefined;
   return result.stdout.trim();
 }
 
@@ -43,17 +44,26 @@ async function findGitRoot(cwd?: string): Promise<string> {
  * file is the project boundary, the same one entity discovery respects.
  * With no config anywhere up to the git root, the git root stands —
  * #1675's original scope, kept for configless layouts.
+ *
+ * Outside any git repository the walk goes to the filesystem root, and the
+ * config is all discovery needs (#2504): a demo copy, an unpacked tarball or
+ * a fresh `chant init` before `git init`. Only a directory with neither a
+ * config above it nor a git root has no Op root, and that is the error.
  */
 async function findDiscoveryRoot(cwd?: string): Promise<string> {
-  const gitRoot = resolve(await findGitRoot(cwd));
+  const found = await findGitRoot(cwd);
+  const gitRoot = found === undefined ? undefined : resolve(found);
   let dir = resolve(cwd ?? process.cwd());
   for (;;) {
     if (existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"))) return dir;
     if (dir === gitRoot) break;
     const parent = dirname(dir);
-    if (parent === dir) break; // filesystem root — cwd was outside the git root
+    if (parent === dir) break; // filesystem root — cwd was outside the git root, or there is none
     dir = parent;
   }
+  if (gitRoot === undefined) {
+    throw new Error("Not in a git repository, and no chant.config.ts or chant.config.json above the current directory");
+  }
   return gitRoot;
 }
 

package/src/op/gate.test.ts

@@ -613,6 +613,36 @@ describe("op/gate — a rejected ledger push is reported, not swallowed (#2310)"
   });
 });
 
+describe("op/gate — an applied record is written on the remote's ledger (#3985)", () => {
+  test("appendApplied fetches first, so a remote another writer moved still takes the push", async () => {
+    const { remote, author } = await clonePair();
+    const other = tmp("other");
+    git(["clone", "-q", remote, other], tmpdir());
+    git(["config", "user.email", "other@chant.dev"], other);
+    git(["config", "user.name", "Other"], other);
+
+    const port = gitGateLedgerPort({ cwd: author });
+    const pending = { op: "migrations", gate: "migrations-wave-1", timestamp: "2026-10-10T00:00:00.000Z", expiresAt: "2026-10-11T00:00:00.000Z" };
+    expect((await port.appendPending(pending)).pushed).toBe(true);
+
+    // Another writer moves the remote past what `author` holds.
+    git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], other);
+    expect((await gitGateLedgerPort({ cwd: other }).appendPending({ ...pending, gate: "migrations-wave-2" })).pushed).toBe(true);
+
+    const line = {
+      version: 1 as const, kind: "applied" as const, op: "migrations", gate: "migrations-wave-1", planDigest: "sha256:aa",
+      approvedAt: "2026-10-10T01:00:00.000Z", approvedBy: "alice", timestamp: "2026-10-10T02:00:00.000Z",
+    };
+    expect(await port.appendApplied!(line)).toEqual({ pushed: true });
+
+    // The remote holds the applied line and the other writer's pending fact.
+    const reader = ciCheckout(remote);
+    const readerPort = gitGateLedgerPort({ cwd: reader });
+    expect(await readerPort.readApplied!("migrations")).toEqual([line]);
+    expect((await readerPort.read("migrations")).pending.map((p) => p.gate)).toEqual(["migrations-wave-1", "migrations-wave-2"]);
+  });
+});
+
 describe("op/gate — the approve hint on a sealed gate (#3521)", () => {
   test("approveCommand adds --sign last, only when sealed", () => {
     expect(approveCommand("app", "ship")).toBe("chant approve app ship");

package/src/op/gate.ts

@@ -176,6 +176,9 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
     async appendApplied(record) {
       const { dir, file } = appliedGatePath(record.op);
       const line = JSON.stringify(record, sortedJsonReplacer);
+      // #3985: write on top of the remote's ledger, not a local copy another
+      // writer has since moved past, so the push that follows can land.
+      await requireLifecycleLedger(opts);
       let lastErr: unknown;
       // The same append-and-retry as a ledger line: another writer to the branch is the ordinary case.
       for (let attempt = 1; attempt <= 5; attempt++) {