declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/pnpm/bad-practices/package-lock-json/.declapract.readme.md

@@ -0,0 +1,30 @@
+# bad-practice: package-lock-json
+
+## .what
+
+a `package-lock.json` (the npm lockfile) in a repo that has migrated to pnpm.
+
+## .why it is bad
+
+pnpm reads `pnpm-lock.yaml`, not `package-lock.json`. a stale npm lockfile left beside the pnpm one
+is a dual source of truth for the dependency graph, and CI lockfile checks that grep the wrong file
+pass or fail for the wrong reason.
+
+## .the fix — forget-not-destroy
+
+the fix removes `package-lock.json`, but ONLY once a `pnpm-lock.yaml` sits beside it. the delete is
+gated on the pnpm lockfile's presence (read from the project root via
+`context.getProjectRootDirectory()`), so a fix that runs on a repo that has not yet run
+`pnpm install` is a no-op rather than a destructive strip that leaves the repo lockfile-less. this
+is the wish's stated safety bar: *"package-lock.json is removed ONLY after pnpm-lock.yaml exists, so
+a fix interrupted midway never leaves the repo lockfile-less."*
+
+a bare `FileCheckType.EXISTS` would delegate to declapract's default fix, which deletes the file
+UNCONDITIONALLY — so this practice declares its own gated `check`/`fix` instead.
+
+## .see also
+
+- `package-lock.json.declapract.integration.test.ts` — the forget-not-destroy clamp (delete-when-safe
+  + survive-when-unsafe)
+- `rule.require.clamp-edge-cases` — the regression clamp a destructive fix owes
+- `howto.craft-practice-migrations` — the forget-not-destroy migration shape

package/dist/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.integration.test.ts

@@ -0,0 +1,105 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import type { FileCheckContext } from 'declapract';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { check, fix } from './package-lock.json.declapract';
+
+/**
+ * .what = the forget-not-destroy clamp for the package-lock.json bad-practice.
+ * .why  = the fix DELETES the npm lockfile, so it is destructive — `rule.require.clamp-edge-cases`
+ *         demands a regression clamp that BITES. the gate reads the real filesystem for a
+ *         `pnpm-lock.yaml` beside the lockfile, so this is an integration test (a filesystem
+ *         boundary, per `rule.forbid.unit.remote-boundaries`), built on the `mkdtempSync`
+ *         throwaway-root pattern from `howto.craft-practice-migrations`. it proves BOTH paths:
+ *         delete-when-safe (pnpm-lock.yaml present) and skip-when-unsafe (absent) — the second
+ *         guards the forget-not-destroy contract: a bare EXISTS default-delete would fail it.
+ */
+/**
+ * .what = builds the minimal FileCheckContext the check and fix functions actually use
+ * .why  = declapract's FileCheckContext carries many fields the package-lock check/fix never
+ *         touch — they read only `getProjectRootDirectory()` (to look for a `pnpm-lock.yaml`
+ *         beside the lockfile). the single documented cast here is the sanctioned test-context
+ *         idiom (howto.craft-practice-migrations); it is confined to this helper so no call
+ *         site casts. removal path: drop the cast the day declapract exports a partial-context
+ *         builder.
+ */
+const genContextForRoot = (root: string): FileCheckContext =>
+  ({ getProjectRootDirectory: () => root }) as unknown as FileCheckContext;
+
+describe('pnpm package-lock-json — forget-not-destroy gate', () => {
+  // .note = deliberate mutation — `roots` accumulates every temp dir genRoot mints so the
+  //         afterAll below can remove them all; a scoped, single-threaded test-cleanup zone
+  //         (rule.require.immutable-vars sanctions in-place mutation with this note).
+  const roots: string[] = [];
+  const genRoot = (slug: string, files: Record<string, string>): string => {
+    const root = mkdtempSync(path.join(tmpdir(), `pnpm-lock-${slug}-`));
+    for (const [name, body] of Object.entries(files))
+      writeFileSync(path.join(root, name), body);
+    roots.push(root);
+    return root;
+  };
+
+  afterAll(() => {
+    for (const root of roots) rmSync(root, { recursive: true, force: true });
+  });
+
+  given('[case1] a package-lock.json WITH a pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('safe', {
+        'package-lock.json': '{}',
+        'pnpm-lock.yaml': 'lockfileVersion: 9\n',
+      });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check detects it — safe to remove', () => {
+        expect(() => check('{}', state.context)).not.toThrow();
+      });
+
+      then('fix removes it — contents become null', () => {
+        expect(state.fixed).toBeNull();
+      });
+    });
+  });
+
+  given('[case2] a package-lock.json with NO pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('unsafe', { 'package-lock.json': '{}' });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — forget-not-destroy, no pnpm-lock.yaml yet', () => {
+        expect(() => check('{}', state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+
+      then('fix is a no-op — the npm lockfile is preserved', () => {
+        // a bare EXISTS default-delete would make this null, which this test would catch
+        expect(state.fixed).toEqual('{}');
+      });
+    });
+  });
+
+  given('[case3] no package-lock.json at all', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('absent', { 'pnpm-lock.yaml': 'lockfileVersion: 9\n' });
+      return { context: genContextForRoot(root) };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — no npm lockfile to remove', () => {
+        expect(() => check(null, state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+    });
+  });
+});

