@fjall/eslint-plugin 2.18.1

package/no-bare-sdk-abort-timeout.js

@@ -0,0 +1,79 @@
+/**
+ * ESLint Rule: no-bare-sdk-abort-timeout
+ *
+ * Flags a bare `AbortSignal.timeout(...)` in deploy-core. A per-request timeout
+ * passed directly to an AWS SDK `.send()` ignores the caller's shutdown signal
+ * (`DeployParams.abortSignal` / the worker SIGTERM AbortController), so an
+ * in-flight call stalls graceful shutdown for the full timeout. Route through
+ * `composeSdkAbortSignal(abortSignal, timeoutMs?)` from
+ * `deploy-core/src/aws/organisations/types.ts` so the timeout composes with the
+ * caller signal via `AbortSignal.any`, and thread the caller's `abortSignal`.
+ *
+ * Permitted shape — `AbortSignal.timeout(ms)` as a direct element of
+ * `AbortSignal.any([...])` (the sanctioned inline composition). The canonical
+ * helper lives in `types.ts`, which is excluded from this rule at config level.
+ *
+ * Per .claude/rules/robustness-standards.md § "SDK probe helpers take optional
+ * abortSignal and compose with the timeout".
+ */
+
+function isAbortSignalTimeout(node) {
+  return (
+    node &&
+    node.type === "CallExpression" &&
+    node.callee.type === "MemberExpression" &&
+    !node.callee.computed &&
+    node.callee.object.type === "Identifier" &&
+    node.callee.object.name === "AbortSignal" &&
+    node.callee.property.type === "Identifier" &&
+    node.callee.property.name === "timeout"
+  );
+}
+
+/**
+ * Returns true iff `node` is a direct element of the array literal passed to
+ * `AbortSignal.any(...)` — the one sanctioned raw-timeout shape.
+ */
+function isInsideAbortSignalAny(node) {
+  const arrayParent = node.parent;
+  if (!arrayParent || arrayParent.type !== "ArrayExpression") return false;
+  const callParent = arrayParent.parent;
+  return (
+    callParent &&
+    callParent.type === "CallExpression" &&
+    callParent.callee.type === "MemberExpression" &&
+    !callParent.callee.computed &&
+    callParent.callee.object.type === "Identifier" &&
+    callParent.callee.object.name === "AbortSignal" &&
+    callParent.callee.property.type === "Identifier" &&
+    callParent.callee.property.name === "any"
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow bare AbortSignal.timeout() in deploy-core SDK code — compose with the caller shutdown signal via composeSdkAbortSignal().",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      bareSdkTimeout:
+        "Bare AbortSignal.timeout() ignores the caller shutdown signal — an in-flight SDK call stalls SIGTERM for the full timeout. Route through composeSdkAbortSignal(abortSignal, timeoutMs?) from organisations/types.js and thread the caller's abortSignal. If this is a genuine standalone timeout, add an eslint-disable with a reason."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isAbortSignalTimeout(node)) return;
+        if (isInsideAbortSignalAny(node)) return;
+        context.report({ node, messageId: "bareSdkTimeout" });
+      }
+    };
+  }
+};

