From 29ba8447a2dde74edce382e10f6cb6319e62dfb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C5=ABdolfs=20O=C5=A1i=C5=86=C5=A1?= <rudolfs@osins.org>
Date: Thu, 22 Oct 2026 13:39:52 +0200
Subject: [PATCH] Document dependency updates under the cooldown

Plain `cargo update` and `npm audit fix --force` bypass or ignore the
cooldown, and nothing told people or agents which commands respect it.
---
 AGENTS.md       | 24 ++++++++++++++++++++++++
 CONTRIBUTING.md | 24 ++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 070b0d9a6..8c8b8eba9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,6 +48,8 @@ source of truth for anything inside it.
   installs are gated by `min-release-age` and `strict-allow-scripts`
 - Use npm, never `yarn` or `pnpm`: the lockfiles and `.npmrc` settings are
   npm's
+- Updates and audit fixes must respect each project's 7-day cooldown, see
+  "Updating dependencies" below
 - Run tests through the `npm run` scripts, not `npm test` (neither project
   has one), `npx vitest` or `npx playwright test`: the scripts set `TZ=UTC`
   and, in explorer, `NODE_CONFIG_ENV`, which the tests rely on
@@ -61,6 +63,28 @@ source of truth for anything inside it.
 - Loading states: `{#await promise}` blocks for inline async;
   local `loading` boolean with `try/catch` for imperative fetches
 
+## Updating dependencies
+
+Both projects only install releases that are at least 7 days old: npm through
+`min-release-age` in `.npmrc`, Cargo through `cooldown.toml` and
+`cargo-cooldown`. Run these from the project's directory:
+
+```sh
+npm audit                         # list advisories
+npm audit fix                     # apply fixes that are past the cooldown
+cargo audit                       # list advisories
+cargo cooldown update -p <crate>  # update a crate within the cooldown
+```
+
+- Never run plain `cargo update`: it ignores `cooldown.toml`
+- Never run `npm audit fix --force`: it takes major-version bumps. Ask first
+- If a fix is still cooling down, report when it clears and ask before
+  taking it early. Taking it early means reviewing the release's diff
+  against the previous version, then:
+  - npm: `npm install <pkg>@<version> --min-release-age=0`
+  - Cargo: add an `[[allow.exact]]` entry to `cooldown.toml` with a comment
+    naming the advisory and the date it can be removed
+
 ## Commit messages
 
 - Imperative mood: "Add feature" not "Added feature"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3fc419a9f..bde4e701d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,6 +27,30 @@ When proposing changes via a patch:
   repository or in the project's own `docs/adr/` otherwise, and get consensus
   on that before proposing the code changes.
 
+## Updating dependencies
+
+Both projects only install releases that are at least 7 days old, to give
+the ecosystem time to catch compromised packages. npm enforces this through
+`min-release-age` in each project's `.npmrc`; Cargo through its
+`cooldown.toml`, which needs `cargo install cargo-cooldown cargo-audit`.
+From the project's directory:
+
+```sh
+npm audit
+npm audit fix
+cargo audit
+cargo cooldown update -p <crate>
+```
+
+Use `cargo cooldown update` rather than `cargo update`, which ignores the
+cooldown, and avoid `npm audit fix --force`, which takes major-version bumps.
+
+When a security fix is still cooling down and can't wait, review the release's
+diff against the previous version first. Then install it with
+`npm install <pkg>@<version> --min-release-age=0`, or allow it in
+`cooldown.toml` with an `[[allow.exact]]` entry and a comment naming the
+advisory and the date it can be removed.
+
 ## Writing Git commit messages
 
 A properly formed git commit subject line should always be able to complete the