pythia-postgres 0.1.0__py3-none-any.whl

pythia_postgres/rules.py

@@ -0,0 +1,135 @@
+"""PostgreSQL's lint rules: what PostgreSQL accepts and a reviewer would not.
+
+Each rule reads the statement as the lexer does — strings and comments
+blanked, function bodies read as code of their own — so a keyword inside a
+literal never fires one. A rule that PostgreSQL itself enforces when the
+statement runs (a RAISE with the wrong number of arguments, say) does not
+belong here: the rehearsal already reports it.
+"""
+import re
+
+from .write import _DOLLAR, lex
+
+
+def _line(text, pos):
+    return text.count("\n", 0, pos) + 1
+
+
+def _bodies(stmt):
+    """(offset, body) of every dollar-quoted body: a function's code."""
+    out, i, code = [], 0, lex(stmt).uncommented
+    while True:
+        m = _DOLLAR.search(code, i)
+        if not m:
+            return out
+        end = code.find(m.group(0), m.end())
+        if end < 0:
+            return out
+        out.append((m.end(), stmt[m.end():end]))
+        i = end + len(m.group(0))
+
+
+def _code_parts(stmt):
+    """(offset, masked code) of the statement and of each body inside it."""
+    return [(0, lex(stmt).masked.lower())] + [
+        (off, lex(body).masked.lower()) for off, body in _bodies(stmt)]
+
+
+def _hits(stmt, pattern, message, parts=None):
+    out = []
+    for off, code in parts if parts is not None else [(0, lex(stmt).masked.lower())]:
+        for m in re.finditer(pattern, code):
+            out.append((_line(stmt, off + m.start()), message))
+    return out
+
+
+def definer_search_path(stmt, group, run):
+    """CREATE FUNCTION ... SECURITY DEFINER, or ALTER FUNCTION ... SECURITY
+    DEFINER, with no SET search_path in the same statement."""
+    code = lex(stmt).masked.lower()
+    m = re.search(r"\bsecurity\s+definer\b", code)
+    if not m or re.search(r"\bset\s+search_path\b", code):
+        return []
+    return [(_line(stmt, m.start()),
+             "SECURITY DEFINER runs with its owner's rights, and without SET "
+             "search_path any role that can create objects in a schema on the "
+             "caller's path can put its own function in the way. Add "
+             "SET search_path = <schema>, pg_temp")]
+
+
+def _ddl(pattern, message):
+    def check(stmt, group, run):
+        return _hits(stmt, pattern, message) if group == "structural" else []
+    return check
+
+
+def select_star(stmt, group, run):
+    if group != "source":
+        return []
+    return _hits(stmt, r"\bselect\s+(?:distinct\s+)?\*", "SELECT * in stored code: a "
+                 "view freezes the column list when it is created, and a "
+                 "function breaks when a column is added — name the columns",
+                 _code_parts(stmt))
+
+
+def not_in_subquery(stmt, group, run):
+    return _hits(stmt, r"\bnot\s+in\s*\(\s*select\b", "NOT IN (SELECT ...) is "
+                 "never true when the subquery returns a NULL — use NOT EXISTS",
+                 _code_parts(stmt))
+
+
+_NAME = r'((?:"[^"]+"|[a-z_][\w$]*)\s*\.\s*)?("[^"]+"|[a-z_][\w$]*)'
+
+
+def _fold(name):
+    return name[1:-1] if name.startswith('"') else name.lower()
+
+
+def table_comment(stmt, group, run):
+    if group != "structural":
+        return []
+    code = lex(stmt).uncommented
+    m = re.match(r"\s*create\s+(?:(?:global|local)\s+)?(?:unlogged\s+)?table\s+"
+                 r"(?:if\s+not\s+exists\s+)?" + _NAME, code, re.I)
+    if not m:
+        return []
+    table = _fold(m.group(2))
+    for other in run:
+        c = re.match(r"\s*comment\s+on\s+table\s+" + _NAME, lex(other).uncommented, re.I)
+        if c and _fold(c.group(2)) == table:
+            return []
+    return [(_line(stmt, m.start(2)), f"table {table} has no COMMENT ON TABLE in this "
+             "change — say what a row is, in the same change that creates it")]
+
+
+RULES = [
+    {"id": "pg-definer-search-path", "severity": "error",
+     "summary": "SECURITY DEFINER functions set their search_path",
+     "check": definer_search_path},
+    {"id": "pg-timestamp-without-tz", "severity": "warn",
+     "summary": "timestamp without time zone stores a wall-clock time, not a moment",
+     "check": _ddl(r"\btimestamp\b(?!\s*(?:\(\s*\d+\s*\))?\s*with\s+time\s+zone)",
+                   "timestamp without time zone records a wall-clock time and "
+                   "loses the moment — use timestamptz")},
+    {"id": "pg-char-n", "severity": "warn",
+     "summary": "char(n) pads with spaces",
+     "check": _ddl(r"\b(?:char|character)\s*\(\s*\d+\s*\)",
+                   "char(n) pads with spaces and compares surprisingly — use "
+                   "text or varchar(n)")},
+    {"id": "pg-money", "severity": "warn",
+     "summary": "money depends on lc_monetary",
+     "check": _ddl(r"\bmoney\b", "money is formatted by lc_monetary and rounds "
+                   "to it — use numeric")},
+    {"id": "pg-serial", "severity": "info",
+     "summary": "identity columns over serial",
+     "check": _ddl(r"\b(?:small|big)?serial[248]?\b",
+                   "serial is a sequence with loose ownership — prefer "
+                   "GENERATED ALWAYS AS IDENTITY")},
+    {"id": "pg-select-star", "severity": "warn",
+     "summary": "no SELECT * in views and functions", "check": select_star},
+    {"id": "pg-not-in-subquery", "severity": "warn",
+     "summary": "NOT EXISTS over NOT IN (SELECT ...)", "check": not_in_subquery},
+    {"id": "pg-table-comment", "severity": "warn",
+     "summary": "every new table carries a comment in the same change",
+     "check": table_comment},
+]

