ronce-racine 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/AGENTS.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +281 -0
  4. package/agents/code-reviewer.md +33 -0
  5. package/agents/qa-tester.md +28 -0
  6. package/dist/hooks/README.md +182 -0
  7. package/dist/hooks/bash-npm-silent.mjs +81 -0
  8. package/dist/hooks/session-inject.mjs +53 -0
  9. package/dist/hooks/session-precompact.mjs +36 -0
  10. package/dist/hooks/session-writer.mjs +142 -0
  11. package/dist/hooks/skill-reminder.mjs +89 -0
  12. package/dist/hooks/truncate-bash-output.mjs +46 -0
  13. package/dist/hooks/truncate-output.mjs +88 -0
  14. package/dist/hooks/worktree-env-setup.mjs +123 -0
  15. package/dist/install.js +962 -0
  16. package/docs/adopting-a-repo.md +80 -0
  17. package/docs/architecture.md +76 -0
  18. package/docs/decisions.md +72 -0
  19. package/docs/developing.md +143 -0
  20. package/docs/evaluating-skills.md +41 -0
  21. package/docs/git-worktrees.md +62 -0
  22. package/docs/rules/clean-architecture-deps.md +66 -0
  23. package/docs/rules/commits.md +59 -0
  24. package/docs/rules/detection-gap-protocol.md +55 -0
  25. package/docs/rules/error-handling-discipline.md +62 -0
  26. package/docs/rules/minimal-code.md +58 -0
  27. package/docs/rules/no-raw-sql-interpolation.md +57 -0
  28. package/docs/rules/pre-commit-secret-detection.md +54 -0
  29. package/docs/rules/secure-logging.md +53 -0
  30. package/docs/rules/sql-migrations-discipline.md +58 -0
  31. package/docs/rules/subscription-cleanup.md +63 -0
  32. package/docs/rules/test-discipline.md +66 -0
  33. package/docs/rules/ui-states-complete.md +52 -0
  34. package/docs/templates/SKILL.template.md +66 -0
  35. package/docs/templates/rule.template.md +16 -0
  36. package/docs/writing-a-rule.md +43 -0
  37. package/docs/writing-a-skill.md +118 -0
  38. package/package.json +45 -0
  39. package/rules/clean-architecture-deps.md +20 -0
  40. package/rules/commits.md +16 -0
  41. package/rules/detection-gap-protocol.md +35 -0
  42. package/rules/error-handling-discipline.md +23 -0
  43. package/rules/minimal-code.md +32 -0
  44. package/rules/no-raw-sql-interpolation.md +20 -0
  45. package/rules/pre-commit-secret-detection.md +14 -0
  46. package/rules/secure-logging.md +16 -0
  47. package/rules/sql-migrations-discipline.md +18 -0
  48. package/rules/subscription-cleanup.md +22 -0
  49. package/rules/test-discipline.md +20 -0
  50. package/rules/ui-states-complete.md +23 -0
  51. package/scripts/subscription-leak-scan.ts +53 -0
  52. package/skills/adversarial-feature-challenge/README.md +65 -0
  53. package/skills/adversarial-feature-challenge/SKILL.md +96 -0
  54. package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
  55. package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
  56. package/skills/api-contract-versioning/README.md +62 -0
  57. package/skills/api-contract-versioning/SKILL.md +76 -0
  58. package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
  59. package/skills/audit-architecture/README.md +56 -0
  60. package/skills/audit-architecture/SKILL.md +97 -0
  61. package/skills/audit-architecture/reference/ar-architecture.md +275 -0
  62. package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
  63. package/skills/audit-architecture/reference/im-incidents.md +217 -0
  64. package/skills/audit-architecture/reference/pa-pannes.md +362 -0
  65. package/skills/audit-architecture/reference/re-recuperation.md +300 -0
  66. package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
  67. package/skills/audit-architecture/reference/su-support.md +180 -0
  68. package/skills/audit-ci-cd/README.md +54 -0
  69. package/skills/audit-ci-cd/SKILL.md +124 -0
  70. package/skills/audit-ci-cd/reference/artefacts.md +39 -0
  71. package/skills/audit-ci-cd/reference/deploiement.md +100 -0
  72. package/skills/audit-ci-cd/reference/dora.md +94 -0
  73. package/skills/audit-ci-cd/reference/iac.md +40 -0
  74. package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
  75. package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
  76. package/skills/audit-compliance/README.md +69 -0
  77. package/skills/audit-compliance/SKILL.md +176 -0
  78. package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
  79. package/skills/audit-compliance/reference/finops.md +318 -0
  80. package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
  81. package/skills/audit-industrialisation/README.md +53 -0
  82. package/skills/audit-industrialisation/SKILL.md +251 -0
  83. package/skills/audit-observability/README.md +64 -0
  84. package/skills/audit-observability/SKILL.md +134 -0
  85. package/skills/audit-observability/reference/alerting.md +214 -0
  86. package/skills/audit-observability/reference/logging.md +114 -0
  87. package/skills/audit-observability/reference/metriques.md +166 -0
  88. package/skills/audit-observability/reference/traces-dashboards.md +90 -0
  89. package/skills/audit-performance-frontend/README.md +91 -0
  90. package/skills/audit-performance-frontend/SKILL.md +194 -0
  91. package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
  92. package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
  93. package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
  94. package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
  95. package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
  96. package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
  97. package/skills/audit-quality/README.md +85 -0
  98. package/skills/audit-quality/SKILL.md +126 -0
  99. package/skills/audit-quality/reference/qa-devops.md +539 -0
  100. package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
  101. package/skills/audit-report/README.md +72 -0
  102. package/skills/audit-report/SKILL.md +241 -0
  103. package/skills/audit-report/reference/scoring-model.md +45 -0
  104. package/skills/audit-security/README.md +72 -0
  105. package/skills/audit-security/SKILL.md +140 -0
  106. package/skills/audit-security/reference/auth-identite.md +98 -0
  107. package/skills/audit-security/reference/autorisation.md +66 -0
  108. package/skills/audit-security/reference/chiffrement-tls.md +97 -0
  109. package/skills/audit-security/reference/detection-patching.md +67 -0
  110. package/skills/audit-security/reference/incident-response.md +98 -0
  111. package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
  112. package/skills/audit-security/reference/secrets.md +36 -0
  113. package/skills/audit-testing/README.md +82 -0
  114. package/skills/audit-testing/SKILL.md +131 -0
  115. package/skills/audit-testing/reference/golden-dataset.md +65 -0
  116. package/skills/audit-testing/reference/resilience-chaos.md +93 -0
  117. package/skills/audit-testing/reference/tests-contractuels.md +65 -0
  118. package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
  119. package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
  120. package/skills/bug-ticket-root-cause/README.md +67 -0
  121. package/skills/bug-ticket-root-cause/SKILL.md +86 -0
  122. package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
  123. package/skills/bug-triage-structured/README.md +63 -0
  124. package/skills/bug-triage-structured/SKILL.md +104 -0
  125. package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
  126. package/skills/ci-pipeline-orchestration/README.md +55 -0
  127. package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
  128. package/skills/commit-readiness-review/README.md +66 -0
  129. package/skills/commit-readiness-review/SKILL.md +82 -0
  130. package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
  131. package/skills/comprehensive-test-strategy/README.md +64 -0
  132. package/skills/comprehensive-test-strategy/SKILL.md +108 -0
  133. package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
  134. package/skills/daily-workflow-optimization/README.md +56 -0
  135. package/skills/daily-workflow-optimization/SKILL.md +80 -0
  136. package/skills/database-schema-evolution/README.md +54 -0
  137. package/skills/database-schema-evolution/SKILL.md +107 -0
  138. package/skills/ddd-backend-implementation/README.md +63 -0
  139. package/skills/ddd-backend-implementation/SKILL.md +95 -0
  140. package/skills/design-system-component-lifecycle/README.md +56 -0
  141. package/skills/design-system-component-lifecycle/SKILL.md +97 -0
  142. package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
  143. package/skills/detection-sweep/README.md +58 -0
  144. package/skills/detection-sweep/SKILL.md +93 -0
  145. package/skills/detection-sweep/scripts/sweep.ts +80 -0
  146. package/skills/domain-modeling-design/README.md +57 -0
  147. package/skills/domain-modeling-design/SKILL.md +83 -0
  148. package/skills/frontend-fullstack-implementation/README.md +60 -0
  149. package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
  150. package/skills/frontend-spec-call-site-audit/README.md +66 -0
  151. package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
  152. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
  153. package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
  154. package/skills/merge-request-review/README.md +60 -0
  155. package/skills/merge-request-review/SKILL.md +77 -0
  156. package/skills/merge-request-review/templates/mr-review-report.md +29 -0
  157. package/skills/production-incident-diagnostic/README.md +63 -0
  158. package/skills/production-incident-diagnostic/SKILL.md +103 -0
  159. package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
  160. package/skills/qa-session-intake/README.md +56 -0
  161. package/skills/qa-session-intake/SKILL.md +78 -0
  162. package/skills/recording-decisions/README.md +91 -0
  163. package/skills/recording-decisions/SKILL.md +84 -0
  164. package/skills/recurring-bug-root-cause/README.md +64 -0
  165. package/skills/recurring-bug-root-cause/SKILL.md +93 -0
  166. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
  167. package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
  168. package/skills/refactoring-shared-component-api/README.md +50 -0
  169. package/skills/refactoring-shared-component-api/SKILL.md +84 -0
  170. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
  171. package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
  172. package/skills/validating-features-end-to-end/README.md +50 -0
  173. package/skills/validating-features-end-to-end/SKILL.md +90 -0
  174. package/skills/visual-regression-check/README.md +51 -0
  175. package/skills/visual-regression-check/SKILL.md +89 -0
  176. package/skills/writing-robust-tests/README.md +53 -0
  177. package/skills/writing-robust-tests/SKILL.md +88 -0
  178. package/templates/.adopted.example +8 -0
  179. package/templates/anti-drift.gitlab-ci.yml +23 -0
