@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-sqlite/scripts/inspect-sqlite.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Read-only inspection of a SQLite database file and, optionally, the source
+that opens it.
+
+    inspect-sqlite.py DATABASE [--source PATH ...] [--quick-check] [--json]
+
+Reports what the file itself records (journal mode, page and freelist counts,
+planner statistics, FTS tables, WAL size) plus the filesystem it sits on. It
+never writes to the database. SQLite may create an empty `-shm` file beside a
+WAL database that no process has open.
+
+Connection settings such as busy_timeout, synchronous, foreign_keys and
+cache_size are not stored in the file, so no database inspection can show what
+an application sets. `--source` is a text scan: for each mention of
+journal_mode it reports whether a busy_timeout mention comes earlier in the
+same file. It does not establish run order or which connection each belongs
+to. Treat those lines as places to read, not verdicts. A source path that cannot
+be read is listed as not scanned and the exit status is 2.
+"""
+import argparse
+import json
+import os
+import pathlib
+import re
+import sqlite3
+import sys
+
+NETWORK_FILESYSTEMS = {"9p", "drvfs", "cifs", "smb3", "smbfs", "nfs", "nfs4", "fuse.sshfs", "virtiofs"}
+SHADOW_SUFFIXES = ("_data", "_idx", "_content", "_docsize", "_config", "_segments", "_segdir", "_stat", "_node", "_parent", "_rowid")
+SOURCE_SUFFIXES = {".py", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".rs", ".go", ".rb", ".java", ".kt", ".cs", ".c", ".cc", ".cpp", ".swift", ".php", ".sql"}
+
+
+def mount_for(path):
+    """Return (mount point, filesystem type, options) for the longest mount prefix."""
+    try:
+        with open("/proc/self/mountinfo", encoding="utf-8", errors="replace") as handle:
+            lines = handle.read().splitlines()
+    except OSError:
+        return None
+    real = os.path.realpath(path)
+    best = None
+    for line in lines:
+        left, _, right = line.partition(" - ")
+        fields = left.split()
+        if len(fields) < 6 or len(right.split()) < 3:
+            continue
+        point = fields[4].replace("\\040", " ")
+        if real == point or real.startswith(point.rstrip("/") + "/") or point == "/":
+            if best is None or len(point) > len(best[0]):
+                kind, _, super_options = right.split()[:3]
+                best = (point, kind, ",".join([fields[5], super_options]))
+    return best
+
+
+def scan_source(paths):
+    """For each file that mentions journal_mode, note where busy_timeout appears.
+
+    Returns (findings, errors). A path that cannot be read is an error, so a
+    failed scan never looks like a scan that found nothing.
+    """
+    findings = []
+    errors = []
+    files = []
+
+    def walk_error(error):
+        errors.append({"file": str(error.filename), "error": error.strerror or str(error)})
+
+    for entry in paths:
+        if os.path.isdir(entry):
+            for root, dirs, names in os.walk(entry, onerror=walk_error):
+                dirs[:] = [d for d in dirs if d not in {".git", "node_modules", ".venv", "target", "dist"}]
+                files.extend(
+                    os.path.join(root, n) for n in names if os.path.splitext(n)[1] in SOURCE_SUFFIXES
+                )
+        else:
+            files.append(entry)
+    for file in sorted(files):
+        try:
+            with open(file, encoding="utf-8", errors="replace") as handle:
+                lines = handle.read().splitlines()
+        except OSError as error:
+            errors.append({"file": file, "error": error.strerror or str(error)})
+            continue
+        journals = [i + 1 for i, l in enumerate(lines) if re.search(r"journal_mode", l, re.I)]
+        timeouts = [i + 1 for i, l in enumerate(lines) if re.search(r"busy_timeout|busyTimeout|set_busy_timeout", l, re.I)]
+        for journal in journals:
+            earlier = [t for t in timeouts if t < journal]
+            if earlier:
+                status = "busy_timeout at line %d comes before journal_mode at line %d" % (earlier[-1], journal)
+            elif timeouts:
+                status = "journal_mode at line %d comes before busy_timeout at line %d" % (journal, timeouts[0])
+            else:
+                status = "journal_mode at line %d; no busy_timeout in this file" % journal
+            findings.append({"file": file, "line": journal, "status": status, "ok": bool(earlier)})
+    return findings, errors
+
+
+def inspect(path, quick_check=False):
+    result = {"path": os.path.abspath(path)}
+    size = os.path.getsize(path)
+    result["fileBytes"] = size
+    uri = pathlib.Path(result["path"]).as_uri() + "?mode=ro"
+    connection = sqlite3.connect(uri, uri=True, timeout=2)
+    try:
+        connection.execute("PRAGMA busy_timeout = 2000")
+
+        def pragma(name):
+            row = connection.execute("PRAGMA " + name).fetchone()
+            return row[0] if row else None
+
+        result["library"] = {"version": sqlite3.sqlite_version}
+        options = [r[0] for r in connection.execute("PRAGMA compile_options")]
+        result["library"]["memstatusDisabled"] = "DEFAULT_MEMSTATUS=0" in options
+        result["library"]["threadsafe"] = next((o for o in options if o.startswith("THREADSAFE")), None)
+        result["journalMode"] = pragma("journal_mode")
+        result["pageSize"] = pragma("page_size")
+        result["pageCount"] = pragma("page_count")
+        result["freelistCount"] = pragma("freelist_count")
+        result["autoVacuum"] = pragma("auto_vacuum")
+        result["userVersion"] = pragma("user_version")
+        result["encoding"] = pragma("encoding")
+        names = connection.execute(
+            "SELECT name, sql FROM sqlite_master WHERE type = 'table' ORDER BY name"
+        ).fetchall()
+        tables = [n for n, _ in names if not n.startswith("sqlite_")]
+        virtual = {n: s for n, s in names if s and s.upper().startswith("CREATE VIRTUAL TABLE")}
+        shadow = {n for table in virtual for n in tables if n in {table + s for s in SHADOW_SUFFIXES}}
+        plain = [n for n in tables if n not in virtual and n not in shadow]
+        result["tables"] = len(plain)
+        result["indexes"] = connection.execute(
+            "SELECT count(*) FROM sqlite_master WHERE type = 'index' AND name NOT LIKE 'sqlite_%'"
+        ).fetchone()[0]
+        result["virtualTables"] = {
+            n: (re.search(r"USING\s+(\w+)", s, re.I) or [None, "unknown"])[1].lower()
+            for n, s in virtual.items()
+        }
+        has_stat = any(n == "sqlite_stat1" for n, _ in names)
+        analyzed = set()
+        if has_stat:
+            analyzed = {r[0] for r in connection.execute("SELECT DISTINCT tbl FROM sqlite_stat1")}
+        result["statistics"] = {
+            "sqliteStat1": has_stat,
+            "rows": connection.execute("SELECT count(*) FROM sqlite_stat1").fetchone()[0] if has_stat else 0,
+            "tablesWithoutStatistics": [n for n in plain if n not in analyzed],
+        }
+        if quick_check:
+            result["quickCheck"] = [r[0] for r in connection.execute("PRAGMA quick_check(10)")]
+    finally:
+        connection.close()
+    for suffix, key in (("-wal", "walBytes"), ("-shm", "shmBytes")):
+        side = result["path"] + suffix
+        result[key] = os.path.getsize(side) if os.path.exists(side) else None
+    mount = mount_for(result["path"])
+    if mount:
+        point, kind, options = mount
+        result["filesystem"] = {"mount": point, "type": kind, "options": options}
+    else:
+        result["filesystem"] = None
+    return result
+
+
+def notes(result):
+    out = []
+    if result["journalMode"] != "wal":
+        out.append("journal_mode is %s, not wal; in a rollback journal a writer's commit waits for readers and blocks new ones while it commits" % result["journalMode"])
+    stats = result["statistics"]
+    if not stats["sqliteStat1"]:
+        out.append("no sqlite_stat1: the planner has no statistics; run PRAGMA optimize at a time you choose (the first run on a large file can take over a minute and hold the write lock)")
+    elif stats["tablesWithoutStatistics"]:
+        out.append("tables with no statistics rows: " + ", ".join(stats["tablesWithoutStatistics"][:8]))
+    pages = result["pageCount"] or 0
+    if pages and result["freelistCount"] and result["freelistCount"] / pages > 0.2:
+        out.append("more than 20%% of pages are free (%d of %d); the file is larger than its content" % (result["freelistCount"], pages))
+    if result["walBytes"] and result["walBytes"] > result["fileBytes"]:
+        out.append("the WAL file is larger than the database; look for a long-running reader or a blocked checkpoint")
+    fs = result["filesystem"]
+    if fs:
+        if fs["type"] in NETWORK_FILESYSTEMS:
+            out.append("filesystem %s: WAL needs shared memory on one host and does not work reliably here" % fs["type"])
+        if re.search(r"(^|,)discard(,|$)", fs["options"]):
+            out.append("mounted with online discard; this stalled fsync on one host (see the evidence), so check fsync latency")
+    if "quickCheck" in result and result["quickCheck"] != ["ok"]:
+        out.append("quick_check reported: " + "; ".join(result["quickCheck"][:3]))
+    return out
+
+
+def render(result, source, source_errors=()):
+    lines = ["database: %s" % result["path"]]
+    lines.append("size: %d bytes; %s pages of %s bytes; %s free" % (
+        result["fileBytes"], result["pageCount"], result["pageSize"], result["freelistCount"]))
+    lines.append("journal_mode: %s; auto_vacuum: %s; user_version: %s; encoding: %s" % (
+        result["journalMode"], result["autoVacuum"], result["userVersion"], result["encoding"]))
+    lines.append("tables: %d; indexes: %d; virtual tables: %s" % (
+        result["tables"], result["indexes"],
+        ", ".join("%s (%s)" % kv for kv in result["virtualTables"].items()) or "none"))
+    stats = result["statistics"]
+    lines.append("statistics: sqlite_stat1 %s, %d rows" % ("present" if stats["sqliteStat1"] else "absent", stats["rows"]))
+    lines.append("wal file: %s; shm file: %s" % (result["walBytes"], result["shmBytes"]))
+    fs = result["filesystem"]
+    lines.append("filesystem: %s" % ("%s at %s (%s)" % (fs["type"], fs["mount"], fs["options"]) if fs else "not available on this platform"))
+    lines.append("inspector library: SQLite %s, %s" % (result["library"]["version"], result["library"]["threadsafe"]))
+    lines.append("not in the file: busy_timeout, synchronous, foreign_keys, cache_size, mmap_size, temp_store; read the code that opens the connection")
+    for note in notes(result):
+        lines.append("note: " + note)
+    if source is not None:
+        lines.append("source scan (journal_mode mentions): %d" % len(source))
+        for item in source:
+            lines.append("  %s: %s%s" % (item["file"], item["status"], "" if item["ok"] else "  <- read this"))
+        for item in source_errors:
+            lines.append("  not scanned: %s (%s)" % (item["file"], item["error"]))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("database")
+    parser.add_argument("--source", nargs="+", metavar="PATH", help="files or directories to scan for busy_timeout order")
+    parser.add_argument("--quick-check", action="store_true", help="also run PRAGMA quick_check (reads the whole file)")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    if not os.path.isfile(args.database):
+        print("error: not a file: %s" % args.database, file=sys.stderr)
+        return 2
+    try:
+        result = inspect(args.database, args.quick_check)
+    except (sqlite3.Error, OSError) as error:
+        print("error: %s" % error, file=sys.stderr)
+        return 2
+    source, source_errors = scan_source(args.source) if args.source else (None, [])
+    if args.json:
+        payload = dict(result)
+        payload["notes"] = notes(result)
+        if source is not None:
+            payload["source"] = source
+            payload["sourceErrors"] = source_errors
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(render(result, source, source_errors))
+    for item in source_errors:
+        print("error: could not scan %s: %s" % (item["file"], item["error"]), file=sys.stderr)
+    return 2 if source_errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/hr-stock-ui-audit/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: hr-stock-ui-audit
+description: Find template-default styling nobody chose for this product (stock violet accents, purple-to-blue gradients, one stock font, emoji icons, glow and blur effects), triage each hit in context, and report or fix the real ones. Use when asked to audit or remove generic or AI-looking styling in existing UI. It does not set a visual direction.
+---
+
+# Stock UI audit
+
+Generated and starter-kit interfaces share a recognizable look: an indigo or
+violet accent, a purple-to-blue hero gradient, Inter everywhere, frosted cards,
+emoji in the nav. None of these is wrong on its own. The problem is a choice
+that came with the template instead of from the product. This skill finds those
+choices with a static scanner, then sorts them by judgment. The scanner
+produces candidates; only triage produces findings.
+
+This skill removes unchosen defaults. It does not invent a brand. If the
+product has no visual direction yet, say so and ask for one rather than
+replacing one default with another.
+
+## Before you scan
+
+1. Read the brief, the design tokens and the theme or component-library config.
+   Note every color, font and component the product asked for. Those stay,
+   even when the scanner flags them.
+2. Settle the mode from the request:
+   - **Review**: report findings only. Edit nothing.
+   - **Cleanup**: fix confirmed findings, and only inside the area the user
+     named (a page, a component folder, the whole app). Report anything you
+     notice outside it instead of fixing it.
+3. Pick the scan scope: the source folders that render UI, not the whole
+   repository.
+
+## Run the scanner
+
+```sh
+bun <this skill's directory>/scripts/scan.mjs [--json] [--fail-on high|medium|low] <paths>...
+```
+
+Node 22 or later works too. It walks directories, skips dependency, build and
+coverage output and minified files, and reads `.html .css .scss .js .ts .jsx
+.tsx .vue .svelte .astro`. It prints the number of files scanned. Exit 0 means
+nothing reached the failing severity (high by default), 1 means something did,
+2 means bad usage or zero files scanned. A 2 is never a clean result. Pass
+`--fail-on medium` when violet accents, a single stock font or emoji icons
+should fail the run. Do not add the scanner as a CI gate unless asked.
+
+| Rule                    | Severity | Catches                                                                                                                                      |
+| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `purple-blue-gradient`  | high     | gradients whose stops are all cool hues with at least one violet, in CSS or Tailwind `from-`/`to-` classes                                   |
+| `violet-accent`         | medium   | any hex, rgb, hsl, oklch or bare HSL token whose computed hue lands in the indigo-to-purple band, plus Tailwind indigo/violet/purple classes |
+| `gradient-text`         | medium   | `background-clip: text` and `bg-clip-text`                                                                                                   |
+| `single-stock-font`     | medium   | one stock sans (Inter, Roboto, Poppins and similar) as the only named face across two or more declarations in the scanned set                |
+| `emoji-icon`            | medium   | emoji inside headings, buttons, links, nav items or `icon`/`label`/`title` fields                                                            |
+| `neon-glow`             | medium   | zero-offset, wide-blur shadows in a saturated color, and Tailwind colored shadows                                                            |
+| `frosted-glass`         | low      | `backdrop-filter: blur()` and `backdrop-blur`                                                                                                |
+| `library-default-token` | low      | untouched default primaries from Bootstrap, Material, MUI, Ant Design, Chakra, shadcn/ui and the Vite starter                                |
+| `tracked-caps`          | low      | uppercase text with wide letter spacing                                                                                                      |
+
+The font rule looks across every file in one run, so scan the whole UI scope
+together; scanning one file at a time hides it.
+
+## Triage every match
+
+Open each flagged line and read enough around it to see what the element is for.
+Give every match exactly one verdict:
+
+- **Unchosen default**: nothing in the brief, tokens or history asks for it,
+  and it reads like a starter template. This is a finding.
+- **Deliberate choice**: the brief, a token file, a brand guide or a commit
+  message shows someone picked it. Keep it and name the evidence.
+- **False positive**: the match is not doing what the rule assumes, such as a
+  violet hue in a syntax-highlighting theme, a blur on a modal backdrop over
+  busy content, or an emoji inside user-generated sample data. Leave it and say
+  why.
+- **Unresolved**: you cannot tell whether someone chose it. It is not a
+  finding and you change nothing. Report what is missing and the question
+  that would settle it.
+
+## Fixing what is real
+
+- Fix the cause, not the line. Five violet hexes usually mean one missing
+  accent token; define the product's palette and type once and point the
+  components at it.
+- Choose replacements that serve the content: contrast that holds, an accent
+  that marks the one action that matters, type that suits the reading load.
+- Never nudge a value just to leave the scanner's range, such as shifting a hue
+  a few degrees or swapping a hex for an equivalent `oklch()`. If the color is
+  wrong, change it; if it is right, keep it and record why.
+- Never change a brand color, a status color (success, warning, error) or a
+  focus indicator to make the scan pass. Those carry meaning; record them as
+  deliberate.
+- Replace emoji icons with the project's existing icon set. Add a new icon
+  dependency only if the user agrees.
+
+## What the scanner cannot see
+
+Check these by reading the rendered page, since no pattern match finds them:
+
+- every section built from the same centered headline, subtitle and two buttons
+- a three-card feature grid with an icon, title and line of text in each card
+- a small badge or pill sitting above the main heading
+- cards marked by a thick colored left border
+- a stat banner of large numbers ("10k+ users", "99.9% uptime")
+- numbered "1, 2, 3" step sections
+- a dark theme forced on with no light option the brief asked for
+- the same large corner radius and soft shadow on every surface
+- spacing and type sizes that ignore the project's scale
+- copy that could describe any product
+
+## Verify
+
+1. Rerun the scanner on the same scope and confirm each remaining match has a
+   recorded verdict.
+2. Look at the rendered UI at the sizes that matter (a narrow phone width and
+   a desktop width at least), in every theme the product ships.
+3. A clean scan says nothing about accessibility, layout or overall quality.
+   Check contrast and focus states on anything you changed.
+
+If you could not render the UI, say the review was static only.
+
+## Report
+
+Write the report in this order:
+
+1. Scope scanned, files scanned, mode, and the scanner's exit code.
+2. Findings fixed (or, in review mode, proposed), each with `file:line`, the
+   rule, and what replaced it.
+3. Matches kept as deliberate, each with its evidence.
+4. Unresolved matches, each with what is missing and the question that
+   settles it.
+5. False positives, each with one line on why.
+6. Issues the scanner cannot see, if you found any.
+7. How you verified: rerun result, sizes and themes viewed, or "static only".

package/skills/hr-stock-ui-audit/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Stock UI audit"
+  short_description: "Audit or clean up unchosen template styling in UI code"