declapract-typescript-ehmpathy 0.49.12 → 0.49.14

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

@@ -0,0 +1,88 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+
+/**
+ * .what = detects rhachet and any rhachet-<family>-* package in production dependencies
+ * .why = these packages should be devDependencies or peerDependencies, never direct prod deps
+ */
+
+// 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: [${PRACTICE}] package.json has no contents to scan for a rhachet(-<family>-*) prod dep`,
+    );
+
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const prodDeps = Object.keys(packageJSON.dependencies ?? {});
+
+  // check if any rhachet package is in prod dependencies
+  const rhachetInProdDeps = prodDeps.some((dep) =>
+    rhachetPackagePattern.test(dep),
+  );
+
+  if (rhachetInProdDeps) return; // matches 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 = asPackageJSON({ contents }, { practice: PRACTICE });
+
+  // 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' in packageJSON ? { dependencies: prodDeps } : {}),
+    ...('devDependencies' in packageJSON || Object.keys(devDeps).length > 0
+      ? { devDependencies: devDeps }
+      : {}),
+  };
+
+  return { contents: JSON.stringify(fixedPackageJSON, null, 2) };
+};

package/dist/.test/assets/rhachet/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/rhachet/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/rhachet/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/rhachet/declarations/practices/rhachet/best-practice/.agent/keyrack.yml.declapract.ts

