declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.github/workflows/provision.yml.declapract.integration.test.ts

@@ -0,0 +1,167 @@
+import { join } from 'node:path';
+
+import { check, fix } from './provision.yml.declapract';
+
+// .note (rule.forbid.as-cast, documented): the declapract context arg is a PARTIAL mock. check
+// reads `context.projectPractices` AND `context.getProjectRootDirectory()`; the `as any` asserts
+// that partial to the full FileCheckContext type. this is the repo-wide test idiom.
+
+// fixture roots (real dirs, read by existsSync — no temp dir, no symlink walk, so a unit test).
+// repo-non-rds ships NO provision callee, so shipsAnyRdsCallee is false there; the two *-callee
+// roots each ship one rds callee on disk, the scope-robust signal that survives a narrow
+// `--practice cicd-service` apply.
+const FIXTURES = join(__dirname, '../../.test/assets');
+const ROOT_NON_RDS = join(FIXTURES, 'repo-non-rds');
+const ROOT_RDS_SCHEMA = join(FIXTURES, 'repo-with-schema-callee');
+const ROOT_RDS_AWS = join(FIXTURES, 'repo-with-aws-resources-callee');
+
+const genContext = (input: { root: string; projectPractices: string[] }) =>
+  ({
+    projectPractices: input.projectPractices,
+    getProjectRootDirectory: () => input.root,
+  }) as any;
+
+// a minimal non-rds superset: the generic `github` job, then the rds-jobs tail (the anchor).
+const supersetContents = `
+jobs:
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      scope: github
+      access: prod
+
+  sql-schema-prep:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      access: prep
+
+  sql-schema-prod:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      access: prod
+
+  aws-prep-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      scope: aws
+      access: prep
+
+  aws-prod-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      scope: aws
+      access: prod
+`.trim();
+
+const RDS_JOBS = [
+  'sql-schema-prep:',
+  'sql-schema-prod:',
+  'aws-prep-declastruct:',
+  'aws-prod-declastruct:',
+];
+
+describe('rds-jobs-in-non-rds-service', () => {
+  describe('check', () => {
+    it('detects the rds-jobs tail in a non-rds service', () => {
+      expect(() =>
+        check(
+          supersetContents,
+          genContext({
+            root: ROOT_NON_RDS,
+            projectPractices: ['cicd-service'],
+          }),
+        ),
+      ).not.toThrow();
+    });
+
+    it('does not match when persist-with-rds is in play — an rds service keeps its jobs', () => {
+      expect(() =>
+        check(
+          supersetContents,
+          genContext({
+            root: ROOT_NON_RDS,
+            projectPractices: ['cicd-service', 'persist-with-rds'],
+          }),
+        ),
+      ).toThrow('does not match bad practice');
+    });
+
+    it('does not match when the rds tail is already gone', () => {
+      const narrowed = supersetContents.split('\n\n  sql-schema-prep:')[0]!;
+      expect(() =>
+        check(
+          narrowed,
+          genContext({
+            root: ROOT_NON_RDS,
+            projectPractices: ['cicd-service'],
+          }),
+        ),
+      ).toThrow('does not match bad practice');
+    });
+
+    // the scope-robust clamp (r11 b2). a narrow `declapract fix --practice cicd-service` darkens
+    // `context.projectPractices` to `['cicd-service']` (getScopedPractices runs BEFORE the
+    // derivation), so the persist-with-rds flag alone would go dark on a GENUINE rds repo and the
+    // strip would truncate its live rds jobs. the callee-on-disk signal does not depend on the
+    // `--practice` filter, so it holds the rds truth under a narrow apply and refuses the strip.
+    it('does NOT strip a genuine rds repo under narrow --practice scope — schema callee on disk', () => {
+      expect(() =>
+        check(
+          supersetContents,
+          genContext({
+            root: ROOT_RDS_SCHEMA, // provision/schema present, though the flag is dark
+            projectPractices: ['cicd-service'],
+          }),
+        ),
+      ).toThrow('does not match bad practice');
+    });
+
+    it('does NOT strip a genuine rds repo under narrow --practice scope — aws resources callee on disk', () => {
+      expect(() =>
+        check(
+          supersetContents,
+          genContext({
+            root: ROOT_RDS_AWS, // provision/aws/resources.ts present, though the flag is dark
+            projectPractices: ['cicd-service'],
+          }),
+        ),
+      ).toThrow('does not match bad practice');
+    });
+  });
+
+  describe('fix', () => {
+    it('strips all 4 rds jobs from a non-rds superset', async () => {
+      const { contents: fixed } = await fix(supersetContents, {} as any);
+      for (const job of RDS_JOBS) expect(fixed).not.toContain(job);
+    });
+
+    it('keeps the generic github job intact', async () => {
+      const { contents: fixed } = await fix(supersetContents, {} as any);
+      expect(fixed).toContain('github:');
+    });
+
+    it('leaves absent contents untouched', async () => {
+      const { contents: fixed } = await fix(null as any, {} as any);
+      expect(fixed).toBeNull();
+    });
+  });
+
+  describe('idempotency (rule.require.idempotent-fixes)', () => {
+    it('check throws on the fixed output — a second pass cannot loop', async () => {
+      const { contents: fixed } = await fix(supersetContents, {} as any);
+      expect(() =>
+        check(
+          fixed as string,
+          genContext({ root: ROOT_NON_RDS, projectPractices: ['cicd-service'] }),
+        ),
+      ).toThrow('does not match bad practice');
+    });
+
+    it('fix(fix(x)) throws loud on the second strip — the anchor is gone', async () => {
+      const { contents: once } = await fix(supersetContents, {} as any);
+      expect(() => fix(once as string, {} as any)).toThrow(
+        'could not find the rds-jobs anchor',
+      );
+    });
+  });
+});

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.github/workflows/provision.yml.declapract.ts

