declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/environments/declarations/practices/environments/bad-practices/old-stage-enum/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,304 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import * as ts from 'typescript';
+
+// `Stage.DEVELOPMENT` (value `'dev'`) was overloaded across two axes: the access
+// (→ 'prep') and the deploy-stage slug (→ 'dev'). a rewrite cannot know which axis a given
+// occurrence sits on. so the fix NEVER guesses it: `Stage.PRODUCTION` and `Stage.TEST` are
+// unambiguous and migrate to `'prod'` / `'test'`, but `Stage.DEVELOPMENT` is LEFT IN PLACE.
+// because it is left, `check` still detects it, so `declapract plan` stays RED until a
+// human decides the axis by hand — the loud, plan-visible "leave the file in violation"
+// signal guard #3 demands, never a green plan that hides a possibly-wrong `'prep'` guess.
+//
+// a red plan alone does not say WHERE the unsettled reference sits or WHAT the human must
+// do, so the fix also inserts a `// @declapract:review:` COMMENT directly above each
+// `Stage.DEVELOPMENT` line. the comment names the file location (it rides the very line) and
+// the choice to make (an access, or the deploy-stage slug). it is a COMMENT, not a value
+// splice — the real `Stage.DEVELOPMENT` property access is untouched — so it neither guesses a
+// value NOR clears the check (a comment is not a property-access node, so the parser still
+// detects the real reference and `plan` stays red). idempotent: a line that already holds the
+// marker is skipped, so a second `fix` pass adds no second marker.
+//
+// this pairs with, and is deliberately UNLIKE, an earlier shape that rewrote
+// `Stage.DEVELOPMENT` → `'prep' /* marker */`. that VALUE-SPLICE shape (a) still GUESSED
+// `'prep'` (a deploy-stage occurrence, whose correct value is `'dev'`, was silently
+// mis-migrated), and (b) once it rewrote the reference, the check no longer matched, so `plan`
+// read CLEAN with a possibly-wrong value — the exact silent-break class this wish exists to
+// retire. the COMMENT marker forecloses both: no value is emitted (no guess), and the
+// still-red plan cannot hide the unsettled axis — it now carries the pointer + the hint.
+
+/**
+ * .what = find every `Stage.<member>` reference in real code, via the typescript parser. three
+ *         node shapes carry it: a value-position PROPERTY ACCESS (`Stage.PRODUCTION`), a
+ *         type-position QUALIFIED NAME (`x: Stage.PRODUCTION`), and a bracket ELEMENT ACCESS with a
+ *         string-literal key (`Stage['PRODUCTION']`). all three name the same enum member and must
+ *         migrate together.
+ * .why  = the parser classifies every token exactly, so a `Stage.PRODUCTION` that sits inside a
+ *         comment, a string literal, a template literal's static text, or a REGEX literal is that
+ *         token's own text — never one of these three nodes — and is therefore invisible to this
+ *         walk BY CONSTRUCTION. a live `${Stage.X}` interpolation, by contrast, IS a property
+ *         access and is found. this forecloses the whole "a value spliced into a non-code span"
+ *         corruption class that a hand-rolled character mask could only chase one token position
+ *         at a time — a `/` after `}`/`)`/`]`, a regex nested in a `${...}`, a brace inside an
+ *         interpolated string — each a fresh hole. the parser has none. and the type + bracket
+ *         positions close the mirror hole: a `Stage.DEVELOPMENT` in a type annotation or a
+ *         `Stage['DEVELOPMENT']` bracket lookup is just as axis-ambiguous as the value form, so it
+ *         too must keep `check` red until a human settles it.
+ * .note = a `Stage.X` is matched wherever the top-level identifier `Stage` is accessed. a consumer
+ *         that shadows the enum with its own object literally named `Stage` is an accepted,
+ *         disclosed residual — the org-standard enum name is not re-used locally in practice.
+ */
+type StageAccess = { member: string; start: number; end: number };
+
+const getStageAccesses = (contents: string): StageAccess[] => {
+  const source = ts.createSourceFile(
+    'stage-scan.ts',
+    contents,
+    ts.ScriptTarget.Latest,
+    true, // setParentNodes — so getStart(source) reads real offsets
+    ts.ScriptKind.TS,
+  );
+  const accesses: StageAccess[] = [];
+  const visit = (node: ts.Node): void => {
+    // value position: `Stage.PRODUCTION`
+    if (
+      ts.isPropertyAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage'
+    )
+      accesses.push({
+        member: node.name.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // type position: `x: Stage.PRODUCTION` (a QualifiedName, `left.right`)
+    if (
+      ts.isQualifiedName(node) &&
+      ts.isIdentifier(node.left) &&
+      node.left.text === 'Stage'
+    )
+      accesses.push({
+        member: node.right.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // bracket position: `Stage['PRODUCTION']` (an ElementAccess with a string-literal key)
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage' &&
+      ts.isStringLiteral(node.argumentExpression)
+    )
+      accesses.push({
+        member: node.argumentExpression.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return accesses;
+};
+
+// only PRODUCTION + TEST are unambiguous (prod → 'prod', test → 'test'). DEVELOPMENT is
+// axis-ambiguous and is deliberately NOT mapped here — it is never rewritten.
+const replacementFor = (member: string): string =>
+  member === 'PRODUCTION' ? "'prod'" : "'test'";
+
+/**
+ * .what = replace every unambiguous `Stage.PRODUCTION`/`Stage.TEST` PROPERTY ACCESS with its
+ *         string literal, spliced into the ORIGINAL at the parser's node offsets — so a comment,
+ *         string, template-static, or regex mention is preserved byte-for-byte (it is not a
+ *         property-access node, so it is never in the splice set). `Stage.DEVELOPMENT` is never in
+ *         the set, so it is left in place (never guessed).
+ * .why  = keeps `fix` a what-not-how read; the splice + offset math lives in this one op.
+ */
+const withUnambiguousStageRefsReplaced = (input: {
+  contents: string;
+}): string => {
+  const accesses = getStageAccesses(input.contents)
+    .filter(
+      (access) => access.member === 'PRODUCTION' || access.member === 'TEST',
+    )
+    .sort((a, b) => a.start - b.start);
+  // a pure fold over the sorted accesses — carries { spliced, last } with no mutable accumulator
+  // (rule.forbid.maintenance-hazards). each step appends the gap since the prior splice plus this
+  // member's literal, then advances the cursor past the property access.
+  const { spliced, last } = accesses.reduce(
+    (acc, access) => ({
+      spliced:
+        acc.spliced +
+        input.contents.slice(acc.last, access.start) +
+        replacementFor(access.member),
+      last: access.end,
+    }),
+    { spliced: '', last: 0 },
+  );
+  return spliced + input.contents.slice(last);
+};
+
+/**
+ * .what = drop the now-unused `Stage` named-import specifier — ONLY when no real-code `Stage.`
+ *         reference remains. done via the parser, so the `Stage` specifier is dropped wherever it
+ *         sits in the named-bindings list — first (`{ Stage, A }`), last (`{ A, Stage }`), or MIDDLE
+ *         (`{ A, Stage, B }`) — and the surviving specifiers are preserved verbatim. when `Stage`
+ *         is the sole specifier, the whole import statement (and its trailing newline) is removed.
+ * .why  = a leftover `Stage.DEVELOPMENT` still needs the import to compile, so the import is kept
+ *         while any real reference survives; keeps `fix` a what-not-how read. the parser finds the
+ *         specifier by its position in the list, so a mid-list `Stage` — which a first/last-only
+ *         regex silently skips, leaving a dead import that fails the lint — is dropped like any
+ *         other. a comment/string mention of `Stage` is not an import specifier, so it is untouched.
+ */
+const withUnusedStageImportRemoved = (input: { contents: string }): string => {
+  if (getStageAccesses(input.contents).length > 0) return input.contents;
+
+  const source = ts.createSourceFile(
+    'stage-import-scan.ts',
+    input.contents,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+  // find the `Stage` named-import specifier + the NamedImports list it sits in, via the parser
+  const found = source.statements.reduce<{
+    named: ts.NamedImports;
+    decl: ts.ImportDeclaration;
+  } | null>((hit, statement) => {
+    if (hit) return hit;
+    if (!ts.isImportDeclaration(statement)) return null;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) return null;
+    const hasStage = bindings.elements.some(
+      (specifier) => specifier.name.text === 'Stage',
+    );
+    return hasStage ? { named: bindings, decl: statement } : null;
+  }, null);
+
+  // no `Stage` specifier to drop → leave the file byte-for-byte
+  if (!found) return input.contents;
+
+  // the survivors — every specifier that is not `Stage`, kept verbatim by their source text
+  const survivors = found.named.elements.filter(
+    (specifier) => specifier.name.text !== 'Stage',
+  );
+
+  // sole specifier → remove the whole import statement, including its trailing newline
+  if (survivors.length === 0) {
+    const declStart = found.decl.getStart(source);
+    const declEnd = found.decl.getEnd();
+    const withTrailingNewline =
+      input.contents[declEnd] === '\n' ? declEnd + 1 : declEnd;
+    return (
+      input.contents.slice(0, declStart) +
+      input.contents.slice(withTrailingNewline)
+    );
+  }
+
+  // otherwise, rebuild the named-bindings list from the survivors + splice it over the original
+  const rebuilt = `{ ${survivors
+    .map((specifier) => specifier.getText(source))
+    .join(', ')} }`;
+  return (
+    input.contents.slice(0, found.named.getStart(source)) +
+    rebuilt +
+    input.contents.slice(found.named.getEnd())
+  );
+};
+
+// the review pointer inserted above each axis-ambiguous `Stage.DEVELOPMENT` line. it names WHERE
+// (it rides the reference's line) and WHAT (pick an access, or the deploy-stage slug). the
+// literal `Stage.DEVELOPMENT` text here sits in a `//` comment, so the parser never reads it as a
+// property access — it never keeps the check red on its own, and it never adds a second real ref.
+const REVIEW_MARKER =
+  "// @declapract:review: Stage.DEVELOPMENT is axis-ambiguous — pick by hand: an access ('test'|'prep'|'prod') or the deploy-stage slug ('dev'), then delete this marker";
+
+/**
+ * .what = insert a `// @declapract:review:` comment above each `Stage.DEVELOPMENT` line, once.
+ * .why  = the fix leaves `Stage.DEVELOPMENT` in place so `plan` stays red (guard #3), but a bare
+ *         red plan names neither the file/line nor the axis to pick. the comment supplies both,
+ *         without a value guess and without a cleared check (a comment is not a property access).
+ *         each line is marked at most once (idempotent), so a re-apply is a no-op.
+ */
+const withDevelopmentAxisReviewMarker = (input: {
+  contents: string;
+}): string => {
+  // the start offset of every line that holds a real `Stage.DEVELOPMENT` property access
+  const lineStarts = Array.from(
+    new Set(
+      getStageAccesses(input.contents)
+        .filter((access) => access.member === 'DEVELOPMENT')
+        .map(
+          (access) => input.contents.lastIndexOf('\n', access.start - 1) + 1,
+        ),
+    ),
+  ).sort((a, b) => b - a); // splice bottom-up so lower offsets stay valid
+
+  // a pure fold over the bottom-up line starts — carries the text-so-far with no mutable
+  // accumulator (rule.forbid.maintenance-hazards). each step splices the marker above its line, or
+  // returns the text unchanged when the contiguous comment block just above already holds the
+  // marker (idempotent).
+  return lineStarts.reduce((out, lineStart) => {
+    const indent = out.slice(lineStart).match(/^[ \t]*/)?.[0] ?? '';
+
+    // idempotent guard: walk up the CONTIGUOUS `//` comment block directly above this line and skip
+    // if any of its lines already holds the marker. a single-line check above would miss a marker
+    // that a reformat pushed one line up (e.g. a blank-less comment now sits between it and the
+    // reference), so it would double-insert. the block scan sees the whole comment run.
+    const priorBlockHoldsMarker = (() => {
+      const walk = (cursor: number): boolean => {
+        if (cursor === 0) return false;
+        const priorStart = out.lastIndexOf('\n', cursor - 2) + 1;
+        const priorLine = out.slice(priorStart, cursor - 1);
+        if (priorLine.includes('@declapract:review')) return true;
+        // stop at the first non-comment line — the comment block ends there
+        if (!priorLine.trimStart().startsWith('//')) return false;
+        return walk(priorStart);
+      };
+      return walk(lineStart);
+    })();
+    if (priorBlockHoldsMarker) return out;
+
+    return (
+      out.slice(0, lineStart) +
+      indent +
+      REVIEW_MARKER +
+      '\n' +
+      out.slice(lineStart)
+    );
+  }, input.contents);
+};
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents)
+    throw new Error(
+      'does not match bad practice: file has no contents to scan for a Stage.* enum reference',
+    );
+
+  // detect a `Stage.<member>` PROPERTY ACCESS in real code, via the parser. a comment/string/
+  // regex/template-static mention is not a property-access node, so it never keeps the check red
+  // after the fix (it would never clear). the check detects ALL three members — a DEVELOPMENT
+  // reference must keep the check red so `plan` stays visibly unsettled.
+  const accesses = getStageAccesses(contents);
+  if (accesses.length > 0) return; // bad practice detected
+
+  throw new Error(
+    'does not match bad practice: no Stage.PRODUCTION|DEVELOPMENT|TEST property access found in real code (a comment/string/regex/template-static mention is ignored)',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // migrate the unambiguous members, mark each axis-ambiguous `Stage.DEVELOPMENT` with a review
+  // pointer, then drop the Stage import when no reference remains. `Stage.DEVELOPMENT` is left in
+  // place (never guessed), so `check` still detects it and `plan` stays red until a human decides
+  // the axis — now with a `// @declapract:review:` line naming where + what.
+  const spliced = withUnambiguousStageRefsReplaced({ contents });
+  const marked = withDevelopmentAxisReviewMarker({ contents: spliced });
+  const fixed = withUnusedStageImportRemoved({ contents: marked });
+
+  return { contents: fixed };
+};

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/.declapract.readme.md

@@ -0,0 +1,61 @@
+# environments
+
+a critical part of an application's environment is its `access` — which deployment's resources
+the runtime may reach, and with what weight.
+
+ehmpathy recognizes three standard tiers in which applications run throughout their development cycle
+- `prod` — a deployed production stack the business depends on, which serves real customers
+- `prep` — a deployed pre-production stack where applications interact for cross-service tests
+- `test` — an ephemeral, primarily local, developer-only tier for local code
+
+`access` is the one canonical axis (`test | prep | prod`). the runtime reads it via
+`getEnvironment.static().access` (sdk-environment), which derives it from the `ACCESS` env var, then
+the aws account, then `NODE_ENV`.
+
+# vocab
+
+definitions
+- `stack`
+  - > A stack is your application plus everything that it requires to run. This can include (but is not limited to) networks, servers, storage folders, Docker containers, build pipelines, etc.
+
+- `environment`
+  - > An environment is a runtime for an application, complete with all of its code, components, and configurations.
+
+
+ref
+- https://www.tinystacks.com/blog-post/what-are-stacks-stages-and-environments/
+
+# the access axis, and how a caller reaches a peer lambda
+
+one fact — which deployment a runtime reaches — is named by `access` (`test | prep | prod`).
+below prod the deployed resource names carry a legacy `dev` label, so an `access=prep` runtime must
+reach resources named `-dev-`. that mismatch (`access=prep` ⟺ deployed name `dev`) is a
+compiler-invisible fault: both are `string`, so a wrong reference is green at build and red only at
+runtime, against a deployed resource.
+
+`src/access/sdks/` holds the transitional bridge that lets a caller reach a peer lambda by the slug
+the peer actually publishes at, per callee — one procedure per file (`rule.require.single-responsibility`):
+
+- `sdkAwsLambdaEnvAccessAncient.ts` → `sdkAwsLambdaEnvAccessAncient()` — emits the legacy `dev` slug
+  below prod. for a peer still published under `-dev-` only. carries the shared `LambdaEnvSlug` type.
+- `sdkAwsLambdaEnvAccessContemp.ts` → `sdkAwsLambdaEnvAccessContemp()` — emits the access direct.
+  for a `-prep-` peer, or self.
+
+## the migration ledger
+
+the helper choice IS the ledger: `grep AccessAncient` across a repo lists every peer still on the
+ancient (`-dev-` only) slug. a per-peer migration is a one-line `Ancient → Contemp` flip. once the
+org's last `Ancient` import is gone, the ancient branch, the `-dev-` publish, and the divergent
+`dev` slug retire together — the helper is scaffold built to be torn down.
+
+`ancient`/`contemp` is `sdk-aws-lambda`'s own vocabulary (it names the payload-format axis there);
+the `EnvAccess` qualifier disambiguates this slug-axis sense from that homograph.
+
+## the helper is a shared primitive
+
+the helper is a pure, shared target-resolution primitive that a consumer wires when it migrates a
+peer, so a fresh consumer holds it with no call site yet. the caller-side wire-up and the helper's
+retirement both land at the north-star endpoint.
+
+the full transition design (dual-publish, the ledger, the deletion endpoint) is the north-star of
+the fix-lambdas wish — see `.behavior/v2026_08_31.fix-lambdas-3/1.vision.yield.md` in this repo.

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "@aws-sdk/client-account": "@declapract{check.minVersion('3.1042.0')}",
+    "@aws-sdk/client-iam": "@declapract{check.minVersion('3.1042.0')}",
+    "sdk-environment": "@declapract{check.minVersion('0.1.5')}"
+  }
+}

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessAncient.ts

@@ -0,0 +1,32 @@
+import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = the fleet slug a caller addresses a peer lambda by.
+ * .why  = it is an access (`test | prep | prod`) OR the legacy `dev` slug an
+ *         ancient peer still publishes under. a first-class `dev` member keeps the slug
+ *         compiler-tracked — never an `as`-cast that lies a `dev` value through a type
+ *         that forbids it (the exact silent fault this transition exists to kill).
+ */
+export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
+
+/**
+ * .what = address an **ancient** peer — one that publishes `-dev-` only.
+ * .why  = `askLambdaEndpoint` builds its target as `${service}-${access}-${function}`.
+ *         an ancient peer publishes under a legacy `dev` slug that disagrees with
+ *         **access** (`test | prep | prod`) below prod (`access=prep` ⟺ deployed name
+ *         `dev`). so a caller emits the legacy `dev` slug below prod, because that is the
+ *         only name the peer publishes. `prod` maps to `prod` on both.
+ * .note = the helper choice IS the migration ledger: `grep AccessAncient` lists every
+ *         peer still published under `-dev-` only. once zero remain, this ancient branch
+ *         — and the divergent `dev` slug — retire together, alongside its contemp
+ *         counterpart `sdkAwsLambdaEnvAccessContemp`. the return type is `LambdaEnvSlug`,
+ *         so the `dev` slug flows with a compiler-tracked type — no cast, no lie.
+ */
+export const sdkAwsLambdaEnvAccessAncient = (
+  input?: { access: EnvironmentAccessTier | null },
+): LambdaEnvSlug => {
+  const access = input?.access ?? envStatic.access;
+  return access === 'prod' ? 'prod' : 'dev';
+};

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts

@@ -0,0 +1,14 @@
+import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = address a **contemp** peer, or **self** — one that publishes `-prep-`.
+ * .why  = emit the access direct; no bridge is needed once the callee is
+ *         published under the access slug. the contemp counterpart of
+ *         `sdkAwsLambdaEnvAccessAncient`: as peers migrate, a caller flips
+ *         `Ancient → Contemp` per peer, and `grep AccessAncient` at zero is the exit.
+ */
+export const sdkAwsLambdaEnvAccessContemp = (
+  input?: { access: EnvironmentAccessTier | null },
+): EnvironmentAccessTier => input?.access ?? envStatic.access;

package/dist/.test/assets/environments/declarations/practices/environments/best-practice/src/utils/environment.ts

@@ -0,0 +1,9 @@
+import { getEnvironment } from 'sdk-environment';
+
+export { getEnvironment };
+
+export const envStatic = getEnvironment.static();
+
+// the access (`test | prep | prod`), re-exported flat for convenience. one axis, never a
+// divergent deploy slug.
+export const access = envStatic.access;

package/dist/.test/assets/environments/declarations/useCases.yml

@@ -0,0 +1,5 @@
+# minimal use case for the environments practice integration test
+use-cases:
+  lambda-service:
+    practices:
+      - environments

package/dist/.test/assets/expo/declarations/practices/cicd-app-react-native-expo/.declapract.integration.test.ts

@@ -171,16 +171,17 @@ describe('app-react-native-expo — graceful migration of an app-protools-shaped
       });
 
       then('the packageManager pin converges to the blessed exact version', () => {
-        // the fixture is AHEAD of the blessed pin (pnpm@10.32.1). the pnpm
-        // best-practice CONTAINS declares the ONE blessed version (pnpm@10.31.7),
-        // so a consumer ahead of it is pinned BACK on fix — that downgrade is the
-        // wisher-settled org-convergence REQUIREMENT (one blessed pnpm across CI,
-        // local, every repo), not a regression. this characterizes it.
+        // the fixture is OFF the blessed pin (pnpm@10.32.1). the pnpm
+        // best-practice CONTAINS declares the ONE blessed version (pnpm@10.34.5),
+        // so a consumer off it is converged onto the blessed pin on fix — in
+        // either direction. that convergence-to-one-version is the wisher-settled
+        // org-convergence REQUIREMENT (one blessed pnpm across CI, local, every
+        // repo), not a regression. this characterizes it.
         const pkgBefore = JSON.parse(state.before.pkg!);
         expect(pkgBefore.packageManager).toEqual('pnpm@10.32.1');
 
         const pkg = JSON.parse(state.after2.pkg!);
-        expect(pkg.packageManager).toEqual('pnpm@10.31.7');
+        expect(pkg.packageManager).toEqual('pnpm@10.34.5');
       });
 
       then('the inline jest dual-source block is dropped', () => {
@@ -389,6 +390,20 @@ describe('app-react-native-expo — migration-fixture drift guard', () => {
     return parsed['use-cases'][input.usecase].practices;
   };
 
+  // the practices in `of` absent from `reference` — the set-difference the drift asserts on.
+  const getPracticesAbsentFrom = (input: {
+    of: string[];
+    reference: string[];
+  }): string[] =>
+    input.of.filter((practice) => !input.reference.includes(practice));
+
+  // the practices in `of` also present in `reference` — the set-overlap the drift forbids.
+  const getPracticesPresentIn = (input: {
+    of: string[];
+    reference: string[];
+  }): string[] =>
+    input.of.filter((practice) => input.reference.includes(practice));
+
   const repoRoot = path.join(__dirname, '../../..');
 
   given('the real usecase and the fixture usecase', () => {
@@ -410,34 +425,34 @@ describe('app-react-native-expo — migration-fixture drift guard', () => {
 
     when('the fixture subset is measured against the real usecase', () => {
       then('the fixture invents no practice absent from the real usecase', () => {
-        const invented = fixturePractices.filter(
-          (practice) => !realPractices.includes(practice),
-        );
+        const invented = getPracticesAbsentFrom({
+          of: fixturePractices,
+          reference: realPractices,
+        });
         expect(invented).toEqual([]);
       });
 
       then('a fixture practice is never also on the config-only allowlist', () => {
-        const overlap = fixturePractices.filter((practice) =>
-          configOnlyAllowlist.includes(practice),
-        );
+        const overlap = getPracticesPresentIn({
+          of: fixturePractices,
+          reference: configOnlyAllowlist,
+        });
         expect(overlap).toEqual([]);
       });
 
       then('the allowlist names no practice absent from the real usecase', () => {
-        const dead = configOnlyAllowlist.filter(
-          (practice) => !realPractices.includes(practice),
-        );
+        const dead = getPracticesAbsentFrom({
+          of: configOnlyAllowlist,
+          reference: realPractices,
+        });
         expect(dead).toEqual([]);
       });
 
       then('every real usecase practice is classified — exercised or config-only', () => {
-        const classified = new Set([
-          ...fixturePractices,
-          ...configOnlyAllowlist,
-        ]);
-        const unclassified = realPractices.filter(
-          (practice) => !classified.has(practice),
-        );
+        const unclassified = getPracticesAbsentFrom({
+          of: realPractices,
+          reference: [...fixturePractices, ...configOnlyAllowlist],
+        });
         expect(unclassified).toEqual([]);
       });
     });
@@ -662,6 +677,91 @@ describe('useCases.yml — resolved-practice characterization', () => {
  * .note = a practice-set parity guard below pins this fixture's usecase === the real
  *         `src/useCases.yml` usecase, so the smoke can never silently test a stale set.
  */
+/**
+ * .what = a clamp on the expo `deploy.yml` prod job's `if:` test-gate precedence — the prod
+ *         job must bind the `needs.test` gate to EVERY trigger branch, so a `v*` tag push
+ *         cannot deploy to prod on a FAILED test.
+ * .why  = github-actions `&&` binds tighter than `||`, so an `if:` written
+ *         `(tag) || (access==prod) && always() && (test ok)` parses as `tag || (access &&
+ *         always && test)` — the test gate binds ONLY to the access branch, so a `v*` TAG
+ *         PUSH deploys to prod even when `test` FAILED. the correct shape wraps both trigger
+ *         branches in one OUTER group the gate applies to:
+ *         `((tag) || access==prod) && always() && (test ok)`. this is the silent-break class
+ *         the wish fights — an untested build reaches prod, every gate green. the clamp reads
+ *         the raw prod `if:` and reddens on the un-grouped (bug) shape. it mirrors the
+ *         cicd-service prod-gate clamp so both service and app deploy callers hold the guard.
+ * .note = a filesystem walk → integration suite per rule.forbid.unit.remote-boundaries; no
+ *         credential, no network — the boundary alone classifies it. the clamp lives at the
+ *         practice root, never under best-practice/, so it is a declaration and not a template.
+ */
+/**
+ * .what = whether the prod job's collapsed `if:` wraps BOTH trigger branches in ONE outer group
+ *         that the ` && always()` test-gate binds over — the correct precedence.
+ * .why  = a pure transformer leaf, named so the assertion below reads intent rather than a raw
+ *         precedence regex a reader must simulate. the buggy single-group shape opens one paren
+ *         `(startsWith`; the correct shape opens a second, OUTER paren `((startsWith` that the
+ *         ` && always()` gate closes over, so the gate binds to the tag-push branch too, not the
+ *         access branch alone.
+ */
+const isProdGateGroupedCorrectly = (input: { collapsedIf: string }): boolean =>
+  /\(\(startsWith\(github\.ref, 'refs\/tags\/'\).*\|\| github\.event\.inputs\.access == 'prod'\) &&\s*always\(\)/.test(
+    input.collapsedIf,
+  );
+
+describe('cicd-app-react-native-expo — prod test-gate precedence (silent-break clamp)', () => {
+  const readProdIf = (): string => {
+    const text = readFileSync(
+      `${__dirname}/best-practice/.github/workflows/deploy.yml`,
+      'utf-8',
+    );
+    // yaml.parse already returns `any`; annotate (not cast) to read the untyped workflow doc, as
+    // the peer cicd-service clamp does with its `parsed: any` annotation (no rule.forbid.as-cast cast)
+    const parsed: any = yaml.parse(text);
+    return (parsed.jobs?.prod?.if ?? '').replace(/\s+/g, ' ').trim();
+  };
+
+  given('[case1] the expo deploy.yml prod job', () => {
+    when('[t0] the prod job gates on the test result across every trigger branch', () => {
+      then('the two trigger branches sit in one outer group the test-gate binds to', () => {
+        const collapsed = readProdIf();
+        // guard the shape: an absent `if` leaves collapsed empty, a clean red not a crash
+        expect(collapsed.length).toBeGreaterThan(0);
+        // teeth: revert the outer paren and isProdGateGroupedCorrectly reddens.
+        expect(isProdGateGroupedCorrectly({ collapsedIf: collapsed })).toEqual(
+          true,
+        );
+      });
+
+      then('the buggy per-branch group (access alone in parens after `||`) is absent', () => {
+        // teeth: the precedence bug wraps the access branch in its OWN parens after the `||`
+        // (`|| (github.event.inputs.access == 'prod') &&`), which lets the tag branch stand alone.
+        // the correct shape leaves the access branch bare inside the outer group.
+        expect(readProdIf()).not.toContain(
+          "|| (github.event.inputs.access == 'prod') &&",
+        );
+      });
+
+      then('the test-result gate itself is present (guards the above from vacuity)', () => {
+        expect(readProdIf()).toContain(
+          "always() && (needs.test.result == 'success' || needs.test.result == 'skipped')",
+        );
+      });
+    });
+
+    when('[t1] the emitted prod-job gate is snapshotted for review', () => {
+      // the regex + toContain clamps above prove the SHAPE; this snapshots the emitted
+      // `if:` gate itself so a reviewer vibechecks the actual precedence group, and any
+      // drift (a reword, an operand reshuffle, a lost outer paren) shows as a diff. per
+      // rule.require.contract-snapshot-exhaustiveness, and mirrors the peer cicd-service clamp.
+      then('the prod job `if:` gate matches snapshot', () => {
+        expect(readProdIf()).toMatchSnapshot(
+          'deploy.yml prod job if: (test-gate precedence)',
+        );
+      });
+    });
+  });
+});
+
 describe('app-react-native-expo — full-usecase evaluation smoke', () => {
   const repoRoot = path.join(__dirname, '../../..');
   const sorted = (input: string[]): string[] => [...input].sort();