fix(rules): address Greptile review on migration-discipline rules

Greptile flagged 4 issues on the initial PR (3/5 confidence). All four
are now resolved without weakening the rules' intent:

1. Marketplace-safe production project ref (was: hardcoded literal)
   - Replace ukwovawzehnebuoowcec / xepaexmpawtpqtilhcpw in rules.yaml
     with __PROD_SUPABASE_REF__ / __STAGING_SUPABASE_REF__ placeholders.
   - Extend scripts/build-rules.mjs with an opt-in substitution layer
     that reads .private/substitutions.json (UPPER_SNAKE token map) and
     swaps placeholders before YAML parsing. Mirrors the existing
     gitignored .private/forbidden-names.txt IP-leak guard.
   - When the file is absent, placeholders remain in rules.json and the
     rule is documented inert (only fires for commands containing the
     literal placeholder text). Preferred over a silent broken
     protection for marketplace consumers.
   - hooks/rules/README.md documents the substitution workflow and
     lists currently-consumed tokens.

2. Cover supabase db push --linked, which silently bypassed the block
   when the linked project was prod. Pattern now matches
   __PROD_SUPABASE_REF__ OR --linked\b. Two new tests:
   blocks-supabase-db-push-linked and
   blocks-supabase-db-push-linked-with-extra-flags. Bypass marker
   prod-db-push-approved continues to apply.

3. Stop false-positive on gh pr create --body-file. Positive pattern
   tightened to require --body followed by space, "=", or end-of-string;
   added not_pattern --body-file as defense in depth. New test
   allows-pr-create-with-body-file.

4. Extend warn-psql-against-supabase-remote to cover pg_dump,
   pg_restore, pg_dumpall — equivalent vectors for ad-hoc Postgres CLI
   work against the live Supabase host. Two new tests:
   warns-on-pg-dump-supabase-remote and
   warns-on-pg-restore-supabase-remote. Test fixtures use generic
   example.supabase.co hosts (no team-specific refs).

Test count: 80 -> 86 (6 new tests, all 86 pass).
No version bump (still 1.7.0 — pre-merge fixes).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lapc506

hooks/rules/README.md

