pythia-plsql 0.14.2__tar.gz → 0.15.1__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.2/scripts/pythia_plsql.egg-info → pythia_plsql-0.15.1}/PKG-INFO +122 -33
  2. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/README.md +121 -32
  3. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/pyproject.toml +1 -1
  4. pythia_plsql-0.15.1/queries/comment-current.sql +19 -0
  5. pythia_plsql-0.15.1/queries/db-nls.sql +10 -0
  6. pythia_plsql-0.15.1/queries/db-version.sql +7 -0
  7. pythia_plsql-0.15.1/queries/explain-display.sql +7 -0
  8. pythia_plsql-0.15.1/queries/schema-settings.sql +19 -0
  9. pythia_plsql-0.15.1/queries/table-comments.sql +30 -0
  10. pythia_plsql-0.15.1/queries/table-indexes.sql +20 -0
  11. pythia_plsql-0.15.1/queries/table-stats.sql +17 -0
  12. pythia_plsql-0.15.1/queries/unindexed-fks.sql +36 -0
  13. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia.py +3259 -157
  14. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1/scripts/pythia_plsql.egg-info}/PKG-INFO +122 -33
  15. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia_plsql.egg-info/SOURCES.txt +21 -1
  16. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-apply/SKILL.md +45 -45
  17. pythia_plsql-0.15.1/skills/pythia-autopilot/SKILL.md +87 -0
  18. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-conventions/SKILL.md +22 -0
  19. pythia_plsql-0.15.1/skills/pythia-deploy/SKILL.md +93 -0
  20. pythia_plsql-0.15.1/skills/pythia-package/SKILL.md +87 -0
  21. pythia_plsql-0.15.1/skills/pythia-package/reference/plsql-standards.md +191 -0
  22. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-review/SKILL.md +4 -1
  23. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-setup/SKILL.md +22 -0
  24. pythia_plsql-0.15.1/skills/pythia-setup/reference/environment.md +92 -0
  25. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-skill-author/SKILL.md +8 -1
  26. pythia_plsql-0.15.1/skills/pythia-table/SKILL.md +101 -0
  27. pythia_plsql-0.15.1/skills/pythia-table/reference/ddl-standards.md +132 -0
  28. pythia_plsql-0.15.1/skills/pythia-tune/SKILL.md +90 -0
  29. pythia_plsql-0.15.1/skills/pythia-tune/reference/tuning-checklist.md +100 -0
  30. pythia_plsql-0.15.1/skills/pythia-verify/SKILL.md +79 -0
  31. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-write/SKILL.md +8 -4
  32. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/using-pythia/SKILL.md +13 -4
  33. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/tests/test_install.py +113 -10
  34. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/tests/test_phase5.py +31 -3
  35. pythia_plsql-0.15.1/tests/test_phase6.py +1260 -0
  36. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/LICENSE +0 -0
  37. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/compile-errors.sql +0 -0
  38. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/current-schema.sql +0 -0
  39. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/dependencies.sql +0 -0
  40. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/impact.sql +0 -0
  41. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/invalid-objects.sql +0 -0
  42. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/name-occupants.sql +0 -0
  43. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/object-names.sql +0 -0
  44. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/object-source.sql +0 -0
  45. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/plscope-enabled.sql +0 -0
  46. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/plscope-statements.sql +0 -0
  47. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/plscope-usages.sql +0 -0
  48. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/session-privileges.sql +0 -0
  49. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/similar-candidates.sql +0 -0
  50. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/queries/source.sql +0 -0
  51. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia_plsql.egg-info/dependency_links.txt +0 -0
  52. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia_plsql.egg-info/entry_points.txt +0 -0
  53. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia_plsql.egg-info/requires.txt +0 -0
  54. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/scripts/pythia_plsql.egg-info/top_level.txt +0 -0
  55. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/setup.cfg +0 -0
  56. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-comment/SKILL.md +0 -0
  57. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-explore/SKILL.md +0 -0
  58. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-explore/reference/data-dictionary.md +0 -0
  59. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-impact/SKILL.md +0 -0
  60. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-review/reference/antipatterns.md +0 -0
  61. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-spec/SKILL.md +0 -0
  62. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/skills/pythia-write/reference/patterns.md +0 -0
  63. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/tests/test_mcp.py +0 -0
  64. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/tests/test_phase1.py +0 -0
  65. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/tests/test_phase2.py +0 -0
  66. {pythia_plsql-0.14.2 → pythia_plsql-0.15.1}/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.2
