@alexcodeplace/slopgate 0.1.0

package/bin/slopgate

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Launcher: locate the native slopgate engine binary and exec it, passing argv
+// through and propagating the exit code. The engine is Rust (crates/slopgate-rs);
+// this thin node shim is the npm `bin` entry (cross-platform).
+//
+// One package ships every platform binary under vendor/<platform>-<arch>/; npm
+// delivers them all and this shim picks the one matching the host.
+//
+// Resolution order:
+//   1. $SLOPGATE_BIN                                  (explicit override)
+//   2. <pkg>/vendor/<platform>-<arch>/slopgate-rs     (bundled prebuilt; npm-install path)
+//   3. <pkg>/target/release/slopgate-rs               (cargo build --release; dev)
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const binName = process.platform === 'win32' ? 'slopgate-rs.exe' : 'slopgate-rs';
+const host = `${process.platform}-${process.arch}`;
+
+const candidates = [
+  process.env.SLOPGATE_BIN,
+  join(pkgRoot, 'vendor', host, binName),
+  join(pkgRoot, 'target', 'release', binName),
+].filter(Boolean);
+
+const bin = candidates.find((p) => existsSync(p));
+if (!bin) {
+  process.stderr.write(
+    `slopgate: native engine binary not found for ${host}.\n` +
+    `  This platform may not be supported, or the package install was incomplete.\n` +
+    `  For development, build the engine with \`cargo build --release\`.\n` +
+    `  looked in: ${candidates.join(', ') || '(none)'}\n`,
+  );
+  process.exit(1);
+}
+
+const r = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+if (r.error) {
+  process.stderr.write(`slopgate: failed to exec engine (${bin}): ${r.error.message}\n`);
+  process.exit(1);
+}
+process.exit(r.status ?? 1);

package/hooks/baseline-guard.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Slopgate baseline-guard — PreToolUse hook blocking agent bypass of the gate.
+# Covers: Edit/Write to baseline.json/suppressions.json, Bash rm/mv on baseline*,
+# Bash `slopgate baseline` in any form.
+# Exit 2 = block the tool use (PreToolUse protocol). Exit 0 = allow. Always fail-open on errors.
+
+set -euo pipefail
+INPUT=$(cat)
+
+tool_name=$(node -e "try{const j=JSON.parse(process.argv[1]);process.stdout.write(j.tool_name||'')}catch{}" "$INPUT" 2>/dev/null || echo '')
+tool_input=$(node -e "try{const j=JSON.parse(process.argv[1]);process.stdout.write(JSON.stringify(j.tool_input||{}))}catch{}" "$INPUT" 2>/dev/null || echo '{}')
+
+blocked=0
+reason=''
+
+case "$tool_name" in
+  Edit|Write)
+    file_path=$(node -e "try{const j=JSON.parse(process.argv[1]);process.stdout.write(j.file_path||'')}catch{}" "$tool_input" 2>/dev/null || echo '')
+    if echo "$file_path" | grep -qE '\.slopgate/(baseline|suppressions)\.json$'; then
+      blocked=1
+      reason="direct write to $file_path blocked — edit baseline/suppressions via slopgate CLI only"
+    fi
+    ;;
+  Bash)
+    cmd=$(node -e "try{const j=JSON.parse(process.argv[1]);process.stdout.write(j.command||'')}catch{}" "$tool_input" 2>/dev/null || echo '')
+    # Block: slopgate baseline (create or --update)
+    if echo "$cmd" | grep -qE '(^|[;&|[:space:]])(npx[[:space:]]+|pnpm[[:space:]]+exec[[:space:]]+|yarn[[:space:]]+)?(node[[:space:]]+[^ ]+/bin/slopgate|slopgate)[[:space:]]+baseline([[:space:]]|$)'; then
+      blocked=1
+      reason="slopgate baseline blocked — agent cannot update/create baseline; run in your own terminal"
+    fi
+    # Block: rm/mv targeting .slopgate/baseline*
+    if echo "$cmd" | grep -qE '(rm|mv)\s+.*\.slopgate/baseline'; then
+      blocked=1
+      reason="rm/mv of .slopgate/baseline blocked — baseline integrity guard"
+    fi
+    ;;
+esac
+
+if [ "$blocked" -eq 1 ]; then
+  echo "⛔ SLOPGATE GUARD: $reason" >&2
+  # Write bypass-attempt stats row (fail-open)
+  ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  node -e "
+const crypto=require('crypto'),fs=require('fs'),path=require('path'),os=require('os');
+const root=process.argv[1], reason=process.argv[2];
+try {
+  const key=crypto.createHash('sha256').update(root).digest('hex').slice(0,16);
+  const sess=JSON.parse(fs.readFileSync(path.join(os.homedir(),'.slopgate','sessions',key+'.json'),'utf8'));
+  const row=JSON.stringify({ts:new Date().toISOString(),project:path.basename(root),projectPath:root,
+    model:sess.model||'unknown',sessionId:sess.sessionId||null,mode:'bypass-attempt',
+    ruleId:'baseline-tamper',severity:'critical',category:'security',engine:'bypass-attempt',
+    file:null,line:null,reason});
+  const gp=path.join(os.homedir(),'.slopgate','stats.jsonl');
+  fs.appendFileSync(gp,row+'\n');
+} catch { /* fail-open */ }
+" "$ROOT" "$reason" 2>/dev/null || true
+  exit 2
+fi
+
+exit 0

