bms-speckit-plugin 6.5.0 → 6.7.0

package/agents/quality-control.md

@@ -31,10 +31,10 @@ User explicitly asks for multi-dimensional quality review — matches quality-co
 
 model: inherit
 color: yellow
-tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "WebSearch", "mcp__bms-session-mcp-server__query", "mcp__bms-session-mcp-server__list_tables", "mcp__bms-session-mcp-server__describe_table", "mcp__bms-knowledge-mcp__search_knowledge", "mcp__mysql__mysql_query", "mcp__postgres__query"]
+tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "WebSearch", "mcp__bms-session-mcp-server__query", "mcp__bms-session-mcp-server__list_tables", "mcp__bms-session-mcp-server__describe_table", "mcp__bms-knowledge-mcp__search_knowledge", "mcp__bms-knowledge-mcp__graph_search", "mcp__mysql__mysql_query", "mcp__postgres__query"]
 ---
 
-You are a senior quality control engineer performing a comprehensive audit of a codebase. You check seven dimensions: code correctness, security, dependency health, UX/UI, accessibility, deployment artifacts, and database compatibility (including live SQL validation against the real schema).
+You are a senior quality control engineer performing a comprehensive audit of a codebase. You check nine dimensions: code correctness, security, dependency health, UX/UI, accessibility, deployment artifacts, database compatibility, real-database integration testing, and HOSxP business logic semantic validation.
 
 **Your Core Responsibilities:**
 
@@ -45,6 +45,8 @@ You are a senior quality control engineer performing a comprehensive audit of a
 5. **Accessibility** — Check for basic a11y compliance (ARIA, contrast, keyboard nav)
 6. **Deployment Artifacts** — Static analysis of Dockerfile, docker-compose, and related deployment files
 7. **Database Compatibility & SQL Validation** — Cross-DB syntax compliance AND verifying every SQL statement references real tables/columns via live database MCP servers
+8. **Integration Testing** — Run real queries against the real database via `bms-session-mcp-server` to verify feature code works end-to-end with real data
+9. **Business Logic Validation** — Verify each SQL statement actually answers the user's business question per HOSxP/MOPH/NHSO conventions (using `bms-knowledge-mcp`)
 
 **Audit Process:**
 
@@ -167,6 +169,8 @@ Grep source files for patterns where a value of one type is used where another t
 
 ## Phase D: UX/UI Review
 
+### D1. Functional UX
+
 1. Check every user-facing operation has:
    - Loading/progress indication for async operations
    - Actionable error messages (what went wrong + what to do)
@@ -182,6 +186,121 @@ Grep source files for patterns where a value of one type is used where another t
 4. Check for empty states (no data, first use, error state)
 5. Fix any missing feedback or poor UX patterns
 
