declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/git/best-practice/.gitattributes.declapract.ts

@@ -39,134 +39,60 @@ const SECTIONS: {
 ];
 
 /**
- * all latest entries managed by this practice (for deduplication)
+ * .what = every line this practice manages: each section's header and entries, latest and prior
+ * .why  = the fix lifts each of these out of wherever it sits, so none can linger out of place,
+ *         out of order, or twice
  */
-const ALL_LATEST_ENTRIES = SECTIONS.flatMap((s) => s.entries.latest);
+const ALL_MANAGED_LINES = SECTIONS.flatMap((s) => [
+  s.header.latest,
+  ...s.header.priors,
+  ...s.entries.latest,
+  ...s.entries.priors,
+]);
 
 /**
- * all prior entries that should be removed
+ * .what = the canonical block: each section's latest header + latest entries, in declared order
+ * .why  = the check is CONTAINS — the file must hold the whole template as one contiguous run of
+ *         text — so the fix must emit this block verbatim. a section re-assembled in place (an
+ *         entry inserted after its header, or a stray entry left outside its section) is a fixed
+ *         point that never CONTAINS the template, so the plan would flag the file on every run
  */
-const ALL_PRIOR_ENTRIES = SECTIONS.flatMap((s) => s.entries.priors);
+const CANONICAL_BLOCK = SECTIONS.map((s) =>
+  [s.header.latest, ...s.entries.latest].join('\n'),
+).join('\n\n');
 
 /**
- * all prior headers that should be removed
+ * .what = the repo-own lines of a .gitattributes: every managed line dropped, runs of blank
+ *         lines collapsed to one, and the edges trimmed
+ * .why  = the repo keeps every line this practice does not manage, in its own order
  */