3
+ Version: 0.15.1
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 CLAUDE.md/hooks + Codex AGENTS.md/MCP approver
132
143
  pythia check # fill in connections.json first, then verify
133
144
  ```
134
145
 
@@ -159,18 +170,93 @@ 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
+ It also writes the harness into **`CLAUDE.md`** — the file Claude Code
195
+ itself loads every session — in a marker-delimited block, leaving your own
196
+ text untouched. The rules hold even with `--no-hooks`, before a restart,
197
+ or while the hooks are untrusted; when the block is there, the
198
+ SessionStart hook adds only the live state instead of repeating the guide.
199
+
200
+ Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
201
+ 2. **Restart the Claude Code session** so the hooks and the MCP server load.
202
+ 3. **Run `pythia doctor`.** It confirms the wiring and names every setting
203
+ known to make `AskUserQuestion` return without showing the question — an
204
+ allow rule or a skill's `allowed-tools` naming it, a PreToolUse hook with an
205
+ empty or `*` matcher, `dontAsk` mode. That class of setting is why chat
206
+ approval could fail outside `bypassPermissions`; the MCP door is immune
207
+ to all but `dontAsk`.
208
+ 4. *Optional:* copy the allow-list and `autoMode` from
209
+ [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json).
210
+ Those are your permission preferences, so pythia does not set them for you
211
+ ([why](GUIDE.md#11-optional-claude-code-permission-settings)).
212
+
213
+ **Approving a change:** the agent previews with `pythia apply`, calls the
214
+ `pythia_approve` tool (or asks an `AskUserQuestion` carrying the card), you
215
+ click **Approve**, and the agent runs `apply --confirm` itself.
216
+
217
+ **Working autonomously:** say so. The agent requests a lease
218
+ (`pythia autopilot request`), you approve its card once, and it builds —
219
+ tables, comments, packages, releases — without stopping for each write.
220
+ `acceptEdits` mode plus a lease is the fully hands-off setup.
221
+
222
+ ### Codex
223
+
224
+ 1. Run `python -m pythia install` in the project root. It:
225
+ - writes the harness into **`AGENTS.md`** (Codex loads it every session);
226
+ - registers a write-free MCP approver in **`.codex/config.toml`**;
227
+ - adds a SessionStart guide hook in **`.codex/hooks.json`**.
228
+
229
+ Skills land in `.agents/skills` (or `~/.agents/skills` with `-g`) — the
230
+ directory Codex reads.
231
+ 2. In Codex, **trust the pieces once**: `/mcp` (the `pythia` server) and
232
+ `/hooks` (the project `.codex` layer).
233
+ 3. **Restart the Codex session** so the new `AGENTS.md` loads.
234
+ 4. Check it: `/skills` lists the pythia skills, `/mcp` shows
235
+ `pythia: connected`.
236
+
237
+ Needs **Codex ≥ v0.120** for the in-chat approval (MCP elicitation); an older
238
+ or headless Codex falls back to the console `pythia approve <token>`. Do
239
+ **not** run Codex under `danger-full-access` — that sandbox auto-approves
240
+ elicitations and bypasses your Approve.
241
+
242
+ **Approving a change:** the agent previews with `pythia apply`, calls the
243
+ `pythia_approve` tool, you answer a select **Approve / Reject** prompt right in
244
+ Codex, and on Approve the agent runs `apply --confirm` itself.
245
+
162
246
  ## Commands
163
247
 
164
248
  | Read | Understand | Write |
165
249
  |---|---|---|
166
250
  | `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) | | |
