@tekyzinc/gsd-t 5.2.11 → 5.4.10

package/commands/gsd-t-help.md

@@ -519,16 +519,16 @@ Use these when user asks for help on a specific command:
 - **Contract**: `.gsd-t/contracts/plan-hardening-contract.md` v1.0.0 STABLE.
 
 ### model-tier-policy (M85)
-- **Summary**: SINGLE source of truth for GSD-T model-tier assignments. Publishes the authoritative tier set (haiku/sonnet/opus/fable), the 7 designated stage→tier mappings, and the `requiresThinkingOmitted(model)` predicate (encoding Fable's HTTP-400 breaking change ONCE). M85 slots the Fable tier into the 5 highest-leverage stages (solution-space probe, partition probe, competition judge, pre-mortem, Red Team) where one call's judgment gates the most downstream spend; competition producers STAY opus (M82 blindness invariant); debug cycle-1→opus, cycle-2→fable. A M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`) proves every workflow `model:` literal matches the policy — a drifted literal FAILS the lint (mandatory negative test).
+- **Summary**: SINGLE source of truth for GSD-T model-tier assignments. Publishes the authoritative tier set (haiku/sonnet/opus — **Fable removed 2026-07-24**; `opus` = claude-opus-5) and the 7 designated stage→tier mappings (all → opus). Opus 5 shipped at the same price as Opus 4.8 but >2× its coding score, so every stage formerly on Fable OR Opus 4.8 now runs Opus 5. The M82 competition judge-blindness invariant is RELAXED to "fresh independent context" — producers AND judge both run opus. A M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`) proves every workflow `model:` literal matches the policy — a drifted literal FAILS the lint (mandatory negative test).
 - **Files**: `bin/gsd-t-model-tier-policy.cjs` (zero external deps — installer invariant).
 - **Use when**: Any phase that needs to resolve a concrete model id from a stage key at invoke time (M69 pattern). Workflows NEVER `require` this module (sandbox ban) — they use hard-coded tier alias literals the lint proves match the policy.
 - **CLI**: `gsd-t model-tier-policy resolve <stageKey> [--json]`. Emits `{ok, stageKey, tier, model, requiresThinkingOmitted}`. Exit 0 resolved · 1 unknown stage key.
 - **Contract**: `.gsd-t/contracts/model-tier-policy-contract.md` v1.1.0 STABLE.
 
 ### model-profile (M86)
-- **Summary**: Per-project model-tier profile switcher — a SECOND dimension over the M85 stage-tier policy. Manages `.gsd-t/model-profile.json` and resolves which concrete model id each workflow stage runs on under the active profile. Three named profiles: `standard` (zero Fable — pre-M85 posture), `pro` (Fable on red-team + pre-mortem + debug-cycle-2), `premium` (all 6 M85 designated Fable stages — global default). Switching profiles injects the overrides into workflow args at invoke time (M69 pattern — NO tracked-file rewriting). Competition producers are HELD at opus in ALL profiles (M82 blindness invariant). The active profile is surfaced in the session banner (`[GSD-T PROFILE]`), the statusline, and `gsd-t status` — always named, never an implicit fallback (SC(f)).
+- **Summary**: Per-project model-tier profile switcher — a SECOND dimension over the stage-tier policy. Manages `.gsd-t/model-profile.json` and resolves which concrete model id each workflow stage runs on under the active profile. Three named profiles (Fable removed 2026-07-24 — they now dial OPUS-vs-SONNET spend): `standard` (probes opus, high-stakes stages sonnet — cost-leanest), `pro` (probes + pre-mortem + red-team + debug-cycle-2 opus, judge sonnet), `premium` (all 6 designated stages opus — global default). Switching profiles injects the overrides into workflow args at invoke time (M69 pattern — NO tracked-file rewriting). Competition producers are held at opus in ALL profiles. The active profile is surfaced in the session banner (`[GSD-T PROFILE]`), the statusline, and `gsd-t status` — always named, never an implicit fallback (SC(f)).
 - **Files**: `bin/gsd-t-model-profile.cjs` (zero external deps — installer invariant). Config: `.gsd-t/model-profile.json` (`{ "profile": "pro", "stageOverrides": { ... } }`).
