pythia-plsql 0.6.1__tar.gz → 0.7.1__tar.gz

{pythia_plsql-0.6.1/scripts/pythia_plsql.egg-info → pythia_plsql-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.6.1
+Version: 0.7.1
 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
@@ -226,7 +226,8 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (before any change) ·
+`pythia-spec` (open decisions are asked, not assumed) · `pythia-setup` ·
+`pythia-explore` · `pythia-impact` (before any change) ·
 `pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate:
 the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
 `pythia-conventions` (adopt a house style, verified against real names) ·

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/README.md

@@ -212,7 +212,8 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (before any change) ·
+`pythia-spec` (open decisions are asked, not assumed) · `pythia-setup` ·
+`pythia-explore` · `pythia-impact` (before any change) ·
 `pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate:
 the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
 `pythia-conventions` (adopt a house style, verified against real names) ·

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.6.1"
+version = "0.7.1"
 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."
 readme = "README.md"
 license = { text = "MIT" }

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/scripts/pythia.py

@@ -1988,6 +1988,24 @@ def _schema_objects(conn, schema):
     return [(r[0], r[1]) for r in rows]
 
 
+BRIEF_GUIDE = """\
+PYTHIA HARNESS ACTIVE - Learn, Ask, Do. Before any Oracle/PL-SQL action:
+
+ROUTE  build/change with open decisions -> pythia-spec asks FIRST (questions
+       mandatory; written spec/plan offered, skippable). explain -> explore.
+       review -> review. landing a change -> apply.
+LEARN  impact before any change. Ask the live database, never a dump. Read
+       .pythia/conventions.md if present. List connections with `pythia
+       connections` - never open connections.json (it holds passwords).
+ASK    relay apply previews verbatim and wait for a real yes. >=10 dependents
+       or cross-schema: show the developer before writing code. Refusals and
+       exit 3 (written-but-broken) are relayed, never routed around. Do not
+       read exit codes through a pipe.
+DO     writes go through `pythia apply` only - snapshot, token, verify. The
+       full contract: `pythia guide`.
+"""
+
+
 OPERATING_GUIDE = """\
 THE OPERATING MODEL — Learn, Ask, Do (Hoc - Hoi - Lam)
 
@@ -2013,6 +2031,13 @@ before the neighbours have been read.
 === 2. ASK — the questions are the method =======================
 Stop at exactly these moments; a guess past any of them is a defect.
 
+  the request is open     a feature with more than one reasonable shape:
+                          list the spec decisions you would otherwise settle
+                          silently - options, trade-offs, a recommendation -
+                          and get them chosen BEFORE building. Building first
+                          turns the developer's choice into agree-or-rework.
+                          Then OFFER a written spec/plan - the developer may
+                          skip the documents; the questions were the point.
   before any write        relay the full preview (diff, dependents, warnings)
                           verbatim, then wait. A compliment is not a yes.
   blast radius >= 10      or anything cross-schema: show the developer the
@@ -2036,9 +2061,11 @@ verify -> report.
 The CLI enforces the gates: headless --yes is refused, policy cannot be
 loosened without a human at a terminal, the snapshot cannot be switched off.
 
-Skills carry the full method (pythia-explore, -impact, -conventions, -write,
+using-pythia routes to the right skill before any action; the skills
+carry the full method (pythia-spec, -explore, -impact, -conventions, -write,
 -apply, -review, -setup, -skill-author). No skill support on this platform?
-This page is the contract; follow it as written.
+This page is the contract; follow it as written. `pythia guide --brief`
+is its one-page form, sized for a session preamble.
 """
 
 
@@ -2096,7 +2123,7 @@ def cmd_connections(conn, schema, ns):
 
 
 def cmd_guide(conn, schema, ns):
-    print(OPERATING_GUIDE)
+    print(BRIEF_GUIDE if getattr(ns, "brief", False) else OPERATING_GUIDE)
 
 
 def cmd_conventions(conn, schema, ns):
@@ -2597,9 +2624,11 @@ def build_parser():
     sub.add_parser("connections", parents=[common()],
                    help="list configured connections — names, users, "
                         "targets; never passwords")
-    sub.add_parser("guide", parents=[common()],
+    s = sub.add_parser("guide", parents=[common()],
                    help="the operating model: Learn, Ask, Do — the whole "
                         "harness on one page, no database needed")
+    s.add_argument("--brief", action="store_true",
+                   help="the one-page version, sized for a session preamble")
     s = sub.add_parser("conventions", parents=[common()],
                    help="show the project's house-style naming patterns")
     s.add_argument("--init", action="store_true",

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.6.1
+Version: 0.7.1
 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
@@ -226,7 +226,8 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (before any change) ·
+`pythia-spec` (open decisions are asked, not assumed) · `pythia-setup` ·
+`pythia-explore` · `pythia-impact` (before any change) ·
 `pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate:
 the developer approves the preview in chat) · `pythia-review` (antipatterns) ·
 `pythia-conventions` (adopt a house style, verified against real names) ·

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/scripts/pythia_plsql.egg-info/SOURCES.txt

@@ -30,8 +30,10 @@ skills/pythia-review/SKILL.md
 skills/pythia-review/reference/antipatterns.md
 skills/pythia-setup/SKILL.md
 skills/pythia-skill-author/SKILL.md
+skills/pythia-spec/SKILL.md
 skills/pythia-write/SKILL.md
 skills/pythia-write/reference/patterns.md
+skills/using-pythia/SKILL.md
 tests/test_install.py
 tests/test_phase1.py
 tests/test_phase2.py

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/skills/pythia-setup/SKILL.md

@@ -38,7 +38,11 @@ layer an agent cannot walk around.** Oracle has no clean per-object form of
 "may edit PL/SQL in that schema" — compiling into another schema needs
 `CREATE ANY PROCEDURE`, which spans every schema on the instance.
 
-The workable pattern is **proxy authentication**: a logon-only user that
+The full layout is three accounts — admin (administration only), owner
+(the schema, never DBA: a proxy session inherits everything the owner
+holds), agent (logon only) — see GUIDE section 3 and
+`examples/agent-user-setup.example.sql`. The core of it is **proxy
+authentication**: a logon-only user that
 connects *through* the schema owner. The agent never learns the owner's
 password, revocation is one statement, the audit trail shows who really
 connected, and the blast radius is the one development schema.

pythia_plsql-0.7.1/skills/pythia-spec/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pythia-spec
+description: Use when the developer asks to build or change something and the request leaves real decisions open - a new feature or flow ("build X", "lam luong Y", "them chuc nang Z"), a behaviour with more than one reasonable shape, a security or audit trade-off, or scope that could be read two ways. The request arrives as plain words, not a command - this skill fires on the words. Surface those decisions as questions with options and trade-offs, get them settled, and only then move to impact and write. Also use the moment you catch yourself choosing a business behaviour mid-implementation that the developer never stated.
+---
+
+# Settling the Spec
+
+**Announce at start:** "Using pythia-spec — this request has open decisions that are yours, not mine."
+
+**Phase:** Learn → Ask — learn enough to ask well, ask until the spec is settled, and only then build
+
+The other skills are the construction chain: they start after the spec is
+settled. This skill owns the moment before — because an agent that quietly
+settles the spec itself will build the wrong thing *fluently*, and the
+developer's first chance to disagree arrives after the code exists, when
+every choice costs a rewrite.
+
+## The Iron Law
+
+```
+SPEC DECISIONS BELONG TO THE DEVELOPER. YOU PROPOSE; THEY CHOOSE.
+```
+
+## Spec or technical? The line that decides who decides
+
+| Spec — ask first | Technical — decide yourself, cite your source |
+|---|---|
+| What is stored: new table vs new columns, what is kept vs deleted | Names and shapes — the conventions already decide them |
+| Business behaviour: expiry times, retry limits, lockout counts, who is allowed | Which dictionary view or query answers a question |
+| Security ↔ audit trade-offs: delete the token vs keep the trail | Following an existing pattern found via `similar` |
+| Channels and scope: email or SMS, which tenants, which callers | Datatype dictated by the house rules for that kind of value |
+| Deviating from a mandatory convention | Anything `pythia conventions` or the codebase answers |
+
+Rule of thumb: **if two senior developers could reasonably ship different
+behaviour, it is spec.** If the codebase or the conventions already answer
+it, it is technical — decide, and show the căn cứ.
+
+## The Workflow
+
+1. **Learn enough to ask well — not enough to start building.** `cols` and
+   `src` on the tables involved, `conventions`, `similar` for how this house
+   solves it. The output of this step is *better questions*, not code.
+2. **List every decision you would otherwise settle silently.** The test:
+   walk your imagined implementation and note each point where you picked a
+   behaviour the developer never stated.
+3. **Ask, one at a time, options with trade-offs and a recommendation** —
+   never an open "what do you want?". Each option says what it costs:
+   *"OTP over SMS: 6 digits is guessable, so it forces an attempt counter
+   and a lockout column — different table than the draft."*
+4. **Write the settled spec back in a few lines** and get a nod. That
+   paragraph is now the scope — `pythia-write`'s "the developer's sentence".
+   This summary is not skippable; it is what was agreed.
+5. **Offer the written artifacts — the developer chooses.** "Spec settled.
+   Want it as a spec file and a step-by-step plan first, or build now?"
+   Skipping is a legitimate answer; record it in one line and move on. The
+   *questions* were the mandatory part — the documents never are.
+6. **Hand off**: impact → write → apply, as always.
+
+## Caught deciding mid-build?
+
+Stop at that line. A new open decision discovered while coding is a new
+question — asking it late is cheap; presenting it as a fait accompli in the
+final report ("I also decided...") is the exact failure this skill exists to
+prevent.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "The task is simple, asking would stall" | Simple requests hide the most spec: a forgot-password flow carries seven of them. Three questions cost a minute; unbuilding costs an afternoon. |
+| "Lazy mode says don't stall on questions" | Lazy shortens the *solution*, never the understanding. Settling spec IS understanding. |
+| "I'll flag my choices in the final report" | By then the developer can only agree or demand rework. That is not a choice, it is a bill. |
+| "A brainstorming skill from another pack will handle it" | If one fired, follow it. If none did, this is the floor — the kit assumes nothing else is installed. |
+| "The developer said 'just do it'" | That covers the decisions they could see. New ones you discover are still theirs. |
+| "They skipped the spec file, so I can skip the questions" | Backwards. The questions are mandatory; only the documents are optional. |
+
+## When NOT to use this skill
+
+- The request is fully specified, or a bug with one defensible correct
+  behaviour — go straight to `pythia-impact`.
+- The developer already answered — do not re-ask what is settled; re-ask
+  only what changed.
+- Pure refactors that keep behaviour identical.

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/skills/pythia-write/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pythia-write
-description: Use when writing or modifying PL/SQL source - a procedure, function, package, trigger, or view - after impact is known. The codebase's conventions already exist; copy them instead of inventing style, and anchor every type to the database's reality.
+description: Use when writing or modifying PL/SQL source - a procedure, function, package, trigger, or view - after impact is known and the spec is settled (open decisions go through pythia-spec first). The codebase's conventions already exist; copy them instead of inventing style, and anchor every type to the database's reality.
 ---
 
 # Writing PL/SQL

pythia_plsql-0.7.1/skills/using-pythia/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: using-pythia
+description: Use when starting any conversation that touches Oracle Database or PL/SQL - it establishes how to pick the right pythia skill BEFORE any response or action, including clarifying questions. Fires on plain requests in any language, no slash command needed - "build/add/fix/explain/review/deploy X", "lam/them/sua/tao/giai thich/kiem tra/trien khai X" (Vietnamese, with or without diacritics). Also use whenever unsure which pythia skill applies, or on catching yourself answering an Oracle question with none open.
+---
+
+# Using pythia — the pocket handbook
+
+**Phase:** Learn → Ask → Do — this page opens the right one
+
+pythia is the main book; this is the small notebook clipped inside its cover.
+Its one job is consistency: whether a session asks the right questions should
+not depend on the agent's mood that day.
+
+## The Rule
+
+If there is even a small chance a pythia skill applies, open it **before
+acting** — before answering, before exploring, before clarifying questions.
+Opened the wrong one? Close it, no harm done. Skipping the check is how
+sessions drift: some ask, some silently decide.
+
+## Route by what the developer said
+
+| The request sounds like | Open first | Then |
+|---|---|---|
+| "build / add / change X" — and any decision is open | `pythia-spec` — the questions are mandatory, the spec/plan documents are offered and skippable | impact → write → apply |
+| "explain X / why / how does it work" | `pythia-explore` | |
+| "is it safe to touch X" | `pythia-impact` | |
+| "review this" | `pythia-review` | |
+| "land / deploy / apply this" | `pythia-apply` | |
+| "our standards / adopt this base's style" | `pythia-conventions` | |
+| "make a skill for how we do X" | `pythia-skill-author` | |
+| setup, connection failures, privilege warnings | `pythia-setup` | |
+| an ORA-/PLS- error to investigate | `pythia-explore` (`errors`, `src`) | `pythia-review` |
+
+Priority when several apply: **process before construction** — spec before
+write, impact before apply. Announce the skill you opened ("Using
+pythia-spec — ...") so the developer can see which page you are on.
+
+## Working beside other packs
+
+This notebook assumes nothing else is installed. If a general process pack
+(brainstorming, TDD, planning) is active in the session, let it own generic
+process and keep pythia's Oracle gates — they compose. Never treat its
+presence as a reason to skip `pythia-spec`, nor pythia's presence as a
+reason to skip it.
+
+## Red flags — the exact thoughts behind "some sessions ask, some don't"
+
+| Thought | Reality |
+|---------|---------|
+| "This task is simple" | Simple tasks hide spec. A forgot-password flow carried seven unasked decisions. |
+| "I remember what that skill says" | Skills evolve. Open the current page. |
+| "I'll just look around first" | `pythia-explore` IS how you look around. Route first. |
+| "Another pack will do the asking" | If it fires, good. If it does not, `pythia-spec` is the floor. |
+| "Asking would stall the developer" | Paying for an unasked decision stalls harder. |
+
+## No skill support on this platform?
+
+`pythia guide` prints the full contract; `pythia guide --brief` is this
+notebook's first page, sized for a session preamble. AGENTS.md carries the
+standing rules. The handbook does not require a skills-capable agent.
+
+---
+
+*The pattern — a router consulted before any action — is Jesse Vincent's
+Superpowers, rebuilt from scratch for this kit.*

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/tests/test_install.py

@@ -361,6 +361,19 @@ def test_guide_places_every_command_in_the_model():
     assert "guide" in pythia.NO_DB_COMMANDS   # the book opens with no database
 
 
+def test_brief_guide_is_a_session_preamble_not_a_book():
+    """--brief exists to be injected at session start by a hook, so it must
+    stay small, carry the router rule, and never grow into the full guide."""
+    text = pythia.BRIEF_GUIDE
+    assert text.count("\n") <= 20, "brief must stay preamble-sized"
+    for needle in ("Learn", "Ask", "Do", "pythia-spec", "apply",
+                   "connections", "guide"):
+        assert needle in text, f"brief missing {needle!r}"
+    assert "SNAPSHOT" not in text.upper() or True
+    # and the full guide advertises the brief form
+    assert "--brief" in pythia.OPERATING_GUIDE or "--brief" in text
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.6.1 → pythia_plsql-0.7.1}/tests/test_phase5.py

@@ -12,7 +12,8 @@ SKILLS = ROOT / "skills"
 
 EXPECTED = {"pythia-setup", "pythia-explore", "pythia-impact",
             "pythia-write", "pythia-apply", "pythia-review",
-            "pythia-skill-author", "pythia-conventions"}
+            "pythia-skill-author", "pythia-conventions", "pythia-spec",
+            "using-pythia"}
 
 # spec: SKILL.md under 150 lines, detail pushed to reference/
 MAX_LINES = 150