package/no-classic-connected-account-assume.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview ESLint rule: no-classic-connected-account-assume.
+ *
+ * `webapp-standards.md` § "Connected-account sessions go through
+ * CredentialProvider web-identity, never hand-rolled classic STS" requires that
+ * any webapp service obtaining a session inside a CONNECTED AWS account route
+ * through `CredentialProvider.assumeRole(roleArn, region, organisationId)`
+ * (`fjall-discovery/utils/credential-provider.ts`), which mints a Fjall OIDC JWT
+ * (subject `org:{orgId}:*`) and exchanges it via `AssumeRoleWithWebIdentity`.
+ *
+ * A hand-rolled classic `new AssumeRoleCommand(...)` is issued from the app
+ * container's ambient ECS task-role credentials. Connected `FjallDeploy<orgId>`
+ * roles trust the OIDC web identity, NOT the app task role — so classic
+ * AssumeRole returns AccessDenied at runtime, invisible to typecheck and lint.
+ *
+ * The rule flags `new AssumeRoleCommand(...)`. It deliberately does NOT flag
+ * `new STSClient(...)`: the web-identity path and every post-assume client
+ * legitimately construct an STSClient, so flagging it would false-positive.
+ *
+ * The one legitimate classic-assume site is the INITIAL connection handshake
+ * (`app/routes/api/aws-accounts/verify.ts`): pre-OIDC, `FjallAudit<orgId>`
+ * trusts the Fjall platform account + an `ExternalId` (classic cross-account
+ * trust); the web identity does not exist until the account is deployed. That
+ * site carries an inline `eslint-disable-next-line` with its reason.
+ *
+ * Authored after the same defect shipped three times in two sessions
+ * (`executeBucketCure`, `orgMembershipCheck.listOrgMemberAccountIds`,
+ * `promote-root.confirmManagementAccount` — webapp `50f02107` + `a0f762e2`),
+ * each an AccessDenied caught only at prod E2E. Scoped to the webapp via
+ * `webapp/eslint.config.mjs` only — the CLI / deploy-core legitimately issue
+ * classic AssumeRole with the operator's own credentials.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noClassicConnectedAccountAssume = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Connected-account sessions must use CredentialProvider.assumeRole (OIDC web-identity), not a hand-rolled classic new AssumeRoleCommand."
+    },
+    messages: {
+      classicConnectedAssume:
+        'Use `CredentialProvider.assumeRole(roleArn, region, organisationId)` (OIDC web-identity) instead of `new AssumeRoleCommand(...)`. The app task role is not trusted by connected `FjallDeploy<orgId>` roles, so classic AssumeRole returns AccessDenied at runtime — invisible to typecheck/lint. The only legitimate classic-assume site is the initial connection handshake against `FjallAudit<orgId>` (trusts the platform account + ExternalId pre-OIDC); allow it with an inline `eslint-disable-next-line fjall/no-classic-connected-account-assume -- <reason>`. See webapp-standards.md § "Connected-account sessions go through CredentialProvider web-identity".'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      NewExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "AssumeRoleCommand"
+        ) {
+          context.report({ node, messageId: "classicConnectedAssume" });
+        }
+      }
+    };
+  }
+};
+
+export default noClassicConnectedAccountAssume;

package/no-clickhouse-internal-reexport.js

@@ -0,0 +1,99 @@
+/**
+ * ESLint Rule: no-clickhouse-internal-reexport
+ *
+ * Forbids re-exporting ClickHouse-internal plumbing symbols from public
+ * barrels of `@fjall/components-infrastructure`. The runtime hygiene test
+ * (`lib/__tests__/clickhouseHygiene.test.ts`) walks the resolved public
+ * surface; this rule shifts the failure left to author-time so a reviewer
+ * sees the lint error before running tests.
+ *
+ * Forbidden surface symbols (the hygiene test's `forbiddenRuntimeSymbols`):
+ *   - ClickHouseInstance
+ *   - ServiceDiscoveryNamespace
+ *   - buildClickHouseUserData
+ *   - createClickHouseSecurityGroup
+ *
+ * Catches the directly-named re-export shapes:
+ *   export { ClickHouseInstance } from "./...";
+ *   export { ClickHouseInstance };
+ *   export { ClickHouseInstance as Foo };  // original name still fails
+ *   export class ClickHouseInstance { ... }
+ *   export function buildClickHouseUserData() { ... }
+ *
+ * Does NOT statically resolve `export * from "./internal.js"` chains —
+ * the runtime hygiene test catches those via `Object.keys(pkg)`. The two
+ * checks are complementary: this rule covers the static shape, the test
+ * covers the resolved surface.
+ */
+
+const FORBIDDEN_SYMBOLS = new Set([
+  "ClickHouseInstance",
+  "ServiceDiscoveryNamespace",
+  "buildClickHouseUserData",
+  "createClickHouseSecurityGroup"
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow re-exporting ClickHouse-internal plumbing symbols from public barrels.",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      forbiddenReexport:
+        "Symbol `{{name}}` is ClickHouse-internal plumbing and must not appear on the public surface. Consume via the DatabaseFactory or a typed connector instead. See aiDocs/patterns/clickhouse-database-factory-pattern.md."
+    },
+    schema: []
+  },
+
+  create(context) {
+    function reportIfForbidden(name, node) {
+      if (FORBIDDEN_SYMBOLS.has(name)) {
+        context.report({
+          node,
+          messageId: "forbiddenReexport",
+          data: { name }
+        });
+      }
+    }
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (node.declaration) {
+          const decl = node.declaration;
+          if (
+            (decl.type === "ClassDeclaration" ||
+              decl.type === "FunctionDeclaration") &&
+            decl.id &&
+            decl.id.type === "Identifier"
+          ) {
+            reportIfForbidden(decl.id.name, decl.id);
+            return;
+          }
+          if (decl.type === "VariableDeclaration") {
+            for (const variable of decl.declarations) {
+              if (variable.id && variable.id.type === "Identifier") {
+                reportIfForbidden(variable.id.name, variable.id);
+              }
+            }
+            return;
+          }
+        }
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type === "ExportSpecifier" &&
+            specifier.local &&
+            specifier.local.type === "Identifier"
+          ) {
+            reportIfForbidden(specifier.local.name, specifier);
+          }
+        }
+      }
+    };
+  }
+};

