pythia-plsql 0.1.0__py3-none-any.whl

pythia_plsql-0.1.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: pythia-plsql
+Version: 0.1.0
+Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
+License: MIT
+Project-URL: Homepage, https://github.com/thaildhe172591/pythia
+Project-URL: Repository, https://github.com/thaildhe172591/pythia
+Keywords: oracle,plsql,database,agent-skills,sql
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oracledb>=2.0
+Dynamic: license-file
+
+# pythia
+
+> Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
+
+[![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI coding
+agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills` supports).
+Explore schemas too big to dump, measure blast radius **before** touching anything,
+and land changes through a snapshot-verified write path that never lies about rollback.
+
+## Why ask the database instead of reading dumps
+
+A real mid-size system, repo export vs live database, audited in 2026:
+
+| Object type | In the dump | In the database | Verdict |
+|---|---|---|---|
+| Procedures | 3,827 | 3,827 | matched |
+| Tables | 952 | 952 | matched |
+| **Types** | **0** | **115** | **all missing** |
+| **Packages** | **0** | **9** | **all missing** |
+| **Indexes** | **116** | **1,016** | **~89% missing** |
+
+Code that "reads fine" against the dump references types and packages the dump never
+heard of. Every pythia command asks the live data dictionary instead — and every
+truncated output says so, so an agent never mistakes a partial answer for a full one.
+
+## How it works
+
+```
+developer chats with the agent
+        │
+skills/  teach the agent when to ask, when to stop, when to ask YOU
+        │
+pythia   CLI — expert queries, impact analysis, the six-step write path
+        │
+Oracle   data dictionary: ALL_SOURCE, ALL_DEPENDENCIES, ALL_ERRORS, PL/Scope
+```
+
+The write path is the heart: **snapshot → impact → preview → apply → verify → report**.
+DDL self-commits in Oracle — the snapshot is the only real undo, so it always runs
+first and no flag can turn it off. A 6-hex token binds the write to exactly what was
+previewed; exit codes make honesty machine-readable
+(`0` clean · `1` refused · `3` **written but broken — never reported as success**).
+
+## Install
+
+```bash
+npx pythia-plsql           # everything: pip install + skills picker + config scaffold
+```
+
+Or the same thing piecewise:
+
+```bash
+pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
+pythia install             # skills into your agent + .pythia/connections.json scaffold
+pythia check               # fill in connections.json first, then verify
+```
+
+The pip package is the whole kit: with Node.js present, `pythia install`
+runs `npx skills add` (77 agents, symlinked updates; `--source <git-url>`
+for internal mirrors) — without Node it copies the bundled skill pack into
+`.claude/skills/` and `.agents/skills/`. Skills alone: `npx skills add
+thaildhe172591/pythia`, or `/plugin marketplace add thaildhe172591/pythia`.
+
+Running from a clone works too — `python scripts/pythia.py <command>`; every
+printed follow-up command matches how you invoked it. Windows, macOS, Linux
+and WSL are all CI-tested.
+
+## Commands
+
+| Read | Understand | Write |
+|---|---|---|
+| `check` connectivity + counts | `deps` what it depends on | `apply` the six-step write |
+| `ls` find objects | `impact` what depends on it | `journal` list · diff · export · restore |
+| `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
+| `args` signatures | `invalid` everything broken | |
+| `ddl` via DBMS_METADATA | `plscope` exact identifier usages | |
+| `cols` columns + types | `similar` programs named like this | |
+| `grep` search all source | | |
+| `sql` free query (SELECT/WITH only) | | |
+
+Every command takes `--json` (machine output), `--conn` (pick a connection), and
+caps output with explicit truncation markers so context windows stay intact.
+
+**Your house style is config, not folklore**: put naming patterns in
+`.pythia/conventions.json` and apply previews warn when a new object's name
+drifts; put the prose rules in `.pythia/conventions.md` and the skills make
+every agent read them first (`pythia conventions` shows both).
+
+## Security & write policy
+
+**The account is the real security layer** — the policy file is an application-side
+fence. Give the agent its own revocable credential with proxy authentication
+(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared):
+see [`examples/agent-user-setup.example.sql`](examples/agent-user-setup.example.sql).
+`pythia check` warns when the session runs with more power than the task needs.
+
+Per-group write policy, `.pythia/policy.json` (defaults shown):
+
+| Group | Default | Is rollback real? |
+|---|---|---|
+| `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
+| `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. |
+| `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
+| `grants` | `deny` | Yes, but by hand. |
+| `session` | `allow` | Not needed. |
+
+The groups that cannot be snapshotted default to `deny` — and the refusal says that,
+instead of "policy forbids it". Anonymous PL/SQL blocks are refused outright.
+Unrecognized statements are refused, never guessed into a group.
+
+Reads may flow through Oracle's official SQLcl MCP server (`sql -mcp`, keep `-R 4`);
+it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
+`pythia apply` has the snapshot, preview, verify and journal.
+
+## Skills
+
+Seven skills teach the agent the workflow — superpowers-style gates, not suggestions:
+
+`plsql-setup` · `plsql-explore` · `plsql-impact` (impact **before** any change) ·
+`plsql-write` (copy the codebase's conventions) · `plsql-apply` (the gate: the
+developer sees the preview and approves in chat before anything is written) ·
+`plsql-review` (seven antipatterns) · `plsql-skill-author` (capture *your team's*
+workflow as a new skill, mined from the live schema).
+
+## Compatibility
+
+| | |
+|---|---|
+| OS | Windows, macOS, Linux, WSL — full test matrix in CI |
+| Python | 3.9+ · stdlib + `python-oracledb` (thin mode) only |
+| Oracle | core works broadly; PL/Scope statement capture needs 12.2+; license-safe views only |
+| Agents | any `npx skills` agent (76) · native Claude Code plugin |
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=thaildhe172591%2Fpythia&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=thaildhe172591/pythia&type=date&theme=dark&legend=top-left&sealed_token=OnPCuXPZZEbpQk5_Eor5ZB0fTeMzMN1nmrsDJ8qqahouiJt4-IoDvjONdD05i2D2PhfDC5kwd6CUQeBsWGNV20gt2-4HSD-RygX3h0Ni0lrbQnRh60EN3A" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=thaildhe172591/pythia&type=date&legend=top-left&sealed_token=OnPCuXPZZEbpQk5_Eor5ZB0fTeMzMN1nmrsDJ8qqahouiJt4-IoDvjONdD05i2D2PhfDC5kwd6CUQeBsWGNV20gt2-4HSD-RygX3h0Ni0lrbQnRh60EN3A" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=thaildhe172591/pythia&type=date&legend=top-left&sealed_token=OnPCuXPZZEbpQk5_Eor5ZB0fTeMzMN1nmrsDJ8qqahouiJt4-IoDvjONdD05i2D2PhfDC5kwd6CUQeBsWGNV20gt2-4HSD-RygX3h0Ni0lrbQnRh60EN3A" />
+ </picture>
+</a>
+
+## Contributing
+
+Tests need **no database** — the fakes prove the safety properties (snapshot before
+write, deny touches nothing, stale tokens refused). See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+MIT — see [LICENSE](LICENSE).

pythia_plsql-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+pythia.py,sha256=odx1LIG-ve0fv5byYkVTNZT7TNQjvqxErdwutjkOoVM,66824
+pythia_plsql-0.1.0.dist-info/licenses/LICENSE,sha256=fY6GEoq3pNfFbCVGoUQulGzhdL5NrJCnoLdc7dOA4dQ,1063
+pythia_queries/compile-errors.sql,sha256=wUZHicAxONcAsltUSgiihYajHzuyjksUOuxeT0oRJ5Q,573
+pythia_queries/dependencies.sql,sha256=tt1c25dOY_340eVvfzKoNB7FJFZd6Y8bCeLYmAkkxNw,1544
+pythia_queries/impact.sql,sha256=s2AH8QW6vaj0V5PHVbvnqmiK-_wVuKI57ZtJGfWciqY,1022
+pythia_queries/invalid-objects.sql,sha256=wa3Cw4nsxnkGa9Ik15QgTHWC1BiYdmSbOCo9mKbV0kk,439
+pythia_queries/name-occupants.sql,sha256=lTx26iWSdG7sobCfxJNWf0tev9JbY86DPvXasFMVuxc,758
+pythia_queries/object-source.sql,sha256=foqe7AOd_wVyLqDZ6nSe7GLK-3ct44FKewlCBS0DlEs,493
+pythia_queries/plscope-enabled.sql,sha256=LOlpd7FFsWJ2mXSAfRBMlR2P2mwaXJZZ7OmYIiAe-Bo,324
+pythia_queries/plscope-statements.sql,sha256=6LATpNm-3WrSHEMIWkJpI3OlUreglUnGC9mg2x0vzVw,732
+pythia_queries/plscope-usages.sql,sha256=THcR4GbPvVA-aTWs9oAzul5L17iekUwkMWt80y_gv2Q,619
+pythia_queries/session-privileges.sql,sha256=q5OUhFHPGaOXsdCSChBw9SUbiyVdf0fWf9dMgG551lM,280
+pythia_queries/similar-candidates.sql,sha256=Q04BnVlJJuV1EIVaot6jkoV0zvzZhYi_1wP-tAvWwps,556
+pythia_queries/source.sql,sha256=Q-nJ58LHAverO07hy9wOHzPsWwfdQ2h19ZyEbn0fUaQ,328
+pythia_skills/plsql-apply/SKILL.md,sha256=sF8NHR8huWkPEXpl0-weIXSjakTnxL9eCH6XvkbxHjQ,6513
+pythia_skills/plsql-explore/SKILL.md,sha256=VuE3QSON29lBQllXG_lKZgviR2BVMo0tzyZ3A1MYS1s,2891
+pythia_skills/plsql-explore/reference/data-dictionary.md,sha256=DnpaPq6ukHnwFMaAuc8vVOz6PKhGIsc3RzRE_KVpyf8,2560
+pythia_skills/plsql-impact/SKILL.md,sha256=85sPgPahXX_YaolZpBjcp5RFtUKWPBLQ8ve7FoebsXg,2468
+pythia_skills/plsql-review/SKILL.md,sha256=w3Cfg4KRI6ziiHz_Es4MHlJAs4p5nZC0a-5Docp_FYc,2356
+pythia_skills/plsql-review/reference/antipatterns.md,sha256=I2s9f6GKiwQ0l0FU8Ifj-CqMT2Z4ZY4GygH62PVWkks,3213
+pythia_skills/plsql-setup/SKILL.md,sha256=rNr3SFw1HaxJAdiFgU0iDJ__lfoobuh9oVYCOWAMGmE,3489
+pythia_skills/plsql-skill-author/SKILL.md,sha256=pG_qRTktVzEfEEniziJtf6w-qMSfi8XVOif221uxGnE,4594
+pythia_skills/plsql-write/SKILL.md,sha256=PNeFTd6UU3c2ni614nN7bdQWTmvmoQduQ4Bf04HC4eU,2644
+pythia_skills/plsql-write/reference/patterns.md,sha256=1p5-GTGpaDeSrHPSEkWf4vCaUGREzQ3F-P67uXj4eBo,2812
+pythia_plsql-0.1.0.dist-info/METADATA,sha256=BeQ9ZdOvdpugKIooUFtuV73CdGLafbM2OtXEkOIQrGQ,8130
+pythia_plsql-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pythia_plsql-0.1.0.dist-info/entry_points.txt,sha256=dUdl60jlLUfdd4utUcbQruuHgxron7LMmWvxm_SkGFg,39
+pythia_plsql-0.1.0.dist-info/top_level.txt,sha256=5a6jYMFVXa2nyT6jPP8WAbgKAC2qYfRw1PvAyDzQH-E,36
+pythia_plsql-0.1.0.dist-info/RECORD,,

pythia_plsql-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pythia_plsql-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pythia = pythia:main

pythia_plsql-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thaild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythia_plsql-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+pythia
+pythia_queries
+pythia_skills

pythia_queries/compile-errors.sql

@@ -0,0 +1,17 @@
+-- Purpose: compilation errors and warnings with the exact line and column
+--          Oracle reports, so a fix can be aimed rather than guessed. This
+--          closes the compile-read-fix loop.
+-- Binds:   :s  schema (object owner)
+--          :n  object name, or NULL for every object in the schema
+-- Returns: NAME, TYPE, SEQUENCE, LINE, POSITION, ATTRIBUTE, TEXT
+select name,
+       type,
+       sequence,
+       line,
+       position,
+       attribute,
+       text
+  from all_errors
+ where owner = :s
+   and (:n is null or name = upper(:n))
+ order by name, sequence

pythia_queries/dependencies.sql

@@ -0,0 +1,30 @@
+-- Purpose: what an object depends on, walked downward. NOCYCLE survives
+--          circular references; the depth bound sits in CONNECT BY so the
+--          walk is pruned rather than filtered after the fact.
+--          Oracle's own built-ins (SYS.STANDARD and friends) are excluded
+--          unless asked for: every PL/SQL object depends on them, so they
+--          crowd out the dependencies a developer is actually looking for.
+--          The test is applied in both START WITH and CONNECT BY, so an
+--          excluded object takes its whole subtree with it instead of
+--          leaving its children behind as orphans.
+-- Binds:   :s        schema (owner of the starting object)
+--          :n        starting object name
+--          :depth    levels to walk (1 = direct dependencies only)
+--          :with_sys 1 to include SYS/PUBLIC built-ins, 0 to leave them out
+-- Returns: LVL, OWNER, NAME, TYPE, DEPENDENCY_TYPE
+select level lvl,
+       d.referenced_owner owner,
+       d.referenced_name  name,
+       d.referenced_type  type,
+       d.dependency_type
+  from all_dependencies d
+ start with d.owner = :s
+        and d.name  = upper(:n)
+        and (:with_sys = 1 or d.referenced_owner not in ('SYS', 'PUBLIC'))
+connect by nocycle
+           prior d.referenced_owner = d.owner
+       and prior d.referenced_name  = d.name
+       and prior d.referenced_type  = d.type
+       and level <= :depth
+       and (:with_sys = 1 or d.referenced_owner not in ('SYS', 'PUBLIC'))
+ order siblings by d.referenced_type, d.referenced_name

pythia_queries/impact.sql

@@ -0,0 +1,26 @@
+-- Purpose: what depends on an object — everything a change to it can break.
+--          The reverse of dependencies.sql. Status comes from a scalar
+--          subquery so the hierarchical row order survives.
+-- Binds:   :s      schema (owner of the starting object)
+--          :n      starting object name
+--          :depth  levels to walk (1 = direct dependents only)
+-- Returns: LVL, OWNER, NAME, TYPE, STATUS, DEPENDENCY_TYPE
+select level lvl,
+       d.owner,
+       d.name,
+       d.type,
+       (select o.status
+          from all_objects o
+         where o.owner       = d.owner
+           and o.object_name = d.name
+           and o.object_type = d.type) status,
+       d.dependency_type
+  from all_dependencies d
+ start with d.referenced_owner = :s
+        and d.referenced_name  = upper(:n)
+connect by nocycle
+           prior d.owner = d.referenced_owner
+       and prior d.name  = d.referenced_name
+       and prior d.type  = d.referenced_type
+       and level <= :depth
+ order siblings by d.type, d.name

pythia_queries/invalid-objects.sql

@@ -0,0 +1,11 @@
+-- Purpose: every INVALID object in the schema. Captured before and after a
+--          change, this is what proves a fix did not break something else.
+-- Binds:   :s  schema (object owner)
+-- Returns: OBJECT_NAME, OBJECT_TYPE, LAST_DDL
+select object_name,
+       object_type,
+       to_char(last_ddl_time, 'yyyy-mm-dd hh24:mi:ss') last_ddl
+  from all_objects
+ where owner = :s
+   and status = 'INVALID'
+ order by object_type, object_name

pythia_queries/name-occupants.sql

@@ -0,0 +1,15 @@
+-- Purpose: which object types currently hold a name in the schema's main
+--          namespace. CREATE OR REPLACE cannot change an object's type, so a
+--          name held by a different type must be refused at preview time —
+--          otherwise the preview promises what the database will reject with
+--          ORA-00955. Found by an agent during the first field test.
+-- Binds:   :s  schema (object owner)
+--          :n  object name
+-- Returns: OBJECT_TYPE
+select object_type
+  from all_objects
+ where owner = :s
+   and object_name = upper(:n)
+   and object_type in ('PROCEDURE', 'FUNCTION', 'PACKAGE', 'PACKAGE BODY',
+                       'TYPE', 'TYPE BODY', 'VIEW', 'TABLE',
+                       'MATERIALIZED VIEW', 'SEQUENCE', 'SYNONYM')

pythia_queries/object-source.sql

@@ -0,0 +1,13 @@
+-- Purpose: source of one specific unit — the snapshot read that runs before
+--          every write. PACKAGE and PACKAGE BODY are distinct objects, so the
+--          type is part of the identity, not a filter convenience.
+-- Binds:   :s  schema (object owner)
+--          :n  object name
+--          :t  object type exactly as in ALL_SOURCE (e.g. PACKAGE BODY)
+-- Returns: TEXT
+select text
+  from all_source
+ where owner = :s
+   and name = upper(:n)
+   and type = upper(:t)
+ order by line

pythia_queries/plscope-enabled.sql

@@ -0,0 +1,9 @@
+-- Purpose: one-row probe telling an empty result apart from a schema that was
+--          never compiled with PL/Scope — the difference between "not found"
+--          and "cannot know".
+-- Binds:   :s  schema (object owner)
+-- Returns: ENABLED
+select 1 enabled
+  from all_identifiers
+ where owner = :s
+   and rownum = 1

pythia_queries/plscope-statements.sql

@@ -0,0 +1,21 @@
+-- Purpose: the SQL statements that touch a table, and where they sit. Answers
+--          "which program writes to this table?" exactly. Needs PL/Scope with
+--          STATEMENTS:ALL (Oracle 12.2+).
+-- Binds:   :s  schema (object owner)
+--          :n  table name
+-- Returns: SQL_TYPE, OBJECT_NAME, OBJECT_TYPE, LINE, COL
+select s.type sql_type,
+       s.object_name,
+       s.object_type,
+       s.line,
+       s.col
+  from all_statements s
+  join all_identifiers i
+    on i.owner            = s.owner
+   and i.object_name      = s.object_name
+   and i.object_type      = s.object_type
+   and i.usage_context_id = s.usage_id
+ where s.owner = :s
+   and i.name  = upper(:n)
+   and i.type  = 'TABLE'
+ order by s.object_name, s.line

pythia_queries/plscope-usages.sql

@@ -0,0 +1,18 @@
+-- Purpose: every place an identifier is declared, referenced, assigned or
+--          called. PL/Scope records this at compile time, so it is exact where
+--          grep can only guess. Declarations sort first.
+-- Binds:   :s  schema (object owner)
+--          :n  identifier name
+-- Returns: USAGE, OBJECT_NAME, OBJECT_TYPE, TYPE, LINE, COL, USAGE_ID
+select usage,
+       object_name,
+       object_type,
+       type,
+       line,
+       col,
+       usage_id
+  from all_identifiers
+ where owner = :s
+   and name = upper(:n)
+ order by case usage when 'DECLARATION' then 0 else 1 end,
+          object_name, line, col

pythia_queries/session-privileges.sql

@@ -0,0 +1,8 @@
+-- Purpose: the dangerous ANY privileges this session holds. Feeds the
+--          one-line warning in apply previews and check — warn, never block.
+-- Binds:   (none)
+-- Returns: PRIVILEGE
+select privilege
+  from session_privs
+ where privilege like '%ANY%'
+ order by privilege

pythia_queries/similar-candidates.sql

@@ -0,0 +1,13 @@
+-- Purpose: the pool of programs a new one could be modelled on. Ranking runs
+--          in Python (rank_similar) where it is unit-testable; splitting names
+--          in SQL would need a recursive CTE and make this file unreviewable.
+-- Binds:   :s  schema (object owner)
+-- Returns: OBJECT_NAME, OBJECT_TYPE, STATUS, LAST_DDL
+select object_name,
+       object_type,
+       status,
+       to_char(last_ddl_time, 'yyyy-mm-dd') last_ddl
+  from all_objects
+ where owner = :s
+   and object_type in ('PROCEDURE', 'FUNCTION', 'PACKAGE')
+ order by object_name

pythia_queries/source.sql

@@ -0,0 +1,10 @@
+-- Purpose: full source of a named object, every unit (spec and body), in
+--          compilation order. Backs the src command.
+-- Binds:   :s  schema (object owner)
+--          :n  object name
+-- Returns: TYPE, LINE, TEXT
+select type, line, text
+  from all_source
+ where owner = :s
+   and name = upper(:n)
+ order by type, line

pythia_skills/plsql-apply/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: plsql-apply
+description: Use when a PL/SQL change is ready to reach the database - applying a CREATE OR REPLACE, restoring from the journal, or any other write. Runs the six-step flow through pythia apply and enforces the gate - the developer sees the preview and approves in chat before anything is written, and a broken result is never reported as success.
+---
+
+# Applying PL/SQL Changes
+
+**Announce at start:** "Using plsql-apply — I'll preview the change first."
+
+DDL in Oracle commits itself. There is no transaction to roll back — the
+snapshot pythia takes before writing is the only undo that exists. This skill
+exists so that safety net is always used, and used honestly.
+
+## The Iron Law
+
+```
+NO WRITE THE DEVELOPER HAS NOT SEEN AND APPROVED
+```
+
+Applies to every write: new objects, fixes, restores, batch runs. No
+exceptions for "trivial" changes — a one-line change can invalidate twelve
+dependents.
+
+## The Workflow
+
+**Before step 1:** if this conversation has not yet seen a standalone impact
+analysis for this object, run `plsql-impact` first. The `impact:` line inside
+apply's preview is confirmation of a number you already knew — if it is the
+first time anyone sees it, a step was skipped.
+
+1. **Preview.** Run `pythia apply <file>`. This writes nothing: it snapshots,
+   computes impact, prints a diff, a warning block, and a confirm token.
+2. **Relay the preview to the developer — verbatim.** Show the diff, the
+   `impact:` line, and any `!` warning exactly as printed. Do not summarize
+   the diff away; the developer approves what they see, not your paraphrase.
+3. **Wait for an explicit yes.** A yes is an instruction to proceed with THIS
+   preview: "yes, apply it", "go ahead", "looks good — do it". Not a yes: a
+   compliment without a go-ahead, a question, silence, or an approval that
+   was given for an earlier preview. If the developer changes the file
+   instead, start over at step 1.
+4. **Apply** by running the exact `To apply:` command pythia printed (it
+   contains the token). If pythia says the token is stale, the file or the
+   database changed since the preview — go back to step 1, never "retry".
+   If the fresh preview's before-side no longer matches what you last saw,
+   say so explicitly: someone else may have changed the object on this
+   shared database, and the developer must know that before approving.
+5. **Read the exit code — it is the verdict:**
+
+   | Exit | Meaning | What you must do |
+   |------|---------|-----------------|
+   | 0 | applied, compiled clean, nothing newly INVALID | report done, mention the restore id |
+   | 1 | refused (policy, classification, stale token) | relay the printed reason and its fix; do not work around it |
+   | 3 | **written but broken** — compile errors or other objects now INVALID | see below |
+6. **On exit 3, never report success.** Say plainly that the change went in
+   and broke something, show the compile errors (line:col) and the list of
+   newly INVALID objects, and offer the `To undo:` command pythia printed.
+   Fixing forward is allowed only after the developer sees this state.
+
+## Restores
+
+`pythia journal restore <id>` is itself a write and goes through the same six
+steps and the same gate: preview the reverse diff to the developer, wait for
+yes, then confirm. Note: restoring an object that did not exist before means
+DROP — policy will refuse it under `structural: deny`, and that refusal is
+correct; relay it instead of forcing a way around.
+
+## Batch mode
+
+`--yes` skips the pause, not the preview — output and journal are identical.
+Use it only when the developer explicitly asked for unattended application
+("apply all of these"). A frustrated "stop asking" grants `--yes` for the
+task at hand, not from now on: confirm the scope once ("this batch, or
+standing?") and default to this-batch-only. A standing `--yes` never extends
+to restores. Rules for a batch:
+
+- **Stop at the first exit 3.** Never keep applying onto a broken state.
+- Afterwards report: one line per success, full detail (errors, newly
+  INVALID, restore command) for the failure, and the exact list of files
+  that were NOT applied because the batch stopped.
+
+## Never bypass the write path
+
+When `pythia apply` is available, do not write through anything else — not
+SQLcl MCP `run-sql`, not `sqlplus`, not a driver script. Those paths have no
+snapshot, no impact preview, no verify, no journal. If apply refuses a
+statement, that refusal is information for the developer, not an obstacle to
+route around.
+
+## Is rollback real? Be honest about it
+
+| Group | Is rollback real? |
+|---|---|
+| `plsql_source` | **Yes — completely.** The source is recoverable from `ALL_SOURCE`. |
+| `data_dml` | **No.** After commit only Flashback Query remains, and only within undo retention. |
+| `structural` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
+| `grants` | Yes, but by hand. |
+| `session` | Not needed. |
+
+Never promise "we can always roll back" — that sentence is only true for the
+first row, and saying it generally misleads the developer at the exact moment
+the stakes are highest.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "It's a tiny change, skip the preview" | Tiny changes invalidate dependents too. Preview. |
+| "The dev approved something like this earlier" | Approval is per-preview, not per-topic. Ask again. |
+| "Exit 3, but my part compiled — report done" | Something is broken that was not. That is not done. |
+| "Token is stale, I'll just take the new one" | The content changed. The developer must see the new preview. |
+| "apply refused it; run-sql will take it" | The refusal is the product working. Relay it. |
+| "I'll restore quietly to clean up my mistake" | Restores are writes. Same gate, same visibility. |
+| "The dev said 'stop asking' once" | That covered that task, not forever. Re-confirm scope on the next one. |
+
+## When NOT to use this skill
+
+- Reading or exploring — use `plsql-explore`.
+- Judging blast radius before editing — use `plsql-impact` (always run it
+  before proposing a change; apply's preview is confirmation, not discovery).
+- Editing files the developer has not asked to land on the database yet.
+
+> Invocation note: examples say `pythia ...`; run it however this project
+> provides it (for example `python scripts/pythia.py ...`). Every pythia
+> output prints follow-up commands in the correct form — prefer pasting those.

pythia_skills/plsql-explore/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: plsql-explore
+description: Use when you need to understand anything in an Oracle schema - finding objects, reading PL/SQL source, signatures, table columns, DDL, searching code, or asking who uses what. The database is the only source of truth; repo dumps and exports drift and lie.
+---
+
+# Exploring the Schema
+
+**Announce at start:** "Using plsql-explore — asking the database directly."
+
+## The principle: ask the database, never the dump
+
+Repositories of exported `.sql` files go stale the day after export. A real
+mid-size system, audited in 2026, compared its repo dump against the live
+database:
+
+| Object type | In the dump | In the database | Verdict |
+|---|---|---|---|
+| Procedures | 3,827 | 3,827 | matched |
+| Tables | 952 | 952 | matched |
+| **Types** | **0** | **115** | **all missing** |
+| **Packages** | **0** | **9** | **all missing** |
+| **Indexes** | **116** | **1,016** | **~89% missing** |
+
+Code that "reads fine" against the dump can reference types and packages the
+dump never heard of. Read files only when the database is unreachable, or to
+compare a repo version against the live one.
+
+## What you need → what you run
+
+| Need | Command |
+|---|---|
+| Is the connection alive, what schema | `pythia check` |
+| Find objects by name | `pythia ls "PKG_%"` |
+| Read source, with the compiler's line numbers | `pythia src NAME` (`--body`, `--spec`) |
+| A procedure/function signature | `pythia args NAME` |
+| Columns and real data types | `pythia cols TABLE_NAME` |
+| Full DDL | `pythia ddl TABLE NAME` |
+| Search all PL/SQL text | `pythia grep "text"` |
+| What an object depends on | `pythia deps NAME` |
+| What depends on an object | `pythia impact NAME` |
+| Exact identifier usages (beats grep) | `pythia plscope NAME` |
+| Programs named like this one | `pythia similar NAME` |
+| Everything currently broken | `pythia invalid`, `pythia errors` |
+| A free-form question | `pythia sql "select ..."` (SELECT/WITH only) |
+
+## Rules that keep answers honest
+
+- **Truncation is always announced.** Outputs end with `-- truncated ...` or
+  set `"truncated": true` in `--json`. If you do not see the marker, you saw
+  everything; if you do, say so or fetch more (`--limit`, `--offset`,
+  `--max-lines`) — never present a truncated list as complete.
+- **`plscope` before `grep`** for "where is X used": PL/Scope is recorded by
+  the compiler and exact; grep matches comments and look-alike names. If
+  PL/Scope has no data, the command says so and grep is the fallback.
+- **`src` line numbers are the compiler's own** — an error at `line 47`
+  means line 47 in `src` output. No offset arithmetic.
+- Default output caps exist to protect your context window; raise them only
+  for the object you are actually working on.
+
+Deeper reference — which dictionary views back these commands, PL/Scope
+enablement, licensing boundaries: `reference/data-dictionary.md`.