declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/.test/assets/repo-self-linked/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "rhachet-roles-demo",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "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"
+  },
+  "devDependencies": {
+    "rhachet": "1.49.2",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "0.1.6",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.34.1",
+    "rhachet-roles-bhrowser": "0.1.0",
+    "rhachet-roles-bhuild": "0.21.36",
+    "rhachet-roles-demo": "link:.",
+    "rhachet-roles-ehmpathy": "1.38.12",
+    "rhachet-roles-ghlitch": "0.3.0",
+    "rhachet-roles-rhachet": "0.1.7"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/__snapshots__/.declapract.integration.test.ts.snap

@@ -25,14 +25,15 @@ exports[`rhachet/prod-deps relocation given: [case1] a repo with rhachet + a rha
   },
   "devDependencies": {
     "jest": "29.3.1",
-    "rhachet": "1.47.5",
+    "rhachet": "1.49.2",
     "rhachet-brains-anthropic": "0.4.3",
-    "rhachet-brains-fireworksai": "@declapract{check.minVersion('0.1.6')}",
+    "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.34.1')}",
+    "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.21.36')}",
-    "rhachet-roles-ehmpathy": "@declapract{check.minVersion('1.38.12')}",
+    "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')}"
   },

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

@@ -8,6 +8,8 @@ briefs:
     - briefs/my-own-brief.md
   ref:
     - briefs/my-own-deep-variant.md
+    # the old practice shape put this declared glob under ref; the fix moves it to not (#689)
+    - briefs/domain.terms/term=*._.choice.reason.md
 "
 `;
 
@@ -19,8 +21,12 @@ briefs:
     - briefs/my-own-brief.md
   ref:
     - briefs/my-own-deep-variant.md
+  not:
     - briefs/domain.terms/term=*._.choice.reason.md
     - briefs/domain.terms/term=*._.choice.example=*.md
+# 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
 "

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

@@ -0,0 +1,28 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`rhachet — keyrack.yml AWS_PROFILE findsert given: [case1] an aws repo whose keyrack.yml holds a bare AWS_PROFILE when: [t0] the rhachet practice is applied then: the before + after contents match snapshot: keyrack.yml — after 1`] = `
+"org: ehmpathy
+extends:
+  - .agent/repo=ehmpathy/role=mechanic/keyrack.yml
+env.prod: null
+env.prep:
+  - OPENROUTER_API_KEY
+env.test:
+  # the local aws login, from before is-optional-if-has
+  - key: AWS_PROFILE
+    is-optional-if-has: AWS_ACCESS_KEY_ID
+"
+`;
+
+exports[`rhachet — keyrack.yml AWS_PROFILE findsert given: [case1] an aws repo whose keyrack.yml holds a bare AWS_PROFILE when: [t0] the rhachet practice is applied then: the before + after contents match snapshot: keyrack.yml — before 1`] = `
+"org: ehmpathy
+extends:
+  - .agent/repo=ehmpathy/role=mechanic/keyrack.yml
+env.prod: null
+env.prep:
+  - OPENROUTER_API_KEY
+env.test:
+  # the local aws login, from before is-optional-if-has
+  - AWS_PROFILE
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/__snapshots__/self-link-build-order.declapract.integration.test.ts.snap

@@ -0,0 +1,81 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`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 when: [t0] the rhachet practice is applied then: the before + after contents match snapshot: package.json — after 1`] = `
+"{
+  "name": "rhachet-roles-demo",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "prepare:rhachet": "npm run build && 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"
+  },
+  "devDependencies": {
+    "rhachet": "1.49.2",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "0.2.3",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.40.0",
+    "rhachet-roles-bhrowser": "0.1.0",
+    "rhachet-roles-bhuild": "0.23.2",
+    "rhachet-roles-demo": "link:.",
+    "rhachet-roles-ehmpathy": "1.39.5",
+    "rhachet-roles-ghlitch": "0.3.0",
+    "rhachet-roles-rhachet": "0.1.7",
+    "rhachet-brains-openrouter": "@declapract{check.minVersion('0.1.3')}"
+  }
+}
+"
+`;
+
+exports[`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 when: [t0] the rhachet practice is applied then: the before + after contents match snapshot: package.json — before 1`] = `
+"{
+  "name": "rhachet-roles-demo",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "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"
+  },
+  "devDependencies": {
+    "rhachet": "1.49.2",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "0.1.6",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.34.1",
+    "rhachet-roles-bhrowser": "0.1.0",
+    "rhachet-roles-bhuild": "0.21.36",
+    "rhachet-roles-demo": "link:.",
+    "rhachet-roles-ehmpathy": "1.38.12",
+    "rhachet-roles-ghlitch": "0.3.0",
+    "rhachet-roles-rhachet": "0.1.7"
+  }
+}
+"
+`;
+
+exports[`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 when: [t1] the practice is applied a second time then: every raw marker resolves to a version, and the build step is kept: package.json — after the second apply 1`] = `
+"{
+  "name": "rhachet-roles-demo",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc -p ./tsconfig.build.json",
+    "prepare:rhachet": "npm run build && 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"
+  },
+  "devDependencies": {
+    "rhachet": "1.49.2",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "0.2.3",
+    "rhachet-brains-xai": "0.3.3",
+    "rhachet-roles-bhrain": "0.40.0",
+    "rhachet-roles-bhrowser": "0.1.0",
+    "rhachet-roles-bhuild": "0.23.2",
+    "rhachet-roles-demo": "link:.",
+    "rhachet-roles-ehmpathy": "1.39.5",
+    "rhachet-roles-ghlitch": "0.3.0",
+    "rhachet-roles-rhachet": "0.1.7",
+    "rhachet-brains-openrouter": "0.1.3"
+  }
+}
+"
+`;

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

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

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

@@ -1,3 +1,143 @@
-import { FileCheckType } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
 
-export const check = FileCheckType.EXISTS;
+/**
+ * .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/expo-fullusecase/declarations/practices/rhachet/best-practice/.agent/repo=.this/role=any/boot.yml

@@ -1,46 +1,22 @@
-# boot.yml — curate which briefs load into context at each session boot.
+# 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
 #
-# 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)
+# 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`.
 #
