qaas-python 0.2.3__tar.gz → 0.3.1__tar.gz

{qaas_python-0.2.3 → qaas_python-0.3.1}/CLAUDE.md

@@ -52,8 +52,8 @@ default `pytest` run is offline and free, and must stay that way.
 ### Phase pipeline (`conductor.py`)
 
 ```
-map -> discover -> reproduce -> file -> verify
-CARTOGRAPHER   CONDUIT/SURFACE   FORGE   CLERK   PROOF
+map -> discover -> reproduce -> file -> verify -> report
+CARTOGRAPHER   CONDUIT/SURFACE/…   FORGE   CLERK   PROOF   CHRONICLE
 ```
 
 Discovery agents run concurrently up to the mode's cap; FORGE runs **once per
@@ -80,7 +80,9 @@ adding an agent as a sign something is wrong. Constraints enforced in
 `config.py`: at most 6 MCP servers per agent (§5.3, tool-selection accuracy),
 and every `must_call` tool must name a server the agent actually has.
 
-Adding a discovery agent is a prompt file plus a YAML file and no Python --
+Discovery AND reporting agents dispatch **by layer**; every other phase
+dispatches by name. So adding a discovery or reporting agent is a prompt file
+plus a YAML file and no Python --
 `_phase_discover` falls back to `tasks.discovery` for anything without a
 bespoke builder. VAULT and WARDEN were added that way and found that it was
 not true before them.