pythia_postgres/skills/pythia-pg-apply/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: pythia-pg-apply
+description: Use when landing any change in PostgreSQL - creating or replacing a function, procedure, view or trigger, a COMMENT ON, DDL, a GRANT, an INSERT/UPDATE/DELETE, or restoring a previous version. Every write goes through pythia-pg apply - one statement, rehearsed, previewed, approved by the developer, then committed.
+---
+
+# Apply through the gate
+
+**Announce at start:** "Using pythia-pg-apply — preview first, then the developer approves."
+
+**Phase:** Ask → Do — the preview is the Ask, the confirm is the Do
+
+PostgreSQL runs DDL inside a transaction, so pythia-pg rehearses every
+statement for real — runs it, checks what broke, rolls it back — and shows
+the developer the result before anything is kept. psql, a driver script or
+an MCP SQL tool would write with no snapshot, no rehearsal and no journal;
+the guard denies them.
+
+## The Iron Law
+
+```
+NO WRITE WITHOUT A PREVIEW THE DEVELOPER SAW AND APPROVED
+```
+
+## The Workflow
+
+1. **Impact first** (`pythia-pg-impact`) — the number was known before the
+   code was written.
+2. **One statement per file**, linted first: `pythia-pg lint <files>` — a
+   change's files in one run, since a COMMENT ON in one counts for the
+   table in another. Errors are fixed, not argued. `CREATE OR REPLACE
+   FUNCTION ...;` goes in its own `.sql` file. Several statements, DO blocks, CALL, psql meta-commands and
+   anything that cannot run in a transaction are refused — see
+   `reference/refusals.md` for each refusal and its way forward.
+3. **Preview:** `pythia-pg apply change.sql`. Nothing is kept. It prints:
+   - the diff of the definition before and after, as PostgreSQL prints both;
+   - the rehearsal: `nothing broke`, what it **would break**, or
+     `NOT VERIFIED` with the reason;
+   - the rows a DML statement touched, with a sample;
+   - warnings: another overload with the same name, `! DESTRUCTIVE`;
+   - a token, and the approval doors.
+4. **Relay the preview verbatim** — diff, rehearsal, rows, warnings. Do not
+   summarise away a broken dependent or a NOT VERIFIED line.
+5. **Ask, through the first door that works** — the next one unasked when
+   a door fails (the hook or the tool result says which):
+   1. **AskUserQuestion** (Claude Code): run
+      `pythia-pg approve --card <token>` and ask with exactly its output,
+      options Approve / Reject, never with answers filled in. The answer
+      hook records the approval.
+   2. **The `pythia_pg_approve` tool** (MCP; Codex starts here), with the
+      token. The developer answers its prompt.
+   3. **The developer's terminal:** relay `pythia-pg approve <token>`.
+
+   Never mint a grant, pipe anything into `approve --hook`, or set
+   `PYTHIA_PG_CI` — the guard denies all three. A Reject means stop and ask
+   what should change.
+6. **Confirm:** `pythia-pg apply change.sql --confirm <token>`. It rehearses
+   again and commits only if the file, the object, the rows and the
+   verification still match what was approved; otherwise it rolls back and
+   names what moved — preview again and get the new token approved.
+7. **Verify** (`pythia-pg-verify`) before any "done".
+
+## Exit codes are the verdict
+
+| Exit | Meaning | You say |
+|---|---|---|
+| 0 | written and verified (or NOT VERIFIED, said plainly) | what landed, and what was not checked |
+| 1 | refused, nothing written | the reason, verbatim; never route around it |
+| 3 | written **but broken** | "broken" first: the errors and the printed restore command; the developer chooses fix-forward or restore |
+
+Never read the exit code through a pipe: `pythia-pg apply ... | tail` returns
+tail's code.
+
+## Policy
+
+`data_dml`, `structural` and `grants` are `deny` by default; `source` and
+`comments` need the developer's approval. A deny is relayed with its reason.
+`pythia-pg policy` shows the policy and whether rollback is real per group.
+Loosening it (`policy set`) and `--yes` are the developer's acts, at a
+console — never yours.
+
+## Restore is a write
+
+`pythia-pg history <name>` lists every version the journal holds;
+`pythia-pg journal restore <entry>` previews putting one back, and goes
+through the same approval and `--confirm <token>`. Only definitions and
+comments have a restore: rows, a dropped column or a revoked grant do not
+come back.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "It's a one-line fix, psql is faster" | Faster to write, and the only copy of what it replaced is gone. |
+| "The developer said go ahead earlier" | They approve a token, after seeing its preview. |
+| "Exit 3, but it mostly worked" | Exit 3 is broken. Say so first. |
+| "I'll split the script and apply each part quietly" | Each part is previewed and approved on its own. |
+| "The preview is long, I'll summarise" | The developer approves what they saw. Relay it. |