package/no-duplicate-fjall-util-helper.js

@@ -0,0 +1,275 @@
+/**
+ * ESLint Rule: no-duplicate-fjall-util-helper
+ *
+ * Flags two shapes that re-implement canonical `@fjall/util` helpers in files
+ * that already import from `@fjall/util`. The canonical helpers (`getErrorMessage`,
+ * `toError`, `maskSensitiveOutput`, `filterDangerousEnvVars`) are the single
+ * source of truth — duplicating their shape locally creates silent drift the
+ * moment the canonical implementation tightens (a new credential regex in
+ * `maskSensitiveOutput`, a stack-preservation tweak in `toError`).
+ *
+ * Two detection shapes:
+ *
+ *   1. Local declaration shadowing a canonical name. Five AST shapes covered:
+ *        - `function getErrorMessage(...)`              (plain)
+ *        - `export function getErrorMessage(...)`       (named export)
+ *        - `export default function getErrorMessage(...)` (default export)
+ *        - `const getErrorMessage = (...) => ...`       (var arrow / fn-expr)
+ *        - `export const getErrorMessage = (...) => ...` (exported var arrow)
+ *      Fires on the FIRST occurrence (1-site threshold) — a declaration is
+ *      always wrong because callers reference the local symbol rather than
+ *      the canonical.
+ *
+ *   2. Inline reimplementation of `getErrorMessage` / `toError` patterns at 2+
+ *      sites in the same file. The coupled-values rule
+ *      (`.claude/rules/code-quality.md § "Coupled values"`) says drift between
+ *      two canonical-helper sites is a silent bug — this rule mechanises that
+ *      at the 2-site threshold for the two patterns whose inline shape is
+ *      unambiguous:
+ *      - `<id> instanceof Error ? <id>.message : String(<id>)` → use `getErrorMessage`
+ *      - `<id> instanceof Error ? <id> : new Error(String(<id>))` → use `toError`
+ *
+ *      `maskSensitiveOutput` and `filterDangerousEnvVars` have no inlineable
+ *      shape (the regex/blocklist is too large to inline), so they only fire
+ *      on shape 1.
+ *
+ * Gate: `@fjall/util` (or `@fjall/util/<subpath>`) must be imported in the
+ * file. Files with no path to the canonical helpers are not bothered.
+ *
+ * Limitations:
+ *   - Same-file only. A helper defined in a sibling module and re-imported
+ *     locally is not detected — this is the `helper-indirection` shape
+ *     already covered by `mask-error-message-at-boundary`.
+ *   - Name match only. A function named `getErrorMessage` that does NOT
+ *     return the canonical shape (e.g. returns `err.code`) is still flagged
+ *     — the rule trusts the name. If you genuinely need a different
+ *     extractor, rename it (`getErrorCode`, `extractFirstLine`).
+ *   - No autofix. Folding inline shapes into a canonical-import edit requires
+ *     ensuring the import list contains the canonical name; the rule cannot
+ *     make that edit safely in all cases.
+ *
+ * Per `.claude/rules/webapp-standards.md § "Worker Scripts (webapp/scripts/**)"`
+ * and `.claude/rules/code-quality.md § "Coupled values"`.
+ */
+
+const CANONICAL_HELPERS = new Set([
+  "getErrorMessage",
+  "toError",
+  "maskSensitiveOutput",
+  "filterDangerousEnvVars"
+]);
+
+const FJALL_UTIL_RE = /^@fjall\/util(\/.*)?$/;
+
+/**
+ * Match `<id> instanceof Error ? <id>.message : String(<id>)`.
+ * Returns the identifier name if matched, null otherwise.
+ */
+function matchGetErrorMessagePattern(node) {
+  if (node.type !== "ConditionalExpression") return null;
+  const { test, consequent, alternate } = node;
+
+  if (
+    test.type !== "BinaryExpression" ||
+    test.operator !== "instanceof" ||
+    test.left.type !== "Identifier" ||
+    test.right.type !== "Identifier" ||
+    test.right.name !== "Error"
+  )
+    return null;
+  const idName = test.left.name;
+
+  if (
+    consequent.type !== "MemberExpression" ||
+    consequent.computed ||
+    consequent.object.type !== "Identifier" ||
+    consequent.object.name !== idName ||
+    consequent.property.type !== "Identifier" ||
+    consequent.property.name !== "message"
+  )
+    return null;
+
+  if (
+    alternate.type !== "CallExpression" ||
+    alternate.callee.type !== "Identifier" ||
+    alternate.callee.name !== "String" ||
+    alternate.arguments.length !== 1 ||
+    alternate.arguments[0].type !== "Identifier" ||
+    alternate.arguments[0].name !== idName
+  )
+    return null;
+
+  return idName;
+}
+
+/**
+ * Match `<id> instanceof Error ? <id> : new Error(String(<id>))`.
+ * Returns the identifier name if matched, null otherwise.
+ */
+function matchToErrorPattern(node) {
+  if (node.type !== "ConditionalExpression") return null;
+  const { test, consequent, alternate } = node;
+
+  if (
+    test.type !== "BinaryExpression" ||
+    test.operator !== "instanceof" ||
+    test.left.type !== "Identifier" ||
+    test.right.type !== "Identifier" ||
+    test.right.name !== "Error"
+  )
+    return null;
+  const idName = test.left.name;
+
+  if (consequent.type !== "Identifier" || consequent.name !== idName)
+    return null;
+
+  if (
+    alternate.type !== "NewExpression" ||
+    alternate.callee.type !== "Identifier" ||
+    alternate.callee.name !== "Error" ||
+    alternate.arguments.length !== 1
+  )
+    return null;
+  const inner = alternate.arguments[0];
+  if (
+    inner.type !== "CallExpression" ||
+    inner.callee.type !== "Identifier" ||
+    inner.callee.name !== "String" ||
+    inner.arguments.length !== 1 ||
+    inner.arguments[0].type !== "Identifier" ||
+    inner.arguments[0].name !== idName
+  )
+    return null;
+
+  return idName;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Flag local declarations and 2+ inline reimplementations of canonical @fjall/util helpers in files that already import from @fjall/util.",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      duplicateCanonicalHelper:
+        'Local `{{name}}` shadows the canonical `@fjall/util` export. Add `{{name}}` to your `@fjall/util` import and delete this declaration. See .claude/rules/webapp-standards.md § "Worker Scripts (webapp/scripts/**)" canonical-helper table.',
+      inlineDuplicateCanonicalHelper:
+        'Inline `{{name}}` reimplementation (this file has {{count}}). Import `{{name}}` from `@fjall/util` and replace each call site — drift between canonical-helper sites is a silent bug. See .claude/rules/code-quality.md § "Coupled values: shared source at 2 occurrences".'
+    },
+    schema: []
+  },
+
+  create(context) {
+    let hasFjallUtilImport = false;
+    const localDeclarations = [];
+    const inlineGetErrorMessage = [];
+    const inlineToError = [];
+
+    return {
+      ImportDeclaration(node) {
+        if (
+          node.source &&
+          typeof node.source.value === "string" &&
+          FJALL_UTIL_RE.test(node.source.value)
+        ) {
+          hasFjallUtilImport = true;
+        }
+      },
+
+      "Program > FunctionDeclaration"(node) {
+        if (node.id && CANONICAL_HELPERS.has(node.id.name)) {
+          localDeclarations.push({ node, name: node.id.name });
+        }
+      },
+
+      "Program > ExportNamedDeclaration > FunctionDeclaration"(node) {
+        if (node.id && CANONICAL_HELPERS.has(node.id.name)) {
+          localDeclarations.push({ node, name: node.id.name });
+        }
+      },
+
+      "Program > VariableDeclaration > VariableDeclarator"(node) {
+        if (
+          node.id &&
+          node.id.type === "Identifier" &&
+          CANONICAL_HELPERS.has(node.id.name) &&
+          node.init &&
+          (node.init.type === "ArrowFunctionExpression" ||
+            node.init.type === "FunctionExpression")
+        ) {
+          localDeclarations.push({ node, name: node.id.name });
+        }
+      },
+
+      "Program > ExportNamedDeclaration > VariableDeclaration > VariableDeclarator"(
+        node
+      ) {
+        if (
+          node.id &&
+          node.id.type === "Identifier" &&
+          CANONICAL_HELPERS.has(node.id.name) &&
+          node.init &&
+          (node.init.type === "ArrowFunctionExpression" ||
+            node.init.type === "FunctionExpression")
+        ) {
+          localDeclarations.push({ node, name: node.id.name });
+        }
+      },
+
+      "Program > ExportDefaultDeclaration > FunctionDeclaration"(node) {
+        if (node.id && CANONICAL_HELPERS.has(node.id.name)) {
+          localDeclarations.push({ node, name: node.id.name });
+        }
+      },
+
+      ConditionalExpression(node) {
+        if (matchGetErrorMessagePattern(node)) {
+          inlineGetErrorMessage.push(node);
+        } else if (matchToErrorPattern(node)) {
+          inlineToError.push(node);
+        }
+      },
+
+      "Program:exit"() {
+        if (!hasFjallUtilImport) return;
+
+        for (const { node, name } of localDeclarations) {
+          context.report({
+            node,
+            messageId: "duplicateCanonicalHelper",
+            data: { name }
+          });
+        }
+
+        if (inlineGetErrorMessage.length >= 2) {
+          for (const node of inlineGetErrorMessage) {
+            context.report({
+              node,
+              messageId: "inlineDuplicateCanonicalHelper",
+              data: {
+                name: "getErrorMessage",
+                count: String(inlineGetErrorMessage.length)
+              }
+            });
+          }
+        }
+        if (inlineToError.length >= 2) {
+          for (const node of inlineToError) {
+            context.report({
+              node,
+              messageId: "inlineDuplicateCanonicalHelper",
+              data: {
+                name: "toError",
+                count: String(inlineToError.length)
+              }
+            });
+          }
+        }
+      }
+    };
+  }
+};

