@intentius/chant-lexicon-terraform 0.58.0 → 0.60.0

package/src/composites/terraform-watch-op.test.ts

@@ -4,7 +4,10 @@
  * only the `-no-color` plan text can reach an issue or PR body.
  */
 
-import { describe, test, expect } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, test, expect } from "vitest";
 import {
   isStepOutputRef,
   collectStepOutputRefs,
@@ -71,7 +74,7 @@ describe("TerraformWatchOp phases (#2087)", () => {
 });
 
 describe("TerraformWatchOp finding modes (#2087)", () => {
-  const findingStep = (mode: "issue" | "pull-request"): ActivityStep => {
+  const findingStep = (mode: "issue" | "comment" | "pull-request"): ActivityStep => {
     const op = props({ name: "app-watch", root: "app", findingMode: mode });
     expect(phaseNames(op)).toEqual(["Init", "Plan", "Report"]);
     return op.phases[2].steps[0] as ActivityStep;
@@ -92,6 +95,14 @@ describe("TerraformWatchOp finding modes (#2087)", () => {
     expect(step.outcomeAttribute).toEqual({ name: "PR", from: "prUrl" });
   });
 
+  test("comment mode posts on the triggering pull request and surfaces the comment URL (#2231)", () => {
+    const step = findingStep("comment");
+    expect(step.fn).toBe("reconcilePr");
+    expect(step.args?.mode).toBe("comment");
+    expect(step.args?.env).toBe("app");
+    expect(step.outcomeAttribute).toEqual({ name: "Comment", from: "commentUrl" });
+  });
+
   test("the finding step derives no plan of its own", () => {
     // `entries: []` is what stops reconcilePr shelling to `chant lifecycle
     // plan --json`: the finding is already written by the time it runs.
@@ -114,7 +125,7 @@ describe("TerraformWatchOp finding modes (#2087)", () => {
 });
 
 describe("TerraformWatchOp posts the human plan and never the plan JSON (#2087)", () => {
-  for (const mode of ["issue", "pull-request"] as const) {
+  for (const mode of ["issue", "comment", "pull-request"] as const) {
     test(`${mode}: the body is a reference to the Plan step's -no-color text`, () => {
       const op = props({ name: "app-watch", root: "app", findingMode: mode });
       const report = op.phases[2].steps[0] as ActivityStep;
@@ -192,7 +203,7 @@ describe("TerraformWatchOp on a live root (#2105)", () => {
     expect(plan.outcomeAttribute).toEqual({ name: "Drift", from: "changed" });
   });
 
-  for (const mode of ["issue", "pull-request"] as const) {
+  for (const mode of ["issue", "comment", "pull-request"] as const) {
     test(`${mode}: the body is the plan text plus the adoption ledger, as one field`, () => {
       const op = live({ findingMode: mode });
       expect(phaseNames(op)).toEqual(["Init", "Plan", "Report"]);
@@ -241,3 +252,73 @@ describe("TerraformWatchOp schedule (#2087, #2120)", () => {
     });
   });
 });
+
+/**
+ * The `live` flag against the root it names (#2216). Best-effort: the mode
+ * resolves from a `chant.config.json` only, so these projects are written in
+ * that format. TF028 (`../lint/post-synth/tf028.ts`) is what reports the same
+ * mismatch on a `chant.config.ts` project, where the mode does not resolve
+ * here at all.
+ */
+describe("TerraformWatchOp cross-checks live against the root's mode (#2216)", () => {
+  const dirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  const LIVE_ROOT = [
+    "terraform {",
+    "  live {",
+    '    estate = "prod-estate"',
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+
+  /** A project on a `chant.config.json` whose root `estate` is `mainTf`, run on `binary`. */
+  function project(binary: string, mainTf: string): string {
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf-watch-mode-"));
+    dirs.push(dir);
+    mkdirSync(join(dir, "estate"), { recursive: true });
+    writeFileSync(join(dir, "estate", "main.tf"), mainTf);
+    writeFileSync(
+      join(dir, "chant.config.json"),
+      JSON.stringify({ terraform: { binary, roots: { estate: { dir: "./estate" } } } }),
+    );
+    return dir;
+  }
+
+  test("refuses a live root watched in stock mode, naming the Op and the root", () => {
+    const cwd = project("choudoufu", LIVE_ROOT);
+    expect(() => TerraformWatchOp({ name: "estate-watch", root: "estate", cwd })).toThrow(
+      /TerraformWatchOp "estate-watch": root "estate" runs choudoufu with a declared estate/,
+    );
+  });
+
+  test("accepts the same root with live: true", () => {
+    const cwd = project("choudoufu", LIVE_ROOT);
+    expect(() => TerraformWatchOp({ name: "estate-watch", root: "estate", live: true, cwd })).not.toThrow();
+  });
+
+  test("refuses live: true on a root that declares no estate", () => {
+    const cwd = project("choudoufu", 'resource "null_resource" "first" {}\n');
+    expect(() => TerraformWatchOp({ name: "app-watch", root: "estate", live: true, cwd })).toThrow(
+      /declares no estate/,
+    );
+  });
+
+  test("refuses live: true when the binary is not choudoufu, whatever the root declares", () => {
+    const cwd = project("terraform", LIVE_ROOT);
+    expect(() => TerraformWatchOp({ name: "app-watch", root: "estate", live: true, cwd })).toThrow(
+      /declares no estate/,
+    );
+  });
+
+  test("says nothing when the mode does not resolve: no config to read", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-tf-watch-mode-"));
+    dirs.push(dir);
+    expect(() => TerraformWatchOp({ name: "app-watch", root: "estate", cwd: dir })).not.toThrow();
+    expect(() => TerraformWatchOp({ name: "app-watch", root: "estate", live: true, cwd: dir })).not.toThrow();
+  });
+});

package/src/composites/terraform-watch-op.ts

@@ -51,16 +51,20 @@
  *
  * ## Findings reuse `reconcilePr`
  *
- * `issue` and `pull-request` call core's `reconcilePr` activity, the one place
- * in chant that shells to `gh issue create` / `gh pr create`, rather than
- * growing a second copy of those calls here.
+ * `issue`, `comment` and `pull-request` call core's `reconcilePr` activity,
+ * the one place in chant that shells to `gh`, rather than growing a second
+ * copy of those calls here.
  * That activity built its own change-set summary and had no way to be handed
  * one, so #2087 added a single field to it (`ReconcilePrArgs.body`), which is
  * what carries the `-no-color` plan through. Note that the pull-request mode
  * of `reconcilePr` regenerates chant TypeScript via `chant import`; a
  * terraform-native regeneration of HCL from live state is #2089, so
  * `findingMode: "issue"` is the mode with an end-to-end answer and
- * `"pull-request"` opens a PR whose body is the plan. On a live root #2089's
+ * `"pull-request"` opens a PR whose body is the plan. `"comment"` (#2231) is
+ * the mode for the plan-on-pull-request shape: the plan is posted onto the
+ * pull request that triggered the run and re-edited there on the next push,
+ * which is where a reviewer is already looking. It needs that trigger; a run
+ * without one fails the Report step by name rather than posting elsewhere. On a live root #2089's
  * question has a different answer rather than a pending one, and it is not
  * regeneration: see `TerraformAdoptOp`.
  *
@@ -80,6 +84,13 @@
  * // one-shot, local executor: chant run app-watch
  * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
  *
+ * // the plan as a sticky comment on the pull request that triggered the run
+ * export const { op } = TerraformWatchOp({
+ *   name: "app-plan",
+ *   root: "app",
+ *   findingMode: "comment",
+ * });
+ *
  * // nightly, opening an issue when the plan is non-empty
  * export const { op } = TerraformWatchOp({
  *   name: "app-watch",
@@ -99,6 +110,7 @@
  */
 
 import { Op, phase, OpResource, type ActivityStep } from "@intentius/chant/op";
+import { resolveRootModeSync } from "../op/resolve-root-mode";
 import { CHOUDOUFU_LIVE_PLAN_OUT_REFUSAL, DEFAULT_PLAN_FILE } from "../op/activities/terraform";
 import {
   terraformInit as initStep,
@@ -110,8 +122,14 @@ import {
  * What to do with a non-empty plan. A subset of core's `OpFindingMode`
  * (`packages/core/src/lexicon.ts`): `merge-request` is GitLab's spelling of
  * `pull-request` and is produced by the CI generator, not chosen here.
+ *
+ * `comment` (#2231) is the mode a plan-on-pull-request Op wants: the plan
+ * lands as one comment on the pull request that triggered the run and the
+ * next push edits that same comment. It needs a `pull_request` trigger on the
+ * `ScheduledOpSpec` the workflow is generated from, and the github generator
+ * refuses it by name on any other trigger.
  */
-export type TerraformFindingMode = "report" | "issue" | "pull-request";
+export type TerraformFindingMode = "report" | "issue" | "comment" | "pull-request";
 
 export interface TerraformWatchOpConfig {
   /** Op name (kebab-case). */
@@ -138,8 +156,14 @@ export interface TerraformWatchOpConfig {
    * Declared here rather than detected, because a composite is built by
    * `chant build` without reading a root module's `.tf` files. The activities
    * detect the estate at run time (`op/activities/live-detect.ts`), but by then
-   * the phases are already serialized. Setting this on a stock root fails at
-   * the first step, with choudoufu's own reason.
+   * the phases are already serialized.
+   *
+   * Two things check the answer against the root's real mode, since a wrong
+   * one is otherwise silent (#2216). This function refuses a mismatch outright
+   * when it can resolve the mode synchronously, which is a
+   * `chant.config.json` project (`op/resolve-root-mode.ts`); TF028
+   * (`lint/post-synth/tf028.ts`) reports the same mismatch off the parsed HCL
+   * for every project, `chant.config.ts` included.
    */
   live?: boolean;
   /**
@@ -193,6 +217,29 @@ export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatch
     );
   }
 
+  // The `live` flag against the root it names. Best-effort and synchronous:
+  // `resolveRootModeSync` reads a `chant.config.json` only and returns
+  // undefined for anything else, so a `chant.config.ts` project reaches
+  // neither branch and TF028 is what reports the mismatch there. Where the
+  // mode does resolve, refusing at build time names the Op, which a
+  // post-synth diagnostic does too but a run-time failure at the first step
+  // does not.
+  const resolvedMode = resolveRootModeSync(config.root, config.cwd)?.mode;
+  if (resolvedMode === "live" && !config.live) {
+    throw new Error(
+      `TerraformWatchOp "${config.name}": root "${config.root}" runs choudoufu with a declared estate, ` +
+        "but this Op watches it in stock mode. A stock plan reports drift alone and stays quiet about " +
+        "every unowned and adoptable resource in the estate. Set live: true.",
+    );
+  }
+  if (resolvedMode === "state" && config.live) {
+    throw new Error(
+      `TerraformWatchOp "${config.name}": live: true, but root "${config.root}" declares no estate (or ` +
+        "terraform.binary is not \"choudoufu\"), so there is no live system to plan against. Drop " +
+        "live, or declare the root's estate.",
+    );
+  }
+
   // `id` is what makes `plan.out` legal, and one field of `plan.out` is the
   // only channel by which any part of the plan leaves this Op.
   //
@@ -238,7 +285,11 @@ export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatch
         ...(config.branch ? { branch: config.branch } : {}),
       },
       outcomeAttribute:
-        findingMode === "pull-request" ? { name: "PR", from: "prUrl" } : { name: "Issue", from: "issueUrl" },
+        findingMode === "pull-request"
+          ? { name: "PR", from: "prUrl" }
+          : findingMode === "comment"
+            ? { name: "Comment", from: "commentUrl" }
+            : { name: "Issue", from: "issueUrl" },
     };
     phases.push(phase("Report", [report]));
   }

package/src/hcl/parse.ts

@@ -436,6 +436,26 @@ export async function parseTerraformRootContent(
   return blocksToEntities(splitBundleContent(content), root, hcl2json, modeOptions);
 }
 
+/** The root name an audit of the audited directory itself parses under. */
+export const AUDIT_ROOT_NAME = "audit-root";
+
+/**
+ * The root name one `chant audit` input parses under (#2217).
+ *
+ * A build names its roots from `terraform.roots`; an audit has no such
+ * config, so the name comes from the input's own path, which is the one thing
+ * that tells two discovered roots apart. `envs/prod` becomes `envs.prod`,
+ * because an entity key is `<root>/<address>` with the module chain between
+ * them and a `/` inside the root name would read as a module scope. The
+ * audited directory itself keeps the name {@link AUDIT_ROOT_NAME}, so a
+ * single-root audit reads the way it did before an input path was available.
+ */
+export function auditRootName(path?: string): string {
+  const trimmed = (path ?? "").replace(/^\.\//, "").replace(/\/+$/, "");
+  if (trimmed === "" || trimmed === ".") return AUDIT_ROOT_NAME;
+  return trimmed.replace(/\//g, ".");
+}
+
 /**
  * The module scope an entity key names: the part before the address.
  *

package/src/lint/audit-catalog.ts

@@ -4,8 +4,8 @@
  * Every post-synth check needs an entry or it contributes nothing to
  * `chant audit`, silently, and `packages/core/src/audit/catalog.test.ts` fails.
  *
- * TF001, TF024, TF025 and TF026 all read the chant model (`ctx.entities`),
- * never emitted output, so `yamlBased` is false for all four. Prior-art
+ * TF001 and TF024 through TF028 all read the chant model (`ctx.entities`),
+ * never emitted output, so `yamlBased` is false for all of them. Prior-art
  * lineage lives in ./audit-lineage.ts.
  */
 import type { Authority, RuleMeta } from "@intentius/chant/audit/catalog";
@@ -69,6 +69,30 @@ export const terraformAuditCatalog: Record<string, RuleMeta> = {
       "deleted after all.",
     yamlBased: false,
   },
+  TF027: {
+    id: "TF027",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: 'Live root\'s policy block sets undeclared_untagged = "delete"',
+    remediation:
+      'Remove undeclared_untagged = "delete" from the live root\'s policy block. chant never proposes ' +
+      "deleting a resource it does not own; narrow the estate's own ownership answer " +
+      "(undeclared_tagged) instead of the account's.",
+    yamlBased: false,
+  },
+  TF028: {
+    id: "TF028",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Live root is watched by a TerraformWatchOp built without live: true",
+    remediation:
+      "Set live: true on the TerraformWatchOp that names this root, so the Plan phase runs " +
+      "choudoufuLivePlan and reports the unowned and adoptable counts as well as drift. Drop the root's " +
+      "estate instead if it is not a live root.",
+    yamlBased: false,
+  },
   TF002: {
     id: "TF002",
     tier: "merge-worthy",

package/src/lint/audit-lineage.ts

@@ -42,26 +42,37 @@
  * TF021) added `gcp-terraform-best-practices`, the last row of the table below
  * that no shipped rule had cited yet.
  *
+ * Each row's Sweep note says whether `scripts/prior-art-sweep.ts` can index the
+ * source and, when it cannot, why (#2219). Five of these are indexed as of
+ * 2026-09-07: the three tflint rulesets, tfsec and the Sentinel policy set,
+ * 311 upstream rule ids in `scripts/prior-art/snapshot.json`. The rest are
+ * prose or code, so the tools they credit are re-read by hand when their
+ * documents change.
+ *
  * | Key | Name | URL | Licence | Kind | Note |
  * |---|---|---|---|---|---|
- * | `tflint` | tflint | https://github.com/terraform-linters/tflint | MPL-2.0 (its `terraform` package is BUSL-1.1; binaries are bound by both) | scanner | The plugin host; ships no language rules of its own. |
- * | `tflint-ruleset-terraform` | tflint-ruleset-terraform | https://github.com/terraform-linters/tflint-ruleset-terraform | MPL-2.0 | scanner | The official language-level ruleset, bundled into tflint. |
- * | `tflint-ruleset-redeploy` | tflint-ruleset-redeploy | https://github.com/RedeployAB/tflint-ruleset-redeploy | 0BSD | scanner | Community ruleset; richest source of language-level rules outside the official set. |
- * | `tflint-ruleset-avm` | tflint-ruleset-avm | https://github.com/Azure/tflint-ruleset-avm | MIT | scanner | Azure Verified Modules conformance; two of its 33 rules are provider-agnostic. |
- * | `tfsec` | tfsec | https://github.com/aquasecurity/tfsec | MIT | scanner | Historical: not archived but effectively frozen (no release since 2025-05); its docs site 404s above v0.61.x, so cite pinned repository paths (`github.com/aquasecurity/tfsec/blob/master/docs/checks/...`), not the docs site. |
- * | `trivy-checks` | trivy-checks | https://github.com/aquasecurity/trivy-checks | MIT (not the trivy scanner's own Apache-2.0; cite the checks repo's licence, not the engine's) | scanner | Where tfsec's rules live today (tfsec -> defsec -> trivy + trivy-checks). Cite rules by `long_id` (stable, human-readable); `AVD-*` ids are aliases now. |
- * | `terraform-sentinel-policies` | HashiCorp reference Sentinel policies | https://github.com/hashicorp/terraform-sentinel-policies | MPL-2.0 | specification | HashiCorp's own example policy set; ships zero rules baked into HCP Terraform itself, so treat a cited policy as a documented pattern (`specification`) unless a future entry runs it as a real check (`scanner`); the `kind` union allows either. |
- * | `choudoufu` | choudoufu | https://github.com/INTENTIUS/choudoufu | MPL-2.0 | scanner | Its `internal/live/lint` package; experimental, AWS-only. |
- * | `hashicorp-style-guide` | HashiCorp Terraform style guide | https://developer.hashicorp.com/terraform/language/style | n/a | specification | |
- * | `gcp-terraform-best-practices` | Google Cloud Terraform best-practices series | https://docs.cloud.google.com/docs/terraform/best-practices/general-style-structure | n/a | specification | A multi-page series; cite the specific page's fragment. |
- * | `aws-terraform-prescriptive-guidance` | AWS prescriptive guidance for Terraform | https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/ | n/a | specification | |
+ * | `tflint` | tflint | https://github.com/terraform-linters/tflint | MPL-2.0 (its `terraform` package is BUSL-1.1; binaries are bound by both) | scanner | The plugin host; ships no language rules of its own. Sweep: not registered in `PRIOR_ART` (no rule cites it), so it is not swept. |
+ * | `tflint-ruleset-terraform` | tflint-ruleset-terraform | https://github.com/terraform-linters/tflint-ruleset-terraform | MPL-2.0 | scanner | The official language-level ruleset, bundled into tflint. Sweep: indexed from `docs/rules/README.md`, whose table links each rule's page (20 rules). |
+ * | `tflint-ruleset-redeploy` | tflint-ruleset-redeploy | https://github.com/RedeployAB/tflint-ruleset-redeploy | 0BSD | scanner | Community ruleset; richest source of language-level rules outside the official set. Sweep: indexed from `docs/rules/README.md`, same table shape (33 rules). |
+ * | `tflint-ruleset-avm` | tflint-ruleset-avm | https://github.com/Azure/tflint-ruleset-avm | MIT | scanner | Azure Verified Modules conformance; two of its 33 rules are provider-agnostic. Sweep: indexed from the repository-root `RULES.md`, since `docs/` holds pages for only two rules (33 rules). |
+ * | `tfsec` | tfsec | https://github.com/aquasecurity/tfsec | MIT | scanner | Historical: not archived but effectively frozen (no release since 2025-05); its docs site 404s above v0.61.x, so cite pinned repository paths (`github.com/aquasecurity/tfsec/blob/master/docs/checks/...`), not the docs site. Sweep: indexed from the root `rules.md` on `master`, a flat table of all 152 check ids, because `docs/checks` nests a directory per provider, service and check. |
+ * | `trivy-checks` | trivy-checks | https://github.com/aquasecurity/trivy-checks | MIT (not the trivy scanner's own Apache-2.0; cite the checks repo's licence, not the engine's) | scanner | Where tfsec's rules live today (tfsec -> defsec -> trivy + trivy-checks). Cite rules by `long_id` (stable, human-readable); `AVD-*` ids are aliases now. Sweep: not registered in `PRIOR_ART` (no rule cites it yet) and its `long_id`s live in Rego metadata under `checks/<kind>/<provider>/<service>/`, with no flat index. |
+ * | `terraform-sentinel-policies` | HashiCorp reference Sentinel policies | https://github.com/hashicorp/terraform-sentinel-policies | MPL-2.0 | specification | HashiCorp's own example policy set; ships zero rules baked into HCP Terraform itself, so treat a cited policy as a documented pattern (`specification`) unless a future entry runs it as a real check (`scanner`); the `kind` union allows either. Sweep: indexed by listing the five per-cloud directories, whose `.sentinel` filenames are the policy ids credits cite (73 policies); the repository publishes no index page. |
+ * | `choudoufu` | choudoufu | https://github.com/INTENTIUS/choudoufu | MPL-2.0 | scanner | Its `internal/live/lint` package; experimental, AWS-only. Sweep: unsweepable, its rule ids are Go constants in `internal/live/lint/issue.go` and it publishes no rule index. |
+ * | `hashicorp-style-guide` | HashiCorp Terraform style guide | https://developer.hashicorp.com/terraform/language/style | n/a | specification | Sweep: unsweepable, one prose page of recommendations with no rule ids; a credit quotes the sentence and links its fragment. |
+ * | `gcp-terraform-best-practices` | Google Cloud Terraform best-practices series | https://docs.cloud.google.com/docs/terraform/best-practices/general-style-structure | n/a | specification | A multi-page series; cite the specific page's fragment. Sweep: unsweepable, prose across several pages with no rule ids. |
+ * | `aws-terraform-prescriptive-guidance` | AWS prescriptive guidance for Terraform | https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/ | n/a | specification | Sweep: unsweepable, a prose guide whose sections carry headings rather than rule ids. |
  *
  * Deliberately excluded, per the survey: Terrascan and regula (both archived,
  * do not build on dead projects); Snyk IaC (a product, not a rule source);
  * semgrep (no SPDX id: its engine is LGPL-2.1 but its rules ship under the
  * proprietary Semgrep Rules License v1.0, which forbids redistribution; cite
  * it by name in prose if a rule's idea comes from it, never register it in
- * `PRIOR_ART` with an SPDX licence).
+ * `PRIOR_ART` with an SPDX licence). TF008 credits semgrep by name under that
+ * rule, so `PRIOR_ART` does carry the entry, with the licence spelled out
+ * rather than as an SPDX id. Sweep: unsweepable, the registry publishes no
+ * index and a rule id is the path of its YAML file under
+ * `terraform/<provider>/<category>/`, which no single directory listing covers.
  *
  * TF024 (#2103, live root declares a backend/cloud block) credits choudoufu's
  * own `RuleStateBackend`, `internal/live/lint/issue.go` of
@@ -83,6 +94,22 @@
  * activities/kubectl.ts`'s `ApplyDeleteMode`, `packages/core/src/op/
  * activities/apply.ts`'s `DeleteMode`), applied here to a tool that does not
  * itself carry the concept. Ship with no lineage rather than invent a credit.
+ *
+ * TF027 (#2216, a live root's `policy` block setting `undeclared_untagged =
+ * "delete"`) does have one: choudoufu's `RulePolicyScope`
+ * (`internal/live/lint/policy.go`) refuses the same assignment, and issue #67
+ * there makes it a lint refusal rather than a default. The relation is
+ * `extends`, because choudoufu refuses it only when no `scope` block narrows
+ * the purge, while chant refuses it either way: a `scope` block bounds an
+ * account-wide sweep to a service, type or region, and every resource inside
+ * that boundary is still one this estate never marked. "Bounded" is not
+ * "owned", and owning it is the condition chant applies.
+ *
+ * TF028 (#2216, a live root watched by a `TerraformWatchOp` built without
+ * `live: true`) has no entry. It reads a chant Op's own configuration against
+ * a root's mode, and no surveyed tool has an Op model to read: choudoufu lints
+ * HCL, and every tflint ruleset, tfsec/trivy-checks and the Sentinel policies
+ * do the same. There is nothing upstream to credit.
  */
 import type { Lineage } from "@intentius/chant/audit/catalog";
 
@@ -93,6 +120,14 @@ const TFLINT_RULES = "https://github.com/terraform-linters/tflint-ruleset-terraf
 const REDEPLOY_RULES = "https://github.com/RedeployAB/tflint-ruleset-redeploy/blob/main/docs/rules";
 
 export const terraformAuditLineage: Record<string, Lineage[]> = {
+  TF027: [
+    {
+      tool: "choudoufu",
+      rule: "RulePolicyScope",
+      url: "https://github.com/INTENTIUS/choudoufu/blob/main/internal/live/lint/policy.go",
+      relation: "extends",
+    },
+  ],
   TF024: [
     {
       tool: "choudoufu",
@@ -196,6 +231,19 @@ export const terraformAuditLineage: Record<string, Lineage[]> = {
     { tool: "tfsec", rule: "general-secrets-sensitive-in-variable", url: `${TFSEC_V061}/sensitive-in-variable.md`, relation: "equivalent" },
     { tool: "tfsec", rule: "general-secrets-sensitive-in-local", url: `${TFSEC_V061}/sensitive-in-local.md`, relation: "equivalent" },
   ],
+  // #2107's rule table credits TF008 with Snyk `SNYK-CC-TF-74` ("Credentials
+  // are configured via provider attributes") alongside these three. That
+  // credit is deliberately absent here, and the absence is the epic's own
+  // decision rather than an oversight: Snyk IaC is a product, not a rule
+  // source, which is why it sits in this file's "deliberately excluded" list
+  // above and has no `PRIOR_ART` entry to cite. The rules have no open
+  // repository behind them, and the public index (security.snyk.io/rules/
+  // cloud) does not even enumerate the legacy `SNYK-CC-TF-*` ids, so a
+  // credit here could not be swept the way every other one in this file is
+  // (scripts/prior-art-sweep.ts). The condition loses nothing by it:
+  // `SNYK-CC-TF-74`, checkov's `CKV_AWS_41` and semgrep's
+  // `aws-provider-static-credentials` are the same check three times over,
+  // and the other two are credited below (#2220).
   TF008: [
     { tool: "checkov", rule: "CKV_AWS_41", url: "https://www.checkov.io/5.Policy%20Index/terraform.html", relation: "overlaps" },
     { tool: "kics", rule: "d7b9d850-3e06-4a75-852f-c46c2e92240b", url: "https://docs.kics.io/latest/queries/terraform-queries/aws/d7b9d850-3e06-4a75-852f-c46c2e92240b/", relation: "overlaps" },
@@ -235,6 +283,18 @@ export const terraformAuditLineage: Record<string, Lineage[]> = {
   TF013: [
     { tool: "tflint-ruleset-redeploy", rule: "terraform_ignore_changes_all", url: `${REDEPLOY_RULES}/terraform_ignore_changes_all.md`, relation: "equivalent" },
   ],
+  // The two vendor documents below (and the one on TF015, and the HashiCorp
+  // style guide on TF021) are `Lineage` entries, not `RuleMeta.authority`
+  // ones, though #2107's table calls them "authority". `authority` is not a
+  // free-standing "this document says so" field: an authority citation forces
+  // `category: "security"` (`packages/core/src/audit/catalog.ts`), and
+  // `catalog.test.ts` binds the two together in both directions, "an
+  // authority citation always means security" and "authority citations only
+  // attach to merge-worthy entries". A provider block in a child module is a
+  // structural rule, not a security finding, so citing these guides as
+  // authority would have relabelled three rules as security to get a citation
+  // rendered. Lineage carries the same URLs and never touches tier or
+  // category, so that is where they live (#2112, recorded here by #2220).
   TF014: [
     {
       tool: "tflint-ruleset-avm",
@@ -262,7 +322,9 @@ export const terraformAuditLineage: Record<string, Lineage[]> = {
   // provider block TF014 credits. What states the rule is Google Cloud's
   // reusable-modules guide, so that document is the single credit here, and
   // the page section says plainly that the credit is a document rather than
-  // a tool (#2112).
+  // a tool (#2112). It is lineage rather than `authority` for the reason on
+  // TF014 above: an authority citation would force `category: "security"` on
+  // a rule about where state configuration belongs.
   TF015: [
     {
       tool: "gcp-terraform-best-practices",
@@ -303,7 +365,10 @@ export const terraformAuditLineage: Record<string, Lineage[]> = {
     // the ones that build an identity out of `count.index`, which is a
     // strict subset, hence `overlaps` on both credits rather than
     // `equivalent`. choudoufu's own rule is the survey's deepest reading of
-    // the identity-bearing question (#2112).
+    // the identity-bearing question (#2112). The HashiCorp style guide entry
+    // is lineage rather than `authority` for the reason recorded on TF014: an
+    // authority citation forces `category: "security"`, and `count` versus
+    // `for_each` is not a security finding.
     {
       tool: "tflint-ruleset-redeploy",
       rule: "terraform_prefer_for_each",