diff --git a/CLAUDE.md b/CLAUDE.md
index 78184aaf2..d404f858c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -53,6 +53,7 @@ The `.claude/` folder contains embedded settings, skills, and agents that are av
 - Avoid risky renames or moves of core stack paths used by downstream merges
 - Keep changes minimal and merge-friendly for downstream projects
 - Flag security or mergeability risks explicitly in reviews
+- Every new or modified function must have a JSDoc header: one-line description, `@param` for each argument, `@returns` for any non-void return value (always include `@returns` for async functions to document the resolved value)
 
 ## Available embedded skills
 
diff --git a/ERRORS.md b/ERRORS.md
index 6db89ee8e..bdcf2f0fc 100644
--- a/ERRORS.md
+++ b/ERRORS.md
@@ -14,4 +14,4 @@ Use this file as a compact memory of recurring AI mistakes.
 - [2026-02-22] functions: new or modified functions without JSDoc header -> always add JSDoc (description + `@param` for each arg + `@returns` for non-void return values and all async functions)
 - [2026-02-22] tests: never patch code to pass a test -> if a test is wrong, fix the test; if logic needs refactoring, refactor it
 - [2026-02-23] pr skill: stopping after `gh pr ready` -> always enter the monitor loop (wait CI → 3min grace → read feedback → iterate) until stop condition is met
-- [2026-02-23] pr skill: skipping issue creation when none found -> always create a GitHub issue before opening a PR (`gh issue create --web` or via CLI)
\ No newline at end of file
+- [2026-02-23] pr skill: skipping issue creation when none found -> always create a GitHub issue before opening a PR (`gh issue create --web` or via CLI)