declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml

@@ -3,13 +3,13 @@ name: .deploy-sls
 on:
   workflow_call:
     inputs:
-      stage:
+      access:
         type: string
-        description: "the stage to deploy to"
+        description: "the access to deploy with (test | prep | prod)"
         required: true
       github-environment-apply:
         type: string
-        description: "github environment for the deploy jobs (prod only; omit for prep — its oidc role is repo-scoped, no env claim)"
+        description: "github environment for the deploy jobs"
       creds-aws-region:
         description: "creds for aws, specifies the region"
         required: true
@@ -38,7 +38,12 @@ jobs:
 
   deploy:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
+      # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on
+      # the PR timeline. the environment is ALWAYS declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: [install]
     steps:
       - name: checkout
@@ -63,11 +68,16 @@ jobs:
           fail-on-cache-miss: true
 
       - name: deploy
-        run: ACCESS=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy
+        run: ACCESS=${{ inputs.access }} DEPLOYER_NAME="${GITHUB_ACTOR:-}" npm run deploy
 
   assure:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
+      # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on
+      # the PR timeline. the environment is ALWAYS declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: [install, deploy]
     steps:
       - name: checkout
@@ -98,10 +108,16 @@ jobs:
 
       - name: vpc:tunnel:open
         if: inputs.needs-vpn-for-acceptance
-        run: npx rhx use.vpc.tunnel --env ${{ inputs.stage }}
-
+        run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
+
+      # acceptance targets the contemp fleet — the service's own access-tier slug (-prep- at prep,
+      # -prod- at prod). dual-publish ships the SAME artifact under the ancient (-dev-) slug too, so
+      # a run against contemp proves the deployed code; the ancient slug is an alias for inbound
+      # callers still on the old name, never a second target to test. contemp maps to the deployed
+      # access at both prep and prod, so one run covers every tier this job deploys — no
+      # per-fleet fan-out, no per-tier skip.
       - name: test:acceptance
-        run: ACCESS=${{ inputs.stage }} npm run test:acceptance
+        run: ACCESS=${{ inputs.access }} npm run test:acceptance
 
       - name: alarm on failure
         env:
@@ -114,7 +130,12 @@ jobs:
 
   prune:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in environment gate (required reviewers, tag/branch
+      # policy) but suppresses the auto-Deployment, so no "deployed to <env>" status accretes on
+      # the PR timeline. the environment is ALWAYS declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: [install, deploy]
     steps:
       - name: checkout
@@ -139,4 +160,4 @@ jobs:
           fail-on-cache-miss: true
 
       - name: prune
-        run: ACCESS=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy:prune
+        run: ACCESS=${{ inputs.access }} DEPLOYER_NAME="${GITHUB_ACTOR:-}" npm run deploy:prune

package/dist/practices/cicd-service/best-practice/.github/workflows/.sql-schema-control.yml

@@ -3,16 +3,16 @@ name: .sql-schema-control
 on:
   workflow_call:
     inputs:
-      stage:
+      access:
         type: string
-        description: "the stage to execute against"
+        description: "the access to execute with (test | prep | prod)"
         required: true
       github-environment-plan:
         type: string
-        description: "github environment for the plan job (prod only; omit for prep — its oidc role is repo-scoped, no env claim)"
+        description: "github environment for the plan job"
       github-environment-apply:
         type: string
-        description: "github environment for the apply job (prod only; omit for prep)"
+        description: "github environment for the apply job"
       allow-apply:
         type: boolean
         description: "whether the apply step is enabled. defaults to true on main"
@@ -40,7 +40,12 @@ jobs:
 
   plan:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-plan }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-plan }}
+      deployment: false
     needs: [install]
     # opt into the readonly plan grant for every step in this job (tunnel + plan
     # both call getConfig): under plan the oidc role can read only the for-plan
@@ -77,12 +82,12 @@ jobs:
         run: npm run prepare:rhachet --if-present
 
       - name: vpc:tunnel:open
-        run: npx rhx use.vpc.tunnel --env ${{ inputs.stage }}
+        run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
 
       - name: plan
         run: |
           set -o pipefail
-          ACCESS=${{ inputs.stage }} npm run provision:schema:plan | tee ./plan.log
+          ACCESS=${{ inputs.access }} npm run provision:schema:plan | tee ./plan.log
 
       - name: evaluate plan
         id: evaluate-plan
@@ -107,7 +112,12 @@ jobs:
 
   apply:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: [install, plan]
     if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
     steps:
