pythia-plsql 0.4.10__tar.gz → 0.6.0__tar.gz

{pythia_plsql-0.4.10/scripts/pythia_plsql.egg-info → pythia_plsql-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.10
+Version: 0.6.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
@@ -26,10 +26,16 @@ Dynamic: license-file
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 
-An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI coding
-agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills` supports).
-Explore schemas too big to dump, measure blast radius **before** touching anything,
-and land changes through a snapshot-verified write path that never lies about rollback.
+An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI
+coding agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills`
+supports).
+
+pythia is a **harness**: a book of working rules an agent studies and follows
+when it sits next to a developer. Not a chatbot, not an autopilot — a
+disciplined assistant with three properties a good one has: **knowledge** (it
+asks the live schema, never its memory of one), **judgment** (it measures
+before it proposes), and **obedience to rules it can recite** (gates it will
+quote back to you rather than quietly skip).
 
 ## Why ask the database instead of reading dumps
 
@@ -47,23 +53,63 @@ Code that "reads fine" against the dump references types and packages the dump n
 heard of. Every pythia command asks the live data dictionary instead — and every
 truncated output says so, so an agent never mistakes a partial answer for a full one.
 
-## How it works
+## The operating model: Learn → Ask → Do
 
-```
-developer chats with the agent
-        │
-skills/  teach the agent when to ask, when to stop, when to ask YOU
-        │
-pythia   CLI — expert queries, impact analysis, the six-step write path
-        │
-Oracle   data dictionary: ALL_SOURCE, ALL_DEPENDENCIES, ALL_ERRORS, PL/Scope
-```
+Give the agent a problem — "add a column and every procedure that maintains
+it", "why does this report double rows", "port this fix" — and the kit walks
+it through the same three movements a careful senior developer makes.
 