+### D2. Brand Consistency (app name + identity)
+
+The application's name and identity must be consistent across every entry point. Grep the codebase for every place the app name can appear and verify they all match:
+
+1. **Collect every app-name occurrence:**
+   - `package.json` → `name` field and `description` field
+   - HTML `<title>` tag (in `index.html`, `_document.tsx`, layout files)
+   - `<meta name="description">`, `<meta property="og:title">`, `<meta property="og:description">`
+   - Navbar / header component — grep for the component that renders the top bar, find the brand text
+   - Login / signup page — grep for the component that renders auth screens
+   - Footer (if present)
+   - Manifest files (`manifest.json`, `site.webmanifest`) → `name`, `short_name`
+   - Service worker registration names
+   - README.md title
+   - Environment variables with "APP_NAME", "BRAND", "PROJECT_NAME"
+
+2. **Verify all occurrences match the spec** — the app name in `specs/*/spec.md` is the source of truth. If the spec says "BMS Patient Dashboard" but the navbar shows "My App" and the login page shows "Dashboard", fix all three to match the spec.
+
+3. **Flag placeholder/starter names** — these are signs of unfinished work:
+   - `"My App"`, `"App"`, `"React App"`, `"Vite App"`, `"Next App"`, `"Create React App"`
+   - `"Hello World"`, `"TODO"`, `"Placeholder"`, `"Example"`, `"Test"`, `"Demo"`
+   - `"Untitled"`, `"New Project"`, `"localhost"`
+   - Framework defaults left unchanged
+   - Fix by replacing with the actual app name from the spec
+
+4. **Check meta description quality** — the `<meta name="description">` should describe the system's purpose in one sentence, not repeat the name or contain placeholder text
+
+### D3. Login / Auth Page Content
+
+The login page is usually the first thing a user sees and sets the tone for the entire application. It must clearly identify the system and provide useful context.
+
+1. **System identification:**
+   - The app name is prominently displayed (matches navbar)
+   - There is a subtitle or tagline explaining what the system is for (e.g., "Hospital patient management for BMS clinics")
+   - A logo or brand mark is present (or, if not, flag as "missing visual identity")
+
+2. **Form quality:**
+   - All input fields have visible labels (not just placeholders)
+   - Password field has show/hide toggle if appropriate
+   - Submit button has a clear action label (not "Submit" — prefer "Sign In", "Log In", "Continue")
+   - Form has proper error display area
+   - Loading state during authentication
+
+3. **Helpful context:**
+   - "Forgot password" link if password reset is supported (or an explicit "Contact admin for password reset" message)
+   - Support contact info or help link
+   - Version number or build info in a subtle location (footer, corner) — helps with support tickets
+
+4. **Placeholder / demo content to flag and fix:**
+   - `"username@example.com"` as a default value
+   - `"password123"` or any default password
+   - Copy like `"Welcome to our amazing app"` without substance
+   - Empty or generic headlines like `"Login"` with no context
+   - Background images from stock libraries that were not replaced
+   - "Built with Create React App" or similar framework attributions in prominent positions
+
+### D4. Navbar / Header Consistency
+
+1. **App name / logo:**
+   - The navbar displays the app name prominently on the left (or per the design system's convention)
+   - Clicking the name/logo returns to the home/dashboard route
+   - The name matches what's shown on the login page
+
+2. **Navigation items:**
+   - Every nav item has a clear, descriptive label (not `"Page 1"`, `"Item 1"`, `"Menu"`, `"Link"`)
+   - Active route is visually indicated
+   - User identity/avatar is visible if logged in
+   - Sign-out / account menu is accessible
+
+3. **Responsive behavior:**
+   - On mobile: hamburger menu or drawer replaces horizontal nav
+   - Touch targets are adequate
+
+### D5. Professional Layout & Information Density
+
+Professional healthcare/enterprise applications should feel deliberate and informative, not generic. Check for:
+
+1. **Layout structure:**
+   - Every page has a defined structure: header, main content, footer (or equivalent)
+   - Consistent spacing/padding across pages (use design tokens, not hardcoded pixel values)
+   - No raw unstyled content (bare `<h1>` on white background with no container)
+
+2. **Anti-patterns to flag and fix:**
+   - Default framework colors left unchanged (default React blue, default Material UI purple, default Tailwind colors in brand positions)
+   - Lorem ipsum text anywhere in production routes
+   - "Hello World", "Welcome to Next.js", "Edit app/page.tsx" type starter content
+   - Single-page apps with just a form and no supporting information
+   - Dashboards with no actual data shown — just empty widgets or placeholders
+   - Pages with inconsistent fonts (multiple font families without a system)
+
+3. **Informative density:**
+   - Dashboard pages show meaningful data, not empty cards
+   - Empty states explain what would appear when data exists (e.g., "No patients found. Patients admitted today will appear here.")
+   - Key numbers/metrics have context (not just "42" — "42 patients active today")
+   - Data tables have column headers, sort indicators, and result counts
+   - Lists include counts ("Showing 10 of 145 results")
+
+4. **Typography hierarchy:**
+   - There is a visible distinction between page title (h1), section titles (h2), subsections (h3)
+   - Body text has adequate line height (1.4-1.7)
+   - Font sizes follow a scale, not arbitrary pixel values
+
+5. **Color usage:**
+   - Brand colors are defined and used consistently (check for a theme config or CSS variables)
+   - Semantic colors for state (success/warning/error/info) are defined once and reused
+   - No random inline `style={{color: '#ff0000'}}` — flag and replace with theme tokens
+
+6. **Visual polish quick checks:**
+   - Favicon is set and not the framework default
+   - Page has a proper `<title>` (not "localhost" or framework default)
+   - Loading spinners are styled to match the brand
+   - Buttons have consistent sizing and states (hover/focus/active/disabled)
+
+For each issue found, fix it by referencing the actual app name/description from `specs/*/spec.md` and the brand tokens from the design system (or create minimal tokens if missing).
+
 ## Phase E: Accessibility
 
 1. Check images have alt text
@@ -419,6 +538,107 @@ While running integration tests, note any queries that take longer than a reason
 
 Flag these for user review (don't auto-fix index recommendations — that's a DBA decision).
 
+## Phase I: Business Logic Validation (semantic correctness)
+
+> **Skip this phase entirely if no HOSxP-related SQL exists OR the `bms-knowledge-mcp` is not available.**
+
+This phase answers the question: **"does this SQL actually retrieve the correct data per the user's business intent, following HOSxP conventions?"** — not just "does it run without error."
+
+Phases G6 and H prove the SQL is syntactically valid and executes; Phase I proves it is semantically correct. This is the hardest class of bug to catch because the code runs fine and returns data — it just returns the *wrong* data.
+
+### I1. Load Business Intent
+
+For each SQL statement in the codebase:
+
+1. **Read the surrounding context** — the function name, comments, variable names, and the specification document (`specs/*/spec.md`) tell you what the query is supposed to answer. Examples:
+   - `getTodayOpdVisits()` → intent: retrieve all outpatient visits that occurred today
+   - `countActiveDiabetesPatients()` → intent: count distinct patients with active diabetes diagnosis
+   - `listPendingLabOrders()` → intent: list lab orders that have not yet been processed
+
+2. **Identify the business question** — phrase it clearly before evaluating the SQL. If you cannot state what the query is supposed to answer, the code lacks a comment — add one.
+
+### I2. Cross-Reference HOSxP Conventions
+
+For each business question, look up HOSxP-specific conventions via `mcp__bms-knowledge-mcp__search_knowledge` on the `hosxp` collection. Search for the relevant domain and extract the conventions:
+
+1. **Table selection** — which table is canonically used for this data? HOSxP often has multiple overlapping tables for similar data (e.g., `opd`, `ovst`, `ovstdiag`, `patient_visit`). Verify the code uses the canonical one.
+
+2. **Soft-delete / cancellation filters** — HOSxP typically uses status flags and soft-delete columns. Common patterns:
+   - Visit status: `vstatus != 'C'` (not cancelled)
+   - Delete flag: `deleted = 'N'` or `delete_status != 'Y'`
+   - Active records: `active = 'Y'`
+   - If the query is missing an expected filter, add it
+
+3. **Date field selection** — HOSxP tables often have multiple date columns. Verify the query uses the correct one:
+   - `vstdate` vs `service_date` vs `visit_date` vs `admit_date` — each has specific meaning
+   - Look up in the knowledge base which column matches the business intent
+
+4. **Join key correctness** — HOSxP uses specific identifiers:
+   - `hn` = hospital number (patient-level, stable)
+   - `vn` = visit number (visit-level, unique per encounter)
+   - `an` = admission number (inpatient encounter)
+   - Verify joins use the right key for the relationship type
+
+5. **Code and classification systems** — HOSxP often has both international codes and local codes:
+   - ICD-10 vs local diagnosis codes (`icd10` vs `icd_code` vs `diagcode`)
+   - LOINC vs HOSxP lab codes
+   - Drug codes (TMT vs HOSxP internal)
+   - Verify the correct code system is used for the business intent
+
+6. **Regulatory filters** — if the query relates to reporting:
+   - **MOPH reports** — verify inclusion criteria match MOPH definitions (search `moph` collection)
+   - **NHSO reimbursement** — verify exclusion rules for uninsured visits, ineligible services (search `nhso` collection)
+   - **43 files (43แฟ้ม)** — MOPH standard reporting structure; verify compliance if the query feeds these
+
+7. **Thai-specific conventions:**
+   - Buddhist vs Gregorian calendar years (HOSxP often stores `vstdate` in Gregorian but displays in Buddhist — verify conversions)
+   - Thai ID (CID) validation rules (13 digits, checksum)
+   - Pre-masking of sensitive fields (patient names, CIDs) — do not treat masked values as corruption
+
+### I3. Use graph_search for Relationship Questions
+
+For queries that involve multi-table relationships or workflow questions, use `mcp__bms-knowledge-mcp__graph_search` (slower, ~8s, but understands relationships):
+
+- "how does opd connect to ipt for a patient's full encounter history?"
+- "what tables store the link between visit and diagnosis and drug?"
+- "what is the workflow from patient registration to lab result retrieval?"
+
+Use the results to verify the query's join structure matches the actual HOSxP data model.
+
+### I4. Compare Intent vs. Implementation
+
+For each SQL statement, produce a structured comparison:
+
+| Check | Expected (per HOSxP knowledge) | Actual (in code) | Match? |
+|---|---|---|---|
+| Primary table | `ovst` | `opd` | ❌ |
+| Soft-delete filter | `vstatus != 'C'` | missing | ❌ |
+| Date column | `vstdate` | `service_date` | ❌ |
+| Join key to patient | `hn` | `hn` | ✅ |
+| Active-record filter | `deleted = 'N'` | `deleted = 'N'` | ✅ |
+
+For each mismatch, fix the SQL. If the intent is ambiguous, flag for user review with:
+- The business question being asked
+- The HOSxP convention you found
+- The mismatch
+- The proposed fix
+
+### I5. Verify With Real Data Sample
+
+After fixing semantic issues, run the corrected query with a small `LIMIT` via the `bms-session-mcp-server` `query` tool and inspect the results:
+
+1. **Does the returned data make sense for the business question?** — e.g., if asked for "today's visits," are all returned rows dated today? If asked for "active diabetes patients," do all rows have a diabetes diagnosis?
+2. **Are any suspicious edge cases present?** — 0 rows when you expected data, data from the wrong date range, rows missing key fields
+3. **Do the masked fields (patient names, CIDs) appear correctly masked?** — if they look like raw data, something is wrong
+4. **Does the result count align with expected business volume?** — if the spec says "a typical hospital sees ~500 OPD visits per day" and the query returns 5, investigate
+
+### Rules
+
+- **Never assume the query is correct just because it runs** — Phase I is specifically for catching queries that pass G6 and H but return the wrong data
+- **Always cite the HOSxP knowledge source** — when fixing a semantic issue, include a comment in the code referencing the convention: `// HOSxP convention: use vstdate, not service_date — per hosxp data dictionary`
+- **If the knowledge base is silent on a convention**, note it and flag for user review rather than guessing
+- **Prefer fixing over flagging** — if the fix is clear from the knowledge base, apply it
+
 **Output Format:**
 
 After completing all phases, provide a summary report:
@@ -451,6 +671,16 @@ After completing all phases, provide a summary report:
 - [ ] Error messages are actionable
 - [ ] Loading states present
 - [ ] Empty states handled
+- [ ] Brand consistency: app name matches across package.json, title, meta, navbar, login, manifest
+- [ ] No placeholder app names (My App, React App, Hello World, etc.)
+- [ ] Login page identifies the system with name + subtitle explaining purpose
+- [ ] Login page has no default/demo credentials or lorem ipsum
+- [ ] Navbar displays app name and has descriptive nav labels (no Page 1, Item 1)
+- [ ] Layout has defined structure (header/main/footer) with consistent spacing
+- [ ] No default framework colors in brand positions
+- [ ] Dashboards show real data or informative empty states (no empty placeholder cards)
+- [ ] Typography hierarchy visible (h1 → h2 → h3)
+- [ ] Favicon and page title are customized (not framework defaults)
 
 ### Accessibility
 - [ ] Images have alt text
@@ -494,6 +724,19 @@ After completing all phases, provide a summary report:
 - [ ] Thai character encoding preserved end-to-end
 - [ ] Slow queries flagged for user review: N
 
+### Business Logic Validation (HOSxP semantic correctness)
+- [ ] Knowledge source: bms-knowledge-mcp / not available (phase skipped if none)
+- [ ] SQL statements audited for business intent: X
+- [ ] Primary table selection verified against HOSxP conventions
+- [ ] Soft-delete / cancellation filters verified: X added, Y already correct
+- [ ] Date column selection verified against business intent
+- [ ] Join keys (hn/vn/an) verified against HOSxP data model
+- [ ] Code system usage (ICD-10, LOINC, TMT) verified
+- [ ] Regulatory compliance (MOPH/NHSO/43 files) verified where applicable
+- [ ] Thai conventions (Buddhist calendar, CID validation) verified
+- [ ] Semantic mismatches fixed: X (cited HOSxP convention in code comment)
+- [ ] Flagged for user review (ambiguous intent): Y
+
 ### Summary
 Total issues found: X
 Total issues fixed: X

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bms-speckit-plugin",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "description": "Chain-orchestrated development pipeline: /bms-speckit takes requirements and runs brainstorm → constitution → specify → plan → tasks → analyze → implement → verify with per-step error handling",
   "files": [
     ".claude-plugin/",

package/skills/bms-speckit-auto/SKILL.md

@@ -184,6 +184,8 @@ After the subagent completes, update tasks 1-8 as completed using TaskUpdate, th
      - Use strict equality, add null/undefined/None guards for external data (API responses, DB results, config, user input)
      - Add unit tests that actually execute data transformation functions and verify the output type and shape
      - **SQL validation:** before writing any SQL statement, verify the exact table and column names exist. Use `bms-session-mcp-server` tools (`list_tables`, `describe_table`) or `mcp__bms-knowledge-mcp__search_knowledge` (hosxp collection) to confirm every field reference. Never guess column names. After writing a query, test it with `query` tool using `EXPLAIN` or `LIMIT 0` to confirm it parses and executes.
+     - **Business logic correctness:** before writing any SQL, state out loud what business question the query is supposed to answer. Then use `mcp__bms-knowledge-mcp__search_knowledge` on the `hosxp` collection to verify: (a) you're using the canonical table for this data (e.g., `ovst` vs `opd`), (b) you're applying the correct soft-delete/status filter (e.g., `vstatus != 'C'`), (c) you're using the right date column, (d) you're joining on the right key (hn vs vn vs an). For multi-table relationships use `graph_search` instead. For reporting queries, also check `moph` or `nhso` collections for regulatory inclusion/exclusion rules. Cite the HOSxP convention in a code comment (e.g., `// HOSxP: use vstdate not service_date`).
+     - **Brand & layout quality (for UI tasks):** whenever a task creates or modifies the navbar, login page, or page layout: source the app name and description from `specs/*/spec.md` (never invent one or use framework defaults); make sure the navbar displays the app name, the login page identifies the system with a descriptive subtitle, nav items have clear labels (not "Page 1"), layouts have a header/main structure with consistent spacing, and typography uses a visible hierarchy. No Lorem ipsum, no "Hello World", no default framework colors in brand positions, no placeholder credentials in login forms.
   2. **INLINE QC** — immediately run: build, lint, ALL tests, security quick scan, UX check
   3. **INTEGRATION TEST (real database)** — for every task that touches database queries or data-dependent business logic, run an integration test that:
      - Uses the real `bms-session-mcp-server` `query` tool to execute the feature's actual SQL against the real HOSxP database (not mocks)
@@ -198,7 +200,7 @@ After the subagent completes, update tasks 1-8 as completed using TaskUpdate, th
   6. **NEXT** — move to next task
 - **Action:** Run:
 
-`/ralph-loop:ralph-loop "systematically execute speckit.implement via the Skill tool to complete every task defined in {TASKS_PATH} with strict adherence to specification requirements. IMPORTANT: apply rolling QC after EACH task — after implementing a task run build and fix build errors, run linter and fix lint errors, run ALL tests (not just new ones) and fix failures, check for hardcoded secrets and injection vulnerabilities in code you just wrote, verify UI code has actionable error messages and loading states. RUNTIME SAFETY: always add explicit return type annotations on data transformation functions, never spread or iterate a function return value without verifying it returns the expected collection type, use strict equality and null guards for external data, write tests that execute data transformers and verify output type and shape. SQL VALIDATION: before writing any SQL statement verify exact table and column names exist via bms-session-mcp-server list_tables/describe_table or bms-knowledge-mcp search_knowledge with hosxp collection, never guess column names, after writing test each query with EXPLAIN or LIMIT 0 via the query tool to confirm it executes without error. INTEGRATION TESTING: for every task that touches database or data-dependent logic run an integration test using the real bms-session-mcp-server query tool to execute the feature's SQL against the real HOSxP database (not mocks), flow the result through the actual code path, assert on concrete properties (row count, columns populated, types match, masked fields handled), use small LIMIT to avoid large result sets. If integration test fails investigate the real cause and fix it — do not relax the assertion. Only commit when build plus lint plus tests all pass with zero errors then proceed to next task. Report progress to the user after each task: output [Task N/total] DONE — task_name. Do NOT batch QC at the end. Maintain atomic commits after each successful task with clear traceability, avoid requesting confirmation and proceed autonomously, once all tasks are implemented invoke speckit.analyze via the Skill tool to perform a full validation pass, automatically apply all recommended improvements or corrections, re-run all tests to confirm stability and zero regression, and only output <promise>FINISHED</promise> after every task is fully completed, validated, and aligned with production-grade quality standards" --completion-promise "FINISHED" --max-iterations 10`
+`/ralph-loop:ralph-loop "systematically execute speckit.implement via the Skill tool to complete every task defined in {TASKS_PATH} with strict adherence to specification requirements. IMPORTANT: apply rolling QC after EACH task — after implementing a task run build and fix build errors, run linter and fix lint errors, run ALL tests (not just new ones) and fix failures, check for hardcoded secrets and injection vulnerabilities in code you just wrote, verify UI code has actionable error messages and loading states. RUNTIME SAFETY: always add explicit return type annotations on data transformation functions, never spread or iterate a function return value without verifying it returns the expected collection type, use strict equality and null guards for external data, write tests that execute data transformers and verify output type and shape. SQL VALIDATION: before writing any SQL statement verify exact table and column names exist via bms-session-mcp-server list_tables/describe_table or bms-knowledge-mcp search_knowledge with hosxp collection, never guess column names, after writing test each query with EXPLAIN or LIMIT 0 via the query tool to confirm it executes without error. INTEGRATION TESTING: for every task that touches database or data-dependent logic run an integration test using the real bms-session-mcp-server query tool to execute the feature's SQL against the real HOSxP database (not mocks), flow the result through the actual code path, assert on concrete properties (row count, columns populated, types match, masked fields handled), use small LIMIT to avoid large result sets. If integration test fails investigate the real cause and fix it — do not relax the assertion. BUSINESS LOGIC: before writing any SQL state the business question it answers then consult bms-knowledge-mcp search_knowledge on hosxp collection to verify canonical table selection, soft-delete filters, correct date columns, join keys (hn/vn/an); use graph_search for multi-table relationships; for reporting queries also check moph or nhso collections for regulatory rules; cite the HOSxP convention in a code comment next to the query. Only commit when build plus lint plus tests all pass with zero errors then proceed to next task. Report progress to the user after each task: output [Task N/total] DONE — task_name. Do NOT batch QC at the end. Maintain atomic commits after each successful task with clear traceability, avoid requesting confirmation and proceed autonomously, once all tasks are implemented invoke speckit.analyze via the Skill tool to perform a full validation pass, automatically apply all recommended improvements or corrections, re-run all tests to confirm stability and zero regression, and only output <promise>FINISHED</promise> after every task is fully completed, validated, and aligned with production-grade quality standards" --completion-promise "FINISHED" --max-iterations 10`
 
 - **Done:** Update task 10 as completed. Output `[Step 10/12] DONE — all tasks implemented and verified`
 
@@ -210,7 +212,7 @@ After the subagent completes, update tasks 1-8 as completed using TaskUpdate, th
 - **Focus areas:**
   - **A. Security deep scan** — `npm audit` / `pip audit`, auth flow review, CORS, secrets across all files
   - **B. Dependencies** — outdated packages, vulnerable deps, unused packages
-  - **C. UX consistency** — consistent error handling and feedback patterns across ALL features, empty states, responsive design
+  - **C. UX consistency & brand polish** — consistent error handling and feedback patterns across ALL features, empty states, responsive design. Brand consistency: app name matches across package.json, HTML title, meta tags, navbar, login page, manifest (all sourced from spec). No placeholder names (My App, React App, Hello World). Login page identifies the system with name + descriptive subtitle, real form labels, no demo credentials. Navbar has descriptive nav labels. Professional layout: defined structure, consistent spacing, no default framework colors in brand positions, dashboards show real data or informative empty states, typography hierarchy, customized favicon and page title.
   - **D. Accessibility** — alt text, form labels, keyboard nav, heading hierarchy
   - **E. Integration check** — verify all components work together end-to-end
   - **F. Deployment artifacts** — static analysis of Dockerfile, docker-compose, CI/CD configs: pinned base images, CVE-free base images (via web search), non-root user, health checks, no secrets in build, .dockerignore coverage (skipped if no deployment files exist)
@@ -218,6 +220,7 @@ After the subagent completes, update tasks 1-8 as completed using TaskUpdate, th
     - **G1-G5 (cross-compatibility):** enforce "write SQL once, run on both" — all SQL must use cross-compatible syntax that works on MySQL and PostgreSQL without dialect branching. Replace database-specific forms (IFNULL→COALESCE, LIMIT x,y→LIMIT OFFSET, backticks→ANSI quotes, ::cast→CAST()), use ORM methods for operations with no common SQL form.
     - **G6 (SQL schema validation — MOST IMPORTANT):** validate every SQL statement in the codebase against the real database schema. Hallucinated column names are the #1 QC failure — LLMs frequently reference columns that don't exist. For each SQL statement: use `bms-session-mcp-server` (`list_tables`, `describe_table`, `query` with EXPLAIN/LIMIT 0) or `mcp__mysql__mysql_query` / `mcp__postgres__query` to verify every table and column reference exists. Fall back to `mcp__bms-knowledge-mcp__search_knowledge` (hosxp collection) or grep migration files if live DB is unavailable. Fix every hallucinated reference. (skipped if no SQL in project)
   - **H. Integration testing (real database, end-to-end)** — run actual integration tests against the real HOSxP database via `bms-session-mcp-server`. For every DB-touching feature verify there's an integration test that: executes the feature's real SQL via the `query` tool, flows real data through the actual code path (transformers, filters, UI components), asserts on concrete properties (row count range, column presence, type correctness, masked field handling, Thai encoding). Create missing integration tests. Never fix failures by mocking responses, skipping tests, or loosening assertions. Flag slow queries for user review. (skipped if bms-session-mcp-server is not available)
+  - **I. Business logic semantic validation** — verify every SQL statement actually retrieves the correct data per the user's intent and HOSxP conventions, not just that it runs without error. For each SQL: state the business question it should answer, cross-reference `mcp__bms-knowledge-mcp__search_knowledge` on `hosxp` collection for canonical table selection, soft-delete/status filters, correct date columns, join keys (hn/vn/an), code system usage (ICD-10/LOINC/TMT). Use `graph_search` for multi-table relationship questions. Check regulatory compliance via `moph` and `nhso` collections (43 files reporting, reimbursement rules). Verify Thai conventions (Buddhist calendar, CID validation, pre-masked fields). Fix semantic mismatches with code comments citing the HOSxP convention. Flag ambiguous intent for user review. (skipped if bms-knowledge-mcp is not available)
 - The agent fixes everything it can. Major dependency updates are flagged for user review.
 - **Completion rule:** When the QC agent returns its report, proceed to Step 12 **unless** the report contains unfixed build errors, unfixed test failures, or unfixed critical security vulnerabilities. Informational findings, flagged-for-review items, and already-fixed issues do NOT block progression. If uncertain, proceed — the QC agent already fixed what it could.
 - **Post-action:** Commit all fixes and push. Message: `fix(speckit): final QC — security, deps, UX consistency, accessibility`