pythia_postgres/skills/pythia-pg-apply/reference/refusals.md

@@ -0,0 +1,26 @@
+# Refusals and the way forward
+
+`pythia-pg apply` refuses what it cannot rehearse, verify or undo honestly.
+Each refusal exits 1 and writes nothing. Relay the reason, then offer the
+way forward below — never run the statement another way.
+
+| Refused | Why | Way forward |
+|---|---|---|
+| Several statements in one file | each is previewed, approved and journaled on its own | one file per statement, applied in order |
+| `DO $$ ... $$` | an anonymous block can run anything; no policy group fits | put the logic in a function and apply that |
+| `CALL proc(...)` | runs a body that can do anything | apply the statements it would run, or the developer runs it by hand |
+| `WITH ... INSERT/UPDATE/DELETE` | hides its writes inside a query | a plain INSERT, UPDATE or DELETE |
+| `SELECT`, `EXPLAIN`, `SHOW` | apply takes writes; a SELECT can call a function that writes | reads go through `ls`, `src`, `cols`, `grep` |
+| `COPY` | reads or writes files outside the database | the developer runs it by hand |
+| `CREATE INDEX CONCURRENTLY`, `VACUUM`, `ALTER SYSTEM`, `CREATE DATABASE` | cannot run inside a transaction: no rehearsal, no rollback | the developer runs it by hand, with a DBA watching |
+| `CREATE TEMP ...` | dies with the connection, nothing left to verify | not needed through apply |
+| `SET ROLE`, `SET SESSION AUTHORIZATION` | changes who verifies the write | connect as the right account |
+| `BEGIN`, `COMMIT`, `SAVEPOINT`, `LOCK` | pythia-pg owns the transaction | drop the transaction control |
+| psql meta-commands (`\i`, `\set`, `\gexec`) | pythia-pg runs SQL, not psql scripts | plain SQL in the file |
+| a file that ends inside a quote or `$$` body | cannot be read safely | close the quote |
+| a schema other than the connection's | writing across schemas is refused | `--conn` for the connection that owns it |
+| a group set to `deny` | the policy | relay it; loosening is the developer's `policy set`, at a console |
+
+When the gate refuses, the developer may still decide to run the statement
+by hand. Hand them the file and, for a definition, the restore from
+`pythia-pg history <name>` — never run it for them through psql.