package/hooks/commit-hook.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Slopgate PreToolUse hook — runs --staged before a git commit. Exit 1 → commit blocked.
+TOOL_JSON=$(cat)
+CMD=$(node -e "
+let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{process.stdout.write('')}});" <<< "$TOOL_JSON" 2>/dev/null)
+echo "$CMD" | grep -qE 'git[[:space:]]+commit' || exit 0
+
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+CONFIG="$ROOT/.slopgate/config.toml"
+[ -f "$CONFIG" ] || exit 0
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec node "$HERE/../bin/slopgate" --staged --config "$CONFIG"

package/hooks/edit-hook.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Slopgate PostToolUse hook — single-file scan after Edit/Write.
+# Exit 2 → stderr feeds back into the agent turn. FAIL-OPEN: any error/timeout → exit 0.
+TOOL_JSON=$(cat)
+FILE=$(node -e "
+let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.file_path||'')}catch{process.stdout.write('')}});" <<< "$TOOL_JSON" 2>/dev/null) || exit 0
+[ -n "$FILE" ] || exit 0
+case "$FILE" in *.test.ts|*.test.tsx) exit 0 ;; *.ts|*.tsx|*.astro) ;; *) exit 0 ;; esac
+# Skip fixture files — they are intentional violation examples for slopgate self-test.
+case "$FILE" in */.slopgate/fixtures/*|*/slopgate/*/fixtures/*) exit 0 ;; esac
+
+ROOT=$(git -C "$(dirname "$FILE")" rev-parse --show-toplevel 2>/dev/null) || exit 0
+CONFIG="$ROOT/.slopgate/config.toml"
+[ -f "$CONFIG" ] || exit 0
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT=$(timeout 5 node "$HERE/../bin/slopgate" --file "$FILE" --config "$CONFIG" 2>&1)
+[ "$?" -eq 1 ] && { echo "$OUT" >&2; exit 2; }
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Slopgate SessionStart hook — capture the session-start model for stats attribution.
+# Only SessionStart receives a `model` field; mid-session /model switches are invisible.
+# Fail-open: any error leaves no file -> stats resolves model to 'unknown'.
+ROOT=$(realpath "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null || git rev-parse --show-toplevel 2>/dev/null || pwd)
+exec node -e '
+const crypto = require("crypto"), fs = require("fs"), path = require("path"), os = require("os");
+const root = process.argv[1];
+let d = "";
+process.stdin.on("data", (c) => (d += c)).on("end", () => {
+  let m;
+  try {
+    const j = JSON.parse(d);
+    m = { model: j.model || "unknown", sessionId: j.session_id || null, startedAt: new Date().toISOString(), cwd: j.cwd || root };
+  } catch {
+    m = { model: "unknown", sessionId: null, startedAt: new Date().toISOString(), cwd: root };
+  }
+  try {
+    const key = crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+    const dir = path.join(process.env.HOME || os.homedir(), ".slopgate", "sessions");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, key + ".json"), JSON.stringify(m));
+  } catch { /* fail-open */ }
+});
+' "$ROOT"

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@alexcodeplace/slopgate",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Global code-quality / anti-slop gate — engine shared, rules per-project.",
+  "license": "MIT",
+  "author": "Alex <git@alex.org.il>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexcodeplace/slopgate.git"
+  },
+  "homepage": "https://github.com/alexcodeplace/slopgate#readme",
+  "bugs": {
+    "url": "https://github.com/alexcodeplace/slopgate/issues"
+  },
+  "bin": {
+    "slopgate": "bin/slopgate"
+  },
+  "files": [
+    "bin",
+    "hooks",
+    "rules",
+    "skills",
+    "vendor",
+    "!rules/baseline/fixtures",
+    "!bin/slopgate-rs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "self-test": "node bin/slopgate --self-test --config rules/baseline/selftest.config.toml",
+    "test": "cargo test --workspace"
+  }
+}