-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>() },
+const asRepoOwnBlock = (input: { contents: string }): string => {
+  // drop every managed line, wherever it sits
+  const linesRepoOwn = input.contents
+    .split('\n')
+    .filter((line) => !ALL_MANAGED_LINES.includes(line.trim()));
+
+  // collapse runs of blank lines into one (drop a blank that follows a blank)
+  const linesCollapsed = linesRepoOwn.filter(
+    (line, index) =>
+      !(
+        line.trim() === '' &&
+        index > 0 &&
+        linesRepoOwn[index - 1]!.trim() === ''
+      ),
   );
-  return lines;
-};
-
-/**
- * removes legacy headers, duplicate entries, and cleans up empty lines
- */
-const cleanContent = (content: string): string => {
-  // drop legacy headers, legacy entries, and duplicate latest entries (keep first)
-  const cleanedLines = asLinesWithLegacyDroppedAndDeduped({
-    lines: content.split('\n'),
-  });
 
-  // collapse multiple consecutive empty lines into one (drop an empty that follows an empty)
-  const collapsedLines = cleanedLines.filter((line, index) => {
-    const isEmpty = line.trim() === '';
-    const prevWasEmpty = index > 0 && cleanedLines[index - 1]!.trim() === '';
-    return !(isEmpty && prevWasEmpty);
-  });
-
-  return collapsedLines.join('\n').trim();
+  return linesCollapsed.join('\n').trim();
 };
 
 /**
- * ensures a section with header and entries exists in the content
- */
-const ensureSection = (
-  content: string,
-  section: (typeof SECTIONS)[number],
-): string => {
-  const lines = content.split('\n');
-
-  // find which entries are absent from the content
-  const entriesAbsent = section.entries.latest.filter(
-    (entry) => !content.includes(entry),
-  );
-
-  // find the header line index
-  const headerIndex = lines.findIndex(
-    (line) => line.trim() === section.header.latest,
-  );
-
-  // if header not found, append header and only absent entries
-  if (headerIndex === -1) {
-    return (
-      content.trimEnd() +
-      '\n\n' +
-      [section.header.latest, ...entriesAbsent].join('\n') +
-      '\n'
-    );
-  }
-
-  // if all entries present, no fix required
-  if (entriesAbsent.length === 0) return content;
-
-  // insert absent entries right after the header
-  const newLines = [
-    ...lines.slice(0, headerIndex + 1),
-    ...entriesAbsent,
-    ...lines.slice(headerIndex + 1),
-  ];
-
-  return newLines.join('\n');
-};
-
-/**
- * fix by cleanup of legacy content and ensure all sections are present
+ * .what = the repo-own lines first, then the canonical block, with exactly one final newline
+ * .why  = legacy headers and entries drop, duplicates collapse to one, and the output CONTAINS the
+ *         template — so the check passes on the fixed output and a second fix changes zero
  */
 export const fix: FileFixFunction = (contents) => {
-  // if no contents, create the file with all sections
-  if (!contents) {
-    const allSections = SECTIONS.map((s) =>
-      [s.header.latest, ...s.entries.latest].join('\n'),
-    ).join('\n\n');
-    return { contents: allSections + '\n' };
-  }
-
-  // clean up legacy headers and duplicates, then ensure each section exists
-  const result = SECTIONS.reduce(
-    (acc, section) => ensureSection(acc, section),
-    cleanContent(contents),
-  );
-
-  // trim to exactly one final newline
-  return { contents: result.trimEnd() + '\n' };
+  const repoOwnBlock = asRepoOwnBlock({ contents: contents ?? '' });
+  return {
+    contents: `${[repoOwnBlock, CANONICAL_BLOCK].filter((block) => block).join('\n\n')}\n`,
+  };
 };

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/.test/assets/demo-repo-with-edited-timestamp-hook/.husky/check.timestamps.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# a hand-softened timestamp hook: someone added an exemption so .goals/ commits go through
+staged=$(git diff --cached --name-only --diff-filter=ACM)
+while IFS= read -r file; do
+  case "$file" in
+    *.ts | *.sh | .goals/*) continue ;;
+  esac
+done <<EOF
+$staged
+EOF

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/.test/assets/demo-repo-with-edited-timestamp-hook/declapract.declare.yml

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

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/.test/assets/demo-repo-with-edited-timestamp-hook/declapract.use.yml

@@ -0,0 +1,2 @@
+declarations: './'
+useCase: typescript-project-core

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/.test/assets/demo-repo-with-edited-timestamp-hook/package.json

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

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/__snapshots__/check.secrets.play.declapract.integration.test.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`check.secrets guard given: [case1] a staged debug file that holds a fireworks key (the #514 incident) when: [t0] the guard runs then: the halt output matches snapshot: check.secrets halt output 1`] = `
+"✋ ConstraintError: a secret key shape is staged. remove it, and rotate the key if it ever left this machine
+   ├─ shape: fireworks key
+   └─ .cache/debug.env:2
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/__snapshots__/check.timestamps.lock.play.declapract.integration.test.ts.snap

@@ -0,0 +1,107 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t0] the input (before any apply) then: the softened hook carries the exemption, and matches snapshot: check.timestamps.sh — before 1`] = `
+"#!/bin/bash
+
+# a hand-softened timestamp hook: someone added an exemption so .goals/ commits go through
+staged=$(git diff --cached --name-only --diff-filter=ACM)
+while IFS= read -r file; do
+  case "$file" in
+    *.ts | *.sh | .goals/*) continue ;;
+  esac
+done <<EOF
+$staged
+EOF
+"
+`;
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t1] the lock is applied, the softened hook left in place then: the lock halts with exit 2 and says revert, zero exceptions: lock halt output — on disk 1`] = `
+"✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps
+   ├─ why: the timestamp hook never takes an exemption. a timestamp is a privacy leak
+   ├─ expected: [blob]
+   ├─ found: [blob] (on disk)
+   └─ fix: npx declapract apply --practice husky
+"
+`;
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t1] the lock is applied, the softened hook left in place then: the lock is stamped with the declared hook blob id, and matches snapshot: check.timestamps.lock.sh — after 1`] = `
+"#!/bin/bash
+
+# .what = halt every commit if .husky/check.timestamps.sh differs from the practice's copy
+# .why  = the timestamp hook has zero exemptions, by design. a timestamp in a tracked file a
+#         privacy leak that ships to every clone and fork, forever. an edit
+#         that softens the hook (an exemption, a skip, a looser pattern) lets it back in, so
+#         this lock refuses the commit until the hook is reverted
+# .how  = compare the git blob id of the hook (on disk, and in the index) to the blob id the
+#         practice declared; halt with a constraint error (exit 2) on any mismatch, or with a
+#         malfunction error (exit 1) when git cannot read the index
+#
+# ⛔ do not edit this lock or its expected id by hand to let a changed hook through. the only
+#    sanctioned change to the timestamp hook is a practice upgrade, which rewrites both at once.
+
+# the blob id of the declared hook (stamped by the practice on apply)
+TIMESTAMPS_LOCK_EXPECTED='[blob]'
+
+# the hook under lock; $0 is the hook dir whether sourced by pre-commit or run direct
+TIMESTAMPS_LOCK_HOOK="$(dirname -- "$0")/check.timestamps.sh"
+
+# halt with the revert instruction
+timestamps_lock_halt() {
+  printf '✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps\\n' >&2
+  printf '   ├─ why: the timestamp hook never takes an exemption. a timestamp is a privacy leak\\n' >&2
+  printf '   ├─ expected: %s\\n' "$TIMESTAMPS_LOCK_EXPECTED" >&2
+  printf '   ├─ found: %s (%s)\\n' "$1" "$2" >&2
+  printf '   └─ fix: npx declapract apply --practice husky\\n' >&2
+  exit 2
+}
+
+# halt when the index cannot be read; the hook may be intact, so never say it was changed
+timestamps_lock_malfunction() {
+  printf '💥 MalfunctionError: the git index is unreadable, so the lock cannot verify .husky/check.timestamps.sh\\n' >&2
+  printf '   ├─ found: unreadable (in the index)\\n' >&2
+  printf '   ├─ why: a failed read halts the commit, never reads as "not staged"\\n' >&2
+  printf '   └─ fix: repair the git index (git status names the fault), then commit again\\n' >&2
+  exit 1
+}
+
+# halt if the hook is absent
+[ -f "$TIMESTAMPS_LOCK_HOOK" ] || timestamps_lock_halt 'absent' 'on disk'
+
+# halt if the hook on disk differs
+TIMESTAMPS_LOCK_DISK=$(git hash-object -- "$TIMESTAMPS_LOCK_HOOK")
+[ "$TIMESTAMPS_LOCK_DISK" = "$TIMESTAMPS_LOCK_EXPECTED" ] || timestamps_lock_halt "$TIMESTAMPS_LOCK_DISK" 'on disk'
+
+# halt if the hook in the index differs (a staged edit, then a revert on disk, still commits the edit)
+# the index read stands alone, so a failed read halts rather than reads as "not staged"
+TIMESTAMPS_LOCK_STAGE=$(git ls-files -s -- "$TIMESTAMPS_LOCK_HOOK") || timestamps_lock_malfunction
+TIMESTAMPS_LOCK_INDEX=$(printf '%s\\n' "$TIMESTAMPS_LOCK_STAGE" | awk '{ print $2 }')
+[ -z "$TIMESTAMPS_LOCK_INDEX" ] || [ "$TIMESTAMPS_LOCK_INDEX" = "$TIMESTAMPS_LOCK_EXPECTED" ] || timestamps_lock_halt "$TIMESTAMPS_LOCK_INDEX" 'in the index'
+"
+`;
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t2] the hook edit is staged, then reverted on disk only then: the lock still halts — the index would commit the exemption: lock halt output — in the index 1`] = `
+"✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps
+   ├─ why: the timestamp hook never takes an exemption. a timestamp is a privacy leak
+   ├─ expected: [blob]
+   ├─ found: [blob] (in the index)
+   └─ fix: npx declapract apply --practice husky
+"
+`;
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t4] the index cannot be read then: the lock halts as a malfunction (exit 1) and names the unreadable index, never reads it as unstaged: lock halt output — index unreadable 1`] = `
+"fatal: .git/index: index file smaller than expected
+💥 MalfunctionError: the git index is unreadable, so the lock cannot verify .husky/check.timestamps.sh
+   ├─ found: unreadable (in the index)
+   ├─ why: a failed read halts the commit, never reads as "not staged"
+   └─ fix: repair the git index (git status names the fault), then commit again
+"
+`;
+
+exports[`check.timestamps.lock given: [case2] a repo whose timestamp hook was hand-softened with an exemption when: [t6] the hook is deleted then: the lock halts with exit 2: lock halt output — hook absent 1`] = `
+"✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps
+   ├─ why: the timestamp hook never takes an exemption. a timestamp is a privacy leak
+   ├─ expected: [blob]
+   ├─ found: absent (on disk)
+   └─ fix: npx declapract apply --practice husky
+"
+`;

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/__snapshots__/check.timestamps.play.declapract.integration.test.ts.snap

@@ -1,7 +1,8 @@
 // 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
+exports[`check.timestamps guard given: [case1] a non-code file with an iso timestamp when: [t0] the guard runs then: the halt output, its instant masked, matches snapshot: check.timestamps halt output 1`] = `
+"✋ ConstraintError: timestamps are forbidden in tracked files, prose and docs included. remove them, zero exceptions
+   ├─ why: a timestamp is a privacy leak, and churns every diff
    └─ snapshot.json:1:{ "createdAt": "[timestamp]" }
 "
 `;

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/check.nvm.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
 
 # if exists a .nvmrc, then `nvm use`, to use the specified version
-# [[ -f ".nvmrc" ]] && nvm use # todo: find a way to share nvm permissions
+# disabled: a git hook shell does not load nvm, so `nvm use` cannot run here
+# [[ -f ".nvmrc" ]] && nvm use

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/check.secrets.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+# .what = block commit of files whose staged content holds a secret key shape
+# .why  = a key committed once ships to every clone and fork, forever; a rotation is the
+#         only repair. a key shape (a vendor prefix plus a long random tail) is cheap to
+#         spot before the commit, and costly to chase after it
+# .how  = scan each staged blob for known key shapes; halt with a constraint error
+#         (exit 2) that names the file, the line, and the shape — never the key itself
+
+# fail fast on errors and unbound vars (safe here: scan pipelines end in `head`
+# so a no-match grep does not abort, and all vars are assigned before use)
+set -eu
+
+# the key shapes, one per line as `name|regex`. each regex starts at a word edge, so a
+# vendor prefix inside a longer word (e.g. `disk-`) does not match
+EDGE='(^|[^A-Za-z0-9_])'
+SHAPES="aws access key id|${EDGE}(AKIA|ASIA)[0-9A-Z]{16}([^0-9A-Z]|\$)
+private key block|-----BEGIN [A-Z ]*PRIVATE KEY-----
+github token|${EDGE}(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})
+openai-style key|${EDGE}sk-(proj-)?[A-Za-z0-9_-]{20,}
+anthropic key|${EDGE}sk-ant-[A-Za-z0-9_-]{20,}
+xai key|${EDGE}xai-[A-Za-z0-9]{20,}
+fireworks key|${EDGE}fw_[A-Za-z0-9]{20,}
+slack token|${EDGE}xox[abposr]-[A-Za-z0-9-]{10,}
+stripe secret key|${EDGE}(sk|rk)_live_[A-Za-z0-9]{16,}"
+
+# collect staged files (added/copied/modified); skip deletions
+# core.quotepath=off emits a non-ascii path raw, so `git show` below can read it
+staged=$(git -c core.quotepath=off diff --cached --name-only --diff-filter=ACM)
+
+# scan each staged blob against each shape
+# note: the here-docs feed the loops in the current shell (no pipe subshell),
+#       so `exit 2` halts the commit directly and a clean pass falls through
+while IFS= read -r file; do
+  # skip empty lines
+  [ -n "$file" ] || continue
+
+  # read the staged blob; fail loud if git cannot read it
+  if ! content=$(git show ":$file"); then
+    printf '💥 MalfunctionError: check.secrets could not read the staged blob\n' >&2
+    printf '   └─ %s\n' "$file" >&2
+    exit 1
+  fi
+
+  # halt on the first shape found; print the line number only, so the key never echoes
+  while IFS='|' read -r name regex; do
+    [ -n "$name" ] || continue
+    line=$(printf '%s\n' "$content" | grep -nIE -e "$regex" | head -n 1 | cut -d: -f1)
+    if [ -n "$line" ]; then
+      printf '✋ ConstraintError: a secret key shape is staged. remove it, and rotate the key if it ever left this machine\n' >&2
+      printf '   ├─ shape: %s\n' "$name" >&2
+      printf '   └─ %s:%s\n' "$file" "$line" >&2
+      exit 2
+    fi
+  done <<SHAPES_EOF
+$SHAPES
+SHAPES_EOF
+done <<EOF
+$staged
+EOF

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/check.timestamps.lock.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# .what = halt every commit if .husky/check.timestamps.sh differs from the practice's copy
+# .why  = the timestamp hook has zero exemptions, by design. a timestamp in a tracked file a
+#         privacy leak that ships to every clone and fork, forever. an edit
+#         that softens the hook (an exemption, a skip, a looser pattern) lets it back in, so
+#         this lock refuses the commit until the hook is reverted
+# .how  = compare the git blob id of the hook (on disk, and in the index) to the blob id the
+#         practice declared; halt with a constraint error (exit 2) on any mismatch, or with a
+#         malfunction error (exit 1) when git cannot read the index
+#
+# ⛔ do not edit this lock or its expected id by hand to let a changed hook through. the only
+#    sanctioned change to the timestamp hook is a practice upgrade, which rewrites both at once.
+
+# the blob id of the declared hook (stamped by the practice on apply)
+TIMESTAMPS_LOCK_EXPECTED='__EXPECTED_BLOB__'
+
+# the hook under lock; $0 is the hook dir whether sourced by pre-commit or run direct
+TIMESTAMPS_LOCK_HOOK="$(dirname -- "$0")/check.timestamps.sh"
+
+# halt with the revert instruction
+timestamps_lock_halt() {
+  printf '✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps\n' >&2
+  printf '   ├─ why: the timestamp hook never takes an exemption. a timestamp is a privacy leak\n' >&2
+  printf '   ├─ expected: %s\n' "$TIMESTAMPS_LOCK_EXPECTED" >&2
+  printf '   ├─ found: %s (%s)\n' "$1" "$2" >&2
+  printf '   └─ fix: npx declapract apply --practice husky\n' >&2
+  exit 2
+}
+
+# halt when the index cannot be read; the hook may be intact, so never say it was changed
+timestamps_lock_malfunction() {
+  printf '💥 MalfunctionError: the git index is unreadable, so the lock cannot verify .husky/check.timestamps.sh\n' >&2
+  printf '   ├─ found: unreadable (in the index)\n' >&2
+  printf '   ├─ why: a failed read halts the commit, never reads as "not staged"\n' >&2
+  printf '   └─ fix: repair the git index (git status names the fault), then commit again\n' >&2
+  exit 1
+}
+
+# halt if the hook is absent
+[ -f "$TIMESTAMPS_LOCK_HOOK" ] || timestamps_lock_halt 'absent' 'on disk'
+
+# halt if the hook on disk differs
+TIMESTAMPS_LOCK_DISK=$(git hash-object -- "$TIMESTAMPS_LOCK_HOOK")
+[ "$TIMESTAMPS_LOCK_DISK" = "$TIMESTAMPS_LOCK_EXPECTED" ] || timestamps_lock_halt "$TIMESTAMPS_LOCK_DISK" 'on disk'
+
+# halt if the hook in the index differs (a staged edit, then a revert on disk, still commits the edit)
+# the index read stands alone, so a failed read halts rather than reads as "not staged"
+TIMESTAMPS_LOCK_STAGE=$(git ls-files -s -- "$TIMESTAMPS_LOCK_HOOK") || timestamps_lock_malfunction
+TIMESTAMPS_LOCK_INDEX=$(printf '%s\n' "$TIMESTAMPS_LOCK_STAGE" | awk '{ print $2 }')
+[ -z "$TIMESTAMPS_LOCK_INDEX" ] || [ "$TIMESTAMPS_LOCK_INDEX" = "$TIMESTAMPS_LOCK_EXPECTED" ] || timestamps_lock_halt "$TIMESTAMPS_LOCK_INDEX" 'in the index'

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/check.timestamps.lock.sh.declapract.ts

@@ -0,0 +1,36 @@
+import type { FileContentsFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+import { createHash } from 'node:crypto';
+import { readFile } from '../../../../utils/readFile';
+
+/**
+ * .what = the git blob id of some file contents, as `git hash-object` computes it
+ * .why  = the lock hook compares blob ids with plain git, so no sha256 tool must exist on the host
+ */
+export const asGitBlobId = (input: { contents: string }): string =>
+  createHash('sha1')
+    .update(`blob ${Buffer.byteLength(input.contents)}\0`)
+    .update(input.contents)
+    .digest('hex');
+
+/**
+ * .what = declare the timestamp lock hook, stamped with the blob id of the declared timestamp hook
+ * .why  = the lock id is derived from the hook template at apply time, so the two can never drift;
+ *         a practice upgrade rewrites both at once, and any hand edit to the hook halts the commit
+ */
+export const contents: FileContentsFunction = async () => {
+  // read the declared timestamp hook and the lock template
+  const hook = await readFile({ filePath: `${__dirname}/check.timestamps.sh` });
+  const lock = await readFile({
+    filePath: `${__dirname}/check.timestamps.lock.sh`,
+  });
+
+  // stamp the hook's blob id into the lock
+  return lock.replace('__EXPECTED_BLOB__', asGitBlobId({ contents: hook }));
+};
+
+/**
+ * the lock is a whole-file template with no usecase branch, so exact match is scope-safe
+ */
+export const check = FileCheckType.EQUALS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/check.timestamps.sh