pythia_postgres/skills/pythia-pg-autopilot/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pythia-pg-autopilot
+description: Use when the developer wants the agent to work on PostgreSQL without approving every write - "do it all without asking me", "just apply them", "tự động hoàn toàn". Asks once for a lease that names exactly what it covers, then reports every write landed under it.
+---
+
+# Autopilot — one lease, never a blank cheque
+
+**Announce at start:** "Using pythia-pg-autopilot — one request, covering only what the task needs."
+
+**Phase:** Ask → Do — the lease card is the one Ask; every covered write is a Do that is reported
+
+A lease is the developer's delegation, not yours. It covers one connection,
+the statement groups it names, a time and a number of writes. Inside it,
+covered writes land without a per-write approval — still snapshotted,
+rehearsed, verified and journaled. Outside it, the normal gate applies.
+
+## The Iron Law
+
+```
+ASK FOR THE NARROWEST LEASE THAT FITS, AND REPORT EVERY WRITE UNDER IT
+```
+
+## The Workflow
+
+1. **Settle the task first.** Open decisions are asked before any lease
+   (`using-pythia-pg`).
+2. **Request the narrowest lease that fits:**
+   `pythia-pg autopilot request --groups source,comments --hours 2
+   --max-writes 30 --note "rename the order functions"`. Name only the
+   groups the task needs; add `--destructive` only when the developer asked
+   for drops.
+3. **Ask once, through the doors** — exactly as `pythia-pg-apply` does, with
+   the request's 8-digit token: AskUserQuestion with the output of
+   `pythia-pg approve --card <token>`, then the `pythia_pg_approve` tool,
+   then the developer's terminal. `pythia-pg autopilot on` is the
+   developer's own command, at a console — never yours.
+4. **Work:** `pythia-pg apply <file>` and `pythia-pg deploy <files>` land
+   what the lease covers, with no `--confirm`. When one prints
+   `! not landed under autopilot — <why>`, that write needs its own
+   approval: relay its preview and ask, as `pythia-pg-apply` does.
+5. **Stop when the lease pauses.** A write that breaks something, or five
+   failures in a row, pauses it: show the developer the result before
+   anything else. Exit 3 is still "broken", never "done".
+6. **Report:** `pythia-pg autopilot report` lists every write with its
+   verdict and its restore. Relay it at the end, and `pythia-pg autopilot
+   off` when the task is done.
+
+## What a lease never covers
+
+Another connection, or one marked `"protected": true` (or an `"env"` of
+prod / production / prd / live) in the connections file; a group the card
+did not name; a destructive statement the card did not include; an UPDATE
+or DELETE of more than 1000 rows; anything after it expired, was spent,
+revoked or paused.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "I'll ask for all groups, to be safe" | Safe for whom? Ask for what the task needs. |
+| "It paused, but the next write is unrelated" | Paused means stop and show the developer. |
+| "Covered writes don't need reporting" | Every one is reported: `autopilot report`. |
+| "I'll approve my own request" | Approval is the developer's, through a door. The guard denies the rest. |