package/rules/baseline/ast/empty-catch-block-ts.yml

@@ -0,0 +1,7 @@
+id: empty-catch-block-ts
+language: typescript
+severity: error
+message: Empty catch block swallows error silently
+note: '{"severity":"high","category":"convention","resolution":"Handle or rethrow. Minimum: log with context (console.error). Comment-only bodies count as empty."}'
+rule:
+  pattern: 'try { $A } catch ($E) {}'

package/rules/baseline/ast/empty-catch-block-tsx.yml

@@ -0,0 +1,7 @@
+id: empty-catch-block-tsx
+language: tsx
+severity: error
+message: Empty catch block swallows error silently
+note: '{"severity":"high","category":"convention","resolution":"Handle or rethrow. Minimum: log with context (console.error). Comment-only bodies count as empty."}'
+rule:
+  pattern: 'try { $A } catch ($E) {}'

package/rules/baseline/ast/inner-html.yml

@@ -0,0 +1,9 @@
+id: inner-html-assignment
+language: tsx
+severity: error
+message: innerHTML / insertAdjacentHTML assignment — XSS surface
+note: '{"severity":"high","category":"security","resolution":"Build DOM via safe APIs or sanitize with isomorphic-dompurify."}'
+rule:
+  any:
+    - pattern: $X.innerHTML = $$$
+    - pattern: $X.insertAdjacentHTML($$$)

package/rules/baseline/ast/slopgate-canary.yml

@@ -0,0 +1,9 @@
+id: slopgate-canary
+language: tsx
+severity: error
+message: slopgate self-test canary
+note: '{"severity":"high","category":"convention","resolution":"self-test only — must only ever match fixtures/"}'
+files:
+  - '**/fixtures/**'
+rule:
+  pattern: __SLOPGATE_AST_CANARY__

package/rules/baseline/ast/target-blank-norel.yml

@@ -0,0 +1,25 @@
+id: target-blank-norel
+language: tsx
+severity: error
+message: target=_blank without rel=noopener noreferrer (reverse-tabnabbing)
+note: '{"severity":"high","category":"security","resolution":"Add rel=\"noopener noreferrer\" to the element."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has:
+            kind: jsx_attribute
+            regex: '^target=["\x27]_blank["\x27]$'
+        - not:
+            has:
+              kind: jsx_attribute
+              regex: '^rel='
+    - all:
+        - kind: jsx_self_closing_element
+        - has:
+            kind: jsx_attribute
+            regex: '^target=["\x27]_blank["\x27]$'
+        - not:
+            has:
+              kind: jsx_attribute
+              regex: '^rel='

package/rules/baseline/ast/window-in-render.yml

