@intentius/chant 0.45.0 → 0.49.0

package/src/cli/commands/build.ts

@@ -4,15 +4,23 @@ import {
   resolveOwnershipMarker,
   resolveOwnershipEnv,
   ownershipEnvDisagreement,
+  isOwnershipParamRef,
   resolveFoldEnabled,
   resolveSandboxEnabled,
+  resolveKnowledgeDir,
 } from "../../config";
+import { loadOkfBundle } from "../../okf-read";
+import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
+import { collectSecretDeclarations } from "../../secret-provenance";
+import { coreReceiptChecks } from "../../lint/receipt-checks";
+import { coreOutputChecks } from "../../lint/output-checks";
+import { coreKnowledgeChecks } from "../../lint/knowledge-checks";
 import { applyConfiguredSeverity } from "../../lint/config";
 import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
@@ -258,6 +266,24 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const disagreement = ownershipEnvDisagreement(config, paramsResolution.provenance);
   if (disagreement) warnings.push(formatWarning({ message: disagreement }));
 
+  // #1221 — dynamic-env legality. `--env` is validated against the declared
+  // `environments` in cli/main.ts; a param-bound `ownership.env` supplied via
+  // `--param env=<value>` reached here unchecked, so `--param env=pord`
+  // stamped a marker for an environment the project never declared. Same
+  // check, same site of truth: literal entries match by equality, entries
+  // containing `*` (e.g. `"pr-*"`) match as glob patterns, so an unbounded
+  // family like per-PR environments is declarable without listing each name.
+  if (isOwnershipParamRef(config.ownership?.env)) {
+    const dynamicEnvErr = unknownEnvError(env, config.environments);
+    if (dynamicEnvErr) {
+      errors.push(formatError({
+        message: dynamicEnvErr,
+        hint: 'Declare it in chant.config `environments` (a "pr-*" pattern entry covers a dynamic family), or pass a declared value.',
+      }));
+      return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
+    }
+  }
+
   // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
   // `Sub`) through to the fold path, so a file using a registered intrinsic
   // tagged template folds instead of unconditionally falling back to run.
@@ -362,6 +388,66 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // finding just as it suppresses a pre-synth one. A finding it suppresses is
   // counted, not dropped silently — see `suppressedPostSynthCount` below.
   let suppressedPostSynthCount = 0;
