@intentius/chant 0.46.0 → 0.49.0

package/src/cli/handlers/lifecycle.ts

@@ -18,6 +18,8 @@ import {
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
+import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
+import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
 import {
   formatUnobserved,
   mergeObservations,
@@ -358,6 +360,10 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   // committed set. Absent is the normal state (nothing accepted yet).
   const baseline = args.live ? await readObservationBaseline(environment) : null;
   const accepted: Record<string, DeviationToAccept[]> = {};
+  // Effect receipts across every target's build (#1833) — `--update-baseline`
+  // refuses to accept drift on them (the effect step is their only writer),
+  // and recognition is marker-based so materialized lexicon rows are caught.
+  const receiptEntities = new Set<string>();
 
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), so `--live` is self-sufficient even when the ambient shell never
@@ -430,6 +436,9 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
         for (const [lexicon, deviations] of Object.entries(r.toAccept)) {
           (accepted[lexicon] ??= []).push(...deviations);
         }
+        if (args.updateBaseline) {
+          for (const name of collectEffectReceipts(buildResult.entities).keys()) receiptEntities.add(name);
+        }
         if (json) {
           if (target.stack) perStackJson[target.stack] = r.byLexicon;
           else combinedLexiconsJson = r.byLexicon;
@@ -443,7 +452,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
     // accepted, so it stops re-alerting. Runs before the summary lines so the
     // "no drift" verdict below still describes the run that produced it.
     if (args.live && args.updateBaseline) {
-      await recordAcceptedBaseline(environment, baseline, accepted, json);
+      await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities);
     }
 
     if (args.live) {
@@ -495,6 +504,7 @@ async function recordAcceptedBaseline(
   existing: ObservationBaseline | null,
   accepted: Record<string, DeviationToAccept[]>,
   json: boolean,
+  receipts?: ReadonlySet<string>,
 ): Promise<void> {
   const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
   if (total === 0) {
@@ -505,11 +515,14 @@ async function recordAcceptedBaseline(
     }
     return;
   }
-  let next = existing ?? emptyBaseline(environment);
-  for (const [lexicon, deviations] of Object.entries(accepted)) {
-    next = acceptDeviations(next, lexicon, deviations);
-  }
   try {
+    // `acceptDeviations` throws on an effect-receipt deviation (#1833) —
+    // inside the try so the refusal reaches the operator as a formatted
+    // error, with no baseline written at all.
+    let next = existing ?? emptyBaseline(environment);
+    for (const [lexicon, deviations] of Object.entries(accepted)) {
+      next = acceptDeviations(next, lexicon, deviations, { receipts });
+    }
     await writeObservationBaseline(next);
     const pushed = await pushLifecycle();
     if (!json) {
@@ -520,7 +533,7 @@ async function recordAcceptedBaseline(
     }
   } catch (err) {
     console.error(formatError({
-      message: `--update-baseline: could not write the baseline — ${err instanceof Error ? err.message : String(err)}`,
+      message: `--update-baseline: baseline not updated — ${err instanceof Error ? err.message : String(err)}`,
     }));
   }
 }
@@ -1126,6 +1139,15 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   const merged: ChangeSet = { env: environment, entries: [] };
   let checked = 0;
 
+  // Effect receipts (#1832): declared, diffed, and observed like any resource,
+  // but observe-only to the generic apply path — the plan compares live value
+  // to resolved expectation and proposes the fire, never a create/update.
+  const receipts = collectEffectReceipts(buildResult.entities);
+  const receiptReadings = new Map<string, ReceiptReading>();
+  // Every lexicon's observed resources merged, for resolving a receipt's
+  // reference inputs against observed values / stack outputs at plan time.
+  const allObservedResources: Record<string, ResourceMetadata> = {};
+
   // #1166 — same self-sufficiency as `chant graph --live`: an environment can
   // declare its own endpoint, applied here unless the ambient shell already
   // set it. `chant lifecycle plan` is always a live read (no `--live` flag of
@@ -1156,11 +1178,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
       const declared = new Set<string>();
       const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
       for (const [name, entity] of buildResult.entities) {
-        if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
+        // A receipt has no `props` payload of its own but is declared, diffed,
+        // and observed like any resource (#1832) — it joins the declared axis
+        // so its lexicon's observation can confirm presence or absence.
+        if (entity.lexicon === lexiconName && (isResourceDeclarable(entity) || isEffectReceipt(entity))) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (isResourceDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }
@@ -1185,6 +1210,37 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         ...(args.namespace ? { namespace: args.namespace } : {}),
       });
 
+      Object.assign(allObservedResources, observed.resources);
+      for (const [receiptName, receipt] of receipts) {
+        if (receipt.lexicon !== lexiconName) continue;
+        const live = observed.resources[receiptName];
+        const hole = observed.unobserved[receiptName];
+        if (live) {
+          receiptReadings.set(receiptName, {
+            observed: true,
+            present: true,
+            value: readReceiptValue(live.attributes),
+            type: live.type,
+            ...(live.physicalId ? { physicalId: live.physicalId } : {}),
+            lexicon: lexiconName,
+          });
+        } else if (hole) {
+          receiptReadings.set(receiptName, {
+            observed: false,
+            present: false,
+            lexicon: lexiconName,
+            ...(hole.type ? { type: hole.type } : {}),
+            unobservedReason: hole.reason,
+            ...(hole.detail ? { unobservedDetail: hole.detail } : {}),
+          });
+        } else {
+          // Neither returned nor named unobserved: the lexicon looked and
+          // confirmed the receipt absent — the same claim the change set
+          // reads off a bare observation (#1089).
+          receiptReadings.set(receiptName, { observed: true, present: false, lexicon: lexiconName });
+        }
+      }
+
       const content = await readSnapshot(environment, lexiconName);
       const observedThen = content ? (JSON.parse(content) as LifecycleSnapshot).resources : undefined;
 
@@ -1214,6 +1270,16 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // Receipt classification (#1832): live value vs resolved expectation.
+  // Absent/stale proposes the fire; unobservable is a loud hole; whatever the
+  // generic classification proposed for a receipt (a create, a delete) is
+  // replaced — the effect step is the sole writer, and a receipt is never a
+  // prune candidate.
+  if (receipts.size > 0) {
+    const receiptEntries = planReceipts(receipts, receiptReadings, observedValueResolver(allObservedResources));
+    mergeReceiptEntries(merged, receipts, receiptEntries);
+  }
+
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
@@ -1250,7 +1316,7 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
  * with the requested env identity. Stateless — live markers only, no build, no
  * snapshot. Without `--yes` nothing is deleted; with it the planned set is
  * executed per lexicon with one bounded retry pass over failures, and every
- * candidate's outcome is reported (deleted / failed / not-prunable / skipped —
+ * candidate's outcome is reported (deleted / failed / not-prunable / retained / skipped —
  * never silence). A production-like environment name additionally requires an
  * interactive confirmation, or `--confirm-prod` non-interactively.
  */
@@ -1410,10 +1476,11 @@ export async function runLifecycleTeardown(ctx: CommandContext): Promise<number>
     }
   }
 