package/dist/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.ts

@@ -1,3 +1,41 @@
-import { FileCheckType } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
-export const check = FileCheckType.EXISTS;
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * .what = detects a `package-lock.json` (the npm lockfile) that is SAFE to remove — i.e. only
+ *         once a `pnpm-lock.yaml` sits beside it.
+ * .why  = the npm→pnpm migration must be FORGET-NOT-DESTROY: `package-lock.json` is removed ONLY
+ *         after `pnpm-lock.yaml` exists, so a fix interrupted midway never leaves the repo
+ *         lockfile-less (the wish's stated safety bar). a bare `FileCheckType.EXISTS` would let
+ *         declapract's default fix delete the npm lockfile UNCONDITIONALLY — even on a repo that
+ *         has not yet run `pnpm install` — which is exactly the destructive strip this gate
+ *         forecloses. so the delete is gated on the pnpm lockfile's presence, read from the
+ *         project root via `context.getProjectRootDirectory()`.
+ */
+const hasPnpmLock = (context: {
+  getProjectRootDirectory: () => string;
+}): boolean =>
+  existsSync(path.join(context.getProjectRootDirectory(), 'pnpm-lock.yaml'));
+
+export const check: FileCheckFunction = (contents, context) => {
+  // no package-lock.json → no npm lockfile to remove, skip
+  if (contents === null) throw new Error('does not match bad practice');
+
+  // forget-not-destroy: without a pnpm-lock.yaml beside it, removal would leave the repo
+  // lockfile-less — so this is NOT yet a safe-to-remove npm lockfile, skip
+  if (!hasPnpmLock(context)) throw new Error('does not match bad practice');
+
+  // package-lock.json present AND pnpm-lock.yaml present → safe to remove, detected
+  return;
+};
+
+export const fix: FileFixFunction = (contents, context) => {
+  // gate the delete on the pnpm lockfile's presence (forget-not-destroy) — a fix that ran
+  // where the check would not detect leaves the file untouched, never lockfile-less
+  if (!hasPnpmLock(context)) return { contents };
+
+  // pnpm-lock.yaml exists → remove the redundant npm lockfile
+  return { contents: null };
+};

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

@@ -0,0 +1,22 @@
+# 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.34.5`, an intentional org-convergence requirement — see the `.declapract.ts` note).
+
+## where the hoisted-linker `.npmrc` lives — NOT here
+
+the pnpm-only `.npmrc` directives an expo repo needs (`node-linker=hoisted`,
+`public-hoist-pattern[]=*expo*`, …) are declared by the **`node`** practice, not this one. the
+`node` practice owns the whole `.npmrc` (it is the package-manager-config file), and its declaration
+is usecase-aware: it findserts the hoist block only when the `cicd-app-react-native-expo` usecase is
+present.
+
+so an auditor of all that pnpm needs should also read:
+
+- `src/practices/node/best-practice/.npmrc.declapract.ts` — the usecase-aware `.npmrc` declaration
+- `src/utils/defineExpectedNpmrcContents.ts` — the shared base + expo-hoist line source
+- `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md` — why the flat linker is
+  required for metro/expo, and the transitive-skew gotcha it exposes
+
+the split is deliberate: the `.npmrc` is one file with one owner (`node`), so a repo gets a single
+coherent `.npmrc` rather than two practices that fight over it.

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

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

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

@@ -1,3 +1,17 @@
 import { FileCheckType } from 'declapract';
 
+/**
+ * .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. 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.
+ */
 export const check = FileCheckType.CONTAINS;

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,

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

@@ -0,0 +1,98 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the rhachet/prod-deps fix (D26 / #571), run through the REAL declapract
+ *   apply pipeline against a genTempDir clone of a consumer repo whose package.json lists `rhachet`
+ *   AND a `rhachet-brains-*` package in `dependencies` (prod).
+ * .why  = the old family regex was `/^rhachet(-roles-.*)?$/`, so a `rhachet-brains-*` prod dep slipped
+ *   the net and stayed a prod dep — and if it were also a devDep at a different version, the manifest
+ *   carried a duplicate whose two versions conflict. the fix is a widened `/^rhachet(-[a-z]+-.*)?$/`
+ *   plus a `withRhachetDepsMovedToDevDeps` partition transformer that relocates every rhachet family
+ *   package into devDependencies. a unit test of the transformer is necessary but not sufficient
+ *   (`rule.require.declapract-integration-tests`): only the pipeline proves the declaration's target
+ *   glob matches package.json and the relocation lands on a real consumer file.
+ * .note = the package.json holds `rhachet` (single-segment) AND `rhachet-brains-anthropic` (the
+ *   `-brains-` family the old regex missed), plus a non-rhachet prod dep (`uuid`) that must be
+ *   retained. the after-state proves the widened match AND the retention of every other prod dep.
+ */
+describe('rhachet/prod-deps relocation', () => {
+  given('[case1] a repo with rhachet + a rhachet-brains-* package in prod deps', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-prod-deps',
+      clone: './src/practices/rhachet/bad-practices/prod-deps/.test/assets/demo-repo-with-rhachet-prod-deps',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const pkgPath = 'package.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: pkgPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the package.json input matches snapshot', async () => {
+        expect(await read(pkgPath)).toMatchSnapshot('package.json — before');
+      });
+    });
+
+    when('[t1] the prod-deps fix is applied', () => {
+      useThen('relocate every rhachet family package into devDeps', async () =>
+        applyFix(),
+      );
+
+      then(
+        'both rhachet packages leave dependencies and land in devDependencies, the non-rhachet prod dep is retained, and it matches snapshot',
+        async () => {
+          const pkg = JSON.parse(await read(pkgPath));
+          // both rhachet family packages are gone from prod deps
+          expect(pkg.dependencies?.['rhachet']).toBeUndefined();
+          expect(pkg.dependencies?.['rhachet-brains-anthropic']).toBeUndefined();
+          // and now sit in dev deps (the -brains- match is the D26 proof)
+          expect(pkg.devDependencies['rhachet']).toEqual('1.47.5');
+          expect(pkg.devDependencies['rhachet-brains-anthropic']).toEqual(
+            '0.4.3',
+          );
+          // the non-rhachet prod dep is retained in dependencies
+          expect(pkg.dependencies.uuid).toEqual('9.0.0');
+          // the prior devDep survives untouched
+          expect(pkg.devDependencies.jest).toEqual('29.3.1');
+          // full content, for the reviewer's eye
+          expect(await read(pkgPath)).toMatchSnapshot('package.json — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // .note = the D26 invariant under re-apply is that the relocation is a FIXED POINT: once
+      //   moved, a second pass neither re-introduces a rhachet package into prod deps nor drops a
+      //   retained dep. we do NOT assert full-file byte equality, because the rhachet best-practice
+      //   package.json declaration (a separate declarer, out of scope for D26) writes a raw
+      //   `@declapract{check.minVersion(...)}` marker on the first pass and resolves it on the
+      //   second — a marker-resolution quirk of that declaration, not of the relocation under test.
+      const pkg = useThen('a second apply over its own output', async () => {
+        await applyFix(); // second apply, over the post-first-fix output
+        return JSON.parse(await read(pkgPath));
+      });
+
+      then('the rhachet packages stay out of prod deps', () => {
+        expect(pkg.dependencies?.['rhachet']).toBeUndefined();
+        expect(pkg.dependencies?.['rhachet-brains-anthropic']).toBeUndefined();
+      });
+
+      then('the relocated + retained deps survive the re-apply', () => {
+        expect(pkg.devDependencies['rhachet']).toEqual('1.47.5');
+        expect(pkg.devDependencies['rhachet-brains-anthropic']).toEqual('0.4.3');
+        expect(pkg.dependencies.uuid).toEqual('9.0.0');
+        expect(pkg.devDependencies.jest).toEqual('29.3.1');
+      });
+    });
+  });
+});

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/.agent/repo=.this/role=any/boot.yml

@@ -0,0 +1,7 @@
+# a consumer's OWN boot curation — it predates the declapract fix and carries entries
+# the fix must preserve: a say pick of its own, and a ref pick of its own deep variant.
+briefs:
+  say:
+    - briefs/my-own-brief.md
+  ref:
+    - briefs/my-own-deep-variant.md

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: './'
+useCase: typescript-project-core

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

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

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`rhachet/prod-deps relocation given: [case1] a repo with rhachet + a rhachet-brains-* package in prod deps when: [t0] the input (before any fix) then: the package.json input matches snapshot: package.json — before 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "rhachet": "1.47.5",
+    "rhachet-brains-anthropic": "0.4.3",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "jest": "29.3.1"
+  }
+}
+"
+`;
+
+exports[`rhachet/prod-deps relocation given: [case1] a repo with rhachet + a rhachet-brains-* package in prod deps when: [t1] the prod-deps fix is applied then: both rhachet packages leave dependencies and land in devDependencies, the non-rhachet prod dep is retained, and it matches snapshot: package.json — after 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "jest": "29.3.1",
+    "rhachet": "1.47.5",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.6')}",
+    "rhachet-brains-xai": "@declapract{check.minVersion('0.3.3')}",
+    "rhachet-roles-bhrain": "@declapract{check.minVersion('0.34.1')}",
+    "rhachet-roles-bhrowser": "@declapract{check.minVersion('0.1.0')}",
+    "rhachet-roles-bhuild": "@declapract{check.minVersion('0.21.36')}",
+    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.12')}",
+    "rhachet-roles-ghlitch": "@declapract{check.minVersion('0.3.0')}",
+    "rhachet-roles-rhachet": "@declapract{check.minVersion('0.1.7')}"
+  },
+  "scripts": {
+    "prepare:rhachet": "rhachet init --keys --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect dispatcher learner achiever telepath operator observer deployer playwright enroller",
+    "upgrade:rhachet": "rhachet upgrade"
+  }
+}
+"
+`;

package/dist/practices/rhachet/__snapshots__/boot-refs-glossary.declapract.integration.test.ts.snap

@@ -0,0 +1,6 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`rhachet boot.yml defaults to say, refs only deep glossary variants given: [case1] the shipped boot.yml template when: [t0] the template is read then: the emitted glossary ref lines match snapshot: boot.yml glossary refs 1`] = `
+"- briefs/domain.terms/term=*._.choice.reason.md
+- briefs/domain.terms/term=*._.choice.example=*.md"
+`;

package/dist/practices/rhachet/__snapshots__/boot-yml-findsert.declapract.integration.test.ts.snap

@@ -0,0 +1,27 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`rhachet — boot.yml findsert (req 1: consumer entries survive) given: [case1] a consumer whose boot.yml carries its own entries when: [t0] the input (before any fix) then: the consumer boot.yml carries its own picks, no budget, + matches snapshot: boot.yml — before 1`] = `
+"# a consumer's OWN boot curation — it predates the declapract fix and carries entries
+# the fix must preserve: a say pick of its own, and a ref pick of its own deep variant.
+briefs:
+  say:
+    - briefs/my-own-brief.md
+  ref:
+    - briefs/my-own-deep-variant.md
+"
+`;
+
+exports[`rhachet — boot.yml findsert (req 1: consumer entries survive) given: [case1] a consumer whose boot.yml carries its own entries when: [t1] the findsert fix is applied then: both declared globs land AND the consumer's own say + ref picks survive, and it matches snapshot: boot.yml — after 1`] = `
+"# a consumer's OWN boot curation — it predates the declapract fix and carries entries
+# the fix must preserve: a say pick of its own, and a ref pick of its own deep variant.
+briefs:
+  say:
+    - briefs/my-own-brief.md
+  ref:
+    - briefs/my-own-deep-variant.md
+    - briefs/domain.terms/term=*._.choice.reason.md
+    - briefs/domain.terms/term=*._.choice.example=*.md
+budget:
+  tokens: 5000
+"
+`;

