@tekyzinc/gsd-t 5.3.10 → 5.4.11

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.4.11] - 2026-07-27
+
+### Fixed — schema-id gate never reached projects (propagation gap)
+
+v5.4.10 wired the `schema-id` verify gate into `gsd-t-verify-gate.cjs`, which dispatches to `bin/gsd-t-schema-id-check.cjs` by absolute path — but the new file was in neither `GLOBAL_BIN_TOOLS` nor `PROJECT_BIN_TOOLS`, so `update-all` propagated the *caller* to all 32 projects without the *callee*. Every project would have hit ENOENT on the check. Caught by verifying the file actually landed on disk in three sample projects rather than trusting the "copied 1 bin tool(s)" report.
+
+This is the third occurrence of the same class (M89 research gate, M99 graph store-resolver) — a tool added to the source and wired into a caller, but never added to a propagation list.
+
+- `bin/gsd-t.js`: added `gsd-t-schema-id-check.cjs` to both `GLOBAL_BIN_TOOLS` and `PROJECT_BIN_TOOLS`, with comments naming the dispatch dependency.
+- `.gsd-t/contracts/graph-metrics-contract.md`: line citation for `doMetrics` refreshed (4907 → 4915) after the insertion shifted it — enforced by the M99 T6 contract-line test.
+
+Note: `templates/stacks/_comparison.md` needed no propagation entry — stack rules are read from the installed package at spawn time (`gsd-t-task-brief.js`), not copied per-project. Verified live in the published package.
+
+## [5.4.10] - 2026-07-27
+
+### Added — Integer-identity primary keys + case-insensitive domain comparisons (two framework-wide code standards)
+
+Two mandatory standards, both previously absent from GSD-T. **(1) Every NEW relational table gets a self-incrementing integer primary key named `id`**; API-exposed tables also get a separate UNIQUE `public_id` UUID. The integer wins inside the database (8 bytes vs 16, insert-ordered so the index stays compact, fast joins, readable in logs); the UUID protects the edge (a sequential id in a URL leaks row counts and lets anyone enumerate `/invoice/1`, `/invoice/2`). `postgresql.md` previously said the opposite — "UUID preferred over serial" — with a UUID GOOD example agents were copying. **(2) Comparing a domain string value against a literal is case-insensitive by default** (status, filter, tab, role, category, email, user-entered text), while identifiers, secrets, hashes, encoded values, Linux file paths, object keys, and env-var names stay case-sensitive — blanket insensitivity on a token or hash is a security defect. Origin: a real shipped bug where `filter !== 'Invoiced'` never matched a lowercase `'invoiced'`, producing two visible UI defects from one casing mismatch.
+
+**Scope — NEW tables only.** A survey of all 32 registered projects found ~480 existing tables on UUID/cuid primary keys whose foreign keys already point at those UUIDs; changing an established primary key is a data migration and a Destructive Action Guard item, not an in-passing edit. No distributed-writes escape hatch was added — the same survey found zero multi-node or offline-first writers, so an unused exception path would be a speculative branch.
+
+**Firestore and Neo4j are exempt, and the exemption is stated rather than silent.** Firestore has no sequence to increment — forcing one means a counter document that serializes every write in the collection, re-introducing the bottleneck the database exists to avoid. Neo4j has no rows, and its internal `id()` is reused after node deletion. Leaving those files silent would let an agent read the gap as an oversight and invent the counter-document anti-pattern.
+
+- `bin/gsd-t-schema-id-check.cjs`: NEW deterministic verify gate (`schema-id`), FAIL-CLOSED. Inspects only schema files new or modified in the working tree, so established UUID-keyed repos pass untouched. Explicit no-op PASS (distinguishable from a wired-but-broken FAIL) when git is unavailable or no schema files changed.
+- `bin/gsd-t-verify-gate.cjs`: wired `schema-id` into the Track 2 default plan.
+- `templates/stacks/_comparison.md`: NEW universal rules file (`_` prefix → auto-injected into every project regardless of stack). Case-insensitive/case-sensitive split, SQL guidance with functional-index note, shared-constant rule, verification checklist.
+- `templates/stacks/postgresql.md`: §1 naming + §2 schema design rewritten; GOOD/BAD examples and checklist updated; explicit scope note on non-retrofit.
+- `templates/stacks/prisma.md`: `id Int @id @default(autoincrement())` mandatory + `publicId`; GOOD/BAD examples inverted (the old BAD example was the new rule).
+- `templates/stacks/supabase.md`: NEW §6.5 — including that a `user_id` column referencing `auth.users` stays UUID because row-level security compares it against `auth.uid()`.
+- `templates/stacks/firebase.md`, `templates/stacks/neo4j.md`: stated exemptions with the counter-document anti-pattern shown as BAD.
+- `templates/stacks/typescript.md`: §6 extended — a fixed value set lives in ONE shared constant so the compiler catches mismatches (case-insensitivity only treats the symptom; a typo'd value still fails silently).
+- `templates/CLAUDE-global.md` + live `~/.claude/CLAUDE.md`: both rules added and kept in sync, so they govern conversational work as well as spawned domain workers.
+- `test/schema-id-check.test.js`: NEW — 11 regression tests covering all three Postgres identity spellings, UUID/text/composite rejection, nested-paren bodies, Prisma models, and the new-tables-only scope.
+
+Migration: none required. Existing schemas are unaffected — the gate ignores committed tables, and no existing project is retrofitted.
+
 ## [5.3.10] - 2026-07-24
 
 ### Changed — Fable 5 removed; Opus tier upgraded to Opus 5 (claude-opus-5)

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.3.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.4.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-schema-id-check.cjs

@@ -0,0 +1,246 @@
+"use strict";
+
+// bin/gsd-t-schema-id-check.cjs
+//
+// The deterministic verify-gate lint for the integer-primary-key rule.
+// FAIL-CLOSED for relational schemas; NO-OP PASS for projects with no schema.
+//
+// THE RULE (relational stacks only — postgresql / prisma / supabase / drizzle):
+//   every NEW table has a self-incrementing integer primary key named `id`.
+//
+// SCOPE — NEW tables only. A pre-existing table with a UUID primary key is NOT a
+// failure: its foreign keys already point at that UUID, so changing the PK is a
+// data migration + Destructive Action Guard item, never an in-passing edit. The
+// gate therefore checks only tables whose defining file is UNCOMMITTED or was
+// added in the working tree — i.e. tables this run is introducing. A repo with an
+// established UUID-keyed schema passes untouched.
+//
+// NOT APPLICABLE — firestore/firebase (document store: no sequence to increment;
+// a counter document serializes writes) and neo4j (no rows; internal id() is
+// reused after deletion). Those stacks state the exemption in their own rules
+// file; this gate never inspects them.
+//
+// Zero external npm runtime deps — fs/path/child_process only.
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+// ─── SQL: CREATE TABLE detection ─────────────────────────────────────────────
+
+// A table body is scanned for a column that is BOTH an integer type AND carries
+// an identity/serial default AND is the primary key. Postgres spells this three
+// ways; all three are accepted.
+const SQL_IDENTITY_PK =
+  /\bid\b[^,]*?\b(?:bigint|integer|int|smallint)\b[^,]*?\bgenerated\s+(?:always|by\s+default)\s+as\s+identity\b[^,]*?\bprimary\s+key\b/is;
+const SQL_SERIAL_PK = /\bid\b\s+(?:big|small)?serial\b[^,]*?\bprimary\s+key\b/is;
+// Table-level constraint form: id BIGINT GENERATED ... , PRIMARY KEY (id)
+const SQL_IDENTITY_COL =
+  /\bid\b[^,]*?\b(?:bigint|integer|int|smallint)\b[^,]*?\b(?:generated\s+(?:always|by\s+default)\s+as\s+identity|serial)\b/is;
+const SQL_TABLE_PK_ID = /\bprimary\s+key\s*\(\s*"?id"?\s*\)/is;
+
+/**
+ * Extract (tableName, body) for each CREATE TABLE in a SQL string.
+ * Brace-matched on parentheses so nested type parens (numeric(10,2)) don't
+ * truncate the body.
+ */
+function extractSqlTables(sql) {
+  const out = [];
+  const re = /create\s+table\s+(?:if\s+not\s+exists\s+)?([`"\[]?[\w.]+[`"\]]?)\s*\(/gi;
+  let m;
+  while ((m = re.exec(sql)) !== null) {
+    const name = m[1].replace(/[`"\[\]]/g, "");
+    let depth = 1;
+    let i = re.lastIndex;
+    while (i < sql.length && depth > 0) {
+      const ch = sql[i];
+      if (ch === "(") depth++;
+      else if (ch === ")") depth--;
+      i++;
+    }
+    out.push({ name, body: sql.slice(re.lastIndex, i - 1) });
+  }
+  return out;
+}
+
+function sqlTableHasIntegerIdPk(body) {
+  if (SQL_IDENTITY_PK.test(body)) return true;
+  if (SQL_SERIAL_PK.test(body)) return true;
+  if (SQL_IDENTITY_COL.test(body) && SQL_TABLE_PK_ID.test(body)) return true;
+  return false;
+}
+
+// ─── Prisma: model detection ─────────────────────────────────────────────────
+
+const PRISMA_INT_ID = /\bid\s+Int\s+@id\s+@default\s*\(\s*autoincrement\s*\(\s*\)\s*\)/;
+const PRISMA_BIGINT_ID = /\bid\s+BigInt\s+@id\s+@default\s*\(\s*autoincrement\s*\(\s*\)\s*\)/;
+
+/** Extract (modelName, body) for each `model X { ... }` block. */
+function extractPrismaModels(src) {
+  const out = [];
+  const re = /^\s*model\s+(\w+)\s*\{/gm;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    let depth = 1;
+    let i = re.lastIndex;
+    while (i < src.length && depth > 0) {
+      const ch = src[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") depth--;
+      i++;
+    }
+    out.push({ name: m[1], body: src.slice(re.lastIndex, i - 1) });
+  }
+  return out;
+}
+
+function prismaModelHasIntegerIdPk(body) {
+  return PRISMA_INT_ID.test(body) || PRISMA_BIGINT_ID.test(body);
+}
+
+// A Prisma block that is only a relation join table declared with @@id([a, b])
+// still needs its own integer id under the rule — no exemption. But a `view`
+// or `enum` block is not a model and is never reached (regex matches `model`).
+
+// ─── Which files are NEW in this working tree ────────────────────────────────
+
+/**
+ * Files added/modified relative to HEAD, per git. The rule governs NEW tables,
+ * so only these files are inspected.
+ *
+ * Returns null when git is unavailable or the directory is not a repo — the
+ * caller turns that into a NO-OP PASS with an explicit note rather than
+ * silently scanning everything (which would fail every legacy schema).
+ */
+function changedFiles(projectDir) {
+  try {
+    const out = execFileSync(
+      "git",
+      ["status", "--porcelain=v1", "--untracked-files=all"],
+      { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const files = [];
+    for (const line of out.split("\n")) {
+      if (!line.trim()) continue;
+      // porcelain v1: XY <path>  (rename: XY <old> -> <new>)
+      const p = line.slice(3).trim();
+      const finalPath = p.includes(" -> ") ? p.split(" -> ").pop() : p;
+      files.push(finalPath.replace(/^"|"$/g, ""));
+    }
+    return files;
+  } catch (_) {
+    return null;
+  }
+}
+
+const SQL_EXT = /\.sql$/i;
+const PRISMA_EXT = /\.prisma$/i;
+
+function isSchemaFile(rel) {
+  if (/node_modules|\.git\//.test(rel)) return false;
+  return SQL_EXT.test(rel) || PRISMA_EXT.test(rel);
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (_) {
+    return null;
+  }
+}
+
+// ─── Main check ──────────────────────────────────────────────────────────────
+
+function check(projectDir) {
+  const failures = [];
+  const inspected = [];
+
+  const changed = changedFiles(projectDir);
+  if (changed === null) {
+    return {
+      ok: true,
+      check: "schema-id",
+      inspected: [],
+      failures: [],
+      note:
+        "no-op PASS: git unavailable or not a repository — cannot distinguish NEW tables from " +
+        "pre-existing ones, and the rule governs NEW tables only",
+    };
+  }
+
+  const schemaFiles = changed.filter(isSchemaFile);
+  if (schemaFiles.length === 0) {
+    return {
+      ok: true,
+      check: "schema-id",
+      inspected: [],
+      failures: [],
+      note: "no-op PASS: no new or modified .sql/.prisma schema files in the working tree",
+    };
+  }
+
+  for (const rel of schemaFiles) {
+    const abs = path.join(projectDir, rel);
+    const src = readSafe(abs);
+    if (src === null) continue; // deleted file listed by git status
+
+    if (PRISMA_EXT.test(rel)) {
+      for (const model of extractPrismaModels(src)) {
+        inspected.push(`${rel}::model ${model.name}`);
+        if (!prismaModelHasIntegerIdPk(model.body)) {
+          failures.push(
+            `${rel}: model \`${model.name}\` has no self-incrementing integer primary key — ` +
+              `add \`id Int @id @default(autoincrement())\`. If this model is API-exposed, also add ` +
+              `\`publicId String @unique @default(uuid())\` and expose that instead of the integer id.`
+          );
+        }
+      }
+    } else {
+      for (const table of extractSqlTables(src)) {
+        inspected.push(`${rel}::table ${table.name}`);
+        if (!sqlTableHasIntegerIdPk(table.body)) {
+          failures.push(
+            `${rel}: table \`${table.name}\` has no self-incrementing integer primary key — ` +
+              `add \`id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY\`. If this table is ` +
+              `API-exposed, also add \`public_id UUID NOT NULL DEFAULT gen_random_uuid()\` with a ` +
+              `UNIQUE constraint and expose that instead of the integer id.`
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    check: "schema-id",
+    inspected,
+    failures,
+    note:
+      inspected.length === 0
+        ? "no-op PASS: changed schema files contain no CREATE TABLE / model definitions"
+        : undefined,
+  };
+}
+
+function parseArgs(argv) {
+  const out = { projectDir: "." };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project") out.projectDir = argv[++i] || ".";
+  }
+  return out;
+}
+
+module.exports = {
+  check,
+  extractSqlTables,
+  sqlTableHasIntegerIdPk,
+  extractPrismaModels,
+  prismaModelHasIntegerIdPk,
+};
+
+if (require.main === module) {
+  const { projectDir } = parseArgs(process.argv.slice(2));
+  const result = check(projectDir);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(result.ok ? 0 : 1);
+}

package/bin/gsd-t-verify-gate.cjs

@@ -309,6 +309,8 @@ function _detectDefaultTrack2(projectDir, notes) {
 
   plan.push({ id: 'env-registry', cmd: 'node', args: [path.join(__dirname, 'gsd-t-env-registry-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // M102 D3: no-secret-in-registry + rule-without-table gate, FAIL-CLOSED
 
+  plan.push({ id: 'schema-id', cmd: 'node', args: [path.join(__dirname, 'gsd-t-schema-id-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // integer-identity PK on every NEW relational table, FAIL-CLOSED (no-op PASS when no new schema files)
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({

package/bin/gsd-t.js

@@ -1559,6 +1559,10 @@ const GLOBAL_BIN_TOOLS = [
   "gsd-t-loop-ledger.cjs",
   // Backlog #40 — deterministic archive+sweep of a completed milestone's domain dirs.
   "gsd-t-archive-domains.cjs",
+  // v5.4.10 — integer-identity primary-key gate. gsd-t-verify-gate.cjs dispatches to
+  // this by absolute path, so it MUST ship wherever the verify gate ships or the
+  // schema-id check throws ENOENT. Same class as the M99 store-resolver omission below.
+  "gsd-t-schema-id-check.cjs",
 ];
 
 function installGlobalBinTools() {
@@ -2939,6 +2943,10 @@ const PROJECT_BIN_TOOLS = [
   "cli-preflight.cjs", "parallel-cli.cjs", "parallel-cli-tee.cjs",
   "gsd-t-context-brief.cjs",
   "gsd-t-verify-gate.cjs", "gsd-t-verify-gate-judge.cjs",
+  // v5.4.10 — integer-identity primary-key gate. gsd-t-verify-gate.cjs dispatches to
+  // it via an absolute path in the Track 2 plan, so a project that has the verify gate
+  // but NOT this file gets an ENOENT on every verify. Ships alongside the gate itself.
+  "gsd-t-schema-id-check.cjs",
   // M82 — Competition Mode judge + its disjointness oracle dependency, so a
   // project's gsd-t-phase workflow can score candidate partitions via the
   // project-local bin (runCli prefers bin/<tool>.cjs over the global binary).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.3.10",
+  "version": "5.4.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -569,6 +569,35 @@ Skip the hint if auto-advancing (Level 3 mid-wave) — only show when the user n
 - Functions under 30 lines — split if longer
 - Files under 200 lines — create new modules if needed
 - Enums for state management and fixed option sets
+- **Fixed value sets live in ONE shared constant** — every comparison references it, never a retyped literal (a second literal is where casing/typo mismatches hide)
+
+## Comparisons — case-insensitive by default (MANDATORY)
+
+**Comparing a domain string VALUE against a literal is CASE-INSENSITIVE unless the user specifically directs otherwise.** Domain values (status, filter, tab, mode, role, category, email, user-entered text) cross boundaries — database, API, URL, form — and each is free to change the casing. A literal comparison silently returns `false` and the feature quietly does nothing.
+
+```
+CASE-INSENSITIVE:  statuses, filters, tabs, modes, roles, categories, emails,
+                   user-entered values, route/query params carrying any of these
+CASE-SENSITIVE:    passwords, tokens, API keys, hashes, signatures (case-insensitive
+                   here is a SECURITY defect); base64/JWT/hex/uuid-as-string/git SHA
+                   (case IS data); Linux file paths; object/property keys; DOM tag
+                   and prop names; env-var NAMES; branch names
+```
+
+Guard for absent values: `(filter || '').toLowerCase() !== 'invoiced'`. In SQL: `lower(col) = lower($1)` with a functional index on `lower(col)` when queried at volume.
+
+Full rule + worked examples: `templates/stacks/_comparison.md` (universal — auto-injected into every project).
+
+## Database schema — every new table gets a self-incrementing integer ID (MANDATORY)
+
+**Every NEW relational table has a self-incrementing integer primary key named `id`.** API-exposed tables ALSO get a separate `public_id` UUID (unique, indexed) — expose that externally, never the integer id.
+
+- **Why the integer inside** — 8 bytes vs 16, sorts in insert order so the index stays compact, joins fast, readable in a log. A UUID primary key scatters index writes and bloats every foreign key pointing at it.
+- **Why the UUID at the edge** — a sequential id in a URL leaks row counts and lets anyone walk `/invoice/1`, `/invoice/2` looking for other people's data.
+- **NEW tables only.** Existing UUID-keyed tables are NOT retrofitted — their foreign keys already point at the UUID, so changing the PK is a data migration and a **Destructive Action Guard** item requiring explicit user approval.
+- **Does NOT apply to Firestore or Neo4j** — deliberate, not an oversight. Firestore has no sequence to increment (forcing one means a counter document that serializes every write); Neo4j has no rows, and its internal `id()` is reused after deletion. Each stack file states this.
+
+Enforced mechanically by `bin/gsd-t-schema-id-check.cjs` (verify-gate `schema-id`, FAIL-CLOSED; no-op PASS when a run adds no schema files). Full rules: `templates/stacks/postgresql.md` §2, `prisma.md` §1, `supabase.md` §6.5.
 
 ## Naming
 ```

package/templates/stacks/_comparison.md

@@ -0,0 +1,134 @@
+# Comparison Standards (Universal)
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Domain String Comparisons Are Case-Insensitive by Default
+
+**Comparing a domain string VALUE against a literal is case-insensitive unless the user has
+specifically directed otherwise.**
+
+A domain value is a string that names something in the business world: a status, a filter, a tab, a
+mode, a role, a category, a user-entered value, an email address. These cross system boundaries —
+database, API, URL, form input, config — and each boundary is free to change the casing. A literal
+comparison silently returns `false` and the feature just quietly does nothing.
+
+```
+CASE-INSENSITIVE (domain value vs literal):
+  ├── Statuses, filters, tabs, modes, view names
+  ├── Roles, categories, types, enum-ish values
+  ├── Email addresses (the local part is technically case-sensitive per spec,
+  │     but no real mail provider treats it that way — compare lowercased)
+  ├── User-entered text being matched against known values
+  └── Query-string and route params carrying any of the above
+```
+
+**GOOD**
+```ts
+filter.toLowerCase() !== 'invoiced'
+status.toLowerCase() === 'pending'
+user.email.toLowerCase() === input.email.toLowerCase()
+row.category?.toLowerCase() === selected.toLowerCase()
+```
+
+**BAD** — a real bug, shipped:
+```ts
+// TILE_FILTERS maps the Invoiced tile to lowercase 'invoiced'.
+// This compares against 'Invoiced'. It never matched. The "+ Add Order" button
+// appeared on a tab where hand-adding an order is impossible, and the widening
+// branch below pulled in orders that made an unrelated button appear too —
+// two visible defects, one casing mismatch.
+onAddOrder={view === 'orders' && filter !== 'Invoiced' ? handleAdd : undefined}
+```
+
+Guard against null/undefined when lowercasing a value that may be absent:
+```ts
+(filter || '').toLowerCase() !== 'invoiced'   // or filter?.toLowerCase()
+```
+
+---
+
+## 2. Identifiers, Secrets, and Encoded Values Stay Case-Sensitive
+
+Case-insensitivity is a **default for domain values, not a blanket rule**. Applying it to the
+following is a defect — and for the first group, a security defect:
+
+```
+ALWAYS CASE-SENSITIVE:
+  ├── Passwords, tokens, API keys, session IDs, signatures, hashes
+  │     (case-insensitive matching here weakens the secret — a real vulnerability)
+  ├── Encoded values: base64, JWTs, hex digests, cuid/uuid-as-string, git SHAs
+  │     (case IS data — aB and Ab are different values)
+  ├── File paths and filenames on Linux (Makefile ≠ makefile — different files)
+  ├── Object and property keys (obj.userId ≠ obj.userid — different properties)
+  ├── DOM/JSX tag names, prop names, CSS custom properties
+  ├── Environment variable NAMES, git branch names, DNS record values
+  └── Anything compared for cryptographic equality
+```
+
+**BAD** — a security defect:
+```ts
+if (providedToken.toLowerCase() === storedToken.toLowerCase()) grantAccess();
+```
+
+**GOOD**
+```ts
+if (providedToken === storedToken) grantAccess();  // exact, case-sensitive
+```
+
+---
+
+## 3. Database Comparisons
+
+The same split applies in SQL. A domain-value comparison is case-insensitive; an identifier or
+token comparison is exact.
+
+```sql
+-- GOOD — domain value, case-insensitive
+WHERE lower(status) = 'pending'
+WHERE lower(email) = lower($1)
+
+-- GOOD — citext column, or a functional index to keep it fast
+CREATE INDEX idx_orders_status_lower ON orders (lower(status));
+
+-- GOOD — identifier, exact
+WHERE public_id = $1
+WHERE api_key_hash = $1
+
+-- BAD — domain value compared exactly; breaks when casing drifts
+WHERE status = 'Pending'
+```
+
+Note: `lower(col) = ...` cannot use a plain index on `col`. Add a functional index on
+`lower(col)`, or use a case-insensitive column type, when the column is queried at volume.
+
+---
+
+## 4. Prefer a Shared Constant Over Any String Literal
+
+Case-insensitivity is the safety net. The structural fix is that a fixed set of values exists in
+**one** place and every comparison references it — then a mismatch is caught by the compiler
+instead of by a user.
+
+```ts
+// The bug above cannot occur when both sites reference the same constant:
+export const ORDER_FILTER = { ORDERS: 'orders', INVOICED: 'invoiced' } as const;
+```
+
+Use both mechanisms. The shared constant catches typos and casing at build time; case-insensitive
+comparison catches the same class of bug at the boundaries a constant can't reach — data arriving
+from a database, an API response, a URL, or a user.
+
+See `typescript.md` §6 for the typed form, and `postgresql.md`/`prisma.md` for database enums.
+
+---
+
+## Comparison Verification Checklist
+
+- [ ] Every domain-value comparison (status/filter/tab/role/category/email) is case-insensitive
+- [ ] No `.toLowerCase()` applied to a token, hash, signature, key, or encoded value
+- [ ] Lowercasing guards against null/undefined (`(x || '').toLowerCase()`)
+- [ ] Fixed value sets are declared once and referenced — not retyped as literals
+- [ ] SQL domain-value filters use `lower()` (with a functional index if queried at volume)
+- [ ] File paths, object keys, and env-var names compared exactly

package/templates/stacks/firebase.md

@@ -44,9 +44,40 @@ MANDATORY:
   ├── Embedded objects for small, bounded data that's always read together
   ├── Store document IDs as fields when needed for queries
   ├── Use server timestamps: serverTimestamp() — not client Date.now()
+  ├── Use Firestore's auto-generated document IDs — NEVER build a sequential counter (see below)
   └── NEVER create deeply nested subcollection hierarchies (max 2-3 levels)
 ```
 
+**The self-incrementing-integer-ID rule does NOT apply to Firestore.** This is deliberate, not an
+oversight — the GSD-T relational stacks (postgresql, prisma, supabase) mandate an integer identity
+primary key on every table. Firestore cannot provide one:
+
+- A self-incrementing ID requires every writer to agree on "what was the last number", which means
+  one machine must be the authority and every insert must wait its turn. Firestore is built to
+  spread writes across many machines precisely to avoid that.
+- Forcing it means a single counter document that every write locks and updates — capping the
+  collection's write rate at roughly one per second and re-introducing the bottleneck the database
+  exists to avoid.
+
+Firestore's auto-generated IDs need no coordination and cannot collide between writers. Use them.
+
+**BAD** — the counter-document anti-pattern:
+```typescript
+// NEVER — serializes every write in the collection behind one document
+const counterRef = db.doc('counters/orders');
+await db.runTransaction(async (tx) => {
+  const snap = await tx.get(counterRef);
+  const next = snap.data().value + 1;
+  tx.update(counterRef, { value: next });
+  tx.set(db.doc(`orders/${next}`), orderData);
+});
+```
+
+**GOOD** — let Firestore assign the ID:
+```typescript
+await db.collection('orders').add(orderData);  // auto-ID, no coordination, no contention
+```
+
 **GOOD**
 ```typescript
 // User document — embedded small data

package/templates/stacks/neo4j.md

@@ -15,9 +15,21 @@ MANDATORY:
   ├── Properties: camelCase (firstName, createdAt)
   ├── Store properties on the node or relationship that "owns" them
   ├── Relationships ALWAYS have a direction — even if queried bidirectionally
+  ├── Every node carries an application-assigned `id` property with a UNIQUE constraint (see §3)
+  ├── NEVER persist or expose Neo4j's internal id() — it is reused after deletion (see below)
   └── NEVER use relationships as nodes (reify only when the relationship needs its own relationships)
 ```
 
+**The self-incrementing-integer-ID rule does NOT apply to Neo4j.** This is deliberate, not an
+oversight — the GSD-T relational stacks (postgresql, prisma, supabase) mandate an integer identity
+primary key on every table. Neo4j has no tables and no rows to number: it stores nodes and the
+relationships between them, so there is nothing for a sequence to attach to.
+
+Neo4j does expose an internal `id()` per node, but it is **not a stable identifier** — delete a node
+and the number is reused by a different node later. Anything that stored the old value now points at
+the wrong entity. Use an application-assigned `id` property with a uniqueness constraint instead
+(§3 Indexing and Constraints).
+
 **GOOD**
 ```cypher
 (:User {id: "u-123", name: "Jane", email: "jane@example.com"})

package/templates/stacks/postgresql.md

@@ -10,7 +10,8 @@ These rules are MANDATORY. Violations fail the task. No exceptions.
 MANDATORY:
   ├── Tables: snake_case, plural (users, order_items)
   ├── Columns: snake_case, singular (first_name, created_at)
-  ├── Primary keys: id (UUID preferred over serial for distributed systems)
+  ├── Primary keys: id — ALWAYS a self-incrementing integer identity (see §2)
+  ├── Public identifiers: public_id UUID — only on API-exposed tables (see §2)
   ├── Foreign keys: {referenced_table_singular}_id (user_id, order_id)
   ├── Indexes: idx_{table}_{columns} (idx_users_email)
   ├── Constraints: {type}_{table}_{columns} (uq_users_email, fk_orders_user_id)
@@ -24,29 +25,64 @@ MANDATORY:
 
 ```
 MANDATORY:
-  ├── Every table has: id (PK), created_at (timestamptz DEFAULT now()), updated_at
+  ├── EVERY table has a self-incrementing integer primary key named id — NO EXCEPTIONS
+  │     BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+  │     NEVER a UUID primary key. NEVER a natural/composite key as the PK.
+  ├── API-exposed tables ALSO get public_id UUID NOT NULL DEFAULT gen_random_uuid()
+  │     with a UNIQUE constraint — expose public_id externally, NEVER the integer id
+  ├── Every table has: created_at (timestamptz DEFAULT now()), updated_at
   ├── Use timestamptz — NEVER timestamp without time zone
-  ├── Use UUID for primary keys in distributed or API-exposed systems
   ├── Use appropriate types: text (not varchar), numeric (not float for money)
   ├── Add NOT NULL constraints by default — allow NULL only with explicit reason
   ├── Foreign keys with ON DELETE policy (CASCADE, SET NULL, or RESTRICT — choose deliberately)
   └── NEVER store JSON when a proper relational schema exists — use jsonb only for truly unstructured data
 ```
 
+**Why an integer PK plus a separate public UUID** — the two identifiers do different jobs:
+
+- **Integer `id` inside the database** — 8 bytes (vs 16 for UUID), sorts in insert order so the
+  index stays compact, joins fast, and is readable in a log (`order 4471`). A UUID primary key
+  scatters index writes and bloats every foreign key pointing at it.
+- **UUID `public_id` at the edge** — a sequential ID in a URL leaks your row count and lets anyone
+  walk `/invoice/1`, `/invoice/2` looking for other people's data. The public column removes that
+  without giving up the storage and join win.
+
 **GOOD**
 ```sql
 CREATE TABLE users (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  public_id UUID NOT NULL DEFAULT gen_random_uuid(),
   email TEXT NOT NULL,
   display_name TEXT NOT NULL,
   role user_role NOT NULL DEFAULT 'viewer',
   is_active BOOLEAN NOT NULL DEFAULT true,
   created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT uq_users_public_id UNIQUE (public_id),
   CONSTRAINT uq_users_email UNIQUE (email)
 );
 ```
 
+**BAD**
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- UUID as PK: scattered index writes,
+  email TEXT NOT NULL                             -- 16-byte FKs, unreadable in logs
+);
+
+CREATE TABLE order_items (
+  order_id BIGINT NOT NULL,                       -- composite natural key as PK:
+  sku TEXT NOT NULL,                              -- no stable single-column identity
+  PRIMARY KEY (order_id, sku)
+);
+```
+
+**Scope** — this rule governs NEW tables. Existing tables with UUID primary keys are NOT
+retrofitted: their foreign keys already point at the UUID, so adding an integer id without
+repointing every referencing table leaves two competing identifier systems. Changing an existing
+table's primary key is a data migration and a Destructive Action Guard item — it requires explicit
+user approval, never an in-passing change.
+
 ---
 
 ## 3. Migrations
@@ -214,6 +250,8 @@ NEVER:
 ## PostgreSQL Verification Checklist
 
 - [ ] Naming follows conventions (snake_case, plural tables, singular columns)
+- [ ] Every NEW table has a self-incrementing integer `id` primary key (identity/bigserial)
+- [ ] API-exposed tables also have a UNIQUE `public_id UUID` — and expose that, not the integer id
 - [ ] Every table has id, created_at, updated_at
 - [ ] timestamptz used — not timestamp
 - [ ] All foreign keys indexed

package/templates/stacks/prisma.md

@@ -10,7 +10,9 @@ Applies when `prisma` or `@prisma/client` is in `package.json` or `schema.prisma
 ```
 MANDATORY:
   ├── One schema.prisma file — NEVER split across multiple files (use comments to section)
-  ├── Use @id with autoincrement() or uuid() — NEVER application-generated IDs
+  ├── EVERY model has id Int @id @default(autoincrement()) — NEVER a uuid()/cuid() primary key
+  ├── API-exposed models ALSO get publicId String @unique @default(uuid()) — expose publicId
+  │     externally, NEVER the integer id (a sequential id in a URL leaks row counts and is enumerable)
   ├── Every model has createdAt DateTime @default(now()) and updatedAt DateTime @updatedAt
   ├── Use @map and @@map for snake_case DB column/table names with camelCase Prisma models
   ├── Define explicit relation names when a model has multiple relations to the same table
@@ -21,7 +23,8 @@ MANDATORY:
 **GOOD**
 ```prisma
 model User {
-  id        String   @id @default(uuid())
+  id        Int      @id @default(autoincrement())
+  publicId  String   @unique @default(uuid()) @map("public_id")
   email     String   @unique
   name      String
   role      UserRole @default(MEMBER)
@@ -45,12 +48,16 @@ enum UserRole {
 **BAD**
 ```prisma
 model User {
-  id   Int    @id @default(autoincrement())
-  role String // Should be enum
-  // Missing createdAt, updatedAt, indexes
+  id   String @id @default(uuid()) // UUID as PK — scattered index writes, 16-byte FKs
+  role String                      // Should be enum
+  // Missing publicId, createdAt, updatedAt, indexes
 }
 ```
 
+**Scope** — governs NEW models. Existing models with uuid()/cuid() primary keys are NOT retrofitted:
+their relations already point at the string id, so switching the PK is a data migration and a
+Destructive Action Guard item requiring explicit user approval.
+
 ---
 
 ## 2. Client Setup

package/templates/stacks/supabase.md

@@ -144,6 +144,43 @@ MANDATORY:
 
 ---
 
+## 6.5. Schema Design — Primary Keys
+
+Supabase is PostgreSQL — the full PostgreSQL standards apply. The primary-key rule:
+
+```
+MANDATORY:
+  ├── EVERY new table has a self-incrementing integer primary key named id
+  │     id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+  ├── API-exposed tables ALSO get public_id UUID NOT NULL DEFAULT gen_random_uuid() UNIQUE
+  │     PostgREST exposes every table over HTTP by default — treat tables as API-exposed
+  │     unless RLS blocks all client access. Return public_id to clients, never the integer id.
+  ├── A user_id column referencing auth.users STAYS UUID — auth.uid() returns a UUID and
+  │     RLS policies compare against it directly. This is NOT the table's primary key.
+  └── Existing tables are NOT retrofitted (see PostgreSQL standards §2 Scope)
+```
+
+**GOOD**
+```sql
+CREATE TABLE user_profiles (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  public_id UUID NOT NULL DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES auth.users (id) ON DELETE CASCADE,  -- UUID: RLS compares to auth.uid()
+  display_name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT uq_user_profiles_public_id UNIQUE (public_id)
+);
+
+ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users read own profile"
+  ON user_profiles FOR SELECT
+  USING (auth.uid() = user_id);
+```
+
+---
+
 ## 7. Migrations
 
 ```
@@ -176,6 +213,9 @@ NEVER:
 
 ## Supabase Verification Checklist
 
+- [ ] Every NEW table has a self-incrementing integer `id` primary key
+- [ ] API-exposed tables have a UNIQUE `public_id UUID` — clients get public_id, not the integer id
+- [ ] `user_id` columns referencing auth.users are UUID (RLS compares to auth.uid())
 - [ ] RLS enabled on every table with explicit policies
 - [ ] auth.uid() used in policies — no client-sent user IDs trusted
 - [ ] Service role key only used server-side

package/templates/stacks/typescript.md

@@ -113,6 +113,31 @@ enum Direction { Up = 'UP', Down = 'DOWN', Left = 'LEFT', Right = 'RIGHT' }
 if (status === 'pndng') { /* ... */ }
 ```
 
+**MANDATORY — a fixed set of values lives in ONE shared declaration, and every comparison
+references it.** Declaring the type is not enough: if the literal `'invoiced'` is typed in two
+files, nothing connects them, and a casing or spelling mismatch fails silently at runtime.
+
+```ts
+// BAD — the same value written as a loose literal in two places.
+// TILE_FILTERS maps the tile to 'invoiced'; this file compares against 'Invoiced'.
+// Different strings. Never matches. No error, no warning — the button just never appears.
+onAddOrder={view === 'orders' && filter !== 'Invoiced' ? handleAdd : undefined}
+
+// GOOD — one source of truth, referenced everywhere.
+export const ORDER_FILTER = {
+  ORDERS:   'orders',
+  INVOICED: 'invoiced',
+} as const;
+export type OrderFilter = typeof ORDER_FILTER[keyof typeof ORDER_FILTER];
+
+onAddOrder={view === 'orders' && filter !== ORDER_FILTER.INVOICED ? handleAdd : undefined}
+// A typo is now a compile error, not a silent mismatch a user finds later.
+```
+
+This is the structural fix for the casing-mismatch bug class. Case-insensitive comparison
+(`_comparison.md`) is the safety net that catches the same bug where a shared constant doesn't
+exist or the value crosses a system boundary — use both.
+
 ---
 
 ## 7. Import Ordering