@@ -0,0 +1,143 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+
+/**
+ * .what = the practices whose presence means the repo reaches aws with local credentials
+ * .why  = such a repo needs AWS_PROFILE on a laptop (#487); a repo with none of them needs no
+ *         aws key at all, so the findsert stays out of its keyrack.yml
+ */
+const AWS_PRACTICES: readonly string[] = [
+  'environments-aws',
+  'node-service',
+  'persist-with-dynamodb',
+  'persist-with-rds',
+  'serverless',
+  'terraform-aws',
+];
+
+/**
+ * .what = the AWS_PROFILE entry this practice declares, in the is-optional-if-has shape (#491)
+ * .why  = a laptop sets AWS_PROFILE; ci sets AWS_ACCESS_KEY_ID via oidc. the key is optional when
+ *         the alternative is present, so `keyrack.source({ mode: strict })` passes in ci too
+ */
+const declaredAwsProfileEntry = {
+  key: 'AWS_PROFILE',
+  'is-optional-if-has': 'AWS_ACCESS_KEY_ID',
+};
+
+/**
+ * .what = whether a keyrack env seq item names AWS_PROFILE, as a bare string or a `key:` map
+ */
+const isAwsProfileItem = (item: unknown): boolean => {
+  if (yaml.isScalar(item)) return item.value === 'AWS_PROFILE';
+  if (yaml.isMap(item)) return item.get('key') === 'AWS_PROFILE';
+  return false;
+};
+
+/**
+ * .what = the `env.*` seq nodes a keyrack.yml declares (env.all, env.test, env.prep, env.prod)
+ */
+const getEnvSeqs = (doc: yaml.Document): yaml.YAMLSeq[] => {
+  if (!yaml.isMap(doc.contents)) return [];
+  return doc.contents.items
+    .filter(
+      (pair) =>
+        yaml.isScalar(pair.key) &&
+        String(pair.key.value).startsWith('env.') &&
+        yaml.isSeq(pair.value),
+    )
+    .map((pair) => pair.value as yaml.YAMLSeq);
+};
+
+/**
+ * .what = the keyrack.yml a repo should hold, given its extant one and its practices
+ * .why  = a FINDSERT, scope-safe (rule.avoid.runtime-forks): it only adds or upgrades the
+ *         AWS_PROFILE entry, never removes a line, so a narrow-scope apply (where the aws signal
+ *         goes dark) leaves a correct file intact
+ *         - no aws practice → the file as it stands
+ *         - a bare `AWS_PROFILE` under any env.* section → upgraded in place to is-optional-if-has
+ *         - AWS_PROFILE absent from every env.* section → added under env.all
+ *         - AWS_PROFILE already a `key:` map → kept as the adopter shaped it
+ * .note = a fixed point: a conformant file is returned verbatim, so fix(fix(x)) === fix(x)
+ */
+const defineExpectedKeyrackContents = (input: {
+  contents: string;
+  projectPractices: string[];
+}): string => {
+  // a repo with no aws practice: no aws key is owed
+  const isAws = input.projectPractices.some((practice) =>
+    AWS_PRACTICES.includes(practice),
+  );
+  if (!isAws) return input.contents;
+
+  // find each AWS_PROFILE entry the repo declares
+  const doc = yaml.parseDocument(input.contents);
+  const envSeqs = getEnvSeqs(doc);
+  const bareEntries = envSeqs.flatMap((seq) =>
+    seq.items
+      .map((item, index) => ({ seq, item, index }))
+      .filter(({ item }) => yaml.isScalar(item) && isAwsProfileItem(item)),
+  );
+  const hasAnyEntry = envSeqs.some((seq) => seq.items.some(isAwsProfileItem));
+
+  // already conformant → the file verbatim (no round-trip)
+  if (hasAnyEntry && bareEntries.length === 0) return input.contents;
+
+  // upgrade each bare entry in place, so its env section and its comment stay put
+  // .note = deliberate mutation — the yaml document api mutates nodes in place to keep comments
+  bareEntries.forEach(({ seq, item, index }) => {
+    const upgraded = doc.createNode(declaredAwsProfileEntry);
+    upgraded.commentBefore = (item as yaml.Scalar).commentBefore;
+    seq.items[index] = upgraded;
+  });
+  if (hasAnyEntry) return doc.toString();
+
+  // absent: add under env.all (seed the seq where env.all is null or absent)
+  const envAll = doc.get('env.all');
+  if (!yaml.isSeq(envAll)) {
+    doc.set('env.all', doc.createNode([declaredAwsProfileEntry]));
+    return doc.toString();
+  }
+  envAll.add(doc.createNode(declaredAwsProfileEntry));
+  return doc.toString();
+};
+
+/**
+ * .what = throws when the repo lacks a keyrack.yml, or an aws repo lacks the AWS_PROFILE entry
+ * .note = best-practice semantics: a THROW means violated (declapract-check-semantics.md)
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  // the file must exist (rhachet init --keys writes it)
+  if (contents === null)
+    throw new ConstraintError('.agent/keyrack.yml is absent', {
+      hint: 'run `npx rhachet init --keys` to create it',
+    });
+
+  // an aws repo must carry AWS_PROFILE in the is-optional-if-has shape
+  const expected = defineExpectedKeyrackContents({
+    contents,
+    projectPractices: context.projectPractices,
+  });
+  if (contents !== expected)
+    throw new ConstraintError(
+      '.agent/keyrack.yml lacks AWS_PROFILE (is-optional-if-has AWS_ACCESS_KEY_ID) for an aws repo',
+      { relativeFilePath: context.relativeFilePath },
+    );
+};
+
+/**
+ * .what = findserts the AWS_PROFILE entry into an aws repo's keyrack.yml (#491, #487)
+ * .note = an absent file is left to `rhachet init --keys` (it knows the org); the fix returns no
+ *         contents for it, which declapract reads as "no automatic fix"
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (contents === null) return {};
+  return {
+    contents: defineExpectedKeyrackContents({
+      contents,
+      projectPractices: context.projectPractices,
+    }),
+  };
+};

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

@@ -0,0 +1,22 @@
+# boot.yml — which briefs load into context at each boot
+#   say = full content, every boot (costs tokens)
+#   ref = path only, read on demand
+#   not = never booted
+#
+# no `say` key = say all, minus `ref` and `not`. a non-empty `say` = say only what it
+# matches, ref all else. `say: []` = ref all. skills curate the same way, via `skills:`.
+# to curate a large corpus, add a `say:` allowlist, e.g. `- briefs/rule.*.md`.
+#
+# an upgrade keeps your own entries and budget; it only adds the `not` globs below.
+
+# budget = the token cap on the say payload; a boot over it halts.
+# to fix a halt: demote a say glob to ref, use a .min brief, or raise the cap.
+# plain `5000`, never `5_000`: yaml 1.2 reads an underscore integer as a string.
+budget:
+  tokens: 5000
+
+# each term's say file names its .reason path, so its variants never boot
+briefs:
+  not:
+    - briefs/domain.terms/term=*._.choice.reason.md
+    - briefs/domain.terms/term=*._.choice.example=*.md

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

@@ -0,0 +1,189 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import expect from 'expect';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+
+/**
+ * .what = the `not` globs this practice declares — the deep glossary variants, dropped from boot.
+ * .why  = each term's say file names its `.reason` path, so a ref line per variant adds no reach and
+ *         costs a path line per term on every boot. `not` drops them. the findsert adds only these
+ *         two globs, never the whole template, so a consumer's own boot entries survive.
+ */
+const declaredNotGlobs: 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 (F62).
+ */
+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 — and it names the boot halt and its remedy.
+ * .note = the yaml serializer prefixes each line with `# `, so a space at the front renders `# budget`.
+ */
+const declaredBudgetComment = [
+  ' budget = the token cap on the say payload; a boot over it halts.',
+  ' to fix a halt: demote a say glob to ref, use a .min brief, or raise the cap.',
+  ' plain `5000`, never `5_000`: yaml 1.2 reads an underscore integer as a string.',
+].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 = true when the consumer curates in the legacy SUBJECT mode (`always.briefs`).
+ * .why  = the findsert writes into whichever mode the consumer already uses, so a subject-mode
+ *         consumer is never corrupted into an invalid mixed `always:` + `briefs:` file.
+ */
+const isSubjectMode = (doc: yaml.Document): boolean =>
+  doc.getIn(['always', 'briefs']) !== undefined;
+
+/**
+ * .what = the key path of a briefs level list (`ref` or `not`) in the consumer's mode.
+ */
+const asBriefsLevelPath = (input: {
+  doc: yaml.Document;
+  level: 'ref' | 'not';
+}): string[] =>
+  isSubjectMode(input.doc)
+    ? ['always', 'briefs', input.level]
+    : ['briefs', input.level];
+
+/**
+ * .what = reads the globs a consumer's boot.yml carries at one level (`ref` or `not`).
+ * .why  = the read half: the union and the move are computed against the consumer's real lists.
+ */
+const getCurrentLevelGlobs = (input: {
+  doc: yaml.Document;
+  level: 'ref' | 'not';
+}): 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 = input.doc.getIn(asBriefsLevelPath(input));
+  if (!yaml.isSeq(node)) return [];
+  return (node.toJSON() as string[] | null) ?? [];
+};
+
+/**
+ * .what = the mutable `not` seq node to union into: the consumer's extant one, or a seeded one.
+ * .why  = a plain [] becomes a js array without the `.add` the union relies on, so seed a real seq.
+ */
+const getOrSeedNotSeq = (doc: yaml.Document): yaml.YAMLSeq => {
+  const path = asBriefsLevelPath({ doc, level: 'not' });
+  const extant = doc.getIn(path);
+  if (yaml.isSeq(extant)) return extant;
+  const seq = new yaml.YAMLSeq();
+  doc.setIn(path, seq);
+  return seq;
+};
+
+/**
+ * .what = the boot.yml a consumer should hold: its extant file with the declared globs under `not`
+ *         (and out of `ref`) and the budget cap findserted, or the whole template where it has none
+ * .why  = a findsert by construction: a glob already under `not` stays there once, a consumer's own
+ *         `ref` entries stay, a budget already set is left as the consumer chose it, and every other
+ *         line (say 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.
+ */
+const defineExpectedContents = (
+  contents: string | null,
+  declaredContents: string,
+): string => {
+  // a fresh consumer (no boot.yml) gets the whole declared template verbatim.
+  if (!contents) return declaredContents;
+
+  // measure what the consumer lacks
+  const doc = yaml.parseDocument(contents);
+  const notGlobs = getCurrentLevelGlobs({ doc, level: 'not' });
+  const refGlobs = getCurrentLevelGlobs({ doc, level: 'ref' });
+  const absentFromNot = declaredNotGlobs.filter(
+    (glob) => !notGlobs.includes(glob),
+  );
+  const strayInRef = declaredNotGlobs.filter((glob) => refGlobs.includes(glob));
+  const budgetAbsent = !hasBudgetTokens(doc);
+
+  // already conformant → return the consumer's file verbatim (no round-trip).
+  if (absentFromNot.length === 0 && strayInRef.length === 0 && !budgetAbsent)
+    return contents;
+
+  // move: drop each declared glob from `ref`; drop the `ref` key if it empties
+  // .note = deliberate mutation — the yaml document api mutates nodes in place to keep comments
+  if (strayInRef.length > 0) {
+    const refPath = asBriefsLevelPath({ doc, level: 'ref' });
+    const refSeq = doc.getIn(refPath) as yaml.YAMLSeq;
+    refSeq.items = refSeq.items.filter(
+      (item) =>
+        !strayInRef.includes(String(yaml.isScalar(item) ? item.value : item)),
+    );
+    if (refSeq.items.length === 0) doc.deleteIn(refPath);
+  }
+
+  // union: add each absent declared glob under `not`
+  if (absentFromNot.length > 0) {
+    const notSeq = getOrSeedNotSeq(doc);
+    absentFromNot.forEach((glob) => notSeq.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) {
+    // .note = a key built via a node (not `setIn`) is a Scalar, which can carry a commentBefore;
+    //         a `setIn`-made key is a bare string and would drop the NOTE in silence
+    if (!yaml.isMap(doc.contents)) doc.contents = doc.createNode({});
+    const budgetKey = doc.createNode('budget');
+    budgetKey.commentBefore = declaredBudgetComment;
+    (doc.contents as yaml.YAMLMap).add(
+      doc.createPair(budgetKey, { tokens: declaredBudgetTokens }),
+    );
+  }
+
+  return doc.toString();
+};
+
+/**
+ * .what = throws when a consumer's boot.yml lacks a declared `not` glob, still lists one under `ref`,
+ *         lacks a budget, or is absent entirely.
+ * .why  = `check` is the GATE: declapract runs `fix` only when `check` rejects.
+ * .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, 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 `not` globs into a consumer's boot.yml (moved out of `ref`) 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, #689).
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  return {
+    contents: defineExpectedContents(
+      contents,
+      context.declaredFileContents ?? '',
+    ),
+  };
+};

package/dist/.test/assets/rhachet/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/rhachet/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/rhachet/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"
+  }
+}