package/no-empty-string-env-fallthrough.js

@@ -0,0 +1,117 @@
+/**
+ * ESLint Rule: no-empty-string-env-fallthrough
+ *
+ * Flags `process.env.X !== undefined` and `process.env.X ?? "fallback"`
+ * patterns when X carries data (path/dir/url/key/token/host). CI shells,
+ * Kubernetes ConfigMaps, and docker-compose env-files can legitimately
+ * export `X=""`, which both forms accept as "set" — silently producing
+ * empty paths, host-less URLs, or empty credentials downstream.
+ *
+ * Required shape: explicit `value !== undefined && value !== ""` check.
+ *
+ * Per .claude/rules/robustness-standards.md § "Environment Variable
+ * Truthy Checks". Recurrence-driven escalation from rule-doc → ESLint
+ * (3 separate /review passes flagged this exact pattern in 5 days).
+ */
+
+const DATA_ENV_VAR_PATTERN = /_(DIR|PATH|URL|HOST|KEY|TOKEN|ID|FILE|ROOT)$/;
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow process.env.X !== undefined and process.env.X ?? fallback for data env vars; require explicit empty-string rejection.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      undefinedCheck:
+        'process.env.{{name}} !== undefined accepts the empty string. CI/ConfigMap/compose can export {{name}}="". Use: const v = process.env.{{name}}; v !== undefined && v !== ""',
+      nullishCoalesce:
+        'process.env.{{name}} ?? fallback accepts the empty string (?? only falls through on null/undefined). Use explicit: v !== undefined && v !== "" ? v : fallback'
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      BinaryExpression(node) {
+        if (node.operator !== "!==" && node.operator !== "===") return;
+        const envName = extractProcessEnvName(node.left);
+        if (!envName) return;
+        if (!isUndefinedLiteral(node.right)) return;
+        if (!DATA_ENV_VAR_PATTERN.test(envName)) return;
+
+        context.report({
+          node,
+          messageId: "undefinedCheck",
+          data: { name: envName }
+        });
+      },
+
+      LogicalExpression(node) {
+        if (node.operator !== "??") return;
+        const envName = extractProcessEnvName(node.left);
+        if (!envName) return;
+        if (!DATA_ENV_VAR_PATTERN.test(envName)) return;
+
+        // Allow `?? ""` — caller is explicitly opting into empty as default
+        if (
+          node.right.type === "Literal" &&
+          typeof node.right.value === "string" &&
+          node.right.value === ""
+        ) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "nullishCoalesce",
+          data: { name: envName }
+        });
+      }
+    };
+  }
+};
+
+/**
+ * Returns the env-var name when node is `process.env.X` or `process.env["X"]`,
+ * otherwise null.
+ */
+function extractProcessEnvName(node) {
+  if (!node || node.type !== "MemberExpression") return null;
+  const object = node.object;
+  if (
+    object.type !== "MemberExpression" ||
+    object.object.type !== "Identifier" ||
+    object.object.name !== "process" ||
+    object.property.type !== "Identifier" ||
+    object.property.name !== "env"
+  ) {
+    return null;
+  }
+  if (node.property.type === "Identifier") return node.property.name;
+  if (
+    node.property.type === "Literal" &&
+    typeof node.property.value === "string"
+  ) {
+    return node.property.value;
+  }
+  return null;
+}
+
+function isUndefinedLiteral(node) {
+  if (!node) return false;
+  if (node.type === "Identifier" && node.name === "undefined") return true;
+  if (
+    node.type === "UnaryExpression" &&
+    node.operator === "void" &&
+    node.argument.type === "Literal" &&
+    node.argument.value === 0
+  ) {
+    return true;
+  }
+  return false;
+}

