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

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

@@ -17,7 +17,7 @@ first, and update the plan's milestone table when work lands.
 uv venv && uv pip install -e ".[dev]"    # setup
 npx playwright install chromium          # only for UI (SURFACE) runs
 
-pytest                                   # 649 tests, no API calls, no network
+pytest                                   # 686 tests, no API calls, no network
 pytest tests/test_guardrails.py::test_name -x
 pytest -m docker                         # needs target-app running
 pytest -m 'llm or github or jira'        # tiers excluded by default in pyproject
@@ -27,6 +27,8 @@ qaas doctor --target corvid              # what a target makes possible
 qaas run --mode pr-check --dry-run       # renders each agent's options, no API call
 qaas run --mode nightly --only CONDUIT   # real run, costs money
 qaas runs / qaas show <run-id> / qaas map
+qaas trace <run-id> --follow --quiet     # watch a live run's decisions
+qaas board                               # find-or-create this target's Jira board
 qaas trace <run-id> [--agent NAME] [--kind KIND] [--json]   # the ledger, readably
 qaas score [<run-id>]                    # recall/precision against the golden ledger
 qaas sweep                               # run + score + fail below the precision gate
@@ -139,6 +141,39 @@ one stdio subprocess, declared in `registry.STDIO_SERVERS`.
 Tool results use `ok()`/`err()` from `mcp/context.py`: errors are **returned, not
 raised**, so the agent reads the reason and corrects itself.
 