@@ -0,0 +1,38 @@
+id: window-in-render
+language: tsx
+severity: error
+message: window/document accessed during render — SSR crash
+note: '{"severity":"medium","category":"convention","resolution":"Move into useEffect/useLayoutEffect, an event handler, or guard with typeof window !== \"undefined\"."}'
+files:
+  - '**/src/components/**'
+  - '**/src/features/**'
+  - '**/fixtures/src/components/**'
+ignores:
+  - '**/features/design-system/**'
+rule:
+  any:
+    - pattern: window.$PROP
+    - pattern: document.$PROP
+  not:
+    any:
+      - inside:
+          stopBy: end
+          pattern: useEffect($$$)
+      - inside:
+          stopBy: end
+          pattern: useLayoutEffect($$$)
+      - inside:
+          stopBy: end
+          kind: jsx_attribute
+      - inside:
+          stopBy: end
+          pattern: if (typeof window !== 'undefined') { $$$ }
+      - inside:
+          stopBy: end
+          pattern: typeof window
+      - inside:
+          stopBy: end
+          kind: variable_declarator
+          has:
+            field: name
+            regex: ^(handle|on)[A-Z]

package/rules/baseline/selftest.config.toml

@@ -0,0 +1,23 @@
+# Canonical self-test config for the Rust engine.
+# Behavior frozen against the former JS oracle via the Stage-0b golden regression test.
+# Path resolution: roots are repo-root-relative; suppressions/fixtures are config-dir-relative.
+# astRules is intentionally omitted; the resolver always adds
+# rules/baseline/ast, and UX-high adds rules/ux/ast.
+roots = ["rules/baseline/fixtures/src"]
+exts = [".ts", ".tsx"]
+skipDirs = ["node_modules"]
+baseline = ["no-stubs", "ts-suppress", "as-any", "raw-hex", "kv-ban", "live-secrets", "eval-ban", "pii-logs", "weak-hash", "sql-safety"]
+rules = []
+suppressions = "./fixtures/suppressions.json"
+fixtures = "./fixtures"
+
+[ux]
+a11y = "high"
+cls = "high"
+feedback = "high"
+taste = "advisory"
+advisory = "advisory"
+
+[gate]
+file = ["critical", "high"]
+staged = ["critical", "high"]

package/rules/ux/ast/ux-anchor-no-href.yml

@@ -0,0 +1,17 @@
+id: ux-anchor-no-href
+language: tsx
+severity: error
+message: <a onClick> without href — not a real link, not keyboard-focusable
+note: '{"severity":"high","category":"convention","resolution":"Use a <button> for actions, or give the <a> a real href. An anchor with only onClick is invisible to keyboard and screen readers (ANTI-SLOP UX §11)."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^a$' }
+        - has: { kind: jsx_attribute, regex: '^onClick' }
+        - not: { has: { kind: jsx_attribute, regex: '^href=' } }
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^a$' }
+        - has: { kind: jsx_attribute, regex: '^onClick' }
+        - not: { has: { kind: jsx_attribute, regex: '^href=' } }

package/rules/ux/ast/ux-async-onclick-no-disable.yml

@@ -0,0 +1,17 @@
+id: ux-async-onclick-no-disable
+language: tsx
+severity: error
+message: async onClick on a <button> with no disabled state — double-submit / silent wait
+note: '{"severity":"high","category":"convention","resolution":"Disable the trigger while the promise is in flight (disabled={pending}) and show an inline loading indicator. Prevents double-submit and ghost interactions (ANTI-SLOP UX §3/§12)."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^button$' }
+        - has: { kind: jsx_attribute, regex: 'onClick=\{\s*async' }
+        - not: { has: { kind: jsx_attribute, regex: '^disabled' } }
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^button$' }
+        - has: { kind: jsx_attribute, regex: 'onClick=\{\s*async' }
+        - not: { has: { kind: jsx_attribute, regex: '^disabled' } }

package/rules/ux/ast/ux-button-no-type.yml

@@ -0,0 +1,11 @@
+id: ux-button-no-type
+language: tsx
+severity: error
+message: <button> without an explicit type — defaults to "submit" and can fire forms
+note: '{"severity":"high","category":"convention","resolution":"Add type=\"button\" (or type=\"submit\" intentionally). A typeless button inside a form submits it on click — a classic silent bug (ANTI-SLOP UX §3/§11)."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^button$' }
+        - not: { has: { kind: jsx_attribute, regex: '^type=' } }

