@wazir-dev/cli 1.0.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 (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
@@ -0,0 +1,400 @@
1
+ # PostgreSQL -- Expertise Module
2
+
3
+ > PostgreSQL specialist responsible for designing, optimizing, and administering relational databases.
4
+ > Scope covers schema design, query optimization, replication, security hardening, backup/recovery,
5
+ > and operational excellence for PostgreSQL 16+ in both self-hosted and managed environments.
6
+
7
+ ---
8
+
9
+ ## Core Patterns & Conventions
10
+
11
+ ### Schema Design Conventions
12
+
13
+ **Naming:** Tables: plural `snake_case` (`order_items`). Columns: singular `snake_case` (`created_at`). PKs: `id` as `BIGINT GENERATED ALWAYS AS IDENTITY`. FKs: `<table_singular>_id`. Indexes: `idx_<table>_<cols>`. Constraints: `chk_`/`uq_` prefix. Booleans: `is_`/`has_` prefix.
14
+
15
+ **Data Types:**
16
+ - `BIGINT GENERATED ALWAYS AS IDENTITY` over `SERIAL` (SQL-standard, PG 10+)
17
+ - `timestamptz` always; never bare `timestamp` (ambiguous across timezones)
18
+ - `text` over `varchar(n)` unless a hard DB-enforced length limit is needed
19
+ - `numeric`/`integer` for money; never `float`/`double precision`
20
+ - `uuid` for external IDs; `bigint` for internal PKs
21
+ - `inet`/`cidr` for IPs; `daterange`/`tstzrange` for temporal ranges
22
+
23
+ **Constraints:** Default to `NOT NULL`. Use `CHECK` for domain rules (`CHECK (price >= 0)`). Prefer DB-level `UNIQUE` over app-level checks. Use `EXCLUDE` for range overlaps. Define FKs with explicit `ON DELETE` behavior.
24
+
25
+ ### Indexing Strategies
26
+
27
+ | Type | Use Case | Notes |
28
+ |------|----------|-------|
29
+ | **B-tree** | Equality, range, ORDER BY | Default; covers 95% of cases; supports index-only scans |
30
+ | **GIN** | Full-text search, JSONB `@>`, arrays | Use `jsonb_path_ops` for containment-only queries (smaller, faster) |
31
+ | **GiST** | PostGIS geometry, range types, FTS (write-heavy) | Lossy; faster builds than GIN; proximity/nearest-neighbor |
32
+ | **BRIN** | Naturally-ordered append-only data (timestamps) | Up to 1000x smaller than B-tree; requires correlated physical order |
33
+ | **Hash** | Equality-only `=` lookups | WAL-logged since PG 10; rarely beats B-tree |
34
+
35
+ **Partial indexes:** `CREATE INDEX idx_orders_pending ON orders(created_at) WHERE status = 'pending'` -- dramatically smaller and cheaper to maintain.
36
+ **Covering indexes:** `CREATE INDEX ... ON orders(user_id) INCLUDE (total, status)` -- enables index-only scans for extra columns.
37
+ **Expression indexes:** `CREATE INDEX ... ON users(lower(email))` -- must match the exact expression in queries.
38
+
39
+ ### Migration Patterns and Tools
40
+
41
+ | Tool | Approach | Best For |
42
+ |------|----------|----------|
43
+ | **Flyway** | Versioned SQL scripts | Java/JVM teams, CI/CD pipelines |
44
+ | **Liquibase** | Changelog (XML/YAML/SQL) | Enterprise teams needing rollback plans |
45
+ | **Prisma Migrate** | Declarative schema DSL | TypeScript full-stack teams |
46
+ | **Atlas** | Declarative HCL/SQL | "Terraform for databases" approach |
47
+ | **dbmate** | Plain SQL up/down files | Lightweight, language-agnostic |
48
+ | **Alembic** | Python migration scripts | SQLAlchemy / Python teams |
49
+
50
+ **Rules:** Migrations must be idempotent (`IF NOT EXISTS`). Never modify applied migrations. Include `up`+`down` scripts. Use `CREATE INDEX CONCURRENTLY`. Separate DDL from DML. Lint with `squawk` or `pgspot` in CI.
51
+
52
+ ### Query Patterns
53
+
54
+ **CTEs:** PG 12+ auto-inlines CTEs when beneficial. Use `MATERIALIZED`/`NOT MATERIALIZED` to override.
55
+ **Window functions:** `RANK()`, `LAG()`, `LEAD()` with `PARTITION BY` + `ORDER BY` for analytics without self-joins.
56
+ **LATERAL joins:** Row-by-row correlated subqueries -- ideal for "top-N per group" patterns.
57
+ **Bulk operations:** Use `COPY` or multi-row `INSERT` (up to 100x faster than row-by-row).
58
+
59
+ ### Connection Management
60
+
61
+ pgBouncer is the standard pooler. Use `transaction` mode (connection returned after each transaction) for most workloads. Use `session` mode only when you need prepared statements, LISTEN/NOTIFY, or temp tables. Sizing: `(num_pools x default_pool_size) < max_connections - 15`. For CPU-bound OLTP, set `max_connections` to 2-4x vCPU count. Deploy multiple pgBouncer instances behind HAProxy for HA.
62
+
63
+ ### Transaction Isolation Levels
64
+
65
+ | Level | When to Use | Trade-off |
66
+ |-------|-------------|-----------|
67
+ | **Read Committed** (default) | 90% of OLTP workloads | Non-repeatable reads between statements |
68
+ | **Repeatable Read** | Reporting, analytics, consistent multi-statement reads | Must retry on serialization failure |
69
+ | **Serializable** | Financial ops, inventory, double-booking prevention | Highest retry rate; always implement retry logic |
70
+
71
+ PG silently upgrades `Read Uncommitted` to `Read Committed`.
72
+
73
+ ### JSONB Usage Patterns
74
+
75
+ **Use for:** variable-schema metadata, event payloads, sparse attributes, user preferences.
76
+ **Avoid for:** fixed schemas (use columns), frequently filtered/joined data, deeply nested docs (5+ levels), large documents (>2KB triggers TOAST overhead).
77
+ **Best practice:** Hybrid -- typed columns for fixed attributes, `metadata JSONB` for variable data. Index with GIN (`jsonb_path_ops` for `@>` only). **Caveat:** PG cannot collect statistics inside JSONB -- planner uses hardcoded 0.1% selectivity estimate, leading to poor plans. Extract hot keys to typed columns.
78
+
79
+ ### Partitioning Strategies
80
+
81
+ **Range:** Time-series data (partition by month/week). **List:** Categorical data (tenant, region). **Hash:** No natural key; even distribution.
82
+ **When:** Table exceeds server RAM or >50-100M rows; queries consistently filter on partition key; need fast bulk deletes (DROP PARTITION). **Limits:** Keep to a few dozen to a few hundred partitions; avoid <10K rows per partition. Automate creation with cron or `pg_partman`.
83
+
84
+ ---
85
+
86
+ ## Anti-Patterns & Pitfalls
87
+
88
+ ### 1. Using `SELECT *` in Production Queries
89
+ Forces heap fetches for every row, defeating index-only scans. Breaks app code when columns change. Always specify exact columns needed.
90
+
91
+ ### 2. Missing Indexes on Foreign Keys
92
+ PG does NOT auto-index FK columns. JOINs and cascading DELETE/UPDATE degrade to sequential scans -- O(n) per operation on the referenced table.
93
+
94
+ ### 3. Using `timestamp` Without Time Zone
95
+ Stores wall-clock time with no timezone context. Values become ambiguous when servers/clients operate in different timezones. Always use `timestamptz` (stores UTC, converts on display).
96
+
97
+ ### 4. Long-Running Transactions
98
+ MVCC keeps old row versions for any open transaction. Hours-long transactions prevent autovacuum from reclaiming dead tuples across ALL tables, causing persistent bloat. Monitor `pg_stat_activity` for `idle in transaction`.
99
+
100
+ ### 5. Not Tuning Autovacuum for High-Churn Tables
101
+ Default `scale_factor = 0.2` means vacuum waits for 20% dead rows. For a 100M-row table, that is 20M dead rows. Set per-table: `ALTER TABLE hot_table SET (autovacuum_vacuum_scale_factor = 0.01)`.
102
+
103
+ ### 6. Using `OFFSET` for Pagination
104
+ `OFFSET N` scans and discards N rows. Page 1000 scans 1000 x page_size rows. Use keyset pagination: `WHERE (created_at, id) < (:last_created_at, :last_id) ORDER BY created_at DESC, id DESC LIMIT 20`.
105
+
106
+ ### 7. Read-Modify-Write Without Proper Locking
107
+ Read, modify in app, write back = race condition. Concurrent sessions cause lost updates. Use atomic SQL (`SET balance = balance - 100`), `SELECT ... FOR UPDATE`, or Serializable isolation.
108
+
109
+ ### 8. Using `SERIAL` Instead of Identity Columns
110
+ `SERIAL` has loose coupling -- values can be manually set, `pg_dump`/restore causes sequence drift. `GENERATED ALWAYS AS IDENTITY` enforces DB control (SQL-standard, PG 10+).
111
+
112
+ ### 9. Storing ENUMs as Text Strings
113
+ `'pending'`/`'active'` wastes storage per row, inflates indexes. Use PG `ENUM` types for small stable sets, or a lookup table with integer FK for mutable sets.
114
+
115
+ ### 10. Using `NOT IN` with Nullable Columns
116
+ `NOT IN (subquery)` returns zero rows if any subquery value is NULL (three-valued logic). Use `NOT EXISTS` instead -- handles NULLs correctly and often yields better anti-join plans.
117
+
118
+ ### 11. Over-Indexing Write-Heavy Tables
119
+ Each index adds maintenance cost to every INSERT/UPDATE/DELETE (5-10x write slowdown with 10+ indexes). Increases WAL volume and replication lag. Audit with `pg_stat_user_indexes`; drop indexes with `idx_scan = 0`.
120
+
121
+ ### 12. UUIDv4 as Primary Key
122
+ Random UUIDs destroy B-tree locality -- index page splits, fragmentation, cache misses. Inserts drop from ~72K/s (BIGINT) to ~13K/s. Use UUIDv7 (time-sorted, `pg_uuidv7` extension) or BIGINT PK + UUID column for external exposure.
123
+
124
+ ### 13. `CREATE INDEX` Without `CONCURRENTLY`
125
+ Standard `CREATE INDEX` acquires SHARE lock, blocking all writes. Hours of downtime on large tables. Always use `CONCURRENTLY` in production (cannot run inside a transaction).
126
+
127
+ ### 14. ORM `synchronize: true` in Production
128
+ TypeORM's `synchronize` / Prisma's `db push` can drop columns, alter types, remove constraints without warning. Use migration files in all non-dev environments.
129
+
130
+ ### 15. No `statement_timeout` on Application Connections
131
+ Without timeout, bad queries run for hours, holding locks, blocking autovacuum. Set `statement_timeout = '30s'` per role. Use longer timeouts for batch/admin connections.
132
+
133
+ ---
134
+
135
+ ## Testing Strategy
136
+
137
+ **Approaches:** Unit-test functions/triggers/constraints with pgTAP. Integration-test queries against real PG (never SQLite). Run migration up/down/up in CI. Property-test constraint enforcement with random data.
138
+
139
+ **Test data:** Use factories (`factory_bot`, `fishery`, `faker.js`) over static fixtures. Use `TRUNCATE ... CASCADE` (not DELETE) for fast cleanup. Snapshot with `pg_dump` for known-good states.
140
+
141
+ **pgTAP example:**
142
+ ```sql
143
+ BEGIN;
144
+ SELECT plan(3);
145
+ SELECT has_table('users');
146
+ SELECT has_column('users', 'email');
147
+ SELECT col_is_unique('users', 'email');
148
+ SELECT * FROM finish();
149
+ ROLLBACK;
150
+ ```
151
+ Run with `pg_prove -d mydb tests/*.sql`. `runtests()` auto-rolls back each test.
152
+
153
+ **Migration testing:** Validate reversibility (up/down/up). Compare schema with `pg_dump --schema-only`. Test against anonymized production data. Lint with `squawk`/`pgspot`.
154
+
155
+ **Isolation:** Each test in its own `BEGIN`/`ROLLBACK`. For committed data, use template databases (`CREATE DATABASE test_x TEMPLATE test_base`). `pgtestdb` (Go) creates ephemeral DBs from cached templates in milliseconds.
156
+
157
+ ---
158
+
159
+ ## Performance Considerations
160
+
161
+ ### EXPLAIN ANALYZE Interpretation
162
+ ```sql
163
+ EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
164
+ ```
165
+ - **Seq Scan:** OK for <10K rows or >5-10% selectivity; investigate otherwise
166
+ - **Index Scan → heap fetch:** Good for selective queries
167
+ - **Index Only Scan:** Best case; requires up-to-date visibility map (VACUUM)
168
+ - **Buffers shared hit/read:** `hit` = cache; `read` = disk I/O. High `read` = cache miss
169
+ - **rows vs actual rows mismatch:** Stale statistics; run `ANALYZE`
170
+
171
+ ### Query Optimization
172
+ Run `ANALYZE` after bulk loads. Rewrite `NOT IN` as `NOT EXISTS`. Use keyset pagination. Avoid bare functions in WHERE (or create expression indexes). Use `EXISTS` not `COUNT(*) > 0`. Use `COPY` for bulk inserts. Use `ANY(ARRAY[...])` over long `IN (...)` lists.
173
+
174
+ ### Autovacuum Tuning (PostgreSQL 16+)
175
+ ```ini
176
+ autovacuum_max_workers = 4 # default 3
177
+ autovacuum_vacuum_scale_factor = 0.05 # default 0.2
178
+ autovacuum_analyze_scale_factor = 0.02 # default 0.1
179
+ autovacuum_vacuum_cost_delay = 2ms # default 2ms (PG12+)
180
+ autovacuum_vacuum_cost_limit = 1000 # default 200
181
+ autovacuum_naptime = 15s # default 60s
182
+ ```
183
+ Monitor: `SELECT relname, n_dead_tup, last_autovacuum FROM pg_stat_user_tables ORDER BY n_dead_tup DESC;`
184
+
185
+ ### Memory Tuning
186
+
187
+ | Parameter | Setting | Notes |
188
+ |-----------|---------|-------|
189
+ | `shared_buffers` | 25% RAM (max 40%) | PG internal cache; OS handles the rest |
190
+ | `effective_cache_size` | 50-75% RAM | Not an allocation; tells planner expected cache |
191
+ | `work_mem` | 32-256 MB | Per-operation (sorts, hashes); multiply by connections for worst case |
192
+ | `maintenance_work_mem` | 512 MB - 2 GB | VACUUM, CREATE INDEX |
193
+ | `random_page_cost` | 1.1 (SSD) | Default 4.0 assumes HDD |
194
+ | `effective_io_concurrency` | 200 (SSD) | Default 1 assumes HDD |
195
+
196
+ **Rule:** `shared_buffers + effective_cache_size <= 0.97 * total_RAM`
197
+
198
+ ### Monitoring
199
+ - **pg_stat_statements:** Query execution stats (essential; enable in `shared_preload_libraries`)
200
+ - **pg_stat_user_tables/indexes:** Dead tuples, unused indexes (`idx_scan = 0`)
201
+ - **pg_stat_activity:** Active queries, idle-in-transaction, wait events
202
+ - **auto_explain:** Logs plans for slow queries (`log_min_duration = 3s`)
203
+ - **pgBadger:** Log analysis into HTML reports
204
+ - **Datadog/Grafana:** Real-time dashboards from pg_stat_statements
205
+
206
+ ---
207
+
208
+ ## Security Considerations
209
+
210
+ ### Role-Based Access Control
211
+ Create per-responsibility roles: `app_readonly`, `app_readwrite`, `app_admin`, `migration_runner`. Grant minimum privileges. Never use `postgres` superuser for app connections. Revoke `CREATE ON SCHEMA public FROM PUBLIC`. Use `ALTER DEFAULT PRIVILEGES` for future objects.
212
+
213
+ ### Row-Level Security (RLS)
214
+ ```sql
215
+ ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
216
+ ALTER TABLE orders FORCE ROW LEVEL SECURITY;
217
+ CREATE POLICY tenant_isolation ON orders
218
+ USING (tenant_id = current_setting('app.tenant_id')::bigint)
219
+ WITH CHECK (tenant_id = current_setting('app.tenant_id')::bigint);
220
+ ```
221
+ Always `FORCE` RLS (owners bypass otherwise). Index policy columns. Test with non-superuser accounts. Avoid non-`LEAKPROOF` functions (prevent index usage). Set session vars at connection time, never from user input.
222
+
223
+ ### SSL/TLS and Authentication
224
+ Set `ssl = on`, `ssl_min_protocol_version = 'TLSv1.3'` in postgresql.conf. Use `hostssl` in pg_hba.conf with `scram-sha-256` (never `md5` or `trust` over TCP). Client-side: `sslmode=verify-full`.
225
+
226
+ ### SQL Injection Prevention
227
+ Always use parameterized queries. Never interpolate user input. Set `statement_timeout` to limit blast radius.
228
+
229
+ ### Audit Logging
230
+ Use `pgaudit` extension: `pgaudit.log = 'write, ddl'` logs all data modifications and schema changes.
231
+
232
+ ### Encryption
233
+ **In transit:** SSL/TLS. **At rest:** OS/cloud-level (LUKS, dm-crypt, RDS default encryption). **Column-level:** `pgcrypto` (`pgp_sym_encrypt`). **Keys:** Store outside DB (AWS KMS, Vault). PG has no native TDE.
234
+
235
+ ---
236
+
237
+ ## Integration Patterns
238
+
239
+ ### ORM Best Practices
240
+ - **Prisma:** Type-safe; use `prisma migrate` not `db push` in prod; vendor lock-in via proprietary DSL
241
+ - **Drizzle:** Generates single optimized SQL; up to 14x lower latency than N+1-prone ORMs
242
+ - **TypeORM:** Never `synchronize: true` in prod; validate generated migration SQL
243
+ - **SQLAlchemy:** Prefer `Core` over `ORM` for complex queries; use scoped sessions
244
+ - **General:** Review generated SQL in dev. Eager-load to avoid N+1. Use raw SQL for CTEs/window functions/LATERAL. Match ORM pool size to pgBouncer's `default_pool_size`.
245
+
246
+ ### Replication
247
+ **Streaming (physical):** Byte-for-byte replica. HA failover + read scaling. Sync mode for zero data loss.
248
+ **Logical (PG 10+):** Publish/subscribe. Replicate specific tables or filtered rows (PG 15+ WHERE). Use for cross-version upgrades. Does NOT replicate DDL or sequences.
249
+
250
+ ### LISTEN/NOTIFY for Real-Time
251
+ ```sql
252
+ CREATE OR REPLACE FUNCTION notify_change() RETURNS TRIGGER AS $$
253
+ BEGIN
254
+ PERFORM pg_notify('order_changes', json_build_object('op', TG_OP, 'id', NEW.id)::text);
255
+ RETURN NEW;
256
+ END; $$ LANGUAGE plpgsql;
257
+ ```
258
+ Ideal for low-medium rates (hundreds/sec). Payload max 8KB. Transactional (delivered on COMMIT). Use `pg_eventserv` for WebSocket bridging. For high throughput, pair with Redis/Kafka.
259
+
260
+ ### Full-Text Search
261
+ ```sql
262
+ ALTER TABLE articles ADD COLUMN search_vector tsvector GENERATED ALWAYS AS (
263
+ setweight(to_tsvector('english', coalesce(title,'')), 'A') ||
264
+ setweight(to_tsvector('english', coalesce(body,'')), 'B')
265
+ ) STORED;
266
+ CREATE INDEX idx_articles_search ON articles USING GIN (search_vector);
267
+ ```
268
+ Good for small-to-medium datasets. Use `pg_trgm` for `LIKE '%pattern%'`. For faceting/fuzzy/synonyms, consider Elasticsearch or ParadeDB.
269
+
270
+ ### PostGIS
271
+ Use `geography` for lat/lon; `geometry` for projected coordinates. GiST indexes for spatial queries (`ST_DWithin`, `ST_Distance`, `ST_Contains`).
272
+
273
+ ---
274
+
275
+ ## DevOps & Deployment
276
+
277
+ ### Backup Strategies
278
+
279
+ | Method | Type | RPO |
280
+ |--------|------|-----|
281
+ | `pg_dump`/`pg_dumpall` | Logical | Point-in-time of dump |
282
+ | `pg_basebackup` + WAL | Physical | Seconds (PITR) |
283
+ | **pgBackRest** | Physical + WAL | Seconds; incremental, parallel, encrypted, S3/GCS |
284
+ | **Barman** | Physical + WAL | Seconds; strong Patroni integration |
285
+
286
+ Test restores monthly. Store backups in a different region/account. Retain 7+ days PITR (30 for compliance).
287
+
288
+ ### High Availability
289
+ **Patroni** (recommended): Cluster orchestration with auto-failover via etcd/Consul/ZooKeeper. Deploy across 3+ AZs. Pair with pgBackRest. Architecture: `etcd (3 nodes) -> Patroni (primary + replicas) -> HAProxy/pgBouncer -> App`.
290
+ **repmgr:** Lighter alternative; less automation, simpler setup.
291
+
292
+ ### Docker
293
+ Use `postgres:16-alpine` or `postgres:17-alpine`. Named volumes for data. Enable `--data-checksums`. Health check: `pg_isready`. Docker is excellent for dev/CI; prefer VMs or managed for production.
294
+
295
+ ### Managed vs Self-Hosted
296
+ Managed (RDS/Cloud SQL/Supabase): low ops, limited extensions, higher cost at scale. Self-hosted (Patroni): full control, any extension, lower cost but requires DBA expertise. Supabase for instant APIs + auth. Neon for serverless scale-to-zero.
297
+
298
+ ### Alerting
299
+ **Page immediately:** replication lag >30s, disk >85%, connections >80% of max, queries >5min, failed autovacuum.
300
+ **Warning:** dead tuples growing, cache hit ratio <99%, checkpoint storms, lock waits increasing.
301
+
302
+ ---
303
+
304
+ ## Decision Trees
305
+
306
+ ### Which Index Type?
307
+ ```
308
+ Equality (=)? --> B-tree
309
+ Range (<, >, BETWEEN, ORDER BY)? --> B-tree
310
+ Full-text (tsvector @@ tsquery)? --> GIN (read-heavy) or GiST (write-heavy)
311
+ JSONB containment (@>), arrays? --> GIN (jsonb_path_ops for @> only)
312
+ Geospatial (PostGIS)? --> GiST
313
+ Append-only, naturally ordered? --> BRIN (large tables only)
314
+ Subset of rows? --> Add WHERE clause (partial index)
315
+ Need index-only scan extras? --> Add INCLUDE clause (covering index)
316
+ Function in WHERE? --> Expression index
317
+ ```
318
+
319
+ ### Managed vs Self-Hosted?
320
+ ```
321
+ Team < 5 engineers? --> Managed
322
+ Need extensions not on managed platforms? --> Self-host (Patroni)
323
+ DB spend > $5K/mo + have DBA expertise? --> Self-host (cost savings)
324
+ DB spend > $5K/mo but no DBA? --> Managed (ops cost offsets)
325
+ Serverless / bursty? --> Neon
326
+ Need instant APIs + auth + realtime? --> Supabase
327
+ Multi-region active-active? --> Aurora or CockroachDB
328
+ ```
329
+
330
+ ### When to Partition?
331
+ ```
332
+ Table > 50-100M rows or exceeds server RAM? --> Yes
333
+ Queries filter on partition key consistently? --> Range (dates) or List (categories)
334
+ No natural key? --> Hash partitioning
335
+ Need fast bulk deletes of old data? --> Range + DROP PARTITION
336
+ Otherwise? --> Do not partition (overhead not justified)
337
+ ```
338
+
339
+ ---
340
+
341
+ ## Code Examples
342
+
343
+ ### 1. Safe Migration: Add Column + Concurrent Index
344
+ ```sql
345
+ -- PG 11+ does NOT rewrite table for non-volatile defaults. Fast on billion-row tables.
346
+ ALTER TABLE users ADD COLUMN is_verified BOOLEAN NOT NULL DEFAULT false;
347
+ CREATE INDEX CONCURRENTLY idx_users_unverified ON users (is_verified) WHERE is_verified = false;
348
+ ```
349
+
350
+ ### 2. Keyset Pagination
351
+ ```sql
352
+ -- First page
353
+ SELECT id, title, created_at FROM articles
354
+ WHERE published = true ORDER BY created_at DESC, id DESC LIMIT 20;
355
+ -- Next page (pass last row's values)
356
+ SELECT id, title, created_at FROM articles
357
+ WHERE published = true AND (created_at, id) < (:last_created_at, :last_id)
358
+ ORDER BY created_at DESC, id DESC LIMIT 20;
359
+ ```
360
+ Constant performance at any depth -- unlike OFFSET which degrades linearly.
361
+
362
+ ### 3. Upsert with Conflict Handling
363
+ ```sql
364
+ INSERT INTO product_inventory (product_id, warehouse_id, quantity)
365
+ VALUES (:product_id, :warehouse_id, :quantity)
366
+ ON CONFLICT (product_id, warehouse_id) DO UPDATE SET
367
+ quantity = product_inventory.quantity + EXCLUDED.quantity,
368
+ updated_at = NOW()
369
+ RETURNING *;
370
+ ```
371
+
372
+ ### 4. Advisory Locks for Job Coordination
373
+ ```sql
374
+ SELECT pg_try_advisory_lock(hashtext('process_batch_42')); -- non-blocking acquire
375
+ -- ... exclusive work ...
376
+ SELECT pg_advisory_unlock(hashtext('process_batch_42'));
377
+ ```
378
+ Lightweight, never conflict with row/table locks. Ideal for preventing duplicate background job processing.
379
+
380
+ ### 5. Production postgresql.conf (32 GB RAM, 8 vCPU, SSD)
381
+ ```ini
382
+ max_connections = 200
383
+ shared_buffers = 8GB
384
+ effective_cache_size = 24GB
385
+ work_mem = 64MB
386
+ maintenance_work_mem = 2GB
387
+ random_page_cost = 1.1
388
+ effective_io_concurrency = 200
389
+ max_wal_size = 4GB
390
+ checkpoint_completion_target = 0.9
391
+ autovacuum_max_workers = 4
392
+ autovacuum_vacuum_scale_factor = 0.05
393
+ autovacuum_vacuum_cost_limit = 1000
394
+ log_min_duration_statement = 1000
395
+ shared_preload_libraries = 'pg_stat_statements, auto_explain, pgaudit'
396
+ ```
397
+
398
+ ---
399
+
400
+ *Researched: 2026-03-07 | Sources: [PostgreSQL Official Docs v18](https://www.postgresql.org/docs/current/), [Instaclustr Best Practices 2025](https://www.instaclustr.com/education/postgresql/top-10-postgresql-best-practices-for-2025/), [PostgreSQL Wiki - Don't Do This](https://wiki.postgresql.org/wiki/Don't_Do_This), [Percona Index Guide](https://www.percona.com/blog/a-practical-guide-to-postgresql-indexes/), [Sachith Indexing Playbook 2026](https://www.sachith.co.uk/postgresql-indexing-playbook-practical-guide-feb-12-2026/), [MyDBOps Tuning 2025](https://www.mydbops.com/blog/postgresql-parameter-tuning-best-practices), [AWS JSONB Patterns](https://aws.amazon.com/blogs/database/postgresql-as-a-json-database-advanced-patterns-and-best-practices/), [Bytebase Flyway vs Liquibase 2026](https://www.bytebase.com/blog/flyway-vs-liquibase/), [Permit.io RLS Guide](https://www.permit.io/blog/postgres-rls-implementation-guide), [Bytebase RLS Footguns](https://www.bytebase.com/blog/postgres-row-level-security-footguns/), [CYBERTEC Autovacuum](https://www.cybertec-postgresql.com/en/tuning-autovacuum-postgresql/), [pgTAP](https://pgtap.org/), [Brandur Notifier Pattern](https://brandur.org/notifier), [OneUpTime PG Tuning 2026](https://oneuptime.com/blog/post/2026-02-20-postgresql-performance-tuning/view), [SQLFlash Managed PG 2026](https://sqlflash.ai/article/20260114_aws-azure-gcp-supabase-postgresql-2026/), [EDB Security Hardening](https://www.enterprisedb.com/blog/how-to-secure-postgresql-security-hardening-best-practices-checklist-tips-encryption-authentication-vulnerabilities)*