pythia-plsql 0.11.2__tar.gz → 0.13.0__tar.gz

{pythia_plsql-0.11.2/scripts/pythia_plsql.egg-info → pythia_plsql-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.11.2
+Version: 0.13.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -128,7 +128,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -212,6 +212,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/README.md

@@ -114,7 +114,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -198,6 +198,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.11.2"
+version = "0.13.0"
 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.11.2 → pythia_plsql-0.13.0}/queries/name-occupants.sql

@@ -5,8 +5,9 @@
 --          ORA-00955. Found by an agent during the first field test.
 -- Binds:   :s  schema (object owner)
 --          :n  object name
--- Returns: OBJECT_TYPE
-select object_type
+-- Returns: OBJECT_TYPE, EDITIONABLE ('Y'/'N', null when the type
+--          has no edition — the apply reconciles the keyword to it)
+select object_type, editionable
   from all_objects
  where owner = :s
    and object_name = upper(:n)

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/scripts/pythia.py

@@ -1240,6 +1240,46 @@ EDITIONABLE_KW_RE = re.compile(
     r"^create\s+(?:or\s+replace\s+)?((?:non?)?editionable)\b", re.I)
 
 
+CREATE_HEAD_RE = re.compile(
+    r"^(create\s+(?:or\s+replace\s+)?)((?:non?)?editionable\s+)?", re.I)
+
+
+def reconcile_editionable(stmt, editionable):
+    """Make the statement agree with the property the database already holds.
+
+    ALL_SOURCE stores no CREATE header, so a body read back with `src` comes
+    back bare and the keyword is the easiest thing in Oracle to lose — and
+    Oracle refuses to *change* the property through CREATE OR REPLACE, so the
+    statement cannot succeed. Left alone, ORA-38824 lands after the developer
+    has already approved the preview. Nothing here is guessed:
+    ALL_OBJECTS.EDITIONABLE is the answer, and the edit is announced.
+
+    Returns (statement, note). The file on disk is never touched."""
+    if editionable not in ("Y", "N"):
+        return stmt, None      # a new object, or a type that has no edition
+    body = skip_leading_noise(stmt)
+    m = CREATE_HEAD_RE.match(body)
+    if not m:
+        return stmt, None
+    have = (m.group(2) or "").strip().upper()
+    if editionable == "N":
+        want = "NONEDITIONABLE"
+    else:
+        # only NONEDITIONABLE contradicts an editionable object; a bare header
+        # and an explicit EDITIONABLE both say the same thing to Oracle
+        want = "" if have.endswith("EDITIONABLE") and have != "EDITIONABLE" else have
+    if have == want:
+        return stmt, None
+    head = stmt[:len(stmt) - len(body)]
+    fixed = head + m.group(1) + (want + " " if want else "") + body[m.end():]
+    verb = "added" if want else "removed"
+    # two lines, indented like the other preview warnings: one long line wraps
+    # into noise in a terminal
+    return fixed, (f"NONEDITIONABLE {verb} to match the object in the "
+                   "database — Oracle cannot\n  change that property through "
+                   "CREATE OR REPLACE (ORA-38824). Your file is unchanged.")
+
+
 def create_prefix(after_text):
     """The CREATE header ALL_SOURCE does not store, rebuilt for the version
     held in the database. The editionable keyword is read off the file being
@@ -1253,6 +1293,54 @@ def create_prefix(after_text):
     return "CREATE OR REPLACE " + (f"{m.group(1).upper()} " if m else "")
 
 
+def source_body(after_text):
+    """The ALL_SOURCE-shaped half of a stored statement. create_prefix builds
+    the header ALL_SOURCE does not keep; this drops it again, plus the
+    SQL*Plus terminator, so the two can be compared as equals."""
+    body = skip_leading_noise(prepare_statement(after_text, "plsql_source"))
+    m = CREATE_HEAD_RE.match(body)
+    return body[m.end():] if m else body
+
+
+def drift_note(db_source, last_applied, entry):
+    """Whether the object moved since pythia last wrote it.
+
+    The snapshot proves what pythia did; nothing ever proved what anyone else
+    did. In the field a comment line was written, read back intact two seconds
+    later, and gone eight minutes on with no journal entry in between — and
+    the developer went hunting a lying `src` instead of a second writer. The
+    journal held both halves of the answer the whole time and nothing compared
+    them. Warn, never refuse: editing by hand is legitimate, not noticing is
+    not."""
+    if not last_applied or not db_source.strip():
+        return None
+    mine = source_body(last_applied).replace("\r\n", "\n").rstrip()
+    now = db_source.replace("\r\n", "\n").rstrip()
+    if mine == now:
+        return None
+    delta = len(now.splitlines()) - len(mine.splitlines())
+    how = (f"{abs(delta)} line{'s' if abs(delta) != 1 else ''} "
+           + ("more" if delta > 0 else "fewer")) if delta else         "the same line count, different text"
+    return (f"This object changed outside pythia since {entry} ({how}). The "
+            "diff below is\n  against the database as it stands now, not "
+            "against what pythia wrote.")
+
+
+def last_applied_after(root, obj_type, name):
+    """The text pythia last actually wrote to this object, from the journal."""
+    for eid in list_journal_entries(root):
+        try:
+            e = read_journal_entry(root, eid)
+        except SystemExit:
+            continue
+        meta = e["meta"]
+        if (meta.get("applied")
+                and str(meta.get("object", "")).upper() == name.upper()
+                and str(meta.get("type", "")).upper() == obj_type.upper()):
+            return eid, e["after"]
+    return None, None
+
+
 def render_restore(obj_type, name, before_text, after_text=""):
     """The statement that puts things back. For an object that did not exist,
     undo means DROP — a genuinely different promise than restoring source, so