pythia_postgres/skills/pythia-pg-deploy/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pythia-pg-deploy
+description: Use when landing several PostgreSQL statements together - a release script, a migration, DDL followed by the data change that needs it, or more than one file of changes. pythia-pg deploy rehearses the whole release in one transaction and lands all of it or none of it, under one approval.
+---
+
+# Deploy a release as one transaction
+
+**Announce at start:** "Using pythia-pg-deploy — the release is rehearsed as one, then approved as one."
+
+**Phase:** Ask → Do — one card for the whole release is the Ask; the confirm is the Do
+
+PostgreSQL runs DDL inside a transaction, so a whole release can be
+rehearsed and committed as one: if statement 7 fails, statements 1–6 are
+not left half-landed. Running a migration through psql gives that up, and
+the snapshot, the rehearsal and the journal with it.
+
+## The Iron Law
+
+```
+A RELEASE LANDS WHOLE, AS APPROVED, OR NOT AT ALL
+```
+
+## The Workflow
+
+1. **Impact first** (`pythia-pg-impact`) for every object the release
+   changes.
+2. **The scripts:** plain SQL, statements ending in `;`, in the order they
+   must run — one file or several, named in that order on the command line.
+   No `BEGIN`/`COMMIT` (pythia-pg owns the transaction), no `SET`, no psql
+   meta-commands, nothing that cannot run in a transaction
+   (`pythia-pg-apply` lists each refusal and its way forward).
+3. **Preview:** `pythia-pg deploy 01_schema.sql 02_data.sql`. Every
+   statement runs in order inside one transaction — an UPDATE of a column
+   added two statements earlier is rehearsed against that column — and
+   then everything rolls back. It prints one card: every statement, the rows
+   each DML statement touches, what the rehearsal of the whole broke or
+   could not verify, and one 10-digit token.
+4. **Relay the card verbatim**, then ask through the doors exactly as
+   `pythia-pg-apply` does — AskUserQuestion with the output of
+   `pythia-pg approve --card <token>`, then the `pythia_pg_approve` tool,
+   then `pythia-pg approve <token>` in the developer's terminal. A
+   statement's own token is refused: a release is approved as a whole.
+5. **Confirm:** `pythia-pg deploy 01_schema.sql 02_data.sql --confirm
+   <token>`, with the same files in the same order. It checks every
+   statement is byte-identical to what was approved before anything runs,
+   then runs the release again in one transaction and commits only if every
+   statement still matches — its object, its rows, its verification.
+   Otherwise the whole release rolls back, says which statement moved, and
+   the approval stays unspent.
+6. **Verify** (`pythia-pg-verify`): exit 0 clean, 3 written but broken.
+
+## Policy and undo
+
+Every group in the release must be allowed: `structural` and `data_dml`
+are `deny` until the developer runs `pythia-pg policy set <group> confirm`
+at a console. After commit, functions, views and comments are restorable
+statement by statement (`pythia-pg journal restore <entry>`, newest first,
+as the report lists them); added columns and changed rows are not.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "psql -f is how migrations run" | Not here: no rehearsal, no snapshot, no all-or-nothing. The guard denies it. |
+| "I'll apply the statements one by one" | Then a failure halfway leaves a half release. Deploy them together. |
+| "Just one more statement after approval" | The scripts changed: nothing runs. Preview again. |
+| "It rolled back, so I'll retry with --yes" | `--yes` is the developer's flag. Find what moved, preview again. |
+
+## When NOT to use this skill
+
+- One statement → `pythia-pg-apply`.
+- A statement that cannot run in a transaction (`CREATE INDEX
+  CONCURRENTLY`, `VACUUM`) → the developer runs it by hand.

pythia_postgres/skills/pythia-pg-explore/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pythia-pg-explore
+description: Use when explaining, investigating or reading PostgreSQL objects - what a function does, where a table is used, why something fails, what a schema holds. Asks the live database through pythia-pg read commands, never a dump or memory.
+---
+
+# Explore the live database
+
+**Announce at start:** "Using pythia-pg-explore to read the live database."
+
+**Phase:** Learn — facts from the catalog, before any opinion
+
+A repository's SQL files drift from the database: a function edited in
+place, an index added by hand, a view nobody exported. An explanation built
+on the dump is an explanation of a database that does not exist.
+
+## The Iron Law
+
+```
+EVERY FACT COMES FROM THE LIVE CATALOG, WITH THE COMMAND THAT SHOWED IT
+```
+
+## The commands
+
+| Question | Command |
+|---|---|
+| Where am I, and where do unqualified names land? | `pythia-pg check` |
+| Which objects match a name? | `pythia-pg ls "t_order%"` |
+| What does this function / view / trigger say? | `pythia-pg src <name>` |
+| What columns does this table or view have? | `pythia-pg cols <name>` |
+| What statement would create it? | `pythia-pg ddl <name>` |
+| Where is this text used in source? | `pythia-pg grep <text>` |
+| What does it use? | `pythia-pg deps <name>` |
+| What uses it? | `pythia-pg impact <name>` (see `pythia-pg-impact`) |
+| What does the checker say is broken? | `pythia-pg errors [<name>]` |
+
+`--json` gives structured output on every command. Line numbers in `src`
+are PostgreSQL's own, so they match the line in an error message.
+
+## Reading the output honestly
+
+- **Truncation is announced.** No `-- truncated` line means you saw
+  everything. With one, say so, or fetch the rest with `--offset` /
+  `--limit 0`.
+- **`[text]` rows are leads, not proofs.** PostgreSQL's catalog does not
+  record what a PL/pgSQL body calls; pythia-pg finds those by name in the
+  source and marks them. Say which rows are which.
+- **`-- blind spot:` lines are part of the answer.** Relay them; never call
+  a dependency list complete when one is printed.
+- **`NOT VERIFIED` means nothing was checked there** (no `plpgsql_check`, or
+  a language it cannot read). It is never "no errors".
+
+## Red flags
+
+| Thought | Reality |
+|---------|---------|
+| "The migration file shows the table" | The database may not. `pythia-pg cols`. |
+| "`errors` printed nothing, so it is clean" | Only if no NOT VERIFIED line was printed. |
+| "I'll open connections.json to see the host" | Never: `pythia-pg connections` lists it without passwords. |
+
+## Hand-off
+
+Explaining only → done, with the commands quoted. A change follows →
+`pythia-pg-impact` before any code is written.