package/dist/practices/rhachet/bad-practices/prod-deps/.declapract.readme.md

@@ -2,7 +2,7 @@
 
 ## what
 
-detects `rhachet` and `rhachet-roles-*` packages listed as production dependencies and moves them to devDependencies.
+detects `rhachet` and every `rhachet-<family>-*` package (e.g. `rhachet-roles-*`, `rhachet-brains-*`) listed as production dependencies and moves them to devDependencies.
 
 ## why
 
@@ -17,7 +17,11 @@ rhachet packages are build-time / development tooling only. they should never be
 ## packages covered
 
 - `rhachet`
-- `rhachet-roles-*` (e.g., `rhachet-roles-ehmpathy`, `rhachet-roles-bhrain`, `rhachet-roles-bhuild`)
+- `rhachet-<family>-*` — every rhachet family, e.g.
+  - `rhachet-roles-*` (`rhachet-roles-ehmpathy`, `rhachet-roles-bhrain`, `rhachet-roles-bhuild`)
+  - `rhachet-brains-*`
+
+a single-segment `rhachet-*` (e.g. `rhachet-other`, no family segment) is left alone.
 
 ## fix
 

package/dist/practices/rhachet/bad-practices/prod-deps/.test/assets/demo-repo-with-rhachet-prod-deps/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/practices/rhachet/bad-practices/prod-deps/.test/assets/demo-repo-with-rhachet-prod-deps/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: './'
+useCase: typescript-project-core