@@ -2046,6 +2134,7 @@ def run_apply(conn, schema, ns, file_text, origin=None):
               "invocation's connection, which is now over.")
         return 0
 
+    edition_note = None
     if group == "plsql_source":
         otype, name, file_schema = parse_object(file_text)
         if file_schema and file_schema.upper() != schema:
@@ -2056,6 +2145,9 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         _, occ_rows = run_query(conn, load_query("name-occupants.sql"),
                                 {"s": schema, "n": name})
         blockers = name_conflicts(otype, [r[0] for r in occ_rows])
+        stmt, edition_note = reconcile_editionable(
+            stmt, next((cell(r[1]) for r in occ_rows
+                        if str(r[0]).upper() == otype.upper()), None))
         if blockers:
             sys.exit(f"{name} already exists as {', '.join(blockers)} in {schema} "
                      "— CREATE OR REPLACE cannot change an object's type "
@@ -2112,12 +2204,17 @@ def run_apply(conn, schema, ns, file_text, origin=None):
             "tty": human_at_the_keyboard(),
             "invalid_before": invalid_before, **(origin or {})}
     entry = write_journal_entry(ns.project_root, otype, name, db_source,
-                                file_text, meta)
+                                stmt if edition_note else file_text, meta)
     # "created" is about an OBJECT that did not exist. A DML/DDL statement has
     # no object identity, so it is never "new" — and saying so would promise a
     # DROP-shaped undo that does not exist for those groups.
     created = not db_source.strip() and group == "plsql_source"
 
+    drift = None
+    if group == "plsql_source" and db_source.strip():
+        eid, last = last_applied_after(ns.project_root, otype, name)
+        drift = drift_note(db_source, last, eid)
+
     # 2. IMPACT
     summary = ""
     if group == "plsql_source":
@@ -2140,7 +2237,9 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                           "created": created, "changed_lines": changed,
                           "summary": summary, "warning": warn,
                           "row_set": row_set,
-                          "naming_warning": style, "token": token,
+                          "naming_warning": style,
+                          "editionable_note": edition_note, "drift": drift,
+                          "token": token,
                           "journal": entry, "will_apply": confirmed}))
     else:
         en = getattr(ns, "color", False)
@@ -2164,6 +2263,10 @@ def run_apply(conn, schema, ns, file_text, origin=None):
         elif group == "data_dml":
             print("\n  INSERT — no rows exist beforehand, so there is no row "
                   "set to revalidate.")
+        if drift:
+            print(f"\n  {paint('! ' + drift, 'yellow', en)}")
+        if edition_note:
+            print(f"\n  {paint('! ' + edition_note, 'yellow', en)}")
         if warn:
             print(f"\n  {paint(warn, 'yellow', en)}")
         if style:
@@ -2203,7 +2306,15 @@ def run_apply(conn, schema, ns, file_text, origin=None):
             cur.execute("ALTER SESSION SET plscope_settings = "
                         "'IDENTIFIERS:ALL, STATEMENTS:ALL'")
     with conn.cursor() as cur:
-        cur.execute(stmt)
+        try:
+            cur.execute(stmt)
+        except Exception as e:            # noqa: BLE001 - the driver refused
+            # the preview and "Snapshot saved" printed before this line ran,
+            # so without a closing verdict the run reads like one that landed
+            sys.exit(f"FAILED — nothing was written.\n{e}\n"
+                     "The object is unchanged. The approval is unspent: retry "
+                     "the same file with the same token, or fix the file and "
+                     "preview again for a new one.")
         affected = cur.rowcount if group == "data_dml" else None
     if group == "data_dml":
         # the last-millisecond check: the probe ran before this statement, and
