diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 88a68a95..e6e1dfa8 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -37,6 +37,7 @@ Use `.github/prompts/*.prompt.md` for guided workflows:
 - 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)
 
 ## Architecture and modularity
 
@@ -62,4 +63,4 @@ Use `.github/prompts/*.prompt.md` for guided workflows:
 
 - `npm run lint` passes
 - `npm test` passes
-- Cross-module impact is documented and justified when present
+- Cross-module impact is documented and justified when present
\ No newline at end of file
diff --git a/ERRORS.md b/ERRORS.md
index 4d9a504b..e8144069 100644
--- a/ERRORS.md
+++ b/ERRORS.md
@@ -11,3 +11,5 @@ Use this file as a compact memory of recurring AI mistakes.
 
 ## Entries
 
+- [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
\ No newline at end of file