declapract-typescript-ehmpathy 0.49.14 → 0.50.0

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

@@ -0,0 +1,94 @@
+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*` at any depth (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*` at any depth 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/',
+  // role scratch notes (e.g. a draft issue comment); host-local, never source (#688)
+  '.agent/.notes/',
+  // `**/` so the actor brain's own `.agent/.actors/<actor>/brain/.claude/` lock is
+  // ignored too; a line with a slash anchors to the repo root otherwise (#667)
+  '**/.claude/scheduled_tasks*',
+];
+
+/**
+ * .what = lines this practice once declared and now replaces
+ * .why  = the root-anchored `.claude/scheduled_tasks*` is superseded by the any-depth form;
+ *         a union alone would leave it in every extant file forever
+ * .note = a lock already tracked stays tracked until `git rm --cached` — an ignore never
+ *         untracks a file
+ */
+const ignoresRetired: readonly string[] = ['.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,
+    ignoresRetired,
+  });
+
+/**
+ * .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/git/declarations/practices/rhachet/best-practice/package.json

@@ -0,0 +1,19 @@
+{
+  "devDependencies": {
+    "rhachet": "@declapract{check.minVersion('1.49.2')}",
+    "rhachet-brains-anthropic": "@declapract{check.minVersion('0.4.3')}",
+    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.2.3')}",
+    "rhachet-brains-openrouter": "@declapract{check.minVersion('0.1.3')}",
+    "rhachet-brains-xai": "@declapract{check.minVersion('0.3.3')}",
+    "rhachet-roles-bhrain": "@declapract{check.minVersion('0.40.0')}",
+    "rhachet-roles-bhrowser": "@declapract{check.minVersion('0.1.0')}",
+    "rhachet-roles-bhuild": "@declapract{check.minVersion('0.23.2')}",
+    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.39.5')}",
+    "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/git/declarations/practices/rhachet/best-practice/package.json.declapract.ts

@@ -0,0 +1,51 @@
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+
+import { getFileTextOrNull } from '../../../utils/getFileTextOrNull';
+import { readFile } from '../../../utils/readFile';
+
+/**
+ * .what = whether a package.json declares a `link:.` self-dep (a rhachet roles package)
+ * .why  = such a repo links its own roles, and `rhachet init` loads their hooks from `dist/`; any
+ *         dep whose value is `link:.` counts, so a self-dep under an alias still keys the build
+ */
+const hasSelfLinkDep = (input: { packageJson: string }): boolean => {
+  const parsed = JSON.parse(input.packageJson) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+  return [
+    ...Object.values(parsed.dependencies ?? {}),
+    ...Object.values(parsed.devDependencies ?? {}),
+  ].some((version) => version === 'link:.' || version === 'link:./');
+};
+
+/**
+ * .what = declare the rhachet package.json, with `npm run build && ` before `rhachet init` in a
+ *         repo that self-links its own roles (#520)
+ * .why  = a `link:.` repo boots its own roles, whose hooks load from the compiled `dist/`; with no
+ *         build first, hook discovery fails before jest starts. CONTAINS used to strip a hand-added
+ *         build step; a branch on the repo's own package.json keeps it (rule.avoid.runtime-forks)
+ */
+export const contents: FileContentsFunction = async (context) => {
+  // grab the declared package.json
+  const declared = await readFile({ filePath: `${__dirname}/package.json` });
+
+  // read the repo's own package.json, if any, to see whether it self-links
+  const repoPackageJson = getFileTextOrNull({
+    root: context.getProjectRootDirectory(),
+    relativePath: 'package.json',
+  });
+  const isSelfLinked =
+    repoPackageJson !== null &&
+    hasSelfLinkDep({ packageJson: repoPackageJson });
+
+  // a self-linked repo builds before it inits
+  return isSelfLinked
+    ? declared.replace(
+        '"prepare:rhachet": "rhachet init ',
+        '"prepare:rhachet": "npm run build && rhachet init ',
+      )
+    : declared;
+};
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/git/declarations/practices/rhachet/boot-refs-glossary.declapract.integration.test.ts

@@ -0,0 +1,91 @@
+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 drops the deep glossary variants via globs under not, never ref (#689)', () => {
+        expect(contents).toContain(REASON_REF);
+        expect(contents).toContain(EXAMPLE_REF);
+        expect(contents).toMatch(/^ {2}not:\n {4}- briefs\/domain\.terms\/term=\*\._\.choice\.reason\.md$/m);
+        expect(contents).not.toMatch(/^ {2}ref:/m);
+      });
+
+      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/git/declarations/practices/rhachet/boot-yml-findsert.declapract.integration.test.ts

