update qa1

.claude/skills/database-guide/SKILL.md

@@ -45,9 +45,25 @@ String jpql = "SELECT SUM(b.netTotal) FROM Bill b WHERE ...";
 - Use DTOs instead of full entities for display
 - Limit result sets with pagination
 
+## Local Development Databases
+
+Each developer machine may have different Payara JDBC pool names and JNDI names. Common local databases:
+
+- **`rh`** — primary dev database (JNDI typically `jdbc/rhDS`)
+- **`ruhunu`** — useful as a testing environment with richer data coverage
+
+When a restored database has **lowercase table names**, it must be converted to uppercase before the app can use it. Generate and run the rename script:
+```sql
+SELECT CONCAT('RENAME TABLE `', table_name, '` TO `temp_', table_name, '`; ',
+              'RENAME TABLE `temp_', table_name, '` TO `', UPPER(table_name), '`;')
+FROM information_schema.tables
+WHERE table_schema = '<db_name>' AND table_name != UPPER(table_name);
+```
+Then pipe the output into mysql for that database. See `src/main/webapp/resources/sql/UpperCase.sql` for reference (note: that file targets a specific schema — always generate fresh from the actual database).
+
 ## Persistence Configuration
 
-- **Development**: Use hardcoded JNDI (`jdbc/rhDS`)
+- **Development**: Use hardcoded JNDI (machine-specific — check your local Payara setup)
 - **Before push**: Must use environment variables (`${JDBC_DATASOURCE}`)
 
 For complete reference, read [developer_docs/database/mysql-developer-guide.md](../../developer_docs/database/mysql-developer-guide.md).

.claude/skills/jsf-ajax/SKILL.md

@@ -3,7 +3,10 @@ name: jsf-ajax
 description: >
   JSF AJAX update rules for the HMIS project. Use when working on AJAX updates,
   p:commandButton update attributes, PrimeFaces AJAX callbacks, partial page rendering,
-  or debugging AJAX update failures. Critical rules to prevent silent AJAX failures.
+  or debugging AJAX update failures. Also covers JSF navigation patterns: why
+  f:viewAction must not be used on @SessionScoped beans, and how initialization
+  belongs in navigation methods. Critical rules to prevent silent AJAX failures
+  and refresh/back-button state corruption.
 user-invocable: true
 ---
 
@@ -61,3 +64,40 @@ The growl component is in `template.xhtml` outside forms. Use absolute ID with c
 5. Check component hierarchy - nested components affect id resolution
 
 For complete reference, read [developer_docs/jsf/ajax-update-guidelines.md](../../developer_docs/jsf/ajax-update-guidelines.md).
+
+---
+
+## Navigation Pattern: Never Use f:viewAction on @SessionScoped Beans
+
+**🚨 Most controllers in this project are `@SessionScoped`. Never use `f:viewAction` or `f:event type="preRenderView"` to initialize state on `@SessionScoped` beans.**
+
+`f:viewAction` fires on every GET — including browser refresh and back-button — silently resetting in-progress state. All initialization belongs in the navigation method that redirects to the page.
+
+### Correct pattern
+
+```java
+// Navigation method — initialize here
+public String navigateToFundTransferBill() {
+    resetClassVariables();
+    prepareToAddNewFundTransferBill();
+    currentBillPayments = new ArrayList<>();
+    return "/cashier/fund_transfer_bill?faces-redirect=true";
+}
+```
+
+```xhtml
+<!-- XHTML — no f:metadata needed -->
+<ui:define name="subcontent">
+    <h:form>...</h:form>
+</ui:define>
+```
+
+### The two legitimate uses of f:viewAction
+
+1. **URL parameter ingestion** — page is reached via external URL with `f:viewParam` query params (lab result links, mobile API, patient portal). No navigation method exists; the URL is the entry point. **Signal: `f:metadata` contains `f:viewParam` elements.**
+
+2. **`@ViewScoped` beans** — bean is created fresh on each page load, so there is no prior navigation method. (Rare in this project — most controllers are `@SessionScoped`.)
+
+If you see `f:viewAction` without any `f:viewParam`, it is almost certainly wrong.
+
+For complete reference, read [developer_docs/jsf/navigation-patterns.md](../../developer_docs/jsf/navigation-patterns.md).

.claude/skills/pharmacy-dev/SKILL.md

@@ -46,6 +46,17 @@ Pharmacy uses `configOptionApplicationController.getBooleanValueByKey()` for fea
 - Cache autocomplete results for converter
 - Defer expensive discount calculations
 