@@ -0,0 +1,55 @@
1
+ # Rule - `detection-gap-protocol`
2
+
3
+ > If a user finds a P0 before your automation does, the bug is only half the problem - the missing detection is the other half.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `docs/postmortems/**` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/detection-gap-protocol.md`](../../rules/detection-gap-protocol.md) |
11
+ | **Paired skills** | [`production-incident-diagnostic`](../../skills/production-incident-diagnostic/), [`detection-sweep`](../../skills/detection-sweep/), [`recurring-bug-root-cause`](../../skills/recurring-bug-root-cause/) |
12
+
13
+ ## What it enforces
14
+
15
+ When a **P0 regression is reported by a user** - not by CI, E2E, smoke tests, or monitoring - the postmortem must treat the missing detection as a first-class failure. The rule mandates:
16
+
17
+ 1. A postmortem using the dedicated **"detection gap" template**, not the standard one.
18
+ 2. A **"Detection gap" section** analyzing every level that should have caught it.
19
+ 3. A **regression test that would actually have caught the bug**, written at the right level (SPA navigation, mobile, deployed environment).
20
+ 4. A **`detection-gap` label** on the originating ticket.
21
+ 5. A **blocking lint** that rejects a user-reported postmortem lacking the "Detection gap" section.
22
+
23
+ ## Why it matters
24
+
25
+ A fix removes one bug. Understanding **why every automated layer let it through** removes the whole class of bugs. If the response to a user-reported incident is only "we fixed it", the next regression of the same shape reaches users too - the safety net still has the same hole.
26
+
27
+ Making the user the discoverer of a P0 is itself the defect: it means CI, tests, smoke, and monitoring all passed on broken behavior. The protocol forces the team to name which layer failed and to close that layer, so the automation - not the customer - catches the next one. Aggregating the `detection-gap` label over time reveals **families of holes** and tells you where coverage investment pays off most.
28
+
29
+ ## How to apply it
30
+
31
+ ### Analyze every coverage level
32
+
33
+ | Level | Question to answer in the postmortem |
34
+ |-------|--------------------------------------|
35
+ | CI compile/lint | Did the code pass typecheck / lint / clippy? |
36
+ | Unit tests | Did a UT cover the broken invariant? |
37
+ | E2E tests | Did a scenario reproduce the user flow? |
38
+ | Post-deploy smoke | Did the smoke test hit this route? |
39
+ | Synthetic monitoring | Did a probe watch this endpoint in prod? |
40
+
41
+ For each level, state whether it *could* have caught the bug and why it did not.
42
+
43
+ ### Write the test at the level that failed
44
+
45
+ If the bug only manifests after SPA client-side navigation, a unit test that passes in isolation does not close the gap - the regression test must reproduce the real flow that broke.
46
+
47
+ ### Feed the recurring review
48
+
49
+ Label the ticket `detection-gap` so periodic reviews can cluster incidents and prioritize E2E / smoke / monitoring work against the biggest gap families.
50
+
51
+ ## Related
52
+
53
+ - [`production-incident-diagnostic`](../../skills/production-incident-diagnostic/) drives the incident analysis that feeds the postmortem.
54
+ - [`detection-sweep`](../../skills/detection-sweep/) proactively hunts for the gaps before a user does.
55
+ - [`recurring-bug-root-cause`](../../skills/recurring-bug-root-cause/) handles the case where the same class of bug keeps returning.
@@ -0,0 +1,62 @@
1
+ # Rule - `error-handling-discipline`
2
+
3
+ > No error is ever swallowed and no fallible call ever crashes production. Every failure is either propagated or handled - explicitly, with context.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.vue`, `**/*.py`, `**/*.go`, `**/*.rs`, `**/*.php`, `**/*.java` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/error-handling-discipline.md`](../../rules/error-handling-discipline.md) |
11
+ | **Paired rule** | [`secure-logging`](secure-logging.md) |
12
+
13
+ ## What it enforces
14
+
15
+ Disciplined failure handling across every backend and frontend language in scope:
16
+
17
+ - **No swallowed error**: no empty `catch {}`, no log-and-continue as if nothing happened, no `except: pass`, no ignored `_ = err`.
18
+ - **No crash on a fallible op in prod**: no `unwrap()` / `expect()` / `panic!`, no unguaranteed `!!` / `!`, no forced cast on a value that can fail - return or propagate a typed error. (Tolerated in tests.)
19
+ - **Propagate or handle - pick one**: surface it (`Result` / `throw` / `raise`) or deal with it (fallback, bounded retry, user message). Never in between.
20
+ - **Enrich context before propagating**: which operation, which non-sensitive identifier - not a bare message.
21
+ - **Distinguish expected vs unexpected**: business errors handled locally; unexpected ones bubble to a boundary that decides and alerts.
22
+
23
+ ## Why it matters
24
+
25
+ A swallowed error is the most expensive kind of bug: the system keeps running on corrupt state, and the failure surfaces far from its cause - often as a mysterious downstream symptom that costs hours to trace. A `.unwrap()` on a value that can be absent turns a recoverable condition into a full crash.
26
+
27
+ The middle ground - logging an error and continuing anyway - is the worst of both: you neither recover cleanly nor stop the damage. Forcing an **explicit** choice between propagating and handling makes the failure path a designed part of the code, not an afterthought. Enriching context at each boundary means the log line that finally reaches you says *which operation on which entity failed*, turning a debugging session into a glance.
28
+
29
+ ## How to apply it
30
+
31
+ ### Swallowing vs propagating
32
+
33
+ ```ts
34
+ // Bad - swallowed, state now inconsistent
35
+ try { await save(order); } catch (e) { console.log(e); }
36
+
37
+ // Good - enrich and propagate
38
+ try {
39
+ await save(order);
40
+ } catch (cause) {
41
+ throw new Error(`persisting order ${order.id} failed`, { cause });
42
+ }
43
+ ```
44
+
45
+ ### Fallible operations in Rust
46
+
47
+ ```rust
48
+ // Bad - crashes prod if the row is missing
49
+ let user = repo.find(id).unwrap();
50
+
51
+ // Good - propagate a typed error
52
+ let user = repo.find(id)?;
53
+ ```
54
+
55
+ ### Expected vs unexpected
56
+
57
+ Handle an expected business error (e.g. "email already taken") right where the use case can react. Let an unexpected error (DB down, invariant violated) bubble to a boundary - an HTTP error handler, a job supervisor - that maps it to a response and alerts.
58
+
59
+ ## Related
60
+
61
+ - [`secure-logging`](secure-logging.md) - enrich context with **non-sensitive** identifiers only; never log the payload.
62
+ - Companion rule: [`clean-architecture-deps`](clean-architecture-deps.md) - errors cross layer boundaries as typed values.
@@ -0,0 +1,58 @@
1
+ # Rule - `minimal-code`
2
+
3
+ > The best code is the code you don't write - but "less code" means less surface to maintain, never fewer characters at the cost of clarity.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.rs`, `**/*.ts`, `**/*.tsx`, `**/*.vue`, `**/*.py`, `**/*.go` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/minimal-code.md`](../../rules/minimal-code.md) |
11
+
12
+ ## What it enforces
13
+
14
+ Before adding code, walk down a hierarchy and stop at the first level that meets the need:
15
+
16
+ 1. **Is the need real?** No speculation (YAGNI) - code only what is asked or proven necessary.
17
+ 2. **Does the stdlib / language already do it?**
18
+ 3. **Does an already-installed dependency do it?** Check the manifest before adding a lib or reimplementing.
19
+ 4. **Does an existing component / module / function in the project do it?** Reuse before duplicating.
20
+ 5. **Otherwise, write the simplest solution** that covers exactly the case at hand.
21
+
22
+ And a hard guardrail: **readability beats brevity**. Minimizing code is not minimizing lines. Cryptic one-liners, nested operator chains, and stripped-out intermediate names are failures, not wins.
23
+
24
+ ## Why it matters
25
+
26
+ Every line is a liability: it must be read, tested, reviewed, and maintained forever. Code you avoid writing - because the stdlib, a dependency, or an existing helper already covers it - has zero maintenance cost and zero bug surface. Speculative generality (the "we might need it later" abstraction) is pure cost against a benefit that usually never arrives.
27
+
28
+ But the goal is often misread as "shortest code wins", which produces dense, unreadable expressions that are *harder* to maintain than the verbose version - the opposite of the intent. The rule draws the line explicitly: delete **superfluous** code (premature abstractions, empty wrappers, unused options), never **compress useful** code. A well-named intermediate variable and an early return are worth more than a saved line.
29
+
30
+ ## How to apply it
31
+
32
+ ### Reuse before reimplementing
33
+
34
+ ```ts
35
+ // Before writing a dedupe loop - the language already does it
36
+ const unique = [...new Set(items)];
37
+
38
+ // Before adding a date lib - check package.json for one already present
39
+ ```
40
+
41
+ ### Delete surface, don't compress it
42
+
43
+ ```ts
44
+ // Bad - "one line" at the cost of readability
45
+ const r = xs.filter(x=>x.a&&x.b).map(x=>x.a*x.b).reduce((s,v)=>s+v,0)||0;
46
+
47
+ // Good - same behavior, named steps, early clarity
48
+ const eligible = xs.filter((x) => x.a && x.b);
49
+ const products = eligible.map((x) => x.a * x.b);
50
+ const total = products.reduce((sum, v) => sum + v, 0);
51
+ ```
52
+
53
+ > Arbitration rule: if the shortest code is less clear than slightly longer code, choose the clearer one. The target is *less surface to maintain*, not *fewer characters*.
54
+
55
+ ## Related
56
+
57
+ - Companion rule: [`clean-architecture-deps`](clean-architecture-deps.md) - reuse across layers instead of duplicating logic.
58
+ - Companion rule: [`error-handling-discipline`](error-handling-discipline.md) - the simplest solution still handles failure explicitly.
@@ -0,0 +1,57 @@
1
+ # Rule - `no-raw-sql-interpolation`
2
+
3
+ > A query is code; a value is data. Never stitch the two together by hand - parameterize, always.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.ts`, `**/*.js`, `**/*.py`, `**/*.go`, `**/*.rs`, `**/*.php`, `**/*.java` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/no-raw-sql-interpolation.md`](../../rules/no-raw-sql-interpolation.md) |
11
+ | **Paired skill** | [`audit-security`](../../skills/audit-security/) |
12
+
13
+ ## What it enforces
14
+
15
+ - **Never build a query by interpolation/concatenation** of an input: no `format!`, template string, f-string, or `+` injecting a value into SQL.
16
+ - **Parameterized queries only**: bound placeholders (`$1`, `?`, `:name`) with values passed separately, or a query builder / ORM that parameterizes for you.
17
+ - **Dynamic identifiers** (table/column names, which cannot be parameterized): validate against an **explicit allowlist**, never interpolate raw input.
18
+ - Same principle for neighboring interpreters: NoSQL, LDAP, shell commands - separate code from data.
19
+
20
+ ## Why it matters
21
+
22
+ String-interpolated SQL is the root cause of injection, still one of the most damaging and common vulnerabilities. When a value is concatenated into query text, a crafted input like `'; DROP TABLE users; --` is parsed as *code* rather than *data*. Parameterized queries close this entirely: the driver sends the query structure and the values over separate channels, so a value can never change the query's meaning - no amount of escaping cleverness is needed, and none can be forgotten.
23
+
24
+ Dynamic identifiers are the trap: placeholders bind values, not table or column names, so developers reach for interpolation there. An allowlist keeps that path safe - only known-good identifiers are ever spliced in, and arbitrary input is rejected outright.
25
+
26
+ ## How to apply it
27
+
28
+ ### Parameterize values
29
+
30
+ ```ts
31
+ // Bad - injectable
32
+ db.query(`SELECT * FROM users WHERE email = '${email}'`);
33
+
34
+ // Good - bound placeholder, value sent separately
35
+ db.query('SELECT * FROM users WHERE email = $1', [email]);
36
+ ```
37
+
38
+ ```python
39
+ # Bad
40
+ cur.execute(f"SELECT * FROM users WHERE id = {user_id}")
41
+ # Good
42
+ cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
43
+ ```
44
+
45
+ ### Allowlist dynamic identifiers
46
+
47
+ ```ts
48
+ const SORTABLE = new Set(['created_at', 'name', 'total']);
49
+ if (!SORTABLE.has(sortColumn)) throw new Error('invalid sort column');
50
+ db.query(`SELECT * FROM orders ORDER BY ${sortColumn}`); // safe: value came from the allowlist
51
+ ```
52
+
53
+ ## Related
54
+
55
+ - [`audit-security`](../../skills/audit-security/) reviews injection surfaces as part of a security audit.
56
+ - Companion rule: [`sql-migrations-discipline`](sql-migrations-discipline.md) (the other half of safe database work).
57
+ - Companion rule: [`secure-logging`](secure-logging.md) (don't log the injected value either).
@@ -0,0 +1,54 @@
1
+ # Rule - `pre-commit-secret-detection`
2
+
3
+ > No secret ever reaches a commit. Scan the staged diff every time; treat any pushed secret as compromised.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (always-on) |
8
+ | **Scope (`paths`)** | always active |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/pre-commit-secret-detection.md`](../../rules/pre-commit-secret-detection.md) |
11
+ | **Paired skill** | [`commit-readiness-review`](../../skills/commit-readiness-review/) |
12
+
13
+ ## What it enforces
14
+
15
+ A hard gate: **no credential of any kind is ever committed** - API keys, tokens, passwords, private keys, connection strings. The rule is always active because a leak can happen in any file type, at any commit.
16
+
17
+ ## Why it matters
18
+
19
+ A secret is not "removed" by a later commit. Once it exists in git history - and especially once it is pushed - it must be considered **compromised**: anyone with repo access (now or via a future clone/fork/backup) can recover it. That is why the response to a pushed secret is **rotation on the provider side + history purge**, never a plain `git revert` (which leaves the value in history).
20
+
21
+ The rule is layered so it fails safe:
22
+
23
+ - **Local, tool present** - `gitleaks protect --staged` blocks the commit before the secret lands.
24
+ - **Local, no tool** - a grep fallback on common patterns warns; it does not block, so it never wedges a commit, but it flags the obvious cases.
25
+ - **CI** - `gitleaks detect` over the full repo and history is the backstop that catches anything local checks missed. This CI must never be disabled.
26
+
27
+ ## How to apply it
28
+
29
+ ### Scanning
30
+
31
+ ```bash
32
+ # Preferred: dedicated scanner on the staged diff
33
+ gitleaks protect --staged
34
+
35
+ # Fallback when gitleaks is unavailable
36
+ git diff --cached | grep -nE 'AKIA|BEGIN .* PRIVATE KEY|sk_live_|glpat-|ghp_|(password|secret|token)\s*[:=]'
37
+ ```
38
+
39
+ ### Handling a false positive
40
+
41
+ - **One-off**: add a `gitleaks:allow` comment on the offending line.
42
+ - **Systemic**: add an allowlist entry to `.gitleaks.toml` (by path or by value regex).
43
+ - **Never** silence a finding by disabling the scan.
44
+
45
+ ### Handling a real secret
46
+
47
+ 1. Do **not** commit. Move the value to an environment variable or a secret manager (in a gitignored file).
48
+ 2. If already committed locally but **not pushed**: `git reset --soft HEAD~1`, then remove the value.
49
+ 3. If already **pushed**: rotate the credential immediately on the provider side, then purge history with `git filter-repo`.
50
+
51
+ ## Related
52
+
53
+ - [`commit-readiness-review`](../../skills/commit-readiness-review/) orchestrates this check as its secret-scan step before a commit.
54
+ - Companion rule: `secure-logging` (never log sensitive data).
@@ -0,0 +1,53 @@
1
+ # Rule - `secure-logging`
2
+
3
+ > Logs are forever and widely read. Personal data and secrets never belong in them - log an identifier, not the thing itself.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.rs`, `**/*.ts` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/secure-logging.md`](../../rules/secure-logging.md) |
11
+ | **Paired skills** | [`audit-security`](../../skills/audit-security/), [`audit-compliance`](../../skills/audit-compliance/) |
12
+
13
+ ## What it enforces
14
+
15
+ - **Absolute rule**: never log an email, IP, token, hash, or secret in logs or traces (`warn!`, `error!`, `info!`, `console.log`, application logger…).
16
+ - Use **non-personal identifiers** (`user_id`, `org_id`, `*_id`) in place of the data itself.
17
+ - Every new database field must be **classified** (Public / Internal / Confidential).
18
+
19
+ ## Why it matters
20
+
21
+ Logs flow to places production data never should: aggregation platforms, third-party observability vendors, developer laptops, long-lived archives, and support tooling. Anything written to a log is effectively distributed and retained beyond the app's own access controls. Logging an email or IP therefore turns an ordinary log line into a GDPR-relevant personal-data processing - and logging a token or secret hands an attacker with log access a live credential.
22
+
23
+ Referencing a stable `user_id` instead of the email gives you the same debuggability (you can still correlate, trace, and support) with none of the exposure. Classifying every new field at design time makes the "can this be logged?" question answerable by construction rather than discovered during an incident.
24
+
25
+ ## How to apply it
26
+
27
+ ### Log the identifier, not the data
28
+
29
+ ```ts
30
+ // Bad - leaks PII / a live secret into the log sink
31
+ logger.info(`login for ${email} with token ${accessToken}`);
32
+
33
+ // Good - correlate by non-personal id
34
+ logger.info('login', { user_id: user.id });
35
+ ```
36
+
37
+ ```rust
38
+ // Bad
39
+ tracing::warn!("rate limit hit for {}", client_ip);
40
+ // Good
41
+ tracing::warn!(org_id = %org.id, "rate limit hit");
42
+ ```
43
+
44
+ ### Classify new fields
45
+
46
+ When adding a column, tag it Public / Internal / Confidential in the schema or data catalog, and let that classification decide whether it may ever appear in a log or trace.
47
+
48
+ > The rule intentionally leaves project-specific identifiers, the CI lint, and the full classification policy to a project-level rule and `docs/security`.
49
+
50
+ ## Related
51
+
52
+ - [`audit-security`](../../skills/audit-security/) and [`audit-compliance`](../../skills/audit-compliance/) review logging exposure and data governance.
53
+ - Companion rule: [`error-handling-discipline`](error-handling-discipline.md) - enrich error context with ids, never with the sensitive payload.
@@ -0,0 +1,58 @@
1
+ # Rule - `sql-migrations-discipline`
2
+
3
+ > Migrations are append-only history. Never rewrite an applied one, and never block production with a single destructive step.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/migrations/**/*.sql`, `**/migrate/**/*.sql`, `**/db/migrate/**/*` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/sql-migrations-discipline.md`](../../rules/sql-migrations-discipline.md) |
11
+ | **Paired skill** | [`database-schema-evolution`](../../skills/database-schema-evolution/) |
12
+
13
+ ## What it enforces
14
+
15
+ - **Never modify an already-applied migration**: most tools (SQLx, Flyway, Liquibase, Alembic, Knex…) store a checksum; editing breaks validation. Fix forward with a **new** migration.
16
+ - **Idempotence**: `IF NOT EXISTS` / `IF EXISTS` on DDL, conditional logic in a block (`DO $$ … $$` in PostgreSQL).
17
+ - **Table with production data → two-step (expand-contract)**: add *nullable* → backfill → add the constraint. Never a single blocking step.
18
+ - **Risky operations** (drop, rename, type change, `NOT NULL` on a populated table): route through expand-contract and a backward-compatible change.
19
+ - **Validate from a clean state**: replay all migrations on a fresh database before pushing, not just the last one.
20
+ - Regenerate compiled query artifacts (prepared queries, generated types) after any change touching queries.
21
+
22
+ ## Why it matters
23
+
24
+ Migration tools trust their checksums to know what has run. Editing an applied migration desynchronizes every environment that already ran the old version - teammates and production diverge silently, and the tool refuses to proceed or, worse, skips the change. Forward-only migrations keep every environment on the same deterministic path.
25
+
26
+ The two-step / expand-contract discipline exists because a single destructive change on a live table can lock it, break the currently-deployed code, or fail halfway with no clean rollback. Adding a column as nullable, backfilling, then tightening the constraint keeps the old and new code both working during the deploy window - the essence of a zero-downtime schema change. Replaying from a clean database catches migrations that only "work" because of accumulated local state.
27
+
28
+ ## How to apply it
29
+
30
+ ### Idempotent DDL
31
+
32
+ ```sql
33
+ CREATE TABLE IF NOT EXISTS invoices (id uuid PRIMARY KEY);
34
+ ALTER TABLE invoices ADD COLUMN IF NOT EXISTS status text;
35
+ ```
36
+
37
+ ### Expand-contract for a NOT NULL column on a populated table
38
+
39
+ ```sql
40
+ -- Migration N: expand (nullable, non-blocking)
41
+ ALTER TABLE users ADD COLUMN country text;
42
+
43
+ -- App deploy backfills / starts writing country
44
+
45
+ -- Migration N+2: contract (now safe to constrain)
46
+ ALTER TABLE users ALTER COLUMN country SET NOT NULL;
47
+ ```
48
+
49
+ ### Validate from scratch before pushing
50
+
51
+ ```bash
52
+ # Drop + recreate a throwaway DB, then replay every migration in order
53
+ ```
54
+
55
+ ## Related
56
+
57
+ - [`database-schema-evolution`](../../skills/database-schema-evolution/) plans and reviews schema changes end to end.
58
+ - Companion rule: [`no-raw-sql-interpolation`](no-raw-sql-interpolation.md) (safe queries against the evolved schema).
@@ -0,0 +1,63 @@
1
+ # Rule - `subscription-cleanup`
2
+
3
+ > Anything that subscribes or registers must have a matching teardown - or it leaks memory, fires ghost handlers, and runs twice.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`, `**/*.vue` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/subscription-cleanup.md`](../../rules/subscription-cleanup.md) |
11
+ | **Paired skill** | [`refactoring-shared-component-api`](../../skills/refactoring-shared-component-api/) |
12
+
13
+ ## What it enforces
14
+
15
+ Every resource that subscribes or registers is explicitly torn down:
16
+
17
+ - **Observables / streams**: `unsubscribe()`, a completion operator (`takeUntil(destroy$)`, `takeUntilDestroyed()`, `take(1)`), or the `async` pipe / lifecycle-managed binding. Never a bare `.subscribe(`.
18
+ - **Listeners**: every `addEventListener` / `on(...)` has a matching `removeEventListener` / `off(...)` on teardown.
19
+ - **Timers**: every recurring `setInterval` / `setTimeout` is cancelled.
20
+ - **Watchers / reactive effects**: keep the handle and stop it, or use a self-managing lifecycle API (`watchEffect`, effect scope).
21
+ - **Cancellable requests**: `AbortController` aborted on teardown or dependency change.
22
+ - Cleanup lives in the end-of-life hook (`onUnmounted`, `ngOnDestroy`, `useEffect` cleanup, `Drop`…), never "later".
23
+
24
+ ## Why it matters
25
+
26
+ A subscription without teardown is a slow-motion outage. Each time a component mounts, it registers another listener or stream; when it unmounts without cleanup, that registration survives - holding references (a memory leak) and still reacting to events (a ghost handler). Navigate back and forth a few times and the same callback fires three, five, ten times, causing duplicated network calls, doubled state updates, and bugs that only appear after a while and are miserable to reproduce.
27
+
28
+ Binding cleanup to the component's own lifecycle hook makes teardown deterministic: it happens exactly when the thing that created the subscription goes away, not on a hopeful "later" that never comes. This is the single most common source of leaks in long-lived SPA sessions.
29
+
30
+ ## How to apply it
31
+
32
+ ### Never a bare subscribe
33
+
34
+ ```ts
35
+ // Bad - leaks on every re-render / re-navigation
36
+ source$.subscribe((v) => this.value = v);
37
+
38
+ // Good - completes with the component
39
+ source$.pipe(takeUntilDestroyed()).subscribe((v) => this.value = v);
40
+ ```
41
+
42
+ ### Match every registration
43
+
44
+ ```ts
45
+ // React
46
+ useEffect(() => {
47
+ const onResize = () => measure();
48
+ window.addEventListener('resize', onResize);
49
+ const id = setInterval(poll, 5000);
50
+ const ctrl = new AbortController();
51
+ fetch(url, { signal: ctrl.signal });
52
+ return () => {
53
+ window.removeEventListener('resize', onResize);
54
+ clearInterval(id);
55
+ ctrl.abort();
56
+ };
57
+ }, []);
58
+ ```
59
+
60
+ ## Related
61
+
62
+ - [`refactoring-shared-component-api`](../../skills/refactoring-shared-component-api/) - when reworking a shared component, audit its teardown paths.
63
+ - Companion rule: [`ui-states-complete`](ui-states-complete.md) (the other half of robust async UI).
@@ -0,0 +1,66 @@
1
+ # Rule - `test-discipline`
2
+
3
+ > Tests wait for state, not for the clock; select by intent, not by fragile markup; and every feature and bug ships with the tests that prove it.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.spec.ts`, `**/*.test.ts` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/test-discipline.md`](../../rules/test-discipline.md) |
11
+ | **Paired skills** | [`writing-robust-tests`](../../skills/writing-robust-tests/), [`comprehensive-test-strategy`](../../skills/comprehensive-test-strategy/) |
12
+
13
+ ## What it enforces
14
+
15
+ - **Zero `waitForTimeout`** - wait for a state/locator, never an arbitrary delay.
16
+ - **`data-testid` selectors only** - no bare `text=` nor fragile CSS selector.
17
+ - **Scoped locators** (`parent.getByTestId('child')`) - no ambiguous global locator.
18
+ - **Page objects** for E2E - no selectors scattered across specs.
19
+ - **FIRST** principles: Fast, Isolated, Repeatable, Self-validating, Timely.
20
+ - Every feature/fix → **UT + E2E + API** tests (deterministic golden dataset).
21
+ - Every bug → one UT + one E2E confirmation test written **with** the fix.
22
+
23
+ ## Why it matters
24
+
25
+ Arbitrary sleeps are the number-one source of flaky E2E suites: too short and the test races the app, too long and the suite crawls - and either way the timeout says nothing about the actual condition you care about. Waiting for a state or locator makes the test both faster and deterministic.
26
+
27
+ Selecting by visible text or CSS couples the test to wording and styling that change for reasons unrelated to behavior, so refactors break green tests and teams learn to distrust the suite. A stable `data-testid` expresses *what* element matters, decoupled from *how* it looks. Scoping the locator and centralizing selectors in page objects keeps that intent unambiguous and maintainable as the UI grows.
28
+
29
+ Shipping the confirming tests **with** each feature and each fix is what makes coverage real: a bug that arrives with a failing-then-passing test can never silently regress again.
30
+
31
+ ## How to apply it
32
+
33
+ ### Wait for state, not time
34
+
35
+ ```ts
36
+ // Bad - flaky and slow
37
+ await page.waitForTimeout(2000);
38
+ expect(await page.locator('.result').count()).toBe(1);
39
+
40
+ // Good - deterministic
41
+ await expect(page.getByTestId('result')).toBeVisible();
42
+ ```
43
+
44
+ ### Scoped, intent-based selectors via a page object
45
+
46
+ ```ts
47
+ class OrdersPage {
48
+ constructor(private page: Page) {}
49
+ row(id: string) {
50
+ return this.page.getByTestId(`order-row-${id}`);
51
+ }
52
+ status(id: string) {
53
+ return this.row(id).getByTestId('status'); // scoped, not global
54
+ }
55
+ }
56
+ ```
57
+
58
+ ### Bug → regression test with the fix
59
+
60
+ Write a unit test reproducing the bug and an E2E test reproducing the user flow, commit them alongside the fix so the pair proves the fix and guards against recurrence.
61
+
62
+ ## Related
63
+
64
+ - [`writing-robust-tests`](../../skills/writing-robust-tests/) turns uncovered code into resilient tests.
65
+ - [`comprehensive-test-strategy`](../../skills/comprehensive-test-strategy/) plans the UT/E2E/API layering for a feature.
66
+ - Companion rule: [`detection-gap-protocol`](detection-gap-protocol.md) (the test that *would have* caught a user-found bug).
@@ -0,0 +1,52 @@
1
+ # Rule - `ui-states-complete`
2
+
3
+ > Every async view answers four questions - loading, error, empty, success - and never leaves the user staring at an ambiguous blank or an eternal spinner.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (path-scoped) |
8
+ | **Scope (`paths`)** | `**/*.tsx`, `**/*.jsx`, `**/*.vue`, `**/*.svelte` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/ui-states-complete.md`](../../rules/ui-states-complete.md) |
11
+ | **Paired skills** | [`frontend-fullstack-implementation`](../../skills/frontend-fullstack-implementation/), [`design-system-component-lifecycle`](../../skills/design-system-component-lifecycle/) |
12
+
13
+ ## What it enforces
14
+
15
+ Any view fed by an async operation handles all four states, each distinguishable (ideally a distinct `data-testid`):
16
+
17
+ - **loading**: visual feedback while waiting - never a frozen screen.
18
+ - **error**: actionable message + retry when possible - never a silent failure or an infinite spinner.
19
+ - **empty**: explicit "0 results" state, distinct from loading - not an ambiguous blank page.
20
+ - **success**: the nominal content.
21
+
22
+ Plus the invariants: a failed promise must **end** the loading state; states must not overlap (no "loading + error" together); and this applies to *any* async block - page, list, form submission, request-fed widget.
23
+
24
+ ## Why it matters
25
+
26
+ The success path is the one developers naturally build; the other three are where real users spend a surprising amount of their time - on slow networks, on empty accounts, and when things fail. A view that only models success degrades badly at exactly those moments: a spinner that never resolves because the promise rejected, a blank page that could mean "loading", "no data", or "broken" with no way to tell, an error that vanishes silently and leaves the user stuck.
27
+
28
+ Treating the four states as a required set turns these from afterthoughts into designed behavior. Making each state distinguishable (a dedicated `data-testid`) also makes them **testable** - the E2E suite can assert that a failed request shows the error state and stops the spinner, closing the most common class of frontend "it just hangs" bugs.
29
+
30
+ ## How to apply it
31
+
32
+ ### Model the states explicitly
33
+
34
+ ```tsx
35
+ function OrderList() {
36
+ const { status, data, error, refetch } = useOrders();
37
+
38
+ if (status === 'loading') return <Spinner data-testid="orders-loading" />;
39
+ if (status === 'error')
40
+ return <ErrorBox data-testid="orders-error" onRetry={refetch}>{error.message}</ErrorBox>;
41
+ if (data.length === 0) return <Empty data-testid="orders-empty" />;
42
+ return <ul data-testid="orders-success">{data.map(/* ... */)}</ul>;
43
+ }
44
+ ```
45
+
46
+ Key points: the error branch ends the loading state and offers `retry`; `empty` is a separate branch from `loading`; each state carries its own `data-testid` so the four are never confused - by a user or by a test.
47
+
48
+ ## Related
49
+
50
+ - [`frontend-fullstack-implementation`](../../skills/frontend-fullstack-implementation/) builds views that satisfy this contract.
51
+ - [`design-system-component-lifecycle`](../../skills/design-system-component-lifecycle/) standardizes the four-state components.
52
+ - Companion rule: [`subscription-cleanup`](subscription-cleanup.md) (the other half of robust async UI).
@@ -0,0 +1,66 @@
1
+ ---
2
+ name: name-in-kebab-case
3
+ description: Use when <concrete third-person triggers - symptoms, situations, user verbatims>. Triggers on "<english trigger>", "<another english trigger>", "<french trigger>", "<another french trigger>". <Describe WHEN, not HOW - never summarize the workflow here.>
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: YYYY-MM-DD
7
+ category: audit | feature | bug | frontend | test | process
8
+ ---
9
+
10
+ # Readable title - the principle in one line
11
+
12
+ > If the current repo has an equivalent skill (e.g. acme-app -> `<project-skill>`), it wins - it knows the paths, the tracker and the project commands.
13
+
14
+ ## When ME and not X
15
+
16
+ - **ME** when: <precise use case>
17
+ - **<neighbour-skill>** instead if: <boundary>
18
+
19
+ ## Principle
20
+
21
+ <1-2 sentences: the central insight, the expected output. What separates a good result from a bad one.>
22
+
23
+ ## Context to gather (before acting)
24
+
25
+ - Framework + commands: read `package.json` / `Cargo.toml` / `Makefile` / CI config
26
+ - Read an existing neighbour and copy its conventions before inventing
27
+ - <project reference data / fixtures / locations>
28
+
29
+ ## Protocol
30
+
31
+ 1. <step>
32
+ 2. <step>
33
+ 3. <step>
34
+
35
+ <For a complex workflow, provide a copyable checklist:>
36
+ ```
37
+ - [ ] Step 1
38
+ - [ ] Step 2
39
+ ```
40
+
41
+ ## Templates
42
+
43
+ - `templates/<x>.md` - <expected output to fill in>
44
+
45
+ ## Pitfalls & rationalizations
46
+
47
+ | Excuse | Reality |
48
+ |--------|---------|
49
+ | "<common excuse>" | <why it is wrong> |
50
+
51
+ ## Exit condition
52
+
53
+ Written as observable outcomes, because this section is what the evaluation
54
+ harness gates on (see `eval.yaml` below).
55
+
56
+ - [ ] <measurable proof the skill reached its goal>
57
+ - [ ] <verification run, output pasted - never "it should pass">
58
+
59
+ ## Tooling
60
+
61
+ - `scripts/<x>.ts` - <runnable static detection: "Run scripts/x.ts">
62
+ - `reference/<x>.md` - <heavy grid / reference loaded on demand>
63
+
64
+ ## Changelog
65
+
66
+ - 1.0.0 (YYYY-MM-DD) - initial versioned release