bms-speckit-plugin 6.3.0 → 6.3.1

package/agents/quality-control.md

@@ -232,80 +232,73 @@ Search for `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`, etc. For
 
 > **Skip this phase entirely if the project has no SQL statements (no .sql files, no SQL strings in source code).**
 
-All SQL in the project must be compatible with both MySQL and PostgreSQL. Since no database runtime is available, this phase uses **static grep-based analysis** to find database-specific syntax and replace it with cross-compatible alternatives.
+**Philosophy: write SQL once, run on both.** All SQL must use syntax that works identically on MySQL and PostgreSQL without runtime database-type detection or dialect branching. Do NOT introduce `if (dialect === 'mysql')` patterns — instead, always use the ANSI SQL or cross-compatible form.
 
 ### G1. Identifier Quoting
 
-- **MySQL backticks** — Grep for backtick-quoted identifiers: `` `table_name` ``, `` `column` ``
-  - Fix: Replace with double quotes `"table_name"` (ANSI SQL, works on both) or remove quoting if identifiers don't need escaping
-  - If using an ORM, prefer the ORM's quoting mechanism instead of raw quoting
+Grep for backtick-quoted identifiers (MySQL-only). Fix by removing quoting entirely (preferred) or replacing with ANSI double quotes. If using an ORM, prefer the ORM's quoting mechanism.
 
 ### G2. Data Types
 