package/rules/ux/ast/ux-div-onclick.yml

@@ -0,0 +1,17 @@
+id: ux-div-onclick
+language: tsx
+severity: error
+message: onClick on a <div>/<span> — not keyboard-focusable, breaks a11y
+note: '{"severity":"high","category":"convention","resolution":"Use a native <button> (or add role + tabIndex + onKeyDown). Semantic HTML first — ANTI-SLOP UX §11."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^(div|span)$' }
+        - has: { kind: jsx_attribute, regex: '^onClick' }
+        - not: { has: { kind: jsx_attribute, regex: '^role=' } }
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^(div|span)$' }
+        - has: { kind: jsx_attribute, regex: '^onClick' }
+        - not: { has: { kind: jsx_attribute, regex: '^role=' } }

package/rules/ux/ast/ux-img-no-alt.yml

@@ -0,0 +1,15 @@
+id: ux-img-no-alt
+language: tsx
+severity: error
+message: <img> without an alt attribute — invisible to screen readers
+note: '{"severity":"high","category":"convention","resolution":"Add alt text (alt=\"…\"), or alt=\"\" for purely decorative images (ANTI-SLOP UX §11). Semantic/accessible by default."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^img$' }
+        - not: { has: { kind: jsx_attribute, regex: '^alt' } }
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^img$' }
+        - not: { has: { kind: jsx_attribute, regex: '^alt' } }

package/rules/ux/ast/ux-img-no-dimensions.yml

@@ -0,0 +1,15 @@
+id: ux-img-no-dimensions
+language: tsx
+severity: error
+message: <img> without width/height — causes layout shift (CLS) as it loads
+note: '{"severity":"high","category":"convention","resolution":"Reserve the footprint: add width and height attributes, or a CSS aspect-ratio / min-height (ANTI-SLOP UX §13). Use a framework <Image> that sets dimensions."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^img$' }
+        - not: { has: { kind: jsx_attribute, regex: '^width=' } }
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^img$' }
+        - not: { has: { kind: jsx_attribute, regex: '^width=' } }

package/rules/ux/ast/ux-media-no-dimensions.yml

@@ -0,0 +1,15 @@
+id: ux-media-no-dimensions
+language: tsx
+severity: error
+message: <video>/<iframe> without width/height — causes layout shift (CLS)
+note: '{"severity":"high","category":"convention","resolution":"Reserve the footprint: set width and height (or a CSS aspect-ratio / fixed min-height) so the page does not jump as the media loads (ANTI-SLOP UX §13)."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^(video|iframe)$' }
+        - not: { has: { kind: jsx_attribute, regex: '^width=' } }
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^(video|iframe)$' }
+        - not: { has: { kind: jsx_attribute, regex: '^width=' } }

package/rules/ux/ast/ux-modal-no-close.yml

@@ -0,0 +1,15 @@
+id: ux-modal-no-close
+language: tsx
+severity: warning
+message: <Dialog>/<Modal> without an onClose/onDismiss handler — possible dead end
+note: '{"severity":"medium","category":"convention","resolution":"Give every modal an explicit escape: onClose / onOpenChange / onDismiss plus a visible Close control. No dead ends (ANTI-SLOP UX §10)."}'
+rule:
+  any:
+    - all:
+        - kind: jsx_opening_element
+        - has: { field: name, regex: '^(Dialog|Modal)$' }
+        - not: { has: { kind: jsx_attribute, regex: '^(onClose|onDismiss|onOpenChange)' } }
+    - all:
+        - kind: jsx_self_closing_element
+        - has: { field: name, regex: '^(Dialog|Modal)$' }
+        - not: { has: { kind: jsx_attribute, regex: '^(onClose|onDismiss|onOpenChange)' } }