-The write path is the heart: **snapshot → impact → preview → apply → verify → report**.
-DDL self-commits in Oracle — the snapshot is the only real undo, so it always runs
-first and no flag can turn it off. A 6-hex token binds the write to exactly what was
-previewed; exit codes make honesty machine-readable
-(`0` clean · `1` refused · `3` **written but broken — never reported as success**).
+### 1 · Learn — understand before proposing
+
+The agent studies four things, in order, with tools instead of guesses:
+
+| It learns | How | Instead of |
+|---|---|---|
+| the problem's real shape | `deps`, `impact`, `plscope` — the exact dependency graph and usage sites | skimming code and hoping |
+| the schema's ground truth | `src`, `cols`, `args`, `ddl`, `errors` against the live database | trusting a dump that drifted |
+| the house style | `.pythia/conventions.md` + `conventions --scan/--check` — rules measured against real names | inventing a style per session |
+| how this codebase already solves it | `similar` — the neighbours to imitate | writing the first thing that compiles |
+
+Nothing in this phase writes. Reading is free, so the bar is: **no proposal
+before the blast radius is known** (`pythia-impact`'s iron law) and **no line
+written before the neighbours have been read** (`pythia-write`'s).
+
+### 2 · Ask — the questions are part of the method, not an interruption
+
+The kit makes the agent stop at exactly the moments where a human's judgment
+is the missing input, and forbids it to guess past them:
+
+- **Before any write**: the full preview — diff, dependents, warnings — is
+  relayed verbatim, and the agent waits for a real yes. A compliment is not a
+  yes. Silence is not a yes.
+- **When the blast radius is large**: ten or more dependents, or anything
+  cross-schema, goes to the developer *before code is written*, not after.
+- **When sources of truth disagree**: a standards document says one thing,
+  the schema does another — that gap is a question ("rule nobody follows,
+  new-code-only, or drift?"), never a silent pick.
+- **When something breaks**: exit 3 means *written but broken*. The agent
+  reports it exactly so, with the ready rollback — reporting success here is
+  the one sin the whole kit is built to prevent.
+- **When policy refuses**: the refusal is relayed as information, not routed
+  around.
+
+### 3 · Do — act inside a pipeline that cannot lie
+
+Only after Learn and Ask does anything touch the database, and then only
+through one door: **snapshot → impact → preview → token → apply → verify →
+report**. DDL self-commits in Oracle, so the snapshot is the only real undo —
+it runs first and no flag disables it. A content-bound token guarantees what
+lands is byte-for-byte what was approved. And the CLI enforces the gates
+itself: a headless agent cannot `--yes` its own writes or loosen policy —
+that takes a human at a real terminal.
+
+The same discipline holds when the *developer* does the work: `src` and
+`impact` silently snapshot what they read, so even a change made by hand in
+SQL Developer has a rollback file waiting (`history` lists them, drift is
+reported when source moved with no apply behind it).
+
+**Học – Hỏi – Làm** — Learn, Ask, Do. If the agent cannot show which phase it
+is in, it is doing none of them.
 
 ## Install
 
@@ -178,13 +224,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.10 → pythia_plsql-0.6.0}/README.md

@@ -12,10 +12,16 @@
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 
-An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI coding
-agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills` supports).
-Explore schemas too big to dump, measure blast radius **before** touching anything,
-and land changes through a snapshot-verified write path that never lies about rollback.
+An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI
+coding agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills`
+supports).
+
+pythia is a **harness**: a book of working rules an agent studies and follows
+when it sits next to a developer. Not a chatbot, not an autopilot — a
+disciplined assistant with three properties a good one has: **knowledge** (it
+asks the live schema, never its memory of one), **judgment** (it measures
+before it proposes), and **obedience to rules it can recite** (gates it will
+quote back to you rather than quietly skip).
 
 ## Why ask the database instead of reading dumps
 
@@ -33,23 +39,63 @@ Code that "reads fine" against the dump references types and packages the dump n
 heard of. Every pythia command asks the live data dictionary instead — and every
 truncated output says so, so an agent never mistakes a partial answer for a full one.
 
-## How it works
+## The operating model: Learn → Ask → Do
 
-```
-developer chats with the agent
-        │
-skills/  teach the agent when to ask, when to stop, when to ask YOU
-        │
-pythia   CLI — expert queries, impact analysis, the six-step write path
-        │
-Oracle   data dictionary: ALL_SOURCE, ALL_DEPENDENCIES, ALL_ERRORS, PL/Scope
-```
+Give the agent a problem — "add a column and every procedure that maintains
+it", "why does this report double rows", "port this fix" — and the kit walks
+it through the same three movements a careful senior developer makes.
 
-The write path is the heart: **snapshot → impact → preview → apply → verify → report**.
-DDL self-commits in Oracle — the snapshot is the only real undo, so it always runs
-first and no flag can turn it off. A 6-hex token binds the write to exactly what was
-previewed; exit codes make honesty machine-readable
-(`0` clean · `1` refused · `3` **written but broken — never reported as success**).
+### 1 · Learn — understand before proposing
+
+The agent studies four things, in order, with tools instead of guesses:
+
+| It learns | How | Instead of |
+|---|---|---|
+| the problem's real shape | `deps`, `impact`, `plscope` — the exact dependency graph and usage sites | skimming code and hoping |
+| the schema's ground truth | `src`, `cols`, `args`, `ddl`, `errors` against the live database | trusting a dump that drifted |
+| the house style | `.pythia/conventions.md` + `conventions --scan/--check` — rules measured against real names | inventing a style per session |
+| how this codebase already solves it | `similar` — the neighbours to imitate | writing the first thing that compiles |
+
+Nothing in this phase writes. Reading is free, so the bar is: **no proposal
+before the blast radius is known** (`pythia-impact`'s iron law) and **no line
+written before the neighbours have been read** (`pythia-write`'s).
+
+### 2 · Ask — the questions are part of the method, not an interruption
+
+The kit makes the agent stop at exactly the moments where a human's judgment
+is the missing input, and forbids it to guess past them:
+
+- **Before any write**: the full preview — diff, dependents, warnings — is
+  relayed verbatim, and the agent waits for a real yes. A compliment is not a
+  yes. Silence is not a yes.
+- **When the blast radius is large**: ten or more dependents, or anything
+  cross-schema, goes to the developer *before code is written*, not after.
+- **When sources of truth disagree**: a standards document says one thing,
+  the schema does another — that gap is a question ("rule nobody follows,
+  new-code-only, or drift?"), never a silent pick.
+- **When something breaks**: exit 3 means *written but broken*. The agent
+  reports it exactly so, with the ready rollback — reporting success here is
+  the one sin the whole kit is built to prevent.
+- **When policy refuses**: the refusal is relayed as information, not routed
+  around.
+
+### 3 · Do — act inside a pipeline that cannot lie
+
+Only after Learn and Ask does anything touch the database, and then only
+through one door: **snapshot → impact → preview → token → apply → verify →
+report**. DDL self-commits in Oracle, so the snapshot is the only real undo —
+it runs first and no flag disables it. A content-bound token guarantees what
+lands is byte-for-byte what was approved. And the CLI enforces the gates
+itself: a headless agent cannot `--yes` its own writes or loosen policy —
+that takes a human at a real terminal.
+
+The same discipline holds when the *developer* does the work: `src` and
+`impact` silently snapshot what they read, so even a change made by hand in
+SQL Developer has a rollback file waiting (`history` lists them, drift is
+reported when source moved with no apply behind it).
+
+**Học – Hỏi – Làm** — Learn, Ask, Do. If the agent cannot show which phase it
+is in, it is doing none of them.
 
 ## Install
 
@@ -164,13 +210,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.10 → pythia_plsql-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.4.10"
+version = "0.6.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.6.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.10 → pythia_plsql-0.6.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,24 @@ 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_]+$",
@@ -1383,6 +1402,109 @@ 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.
@@ -1861,6 +1983,65 @@ 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]
+
+
+OPERATING_GUIDE = """\
+THE OPERATING MODEL — Learn, Ask, Do (Hoc - Hoi - Lam)
+
+pythia is a harness: a book of working rules for an AI agent sitting next to
+a developer. Every task moves through the same three movements. If you cannot
+say which movement you are in, you are in none of them.
+
+=== 1. LEARN — understand before proposing ======================
+Nothing here writes. Reading is free; guessing is not.
+
+  the problem's shape     deps · impact · plscope     the exact graph, not a skim
+  the schema's truth      src · args · cols · ddl · errors · invalid · check · ls · grep · sql
+  the house style         conventions (--scan / --check) · the project's conventions.md
+  how it is done here     similar · history            neighbours to imitate, versions that exist
+
+Iron laws: no proposal before the blast radius is known; no line written
+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.
+
+  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
+                          list BEFORE writing code.
+  truths disagree         document says one thing, schema another - ask which:
+                          rule nobody follows, new-code-only, or drift.
+  policy refuses          relay the refusal (policy shows the rules). Never
+                          route around it.
+  it broke                exit 3 = written but broken. Say exactly that, with
+                          the rollback line. journal (show/diff) is your evidence.
+
+=== 3. DO — act inside a pipeline that cannot lie ===============
+One door for writes: snapshot -> impact -> preview -> token -> apply ->
+verify -> report.
+
+  apply                   the six-step write; --confirm binds to the preview
+  journal restore         undo, through the same six steps
+  unistr                  exact non-ASCII literals for what you are writing
+  install · agent-user · guide    setting the harness itself up
+
+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,
+-apply, -review, -setup, -skill-author). No skill support on this platform?
+This page is the contract; follow it as written.
+"""
+
+
+def cmd_guide(conn, schema, ns):
+    print(OPERATING_GUIDE)
+
+
 def cmd_conventions(conn, schema, ns):
     root = ns.project_root
     if getattr(ns, "init", False):
@@ -1872,19 +2053,54 @@ def cmd_conventions(conn, schema, ns):
                   f"{pathlib.Path(root) / CONFIG_DIR} — left untouched.")
         else:
             print(NL + "Edit the patterns to match this schema — "
-                  f"`{invocation()} similar <A_TYPICAL_NAME>` shows what "
-                  "it already does." + NL + "Every apply preview then "
-                  "warns when a name drifts from them.")
+                  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 the starter pair with: {invocation()} conventions --init")
-        print("  conventions.json  naming patterns; apply previews warn on drift")
-        print("  conventions.md    the prose rules your agents read first")
+        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():
@@ -1892,28 +2108,7 @@ def cmd_conventions(conn, schema, ns):
     md = pathlib.Path(root) / CONFIG_DIR / "conventions.md"
     if md.is_file():
         print(NL + f"Prose rules for agents: {md}")
-    else:
-        print(NL + f"No conventions.md yet — {invocation()} conventions "
-              "--init writes one.")
-
-
-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(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,
@@ -2240,11 +2435,11 @@ COMMANDS = {"check": cmd_check, "ls": cmd_ls, "src": cmd_src, "args": cmd_args,
             "invalid": cmd_invalid, "errors": cmd_errors, "deps": cmd_deps,
             "impact": cmd_impact, "similar": cmd_similar, "plscope": cmd_plscope,
             "policy": cmd_policy, "journal": cmd_journal, "apply": cmd_apply,
-            "conventions": cmd_conventions, "install": cmd_install,
+            "conventions": cmd_conventions, "guide": cmd_guide, "install": cmd_install,
             "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", "guide",
                   "history"}
 
 
@@ -2342,11 +2537,20 @@ 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("guide", parents=[common()],
+                   help="the operating model: Learn, Ask, Do — the whole "
+                        "harness on one page, no database needed")
     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")
@@ -2405,7 +2609,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.10 → pythia_plsql-0.6.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.4.10
+Version: 0.6.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
@@ -26,10 +26,16 @@ Dynamic: license-file
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![python](https://img.shields.io/badge/python-3.9%2B-blue)
 
-An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI coding
-agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills` supports).
-Explore schemas too big to dump, measure blast radius **before** touching anything,
-and land changes through a snapshot-verified write path that never lies about rollback.
+An Agent Skills + CLI kit for developing PL/SQL on Oracle Database with AI
+coding agents (Claude Code, Codex, Cursor — any of the 76 agents `npx skills`
+supports).
+
+pythia is a **harness**: a book of working rules an agent studies and follows
+when it sits next to a developer. Not a chatbot, not an autopilot — a
+disciplined assistant with three properties a good one has: **knowledge** (it
+asks the live schema, never its memory of one), **judgment** (it measures
+before it proposes), and **obedience to rules it can recite** (gates it will
+quote back to you rather than quietly skip).
 
 ## Why ask the database instead of reading dumps
 
@@ -47,23 +53,63 @@ Code that "reads fine" against the dump references types and packages the dump n
 heard of. Every pythia command asks the live data dictionary instead — and every
 truncated output says so, so an agent never mistakes a partial answer for a full one.
 
-## How it works
+## The operating model: Learn → Ask → Do
 
-```
-developer chats with the agent
-        │
-skills/  teach the agent when to ask, when to stop, when to ask YOU
-        │
-pythia   CLI — expert queries, impact analysis, the six-step write path
-        │
-Oracle   data dictionary: ALL_SOURCE, ALL_DEPENDENCIES, ALL_ERRORS, PL/Scope
-```
+Give the agent a problem — "add a column and every procedure that maintains
+it", "why does this report double rows", "port this fix" — and the kit walks
+it through the same three movements a careful senior developer makes.
 
-The write path is the heart: **snapshot → impact → preview → apply → verify → report**.
-DDL self-commits in Oracle — the snapshot is the only real undo, so it always runs
-first and no flag can turn it off. A 6-hex token binds the write to exactly what was
-previewed; exit codes make honesty machine-readable
-(`0` clean · `1` refused · `3` **written but broken — never reported as success**).
+### 1 · Learn — understand before proposing
+
+The agent studies four things, in order, with tools instead of guesses:
+
+| It learns | How | Instead of |
+|---|---|---|
+| the problem's real shape | `deps`, `impact`, `plscope` — the exact dependency graph and usage sites | skimming code and hoping |
+| the schema's ground truth | `src`, `cols`, `args`, `ddl`, `errors` against the live database | trusting a dump that drifted |
+| the house style | `.pythia/conventions.md` + `conventions --scan/--check` — rules measured against real names | inventing a style per session |
+| how this codebase already solves it | `similar` — the neighbours to imitate | writing the first thing that compiles |
+
+Nothing in this phase writes. Reading is free, so the bar is: **no proposal
+before the blast radius is known** (`pythia-impact`'s iron law) and **no line
+written before the neighbours have been read** (`pythia-write`'s).
+
+### 2 · Ask — the questions are part of the method, not an interruption
+
+The kit makes the agent stop at exactly the moments where a human's judgment
+is the missing input, and forbids it to guess past them:
+
+- **Before any write**: the full preview — diff, dependents, warnings — is
+  relayed verbatim, and the agent waits for a real yes. A compliment is not a
+  yes. Silence is not a yes.
+- **When the blast radius is large**: ten or more dependents, or anything
+  cross-schema, goes to the developer *before code is written*, not after.
+- **When sources of truth disagree**: a standards document says one thing,
+  the schema does another — that gap is a question ("rule nobody follows,
+  new-code-only, or drift?"), never a silent pick.
+- **When something breaks**: exit 3 means *written but broken*. The agent
+  reports it exactly so, with the ready rollback — reporting success here is
+  the one sin the whole kit is built to prevent.
+- **When policy refuses**: the refusal is relayed as information, not routed
+  around.
+
+### 3 · Do — act inside a pipeline that cannot lie
+
+Only after Learn and Ask does anything touch the database, and then only
+through one door: **snapshot → impact → preview → token → apply → verify →
+report**. DDL self-commits in Oracle, so the snapshot is the only real undo —
+it runs first and no flag disables it. A content-bound token guarantees what
+lands is byte-for-byte what was approved. And the CLI enforces the gates
+itself: a headless agent cannot `--yes` its own writes or loosen policy —
+that takes a human at a real terminal.
+
+The same discipline holds when the *developer* does the work: `src` and
+`impact` silently snapshot what they read, so even a change made by hand in
+SQL Developer has a rollback file waiting (`history` lists them, drift is
+reported when source moved with no apply behind it).
+
+**Học – Hỏi – Làm** — Learn, Ask, Do. If the agent cannot show which phase it
+is in, it is doing none of them.
 
 ## Install
 
@@ -178,13 +224,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.10 → pythia_plsql-0.6.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.4.10 → pythia_plsql-0.6.0}/skills/pythia-apply/SKILL.md

@@ -7,6 +7,8 @@ description: Use when a PL/SQL change is ready to reach the database - applying
 
 **Announce at start:** "Using pythia-apply — I'll preview the change first."
 
+**Phase:** Ask → Do — the preview is relayed and approved before the one write door opens
+
 DDL in Oracle commits itself. There is no transaction to roll back — the
 snapshot pythia takes before writing is the only undo that exists. This skill
 exists so that safety net is always used, and used honestly.

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

@@ -0,0 +1,103 @@
+---
+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."
+
+**Phase:** Learn → Ask — derive from the schema, ask where the document disagrees, only then write the config
+
+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.10 → pythia_plsql-0.6.0}/skills/pythia-explore/SKILL.md

@@ -7,6 +7,8 @@ description: Use when you need to understand anything in an Oracle schema - find
 
 **Announce at start:** "Using pythia-explore — asking the database directly."
 
+**Phase:** Learn
+
 ## The principle: ask the database, never the dump
 
 Repositories of exported `.sql` files go stale the day after export. A real

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/skills/pythia-impact/SKILL.md

@@ -7,6 +7,8 @@ description: Use before proposing or writing any change to an Oracle object - a
 
 **Announce at start:** "Using pythia-impact to measure the blast radius first."
 
+**Phase:** Learn — and the first Ask gate: a large blast radius reaches the developer before any code is written
+
 Changing an Oracle object recompiles or invalidates everything that depends
 on it — immediately, schema-wide, for every user of a shared database. The
 cost of knowing first is one command.

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/skills/pythia-review/SKILL.md

@@ -7,6 +7,8 @@ description: Use when reviewing PL/SQL - a changed procedure or package, a propo
 
 **Announce at start:** "Using pythia-review — checking the database's signals first."
 
+**Phase:** Learn → Ask — the database's own signals first, findings back to the developer
+
 Review in two passes: what the database *knows* is wrong, then what the
 checklist says is *likely* wrong. Machine signals first — they are free and
 exact.

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/skills/pythia-setup/SKILL.md

@@ -7,6 +7,8 @@ description: Use when setting pythia up for a project or a machine - writing con
 
 **Announce at start:** "Using pythia-setup to configure the database access."
 
+**Phase:** Do — one-time harness setup; everything after runs through Learn → Ask → Do
+
 Set up in this order: connection first (everything else needs it), the
 least-privilege user second (the only protection that cannot be bypassed),
 SQLcl MCP last (optional, reads only).

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/skills/pythia-skill-author/SKILL.md

@@ -7,6 +7,8 @@ description: Use when the developer wants their own way of working captured as a
 
 **Announce at start:** "Using pythia-skill-author — let's capture how you actually work."
 
+**Phase:** Learn → Ask → Do — interview, mine the schema, verify triggering
+
 A skill is a decision captured so it never has to be re-argued. Capture what
 the team *actually does* — with evidence from the database — not what anyone
 remembers about it.

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/skills/pythia-write/SKILL.md

@@ -7,6 +7,8 @@ description: Use when writing or modifying PL/SQL source - a procedure, function
 
 **Announce at start:** "Using pythia-write — mining the codebase's conventions first."
 
+**Phase:** Learn → Do — mine the neighbours first, then draft; landing it is pythia-apply's job
+
 **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. If the project has none and the developer

{pythia_plsql-0.4.10 → pythia_plsql-0.6.0}/tests/test_install.py

@@ -348,6 +348,19 @@ def test_conventions_init_writes_both_halves_and_never_clobbers():
         assert (d / "conventions.json").read_text(encoding="utf-8") == '{"naming": {}}'
 
 
+def test_guide_places_every_command_in_the_model():
+    """`pythia guide` is the book an agent can open on any platform, skills
+    support or not. Coherence is enforced: every command the CLI exposes must
+    appear somewhere in the guide -- adding a command without giving it a
+    place in Learn/Ask/Do fails here."""
+    text = pythia.OPERATING_GUIDE
+    for phase in ("LEARN", "ASK", "DO"):
+        assert phase in text, f"guide missing the {phase} movement"
+    for cmd in pythia.COMMANDS:
+        assert cmd in text, f"command {cmd!r} has no place in the guide"
+    assert "guide" in pythia.NO_DB_COMMANDS   # the book opens with no database
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):

{pythia_plsql-0.4.10 → pythia_plsql-0.6.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.10 → pythia_plsql-0.6.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
@@ -109,17 +109,40 @@ def test_reference_files_exist_where_promised():
 
 
 def test_readme_carries_the_required_tables():
-    """The spec's completion criteria: drift table up top, honest-rollback and
-    policy tables present, install channels, under 200 lines."""
+    """The line cap is gone by the owner's call — the README now explains
+    the operating model in full. What stays pinned is content: the drift
+    table, the honest-rollback and policy tables, the install channels, and
+    the Learn-Ask-Do frame the whole kit is organised around."""
     text = (ROOT / "README.md").read_text(encoding="utf-8")
-    for needle in ("1,016",                              # drift table, index row
+    for needle in ("1,016",                              # drift table
                    "Flashback Query", "Recycle Bin",     # rollback honesty
                    "plsql_source", "data_dml",           # policy table
                    "npx skills add",                     # install channel
-                   "star-history.com",                   # star chart
+                   "Learn", "Ask", "Do",                 # the operating model
+                   "star-history.com",
                    "MIT"):
         assert needle in text, f"README missing {needle!r}"
-    assert text.count("\n") + 1 <= 200, "README must stay under 200 lines"
+
+
+def test_vietnamese_readme_carries_the_operating_model():
+    text = (ROOT / "README.vi.md").read_text(encoding="utf-8")
+    for needle in ("Học", "Hỏi", "Làm"):
+        assert needle in text, f"README.vi missing {needle!r}"
+
+
+def test_every_skill_declares_its_phase():
+    """The kit's operating model is Learn - Ask - Do. A skill that cannot say
+    which movement it serves is not part of the method, it is a loose page."""
+    for name in sorted(EXPECTED):
+        path = SKILLS / name / "SKILL.md"
+        if not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8")
+        m = re.search(r"\*\*Phase:\*\* (.+)", text)
+        assert m, f"{name}: no '**Phase:**' declaration"
+        words = set(re.findall(r"Learn|Ask|Do", m.group(1)))
+        assert words and words <= {"Learn", "Ask", "Do"}, \
+            f"{name}: phase must name Learn/Ask/Do, got {m.group(1)!r}"
 
 
 def main():