@@ -1,27 +1,45 @@
 #!/bin/bash
 
-# .what = block commit of files that embed a timestamp (T?HH:MM:SS{tz})
-# .why  = timestamps in snapshots permadrift — they change every run, so the
-#         snapshot can never be "correct" twice; mask them to keep it stable
+# .what = block commit of files that embed a clock time (HH:MM, HH:MM:SS, a T-dash form, any zone)
+#         in ANY staged file but .ts/.sh — prose included: readmes, docs, briefs, yields, dreams
+# .why  = a timestamp in a tracked file is a privacy leak that ships to every clone and fork,
+#         forever; it also churns every diff
 # .how  = scan staged files (except .ts/.sh) for the pattern; halt with a
 #         constraint error (exit 2) if any are found
+#
+# ⛔ NEVER ADD AN EXEMPTION TO THIS HOOK. NOT A PATH, NOT A DIR, NOT A FILE, NOT A PATTERN.
+#    this hook exists to block EVERY timestamp in every tracked file. that is the whole point.
+#    an exemption is how the leak gets back in — one dir today, every dir tomorrow.
+#    a file that "needs" a timestamp removes it or masks it (e.g. `[timestamp]`, a fixed clock).
+#    the .ts/.sh skip below is code that computes time, not data that records it; it may never
+#    widen. check.timestamps.lock.sh halts every commit if this file differs from the practice.
 
 # fail fast on errors and unbound vars (safe here: scan pipelines end in `head`
 # so a no-match grep does not abort, and all vars are assigned before use)
 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])?'