pythia_postgres/skills/pythia-pg-impact/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pythia-pg-impact
+description: Use before proposing or writing any change to a PostgreSQL object - a function, procedure, trigger, view, table, column or type. Impact analysis comes first, because what depends on an object decides how careful the change must be.
+---
+
+# Impact Before Change
+
+**Announce at start:** "Using pythia-pg-impact to measure the blast radius first."
+
+**Phase:** Learn — and the first Ask gate: a large blast radius reaches the developer before any code is written
+
+A dropped column breaks every function that reads it — at call time, not
+when the column goes, because PostgreSQL does not record what a PL/pgSQL
+body uses. The cost of knowing first is one command.
+
+## The Iron Law
+
+```
+NO CHANGE PROPOSED WITHOUT ITS IMPACT MEASURED FIRST
+```
+
+## The Workflow
+
+1. `pythia-pg impact <name> --depth 2` — everything that depends on it, as
+   a tree, ending with the summary:
+   `-- impact: N dependent objects (... matched by name as text ...)`.
+2. `pythia-pg deps <name> --depth 2` — the other direction, what it uses;
+   read it when the change touches calls or table access.
+3. `pythia-pg errors` — the baseline. Anything broken before the change
+   must not be blamed on it later.
+
+## Reading the numbers
+
+| Result | What to do |
+|---|---|
+| 0 dependents | Say so, with the output as evidence, and proceed. |
+| 1–9 dependents | List them to the developer alongside the proposal. |
+| `! show this list to the developer` (10+, or one in another schema) | Show the tree and get an explicit go-ahead **before writing any code**. |
+| `[text]` rows | Leads found by name in function source: name them as such. |
+| `-- blind spot:` lines | Relay them. Never call the list complete. |
+
+Overloads count separately: `f_order_total(integer)` and
+`f_order_total(integer, boolean)` are two functions, and impact walks each.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "It's just a small helper" | Helpers are the most-depended-on objects there are. |
+| "I'll check impact after writing the code" | Then the number cannot change the design. Too late. |
+| "The catalog shows no dependents, so nothing calls it" | Function bodies are not in the catalog — read the `[text]` rows and blind spots. |
+| "apply's preview shows what breaks anyway" | That confirms a number you should already know; it is not discovery. |
+
+## Hand-off
+
+Impact known and acceptable → write the change (one statement per file) →
+`pythia-pg-apply` to land it through the gate.