251
+ | `ls` find objects | `impact` what depends on it | `deploy` a release script, in order, one approval |
252
+ | `src` source, compiler line numbers | `errors` compile errors, line:col | `journal` list · diff · export · restore |
253
+ | `args` signatures | `invalid` everything broken | `policy` show · set |
254
+ | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `approve` the developer's one-time grant |
255
+ | `cols` columns + types | `similar` programs named like this | `autopilot` request · status · report · off |
256
+ | `comments` table/column comments, `--scaffold` | `lint` house + built-in standards | `unistr` exact non-ASCII literals |
257
+ | `stats` optimizer stats, indexes, unindexed FKs | `explain` the plan, never run | `agent-user` least-privilege setup |
258
+ | `grep` search all source | `doctor` harness + environment health | `history` every captured version |
259
+ | `sql` free query (SELECT/WITH only) | | `skill new · lint` grow your own skills |
174
260
 
175
261
  Every command takes `--json` (machine output), `--conn` (pick a connection), and
176
262
  caps output with explicit truncation markers so context windows stay intact.
@@ -204,23 +290,17 @@ hand with
204
290
  works just as well.
205
291
  `pythia check` warns when the session runs with more power than the task needs.
206
292
 
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.
293
+ The developer approval that `apply` requires is minted per agent — Claude
294
+ Code's `AskUserQuestion` hook, or Codex's `pythia_approve` MCP tool, or the
295
+ console `pythia approve <token>` anywhere. How each is wired is in
296
+ [Setting up Claude Code and Codex](#setting-up-claude-code-and-codex) above.
218
297
 
219
298
  Per-group write policy, `.pythia/policy.json` (defaults shown):
220
299
 
221
300
  | Group | Default | Is rollback real? |
222
301
  |---|---|---|
223
302
  | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
303
+ | `comments` | `confirm` | **Yes.** The previous comment is snapshotted before every write. |
224
304
  | `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
305
  | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
226
306
  | `grants` | `deny` | Yes, but by hand. |
@@ -238,14 +318,23 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
238
318
 
239
319
  ## Skills
240
320
 
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).
321
+ The skills teach the agent the workflow — gates, not suggestions:
322
+
323
+ - **The method:** `using-pythia` (the router) · `pythia-spec` (open decisions
324
+ are asked, not assumed) · `pythia-explore` · `pythia-impact` (before any
325
+ change) · `pythia-verify` (evidence before "done").
326
+ - **Building on Oracle:** `pythia-table` (tables, columns, constraints,
327
+ indexes, every column commented) · `pythia-package` (packages, procedures,
328
+ functions, triggers to industry-standard design) · `pythia-write` (copy the
329
+ codebase's conventions) · `pythia-comment` · `pythia-tune` (measure, change
330
+ one thing, measure again) · `pythia-review` (antipatterns).
331
+ - **Landing it:** `pythia-apply` (the gate) · `pythia-deploy` (release
332
+ scripts, in order, one approval) · `pythia-autopilot` (one delegated lease
333
+ instead of every approval).
334
+ - **The team's own way:** `pythia-conventions` (the LEAD's naming and lint
335
+ rules, verified against real names) · `pythia-skill-author` (capture a
336
+ workflow as a skill; `pythia skill new` / `skill lint`) · `pythia-setup`
337
+ (connections, agent user, `pythia doctor`, a robust dev environment).
249
338
 
250
339
  ## Compatibility
251
340
 
@@ -254,7 +343,7 @@ the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
254
343
  | OS | Windows, macOS, Linux, WSL — full test matrix in CI |
255
344
  | Python | 3.9+ · stdlib + `python-oracledb` (thin mode) only |
256
345
  | 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 |
346
+ | 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
347
 
259
348
  ## Star History
260
349
 
@@ -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 CLAUDE.md/hooks + Codex AGENTS.md/MCP approver
118
129
  pythia check # fill in connections.json first, then verify
119
130
  ```
120
131
 
@@ -145,18 +156,93 @@ 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
+ It also writes the harness into **`CLAUDE.md`** — the file Claude Code
181
+ itself loads every session — in a marker-delimited block, leaving your own
182
+ text untouched. The rules hold even with `--no-hooks`, before a restart,
183
+ or while the hooks are untrusted; when the block is there, the
184
+ SessionStart hook adds only the live state instead of repeating the guide.
185
+
186
+ Skills land in `.claude/skills` (or `~/.claude/skills` with `-g`).
187
+ 2. **Restart the Claude Code session** so the hooks and the MCP server load.
188
+ 3. **Run `pythia doctor`.** It confirms the wiring and names every setting
189
+ known to make `AskUserQuestion` return without showing the question — an
190
+ allow rule or a skill's `allowed-tools` naming it, a PreToolUse hook with an
191
+ empty or `*` matcher, `dontAsk` mode. That class of setting is why chat
192
+ approval could fail outside `bypassPermissions`; the MCP door is immune
193
+ to all but `dontAsk`.
194
+ 4. *Optional:* copy the allow-list and `autoMode` from
195
+ [`examples/claude-code-settings.example.json`](examples/claude-code-settings.example.json).
196
+ Those are your permission preferences, so pythia does not set them for you
197
+ ([why](GUIDE.md#11-optional-claude-code-permission-settings)).
198
+
199
+ **Approving a change:** the agent previews with `pythia apply`, calls the
200
+ `pythia_approve` tool (or asks an `AskUserQuestion` carrying the card), you
201
+ click **Approve**, and the agent runs `apply --confirm` itself.
202
+
203
+ **Working autonomously:** say so. The agent requests a lease
204
+ (`pythia autopilot request`), you approve its card once, and it builds —
205
+ tables, comments, packages, releases — without stopping for each write.
206
+ `acceptEdits` mode plus a lease is the fully hands-off setup.
207
+
208
+ ### Codex
209
+
210
+ 1. Run `python -m pythia install` in the project root. It:
211
+ - writes the harness into **`AGENTS.md`** (Codex loads it every session);
212
+ - registers a write-free MCP approver in **`.codex/config.toml`**;
213
+ - adds a SessionStart guide hook in **`.codex/hooks.json`**.
214
+
215
+ Skills land in `.agents/skills` (or `~/.agents/skills` with `-g`) — the
216
+ directory Codex reads.
217
+ 2. In Codex, **trust the pieces once**: `/mcp` (the `pythia` server) and
218
+ `/hooks` (the project `.codex` layer).
219
+ 3. **Restart the Codex session** so the new `AGENTS.md` loads.
220
+ 4. Check it: `/skills` lists the pythia skills, `/mcp` shows
221
+ `pythia: connected`.
222
+
223
+ Needs **Codex ≥ v0.120** for the in-chat approval (MCP elicitation); an older
224
+ or headless Codex falls back to the console `pythia approve <token>`. Do
225
+ **not** run Codex under `danger-full-access` — that sandbox auto-approves
226
+ elicitations and bypasses your Approve.
227
+
228
+ **Approving a change:** the agent previews with `pythia apply`, calls the
229
+ `pythia_approve` tool, you answer a select **Approve / Reject** prompt right in
230
+ Codex, and on Approve the agent runs `apply --confirm` itself.
231
+
148
232
  ## Commands
149
233
 
150
234
  | Read | Understand | Write |
151
235
  |---|---|---|
152
236
  | `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) | | |
237
+ | `ls` find objects | `impact` what depends on it | `deploy` a release script, in order, one approval |
238
+ | `src` source, compiler line numbers | `errors` compile errors, line:col | `journal` list · diff · export · restore |
239
+ | `args` signatures | `invalid` everything broken | `policy` show · set |
240
+ | `ddl` via DBMS_METADATA | `plscope` exact identifier usages | `approve` the developer's one-time grant |
241
+ | `cols` columns + types | `similar` programs named like this | `autopilot` request · status · report · off |
242
+ | `comments` table/column comments, `--scaffold` | `lint` house + built-in standards | `unistr` exact non-ASCII literals |
243
+ | `stats` optimizer stats, indexes, unindexed FKs | `explain` the plan, never run | `agent-user` least-privilege setup |
244
+ | `grep` search all source | `doctor` harness + environment health | `history` every captured version |
245
+ | `sql` free query (SELECT/WITH only) | | `skill new · lint` grow your own skills |
160
246
 
161
247
  Every command takes `--json` (machine output), `--conn` (pick a connection), and
162
248
  caps output with explicit truncation markers so context windows stay intact.
@@ -190,23 +276,17 @@ hand with
190
276
  works just as well.
191
277
  `pythia check` warns when the session runs with more power than the task needs.
192
278
 
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.
279
+ The developer approval that `apply` requires is minted per agent — Claude
280
+ Code's `AskUserQuestion` hook, or Codex's `pythia_approve` MCP tool, or the
281
+ console `pythia approve <token>` anywhere. How each is wired is in
282
+ [Setting up Claude Code and Codex](#setting-up-claude-code-and-codex) above.
204
283
 
205
284
  Per-group write policy, `.pythia/policy.json` (defaults shown):
206
285
 
207
286
  | Group | Default | Is rollback real? |
208
287
  |---|---|---|
209
288
  | `plsql_source` | `confirm` | **Yes — completely.** Source is recoverable from `ALL_SOURCE`. |
289
+ | `comments` | `confirm` | **Yes.** The previous comment is snapshotted before every write. |
210
290
  | `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
291
  | `structural` | `deny` | **Almost never.** `DROP COLUMN` is permanent; a dropped table may be in the Recycle Bin. |
212
292
  | `grants` | `deny` | Yes, but by hand. |
@@ -224,14 +304,23 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
224
304
 
225
305
  ## Skills
226
306
 
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).
307
+ The skills teach the agent the workflow — gates, not suggestions:
308
+
309
+ - **The method:** `using-pythia` (the router) · `pythia-spec` (open decisions
310
+ are asked, not assumed) · `pythia-explore` · `pythia-impact` (before any
311
+ change) · `pythia-verify` (evidence before "done").
312
+ - **Building on Oracle:** `pythia-table` (tables, columns, constraints,
313
+ indexes, every column commented) · `pythia-package` (packages, procedures,
314
+ functions, triggers to industry-standard design) · `pythia-write` (copy the
315
+ codebase's conventions) · `pythia-comment` · `pythia-tune` (measure, change
316
+ one thing, measure again) · `pythia-review` (antipatterns).
317
+ - **Landing it:** `pythia-apply` (the gate) · `pythia-deploy` (release
318
+ scripts, in order, one approval) · `pythia-autopilot` (one delegated lease
319
+ instead of every approval).
320
+ - **The team's own way:** `pythia-conventions` (the LEAD's naming and lint
321
+ rules, verified against real names) · `pythia-skill-author` (capture a
322
+ workflow as a skill; `pythia skill new` / `skill lint`) · `pythia-setup`
323
+ (connections, agent user, `pythia doctor`, a robust dev environment).
235
324
 
236
325
  ## Compatibility
237
326
 
@@ -240,7 +329,7 @@ the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
240
329
  | OS | Windows, macOS, Linux, WSL — full test matrix in CI |
241
330
  | Python | 3.9+ · stdlib + `python-oracledb` (thin mode) only |
242
331
  | 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 |
332
+ | 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
333
 
245
334
  ## Star History
246
335
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pythia-plsql"
7
- version = "0.14.2"
7
+ version = "0.15.1"
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