-- **Use when**: A project needs a different spend posture than the global default (e.g., run `standard` on a CI cost budget, or `pro` for a production release with targeted Fable quality gates). Per-stage overrides allow fine-grained control beyond the named profiles.
+- **Use when**: A project needs a different spend posture than the global default (e.g., run `standard` on a CI cost budget, or `pro` for a production release with targeted opus quality gates). Per-stage overrides allow fine-grained control beyond the named profiles.
 - **CLI**:
   - `gsd-t model-profile show [--json]` — display active profile + per-stage resolution
   - `gsd-t model-profile set <standard|pro|premium>` — switch the project profile
@@ -540,7 +540,7 @@ Use these when user asks for help on a specific command:
 - **Contract**: `.gsd-t/contracts/model-profile-config-contract.md` v1.0.0 STABLE.
 
 ### research-gate (M89)
-- **Summary**: Deterministic CLASSIFY step of the M89 auto-research pipeline. Takes a load-bearing claim the agent tagged `[GUESSED:*]` in its Stated Claims section. The classifier is a MECHANICAL STRING-FACT FILTER (NOT a semantic oracle) returning one of THREE classes: `internal` (grep/Read, route `grep`), `external` (web-research, route `web`), or `ambiguous` (route `judge`). No LLM call in the classifier itself — semantic judgment is deferred to the wiring's LLM judge. An `ambiguous` claim is routed to a small LLM `classify-judge` stage (model: "fable") that decides internal/external/uncertain; **uncertain → research** (never guess-internal). The research `agent()` stage (model: "fable") runs for external guesses. An ENFORCE marker (`<!-- auto-research-claim: ... status=uncited -->`) is written into the artifact (a deterministic `.gsd-t/research/...` fallback if the stage reports no artifact path — fail-closed); the verify gate FAILs if it stays uncited.
+- **Summary**: Deterministic CLASSIFY step of the M89 auto-research pipeline. Takes a load-bearing claim the agent tagged `[GUESSED:*]` in its Stated Claims section. The classifier is a MECHANICAL STRING-FACT FILTER (NOT a semantic oracle) returning one of THREE classes: `internal` (grep/Read, route `grep`), `external` (web-research, route `web`), or `ambiguous` (route `judge`). No LLM call in the classifier itself — semantic judgment is deferred to the wiring's LLM judge. An `ambiguous` claim is routed to a small LLM `classify-judge` stage (model: "opus") that decides internal/external/uncertain; **uncertain → research** (never guess-internal). The research `agent()` stage (model: "opus") runs for external guesses. An ENFORCE marker (`<!-- auto-research-claim: ... status=uncited -->`) is written into the artifact (a deterministic `.gsd-t/research/...` fallback if the stage reports no artifact path — fail-closed); the verify gate FAILs if it stays uncited.
 - **Files**: `bin/gsd-t-research-gate.cjs` (D1). Contract: `.gsd-t/contracts/auto-research-contract.md` v1.3.2 STABLE. Stage prompt: `templates/prompts/research-subagent.md`. DETECT snippet: `templates/prompts/stated-claims-snippet.md`. Cite-format test: `test/m89-research-stage-cite-format.test.js`.
 - **Use when**: A workflow stage needs to classify a guessed claim before deciding whether to grep, run a web-research sub-agent, or route to the LLM judge. Called by D3 (upper phases: plan, pre-mortem, partition, discuss, milestone) and D4 (worker phases: execute, debug, quick). NOT called manually — the wiring invokes it per `[GUESSED:*]` entry in the `## Stated Claims` section.
 - **CLI**: `gsd-t research-gate classify "<guessed claim text>"`. Emits `{ok, gap, class, route, reason}` where `class` ∈ {internal, external, ambiguous} and `route` ∈ {grep, web, judge}. Exit 0 on classify · 1 on bad input.
@@ -549,7 +549,7 @@ Use these when user asks for help on a specific command:
 
 ### architectural-trigger (M90)
 - **Summary**: Deterministic architectural-assumption trigger (M90 §2). Two fire paths: **R-ARCH-1** (divergence-sampling — N fresh-context producer answers → divergence score; competition-arm only, EXPERIMENTAL+MEASURED) and **R-ARCH-2** (protocol-class — any task whose `**Touches**` lists an EXISTING file triggers unconditionally; everywhere feed). Fires produce an instrumentation record in `.gsd-t/metrics/arch-trigger-events.jsonl`; a `provenByAdversaryOnly=true` flag from either path surfaces at the §4 fail-closed verify gate (R-FAIL-2). The module NEVER asserts it works — it emits measurement data only.
