@intentius/chant 0.46.0 → 0.50.0

package/src/lint/pipeline-change-gate.ts

@@ -0,0 +1,153 @@
+/**
+ * The pipeline-change gate class (#1569): changes to the pipeline itself
+ * route to a stricter gate.
+ *
+ * The honest concession in the PR-flow teardown (rubric-product-research,
+ * 06-objections §1): chant Ops have a `shell` step, so a governed plane is
+ * not automatically immune to "the change edits the machinery that applies
+ * changes." What chant *can* claim — and a plain PR flow structurally cannot
+ * — is that pipeline changes are distinguishable: a composition is data over
+ * a bounded verb registry, and the COMP rules already police the escape
+ * hatches (COMP006 — every `shell` step carries a declared reason;
+ * COMP005 — no noun-shaped escape hatches, `./rules/comp/`). What was missing
+ * was the routing: nothing classified a change as "touches the pipeline" and
+ * required a stricter gate for it, so a change to a composition rode through
+ * the same gate as a replica-count bump.
+ *
+ * This is the cheap first cut #1569 asks for: the registry-only predicate.
+ * A composition that contains only registry verbs is ordinary; a `shell`
+ * step (the deliberate escape hatch) or a change to the set of verbs a
+ * composition invokes trips the stricter class. comp005/comp006 already make
+ * both decidable from the text — this module reuses the same walk
+ * (`./rules/comp/support.ts`) rather than re-deriving it.
+ *
+ * Like #1568's `evaluateUnobservedGate`
+ * (../lifecycle/unobserved-gate.ts), this is a reusable predicate, not a
+ * runtime: classify a change and get back a verdict; the caller (a
+ * `lint.policies` check routed through `policyGate`, an Op step, #1487's
+ * gate-as-fact once it lands) decides what "stricter" means in its own
+ * context. The stricter class composes with #1487's principle that
+ * destructive verbs always wait for a person — pipeline changes are the
+ * second category that should never free-run, because they change what
+ * "gated" means for everything after them. That is why the default policy
+ * below is `"human-always"`, not `"stricter-gate"`.
+ */
+import type { Component } from "../components/component";
+import { STARTER_VERB_FAMILIES } from "../components/starter-plugin";
+import { walkComponent } from "./rules/comp/support";
+
+/**
+ * Fallback registry when no project registry is supplied: core's own starter
+ * verbs, the same fallback COMP005 uses for a direct unit test
+ * (`./rules/comp/comp005-capability-kind-is-noun.ts`). A real `chant lint` /
+ * gate run passes the project's resolved `knownKinds` (core's starter set
+ * plus the active lexicons' leaves) so a real project's cloud verbs are never
+ * mistaken for an out-of-registry escape hatch.
+ */
+const CORE_STARTER_KINDS: ReadonlySet<string> = new Set(Object.values(STARTER_VERB_FAMILIES).flat());
+
+/** Why a composition (or a change to one) tripped the pipeline-change class. */
+export type PipelineChangeReason =
+  | { kind: "shell-step"; phaseName: string }
+  | { kind: "unregistered-verb"; stepKind: string; phaseName: string }
+  | { kind: "verb-set-changed"; added: string[]; removed: string[] };
+
+export interface PipelineChangeClassification {
+  /** True when any reason below applies. */
+  pipelineChange: boolean;
+  reasons: PipelineChangeReason[];
+}
+
+/** Every non-gate step kind a component's composition invokes, across `deploy` and `rollback` (nested fan-out phases included, via `walkComponent`). `gate` steps are excluded — they are not a capability verb. */
+export function componentVerbSet(component: Component): Set<string> {
+  const { steps } = walkComponent(component);
+  return new Set(steps.map((s) => s.step.kind));
+}
+
+/**
+ * Classify a single component's composition (the "cheap first cut", no
+ * before/after needed): a `shell` step trips the class unconditionally — it
+ * is the escape hatch by construction (COMP006) — and any step whose `kind`
+ * is outside `knownKinds` trips it too, since an unregistered verb is,
+ * structurally, the same kind of hole a `shell` step is: something the
+ * bounded registry does not account for.
+ */
+export function classifyComponentPipelineChange(
+  component: Component,
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeClassification {
+  const knownKinds = opts?.knownKinds ?? CORE_STARTER_KINDS;
+  const { steps } = walkComponent(component);
+
+  const reasons: PipelineChangeReason[] = [];
+  for (const { step, phaseName } of steps) {
+    if (step.kind === "shell") {
+      reasons.push({ kind: "shell-step", phaseName });
+    } else if (!knownKinds.has(step.kind)) {
+      reasons.push({ kind: "unregistered-verb", stepKind: step.kind, phaseName });
+    }
+  }
+
+  return { pipelineChange: reasons.length > 0, reasons };
+}
+
+/**
+ * Classify a *change* to a component's composition between two revisions
+ * (#1569's "add or modify a shell step ... or the composition graph
+ * itself"): on top of `classifyComponentPipelineChange`'s single-composition
+ * check on `after`, a change also trips the class when the verb set itself
+ * changed — a verb added or removed changes what the composition can invoke,
+ * which is the routing signal even when every individual verb, before and
+ * after, is registry-clean. `before: undefined` (a brand-new component) never
+ * reports a verb-set change — there is nothing to diff against, and the
+ * single-composition check already covers a new component's own shell/
+ * unregistered-verb findings.
+ */
+export function classifyPipelineChange(
+  before: Component | undefined,
+  after: Component,
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeClassification {
+  const base = classifyComponentPipelineChange(after, opts);
+  if (!before) return base;
+
+  const beforeVerbs = componentVerbSet(before);
+  const afterVerbs = componentVerbSet(after);
+  const added = [...afterVerbs].filter((v) => !beforeVerbs.has(v)).sort();
+  const removed = [...beforeVerbs].filter((v) => !afterVerbs.has(v)).sort();
+
+  if (added.length === 0 && removed.length === 0) return base;
+
+  return {
+    pipelineChange: true,
+    reasons: [...base.reasons, { kind: "verb-set-changed", added, removed }],
+  };
+}
+
+/**
+ * How the gate routes a classified pipeline change.
+ *
+ * - `"human-always"` (the recommended default — see this module's doc
+ *   comment) — a pipeline change never free-runs, mirroring #1487's "a
+ *   destructive verb always waits for a person."
+ * - `"stricter-gate"` — route to a named stricter gate class rather than
+ *   requiring a person on every run; the caller supplies what "stricter"
+ *   means (an additional approval, a narrower blast-radius budget, ...).
+ */
+export type PipelineChangeGatePolicy = "stricter-gate" | "human-always";
+
+export interface PipelineChangeGateVerdict extends PipelineChangeClassification {
+  /** What the policy says to do about it. `"none"` when the change is not a pipeline change at all. */
+  route: PipelineChangeGatePolicy | "none";
+}
+
+/** Evaluate a component composition change against a routing policy. Pure — no I/O. */
+export function evaluatePipelineChangeGate(
+  before: Component | undefined,
+  after: Component,
+  policy: PipelineChangeGatePolicy = "human-always",
+  opts?: { knownKinds?: ReadonlySet<string> },
+): PipelineChangeGateVerdict {
+  const classification = classifyPipelineChange(before, after, opts);
+  return { ...classification, route: classification.pipelineChange ? policy : "none" };
+}

package/src/lint/post-synth.test.ts

@@ -145,3 +145,100 @@ describe("isPostSynthCheck", () => {
 // chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
 // pass over `PostSynthDiagnostic`s) is tested in `./config.test.ts`, where the
 // function itself now lives — see `./config.ts`'s doc comment for why.
+
+// ── chant #975 — ctx.docs: lazy, memoized, shared across every check ───────
+describe("ctx.docs (chant #975)", () => {
+  /** A Map subclass that counts how many times it was iterated — the only
+   *  way `parseOutputDocs` reads its outputs — so the tests below can prove
+   *  "parsed once" without reaching into module internals. */
+  class CountingOutputs extends Map<string, string> {
+    iterations = 0;
+    [Symbol.iterator](): IterableIterator<[string, string]> {
+      this.iterations++;
+      return super[Symbol.iterator]();
+    }
+  }
+
+  test("is not computed until first accessed", () => {
+    const outputs = new CountingOutputs([["k8s", "kind: Namespace"]]);
+    const check: PostSynthCheck = {
+      id: "PS-DOCS-1",
+      description: "never touches ctx.docs",
+      check() {
+        return [];
+      },
+    };
+    runPostSynthChecks([check], createBuildResult({ outputs: outputs as never }));
+    expect(outputs.iterations).toBe(0);
+  });
+
+  test("is parsed exactly once even when read by multiple checks", () => {
+    const outputs = new CountingOutputs([
+      ["k8s", "apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ns-a"],
+    ]);
+    let seenByFirst: unknown;
+    let seenBySecond: unknown;
+    const checks: PostSynthCheck[] = [
+      {
+        id: "PS-DOCS-2A",
+        description: "reads ctx.docs once",
+        check(ctx) {
+          seenByFirst = ctx.docs;
+          return [];
+        },
+      },
+      {
+        id: "PS-DOCS-2B",
+        description: "reads ctx.docs again, and a second time in the same check",
+        check(ctx) {
+          seenBySecond = ctx.docs;
+          void ctx.docs; // a second read within the same check — still no reparse
+          return [];
+        },
+      },
+    ];
+    runPostSynthChecks(checks, createBuildResult({ outputs: outputs as never }));
+    expect(outputs.iterations).toBe(1);
+    // Every reader gets the exact same array instance, not an equal copy.
+    expect(seenByFirst).toBe(seenBySecond);
+  });
+
+  test("parses ctx.outputs into the expected OutputDoc shape", () => {
+    const outputs = new Map<string, string>([
+      ["k8s", "apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ns-a"],
+    ]);
+    const check: PostSynthCheck = {
+      id: "PS-DOCS-3",
+      description: "reads a manifest field off ctx.docs",
+      check(ctx) {
+        const doc = (ctx.docs ?? [])[0];
+        return [
+          {
+            checkId: "PS-DOCS-3",
+            severity: "info",
+            message: `kind=${(doc.value as { kind?: string }).kind}`,
+          },
+        ];
+      },
+    };
+    const diags = runPostSynthChecks([check], createBuildResult({ outputs: outputs as never }));
+    expect(diags[0].message).toBe("kind=Namespace");
+  });
+
+  test("two independent runPostSynthChecks calls each get their own cache", () => {
+    const outputsA = new CountingOutputs([["k8s", "kind: Namespace"]]);
+    const outputsB = new CountingOutputs([["k8s", "kind: Deployment"]]);
+    const reader: PostSynthCheck = {
+      id: "PS-DOCS-4",
+      description: "reads ctx.docs",
+      check(ctx) {
+        void ctx.docs;
+        return [];
+      },
+    };
+    runPostSynthChecks([reader], createBuildResult({ outputs: outputsA as never }));
+    runPostSynthChecks([reader], createBuildResult({ outputs: outputsB as never }));
+    expect(outputsA.iterations).toBe(1);
+    expect(outputsB.iterations).toBe(1);
+  });
+});

package/src/lint/post-synth.ts

@@ -1,6 +1,9 @@
 import type { Declarable } from "../declarable";
 import type { SerializerResult } from "../serializer";
 import type { Severity } from "./rule";
+import { parseOutputDocs, type OutputDoc } from "./output-docs";
+
+export { parseOutputDocs, pick, get, type OutputDoc } from "./output-docs";
 
 /**
  * Context provided to post-synthesis checks.
@@ -16,6 +19,25 @@ export interface PostSynthContext {
    * e.g. "no public buckets in prod". Undefined when no environment is set.
    */
   env?: string;
+  /**
+   * Parsed output documents (chant #975) — `ctx.outputs` run through
+   * `parseOutputDocs` once and cached. A lazy `readonly` getter, not a plain
+   * field: computed on first access and shared across every check in the
+   * run, so a check that only reads `entities` pays nothing, and no two
+   * checks re-parse the same YAML/JSON. See `./output-docs.ts`.
+   *
+   * Optional at the type level — NOT because it can be absent from a real
+   * build. Every context chant itself constructs (`runPostSynthChecks`
+   * below, `@intentius/chant-test-utils`'s `createPostSynthContext` and
+   * `makePostSynthCtx*`) wires it up via `createDocsAccessor` and it is
+   * always present there. It is typed optional only so the many lexicon
+   * tests that build a `PostSynthContext` object literal by hand (predating
+   * this field) keep compiling unchanged, per this issue's own "existing
+   * checks compile unchanged" constraint — a new check that wants `ctx.docs`
+   * should still get a real array from every context chant builds; guard
+   * with `ctx.docs ?? []` only when a context's provenance is unknown.
+   */
+  readonly docs?: OutputDoc[];
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -26,6 +48,25 @@ export interface PostSynthContext {
   };
 }
 
+/**
+ * Build the lazy, memoized `docs` accessor shared by `runPostSynthChecks`
+ * (below) and `@intentius/chant-test-utils`'s `createPostSynthContext` — the
+ * two places a `PostSynthContext` gets constructed. Returns a zero-arg
+ * function suitable for a `get docs()` object-literal accessor; the first
+ * call parses, every later call returns the same cached array.
+ */
+export function createDocsAccessor(
+  outputs: Map<string, string | SerializerResult>,
+): () => OutputDoc[] {
+  let cached: OutputDoc[] | undefined;
+  return () => {
+    if (cached === undefined) {
+      cached = parseOutputDocs(outputs);
+    }
+    return cached;
+  };
+}
+
 /**
  * Extract the primary content string from a serializer output.
  */
@@ -33,6 +74,21 @@ export function getPrimaryOutput(output: string | SerializerResult): string {
   return typeof output === "string" ? output : output.primary;
 }
 
+/**
+ * Extract the ADDITIONAL files from a serializer output — everything
+ * {@link getPrimaryOutput} discards.
+ *
+ * Every post-synth check shipped before this one reads the primary output
+ * only, which means a sidecar file (a nested stack template, committed SOPS
+ * ciphertext) is invisible to all of them. That is the right default — the
+ * primary output is what appliers read — but a rule ABOUT a sidecar has to
+ * be able to see it, and `PostSynthContext.outputs` has carried the data all
+ * along. WK8504 (k8s) is the first caller.
+ */
+export function getAdditionalFiles(output: string | SerializerResult): Record<string, string> {
+  return typeof output === "string" ? {} : (output.files ?? {});
+}
+
 /**
  * A diagnostic from a post-synthesis check.
  *
@@ -100,11 +156,15 @@ export function runPostSynthChecks(
   buildResult: PostSynthContext["buildResult"],
   env?: string,
 ): PostSynthDiagnostic[] {
+  const getDocs = createDocsAccessor(buildResult.outputs);
   const ctx: PostSynthContext = {
     outputs: buildResult.outputs,
     entities: buildResult.entities,
     env,
     buildResult,
+    get docs(): OutputDoc[] {
+      return getDocs();
+    },
   };
 
   const diagnostics: PostSynthDiagnostic[] = [];

package/src/lint/receipt-checks.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect } from "vitest";
+import { coreReceiptChecks, RECEIPT_PLAIN_STORE_CHECK_ID } from "./receipt-checks";
+import { runPostSynthChecks } from "./post-synth";
+import { EffectReceipt, EFFECT_RECEIPT_MARKER } from "../effect-receipt";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+
+/** A lexicon-materialized receipt row: its own entityType, the receipt marker. */
+function materializedReceipt(opts: {
+  lexicon: string;
+  entityType: string;
+  props?: Record<string, unknown>;
+}): Declarable {
+  return {
+    [DECLARABLE_MARKER]: true,
+    [EFFECT_RECEIPT_MARKER]: true,
+    lexicon: opts.lexicon,
+    entityType: opts.entityType,
+    ...(opts.props ? { props: opts.props } : {}),
+  } as unknown as Declarable;
+}
+
+function run(entities: Map<string, Declarable>) {
+  return runPostSynthChecks(coreReceiptChecks(), {
+    outputs: new Map(),
+    entities,
+    warnings: [],
+    errors: [],
+    sourceFileCount: 1,
+  });
+}
+
+describe("COR023: receipt materializes into a plain store (#1833)", () => {
+  test("check id", () => {
+    expect(RECEIPT_PLAIN_STORE_CHECK_ID).toBe("COR023");
+    expect(coreReceiptChecks().map((c) => c.id)).toContain("COR023");
+  });
+
+  test("fires when a receipt is materialized into a Secret kind", () => {
+    const entities = new Map<string, Declarable>([
+      ["seededReceipt", materializedReceipt({ lexicon: "k8s", entityType: "K8s::Core::Secret" })],
+    ]);
+    const diags = run(entities);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("COR023");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("seededReceipt");
+    expect(diags[0].message).toContain("K8s::Core::Secret");
+    expect(diags[0].message).toContain("plain store");
+  });
+
+  test("fires when a plain kind selects a secret-capable variant (SSM SecureString)", () => {
+    const entities = new Map<string, Declarable>([
+      [
+        "migratedReceipt",
+        materializedReceipt({
+          lexicon: "aws",
+          entityType: "AWS::SSM::Parameter",
+          props: { Name: "/receipts/migrated", Type: "SecureString" },
+        }),
+      ],
+    ]);
+    const diags = run(entities);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('Type: "SecureString"');
+    expect(diags[0].entity).toBe("migratedReceipt");
+  });
+
+  test("passes: a receipt materialized into a plain store", () => {
+    const entities = new Map<string, Declarable>([
+      [
+        "migratedReceipt",
+        materializedReceipt({
+          lexicon: "aws",
+          entityType: "AWS::SSM::Parameter",
+          props: { Name: "/receipts/migrated", Type: "String" },
+        }),
+      ],
+    ]);
+    expect(run(entities)).toHaveLength(0);
+  });
+
+  test("passes: the core Chant::EffectReceipt declaration itself", () => {
+    const receipt = EffectReceipt("seeded", {
+      effect: "db-seed",
+      flavor: "hash",
+      inputs: { schema: "v3" },
+    });
+    const entities = new Map<string, Declarable>([["seeded", receipt]]);
+    expect(run(entities)).toHaveLength(0);
+  });
+
+  test("passes: a Secret-kind entity that is NOT a receipt is not this check's concern", () => {
+    const secret: Declarable = {
+      [DECLARABLE_MARKER]: true,
+      lexicon: "k8s",
+      entityType: "K8s::Core::Secret",
+    } as unknown as Declarable;
+    const entities = new Map<string, Declarable>([["dbSecret", secret]]);
+    expect(run(entities)).toHaveLength(0);
+  });
+});

package/src/lint/receipt-checks.ts

@@ -0,0 +1,93 @@
+import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import { isEffectReceipt } from "../effect-receipt";
+import { isSensitiveKey } from "../deep-observation";
+import { isResourceDeclarable } from "../declarable";
+
+/**
+ * COR023: Receipt Materializes Into a Plain Store (#1833, epic #1703)
+ *
+ * A receipt's materialization target must be a plain store — never a
+ * SecureString, a Secret, or any secret-capable kind. A receipt value is a
+ * witness (an existence marker or a `sha256:` digest,
+ * ../effect-receipt.ts), not a secret: parking it in a secret-capable store
+ * invites masking, rotation, and access-control semantics that defeat the
+ * observe-and-compare loop the receipt exists for, and quietly teaches
+ * readers that the value is sensitive when it must never be.
+ *
+ * This is the honest core half of the guard. Core recognizes receipts
+ * lexicon-independently through the marker (#1831) but cannot know what any
+ * lexicon's kinds mean, so it checks the two signals it does have, both
+ * reusing the secret-kind knowledge core already carries
+ * (SENSITIVE_KEY_PATTERNS, ../deep-observation.ts):
+ *
+ *  - the materialized `entityType` names a secret-capable kind
+ *    (`K8s::Core::Secret`, `AWS::SecretsManager::Secret`, ...);
+ *  - the declared props select a secret-capable variant of an otherwise
+ *    plain kind (a `Type`/`Kind` prop whose value matches secret/secure —
+ *    SSM's `Type: "SecureString"` is the canonical case).
+ *
+ * The concrete per-kind enforcement is each materialization row's job — the
+ * aws row (#1835) pins SSM to plain `String` at the source.
+ */
+
+/** Prop names that select a store variant. */
+const VARIANT_PROP = /^(type|kind)$/i;
+/** Variant values that make the store secret-capable. */
+const SECRET_VARIANT = /secret|secure/i;
+
+export const RECEIPT_PLAIN_STORE_CHECK_ID = "COR023";
+
+const receiptPlainStoreCheck: PostSynthCheck = {
+  id: RECEIPT_PLAIN_STORE_CHECK_ID,
+  description:
+    "An effect receipt's materialization target must be a plain store — never a secret-capable kind or variant",
+  check(ctx) {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [name, entity] of ctx.entities) {
+      if (!isEffectReceipt(entity)) continue;
+
+      if (isSensitiveKey(entity.entityType)) {
+        diagnostics.push({
+          checkId: RECEIPT_PLAIN_STORE_CHECK_ID,
+          severity: "error",
+          entity: name,
+          lexicon: entity.lexicon,
+          message:
+            `Effect receipt "${name}" materializes into secret-capable kind "${entity.entityType}" — ` +
+            `a receipt's target must be a plain store. The receipt value is a witness ` +
+            `(an existence marker or a sha256 digest), not a secret; a secret-capable store adds ` +
+            `masking and rotation semantics that defeat the receipt's observe-and-compare loop.`,
+        });
+        continue;
+      }
+
+      if (isResourceDeclarable(entity) && typeof entity.props === "object" && entity.props !== null) {
+        for (const [key, value] of Object.entries(entity.props as Record<string, unknown>)) {
+          if (VARIANT_PROP.test(key) && typeof value === "string" && SECRET_VARIANT.test(value)) {
+            diagnostics.push({
+              checkId: RECEIPT_PLAIN_STORE_CHECK_ID,
+              severity: "error",
+              entity: name,
+              lexicon: entity.lexicon,
+              message:
+                `Effect receipt "${name}" (${entity.entityType}) declares ${key}: "${value}" — ` +
+                `a secret-capable store variant. A receipt's target must be a plain store; ` +
+                `use the plain variant (e.g. SSM Type: "String") so the witness value stays ` +
+                `readable to the observe-and-compare loop.`,
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  },
+};
+
+/**
+ * Core's own post-synth checks over effect receipts, run by `chant build`
+ * over the full build result (plugin checks are lexicon-scoped; receipts are
+ * recognized by marker, so this set is deliberately not).
+ */
+export function coreReceiptChecks(): PostSynthCheck[] {
+  return [receiptPlainStoreCheck];
+}

package/src/lint/rules/__fixtures__/comp/comp003/pass/agent-turn.component.ts

@@ -0,0 +1,26 @@
+import type { Component } from "../../../../../../components/component";
+import { phase } from "../../../../../../components/component";
+
+/**
+ * COMP003 pass case (#1944): a bare "run-agent" step with no "noRollback"
+ * opt-out and no component-level "rollback" — must pass COMP003 because
+ * "run-agent"'s rollbackPolicy is "native" (#1941), not "needs-opt-out". This
+ * is the regression test proving the registry's declared rollbackPolicy for
+ * "run-agent" is wired correctly into ctx.rollbackPolicies, the same seam
+ * COMP005 uses for ctx.knownKinds — see comp.test.ts's FIXTURE_ROLLBACK_POLICIES.
+ */
+export const agentTurn: Component = {
+  name: "agent-turn",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [
+    phase("Run", [
+      {
+        kind: "run-agent",
+        agent: "claude",
+        task: { prompt: "run the migration script and report the result" },
+        workspace: {},
+      },
+    ]),
+  ],
+};

package/src/lint/rules/comp/comp.test.ts

@@ -23,11 +23,14 @@ const checks = loadComponentChecks();
 /**
  * Rollback dispositions the COMP003 fixtures reference, standing in for what
  * `chant lint` derives from the project's registry (`cfn-deploy` has a native
- * `rollback`; `run-migration` declares `needs-opt-out` in the aws lexicon).
+ * `rollback`; `run-migration` declares `needs-opt-out` in the aws lexicon;
+ * `run-agent` declares `native` from phase 1 (#1941) — see
+ * `../../../components/verbs/run-agent.ts`'s `rollbackPolicy: "native"`).
  */
 const FIXTURE_ROLLBACK_POLICIES = new Map<string, RollbackPolicy>([
   ["cfn-deploy", "native"],
   ["run-migration", "needs-opt-out"],
+  ["run-agent", "native"],
 ]);
 
 async function lintFixture(
@@ -124,6 +127,16 @@ describe("COMP003: mutating-no-rollback", () => {
     expect(diagnostics.filter((d) => d.checkId === "COMP003")).toHaveLength(0);
   });
 
+  it("does not flag a bare run-agent step — its registry-declared rollbackPolicy is \"native\" (#1941), never needing a noRollback opt-out (#1944)", async () => {
+    // Regression test: proves the registry's rollbackPolicy for "run-agent"
+    // is wired correctly into ctx.rollbackPolicies (the same seam COMP005
+    // uses for ctx.knownKinds), not just that COMP003 happens to stay quiet.
+    // See ../../../components/verbs/run-agent.ts's "rollbackPolicy: 'native'".
+    const diagnostics = await lintFixture("comp003", "pass", { rollbackPolicies: FIXTURE_ROLLBACK_POLICIES });
+    const hits = diagnostics.filter((d) => d.checkId === "COMP003" && d.component === "agent-turn");
+    expect(hits).toHaveLength(0);
+  });
+
   it("flags a needs-opt-out step nested inside a fan-out phase, not just top-level phases", () => {
     // Regression test: the rule used to iterate component.deploy directly and
     // never recursed into nested Phase entries (a fan-out unit, e.g. the
@@ -163,6 +176,41 @@ describe("COMP003: mutating-no-rollback", () => {
     expect(diagnostics[0].message).toContain("run-migration");
   });
 
+  it("DOES flag a \"run-agent\"-kind step when a synthetic registry declares it needs-opt-out — proves the rule is conditional on the registry, not a hard-coded allowance for this one verb name (#1944)", () => {
+    // Companion negative case to the "does not flag a bare run-agent step"
+    // test above: same step kind, same shape, but with a synthetic
+    // rollbackPolicies map that declares "run-agent" as "needs-opt-out"
+    // instead of the real registry's "native". If this rule silently
+    // special-cased "run-agent" by name, this would incorrectly pass; it must
+    // flag exactly like any other needs-opt-out verb.
+    const [comp003] = checks.filter((c) => c.id === "COMP003");
+    const ctx = {
+      rollbackPolicies: new Map<string, RollbackPolicy>([["run-agent", "needs-opt-out"]]),
+      components: new Map([
+        [
+          "agent-turn",
+          {
+            component: {
+              name: "agent-turn",
+              dependsOn: [],
+              deploy: [
+                {
+                  phase: "Run",
+                  steps: [{ kind: "run-agent", agent: "claude", task: { prompt: "..." }, workspace: {} }],
+                },
+              ],
+            },
+            filePath: "agent-turn.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp003.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].component).toBe("agent-turn");
+    expect(diagnostics[0].message).toContain("run-agent");
+  });
+
   it("a compensation sibling only counts within the same nested phase, not a same-named sibling phase elsewhere in the component", () => {
     // Two different "Node" phases both contain a run-migration step; only the
     // second one has a rollback-previous sibling. The first must still be