declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/expo-fullusecase/declarations/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/.test/assets/expo-fullusecase/declarations/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/.test/assets/expo-fullusecase/declarations/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) };

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.agent/repo=.this/role=any/boot.yml

@@ -0,0 +1,46 @@
+# boot.yml — curate which briefs load into context at each session boot.
+#
+# every brief loads at one of two levels:
+#   say = full content in context        (costs tokens on every boot)
+#   ref = path only, fetched on demand   (near-zero tokens)
+#
+# this file is SIMPLE mode: a top-level `briefs:` with `say` and/or `ref` glob
+# lists. the `say` key sets the DEFAULT level for every brief it does not match:
+#
+#   say absent (this file)    say ALL, except what the `ref` globs demote below.
+#                             the backcompat default — the whole corpus loads say.
+#   say present + non-empty    say ONLY what `say` matches; ref everything else.
+#                             (once `say` is set the `ref` list is inert — anything
+#                              `say` does not match is already ref.)
+#   say present + empty []     say none; ref all.
+#
+# TO CURATE (recommended once a repo grows brief-heavy): add a `say:` allowlist of
+# the briefs you want resident each boot. the moment `say` is non-empty the default
+# FLIPS to ref-by-default, so a large corpus stops loading whole. e.g.:
+#
+#   briefs:
+#     say:
+#       - briefs/rule.*.md
+#       - briefs/howto.*.md
+#
+# the `ref` globs below are the backcompat demotions — they bite ONLY while `say`
+# is absent, and demote the deep glossary variants (reason + example) to on-demand.
+# skills curate the same way, via a top-level `skills:` block.
+#
+# this file is FINDSERTED into a consumer, never overwritten — your own say/ref
+# entries survive an upgrade; the fix only unions the declared ref globs in.
+
+# budget — the token cap for the resident `say` payload at each boot.
+# a boot whose say-content exceeds this halts, so the corpus cannot silently bloat
+# context. remedies: demote a say glob to ref, adopt a .min brief variant, or raise
+# this cap deliberately. enforced by rhachet once ehmpathy/rhachet#536 lands (with the
+# --manifest boot of #537); declared here now so the cap is in place on arrival.
+# NOTE: plain `5000`, not `5_000` — yaml 1.2 (the yaml v2 default) reads an underscore
+# integer as a STRING, which would silently make the cap non-numeric.
+budget:
+  tokens: 5000
+
+briefs:
+  ref:
+    - briefs/domain.terms/term=*._.choice.reason.md
+    - briefs/domain.terms/term=*._.choice.example=*.md

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.agent/repo=.this/role=any/boot.yml.declapract.ts