@@ -84,6 +84,43 @@ client-acme
 client-beta
 ```
 
+## Per-install substitutions (opt-in, gitignored)
+
+Some rules need values that are specific to your team or environment —
+for example, the `block-supabase-db-push-prod` rule guards a Supabase
+production project ref that varies per organization. Hard-coding such
+values in the public rules.yaml would either leak the value upstream or
+leave consumers of this toolkit with a rule that silently never fires.
+
+The build script supports literal-string substitution from a gitignored
+`.private/substitutions.json` file. The file is a flat JSON object where
+keys are UPPER_SNAKE token names and values are the literal replacement
+strings. For each pair, every occurrence of `__TOKEN__` in `rules.yaml` is
+replaced before the YAML is parsed, so both the rule patterns and the
+test fixtures see the substituted value.
+
+Example `.private/substitutions.json`:
+
+```json
+{
+  "PROD_SUPABASE_REF": "abcdefghij1234567890",
+  "STAGING_SUPABASE_REF": "klmnopqrst0987654321"
+}
+```
+
+When the file is absent, `__TOKEN__` placeholders remain in `rules.json`
+verbatim. The rule still parses and runs; it simply does not fire for any
+real-world command (only for commands that happen to contain the literal
+placeholder text). This is a deliberately documented inert state — it is
+preferable to a silently-broken protection.
+
+Tokens currently consumed by the published rule set:
+
+- `PROD_SUPABASE_REF` — production Supabase project ref, used by the
+  `block-supabase-db-push-prod` rule and its test fixtures.
+- `STAGING_SUPABASE_REF` — staging Supabase project ref, used as the
+  negative-match example in the same rule's test array.
+
 ## Rule families
 
 The manifest groups rules into informal families by prefix / domain.
@@ -110,12 +147,15 @@ Adding a new family is fine — just keep ids unique and follow the schema.
   `pr-create-with-migrations-needs-deploy-note`,
   `block-supabase-db-push-prod`) — keep schema mutations inside
   versioned `supabase/migrations/` files, nudge developers away from
-  SQL-Editor-style direct execution against `*.supabase.co` hosts,
-  remind PR authors to document migration deployment, and hard-block
-  `supabase db push` aimed at the production project ref. Added after
-  a Slack discussion surfaced drift between manually-applied SQL and
-  the migrations directory when migrations failed to auto-run on
-  staging after a teammate's PR merged.
+  direct `psql` / `pg_dump` / `pg_restore` execution against
+  `*.supabase.co` hosts, remind PR authors to document migration
+  deployment, and hard-block `supabase db push` aimed at the production
+  project ref or `--linked` (which transparently resolves to whichever
+  project was last linked, possibly production). The production project
+  ref is configured per install via the substitutions mechanism described
+  above (`PROD_SUPABASE_REF` token). Added after a discussion surfaced
+  drift between manually-applied SQL and the migrations directory when
+  migrations failed to auto-run after a teammate's PR merged.
 
 ## Tier 2 — decomposing non-deterministic memories
 

hooks/rules/rules.json

@@ -982,27 +982,27 @@
   },
   {
     "id": "warn-psql-against-supabase-remote",
-    "description": "Warn when psql/SQL is executed directly against a *.supabase.co host (drift risk vs versioned migrations)",
+    "description": "Warn when psql / pg_dump / pg_restore is executed directly against a *.supabase.co host (drift risk vs versioned migrations)",
     "applies_to": [
       "Bash"
     ],
     "match": [
       {
         "field": "command",
-        "pattern": "psql.*\\.supabase\\.co",
+        "pattern": "\\b(psql|pg_dump|pg_restore|pg_dumpall)\\b.*\\.supabase\\.co",
         "flags": "i"
       }
     ],
     "action": "warn",
     "bypass_marker": "psql-supabase-remote",
     "memory_ref": "feedback_scripts_not_db.md",
-    "message": "WARNING: direct psql execution against a Supabase remote host.\n\nSQL Editor / psql-against-remote workflows create drift between the\nversioned migrations directory and other devs' local databases.\n\nCorrect workflow:\n  1. Add a migration in supabase/migrations/<timestamp>_<slug>.sql\n  2. Test locally:  supabase db reset --local\n  3. Push to develop — CI applies the migration to staging automatically\n  4. For production: William runs the create-release SOP\n\nUse the bypass marker only for legitimate hotfixes where the PR cycle\nis too slow.\n",
+    "message": "WARNING: direct psql / pg_dump / pg_restore execution against a Supabase\nremote host.\n\nSQL Editor / direct-Postgres-CLI workflows create drift between the\nversioned migrations directory and other devs' local databases.\n\nCorrect workflow:\n  1. Add a migration in supabase/migrations/<timestamp>_<slug>.sql\n  2. Test locally:  supabase db reset --local\n  3. Push to develop — CI applies the migration to staging automatically\n  4. For production: follow the create-release SOP\n\nUse the bypass marker only for legitimate hotfixes where the PR cycle\nis too slow.\n",
     "tests": [
       {
         "name": "warns-on-psql-supabase-remote",
         "input": {
           "tool_input": {
-            "command": "psql postgresql://user:pass@db.xepaexmpawtpqtilhcpw.supabase.co:5432/postgres -c 'SELECT 1'"
+            "command": "psql postgresql://user:pass@db.example1.supabase.co:5432/postgres -c 'SELECT 1'"
           }
         },
         "expected_exit": 0,
@@ -1012,7 +1012,27 @@
         "name": "warns-on-psql-different-supabase-host",
         "input": {
           "tool_input": {
-            "command": "psql -h db.ukwovawzehnebuoowcec.supabase.co -d postgres -c 'CREATE INDEX foo_idx ON foo (id)'"
+            "command": "psql -h db.example2.supabase.co -d postgres -c 'CREATE INDEX foo_idx ON foo (id)'"
+          }
+        },
+        "expected_exit": 0,
+        "expected_stderr_contains": "warn-psql-against-supabase-remote"
+      },
+      {
+        "name": "warns-on-pg-dump-supabase-remote",
+        "input": {
+          "tool_input": {
+            "command": "pg_dump -h db.example1.supabase.co -d postgres -t public.foo > foo.sql"
+          }
+        },
+        "expected_exit": 0,
+        "expected_stderr_contains": "warn-psql-against-supabase-remote"
+      },
+      {
+        "name": "warns-on-pg-restore-supabase-remote",
+        "input": {
+          "tool_input": {
+            "command": "pg_restore -h db.example1.supabase.co -d postgres backup.dump"
           }
         },
         "expected_exit": 0,
@@ -1031,7 +1051,7 @@
         "name": "allows-non-psql-supabase-references",
         "input": {
           "tool_input": {
-            "command": "curl https://xepaexmpawtpqtilhcpw.supabase.co/rest/v1/foo"
+            "command": "curl https://example1.supabase.co/rest/v1/foo"
           }
         },
         "expected_exit": 0
@@ -1040,7 +1060,7 @@
         "name": "allows-bypass-marker",
         "input": {
           "tool_input": {
-            "command": "psql -h db.xepaexmpawtpqtilhcpw.supabase.co -c 'SELECT 1' # hook-bypass: psql-supabase-remote"
+            "command": "psql -h db.example1.supabase.co -c 'SELECT 1' # hook-bypass: psql-supabase-remote"
           }
         },
         "expected_exit": 0
@@ -1049,14 +1069,15 @@
   },
   {
     "id": "pr-create-with-migrations-needs-deploy-note",
-    "description": "Warn when gh pr create body does not mention migrations (caller should verify the PR has no migration files)",
+    "description": "Warn when gh pr create body (inline --body) does not mention migrations (caller should verify the PR has no migration files)",
     "applies_to": [
       "Bash"
     ],
     "match": [
       {
         "field": "command",
-        "pattern": "gh[[:space:]]+pr[[:space:]]+create.*--body",
+        "pattern": "gh[[:space:]]+pr[[:space:]]+create.*--body([[:space:]]|=|$)",
+        "not_pattern": "--body-file",
         "flags": "i"
       },
       {
@@ -1068,7 +1089,7 @@
     "action": "warn",
     "bypass_marker": "pr-create-no-migration-note",
     "memory_ref": "feedback_scripts_not_db.md",
-    "message": "WARNING: gh pr create body does not mention migrations.\n\nIf your PR modifies files under supabase/migrations/, the body MUST\ninclude a \"Migration deployment\" section that lists:\n  1. Which envs need supabase db push (staging auto via CI; prod via release)\n  2. Backfill order if the migrations depend on existing data\n  3. Post-merge verification steps\n\nThis rule does NOT inspect the diff — it only reads the command. Use\nthe bypass marker if your PR has no migrations.\n",
+    "message": "WARNING: gh pr create body does not mention migrations.\n\nIf your PR modifies files under supabase/migrations/, the body MUST\ninclude a \"Migration deployment\" section that lists:\n  1. Which envs need supabase db push (staging auto via CI; prod via release)\n  2. Backfill order if the migrations depend on existing data\n  3. Post-merge verification steps\n\nThis rule does NOT inspect the diff — it only reads the command, and it\nintentionally skips --body-file invocations because it cannot read the\nreferenced file. Use the bypass marker if your PR has no migrations.\n",
     "tests": [
       {
         "name": "warns-on-pr-create-body-without-migration-mention",
@@ -1098,6 +1119,15 @@
         },
         "expected_exit": 0
       },
+      {
+        "name": "allows-pr-create-with-body-file",
+        "input": {
+          "tool_input": {
+            "command": "gh pr create --base develop --title \"feat: foo\" --body-file ./pr-body.md"
+          }
+        },
+        "expected_exit": 0
+      },
       {
         "name": "allows-bypass-marker",
         "input": {
@@ -1111,26 +1141,26 @@
   },
   {
     "id": "block-supabase-db-push-prod",
-    "description": "Block supabase db push targeting the PRODUCTION project ref without an explicit bypass marker",
+    "description": "Block supabase db push that targets the PRODUCTION project ref or uses --linked (the linked project may transparently be production)",
     "applies_to": [
       "Bash"
     ],
     "match": [
       {
         "field": "command",
-        "pattern": "supabase[[:space:]]+db[[:space:]]+push.*ukwovawzehnebuoowcec"
+        "pattern": "supabase[[:space:]]+db[[:space:]]+push.*(__PROD_SUPABASE_REF__|--linked\\b)"
       }
     ],
     "action": "block",
     "bypass_marker": "prod-db-push-approved",
     "memory_ref": "feedback_never_touch_prod_without_approval.md",
-    "message": "BLOCKED: supabase db push targeting the PRODUCTION project ref\n(ukwovawzehnebuoowcec).\n\nNEVER run against production without explicit user approval — see\nfeedback_never_touch_prod_without_approval.md.\n\nCorrect workflow:\n  1. Merge to main\n  2. William runs the release per the SOP at\n     https://github.com/DojoCodingLabs/dojo-os/blob/develop/.claude/commands/create-release.md\n\nUse the bypass marker ONLY when the user has verbally approved the\noperation.\n",
+    "message": "BLOCKED: supabase db push targeting either the PRODUCTION project ref\nor the currently-linked project (which may be production).\n\nNEVER run against production without explicit user approval — see\nfeedback_never_touch_prod_without_approval.md.\n\nCorrect workflow:\n  1. Merge to main\n  2. The release owner runs the create-release SOP that ships\n     migrations to production through CI, not from a developer machine.\n\nUse the bypass marker ONLY when the user has verbally approved the\noperation. For --linked, double-check the active link first:\n  supabase status --output json | jq -r '.project_ref'\n\nMarketplace consumers: the production project ref is configured per\ninstall via .private/substitutions.json (PROD_SUPABASE_REF token). See\nhooks/rules/README.md for the substitution workflow.\n",
     "tests": [
       {
         "name": "blocks-supabase-db-push-prod",
         "input": {
           "tool_input": {
-            "command": "supabase db push --db-url postgresql://postgres:pwd@db.ukwovawzehnebuoowcec.supabase.co:5432/postgres"
+            "command": "supabase db push --db-url postgresql://postgres:pwd@db.__PROD_SUPABASE_REF__.supabase.co:5432/postgres"
           }
         },
         "expected_exit": 2
@@ -1139,7 +1169,25 @@
         "name": "blocks-supabase-db-push-prod-with-project-ref-flag",
         "input": {
           "tool_input": {
-            "command": "supabase db push --project-ref ukwovawzehnebuoowcec"
+            "command": "supabase db push --project-ref __PROD_SUPABASE_REF__"
+          }
+        },
+        "expected_exit": 2
+      },
+      {
+        "name": "blocks-supabase-db-push-linked",
+        "input": {
+          "tool_input": {
+            "command": "supabase db push --linked"
+          }
+        },
+        "expected_exit": 2
+      },
+      {
+        "name": "blocks-supabase-db-push-linked-with-extra-flags",
+        "input": {
+          "tool_input": {
+            "command": "supabase db push --linked --include-all"
           }
         },
         "expected_exit": 2
@@ -1148,7 +1196,7 @@
         "name": "allows-supabase-db-push-staging",
         "input": {
           "tool_input": {
-            "command": "supabase db push --project-ref xepaexmpawtpqtilhcpw"
+            "command": "supabase db push --project-ref __STAGING_SUPABASE_REF__"
           }
         },
         "expected_exit": 0
@@ -1163,10 +1211,19 @@
         "expected_exit": 0
       },
       {
-        "name": "allows-bypass-marker",
+        "name": "allows-bypass-marker-prod-ref",
+        "input": {
+          "tool_input": {
+            "command": "supabase db push --project-ref __PROD_SUPABASE_REF__ # hook-bypass: prod-db-push-approved"
+          }
+        },
+        "expected_exit": 0
+      },
+      {
+        "name": "allows-bypass-marker-linked",
         "input": {
           "tool_input": {
-            "command": "supabase db push --project-ref ukwovawzehnebuoowcec # hook-bypass: prod-db-push-approved"
+            "command": "supabase db push --linked # hook-bypass: prod-db-push-approved"
           }
         },
         "expected_exit": 0