declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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"

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

@@ -62,6 +62,20 @@ describe('check.timestamps guard', () => {
           '   └─ snapshot.json:1:{ "createdAt": "2026-06-25T14:30:00Z" }',
         );
       });
+      then('the verbatim halt output matches snapshot', () => {
+        // user-faced halt message — a reword must redden a vibecheck, not slip past the
+        // toContain asserts above (rule.require.snapshots). the fixture timestamp is a fixed
+        // input (not a live clock), so the output is deterministic.
+        // mask the instant to [timestamp] before the snapshot: the .snap is itself scanned by
+        // this very guard (only .ts/.sh are exempt), so a raw instant here would forbid its own
+        // commit. the raw detail-line toContain above already locks the exact instant in the
+        // output; the snapshot vibechecks the message shape, per the guard's own mask remedy (case8).
+        const masked = result.stdout.replace(
+          /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/g,
+          '[timestamp]',
+        );
+        expect(masked).toMatchSnapshot('check.timestamps halt output');
+      });
     });
   });
 
@@ -145,4 +159,55 @@ describe('check.timestamps guard', () => {
       });
     });
   });
+
+  // #566: an iso-8601 duration is a fixed span, not an instant, so it cannot permadrift —
+  // the matcher must not halt on it (a false positive that trains folks to bypass the hook)
+  given('[case9] a non-code file with a simple iso duration (PT12:30:00)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'fixture.json': '{ "window": "PT12:30:00" }\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case10] a non-code file with a day+time duration (P1DT02:15:30)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'fixture.json': '{ "elapsed": "P1DT02:15:30" }\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case11] a non-code file with a full-designator duration (P3Y6M4DT12:30:05)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'fixture.json': '{ "span": "P3Y6M4DT12:30:05" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case12] a non-code file with BOTH a duration and a real timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'fixture.json':
+          '{ "window": "PT12:30:00", "createdAt": "2026-06-25T14:30:00Z" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it halts with exit 2 (the real stamp wins, despite the duration)', () => {
+        expect(result.code).toEqual(2);
+      });
+    });
+  });
 });

package/dist/practices/lint/__snapshots__/dpdmrc-exclude-policy.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`lint .dpdmrc.yaml exclude policy given: the shipped .dpdmrc.yaml when: the exclude list is read then: the emitted exclude value matches snapshot: dpdmrc exclude value 1`] = `[]`;

package/dist/practices/lint/bad-practices/depcheck-denylisted-ignores/.depcheckrc.yml.declapract.ts

@@ -46,6 +46,10 @@ export const fix: FileFixFunction = (contents) => {
   if (denylistedPresent.length === 0) return { contents };
 
   // Remove denylisted ignores from the document
+  // note = `as any` at an external boundary (the `yaml` library ships no node type for
+  //        `doc.get`, which returns `unknown`). correct type = the library's `YAMLSeq`
+  //        with an `items` array. removal path = when `yaml` exports a typed `get`, or a
+  //        local `isYamlSeq` type-guard narrows the node before the `.items` access.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const ignoresNode = doc.get('ignores') as any;
   if (ignoresNode?.items) {

package/dist/practices/lint/best-practice/.depcheckrc.yml.declapract.ts

@@ -25,17 +25,18 @@ export const fix: FileFixFunction = (contents, context) => {
 
   if (missingIgnores.length === 0) return { contents };
 
-  // Add missing ignores to the document (preserves comments)
+  // get the ignores seq node, seeding an empty seq onto the doc if absent
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let ignoresNode = currentDoc.get('ignores') as any;
-  if (!ignoresNode) {
+  const ignoresNode = ((): any => {
+    const node = currentDoc.get('ignores');
+    if (node) return node;
     currentDoc.set('ignores', []);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ignoresNode = currentDoc.get('ignores') as any;
-  }
-  for (const ignore of missingIgnores) {
-    ignoresNode.add(ignore);
-  }
+    return currentDoc.get('ignores');
+  })();
+
+  // .note = deliberate mutation — the yaml document api mutates the seq node in
+  // place to preserve the surrounding comments; there is no immutable seq-add
+  missingIgnores.forEach((ignore) => ignoresNode.add(ignore));
 
   return { contents: currentDoc.toString() };
 };

package/dist/practices/lint/best-practice/.dpdmrc.yaml

@@ -1,9 +1,13 @@
-# dpdm exclude patterns
-# each entry is joined with | to form a single regex for --exclude
+# dpdm exclude patterns — each entry is joined with | into a single --exclude regex.
 #
-# with --transform flag, type imports are erased before analysis
-# and test files are excluded via glob pattern '!(*.test).ts'
-# so excludes are rarely needed even for devDependencies
+# an empty `exclude: []` means dpdm checks every file for cycles, node_modules included. this is
+# the org policy `rule.forbid.dpdm-exclude-change`: we check dependencies too, because a prod-dep
+# cycle ships to consumers.
 #
-# never exclude prod dependencies — you'd ship cycles to consumers
+# with --transform, type imports are erased before analysis and test files drop via the
+# '!(*.test).ts' glob, so an exclude is rarely needed even for a devDep. a devDep may be added as
+# an escape hatch; a prod dep must not, since that ships cycles.
+#
+# the empty list is the policy — an entry of `node_modules` (or dpdm's own `/node_modules/`
+# default) disables the check across every consumer repo.
 exclude: []