pythia-plsql 0.4.9__tar.gz → 0.5.0__tar.gz

{pythia_plsql-0.4.9/scripts/pythia_plsql.egg-info → pythia_plsql-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.9
+Version: 0.5.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
@@ -178,13 +178,13 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 ## Skills
 
-Seven skills teach the agent the workflow — superpowers-style gates, not suggestions:
+Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (impact **before** any change) ·
-`pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate: the
-developer sees the preview and approves in chat before anything is written) ·
-`pythia-review` (seven antipatterns) · `pythia-skill-author` (capture *your team's*
-workflow as a new skill, mined from the live schema).
+`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-skill-author` (capture your team's workflow as a skill).
 
 ## Compatibility
 

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/README.md

@@ -164,13 +164,13 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 ## Skills
 
-Seven skills teach the agent the workflow — superpowers-style gates, not suggestions:
+Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (impact **before** any change) ·
-`pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate: the
-developer sees the preview and approves in chat before anything is written) ·
-`pythia-review` (seven antipatterns) · `pythia-skill-author` (capture *your team's*
-workflow as a new skill, mined from the live schema).
+`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-skill-author` (capture your team's workflow as a skill).
 
 ## Compatibility
 

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.4.9"
+version = "0.5.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.5.0/queries/object-names.sql

@@ -0,0 +1,11 @@
+-- Purpose: every object name in the schema with its type, for measuring how
+--          well a naming pattern describes what is actually there. Derived
+--          patterns are guesses until the schema agrees with them.
+-- Binds:   :s  schema (object owner)
+-- Returns: OBJECT_TYPE, OBJECT_NAME
+select object_type,
+       object_name
+  from all_objects
+ where owner = :s
+   and object_type not in ('INDEX', 'LOB', 'TABLE PARTITION', 'INDEX PARTITION')
+ order by object_type, object_name

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/scripts/pythia.py

@@ -85,6 +85,7 @@ QUERY_BINDS = {
     "object-source.sql": {"s", "n", "t"},
     "session-privileges.sql": set(),
     "name-occupants.sql": {"s", "n"},
+    "object-names.sql": {"s"},
 }
 
 
@@ -1332,6 +1333,199 @@ def cmd_plscope(conn, schema, ns):
         emit_table(ns, stmt_cols, *clip(stmt_rows, ns.limit))
 
 
+AGENT_USER_SQL = """\
+-- Least-privilege agent credential for schema {owner} — run as a DBA.
+-- Proxy authentication: the agent logs in with its OWN password but works
+-- inside {owner}; it never learns the owner password, owns nothing, and
+-- revocation is one statement. Deliberately absent: DBA, RESOURCE, ANY
+-- privileges, utility grants — the agent needs none of them to develop
+-- PL/SQL, and every extra grant widens the blast radius.
+
+{create_line}
+GRANT CREATE SESSION TO {agent};
+ALTER USER {owner} GRANT CONNECT THROUGH {agent};
+
+-- Cut the agent off later (owner untouched):
+--   ALTER USER {owner} REVOKE CONNECT THROUGH {agent};
+-- Fresh owner schema instead? See examples/agent-user-setup.example.sql.
+"""
+
+
+CONVENTIONS_TEMPLATE = """{
+  "naming": {
+    "TABLE": "^T_[A-Z0-9_]+$",
+    "PROCEDURE": "^P_[A-Z0-9_]+$",
+    "FUNCTION": "^F_[A-Z0-9_]+$",
+    "PACKAGE": "^PKG_[A-Z0-9_]+$",
+    "SEQUENCE": "^S_[A-Z0-9_]+$",
+    "TRIGGER": "^TRG_[A-Z0-9_]+$"
+  }
+}
+"""
+
+CONVENTIONS_PROSE_TEMPLATE = """# Project conventions
+
+Rules for anyone — human or agent — writing PL/SQL in this schema. Agents are
+told to read this before writing, and it outranks the generic patterns the
+skill pack ships with.
+
+`conventions.json` next to this file holds the naming patterns as regexes;
+every `pythia apply` preview warns when a new object's name does not match.
+Keep the two in step: this file explains, that file enforces.
+
+## Naming
+
+Replace the patterns in `conventions.json` with yours, then describe them
+here so the reasoning survives. `pythia similar <A_TYPICAL_NAME>` shows what
+the schema already does — copy that rather than inventing a scheme.
+
+| Kind | Rule | Example |
+|---|---|---|
+| Table | | |
+| Procedure | | |
+| Function | | |
+
+## Rules that carry a cost when broken
+
+State the consequence, not just the rule — a rule with a named cost gets
+followed. For example: which parameter prefixes the calling layer depends on,
+which column every query must filter by, where a transaction may commit.
+
+| Rule | Cost of breaking it |
+|---|---|
+| | |
+
+## Known exceptions
+
+Objects that break the pattern on purpose, and why renaming them is worse
+than the warning they produce on every apply.
+"""
+
+
+SCAN_SHARE = 0.9        # a token set must cover this much to count as the rule
+SCAN_MAX_ALTERNATIVES = 12
+
+
+def _dominant(tokens_at_position, total):
+    """The smallest set of tokens covering SCAN_SHARE of the names, or None.
+
+    A set only counts as a rule when its tokens repeat. As many distinct
+    tokens as there are names is a list of names, not a convention — and
+    writing that down produces a pattern that fails on the next object
+    anyone adds.
+    """
+    limit = min(SCAN_MAX_ALTERNATIVES, max(1, total // 2))
+    counts = {}
+    for tok in tokens_at_position:
+        counts[tok] = counts.get(tok, 0) + 1
+    ranked = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    picked, covered = [], 0
+    for tok, n in ranked:
+        if len(picked) >= limit:
+            return None
+        picked.append(tok)
+        covered += n
+        if covered >= total * SCAN_SHARE:
+            return picked
+    return None
+
+
+def propose_pattern(names, min_names=3):
+    """Read the shape off real names: a dominant first token, and a dominant
+    last token when there is one. Returns None when the names share no
+    structure — configuring nothing beats configuring a rule that means
+    nothing."""
+    names = [str(n).upper() for n in names if n]
+    if len(names) < min_names:
+        return None
+    split = [n.split("_") for n in names]
+    if sum(1 for p in split if len(p) >= 2) < len(names) * SCAN_SHARE:
+        return None                       # mostly single-word names: no shape
+    heads = _dominant([p[0] for p in split], len(names))
+    if not heads:
+        return None
+    head = heads[0] if len(heads) == 1 else "(" + "|".join(sorted(heads)) + ")"
+    # the suffixed form needs a third token to sit in; without one for most
+    # names, an alternation at the end would exclude the short ones
+    if sum(1 for p in split if len(p) >= 3) >= len(names) * SCAN_SHARE:
+        tails = _dominant([p[-1] for p in split], len(names))
+        if tails:
+            tail = (tails[0] if len(tails) == 1
+                    else "(" + "|".join(sorted(tails)) + ")")
+            return f"^{head}_[A-Z0-9_]+_{tail}$"
+    return f"^{head}_[A-Z0-9_]+$"
+
+
+def scan_conventions(objects):
+    """Propose a naming block from the schema itself. The tool tokenizes the
+    names so the agent never has to read thousands of them into context; the
+    developer's own document decides what is kept."""
+    by_type = {}
+    for otype, name in objects:
+        by_type.setdefault(str(otype).upper(), []).append(name)
+    naming = {}
+    for otype, names in sorted(by_type.items()):
+        pattern = propose_pattern(names)
+        if pattern:
+            naming[otype] = pattern
+    return {"naming": naming}
+
+
+def pattern_coverage(conv, objects):
+    """How well each configured pattern describes the names already in the
+    schema. objects: (object_type, object_name).
+
+    A pattern derived from a document, or from reading a few examples, is a
+    guess. Measuring it against every real name turns the guess into a number
+    and names the exceptions — which is the difference between conventions
+    that hold and conventions that produce a warning on every apply.
+    """
+    patterns = (conv or {}).get("naming") or {}
+    out = {}
+    for otype, pattern in patterns.items():
+        rx = re.compile(pattern)
+        names = sorted(n for t, n in objects if str(t).upper() == otype.upper())
+        misses = [n for n in names if not rx.match(str(n))]
+        out[otype] = {"pattern": pattern, "total": len(names),
+                      "matched": len(names) - len(misses), "misses": misses}
+    return out
+
+
+def coverage_verdict(matched, total):
+    """Read the numbers so nobody has to. A low rate means the pattern is
+    wrong far more often than it means the schema is."""
+    if total == 0:
+        return "nothing of that type in this schema — untested rule"
+    if matched == total:
+        return "every name matches"
+    pct = round(100 * matched / total)
+    if pct >= 90:
+        return f"{pct}% match — the rest are worth listing as exceptions"
+    return (f"only {pct}% match — the derived pattern is probably wrong; "
+            "widen it or split it before writing it down")
+
+
+def scaffold_conventions(root):
+    """Write the conventions pair, skipping anything that already exists.
+    Returns the paths actually created.
+
+    The docs used to say "copy examples/conventions.example.json", which is
+    no help to anyone who installed the wheel: there is no examples directory
+    there. The tool carries the templates instead.
+    """
+    d = pathlib.Path(root) / CONFIG_DIR
+    made = []
+    for name, body in (("conventions.json", CONVENTIONS_TEMPLATE),
+                       ("conventions.md", CONVENTIONS_PROSE_TEMPLATE)):
+        path = d / name
+        if path.is_file():
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body, encoding="utf-8")
+        made.append(path)
+    return made
+
+
 def load_conventions(root):
     """Project house style from .pythia/conventions.json — the machine half of
     the customization surface (the prose half is conventions.md, for agents).
@@ -1789,43 +1983,78 @@ def cmd_journal(conn, schema, ns):
         sys.exit("unreachable: restore is dispatched with a connection in main")
 
 
+def _schema_objects(conn, schema):
+    _, rows = run_query(conn, load_query("object-names.sql"), {"s": schema})
+    return [(r[0], r[1]) for r in rows]
+
+
 def cmd_conventions(conn, schema, ns):
-    conv = load_conventions(ns.project_root)
+    root = ns.project_root
+    if getattr(ns, "init", False):
+        made = scaffold_conventions(root)
+        for path in made:
+            print(f"Created {path}")
+        if not made:
+            print(f"Both files already exist in "
+                  f"{pathlib.Path(root) / CONFIG_DIR} — left untouched.")
+        else:
+            print(NL + "Edit the patterns to match this schema — "
+                  f"`{invocation()} conventions --scan` reads them off it.")
+        return
+
+    if getattr(ns, "scan", False):
+        proposed = scan_conventions(_schema_objects(conn, schema))
+        if ns.json:
+            print(json.dumps(proposed, indent=2))
+            return
+        print(f"Patterns read off {schema}. Review against your own standards, "
+              "then save as" + NL + f"{CONFIG_DIR}/conventions.json:" + NL)
+        print(json.dumps(proposed, indent=2))
+        if not proposed["naming"]:
+            print(NL + "Nothing proposed: too few objects, or names with no "
+                  "shared shape.")
+        return
+
+    if getattr(ns, "check", False):
+        conv = load_conventions(root)
+        if not conv:
+            sys.exit(f"No conventions to check. {invocation()} conventions "
+                     "--scan proposes some from this schema.")
+        cov = pattern_coverage(conv, _schema_objects(conn, schema))
+        if ns.json:
+            print(json.dumps(cov, indent=2))
+            return
+        worst = 0
+        for otype, s in sorted(cov.items()):
+            print(f"{otype:<14} {s['matched']}/{s['total']}  "
+                  f"{coverage_verdict(s['matched'], s['total'])}")
+            if s["misses"]:
+                shown, more = s["misses"][:8], len(s["misses"]) - 8
+                print("               not matching: " + ", ".join(shown)
+                      + (f", +{more} more" if more > 0 else ""))
+                worst = max(worst, len(s["misses"]))
+        if worst:
+            print(NL + "Every name above warns on `apply`. Widen the pattern "
+                  "if it is the rule that is wrong," + NL + "or record them in "
+                  "conventions.md as deliberate exceptions.")
+        return
+
+    conv = load_conventions(root)
     if ns.json:
         print(json.dumps(conv or {}))
         return
     if not conv:
         print("No project conventions configured.")
-        print(f"Create {pathlib.Path(ns.project_root) / CONFIG_DIR / 'conventions.json'} "
-              "(see examples/conventions.example.json) and apply previews will "
-              "warn when a new object's name drifts from your patterns.\n"
-              "Put the prose rules in conventions.md next to it for your agents.")
+        print(f"  {invocation()} conventions --scan   read patterns off this schema")
+        print(f"  {invocation()} conventions --init   start from a blank template")
         return
     print("Naming patterns — apply previews warn when a name drifts:")
     for otype, pattern in conv.get("naming", {}).items():
         print(f"  {otype:<13} {pattern}")
-    md = pathlib.Path(ns.project_root) / CONFIG_DIR / "conventions.md"
+    md = pathlib.Path(root) / CONFIG_DIR / "conventions.md"
     if md.is_file():
-        print(f"\nProse rules for agents: {md}")
-
-
-AGENT_USER_SQL = """\
--- Least-privilege agent credential for schema {owner} — run as a DBA.
--- Proxy authentication: the agent logs in with its OWN password but works
--- inside {owner}; it never learns the owner password, owns nothing, and
--- revocation is one statement. Deliberately absent: DBA, RESOURCE, ANY
--- privileges, utility grants — the agent needs none of them to develop
--- PL/SQL, and every extra grant widens the blast radius.
-
-{create_line}
-GRANT CREATE SESSION TO {agent};
-ALTER USER {owner} GRANT CONNECT THROUGH {agent};
-
--- Cut the agent off later (owner untouched):
---   ALTER USER {owner} REVOKE CONNECT THROUGH {agent};
--- Fresh owner schema instead? See examples/agent-user-setup.example.sql.
-"""
-
+        print(NL + f"Prose rules for agents: {md}")
+    print(f"{NL}Measure them against the schema: {invocation()} conventions --check")
 
 def agent_user_sql(owner, agent, password, exists):
     """exists True: the user is already there — CREATE would be ORA-01920,
@@ -2156,7 +2385,7 @@ COMMANDS = {"check": cmd_check, "ls": cmd_ls, "src": cmd_src, "args": cmd_args,
             "unistr": cmd_unistr, "agent-user": cmd_agent_user,
             "history": cmd_history}
 
-NO_DB_COMMANDS = {"policy", "journal", "conventions", "install", "unistr",
+NO_DB_COMMANDS = {"policy", "journal", "install", "unistr",
                   "history"}
 
 
@@ -2254,8 +2483,17 @@ def build_parser():
                    help="apply without stopping; the full preview still prints and journals")
     s.add_argument("--depth", type=int, default=3,
                    help="impact depth for the preview (default 3)")
-    sub.add_parser("conventions", parents=[common()],
+    s = sub.add_parser("conventions", parents=[common()],
                    help="show the project's house-style naming patterns")
+    s.add_argument("--init", action="store_true",
+                   help="write starter conventions.json and conventions.md "
+                        "into .pythia/ (never overwrites)")
+    s.add_argument("--scan", action="store_true",
+                   help="read naming patterns off the live schema and "
+                        "propose them (needs a connection)")
+    s.add_argument("--check", action="store_true",
+                   help="measure the configured patterns against the "
+                        "schema: coverage and the names that miss")
     s = sub.add_parser("agent-user", parents=[common()],
                        help="SQL for a least-privilege proxy agent user; "
                             "--save adds it to connections.json")
@@ -2314,7 +2552,11 @@ def main(argv=None):
     cwd = pathlib.Path.cwd()
     cfg, root = find_config(cwd, os.environ)
     ns.project_root = root if root is not None else cwd
-    if ns.command in NO_DB_COMMANDS and not (
+    # conventions reads the schema only for --scan and --check; listing what
+    # is configured, or writing the template, must work with no database at all
+    offline_conventions = ns.command == "conventions" and not (
+        getattr(ns, "scan", False) or getattr(ns, "check", False))
+    if (ns.command in NO_DB_COMMANDS or offline_conventions) and not (
             ns.command == "journal" and getattr(ns, "action", "") == "restore"):
         COMMANDS[ns.command](None, None, ns)
         return

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.9
+Version: 0.5.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
@@ -178,13 +178,13 @@ it audits every interaction in `DBTOOLS$MCP_LOG`. **Writes never do** — only
 
 ## Skills
 
-Seven skills teach the agent the workflow — superpowers-style gates, not suggestions:
+Eight skills teach the agent the workflow — gates, not suggestions:
 
-`pythia-setup` · `pythia-explore` · `pythia-impact` (impact **before** any change) ·
-`pythia-write` (copy the codebase's conventions) · `pythia-apply` (the gate: the
-developer sees the preview and approves in chat before anything is written) ·
-`pythia-review` (seven antipatterns) · `pythia-skill-author` (capture *your team's*
-workflow as a new skill, mined from the live schema).
+`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-skill-author` (capture your team's workflow as a skill).
 
 ## Compatibility
 

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/scripts/pythia_plsql.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ queries/dependencies.sql
 queries/impact.sql
 queries/invalid-objects.sql
 queries/name-occupants.sql
+queries/object-names.sql
 queries/object-source.sql
 queries/plscope-enabled.sql
 queries/plscope-statements.sql
@@ -21,6 +22,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-conventions/SKILL.md
 skills/pythia-explore/SKILL.md
 skills/pythia-explore/reference/data-dictionary.md
 skills/pythia-impact/SKILL.md

pythia_plsql-0.5.0/skills/pythia-conventions/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: pythia-conventions
+description: Use when a project's house style already exists somewhere and needs to become something the tooling can check - the developer hands over a standards document, points at an older or company base schema whose naming should be adopted, says "our team does it this way", or asks why an apply preview warned about a name. Derives the patterns from the real schema, verifies them against it, and writes .pythia/conventions.json and conventions.md.
+---
+
+# Adopting a Project's Conventions
+
+**Announce at start:** "Using pythia-conventions — I'll read the patterns off the schema first."
+
+Conventions already exist in every mature schema. They are in the object
+names, in a standards document, or in a senior developer's head. This turns
+them into two files: patterns the tool checks on every write, and prose every
+future agent session reads before writing.
+
+## The Iron Law
+
+```
+NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT
+```
+
+A pattern that does not match the objects already there is not a convention.
+It is a guess that will warn on every apply until someone deletes it.
+
+## The Workflow
+
+1. **Read the shape off the database, not off your memory of it.**
+
+   ```bash
+   pythia conventions --scan
+   ```
+
+   It tokenises every object name and proposes a pattern per type. Do this
+   even when a document exists — and never page through thousands of names
+   yourself: that is what the command is for, and your context is better
+   spent elsewhere.
+
+2. **Read the developer's document, if there is one.** A base system's
+   standards, a wiki page, an older project's rules. Look for what a regex
+   cannot hold: parameter prefixes a calling layer depends on, a column every
+   query must filter by, where a transaction may commit, which date or money
+   representation is canonical. Those go in the prose half.
+
+3. **Reconcile, and say so when the two disagree.** The document states
+   intent; the schema states fact. A rule in the document that the schema
+   contradicts is one of three things — a rule nobody follows, a rule for new
+   code only, or drift worth reporting. Ask the developer which; do not
+   silently pick.
+
+4. **Write `.pythia/conventions.json`.** Start from the scan output, narrowed
+   by the document. `pythia conventions --init` writes a blank pair if you
+   want the skeleton first.
+
+5. **Verify — this step is the point of the skill.**
+
+   ```bash
+   pythia conventions --check
+   ```
+
+   It reports coverage per type and names what misses.
+
+   | Result | What it means |
+   |---|---|
+   | every name matches | the pattern is real; keep it |
+   | ~90%+ with a handful of misses | genuine exceptions — list them in step 6 |
+   | below 90% | **the pattern is wrong**, not the schema; widen or split it, then check again |
+   | nothing of that type | an untested rule; keep it only if new objects of that type are expected |
+
+6. **Record the exceptions, with their reason.** Objects that break the rule
+   on purpose — ported names from a base platform, legacy entry points whose
+   names are part of a public surface. Say why renaming would cost more than
+   the warning. An unexplained exception gets "fixed" by the next person.
+
+7. **Write `.pythia/conventions.md`.** For every rule, state **the cost of
+   breaking it**, not just the rule. "Parameter prefixes must be `b_`/`a_`"
+   is ignorable; "the calling layer binds by prefix, so a wrong one silently
+   unbinds the field" is not. Rules with named consequences get followed.
+
+## Adopting from an older base the team already runs
+
+Point the connection at that schema and run steps 1 and 2 there — a base
+system with thousands of objects is the most reliable statement of a house
+style that exists, far better than anyone's recollection of it. Then switch
+the connection to the new project and run `--check`: coverage tells you how
+much of the base style the new schema has actually inherited.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "I'll write the patterns from the document alone" | Documents describe intent; schemas record what happened. Scan first. |
+| "80% coverage is good enough" | Every miss warns on every apply. Fix the pattern or record the exception. |
+| "I'll read all the object names to work it out" | `--scan` does that without spending your context. |
+| "The schema disagrees, so the document is wrong" | It may be a new-code-only rule. Ask. |
+| "A rule per line is enough" | A rule without its cost is a rule people skip. |
+
+## When NOT to use this skill
+
+- Writing one object in an existing style → `pythia-write`, which reads these
+  files and uses `similar` for the details.
+- Capturing a *workflow* with steps and gates → `pythia-skill-author`.
+  Naming and style belong here; procedures belong in a skill.

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/skills/pythia-setup/SKILL.md

@@ -75,6 +75,29 @@ server: command `sql -mcp`. Example client config:
   `V$SESSION.ACTION` the LLM's name; generated SQL carries an
   `/* LLM in use */` comment.
 
+## 4. What lives in `.pythia/`, and what creates it
+
+Only `connections.json` is written by `install`. The rest appear when you ask
+for them, so an empty `.pythia/` is a working one — nothing here is missing
+until you want it.
+
+| File | Created by | What it does |
+|---|---|---|
+| `connections.json` | `pythia install` | Where to connect. Holds credentials; gitignored. |
+| `journal/` | first write or snapshot | Every captured version, with a runnable rollback per entry. |
+| `conventions.json` | `pythia conventions --init` | Naming patterns per object type. Every apply preview warns when a new name drifts. |
+| `conventions.md` | `pythia conventions --init` | The house rules in prose. **`pythia-write` reads this before writing anything**, and it outranks the generic patterns this pack ships with. |
+| `policy.json` | `pythia policy set <group> <value>` | Pins the write policy. Absent means the built-in defaults, which are already the safe ones. |
+| `settings.json` | you, by hand | Optional switches, e.g. `{"auto_snapshot": false}`. |
+
+**Capturing a team's house style is the highest-value optional step.** Run
+`pythia conventions --init`, then replace the placeholder patterns with the
+real ones — `pythia similar <A_TYPICAL_NAME>` shows what the schema already
+does, which beats inventing a scheme. Fill in `conventions.md` with the rules
+that carry a cost when broken, and say what the cost is; a rule with a named
+consequence gets followed. Commit both files to the project repo so the whole
+team and every agent session works from the same rules.
+
 ## Done when
 
 - `pythia check` connects, shows the right schema, and prints **no**

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/skills/pythia-write/SKILL.md

@@ -9,7 +9,9 @@ description: Use when writing or modifying PL/SQL source - a procedure, function
 
 **Before anything:** if the project has `.pythia/conventions.md`, read it —
 house rules there outrank every generic pattern below, and
-`pythia conventions` shows the naming patterns the apply preview will check.
+`pythia conventions` shows the naming patterns the apply preview will check. If the project has none and the developer
+describes a house style, offer `pythia conventions --init` — captured once,
+it applies to every future session instead of being re-explained.
 
 A codebase with thousands of procedures has already decided how procedures
 look. Your job is to write one that a maintainer cannot tell from the

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/tests/test_install.py

@@ -7,6 +7,7 @@ Run: python tests/test_install.py
 import json
 import os
 import pathlib
+import re
 import sys
 import tempfile
 
@@ -325,6 +326,28 @@ def test_long_path_is_flagged_before_it_silently_truncates():
     assert "duplicate" in w.lower()      # names the usual cause
 
 
+def test_conventions_init_writes_both_halves_and_never_clobbers():
+    """Telling a pip user to copy examples/conventions.example.json is no help:
+    the wheel does not ship an examples directory. The tool writes the pair."""
+    import json
+    with tempfile.TemporaryDirectory() as td:
+        made = pythia.scaffold_conventions(td)
+        d = pathlib.Path(td) / ".pythia"
+        assert sorted(p.name for p in made) == ["conventions.json",
+                                                "conventions.md"]
+        rules = json.loads((d / "conventions.json").read_text(encoding="utf-8"))
+        assert "naming" in rules and rules["naming"]        # usable as written
+        for otype, pattern in rules["naming"].items():
+            re.compile(pattern)                             # every one valid
+        assert pythia.load_conventions(td) is not None      # accepted by the loader
+        prose = (d / "conventions.md").read_text(encoding="utf-8")
+        assert "conventions.json" in prose                  # the halves reference
+        # a second run leaves existing files alone
+        (d / "conventions.json").write_text('{"naming": {}}', encoding="utf-8")
+        assert pythia.scaffold_conventions(td) == []
+        assert (d / "conventions.json").read_text(encoding="utf-8") == '{"naming": {}}'
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/tests/test_phase2.py

@@ -114,6 +114,70 @@ def test_plscope_message_distinguishes_disabled_from_missing():
     assert "CALC_TAX" in missing
 
 
+def test_pattern_coverage_measures_patterns_against_real_names():
+    """A derived pattern is a guess until the schema agrees. Coverage turns
+    'I think procedures look like this' into a number, and names the
+    exceptions instead of leaving them to surface one apply at a time."""
+    conv = {"naming": {"PROCEDURE": "^P_[A-Z0-9_]+_(NH|LKE)$",
+                       "FUNCTION": "^F_[A-Z0-9_]+$"}}
+    objects = [("PROCEDURE", "P_ORDER_NH"), ("PROCEDURE", "P_ORDER_LKE"),
+               ("PROCEDURE", "LEGACY_THING"), ("FUNCTION", "F_TAX"),
+               ("TABLE", "T_ORDER")]          # no TABLE pattern: not reported
+    cov = pythia.pattern_coverage(conv, objects)
+    assert cov["PROCEDURE"]["matched"] == 2
+    assert cov["PROCEDURE"]["total"] == 3
+    assert cov["PROCEDURE"]["misses"] == ["LEGACY_THING"]
+    assert cov["FUNCTION"]["matched"] == 1 and cov["FUNCTION"]["misses"] == []
+    assert "TABLE" not in cov
+
+    # a pattern for a type the schema has none of is reported, not hidden:
+    # it is a rule nothing has tested yet
+    cov2 = pythia.pattern_coverage({"naming": {"TRIGGER": "^TRG_"}}, objects)
+    assert cov2["TRIGGER"]["total"] == 0
+
+
+def test_coverage_verdict_reads_the_numbers_for_you():
+    assert "every" in pythia.coverage_verdict(7, 7).lower()
+    poor = pythia.coverage_verdict(2, 10)
+    assert "20%" in poor and "derived" in poor.lower()   # suspect the pattern
+    assert "nothing of that type" in pythia.coverage_verdict(0, 0).lower()
+
+
+def test_propose_pattern_reads_the_shape_off_real_names():
+    """The tool tokenizes thousands of names so the agent does not have to
+    read them. Dominant first and last tokens become alternations."""
+    names = ["PHT_NSD_LKE", "PHT_NSD_CT", "PHT_NSD_NH",
+             "PBH_HD_LKE", "PBH_HD_CT", "PBH_HD_NH"]
+    p = pythia.propose_pattern(names)
+    import re
+    assert all(re.match(p, n) for n in names), p
+    assert "PBH" in p and "PHT" in p and "LKE" in p        # both ends captured
+
+    # no dominant suffix: leave the tail open rather than invent one
+    tables = ["HT_NSD", "HT_QUYEN", "HT_VAI_TRO", "HT_MA_BENH_VIEN"]
+    p2 = pythia.propose_pattern(tables)
+    assert all(re.match(p2, n) for n in tables), p2
+    assert p2.startswith("^HT_") and p2.endswith("$")
+
+    # nothing in common: say so with None rather than a pattern matching all
+    assert pythia.propose_pattern(["ALPHA", "B_TWO", "ZZZ_9"]) is None
+    assert pythia.propose_pattern([]) is None
+
+
+def test_scan_proposal_covers_what_it_proposes():
+    """Whatever it proposes must match the names it was derived from —
+    otherwise the very first check would contradict the scan."""
+    objects = [("PROCEDURE", "PHT_A_LKE"), ("PROCEDURE", "PHT_B_CT"),
+               ("PROCEDURE", "PHT_C_NH"),
+               ("TABLE", "HT_A"), ("TABLE", "HT_B"), ("TABLE", "HT_C"),
+               ("SEQUENCE", "SEQ_ONE")]      # too few to infer: left alone
+    conv = pythia.scan_conventions(objects)
+    cov = pythia.pattern_coverage(conv, objects)
+    for otype, stats in cov.items():
+        assert stats["misses"] == [], (otype, stats)
+    assert set(conv["naming"]) == {"PROCEDURE", "TABLE"}
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.4.9 → pythia_plsql-0.5.0}/tests/test_phase5.py

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