+
+  // Core-owned post-synth checks over effect receipts (#1833). Receipts are
+  // recognized by marker, lexicon-independently, so this set runs over the
+  // FULL build result — unscoped, and regardless of which plugins loaded.
+  // Same severity-resolution funnel as every other post-synth finding.
+  if (result.errors.length === 0) {
+    const receiptDiags = runPostSynthChecks(coreReceiptChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(receiptDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over serialized output text (#1526). The
+  // "[object Object]" marker means a reference got stringified instead of
+  // resolved; it can appear in any lexicon's emitted text, so this runs over
+  // the FULL build result the same way the receipt checks above do.
+  if (result.errors.length === 0) {
+    const outputDiags = runPostSynthChecks(coreOutputChecks(), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(outputDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
+  // Core-owned post-synth check over the project's OKF knowledge bundle
+  // (#1865, design #1059): a concept's `binds` naming no discovered entity is
+  // a stale binding, surfaced as a COR026 warning. `resolveKnowledgeDir` +
+  // `loadOkfBundle` never fail — a missing/absent `knowledge/` directory
+  // loads an empty bundle, so this is a no-op for a project that has none.
+  if (result.errors.length === 0) {
+    const bundle = await loadOkfBundle(resolveKnowledgeDir(config, configDir));
+    const knowledgeDiags = runPostSynthChecks(coreKnowledgeChecks(bundle), result, env);
+    const { diagnostics: activeDiags, suppressed } = applyConfiguredSeverity(knowledgeDiags, config.lint?.rules);
+    suppressedPostSynthCount += suppressed.length;
+    for (const diag of activeDiags) {
+      const prefix = diag.entity ? `[${diag.entity}] ` : "";
+      const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
+      if (diag.severity === "error") {
+        errors.push(formatError({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      } else {
+        warnings.push(formatWarning({ message: `${prefix}${diag.message}${lexiconSuffix}` }));
+      }
+    }
+  }
+
   if (result.errors.length === 0 && options.plugins) {
     for (const plugin of options.plugins) {
       if (!plugin.postSynthChecks) continue;
@@ -462,6 +548,20 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     // Extract primary content and collect additional files from SerializerResult
     const additionalFiles = new Map<string, string>();
 
+    // Sidecar files that must reach disk BYTE-FOR-BYTE: committed ciphertext
+    // (`declareSecret({ provenance: "committed-encrypted", file })`). The
+    // additional-file writer below round-trips anything JSON.parse accepts,
+    // key-sorting it and possibly re-emitting it as YAML — which would break
+    // the `sops` MAC. `file` is restricted to .yaml/.yml, so that parse fails
+    // in practice, but naming the files here makes byte identity structural
+    // rather than a lucky accident.
+    const verbatimFiles = new Set<string>();
+    for (const decl of collectSecretDeclarations(result.entities).values()) {
+      if (decl.provenance === "committed-encrypted") {
+        verbatimFiles.add(decl.file.split(/[\\/]/).pop()!);
+      }
+    }
+
     function getPrimaryContent(raw: string | SerializerResult): string {
       if (typeof raw === "string") return raw;
       if (raw.files) {
@@ -567,15 +667,18 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
           const outputDir = dirname(outputPath);
           for (const [filename, content] of additionalFiles) {
             let fileContent = content;
-            // Format additional files consistently
-            try {
-              const fileParsed = JSON.parse(content);
-              fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
-              if (options.format === "yaml") {
-                fileContent = jsonToYaml(JSON.parse(fileContent));
+            // Format additional files consistently — except the ones declared
+            // verbatim, which are copied exactly as they were committed.
+            if (!verbatimFiles.has(filename)) {
+              try {
+                const fileParsed = JSON.parse(content);
+                fileContent = JSON.stringify(fileParsed, sortedJsonReplacer, 2);
+                if (options.format === "yaml") {
+                  fileContent = jsonToYaml(JSON.parse(fileContent));
+                }
+              } catch {
+                // If not JSON, write as-is
               }
-            } catch {
-              // If not JSON, write as-is
             }
             const targetPath = join(outputDir, filename);
             mkdirSync(dirname(targetPath), { recursive: true });
@@ -589,6 +692,21 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
           })
         );
       }
+    } else if (verbatimFiles.size > 0) {
+      // A build carrying committed ciphertext and no --output has nowhere to
+      // put the sidecar. Echoing it to a terminal is not useful and dropping
+      // it silently is worse: the primary output would reference a Secret
+      // whose file never got written, and the miss would surface as a pod
+      // failing to start, far from its cause. Refuse, naming the flag.
+      const names = [...verbatimFiles].sort().join(", ");
+      errors.push(
+        formatError({
+          message:
+            `This build emits committed-encrypted secret file(s) (${names}) as sidecars, ` +
+            `which need a directory to be written into. Re-run with --output <path> ` +
+            `(the sidecars land beside it).`,
+        }),
+      );
     } else {
       // Print to stdout
       console.log(output);

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

@@ -1,7 +1,9 @@
 import { describe, test, expect } from "vitest";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkLexicon } from "./check-lexicon";
+import { checkLexicon, coverageReportCheck } from "./check-lexicon";
+import { loadLexiconFromDir } from "./check-lexicon-plugin";
+import type { LexiconPlugin } from "../../lexicon";
 
 // chant #1067 — check-lexicon.ts had zero tests before this issue, despite
 // being the tool meant to gate every lexicon's completeness. This locks in
@@ -32,3 +34,45 @@ describe("checkLexicon", () => {
     expect(matches?.pass).toBe(true);
   });
 });
+
+// chant #1330 — fountain's spec-coverage gate lived only in its own
+// coverage.test.ts, a convention rather than a check-lexicon contract. These
+// lock in the tier-1 check over the plugin's coverageReport() member: red on
+// an unaccounted kind, vacuous pass without the member, red on a throw, and
+// green against the real fountain lexicon in this repo.
+describe("coverageReportCheck", () => {
+  test("fails when the report leaves a kind unaccounted", async () => {
+    const plugin = {
+      coverageReport: async () => ({ unaccountedKinds: ["SandboxRequest"] }),
+    } as unknown as LexiconPlugin;
+    const item = await coverageReportCheck(plugin);
+    expect(item.tier).toBe(1);
+    expect(item.pass).toBe(false);
+    expect(item.detail).toContain("SandboxRequest");
+  });
+
+  test("passes vacuously when the plugin has no coverageReport", async () => {
+    const item = await coverageReportCheck({} as LexiconPlugin);
+    expect(item.pass).toBe(true);
+    expect(item.detail).toBeUndefined();
+  });
+
+  test("fails when the report throws", async () => {
+    const plugin = {
+      coverageReport: async () => {
+        throw new Error("snapshot missing");
+      },
+    } as unknown as LexiconPlugin;
+    const item = await coverageReportCheck(plugin);
+    expect(item.pass).toBe(false);
+    expect(item.detail).toContain("snapshot missing");
+  });
+
+  test("is green on the current fountain lexicon", async () => {
+    const loaded = await loadLexiconFromDir(join(repoRoot, "lexicons", "fountain"));
+    expect(loaded.plugin).toBeDefined();
+    const item = await coverageReportCheck(loaded.plugin);
+    expect(item.pass).toBe(true);
+    expect(item.detail).toBe("all spec kinds accounted for");
+  });
+});

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

@@ -6,6 +6,7 @@ import { auditDocsClassification, auditDocsReachability } from "./check-lexicon-
 import { auditMcpNames, lexiconNameFor } from "./check-lexicon-mcp";
 import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin";
 import { RULE_CATALOG } from "../../audit/catalog";
+import type { LexiconPlugin } from "../../lexicon";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -66,6 +67,45 @@ function countSubdirs(dir: string): number {
     .length;
 }
 
+/**
+ * #1330 — gate on the plugin's own spec-coverage accounting.
+ *
+ * fountain's `coverage.test.ts` asserts `unaccountedKinds == []` in CI, but a
+ * lexicon-local test is a convention, not a check-lexicon contract — the same
+ * class of gap #1342 closed for LSP providers. `coverageReport()` gives core
+ * the one fact to gate on: which upstream spec kinds are neither modeled nor
+ * on the lexicon's exclusion list. A lexicon without the member passes
+ * vacuously, the same conditional shape as the docs-reachability and
+ * Diátaxis checks; a report that throws fails, for the same reason `safeList`
+ * treats a throw as worse than absence.
+ */
+export async function coverageReportCheck(plugin: LexiconPlugin | undefined): Promise<CheckItem> {
+  const report = plugin?.coverageReport;
+  const hasReport = typeof report === "function";
+  let unaccounted: string[] = [];
+  let error: string | undefined;
+  if (hasReport) {
+    try {
+      unaccounted = (await report.call(plugin))?.unaccountedKinds ?? [];
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+    }
+  }
+  return {
+    name: "coverageReport() leaves no spec kind unaccounted",
+    tier: 1,
+    pass: !hasReport || (error === undefined && unaccounted.length === 0),
+    detail:
+      error !== undefined
+        ? `threw: ${error}`
+        : unaccounted.length > 0
+          ? `${unaccounted.length} unaccounted: ${unaccounted.join(", ")}`
+          : hasReport
+            ? "all spec kinds accounted for"
+            : undefined,
+  };
+}
+
 // ── Check runner ─────────────────────────────────────────────────────
 
 /**
@@ -389,6 +429,11 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
         : undefined,
   });
 
+  // #1330 — fountain's spec-coverage gate lived in a lexicon-local vitest
+  // assertion, a convention rather than a check-lexicon contract. The plugin
+  // now states the fact directly via `coverageReport()`.
+  items.push(await coverageReportCheck(plugin));
+
   // ── Tier 2: Recommended ────────────────────────────────────────
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));

package/src/cli/commands/lexicon-surface-diff.ts

@@ -9,6 +9,12 @@
  *
  * The snapshot file is written to `<lexicon-dir>/surface.snapshot.json`.
  * Pass `--update-snapshot` to commit the fresh snapshot after a successful run.
+ *
+ * An update run is exempt from the `surface-matches-snapshot` validate check
+ * and from nothing else (#1825): that check fails on the stale baseline the
+ * run exists to replace, and with an `"always"` gate (#1475) the documented
+ * re-baseline flow would deadlock. Any other failing step still refuses the
+ * write, so a broken generate cannot be baselined.
  */
 
 import { existsSync, readFileSync } from "fs";
@@ -78,6 +84,9 @@ export async function runSurfaceDiff(opts: SurfaceDiffOptions): Promise<RegenRes
     skipLint: opts.skipLint,
     skipExamples: !opts.runExamples,
     pinnedDigestPath: opts.pinnedDigestPath,
+    // The update run skips only the surface-matches-snapshot validate check —
+    // the staleness it is about to fix (#1825).
+    updatingSnapshot: opts.updateSnapshot,
   });
 
   // Update snapshot when requested and the run succeeded

package/src/cli/commands/lexicon-surface-diff.update.test.ts

@@ -0,0 +1,112 @@
+/**
+ * `--update-snapshot` against a failing snapshot gate (#1825).
+ *
+ * Since #1475 the k8s/azure gates run in "always" mode, so a stale baseline
+ * fails validate on every run — including the update run whose whole purpose
+ * is to replace that baseline. These tests run the real pipeline (no mocks)
+ * against a fixture lexicon whose validate script behaves like an "always"
+ * gate: it fails while the committed snapshot is stale, unless the run is
+ * exempted via CHANT_SNAPSHOT_UPDATE.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { runSurfaceDiff } from "./lexicon-surface-diff";
+import { SNAPSHOT_FILENAME } from "../../codegen/lexicon-regen";
+import { parseSnapshot } from "../../codegen/surface-snapshot";
+
+const STALE_SNAPSHOT = JSON.stringify({
+  schemaVersion: 1,
+  generatedAt: "2026-01-01T00:00:00.000Z",
+  entries: { Queue: { kind: "resource", resourceType: "X::Y::Queue", attrs: [], props: [] } },
+});
+
+const GENERATE_SCRIPT = `node -e "
+const fs = require('fs');
+const path = require('path');
+const dir = path.join(process.cwd(), 'src', 'generated');
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, 'lexicon-test.json'), JSON.stringify({Widget:{kind:'resource',resourceType:'X::Y::Widget',attrs:{Id:'Id'}}}));
+fs.writeFileSync(path.join(dir, 'index.d.ts'), 'export declare class Widget { constructor(props: { Name?: string; }); readonly Id: string; }');
+"`;
+
+// Emulates a checkSurfaceSnapshot: "always" gate: fail while the committed
+// snapshot does not describe the generated surface, unless the run carries the
+// update exemption.
+const GATED_VALIDATE_SCRIPT = `node -e "
+if (process.env.CHANT_SNAPSHOT_UPDATE === '1') process.exit(0);
+const fs = require('fs');
+const path = require('path');
+const snap = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'surface.snapshot.json'), 'utf-8'));
+process.exit(snap.entries && snap.entries.Widget ? 0 : 1);
+"`;
+
+function makeLexiconDir(validateScript: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sd-update-"));
+  const pkg = {
+    name: "@intentius/chant-lexicon-test",
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      generate: GENERATE_SCRIPT,
+      validate: validateScript,
+    },
+  };
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2));
+  writeFileSync(join(dir, SNAPSHOT_FILENAME), STALE_SNAPSHOT);
+  return dir;
+}
+
+const baseOpts = { skipBundle: true, skipBuild: true, skipLint: true };
+
+describe("surface-diff --update-snapshot vs. an \"always\" snapshot gate (#1825)", () => {
+  test("without --update-snapshot the stale snapshot still fails validate", async () => {
+    const dir = makeLexiconDir(GATED_VALIDATE_SCRIPT);
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts });
+      expect(result.ok).toBe(false);
+      expect(result.failures.some((f) => f.step === "validate")).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("stale snapshot + healthy codegen: the update succeeds and the snapshot matches after", async () => {
+    const dir = makeLexiconDir(GATED_VALIDATE_SCRIPT);
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts, updateSnapshot: true });
+      expect(result.ok).toBe(true);
+      expect(result.failures).toEqual([]);
+
+      // The baseline now describes the generated surface, not the stale one.
+      const written = parseSnapshot(readFileSync(join(dir, SNAPSHOT_FILENAME), "utf-8"));
+      expect(written.entries.Widget).toBeDefined();
+      expect(written.entries.Queue).toBeUndefined();
+
+      // A second run against the fresh baseline is green with no exemption.
+      const rerun = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts });
+      expect(rerun.ok).toBe(true);
+      expect(rerun.changed).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("stale snapshot + another failing validate check: the update refuses", async () => {
+    // A validate that fails even with the exemption stands in for any check
+    // other than surface-matches-snapshot. The exemption covers only the
+    // staleness check, so a broken generate cannot be baselined.
+    const dir = makeLexiconDir("node -e \"process.exit(1)\"");
+    try {
+      const result = await runSurfaceDiff({ lexiconDir: dir, ...baseOpts, updateSnapshot: true });
+      expect(result.ok).toBe(false);
+      expect(result.failures.some((f) => f.step === "validate")).toBe(true);
+      // The stale baseline is untouched.
+      expect(readFileSync(join(dir, SNAPSHOT_FILENAME), "utf-8")).toBe(STALE_SNAPSHOT);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/commands/lint.ts

@@ -20,6 +20,9 @@ import { GENERATED_MARKER } from "../../discovery/files";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
+import { loadChantConfig, resolveKnowledgeDir } from "../../config";
+import type { LintProjectConfig } from "../../lint/rule";
+import { loadOkfBundle, type OkfBundle } from "../../okf-read";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -447,6 +450,28 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   const config = loadConfig(projectRoot);
   const hasOverrides = config.overrides && config.overrides.length > 0;
 
+  // chant #1221 — the project's chant.config slice for config-aware rules
+  // (COR021 reads `environments` + `ownership`), threaded into every
+  // runLint() call below via LintContext.projectConfig. Best-effort: a
+  // directory with no project config lints with those rules silent.
+  let projectConfig: LintProjectConfig | undefined;
+  // chant #1866 — the loaded OKF knowledge bundle, threaded into
+  // `formatStylish` below so its suppressed section can resolve `okf:`
+  // citations. Best-effort like `projectConfig` above (same
+  // `loadChantConfig` call): a directory with no chant config, or no
+  // `knowledge/` bundle, lints with citations rendering unresolved rather
+  // than a failure — `loadOkfBundle` already treats a missing directory as
+  // an empty bundle.
+  let knowledgeBundle: OkfBundle | undefined;
+  try {
+    const chantConfig = (await loadChantConfig(projectRoot)).config;
+    projectConfig = chantConfig as LintProjectConfig;
+    knowledgeBundle = await loadOkfBundle(resolveKnowledgeDir(chantConfig, projectRoot));
+  } catch {
+    projectConfig = undefined;
+    knowledgeBundle = undefined;
+  }
+
   // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
   const loaded = await loadAllPluginRules(projectRoot);
   let allRules = loaded.rules;
@@ -470,7 +495,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   let diagnostics: LintDiagnostic[];
   let suppressed: Array<LintDiagnostic & { reason?: string }> = [];
   if (options.rules) {
-    const result = await runLint(files, options.rules, undefined, intrinsics);
+    const result = await runLint(files, options.rules, undefined, intrinsics, projectConfig);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   } else if (hasOverrides) {
@@ -478,13 +503,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     for (const file of files) {
       const relativePath = relative(projectRoot, file);
       const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-      const result = await runLint([file], fileRules, ruleOptions, intrinsics);
+      const result = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig);
       diagnostics.push(...result.diagnostics);
       suppressed.push(...result.suppressed);
     }
   } else {
     const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-    const result = await runLint(files, rules, ruleOptions, intrinsics);
+    const result = await runLint(files, rules, ruleOptions, intrinsics, projectConfig);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   }
@@ -518,7 +543,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
 
     // Re-lint after fixes to get updated diagnostics
     if (options.rules) {
-      const postResult = await runLint(files, options.rules, undefined, intrinsics);
+      const postResult = await runLint(files, options.rules, undefined, intrinsics, projectConfig);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     } else if (hasOverrides) {
@@ -527,13 +552,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       for (const file of files) {
         const relativePath = relative(projectRoot, file);
         const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-        const postResult = await runLint([file], fileRules, ruleOptions, intrinsics);
+        const postResult = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig);
         diagnostics.push(...postResult.diagnostics);
         suppressed.push(...postResult.suppressed);
       }
     } else {
       const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-      const postResult = await runLint(files, rules, ruleOptions, intrinsics);
+      const postResult = await runLint(files, rules, ruleOptions, intrinsics, projectConfig);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     }
@@ -575,7 +600,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       break;
     case "stylish":
     default:
-      output = formatStylish(diagnostics);
+      output = formatStylish(diagnostics, suppressed, knowledgeBundle);
       break;
   }
 

package/src/cli/handlers/explain.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
@@ -90,4 +90,73 @@ describe("runExplain", () => {
     const code = await runExplain(ctx({ format: "okf" }));
     expect(code).toBe(1);
   });
+
+  describe("knowledge sections (#1867)", () => {
+    let projectDir: string;
+
+    beforeEach(async () => {
+      projectDir = await mkdtemp(join(tmpdir(), "chant-explain-knowledge-"));
+    });
+
+    afterEach(async () => {
+      await rm(projectDir, { recursive: true, force: true });
+    });
+
+    test("omits the Knowledge section cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      expect(logSpy.mock.calls[0][0]).not.toContain("## Knowledge");
+    });
+
+    test("json omits the knowledge field cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toBeUndefined();
+    });
+
+    test("markdown includes a per-entity Knowledge section for bound concepts", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      const out = logSpy.mock.calls[0][0] as string;
+      expect(out).toContain("## Knowledge");
+      expect(out).toContain("### `vpc`");
+      expect(out).toContain("decision: Public VPC (`decisions/public-vpc.md`)");
+      expect(out).not.toContain("### `subnet`");
+    });
+
+    test("json carries type/title/path per bound entity", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toEqual({
+        vpc: [{ type: "decision", title: "Public VPC", path: "decisions/public-vpc.md" }],
+      });
+    });
+
+    test("--format okf output is untouched by a present bundle", async () => {
+      await mkdir(join(projectDir, "knowledge"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "note.md"),
+        "---\ntype: decision\ntitle: Note\nbinds: vpc\n---\nBody.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "okf" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(Object.keys(parsed.files).sort()).toEqual(["gcp/subnet.md", "gcp/vpc.md", "index.md"]);
+    });
+  });
 });

package/src/cli/handlers/graph.ts

@@ -8,7 +8,7 @@ import { mergeProjectOps } from "../../graph-ops";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
-import { loadChantConfig, environmentNames, loadChantConfigUpward, type ChantConfig } from "../../config";
+import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, loadChantConfigUpward, type ChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { applyDetail, detailInertNotice, type DetailLevel } from "../../graph-detail";
 import { applyLens, parseLens } from "../../graph-lens";
@@ -77,7 +77,7 @@ async function graphBuildParams(
 async function graphBuildRootContributors(
   ctx: CommandContext,
   projectPath: string,
-): Promise<Array<() => Promise<import("../../lexicon").BuildRootContribution>>> {
+): Promise<Array<import("../../lexicon").BuildRootContributor>> {
   const { config, configPath } = await loadChantConfigUpward(projectPath).catch(
     () => ({ config: {} as ChantConfig, configPath: undefined }),
   );
@@ -109,7 +109,7 @@ async function graphBuildRootContributors(
  */
 async function mergeGraphBuildRoots(
   entities: Map<string, import("../../declarable").Declarable>,
-  contributors: Array<() => Promise<import("../../lexicon").BuildRootContribution>>,
+  contributors: Array<import("../../lexicon").BuildRootContributor>,
 ): Promise<boolean> {
   if (contributors.length === 0) return true;
   const merged = await mergeBuildRootEntities(entities, contributors);
@@ -210,7 +210,7 @@ async function runGraphLive(
   // observation plugins — load them here, mirroring the lifecycle handlers.
   const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
   const declaredEnvNames = environmentNames(config.environments);
-  if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
+  if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
       message: `Unknown environment "${environment}"`,
       hint: `Defined environments: ${declaredEnvNames.join(", ")}`,