@@ -138,7 +148,7 @@ jobs:
         run: npm run prepare:rhachet --if-present
 
       - name: vpc:tunnel:open
-        run: npx rhx use.vpc.tunnel --env ${{ inputs.stage }}
+        run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
 
       - name: apply
-        run: ACCESS=${{ inputs.stage }} npm run provision:schema:apply
+        run: ACCESS=${{ inputs.access }} npm run provision:schema:apply

package/dist/practices/cicd-service/best-practice/.github/workflows/.terraform.yml

@@ -8,10 +8,10 @@ on:
         description: "the directory from within which to execute terraform commands"
       github-environment-plan:
         type: string
-        description: "github environment for the plan job (prod only; omit for prep — its oidc role is repo-scoped, no env claim)"
+        description: "github environment for the plan job"
       github-environment-apply:
         type: string
-        description: "github environment for the apply job (prod only; omit for prep)"
+        description: "github environment for the apply job"
       allow-apply:
         type: boolean
         description: "whether the apply step is enabled. defaults to true on main"
@@ -36,7 +36,12 @@ permissions:
 jobs:
   plan:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-plan }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-plan }}
+      deployment: false
     defaults:
       run:
         working-directory: ${{ inputs.working-directory }}
@@ -81,7 +86,12 @@ jobs:
 
   apply:
     runs-on: ubuntu-24.04
-    environment: ${{ inputs.github-environment-apply }}
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
     needs: plan
     if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
     defaults:

package/dist/practices/cicd-service/best-practice/.github/workflows/deploy.yml

@@ -9,8 +9,8 @@ on:
       - "master"
   workflow_dispatch:
     inputs:
-      stage:
-        description: "which stage do you want to deploy to?"
+      access:
+        description: "which access do you want to deploy with?"
         type: choice
         options:
           - prep
@@ -47,23 +47,31 @@ jobs:
     uses: ./.github/workflows/.deploy-sls.yml
     needs: [test]
     if: |
