@intentius/chant 0.56.0 → 0.58.0

package/src/cli/commands/init-lexicon.test.ts

@@ -1,10 +1,11 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync, realpathSync } from "fs";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, readdirSync, realpathSync, symlinkSync } from "fs";
 import { execFileSync } from "child_process";
 import { join, dirname } from "path";
 import { tmpdir } from "os";
-import { fileURLToPath } from "url";
+import { fileURLToPath, pathToFileURL } from "url";
 import { initLexiconCommand } from "./init-lexicon";
+import { checkLexicon } from "./check-lexicon";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FIXTURE_DIR = join(__dirname, "__fixtures__", "init-lexicon-output");
@@ -44,6 +45,8 @@ describe("initLexiconCommand", () => {
       "src/codegen/naming.ts",
       "src/codegen/package.ts",
       "src/codegen/docs.ts",
+      "src/codegen/docs-cli.ts",
+      "src/package-cli.ts",
       "src/spec/fetch.ts",
       "src/spec/parse.ts",
       "src/lint/rules/sample.ts",
@@ -245,6 +248,16 @@ describe("scaffold content validation", () => {
     expect(pkg.scripts.build).toContain("tsconfig.build.json");
   });
 
+  // #2090, the scaffolded package.json failed tier 1 as generated: a bare
+  // string exports["."], a build script that never deletes emitted .js, and
+  // a prepack that never bundled, so dist/manifest.json never existed.
+  test("package.json exports[\".\"].default is ./src/index.ts, build deletes emitted JS, prepack bundles (#2090)", () => {
+    const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
+    expect(pkg.exports["."].default).toBe("./src/index.ts");
+    expect(pkg.scripts.build).toContain("-delete");
+    expect(pkg.scripts.prepack).toContain("bundle");
+  });
+
   test("tsconfig.build.json uses bundler resolution + the development condition (#749)", () => {
     const cfg = JSON.parse(readFileSync(join(targetDir, "tsconfig.build.json"), "utf-8"));
     expect(cfg.compilerOptions.moduleResolution).toBe("bundler");
@@ -308,6 +321,88 @@ describe("scaffold content validation", () => {
   });
 });
 
+// #2090, a fresh scaffold used to fail 5 tier-1 checks before the author
+// wrote anything. The docs-cli.ts gap (section 1) and the package.json/bundle
+// gap (section 2) together fixed the packaging-shape check and let
+// `npm run bundle` actually produce dist/manifest.json with a chantVersion.
+describe("a fresh scaffold's tier-1 completeness (#2090)", () => {
+  let root: string;
+  let dir: string;
+
+  beforeEach(async () => {
+    root = join(tmpdir(), `chant-scaffold-tier1-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(root, { recursive: true });
+    // The scaffold's tsconfig.json extends "../../tsconfig.json" (mirroring
+    // lexicons/<name>/tsconfig.json's real "../../tsconfig.json" -> repo
+    // root), so loading it needs a real file two levels up.
+    writeFileSync(join(root, "tsconfig.json"), "{}\n");
+
+    // A self-contained node_modules so the scaffold's own runtime imports of
+    // "@intentius/chant/*" resolve exactly as they would in the real
+    // monorepo, without touching the real repo's node_modules or lexicons/.
+    mkdirSync(join(root, "node_modules/@intentius"), { recursive: true });
+    symlinkSync(
+      join(__dirname, "..", "..", ".."), // commands -> cli -> src -> packages/core
+      join(root, "node_modules/@intentius/chant"),
+      "dir",
+    );
+
+    dir = join(root, "lexicons", "acme");
+    await initLexiconCommand({ name: "acme", path: dir });
+
+    // Bypass the generate() TODO throw. A real spec fetcher/parser is the
+    // author's job, not this test's. writeGeneratedFiles resolves its own
+    // target so a no-op stub is fine.
+    writeFileSync(
+      join(dir, "src/codegen/generate.ts"),
+      [
+        "export async function generate() {",
+        "  return { resources: 0, properties: 0, enums: 0, lexiconJSON: '{}', typesDTS: '', indexTS: '' };",
+        "}",
+        "export function writeGeneratedFiles() {}",
+        "",
+      ].join("\n"),
+    );
+
+    // Run the fixed bundle pipeline for real, proving section 2's package.json
+    // + package-cli.ts changes actually produce dist/manifest.json, not just
+    // that the scripts look right.
+    const packageMod = (await import(pathToFileURL(join(dir, "src/codegen/package.ts")).href)) as {
+      packageLexicon: (opts?: { verbose?: boolean }) => Promise<{ spec: unknown }>;
+    };
+    const { spec } = await packageMod.packageLexicon({ verbose: false });
+
+    const bundleMod = (await import(
+      pathToFileURL(join(root, "node_modules/@intentius/chant/src/codegen/package.ts")).href
+    )) as { writeBundleSpec: (spec: unknown, distDir: string) => void };
+    bundleMod.writeBundleSpec(spec, join(dir, "dist"));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("the fixed bundle pipeline actually produces dist/manifest.json with a chantVersion", () => {
+    expect(existsSync(join(dir, "dist/manifest.json"))).toBe(true);
+    const manifest = JSON.parse(readFileSync(join(dir, "dist/manifest.json"), "utf-8"));
+    expect(typeof manifest.chantVersion).toBe("string");
+    expect(manifest.chantVersion.length).toBeGreaterThan(0);
+  });
+
+  // Only real author work should remain. "Every shipped example builds..."
+  // also fails here, but for a reason outside this issue's scope: the
+  // scaffold's getting-started example has every line commented out (nothing
+  // to build yet), which is true independent of sections 1 and 2 above.
+  test("fails only on real author work, not on anything sections 1-2 fix", async () => {
+    const result = await checkLexicon(dir);
+    const tier1Failures = result.items.filter((i) => i.tier === 1 && !i.pass).map((i) => i.name);
+    expect(tier1Failures).toEqual([
+      "postSynthChecks() returns at least 1 check",
+      "Every shipped example builds and passes its own post-synth checks",
+    ]);
+  });
+});
+
 // ── Fixture snapshot tests ──────────────────────────────────────────
 
 describe("init-lexicon fixture snapshot", () => {

package/src/cli/commands/init-lexicon.ts

@@ -4,11 +4,11 @@ import { formatSuccess, formatWarning } from "../format";
 
 // Template generators
 import { generatePluginTs, generateIndexTs } from "./init-lexicon/templates/plugin";
-import { generateCodegenGenerateTs, generateCodegenGenerateCliTs, generateCodegenNamingTs, generateCodegenPackageTs, generateCodegenDocsTs } from "./init-lexicon/templates/codegen";
+import { generateCodegenGenerateTs, generateCodegenGenerateCliTs, generateCodegenNamingTs, generateCodegenPackageTs, generateCodegenDocsTs, generateCodegenDocsCliTs } from "./init-lexicon/templates/codegen";
 import { generateSpecFetchTs, generateSpecParseTs } from "./init-lexicon/templates/spec";
 import { generateSampleRuleTs, generateLintRulesIndexTs } from "./init-lexicon/templates/lint";
 import { generateLspCompletionsTs, generateLspHoverTs } from "./init-lexicon/templates/lsp";
-import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJustfile, generateGitignore, generateReadme, generateSerializerTs, generateValidateTs, generateValidateCliTs } from "./init-lexicon/templates/project";
+import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJustfile, generateGitignore, generateReadme, generateSerializerTs, generateValidateTs, generateValidateCliTs, generatePackageCliTs } from "./init-lexicon/templates/project";
 import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests";
 import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs";
 import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples";
@@ -137,6 +137,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "src/codegen/naming.ts": generateCodegenNamingTs(),
     "src/codegen/package.ts": generateCodegenPackageTs(name),
     "src/codegen/docs.ts": generateCodegenDocsTs(name),
+    "src/codegen/docs-cli.ts": generateCodegenDocsCliTs(),
     "src/spec/fetch.ts": generateSpecFetchTs(),
     "src/spec/parse.ts": generateSpecParseTs(),
     "src/lint/rules/sample.ts": generateSampleRuleTs(names),
@@ -149,6 +150,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "src/serializer.test.ts": generateSerializerTestTs(name, names),
     "src/validate.ts": generateValidateTs(name),
     "src/validate-cli.ts": generateValidateCliTs(),
+    "src/package-cli.ts": generatePackageCliTs(),
     "package.json": generatePackageJson(name, names),
     "tsconfig.json": generateTsConfig(),
     "tsconfig.build.json": generateTsConfigBuild(),

package/src/cli/commands/init.test.ts

@@ -348,5 +348,39 @@ describe("initCommand", () => {
       expect(pipeline).toContain("NodePipeline");
     });
   });
-});
 
+  // chant #2129 — core writes `chant.config.ts` before a plugin's root files
+  // and `writeIfNotExists` keeps the first one, so a template that ships its
+  // own config used to be discarded in silence. The template's wins now: it
+  // is the only one that knows the config namespace the scaffold needs.
+  test("a template's own chant.config.ts wins over the generic one", async () => {
+    await withTestDir(async (testDir) => {
+      const result = await initCommand({
+        path: testDir,
+        lexicon: "fountain",
+        template: "steward",
+        skipMcp: true,
+        skipInstall: true,
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.createdFiles).toContain("chant.config.ts");
+      // Written once, so no "already exists, skipping" warning about it.
+      expect(result.warnings.filter((w) => w.includes("chant.config.ts"))).toEqual([]);
+
+      const config = readFileSync(join(testDir, "chant.config.ts"), "utf-8");
+      expect(config).toContain("fountain:");
+      expect(config).toContain('token: { env: "FOUNTAIN_TOKEN" }');
+      expect(result.createdFiles).toContain("src/prod-watch.op.ts");
+    });
+  });
+
+  test("a template without a config still gets the generic one", async () => {
+    await withTestDir(async (testDir) => {
+      await initCommand({ path: testDir, lexicon: "fountain", skipMcp: true, skipInstall: true });
+      const config = readFileSync(join(testDir, "chant.config.ts"), "utf-8");
+      expect(config).toContain('lexicons: ["fountain"]');
+      expect(config).not.toContain("profiles");
+    });
+  });
+});

package/src/cli/commands/init.ts

@@ -343,10 +343,17 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
     warnings,
   );
 
-  // Generate chant.config.ts
+  // Generate chant.config.ts. A template that ships its own wins: core's
+  // version knows only the lexicon name, while a template that declares a
+  // config namespace (fountain's steward scaffold and its `fountain.profiles`
+  // block, chant #2129) is scaffolding a project that needs it to run at all.
+  // The root-file loop below runs *after* this write, and `writeIfNotExists`
+  // keeps the first file, so a template's config would otherwise be discarded
+  // in silence — see lexicons/cedar/src/init-templates.ts, which documents
+  // having had to work around exactly that.
   writeIfNotExists(
     join(targetDir, "chant.config.ts"),
-    generateChantConfig(options.lexicon),
+    templateSet?.root?.["chant.config.ts"] ?? generateChantConfig(options.lexicon),
     "chant.config.ts",
     createdFiles,
     warnings,
@@ -372,9 +379,13 @@ export async function initCommand(options: InitOptions): Promise<InitResult> {
         warnings,
       );
     }
-    // Write root scaffold files (e.g. index.js, test.js, Dockerfile)
+    // Write root scaffold files (e.g. index.js, test.js, Dockerfile).
+    // `chant.config.ts` is skipped: it was already written above, from this
+    // same template set, and re-offering it here would only produce an
+    // "already exists, skipping" warning about a file the template supplied.
     if (templateSet.root) {
       for (const [filename, content] of Object.entries(templateSet.root)) {
+        if (filename === "chant.config.ts") continue;
         writeIfNotExists(
           join(targetDir, filename),
           content,

package/src/cli/commands/lint.test.ts

@@ -69,6 +69,54 @@ export const b = new Bucket({ encryption: { algo: "AES256" } });
     expect(result.diagnostics.some((d) => d.ruleId === "COR001")).toBe(true);
   });
 
+  // #2122 (epic #2114 sub-issue 6) — OPS013 is a core-owned Op-model
+  // post-synth check, run over every `*.op.ts` file `chant lint` finds under
+  // the target path with no lexicon or build needed. This is the acceptance
+  // criterion: it fires on a fixture with a dangling `stepOutput` reference,
+  // on a project with no lexicons configured (no `plugins` in `options`
+  // below, the same as every other test in this file).
+  test("OPS013 fires on a dangling stepOutput reference with no lexicons configured", async () => {
+    await writeFile(
+      join(testDir, "reconcile.op.ts"),
+      `
+export default {
+  [Symbol.for("chant.declarable")]: true,
+  entityType: "Chant::Op",
+  lexicon: "chant",
+  kind: "resource",
+  props: {
+    name: "reconcile",
+    overview: "test",
+    phases: [
+      { name: "Phase", steps: [
+        {
+          kind: "activity",
+          fn: "httpCheck",
+          args: {
+            url: "http://x",
+            contains: { [Symbol.for("chant.op.stepOutputRef")]: true, kind: "step-output-ref", step: "nope", path: "x" },
+          },
+        },
+      ] },
+    ],
+  },
+};
+      `,
+    );
+
+    const options: LintOptions = {
+      path: testDir,
+      format: "stylish",
+    };
+
+    const result = await lintCommand(options);
+
+    expect(result.success).toBe(false);
+    expect(
+      result.diagnostics.some((d) => d.ruleId === "OPS013" && d.message.includes('unknown step id "nope"')),
+    ).toBe(true);
+  });
+
   test("formats output as JSON", async () => {
     await writeFile(
       join(testDir, "nested.ts"),

package/src/cli/commands/lint.ts

@@ -13,6 +13,9 @@ import { loadComponentChecks } from "../../lint/rules/comp/index";
 import { runComponentChecks, type ComponentCheckDiagnostic } from "../../lint/component-checks";
 import { buildCapabilityRegistry } from "../../components/capability-plugin-loader";
 import type { RollbackPolicy } from "../../components/capability";
+import { coreOpChecks } from "../../lint/rules/op";
+import { loadActivityContracts } from "../../op/activity-contract-registry";
+import { runPostSynthChecks } from "../../lint/post-synth";
 import { rule } from "../../lint/declarative";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 import { formatError, formatInfo } from "../format";
@@ -420,6 +423,113 @@ async function runComponentCheckDiagnostics(
   return { diagnostics, suppressed };
 }
 
+/**
+ * Run the OPS* Op-model post-synth checks (#2122, epic #2114 sub-issue 6 —
+ * OPS012/OPS013/OPS014, ported from a hosting lexicon's own
+ * TMP012/TMP013/TMP014) over every `*.op.ts` file under the lint target and
+ * merge them into the same diagnostics/suppressed lists `chant lint` already
+ * reports through, the same treatment {@link runComponentCheckDiagnostics}
+ * above gives COMP*.
+ *
+ * Deliberately scoped DOWNWARD from `infraPath` — the same scan
+ * `getTypeScriptFiles` already ran to build `files` — rather than
+ * `../../op/discover.ts`'s `discoverOps`, which walks UP to the nearest
+ * project root (or the git root, absent a config file) precisely because a
+ * real project's `ops/` convention sits outside `sourceDir`. That upward
+ * walk is right for `chant run`/`chant build`, which always operate on one
+ * whole project; it is wrong here, because `chant lint <path>` (and every
+ * fixture-scoped test that calls this file's `lintCommand`) may point at a
+ * directory with no `chant.config.*` above it short of this repo's own git
+ * root — which would make this check import every `*.op.ts` file in the
+ * entire monorepo on every such call. Scanning only under `infraPath`, like
+ * every other check in this function, keeps this check's cost proportional
+ * to the target the caller actually asked to lint.
+ *
+ * Each `*.op.ts` file's default export is imported directly and used as-is
+ * (it is already the `Declarable` `OpResource` instance `Op()` built) — no
+ * serializer and no lexicon plugin needed, since OPS012/OPS013/OPS014 only
+ * ever read `ctx.entities`, never `ctx.outputs`. That's what lets this fire
+ * even on a project with no lexicons configured at all.
+ *
+ * The project's configured lexicon NAMES are read, though (chant #2101), to
+ * resolve the activity contracts each one declares at
+ * `@intentius/chant-lexicon-<name>/op/activity-contracts` — one dynamic
+ * import per lexicon, no plugin load. Without them a step calling a
+ * lexicon's activity is flagged for the absence of a contract that lexicon
+ * does declare, which is the whole point of OPS013 firing outside a build.
+ *
+ * Reported at `1:1` in the file the Op was declared in, the same whole-file
+ * convention COMP* diagnostics use — a post-synth finding carries no real
+ * line/column (../../lint/post-synth.ts's `PostSynthDiagnostic` doc) and
+ * there's no per-file disable-directive suppression for the same reason
+ * (that doc again), so this reads only `lint.rules` severity overrides, not
+ * `chant-disable` comments.
+ */
+async function runOpCheckDiagnostics(
+  infraPath: string,
+  files: string[],
+): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
+  const config = loadConfig(findProjectRoot(infraPath));
+  const opFiles = files.filter((f) => f.endsWith(".op.ts"));
+  if (opFiles.length === 0) return { diagnostics: [], suppressed: [] };
+
+  const entities = new Map<string, unknown>();
+  const fileByOpName = new Map<string, string>();
+  for (const filePath of opFiles) {
+    try {
+      const mod: unknown = await import(filePath);
+      const entity = (mod as { default?: unknown }).default;
+      if (!entity || typeof entity !== "object") continue;
+      const opConfig = (entity as { props?: unknown }).props as { name?: unknown; phases?: unknown } | undefined;
+      if (!opConfig || typeof opConfig.name !== "string" || !Array.isArray(opConfig.phases)) continue;
+      entities.set(opConfig.name, entity);
+      fileByOpName.set(opConfig.name, filePath);
+    } catch {
+      // A file that fails to import is somebody else's problem — a syntax
+      // error surfaces through the AST rule pass over the same file instead
+      // of crashing this one.
+      continue;
+    }
+  }
+
+  if (entities.size === 0) return { diagnostics: [], suppressed: [] };
+
+  const lexiconNames = await resolveProjectLexicons(infraPath).catch(() => [] as string[]);
+  const activityContracts = await loadActivityContracts(lexiconNames);
+
+  const raw = runPostSynthChecks(
+    coreOpChecks(),
+    {
+      outputs: new Map(),
+      entities: entities as Map<string, never>,
+      warnings: [],
+      errors: [],
+      sourceFileCount: opFiles.length,
+    },
+    undefined,
+    { activityContracts },
+  );
+
+  const diagnostics: LintDiagnostic[] = [];
+  const suppressed: Array<LintDiagnostic & { reason?: string }> = [];
+
+  for (const d of raw) {
+    const resolved = resolveConfiguredSeverity(config.rules, d.checkId, d.severity);
+    if (resolved.severity === "off") continue;
+
+    diagnostics.push({
+      file: (d.entity && fileByOpName.get(d.entity)) ?? infraPath,
+      line: 1,
+      column: 1,
+      ruleId: d.checkId,
+      severity: resolved.severity,
+      message: d.message,
+    });
+  }
+
+  return { diagnostics, suppressed };
+}
+
 /**
  * Apply fixes to a file
  */
@@ -523,6 +633,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   diagnostics.push(...componentResult.diagnostics);
   suppressed.push(...componentResult.suppressed);
 
+  // Run the OPS* Op-model post-synth checks (#2122) over every `*.op.ts`
+  // file under the lint target — see runOpCheckDiagnostics's doc for why
+  // this needs no lexicon or build to fire.
+  const opResult = await runOpCheckDiagnostics(infraPath, files);
+  diagnostics.push(...opResult.diagnostics);
+  suppressed.push(...opResult.suppressed);
+
   // Apply fixes if requested
   if (options.fix) {
     // Group fixes by file
@@ -570,6 +687,12 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, options.buildParams);
     diagnostics.push(...postComponentResult.diagnostics);
     suppressed.push(...postComponentResult.suppressed);
+
+    // OPS* checks have no `.fix` either; re-run for the same consistency
+    // reason as the COMP* re-run just above.
+    const postOpResult = await runOpCheckDiagnostics(infraPath, files);
+    diagnostics.push(...postOpResult.diagnostics);
+    suppressed.push(...postOpResult.suppressed);
   }
 
   // Count errors and warnings

package/src/cli/commands/onboard.test.ts

@@ -72,6 +72,53 @@ jobs:
         run: npm run --prefix lexicons/k8s prepack
 `;
 
+// Mirrors the real chant.yml's check + test jobs: a comment (the cedar note)
+// sitting mid-list splits what would otherwise be one contiguous run of
+// prepack lines into two groups of 2+, so the old grouping wrote the new
+// lexicon's line twice per job (#2098).
+const ciContentWithMidListComment = `name: chant
+on: [push]
+jobs:
+  check:
+    steps:
+      - name: Generate lexicon artifacts
+        run: |
+          npm run --prefix lexicons/aws prepack
+          npm run --prefix lexicons/gitlab prepack
+          # cedar generates from the project's own .cedarschema, falling
+          # back to the schema bundled at src/spec/default-schema.cedarschema
+          # so a clean checkout still produces a surface to gate (#1650).
+          npm run --prefix lexicons/cedar prepack
+          npm run --prefix lexicons/k8s prepack
+      - name: Run tests
+        run: npx vitest run
+
+  test:
+    steps:
+      - name: Generate lexicon artifacts
+        run: |
+          npm run --prefix lexicons/aws prepack
+          npm run --prefix lexicons/gitlab prepack
+          # cedar generates from the project's own .cedarschema, falling
+          # back to the schema bundled at src/spec/default-schema.cedarschema
+          # so a clean checkout still produces a surface to gate (#1650).
+          npm run --prefix lexicons/cedar prepack
+          npm run --prefix lexicons/k8s prepack
+      - name: Run tests
+        run: npx vitest run
+
+  validate:
+    steps:
+      - name: Generate and validate AWS lexicon
+        run: npm run --prefix lexicons/aws prepack
+
+      - name: Generate and validate GitLab lexicon
+        run: npm run --prefix lexicons/gitlab prepack
+
+      - name: Generate and validate K8s lexicon
+        run: npm run --prefix lexicons/k8s prepack
+`;
+
 const publishContent = `name: publish
 on:
   push:
@@ -217,6 +264,34 @@ describe("onboardCommand", () => {
     const docker = readFileSync(join(root, "test/Dockerfile.smoke"), "utf-8");
     expect(docker.match(/terraform/g)?.length).toBe(1);
   });
+
+  test("a comment mid-list in check/test run blocks does not split the group: one insertion per block (#2098)", () => {
+    writeFileSync(join(root, ".github/workflows/chant.yml"), ciContentWithMidListComment);
+
+    const result = onboardCommand({ name: "terraform", root });
+    expect(result.patched).toContain("chant.yml (prepack + validate)");
+
+    const ci = readFileSync(join(root, ".github/workflows/chant.yml"), "utf-8");
+    // check + test + validate: exactly one new line per job, not two per job
+    // from the comment splitting the run: | block into two groups.
+    expect(ci.match(/lexicons\/terraform prepack/g)?.length).toBe(3);
+
+    const [checkBlock, rest] = ci.split("  test:");
+    const [testBlock, validateBlock] = rest.split("  validate:");
+
+    expect(checkBlock.match(/lexicons\/terraform prepack/g)?.length).toBe(1);
+    expect(testBlock.match(/lexicons\/terraform prepack/g)?.length).toBe(1);
+    expect(validateBlock.match(/lexicons\/terraform prepack/g)?.length).toBe(1);
+
+    // The new line lands after the block's last prepack line (k8s, past the
+    // comment), not right after the comment's first half of the group.
+    expect(checkBlock).toContain(
+      "          npm run --prefix lexicons/k8s prepack\n          npm run --prefix lexicons/terraform prepack\n",
+    );
+    expect(testBlock).toContain(
+      "          npm run --prefix lexicons/k8s prepack\n          npm run --prefix lexicons/terraform prepack\n",
+    );
+  });
 });
 
 describe("root tsconfig.json paths (#1614)", () => {

package/src/cli/commands/onboard.ts

@@ -5,6 +5,7 @@ import { formatSuccess, formatError, formatWarning } from "../format";
 
 export interface OnboardOptions {
   name: string;
+  /** Run `chant dev check-lexicon` and print its full output (see `printOnboardResult`). */
   verbose?: boolean;
   /** Monorepo root to patch. Defaults to the root this module lives in. */
   root?: string;
@@ -14,6 +15,7 @@ export interface OnboardResult {
   success: boolean;
   patched: string[];
   skipped: string[];
+  verbose?: boolean;
   error?: string;
 }
 
@@ -41,6 +43,13 @@ function isPrepackLine(line: string): boolean {
   return PREPACK_LINE.test(line);
 }
 
+/** A YAML comment line, e.g. the cedar note sitting mid-list in chant.yml. */
+const COMMENT_LINE = /^\s*#/;
+
+function isCommentLine(line: string): boolean {
+  return COMMENT_LINE.test(line);
+}
+
 function hasPrepackLine(lines: string[], name: string): boolean {
   return lines.some((l) => isPrepackLine(l) && l.includes(`lexicons/${name} prepack`));
 }
@@ -137,27 +146,46 @@ export function patchRootTsconfigPaths(root: string, name: string): PatchResult
 
 /**
  * Insert a new prepack line after the last prepack line in each contiguous group
- * of 2+ lines. Single standalone lines (like YAML `run:` values) are ignored.
- * Used for multi-line `run: |` blocks in workflows.
+ * of 2+ prepack lines. Single standalone lines (like YAML `run:` values) are
+ * ignored. Used for multi-line `run: |` blocks in workflows.
+ *
+ * A comment line between two prepack lines (the cedar note in chant.yml's
+ * check and test jobs) does not end the group: it is skipped when scanning,
+ * so the block still gets exactly one insertion, anchored after its last
+ * real prepack line rather than after the comment (#2098).
  */
 function insertPrepackInContiguousGroups(lines: string[], name: string): boolean {
   if (hasPrepackLine(lines, name)) return false;
 
-  // Identify contiguous groups of prepack lines
-  const groups: { start: number; end: number }[] = [];
+  // Identify contiguous groups of prepack lines, treating comment lines
+  // inside a group as pass-through rather than a boundary.
+  const groups: { lastPrepackIdx: number; count: number }[] = [];
   let groupStart = -1;
-  for (let i = 0; i <= lines.length; i++) {
-    const isPrepack = i < lines.length && isPrepackLine(lines[i]);
-    if (isPrepack && groupStart === -1) {
-      groupStart = i;
-    } else if (!isPrepack && groupStart !== -1) {
-      groups.push({ start: groupStart, end: i - 1 });
-      groupStart = -1;
+  let lastPrepackIdx = -1;
+  let count = 0;
+
+  const closeGroup = () => {
+    if (groupStart !== -1) groups.push({ lastPrepackIdx, count });
+    groupStart = -1;
+    count = 0;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    if (isPrepackLine(lines[i])) {
+      if (groupStart === -1) groupStart = i;
+      lastPrepackIdx = i;
+      count++;
+    } else if (isCommentLine(lines[i])) {
+      // Skip: does not extend a group on its own, and does not close one.
+      continue;
+    } else {
+      closeGroup();
     }
   }
+  closeGroup();
 
-  // Only insert into groups of 2+ lines (multi-line blocks, not standalone steps)
-  const insertAfter = groups.filter((g) => g.end > g.start).map((g) => g.end);
+  // Only insert into groups of 2+ prepack lines (multi-line blocks, not standalone steps)
+  const insertAfter = groups.filter((g) => g.count > 1).map((g) => g.lastPrepackIdx);
 
   if (insertAfter.length === 0) return false;
 
@@ -332,7 +360,7 @@ export function onboardCommand(options: OnboardOptions): OnboardResult {
     patchDockerfile(join(root, "test/Dockerfile.smoke-npm"), options.name),
   );
 
-  return { success: true, patched, skipped };
+  return { success: true, patched, skipped, verbose: options.verbose };
 }
 
 /**
@@ -365,20 +393,23 @@ export async function printOnboardResult(result: OnboardResult, name: string): P
   console.log(`     (must depend on @intentius/chant-lexicon-${name} for workspace resolution)`);
   console.log(`  2. Add smoke tests to test/integration.sh`);
   console.log(`  3. Run: npm install (to update workspace links)`);
-  console.log(`  4. First npm publish: tag with v<version> and push`);
+  console.log(`  4. First release: just release-lexicon ${name} patch`);
   console.log(`  5. Run: chant dev check-lexicon lexicons/${name} (to see completeness status)`);
   console.log(formatWarning({
     message: "First-time scoped packages may publish as private despite --access public",
   }));
   console.log(`     Check https://www.npmjs.com/org/intentius and toggle visibility if needed`);
 
-  // Run check-lexicon if the lexicon directory exists
-  const lexiconDir = join(findRepoRoot(), "lexicons", name);
-  if (existsSync(lexiconDir)) {
-    console.log("");
-    console.log("Lexicon completeness:");
-    const { checkLexicon, printCheckResult } = await import("./check-lexicon");
-    const checkResult = await checkLexicon(lexiconDir);
-    printCheckResult(checkResult, false);
+  // Under --verbose, run check-lexicon now instead of leaving step 5 to the
+  // author, printing the full tier 1/2/3 detail rather than just the summary above.
+  if (result.verbose) {
+    const lexiconDir = join(findRepoRoot(), "lexicons", name);
+    if (existsSync(lexiconDir)) {
+      console.log("");
+      console.log("Lexicon completeness:");
+      const { checkLexicon, printCheckResult } = await import("./check-lexicon");
+      const checkResult = await checkLexicon(lexiconDir);
+      printCheckResult(checkResult, false);
+    }
   }
 }