declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/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/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/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/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"
   }
 }