-- **Files**: `bin/gsd-t-architectural-trigger.cjs`. Contract: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` §2. Blind-adversary prompt: `templates/prompts/blind-adversary-subagent.md`. Model: `fable` (M85 RULE-ARCH-TIER).
+- **Files**: `bin/gsd-t-architectural-trigger.cjs`. Contract: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` §2. Blind-adversary prompt: `templates/prompts/blind-adversary-subagent.md`. Model: `opus` (RULE-ARCH-TIER; Fable removed 2026-07-24).
 - **Use when**: Workflows detect that a task extends existing code (R-ARCH-2 everywhere feed) or that competition producers diverged (R-ARCH-1 competition-arm only). Called automatically by `gsd-t-execute`, `gsd-t-quick`, and `gsd-t-phase` competition arm via inline runCli helper (M81 runtime-native).
 - **CLI**: `gsd-t architectural-trigger trigger '<JSON>'`. JSON shapes: `{"type":"extend-existing-code","context":"...","basis":"..."}` or `{"type":"divergence-sampling","answers":[...],"basis":"..."}`. Emits `{ok, firePath, fired, basis, reason, ...}`. Exit 0 on success · 1 on bad input.
 - **Contract**: `.gsd-t/contracts/unproven-assumption-doctrine-contract.md` §2 v1.0.0 STABLE.

package/commands/gsd-t-partition.md

@@ -58,7 +58,7 @@ binary), do NOT silently proceed on the premium fallback. Either:
     (configured profile unknown; stale global binary may lack model-profile subcommand)
   ```
 
-A configured-standard project silently billing premium fable post-promo is the exact inverse of
+A configured-standard project silently billing premium opus post-promo is the exact inverse of
 the spend-switch goal. Never silently fall through.
 
 Also surface a SUCCESSFUL resolve that carries a `configError` field (the resolver returns a

package/commands/gsd-t-status.md

@@ -81,10 +81,10 @@ The **Model Profile** line MUST always name the active profile — never blank,
 - If the file is absent, display the global default by name with the `(default)` marker: `Model Profile: premium (default)`.
 - If the file is present but malformed or contains an unknown profile, display: `Model Profile: premium (default, config-error)` — never silently promote to the most expensive posture.
 
-Profiles control which workflow stages run on Fable vs. Opus/Sonnet:
-- `standard` — zero Fable stages (pre-M85 posture)
-- `pro` — Fable on red-team + pre-mortem + debug-cycle-2
-- `premium` — all 6 M85 designated Fable stages (full posture, global default)
+Profiles control which workflow stages run on Opus vs. Sonnet (Fable removed 2026-07-24 — `opus` = claude-opus-5):
+- `standard` — probes opus; high-stakes stages (judge/pre-mortem/red-team/debug-cycle-2) sonnet (cost-leanest)
+- `pro` — probes + pre-mortem + red-team + debug-cycle-2 opus; judge sonnet
+- `premium` — all 6 designated stages opus (full posture, global default)
 
 ### Backlog Section
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.2.11",
+  "version": "5.4.10",
   "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

@@ -251,7 +251,7 @@ Every GSD-T project gets TWO logging streams scaffolded by default at `gsd-t-ini
 Every code-producing phase ends with `gsd-t-verify.workflow.js`, which runs three orthogonal validators as `parallel()` `agent()` stages with schema-validated output. Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE, they are declared orthogonal objective functions — no collapse, no substitution, no transitive trust.
 
 - **`/code-review ultra`** — cooperative correctness + cleanup. Severity: `important` / `nit` / `pre-existing`. Skippable via `args.skipUltra=true` + `args.skipUltraReason`. `skipUltra=true` is INELIGIBLE for `VERIFIED`.