@@ -0,0 +1,149 @@
+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: 'declarations', 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 carries the old practice shape: a declared glob under ref (#689)
+        expect(yaml.parse(before).briefs.ref).toContain(REASON_REF);
+        // 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 landed under not (#689) — the one the old
+          // practice shape put under ref was moved, never duplicated
+          expect(parsed.briefs.not).toEqual([REASON_REF, EXAMPLE_REF]);
+          expect(parsed.briefs.ref).not.toContain(REASON_REF);
+          expect(parsed.briefs.ref).not.toContain(EXAMPLE_REF);
+          // the consumer's OWN ref pick survives, and is all that ref holds now
+          expect(parsed.briefs.ref).toEqual(['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: 'declarations', 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/git/declarations/practices/rhachet/keyrack-yml-findsert.declapract.integration.test.ts

@@ -0,0 +1,105 @@
+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, useBeforeAll, when } from 'test-fns';
+
+// executeApply evaluates the whole usecase, so widen the jest budget
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the usecase-aware keyrack.yml findsert (#491, #487)
+ * .why  = the unit grain proves check/fix in memory; only executeApply proves declapract matches
+ *         `.agent/keyrack.yml`, feeds the aws practice into context.projectPractices, and writes the
+ *         upgrade into a real repo file — and that a second apply is a no-op
+ * .note = filter by `file` only, never `practice`: a practice filter narrows projectPractices and
+ *         would silence the aws branch
+ */
+describe('rhachet — keyrack.yml AWS_PROFILE findsert', () => {
+  const keyrackPath = '.agent/keyrack.yml';
+  const DECLARED = {
+    key: 'AWS_PROFILE',
+    'is-optional-if-has': 'AWS_ACCESS_KEY_ID',
+  };
+
+  given('[case1] an aws repo whose keyrack.yml holds a bare AWS_PROFILE', () => {
+    const tempDir = genTempDir({
+      slug: 'rhachet-keyrack-aws',
+      clone: './src/practices/rhachet/.test/assets/repo-keyrack-extant',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/rhachet/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+      const read = () => fs.readFile(path.join(tempDir, keyrackPath), 'utf-8');
+      const before = await read();
+      await executeApply({ config, file: keyrackPath });
+      const after1 = await read();
+      await executeApply({ config, file: keyrackPath });
+      const after2 = await read();
+      return { before, after1, after2 };
+    }, 170_000);
+
+    when('[t0] the rhachet practice is applied', () => {
+      then('the bare AWS_PROFILE is upgraded in place to is-optional-if-has', () => {
+        const parsed = yaml.parse(state.after1);
+        expect(parsed['env.test']).toEqual([DECLARED]);
+        expect(parsed['env.all']).toBeUndefined();
+      });
+
+      then("the repo's own keys, extends, and comment survive", () => {
+        const parsed = yaml.parse(state.after1);
+        expect(parsed['env.prep']).toEqual(['OPENROUTER_API_KEY']);
+        expect(parsed.extends).toEqual([
+          '.agent/repo=ehmpathy/role=mechanic/keyrack.yml',
+        ]);
+        expect(state.after1).toContain(
+          '# the local aws login, from before is-optional-if-has',
+        );
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(state.before).toMatchSnapshot('keyrack.yml — before');
+        expect(state.after1).toMatchSnapshot('keyrack.yml — after');
+      });
+    });
+
+    when('[t1] the practice is applied a second time', () => {
+      then('the second apply is a no-op', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
+
+  given('[case2] the same repo with no aws practice in its usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'rhachet-keyrack-node',
+      clone: './src/practices/rhachet/.test/assets/repo-keyrack-extant',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/rhachet/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const state = useBeforeAll(async () => {
+      const read = () => fs.readFile(path.join(tempDir, keyrackPath), 'utf-8');
+      const before = await read();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.node.yml'),
+        file: keyrackPath,
+      });
+      return { before, after: await read() };
+    }, 170_000);
+
+    when('[t0] the rhachet practice is applied', () => {
+      then('the keyrack.yml is left byte for byte', () => {
+        expect(state.after).toEqual(state.before);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/rhachet/self-link-build-order.declapract.integration.test.ts

@@ -0,0 +1,88 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply evaluates the whole usecase, so widen the jest budget
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the rhachet package.json build order in a self-linked repo (#520)
+ * .why  = a `link:.` repo boots its own roles, whose hooks load from `dist/`, so `prepare:rhachet`
+ *         must build before `rhachet init`. the CONTAINS fix used to strip a hand-added build; now
+ *         the contents fn reads the repo's own package.json and declares the build for a self-link
+ * .note = declapract's CONTAINS fix writes a dep the repo lacks as its raw `@declapract{…}` marker,
+ *         and only the next apply resolves it (ehmpathy/declapract; dream
+ *         `v2026_10_14.reseed.declapract-contains-json-adds-raw-minversion-markers`). so the second
+ *         apply resolves the marker, and the third proves the fixed point. [t0] asserts the marker,
+ *         so the day declapract resolves it in one apply, [t0] reddens and this note retires
+ */
+describe('rhachet — prepare:rhachet builds first in a self-linked repo', () => {
+  given('[case1] a rhachet roles package with a link:. self-dep and no build before init', () => {
+    const tempDir = genTempDir({
+      slug: 'rhachet-self-linked',
+      clone: './src/practices/rhachet/.test/assets/repo-self-linked',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/rhachet/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+      const read = () =>
+        fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+      const before = await read();
+      await executeApply({ config, file: 'package.json' });
+      const after1 = await read();
+      await executeApply({ config, file: 'package.json' });
+      const after2 = await read();
+      await executeApply({ config, file: 'package.json' });
+      const after3 = await read();
+      return { before, after1, after2, after3 };
+    }, 170_000);
+
+    when('[t0] the rhachet practice is applied', () => {
+      then('prepare:rhachet runs npm run build before rhachet init', () => {
+        const commands = JSON.parse(state.after1).scripts;
+        expect(commands['prepare:rhachet']).toMatch(
+          /^npm run build && rhachet init --keys --hooks --roles /,
+        );
+      });
+
+      then('the self-dep and the build command survive', () => {
+        const parsed = JSON.parse(state.after1);
+        expect(parsed.devDependencies['rhachet-roles-demo']).toEqual('link:.');
+        expect(parsed.scripts.build).toEqual('tsc -p ./tsconfig.build.json');
+      });
+
+      then('a dep the repo lacked lands as its raw declapract marker (upstream defect)', () => {
+        expect(JSON.parse(state.after1).devDependencies['rhachet-brains-openrouter']).toMatch(
+          /^@declapract\{check\.minVersion\('[\d.]+'\)\}$/,
+        );
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(state.before).toMatchSnapshot('package.json — before');
+        expect(state.after1).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t1] the practice is applied a second time', () => {
+      then('every raw marker resolves to a version, and the build step is kept', () => {
+        expect(state.after2).not.toContain('@declapract{');
+        expect(JSON.parse(state.after2).scripts['prepare:rhachet']).toMatch(
+          /^npm run build && rhachet init /,
+        );
+        expect(state.after2).toMatchSnapshot('package.json — after the second apply');
+      });
+    });
+
+    when('[t2] the practice is applied a third time', () => {
+      then('the third apply is a no-op', () => {
+        expect(state.after3).toEqual(state.after2);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/tests-any/.test/assets/repo-old-acceptance-utils/blackbox/lambdas/consumeSESEmailEventFromSNS.acceptance.test.ts

@@ -0,0 +1,23 @@
+import { SNSEventRecord, SNSMessage, SNSEvent } from 'aws-lambda';
+
+import { exampleEmailClickEvent } from '../../src/.test/assets/exampleEmailClickEvent';
+import { invokeLambda } from '../_utils/invokeLambda';
+
+describe('consumeSESEmailEventFromSNS', () => {
+  it('should be possible to invoke the lambda', async () => {
+    const exampleSnsEvent: SNSEvent = {
+      Records: [
+        {
+          Sns: {
+            Message: JSON.stringify(exampleEmailClickEvent),
+          } as SNSMessage,
+        } as SNSEventRecord,
+      ],
+    };
+    const response = await invokeLambda({
+      name: 'consumeSESEmailEventFromSNS',
+      data: exampleSnsEvent,
+    });
+    expect(response).toBeDefined();
+  });
+});

package/dist/.test/assets/git/declarations/practices/tests-any/.test/assets/repo-old-acceptance-utils/declapract.use.yml

@@ -0,0 +1,9 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/tests-any-only/declarations
+#         the variables stay: the fix reads projectName from this file for the `which` it emits
+declarations: 'declarations/declapract.declare.yml'
+useCase: tests-any-only
+variables:
+  organizationName: 'test-org'
+  projectName: 'svc-notifications'
+  reviewers:
+    users: ['user1']

package/dist/.test/assets/git/declarations/practices/tests-any/.test/assets/repo-old-acceptance-utils/package.json

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

package/dist/.test/assets/git/declarations/practices/tests-any/.test/assets/repo-old-acceptance-utils-2/blackbox/lambdas/addDecoratedImage.acceptance.test.ts

@@ -0,0 +1,19 @@
+import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';
+
+import { locally } from '../__test_utils__/environment';
+
+describe('addDecoratedImage', () => {
+  it('it should be possible to add a decorated image', async () => {
+    const response = await invokeLambdaForTesting({
+      service: 'svc-images',
+      function: 'addDecoratedImage',
+      locally,
+      event: {
+        url: 'https://some.url',
+        description: 'bo vine at his gig, moooooin the lawn',
+        focalArea: null,
+      },
+    });
+    expect(response.image).toHaveProperty('uuid');
+  });
+});