declapract-typescript-ehmpathy 0.49.15 → 0.50.0

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/.test.yml

@@ -0,0 +1,434 @@
+name: .test
+
+on:
+  workflow_call:
+    inputs:
+      creds-aws-role-arn:
+        description: "creds for aws, specifies the role to assume via oidc. if not provided, aws auth is skipped"
+        required: false
+        type: string
+      creds-aws-region:
+        description: "creds for aws, specifies the region. defaults to us-east-1"
+        required: false
+        type: string
+        default: "us-east-1"
+
+# .why = least privilege: only the jobs that assume the aws role grant id-token, at job scope
+permissions:
+  contents: read
+
+jobs:
+  # install the dependencies
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  # run tests in parallel
+  test-commits:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:commits
+        run: npm run test:commits
+
+  test-types:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: build
+        run: npm run build # build before test:types, to ensure .dist/ artifacts are importable for blackbox tests
+
+      - name: test:types
+        run: npm run test:types
+
+  test-format:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:format
+        run: npm run test:format
+
+  test-lint:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      # .why = lint the same linked .agent/repo=* role tree a laptop holds
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      - name: test:lint
+        run: npm run test:lint
+
+  test-unit:
+    runs-on: ubuntu-24.04
+    needs: [install, test-shards-omit]
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:unit
+        run: THOROUGH=true npm run test:unit
+
+  # shard setup job
+  enshard:
+    name: enshard
+    runs-on: ubuntu-24.04
+    outputs:
+      integration-matrix: ${{ steps.integration.outputs.matrix }}
+      integration-patterns: ${{ steps.integration.outputs.patterns }}
+      acceptance-matrix: ${{ steps.acceptance.outputs.matrix }}
+      acceptance-patterns: ${{ steps.acceptance.outputs.patterns }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          sparse-checkout: |
+            jest.integration.shards.jsonc
+            jest.acceptance.shards.jsonc
+            .github/actions/test-shards-setup
+          sparse-checkout-cone-mode: false
+
+      - name: setup integration shards
+        id: integration
+        uses: ./.github/actions/test-shards-setup
+        with:
+          config-file: jest.integration.shards.jsonc
+          test-type: integration
+
+      - name: setup acceptance shards
+        id: acceptance
+        uses: ./.github/actions/test-shards-setup
+        with:
+          config-file: jest.acceptance.shards.jsonc
+          test-type: acceptance
+
+  # placeholder job for github actions visualization alignment
+  # note: github actions has no column position controls;
+  #       this job pushes test-* jobs one column right to align with test-shards-* column
+  test-shards-omit:
+    runs-on: ubuntu-24.04
+    needs: [install]
+    steps:
+      - run: echo "👌 placeholder for column alignment"
+
+  # shard runner jobs
+  test-shards-integration:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard]
+    permissions:
+      contents: read
+      id-token: write # required for oidc
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ${{ fromJson(needs.enshard.outputs.integration-matrix) }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      # .why = keyrack.yml can extend other manifests via symlinks (e.g., .agent/repo=ehmpathy/role=mechanic/keyrack.yml)
+      #        prepare:rhachet creates these symlinks so keyrack.source() can hydrate extended keys
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      # .why = keyrack firewall translates and validates secrets before tests run
+      #        - filters to declared keys in keyrack.yml
+      #        - translates mechanisms (e.g., GitHub App → ghs_* token)
+      #        - blocks dangerous patterns (ghp_*, AKIA*, etc.)
+      #        - exports to $GITHUB_ENV with mask applied
+      - name: keyrack firewall
+        run: npx rhachet keyrack firewall --env test --from 'json(env://SECRETS_JSON)' --into github.actions
+        env:
+          SECRETS_JSON: ${{ toJSON(secrets) }}
+
+      - name: get aws auth, if creds supplied
+        if: ${{ inputs.creds-aws-role-arn }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
+
+      - name: build
+        run: npm run build
+
+      - name: test:integration (explicit ${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          set -eu
+          patterns='${{ join(matrix.shard.patterns, '|') }}'
+          THOROUGH=true npm run test:integration -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:integration (dynamic ${{ matrix.shard.shard }}/${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          set -eu
+          exclude='${{ needs.enshard.outputs.integration-patterns }}'
+          if [[ -n "$exclude" ]]; then
+            THOROUGH=true npm run test:integration -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          else
+            THOROUGH=true npm run test:integration -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          fi
+
+      - name: report slow tests
+        if: always() && hashFiles('jest-results.json') != ''
+        run: bash .github/workflows/report-slow-tests.sh jest-results.json
+
+  test-shards-acceptance:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard]
+    permissions:
+      contents: read
+      id-token: write # required for oidc
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: ${{ fromJson(needs.enshard.outputs.acceptance-matrix) }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      # .why = keyrack.yml can extend other manifests via symlinks (e.g., .agent/repo=ehmpathy/role=mechanic/keyrack.yml)
+      #        prepare:rhachet creates these symlinks so keyrack.source() can hydrate extended keys
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      # .why = keyrack firewall translates and validates secrets before tests run
+      #        - filters to declared keys in keyrack.yml
+      #        - translates mechanisms (e.g., GitHub App → ghs_* token)
+      #        - blocks dangerous patterns (ghp_*, AKIA*, etc.)
+      #        - exports to $GITHUB_ENV with mask applied
+      - name: keyrack firewall
+        run: npx rhachet keyrack firewall --env test --from 'json(env://SECRETS_JSON)' --into github.actions
+        env:
+          SECRETS_JSON: ${{ toJSON(secrets) }}
+
+      - name: get aws auth, if creds supplied
+        if: ${{ inputs.creds-aws-role-arn }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
+
+      - name: build
+        run: npm run build
+
+      # .why = the PR acceptance gate runs IN-PROCESS (LOCALLY=true), not against a deployed fleet.
+      #        a PR has no deployed lambda to invoke, and a service that publishes only dev/prep (no
+      #        `test` fleet) would target `svc-<name>-test-*` — a slug that does not exist — and 404
+      #        on every call. in-process runs the handler directly, so a fleetless service inherits a
+      #        green PR gate out of the box rather than hand-patching LOCALLY=true into this shard.
+      #        the deployed-fleet acceptance run is a separate post-deploy grain (.deploy-sls.yml).
+      - name: test:acceptance (explicit ${{ matrix.shard.index }})
+        if: matrix.shard.type == 'explicit'
+        run: |
+          set -eu
+          patterns='${{ join(matrix.shard.patterns, '|') }}'
+          LOCALLY=true THOROUGH=true npm run test:acceptance -- --testPathPatterns="$patterns" --json --outputFile=jest-results.json
+
+      - name: test:acceptance (dynamic ${{ matrix.shard.shard }}/${{ matrix.shard.total }})
+        if: matrix.shard.type == 'dynamic'
+        run: |
+          set -eu
+          exclude='${{ needs.enshard.outputs.acceptance-patterns }}'
+          if [[ -n "$exclude" ]]; then
+            LOCALLY=true THOROUGH=true npm run test:acceptance -- --testPathIgnorePatterns="$exclude" --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          else
+            LOCALLY=true THOROUGH=true npm run test:acceptance -- --shard=${{ matrix.shard.shard }}/${{ matrix.shard.total }} --json --outputFile=jest-results.json
+          fi
+
+      - name: report slow tests
+        if: always() && hashFiles('jest-results.json') != ''
+        run: bash .github/workflows/report-slow-tests.sh jest-results.json
+
+  # .why = evaluation tests grade a brain's output and sit outside the unit, integration, and
+  #        acceptance globs, so no other job runs them. in a repo with no `test:evaluation`
+  #        command, every step after the presence check is skipped, so the job costs one checkout
+  test-evaluation:
+    runs-on: ubuntu-24.04
+    needs: [install]
+    permissions:
+      contents: read
+      id-token: write # required for oidc
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: has test:evaluation?
+        id: presence
+        run: echo "declared=$(jq -r '.scripts["test:evaluation"] != null' package.json)" >> "$GITHUB_OUTPUT"
+
+      - name: set node-version
+        if: steps.presence.outputs.declared == 'true'
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: get node-modules from cache
+        if: steps.presence.outputs.declared == 'true'
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: prepare:rhachet
+        if: steps.presence.outputs.declared == 'true'
+        run: npm run prepare:rhachet --if-present
+
+      - name: keyrack firewall
+        if: steps.presence.outputs.declared == 'true'
+        run: npx rhachet keyrack firewall --env test --from 'json(env://SECRETS_JSON)' --into github.actions
+        env:
+          SECRETS_JSON: ${{ toJSON(secrets) }}
+
+      - name: get aws auth, if creds supplied
+        if: ${{ steps.presence.outputs.declared == 'true' && inputs.creds-aws-role-arn }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      - name: start:testdb
+        if: steps.presence.outputs.declared == 'true'
+        run: npm run start:testdb --if-present
+
+      - name: build
+        if: steps.presence.outputs.declared == 'true'
+        run: npm run build
+
+      - name: test:evaluation
+        if: steps.presence.outputs.declared == 'true'
+        run: npm run test:evaluation --if-present
+
+  # union job: aggregates shard results into single status for pr merge constraints
+  test-integration:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard, test-shards-integration]
+    if: always() && needs.install.result == 'success' && needs.enshard.result == 'success'
+    steps:
+      - name: report shard results
+        run: |
+          set -eu
+          if [[ "${{ needs.test-shards-integration.result }}" == "success" ]]; then
+            echo "👌 all integration test shards passed"
+          else
+            echo "::error::some integration test shards failed"
+            exit 1
+          fi
+
+  # union job: aggregates shard results into single status for pr merge constraints
+  test-acceptance-locally:
+    runs-on: ubuntu-24.04
+    needs: [install, enshard, test-shards-acceptance]
+    if: always() && needs.install.result == 'success' && needs.enshard.result == 'success'
+    steps:
+      - name: report shard results
+        run: |
+          set -eu
+          if [[ "${{ needs.test-shards-acceptance.result }}" == "success" ]]; then
+            echo "👌 all acceptance test shards passed"
+          else
+            echo "::error::some acceptance test shards failed"
+            exit 1
+          fi

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/.test.yml.declapract.ts

@@ -0,0 +1,26 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
+
+/**
+ * .what = validates .test.yml matches the template exactly
+ * .why = keyrack firewall handles secrets at runtime; no build-time injection needed
+ */
+export const check = FileCheckType.EQUALS;
+
+/**
+ * .what = replaces .test.yml with the template content
+ * .why = ensures workflow has firewall step for keyrack secrets
+ * .note = fail-fast on absent declared contents. a declared file ALWAYS has content — declapract
+ *         reads the template beside this declaration. so a null/undefined `declaredFileContents`
+ *         is an internal invariant violation (a build wired wrong), never a valid state; a `?? ''`
+ *         would swallow it and write a ZERO-BYTE workflow to a consumer — a silent break the wish
+ *         forbids. throw loud so the misconfigured build surfaces, rather than ship an empty file.
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  if (context.declaredFileContents === null || context.declaredFileContents === undefined)
+    throw new MalfunctionError(
+      'no declaredFileContents for .test.yml — declapract could not read the template beside its declaration',
+      { relativeFilePath: '.github/workflows/.test.yml' },
+    );
+  return { contents: context.declaredFileContents };
+};

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  please-release:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: get github token
+        id: github-token
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
+        with:
+          owner: ${{ github.repository_owner }}
+          repositories: ${{ github.event.repository.name }}
+          app-id: ${{ vars.RHELEASE_APP_ID }}
+          private-key: ${{ secrets.RHELEASE_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.github-token.outputs.token }} # enables git push with app token
+
+      - name: please release
+        uses: ./.github/actions/please-release
+        with:
+          github-token: ${{ steps.github-token.outputs.token }}
+          commit-message: ${{ github.event.head_commit.message }}
+          commit-sha: ${{ github.sha }}
+          repository: ${{ github.repository }}

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/report-slow-tests.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = rank test files by wall-clock duration from a jest --json report
+#
+# .why  = jest 30 dropped the perfStats key that the prior report filtered on
+#         (`perfStats.runtime`), so the filter matched zero rows and the report
+#         went silent-green for its whole life. endTime-startTime
+#         (epoch ms) is the only per-file duration jest 30 still emits, so read
+#         the wall-clock span instead — and fail LOUD if a future schema change
+#         zeroes it again, never silent-green.
+#
+# usage:
+#   report-slow-tests.sh [jest-results.json]
+#
+# guarantee:
+#   - exit 0 = report written to $GITHUB_STEP_SUMMARY (or /dev/null locally)
+#   - exit 0 = empty shard (0 test files) — a legitimate state, stated explicitly
+#   - exit 1 = non-empty report yielded zero real durations (schema drift)
+######################################################################
+set -eu
+
+results="${1:-jest-results.json}"
+
+total=$(jq '.testResults | length' "$results")
+durations=$(jq -r '.testResults[] | "\((.endTime // 0) - (.startTime // 0)):\(.name)"' "$results" | sort -t: -k1 -rn)
+
+summary="${GITHUB_STEP_SUMMARY:-/dev/null}"
+
+# an empty shard (no matched files) is legitimate — say so explicitly, never fail.
+if [[ "$total" -eq 0 ]]; then
+  echo "slow-test report: 0 test files in $results (empty shard)" >> "$summary"
+  exit 0
+fi
+
+# a non-empty testResults that yields zero real durations means the jest --json duration
+# schema changed again — the silent death this check exists to catch. fail loud, never silent-green.
+nonzero=$(printf '%s\n' "$durations" | awk -F: '$1 > 0' | wc -l | tr -d ' ')
+if [[ "$nonzero" -eq 0 ]]; then
+  echo "::error::slow-test report parsed 0 durations from $total test files — the jest --json duration schema likely changed; read endTime/startTime from one entry of $results to see what moved"
+  exit 1
+fi
+
+# a ranked table into the step summary — annotations cannot be sorted, and a diagnosis
+# needs the order (the single slowest file sets the suite's wall-clock floor).
+{
+  echo "### slowest test files"
+  echo ""
+  echo "| duration | file |"
+  echo "| --- | --- |"
+  printf '%s\n' "$durations" | while IFS=: read -r ms name; do
+    [ -z "$name" ] && continue
+    printf '| %ds | %s |\n' "$((ms / 1000))" "$name"
+  done
+} >> "$summary"
+
+# inline annotations flag the outliers at their file (the 30s/10s thresholds are inherited).
+printf '%s\n' "$durations" | while IFS=: read -r ms name; do
+  [ -z "$name" ] && continue
+  seconds=$((ms / 1000))
+  if [[ $seconds -ge 30 ]]; then
+    echo "::warning file=${name}::slow test: ${seconds}s"
+  elif [[ $seconds -ge 10 ]]; then
+    echo "::notice file=${name}::test duration: ${seconds}s"
+  fi
+done

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/review.yml

@@ -0,0 +1,26 @@
+name: review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pullreq-title:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: test:pullreq:title
+        uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # https://github.com/commitizen/conventional-commit-types
+          types: |
+            fix
+            feat
+            chore

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: test
+
+on:
+  workflow_call:
+  push:
+    branches-ignore:
+      - main # exclude main branch, since deploy workflow triggers on main, and calls the test workflow inside of it already
+    tags-ignore:
+      - v* # exclude tags, since deploy workflow triggers on tags, and calls the test workflow inside of it already
+
+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
+  contents: read
+
+jobs:
+  suite:
+    uses: ./.github/workflows/.test.yml
+    with:
+      creds-aws-region: us-east-1
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }} # use aws auth via oidc, if this repo supplies it
+    secrets: inherit # keyrack firewall in .test.yml filters to declared keys

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/best-practice/.github/workflows/test.yml.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = validates test.yml matches the template exactly
+ * .why = secrets: inherit passes all secrets to .test.yml; firewall handles key filter at runtime
+ */
+export const check = FileCheckType.EQUALS;
+
+/**
+ * .what = replaces test.yml with the template content
+ * .why = ensures caller workflow has secrets: inherit for firewall
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  return { contents: context.declaredFileContents ?? '' };
+};

package/dist/.test/assets/cicd-common/declarations/practices/cicd-common/declastruct-insync-grep.declapract.integration.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #561: the .declastruct.yml apply-gate greps the LOWERCASE marker declastruct
+ *         actually emits (`🎉 everything is in sync!`), so the in-sync fast path is live, not dead.
+ * .why  = declastruct's marker is lowercase (planChanges.ts: `context.log.info('🎉 everything is in
+ *         sync!')`). a capital-E `Everything is in sync` grep is case-sensitive and never matches, so
+ *         every plan falls to the has-changes-planned=true arm — a fast path dead its whole life. it
+ *         fails SAFE (over-gates), so no alarm ever fired; a clamp is the only thing that keeps the
+ *         grep tied to the tool's real output.
+ * .teeth = revert the grep to `grep "Everything is in sync"` (capital E) and the "greps the
+ *          lowercase marker" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the practice
+ *         ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('cicd-common .declastruct.yml in-sync grep', () => {
+  given('the shipped .declastruct.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.declastruct.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // declastruct emits this literal phrase, lowercase; the workflow must match it verbatim
+      const markerLower = 'everything is in sync';
+      const markerCapital = 'Everything is in sync';
+
+      then('it greps the lowercase marker declastruct actually emits', () => {
+        expect(yml).toContain(`grep -qF "${markerLower}"`);
+      });
+
+      then('it does NOT grep the capital-E form that never matches (#561)', () => {
+        expect(yml).not.toContain(markerCapital);
+      });
+
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        // snapshot the caller-faced contract itself, so a reword that keeps the
+        // marker token green (a re-ordered -qF, a re-phrased fallback) reddens a vibecheck
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep -qF "'));
+        expect(grepLine?.trim()).toMatchSnapshot('declastruct apply-gate grep');
+      });
+    });
+  });
+});