-# 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.
+# an upgrade keeps your own entries and budget; it only adds the `not` globs below.
 
-# 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 = 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:
-  ref:
+  not:
     - briefs/domain.terms/term=*._.choice.reason.md
     - briefs/domain.terms/term=*._.choice.example=*.md

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

@@ -4,13 +4,12 @@ import expect from 'expect';
 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.
+ * .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 declaredRefGlobs: readonly string[] = [
+const declaredNotGlobs: readonly string[] = [
   'briefs/domain.terms/term=*._.choice.reason.md',
   'briefs/domain.terms/term=*._.choice.example=*.md',
 ];
@@ -21,7 +20,7 @@ const declaredRefGlobs: readonly string[] = [
  *         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.
+ *         so a consumer who deliberately raised or lowered the cap is never reverted (F62).
  */
 const declaredBudgetTokens = 5_000;
 
@@ -30,16 +29,13 @@ const declaredBudgetTokens = 5_000;
  * .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.
+ *         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 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.',
+  ' 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');
 
 /**
@@ -51,48 +47,61 @@ 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.
+ * .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 getCurrentRefGlobs = (doc: yaml.Document): string[] => {
+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 =
-    doc.getIn(['always', 'briefs', 'ref']) ?? doc.getIn(['briefs', 'ref']);
-  if (!node) return [];
+  const node: any = input.doc.getIn(asBriefsLevelPath(input));
+  if (!yaml.isSeq(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.
+ * .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 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 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(['briefs', 'ref'], seq);
+  doc.setIn(path, 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.
+ * .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; without both, `declapract
- *         fix` would rewrite this file forever.
+ *         `fix(fix(x)) === fix(x)` and `check` passes on its own output.
  */
 const defineExpectedContents = (
   contents: string | null,
@@ -101,47 +110,62 @@ const defineExpectedContents = (
   // 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 absentGlobs = declaredRefGlobs.filter(
-    (glob) => !getCurrentRefGlobs(doc).includes(glob),
+  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 (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));
+  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) {
-    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',
+    // .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 }),
     );
-    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.
+ * .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 (globs unioned, budget cap ensured), never the
- *         whole template, so a consumer's own boot entries pass the check untouched.
+ *         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(
@@ -150,10 +174,10 @@ export const check: FileCheckFunction = (contents, context) => {
 };
 
 /**
- * .what = unions the declared ref globs into a consumer's boot.yml and findserts the budget cap (or
- *         writes the template if absent).
+ * .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).
+ *         consumer's own say/ref curation (#105 req 1, #689).
  */
 export const fix: FileFixFunction = (contents, context) => {
   return {