-  const counts = { deleted: 0, failed: 0, "not-prunable": 0, skipped: 0 };
+  const counts = { deleted: 0, failed: 0, "not-prunable": 0, retained: 0, skipped: 0 };
   for (const o of report.outcomes) counts[o.outcome]++;
   console.log(
-    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ${counts.skipped} skipped`,
+    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ` +
+    `${counts.retained} retained, ${counts.skipped} skipped`,
   );
 
   if (report.unimplemented.length > 0) {
@@ -1421,6 +1488,12 @@ export async function runLifecycleTeardown(ctx: CommandContext): Promise<number>
       message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
     }));
   }
+  if (counts.retained > 0) {
+    console.error(formatWarning({
+      message: `${counts.retained} resource(s) retained — owned by this env but deliberately kept (generated-once secrets are never swept). ` +
+        `The environment is NOT clean while they exist; delete them explicitly (e.g. kubectl delete) if you mean to.`,
+    }));
+  }
   if (plan.holes.length > 0) {
     console.error(formatWarning({
       message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",

package/src/cli/mcp/resource-handlers.ts

@@ -1,10 +1,13 @@
-import { resolve } from "node:path";
+import { resolve, join, dirname } from "node:path";
+import { readFile } from "node:fs/promises";
 import type { ResourceDefinition } from "./types";
 import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
 import { resolveWorkflowId } from "../handlers/run-client";
+import { loadOkfBundle } from "../../okf-read";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../config";
 
 type PluginResourceEntry = { definition: ResourceDefinition; handler: () => Promise<string> };
 
@@ -42,6 +45,12 @@ export const coreResourceDefinitions: ResourceDefinition[] = [
     description: "Latest run state for a named Op",
     mimeType: "application/json",
   },
+  {
+    uri: "chant://knowledge",
+    name: "Knowledge bundle",
+    description: "The project's OKF knowledge bundle (#1864, #1059): index.md and every authored concept, empty when no bundle exists",
+    mimeType: "application/json",
+  },
   {
     uri: "chant://state/{environment}",
     name: "State (all lexicons)",
@@ -122,6 +131,34 @@ export async function handleResourcesRead(
     };
   }
 
+  // Authored knowledge (#1867, #1864, design #1059): same bundle the CLI's
+  // `chant explain` reads, over MCP — the resource path has no local
+  // filesystem, so this is the only way an MCP client sees the `knowledge/`
+  // directory's contents at all. Resolved from cwd, matching every other
+  // path-less resource here (`chant://ops`, `chant://state/...`). A missing
+  // bundle is not an error — `loadOkfBundle` already treats it as empty, and
+  // a missing `index.md` reads as `index: null` rather than throwing.
+  if (uri === "chant://knowledge") {
+    const cwd = resolve(".");
+    const loaded = await loadChantConfigUpward(cwd);
+    const projectRoot = loaded.configPath ? dirname(loaded.configPath) : cwd;
+    const dir = resolveKnowledgeDir(loaded.config, projectRoot);
+    const bundle = await loadOkfBundle(dir);
+    let index: string | null = null;
+    try {
+      index = await readFile(join(dir, "index.md"), "utf8");
+    } catch {
+      index = null;
+    }
+    return {
+      contents: [{
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify({ dir, index, concepts: bundle.concepts }, null, 2),
+      }],
+    };
+  }
+
   // Op resources
   if (uri === "chant://ops") {
     const { ops } = await discoverOps();

package/src/cli/mcp/server.test.ts

@@ -590,6 +590,7 @@ describe("McpServer", () => {
       expect(uris).toContain("chant://ops");
       expect(uris).toContain("chant://ops/{name}/runs");
       expect(uris).toContain("chant://ops/{name}/runs/latest");
+      expect(uris).toContain("chant://knowledge");
 
       // Each resource has required fields
       for (const resource of result.resources) {
@@ -735,6 +736,62 @@ describe("McpServer", () => {
         expect(data.error).toBeDefined();
       });
     });
+
+    describe("chant://knowledge", () => {
+      test("empty gracefully when no bundle exists", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string; mimeType: string }> };
+          expect(result.contents[0].mimeType).toBe("application/json");
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBeNull();
+          expect(data.concepts).toEqual([]);
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+
+      test("serves the bundle index and concepts when present", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          await mkdir(join(testDir, "knowledge", "decisions"), { recursive: true });
+          await writeFile(join(testDir, "knowledge", "index.md"), "# Knowledge index\n");
+          await writeFile(
+            join(testDir, "knowledge", "decisions", "public-assets.md"),
+            "---\ntype: decision\ntitle: Public assets\nbinds: bucket\n---\nBody text.\n",
+          );
+
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string }> };
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBe("# Knowledge index\n");
+          expect(data.concepts).toHaveLength(1);
+          expect(data.concepts[0]).toMatchObject({
+            path: "decisions/public-assets.md",
+            type: "decision",
+            title: "Public assets",
+            binds: ["bucket"],
+          });
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -1157,7 +1214,7 @@ describe("McpServer", () => {
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
-      expect(resources).toHaveLength(7);
+      expect(resources).toHaveLength(8);
     });
 
     test("server with empty plugins array works", async () => {

package/src/cli/mcp/tools/explain.ts

@@ -1,6 +1,19 @@
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { discover } from "../../../discovery/index";
 import { buildOkfBundle, OKF_VERSION } from "../../../okf";
+import { loadOkfBundle, bindConcepts, type OkfConcept } from "../../../okf-read";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../../config";
+
+/** One bound concept as surfaced in an explain knowledge section — the trio the #1867 design calls for, not the full {@link OkfConcept}. */
+export interface ExplainKnowledgeEntry {
+  type: string;
+  title?: string;
+  path: string;
+}
+
+function toKnowledgeEntry(concept: OkfConcept): ExplainKnowledgeEntry {
+  return { type: concept.type, title: concept.title, path: concept.path };
+}
 
 /**
  * Explain tool definition for MCP
@@ -46,6 +59,25 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     };
   }
 
+  // Authored knowledge (#1867, design #1059): bind the project's OKF bundle
+  // (if any) to the discovered entities and carry each bound concept's
+  // type/title/path into the summary. A project with no `knowledge/` yet
+  // binds nothing — `bound` is empty — so the section is omitted below
+  // rather than rendered empty; this is the CLI and MCP tool's one shared
+  // code path, so both surfaces match by construction.
+  // `loadChantConfigUpward` walks up from `infraPath` (chant #1117) — a
+  // `chant explain src/<stack>` two levels below `chant.config.ts` must find
+  // the same `knowledge/` a `chant explain .` at the root would, matching
+  // `build.ts`'s `configDir` derivation for the same reason.
+  const loaded = await loadChantConfigUpward(infraPath);
+  const projectRoot = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+  const knowledgeDir = resolveKnowledgeDir(loaded.config, projectRoot);
+  const bundle = await loadOkfBundle(knowledgeDir);
+  const { bound } = bindConcepts(bundle, result.entities);
+  const knowledge = new Map<string, ExplainKnowledgeEntry[]>(
+    Array.from(bound.entries()).map(([name, concepts]) => [name, concepts.map(toKnowledgeEntry)]),
+  );
+
   // Group entities by lexicon and kind
   const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
 
@@ -89,7 +121,11 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
   };
 
   if (format === "json") {
-    return summary;
+    // Omitted entirely when no entity bound a concept — "cleanly absent" per
+    // #1867's AC, not an empty `{}`.
+    return knowledge.size > 0
+      ? { ...summary, knowledge: Object.fromEntries(knowledge) }
+      : summary;
   }
 
   // Markdown format
@@ -133,6 +169,19 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     lines.push("");
   }
 
+  if (knowledge.size > 0) {
+    lines.push("## Knowledge");
+    lines.push("");
+    for (const [name, entries] of knowledge) {
+      lines.push(`### \`${name}\``);
+      for (const entry of entries) {
+        const title = entry.title ? `${entry.title} ` : "";
+        lines.push(`- ${entry.type || "concept"}: ${title}(\`${entry.path}\`)`);
+      }
+      lines.push("");
+    }
+  }
+
   if (result.errors.length > 0) {
     lines.push("## Errors");
     lines.push("");

package/src/cli/plugins.ts

@@ -106,10 +106,12 @@ export function collectBuildRootContributors(
   plugins: readonly LexiconPlugin[] | undefined,
   config: Record<string, unknown>,
   projectRoot: string,
-): Array<() => Promise<import("../lexicon").BuildRootContribution>> {
+): Array<import("../lexicon").BuildRootContributor> {
   return (plugins ?? [])
     .filter((plugin) => typeof plugin.buildRoots === "function")
-    .map((plugin) => () => plugin.buildRoots!({ projectRoot, config }));
+    // `entities` is not bindable here — discovery has not run — so the merge
+    // hands it in when it calls the closure (#1828 / SOPS provenance).
+    .map((plugin) => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
 }
 
 /**

package/src/cli/reporters/stylish.test.ts

@@ -1,6 +1,17 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { formatStylish, formatSummary, formatJson, formatSarif } from "./stylish";
 import type { LintDiagnostic, LintRule } from "../../lint/rule";
+import type { OkfBundle, OkfConcept } from "../../okf-read";
+
+function concept(overrides: Partial<OkfConcept> & { path: string }): OkfConcept {
+  return {
+    type: "decision",
+    binds: [],
+    frontmatter: {},
+    body: "",
+    ...overrides,
+  };
+}
 
 describe("formatStylish", () => {
   const originalNoColor = process.env.NO_COLOR;
@@ -123,6 +134,149 @@ describe("formatStylish", () => {
   });
 });
 
+describe("formatStylish suppressed section (#1866, design #1059)", () => {
+  beforeEach(() => {
+    process.env.NO_COLOR = "1";
+  });
+  afterEach(() => {
+    delete process.env.NO_COLOR;
+  });
+
+  const suppressedDiag: LintDiagnostic & { reason?: string } = {
+    file: "src/storage.ts",
+    line: 12,
+    column: 1,
+    ruleId: "AWS021",
+    severity: "warning",
+    message: "Bucket ACL is public-read",
+  };
+
+  test("no section when there are no suppressed diagnostics", () => {
+    const result = formatStylish([], []);
+    expect(result).not.toContain("Suppressed");
+  });
+
+  test("renders a Suppressed section when suppressed diagnostics exist", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "backwards compat" }]);
+
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("src/storage.ts");
+    expect(result).toContain("AWS021");
+    expect(result).toContain("backwards compat");
+  });
+
+  test("renders the section even when there are no active diagnostics", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("Suppressed");
+    // No active errors/warnings were counted from a suppressed diagnostic
+    expect(result).toContain("No problems found");
+  });
+
+  test("an okf: citation resolves to the concept's title and bundle-relative path", () => {
+    const bundle: OkfBundle = {
+      concepts: [
+        concept({
+          path: "decisions/public-assets.md",
+          title: "Public asset bucket stays world-readable",
+        }),
+      ],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public asset bucket stays world-readable");
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("okf:/decisions/public-assets.md");
+  });
+
+  test("also resolves a citation without a leading slash", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public assets");
+  });
+
+  test("an unresolvable citation prints the raw reason with a warning", () => {
+    const bundle: OkfBundle = { concepts: [] };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/does-not-exist.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("okf:/decisions/does-not-exist.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("an okf: citation with no bundle loaded prints the raw reason with a warning", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }]);
+
+    expect(result).toContain("okf:/decisions/public-assets.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("a plain (non-okf) reason renders as-is, unaffected by a loaded bundle", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "grandfathered, see #412" }], bundle);
+
+    expect(result).toContain("grandfathered, see #412");
+    expect(result).not.toContain("Public assets");
+  });
+
+  test("a suppressed diagnostic with no reason still renders", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("AWS021");
+    expect(result).toContain("suppressed");
+  });
+
+  test("active diagnostics and the suppressed section coexist", () => {
+    const active: LintDiagnostic = {
+      file: "src/other.ts",
+      line: 1,
+      column: 1,
+      ruleId: "COR001",
+      severity: "error",
+      message: "Active problem",
+    };
+
+    const result = formatStylish([active], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    });
+
+    expect(result).toContain("src/other.ts");
+    expect(result).toContain("Active problem");
+    expect(result).toContain("1 error");
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("Public assets");
+  });
+
+  test("a title-less resolved concept falls back to its path as the label", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], bundle);
+
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("unresolved");
+  });
+});
+
 describe("formatSummary", () => {
   beforeEach(() => {
     process.env.NO_COLOR = "1";