pythia-plsql 0.14.1__tar.gz → 0.15.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. {pythia_plsql-0.14.1/scripts/pythia_plsql.egg-info → pythia_plsql-0.15.0}/PKG-INFO +116 -33
  2. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/README.md +115 -32
  3. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/pyproject.toml +1 -1
  4. pythia_plsql-0.15.0/queries/comment-current.sql +19 -0
  5. pythia_plsql-0.15.0/queries/db-nls.sql +10 -0
  6. pythia_plsql-0.15.0/queries/db-version.sql +7 -0
  7. pythia_plsql-0.15.0/queries/explain-display.sql +7 -0
  8. pythia_plsql-0.15.0/queries/schema-settings.sql +19 -0
  9. pythia_plsql-0.15.0/queries/table-comments.sql +30 -0
  10. pythia_plsql-0.15.0/queries/table-indexes.sql +20 -0
  11. pythia_plsql-0.15.0/queries/table-stats.sql +17 -0
  12. pythia_plsql-0.15.0/queries/unindexed-fks.sql +36 -0
  13. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia.py +3188 -145
  14. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0/scripts/pythia_plsql.egg-info}/PKG-INFO +116 -33
  15. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia_plsql.egg-info/SOURCES.txt +21 -1
  16. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-apply/SKILL.md +45 -45
  17. pythia_plsql-0.15.0/skills/pythia-autopilot/SKILL.md +87 -0
  18. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-conventions/SKILL.md +22 -0
  19. pythia_plsql-0.15.0/skills/pythia-deploy/SKILL.md +93 -0
  20. pythia_plsql-0.15.0/skills/pythia-package/SKILL.md +87 -0
  21. pythia_plsql-0.15.0/skills/pythia-package/reference/plsql-standards.md +191 -0
  22. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-review/SKILL.md +4 -1
  23. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-setup/SKILL.md +22 -0
  24. pythia_plsql-0.15.0/skills/pythia-setup/reference/environment.md +92 -0
  25. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-skill-author/SKILL.md +8 -1
  26. pythia_plsql-0.15.0/skills/pythia-table/SKILL.md +101 -0
  27. pythia_plsql-0.15.0/skills/pythia-table/reference/ddl-standards.md +132 -0
  28. pythia_plsql-0.15.0/skills/pythia-tune/SKILL.md +90 -0
  29. pythia_plsql-0.15.0/skills/pythia-tune/reference/tuning-checklist.md +100 -0
  30. pythia_plsql-0.15.0/skills/pythia-verify/SKILL.md +79 -0
  31. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-write/SKILL.md +8 -4
  32. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/using-pythia/SKILL.md +13 -4
  33. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_install.py +39 -10
  34. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_phase5.py +31 -3
  35. pythia_plsql-0.15.0/tests/test_phase6.py +1260 -0
  36. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/LICENSE +0 -0
  37. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/compile-errors.sql +0 -0
  38. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/current-schema.sql +0 -0
  39. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/dependencies.sql +0 -0
  40. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/impact.sql +0 -0
  41. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/invalid-objects.sql +0 -0
  42. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/name-occupants.sql +0 -0
  43. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/object-names.sql +0 -0
  44. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/object-source.sql +0 -0
  45. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/plscope-enabled.sql +0 -0
  46. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/plscope-statements.sql +0 -0
  47. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/plscope-usages.sql +0 -0
  48. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/session-privileges.sql +0 -0
  49. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/similar-candidates.sql +0 -0
  50. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/queries/source.sql +0 -0
  51. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia_plsql.egg-info/dependency_links.txt +0 -0
  52. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia_plsql.egg-info/entry_points.txt +0 -0
  53. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia_plsql.egg-info/requires.txt +0 -0
  54. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/scripts/pythia_plsql.egg-info/top_level.txt +0 -0
  55. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/setup.cfg +0 -0
  56. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-comment/SKILL.md +0 -0
  57. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-explore/SKILL.md +0 -0
  58. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-explore/reference/data-dictionary.md +0 -0
  59. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-impact/SKILL.md +0 -0
  60. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-review/reference/antipatterns.md +0 -0
  61. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-spec/SKILL.md +0 -0
  62. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/skills/pythia-write/reference/patterns.md +0 -0
  63. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_mcp.py +0 -0
  64. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_phase1.py +0 -0
  65. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_phase2.py +0 -0
  66. {pythia_plsql-0.14.1 → pythia_plsql-0.15.0}/tests/test_phase3.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pythia-plsql
3
- Version: 0.14.1
3
+ Version: 0.15.0
4
4
  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.
5
5
  License: MIT
6
6
  Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -101,15 +101,26 @@ through one door: **snapshot → impact → preview → token → approve → ap
101
101
  verify → report**. DDL self-commits in Oracle, so the snapshot is the only real
102
102
  undo — it runs first and no flag disables it. A content-bound token guarantees
103
103
  what lands is byte-for-byte what was previewed, and a **developer-minted grant**
