declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/persist-with-rds/provision-testdb-access.declapract.integration.test.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #563: the shipped provision:testdb chain sets ACCESS=test on every inner
+ *         provision:schema:* call, so a freshly-stamped repo can derive access and provision its
+ *         local testdb without a hand-edit.
+ * .why  = each schema call invokes sql-schema-control → getConfig() → getEnvironment.static(); with
+ *         no ACCESS in a local shell (no aws account alias / NODE_ENV that fits), every access parser
+ *         fails and it throws `could not derive access`. the local testdb always provisions the
+ *         `test` tier, so ACCESS=test is a constant here, not the cicd `${{ inputs.access }}`
+ *         interpolation the live-db path uses.
+ * .teeth = drop an `ACCESS=test` from any inner schema call in best-practice/package.json and the
+ *          "no bare schema call" assertion reddens (a bare `&& npm run provision:schema:` reappears).
+ * .note = the subject is the shipped TEMPLATE (best-practice/package.json, a CONTAINS check), read
+ *         from __dirname. this file sits at the practice ROOT, so declapract never emits it.
+ */
+describe('persist-with-rds provision:testdb access', () => {
+  given('the shipped best-practice package.json', () => {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+    );
+    const provisionTestdb: string = pkg.scripts['provision:testdb'];
+
+    when('the provision:testdb chain is read', () => {
+      then('each inner schema call carries ACCESS=test', () => {
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:plan',
+        );
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:apply',
+        );
+      });
+
+      then('no inner schema call runs without ACCESS (would throw could-not-derive)', () => {
+        // a bare `&& npm run provision:schema:` (not preceded by ACCESS=test) throws
+        // `could not derive access` in a local shell — the #563 defect
+        expect(provisionTestdb).not.toMatch(/&&\s*npm run provision:schema:/);
+      });
+
+      then('the emitted provision:testdb chain matches snapshot', () => {
+        // snapshot the shipped chain contract itself, so a reword that keeps the
+        // ACCESS=test tokens green (a re-ordered &&, a dropped command) reddens a vibecheck
+        expect(provisionTestdb).toMatchSnapshot('provision:testdb chain');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/ssm-cicd-param-names.declapract.integration.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the ssm-off-terraform wish declares the two cicd credentials as SLASH paths
+ *         with NO tier segment, while the crud credential keeps its dotted tier-scoped name.
+ * .why  = the prod plan role pins its ONE `kms:Decrypt` exception to a slash arn
+ *         (`parameter/*​/svc-*​/database/role/cicd/for-plan/*`) that needs literal `/` separators
+ *         and omits a tier (the aws ACCOUNT separates prep from prod, never the name). a dotted
+ *         name cannot match that arn, so the plan role gets ciphertext or a denial, forever, and
+ *         a repo does not find out until prod (#591). the shipped `ahbode/svc-home-services` proved
+ *         the slash form; this clamp ports it into the practice so no consumer inherits the dotted
+ *         cicd name again. crud is pinned by NO policy, so it keeps its dotted name and this clamp
+ *         leaves it alone.
+ * .teeth = revert either cicd entry to the dotted `${namespace}.database.role.cicd.for-plan.password`
+ *          form and the slash-present case reddens; the no-dotted-cicd case reddens too.
+ * .note = `.declapract.test.ts` = this repo's UNIT-test marker; at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/persist-with-rds/) the best-practice tree is one segment down.
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+describe('persist-with-rds ssm cicd param names are slash-path, tierless', () => {
+  const source = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the two cicd credentials', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('for-plan is a slash path, byte-identical to the iam pin', () => {
+        expect(source).toContain('/database/role/cicd/for-plan/password');
+      });
+
+      then('for-apply is a slash path', () => {
+        expect(source).toContain('/database/role/cicd/for-apply/password');
+      });
+
+      then('neither cicd name is dotted (a dotted name cannot match the arn pin)', () => {
+        expect(source).not.toContain('.database.role.cicd.for-plan');
+        expect(source).not.toContain('.database.role.cicd.for-apply');
+      });
+
+      then('the cicd slash path carries no tier segment (project joins /database directly)', () => {
+        // /{org}/{project}/database/... — a tier segment would split project from database
+        expect(source).toContain('projectName}/database/role/cicd/for-plan/password');
+        expect(source).not.toContain('${slug}/database/role/cicd');
+      });
+
+      // the emitted param-name lines are the caller-faced contract: snapshot them so a reword that
+      // keeps the slash tokens green (a re-templated prefix, a moved tier segment) reddens a vibecheck.
+      then('the emitted cicd + crud param-name lines match snapshot', () => {
+        const nameLines = source
+          .split('\n')
+          .filter((line) => line.includes('database/role/cicd') || line.includes('database.role.'))
+          .map((line) => line.trim());
+        expect(nameLines).toMatchSnapshot('ssm cicd + crud param names');
+      });
+    });
+  });
+
+  given('[case2] the crud credential', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('crud keeps its dotted tier-scoped name (no policy pins it)', () => {
+        expect(source).toContain('${namespace}.database.role.crud.password');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/testdb-preflight-failloud.declapract.integration.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the testdb preflight probe (#589) to fail LOUD, not hide
+ * .why  = the prior probe swallowed psql stderr (`> /dev/null 2>&1`), printed one
+ *         hardcoded diagnosis regardless of the true cause, and passed the secret
+ *         inline in the connection string (which leaks it to `ps`). so a bad
+ *         password, a port conflict, and an image build failure all read the same,
+ *         and the real cause never surfaced on timeout.
+ * .teeth = revert the fix (restore `> /dev/null 2>&1` + the inline password + the
+ *          single hardcoded line) and each `then` below goes red.
+ * .note  = a `.declapract.test.ts` at the practice ROOT is a UNIT-test marker — it is
+ *          not loaded as a declaration nor copied to a consumer. it anchors on
+ *          __dirname (not process.cwd()) so it reads the shipped template directly.
+ */
+
+const source = readFileSync(
+  join(
+    __dirname,
+    'best-practice/provision/docker/testdb/wait-for-postgres.sh',
+  ),
+  'utf8',
+);
+
+describe('testdb preflight fails loud (#589)', () => {
+  given('the shipped wait-for-postgres preflight probe', () => {
+    when('[t0] it runs the psql probe', () => {
+      then('it does not swallow the probe stderr to /dev/null', () => {
+        expect(source).not.toContain('/dev/null');
+      });
+
+      then('it captures the probe stderr for surfacing on timeout', () => {
+        expect(source).toContain('lasterr=$(psql');
+        expect(source).toContain('2>&1');
+      });
+    });
+
+    when('[t1] the probe fails past the timeout', () => {
+      then('it echoes the captured last error to stderr', () => {
+        expect(source).toContain('>&2 echo "$lasterr"');
+      });
+
+      then('it no longer prints only the one hardcoded diagnosis', () => {
+        expect(source).not.toContain('postgres too long');
+      });
+    });
+
+    when('[t2] it authenticates to postgres', () => {
+      then('it passes the secret via PGPASSWORD, not inline in the connstring', () => {
+        // the secret rides PGPASSWORD (never the connstring, which leaks to `ps`), and
+        // the env read uses the safe-default form per rule.require.safe-shell-vars
+        expect(source).toContain('export PGPASSWORD="${POSTGRES_PASSWORD:-}"');
+        expect(source).not.toContain('password=$POSTGRES_PASSWORD');
+      });
+    });
+
+    when('[t3] a consumer shell runs it under nounset', () => {
+      then('it opens with set -eu so an unset env fails loud, not silent', () => {
+        expect(source).toContain('set -eu');
+      });
+
+      then('it reads every optional env var with the ${VAR:-} default form', () => {
+        // no bare "$VAR" env read survives: under set -u a bare read is an unbound-variable
+        // crash; the :- default keeps a loud, correct connect attempt instead
+        expect(source).not.toContain('"$POSTGRES_PASSWORD"');
+        expect(source).not.toContain('dbname=$POSTGRES_DB ');
+        expect(source).toContain('${POSTGRES_DB:-}');
+      });
+    });
+
+    when('[t4] the shipped probe is vibechecked as a whole', () => {
+      then('the emitted wait-for-postgres.sh matches snapshot', () => {
+        // snapshot the whole shipped probe so a reword that keeps the pinned tokens green
+        // (a reshaped psql invocation, a rephrased echo, a moved PGPASSWORD export) reddens a
+        // vibecheck in review — the tokens above prove presence, this proves the exact text
+        // (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('wait-for-postgres.sh preflight probe');
+      });
+    });
+  });
+});

package/dist/practices/pnpm/.declapract.integration.test.ts

@@ -1,4 +1,6 @@
 import fs from 'fs/promises';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
@@ -7,6 +9,52 @@ import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
 // executeApply is slow (full practice evaluation)
 jest.setTimeout(180_000);
 
+/** extract the pinned version out of a `packageManager` field (`pnpm@10.34.5` → `10.34.5`). */
+const asPinnedVersionFromPackageManager = (packageManager: string): string =>
+  packageManager.split('@')[1] ?? '';
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((done) => setTimeout(done, ms));
+
+/**
+ * .what = query the npm registry for a package's published version, with bounded retry-with-backoff.
+ * .why  = a bare one-shot `npm view` makes a TRANSIENT registry blip (DNS hiccup, rate limit, brief
+ *         outage) redden the whole suite even when the pin is fine — the intermittent-failure class
+ *         rule.forbid.behavior-hazards targets. a phantom pin (never published) fails EVERY attempt
+ *         and still reddens after the budget, so the phantom-guard intent holds; a transient blip
+ *         recovers on a later attempt. fails loud with the last error once the budget is spent
+ *         (rule.forbid.failhide) — never a silent skip.
+ * .note = a committed/metadata source cannot substitute here: only the registry can confirm a pin
+ *         was actually PUBLISHED (a phantom pin parses fine locally). so the registry read stays,
+ *         hardened by retry rather than replaced.
+ */
+const getPublishedVersionFromRegistry = async (input: {
+  packageName: string;
+  version: string;
+  attemptsLeft: number;
+  backoffMs: number;
+}): Promise<string> => {
+  try {
+    return execFileSync(
+      'npm',
+      ['view', `${input.packageName}@${input.version}`, 'version'],
+      { timeout: 15_000 },
+    )
+      .toString('utf-8')
+      .trim();
+  } catch (error) {
+    // budget spent → fail loud with the last error (never swallow)
+    if (input.attemptsLeft <= 1) throw error;
+    // otherwise back off and retry — a transient blip recovers, a phantom pin fails again
+    await sleep(input.backoffMs);
+    return getPublishedVersionFromRegistry({
+      ...input,
+      attemptsLeft: input.attemptsLeft - 1,
+      backoffMs: input.backoffMs * 2,
+    });
+  }
+};
+
 /**
  * .what = pipeline test for the pnpm npm→pnpm migration bad-practices
  * .why  = the unit tests prove each fix in isolation; only the real executeApply pipeline
@@ -87,7 +135,7 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
 
       then('the packageManager pin survives (best-practice no-op)', () => {
         const pkg = JSON.parse(state.pkgAfter1);
-        expect(pkg.packageManager).toEqual('pnpm@10.31.7');
+        expect(pkg.packageManager).toEqual('pnpm@10.34.5');
       });
 
       then('before + after match snapshot', () => {
@@ -119,14 +167,14 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
     });
   });
 
-  given('[case2] a repo AHEAD of the blessed pnpm pin (10.32.1)', () => {
-    // the [case1] fixture seeds the pin already AT 10.31.7, so it proves only the no-op
-    // path. this case seeds the pin AHEAD of the blessed version to prove the DOWNGRADE
-    // rewrite (10.32.1 → 10.31.7) in pnpm's OWN suite — where an engineer looks first —
+  given('[case2] a repo OFF the blessed pnpm pin (10.32.1)', () => {
+    // the [case1] fixture seeds the pin already AT 10.34.5, so it proves only the no-op
+    // path. this case seeds the pin OFF the blessed version to prove the convergence
+    // rewrite (10.32.1 → 10.34.5) in pnpm's OWN suite — where an engineer looks first —
     // not only inside the expo migration fixture. the best-practice CONTAINS check rejects
-    // a package.json that does not carry the exact `pnpm@10.31.7`, so `declapract fix`
-    // merges the blessed pin over the ahead one. that convergence-to-one-version is the
-    // org-standardization intent, not a regression.
+    // a package.json that does not carry the exact `pnpm@10.34.5`, so `declapract fix`
+    // merges the blessed pin over the off one, in either direction. that
+    // convergence-to-one-version is the org-standardization intent, not a regression.
     const tempDir = genTempDir({
       slug: 'pnpm-ahead-of-pin',
       clone: './src/practices/pnpm/.test/assets/repo-npm-to-pnpm',
@@ -140,7 +188,7 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
     const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
 
     const state = useBeforeAll(async () => {
-      // seed the pin AHEAD of the blessed version, then apply the practice
+      // seed the pin OFF the blessed version, then apply the practice
       const seeded = { ...JSON.parse(await readPkg()), packageManager: 'pnpm@10.32.1' };
       await fs.writeFile(pkgPath(), `${JSON.stringify(seeded, null, 2)}\n`);
       const pkgBefore = await readPkg();
@@ -161,15 +209,117 @@ describe('pnpm npm→pnpm migration — pipeline', () => {
       return { pkgBefore, pkgAfter1, pkgAfter2 };
     }, 170_000);
 
-    when('[t0] the ahead-of-pin package.json is applied', () => {
-      then('the pin is rewritten DOWN to the blessed 10.31.7', () => {
+    when('[t0] the off-pin package.json is applied', () => {
+      then('the pin is rewritten to the blessed 10.34.5', () => {
         expect(JSON.parse(state.pkgBefore).packageManager).toEqual('pnpm@10.32.1');
-        expect(JSON.parse(state.pkgAfter1).packageManager).toEqual('pnpm@10.31.7');
+        expect(JSON.parse(state.pkgAfter1).packageManager).toEqual('pnpm@10.34.5');
       });
 
-      then('a second apply is a fixed point (the downgrade converges)', () => {
+      then('a second apply is a fixed point (the convergence holds)', () => {
         expect(state.pkgAfter2).toEqual(state.pkgAfter1);
       });
     });
   });
+
+  given('[case3] the blessed packageManager pin is a real published version', () => {
+    // a phantom pin (e.g. pnpm@10.31.7, which was never published) 404s corepack on EVERY
+    // pm command in a consumer the moment `declapract fix` applies it — a repo-wide outage,
+    // not a lint nit (#576). so the blessed pin MUST exist on the npm registry. this guard
+    // reads the pin the best-practice ships and puts the question to the registry itself, so
+    // a future bump to an unpublished version reddens HERE rather than in a bricked consumer.
+    // anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different
+    // cwd. from this file (src/practices/pnpm/) the best-practice package.json is one segment down.
+    const bestPracticePkgPath = path.join(
+      __dirname,
+      'best-practice/package.json',
+    );
+
+    when('[t0] the best-practice package.json pin is read', () => {
+      const readPinnedVersion = (): string => {
+        const pkg = JSON.parse(readFileSync(bestPracticePkgPath, 'utf-8'));
+        return asPinnedVersionFromPackageManager(String(pkg.packageManager));
+      };
+
+      then('the pinned pnpm version has a valid semver shape (hermetic, every run)', () => {
+        expect(readPinnedVersion()).toMatch(/^\d+\.\d+\.\d+$/);
+      });
+
+      then('the pinned pnpm version is published on the npm registry (every build)', async () => {
+        // the phantom-pin guard (#576) needs the LIVE registry — only it confirms a pin was
+        // PUBLISHED (a phantom pin parses fine locally, then 404s corepack in every consumer). the
+        // read runs on EVERY build, CI included, per rule.require.external-contract-integration-tests:
+        // an external contract owes a real call, never a silent skip ("either run the real call, or
+        // fail the gate"). the transient-blip hazard rule.forbid.behavior-hazards names is absorbed by
+        // getPublishedVersionFromRegistry's bounded retry-with-backoff (3 attempts) — a brief blip
+        // recovers, a phantom pin fails all 3 and reddens the gate. the read needs no credential (a
+        // public `npm view`), and this repo's CI already reaches the registry to install deps, so a
+        // sustained outage would fail the install too. the shape check above stays hermetic.
+        const pinnedVersion = readPinnedVersion();
+        const published = await getPublishedVersionFromRegistry({
+          packageName: 'pnpm',
+          version: pinnedVersion,
+          attemptsLeft: 3,
+          backoffMs: 500,
+        });
+        expect(published).toContain(pinnedVersion);
+      });
+    });
+  });
+
+  given('[case4] a repo carrying an inert v11 allowBuilds block under the v10 pin', () => {
+    // the fixture's pnpm-workspace.yaml holds ONLY an `allowBuilds:` block — pnpm v11 syntax
+    // under a v10 pin, so it does ZERO work yet reads like a live allowlist (#575). the
+    // inert-build-allowlist bad-practice must DELETE the file (its whole content is the block),
+    // and a re-apply must be a no-op (the file is already gone → no key to detect).
+    const tempDir = genTempDir({
+      slug: 'pnpm-inert-allowbuilds',
+      clone: './src/practices/pnpm/.test/assets/repo-npm-to-pnpm',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/pnpm/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const wsPath = () => path.join(tempDir, 'pnpm-workspace.yaml');
+    const exists = async () =>
+      fs
+        .access(wsPath())
+        .then(() => true)
+        .catch(() => false);
+
+    const state = useBeforeAll(async () => {
+      const before = await fs.readFile(wsPath(), 'utf-8');
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'pnpm-workspace.yaml',
+      });
+      const existsAfter1 = await exists();
+
+      // a re-apply on the now-absent file must be a clean no-op
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'pnpm',
+        file: 'pnpm-workspace.yaml',
+      });
+      const existsAfter2 = await exists();
+
+      return { before, existsAfter1, existsAfter2 };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied to pnpm-workspace.yaml', () => {
+      then('the inert allowBuilds-only file is deleted', () => {
+        expect(state.existsAfter1).toEqual(false);
+      });
+
+      then('before matches snapshot (the inert block that was removed)', () => {
+        expect(state.before).toMatchSnapshot('pnpm-workspace.yaml — before');
+      });
+
+      then('a second apply is a fixed point (absent stays absent)', () => {
+        expect(state.existsAfter2).toEqual(false);
+      });
+    });
+  });
 });

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/package.json

@@ -1,7 +1,7 @@
 {
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",

package/dist/practices/pnpm/.test/assets/repo-npm-to-pnpm/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  node-pty: true

package/dist/practices/pnpm/__snapshots__/.declapract.integration.test.ts.snap

@@ -4,7 +4,7 @@ exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migrat
 "{
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",
@@ -23,7 +23,7 @@ exports[`pnpm npm→pnpm migration — pipeline given: [case1] a repo mid-migrat
 "{
   "name": "app-example-native",
   "version": "1.0.0",
-  "packageManager": "pnpm@10.31.7",
+  "packageManager": "pnpm@10.34.5",
   "scripts": {
     "fix:format": "npm run fix:format:prettier",
     "prepush": "npm run test && npm run build",
@@ -66,3 +66,10 @@ if changed 'package-lock.json'; then
 fi
 "
 `;
+
+exports[`pnpm npm→pnpm migration — pipeline given: [case4] a repo carrying an inert v11 allowBuilds block under the v10 pin when: [t0] the pnpm practice is applied to pnpm-workspace.yaml then: before matches snapshot (the inert block that was removed): pnpm-workspace.yaml — before 1`] = `
+"allowBuilds:
+  esbuild: true
+  node-pty: true
+"
+`;

package/dist/practices/pnpm/bad-practices/inert-build-allowlist/pnpm-workspace.yaml.declapract.ts

@@ -0,0 +1,59 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects a `pnpm-workspace.yaml` that carries an `allowBuilds:` block and removes it.
+ *         when the block is the file's sole content, the whole file is deleted.
+ * .why  = `allowBuilds:` is pnpm v11 syntax; the pnpm practice pins v10 (`pnpm@10.34.5`), where
+ *         the build allowlist key is `pnpm.onlyBuiltDependencies` (an ARRAY, in package.json).
+ *         so an `allowBuilds:` block under the v10 pin does ZERO work — yet it READS like a live
+ *         allowlist, the exact trap #575 / ehmpathy/rhachet#475 burned an hour on.
+ * .note = the fix is DELETE, not a boolean-fill and not a fail-loud stub. (1) rhachet retired the
+ *         manual allowlist step ("by subtraction"); declapract emits no allowlist to converge to.
+ *         (2) a real allowlist is repo-specific (the v10 `pnpm.onlyBuiltDependencies` array the
+ *         repo adds itself). an inert block does no work, so its removal cannot regress a build.
+ * .note = idempotent — after fix the key is gone, check no longer detects it, re-run is a no-op.
+ */
+const ALLOW_BUILDS_KEY = /^allowBuilds:/;
+
+/** a yaml child line: whitespace-indented, then non-whitespace (the block's nested entries). */
+const isIndentedChild = (line: string): boolean => /^\s+\S/.test(line);
+
+/**
+ * strip the `allowBuilds:` key line + its contiguous indented child lines. a pure fold over the
+ * lines with an immutable `{ inBlock, kept }` accumulator (no `let`, no in-place push): the key
+ * line opens the block (and is dropped), each indented child is dropped while open, and the first
+ * non-indented (or blank) line closes the block and is kept. handles more than one block, since a
+ * later key line simply re-opens.
+ */
+const stripAllowBuildsBlock = (contents: string): string =>
+  contents
+    .split('\n')
+    .reduce<{ inBlock: boolean; kept: string[] }>(
+      (acc, line) => {
+        // the key line opens the block and is itself dropped
+        if (ALLOW_BUILDS_KEY.test(line))
+          return { inBlock: true, kept: acc.kept };
+        // an indented child of an open block is dropped
+        if (acc.inBlock && isIndentedChild(line)) return acc;
+        // any non-indented (or blank) line closes the block and is kept
+        return { inBlock: false, kept: [...acc.kept, line] };
+      },
+      { inBlock: false, kept: [] },
+    )
+    .kept.join('\n');
+
+const hasAllowBuilds = (contents: string): boolean =>
+  contents.split('\n').some((line) => ALLOW_BUILDS_KEY.test(line));
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents === null) throw new Error('does not match bad practice');
+  if (!hasAllowBuilds(contents)) throw new Error('does not match bad practice');
+  return;
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (contents === null) return { contents };
+  const stripped = stripAllowBuildsBlock(contents);
+  if (stripped.trim() === '') return { contents: null };
+  return { contents: stripped };
+};

package/dist/practices/pnpm/best-practice/.declapract.readme.md

@@ -1,7 +1,7 @@
 # pnpm best-practice — what this practice owns, and what it does NOT
 
 this practice owns the pnpm **adoption** signal: the `packageManager` exact pin
-(`pnpm@10.31.7`, an intentional org-convergence requirement — see the `.declapract.ts` note).
+(`pnpm@10.34.5`, an intentional org-convergence requirement — see the `.declapract.ts` note).
 
 ## where the hoisted-linker `.npmrc` lives — NOT here
 

package/dist/practices/pnpm/best-practice/package.json

@@ -1,3 +1,3 @@
 {
-  "packageManager": "pnpm@10.31.7"
+  "packageManager": "pnpm@10.34.5"
 }

package/dist/practices/pnpm/best-practice/package.json.declapract.ts

@@ -1,13 +1,15 @@
 import { FileCheckType } from 'declapract';
 
 /**
- * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.31.7`), not a minVersion.
+ * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.34.5`), not a minVersion.
  * .why  = this is an intentional org-standardization REQUIREMENT, not an oversight. every pnpm
  *         consumer runs ONE blessed pnpm version, so `corepack` / `pnpm/action-setup@v4` load the
  *         identical toolchain across CI, local, and every repo — reproducible installs, no per-repo
  *         drift. an exact pin is also the ONLY correct shape here: the `packageManager` field is a
  *         corepack spec that requires the `pnpm@<version>` prefix, which declapract's bare-semver
- *         `check.minVersion(..)` cannot emit.
+ *         `check.minVersion(..)` cannot emit. the pin's major stays v10 by hard rule — see
+ *         `.agent/repo=.this/role=any/briefs/rule.require.pnpm-major-v10.md` (v11 inverts the
+ *         build-allowlist model the peer practices encode).
  * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
  *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
  *         the org bumps the blessed version, this pin bumps and every consumer follows.

package/dist/practices/provision-github/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "devDependencies": {
-    "declastruct": "@declapract{check.minVersion('1.9.1')}",
-    "declastruct-github": "@declapract{check.minVersion('1.7.2')}",
+    "declastruct": "@declapract{check.minVersion('1.9.2')}",
+    "declastruct-github": "@declapract{check.minVersion('1.8.0')}",
     "sdk-logs": "@declapract{check.minVersion('0.9.2')}"
   }
 }

package/dist/practices/provision-github/best-practice/provision/github.repo/resources.ts

@@ -140,6 +140,16 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     permission: 'push', // write access needed to deploy
   });
 
+  // declare the sole preparation environment — one env for every prep/test deploy
+  const envPreparation = DeclaredGithubEnvironment.as({
+    repo,
+    name: 'preparation',
+    reviewers: null, // no approval — prep is the pre-production tier; feature branches deploy freely
+    waitTimer: null, // no delay
+    deploymentBranchPolicy: null, // any branch
+    preventSelfReview: false,
+  });
+
   // declare environment for production deployments from main (auto-approved)
   const envProductionOnMain = DeclaredGithubEnvironment.as({
     repo,
@@ -166,6 +176,9 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
   //        reviewers. so this env carries NO protection rule — the human gate lives
   //        in aws via an `actor_id` allowlist on this env's sts trust statement
   //        (declared org-wide in aws.auth). do NOT add `reviewers` here (it will 422 on apply).
+  //        this is a SEPARATE env from production-on-else-plan on purpose: its name is the oidc
+  //        `sub` anchor for the actor_id-gated WRITER role, so a readonly plan job (anchored to
+  //        -plan) cannot assume the writer role. do NOT collapse the two.
   const envProductionOnElseApply = DeclaredGithubEnvironment.as({
     repo,
     name: 'production-on-else-apply',
@@ -176,6 +189,8 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
   });
 
   // declare environment for production plan from any branch (readonly, no approval)
+  // .why = a SEPARATE env from production-on-else-apply on purpose: its name is the oidc `sub`
+  //        anchor for the READONLY plan role, so a plan job cannot assume the writer role.
   const envProductionOnElsePlan = DeclaredGithubEnvironment.as({
     repo,
     name: 'production-on-else-plan',
@@ -221,6 +236,7 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     repoConfig,
     branchMainProtection,
     teamReleasersRepoAccess,
+    envPreparation,
     envProductionOnMain,
     envProductionOnElseApply,
     envProductionOnElsePlan,