+# the time-of-day forms, each a valid clock (hour 00-23, minute + second 00-59):
+#   - colon clock, with or without seconds: 14:30, 14:30:00, T14:30Z, 14:30:00+05:00
+#   - dash clock after a lead T, as in a filename-safe iso stamp: T14-30-00Z, T14-30Z
+# a clock with no lead T needs a left edge with no digit or colon before the hour, so a
+# `file.ts:12:34` line:col ref and a `5432:5432` port map do not match (a lead T, as in
+# `2026-09-20T14:30`, marks a clock on its own); the right edge forbids a digit after,
+# so a longer number never reads as a clock
+CLOCK_COLON='([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?'
+CLOCK_DASH='T([01][0-9]|2[0-3])-[0-5][0-9](-[0-5][0-9])?'
+ZONE='(Z|[+-][0-9][0-9]:?[0-9][0-9])?'
+TIMESTAMP_PATTERN="(T${CLOCK_COLON}|${CLOCK_DASH}|(^|[^0-9:])${CLOCK_COLON})${ZONE}([^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]'
+# an iso-8601 DURATION is a fixed span, not an instant — 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)
+# core.quotepath=off emits a non-ascii path raw, so `git show` below can read it
+staged=$(git -c core.quotepath=off diff --cached --name-only --diff-filter=ACM)
 
 # scan each staged file for a raw timestamp
 # note: the here-doc feeds the loop in the current shell (no pipe subshell),