package/dist/practices/rhachet/bad-practices/prod-deps/.test/assets/demo-repo-with-rhachet-prod-deps/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "rhachet": "1.47.5",
+    "rhachet-brains-anthropic": "0.4.3",
+    "uuid": "9.0.0"
+  },
+  "devDependencies": {
+    "jest": "29.3.1"
+  }
+}

package/dist/practices/rhachet/bad-practices/prod-deps/package.json.declapract.ts

@@ -1,16 +1,26 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+
 /**
- * .what = detects rhachet and rhachet-roles-* packages in production dependencies
+ * .what = detects rhachet and any rhachet-<family>-* package in production dependencies
  * .why = these packages should be devDependencies or peerDependencies, never direct prod deps
  */
 
-const rhachetPackagePattern = /^rhachet(-roles-.*)?$/;
+// the family segment is a char class `[a-z]+`, so it catches every rhachet family — not just
+// `-roles-` but `-brains-` too — while it still excludes a single-segment `rhachet-*` (which
+// lacks the second dash). a `-brains-` package missed here stays a prod dep, and if it is also
+// a devDep with a different version the manifest carries a duplicate whose two versions conflict.
+const rhachetPackagePattern = /^rhachet(-[a-z]+-.*)?$/;
+const PRACTICE = 'rhachet/prod-deps';
 
 export const check: FileCheckFunction = (contents) => {
-  if (!contents) throw new Error('does not match bad practice');
+  if (!contents)
+    throw new Error(
+      `does not match bad practice: [${PRACTICE}] package.json has no contents to scan for a rhachet(-<family>-*) prod dep`,
+    );
 
-  const packageJSON = JSON.parse(contents);
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
   const prodDeps = Object.keys(packageJSON.dependencies ?? {});
 
   // check if any rhachet package is in prod dependencies
@@ -19,28 +29,59 @@ export const check: FileCheckFunction = (contents) => {
   );
 
   if (rhachetInProdDeps) return; // matches bad practice
-  throw new Error('does not match bad practice');
+  // no violation — no rhachet(-<family>-*) package sits in dependencies
+  throw new Error(
+    'does not match bad practice: no rhachet(-<family>-*) package in dependencies',
+  );
+};
+
+/**
+ * .what = relocate every rhachet(-<family>-*) package from prod deps into dev deps by a pure
+ *         partition, then return the two updated maps (inputs untouched, no in-place mutation).
+ * .why  = names the relocation as one intent so `fix` reads what-not-how; the body partitions prod
+ *         deps into relocated (rhachet) + retained (the rest) rather than a mutate-in-place loop a
+ *         reader must simulate (`rule.forbid.inline-decode-friction`, immutability clause).
+ */
+const withRhachetDepsMovedToDevDeps = (input: {
+  prodDeps: Record<string, string>;
+  devDeps: Record<string, string>;
+}): { prodDeps: Record<string, string>; devDeps: Record<string, string> } => {
+  const prodEntries = Object.entries(input.prodDeps);
+  // partition: rhachet packages relocate into dev deps; every other prod dep is retained as-is
+  const relocated = prodEntries.filter(([dep]) =>
+    rhachetPackagePattern.test(dep),
+  );
+  const retained = prodEntries.filter(
+    ([dep]) => !rhachetPackagePattern.test(dep),
+  );
+  return {
+    prodDeps: Object.fromEntries(retained),
+    // a relocated rhachet dep wins over any prior devDeps entry of the same name (the prod version)
+    devDeps: { ...input.devDeps, ...Object.fromEntries(relocated) },
+  };
 };
 
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return { contents };
 