@@ -2707,6 +2818,51 @@ DO     writes go through `pythia apply` only - snapshot, token, verify. The
 """
 
 
+AGENTS_BEGIN = "<!-- pythia:begin (managed by `pythia install`; edit outside this block) -->"
+AGENTS_END = "<!-- pythia:end -->"
+
+
+def agents_md_block():
+    """The pythia section for AGENTS.md — Codex's always-loaded instruction
+    file. Body is BRIEF_GUIDE verbatim (the same constant `guide --brief`
+    prints and the Claude SessionStart hook runs, so the two cannot drift),
+    plus the one line Codex needs that Claude gets from its hook: where the
+    approval door is, since Codex has no chat-mint. Marker-wrapped so a re-run
+    replaces it in place and the developer's own text is untouched."""
+    return (f"{AGENTS_BEGIN}\n"
+            "## pythia — developing PL/SQL on Oracle\n\n"
+            f"{BRIEF_GUIDE.rstrip()}\n\n"
+            "On Codex there is no chat approval hook: the developer approves a "
+            "preview in this terminal with `pythia approve <token>`, then the "
+            "agent runs `pythia apply <file> --confirm <token>`.\n"
+            f"{AGENTS_END}")
+
+
+def merge_agents_md(path):
+    """Write the pythia block into an AGENTS.md. The file is the developer's,
+    shared with every AGENTS.md-reading agent, so only the delimited block is
+    ours: present -> replaced in place, absent -> appended below their text,
+    everything else byte-identical. Returns (path, action) where action is
+    'created' | 'updated' | 'unchanged'."""
+    path = pathlib.Path(path)
+    block = agents_md_block()
+    old = path.read_text(encoding="utf-8") if path.is_file() else None
+    if old is None:
+        new, action = block + "\n", "created"
+    elif AGENTS_BEGIN in old and AGENTS_END in old:
+        pre = old[:old.index(AGENTS_BEGIN)]
+        post = old[old.index(AGENTS_END) + len(AGENTS_END):]
+        new = pre + block + post
+        action = "unchanged" if new == old else "updated"
+    else:
+        tail = "" if old.endswith("\n\n") else "\n" if old.endswith("\n") else "\n\n"
+        new, action = old + tail + block + "\n", "updated"
+    if new != old:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new, encoding="utf-8")
+    return path, action
+
+
 OPERATING_GUIDE = """\
 THE OPERATING MODEL — Learn, Ask, Do (Hoc - Hoi - Lam)
 
@@ -3125,29 +3281,36 @@ def global_pack_present(home=None):
 
 
 def copy_bundled_skills(base_dir):
-    """No-Node fallback: copy the wheel-bundled pack into
-    <base>/.claude/skills/ ONLY — the directory Claude Code reliably reads
-    in both scopes (field evidence: a project's .agents/skills is invisible
-    to some Claude Code versions, and a second copy doubles every menu
-    entry). base_dir is the project root, or the home directory for -g.
+    """No-Node fallback: copy the wheel-bundled pack into BOTH conventional
+    roots — <base>/.claude/skills/ (Claude Code) and <base>/.agents/skills/
+    (Codex, and ~/.agents/skills on -g). base_dir is the project root, or the
+    home directory for -g. Node users get the same reach from `npx skills
+    add`; this is the machine that has only Python.
+
+    Trade-off, stated plainly: this reverses an earlier one-root-only choice.
+    A Claude Code version that reads both roots may list a pack entry twice —
+    accepted, because a Codex user without Node otherwise gets no skills at
+    all, and Codex reads only .agents/skills.
 
     Both destinations are cleared link-first before the copy. An earlier
     `npx skills add` leaves .claude/skills/<name> as a symlink into
-    .agents/skills/<name>; copying into that symlink would write through to
-    its target, which the .agents cleanup then deletes — leaving a dangling
-    link and no pack at all. Only the pack's own names are touched; other
-    skills in those directories are left alone."""
+    .agents/skills/<name>; removing both links first means each copytree
+    writes a fresh real directory, never through a link into a target the
+    other copy would then overwrite. Only the pack's own names are touched;
+    other skills in those directories are left alone."""
     import shutil
     base = pathlib.Path(base_dir)
-    dest_root = base / ".claude" / "skills"
+    claude_root = base / ".claude" / "skills"      # Claude Code reads this
+    agents_root = base / ".agents" / "skills"      # Codex reads this
     for pack in sorted(SKILLS_DIR.iterdir()):
         if not (pack / "SKILL.md").is_file():
             continue
-        _remove_link_first(dest_root / pack.name)
-        _remove_link_first(base / ".agents" / "skills" / pack.name)
-        shutil.copytree(pack, dest_root / pack.name)
+        _remove_link_first(claude_root / pack.name)
+        _remove_link_first(agents_root / pack.name)
+        shutil.copytree(pack, claude_root / pack.name)
+        shutil.copytree(pack, agents_root / pack.name)
     clean_legacy_skills(base_dir)
-    return [dest_root]
+    return [claude_root, agents_root]
 
 
 def _remove_link_first(path):
@@ -3191,6 +3354,43 @@ CLAUDE_DENY = ["Bash(pythia approve --hook*)",
 # is recognised by what it runs, not by how it invokes it
 HOOK_MARKS = {"SessionStart": "guide --brief", "PostToolUse": "approve --hook"}
 
+# Codex loads hooks from <repo>/.codex/hooks.json once the layer is trusted
+# (/hooks). Only the session-start guide is wired — Codex has no answer-reading
+# PostToolUse and no question tool, so the chat approve-mint cannot port; the
+# developer approves in the terminal. Same shape and merge discipline as the
+# Claude hooks.
+CODEX_HOOKS = {
+    "SessionStart": [{"hooks": [
+        {"type": "command", "command": "python -m pythia guide --brief"}]}],
+}
+CODEX_HOOK_MARKS = {"SessionStart": "guide --brief"}
+
+
+def merge_codex_hooks(path, events=None):
+    """Merge pythia's Codex hooks into a hooks.json ({"hooks": {...}}). Every
+    other key survives, a hook already present in any spelling is recognised by
+    what it runs, and a file that will not parse is left byte-identical.
+    Returns (path, added|None)."""
+    path = pathlib.Path(path)
+    try:
+        s = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+        hooks = s.setdefault("hooks", {})
+        added = []
+        for event in events or CODEX_HOOKS:
+            present = hooks.setdefault(event, [])
+            cmds = " ".join(h.get("command", "")
+                            for e in present for h in e.get("hooks", []))
+            if CODEX_HOOK_MARKS[event] not in cmds:
+                present.extend(json.loads(json.dumps(CODEX_HOOKS[event])))
+                added.append(f"hooks.{event}")
+    except (ValueError, TypeError, AttributeError):
+        return path, None
+    if added:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(s, indent=2, ensure_ascii=False) + "\n",
+                        encoding="utf-8")
+    return path, added
+
 
 def install_claude_hooks(base_dir, events=None):
     """Merge the two hooks and the deny rule into <base>/.claude/settings.json