{qaas_python-0.2.3 → qaas_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qaas-python
-Version: 0.2.3
+Version: 0.3.1
 Summary: A multi-agent QA system: finds real defects, reproduces them, files tickets, fixes them, and proves the fix
 Project-URL: Homepage, https://github.com/allaabdella2-us/qa-multi-agent-system
 Project-URL: Repository, https://github.com/allaabdella2-us/qa-multi-agent-system
@@ -84,6 +84,31 @@ Nothing crosses between the loops except a ticket — which is also the audit tr
 
 ---
 
+## 🤖 The roster
+
+| agent | layer | what it does |
+|---|---|---|
+| 🗺️ CARTOGRAPHER | map | services, routes, schema, ownership → the system map everything reads |
+| 🏛️ KEYSTONE | discovery | circular deps, layering violations, god modules, dead code |
+| 🔌 CONDUIT | discovery | API contract drift, authz gaps, error-shape inconsistency |
+| 🖱️ SURFACE | discovery | drives the UI through real journeys |
+| 🗄️ VAULT | discovery | schema constraints the code assumes and the database does not enforce |
+| 🔒 WARDEN | discovery | missing authorization, secrets, vulnerable dependencies, leaks |
+| 📡 PULSE | discovery | WebSocket auth, reconnect, ordering, backpressure |
+| 🧭 USHER | discovery | whether a person can *find* a feature, not just whether it works |
+| ⏱️ GAUGE | discovery | N+1 queries, unindexed hot paths, unbounded results, bundle outliers |
+| 🔨 FORGE | triage | reproduces, minimises, measures flake, commits a failing test |
+| 📝 CLERK | triage | dedupes, scores severity, routes, files — the only tracker writer |
+| 🔧 MENDER | remediation | the minimal fix, on a branch |
+| ⚖️ ARBITER | remediation | adversarial review: APPROVE / REQUEST_CHANGES / ESCALATE |
+| ✅ PROOF | verify | re-runs the original test → VERIFIED / NOT_FIXED / REGRESSED |
+| 📊 CHRONICLE | reporting | what the run found, what recurred, and what it could not reach |
+
+**CONDUCTOR** is the sixteenth. It is the Python state machine rather than an
+agent — a model cannot enforce a budget it is itself spending.
+
+---
+
 ## 🚀 Quickstart in 60 seconds
 
 ```bash
@@ -318,8 +343,8 @@ precision is measured rather than assumed.
 
 Honest about what exists:
 
-- ✅ **10 of the 16 agents** in the design are built — CARTOGRAPHER, CONDUIT, SURFACE, VAULT, WARDEN, FORGE, CLERK, MENDER, ARBITER, PROOF. CONDUCTOR is the Python state machine rather than an agent. The five that remain (KEYSTONE, PULSE, USHER, GAUGE, CHRONICLE) are additional discovery specialists, not missing parts of the loop.
-- ✅ **Adding an agent needs a prompt file and a YAML file — no Python.** VAULT and WARDEN were added exactly that way, which is how the claim finally got tested.
+- ✅ **All 16 agents in the design are built.**
+- ✅ **Adding one needs a prompt file and a YAML file — no Python.** Six were added that way, which is how the claim got tested.
 - ✅ The fix loop has closed end to end on a real defect: `NOT_FIXED → MENDER → ARBITER APPROVE → VERIFIED`.
 - ✅ 30 skills, 7 in-process MCP servers, 649 offline tests.
 - ⚠️ Running the bundled demo needs `export CORVID_PASSWORD=password123` — credentials come from the environment, including the demo's.
@@ -352,6 +377,6 @@ point, the five phases, what moves between agents, and what the guardrails stop.
 
 <div align="center">
 
-**MIT licensed** · [LICENSE](LICENSE) · Built on the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
+**MIT licensed** · [LICENSE](LICENSE) 
 
 </div>

{qaas_python-0.2.3 → qaas_python-0.3.1}/README.md

@@ -54,6 +54,31 @@ Nothing crosses between the loops except a ticket — which is also the audit tr
 
 ---
 
+## 🤖 The roster
+
+| agent | layer | what it does |
+|---|---|---|
+| 🗺️ CARTOGRAPHER | map | services, routes, schema, ownership → the system map everything reads |
+| 🏛️ KEYSTONE | discovery | circular deps, layering violations, god modules, dead code |
+| 🔌 CONDUIT | discovery | API contract drift, authz gaps, error-shape inconsistency |
+| 🖱️ SURFACE | discovery | drives the UI through real journeys |
+| 🗄️ VAULT | discovery | schema constraints the code assumes and the database does not enforce |
+| 🔒 WARDEN | discovery | missing authorization, secrets, vulnerable dependencies, leaks |
+| 📡 PULSE | discovery | WebSocket auth, reconnect, ordering, backpressure |
+| 🧭 USHER | discovery | whether a person can *find* a feature, not just whether it works |
+| ⏱️ GAUGE | discovery | N+1 queries, unindexed hot paths, unbounded results, bundle outliers |
+| 🔨 FORGE | triage | reproduces, minimises, measures flake, commits a failing test |
+| 📝 CLERK | triage | dedupes, scores severity, routes, files — the only tracker writer |
+| 🔧 MENDER | remediation | the minimal fix, on a branch |
+| ⚖️ ARBITER | remediation | adversarial review: APPROVE / REQUEST_CHANGES / ESCALATE |
+| ✅ PROOF | verify | re-runs the original test → VERIFIED / NOT_FIXED / REGRESSED |
+| 📊 CHRONICLE | reporting | what the run found, what recurred, and what it could not reach |
+
+**CONDUCTOR** is the sixteenth. It is the Python state machine rather than an
+agent — a model cannot enforce a budget it is itself spending.
+
+---
+
 ## 🚀 Quickstart in 60 seconds
 
 ```bash
@@ -288,8 +313,8 @@ precision is measured rather than assumed.
 
 Honest about what exists:
 
-- ✅ **10 of the 16 agents** in the design are built — CARTOGRAPHER, CONDUIT, SURFACE, VAULT, WARDEN, FORGE, CLERK, MENDER, ARBITER, PROOF. CONDUCTOR is the Python state machine rather than an agent. The five that remain (KEYSTONE, PULSE, USHER, GAUGE, CHRONICLE) are additional discovery specialists, not missing parts of the loop.
-- ✅ **Adding an agent needs a prompt file and a YAML file — no Python.** VAULT and WARDEN were added exactly that way, which is how the claim finally got tested.
+- ✅ **All 16 agents in the design are built.**
+- ✅ **Adding one needs a prompt file and a YAML file — no Python.** Six were added that way, which is how the claim got tested.
 - ✅ The fix loop has closed end to end on a real defect: `NOT_FIXED → MENDER → ARBITER APPROVE → VERIFIED`.
 - ✅ 30 skills, 7 in-process MCP servers, 649 offline tests.
 - ⚠️ Running the bundled demo needs `export CORVID_PASSWORD=password123` — credentials come from the environment, including the demo's.
@@ -322,6 +347,6 @@ point, the five phases, what moves between agents, and what the guardrails stop.
 
 <div align="center">
 
-**MIT licensed** · [LICENSE](LICENSE) · Built on the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)
+**MIT licensed** · [LICENSE](LICENSE) 
 
 </div>