@@ -0,0 +1,165 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+
+/**
+ * .what = the ref globs this practice declares — the deep glossary variants that stay on-demand.
+ * .why  = the boot.yml default is say-all (see the template); these two globs are the sole
+ *         demotions to ref, so a consumer's whole glossary rides in context while the reason-deep
+ *         and example variants stay a path-only fetch away. the findsert ensures a consumer's file
+ *         carries these two demotions, never the whole template — so its own boot entries survive.
+ */
+const declaredRefGlobs: readonly string[] = [
+  'briefs/domain.terms/term=*._.choice.reason.md',
+  'briefs/domain.terms/term=*._.choice.example=*.md',
+];
+
+/**
+ * .what = the token cap this practice findserts for the resident `say` payload at each boot.
+ * .why  = a boot whose say-content exceeds this halts, so the corpus cannot silently bloat context.
+ *         findserted so an extant consumer inherits the cap on upgrade, not only a fresh one — the
+ *         template block ships to a new consumer, this findsert reaches the ones already on disk.
+ *         findsert semantics: absent -> add; present -> leave the consumer's chosen value untouched,
+ *         so a consumer who deliberately raised or lowered the cap is never reverted.
+ */
+const declaredBudgetTokens = 5_000;
+
+/**
+ * .what = the comment the findsert attaches above the `budget:` key it injects.
+ * .why  = a bare `budget:\n  tokens: 5000` gives a consumer no clue why the value is plain, so a
+ *         later tidy-up could "improve" it to `5_000` and silently make the cap a yaml STRING. the
+ *         findserted block must carry the same NOTE the shipped template does, so the trap is warned
+ *         at the exact spot the value lands.
+ * .note = the yaml serializer prefixes each line with `# `, so a space at the front renders `# budget`.
+ */
+const declaredBudgetComment = [
+  ' budget — the token cap for the resident `say` payload at each boot.',
+  ' a boot whose say-content exceeds this halts, so the corpus cannot silently bloat',
+  ' context. remedies: demote a say glob to ref, adopt a .min brief variant, or raise',
+  ' this cap deliberately.',
+  ' NOTE: plain `5000`, not `5_000` — yaml 1.2 (the yaml v2 default) reads an underscore',
+  ' integer as a STRING, which would silently make the cap non-numeric.',
+].join('\n');
+
+/**
+ * .what = true when a consumer's boot.yml already declares `budget.tokens` (any value).
+ * .why  = the findsert gate: add the cap only when a consumer carries none, so a present value — even
+ *         a divergent one a consumer chose on purpose — is preserved (findsert, never upsert).
+ */
+const hasBudgetTokens = (doc: yaml.Document): boolean =>
+  doc.getIn(['budget', 'tokens']) !== undefined;
+
+/**
+ * .what = reads the ref globs a consumer's boot.yml currently carries, from whichever mode it uses.
+ * .why  = a consumer may curate in SIMPLE mode (top-level `briefs.ref`) or the legacy SUBJECT mode
+ *         (`always.briefs.ref`). read from whichever exists so the union is computed against the
+ *         consumer's real ref list, never a presumed one. no mutation here — this is the read half.
+ */
+const getCurrentRefGlobs = (doc: yaml.Document): string[] => {
+  // the yaml node api is an external boundary; a documented projection to json is the in-repo norm
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const node: any =
+    doc.getIn(['always', 'briefs', 'ref']) ?? doc.getIn(['briefs', 'ref']);
+  if (!node) return [];
+  return (node.toJSON() as string[] | null) ?? [];
+};
+
+/**
+ * .what = the mutable ref seq node to union into: the consumer's extant one, or a seeded simple-mode one.
+ * .why  = union into whichever ref list already exists (subject or simple), so a subject-mode consumer
+ *         is never corrupted into an invalid mixed `always:`+`briefs:` file. only when NEITHER exists
+ *         does the fix seed a simple-mode `briefs.ref` — the go-forward shape.
+ */
+const getOrSeedRefSeq = (doc: yaml.Document): unknown => {
+  const subject = doc.getIn(['always', 'briefs', 'ref']);
+  if (subject) return subject;
+  const simple = doc.getIn(['briefs', 'ref']);
+  if (simple) return simple;
+  // neither ref list exists — seed a real seq node (a plain [] becomes a js
+  // array without the `.add` the union relies on), then union into it.
+  const seq = new yaml.YAMLSeq();
+  doc.setIn(['briefs', 'ref'], seq);
+  return seq;
+};
+
+/**
+ * .what = the boot.yml a consumer should hold — its extant file with the declared ref globs unioned in
+ *         and the budget cap findserted, or the whole declared template when the consumer has none yet.
+ * .why  = a findsert by construction: a glob already present stays present once, a budget already set
+ *         is left as the consumer chose it, and every other line (a consumer's own say/ref entries,
+ *         comments, mode) is preserved because the file is mutated in place via the yaml document api,
+ *         never regenerated.
+ * .note = a fixed point — an already-conformant file is returned verbatim (no round-trip), so
+ *         `fix(fix(x)) === fix(x)` and `check` passes on its own output; without both, `declapract
+ *         fix` would rewrite this file forever.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  declaredContents: string,
+): string => {
+  // a fresh consumer (no boot.yml) gets the whole declared template verbatim.
+  if (!contents) return declaredContents;
+
+  const doc = yaml.parseDocument(contents);
+  const absentGlobs = declaredRefGlobs.filter(
+    (glob) => !getCurrentRefGlobs(doc).includes(glob),
+  );
+  const budgetAbsent = !hasBudgetTokens(doc);
+
+  // already conformant → return the consumer's file verbatim (no round-trip).
+  if (absentGlobs.length === 0 && !budgetAbsent) return contents;
+
+  // deliberate mutation — the yaml document api mutates the seq node in place to
+  // preserve the adjacent comments; there is no immutable seq-add.
+  if (absentGlobs.length > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const refSeq = getOrSeedRefSeq(doc) as any;
+    absentGlobs.forEach((glob) => refSeq.add(glob));
+  }
+
+  // findsert the budget cap — only when the consumer declares none, so a chosen value survives.
+  // attach the NOTE above the `budget:` key so the plain-5000 yaml trap is warned where it lands.
+  if (budgetAbsent) {
+    doc.setIn(['budget', 'tokens'], declaredBudgetTokens);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const budgetPair = (doc.contents as any)?.items?.find(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (item: any) => yaml.isScalar(item.key) && item.key.value === 'budget',
+    );
+    if (budgetPair?.key) budgetPair.key.commentBefore = declaredBudgetComment;
+  }
+
+  return doc.toString();
+};
+
+/**
+ * .what = throws when a consumer's boot.yml lacks a declared ref glob (or is absent entirely).
+ * .why  = `check` is the GATE: declapract runs `fix` only when `check` rejects. so this is what makes
+ *         an upgrade actually union the deep-variant ref demotions AND findsert the budget cap into a
+ *         consumer that lacks them.
+ * .note = best-practice semantics are inverted — a THROW means the practice is violated, a return
+ *         means it is followed. see `.agent/repo=.this/role=any/briefs/declapract-check-semantics.md`.
+ *         the equality is against the FINDSERT output (globs unioned, budget cap ensured), never the
+ *         whole template, so a consumer's own boot entries pass the check untouched.
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  expect(contents).toEqual(
+    defineExpectedContents(contents, context.declaredFileContents ?? ''),
+  );
+};
+
+/**
+ * .what = unions the declared ref globs into a consumer's boot.yml and findserts the budget cap (or
+ *         writes the template if absent).
+ * .why  = fix forward once, for every consumer — never a whole-file overwrite that would drop a
+ *         consumer's own say/ref curation (#105 req 1).
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(
+      contents,
+      context.declaredFileContents ?? '',
+    ),
+  };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -6,11 +6,21 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
 /**
  * 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:
+ * .why = rhachet boots roles which write scratch state into `.agent/.cache/`, and the
+ *        claude-code harness those roles run writes machine-local scheduler state into
+ *        `.claude/scheduled_tasks*` (a lock + queue). the practice that creates a 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
+ *        - a hurried `git add .` cannot sweep a machine-local lock or a debug file that
+ *          holds a secret
+ *
+ * .note = `.claude/scheduled_tasks*` is machine-local by nature -- a lock/queue for THIS
+ *         host's scheduler, never shared across a team -- so it is ignored, never tracked.
+ *         it belongs HERE, not in `git`: rhachet's role-boot harness is what creates it, and
+ *         a practice declares the ignore for the dirs IT creates. (`*.local.json`, the other
+ *         `.claude/` machine-local shape, stays in `git` -- it is a generic suffix, not a
+ *         rhachet-created path.)
  *
  * .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.
@@ -21,7 +31,10 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
  *         place. `readonly` forbids that mutation outright rather than merely discourages it
  *         (`rule.prefer.prevent-over-correct`).
  */