-  const packageJSON = JSON.parse(contents);
-  const prodDeps = { ...packageJSON.dependencies };
-  const devDeps = { ...packageJSON.devDependencies };
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
 
-  // find all rhachet packages in prod deps and move them to dev deps
-  for (const dep of Object.keys(prodDeps)) {
-    if (rhachetPackagePattern.test(dep)) {
-      devDeps[dep] = prodDeps[dep];
-      delete prodDeps[dep];
-    }
-  }
+  // relocate every rhachet package from prod deps into dev deps
+  const { prodDeps, devDeps } = withRhachetDepsMovedToDevDeps({
+    prodDeps: { ...packageJSON.dependencies },
+    devDeps: { ...packageJSON.devDependencies },
+  });
 
+  // preserve each section's PRESENCE byte-for-byte: a section the consumer declared
+  // (even as an explicit empty `{}`) stays; a section it never had is added only when
+  // the move lands a package into it. this mirrors the leveled-term twin, so an
+  // already-clean manifest is a true no-op rather than a shape mutation.
   const fixedPackageJSON = {
     ...packageJSON,
-    dependencies: Object.keys(prodDeps).length > 0 ? prodDeps : undefined,
-    devDependencies: Object.keys(devDeps).length > 0 ? devDeps : undefined,
+    ...('dependencies' in packageJSON ? { dependencies: prodDeps } : {}),
+    ...('devDependencies' in packageJSON || Object.keys(devDeps).length > 0
+      ? { devDependencies: devDeps }
+      : {}),
   };
 
   return { contents: JSON.stringify(fixedPackageJSON, null, 2) };