@@ -3246,6 +3446,33 @@ def report_claude_hooks(base_dir, ns, events=None):
         print(f"\nClaude Code hooks already in {path}.")
 
 
+def report_codex_agents_md(project_root):
+    """Project scope: write the harness into <project>/AGENTS.md, the file
+    Codex loads every session. Not done on -g — a global AGENTS.md is noise in
+    every non-Oracle session, as the Claude guide is per-project."""
+    path, action = merge_agents_md(pathlib.Path(project_root) / "AGENTS.md")
+    verb = {"created": "Wrote the pythia harness into",
+            "updated": "Updated the pythia block in",
+            "unchanged": "pythia harness already current in"}[action]
+    print(f"\n{verb} {path} (Codex and other AGENTS.md agents load it each session).")
+
+
+def report_codex_hooks(project_root, ns):
+    """Project scope: the Codex session-start guide hook. --no-hooks skips it,
+    as with the Claude hooks. AGENTS.md already carries the guide, so this is
+    reinforcement for hook-driven Codex users."""
+    if getattr(ns, "no_hooks", False):
+        return
+    path, added = merge_codex_hooks(pathlib.Path(project_root) / ".codex" / "hooks.json")
+    if added is None:
+        print(f"\n! {path} is not valid JSON, so it was left untouched.")
+    elif added:
+        print(f"\nWired the Codex session-start hook into {path}.")
+        print("In Codex, run /hooks once to trust this project's .codex layer.")
+    else:
+        print(f"\nCodex session-start hook already in {path}.")
+
+
 def cmd_install(conn, schema, ns):
     import shutil
     en = getattr(ns, "color", False)
@@ -3287,6 +3514,8 @@ def cmd_install(conn, schema, ns):
         else:
             clean_legacy_skills(ns.project_root)
     report_claude_hooks(ns.project_root, ns)
+    report_codex_agents_md(ns.project_root)
+    report_codex_hooks(ns.project_root, ns)
     print(f"\nNext: fill in {path}")
     print(f"Then: {invocation()} check")
     scripts_dir = installed_scripts_dir()

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.11.2
+Version: 0.13.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -128,7 +128,7 @@ Or the same thing piecewise:
 
 ```bash
 pip install pythia-plsql   # the CLI (thin driver — no Oracle Instant Client needed)
-python -m pythia install   # skills into your agent + .pythia/ scaffold + Claude Code hooks
+python -m pythia install   # skills + .pythia/ scaffold + Claude Code hooks + Codex AGENTS.md
 pythia check               # fill in connections.json first, then verify
 ```
 