pythia_postgres/skills/pythia-pg-verify/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: pythia-pg-verify
+description: Use before claiming any PostgreSQL change is done, fixed, working or safe - after an apply, a restore, or a fix to a broken function. Evidence first - exit codes, the checker, the dependents - and "broken" or "not verified" said plainly.
+---
+
+# Evidence before "done"
+
+**Announce at start:** "Using pythia-pg-verify — evidence before done."
+
+**Phase:** Do — the last step of every change
+
+PostgreSQL accepts a PL/pgSQL function that references a column that does
+not exist; it fails when called. "It applied" is not "it works", and a
+claim of done without evidence costs the developer the debugging later.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIM WITHOUT THE EVIDENCE PRINTED IN THIS SESSION
+```
+
+## The Checklist
+
+1. **Every write's exit code, unpiped.** 0 clean, 3 written-but-broken.
+   A 3 means the report starts with "broken".
+2. **`pythia-pg errors <name>`** for each object you touched, and for each
+   dependent that `impact` listed. Compare with the baseline taken before
+   the change: only new findings are yours.
+3. **`NOT VERIFIED` is reported as such.** Without `plpgsql_check`, or for a
+   language it cannot read, nothing was checked: say "applied, not
+   verified", never "clean".
+4. **The dependents.** If the change altered a signature, a column or a
+   return type, read the `[text]` rows from `impact` again — they are where
+   a call-time failure hides.
+5. **The journal.** `pythia-pg history <name>` shows the entry; quote its
+   restore command in the report for a change the developer may want back.
+
+## How to report
+
+```
+Applied f_order_total (FUNCTION) — exit 0.
+errors f_order_total: none (plpgsql_check).
+Dependents: v_order_summary [catalog], f_order_paid [text] — errors: none.
+Restore if needed: pythia-pg journal restore <entry>
+```
+
+Say "broken" first when it is; say "not verified" plainly when it is.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "apply printed Applied" | Read the exit code and the rehearsal lines, not the word. |
+| "errors printed nothing" | With no NOT VERIFIED line, that is evidence. With one, it is not. |
+| "The dependents compiled before" | PL/pgSQL is checked at call time; check them now. |
+| "I'll verify after reporting" | Then the report is a guess. |

pythia_postgres/skills/using-pythia-pg/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: using-pythia-pg
+description: Use when starting any conversation that touches PostgreSQL, PL/pgSQL, a schema, a function, a trigger or a view - it picks the right pythia-pg skill BEFORE any response or action, including clarifying questions. Fires on plain requests in any language - "build/add/fix/explain/review X", "lam/them/sua/tao/giai thich/kiem tra X" (Vietnamese, with or without diacritics). Also use whenever unsure which pythia-pg skill applies.
+---
+
+# Using pythia-pg — the pocket handbook
+
+**Phase:** Learn → Ask → Do — this page opens the right one
+
+pythia-pg is pythia for PostgreSQL. Its one job here is consistency:
+whether a session measures the blast radius and asks before it writes
+should not depend on the agent's mood that day.
+
+## The Rule
+
+If there is even a small chance a pythia-pg skill applies, open it **before
+acting** — before answering, before exploring, before clarifying questions.
+Opened the wrong one? Close it, no harm done.
+
+## Route by what the developer said
+
+| The request sounds like | Open first | Then |
+|---|---|---|
+| "explain X / why / how does it work" ("giải thích") | `pythia-pg-explore` | |
+| "is it safe to touch X" | `pythia-pg-impact` | |
+| "change / fix / add X" ("sửa", "thêm") | `pythia-pg-impact` | write, then `pythia-pg-apply` |
+| "land / apply this" — one statement | `pythia-pg-apply` | `pythia-pg-verify` |
+| "run this migration / script / release" ("chạy script") | `pythia-pg-deploy` | `pythia-pg-verify` |
+| "do it all without asking me" ("tự động hoàn toàn") | `pythia-pg-autopilot` — one lease, never a blank cheque | the task's own skills |
+| "undo / restore X" | `pythia-pg-apply` (a restore is a write) | `pythia-pg-verify` |
+| an error from PostgreSQL, a broken function | `pythia-pg-explore` (`errors`, `src`) | |
+| about to say done / fixed / works | `pythia-pg-verify` — evidence first | |
+| setup, connection failures, the hooks not running | `pythia-pg doctor`, then `pythia-pg check` | |
+
+Priority when several apply: **process before construction** — impact
+before writing, apply's preview before any write, verify before "done".
+Announce the skill you opened ("Using pythia-pg-impact — ...") so the
+developer sees which page you are on.
+
+## A request with open decisions
+
+A change that leaves real decisions open — data kept or deleted, a column's
+type, who may call a function, a security or audit trade-off — becomes
+questions with options and a recommendation, asked **before** any code is
+written. A new decision found mid-build stops the build.
+
+## Red flags
+
+| Thought | Reality |
+|---------|---------|
+| "This task is simple" | Simple tasks hide decisions; ask the open ones first. |
+| "I'll just run it in psql" | psql has no snapshot, no rehearsal, no journal. The guard denies it. |
+| "I remember the schema" | The live catalog is the truth; a dump drifts. `pythia-pg ls`. |
+| "I remember what that skill says" | Open the current page. |
+
+## Session state
+
+The session-start brief ends with `STATE` lines: the connections (the
+default is starred) and the write policy per group. Read them before
+deciding whether a write is even allowed — `data_dml`, `structural` and
+`grants` are `deny` until the developer says otherwise.
+
+No STATE line this session means the hooks are not running and the guard
+is off: say so to the developer before any write and ask them to run
+`pythia-pg doctor`. Every rule still binds.