@@ -0,0 +1,88 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import {
+  RDS_JOBS_ANCHOR,
+  withoutRdsJobs,
+} from '../../../../best-practice/.github/workflows/provision.yml.declapract';
+
+/**
+ * .what = detect a non-rds service whose provision.yml still carries the 4 rds-coupled jobs
+ *         (`sql-schema-{prep,prod}`, `aws-{prep,prod}-declastruct`), and strip them.
+ * .why  = the D28 gate in the best-practice `contents` fn omits those 4 jobs for a non-rds usecase,
+ *         but it is `CONTAINS`, so it is fix-forward for FRESH scaffolds only — a superset PASSES
+ *         the contains check. a non-rds repo STAMPED BEFORE the gate already carries the full
+ *         superset, so no best-practice fix fires and its provision workflow keeps failing (the 4
+ *         jobs reference `persist-with-rds` files the repo does not ship) until a human hand-strips
+ *         them. this bad-practice is the retroactive half: it DETECTS the superset in a non-rds repo
+ *         and strips the rds tail, so a pre-stamped consumer converges without a hand edit.
+ * .note = the strip reuses the best-practice's own `withoutRdsJobs` + `RDS_JOBS_ANCHOR`, so the
+ *         truncation boundary is declared ONCE and cannot drift between the fresh-scaffold gate and
+ *         this retroactive strip.
+ */
+
+/**
+ * .what = the rds jobs' own callees — files a genuine rds consumer ships. `sql-schema-{prep,prod}`
+ *         drive the `provision/schema/` tree; `aws-{prep,prod}-declastruct` drive the
+ *         `provision/aws/resources.ts` wish (the generic `github` job's callee is
+ *         `provision/github.repo/resources.ts`, a distinct path, so it is not listed).
+ * .why  = presence of a callee on disk is a SCOPE-ROBUST rds signal, where
+ *         `context.projectPractices` is NOT. declapract derives `projectPractices` AFTER the
+ *         `--practice` filter (getScopedPractices), so a narrow `declapract fix --practice
+ *         cicd-service` on a genuine rds repo shrinks it to `['cicd-service']` and
+ *         `includes('persist-with-rds')` goes DARK — the exact scope-sensitivity hazard
+ *         `rule.avoid.runtime-forks` names. a file on disk does not depend on the `--practice`
+ *         filter, so it holds the rds truth under any invocation. a strip gated on
+ *         caller-without-callee (fire only when the rds callees are genuinely absent) closes the
+ *         destructive path where a dark practice flag alone would truncate a live rds repo's jobs.
+ */
+const RDS_CALLEE_PATHS = ['provision/schema', 'provision/aws/resources.ts'];
+
+const shipsAnyRdsCallee = (context: {
+  getProjectRootDirectory: () => string;
+}): boolean =>
+  RDS_CALLEE_PATHS.some((rel) =>
+    existsSync(path.join(context.getProjectRootDirectory(), rel)),
+  );
+
+/**
+ * .what = detected (return) when this is a non-rds service whose file still holds the rds jobs.
+ *         not-detected (throw) when the repo IS an rds service, or the rds jobs are already gone.
+ * .why  = an rds service LEGITIMATELY keeps those 4 jobs — a strip there is the destructive
+ *         additive-EQUALS hazard the best-practice avoids. two signals mark a repo rds, and the
+ *         strip fires only when NEITHER holds: `persist-with-rds` in the resolved usecase (the
+ *         full-apply signal), OR an rds callee on disk (the scope-robust signal that survives a
+ *         narrow `--practice cicd-service` apply). only a repo that is non-rds by BOTH is in the bad
+ *         state this fix repairs.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  // an rds service keeps its rds jobs — not a bad practice there. EITHER signal marks it rds; the
+  // callee-on-disk one holds even when the `--practice` filter has darkened projectPractices.
+  if (
+    context.projectPractices.includes('persist-with-rds') ||
+    shipsAnyRdsCallee(context)
+  )
+    throw new Error(
+      'does not match bad practice: an rds signal is present (persist-with-rds in the usecase, or a provision/schema | provision/aws/resources.ts callee on disk), so the rds jobs belong',
+    );
+
+  // detected only when the rds-jobs tail is still present
+  if (contents?.includes(RDS_JOBS_ANCHOR)) return;
+
+  // otherwise the rds tail is already gone (or the file is a non-superset shape) — no tail to strip
+  throw new Error(
+    'does not match bad practice: no rds-jobs tail present to strip',
+  );
+};
+
+/**
+ * .what = strip the 4 rds-coupled jobs, keeping every generic job intact.
+ * .why  = reuse the best-practice truncation so the boundary is defined in one place; on an anchor
+ *         miss `withoutRdsJobs` throws LOUD rather than truncating to the whole superset
+ *         (`rule.forbid.failhide`).
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  return { contents: withoutRdsJobs({ contents }) };
+};

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.test/assets/repo-non-rds/readme.md

@@ -0,0 +1,9 @@
+# repo-non-rds
+
+a fixture root for the rds-jobs-in-non-rds-service unit test.
+
+.what = a non-rds consumer — no `provision/schema` dir, no `provision/aws/resources.ts`
+        file on disk, so `shipsAnyRdsCallee` returns false.
+.why  = the "detects" + "already gone" check cases point their
+        `getProjectRootDirectory` here, so the file-on-disk rds signal is genuinely
+        absent and the strip is allowed to fire (or the tail is already gone).

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.test/assets/repo-with-aws-resources-callee/provision/aws/resources.ts

@@ -0,0 +1,5 @@
+// a placeholder declastruct wish so `provision/aws/resources.ts` exists on disk.
+// .why = the second callee-on-disk rds signal. a genuine rds consumer ships this
+//        aws-provision wish; its presence marks the repo rds even when a narrow
+//        `--practice cicd-service` apply has darkened `context.projectPractices`.
+export const getResources = async (): Promise<[]> => [];

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/.test/assets/repo-with-schema-callee/provision/schema/init.sql

@@ -0,0 +1,5 @@
+-- a placeholder schema file so `provision/schema` exists on disk.
+-- .why = this fixture root marks a genuine rds consumer via a callee-on-disk, the
+--        signal that survives a narrow `--practice cicd-service` apply (which darkens
+--        `context.projectPractices`). the scope-robust clamp points its root here.
+select 1;

package/dist/practices/cicd-service/bad-practices/rds-jobs-in-non-rds-service/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,183 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`rds-jobs-in-non-rds-service — the retroactive strip, end to end given: [case1] a pre-stamped non-rds consumer (lambda-service) when: [t0] before the strip then: the pre-stamped superset matches snapshot (the before diff): provision.yml — pre-stamped superset (before strip) 1`] = `
+"name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc; a called workflow cannot exceed its caller's grant
+  contents: read
+
+jobs:
+  aws-test-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/test
+      github-environment-plan: test
+      github-environment-apply: test
+      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 }}
+
+  aws-prep-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prep
+      github-environment-plan: prep
+      github-environment-apply: prep
+      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 }}
+
+  aws-prod-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    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
+      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 }}
+      creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github.repo/resources.ts
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-plan: prod
+      github-environment-apply: prod
+      creds-github-app-owner: \${{ github.repository_owner }}
+      creds-github-app-id: \${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
+    secrets:
+      creds-github-app-private-key: \${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}
+
+  sql-schema-prep:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      access: prep
+      github-environment-plan: prep
+      github-environment-apply: prep
+      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 }}
+
+  sql-schema-prod:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      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
+      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 }}
+      creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  aws-prep-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/aws/resources.ts
+      scope: aws
+      access: prep
+      github-environment-plan: prep
+      github-environment-apply: prep
+      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 }}
+
+  aws-prod-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/aws/resources.ts
+      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
+      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 }}
+      creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+"
+`;
+
+exports[`rds-jobs-in-non-rds-service — the retroactive strip, end to end given: [case1] a pre-stamped non-rds consumer (lambda-service) when: [t1] the bad-practice strip is applied then: the stripped workflow matches snapshot (the strip diff a reviewer eyeballs): provision.yml — non-rds usecase (after strip) 1`] = `
+"name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc; a called workflow cannot exceed its caller's grant
+  contents: read
+
+jobs:
+  aws-test-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/test
+      github-environment-plan: test
+      github-environment-apply: test
+      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 }}
+
+  aws-prep-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prep
+      github-environment-plan: prep
+      github-environment-apply: prep
+      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 }}
+
+  aws-prod-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    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
+      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 }}
+      creds-aws-role-arn-apply: \${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github.repo/resources.ts
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-plan: prod
+      github-environment-apply: prod
+      creds-github-app-owner: \${{ github.repository_owner }}
+      creds-github-app-id: \${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
+    secrets:
+      creds-github-app-private-key: \${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}
+"
+`;

package/dist/practices/cicd-service/best-practice/.declapract.readme.md

@@ -2,3 +2,21 @@ flows:
 - test on every commit
 - deploy to prep every commit on master
 - deploy to prod every v* tagged commit on master
+
+## provision.yml is usecase-aware — the rds jobs gate on persist-with-rds (D28)
+
+`provision.yml` carries 4 rds-coupled jobs (`sql-schema-{prep,prod}`,
+`aws-{prep,prod}-declastruct`) whose callees — `.sql-schema-control.yml` and the
+`provision/aws/resources.ts` wish — are shipped by `persist-with-rds`, not by this practice. so
+`provision.yml.declapract.ts` emits those 4 jobs **only** when `persist-with-rds` is in the resolved
+practice set; a service without rds (`lambda-service`, `lambda-service-with-dynamodb`) gets the
+generic jobs (terraform ×3, github) alone. this is the D28/#573 gate: a caller that names a callee
+another practice supplies must be reconciled against that practice's presence. it uses `CONTAINS`
+(not `EQUALS`) so a narrow `declapract fix --practice cicd-service` never strips an rds repo's jobs.
+the persist-with-rds side documents the same gate from the callee's view.
+
+### the gate is fix-forward for fresh scaffolds
+
+a `CONTAINS` check passes when the file holds the declared narrowed content, so a pre-extant non-rds
+repo that already carries the full superset keeps its rds jobs — the gate emits the narrowed workflow
+for a fresh scaffold, and an extant non-rds repo is a one-time hand-strip of the 4 rds jobs.

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