-const ignoresSortable: readonly string[] = ['.agent/.cache/'];
+const ignoresSortable: readonly string[] = [
+  '.agent/.cache/',
+  '.claude/scheduled_tasks*',
+];
 
 /**
  * .what = emits the `.gitignore` this practice declares, given the repo's extant one

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/package.json

@@ -1,18 +1,18 @@
 {
   "devDependencies": {
-    "rhachet": "@declapract{check.minVersion('1.43.1')}",
-    "rhachet-brains-anthropic": "@declapract{check.minVersion('0.4.1')}",
-    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.3')}",
+    "rhachet": "@declapract{check.minVersion('1.47.5')}",
+    "rhachet-brains-anthropic": "@declapract{check.minVersion('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.29.24')}",
+    "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.22')}",
-    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.1')}",
-    "rhachet-roles-ghlitch": "@declapract{check.minVersion('0.2.5')}",
+    "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 operator observer deployer playwright enroller",
+    "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/.test/assets/expo-fullusecase/declarations/practices/rhachet/boot-refs-glossary.declapract.integration.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the rhachet practice's shipped boot.yml defaults every brief to SAY level and
+ *         refs ONLY the deep glossary variants (`.reason`, `.example`), via GLOBs — never this repo's
+ *         enumerated term list, and never a `say:` enumeration.
+ * .why  = the boot.yml is a TEMPLATE copied to every consumer. under #105 the shape is SIMPLE mode
+ *         with `say` ABSENT + `ref` present, so the loader reads every discovered brief at say-level
+ *         EXCEPT the ref-matched deep variants. the ref entries must be globs (matched against the
+ *         consumer's tree by rhachet's fast-glob), never a hardcoded list of THIS repo's terms -- an
+ *         enumerated list would ref terms a consumer does not have and miss the ones it does. a glob
+ *         is also drift-proof: a new term's deep variants auto-demote, and no say entry is ever
+ *         enumerated.
+ * .teeth = swap a `term=*` deep-variant glob for an enumerated `term=convergence._.choice.reason.md`
+ *          and the "no hardcoded term name" case reddens; add a `say:` key and the "no say
+ *          enumeration" case reddens; add an `always:` key and the "simple mode" case reddens; ref
+ *          the `._.choice._.md` root (a say-level brief) and the "choice root stays say" case reddens.
+ * .note = the subject is the shipped TEMPLATE text. the `.integration.test.ts` suffix reads the
+ *         filesystem (a remote boundary); this file sits at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ * .note = this supersedes the #587 ref-all clamp: #587 refed the whole glossary (choice root +
+ *         readme) for a near-zero boot cost; #105 flips the default to say and refs only the
+ *         reason/example deep variants. the assertions below encode the #105 shape.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/rhachet/) the best-practice tree is one segment down.
+const bootYmlPath = join(
+  __dirname,
+  'best-practice/.agent/repo=.this/role=any/boot.yml',
+);
+
+const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+const CHOICE_ROOT_REF = 'briefs/domain.terms/term=*._.choice._.md';
+
+describe('rhachet boot.yml defaults to say, refs only deep glossary variants', () => {
+  given('[case1] the shipped boot.yml template', () => {
+    const contents = readFileSync(bootYmlPath, 'utf8');
+
+    when('[t0] the template is read', () => {
+      then('it is simple mode (top-level briefs:, no always:)', () => {
+        expect(contents).toMatch(/^briefs:/m);
+        expect(contents).not.toMatch(/^always:/m);
+      });
+
+      then('it enumerates no say entry (say defaults for every brief)', () => {
+        // the whole point of #105: `say` is absent, so the loader defaults every discovered brief to
+        // say. a `say:` key would enumerate — exactly what #105 forbids.
+        expect(contents).not.toMatch(/^\s*say:/m);
+      });
+
+      then('it refs the deep glossary variants via globs', () => {
+        expect(contents).toContain(REASON_REF);
+        expect(contents).toContain(EXAMPLE_REF);
+      });
+
+      then('it does not ref the choice root (it stays say-level)', () => {
+        // the `._.choice._.md` root is the say-lean brief a consumer wants in context; only the
+        // reason-deep + example variants demote to ref.
+        expect(contents).not.toContain(CHOICE_ROOT_REF);
+      });
+
+      then('it hardcodes no specific term name (stays per-consumer correct)', () => {
+        // a concrete `term=<slug>._.choice...` (slug != the `*` glob) would be this repo's own term,
+        // wrong for a consumer. the only legal `term=` token is the glob wildcard.
+        const concreteTermRefs = (
+          contents.match(/term=[a-z][a-z-]*\._\.choice/g) || []
+        ).filter((m) => !m.startsWith('term=*'));
+        expect(concreteTermRefs).toEqual([]);
+      });
+
+      then('the emitted glossary ref lines match snapshot', () => {
+        // snapshot the governed glossary ref lines themselves, so a reshaped ref that keeps the glob
+        // tokens green (a reordered entry, a rephrased comment) reddens a vibecheck in review
+        // (rule.require.contract-snapshot-exhaustiveness)
+        const refLines = contents
+          .split('\n')
+          .filter((line) => line.includes('domain.terms/'))
+          .map((line) => line.trim())
+          .join('\n');
+        expect(refLines).toMatchSnapshot('boot.yml glossary refs');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/boot-yml-findsert.declapract.integration.test.ts

@@ -0,0 +1,145 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the boot.yml FINDSERT (#105 req 1), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer whose boot.yml already carries its
+ *         OWN say + ref entries.
+ * .why  = req 1 is that the boot.yml is only ever findserted into a consumer, never whole-file
+ *         overwritten — so a consumer's own boot entries survive. per
+ *         `rule.require.declapract-integration-tests`, a `fix` with logic (a yaml union that reads the
+ *         consumer's extant file) owes a pipeline test: a unit test of the exported `fix` never
+ *         exercises the glob→file match nor the apply against a real consumer file. this is that test.
+ * .note = the consumer boot is SIMPLE mode with a `say` pick and a `ref` pick of its own. the
+ *         after-state proves both declared deep-variant globs are unioned in AND both consumer picks
+ *         survive byte-for-value — the whole-file-overwrite failure this guards against would drop them.
+ * .note = the boot is snapshotted in full (before AND after) so a reviewer can eyeball the exact
+ *         end-state (`rule.require.snapshots`).
+ */
+describe('rhachet — boot.yml findsert (req 1: consumer entries survive)', () => {
+  given("[case1] a consumer whose boot.yml carries its own entries", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-findsert',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+    const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+
+    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: bootPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the consumer boot.yml carries its own picks, no budget, + matches snapshot', async () => {
+        const before = await read(bootPath);
+        expect(before).toContain('briefs/my-own-brief.md');
+        expect(before).toContain('briefs/my-own-deep-variant.md');
+        // the consumer predates the budget cap — it carries none (the findsert-add path)
+        expect(yaml.parse(before).budget).toBeUndefined();
+        expect(before).toMatchSnapshot('boot.yml — before');
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('union the declared deep-variant globs into the consumer boot', async () =>
+        applyFix(),
+      );
+
+      then(
+        "both declared globs land AND the consumer's own say + ref picks survive, and it matches snapshot",
+        async () => {
+          const after = await read(bootPath);
+          const parsed = yaml.parse(after);
+
+          // the two declared deep-variant globs were unioned into the consumer's ref list
+          expect(parsed.briefs.ref).toContain(REASON_REF);
+          expect(parsed.briefs.ref).toContain(EXAMPLE_REF);
+          // the consumer's OWN ref pick survives (the whole-overwrite failure would drop it)
+          expect(parsed.briefs.ref).toContain('briefs/my-own-deep-variant.md');
+          // the consumer's OWN say pick survives untouched
+          expect(parsed.briefs.say).toContain('briefs/my-own-brief.md');
+          // it stayed simple mode — the fix created no top-level always: key
+          expect(parsed.always).toBeUndefined();
+          // the budget cap was findserted into a consumer that predated it
+          expect(parsed.budget.tokens).toEqual(5_000);
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('boot.yml — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // once both globs are present, the check passes and the fix is a no-op — the boot must be
+      // byte-identical across a re-apply (`rule.require.idempotent-fixes`).
+      const passes = useThen(
+        'a second apply over its own output',
+        async () => {
+          const before = await read(bootPath);
+          await applyFix();
+          const after = await read(bootPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+
+  given("[case2] a consumer whose boot.yml already declares a divergent budget", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-budget-preserved',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const bootAbs = path.join(tempDir, bootPath);
+
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: bootPath,
+      });
+
+    // seed the writable clone with a budget the consumer chose on purpose — a value the findsert
+    // must NOT revert (findsert, never upsert). this proves the present-value-preserved branch
+    // through the real pipeline, no extra fixture needed.
+    when('[t0] the consumer set its own budget of 9000', () => {
+      useThen('write a divergent budget into the cloned boot', async () => {
+        const before = await fs.readFile(bootAbs, 'utf-8');
+        await fs.writeFile(bootAbs, `${before}budget:\n  tokens: 9000\n`, 'utf-8');
+      });
+
+      then('the seed carries the consumer budget', async () => {
+        expect(yaml.parse(await fs.readFile(bootAbs, 'utf-8')).budget.tokens).toEqual(9000);
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('apply the fix over the consumer-chosen budget', async () => applyFix());
+
+      then("the consumer's budget survives untouched (findsert, never upsert)", async () => {
+        const parsed = yaml.parse(await fs.readFile(bootAbs, 'utf-8'));
+        expect(parsed.budget.tokens).toEqual(9000);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/tests-any/__snapshots__/changedsince-origin-main.declapract.integration.test.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`tests-any changedSince=origin/main policy given: the shipped best-practice/package.json when: the changed-file test commands are read then: the emitted changed-file commands match snapshot: tests-any changed-file commands 1`] = `
+{
+  "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n "\${CI:-}" ] && echo '--ci') $([ "\${THOROUGH:-}" != "true" ] && echo '--changedSince=origin/main') $([ "\${RESNAP:-}" = "true" ] && echo '--updateSnapshot')",
+  "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n "\${CI:-}" ] && echo '--ci') $([ "\${THOROUGH:-}" != "true" ] && echo '--changedSince=origin/main') $([ "\${RESNAP:-}" = "true" ] && echo '--updateSnapshot')",
+}
+`;