-Grep SQL files and SQL strings in source code for database-specific types:
-
-| MySQL-only | PostgreSQL-only | Cross-compatible replacement |
-|---|---|---|
-| `TINYINT(1)` for booleans | `BOOLEAN` | `BOOLEAN` (MySQL treats as TINYINT, PG native) |
-| `AUTO_INCREMENT` | `SERIAL`, `GENERATED ALWAYS AS IDENTITY` | Use ORM auto-increment, or `SERIAL` (PG) + `AUTO_INCREMENT` (MySQL) via migration |
-| `DOUBLE` | `DOUBLE PRECISION` | `DOUBLE PRECISION` (works on both) |
-| `DATETIME` | `TIMESTAMP` | `TIMESTAMP` (works on both) |
-| `TINYINT`, `MEDIUMINT` | not supported | `SMALLINT` or `INTEGER` |
-| `LONGTEXT`, `MEDIUMTEXT`, `TINYTEXT` | not supported | `TEXT` (works on both) |
-| `LONGBLOB`, `MEDIUMBLOB`, `TINYBLOB` | `BYTEA` | Handle via ORM or use `BLOB`/`BYTEA` per dialect |
-| `ENUM('a','b')` | `CREATE TYPE ... AS ENUM` | Use CHECK constraint or application-level validation |
-| `UNSIGNED` | not supported | Remove `UNSIGNED`, use CHECK constraint if needed |
-| `JSON` (MySQL 5.7+) | `JSON` / `JSONB` | `JSON` works on both; prefer `JSONB` on PG for indexing |
-
-### G3. SQL Syntax Differences
-
-Grep for these MySQL-specific or PostgreSQL-specific patterns:
-
-| Pattern | MySQL | PostgreSQL | Cross-compatible |
-|---|---|---|---|
-| Pagination | `LIMIT 10, 20` | not supported | `LIMIT 20 OFFSET 10` (works on both) |
-| String concat | `CONCAT(a, b)` | `a \|\| b` | `CONCAT(a, b)` (works on both in modern versions) |
-| Null coalesce | `IFNULL(a, b)` | not supported | `COALESCE(a, b)` (ANSI SQL, works on both) |
-| If/else | `IF(cond, a, b)` | not supported | `CASE WHEN cond THEN a ELSE b END` |
-| Current time | `NOW()` | `NOW()` | `NOW()` works on both, or `CURRENT_TIMESTAMP` |
-| Date diff | `DATEDIFF(a, b)` | `a - b` (returns interval) | Use `EXTRACT(EPOCH FROM a - b)` or handle per dialect |
-| Date format | `DATE_FORMAT(d, '%Y-%m-%d')` | `TO_CHAR(d, 'YYYY-MM-DD')` | Handle per dialect or use ORM date formatting |
-| Group concat | `GROUP_CONCAT(col)` | `STRING_AGG(col, ',')` | Handle per dialect or use ORM |
-| Upsert | `ON DUPLICATE KEY UPDATE` | `ON CONFLICT ... DO UPDATE` | Use ORM upsert or handle per dialect |
-| Insert ignore | `INSERT IGNORE` | `ON CONFLICT DO NOTHING` | Use ORM or handle per dialect |
-| Regex | `REGEXP` / `RLIKE` | `~` / `~*` | Handle per dialect |
-| Boolean literals | `TRUE`/`FALSE` or `1`/`0` | `TRUE`/`FALSE` | `TRUE`/`FALSE` (works on both) |
-| Table exists | `SHOW TABLES` | `\dt` / information_schema | `SELECT FROM information_schema.tables` (works on both) |
-| Column info | `DESCRIBE table` / `SHOW COLUMNS` | `\d table` | `SELECT FROM information_schema.columns` (works on both) |
-| String escape | `\'` (backslash) | `''` (double single quote) | `''` (ANSI SQL, works on both) |
-
-### G4. ORM/Query Builder Dialect Safety
-
-If the project uses an ORM or query builder:
-
-1. **Check dialect configuration** — Verify the ORM is configured to produce dialect-agnostic SQL, or has explicit multi-dialect support:
-   - Sequelize: check `dialect` option — should support switching between 'mysql' and 'postgres'
-   - TypeORM: check `type` in data source config
-   - Prisma: check `provider` in schema.prisma
-   - SQLAlchemy: check engine URL — should be configurable via env var, not hardcoded
-   - Django: check `DATABASES.ENGINE` setting
-
-2. **Raw SQL in ORM context** — Any raw SQL used alongside an ORM must follow the same cross-compatibility rules above. Flag raw SQL that uses dialect-specific syntax.
-
-3. **Migration files** — Check migration files for dialect-specific DDL. Migrations that use `AUTO_INCREMENT`, backtick quoting, or MySQL-specific types will fail on PostgreSQL.
-
-### G5. Handling Unavoidable Differences
-
-Some operations genuinely differ between databases. For these:
-
-1. **Dialect abstraction** — If the project must support both databases, verify there's a dialect layer that switches SQL per database type. Example:
-   ```
-   // Acceptable pattern
-   const upsertSQL = dialect === 'mysql'
-     ? 'INSERT INTO t (...) VALUES (?) ON DUPLICATE KEY UPDATE ...'
-     : 'INSERT INTO t (...) VALUES ($1) ON CONFLICT (...) DO UPDATE ...';
-   ```
-2. **Document exceptions** — If a query intentionally uses dialect-specific syntax, it must have a comment explaining which database it targets and why cross-compatibility isn't possible.
+Grep SQL files and SQL strings in source code for database-specific types. Replace with the cross-compatible form:
+
+| Flag this | Replace with |
+|---|---|
+| `TINYINT(1)` for booleans | `BOOLEAN` |
+| `AUTO_INCREMENT` or `SERIAL` | ORM-managed auto-increment identity column |
+| `DOUBLE` | `DOUBLE PRECISION` |
+| `DATETIME` | `TIMESTAMP` |
+| `TINYINT`, `MEDIUMINT` | `SMALLINT` or `INTEGER` |
+| `LONGTEXT`, `MEDIUMTEXT`, `TINYTEXT` | `TEXT` |
+| `LONGBLOB`, `MEDIUMBLOB`, `TINYBLOB`, `BYTEA` | ORM binary type or `BLOB`/`BYTEA` handled by ORM layer |
+| `ENUM('a','b')` or `CREATE TYPE AS ENUM` | `VARCHAR` + `CHECK` constraint or application-level validation |
+| `UNSIGNED` | Remove; use `CHECK (col >= 0)` if needed |
+| `JSONB` | `JSON` (works on both; index optimization is a deployment concern, not a code concern) |
+
+### G3. SQL Syntax — Always Use the Cross-Compatible Form
+
+Grep for database-specific syntax. Every match must be replaced with the form that runs on both MySQL and PostgreSQL without modification:
+
+| Flag this | Replace with (works on both) |
+|---|---|
+| `LIMIT 10, 20` (MySQL offset syntax) | `LIMIT 20 OFFSET 10` |
+| `IFNULL(a, b)` | `COALESCE(a, b)` |
+| `IF(cond, a, b)` | `CASE WHEN cond THEN a ELSE b END` |
+| `a \|\| b` for string concat (PG-only when sql_mode strict) | `CONCAT(a, b)` |
+| `DATEDIFF(a, b)` (MySQL) or `a - b` interval (PG) | `EXTRACT(DAY FROM (a - b))` or ORM date math |
+| `DATE_FORMAT(d, '%Y-%m-%d')` (MySQL) or `TO_CHAR(d, 'YYYY-MM-DD')` (PG) | ORM date formatting function |
+| `GROUP_CONCAT(col)` (MySQL) or `STRING_AGG(col, ',')` (PG) | ORM aggregate or application-level concatenation |
+| `ON DUPLICATE KEY UPDATE` (MySQL) | ORM upsert method (most ORMs abstract this) |
+| `INSERT IGNORE` (MySQL) | ORM upsert with ignore/skip-duplicate option |
+| `ON CONFLICT ... DO UPDATE` (PG-only) | ORM upsert method |
+| `REGEXP` / `RLIKE` (MySQL) or `~` / `~*` (PG) | Application-level regex or ORM pattern matching |
+| `1`/`0` for booleans | `TRUE`/`FALSE` |
+| `SHOW TABLES`, `DESCRIBE table`, `SHOW COLUMNS` | `SELECT FROM information_schema.tables` / `information_schema.columns` |
+| `\\d table`, `\\dt` (PG CLI commands) | `information_schema` queries |
+| `\\'` backslash string escape | `''` (ANSI double single-quote) |
+| `NOW()` | `CURRENT_TIMESTAMP` (ANSI standard; `NOW()` also works on both but `CURRENT_TIMESTAMP` is more portable) |
+| `::type` PostgreSQL cast syntax | `CAST(expr AS type)` (ANSI SQL) |
+
+### G4. ORM and Raw SQL
+
+1. **Prefer ORM abstractions** — For operations that have no single cross-compatible SQL form (upsert, date formatting, group concat, regex), the ORM's built-in method is the correct solution. It generates the right SQL per dialect automatically.
+
+2. **Raw SQL must be cross-compatible** — Any raw SQL string (ORM raw queries, migration files, seed files) must use only the cross-compatible forms listed above. No exceptions — if a raw query can't be written cross-compatibly, it must be replaced with an ORM call.
+
+3. **Migration files** — Check all migration files for dialect-specific DDL. Replace `AUTO_INCREMENT`, backtick quoting, MySQL-specific types, and PG-specific types with cross-compatible alternatives or ORM schema methods.
+
+4. **Placeholder syntax** — Use the ORM's parameterization. If writing raw parameterized SQL, use named parameters (`:id`) which most ORMs translate per dialect, rather than `?` (MySQL) or `$1` (PG) which are dialect-specific.
+
+### G5. No Dialect Branching
+
+**Do NOT accept or introduce patterns like:**
+- `if (dialect === 'mysql') { sql = '...' } else { sql = '...' }`
+- `config.database.type === 'postgres' ? pgQuery : mysqlQuery`
+- Separate `.mysql.sql` and `.postgres.sql` files
+
+If code like this already exists, refactor it to use the single cross-compatible form or an ORM method. The goal is one SQL statement that runs on both databases identically.
+
+**Only exception:** ORM configuration that specifies the connection dialect (e.g., Sequelize `dialect`, Django `ENGINE`, SQLAlchemy connection URL). This is infrastructure config, not SQL branching.
 
 **Output Format:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bms-speckit-plugin",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "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

@@ -205,7 +205,7 @@ After the subagent completes, update tasks 1-8 as completed using TaskUpdate, th
   - **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)
-  - **G. Database compatibility** — static analysis of all SQL statements for MySQL/PostgreSQL cross-compatibility: identifier quoting, data types, syntax differences (IFNULL→COALESCE, LIMIT offset, upsert), ORM dialect config, migration files (skipped if no SQL in project)
+  - **G. Database compatibility** — enforce "write SQL once, run on both" principle: 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 (upsert, date format, regex). No `if dialect` patterns allowed. (skipped if no SQL in project)
 - 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`