docs(noir-contracts): document standard-contract re-pin consequences (#24890)

Author: nchamo

CLAUDE.md

@@ -57,6 +57,10 @@ When staging files, prefer `git add -u` or name specific files rather than `git
 Never bulk-update lockfiles (`Cargo.lock`, `yarn.lock`). Use targeted updates only: `cargo update --precise <version> --package <name>` for Rust, and `yarn up <package>@<version>` in the relevant workspace for TypeScript. Bulk updates drag in unrelated transitive changes that make review impossible and frequently break reproducibility.
 </lockfile_discipline>
 
+<standard_contract_repin>
+Never run `noir-projects/noir-contracts/bootstrap.sh pin-standard-build` on your own initiative. The pin exists so ordinary source or bytecode changes do NOT move the standard contracts' canonical addresses, and CI does not fail when the bytecode drifts. A re-pin is a deliberate redeploy decision for a human to make: if a change seems to need one, leave the pin, rebuild against it, and ask. See the comment on `pin-standard-build` for why re-pinning is breaking.
+</standard_contract_repin>
+
 </git_workflow>
 
 <code_formatting>

noir-projects/noir-contracts/bootstrap.sh

@@ -267,8 +267,13 @@ function format {
 }
 
 # Force-builds standard contracts and tar-balls their artifacts into pinned-standard-contracts.tar.gz.
-# Run this to (re)pin the standard-contract artifacts, then commit the resulting tarball. Re-run and
-# re-commit whenever the canonical standard-contract artifacts are intended to change.
+#
+# WARNING: re-pinning (running this, then committing the new tarball) moves the standard contracts'
+# canonical deterministic addresses and class ids. Rebuilding changes the artifact hash and bytecode
+# commitment, which changes the class id and the address derived from it. Those addresses are baked
+# into every already-deployed network and published package, so a re-pin breaks compatibility with all
+# of them and means the standard contracts must be redeployed at their new addresses on any network
+# meant to run the new artifacts. It is only correct as part of a deliberate, coordinated redeploy.
 # Mirrors the v4 `pin-build` mechanism that pins protocol contracts.
 function pin-standard-build {
   rm -f pinned-standard-contracts.tar.gz