package/skills/slopgate-improve/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: slopgate-improve
+description: Mine a project's institutional memory (skills, agents, commands, CLAUDE.md, editor rules) for conventions not yet caught by slopgate, and add them to the right rule tier. Invoke on /slopgate-improve or when a recurring agent mistake is documented but undetected.
+---
+
+# /slopgate-improve
+
+**Goal:** Find real agent mistakes documented in the project's institutional memory that slopgate doesn't yet catch, and add them to the right engine tier.
+
+Scope / focus area (optional): $ARGUMENTS — blank = all sources.
+
+## Rule tier model
+
+| Tier | Pack location | Who opts in |
+|------|--------------|-------------|
+| **baseline** | built-in: `crates/slopgate-core/src/rules/baseline.json` (compiled into the engine) | Any project — enabled by name in TOML (`baseline = ["no-stubs", ...]`) |
+| **stack** | built-in: `crates/slopgate-core/src/rules/stack.json` (compiled into the engine) | Projects using that runtime — enabled by name in TOML (`stack = ["cloudflare"]`) |
+| **project** | ast-grep YAML in the `astRules` dir (`<repo>/.slopgate/rules/ast/<id>.yml`) | That repo only. NOTE: project custom **regex** packs (non-empty `rules = [...]`) are NOT yet supported by the native engine — they error (`PHASE-2: project rule packs`). Use ast-grep YAML, or defer the rule. |
+
+When proposing a new rule, assign the lowest tier where it applies without FPs:
+- Applies to any TypeScript/web project → baseline
+- Applies to all projects using a specific runtime/framework → stack
+- Project-specific convention or business logic → project
+
+## Phase 1 — Inventory current coverage
+
+```bash
+# Baseline packs enabled (TOML array — `baseline = [...]`):
+grep 'baseline' <repo>/.slopgate/config.toml
+# Stack packs enabled (TOML array — `stack = [...]`):
+grep 'stack' <repo>/.slopgate/config.toml
+# Project ast-grep rule IDs (ids live in the .yml files under the astRules dir):
+grep -rho "^id:.*" <repo>/.slopgate/rules/ast/*.yml 2>/dev/null
+```
+
+Built-in (baseline/stack) pack IDs are engine-internal — they are not in a grep-able shipped file. The authoritative set of what is enabled = the pack names in `config.toml` plus the project ast `.yml` ids above; to see exactly what fires, run the engine with `--file` / `--self-test` (Phase 5).
+
+Build a set of already-covered rule IDs. Do NOT propose rules with IDs already present.
+
+## Phase 2 — Extract rule candidates from ALL convention sources
+
+Read `.slopgate/convention-sources.json` and open every file it lists:
+- `claudeMd` roots and subtrees
+- `skills/` — every SKILL.md
+- `agents/` — every agent definition
+- `commands/` — every command file
+- `editorRules` (`.cursorrules`, `.windsurfrules`)
+- `knowledgeDocs`
+
+Also read: `git log --oneline -50` for recent commit messages that describe mistakes.
+
+For each convention/mistake found, record:
+- **source**: which file + section stated it
+- **what**: the mistake or convention in one sentence
+- **already covered**: yes/no (check Phase 1 set)
+
+## Phase 3 — Bucket triage
+
+For each uncovered convention:
+
+| Bucket | Description | Action |
+|--------|-------------|--------|
+| A — regex | Token/pattern/import detectable by line scan | Author regex rule |
+| B — ast | Structural pattern (call shape, attribute presence) | Author ast-grep rule |
+| C — semantic | Judgment/intent — regex/AST would FP constantly | Add to judge-rules.md only |
+| skip | Too noisy, too specific, or already enforced by other tooling | Document why, discard |
+
+**Detectable (A/B):** banned token, hardcoded value where a utility is required, required attribute absence, import boundary violation, file-shape constraint.
+
+**NOT detectable (C/skip):** semantic conventions ("use the knowledge graph first"), runtime behavior, data-shape requirements, anything needing type information a regex can't see.
+
+## Phase 4A — Author regex candidates
+
+For each bucket-A rule, draft:
+```js
+{
+  id: '<kebab-id>',
+  title: '<short title>',
+  category: 'security|convention|duplication|boundary|api|i18n',
+  severity: 'critical|high|medium|low',
+  pattern: '<regex>',
+  description: '<why this is wrong>',
+  resolution: '<what to do instead>',
+  excludeGlobs: ['<legit exception globs>'],
+  canary: '<string the pattern must match>',
+}
+```
+
+**Confidence check:** test the pattern against 3 real examples from the codebase:
+- Does it match the violation? ✓
+- Does it match anything it shouldn't? If yes → add excludeGlobs or raise threshold to medium/low.
+- Low confidence → defer to C (judge-only), do not ship noise.
+
+**Tier decision:** assign to baseline / stack / project per the tier model above. NOTE: a **project-tier regex** rule cannot ship on the native engine (non-empty `rules = [...]` errors — `PHASE-2: project rule packs`). If a regex candidate is genuinely project-specific, either re-express it as an ast-grep rule (bucket B, Phase 4B) or defer it (bucket C / report as deferred). Only baseline/stack regex packs are loadable today.
+
+## Phase 4B — Author ast-grep candidates
+
+For each bucket-B rule, draft a YAML rule in ast-grep syntax:
+- `language: typescript|tsx`
+- `severity: error|warning`
+- `note:` JSON with `{"severity":"high","category":"...","resolution":"..."}`
+- `rule:` structural pattern
+- `files:` / `ignores:` scope guards if needed
+
+Add to correct dir:
+- Baseline-quality → `slopgate/rules/baseline/ast/<id>.yml`
+- Project-specific → `<repo>/.slopgate/rules/ast/<id>.yml`
+
+Always add a fixture file with a canary hit.
+
+## Phase 4C — Add judge-only candidates
+
+For bucket-C rules: append to `<repo>/scripts/code-quality/judge-rules.md` (or equivalent):
+```
+| <id> | <one-line description of what to flag> |
+```
+
+## Phase 5 — Verify
+
+For each new regex rule:
+```bash
+# Canary must match (approximation — the engine matches via fancy-regex for JS-RegExp parity)
+node -e "console.log(new RegExp('<pattern>').test('<canary>'))"
+# Run self-test
+slopgate --self-test --config <repo>/.slopgate/config.toml
+# Dry-run on repo (count hits; review for FPs)
+slopgate --config <repo>/.slopgate/config.toml 2>&1 | grep '<id>'
+```
+
+If FP count > 5% of hits → add excludeGlobs or demote to medium/low. If still noisy → demote to bucket C.
+
+## Phase 6 — Apply
+
+- Baseline/stack rules: edit the built-in JSON in the slopgate repo (`crates/slopgate-core/src/rules/baseline.json` or `stack.json`, loaded by `crates/slopgate-core/src/rules/packs.rs`), rebuild (`cargo build --release`), commit (`feat(rules): add <id> to baseline|stack/cloudflare`). Note: the packs are compiled in via `include_str!`, so the rebuild is required for the new rule to take effect. The file is a JSON object keyed by pack name (`"no-stubs": [ {...}, ... ]`); add your rule object to the right pack's array, writing it as **JSON** — double-quoted keys and strings — matching the existing entries (the Phase 4A draft is shown as a JS literal; translate it to JSON, not the other way around).
+- Project ast-grep rules: write the `.yml` to `<repo>/.slopgate/rules/ast/` (the `astRules` dir), commit to project repo. (Project regex packs are not loadable — see Phase 4A note.)
+- Run self-test one final time; must exit 0.
+
+## Phase 7 — Report (conversation text only, no files)
+
+```
+## /slopgate-improve results
+### Added — regex (N): `<id>` (tier:sev) — desc
+### Added — ast (N): `<id>` (tier:sev) — desc
+### Added — judge-only (N): `<id>` — desc
+### Deferred (N): `<id>`: <why — too noisy / not statically expressible / already covered>
+### Self-test: pass|fail
+```
+
+## Constraints
+
+- NEVER author a rule that fires on > ~5% false positives without excluding the FP sources.
+- NEVER duplicate an existing rule ID — Phase 1 set is authoritative.
+- NEVER add a baseline rule for a project-specific business concept (e.g. "agorot math").
+- NEVER skip the canary check — a rule without a matching canary is untestable and will rot.
+- implementer reports candidates; orchestrator + user decide on tier and enable. Do NOT self-approve critical+ rules without user confirmation.