+## GRN Report Testing
+
+When testing GRN / Direct Purchase report changes:
+- The `ruhunu` local database typically has richer GRN data than `rh` and is better for testing
+- Test URL: `http://localhost:8080/rh/faces/reports/inventoryReports/grn.xhtml`
+- Print view (navigated from grn.xhtml): `grn_detailed_view.xhtml`, `grn_summary_view.xhtml`
+- Key bill types: `PHARMACY_GRN`, `PHARMACY_GRN_RETURN`, `PHARMACY_GRN_CANCELLED`, `PHARMACY_DIRECT_PURCHASE`, `PHARMACY_DIRECT_PURCHASE_REFUND`, `PHARMACY_DIRECT_PURCHASE_CANCELLED`
+- `PHARMACY_DIRECT_PURCHASE` bills have **null** `referenceBill` — always null-guard before accessing `bill.getReferenceBill()`
+- Date/time formats in exports must use `sessionController.getApplicationPreference().getLongDateTimeFormat()` — never hardcode
+- Excel/PDF filenames must not contain colons — use `getLongDateFormat()` (not datetime) and sanitize with `.replaceAll("[: /]", "_")`
+
 ## Backward Compatibility
 
 - Never "fix" `purcahseRate` spelling - it's a database column name

.gitleaks.toml

@@ -0,0 +1,82 @@
+# Gitleaks configuration for HMIS project
+# Docs: https://github.com/gitleaks/gitleaks#configuration
+title = "HMIS Gitleaks Configuration"
+
+[extend]
+# Extend the default gitleaks ruleset
+useDefault = true
+
+# ----------------------------------------------------------------
+# Project-specific rules
+# ----------------------------------------------------------------
+[[rules]]
+id = "hmis-db-password-in-xml"
+description = "Hardcoded database password in XML config"
+regex = '''<property[^>]+name=["']javax\.persistence\.jdbc\.password["'][^>]*value=["']([^"']{4,})["']'''
+tags = ["database", "password", "xml"]
+
+[[rules]]
+id = "hmis-glassfish-password"
+description = "GlassFish/Payara admin or datasource password"
+regex = '''<password-alias[^>]+value=["']([^"']{4,})["']'''
+tags = ["appserver", "password"]
+
+[[rules]]
+id = "hmis-jdbc-url-with-host"
+description = "Hardcoded JDBC URL with hostname or IP (may expose server location)"
+regex = '''jdbc:mysql://([a-zA-Z0-9][-a-zA-Z0-9.]{3,})/'''
+tags = ["network", "database"]
+
+# ----------------------------------------------------------------
+# Allowlist: known-safe patterns that would otherwise trigger
+# ----------------------------------------------------------------
+[allowlist]
+description = "Global allowlist for HMIS project"
+
+# Placeholder text in documentation
+regexes = [
+  '''\[password\]''',
+  '''\[your.password\]''',
+  '''\[admin_password\]''',
+  '''\$\{.*password.*\}''',
+  '''password_placeholder''',
+  # JNDI datasource name — not a credential
+  '''jdbc/\w+''',
+  # Test/example IP addresses used in docs
+  '''192\.0\.2\.\d+''',    # TEST-NET-1 (RFC 5737)
+  '''198\.51\.100\.\d+''', # TEST-NET-2
+  '''203\.0\.113\.\d+''',  # TEST-NET-3
+]
+
+paths = [
+  # Migration docs use placeholder [password] — already checked
+  "src/main/resources/db/migrations",
+  # Test fixtures
+  "src/test",
+  # SE training presentation — uses localhost JDBC example for teaching
+  "SE-Principles-Presentation.md",
+  # Developer docs — uses YOUR_GITHUB_TOKEN placeholder
+  "developer_docs/",
+]
+
+# Historical commits: old JPA direct-connect config used password="admin"
+# before the project migrated to JNDI datasources (~2023).
+# "admin" was the local dev default — no production credential.
+# Current persistence.xml uses JNDI only.
+commits = [
+  # Old local-dev persistence.xml with password=admin (pre-JNDI era)
+  "d9fc300aa4c1c93846bcfd49371bfd300a119c56",
+  "07dc0a6ee6618d804e6dc94bd6705fe17b1500a4",
+  "b8c8ffe7153e64879bd93400e0692fa7ec1231f2",
+  "298e386d9a55e1bcaa9cb33072f1131cf9cbd012",
+  "a7e545b47dfcd83833728eb202d89110487c044f",
+  "3b01d6ef577a40af53ad7978c459b3e41188ab5a",
+  # stock_reset_script.py — UUID used as API key variable name (script context unknown)
+  "dfa8ef6563e2c07fde89b8ce8727838c31c8b542",
+  # EncryptionUtils.java placeholder key "MySecretKey12345" — file deleted, example placeholder
+  "97683edf3ca12fa3b1875e7f989c1e15936b188b",
+  # PaymentGatewayController.java — hardcoded test gateway credentials (fixed in current HEAD)
+  "e733b5bbecf9aa61a4b1270fe190c670512f91bd",
+  "278b904e65cc960fa3b76d004d97f2045b878d01",
+  "e16ccefb7c609a5ed45f5aa1482e5e2896170dad",
+]

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Pre-commit hooks for HMIS project
+# Setup: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+# Docs: https://pre-commit.com
+
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks
+        name: Detect secrets with gitleaks
+        description: Blocks commits that contain credentials, API keys, or passwords

CLAUDE.md