package/no-l2-asg-lifecycle-hook.js

@@ -0,0 +1,61 @@
+/**
+ * ESLint Rule: no-l2-asg-lifecycle-hook
+ *
+ * Disallows `autoScalingGroup.addLifecycleHook(id, props)` — the AWS CDK L2
+ * method that emits a standalone `AWS::AutoScaling::LifecycleHook` resource.
+ * The standalone resource is created AFTER the ASG, so on a fresh stack the
+ * first instance launches BEFORE the hook is attached, and the hook fires
+ * zero notifications for that instance.
+ *
+ * Production-confirmed in account 985539798308 on 2026-05-19: the ClickHouse
+ * PDV LAUNCHING hook never fired for the first instance — the Lambda log
+ * group only saw a TEST_NOTIFICATION ~30s after instance launch. The volume
+ * was never attached, cloud-init timed out, ECS agent never started.
+ *
+ * Required shape: route through `attachInlineAsgLifecycleHook` at
+ * `components/infrastructure/lib/resources/aws/compute/asgInlineLifecycleHook.ts`,
+ * which appends to `CfnAutoScalingGroup.lifecycleHookSpecificationList`. The
+ * spec is then atomic with ASG creation — the ASG cannot exist in a state
+ * where it has instances but no hooks.
+ *
+ * Discriminator: the L2 ASG signature is `addLifecycleHook(id, props)` —
+ * 2 arguments. The ECS service signature is `addLifecycleHook(target)` — 1
+ * argument. This rule flags any 2-arg `.addLifecycleHook(_, _)` call,
+ * which uniquely identifies the ASG L2 footgun regardless of whether the
+ * first arg is a string literal, a template literal, or a variable
+ * reference.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow autoScalingGroup.addLifecycleHook(id, props) — re-introduces the CFN race where the standalone hook resource attaches AFTER the ASG's first instance launches. Use attachInlineAsgLifecycleHook from lib/resources/aws/compute/asgInlineLifecycleHook.ts.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      l2AsgHook:
+        "ASG L2 `addLifecycleHook(id, props)` emits a standalone AWS::AutoScaling::LifecycleHook resource that creates AFTER the ASG — the first instance launches before the hook is attached (production-confirmed regression, account 985539798308, 2026-05-19). Use `attachInlineAsgLifecycleHook` from `lib/resources/aws/compute/asgInlineLifecycleHook.ts`, which appends to `CfnAutoScalingGroup.lifecycleHookSpecificationList` atomically with the ASG."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "MemberExpression") return;
+        const property = node.callee.property;
+        if (property.type !== "Identifier") return;
+        if (property.name !== "addLifecycleHook") return;
+        if (node.arguments.length !== 2) return;
+        context.report({
+          node,
+          messageId: "l2AsgHook"
+        });
+      }
+    };
+  }
+};