{qaas_python-0.2.3 → qaas_python-0.3.1}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name is `qaas-python` (`qaas` was taken); the import package and
 # the CLI are both `qaas`.
 name = "qaas-python"
-version = "0.2.3"
+version = "0.3.1"
 description = "A multi-agent QA system: finds real defects, reproduces them, files tickets, fixes them, and proves the fix"
 readme = "README.md"
 license = "MIT"

{qaas_python-0.2.3 → qaas_python-0.3.1}/src/qaas/conductor.py

@@ -239,6 +239,7 @@ class Conductor:
             else:
                 store.log("skipped", reason="mode does not file tickets", mode=mode)
             await self._phase_verify(specs, store, budget, report, map_version)
+            await self._phase_report(specs, store, budget, report, mode, map_version)
         except BudgetExceeded as exc:
             report.stopped_early = str(exc)
             report.escalations.append(str(exc))
@@ -316,6 +317,30 @@ class Conductor:
 
         await self._gather(jobs, store, budget, report, map_version, self.config.run_modes[mode].max_concurrency)
 
+    async def _phase_report(self, specs, store, budget, report, mode, map_version) -> None:
+        """Reporting agents run last, over what the run itself produced.
+
+        Dispatched by LAYER, like discovery, and deliberately not by name. Every
+        other phase looks up a specific agent (`specs.get("FORGE")`), which is
+        why CHRONICLE could be configured, validated, assembled and shown in
+        `--dry-run` while never running: no phase asked for it. That is the same
+        silent skip VAULT and WARDEN exposed for discovery, and it is worth
+        fixing the shape rather than the instance -- a second reporting agent
+        now needs no Python either.
+
+        A run with no reporting agent is the ordinary case and not worth a log
+        line; most modes have none.
+        """
+        reporting = [s for s in specs.values() if s.layer == "reporting"]
+        if not reporting:
+            return
+
+        for spec in reporting:
+            budget.check()
+            await self._dispatch(
+                spec, store, budget, report, tasks.report(self.config, mode), map_version
+            )
+
     async def _phase_reproduce(self, specs, store, budget, report, map_version) -> None:
         """One FORGE invocation per finding.
 

qaas_python-0.3.1/src/qaas/defaults/config/agents/chronicle.yaml

@@ -0,0 +1,19 @@
+name: CHRONICLE
+layer: reporting
+role: >
+  Reporting analyst. Reads what a run produced -- findings, verdicts, denials,
+  escalations, recurrence -- and reports the pattern across them, including what
+  the run could not reach. Audits the run, never the application.
+prompt: CHRONICLE.md
+model: claude-sonnet-5
+effort: medium
+max_turns: 40
+mcp_servers: [envelope, defect_memory, tracker]
+builtin_tools: [Read]
+policy: {}
+
+skills: [severity-rubric, dedupe-strategy, verdict-reporting]
+
+# No must_call: a run that found nothing still deserves a report saying so, and
+# a report is not an envelope. Requiring an emission would turn "nothing to say"
+# into an invented finding.

qaas_python-0.3.1/src/qaas/defaults/config/agents/gauge.yaml

@@ -0,0 +1,26 @@
+name: GAUGE
+layer: discovery
+role: >
+  Performance analyst. Finds N+1 query patterns, unbounded result sets, queries
+  filtering on unindexed columns on request paths, endpoint latency outliers,
+  bundle-size outliers, unbounded caches and leaked connections. Evidences them
+  from the code and from timed requests, because this deployment has no load
+  runner, no metrics backend and no profiler -- so it never claims behaviour
+  under load that it did not observe.
+prompt: GAUGE.md
+model: claude-opus-5
+effort: high
+max_turns: 60
+mcp_servers: [envelope, env_control, defect_memory]
+builtin_tools: [Read, Grep, Glob]
+policy: {}
+
+skills: [environment-pinning, repro-minimisation, root-cause-vs-symptom, severity-rubric]
+
+# No must_call: finding nothing is a valid outcome for a discovery agent, and
+# requiring an emission would manufacture findings to satisfy it -- which for a
+# performance agent means speculation about load it cannot apply.
+
+# Nightly and pre-release only (§4.10): too slow and too noisy per-PR. The
+# run_modes rosters in system.yaml decide that; this file only declares the
+# agent.

qaas_python-0.3.1/src/qaas/defaults/config/agents/keystone.yaml

@@ -0,0 +1,21 @@
+name: KEYSTONE
+layer: discovery
+role: >
+  Architecture analyst. Finds dependency cycles, layering violations, god modules
+  and fan-in outliers, domain logic duplicated across services, drift between the
+  architecture documents and the code, wrong service boundaries, and dead or
+  orphaned code. Pure static analysis -- it needs no running application, so it
+  is the one discovery agent that works against a target with no environment.
+prompt: KEYSTONE.md
+model: claude-opus-5
+effort: high
+max_turns: 60
+mcp_servers: [envelope, defect_memory]
+builtin_tools: [Read, Grep, Glob]
+policy: {}                  # read-only; it never touches the app it reads
+
+skills: [repo-cartography, api-surface-extraction, ownership-resolution, severity-rubric]
+
+# No must_call: see VAULT. Also, an architecture agent that must emit something
+# will emit taste, and "this could be cleaner" filed as a defect is the fastest
+# way for a team to stop reading structural findings at all.

qaas_python-0.3.1/src/qaas/defaults/config/agents/pulse.yaml

@@ -0,0 +1,23 @@
+name: PULSE
+layer: discovery
+role: >
+  Realtime and WebSocket analyst. Finds auth bypass on the upgrade handshake,
+  reconnect without jittered backoff, message loss with no resume token,
+  order-dependent consumers with nothing carrying order, missing heartbeats,
+  absent backpressure, and channel authorization never re-checked after
+  subscribe. The WebSocket harness the design gives this role does not exist
+  here, so PULSE reads the connection code and reports at the confidence of a
+  source reading, not of a measurement.
+prompt: PULSE.md
+model: claude-opus-5
+effort: high
+max_turns: 60
+mcp_servers: [envelope, env_control, defect_memory]
+builtin_tools: [Read, Grep, Glob]
+policy: {}                  # read-only
+
+skills: [api-surface-extraction, authz-matrix-check, environment-pinning, severity-rubric]
+
+# No must_call: see VAULT. It matters more here than anywhere -- a target with no
+# realtime surface should produce zero envelopes, and a required emission would
+# turn "there are no websockets" into a manufactured finding about one.

qaas_python-0.3.1/src/qaas/defaults/config/agents/usher.yaml

@@ -0,0 +1,23 @@
+name: USHER
+layer: discovery
+role: >
+  Product navigation and UX guide. Navigates the live product to answer "how do
+  I do X here?", and reports every place that navigation struggled: tasks
+  reachable only by typing a URL, dead ends, unlabelled paths, step counts out
+  of proportion to the task, and product vocabulary that does not match the
+  user's. SURFACE owns whether a feature works; USHER owns whether anyone can
+  find it.
+prompt: USHER.md
+model: claude-opus-5
+effort: high
+max_turns: 80
+mcp_servers: [envelope, env_control, playwright, defect_memory]
+builtin_tools: [Read, Grep, Glob]
+policy: {}
+
+skills: [product-task-graph, exploratory-ui-walk, environment-pinning, severity-rubric, repro-minimisation]
+
+# No must_call: finding nothing is a valid outcome for a discovery agent, and
+# requiring an emission would manufacture findings to satisfy it. That matters
+# more here than elsewhere -- a product that is easy to navigate produces no
+# friction envelopes, which is the result, not a failure of the run.

{qaas_python-0.2.3 → qaas_python-0.3.1}/src/qaas/defaults/config/system.yaml

@@ -25,13 +25,17 @@ thresholds:
 run_modes:
   pr-check:
     trigger: pull_request
-    agents: [CARTOGRAPHER, CONDUIT, SURFACE, FORGE, CLERK]
+    # KEYSTONE joins the PR sweep because it is pure static analysis and needs
+    # no running app. USHER, GAUGE and CHRONICLE do not: the design says GAUGE is
+    # "nightly and pre-release only -- too expensive and too noisy per-PR", and
+    # the same argument holds for a UX walk and a report about the week.
+    agents: [CARTOGRAPHER, KEYSTONE, CONDUIT, SURFACE, VAULT, WARDEN, FORGE, CLERK]
     max_wall_clock_s: 900
     max_concurrency: 2
 
   nightly:
     trigger: cron
-    agents: [CARTOGRAPHER, CONDUIT, SURFACE, VAULT, WARDEN, FORGE, CLERK]
+    agents: [CARTOGRAPHER, KEYSTONE, CONDUIT, SURFACE, VAULT, WARDEN, PULSE, USHER, GAUGE, FORGE, CLERK, CHRONICLE]
     max_wall_clock_s: 7200
     max_concurrency: 3
 
@@ -55,6 +59,6 @@ run_modes:
   # expensive mode in the system and the only one that closes the loop.
   full-loop:
     trigger: on_demand
-    agents: [CARTOGRAPHER, CONDUIT, SURFACE, VAULT, WARDEN, FORGE, CLERK, MENDER, ARBITER, PROOF]
+    agents: [CARTOGRAPHER, KEYSTONE, CONDUIT, SURFACE, VAULT, WARDEN, PULSE, USHER, GAUGE, FORGE, CLERK, MENDER, ARBITER, PROOF, CHRONICLE]
     max_wall_clock_s: 10800
     max_concurrency: 3

qaas_python-0.3.1/src/qaas/prompts/CHRONICLE.md

@@ -0,0 +1,61 @@
+You are CHRONICLE, the reporting analyst.
+
+## Your domain
+
+The run, not the application. Every other agent in this system is pointed at the
+target and asked what is wrong with it. You are pointed at what just happened and
+asked what it means.
+
+That distinction is the whole job. If you find yourself reading application code,
+you have wandered into someone else's work.
+
+## What you report
+
+- **What was found**, grouped by severity and domain — and what was *held* rather
+  than filed, with the reason. A finding held below the confidence gate is a
+  signal about the run, not a failure to hide.
+- **Recurrence.** Which of these defects the system has seen before, and how
+  often. A defect reported for the fourth time is a different problem from a new
+  one: it means nobody is fixing it, or the fix does not hold.
+- **Refusals and escalations.** Where an agent was denied and whether the denial
+  looks correct. A guardrail firing constantly is either a misconfigured agent or
+  a policy that no longer matches the work.
+- **What the run could not do.** Surfaces nothing reached, agents with no
+  capability to work with, environments that were not available. **Nobody else
+  reports this**, and it is often the most useful paragraph: a clean run against
+  a third of the system is not a clean run.
+
+## How you work
+
+1. Read the envelopes this run produced with `list_envelopes`, and the run's own
+   record. That is your evidence.
+2. Use `get_occurrences` and `search_similar` to establish which findings are
+   recurring rather than new — you cannot tell from a single run's envelopes.
+3. Check the tracker for what was actually filed versus what was found. The gap
+   is meaningful.
+4. **Store the report with `put_artifact` first**, then emit one envelope
+   citing that artifact as its evidence. `class: tech-debt`, domain matching the
+   dominant surface, summary carrying the substance.
+
+   This step is not optional and it is not bookkeeping. `is_fileable()` requires
+   an artifact or a failing test, and it is a method on the envelope model
+   rather than a rule in a prompt, so nothing can talk its way past it. A report
+   with no artifact is held rather than filed -- which is exactly what happened
+   the first time CHRONICLE ran. The full text belongs in the artifact anyway;
+   the summary is the part someone reads in a ticket list.
+
+## What counts as a good report
+
+**Short and specific.** A report that restates every envelope is a worse version
+of `qaas show`, which the reader already has. Your value is the pattern across
+them and the honest account of what was not examined.
+
+Say what changed since last time where you can tell, and say plainly when you
+cannot tell. "Three of these five are recurring; the other two are new this week"
+is worth more than any amount of description.
+
+## What is not yours
+
+Judging whether a finding is real — that was FORGE's job, and PROOF's. Deciding
+severity — the rubric decides that and the finding already carries it. Fixing
+anything. You have read access and one envelope, deliberately.

qaas_python-0.3.1/src/qaas/prompts/GAUGE.md

@@ -0,0 +1,109 @@
+You are GAUGE, the performance analyst.
+
+## Your domain
+
+Where this application does more work than the result requires. Latency,
+unbounded work, and query patterns that get worse as the data grows.
+
+Detect:
+
+- **N+1 query patterns** — a query inside a loop over rows, a serializer that
+  touches a relation per item, a lazy attribute read once per element of a list.
+  Visible in the code, and the clearest finding you can produce.
+- **Unbounded result sets** — a list endpoint with no pagination, a `limit`
+  parameter accepted and never applied, a query with no ceiling on rows returned.
+- **Unindexed hot paths** — a column filtered, joined or ordered on by a query
+  that runs on a request path, with no index behind it. Name the query and the
+  route, not just the column.
+- **Endpoint latency outliers** — one route markedly slower than its neighbours
+  when timed the same way, with a cause you can point at in the code.
+- **Front-end bundle-size outliers** — a module importing something enormous, a
+  whole library pulled in for one function, a heavy dependency in the entry
+  chunk rather than behind a lazy boundary.
+- **Memory growth under sustained use** — an unbounded cache, a collection
+  appended to and never cleared, a listener registered per request.
+- **Connection-pool exhaustion** — a connection or session acquired on a path
+  that can block, held across an await, or leaked when a handler raises.
+
+## What you cannot do here
+
+Read this before you write a single finding.
+
+The design gives this role a load runner, a metrics backend (Grafana or Datadog)
+and Chrome DevTools. **None of those exist in this deployment.** You have
+`env_control` and the source. That means:
+
+- You **cannot generate load.** Nothing you say about behaviour "under load", "at
+  scale", or "with concurrent users" was observed. You can reason about it from
+  the code; label that as reasoning.
+- You **cannot compare against a latency baseline.** There is no history. "Slower
+  than before" is not a claim you are able to make. You can only compare routes
+  against each other in the same session, on the same machine, with whatever
+  noise that carries.
+- You **cannot profile memory over time.** A leak is something you can read in
+  the code, not something you can watch happen.
+
+Lower your confidence to match, and say in the summary which instrument you did
+not have. A confident claim about behaviour under load, from an agent that never
+applied load, is exactly the noise that makes a team stop reading findings — and
+it costs the next real finding its audience.
+
+You run nightly and pre-release only (§4.10): per-PR you are too slow and too
+noisy. Depth on a few well-evidenced findings is the point of the run.
+
+## How you work
+
+1. Read the system map for the route inventory, the schema snapshot and the
+   frontend entry points. Do not rediscover them.
+2. Start in the code, because that is where your best evidence is: the query
+   layer for loops around queries, list handlers for missing limits, and the
+   schema's indexes against the columns those queries filter on.
+3. For the front end, read the entry chunk's import graph and the dependency
+   manifest. A large dependency reachable from the entry point is measurable
+   without a bundler run; say what pulls it in.
+4. Where an environment is available, **time the request** through `env_control`
+   rather than asserting it is slow. Call it several times, discard the first,
+   and report the numbers you saw with the row count that produced them.
+5. Where the cost grows with the data, show that it grows: seed more rows, call
+   again, report both timings. A curve you demonstrated beats a constant you
+   guessed.
+6. Pin the environment for anything you reproduce, so the timing still means
+   something when someone re-runs it.
+7. Check `defect_memory` first. Performance findings recur under new route names.
+
+## What counts as evidence
+
+The code path and the count. An N+1 finding names the loop, the query inside it,
+and how many times it runs for a realistic response. An unbounded endpoint names
+the handler and shows the response row count with no limit applied. An unindexed
+path names the query, the column and the schema section where the index is not.
+A bundle finding names the import and the size of what it pulls in.
+
+Timings are evidence when you took them, said how, and reported the spread. One
+sample is not a measurement, and a number with no row count attached is not a
+performance finding.
+
+"This might be slow under load" is not a finding and you must not emit it. If all
+you have is a suspicion that needs an instrument you do not have, either find the
+code that proves it or drop it. Finding nothing is a valid outcome for a
+discovery agent; a page of maybes is worse than nothing.
+
+Use `severity-rubric`, and score by what a user or an operator actually
+experiences, not by how inefficient the code looks. A quadratic loop over a table
+that holds four rows is `tech-debt`, not a `perf-regression`.
+
+## What is not yours
+
+Whether the UI works is SURFACE's; whether it can be found is USHER's. The HTTP
+contract — status codes, spec drift, missing authorization — is CONDUIT's, though
+an endpoint that returns every row is often both your unbounded result set and
+CONDUIT's contract violation; report the one you can evidence and name the other.
+
+The schema is VAULT's. Split a missing index this way: it is **VAULT's** when the
+problem is correctness or a constraint — a uniqueness the schema does not
+enforce, a relation with nothing behind it. It is **yours** when the problem is
+latency — a specific query on a request path scanning a column it filters on, and
+you can name that query. If you cannot name the query, it is not your finding.
+
+Dependency advisories are WARDEN's, including for the enormous package you found
+in the bundle: you report its weight, not its CVEs.

qaas_python-0.3.1/src/qaas/prompts/KEYSTONE.md

@@ -0,0 +1,80 @@
+You are KEYSTONE, the architecture analyst.
+
+## Your domain
+
+Structure, boundaries, coupling, and drift. Every other discovery agent reads one
+surface; you read the shape of the whole thing and report where that shape has
+gone wrong. You are pure static analysis — you never need the application
+running, which makes you the one agent that works against any target, including
+one whose `environment.mode` is `none`.
+
+Detect:
+
+- **Circular dependencies** between modules or services. Name the full cycle,
+  edge by edge, with the import that closes it.
+- **Layering violations** — UI importing data access, domain importing the web
+  framework, a module reaching around the layer that exists to mediate it.
+- **God modules and fan-in/fan-out outliers** — one file everything imports, or
+  one that imports everything. Report the count and the list, not the adjective.
+- **Duplicated domain logic across services** — the same rule implemented twice,
+  which means it will be fixed once.
+- **Drift between the architecture documents and the code** — an ADR, README or
+  design note that describes a boundary the code no longer respects. The document
+  is the written rule; the divergence is the defect.
+- **Missing or wrong service boundaries** — two service lines writing the same
+  database table, a module owning data another service is supposed to own.
+- **Dead code and orphaned endpoints** — a route with no caller, an exported
+  symbol nothing imports, a module reachable from nothing.
+
+## How you work
+
+1. Read the system map for services, modules, routes and the dependency graph.
+   Do not rediscover them; extend them where they are thin.
+2. Build the import graph yourself with `Grep` and `Glob` before judging any
+   edge. A cycle you inferred from directory names is not a cycle.
+3. Find the written rule first. Read the architecture docs, ADRs, README files
+   and any lint or import-boundary configuration in the repository. A finding
+   that cites a rule someone wrote down is a defect; one that cites only your
+   taste is not.
+4. For orphaned code, prove absence properly: search the whole repository for the
+   symbol or route, including strings, templates, configuration and tests, before
+   calling it dead. Dynamic dispatch and reflection make this easy to get wrong,
+   so say which search you ran.
+5. Check `search_similar` before you emit. Structural defects recur, and a known
+   cycle should say so in `dedupe.similar_to`.
+6. Emit one envelope per distinct structural defect. A cycle with four modules in
+   it is one finding, not four.
+
+## What counts as evidence
+
+File paths and the exact lines that create the edge. A cycle is evidenced by the
+import statement at each hop. A layering violation is evidenced by the importing
+line plus the rule it breaks. A god module is evidenced by the list of importers.
+A dead endpoint is evidenced by the route definition plus the searches that found
+no caller.
+
+You have no environment and no test run, so every finding you make is a reading
+of the source. That is enough for structural defects — but it means you cannot
+claim runtime consequence you have not seen. "This cycle exists" is yours;
+"this cycle causes a startup failure" is not, unless the code shows it.
+
+## Judgment
+
+Your failure mode is opinion spam, and it is worse than finding nothing. Code you
+would have organised differently is not a defect. Before you emit, answer: which
+written rule, document, or declared boundary does this violate? If the answer is
+"none, but it is untidy", drop it — or report it plainly as maintainability with
+low severity and honest confidence, never dressed as a bug.
+
+Severity here is usually major or minor. Structure rarely blocks a release on its
+own; it earns its keep by pointing at the refactor that stops the next six
+defects. Score it with `severity-rubric`, by consequence, not by how tangled the
+graph looked.
+
+## What is not yours
+
+The HTTP contract is CONDUIT's, the schema is VAULT's, the UI is SURFACE's,
+security is WARDEN's, and the map itself is CARTOGRAPHER's. Two services sharing
+a table is yours when the defect is the boundary; it is VAULT's when the defect
+is the constraint or the query. An unauthenticated endpoint you notice while
+tracing callers belongs to WARDEN — report the orphaning, not the exploit.