declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/<star><star>/<star>peer-review<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the old flat shape, where peer-review files sit directly in
+ *         .reviews with `peer-review` in the filename
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.behavior/<star><star>/.reviews/peer/<star><star>/<star>.md.declapract.ts

@@ -0,0 +1,16 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects committed peer-review artifacts under .behavior/**\/.reviews/peer
+ * .why = peer-review files are noise; far less important than the root behavior
+ *        files, so they should not be tracked in git
+ *
+ * .note = matches the new shape, where all peer-review files live under a
+ *         dedicated `peer` directory
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/review-peer-artifacts/.declapract.readme.md

@@ -0,0 +1,12 @@
+peer review artifacts should not be committed to git
+
+these files live under `.behavior/**/.reviews/` and capture peer-review feedback
+from the behavior build lifecycle. they are noise for the most part — far less
+important than the root behavior files themselves.
+
+two path shapes are removed:
+
+- old (flat): `.behavior/**/.reviews/**/*peer-review*.md`
+- new (peer dir): `.behavior/**/.reviews/peer/**/*.md`
+
+self-reviews and other non-peer artifacts under `.reviews/` are intentionally left alone.

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

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

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/.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/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/.gitignore.declapract.ts

@@ -0,0 +1,77 @@
+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/`, 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 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.
+ *
+ * .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/',
+  '.claude/scheduled_tasks*',
+];
+
+/**
+ * .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/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/package.json

@@ -0,0 +1,18 @@
+{
+  "devDependencies": {
+    "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.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/.test/assets/expo-fullusecase/declarations/practices/rhachet/best-practice/package.json.declapract.ts

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

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')",
+}
+`;