104
- guarantees a person approved it at all — through one of two doors, both the
105
- developer's. In chat: the agent asks with `AskUserQuestion`, the question text
106
- being pythia's own approval card (`pythia approve --card <token>`), and the
107
- answer **Approve** — written into the hook payload by Claude Code, never by
104
+ guarantees a person approved it at all — through a door that is always the
105
+ developer's. The `pythia_approve` tool (MCP, on Claude Code and Codex) shows
106
+ pythia's own approval card as a select prompt, and Claude Code prompts for it
107
+ in every permission mode but `dontAsk` — no allow rule can skip it. In chat:
108
+ an `AskUserQuestion` whose text is the card (`pythia approve --card <token>`),
109
+ whose **Approve** — written into the hook payload by Claude Code, never by
108
110
  the agent — mints the one-time grant. At a console: `pythia approve <token>`.
109
111
  Without that grant `apply --confirm` refuses. A headless agent cannot `--yes`
110
112
  its own writes, cannot mint approval, and cannot loosen policy — each of those
111
113
  takes a human, answering or typing.
112
114
 
115
+ **When the developer wants the agent to just work**, they delegate once: an
116
+ **autopilot lease** — one connection, the statement groups they name, a few
117
+ hours and a write budget — approved through the same doors. Until it ends,
118
+ `apply` and `deploy` land covered statements without asking; every write is
119
+ still snapshotted, journaled and verified. A lease never covers a protected
120
+ connection, destructive statements (unless the card named them), or a file
121
+ with lint errors, and it pauses itself the moment other objects break.
122
+ `pythia autopilot report` lists every write with its undo.
123
+
113
124
  The same discipline holds when the *developer* does the work: `src` and
114
125
  `impact` silently snapshot what they read, so even a change made by hand in