-- **Red Team** — adversarial / security / boundaries. Non-skippable. Protocol: `templates/prompts/red-team-subagent.md`. Verdict: `FAIL` (any CRITICAL or HIGH bug — blocks completion) or `GRUDGING-PASS` (exhaustive search, nothing found). CRITICAL/HIGH bugs get up to 2 fix cycles before deferral. Runs on `model: "fable"` (M85).
+- **Red Team** — adversarial / security / boundaries. Non-skippable. Protocol: `templates/prompts/red-team-subagent.md`. Verdict: `FAIL` (any CRITICAL or HIGH bug — blocks completion) or `GRUDGING-PASS` (exhaustive search, nothing found). CRITICAL/HIGH bugs get up to 2 fix cycles before deferral. Runs on `model: "opus"` (= claude-opus-5; Fable removed 2026-07-24).
 - **QA** — test execution + shallow-test detection + contract compliance. Non-skippable. Protocol: `templates/prompts/qa-subagent.md`. Writes ZERO feature code. Any shallow E2E test blocks phase completion. Runs on `model: "sonnet"`.
 
 When `.gsd-t/contracts/design-contract.md` or `.gsd-t/contracts/design/` exists, a fourth stage runs Design Verification (protocol: `templates/prompts/design-verify-subagent.md`) — opens a browser, compares the build against the design, returns a structured element-by-element MATCH/DEVIATION schema. Deviations block completion.
@@ -260,13 +260,13 @@ Synthesis stage merges results without category collapse. Verdict: `VERIFIED` /
 
 ## Model Display (MANDATORY)
 
-**Each Workflow `agent()` call declares its model explicitly** via the `model:` option (`"haiku"` / `"sonnet"` / `"opus"` / `"fable"`). The Workflow runtime emits a `⚙ [{model}] {label}` line per stage in `/workflows`, giving the user real-time visibility into which model handles each operation.
+**Each Workflow `agent()` call declares its model explicitly** via the `model:` option (`"haiku"` / `"sonnet"` / `"opus"` — **Fable removed 2026-07-24**; `opus` = claude-opus-5). The Workflow runtime emits a `⚙ [{model}] {label}` line per stage in `/workflows`, giving the user real-time visibility into which model handles each operation.
 
 **Model assignments:**
 - `model: "haiku"` — strictly mechanical tasks: run test suites and report counts, check file existence, validate JSON structure, branch guard checks
 - `model: "sonnet"` — mid-tier reasoning: routine code changes, standard refactors, test writing, QA evaluation, straightforward synthesis
 - `model: "opus"` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, quality judgment on critical paths
-- `model: "fable"` — highest-stakes calls where one judgment gates the most downstream spend (M85): solution-space probe, partition probe, competition judge, pre-mortem, Red Team. Competition producers STAY `opus` (M82 blindness invariant — judge must differ from producers). Debug cycle-1 → `opus`, cycle-2 → `fable` (escalation). **Single source of truth for tier assignments:** `bin/gsd-t-model-tier-policy.cjs` + `.gsd-t/contracts/model-tier-policy-contract.md` v1.0.0 STABLE. The M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`) proves every workflow `model:` literal matches the policy and a drifted literal FAILS the lint (mandatory negative test).
+- **Fable removed 2026-07-24** — `opus` (= claude-opus-5) is the top tier and the default for every high-stakes stage: solution-space probe, partition probe, competition judge, pre-mortem, Red Team, competition producers, debug both cycles. Opus 5 shipped at the same price as Opus 4.8 but >2× its coding score, so every stage formerly on Fable OR Opus 4.8 now runs Opus 5. The M82 competition judge-blindness invariant is RELAXED to "fresh independent context" — producers AND judge both run `opus` (fresh contexts remove memory-bias; the modest residual taste/blind-spot bias is accepted for a stronger judge). **Single source of truth for tier assignments:** `bin/gsd-t-model-tier-policy.cjs` + `.gsd-t/contracts/model-tier-policy-contract.md`. The M71-family lint (`test/m85-workflow-tier-policy-lint.test.js`) proves every workflow `model:` literal matches the policy and a drifted literal FAILS the lint (mandatory negative test).
 
 **Context budget:** Workflow scripts receive a `budget` global (`budget.total`, `budget.spent()`, `budget.remaining()`) tied to the user's per-turn token target. Use it for dynamic loops (`while (budget.total && budget.remaining() > 50_000) { ... }`) or to scale fleet size. Opus 4.7/4.8 ship 1M context windows; the legacy meter at `bin/token-budget.cjs` was retired in M61 — use native `/context` for live in-session usage.
 
@@ -421,9 +421,9 @@ For every load-bearing claim, tag it:
 - **`[GUESSED:stale]`** — external/time-varying fact that may have changed.
 
 A `[GUESSED:*]` claim is then CLASSIFIED — mechanical string-fact filter, three classes:
-- **`class: external`** → research agent (`model: "fable"`) writes a `## Verified Facts (auto-research)` block (URL + fetch date); ENFORCE marker `<!-- auto-research-claim: class=external key=<key> status=uncited -->` is written; verify FAILs if it stays `status=uncited` (R-FAIL-1).
+- **`class: external`** → research agent (`model: "opus"`) writes a `## Verified Facts (auto-research)` block (URL + fetch date); ENFORCE marker `<!-- auto-research-claim: class=external key=<key> status=uncited -->` is written; verify FAILs if it stays `status=uncited` (R-FAIL-1).
 - **`class: internal`** → grep/Read only; escalate to external if grep empty.