@@ -35,11 +53,11 @@ while IFS= read -r file; do
     *.ts | *.sh) continue ;;
   esac
 
-  # read the staged content; fail loud if git cannot read the staged blob
-  # (2>&1 captures git's error into the var so the halt message can surface it)
-  if ! content=$(git show ":$file" 2>&1); then
-    printf '💥 check.timestamps: failed to read staged content for %s\n' "$file" >&2
-    printf '   └─ %s\n' "$content" >&2
+  # read the staged blob; fail loud if git cannot read it
+  # (git's own stderr flows straight to the terminal, never into the scanned content)
+  if ! content=$(git show ":$file"); then
+    printf '💥 MalfunctionError: check.timestamps could not read the staged blob\n' >&2
+    printf '   └─ %s\n' "$file" >&2
     exit 1
   fi
 
@@ -48,8 +66,9 @@ while IFS= read -r file; do
   # 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"
+    printf '✋ ConstraintError: timestamps are forbidden in tracked files, prose and docs included. remove them, zero exceptions\n' >&2
+    printf '   ├─ why: a timestamp is a privacy leak, and churns every diff\n' >&2
+    printf '   └─ %s:%s\n' "$file" "$match" >&2
     exit 2
   fi
 done <<EOF

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/best-practice/.husky/pre-commit

@@ -7,4 +7,8 @@ fi
 
 . "$(dirname -- "$0")/check.yalc.sh"
 
+. "$(dirname -- "$0")/check.timestamps.lock.sh"
+
 . "$(dirname -- "$0")/check.timestamps.sh"
+
+. "$(dirname -- "$0")/check.secrets.sh"