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

{pythia_plsql-0.5.0/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.5.0
+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
 

{pythia_plsql-0.5.0 → 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
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.5.0"
+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.5.0 → pythia_plsql-0.6.0}/scripts/pythia.py

@@ -1988,6 +1988,60 @@ def _schema_objects(conn, 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):
@@ -2381,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", "install", "unistr",
+NO_DB_COMMANDS = {"policy", "journal", "install", "unistr", "guide",
                   "history"}
 
 
@@ -2483,6 +2537,9 @@ 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",

{pythia_plsql-0.5.0 → 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.5.0
+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
 

{pythia_plsql-0.5.0 → 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.5.0 → pythia_plsql-0.6.0}/skills/pythia-conventions/SKILL.md

@@ -7,6 +7,8 @@ description: Use when a project's house style already exists somewhere and needs
 
 **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

{pythia_plsql-0.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → 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.5.0 → pythia_plsql-0.6.0}/tests/test_phase5.py

@@ -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():