@@ -37,6 +37,7 @@
 
 ### When Working on JSF/AJAX
 - [JSF AJAX Update Guidelines](developer_docs/jsf/ajax-update-guidelines.md) - Critical AJAX rules
+- [Navigation Patterns](developer_docs/jsf/navigation-patterns.md) - viewAction anti-pattern, initialization in navigation methods
 - [DataTable Selection Guide](developer_docs/jsf/primefaces-datatable-selection.md) - Selection patterns
 
 ### When Working with DTOs

developer_docs/database/mysql-developer-guide.md

@@ -60,6 +60,47 @@ This guide covers MySQL database development, debugging, and maintenance practic
    chmod 600 ~/.config/hmis/credentials.txt
    ```
 
+## Local Development Databases
+
+Each developer machine configures its own Payara JDBC pools and JNDI names. Common databases used in this project:
+
+- **`rh`** — primary development database
+- **`ruhunu`** — useful secondary database with broader data coverage for testing pharmacy reports
+
+### Setting Up a Payara JDBC Pool (per machine)
+
+```bash
+# Create connection pool
+asadmin create-jdbc-connection-pool \
+  --datasourceclassname com.mysql.cj.jdbc.MysqlDataSource \
+  --restype javax.sql.DataSource \
+  --property "serverName=localhost:portNumber=3306:databaseName=<db>:user=<user>:password=<pass>:useSSL=false:allowPublicKeyRetrieval=true" \
+  <poolName>
+
+# Create JNDI resource
+asadmin create-jdbc-resource --connectionpoolid <poolName> jdbc/<jndiName>
+
+# Test
+asadmin ping-connection-pool <poolName>
+```
+
+### Uppercase Table Names
+
+The application requires **UPPERCASE table names**. If a restored database has lowercase tables, convert them:
+
+```bash
+mysql -u<user> -p<pass> <db_name> -e "
+SELECT CONCAT('RENAME TABLE \`', table_name, '\` TO \`temp_', table_name, '\`; ',
+              'RENAME TABLE \`temp_', table_name, '\` TO \`', UPPER(table_name), '\`;')
+FROM information_schema.tables
+WHERE table_schema = '<db_name>' AND table_name != UPPER(table_name);
+" --skip-column-names | mysql -u<user> -p<pass> <db_name>
+```
+
+Verify afterwards: the query `SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='<db>' AND table_name != UPPER(table_name)` should return 0.
+
+See also: `src/main/webapp/resources/sql/UpperCase.sql` (reference only — always generate fresh from the actual database).
+
 ## MySQL Command Line Operations
 
 ### Basic Connection

developer_docs/deployment/persistence-verification.md

@@ -120,6 +120,24 @@ If you found hardcoded values in Steps 3 or 4:
 6. Verify again with Step 2 and Step 4
 7. Now you can safely commit and push
 
+### Step 6: Preserve "Do NOT Remove" Properties
+
+When reverting or editing `persistence.xml`, ensure the following properties marked `Do NOT Remove` are **always present**:
+
+```xml
+<!-- EclipseLink concurrency manager tuning (issue #19397) - Do NOT Remove -->
+<property name="eclipselink.concurrency.manager.waittime" value="10000"/>
+<property name="eclipselink.concurrency.manager.allow.concurrencyexception" value="true"/>
+<property name="eclipselink.concurrency.manager.maxfrequencytodumptinymessage" value="5000"/>
+
+<!-- Sequence pre-allocation fix for SEQUENCE table lock contention (issue #19626) - Do NOT Remove -->
+<property name="eclipselink.sequence.default-sequence-preallocation-size" value="50"/>
+```
+
+These are production-critical tuning properties. Removing them causes:
+- **Concurrency manager properties**: cache lock waits of up to 900 seconds, silent hangs instead of fast-fail errors
+- **Sequence preallocation**: each ID allocation acquires a table-level lock on the SEQUENCE table, causing severe slowness under load (retail sales affected)
+
 ## Why This Matters
 
 ### Local Development vs. QA Deployment

developer_docs/git/commit-conventions.md

@@ -19,3 +19,23 @@ Co-Authored-By: Claude <noreply@anthropic.com>
 
 ## Auto-Close Behavior
 When Claude pushes commits that complete an issue, automatically include the appropriate closing keyword in the commit message.
+
+## Branch Naming Conventions
+
+### Hotfix Branches
+When creating hotfix branches targeting production branches (e.g., `ruhunu-prod`), the branch name **must** end with `-hotfix`. This is required for the PR to be mergeable.
+
+**Format:** `<issue-number>-<description>-hotfix`
+
+**Examples:**
+- `19635-configurable-bill-serial-digits-hotfix`
+- `19500-fix-grn-return-hotfix`
+
+### Feature Branches
+Feature branches should be based on `origin/development` (never `master`) and follow the pattern:
+
+**Format:** `<issue-number>-<description>`
+
+**Examples:**
+- `19635-configurable-bill-number-serial-digits`
+- `19500-fix-grn-return-approval`