@@ -212,6 +212,10 @@ stops it prompting for the read-only commands and asks it to pause on
 writes — optional, and yours to install
 ([why pythia does not](GUIDE.md#11-optional-claude-code-permission-settings)).
 
+On Codex, the same command writes the harness into `AGENTS.md` (loaded every
+session) and a session-start hook into `.codex/hooks.json`; approve previews in
+the terminal with `pythia approve <token>`, since Codex has no chat-mint.
+
 Per-group write policy, `.pythia/policy.json` (defaults shown):
 
 | Group | Default | Is rollback real? |

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/scripts/pythia_plsql.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ scripts/pythia_plsql.egg-info/entry_points.txt
 scripts/pythia_plsql.egg-info/requires.txt
 scripts/pythia_plsql.egg-info/top_level.txt
 skills/pythia-apply/SKILL.md
+skills/pythia-comment/SKILL.md
 skills/pythia-conventions/SKILL.md
 skills/pythia-explore/SKILL.md
 skills/pythia-explore/reference/data-dictionary.md

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/skills/pythia-apply/SKILL.md

@@ -10,8 +10,7 @@ description: Use when a PL/SQL change is ready to reach the database - applying
 **Phase:** Ask → Do — the preview is relayed and approved before the one write door opens
 
 DDL in Oracle commits itself, so the snapshot pythia takes before writing is
-the only undo there is — and for DML not even that. This skill exists so that
-net is always used, and used honestly.
+the only undo there is — for DML not even that. This skill is how it gets used.
 
 ## The Iron Law
 
@@ -54,20 +53,21 @@ confirms a number you already knew.
    warning, exactly as printed. The developer approves what they see, not
    your paraphrase.
 3. **Ask for approval — one question per token.** `pythia approve --card
-   <token>` prints the card; ask an `AskUserQuestion` whose text is that card
-   verbatim (header `pythia`; options exactly `Approve` / `Reject`, no
-   "(Recommended)"; up to four tokens per call). `Approve` mints the grant via
-   the hook. Anything else — `Reject`, free text, silence, an earlier preview's
-   yes — is not approval: stop and ask what should change. File changed → step 1.
-   No hook installed? Relay `pythia approve <token>` for their own terminal.
+   <token>` prints the card; the `AskUserQuestion` text is that card and
+   nothing else — no word before it, no translation after it, no framing of
+   your own. The hook compares question to card, mints nothing when they
+   differ, and by then the developer has already clicked. Put the explanation
+   in the option descriptions; the hook does not read those. Header `pythia`;
+   options exactly `Approve` / `Reject`, no "(Recommended)"; up to four tokens
+   per call. Anything but `Approve` is not approval: stop and ask what should
+   change. File changed → step 1. No hook (Codex, or none)? Relay `pythia approve <token>` in the terminal — Codex has no chat-mint.
 4. **Apply** by running the exact `then the agent:` line pythia printed. Two
    refusals are normal here, and neither is a malfunction:
    - *"no developer approval is on file"* — the answer was not `Approve`, or
      the hook is not installed. Say so and wait; retrying does not create it.
    - *"the confirmation token does not match"* — the file or the database
-     changed since the preview. Go back to step 1, never "retry". If the fresh
-     preview's before-side differs from what you last saw, say so: someone may
-     have changed the object on this shared database.
+     changed since the preview. Go back to step 1, never "retry"; the fresh
+     preview warns by itself when the object moved outside pythia.
 5. **Read the exit code — it is the verdict. Never through a pipe:**
    `apply … | tail` returns *tail's* code, always 0. Unpiped, or `${PIPESTATUS[0]}`.
 
@@ -135,7 +135,7 @@ affected count and up to ten rows, and `--confirm` refuses if that set moved.
 | "I'll restore quietly to clean up my mistake" | Restores are writes. Same gate, same visibility. |
 | "`$?` said 0 after I piped to tail" | That was tail's 0. Read pythia's own words, or its unpiped code. |
 | "I'll run approve myself to unblock this" | The developer's act. Console approve refuses you; the hook mints only from *their* answer. Routing around it is what this gate exists to stop. |
-| "I'll summarise the card so the question reads nicer" | The hook refuses a paraphrase — the developer must approve pythia's words, not yours. Paste the card verbatim. |
+| "I'll add a line of my own around the card" | Any added word voids it, and the refusal arrives after they have clicked. Explanation goes in the option description. |
 
 ## When NOT to use this skill
 

pythia_plsql-0.13.0/skills/pythia-comment/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pythia-comment
+description: Use when you are about to write or edit a comment in PL/SQL you are changing, or in a .sql deliverable headed for the database. One line, one fixed shape, and anything longer goes where it belongs instead. It fires on the act of commenting rather than on a request - catching yourself opening a second comment line above one statement is the trigger.
+---
+
+# Comments - one line, or somewhere else
+
+**Announce at start:** "Using pythia-comment — one line, date - author - what changed."
+
+**Phase:** Do — it applies while writing, before `pythia apply` sees the file
+
+A comment is the only part of a change no compiler checks and no test covers,
+so it is the part that rots. One line survives the next rewrite. A paragraph
+becomes a claim the next reader has to disprove before they can work.
+
+## The shape
+
+```sql
+-- 11/09/2026 - jdoe - source flag reads the mapping table, not the join
+```
+
+`date - author - what changed`, with the date as `DD/MM/YYYY`. The author is
+the developer's handle, never the agent's: the agent did not decide this, and
+a blame trail that names a tool is a dead end.
+
+`--` for PL/SQL and SQL. That is the whole surface this skill covers — what
+pythia applies.
+
+**ASCII only.** Parts of the chain around a .sql file still read it as ANSI,
+and a diacritic there becomes mojibake in something the database keeps
+forever. Vietnamese without diacritics is a house style for exactly this
+reason, and it is a fine one.
+
+## One line
+
+If it needs a second line, the comment is the wrong container. Move it:
+
+| What you were about to write | Where it goes |
+|---|---|
+| why this shape, and what breaks without it | the header block of the .sql deliverable |
+| a rule that must not regress | a test or verifier, as an assertion with a message |
+| the decision, and the alternatives you rejected | the spec, or the ticket |
+| what changed and why, for a reader of history | the commit message |
+| what the statement does | nowhere — the statement already says it |
+
+Comment only what the code cannot show: a trap, a decision, a why.
+
+## Do not
+
+- Multi-line explanatory blocks above one statement.
+- Banners, box drawing, `-- ==== section ====`.
+- Bullet lists, quoted error codes, revision archaeology inline.
+- Commented-out code kept as documentation. Delete it — the journal and the
+  VCS both remember, and neither of them lies about what is live.
+- Touching comments on code you are not changing. That is a different diff,
+  and it buries yours.
+
+## Before you finish
+
+Count the comment lines you added. More than one per statement is a rewrite,
+not a trim.
+
+Then confirm the comment actually reached the database. A comment is exactly
+the kind of line a second writer drops without noticing, and it costs nothing
+to check:
+
+```sql
+select count(*) from all_source
+ where owner = :owner and name = :name and text like :marker
+```
+
+The preview's *changed outside pythia* warning is the other half of that
+check — it fires when the object moved since pythia last wrote it.

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/skills/pythia-write/SKILL.md

@@ -42,7 +42,8 @@ existing ones — not to introduce a better style.
      `unistr('...')`, so the text survives every client/DB charset exactly.
 5. **Check yourself before handing off.** Reread against
    `reference/patterns.md` — cursor and bulk patterns, exception discipline,
-   bind variables, commit ownership.
+   bind variables, commit ownership. Every comment you wrote or touched goes
+   through `pythia-comment` — one line, or it belongs somewhere else.
 
 ## Scope is the developer's sentence, not yours
 

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/skills/using-pythia/SKILL.md

@@ -30,6 +30,7 @@ sessions drift: some ask, some silently decide.
 | "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` | |
+| about to write a comment in code you are changing | `pythia-comment` — one line, or it belongs somewhere else | |
 | an ORA-/PLS- error to investigate | `pythia-explore` (`errors`, `src`) | `pythia-review` |
 
 Priority when several apply: **process before construction** — spec before

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/tests/test_install.py

@@ -57,16 +57,27 @@ def test_missing_npx_falls_back_to_the_bundled_pack():
         (agents / "pythia-apply").mkdir()      # stale copy from 0.2.0-0.2.3
         (claude / "plsql-review").mkdir(parents=True)
         targets = pythia.copy_bundled_skills(td)
-        assert targets == [claude]
+        assert targets == [claude, agents]
         assert (claude / "pythia-apply" / "SKILL.md").is_file()
         assert (claude / "pythia-review" / "reference" / "antipatterns.md").is_file()
-        assert not (agents / "pythia-apply").exists()       # single copy
+        assert (agents / "pythia-apply" / "SKILL.md").is_file()   # Codex reads this
         assert (agents / "my-team-skill" / "SKILL.md").read_text(
             encoding="utf-8") == "x"                         # merge, not wipe
         assert not (claude / "plsql-review").exists()        # legacy cleaned
         pythia.copy_bundled_skills(td)                       # idempotent
 
 
+def test_fallback_serves_both_claude_and_codex():
+    """Claude reads .claude/skills; Codex reads .agents/skills. The no-Node
+    fallback must populate both, or a Codex user without Node gets nothing."""
+    with tempfile.TemporaryDirectory() as td:
+        base = pathlib.Path(td)
+        targets = pythia.copy_bundled_skills(td)
+        assert targets == [base / ".claude" / "skills", base / ".agents" / "skills"]
+        for root in targets:
+            assert (root / "pythia-apply" / "SKILL.md").is_file()
+
+
 def test_copy_survives_a_symlinked_destination():
     """`npx skills add` leaves .claude/skills/<name> as a symlink into
     .agents/skills/<name>. Copying through that link and then cleaning the
@@ -350,6 +361,97 @@ def test_global_install_wires_the_approve_hook_only():
         assert s["hooks"]["PostToolUse"] == pythia.CLAUDE_HOOKS["PostToolUse"]
 
 
+def test_cmd_install_serves_codex_in_the_project_scope():
+    """Project install writes the harness into AGENTS.md always, and the
+    session-start hook unless --no-hooks. (The .agents/skills copy is gated by
+    global_pack_present() — a machine with a global pack skips it — so that is
+    proven directly in test_fallback_serves_both_claude_and_codex, not here.)"""
+    import argparse
+    import contextlib
+    import io
+    old = os.environ.get("PATH")
+    os.environ["PATH"] = ""                     # no npx: bundled fallback
+    try:
+        for no_hooks in (False, True):
+            with tempfile.TemporaryDirectory() as td:
+                ns = argparse.Namespace(project_root=td, glob=False, source=None,
+                                        color=False, json=False, no_hooks=no_hooks)
+                with contextlib.redirect_stdout(io.StringIO()):
+                    pythia.cmd_install(None, None, ns)
+                base = pathlib.Path(td)
+                agents_md = base / "AGENTS.md"
+                assert agents_md.is_file()                        # always
+                assert pythia.BRIEF_GUIDE.rstrip() in agents_md.read_text(encoding="utf-8")
+                hooks = base / ".codex" / "hooks.json"
+                assert hooks.is_file() != no_hooks                # skipped iff --no-hooks
+    finally:
+        if old is not None:
+            os.environ["PATH"] = old
+
+
+# --- Codex: AGENTS.md harness (TP1) ------------------------------------------
+
+def test_agents_md_block_is_the_guide_verbatim():
+    block = pythia.agents_md_block()
+    assert block.startswith(pythia.AGENTS_BEGIN)
+    assert block.rstrip().endswith(pythia.AGENTS_END)
+    assert pythia.BRIEF_GUIDE.rstrip() in block          # one source, no drift
+    assert "pythia approve <token>" in block             # the Codex approval door
+
+
+def test_merge_agents_md_creates_updates_and_is_idempotent():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / "AGENTS.md"
+        p, action = pythia.merge_agents_md(path)
+        assert p == path and action == "created"
+        assert pythia.BRIEF_GUIDE.rstrip() in path.read_text(encoding="utf-8")
+        assert pythia.merge_agents_md(path)[1] == "unchanged"
+
+
+def test_merge_agents_md_preserves_the_developers_text():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / "AGENTS.md"
+        path.write_text("# House rules\n\nUse tabs.\n", encoding="utf-8")
+        pythia.merge_agents_md(path)
+        body = path.read_text(encoding="utf-8")
+        assert body.startswith("# House rules\n\nUse tabs.\n")   # kept, on top
+        assert pythia.AGENTS_BEGIN in body and pythia.BRIEF_GUIDE.rstrip() in body
+        pythia.merge_agents_md(path)                             # a stale block
+        assert path.read_text(encoding="utf-8").count(pythia.AGENTS_BEGIN) == 1
+
+
+# --- Codex: session-start hook (TP3) -----------------------------------------
+
+def test_merge_codex_hooks_creates_and_is_idempotent():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        p, added = pythia.merge_codex_hooks(path)
+        assert p == path and added == ["hooks.SessionStart"]
+        s = json.loads(path.read_text(encoding="utf-8"))
+        assert s["hooks"]["SessionStart"] == pythia.CODEX_HOOKS["SessionStart"]
+        assert pythia.merge_codex_hooks(path) == (path, [])
+
+
+def test_merge_codex_hooks_recognises_an_existing_spelling():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({"hooks": {"SessionStart": [
+            {"hooks": [{"type": "command",
+                        "command": "python3 -m pythia guide --brief"}]}]}}),
+            encoding="utf-8")
+        assert pythia.merge_codex_hooks(path) == (path, [])   # not doubled
+
+
+def test_merge_codex_hooks_refuses_a_file_it_cannot_parse():
+    with tempfile.TemporaryDirectory() as td:
+        path = pathlib.Path(td) / ".codex" / "hooks.json"
+        path.parent.mkdir(parents=True)
+        path.write_text("{not json", encoding="utf-8")
+        assert pythia.merge_codex_hooks(path) == (path, None)
+        assert path.read_text(encoding="utf-8") == "{not json"
+
+
 # Native paths: on POSIX ':' is the PATH separator and would cut a
 # Windows path in half, so these are built from os.sep.
 SCRIPTS = os.path.join(os.sep + 'opt', 'a', 'Scripts')

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/tests/test_phase3.py

@@ -249,7 +249,8 @@ OLD_SRC = "PACKAGE BODY pkg_order AS\n  old line;\nEND;\n"
 NEW_FILE = "CREATE OR REPLACE PACKAGE BODY pkg_order AS\n  new line;\nEND;\n/\n"
 
 
-def base_script(errors=(), invalid_after=None, db_source=OLD_SRC):
+def base_script(errors=(), invalid_after=None, db_source=OLD_SRC,
+                editionable="Y"):
     invalid_before = [("X_ALREADY_BROKEN", "PROCEDURE")]
     return {
         "from all_source": ([("TEXT",)], [(ln + "\n",) for ln in db_source.splitlines()]),
@@ -268,7 +269,8 @@ def base_script(errors=(), invalid_after=None, db_source=OLD_SRC):
         "from session_privs": ([("PRIVILEGE",)], []),
         "current_schema": ([("CURRENT_SCHEMA",)], [("APP",)]),
         # main-namespace occupants of the target name (type-conflict check)
-        "object_name = upper(:n)": ([("OBJECT_TYPE",)], [("PACKAGE BODY",)]),
+        "object_name = upper(:n)": ([("OBJECT_TYPE", "EDITIONABLE")],
+                                    [("PACKAGE BODY", editionable)]),
     }
 
 
@@ -447,6 +449,87 @@ def test_insert_needs_no_row_set():
         assert pythia.read_journal_entry(td, entry)["meta"]["row_set"] is None
 
 
+def test_reconcile_editionable_matches_the_database():
+    """ALL_SOURCE stores no CREATE header, so a body read back with `src`
+    comes back bare and the keyword is the easiest thing in Oracle to lose.
+    Oracle will not change the property through CREATE OR REPLACE, so the
+    statement has to agree with the object before it runs."""
+    r = pythia.reconcile_editionable
+    bare = "CREATE OR REPLACE PROCEDURE p AS BEGIN NULL; END;"
+    non = "CREATE OR REPLACE NONEDITIONABLE PROCEDURE p AS BEGIN NULL; END;"
+    stmt, note = r(bare, "N")
+    assert stmt == non and "NONEDITIONABLE" in note
+    stmt, note = r(non, "Y")
+    assert stmt == bare and "NONEDITIONABLE" in note
+    # already agreed: untouched, and nothing to announce
+    assert r(non, "N") == (non, None)
+    assert r(bare, "Y") == (bare, None)
+    # no property to match: a new object, or a type that cannot be editioned
+    assert r(bare, None) == (bare, None)
+    # the old misspelling is not the property Oracle holds either
+    stmt, _ = r("create or replace NOEDITIONABLE procedure p as begin null; end;", "N")
+    assert stmt.startswith("create or replace NONEDITIONABLE ")
+    # leading comments keep their place
+    stmt, _ = r("-- header\ncreate or replace procedure p as begin null; end;", "N")
+    assert stmt.startswith("-- header\ncreate or replace NONEDITIONABLE ")
+
+
+def test_apply_writes_the_editionable_keyword_the_database_holds():
+    """The whole point is that ORA-38824 never reaches the developer: they
+    approved a preview, and the write has to be able to succeed."""
+    with tempfile.TemporaryDirectory() as td:
+        tok = pythia.apply_token("PACKAGE BODY", "PKG_ORDER", NEW_FILE, OLD_SRC)
+        pythia.mint_grant(td, tok, "DEV")
+        conn = FakeConn(base_script(editionable="N"))
+        code = pythia.run_apply(conn, "APP", apply_ns(td, confirm=tok), NEW_FILE)
+        assert code == 0
+        ddl = wrote_ddl(conn)
+        assert len(ddl) == 1 and ddl[0].lstrip().upper().startswith(
+            "CREATE OR REPLACE NONEDITIONABLE PACKAGE BODY"), ddl
+        # the journal records what ran, so the undo keeps the property too
+        e = pythia.read_journal_entry(td, pythia.list_journal_entries(td)[0])
+        assert "NONEDITIONABLE" in e["after"]
+        assert e["restore"].upper().startswith("CREATE OR REPLACE NONEDITIONABLE")
+
+
+def test_drift_note_fires_only_when_the_object_moved():
+    """The field case: pythia wrote 118 lines, read them back two seconds
+    later, and eight minutes on the database held 117 — with no journal entry
+    in between. `src` was honest both times; nothing ever compared them."""
+    mine = "CREATE OR REPLACE PACKAGE BODY pkg_order AS\n  a;\n  b;\nEND;\n"
+    same = "PACKAGE BODY pkg_order AS\n  a;\n  b;\nEND;"
+    assert pythia.drift_note(same, mine, "E1") is None
+    # trailing whitespace is not drift
+    assert pythia.drift_note(same + "\n\n", mine, "E1") is None
+    assert pythia.drift_note(same.replace("\n", "\r\n"), mine, "E1") is None
+    # a line gone is
+    note = pythia.drift_note("PACKAGE BODY pkg_order AS\n  a;\nEND;", mine, "E1")
+    assert note and "E1" in note and "1 line" in note
+    # nothing to compare against
+    assert pythia.drift_note(same, "", "E1") is None
+    assert pythia.drift_note(same, None, None) is None
+
+
+def test_preview_warns_when_the_object_changed_outside_pythia():
+    with tempfile.TemporaryDirectory() as td:
+        # pythia applied this text once
+        pythia.write_journal_entry(
+            td, "PACKAGE BODY", "PKG_ORDER", "older\n",
+            "CREATE OR REPLACE " + OLD_SRC,
+            {"token": "aaaaaa", "connection": "DEV", "schema": "APP",
+             "group": "plsql_source", "applied": True})
+        # ...and the database now holds something else
+        moved = OLD_SRC.replace("  old line;\n", "")
+        import contextlib
+        import io
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            pythia.run_apply(FakeConn(base_script(db_source=moved)), "APP",
+                             apply_ns(td), NEW_FILE)
+        out = buf.getvalue()
+        assert "outside pythia" in out and "1 line" in out, out
+
+
 def test_apply_preview_writes_nothing_and_gives_token():
     with tempfile.TemporaryDirectory() as td:
         conn = FakeConn(base_script())
@@ -473,6 +556,45 @@ def test_apply_correct_token_writes_and_verifies_clean():
         assert e["meta"]["applied"] is True
 
 
+class ExplodingConn(FakeConn):
+    """The driver refuses the write. ORA-38824 on an editions-enabled schema
+    is the case that prompted this: by the time it lands, the preview and
+    "Snapshot saved" have already printed, so the run reads like a success."""
+
+    def __init__(self, script, error="ORA-38824: cannot change the EDITIONABLE "
+                                     "property of an existing object"):
+        super().__init__(script)
+        self.error = error
+
+    def cursor(self):
+        cur = super().cursor()
+        passthrough = cur.execute
+
+        def execute(sql, binds=None):
+            if sql.lstrip().lower().startswith("create"):
+                raise RuntimeError(self.error)
+            return passthrough(sql, binds)
+
+        cur.execute = execute
+        return cur
+
+
+def test_failed_apply_ends_in_a_verdict_and_keeps_the_approval():
+    """A write that the driver refused must not read like one that landed:
+    the last word is the failure, and it says nothing was written."""
+    with tempfile.TemporaryDirectory() as td:
+        tok = pythia.apply_token("PACKAGE BODY", "PKG_ORDER", NEW_FILE, OLD_SRC)
+        pythia.mint_grant(td, tok, "DEV")
+        conn = ExplodingConn(base_script())
+        expect_exit(lambda: pythia.run_apply(conn, "APP", apply_ns(td, confirm=tok),
+                                             NEW_FILE),
+                    "failed", "nothing was written", "ORA-38824")
+        eid = pythia.list_journal_entries(td)[0]
+        assert pythia.read_journal_entry(td, eid)["meta"]["applied"] is False
+        # one approval, one write — and there was no write, so it still stands
+        assert pythia.read_grant(td, tok)["used_at"] is None
+
+
 def test_apply_stale_token_refused():
     with tempfile.TemporaryDirectory() as td:
         tok = pythia.apply_token("PACKAGE BODY", "PKG_ORDER", "something else", OLD_SRC)
@@ -538,7 +660,7 @@ def test_apply_snapshot_survives_failed_execute():
         conn = Exploding(base_script())
         try:
             pythia.run_apply(conn, "APP", apply_ns(td, confirm=tok), NEW_FILE)
-        except RuntimeError:
+        except SystemExit:          # the driver error, now a closing verdict
             pass
         ids = pythia.list_journal_entries(td)
         assert len(ids) == 1                              # snapshot was already on disk
@@ -1518,7 +1640,9 @@ def test_apply_previews_a_noneditionable_object_end_to_end():
         f.write_text(src, encoding="utf-8")
         buf = io.StringIO()
         with contextlib.redirect_stdout(buf):
-            pythia.cmd_apply(FakeConn(base_script()), "APP",
+            # the object really is NONEDITIONABLE in the database, which is
+            # what makes the keyword in the file the right one
+            pythia.cmd_apply(FakeConn(base_script(editionable="N")), "APP",
                              apply_ns(td, file=str(f)))
         out = buf.getvalue()
         assert "more than one statement" not in out

{pythia_plsql-0.11.2 → pythia_plsql-0.13.0}/tests/test_phase5.py

@@ -13,7 +13,7 @@ SKILLS = ROOT / "skills"
 EXPECTED = {"pythia-setup", "pythia-explore", "pythia-impact",
             "pythia-write", "pythia-apply", "pythia-review",
             "pythia-skill-author", "pythia-conventions", "pythia-spec",
-            "using-pythia"}
+            "pythia-comment", "using-pythia"}
 
 # spec: SKILL.md under 150 lines, detail pushed to reference/
 MAX_LINES = 150
@@ -153,7 +153,7 @@ def test_no_manifest_hardcodes_a_stale_skill_count():
     so the check is: no manifest states a number the code can disprove."""
     import json
     n = len(EXPECTED)
-    words = {7: "seven", 8: "eight", 9: "nine"}
+    words = {7: "seven", 8: "eight", 9: "nine", 10: "ten", 11: "eleven"}
     stale = [w for k, w in words.items() if k != n]
     for rel in (".claude-plugin/marketplace.json", "npm/package.json",
                 "npm/README.md"):