declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/environments/best-practice/src/utils/environment.ts

@@ -4,5 +4,6 @@ export { getEnvironment };
 
 export const envStatic = getEnvironment.static();
 
-export const stage = envStatic.access;
-export const serviceClientStage = stage === 'prod' ? 'prod' : 'prep';
+// the access (`test | prep | prod`), re-exported flat for convenience. one axis, never a
+// divergent deploy slug.
+export const access = envStatic.access;

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

@@ -0,0 +1,121 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `own-implementation` bad-practice to a catch-all `src` glob (matches at any
+ *         depth), so it catches a consumer's own `UnexpectedCodePathError.ts` no matter which
+ *         directory segment holds it (D48 / #571).
+ * .why  = a declapract declaration's FILENAME is its target glob. the declaration was pinned to the
+ *         literal `src/utils/errors/UnexpectedCodePathError.ts`, so a consumer that keeps its own
+ *         implementation one segment away — `src/domain/errors/…`, `src/errors/…` — was NEVER
+ *         matched, and the bad practice silently never fired. its two kin (`error-fns`,
+ *         `local-error-imports`) already glob every `.ts` at any depth; this holds
+ *         `own-implementation` to the same catch-all so the miss-by-one-segment case cannot recur.
+ * .note = this is an INTEGRATION test by the same rule the kin `domain` walk cites — it reads the
+ *         filesystem (`readdirSync` over the bad-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any test that reads the filesystem in the
+ *         integration suite. it needs no credential and no network; the boundary alone classifies it.
+ */
+
+const BAD_PRACTICES_DIR = `${__dirname}/bad-practices`;
+const CATCH_ALL_PREFIX = 'src/**/';
+
+/**
+ * .what = every declaration path (`*.declapract.ts`, minus tests) under a bad-practice dir, walked
+ *         with node's own readdir
+ */
+const getAllDeclarationPathsUnderDir = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null }).filter(
+    (path) =>
+      /\.declapract\.ts$/.test(path) && !/\.declapract\.test\.ts$/.test(path),
+  );
+
+/**
+ * .what = the CONSUMER target glob a declaration governs, relative to its bad-practice dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix — which, since the
+ *         filename may hold glob segments, IS the target glob declapract matches on.
+ */
+const asConsumerTargetGlob = (input: {
+  absPath: string;
+  badPracticeDir: string;
+}): string =>
+  relative(input.badPracticeDir, input.absPath).replace(/\.declapract\.ts$/, '');
+
+/**
+ * .what = the first path segment of a relative path (the head dir, before the first `/`).
+ * .why  = a pure transformer leaf, named so the composer below reads intent rather than an
+ *         inline positional `.split('/')[0]` a reader must simulate to know which segment lands.
+ */
+const asFirstPathSegment = (input: { relPath: string }): string =>
+  input.relPath.split('/')[0]!;
+
+/**
+ * .what = the bad-practice dir that governs a declaration = its first path segment under
+ *         BAD_PRACTICES_DIR. a declaration's consumer glob is computed relative to this, so the
+ *         `own-implementation/` (etc) segment is stripped before the `src/` check.
+ */
+const asBadPracticeDir = (input: { absPath: string }): string =>
+  `${BAD_PRACTICES_DIR}/${asFirstPathSegment({
+    relPath: relative(BAD_PRACTICES_DIR, input.absPath),
+  })}`;
+
+describe('errors practice — catch-all glob paths (D48 clamp)', () => {
+  given('[case1] the `own-implementation` bad-practice', () => {
+    const badPracticeDir = `${BAD_PRACTICES_DIR}/own-implementation`;
+    const scene = useBeforeAll(() => ({
+      targetGlobs: getAllDeclarationPathsUnderDir({ dir: badPracticeDir }).map(
+        (absPath) => asConsumerTargetGlob({ absPath, badPracticeDir }),
+      ),
+    }));
+
+    when('[t0] its declared consumer target globs are gathered', () => {
+      then('it governs UnexpectedCodePathError.ts under a catch-all src glob at any depth', () => {
+        // teeth: the pre-fix declaration at `src/utils/errors/UnexpectedCodePathError.ts.declapract.ts`
+        // governs the literal `src/utils/errors/UnexpectedCodePathError.ts` — no catch-all segment —
+        // so a revert to the pinned path reddens this assertion.
+        expect(scene.targetGlobs).toContain(
+          `${CATCH_ALL_PREFIX}UnexpectedCodePathError.ts`,
+        );
+      });
+
+      then('no declaration pins the file to a fixed intermediate segment', () => {
+        // every declaration under this bad-practice that governs a src-tree file must glob at any
+        // depth; a fixed intermediate dir (e.g. `src/utils/errors/…`) is the miss-by-one-segment
+        // defect D48 names.
+        const pinnedToFixedSegment = scene.targetGlobs.filter(
+          (glob) => glob.startsWith('src/') && !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(pinnedToFixedSegment).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] every error bad-practice that governs a src-tree file', () => {
+    const scene = useBeforeAll(() => ({
+      // gather the src-tree target globs across ALL error bad-practices, so the catch-all
+      // convention is held for the whole practice, not just `own-implementation`. each
+      // declaration's bad-practice dir is its first path segment under BAD_PRACTICES_DIR, so the
+      // consumer glob is computed relative to the practice that governs it.
+      srcTargetGlobs: getAllDeclarationPathsUnderDir({ dir: BAD_PRACTICES_DIR })
+        .map((absPath) =>
+          asConsumerTargetGlob({
+            absPath,
+            badPracticeDir: asBadPracticeDir({ absPath }),
+          }),
+        )
+        .filter((glob) => glob.startsWith('src/')),
+    }));
+
+    when('[t0] their consumer target globs are gathered', () => {
+      then('every src-tree declaration globs at any depth', () => {
+        const notCatchAll = scene.srcTargetGlobs.filter(
+          (glob) => !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(notCatchAll).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practices/errors/bad-practices/own-implementation/src/<star><star>/UnexpectedCodePathError.ts.declapract.ts

@@ -0,0 +1,8 @@
+import { FileCheckType } from 'declapract';
+
+// the declaration path is a catch-all glob (`src/**/UnexpectedCodePathError.ts`), not the
+// literal `src/utils/errors/UnexpectedCodePathError.ts`. a consumer's own implementation one
+// directory segment away (e.g. `src/domain/errors/UnexpectedCodePathError.ts`) must still be
+// caught — a literal path silently passes the miss-by-one-segment case, so the own-implementation
+// bad practice would never fire for it.
+export const check = FileCheckType.EXISTS;

package/dist/practices/errors/best-practice/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "helpful-errors": "@declapract{check.minVersion('1.7.3')}"
+    "helpful-errors": "@declapract{check.minVersion('1.7.5')}"
   }
 }

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

@@ -0,0 +1,131 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = pipeline test for the usecase-aware format package.json `contents` fn (r001.b3)
+ * .why  = a unit test proves the `contents` fn in isolation against a mocked context; only the
+ *         real executeApply pipeline proves that declapract:
+ *         - matches the package.json declaration to the consumer's package.json
+ *         - feeds context.projectPractices with the terraform signal derived through a REAL usecase
+ *           (terraform-common present vs absent), NOT a hand-built context object
+ *         - emits the chained fix:format / test:format the branch builds, into the file on disk
+ *         per rule.require.declapract-integration-tests, a usecase-aware `contents` fn that silently
+ *         changes what a consumer receives owes an executeApply pipeline test, not a unit test alone.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads the filesystem + runs
+ *         executeApply against a temp clone. no credential, no network. the fixtures live under a
+ *         `.test` dot-dir (excluded from tsconfig/jest globs); a lean declarations mirror symlinks
+ *         only format + terraform-common so the whole-usecase compile does not blow the hook timeout.
+ * .note = the confound: terraform-common's OWN package.json also declares a standalone
+ *         `fix:format:terraform` command, so a bare "contains fix:format:terraform" assertion could
+ *         not isolate the format branch. the DISTINGUISHING signal for format's branch is the
+ *         CHAINED `fix:format` value (`... && npm run fix:format:terraform`), which only format emits.
+ *         so every assertion reads the `fix:format` chain value, never the standalone key.
+ * .teeth = with-terraform: the emitted `fix:format` chain MUST include the terraform sub-command —
+ *          a revert of the branch to biome-only reddens it. without-terraform: the chain MUST be
+ *          biome-only — a branch that fired on the wrong (absent) signal reddens it.
+ */
+describe('format practice — the usecase-aware package.json contents fn (r001.b3)', () => {
+  const readCommands = async (
+    tempDir: string,
+  ): Promise<Record<string, string>> => {
+    const raw = await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+    return JSON.parse(raw).scripts as Record<string, string>;
+  };
+
+  given('[case1] a consumer on a terraform usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'format-pkgjson-with-terraform',
+      clone: './src/.test/assets/format/repo-with-terraform',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/format/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    // useBeforeAll RETURNS the captured reads (no in-place mutation of a shared const).
+    // .note = filter by file ONLY, never by practice. the practice filter narrows
+    //         projectPractices too (getDesiredPractices), which would strip terraform-common
+    //         and silence the branch. file-only keeps every usecase practice in projectPractices
+    //         while it applies just the package.json plan.
+    const commands = useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+      return readCommands(tempDir);
+    }, 170_000);
+
+    when('[t0] the format package.json is applied', () => {
+      then('the fix:format chain includes the terraform sub-command', () => {
+        expect(commands['fix:format']).toContain('npm run fix:format:terraform');
+      });
+
+      then('the fix:format chain still leads with biome', () => {
+        expect(commands['fix:format']).toContain('npm run fix:format:biome');
+      });
+
+      then('the test:format chain includes the terraform sub-command', () => {
+        expect(commands['test:format']).toContain(
+          'npm run test:format:terraform',
+        );
+      });
+
+      then('the emitted commands block matches snapshot', () => {
+        expect(commands).toMatchSnapshot('with-terraform — commands');
+      });
+    });
+  });
+
+  given('[case2] a consumer on a non-terraform usecase', () => {
+    const tempDir = genTempDir({
+      slug: 'format-pkgjson-without-terraform',
+      clone: './src/.test/assets/format/repo-without-terraform',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/format/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const commands = useBeforeAll(async () => {
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+      return readCommands(tempDir);
+    }, 170_000);
+
+    when('[t0] the format package.json is applied', () => {
+      then('the fix:format chain is biome-only', () => {
+        expect(commands['fix:format']).toEqual('npm run fix:format:biome');
+      });
+
+      then('the fix:format chain omits the terraform sub-command (the teeth)', () => {
+        expect(commands['fix:format']).not.toContain(
+          'npm run fix:format:terraform',
+        );
+      });
+
+      then('the test:format chain omits the terraform sub-command', () => {
+        expect(commands['test:format']).not.toContain(
+          'npm run test:format:terraform',
+        );
+      });
+
+      then('the emitted commands block matches snapshot', () => {
+        expect(commands).toMatchSnapshot('without-terraform — commands');
+      });
+    });
+  });
+});

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

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`format practice — the usecase-aware package.json contents fn (r001.b3) given: [case1] a consumer on a terraform usecase when: [t0] the format package.json is applied then: the emitted commands block matches snapshot: with-terraform — commands 1`] = `
+{
+  "fix:format": "npm run fix:format:biome && npm run fix:format:terraform",
+  "fix:format:terraform": "terraform fmt -recursive provision",
+  "test:format": "npm run test:format:biome && npm run test:format:terraform",
+  "test:format:terraform": "terraform fmt -recursive -check provision",
+}
+`;
+
+exports[`format practice — the usecase-aware package.json contents fn (r001.b3) given: [case2] a consumer on a non-terraform usecase when: [t0] the format package.json is applied then: the emitted commands block matches snapshot: without-terraform — commands 1`] = `
+{
+  "fix:format": "npm run fix:format:biome",
+  "test:format": "npm run test:format:biome",
+}
+`;

package/dist/practices/format/bad-practices/prettier/prettier.config.js.declapract.ts

@@ -3,6 +3,6 @@ import { FileCheckType, type FileFixFunction } from 'declapract';
 export const check = FileCheckType.EXISTS;
 
 export const fix: FileFixFunction = () => {
-  // Remove the file by returning null contents
+  // remove the file: a null contents result deletes it
   return { contents: null };
 };

package/dist/practices/format/best-practice/package.json.declapract.ts

@@ -1,29 +1,47 @@
 import { FileCheckType, type FileContentsFunction } from 'declapract';
 import { isPresent } from 'type-fns';
 
+/**
+ * .what = the active formatter set for a repo — `biome` always, `terraform` only when a terraform
+ *         practice is in use.
+ * .why  = names the set derivation as one intent, so `contents` reads what-not-how rather than an
+ *         inline conditional-null-in-array + filter pipeline a reader must mentally simulate
+ *         (`rule.forbid.inline-decode-friction`).
+ */
+const asActiveFormatters = (input: { usesTerraform: boolean }): string[] =>
+  ['biome', input.usesTerraform ? 'terraform' : null].filter(isPresent);
+
+/**
+ * .what = build the `fix:format` / `test:format` npm commands from the active formatter list — each
+ *         a ` && `-joined chain of per-formatter sub-commands.
+ * .why  = names the derivation as one intent, so `contents` reads what-not-how rather than an
+ *         inline filter/map/join pipeline a reader must mentally simulate (`rule.require.named-transformers`).
+ */
+const asFormatScripts = (input: {
+  formatters: string[];
+}): Record<string, string> => ({
+  'fix:format': input.formatters
+    .map((formatter) => `npm run fix:format:${formatter}`)
+    .join(' && '),
+  'test:format': input.formatters
+    .map((formatter) => `npm run test:format:${formatter}`)
+    .join(' && '),
+});
+
 /**
  * declare the expected contents
  */
 export const contents: FileContentsFunction = (context) => {
-  const formatters = [
-    'biome',
-    context.projectPractices.includes('terraform') ? 'terraform' : null, // only include the terraform formatter if terraform practice is used
-  ].filter(isPresent);
+  // only include the terraform formatter if a terraform practice is in use.
+  // the practices are named `terraform-common` / `terraform-aws` (see useCases.yml) —
+  // a check for the bare `terraform` matches NO practice, so the formatter would never run.
+  const usesTerraform =
+    context.projectPractices.includes('terraform-common') ||
+    context.projectPractices.includes('terraform-aws');
+
+  const formatters = asActiveFormatters({ usesTerraform });
 
-  return JSON.stringify(
-    {
-      scripts: {
-        'fix:format': formatters
-          .map((formatter) => `npm run fix:format:${formatter}`)
-          .join(' && '),
-        'test:format': formatters
-          .map((formatter) => `npm run test:format:${formatter}`)
-          .join(' && '),
-      },
-    },
-    null,
-    2,
-  );
+  return JSON.stringify({ scripts: asFormatScripts({ formatters }) }, null, 2);
 };
 
 /**

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

@@ -5,7 +5,10 @@ import path from 'node:path';
 import { executeApply } from 'declapract';
 import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
 
-import { check as checkOfRhachet } from '../rhachet/best-practice/.gitignore.declapract';
+import {
+  check as checkOfRhachet,
+  fix as fixOfRhachet,
+} from '../rhachet/best-practice/.gitignore.declapract';
 import { check as checkOfGit } from './best-practice/.gitignore.declapract';
 
 // executeApply is slow (90+ seconds per invocation due to full practice evaluation)
@@ -305,14 +308,61 @@ describe('gitignore practices', () => {
        *         if that ever drifts, `declapract fix` rewrites the file on every run,
        *         forever -- and a hoisted negation turns inert, which silently
        *         un-ignores the test-fixture node_modules the tail exists to protect.
+       * .note = rhachet is DISJOINT from git, not a subset, so a rhachet apply on top of
+       *         git's output ADDS its own line(s) rather than a no-op. this test asserts
+       *         only that git's lines SURVIVE the second declarer -- the settle/no-loss
+       *         property. it does NOT name rhachet's specific line: that line is rhachet's
+       *         to own and assert (its own unit suite + snapshot do), and a git test that
+       *         pinned it would reach across the practice boundary
+       *         (rule.require.entool-requests-as-practices -- the practice that creates an
+       *         artifact declares and asserts it). the full settled artifact, both
+       *         practices' lines included, is the `[t3]` snapshot.
        */
-      then('the file is byte-identical -- the practices converge', async () => {
+      then('the second declarer preserves every git line', async () => {
         const contentsAfterRhachet = await fs.readFile(
           path.join(tempDir, '.gitignore'),
           'utf-8',
         );
 
-        expect(contentsAfterRhachet).toEqual(fileBefore.contents);
+        // every line git emitted survives the second declarer -- no loss
+        fileBefore.contents
+          .split('\n')
+          .filter((line) => line)
+          .forEach((line) => expect(contentsAfterRhachet).toContain(line));
+      });
+
+      /**
+       * .what = the settled file is EXACTLY rhachet's fix of git's output -- so the
+       *         second declarer adds no line but what it declares, and reorders none
+       * .why  = the survival loop above proves no git line is LOST, but a per-line
+       *         `toContain` is blind to two things: a reorder of the lines, and an
+       *         extraneous line appended beyond the union. this strict form closes both
+       *         -- the bytes on disk must equal what rhachet's own `fix` emits from
+       *         git's output, whole and in order.
+       * .note = the expectation is DERIVED from rhachet's own declaration (`fixOfRhachet`),
+       *         never a literal copied here -- so rhachet still owns and declares its line
+       *         (`rule.require.entool-requests-as-practices` holds), while the git test
+       *         still proves the second declarer emits no line but what it declares. a
+       *         `toEqual(fileBefore.contents)` would be WRONG: rhachet legitimately unions
+       *         its own `.agent/.cache/` line in, so the file GAINS a line -- deriving the
+       *         expectation THROUGH rhachet's fix accounts for exactly that gain.
+       * .note = the pipeline writes through `writeFileAsync`, which rewrites the final
+       *         newline (`content.replace(/\n$/, '') + '\n'` -- the seam `[t3]` names), so
+       *         both sides are compared with that one final newline stripped.
+       */
+      then("the settled file is exactly rhachet's fix of git's output", async () => {
+        const contentsAfterRhachet = await fs.readFile(
+          path.join(tempDir, '.gitignore'),
+          'utf-8',
+        );
+
+        const expected =
+          (await fixOfRhachet(fileBefore.contents, {} as any)).contents ?? '';
+
+        // strip the one final newline the pipeline's writeFileAsync rewrites
+        const asStripped = (value: string): string => value.replace(/\n$/, '');
+
+        expect(asStripped(contentsAfterRhachet)).toEqual(asStripped(expected));
       });
 
       then('both cache paths are still ignored', () => {
@@ -334,9 +384,10 @@ describe('gitignore practices', () => {
        *         different input -- one already full of git's 17 lines, rather than the
        *         3-line file `[case2]` hands it. a union or tail defect can behave
        *         differently on that input, and this is the only place it is reachable.
-       * .note = `the practices converge` would go red too, but only as a DISAGREEMENT
-       *         between the two declarers. a reader who saw that alone would look at
-       *         the ordered tail, not at lost lines. these name the actual loss.
+       * .note = `the second declarer preserves every git line` covers the gross no-loss,
+       *         but these name the SPECIFIC union/tail guarantees -- a repo's own custom
+       *         line, no duplicate, a live negation -- each of which a defect could break
+       *         while the gross no-loss still held.
        */
       then("the repo's own custom ignores survive the second apply", () => {
         expect(fileAfterRhachet.lines).toContain('.idea');

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

@@ -16,6 +16,7 @@ exports[`gitignore practices given: [case1] a repo whose .gitignore lacks both c
 .agent/.cache/
 .artifact
 .cache/
+.claude/scheduled_tasks*
 .env
 .idea
 .log/slowtest/
@@ -42,6 +43,7 @@ node_modules
 
 exports[`gitignore practices given: [case2] a repo whose use case has rhachet but NOT git when: [t1] the rhachet practice is applied then: the settled file matches snapshot: .gitignore -- rhachet only 1`] = `
 ".agent/.cache/
+.claude/scheduled_tasks*
 .idea
 dist
 node_modules

package/dist/practices/git/best-practice/.gitattributes.declapract.ts

@@ -53,41 +53,56 @@ const ALL_PRIOR_ENTRIES = SECTIONS.flatMap((s) => s.entries.priors);
  */
 const ALL_PRIOR_HEADERS = SECTIONS.flatMap((s) => s.header.priors);
 
+/**
+ * .what = drops prior headers + prior entries, and dedupes latest entries (keep first)
+ * .why = the fix must not re-emit a legacy line, nor a second copy of a managed entry;
+ *        a named transform keeps cleanContent a narrative of what happens, not how
+ */
+const asLinesWithLegacyDroppedAndDeduped = (input: {
+  lines: string[];
+}): string[] => {
+  const { lines } = input.lines.reduce<{
+    lines: string[];
+    seen: Set<string>;
+  }>(
+    (acc, line) => {
+      const trimmed = line.trim();
+
+      // skip prior headers + prior entries
+      if (ALL_PRIOR_HEADERS.includes(trimmed)) return acc;
+      if (ALL_PRIOR_ENTRIES.includes(trimmed)) return acc;
+
+      // skip duplicate latest entries (keep first occurrence)
+      if (ALL_LATEST_ENTRIES.includes(trimmed)) {
+        if (acc.seen.has(trimmed)) return acc;
+        return {
+          lines: [...acc.lines, line],
+          seen: new Set([...acc.seen, trimmed]),
+        };
+      }
+
+      return { lines: [...acc.lines, line], seen: acc.seen };
+    },
+    { lines: [], seen: new Set<string>() },
+  );
+  return lines;
+};
+
 /**
  * removes legacy headers, duplicate entries, and cleans up empty lines
  */
 const cleanContent = (content: string): string => {
-  const lines = content.split('\n');
-  const seenEntries = new Set<string>();
-  const cleanedLines: string[] = [];
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // skip prior headers
-    if (ALL_PRIOR_HEADERS.includes(trimmed)) continue;
+  // drop legacy headers, legacy entries, and duplicate latest entries (keep first)
+  const cleanedLines = asLinesWithLegacyDroppedAndDeduped({
+    lines: content.split('\n'),
+  });
 
-    // skip prior entries
-    if (ALL_PRIOR_ENTRIES.includes(trimmed)) continue;
-
-    // skip duplicate latest entries (keep first occurrence)
-    if (ALL_LATEST_ENTRIES.includes(trimmed)) {
-      if (seenEntries.has(trimmed)) continue;
-      seenEntries.add(trimmed);
-    }
-
-    cleanedLines.push(line);
-  }
-
-  // collapse multiple consecutive empty lines into one
-  const collapsedLines: string[] = [];
-  let prevWasEmpty = false;
-  for (const line of cleanedLines) {
+  // collapse multiple consecutive empty lines into one (drop an empty that follows an empty)
+  const collapsedLines = cleanedLines.filter((line, index) => {
     const isEmpty = line.trim() === '';
-    if (isEmpty && prevWasEmpty) continue;
-    collapsedLines.push(line);
-    prevWasEmpty = isEmpty;
-  }
+    const prevWasEmpty = index > 0 && cleanedLines[index - 1]!.trim() === '';
+    return !(isEmpty && prevWasEmpty);
+  });
 
   return collapsedLines.join('\n').trim();
 };
@@ -146,14 +161,12 @@ export const fix: FileFixFunction = (contents) => {
     return { contents: allSections + '\n' };
   }
 
-  // clean up legacy headers and duplicates first
-  let result = cleanContent(contents);
-
-  // ensure each section exists
-  for (const section of SECTIONS) {
-    result = ensureSection(result, section);
-  }
+  // clean up legacy headers and duplicates, then ensure each section exists
+  const result = SECTIONS.reduce(
+    (acc, section) => ensureSection(acc, section),
+    cleanContent(contents),
+  );
 
-  // normalize to exactly one final newline
+  // trim to exactly one final newline
   return { contents: result.trimEnd() + '\n' };
 };

package/dist/practices/git/best-practice/.gitignore.declapract.ts

@@ -30,6 +30,14 @@ import { defineExpectedGitignoreContents } from '../../../utils/defineExpectedGi
  *         place. `readonly` forbids that mutation outright rather than merely discourages it
  *         (`rule.prefer.prevent-over-correct`), so the source may group lines by what they are
  *         for, with their comments beside them, and the one sort that matters stays in one place.
+ *
+ * .note = every line here governs an UNTRACKED path only. git consults `.gitignore` for a path
+ *         not yet in the index; a path a consumer ALREADY tracks stays tracked, and this
+ *         declaration cannot reach the index to reconcile it (the `fix` is a pure contents
+ *         transform, so it has no seam to the index). so a consumer that committed a match
+ *         BEFORE this practice declared the pattern keeps it committed, silently, behind a line
+ *         that reads as enforcement. to reconcile an extant match, run `git rm --cached <path>`
+ *         by hand. a loud in-consumer report of that case is a proposed follow-on (#582).
  */
 const ignoresSortable: readonly string[] = [
   '*.log',

package/dist/practices/husky/__snapshots__/check.timestamps.play.declapract.integration.test.ts.snap

@@ -0,0 +1,7 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`check.timestamps guard given: [case1] a non-code file with an iso timestamp when: [t0] the guard runs then: the verbatim halt output matches snapshot: check.timestamps halt output 1`] = `
+"✋ timestamps are forbidden in snapshots. mask them to prevent permadrift
+   └─ snapshot.json:1:{ "createdAt": "[timestamp]" }
+"
+`;

package/dist/practices/husky/best-practice/.husky/check.timestamps.sh

@@ -13,6 +13,13 @@ set -eu
 # the timestamp pattern: optional lead T, HH:MM:SS, optional timezone (Z, ±HH:MM, ±HHMM)
 TIMESTAMP_PATTERN='T?[0-9][0-9]:[0-9][0-9]:[0-9][0-9](Z|[+-][0-9][0-9]:?[0-9][0-9])?'
 
+# an iso-8601 DURATION is a fixed span, not an instant, so it cannot permadrift — it is a
+# valid, stable value to assert on. a duration carries a lead `P` designator and a `T` with
+# NO date part (PT12:30:00, P1DT02:15:30, P3Y6M4DT12:30:05), unlike a stamp
+# (2026-08-08T14:30:00Z). strip durations before the timestamp scan, so a duration-only line
+# falls through and a line with a real stamp still halts (the stamp survives the strip).
+DURATION_PATTERN='P([0-9]+[YMWD])*T([0-9]+[HMS])*[0-9][0-9]:[0-9][0-9]:[0-9][0-9]'
+
 # collect staged files (added/copied/modified); skip deletions
 staged=$(git diff --cached --name-only --diff-filter=ACM)
 
@@ -36,8 +43,10 @@ while IFS= read -r file; do
     exit 1
   fi
 
-  # halt if the staged content embeds a raw timestamp
-  match=$(printf '%s\n' "$content" | grep -nIE "$TIMESTAMP_PATTERN" | head -n 1)
+  # halt if the staged content embeds a raw timestamp. strip iso durations first (sed is
+  # line-by-line, so line numbers are preserved): a duration-only line loses its HH:MM:SS run
+  # and falls through; a line that also holds a real stamp still matches (the stamp wins)
+  match=$(printf '%s\n' "$content" | sed -E "s/$DURATION_PATTERN//g" | grep -nIE "$TIMESTAMP_PATTERN" | head -n 1)
   if [ -n "$match" ]; then
     printf '✋ timestamps are forbidden in snapshots. mask them to prevent permadrift\n'
     printf '   └─ %s:%s\n' "$file" "$match"