qaas-python 0.2.0__tar.gz → 0.2.2__tar.gz

{qaas_python-0.2.0 → qaas_python-0.2.2}/.gitignore

@@ -19,3 +19,6 @@ dist/
 
 # Agent evidence screenshots land here because put_artifact takes only text.
 target-app/*.png
+
+# Personal notes, not published.
+tutorial/

{qaas_python-0.2.0 → qaas_python-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qaas-python
-Version: 0.2.0
+Version: 0.2.2
 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

{qaas_python-0.2.0 → qaas_python-0.2.2}/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.0"
+version = "0.2.2"
 description = "A multi-agent QA system: finds real defects, reproduces them, files tickets, fixes them, and proves the fix"
 readme = "README.md"
 license = "MIT"
@@ -63,7 +63,7 @@ include = [
     # (src/qaas/plugin/skills), so "src/" already carries them. The old
     # ".claude/skills/" entry outlived the directory it named -- hatchling
     # ignores a missing path, so it broke nothing and simply misled.
-    "src/", "config/", "target-app/", "tests/", "tutorial/",
+    "src/", "config/", "target-app/", "tests/",
     "README.md", "LICENSE", "ARCHITECTURE.md", "CLAUDE.md", "BUILD_PLAN.md",
     "pyproject.toml",
 ]

{qaas_python-0.2.0 → qaas_python-0.2.2}/src/qaas/cli.py

@@ -449,16 +449,14 @@ def doctor(
 
 
 def _agent_usable(spec, caps: dict[str, bool]) -> bool:
-    """Whether an agent can do useful work with the capabilities available.
+    """Delegates to `target.agent_usable`, which the conductor also uses.
 
-    SURFACE without a browser-reachable UI has nothing to do; the rest can all
-    contribute from static analysis alone, at lower confidence.
+    Two copies of this rule meant `qaas doctor` could report an agent unusable
+    while a run dispatched it anyway.
     """
-    if spec.name == "SURFACE":
-        return caps["live_ui"]
-    if spec.name == "PROOF":
-        return caps["live_api"] or caps["static_analysis"]
-    return True
+    from qaas.target import agent_usable
+
+    return agent_usable(spec.name, caps)
 
 
 @app.command()

{qaas_python-0.2.0 → qaas_python-0.2.2}/src/qaas/conductor.py

@@ -25,6 +25,7 @@ from typing import Any, Callable
 
 from qaas.config import AgentSpec, SystemConfig, load_config
 from qaas.envelope import DefectEnvelope
+from qaas.target import agent_usable
 from qaas.mcp.context import ToolContext
 from qaas.runner import RunOutcome, run_agent
 from qaas.store import RunStore, SystemMapStore
@@ -269,6 +270,27 @@ class Conductor:
     async def _phase_discover(self, specs, store, budget, report, mode, map_version) -> None:
         """Discovery agents are independent. Run them concurrently, bounded."""
         discovery = [s for name, s in specs.items() if s.layer == "discovery"]
+
+        # Skip agents this target cannot support. `qaas doctor` has always
+        # reported these ("agents that cannot: SURFACE"), but nothing acted on
+        # it, so a run against a target with no reachable UI would still
+        # dispatch SURFACE and spend its entire budget hunting a browser that
+        # was never there. Being told an agent cannot work and then watching it
+        # run is worse than not being told.
+        profile = getattr(self.config, "profile", None)
+        if profile is not None:
+            caps = profile.capabilities()
+            unusable = [s for s in discovery if not agent_usable(s.name, caps)]
+            if unusable:
+                discovery = [s for s in discovery if s not in unusable]
+                store.log(
+                    "skipped",
+                    reason="target cannot support these agents",
+                    agents=[s.name for s in unusable],
+                )
+                for spec in unusable:
+                    self._emit("skipped", agent=spec.name, reason="target lacks the capability")
+
         if not discovery:
             return
 

{qaas_python-0.2.0 → qaas_python-0.2.2}/src/qaas/target.py

@@ -259,3 +259,21 @@ def load_target(name: str, targets_dir: Path | str = "config/targets") -> Target
 # directory is the bug that hid `<project>/config/targets/` the moment anything
 # wrote into `.qaas/config/targets/`; profiles layer across every config
 # directory, and `config.target_files(dirs)` is the one place that knows it.
+
+
+def agent_usable(agent_name: str, caps: dict[str, bool]) -> bool:
+    """Whether an agent can do useful work with the capabilities available.
+
+    Lives here, beside `capabilities()`, because it has two callers that must
+    agree: `qaas doctor` reports it, and the conductor acts on it. They did not
+    agree for a while -- doctor would say "agents that cannot: SURFACE" and then
+    a run would dispatch SURFACE anyway and spend its whole budget looking for a
+    browser that was never there. Being told an agent cannot work and then
+    watching it run is worse than not being told.
+
+    Everything except SURFACE can contribute from static analysis alone, at
+    lower confidence. SURFACE without a reachable UI has nothing to do at all.
+    """
+    if agent_name == "SURFACE":
+        return caps.get("live_ui", False)
+    return True

{qaas_python-0.2.0 → qaas_python-0.2.2}/tests/test_conductor.py

@@ -561,3 +561,23 @@ async def test_a_new_discovery_agent_runs_without_a_hand_written_task(cfg, tmp_p
     report = await make_conductor(cfg, tmp_path).run("nightly")
     ran = {name for name, _ in calls}
     assert {"VAULT", "WARDEN"} <= ran, f"a config-only agent was skipped: {sorted(ran)}"
+
+
+async def test_an_agent_the_target_cannot_support_is_not_dispatched(cfg, tmp_path, fake_agents):
+    """`qaas doctor` has always reported "agents that cannot: SURFACE" for a
+    target with no reachable UI. Nothing acted on it: the run dispatched SURFACE
+    anyway and spent its budget looking for a browser that was never there.
+
+    Being told an agent cannot work and then watching it run is worse than not
+    being told, which is why this asserts the dispatch, not the report.
+    """
+    calls, behaviour = fake_agents
+    from qaas.target import Environment, TargetProfile
+
+    static_only = TargetProfile(name="static", root=".", environment=Environment(mode="none"))
+    cfg2 = cfg.model_copy(update={"profile": static_only})
+
+    await make_conductor(cfg2, tmp_path).run("pr-check")
+    ran = {name for name, _ in calls}
+    assert "SURFACE" not in ran, "dispatched SURFACE at a target with no UI"
+    assert "CONDUIT" in ran, "static analysis agents must still run"

qaas_python-0.2.0/tutorial/01-code-structure.md

@@ -1,251 +0,0 @@
-# 01 — Code structure and how the pieces relate
-
-Where every module lives, what it owns, and which module is allowed to know about
-which. Read this first; the other files assume it.
-
----
-
-## The one-line version
-
-```
-qaas <command>  →  cli.py  →  conductor.py  →  runner.py  →  claude_agent_sdk.query()
-                                    ↑              ↑
-                              a state machine   one agent, one call
-```
-
-Everything else exists to serve those four files.
-
----
-
-## The whole package
-
-```
-src/qaas/
-├── cli.py           1564   entry point — 13 commands
-├── conductor.py      527   THE STATE MACHINE: phases, budget, concurrency, loops
-├── runner.py         192   invokes ONE agent, records what it cost
-├── registry.py       465   turns an agent's YAML into SDK options
-├── guardrails.py     421   the permission matrix, enforced in code
-├── config.py         407   loads and validates config/
-├── tasks.py          361   builds the per-run task string for each agent
-├── paths.py          317   where config, prompts and skills are found
-├── store.py          290   run ledger, artifacts, versioned system map
-├── envelope.py       290   DefectEnvelope — the only inter-agent type
-├── trace.py          270   the read side of the ledger
-├── target.py         261   target profiles — what makes it portable
-├── scorecard.py      425   recall/precision against the golden ledger
-├── discover.py       227   guesses a target profile for `qaas init`
-├── sdk_compat.py      52   fails loudly when the SDK renames a hook event
-│
-├── prompts/                one .md per agent + _shared.md appended to all
-├── plugin/                 the skills, shipped as a Claude Code plugin
-│   ├── .claude-plugin/plugin.json
-│   └── skills/<30 dirs>/SKILL.md
-├── defaults/config/        system.yaml + agents/*.yaml that ship in the wheel
-├── mcp/                    seven in-process tool servers
-└── adapters/               tracker (local | jira), vcs (local | github)
-```
-
-Line counts are real, from `wc -l`. They are a rough guide to where the weight
-sits: `cli.py` and `adapters/tracker.py` are the two biggest files and are mostly
-surface area, not logic.
-
----
-
-## The dependency graph
-
-This is the actual import graph, extracted from the source. **Arrows point at what
-a module is allowed to know about.** Nothing points back up.
-
-```
-                         cli.py
-                           │  (config, paths, store, trace)
-                           ▼
-                      conductor.py ────────────┐
-                           │                   │
-        (config, envelope, │ store,            │
-         mcp.context)      ▼                   │
-                       runner.py               │
-                           │  (registry)       │
-                           ▼                   │
-                      registry.py              │
-                           │  (config,         │
-                           │   guardrails,     │
-                           │   sdk_compat)     │
-                           ▼                   │
-                      guardrails.py            │
-                           │  (mcp.context)    │
-                           ▼                   ▼
-                        config.py  ────────► store.py
-                           │  (target)          │  (envelope)
-                           ▼                    ▼
-                       target.py  ─────────► envelope.py
-                           │  (paths)       (imports nothing)
-                           ▼
-                        paths.py
-                     (imports nothing)
-```
-
-Two facts fall out of this and are worth internalising:
-
-**`envelope.py` and `paths.py` import nothing from the package.** They are the
-foundation. `envelope.py` is the contract every agent speaks; `paths.py` is how
-the package finds its own resources. Both must be understandable on their own,
-and both are heavily tested in isolation.
-
-**`registry.py` imports `config.py`, so `config.py` cannot import `registry.py`.**
-There is a real consequence: the validator in `config.py` that checks every MCP
-server an agent names actually exists has to import `registry` *inside the
-function*. The comment there says so.
-
----
-
-## What each module owns
-
-| module | owns | does **not** own |
-|---|---|---|
-| `cli.py` | argument parsing, printing, exit codes | any decision about a run |
-| `conductor.py` | phase order, budget, concurrency, escalation, loop bounds | how one agent runs |
-| `runner.py` | one `query()`, one `AgentResult` | whether that agent should run |
-| `registry.py` | assembling `ClaudeAgentOptions` | what the agent then does |
-| `guardrails.py` | allow/deny for every tool call | logging policy (it delegates to the store) |
-| `envelope.py` | the shape of a finding, and its two gates | where findings are stored |
-| `store.py` | the ledger, artifacts, the system map | what any entry means |
-| `config.py` | loading and validating YAML | where the YAML lives (that is `paths.py`) |
-| `paths.py` | config/prompt/skill/state resolution | reading any of them |
-
----
-
-## The two decisions that explain the shape
-
-### 1. CONDUCTOR is Python, not a prompt
-
-The design document describes an orchestrator agent. It is implemented as an
-ordinary state machine because **a model cannot enforce a budget it is itself
-spending.**
-
-Everything that must be true regardless of what a model decides lives in
-`conductor.py`: phase ordering, the concurrency cap, retries, escalation, and the
-loop bounds. That is also why 649 tests run offline with no API key — the
-interesting logic is not behind a model call.
-
-```python
-# src/qaas/conductor.py — the five phases, in order
-map_version = await self._phase_map(specs, store, budget, report)
-await self._phase_discover(specs, store, budget, report, mode, map_version)
-await self._phase_reproduce(specs, store, budget, report, map_version)
-if run_mode.files_tickets:
-    await self._phase_file(...)
-await self._phase_verify(...)
-```
-
-### 2. Every agent is its own top-level `query()`
-
-Not SDK subagents under a shared parent. Nesting would pool cost into one number
-and blur the per-agent tool allowlist that the whole permission model depends on.
-
-One `query()` per agent gives three things that matter:
-
-- a real context boundary — CONDUIT cannot see what SURFACE read
-- an enforceable allowlist — the tools are set per call, not per session
-- a per-agent `total_cost_usd`, straight off the `ResultMessage`
-
-`AgentDefinition` / `agents=` remains available for *intra-agent* fan-out.
-
----
-
-## Agents are data, not code
-
-An agent is **a prompt plus a YAML file**. That is the whole definition.
-
-```
-src/qaas/prompts/CONDUIT.md              role and standards
-src/qaas/defaults/config/agents/conduit.yaml   model, budget, tools, skills, policy
-```
-
-Adding an agent should require **no change** to `conductor.py`, `runner.py`,
-`registry.py` or `guardrails.py`. A change to one of those while adding an agent
-is a sign something is wrong.
-
-Where each kind of instruction belongs — this split is easy to get wrong and the
-codebase is strict about it:
-
-| what | where | why |
-|---|---|---|
-| role, standards | `prompts/<AGENT>.md` | stable across every run |
-| house rules for all agents | `prompts/_shared.md` | appended to every prompt, not copy-pasted into eight |
-| **procedure** | `plugin/skills/<name>/SKILL.md` | loaded on demand, shared between agents |
-| the per-run **task** | `tasks.py` | which app, which environment, which finding |
-| **enforcement** | `guardrails.py` | a prompt is a request; code is a rule |
-
-> **Nothing in `tasks.py` or a prompt may name a specific application.** A prompt
-> that mentions one repo's layout works exactly once. This rule has been broken
-> and fixed: two `contract_diff` tool descriptions once said
-> `target-app/openapi.yaml` directly to the model.
-
----
-
-## The eight agents
-
-| agent | layer | does |
-|---|---|---|
-| CARTOGRAPHER | map | services, routes, schema, ownership → `system-map.json` |
-| CONDUIT | discovery | API contract drift; ships a failing contract test |
-| 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, leaked internals |
-| 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 `fix/*` branch |
-| ARBITER | remediation | adversarial review: APPROVE / REQUEST_CHANGES / ESCALATE |
-| PROOF | verify | re-runs the original test → VERIFIED / NOT_FIXED / REGRESSED |
-
-The design names 16. Ten are built; CONDUCTOR is the state machine rather than an
-agent; five further discovery specialists are designed and not written.
-
-VAULT and WARDEN are worth noting for *how* they were added: a prompt file and a
-YAML file each, with no Python. That is the architecture's central claim, and it
-was not quite true until they tested it -- `_phase_discover` dispatched from a
-closed dict of task builders, so a new discovery agent validated, assembled,
-appeared in `--dry-run`, and was then silently skipped with `no task builder`.
-There is a generic discovery task now, and a test that asserts a config-only
-agent actually *runs*.
-
----
-
-## Runtime state
-
-```
-.qaas/                          (gitignored)
-├── config/                     your config, if you ran `qaas init`
-├── runs/<run-id>/
-│   ├── ledger.jsonl            append-only: every tool call, denial, escalation
-│   ├── envelopes/*.json        the findings
-│   ├── artifacts/              screenshots, logs, traces
-│   └── results/*.json          per-agent cost, turns, duration
-├── system-map/                 versioned, shared across runs, pinned per run
-├── memory.db                   SQLite: defect fingerprints, for dedupe
-└── tickets/*.json              the local tracker
-```
-
-The ledger is not only an audit trail — the conductor **reads it back** for
-control flow. `_latest_verdict`, `_latest_review` and `_branch_written_since` all
-query it. That is unusual and it is deliberate: a verdict is a typed ledger entry,
-never parsed out of an agent's prose. See [02 — how agents
-communicate](02-how-agents-communicate.md).
-
----
-
-## Reading order for a newcomer
-
-1. `qaas validate` then `qaas run --mode pr-check --dry-run` — watch the machine
-   describe itself, for free
-2. `envelope.py` — the contract everything moves
-3. `conductor.py::run` — the five phases
-4. `defaults/config/agents/conduit.yaml` + `prompts/CONDUIT.md` — what an agent *is*
-5. `guardrails.py::check` — the one function both enforcement points call
-6. `.qaas/runs/<id>/ledger.jsonl` from a real run, or `qaas trace <id>`
-
----
-
-**Next:** [02 — How agents communicate](02-how-agents-communicate.md)