declapract-typescript-ehmpathy 0.49.7 → 0.49.9

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts

@@ -0,0 +1,82 @@
+import { DeclaredAwsSsmParameterSecure } from 'declastruct-aws';
+import { getEnvironment } from 'sdk-environment';
+
+/**
+ * .what = the secret ssm parameters this service manages via declastruct.
+ * .why = these params were migrated off terraform (provision/aws/product/parameter-store.tf,
+ *        now a forget). declastruct-aws owns them. every param is a real secret, so each is a
+ *        DeclaredAwsSsmParameterSecure (write-only): the plan role reads metadata only
+ *        (DescribeParameters + ListTagsForResource — no GetParameter, no kms:Decrypt), and the
+ *        value is never read back.
+ * .note = adoption supplies NO `value`: the live values were seeded once by terraform and live
+ *         only in aws. a value-less secret is write-only KEEP, so plan reports KEEP for extant
+ *         params and never rewrites them. a CREATE at plan means the name does not match a live
+ *         param — stop and fix. (a value-less secret that is ABSENT throws on apply, per
+ *         declastruct-aws setSsmParameterSecure. only prep + prod apply this wish — there is no
+ *         aws-test-declastruct job — so the params are declared for every tier without a
+ *         conditional, and the absent-throw never triggers in test.)
+ * .scope = only the db-role credentials the service + migrations use are managed here. any
+ *          service-specific secrets (third-party api keys, etc) are declared alongside these by
+ *          the service that owns them. legacy param names with zero consumers are left unmanaged
+ *          (terraform forgets them, no delete touches the live values) and can be pruned from aws
+ *          once confirmed unreferenced everywhere.
+ */
+
+/**
+ * .what = the conformed environment this wish runs in (access ∈ test | prep | prod).
+ * .why = resolved once, as a module global, via sdk-environment's getEnvironment (reads the
+ *        ACCESS envar). the wish speaks the org-standard access vocab everywhere it can.
+ */
+const { access } = getEnvironment.static();
+
+/**
+ * .what = the legacy terraform stage label used inside the live param NAMES.
+ * .why = terraform seeded these params under var.environment, where the prep account carried the
+ *        legacy `dev` label (see define.infrastructure-dev-vs-application-prep). the live param
+ *        names contain that literal string, so the dotted namespace casts prep→dev. test/prod are
+ *        unchanged. (tags do NOT cast — they conform to the access vocab; see `secret` below.)
+ */
+const stage = access === 'prep' ? 'dev' : access;
+
+/**
+ * .what = declare a secret ssm parameter for adoption (write-only, default key).
+ * .why = every param here is a secret whose value already lives in aws; we supply no `value` so
+ *        plan KEEPs the extant value and never reads or rewrites it. keyId=null selects the
+ *        account default aws/ssm key (what terraform used, no kms_key_id). tags conform to the
+ *        org access vocab (`prep`, not the legacy `dev`), so the first apply reconciles the live
+ *        `environment` tag from dev→prep (a metadata-only change, no value write).
+ */
+const secret = (name: string): DeclaredAwsSsmParameterSecure =>
+  DeclaredAwsSsmParameterSecure.as({
+    name,
+    keyId: null, // default aws/ssm key (matches the terraform resources)
+    description: null,
+    tags: {
+      app: '@declapract{variable.organizationName}',
+      environment: access,
+      product: '@declapract{variable.projectName}',
+    },
+    // no `value` → write-only KEEP: adopt the live value, never read or rewrite it
+  });
+
+/**
+ * .what = the full set of secret ssm parameters this wish declares.
+ * .why = the db-role credentials the service + migrations use. declared for every access tier —
+ *        no per-tier conditional. only prep + prod ever APPLY this wish (there is no
+ *        aws-test-declastruct provision job — see .github/workflows/provision.yml), so the
+ *        value-less-absent throw on apply cannot trigger in test. test sources its non-sensitive
+ *        db creds straight from config/test.json and never reconciles these params.
+ * .note = the for-plan credential is the plan role's one decrypt exception; its name is pinned in
+ *         the prod plan role's iam policy, so it MUST stay byte-identical.
+ */
+export const getParameters = (): DeclaredAwsSsmParameterSecure[] => {
+  // dotted namespace that prefixes the env-scoped param names
+  // keep in sync with terraform local.parameter_store_namespace + config/${env}.json
+  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${stage}`;
+
+  return [
+    secret(`${namespace}.database.role.crud.password`),
+    secret(`${namespace}.database.role.cicd.for-plan.password`),
+    secret(`${namespace}.database.role.cicd.for-apply.password`),
+  ];
+};

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.ts

@@ -0,0 +1,27 @@
+import type { DeclastructProvider } from 'declastruct';
+import { getDeclastructAwsProvider } from 'declastruct-aws';
+import type { DomainEntity } from 'domain-objects';
+import { genLogMethods } from 'sdk-logs';
+
+import { getParameters } from './resources.parameters';
+
+/**
+ * .what = the declastruct wish for this service's aws resources.
+ * .why = declastruct-aws owns the ssm parameters that terraform now forgets (see
+ *        provision/aws/product/parameter-store.tf). the plan role reconciles secrets
+ *        WITHOUT any ssm:GetParameter or kms:Decrypt; apply writes via PutParameter +
+ *        kms:Encrypt.
+ */
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  await getDeclastructAwsProvider(
+    {},
+    {
+      // MUST be an sdk-logs logger — the DAOs read log._.level via as-procedure
+      log: genLogMethods(),
+    },
+  ),
+];
+
+export const getResources = async (): Promise<DomainEntity<any>[]> =>
+  getParameters();

package/dist/practices/persist-with-rds/best-practice/provision/schema/connection.config.js

@@ -7,13 +7,19 @@ const { getConfig } = require('../../src/utils/config/getConfig');
 
 const promiseSchemaControlCredentials = async () => {
   const config = await getConfig();
+
+  // select the cicd grant to connect as; default to for-apply (full/write access).
+  // the plan job opts down to the readonly for-plan grant via GRANT=plan.
+  const grant = process.env.GRANT === 'plan' ? 'for-plan' : 'for-apply';
+  const role = config.database.role.cicd[grant];
+
   const credentials = {
     host: config.database.tunnel.local.host,
     port: config.database.tunnel.local.port,
     database: config.database.target.database,
     schema: config.database.target.schema,
-    username: config.database.role.cicd.username,
-    password: config.database.role.cicd.password,
+    username: role.username,
+    password: role.password,
   };
   return credentials;
 };

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -1,45 +1,103 @@
 import { z } from 'zod';
 
-export const schema = z.object({
-  organization: z.string(),
-  project: z.string(),
-  environment: z.object({
-    access: z.enum(['test', 'prep', 'prod']),
-  }),
-  aws: z.object({
-    account: z.string(),
-    namespace: z.string(),
-  }),
-  database: z.object({
-    target: z.object({
-      database: z.string(),
-      schema: z.string(),
+/** .what = the two oidc grant scopes config can be read under. */
+export type Grant = 'plan' | 'apply';
+
+/**
+ * .what = get the config schema for a given oidc grant.
+ * .why = the prod plan job's oidc role is DENIED every ssm secret except the
+ *        for-plan db credential. under grant=plan the
+ *        eagerly-read getConfig() cannot read for-apply's password (or any other
+ *        secret); sdk-config substitutes undefined for each denied param, so those
+ *        must be .optional() to tolerate the miss. grant=apply (the default — apply
+ *        job, cloud runtime, local dev, tests) keeps every secret REQUIRED, so its
+ *        inferred type carries no `| undefined` and needs no guards at consumers.
+ * .note = grant is a per-schema arg, NOT read from env here; getConfig picks which
+ *         schema to parse with at call time (see getConfig.ts).
+ */
+const getSchema = <TGrant extends Grant>(grant: TGrant) => {
+  // required by default; optional only under grant=plan. generic on the LITERAL
+  // TGrant so each schema infers monomorphically (all-required for apply,
+  // reader-denied-optional for plan) instead of the widened union.
+  // .note on `as`: a conditional return type cannot be proven from the runtime
+  //   ternary, so TS needs this one assertion. it is sound — the branch matches
+  //   TGrant exactly (plan => .optional(), apply => schema).
+  const secret = <T extends z.ZodTypeAny>(
+    schema: T,
+  ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
+    (grant === 'plan' ? schema.optional() : schema) as TGrant extends 'plan'
+      ? z.ZodOptional<T>
+      : T;
+
+  return z.object({
+    organization: z.string(),
+    project: z.string(),
+    environment: z.object({
+      access: z.enum(['test', 'prep', 'prod']),
     }),
-    role: z.object({
-      cicd: z.object({
-        username: z.string(),
-        password: z.string(),
-      }),
-      crud: z.object({
-        username: z.string(),
-        password: z.string(),
-      }),
+    aws: z.object({
+      account: z.string(),
+      namespace: z.string(),
     }),
-    tunnel: z.object({
-      bastion: z.string(),
-      cluster: z.string(),
-      local: z.object({
-        host: z.string(),
-        port: z.number(),
+    database: z.object({
+      target: z.object({
+        database: z.string(),
+        schema: z.string(),
       }),
-      lambda: z
-        .object({
+      role: z.object({
+        cicd: z.object({
+          // for-plan and for-apply may map to DIFFERENT db users (e.g. a readonly
+          // user for-plan), so each carries its own username. names mirror the prod
+          // oidc roles (for-plan / for-apply) that read them.
+          // .note: only for-apply's PASSWORD is reader-denied under grant=plan; the
+          // username is a readable static, so the object is always present. mark the
+          // password itself as the secret (a secret() on the whole object would never
+          // tolerate the miss — the present object still validates its required password).
+          'for-plan': z.object({ username: z.string(), password: z.string() }),
+          'for-apply': z.object({
+            username: z.string(),
+            password: secret(z.string()),
+          }),
+        }),
+        crud: z.object({
+          username: z.string(),
+          password: secret(z.string()),
+        }),
+      }),
+      tunnel: z.object({
+        bastion: z.object({ exid: z.string() }).optional(),
+        cluster: z.object({ name: z.string() }).optional(),
+        local: z.object({
           host: z.string(),
           port: z.number(),
-        })
-        .nullable(),
+        }),
+        lambda: z
+          .object({
+            host: z.string(),
+            port: z.number(),
+          })
+          .nullable(),
+      }),
     }),
-  }),
-});
+  });
+};
+
+/**
+ * .what = one schema per grant. apply = every secret required (the default);
+ *         plan = the reader-denied secrets optional.
+ * .why = getConfig picks which to parse with by grant (see getConfig.ts).
+ */
+export const schema = {
+  apply: getSchema('apply'),
+  plan: getSchema('plan'),
+} as const;
 
-export type Config = z.infer<typeof schema>;
+/**
+ * .what = the config type for a grant, default apply.
+ * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
+ *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
+ *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
+ */
+export type Config<TGrant extends Grant = 'apply'> = z.infer<
+  (typeof schema)[TGrant]
+>;

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

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

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

@@ -3,14 +3,17 @@ import {
   type DeclaredGithubBranch,
   DeclaredGithubBranchProtection,
   DeclaredGithubEnvironment,
+  type DeclaredGithubOrg,
   DeclaredGithubRepo,
   DeclaredGithubRepoConfig,
   DeclaredGithubRepoRuleset,
+  type DeclaredGithubTeam,
   DeclaredGithubTeamRepoAccess,
   getDeclastructGithubProvider,
 } from 'declastruct-github';
 import { type DomainEntity, RefByUnique } from 'domain-objects';
 import { UnexpectedCodePathError } from 'helpful-errors';
+import { genLogMethods } from 'sdk-logs';
 
 import pkgJson from '../../package.json';
 
@@ -30,12 +33,8 @@ export const getProviders = async (): Promise<DeclastructProvider[]> => [
       },
     },
     {
-      log: {
-        info: () => {},
-        debug: () => {},
-        warn: console.warn,
-        error: console.error,
-      },
+      // MUST be an sdk-logs logger — 1.6.0 DAOs read log._.level via as-procedure
+      log: genLogMethods(),
     },
   ),
 ];
@@ -128,9 +127,15 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     restrictions: null,
   });
 
-  // grant releasers team access to the repo (required before they can be environment reviewers)
-  const teamReleasersAccess = DeclaredGithubTeamRepoAccess.as({
-    team: { org: { login: '@declapract{variable.organizationName}' }, slug: 'releasers' },
+  // ref the releasers team
+  const teamReleasers = RefByUnique.as<typeof DeclaredGithubTeam>({
+    org: RefByUnique.as<typeof DeclaredGithubOrg>({ login: '@declapract{variable.organizationName}' }),
+    slug: 'releasers',
+  });
+
+  // grant the releasers team push access to the repo (standalone; no env depends on it)
+  const teamReleasersRepoAccess = DeclaredGithubTeamRepoAccess.as({
+    team: teamReleasers,
     repo,
     permission: 'push', // write access needed to deploy
   });
@@ -141,32 +146,56 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     name: 'production-on-main',
     reviewers: null, // no approval required — PR merge is the gate
     waitTimer: null, // no delay
-    deploymentBranchPolicy: { customBranches: ['main'] }, // only main branch
+    deploymentBranchPolicy: {
+      // accept both the main branch and `v*` release tags: prod deploys are
+      // triggered by a release tag cut from main (see protect-release-tags
+      // ruleset below), so the ref gate must admit that tag. a branch-only
+      // policy would have the environment reject the tag-triggered deploy.
+      // (requires declastruct-github >=1.7.2 for tag-target customPatterns.)
+      customPatterns: [
+        { name: 'main', target: 'branch' },
+        { name: 'v*', target: 'tag' },
+      ],
+    },
+    preventSelfReview: false,
+  });
+
+  // declare environment for adhoc production apply from a non-main branch
+  // .why = github env "required reviewers" is Enterprise-only; on a private repo
+  //        under the Free/Pro/Team plan the api returns 422 for BOTH team and user
+  //        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).
+  const envProductionOnElseApply = DeclaredGithubEnvironment.as({
+    repo,
+    name: 'production-on-else-apply',
+    reviewers: null, // gate is the aws actor_id allowlist, not a github reviewer
+    waitTimer: null,
+    deploymentBranchPolicy: null, // any branch
     preventSelfReview: false,
   });
 
-  // declare environment for production deployments from other branches (requires approval)
-  const envProductionOnElse = DeclaredGithubEnvironment.as({
+  // declare environment for production plan from any branch (readonly, no approval)
+  const envProductionOnElsePlan = DeclaredGithubEnvironment.as({
     repo,
-    name: 'production-on-else',
-    reviewers: { users: null, teams: ['releasers'] },
-    waitTimer: null, // no delay once approved
+    name: 'production-on-else-plan',
+    reviewers: null, // no approval required — plan is readonly, safe
+    waitTimer: null, // no delay
     deploymentBranchPolicy: null, // any branch
-    preventSelfReview: false, // self-approval allowed if in reviewers list
+    preventSelfReview: false,
   });
 
   // restrict who may cut `v*` release tags to the rhelease app only
-  // .why = prod apply is gated on a version tag cut from main; if anyone could push a
-  //        `v*` tag, that gate is bypassable. this ruleset blocks creation, update, and
-  //        deletion of `v*` tags for everyone except the rhelease app — the github half
-  //        of the prod-apply oidc guarantee, and the immutability of released tags
+  // .why = prod apply is gated on a release tag cut from main; if anyone could push a
+  //        `v*` tag, that gate is bypassable. this ruleset blocks create/move/delete of
+  //        `v*` tags for everyone except the rhelease app (the github half of the oidc guarantee)
   const rulesetReleaseTags = DeclaredGithubRepoRuleset.as({
     repo,
     name: 'protect-release-tags',
     target: 'tag',
     enforcement: 'active',
 
-    // only the rhelease github app may write `v*` tags
+    // only the rhelease github app may create `v*` tags
     bypassActors: [
       {
         actorId: 2472031, // rhelease github app id (gh api /apps/rhelease)
@@ -191,9 +220,10 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     repo,
     repoConfig,
     branchMainProtection,
-    teamReleasersAccess, // must come before environments that reference this team
+    teamReleasersRepoAccess,
     envProductionOnMain,
-    envProductionOnElse,
+    envProductionOnElseApply,
+    envProductionOnElsePlan,
     rulesetReleaseTags,
   ];
 };

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

@@ -0,0 +1,32 @@
+rhachet boots roles, and role boots write scratch state into `.agent/.cache/`
+
+so this practice declares the gitignore line for that dir — the practice that creates the scratch
+declares its ignore, rather than a neighbor practice a repo may not have taken.
+
+📖 several practices declare this same `.gitignore`. the contract they share — one shared
+algorithm, the ordered tail, what a new declarer owes — is stated once at
+`.agent/repo=.this/role=any/briefs/howto.declare-the-repo-gitignore.md`. read that before you add
+a line here.
+
+## it declares only `.agent/.cache/`, not `.cache/`
+
+`.cache/` is generic tool scratch and belongs to the `git` practice. a practice declares the
+ignore for the dirs it creates.
+
+⚠️ **"rhachet owns it" does not mean "git should drop it".** the `git` practice declares
+`.agent/.cache/` too, and that line stays: `app-react-native-expo` (`src/useCases.yml`) takes
+`git` **without** `rhachet`, so for those repos git's line is the only explicit source of the
+ignore.
+
+## the end-to-end proof lives under the git practice
+
+`src/practices/git/.declapract.integration.test.ts` → `[case2] a repo whose use case has rhachet
+but NOT git`.
+
+that is the scenario which justifies this declaration at all. it clones a demo repo whose use case
+omits `git`, applies **this** practice alone, and asserts the agent cache path is ignored with no
+help from git, that `.cache/` is correctly absent, that the negation is honored by git itself, and
+that a re-apply changes zero bytes.
+
+it sits there because one temp repo must hold both declarations to prove they agree. this pointer
+exists so a reader in `src/practices/rhachet/` can find it.

package/dist/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -0,0 +1,64 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+
+import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGitignoreContents';
+
+/**
+ * ignores that this practice itself owns
+ *
+ * .why = rhachet boots roles which write scratch state into `.agent/.cache/`. the
+ *        practice that creates the dir declares the ignore for it, so a repo that
+ *        takes `rhachet` is never left with cruft it did not ask for:
+ *        - a worktree teardown is not snagged by untracked scratch
+ *        - a hurried `git add .` cannot sweep a debug file that holds a secret
+ *
+ * .note = `.cache/` is generic tool scratch and belongs to the `git` practice, not
+ *         here. a practice declares the ignore for the dirs IT creates, and no more.
+ *
+ * .note = this list is NOT sorted here, and that is deliberate. `defineExpectedGitignoreContents`
+ *         sorts the union of these lines with the repo's own, so a `.sort()` at this site would
+ *         be a second sort that changes no output -- while it mutates a module-cached array in
+ *         place. `readonly` forbids that mutation outright rather than merely discourages it
+ *         (`rule.prefer.prevent-over-correct`).
+ */
+const ignoresSortable: readonly string[] = ['.agent/.cache/'];
+
+/**
+ * .what = emits the `.gitignore` this practice declares, given the repo's extant one
+ * .why  = the algorithm AND the ordered tail are imported, not declared here, because
+ *         `src/practices/git/best-practice/.gitignore.declapract.ts` declares this same
+ *         repo-root file. two declarers converge only while both emit an identical tail
+ *         by an identical algorithm -- so they share one, and the drift that would break
+ *         convergence cannot be written.
+ * .note = this file declares only `ignoresSortable`, which is the part the two
+ *         practices legitimately DIFFER on: rhachet owns `.agent/.cache/`, git owns
+ *         the generic scratch. the shared part is shared; the owned part is owned.
+ */
+const defineExpectedContents = (contents: string | null): string =>
+  defineExpectedGitignoreContents({ contents, ignoresSortable });
+
+/**
+ * .what = throws when the repo's `.gitignore` does not carry what this practice declares
+ * .why  = `check` is the GATE: declapract runs `fix` for a file only when `check`
+ *         rejects it. so this is what makes an upgrade actually deliver
+ *         `.agent/.cache/` to a repo that lacks it.
+ * .note = best-practice semantics are inverted from what a reader expects -- a THROW
+ *         means the practice is violated, a return means it is followed. see
+ *         `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ */
+export const check: FileCheckFunction = (contents) => {
+  expect(contents).toEqual(defineExpectedContents(contents));
+};
+
+/**
+ * .what = unions this practice's declared ignores into the repo's `.gitignore`
+ * .why  = a findsert by construction -- a line already present stays present once,
+ *         and a repo's own custom ignores survive, because the file's extant lines
+ *         are unioned in before the sort.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output -- without both, `declapract fix` would rewrite this file forever.
+ *         clamped by `.gitignore.declapract.test.ts` -> `idempotency`.
+ */
+export const fix: FileFixFunction = (contents) => {
+  return { contents: defineExpectedContents(contents) };
+};

package/dist/practices/terraform-aws/best-practice/provision/aws/environments/prep/versions.tf

@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 0.14"
+  required_version = ">= 1.7" # removed{} blocks (parameter-store forget) need >= 1.7
   required_providers {
     aws = {
       source  = "hashicorp/aws"

package/dist/practices/terraform-aws/best-practice/provision/aws/environments/prod/versions.tf

@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 0.14"
+  required_version = ">= 1.7" # removed{} blocks (parameter-store forget) need >= 1.7
   required_providers {
     aws = {
       source  = "hashicorp/aws"

package/dist/practices/terraform-aws/best-practice/provision/aws/environments/test/versions.tf

@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 0.14"
+  required_version = ">= 1.7" # removed{} blocks (parameter-store forget) need >= 1.7
   required_providers {
     aws = {
       source  = "hashicorp/aws"

package/dist/utils/defineExpectedGitignoreContents.ts

@@ -0,0 +1,84 @@
+import { dedupe } from 'domain-objects';
+
+/**
+ * .what = the ignores whose POSITION carries load, in the sequence git requires
+ * .why  = a `.gitignore` negation re-includes a path only when it appears AFTER the
+ *         pattern it negates. hoist a `!` line above its target and git silently drops
+ *         the negation -- the file still reads as correct while every test-fixture
+ *         `node_modules` it protects is re-ignored.
+ * .why  = it lives HERE, shared, rather than in each declaration, because every
+ *         practice that declares the repo-root `.gitignore` must emit an IDENTICAL
+ *         tail or the two converge no longer, and `declapract fix` rewrites the file on
+ *         every run. one constant makes that drift unrepresentable.
+ * .note = `.test*` dirs hold cloned repos (test fixtures via `genTempDir`), whose
+ *         `node_modules` must stay tracked.
+ * .note = `readonly` carries load here, it is not decoration. this array is
+ *         module-cached and shared by every declarer, so ONE in-place mutation anywhere
+ *         (`.push`, an in-place `.sort`, `.reverse`) would break convergence for ALL of
+ *         them at once -- at runtime, with no compiler signal. `readonly` makes that
+ *         unrepresentable rather than merely discouraged
+ *         (`rule.prefer.prevent-over-correct`).
+ * .note = typed `readonly string[]` rather than `as const`: `as const` narrows the
+ *         elements to literal types, which would make `orderedPatterns.has(line)` below
+ *         reject a plain `string`. this form keeps the element type while it forbids the
+ *         mutation.
+ */
+export const ignoresOrderedForGitignore: readonly string[] = [
+  'node_modules',
+  '!.test*/**/node_modules',
+  '!.test*/**/node_modules/**',
+];
+
+/**
+ * .what = emits the `.gitignore` a practice declares, given the repo's extant one
+ * .why  = a findsert by construction -- the file's own lines are unioned in before the
+ *         sort, so a repo's custom ignores survive and a line already present stays
+ *         present once. and it is a fixed point: `fix(fix(x)) === fix(x)`.
+ * .why  = SHARED across every practice that declares this file. convergence between
+ *         two declarers rests on the whole ALGORITHM, not merely the tail -- union,
+ *         then sort, then append. two copies could drift step-for-step; one cannot.
+ * .note = `sortable` vs `ordered` is the domain's split for a declared line: inert
+ *         position vs load-carrying position. see
+ *         `.agent/repo=.this/role=any/briefs/domain.terms/term=ordered._.choice._.md`.
+ *
+ * ⚠️ .note = **THIS FUNCTION IS THE CONTRACT, NOT A CONVENIENCE.** every practice that declares
+ *         the repo-root `.gitignore` converges only because all of them route through here. a
+ *         declaration that hand-rolls its own union/sort/tail instead of this import is OUTSIDE
+ *         that guarantee -- it may satisfy its own check and still oscillate against the rest,
+ *         forever, on every `declapract fix`.
+ *
+ *         that failure mode is measured, not hypothetical. every declaration of this file once
+ *         carried its own copy of the algorithm, and one of them fell behind: it sorted every
+ *         line and emitted no ordered tail, which hoists the `!` negations above their target and
+ *         turns them inert. re-derive any declaration by hand today and the clamps reproduce it
+ *         exactly -- that declaration's own idempotency assertions stay green while every
+ *         cross-declarer assertion goes red.
+ *
+ *         no build step stops the next author from a repeat. so: **if you declare the repo-root
+ *         `.gitignore` from a new practice, import this -- do not re-derive it.** a lint rule or a
+ *         single-owner registry would be the durable guard; today the cross-declarer clamps are.
+ */
+export const defineExpectedGitignoreContents = (input: {
+  contents: string | null;
+  ignoresSortable: readonly string[];
+}): string => {
+  // parse ignores from the repo's extant file
+  const ignoresFromFile = input.contents ? input.contents.split('\n') : [];
+
+  // separate the file's own lines into sortable vs ordered
+  const orderedPatterns = new Set(ignoresOrderedForGitignore);
+  const ignoresFromFileSortable = ignoresFromFile.filter(
+    (line) => !!line && !orderedPatterns.has(line),
+  );
+
+  // union the file's sortable lines with this practice's, then sort
+  const sortedIgnores = dedupe([
+    ...ignoresFromFileSortable,
+    ...input.ignoresSortable,
+  ])
+    .sort()
+    .filter((line) => !!line);
+
+  // append the ordered tail last, sequence preserved
+  return [...sortedIgnores, ...ignoresOrderedForGitignore, ''].join('\n');
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.49.7",
+  "version": "0.49.9",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,15 +76,15 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.43.1",
-    "rhachet-brains-anthropic": "0.4.1",
+    "rhachet": "1.44.4",
+    "rhachet-brains-anthropic": "0.4.3",
     "rhachet-brains-fireworksai": "0.1.3",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.29.24",
+    "rhachet-roles-bhrain": "0.31.3",
     "rhachet-roles-bhrowser": "0.1.0",
-    "rhachet-roles-bhuild": "0.21.22",
-    "rhachet-roles-ehmpathy": "1.38.1",
-    "rhachet-roles-ghlitch": "0.2.5",
+    "rhachet-roles-bhuild": "0.21.31",
+    "rhachet-roles-ehmpathy": "1.38.6",
+    "rhachet-roles-ghlitch": "0.2.10",
     "rhachet-roles-rhachet": "0.1.7",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",