+### One Jira view per repository, not one project
+
+Every ticket carries `repo-<target>`, stamped by `mcp/tracker.py` rather than
+asked of CLERK. `JiraTracker.ensure_repo_board` finds-or-creates a saved filter
+over exactly that label, plus a board over the filter **only where one can
+render**; `cli._ensure_board` calls it at the top of every Jira-backed run. A
+*project* per repo would need admin rights a bot account rarely has; a filter
+needs none.
+
+**A 200 from the board API is not a working board.** Team-managed (next-gen)
+projects own their board; `POST /rest/agile/1.0/board` over a filter still
+returns 201, and the UI has no page for the result — every candidate URL 404s.
+`is_team_managed` is the authoritative gate and skips the attempt there.
+`_board_is_reachable` (no `location` -> unusable) is a *second, weaker* check
+applied **only to a board that already existed**: Jira populates `location`
+asynchronously, so a board read back immediately after creation reports None
+whatever its project, and gating a fresh board on it rejected good boards.
+Location is necessary, not sufficient — a team-managed board eventually reports
+one and still will not render.
+
+`board_url` never assembles a URL: `/secure/RapidBoard.jspa?rapidView=<id>` is
+followed and whatever Jira resolves it to is the answer (a company-managed
+board's path carries a `/c/` segment that a hand-built URL missed).
+
+**A reused filter is only the right filter if its JQL still matches.** Filters
+are found by name and the name does not encode the project, so repointing
+`JIRA_PROJECT_KEY` left the filter scoped to the old project — tickets filed
+correctly and were invisible on the view. `ensure_repo_board` repairs the JQL;
+`filter/search` is expanded with `jql` so the check costs no extra round trip.
+
+None of this can fail a run — the filter is the fallback and the findings matter
+more than the view.
+
 ### Targets make it portable
 
 `target.py` / `config/targets/*.yaml`. `environment.mode` is the load-bearing
@@ -164,7 +199,10 @@ two sets of rules about where someone else's code lands on disk.
 
 ### Runtime state
 
-`.qaas/` (gitignored): `runs/<id>/ledger.jsonl` (append-only audit trail —
+`.qaas/` (gitignored): `.env` (credentials, read before every command; anything
+already exported wins, and `QAAS_ENV_FILE=` disables the whole mechanism — the
+test suite sets that so a developer's `.env` cannot make the suite pass);
+`runs/<id>/ledger.jsonl` (append-only audit trail —
 every tool call, denial and escalation), `envelopes/`, `artifacts/`, `results/`;
 plus a versioned `system-map/` shared across runs and pinned per run so a bad map
 cannot half-propagate. Evidence is referenced by `artifact://<run>/<name>` uris;

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qaas-python
-Version: 0.3.1
+Version: 0.4.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
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/qaas-python?color=3776AB&logo=python&logoColor=white)](https://pypi.org/project/qaas-python/)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![CI](https://github.com/allaabdella2-us/qa-multi-agent-system/actions/workflows/ci.yml/badge.svg)](https://github.com/allaabdella2-us/qa-multi-agent-system/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-649%20offline-success)](#-contributing)
+[![Tests](https://img.shields.io/badge/tests-686%20offline-success)](#-contributing)
 [![Built on](https://img.shields.io/badge/built%20on-Claude%20Agent%20SDK-D97757)](https://docs.claude.com/en/api/agent-sdk/overview)
 
 [Quickstart](#-quickstart-in-60-seconds) · [Your repo](#-point-it-at-your-repository) · [Jira](#-file-into-jira) · [Architecture](ARCHITECTURE.md)
@@ -75,7 +75,7 @@ Nothing crosses between the loops except a ticket — which is also the audit tr
 
 | | |
 |---|---|
-| 🧠 **The orchestrator is code, not a prompt** | A model cannot enforce a budget it is spending. Phase ordering, concurrency, retries and the loop breakers live in `conductor.py`. That is also why **649 tests run offline, free, with no API key.** |
+| 🧠 **The orchestrator is code, not a prompt** | A model cannot enforce a budget it is spending. Phase ordering, concurrency, retries and the loop breakers live in `conductor.py`. That is also why **686 tests run offline, free, with no API key.** |
 | 🧱 **Every agent is its own `query()`** | Not subagents of a shared parent. Each gets a real context boundary, an enforceable tool allowlist, and its own cost number. |
 | 🔬 **Evidence or it did not happen** | `has_evidence()` and `is_fileable()` are methods on the envelope model, not requests in a prompt. An agent cannot talk its way past them. |
 | 📊 **Measured, not asserted** | A deliberately buggy demo app ships with a golden ledger of **16 seeded defects + 4 planted non-defects**. `qaas score` reports recall *and* precision, so a prompt change has a number attached. |
@@ -189,6 +189,10 @@ QAAS_TRACKER=jira qaas run --mode nightly
 maps your workflow statuses, and prints the exact JSON it *would* POST. **It
 creates nothing.**
 
+Tired of four exports in every new shell? Put them in a `.env` — `.qaas/.env` is
+already gitignored — and every command reads it. **Anything you export wins over
+the file**, so a stale `.env` can never redirect a run.
+
 - 🔁 **Dedupe across runs** — tickets carry a `qaas-fp-<fingerprint>` label, so the next run recognises an already-filed defect and increments its occurrence count instead of filing again.
 - 🔐 **Security findings are refused** unless `JIRA_SECURITY_PROJECT_KEY` is set. A vulnerability in a project the whole company can read is a disclosure with no undo.
 
@@ -197,6 +201,46 @@ creates nothing.**
 > `.qaas/tickets/` so you can read what *would* be filed. Switch per shell with
 > `QAAS_TRACKER=jira`.
 
+### 📌 A view per repository, made for you
+
+Point it at a new repository and it provisions that repository's own Jira view
+before the first agent starts — so there is something to watch *during* the run,
+not a report afterwards.
+
+```console
+$ QAAS_TRACKER=jira qaas run --repo https://github.com/acme/checkout.git --mode nightly
+target: checkout (none)
+filter created — https://you.atlassian.net/issues/?filter=10001
+every ticket from this run carries the label repo-checkout
+```
+
+Every ticket the system files carries `repo-<target>`, stamped in code rather
+than asked of an agent. A **saved filter** over exactly that label is the
+per-repository view, and on a company-managed project a **board** is built over
+the filter too.
+
+```bash
+qaas board                  # find or create this target's view
+qaas board --no-create      # show the label and JQL, touch nothing
+```
+
+> [!NOTE]
+> **Not a project per repository.** Creating a Jira project needs administrator
+> rights a bot account rarely has, and a project per repository is unmanageable
+> by the tenth one. A filter needs no special grant.
+>
+> **Not always a board, either.** Team-managed (next-gen) projects own their own
+> board and cannot have a second one built over a filter — Jira's API will
+> happily create one and give it no page in the UI. So the project's style is
+> checked first, and on a team-managed project you get the filter alone. You are
+> told which you got, and the link always opens. Point `JIRA_PROJECT_KEY` at a
+> **company-managed** project and you get a real board per repository, with
+> To Do / In Progress / Done.
+
+Run it twice on the same repository and it **reuses** what is there. A run is
+never failed over this: a run that found nine defects and could not make a view
+has still done its job.
+
 ---
 
 ## 🔌 Bring your own MCP servers
@@ -281,12 +325,31 @@ $ qaas trace run-20260908T182034-c6ed26
 ```
 
 ```bash
+qaas trace <run-id> --follow                       # watch a run as it happens
+qaas trace <run-id> --quiet                        # decisions only, no file reads
 qaas trace <run-id> --agent proof --kind verdict   # filter
 qaas trace <run-id> --json                         # export
 qaas show <run-id>                                 # mode, commit, tickets, escalations
 qaas runs                                          # everything that ever ran
 ```
 
+**Watch a run live.** `--follow` tails the ledger of a run in progress — start it
+in a second terminal the moment a run begins, or even before, and it waits.
+
+```console
+$ qaas trace run-20260909T163240-83b11c --follow --quiet
+following run-20260909T163240-83b11c — ctrl-c to stop
+16:32:40 -            run_started      mode=pr-check  agents=[8]  target_sha=da19f406
+16:32:40 CARTOGRAPHER agent_started    model=claude-sonnet-5
+16:32:46 CARTOGRAPHER denial           tool=Bash  reason=Bash is not in CARTOGRAPHER's
+                                       tool allowlist (Read, Grep, Glob).
+16:36:11 KEYSTONE     envelope         severity=major  domain=architecture
+16:41:03 CLERK        ticket           action=created  key=QA-118  severity=major
+```
+
+Drop `--quiet` to see every file the agents read, one line each. Combine with
+`--agent` and `--kind` to watch one agent, or only the verdicts.
+
 Runs are pinned to the **commit of the target** they examined, so a finding can
 be replayed against the tree that produced it.
 
@@ -310,44 +373,28 @@ the refusal and adapts.
 
 ---
 
-## 📈 Benchmarks, honestly
+## 📈 How you know it works
 
-Against the bundled demo app and its golden ledger:
+`qaas` ships with a **deliberately buggy demo app** and a golden ledger recording
+every defect seeded into it — plus **planted non-defects**: correct-but-suspicious
+code that a careless reader would report.
 
-Two runs against the demo app, scored automatically:
-
-| metric | run A (full loop) | run B (discovery only) |
-|---|--:|--:|
-| 🎯 recall | **81%** — 13 of 16 | **69%** — 11 of 16 |
-| 🔇 precision | **100%** — 0 FP | **92%** — 1 FP |
-| 🏷️ severity agreement | **100%** | **100%** |
-
-**Both numbers are shown on purpose.** A single figure would be the flattering
-one, and it would not survive contact with a second run. These are stochastic
-agents: the two runs did not find the same 11–13 defects — run B caught a
-contrast failure run A missed, and missed three run A found. Expect variance of
-this order.
+```bash
+cd target-app && docker compose up -d
+qaas run --mode nightly && qaas score
+```
 
-The ledger's `not_defects` section plants **correct-but-suspicious** code, so
-precision is measured rather than assumed.
+`qaas score` reports recall, precision and severity agreement against that
+ledger. That matters more than any number this page could print: it means a
+change to a prompt, a threshold or a model has **a measurement attached** rather
+than an opinion.
 
 > [!CAUTION]
-> **Treat this as a floor, not a proof.** Seeded defects are easier than real
-> ones and the system was calibrated against them. Two runs is not a sample.
-> These numbers show the loop works end to end and does not spray false
-> positives — not that it will find the hard bug in your codebase.
-
----
-
-## 📋 Status
-
-Honest about what exists:
-
-- ✅ **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.
+> **Seeded defects are easier than real ones**, and this system was calibrated
+> against them. A benchmark shows the loop works end to end and does not spray
+> false positives. It does not show that it will find the hard bug in your
+> codebase. Run it on something you know well and judge it on what it finds
+> there.
 
 ---
 
@@ -358,7 +405,7 @@ git clone https://github.com/allaabdella2-us/qa-multi-agent-system
 cd qa-multi-agent-system
 uv venv && uv pip install -e ".[dev]"
 
-pytest                 # 649 tests, offline, free — keep it that way
+pytest                 # 686 tests, offline, free — keep it that way
 pytest -m docker       # needs: cd target-app && docker compose up -d
 qaas validate
 ```

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

@@ -10,7 +10,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/qaas-python?color=3776AB&logo=python&logoColor=white)](https://pypi.org/project/qaas-python/)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![CI](https://github.com/allaabdella2-us/qa-multi-agent-system/actions/workflows/ci.yml/badge.svg)](https://github.com/allaabdella2-us/qa-multi-agent-system/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-649%20offline-success)](#-contributing)
+[![Tests](https://img.shields.io/badge/tests-686%20offline-success)](#-contributing)
 [![Built on](https://img.shields.io/badge/built%20on-Claude%20Agent%20SDK-D97757)](https://docs.claude.com/en/api/agent-sdk/overview)
 
 [Quickstart](#-quickstart-in-60-seconds) · [Your repo](#-point-it-at-your-repository) · [Jira](#-file-into-jira) · [Architecture](ARCHITECTURE.md)
@@ -45,7 +45,7 @@ Nothing crosses between the loops except a ticket — which is also the audit tr
 
 | | |
 |---|---|
-| 🧠 **The orchestrator is code, not a prompt** | A model cannot enforce a budget it is spending. Phase ordering, concurrency, retries and the loop breakers live in `conductor.py`. That is also why **649 tests run offline, free, with no API key.** |
+| 🧠 **The orchestrator is code, not a prompt** | A model cannot enforce a budget it is spending. Phase ordering, concurrency, retries and the loop breakers live in `conductor.py`. That is also why **686 tests run offline, free, with no API key.** |
 | 🧱 **Every agent is its own `query()`** | Not subagents of a shared parent. Each gets a real context boundary, an enforceable tool allowlist, and its own cost number. |
 | 🔬 **Evidence or it did not happen** | `has_evidence()` and `is_fileable()` are methods on the envelope model, not requests in a prompt. An agent cannot talk its way past them. |
 | 📊 **Measured, not asserted** | A deliberately buggy demo app ships with a golden ledger of **16 seeded defects + 4 planted non-defects**. `qaas score` reports recall *and* precision, so a prompt change has a number attached. |
@@ -159,6 +159,10 @@ QAAS_TRACKER=jira qaas run --mode nightly
 maps your workflow statuses, and prints the exact JSON it *would* POST. **It
 creates nothing.**
 
+Tired of four exports in every new shell? Put them in a `.env` — `.qaas/.env` is
+already gitignored — and every command reads it. **Anything you export wins over
+the file**, so a stale `.env` can never redirect a run.
+
 - 🔁 **Dedupe across runs** — tickets carry a `qaas-fp-<fingerprint>` label, so the next run recognises an already-filed defect and increments its occurrence count instead of filing again.
 - 🔐 **Security findings are refused** unless `JIRA_SECURITY_PROJECT_KEY` is set. A vulnerability in a project the whole company can read is a disclosure with no undo.
 
@@ -167,6 +171,46 @@ creates nothing.**
 > `.qaas/tickets/` so you can read what *would* be filed. Switch per shell with
 > `QAAS_TRACKER=jira`.
 
+### 📌 A view per repository, made for you
+
+Point it at a new repository and it provisions that repository's own Jira view
+before the first agent starts — so there is something to watch *during* the run,
+not a report afterwards.
+
+```console
+$ QAAS_TRACKER=jira qaas run --repo https://github.com/acme/checkout.git --mode nightly
+target: checkout (none)
+filter created — https://you.atlassian.net/issues/?filter=10001
+every ticket from this run carries the label repo-checkout
+```
+
+Every ticket the system files carries `repo-<target>`, stamped in code rather
+than asked of an agent. A **saved filter** over exactly that label is the
+per-repository view, and on a company-managed project a **board** is built over
+the filter too.
+
+```bash
+qaas board                  # find or create this target's view
+qaas board --no-create      # show the label and JQL, touch nothing
+```
+
+> [!NOTE]
+> **Not a project per repository.** Creating a Jira project needs administrator
+> rights a bot account rarely has, and a project per repository is unmanageable
+> by the tenth one. A filter needs no special grant.
+>
+> **Not always a board, either.** Team-managed (next-gen) projects own their own
+> board and cannot have a second one built over a filter — Jira's API will
+> happily create one and give it no page in the UI. So the project's style is
+> checked first, and on a team-managed project you get the filter alone. You are
+> told which you got, and the link always opens. Point `JIRA_PROJECT_KEY` at a
+> **company-managed** project and you get a real board per repository, with
+> To Do / In Progress / Done.
+
+Run it twice on the same repository and it **reuses** what is there. A run is
+never failed over this: a run that found nine defects and could not make a view
+has still done its job.
+
 ---
 
 ## 🔌 Bring your own MCP servers
@@ -251,12 +295,31 @@ $ qaas trace run-20260908T182034-c6ed26
 ```
 
 ```bash
+qaas trace <run-id> --follow                       # watch a run as it happens
+qaas trace <run-id> --quiet                        # decisions only, no file reads
 qaas trace <run-id> --agent proof --kind verdict   # filter
 qaas trace <run-id> --json                         # export
 qaas show <run-id>                                 # mode, commit, tickets, escalations
 qaas runs                                          # everything that ever ran
 ```
 
+**Watch a run live.** `--follow` tails the ledger of a run in progress — start it
+in a second terminal the moment a run begins, or even before, and it waits.
+
+```console
+$ qaas trace run-20260909T163240-83b11c --follow --quiet
+following run-20260909T163240-83b11c — ctrl-c to stop
+16:32:40 -            run_started      mode=pr-check  agents=[8]  target_sha=da19f406
+16:32:40 CARTOGRAPHER agent_started    model=claude-sonnet-5
+16:32:46 CARTOGRAPHER denial           tool=Bash  reason=Bash is not in CARTOGRAPHER's
+                                       tool allowlist (Read, Grep, Glob).
+16:36:11 KEYSTONE     envelope         severity=major  domain=architecture
+16:41:03 CLERK        ticket           action=created  key=QA-118  severity=major
+```
+
+Drop `--quiet` to see every file the agents read, one line each. Combine with
+`--agent` and `--kind` to watch one agent, or only the verdicts.
+
 Runs are pinned to the **commit of the target** they examined, so a finding can
 be replayed against the tree that produced it.
 
@@ -280,44 +343,28 @@ the refusal and adapts.
 
 ---
 
-## 📈 Benchmarks, honestly
+## 📈 How you know it works
 
-Against the bundled demo app and its golden ledger:
+`qaas` ships with a **deliberately buggy demo app** and a golden ledger recording
+every defect seeded into it — plus **planted non-defects**: correct-but-suspicious
+code that a careless reader would report.
 
-Two runs against the demo app, scored automatically:
-
-| metric | run A (full loop) | run B (discovery only) |
-|---|--:|--:|
-| 🎯 recall | **81%** — 13 of 16 | **69%** — 11 of 16 |
-| 🔇 precision | **100%** — 0 FP | **92%** — 1 FP |
-| 🏷️ severity agreement | **100%** | **100%** |
-
-**Both numbers are shown on purpose.** A single figure would be the flattering
-one, and it would not survive contact with a second run. These are stochastic
-agents: the two runs did not find the same 11–13 defects — run B caught a
-contrast failure run A missed, and missed three run A found. Expect variance of
-this order.
+```bash
+cd target-app && docker compose up -d
+qaas run --mode nightly && qaas score
+```
 
-The ledger's `not_defects` section plants **correct-but-suspicious** code, so
-precision is measured rather than assumed.
+`qaas score` reports recall, precision and severity agreement against that
+ledger. That matters more than any number this page could print: it means a
+change to a prompt, a threshold or a model has **a measurement attached** rather
+than an opinion.
 
 > [!CAUTION]
-> **Treat this as a floor, not a proof.** Seeded defects are easier than real
-> ones and the system was calibrated against them. Two runs is not a sample.
-> These numbers show the loop works end to end and does not spray false
-> positives — not that it will find the hard bug in your codebase.
-
----
-
-## 📋 Status
-
-Honest about what exists:
-
-- ✅ **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.
+> **Seeded defects are easier than real ones**, and this system was calibrated
+> against them. A benchmark shows the loop works end to end and does not spray
+> false positives. It does not show that it will find the hard bug in your
+> codebase. Run it on something you know well and judge it on what it finds
+> there.
 
 ---
 
@@ -328,7 +375,7 @@ git clone https://github.com/allaabdella2-us/qa-multi-agent-system
 cd qa-multi-agent-system
 uv venv && uv pip install -e ".[dev]"
 
-pytest                 # 649 tests, offline, free — keep it that way
+pytest                 # 686 tests, offline, free — keep it that way
 pytest -m docker       # needs: cd target-app && docker compose up -d
 qaas validate
 ```

{qaas_python-0.3.1 → qaas_python-0.4.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.3.1"
+version = "0.4.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"