115
126
  SQL Developer has a rollback file waiting (`history` lists them, drift is
@@ -128,7 +139,7 @@ Or the same thing piecewise:
128
139
 
129
140
  ```bash
130
141
  pip install pythia-plsql # the CLI (thin driver — no Oracle Instant Client needed)
131
- python -m pythia install # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
142
+ python -m pythia install # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md/MCP approver
132
143
  pythia check # fill in connections.json first, then verify
133
144
  ```
134
145
 
@@ -159,18 +170,87 @@ Running from a clone works too — `python scripts/pythia.py <command>`; every
159
170
  printed follow-up command matches how you invoked it. Windows, macOS, Linux
160
171
  and WSL are all CI-tested.
161
172
 
173
+ ## Setting up Claude Code and Codex
174
+
175
+ `pythia install` configures whichever of these you use — in one run, from the
176
+ project root. Here is exactly what it wires for each, and the one or two steps
177
+ each agent needs you to finish by hand.
178
+
179
+ ### Claude Code
180
+
181
+ 1. Run `python -m pythia install` (or `npx pythia-plsql`) in the project root.
182
+ It registers the write-free **MCP approver** in `.mcp.json` and merges
183
+ into `.claude/settings.json`, keeping every key you already have there:
184
+ - a **SessionStart** hook: the Learn → Ask → Do guide plus the project's
185
+ live state (connections, autopilot lease, conventions, approval door);
186
+ - a **PreToolUse** guard on Bash and SQLcl `run-sql`: pythia's read-only
187
+ commands pass without a prompt that carries no decision, already-approved
188
+ writes pass, and writes that skip the gate (sqlplus/SQLcl DDL) are denied;
189
+ - **PostToolUse** hooks: on `AskUserQuestion` it mints the approval grant;
190
+ on Bash it puts the verdict rules (exit 3 is broken) next to the result;
191
+ - a `deny` rule so the agent cannot forge a grant, and the MCP server
192
+ enabled.
193
+
194
+ Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
195
+ 2. **Restart the Claude Code session** so the hooks and the MCP server load.
196
+ 3. **Run `pythia doctor`.** It confirms the wiring and names every setting
197
+ known to make `AskUserQuestion` return without showing the question — an
198
+ allow rule or a skill's `allowed-tools` naming it, a PreToolUse hook with an
199
+ empty or `*` matcher, `dontAsk` mode. That class of setting is why chat
200
+ approval could fail outside `bypassPermissions`; the MCP door is immune
201
+ to all but `dontAsk`.
202
+ 4. *Optional:* copy the allow-list and `autoMode` from
203
+ [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json).
204
+ Those are your permission preferences, so pythia does not set them for you
205
+ ([why](GUIDE.md#11-optional-claude-code-permission-settings)).
206
+
207
+ **Approving a change:** the agent previews with `pythia apply`, calls the
208
+ `pythia_approve` tool (or asks an `AskUserQuestion` carrying the card), you
209
+ click **Approve**, and the agent runs `apply --confirm` itself.
210
+
211
+ **Working autonomously:** say so. The agent requests a lease
212
+ (`pythia autopilot request`), you approve its card once, and it builds —
213
+ tables, comments, packages, releases — without stopping for each write.
214
+ `acceptEdits` mode plus a lease is the fully hands-off setup.
215
+
216
+ ### Codex
217
+
218
+ 1. Run `python -m pythia install` in the project root. It:
219
+ - writes the harness into **`AGENTS.md`** (Codex loads it every session);
220
+ - registers a write-free MCP approver in **`.codex/config.toml`**;
221
+ - adds a SessionStart guide hook in **`.codex/hooks.json`**.
222
+
223
+ Skills land in `.agents/skills` (or `~/.agents/skills` with `-g`) — the
224
+ directory Codex reads.
225
+ 2. In Codex, **trust the pieces once**: `/mcp` (the `pythia` server) and
226
+ `/hooks` (the project `.codex` layer).
227
+ 3. **Restart the Codex session** so the new `AGENTS.md` loads.
228
+ 4. Check it: `/skills` lists the pythia skills, `/mcp` shows
229
+ `pythia: connected`.
230
+
231
+ Needs **Codex ≥ v0.120** for the in-chat approval (MCP elicitation); an older
232
+ or headless Codex falls back to the console `pythia approve <token>`. Do
233
+ **not** run Codex under `danger-full-access` — that sandbox auto-approves
234
+ elicitations and bypasses your Approve.
235
+
236
+ **Approving a change:** the agent previews with `pythia apply`, calls the
237
+ `pythia_approve` tool, you answer a select **Approve / Reject** prompt right in
238
+ Codex, and on Approve the agent runs `apply --confirm` itself.
239
+
162
240
  ## Commands
163
241
 
164
242
  | Read | Understand | Write |
165
243
  |---|---|---|
166
244
  | `check` connectivity + counts | `deps` what it depends on | `apply` the six-step write |
167
- | `ls` find objects | `impact` what depends on it | `journal` list · diff · export · restore |
168
- | `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
169
- | `args` signatures | `invalid` everything broken | `unistr` exact non-ASCII literals |
170
- | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `agent-user` least-privilege setup |
171
- | `cols` columns + types | `similar` programs named like this | `history` every captured version |
172
- | `grep` search all source | | `approve` the developer's one-time grant |
173
- | `sql` free query (SELECT/WITH only) | | |
245
+ | `ls` find objects | `impact` what depends on it | `deploy` a release script, in order, one approval |
246
+ | `src` source, compiler line numbers | `errors` compile errors, line:col | `journal` list · diff · export · restore |
247
+ | `args` signatures | `invalid` everything broken | `policy` show · set |
248
+ | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `approve` the developer's one-time grant |
249
+ | `cols` columns + types | `similar` programs named like this | `autopilot` request · status · report · off |
250
+ | `comments` table/column comments, `--scaffold` | `lint` house + built-in standards | `unistr` exact non-ASCII literals |
251
+ | `stats` optimizer stats, indexes, unindexed FKs | `explain` the plan, never run | `agent-user` least-privilege setup |
252
+ | `grep` search all source | `doctor` harness + environment health | `history` every captured version |
253
+ | `sql` free query (SELECT/WITH only) | | `skill new · lint` grow your own skills |
174
254
 
175
255
  Every command takes `--json` (machine output), `--conn` (pick a connection), and
176
256
  caps output with explicit truncation markers so context windows stay intact.
@@ -204,23 +284,17 @@ hand with
204
284
  works just as well.
205
285
  `pythia check` warns when the session runs with more power than the task needs.
206
286
 
207
- Using Claude Code? `pythia install` wires the two hooks — the approve-in-chat
208
- door and the session-start guide — and the deny rule into
209
- `.claude/settings.json`, merged into whatever is already there. The rest of
210
- [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json)
211
- stops it prompting for the read-only commands and asks it to pause on
212
- writes — optional, and yours to install
213
- ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
214
-
215
- On Codex, the same command writes the harness into `AGENTS.md` (loaded every
216
- session) and a session-start hook into `.codex/hooks.json`; approve previews in
217
- the terminal with `pythia approve <token>`, since Codex has no chat-mint.
287
+ The developer approval that `apply` requires is minted per agent — Claude
288
+ Code's `AskUserQuestion` hook, or Codex's `pythia_approve` MCP tool, or the
289
+ console `pythia approve <token>` anywhere. How each is wired is in
290
+ [Setting up Claude Code and Codex](#setting-up-claude-code-and-codex) above.
218
291
 
219
292
  Per-group write policy, `.pythia/policy.json` (defaults shown):
220
293
 
221
294
  | Group | Default | Is rollback real? |
222
295
  |---|---|---|
223
296
  | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
297
+ | `comments` | `confirm` | **Yes.** The previous comment is snapshotted before every write. |
224
298
  | `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
225
299
  | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
226
300
  | `grants` | `deny` | Yes, but by hand. |
@@ -238,14 +312,23 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
238
312
 
239
313
  ## Skills
240
314
 
241
- Eight skills teach the agent the workflow — gates, not suggestions:
242
-
243
- `pythia-spec` (open decisions are asked, not assumed) · `pythia-setup` ·
244
- `pythia-explore` · `pythia-impact` (before any change) ·
245
- `pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate:
246
- the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
247
- `pythia-conventions` (adopt a house style, verified against real names) ·
248
- `pythia-skill-author` (capture your team's workflow as a skill).
315
+ The skills teach the agent the workflow — gates, not suggestions:
316
+
317
+ - **The method:** `using-pythia` (the router) · `pythia-spec` (open decisions
318
+ are asked, not assumed) · `pythia-explore` · `pythia-impact` (before any
319
+ change) · `pythia-verify` (evidence before "done").
320
+ - **Building on Oracle:** `pythia-table` (tables, columns, constraints,
321
+ indexes, every column commented) · `pythia-package` (packages, procedures,
322
+ functions, triggers to industry-standard design) · `pythia-write` (copy the
323
+ codebase's conventions) · `pythia-comment` · `pythia-tune` (measure, change
324
+ one thing, measure again) · `pythia-review` (antipatterns).
325
+ - **Landing it:** `pythia-apply` (the gate) · `pythia-deploy` (release
326
+ scripts, in order, one approval) · `pythia-autopilot` (one delegated lease
327
+ instead of every approval).
328
+ - **The team's own way:** `pythia-conventions` (the LEAD's naming and lint
329
+ rules, verified against real names) · `pythia-skill-author` (capture a
330
+ workflow as a skill; `pythia skill new` / `skill lint`) · `pythia-setup`
331
+ (connections, agent user, `pythia doctor`, a robust dev environment).
249
332
 
250
333
  ## Compatibility
251
334
 
@@ -254,7 +337,7 @@ the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
254
337
  | OS | Windows, macOS, Linux, WSL — full test matrix in CI |
255
338
  | Python | 3.9+ · stdlib + `python-oracledb` (thin mode) only |
256
339
  | Oracle | core works broadly; PL/Scope statement capture needs 12.2+; license-safe views only |
257
- | Agents | any `npx skills` agent (76) · native Claude Code plugin |
340
+ | Agents | any `npx skills` agent (76) · native Claude Code plugin (hooks + MCP approver, any permission mode but `dontAsk`) · Codex (AGENTS.md harness + MCP approver, ≥ v0.120 for chat-style approval) |
258
341
 
259
342
  ## Star History
260
343
 
@@ -87,15 +87,26 @@ through one door: **snapshot → impact → preview → token → approve → ap
87
87
  verify → report**. DDL self-commits in Oracle, so the snapshot is the only real
88
88
  undo — it runs first and no flag disables it. A content-bound token guarantees
89
89
  what lands is byte-for-byte what was previewed, and a **developer-minted grant**
90
- guarantees a person approved it at all — through one of two doors, both the
91
- developer's. In chat: the agent asks with `AskUserQuestion`, the question text
92
- being pythia's own approval card (`pythia approve --card <token>`), and the
93
- answer **Approve** — written into the hook payload by Claude Code, never by
90
+ guarantees a person approved it at all — through a door that is always the
91
+ developer's. The `pythia_approve` tool (MCP, on Claude Code and Codex) shows
92
+ pythia's own approval card as a select prompt, and Claude Code prompts for it
93
+ in every permission mode but `dontAsk` — no allow rule can skip it. In chat:
94
+ an `AskUserQuestion` whose text is the card (`pythia approve --card <token>`),
95
+ whose **Approve** — written into the hook payload by Claude Code, never by
94
96
  the agent — mints the one-time grant. At a console: `pythia approve <token>`.
95
97
  Without that grant `apply --confirm` refuses. A headless agent cannot `--yes`
96
98
  its own writes, cannot mint approval, and cannot loosen policy — each of those
97
99
  takes a human, answering or typing.
98
100
 
101
+ **When the developer wants the agent to just work**, they delegate once: an
102
+ **autopilot lease** — one connection, the statement groups they name, a few
103
+ hours and a write budget — approved through the same doors. Until it ends,
104
+ `apply` and `deploy` land covered statements without asking; every write is
105
+ still snapshotted, journaled and verified. A lease never covers a protected
106
+ connection, destructive statements (unless the card named them), or a file
107
+ with lint errors, and it pauses itself the moment other objects break.
108
+ `pythia autopilot report` lists every write with its undo.
109
+
99
110
  The same discipline holds when the *developer* does the work: `src` and
100
111
  `impact` silently snapshot what they read, so even a change made by hand in
101
112
  SQL Developer has a rollback file waiting (`history` lists them, drift is
@@ -114,7 +125,7 @@ Or the same thing piecewise:
114
125
 
115
126
  ```bash
116
127
  pip install pythia-plsql # the CLI (thin driver — no Oracle Instant Client needed)
117
- python -m pythia install # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
128
+ python -m pythia install # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md/MCP approver
118
129
  pythia check # fill in connections.json first, then verify
119
130
  ```
120
131
 
@@ -145,18 +156,87 @@ Running from a clone works too — `python scripts/pythia.py <command>`; every
145
156
  printed follow-up command matches how you invoked it. Windows, macOS, Linux
146
157
  and WSL are all CI-tested.
147
158
 
159
+ ## Setting up Claude Code and Codex
160
+
161
+ `pythia install` configures whichever of these you use — in one run, from the
162
+ project root. Here is exactly what it wires for each, and the one or two steps
163
+ each agent needs you to finish by hand.
164
+
165
+ ### Claude Code
166
+
167
+ 1. Run `python -m pythia install` (or `npx pythia-plsql`) in the project root.
168
+ It registers the write-free **MCP approver** in `.mcp.json` and merges
169
+ into `.claude/settings.json`, keeping every key you already have there:
170
+ - a **SessionStart** hook: the Learn → Ask → Do guide plus the project's
171
+ live state (connections, autopilot lease, conventions, approval door);
172
+ - a **PreToolUse** guard on Bash and SQLcl `run-sql`: pythia's read-only
173
+ commands pass without a prompt that carries no decision, already-approved
174
+ writes pass, and writes that skip the gate (sqlplus/SQLcl DDL) are denied;
175
+ - **PostToolUse** hooks: on `AskUserQuestion` it mints the approval grant;
176
+ on Bash it puts the verdict rules (exit 3 is broken) next to the result;
177
+ - a `deny` rule so the agent cannot forge a grant, and the MCP server
178
+ enabled.
179
+
180
+ Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
181
+ 2. **Restart the Claude Code session** so the hooks and the MCP server load.
182
+ 3. **Run `pythia doctor`.** It confirms the wiring and names every setting
183
+ known to make `AskUserQuestion` return without showing the question — an
184
+ allow rule or a skill's `allowed-tools` naming it, a PreToolUse hook with an
185
+ empty or `*` matcher, `dontAsk` mode. That class of setting is why chat
186
+ approval could fail outside `bypassPermissions`; the MCP door is immune
187
+ to all but `dontAsk`.
188
+ 4. *Optional:* copy the allow-list and `autoMode` from
189
+ [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json).
190
+ Those are your permission preferences, so pythia does not set them for you
191
+ ([why](GUIDE.md#11-optional-claude-code-permission-settings)).
192
+
193
+ **Approving a change:** the agent previews with `pythia apply`, calls the
194
+ `pythia_approve` tool (or asks an `AskUserQuestion` carrying the card), you
195
+ click **Approve**, and the agent runs `apply --confirm` itself.
196
+
197
+ **Working autonomously:** say so. The agent requests a lease
198
+ (`pythia autopilot request`), you approve its card once, and it builds —
199
+ tables, comments, packages, releases — without stopping for each write.
200
+ `acceptEdits` mode plus a lease is the fully hands-off setup.
201
+
202
+ ### Codex
203
+
204
+ 1. Run `python -m pythia install` in the project root. It:
205
+ - writes the harness into **`AGENTS.md`** (Codex loads it every session);
206
+ - registers a write-free MCP approver in **`.codex/config.toml`**;
207
+ - adds a SessionStart guide hook in **`.codex/hooks.json`**.
208
+
209
+ Skills land in `.agents/skills` (or `~/.agents/skills` with `-g`) — the
210
+ directory Codex reads.
211
+ 2. In Codex, **trust the pieces once**: `/mcp` (the `pythia` server) and
212
+ `/hooks` (the project `.codex` layer).
213
+ 3. **Restart the Codex session** so the new `AGENTS.md` loads.
214
+ 4. Check it: `/skills` lists the pythia skills, `/mcp` shows
215
+ `pythia: connected`.
216
+
217
+ Needs **Codex ≥ v0.120** for the in-chat approval (MCP elicitation); an older
218
+ or headless Codex falls back to the console `pythia approve <token>`. Do
219
+ **not** run Codex under `danger-full-access` — that sandbox auto-approves
220
+ elicitations and bypasses your Approve.
221
+
222
+ **Approving a change:** the agent previews with `pythia apply`, calls the
223
+ `pythia_approve` tool, you answer a select **Approve / Reject** prompt right in
224
+ Codex, and on Approve the agent runs `apply --confirm` itself.
225
+
148
226
  ## Commands
149
227
 
150
228
  | Read | Understand | Write |
151
229
  |---|---|---|
152
230
  | `check` connectivity + counts | `deps` what it depends on | `apply` the six-step write |
153
- | `ls` find objects | `impact` what depends on it | `journal` list · diff · export · restore |
154
- | `src` source, compiler line numbers | `errors` compile errors, line:col | `policy` show · set |
155
- | `args` signatures | `invalid` everything broken | `unistr` exact non-ASCII literals |
156
- | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `agent-user` least-privilege setup |
157
- | `cols` columns + types | `similar` programs named like this | `history` every captured version |
158
- | `grep` search all source | | `approve` the developer's one-time grant |
159
- | `sql` free query (SELECT/WITH only) | | |
231
+ | `ls` find objects | `impact` what depends on it | `deploy` a release script, in order, one approval |
232
+ | `src` source, compiler line numbers | `errors` compile errors, line:col | `journal` list · diff · export · restore |
233
+ | `args` signatures | `invalid` everything broken | `policy` show · set |
234
+ | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `approve` the developer's one-time grant |
235
+ | `cols` columns + types | `similar` programs named like this | `autopilot` request · status · report · off |
236
+ | `comments` table/column comments, `--scaffold` | `lint` house + built-in standards | `unistr` exact non-ASCII literals |
237
+ | `stats` optimizer stats, indexes, unindexed FKs | `explain` the plan, never run | `agent-user` least-privilege setup |
238
+ | `grep` search all source | `doctor` harness + environment health | `history` every captured version |
239
+ | `sql` free query (SELECT/WITH only) | | `skill new · lint` grow your own skills |
160
240
 
161
241
  Every command takes `--json` (machine output), `--conn` (pick a connection), and
162
242
  caps output with explicit truncation markers so context windows stay intact.
@@ -190,23 +270,17 @@ hand with
190
270
  works just as well.
191
271
  `pythia check` warns when the session runs with more power than the task needs.
192
272
 
193
- Using Claude Code? `pythia install` wires the two hooks — the approve-in-chat
194
- door and the session-start guide — and the deny rule into
195
- `.claude/settings.json`, merged into whatever is already there. The rest of
196
- [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json)
197
- stops it prompting for the read-only commands and asks it to pause on
198
- writes — optional, and yours to install
199
- ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
200
-
201
- On Codex, the same command writes the harness into `AGENTS.md` (loaded every
202
- session) and a session-start hook into `.codex/hooks.json`; approve previews in
203
- the terminal with `pythia approve <token>`, since Codex has no chat-mint.
273
+ The developer approval that `apply` requires is minted per agent — Claude
274
+ Code's `AskUserQuestion` hook, or Codex's `pythia_approve` MCP tool, or the
275
+ console `pythia approve <token>` anywhere. How each is wired is in
276
+ [Setting up Claude Code and Codex](#setting-up-claude-code-and-codex) above.
204
277
 
205
278
  Per-group write policy, `.pythia/policy.json` (defaults shown):
206
279
 
207
280
  | Group | Default | Is rollback real? |
208
281
  |---|---|---|
209
282
  | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
283
+ | `comments` | `confirm` | **Yes.** The previous comment is snapshotted before every write. |
210
284
  | `data_dml` | `deny` | **No.** After commit only Flashback Query remains, within undo retention. Revalidation checks the row set *before* the write; it is not an undo. |
211
285
  | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
212
286
  | `grants` | `deny` | Yes, but by hand. |
@@ -224,14 +298,23 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
224
298
 
225
299
  ## Skills
226
300
 
227
- Eight skills teach the agent the workflow — gates, not suggestions:
228
-
229
- `pythia-spec` (open decisions are asked, not assumed) · `pythia-setup` ·
230
- `pythia-explore` · `pythia-impact` (before any change) ·
231
- `pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate:
232
- the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
233
- `pythia-conventions` (adopt a house style, verified against real names) ·
234
- `pythia-skill-author` (capture your team's workflow as a skill).
301
+ The skills teach the agent the workflow — gates, not suggestions:
302
+
303
+ - **The method:** `using-pythia` (the router) · `pythia-spec` (open decisions
304
+ are asked, not assumed) · `pythia-explore` · `pythia-impact` (before any
305
+ change) · `pythia-verify` (evidence before "done").
306
+ - **Building on Oracle:** `pythia-table` (tables, columns, constraints,
307
+ indexes, every column commented) · `pythia-package` (packages, procedures,
308
+ functions, triggers to industry-standard design) · `pythia-write` (copy the
309
+ codebase's conventions) · `pythia-comment` · `pythia-tune` (measure, change
310
+ one thing, measure again) · `pythia-review` (antipatterns).
311
+ - **Landing it:** `pythia-apply` (the gate) · `pythia-deploy` (release
312
+ scripts, in order, one approval) · `pythia-autopilot` (one delegated lease
313
+ instead of every approval).
314
+ - **The team's own way:** `pythia-conventions` (the LEAD's naming and lint
315
+ rules, verified against real names) · `pythia-skill-author` (capture a
316
+ workflow as a skill; `pythia skill new` / `skill lint`) · `pythia-setup`
317
+ (connections, agent user, `pythia doctor`, a robust dev environment).
235
318
 
236
319
  ## Compatibility
237
320
 
@@ -240,7 +323,7 @@ the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
240
323
  | OS | Windows, macOS, Linux, WSL — full test matrix in CI |
241
324
  | Python | 3.9+ · stdlib + `python-oracledb` (thin mode) only |
242
325
  | Oracle | core works broadly; PL/Scope statement capture needs 12.2+; license-safe views only |
243
- | Agents | any `npx skills` agent (76) · native Claude Code plugin |
326
+ | Agents | any `npx skills` agent (76) · native Claude Code plugin (hooks + MCP approver, any permission mode but `dontAsk`) · Codex (AGENTS.md harness + MCP approver, ≥ v0.120 for chat-style approval) |
244
327
 
245
328
  ## Star History
246
329
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pythia-plsql"
7
- version = "0.14.1"
7
+ version = "0.15.0"
8
8
  description = "PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback."
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
@@ -0,0 +1,19 @@
1
+ -- Purpose: the comment a COMMENT ON statement is about to replace — the
2
+ -- snapshot for the comments group. One dictionary read is the whole
3
+ -- undo: restore writes this text back. A column comment when :c is
4
+ -- given, the table comment when :c is null.
5
+ -- Binds: :s schema (table owner)
6
+ -- :t table name, exactly as stored
7
+ -- :c column name, exactly as stored, or null for the table comment
8
+ -- Returns: COMMENTS
9
+ select comments
10
+ from all_col_comments
11
+ where owner = :s
12
+ and table_name = :t
13
+ and column_name = :c
14
+ union all
15
+ select comments
16
+ from all_tab_comments
17
+ where owner = :s
18
+ and table_name = :t
19
+ and :c is null
@@ -0,0 +1,10 @@
1
+ -- Purpose: the database character sets and language settings. A non-Unicode
2
+ -- character set cannot hold Vietnamese text in VARCHAR2, which
3
+ -- decides how literals and columns must be written.
4
+ -- Binds: (none)
5
+ -- Returns: PARAMETER, VALUE
6
+ select parameter, value
7
+ from nls_database_parameters
8
+ where parameter in ('NLS_CHARACTERSET', 'NLS_NCHAR_CHARACTERSET',
9
+ 'NLS_LANGUAGE', 'NLS_TERRITORY', 'NLS_LENGTH_SEMANTICS')
10
+ order by parameter
@@ -0,0 +1,7 @@
1
+ -- Purpose: which Oracle release this is — the features a script may use
2
+ -- (FETCH FIRST, identity columns, JSON) depend on it. Readable by
3
+ -- any session, unlike V$VERSION.
4
+ -- Binds: (none)
5
+ -- Returns: PRODUCT, VERSION, STATUS
6
+ select product, version, status
7
+ from product_component_version
@@ -0,0 +1,7 @@
1
+ -- Purpose: the plan EXPLAIN PLAN just wrote, formatted by DBMS_XPLAN.
2
+ -- License-safe: PLAN_TABLE only, no V$ views, no AWR/ASH.
3
+ -- Binds: :id statement id the EXPLAIN PLAN was tagged with
4
+ -- :fmt DBMS_XPLAN format (BASIC, TYPICAL, ALL)
5
+ -- Returns: PLAN_TABLE_OUTPUT
6
+ select plan_table_output
7
+ from table(dbms_xplan.display('PLAN_TABLE', :id, :fmt))
@@ -0,0 +1,19 @@
1
+ -- Purpose: the development environment of one schema at a glance: how many
2
+ -- PL/SQL units exist, how many carry PL/Scope identifiers (exact
3
+ -- usage answers) and compiler warnings, what is INVALID, and whether
4
+ -- the utPLSQL framework is reachable for unit tests.
5
+ -- Binds: :s schema (object owner)
6
+ -- Returns: UNITS, PLSCOPE_UNITS, WARNING_UNITS, INVALID_OBJECTS, UTPLSQL
7
+ select (select count(*) from all_plsql_object_settings
8
+ where owner = :s) units,
9
+ (select count(*) from all_plsql_object_settings
10
+ where owner = :s
11
+ and plscope_settings like '%IDENTIFIERS:ALL%') plscope_units,
12
+ (select count(*) from all_plsql_object_settings
13
+ where owner = :s
14
+ and plsql_warnings not like 'DISABLE:ALL%') warning_units,
15
+ (select count(*) from all_objects
16
+ where owner = :s and status = 'INVALID') invalid_objects,
17
+ (select count(*) from all_objects
18
+ where object_name = 'UT' and object_type = 'PACKAGE') utplsql
19
+ from dual
@@ -0,0 +1,30 @@
1
+ -- Purpose: the comment on one table and on each of its columns, with the
2
+ -- column's type — the data dictionary as documentation, and which
3
+ -- parts of it are still blank. The table's own row comes first, with
4
+ -- a null COLUMN_NAME.
5
+ -- Binds: :s schema (table owner)
6
+ -- :n table or view name
7
+ -- Returns: TABLE_NAME, COLUMN_NAME, DATA_TYPE, COMMENTS, COLUMN_ID
8
+ select t.table_name, null column_name, t.table_type data_type, t.comments,
9
+ 0 column_id
10
+ from all_tab_comments t
11
+ where t.owner = :s
12
+ and t.table_name = upper(:n)
13
+ union all
14
+ select c.table_name, c.column_name,
15
+ c.data_type || case
16
+ when c.data_type in ('VARCHAR2', 'NVARCHAR2', 'CHAR', 'NCHAR', 'RAW')
17
+ then '(' || c.char_length
18
+ || case c.char_used when 'C' then ' CHAR' else '' end || ')'
19
+ when c.data_type = 'NUMBER' and c.data_precision is not null
20
+ then '(' || c.data_precision || ',' || c.data_scale || ')'
21
+ end data_type,
22
+ m.comments, c.column_id
23
+ from all_tab_columns c
24
+ left join all_col_comments m
25
+ on m.owner = c.owner
26
+ and m.table_name = c.table_name
27
+ and m.column_name = c.column_name
28
+ where c.owner = :s
29
+ and c.table_name = upper(:n)
30
+ order by 5
@@ -0,0 +1,20 @@
1
+ -- Purpose: every index on one table with its columns in order, uniqueness,
2
+ -- status and the statistics that decide whether the optimizer will
3
+ -- use it (distinct keys, clustering factor).
4
+ -- Binds: :s schema (table owner)
5
+ -- :n table name
6
+ -- Returns: INDEX_NAME, COLUMNS, UNIQUENESS, INDEX_TYPE, STATUS, VISIBILITY,
7
+ -- DISTINCT_KEYS, CLUSTERING_FACTOR, LAST_ANALYZED
8
+ select i.index_name,
9
+ (select listagg(c.column_name, ', ')
10
+ within group (order by c.column_position)
11
+ from all_ind_columns c
12
+ where c.index_owner = i.owner
13
+ and c.index_name = i.index_name) columns,
14
+ i.uniqueness, i.index_type, i.status, i.visibility,
15
+ i.distinct_keys, i.clustering_factor,
16
+ to_char(i.last_analyzed, 'YYYY-MM-DD HH24:MI') last_analyzed
17
+ from all_indexes i
18
+ where i.table_owner = :s
19
+ and i.table_name = upper(:n)
20
+ order by i.index_name
@@ -0,0 +1,17 @@
1
+ -- Purpose: what the optimizer believes about one table — rows, blocks, when
2
+ -- it last looked, and whether that is stale. Tuning starts from
3
+ -- these numbers, not from a guess about the data.
4
+ -- Binds: :s schema (table owner)
5
+ -- :n table name
6
+ -- Returns: TABLE_NAME, NUM_ROWS, BLOCKS, AVG_ROW_LEN, LAST_ANALYZED,
7
+ -- STALE_STATS, PARTITIONED, TEMPORARY, IOT_TYPE
8
+ select t.table_name, t.num_rows, t.blocks, t.avg_row_len,
9
+ to_char(t.last_analyzed, 'YYYY-MM-DD HH24:MI') last_analyzed,
10
+ s.stale_stats, t.partitioned, t.temporary, t.iot_type
11
+ from all_tables t
12
+ left join all_tab_statistics s
13
+ on s.owner = t.owner
14
+ and s.table_name = t.table_name
15
+ and s.object_type = 'TABLE'
16
+ where t.owner = :s
17
+ and t.table_name = upper(:n)
@@ -0,0 +1,36 @@
1
+ -- Purpose: foreign keys on one table whose columns lead no index. Deleting or
2
+ -- updating the parent key then locks the whole child table — a
3
+ -- classic cause of "the system hangs when someone deletes".
4
+ -- Binds: :s schema (table owner)
5
+ -- :n table name
6
+ -- Returns: CONSTRAINT_NAME, COLUMNS, PARENT_TABLE
7
+ select c.constraint_name,
8
+ (select listagg(cc.column_name, ', ')
9
+ within group (order by cc.position)
10
+ from all_cons_columns cc
11
+ where cc.owner = c.owner
12
+ and cc.constraint_name = c.constraint_name) columns,
13
+ (select p.table_name
14
+ from all_constraints p
15
+ where p.owner = c.r_owner
16
+ and p.constraint_name = c.r_constraint_name) parent_table
17
+ from all_constraints c
18
+ where c.owner = :s
19
+ and c.table_name = upper(:n)
20
+ and c.constraint_type = 'R'
21
+ and not exists (
22
+ select 1
23
+ from all_ind_columns ic
24
+ join all_cons_columns cc
25
+ on cc.owner = c.owner
26
+ and cc.constraint_name = c.constraint_name
27
+ and cc.column_name = ic.column_name
28
+ and cc.position = ic.column_position
29
+ where ic.table_owner = c.owner
30
+ and ic.table_name = c.table_name
31
+ group by ic.index_owner, ic.index_name
32
+ having count(*) = (select count(*)
33
+ from all_cons_columns x
34
+ where x.owner = c.owner
35
+ and x.constraint_name = c.constraint_name))
36
+ order by c.constraint_name