add a warning to the --check doc

Author: oconnor663

b3sum/what_does_check_do.md

@@ -8,6 +8,20 @@ complicated than it might seem, is that representing filepaths as text means we
 need to consider many possible edge cases of unrepresentable filepaths. This
 document describes all of these edge cases in detail.
 
+> [!CAUTION]
+> `b3sum --check` (like all the Coreutils `--check` features) tells you whether
+> some _filepaths_ have changed, but it can't tell you whether a _directory_
+> has changed in general. If you generate a checkfile with something like
+> `b3sum my_dir/* > CHECKFILE`, then `b3sum --check CHECKFILE` will succeed
+> even after _new files_ are added to `my_dir`. Adding new files without
+> changing anything else is often enough to execute arbitrary code, for example
+> by shadowing an `import` in Python or installing something in `.git/hooks`.
+> This is confusing enough that I don't recommend using `--check` as a security
+> tool in new code. "Has this directory changed?" turns out to be a thorny
+> problem, and my recommendation is to use something like tarball hashes or Git
+> commits instead, even though those have their own limitations and security
+> issues.
+
 ## The simple case
 
 Here's the result of running `b3sum a b c/d` in a directory that contains