-      ((github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch') || github.event.inputs.stage == 'prep') &&
+      ((github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch') || github.event.inputs.access == 'prep') &&
       always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
-    # prep omits github-environment: the ahbode-prep-oidc role trusts any branch
-    # (repo-scoped sub), so no env claim is needed — only prod gates on environment.
+    # github-environment is ALWAYS declared — for prep as well as prod. deployment:false (in
+    # .deploy-sls.yml) keeps the gate (required reviewers, oidc claim) and suppresses the
+    # PR-timeline Deployment spam, so prep declares its environment without the noise.
     with:
-      stage: prep
+      access: prep
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
   prod:
     uses: ./.github/workflows/.deploy-sls.yml
     if: |
-      (startsWith(github.ref, 'refs/tags/') && github.event_name != 'workflow_dispatch') || (github.event.inputs.stage == 'prod') &&
+      ((startsWith(github.ref, 'refs/tags/') && github.event_name != 'workflow_dispatch') || github.event.inputs.access == 'prod') &&
       always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
     needs: [test]
     with:
-      stage: prod
-      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      access: prod
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
       creds-aws-region: us-east-1
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+    secrets:
+      # .deploy-sls.yml declares AND uses this secret to page on a failed prod deploy/acceptance.
+      # omit it and the alarm step's `if: env.PAGERDUTY_INTEGRATION_KEY` is false, so the step is
+      # SKIPPED silently and prod alerts are dead. the callee marks it `required: false`, so github
+      # never errors on the omission — this pass-through is what keeps the alert live.
+      pagerduty-integration-key: ${{ secrets.PAGERDUTY_INTEGRATION_KEY }}

package/dist/practices/cicd-service/best-practice/.github/workflows/provision.yml

@@ -21,10 +21,10 @@ permissions:
 jobs:
   aws-test-terraform:
     uses: ./.github/workflows/.terraform.yml
-    # prep omits github-environment: the ahbode-prep-oidc role trusts any branch
-    # (repo-scoped sub), so no env claim is needed — only prod gates on environment.
     with:
       working-directory: provision/aws/environments/test
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -33,6 +33,8 @@ jobs:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -42,7 +44,7 @@ jobs:
     with:
       working-directory: provision/aws/environments/prod
       github-environment-plan: production-on-else-plan
-      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
@@ -54,7 +56,8 @@ jobs:
       wish-path: provision/github.repo/resources.ts
       scope: github
       access: prod # github repo settings are inherently a prod resource
-      github-environment-apply: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply
       creds-github-app-owner: ${{ github.repository_owner }}
       creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
     secrets:
@@ -62,9 +65,10 @@ jobs:
 
   sql-schema-prep:
     uses: ./.github/workflows/.sql-schema-control.yml
-    # prep omits github-environment (repo-scoped oidc role, any branch, no env claim)
     with:
-      stage: prep
+      access: prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -72,9 +76,9 @@ jobs:
   sql-schema-prod:
     uses: ./.github/workflows/.sql-schema-control.yml
     with:
-      stage: prod
+      access: prod
       github-environment-plan: production-on-else-plan
-      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
@@ -82,11 +86,12 @@ jobs:
 
   aws-prep-declastruct:
     uses: ./.github/workflows/.declastruct.yml
-    # prep omits github-environment (repo-scoped oidc role, any branch, no env claim)
     with:
       wish-path: provision/aws/resources.ts
       scope: aws
       access: prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
       creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
@@ -98,7 +103,7 @@ jobs:
       scope: aws
       access: prod
       github-environment-plan: production-on-else-plan
-      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
       creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}

package/dist/practices/cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts

@@ -0,0 +1,74 @@
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
+
+import { readFile } from '../../../../../utils/readFile';
+
+/**
+ * .what = declare the service provision workflow, with the 4 rds-coupled jobs
+ *         (`sql-schema-{prep,prod}`, `aws-{prep,prod}-declastruct`) included only when the
+ *         `persist-with-rds` practice is in play for the project.
+ * .why  = those 4 jobs reference files `persist-with-rds` owns — its schema + daos (the
+ *         `.sql-schema-control.yml` callee) and its `provision/aws/resources.ts` wish (the
+ *         declastruct callee). a service WITHOUT rds (`lambda-service`,
+ *         `lambda-service-with-dynamodb`) ships none of them, so those jobs fail its own
+ *         provision workflow — D28/#573, live on 2 of 3 service usecases. a branch on
+ *         `context.projectPractices` lets one practice serve all three usecases
+ *         (`rule.avoid.runtime-forks`), and CONTAINS (not EQUALS) keeps a narrow
+ *         `--practice cicd-service` apply from a strip of an rds repo's own jobs — the additive
+ *         usecase-delta EQUALS hazard named in that rule's caveat table.
+ * .note = the 4 rds jobs are the contiguous tail after the generic `github` job, so a split on
+ *         the first rds job header (`sql-schema-prep:`) truncates the whole rds block cleanly.
+ */
+
+// the header of the first rds-coupled job; the 4 rds jobs are the contiguous tail after it
+export const RDS_JOBS_ANCHOR = '\n\n  sql-schema-prep:';
+
+/**
+ * .what = the text before the first rds-job header — the generic-jobs prefix.
+ * .why  = names the positional truncation as one intent, so `withoutRdsJobs` reads what-not-how
+ *         rather than an inline positional `split(...)[0]` a reader must mentally simulate
+ *         (`rule.forbid.inline-decode-friction`).
+ */
+const asPrefixBeforeRdsJobs = (input: { contents: string }): string =>
+  input.contents.split(RDS_JOBS_ANCHOR)[0]!;
+
+/**
+ * .what = drop the 4 rds-coupled jobs — the contiguous tail after the generic `github` job — by a
+ *         truncation at the first rds job header. returns the generic-jobs prefix, newline-terminated.
+ * .why  = names the strip as one intent so the orchestrator reads what-not-how, rather than an inline
+ *         positional `split(...)[0]` a reader must mentally simulate (`rule.forbid.inline-decode-friction`).
+ * .note = the anchor is a text boundary, not a structural parse. a miss (a re-indent, a comment added
+ *         mid-block, a re-order of the rds block) throws loudly rather than fails OPEN — a bare
+ *         `split(...)[0]` on a missed anchor returns the WHOLE superset, so a non-rds consumer would
+ *         silently inherit all 4 rds jobs and CONTAINS would still pass (a superset holds the declared
+ *         prefix). that silent re-ship is the exact D28 break this strip exists to close, so a load
+ *         anchor miss must fail LOUD (`rule.forbid.failhide` / `rule.require.failfast`).
+ */
+export const withoutRdsJobs = (input: { contents: string }): string => {
+  // fail loud if the anchor is absent — never truncate to the whole superset on a miss. this is a
+  // server-side malfunction (this practice's own template shape changed, not a consumer input), so a
+  // MalfunctionError (exit 1) carries the who-fixes semantic — a retried/automated caller can
+  // machine-distinguish a transient malfunction from a caller constraint (exit 2), consistent with
+  // the failures this same round converts to ConstraintError elsewhere
+  // (`rule.require.failloud` / `rule.require.exit-code-semantics`)
+  if (!input.contents.includes(RDS_JOBS_ANCHOR))
+    throw new MalfunctionError(
+      `could not find the rds-jobs anchor ('${RDS_JOBS_ANCHOR}') in provision.yml — the template shape changed; a non-rds strip cannot proceed without re-ship of the rds jobs`,
+    );
+
+  return `${asPrefixBeforeRdsJobs({ contents: input.contents })}\n`;
+};
+
+export const contents: FileContentsFunction = async (context) => {
+  // grab the superset — the full workflow, rds jobs included
+  const contentsSuperset = await readFile({
+    filePath: `${__dirname}/provision.yml`,
+  });
+
+  // keep every job for an rds service; drop the rds tail for a non-rds one
+  return context.projectPractices.includes('persist-with-rds')
+    ? contentsSuperset
+    : withoutRdsJobs({ contents: contentsSuperset });
+};
+
+export const check = FileCheckType.CONTAINS;

package/dist/practices/cicd-service/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "devDependencies": {
-    "declastruct": "@declapract{check.minVersion('1.9.1')}",
-    "declastruct-aws": "@declapract{check.minVersion('1.9.0')}",
-    "declastruct-unix-network": "@declapract{check.minVersion('1.0.5')}"
+    "declastruct": "@declapract{check.minVersion('1.9.2')}",
+    "declastruct-aws": "@declapract{check.minVersion('1.11.0')}",
+    "declastruct-unix-network": "@declapract{check.minVersion('1.1.0')}"
   }
 }

package/dist/practices/cicd-service/insync-grep.declapract.integration.test.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the two peer apply-gate greps in cicd-service to the LITERAL in-sync marker
+ *         each tool actually emits, so the has-changes-planned=false fast path stays live — the same
+ *         guard #561 added for cicd-common/.declastruct.yml, extended to its two untested peers.
+ * .why  = an apply-gate greps the tool's plan log for an "in sync / no changes" phrase to skip a
+ *         redundant apply. if the grep string drifts from the tool's real output (the #561 failure:
+ *         a capital-E grep vs a lowercase marker), the fast path silently dies — every plan falls to
+ *         has-changes-planned=true and apply always runs. it fails SAFE (over-gates, a redundant
+ *         idempotent apply), so no alarm ever fires; a clamp tied to the tool's real output is the
+ *         only guard that catches such a drift.
+ * .verified = both markers match the tool's real output as of this clamp:
+ *         - sql-schema-control emits `Everything is up to date 🎉` (capital E) — displayPlans.ts:28
+ *           + src/contract/__snapshots__/cli.acceptance.test.ts.snap.
+ *         - terraform emits `No changes. Your infrastructure matches the configuration.` — the
+ *           standard `terraform plan` no-change line.
+ * .teeth = drift either grep (e.g. lowercase the sql marker, or reword the terraform phrase) and the
+ *          assertion for that grep reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname/best-practice. this file sits at
+ *         the practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('cicd-service apply-gate in-sync greps', () => {
+  given('the shipped .sql-schema-control.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.sql-schema-control.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // sql-schema-control emits this literal phrase (capital E); the workflow must match it verbatim
+      const marker = 'Everything is up to date';
+
+      then('it greps the marker sql-schema-control actually emits', () => {
+        expect(yml).toContain(`grep "${marker}" ./plan.log`);
+      });
+
+      // the emitted grep line is the caller-faced contract: snapshot it so a reword that keeps
+      // the marker token green reddens a vibecheck.
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep "') && line.includes('./plan.log'));
+        expect(grepLine?.trim()).toMatchSnapshot('sql-schema-control apply-gate grep');
+      });
+    });
+  });
+
+  given('the shipped .terraform.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.terraform.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // terraform emits `No changes. Your infrastructure matches the configuration.` on a clean plan
+      const marker = 'infrastructure matches the configuration';
+
+      then('it greps the marker terraform actually emits', () => {
+        expect(yml).toContain(`grep "${marker}" ./plan.log`);
+      });
+
+      // the emitted grep line is the caller-faced contract: snapshot it so a reword that keeps
+      // the marker token green reddens a vibecheck.
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep "') && line.includes('./plan.log'));
+        expect(grepLine?.trim()).toMatchSnapshot('terraform apply-gate grep');
+      });
+    });
+  });
+});