-- **`class: ambiguous`** → LLM judge (`model: "fable"`) decides; uncertain → research (never guess-internal).
+- **`class: ambiguous`** → LLM judge (`model: "opus"`) decides; uncertain → research (never guess-internal).
 
 **§2 — Architectural Trigger (`gsd-t architectural-trigger trigger '<JSON>'`):**
 Two fire paths — both INSTRUMENTED (fire-rate emitted to `.gsd-t/metrics/arch-trigger-events.jsonl`):
@@ -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/prompts/blind-adversary-subagent.md

@@ -4,7 +4,7 @@
 **Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term (e.g. `M93-D2` = milestone 93, domain 2) in plain words on first use. Bullets over paragraphs. Expand only if asked.
 <!-- /reader-contract -->
 
-**Model:** `fable` (M85 tier policy — highest-leverage judgment; separate context from the proposing agent)
+**Model:** `opus` (= claude-opus-5; Fable removed 2026-07-24 — highest-leverage judgment; separate context from the proposing agent)
 
 **Framing:** You are reviewing someone ELSE's architectural design — you did NOT propose it and have no attachment to it. Your goal is to find the **fatal flaw** in the premise being challenged, before a single line of code is committed to that premise. This framing (independent reviewer, not the author) is essential for escaping self-preference bias: the proposing agent's prior context makes it systematically less able to see its own premise's failures (source: https://arxiv.org/abs/2310.08118 — LLM self-evaluation is biased toward confirming prior outputs; https://arxiv.org/abs/2404.13076 — blind adversarial framing surfaces failures that self-critique misses).
 
@@ -32,7 +32,7 @@ You are NOT checking whether the code is correct. You are attacking the **archit
 3. **Has someone else solved this class of problem? How?** Grep the repo, check the brief, research prior art. Do NOT confirm the premise by default — search for evidence that it is WRONG or that a different approach is clearly superior.
 4. **What is the minimal falsifying test?** What single experiment would prove the premise is wrong? Propose it.
 
-## Extends M83 Pre-Mortem + Red-Team-on-fable
+## Extends M83 Pre-Mortem + Red-Team-on-opus
 
 This prompt is the **architectural dual** of the M83 pre-mortem: the pre-mortem attacks a PLAN before execution; this prompt attacks an ARCHITECTURAL PREMISE before the plan is written. It also extends the Red Team (which attacks finished code at verify) by moving the adversarial review LEFT to the assumption stage.
 

package/templates/prompts/research-subagent.md

@@ -6,7 +6,7 @@ ZERO feature code writes. You do NOT answer questions about what the claim PROBA
 it up and cite it.
 
 <!-- M89 — Workflow-stage invocation -->
-**Invocation context.** This protocol runs as a native Workflow `agent()` stage (bare `model: "fable"`,
+**Invocation context.** This protocol runs as a native Workflow `agent()` stage (bare `model: "opus"`,
 Fable tier — the single highest-leverage web call per phase). Your **final emission MUST be a single
 StructuredOutput object** matching the schema declared by the calling Workflow. The Verified-Facts block
 is embedded in the artifact; the StructuredOutput envelope carries the block text + the gap-key.

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