From 80138fd8ef89099c2b1de40b56c196f3a19479f7 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 10:27:06 +0100 Subject: [PATCH 1/9] docs(guardrails): enforce JSDoc on every new or modified function --- .github/copilot-instructions.md | 1 + ERRORS.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 88a68a95..bcc0329f 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` if the function returns a value ## Architecture and modularity diff --git a/ERRORS.md b/ERRORS.md index 4d9a504b..bf0fa7f0 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,3 +11,4 @@ Use this file as a compact memory of recurring AI mistakes. ## Entries +- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @returns) From 486dee89d9a708a8fee8007f23e33f3b6a9ce740 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 10:47:07 +0100 Subject: [PATCH 2/9] =?UTF-8?q?fix(guardrails):=20apply=20Copilot=20feedba?= =?UTF-8?q?ck=20=E2=80=94=20use=20@return,=20clarify=20async=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bcc0329f..5af86d88 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,7 +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` if the function returns a value +- Every new or modified function must have a JSDoc header: one-line description, `@param` for each argument, `@return` for any non-void return value (always include `@return` for async functions to document the resolved value) ## Architecture and modularity From 2a5356bb7123f90d4571fcc3b8228be6bdc7eca8 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 10:48:32 +0100 Subject: [PATCH 3/9] fix(guardrails): use @return (no trailing s) for cross-repo consistency --- ERRORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index bf0fa7f0..07943ffd 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,4 +11,4 @@ Use this file as a compact memory of recurring AI mistakes. ## Entries -- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @returns) +- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @return) From 3e4d59e69508083f19e3566ab36c8251e6a7ffd7 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 10:51:48 +0100 Subject: [PATCH 4/9] fix(guardrails): use @returns to match Node codebase convention, clarify async rule --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5af86d88..e6e1dfa8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -37,7 +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, `@return` for any non-void return value (always include `@return` for async functions to document the resolved value) +- 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 @@ -63,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 From ec0677cbd3a19e22a5c1dbfaca21f89e8a5a88ba Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 10:54:02 +0100 Subject: [PATCH 5/9] fix(guardrails): use @returns to match Node codebase convention --- ERRORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index 07943ffd..cfd14a98 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,4 +11,4 @@ Use this file as a compact memory of recurring AI mistakes. ## Entries -- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @return) +- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @returns) \ No newline at end of file From d65673f88cfc55f2e445f0ae3d245d74193701eb Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 11:26:53 +0100 Subject: [PATCH 6/9] fix(jsdoc): add backticks to @param and @returns for consistent Markdown formatting --- ERRORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index cfd14a98..a3da93cb 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,4 +11,4 @@ Use this file as a compact memory of recurring AI mistakes. ## Entries -- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + @param + @returns) \ No newline at end of file +- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + `@param` + `@returns`) \ No newline at end of file From 6b7eaecb17de034b256cc8172de5081bcb804ec7 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 12:42:08 +0100 Subject: [PATCH 7/9] fix(jsdoc): align ERRORS.md wording with guardrail (new or modified functions) --- ERRORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index a3da93cb..8806183e 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,4 +11,4 @@ Use this file as a compact memory of recurring AI mistakes. ## Entries -- [2026-02-22] functions: added functions without JSDoc header -> always add JSDoc (description + `@param` + `@returns`) \ No newline at end of file +- [2026-02-22] functions: new or modified functions without JSDoc header -> always add JSDoc (description + `@param` + `@returns`) \ No newline at end of file From 2019089ece9210a0f1d821b8b4814b140baeb69e Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 12:57:17 +0100 Subject: [PATCH 8/9] chore(errors): never patch code to pass a test, refactor if needed --- ERRORS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index 8806183e..0bd25fca 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,4 +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` + `@returns`) \ No newline at end of file +- [2026-02-22] functions: new or modified functions without JSDoc header -> always add JSDoc (description + `@param` + `@returns`) +- [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 From d1aa3ecba5b9ae71100f3929c691e33e344fc0b4 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 22 Feb 2026 12:59:58 +0100 Subject: [PATCH 9/9] fix(errors): align ERRORS.md JSDoc rule with guardrail nuance (non-void + async) --- ERRORS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERRORS.md b/ERRORS.md index 0bd25fca..e8144069 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -11,5 +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` + `@returns`) +- [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