qaas-python 0.1.0__py3-none-any.whl

qaas/plugin/skills/repro-minimisation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: repro-minimisation
+description: >
+  Reduce a reported defect to the shortest sequence that still triggers it.
+  TRIGGER - read BEFORE attempting to reproduce any finding, and whenever the
+  task mentions reproduction, repro steps, minimisation, or 'can you make this
+  happen again'. Do NOT record the reporter's steps as the reproduction without
+  reducing them. SKIP only when no reproduction is being produced.
+---
+
+# Minimising a reproduction
+
+The minimal reproduction is the most valuable artifact this system produces. It is read by whoever fixes the defect, becomes the acceptance criterion, and survives as the regression test.
+
+## Reproduce first, minimise second
+
+Get it happening reliably at least twice before removing anything. Minimising something you have seen once produces a shorter sequence that reproduces nothing, and you cannot tell whether your last cut fixed it or it was never deterministic.
+
+## Then cut, one at a time
+
+Remove one step, re-run, check the defect still appears. If it vanishes, put the step back — it was necessary. One change per iteration: cut two and you learn nothing about either.
+
+Cut in this order, because it removes the most noise per step:
+1. Steps before the defect's first observable symptom
+2. Fields, items, and records beyond the minimum
+3. Role and permission complexity — does it need admin, or any user?
+4. Seeded data beyond what the steps touch
+
+## What must survive
+
+The reproduction must state the environment exactly: branch, fixture, flags, role, and clock if it matters. "Log in and go to orders" is not a reproduction — as whom, with what data?
+
+If it only reproduces with a specific fixture, that is not a weakness to hide; it is a fact about the defect and possibly the most informative thing you learned.
+
+## Boundaries are the signal
+
+When the defect appears with one item and not two, **that is the finding**, and it is far more useful than the symptom. Record the boundary explicitly. It usually names the bug — an off-by-one in a guard, an empty-case branch, a comparison that should have been `>=`.
+
+## Honest outcomes
+
+Not reproducible is a real, useful verdict, and delivering it is the job working correctly. Passing through a finding you could not reproduce costs the team more than dropping a real defect: it teaches them that tickets from this system may be fiction, and that judgment applies to every ticket afterward.

qaas/plugin/skills/rollback-plan-authoring/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: rollback-plan-authoring
+description: >
+  Write the rollback note that makes a fix safe to merge: what to revert, what
+  to watch, and what cannot be undone. TRIGGER - read BEFORE opening a pull
+  request or writing its body, and whenever the task mentions rollback, reverts,
+  the PR body, what to monitor after merge, or irreversible effects. Do NOT
+  write 'revert this PR if there are problems' and call it a rollback note - a
+  note with no signal and no irreversibility section creates confidence without
+  supplying safety. SKIP only when no pull request is being opened.
+---
+
+# Writing the rollback note
+
+The note goes in the `body` of `open_pr`, alongside why the change is correct. Its reader is a human at 02:00 who did not write the fix and does not have your context. Everything below is written for that person.
+
+A rollback note earns its place by answering four questions. Fewer than four is not a shorter note, it is an incomplete one.
+
+## 1. What to revert
+
+- The branch and the PR number, and whether reverting **that PR alone** restores the previous behaviour.
+- If the change landed in more than one place — code plus a seeded fixture, code plus a flag flip — the revert order, because the wrong order can leave the system in a state neither version expects.
+- Any change that must *not* be reverted with it (the regression test, usually: reverting a fix while keeping its test leaves a red suite, and that is normally what you want, so say it).
+- If the fix is behind a flag, name the flag and its value. Flipping a flag is a faster rollback than a revert and the on-call needs to know it exists.
+
+## 2. What to watch after merging
+
+A signal, a direction, and a window. Two or three of them, not a list of everything measurable.
+
+Choose them like this:
+
+- **The thing that was broken.** The defect's own observable — the 500 rate on the endpoint, the order status after checkout, the empty list. If it comes back, the fix regressed.
+- **The thing most likely to break from this change.** Look at your own diff and ask what the change could make worse: latency if you added a query, error rate at a call site whose input you narrowed, a downstream consumer if you changed a response field.
+- **A window.** "First 30 minutes" or "the next full nightly" — a signal with no window is never checked and never cleared.
+
+`Watch: the 500 rate on POST /v1/orders and the count of orders left in 'draft', first 30 minutes after deploy. Both should go to zero; the previous value was ~4% and ~12/hour.` That is actionable. "Monitor for errors" is not.
+
+## 3. What is not reversible
+
+This is the section that makes the note worth reading, and the one most often missing. `git revert` restores code. It restores nothing else.
+
+| Irreversible effect | Why the revert does not undo it | What the note must say |
+|---|---|---|
+| Rows written or mutated while the fix was live | The data outlives the code | Which table/field, roughly how many rows, and whether the old code can read them |
+| A migration run | Schema changes are forward-moving; a down-migration is a second risky change | This is outside your envelope entirely — escalate rather than ship |
+| Poisoned caches | Reverted code reads values the new code wrote | Which cache, which keys, and how to bust them |
+| Messages published, webhooks fired, emails or notifications sent | Already delivered to someone else's system | What was sent and to whom |
+| Consumed sequences and external ids | Payment intents, invoice numbers, third-party records | What was created externally |
+| Client-side persisted state — localStorage, a cached bundle, a service worker | Lives in the user's browser past the revert | What users will still be carrying, and whether it breaks the old code |
+| A feature flag other systems began depending on | Flipping back changes their behaviour too | Who else reads the flag |
+
+If none apply, say so explicitly: *"Nothing irreversible: the change is read-path only, writes no data, touches no cache."* An explicit "nothing" is information. Silence reads as "not considered".
+
+## 4. What that means for the risk of the change
+
+Close by joining the previous two sections. Reversibility, not diff size, is what sets the cost of being wrong: a one-line change that writes to a shared cache is riskier than a forty-line change in a leaf module, and the note is where you say so.
+
+- Fully reversible, no persisted effects → the risk is bounded by the revert. Say that.
+- Irreversible component present → name the mitigation before merge: put it behind a flag, add the backfill or cache-bust command *in the note as a runnable line*, or reduce scope to the reversible part.
+- If a rollback would need a data repair you cannot describe, **the fix is not ready to ship alone**. Escalate rather than shipping with a note that admits the gap. A note that documents an unmanaged irreversible effect has transferred the risk to the reader without reducing it.
+
+## Template
+
+```
+## Rollback
+Revert: PR #<n> on fix/<ticket>. That alone restores previous behaviour.
+Keep: the regression test in <path> (it will go red — that is expected).
+Faster option: set <flag>=off, no deploy needed.
+
+## Watch after merge
+- <signal>, expect <direction>, within <window> (was <value>)
+- <signal>, expect <direction>, within <window>
+
+## Not reversible
+- <effect, scale, and how to clean it up>   (or: "nothing — read path only")
+
+## Risk
+<one or two sentences: bounded by the revert, or bounded by <mitigation>>
+```
+
+ARBITER judges this note, and an unviable rollback plan is grounds for `REQUEST_CHANGES` on its own — see `adversarial-review`.

qaas/plugin/skills/root-cause-vs-symptom/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: root-cause-vs-symptom
+description: >
+  Tell a fix that removes the cause from one that suppresses the symptom, from
+  either side of the review. TRIGGER - read BEFORE writing a fix and BEFORE
+  judging one, and whenever the task mentions root cause, symptom, why the
+  defect happens, a try/except or null check added by a fix, a special case, or
+  a widened type. Do NOT decide a change is a real fix because the test went
+  green; symptom fixes turn tests green, that is what makes them dangerous. SKIP
+  only when no fix is being written or reviewed.
+---
+
+# Root cause or symptom
+
+A symptom fix makes the failing test pass while leaving the defect in the system, usually in a shape that will come back under a slightly different input. §10 names this as the failure mode with the most controls pointed at it, because it is the one that looks most like success.
+
+Both agents use this skill. MENDER reads it **before writing**; ARBITER reads it **before judging**, and records the answer in `record_review`'s `root_cause_addressed`.
+
+## The two questions
+
+1. **If the defining test did not exist, would this change still make the program correct?** A change that is only justified by the test is a change aimed at the test.
+2. **Would this change have prevented the defect if the input had been slightly different?** A fix that survives only the exact reproduced input is a special case wearing a fix's clothes.
+
+A change that fails either is a symptom fix, whatever the diff looks like.
+
+## Signatures of a symptom fix
+
+Each of these is a shape you can see in a diff without understanding the domain. Seeing one is not proof — it is the point where you must be able to justify it.
+
+| In the diff | Why it is suspect | What the real fix usually is |
+|---|---|---|
+| `try/except` wrapped around a call that only raises because the caller passed something it built wrong | The caller is the bug; the handler now hides it | Fix what the caller constructs, or validate at the boundary that produced it |
+| `if order_id == 31:` / `if len(items) == 1:` — the exact value or size from the reproduction | The test's input is now a branch in production code | The boundary is the clue, not the case: an off-by-one, an empty-case branch, a `>` that should be `>=` |
+| A field or parameter widened — `int` → `int \| None`, a model field made optional, an annotation relaxed to `Any` | The type was the contract, and the fix moved the contract to fit the bad data | Find who produces the bad value and stop them producing it |
+| `if user is None: return []` where the user cannot legitimately be absent | The null is the defect. Returning empty makes it silent | Trace where the lookup failed; usually a missing filter, a wrong key, or a session not populated |
+| `.get(key, default)` replacing `[key]`, where a missing key means an upstream bug | Converts a loud failure into wrong data | Fix the producer that omits the key |
+| `except Exception:` with a `pass` or a `logger.warning` | Every future defect on this path is now invisible | Catch the specific expected exception at the boundary where it is expected; let the rest propagate |
+| A retry, a `sleep`, or a re-fetch added around an intermittent failure | Races do not get slower, they get rarer | Find the ordering or shared-state assumption that is wrong |
+| A snapshot, fixture or expected constant edited to match observed output | The bug has been written down as the spec | The contract decides the expected value; see `test-quality-audit` |
+| The defining test edited in any way | Not a fix at all | Immediate escalation; MENDER may not do this |
+
+**Defensive code is not automatically a symptom fix.** A null check, a type coercion or a `try/except` at a *trust boundary* — deserialising external input, a third-party response, a user-supplied payload, a cache miss — is correct engineering. The distinction is whether the bad value was produced *inside* the system by code you control. Inside, a guard hides a bug; at the edge, a guard is the design.
+
+## Tracing from the failure to the cause
+
+Do this before proposing a fix, and again when reviewing one that skipped it.
+
+1. **Start from the wrong value, not the exception.** The stack trace tells you where it surfaced. The assertion's *actual* value tells you what is wrong. Write it down.
+2. **Name the invariant that was violated**, in one sentence, in domain terms: "every order row returned belongs to the session's tenant", "the total equals the sum of line items", "a placed order is never left in `draft`". If you cannot name it, you do not yet know what is broken.
+3. **Find the last point where the invariant held.** Walk backwards from the failure through the frames — reading the code, or with `run_single` on a narrower test — until you reach a frame where the state is still correct. The defect lives between that frame and the next.
+4. **Ask where the bad value entered.** Keep walking up while the value is only being *passed*. Stop at the frame where it is *created, defaulted, parsed, or filtered*. That frame is the cause. A value that is wrong three frames deep and wrong at every frame above is one bug at the bottom, not three.
+5. **Check the blast radius of the cause.** Ask what else calls the frame you landed on, and what other symptoms that cause could produce. If your fix handles only the symptom in the ticket, you have found the cause and fixed a leaf.
+6. **State cause and mechanism in one line** for the PR body: *"`list_orders` builds its query without the tenant filter, so any session sees every row; the fix adds the filter the sibling `get_order` already applies."* If you cannot write that line, do not open the PR.
+
+## MENDER: using this before you write
+
+- Do the trace first. The trace is cheap; a rejected round trip is not — the loop breaker allows two MENDER→ARBITER round trips per ticket and then escalates.
+- When the trace lands on a forbidden class (auth, migrations, payment, billing, infra), stop there. Say what the cause is and what you would change. A symptom fix outside the forbidden path, chosen because the real fix was inside it, is the worst available outcome: it looks compliant and it is not a fix.
+- When the cause is real but the fix is bigger than the budget, that is `minimal-diff-discipline`'s escalation, not a licence to patch the symptom instead.
+
+## ARBITER: using this when you read
+
+- Decide `root_cause_addressed` explicitly. It is a field on `record_review`, and a review that leaves it unconsidered has skipped the one check that separates you from a linter.
+- Demand the cause sentence. If the PR body does not say *why* the defect happens, you cannot judge whether the change addresses it, and `REQUEST_CHANGES` naming that absence is a legitimate, cheap review.
+- Test the fix against a neighbouring input, on paper: same code path, one field different. If your description of what happens then is "it would fail again", the fix is a special case.
+- A symptom fix with real tests and a small diff is still a symptom fix. Minimality and green tests are not evidence about causation.
+- When the diff is a symptom fix and the real fix is outside MENDER's envelope, the verdict is `ESCALATE_TO_HUMAN`, not `REQUEST_CHANGES` — sending it back asks for a change the other agent is not permitted to make.

qaas/plugin/skills/routing-rules/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: routing-rules
+description: >
+  Send a ticket to the right project and audience. TRIGGER - read BEFORE
+  choosing any project, component, or assignee, and whenever the task mentions
+  routing, which project, security findings, restricted tickets, the product
+  backlog, or tech debt. Do NOT route a security finding by intuition - a leak
+  here is irreversible. SKIP only when no ticket is being filed.
+---
+
+# Routing
+
+Route by **class**, never by severity. A trivial vulnerability still goes to the restricted project; a blocker UX problem still goes to the product backlog.
+
+| Class | Destination | Why |
+|---|---|---|
+| `vulnerability`, or any envelope with `security_relevant: true` | **Restricted project only** | A public ticket describing an unpatched vulnerability is a disclosure. Irreversible. |
+| `ux-friction` | Product backlog | Not a bug. An engineer cannot action "this flow is confusing"; a product owner can. |
+| `tech-debt` | Debt backlog | Filing debt as a bug corrupts bug metrics and buries real defects. |
+| `bug`, `regression`, `perf-regression` | Engineering, by component | The default path. |
+
+## Security routing is absolute
+
+If there is any doubt whether a finding is security-relevant, **it is**. Route it restricted and let a human downgrade it. The asymmetry is total: a security ticket wrongly filed as restricted costs someone a click, while a vulnerability wrongly filed in public cannot be taken back — it is indexed, cached, and in someone's notification history within minutes.
+
+Never explain a vulnerability's exploitation path in a ticket that might be public. Never paste a leaked credential, token, or key into any ticket, restricted or not — reference where it was found instead.
+
+## Ownership
+
+Resolve component and team from the system map's ownership section (see `ownership-resolution`). Where the map records no owner, **file it unassigned and say so in the ticket**. A guessed assignee is worse than no assignee: it stalls in someone's queue while they work out it is not theirs, and the real owner never sees it.
+
+## Ambiguity
+
+If routing is genuinely unclear — a security-adjacent performance issue, a bug that is arguably product's call — **escalate rather than choose**. Routing mistakes are expensive to reverse and cheap to ask about.

qaas/plugin/skills/severity-rubric/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: severity-rubric
+description: >
+  Score a defect's severity against the house rubric (blocker, critical, major,
+  minor, trivial). TRIGGER - read BEFORE writing any severity value into an
+  envelope, a ticket, or a verdict, and whenever the task mentions severity,
+  priority, impact, 'how bad is this', triage scoring, or which findings matter
+  most. Do NOT score from intuition or from how interesting the bug was to find;
+  this skill is the only authority on severity in this system. SKIP only when no
+  severity field will be written.
+---
+
+# Scoring severity
+
+Severity is a claim about **consequence to users**, not about how the defect was found, how clever the finding was, or how confident the reporter sounded. Score it as the person who has to prioritise the fix would.
+
+| Severity | The test it must pass | Examples |
+|---|---|---|
+| **blocker** | Data loss, a security breach, or a core flow fully broken on the production path. Someone is paged. | Cross-tenant read of another org's data; a migration that drops a column; auth bypass on a handshake |
+| **critical** | A major feature is unusable, there is no workaround, and most users hit it. | Checkout fails for every single-item cart; refund endpoint accepts any role |
+| **major** | Degraded or broken for a subset, and a workaround exists. | Missing index causing an 8s page load; a list endpoint returning every row |
+| **minor** | Cosmetic, edge case, or low frequency. | Focus ring missing on one button; 200 returned where 404 belongs |
+| **trivial** | Polish, cleanup, not user-facing. | Unused import; dead code |
+
+## The four questions, in order
+
+1. **Can data be lost, corrupted, or exposed to someone who should not see it?** If yes, it is blocker. Stop here — nothing below downgrades this.
+2. **Is there a workaround a user could actually discover?** No workaround pushes up a level; an obvious one pushes down.
+3. **What fraction of users hit it, on what fraction of attempts?** "Every user, every time" and "one user, once" are different defects even with identical symptoms.
+4. **Is the failure silent?** A silent failure outranks a loud one at the same blast radius, because nobody reports it and nobody trusts the result. A button that does nothing is worse than a button that shows an error.
+
+## Traps
+
+- **Do not score by effort.** A defect that took four hours to reproduce is not more severe for it.
+- **Do not score by domain.** Accessibility failures are real defects scored on the same scale — minor when they inconvenience, major when they block a user from completing a task, and never dismissed because they are "just a11y".
+- **Do not inflate to get attention.** A rubric everyone games is a rubric nobody reads. If severity keeps landing on critical, the rubric is being used as an argument rather than a measurement.
+- **Do not deflate to seem measured.** Understating a blocker is the more expensive error of the two.
+- **Security findings** are scored on impact like anything else, but routing is separate and non-negotiable — see `routing-rules`.
+
+## Confidence is not severity
+
+They are independent axes and conflating them is the most common scoring error. A defect can be a near-certain minor (confidence 0.95, severity minor) or a suspected blocker (confidence 0.5, severity blocker). Score the consequence if the finding is true; record separately how sure you are that it is.

qaas/plugin/skills/test-first-fix/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: test-first-fix
+description: >
+  Fix a defect test-first: run the defining test, watch it fail, and only then
+  change code. TRIGGER - read BEFORE editing a single line of product code on a
+  ticket, and whenever the task mentions fixing a defect, making a failing test
+  pass, writing a regression test, or 'the ticket has a failing test'. Do NOT
+  start editing on the strength of having read the test; a test you have not
+  watched fail is a guess about what is broken. SKIP only when no code is being
+  changed.
+---
+
+# Fixing test-first
+
+The ticket carries `reproduction.failing_test` as a nodeid. That test is the definition of success and the order below is built around it. Running it only after the fix is how a change that fixes nothing ships with a green suite.
+
+## 1. Run it and watch it fail
+
+`run_single` on the nodeid, before any edit, in the environment the reproduction pinned — `seed`, `set_flag`, `set_clock`, `impersonate` from `reproduction.environment`. A different environment tells you about a different defect.
+
+Read the failure text, not the colour. Write down the assertion that failed and the expected-versus-actual pair. That pair is what your change has to move, and it is the only thing that will later tell you whether it moved for the right reason.
+
+| The first run | What it means | What you do |
+|---|---|---|
+| Fails on the ticket's assertion, expected vs actual as described | The defect is live and yours to fix | Proceed to step 2 |
+| **Passes** | Already fixed, or the test does not capture the defect | Stop. Escalate. See below |
+| Errors in collection or fixture setup | Broken environment, not evidence | Repair the environment and re-run; if you cannot, escalate |
+| Fails with a message the ticket does not describe | Wrong nodeid, or a second defect on top | Resolve which before changing anything |
+| Passes on some runs | Flaky. Confirm with `run_n_times`, n=5 | A flake is a quarantine finding, not a fix (§10) |
+
+## When it passes before you have touched anything
+
+This is the case the step exists to catch, and the wrong move is to make a plausible change anyway and claim the ticket. Both explanations are escalations, and they are different escalations, so say which one you believe and why:
+
+- **Already fixed** — name the commit or change you think closed it. Transition the ticket with that reason rather than opening a PR that changes nothing.
+- **The test does not capture the defect** — quote what the test asserts, quote what the reproduction describes, and state the gap.
+
+You may not widen, weaken, retitle, or delete the defining test to make it fail. When the run lists that path in your policy's `protected_paths`, the write is refused outright — the guardrail answers that it "is the test that defines success for this ticket and may not be edited (§10)". When it is not listed, the rule holds anyway. A fixer that can edit its own acceptance criterion has no acceptance criterion, and this is the failure mode the system is most designed to prevent.
+
+## 2. Make it pass for the right reason
+
+Before you edit, be able to complete this sentence: *the test fails because \<cause\>, and my change makes it pass by \<mechanism\>*. If the mechanism is "I caught the exception", "I added a branch for that input", or "I made the field optional", you are about to write a symptom fix — stop and read `root-cause-vs-symptom`.
+
+After the edit, re-run the same nodeid and confirm that **the failure you wrote down is the one that disappeared**. Green is not enough. A test goes green for the wrong reason when the code now returns early, when the assertion is no longer reached, when an exception is swallowed before it propagates, or when a fixture stopped producing the triggering data. Each of those looks identical in a summary line.
+
+## 3. Regression test, proven against the old code
+
+The defining test proves this defect is gone. The regression test states the contract that was violated, so the defect cannot come back in a different shape. They are not the same test — if your regression test is a copy of the defining test with a new name, you have added nothing.
+
+Write it against the boundary the reproduction found. "Fails with one item, works with two" means the regression test is parameterised over 0, 1 and 2 items, not a second assertion about one item.
+
+**Verify it fails against the unfixed code.** Two ways, in order of preference:
+
+1. **Write the regression test before the fix.** Run it, watch it fail, keep the failure text, then fix. Nothing to undo, and the evidence is free.
+2. **Stash the fix and re-run.** `git stash push -- <changed files>`, `run_single` on the new test, confirm it fails, `git stash pop`. Do not reach for `git reset --hard` or `git checkout main` — both are refused, and for good reason.
+
+Record the observed old-code failure in the PR body. ARBITER cannot run this check itself (it has no shell and no write access), so your statement of it, with the failure message, is the evidence the review depends on.
+
+## 4. Before you open anything
+
+1. `affected_tests` on your changed paths, then `run_suite` on what it names. Its ranking is a documented heuristic, not coverage — widen it when the change is in shared code.
+2. Establish pre-existing failures on the base first, or you will attribute someone else's breakage to your diff. `regression-suite-selection` covers the selection; use it.
+3. Read the failures. A summary count is not a result.
+4. Open the PR as a draft on your `fix/*` branch with a rollback note — `rollback-plan-authoring`. Never merge.
+
+A green run you did not first watch turn from red is not evidence about this defect. It is evidence that a suite passes, which was already true yesterday.

qaas/plugin/skills/test-quality-audit/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: test-quality-audit
+description: >
+  Audit the tests that come with a fix for whether they can actually fail.
+  TRIGGER - read BEFORE judging any regression test attached to a fix, and
+  whenever the task mentions test quality, asserted-to-pass tests, mocks,
+  snapshots, coverage, or 'are these tests real'. Do NOT accept a green run as
+  evidence that a test discriminates; a test that passes against the unfixed
+  code tests nothing and is the most common way a bad fix looks good. SKIP only
+  when a fix carries no tests - which is itself the finding.
+---
+
+# Auditing the tests on a fix
+
+A regression test has one job: fail if the defect comes back. A test that cannot fail is worse than no test, because it occupies the slot where a real one would go and it makes the next reviewer relax.
+
+The audit answers one question — **would this test have failed against the code before the fix?** — and everything below is a way of getting at it.
+
+## The central technique: run it against the old code
+
+- **MENDER can do this directly.** Write the regression test before the fix and watch it fail, or `git stash push -- <changed files>`, `run_single` on the new test, confirm the failure, `git stash pop`. Put the observed old-code failure message in the PR body.
+- **ARBITER cannot.** You have `Read`, `Grep`, `Glob` and read-only vcs and test_runner; no shell, no write access, no way to revert the diff. So:
+  1. Running `run_single` on the new test in the current tree proves it passes with the fix. That is the premise, not the check — do not record it as evidence of quality.
+  2. Do the revert **on paper**: for each hunk of the fix, ask which assertion in the new test goes red if that hunk is deleted. If no assertion depends on any hunk, the test does not test the fix.
+  3. Require the PR body to state that the check was run, and quote the old-code failure. If it does not, `REQUEST_CHANGES` asking for exactly that. It is the cheapest and most specific review you can write, and it puts the work where the tools are.
+
+## Shapes that cannot fail
+
+| In the test | Why it proves nothing | What it should assert |
+|---|---|---|
+| `result = f(x)` and then nothing, or `assert result`, or `assert result is not None` | Only that the call returned | The value: the field, the count, the status the contract promises |
+| `assert isinstance(r, list)` / `assert "items" in body` | Shape, not behaviour. True before the fix as well | What is *in* the list, and why that is right |
+| `assert r.status_code == 200` on a defect about the response body | The endpoint was probably 200 while broken | The body field the defect corrupted |
+| `assert total == 4`, where 4 is whatever the code printed | Pins observed output as the spec. If it was pinned *before* the fix, it pins the bug | The contract-derived value, with the assertion message naming the contract |
+| `mock_repo.get.assert_called_once()` | That the code called something. The bug may be in what it did with the answer | The behaviour after the call. Mock the boundary, never the unit under test |
+| A mock standing in for the function that contained the bug | The buggy code no longer runs in the test | Exercise the real code; mock only what crosses a process boundary |
+| A snapshot or expected fixture updated in the same PR | The bug may have been written down as the expectation | Check the snapshot diff moved *toward* the contract, not toward the observed output |
+| `try: ... except Exception: pass` around the assertion, or `pytest.raises(Exception)` | Swallows the failure, or matches any failure including an import error | Let it raise; name the specific exception type and match its message |
+| `assert` after a `return`, or inside an `if` that is never true | Never executes | Unconditional assertions |
+| Function not named `test_*`, a `skip`/`xfail` marker, an empty `parametrize` list, a method on an uncollected class | Never runs. Confirm it appeared in the run's per-test rows | It must show as `passed` in `run_suite` output, by nodeid |
+| Passes only after another test, or reuses the defining test's fixture state | A coincidence of ordering, not a reproduction | Self-contained setup and teardown |
+
+## Beyond "can it fail"
+
+- **Is it a different test from the defining one?** A regression test that is the defining test renamed adds nothing. The defining test proves *this* defect is gone; the regression test states the *contract* so the defect cannot return in another shape.
+- **Does it cover the boundary?** If the reproduction found "fails with one item, works with two", the test is parameterised over 0, 1 and 2. A single-case test at the reported value is a special case, and it pairs suspiciously often with a special-cased fix (`root-cause-vs-symptom`).
+- **Does it assert the contract, not the bug?** `assert len(items) <= limit` survives a future fix; `assert len(items) == 30` goes red when someone gets it right and is then deleted as flaky.
+- **Was the defining test touched?** Diff its file against the base. Any hunk there is a `REQUEST_CHANGES`; a weakened assertion, a new skip marker, or a changed parametrisation is an `ESCALATE_TO_HUMAN`.
+- **Was it actually run?** Check the per-test rows from `run_suite` or `run_single`, by nodeid. A summary count does not tell you your test was among them, and a test that matched nothing returns an error rather than a pass.
+- **Is it deterministic?** If the area is timing- or ordering-sensitive, `run_n_times` with n=5. A test that passes intermittently has not passed, and a flaky regression test is deleted within a month.
+
+## Coverage is not quality
+
+`get_coverage` measures which lines executed, and it returns an error rather than an estimate when `coverage` is not installed. Executed is not asserted: a covered line under a vacuous assertion is more dangerous than an uncovered one, because it reports as safe. Use coverage only to find lines the new tests never reach — that is a real gap — never as evidence that the tests are good.
+
+## When the tests are the only problem
+
+A correct fix with a vacuous test is `REQUEST_CHANGES`, not `APPROVE` with a concern. The test is what stops the defect returning after everyone involved has forgotten the ticket, and it is the cheapest thing in the change to get right. Name the file, name the assertion, and say what it should assert instead — MENDER receives your words verbatim and there are only two round trips.

qaas/plugin/skills/ticket-writer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ticket-writer
+description: >
+  Compose a ticket in the house format so an engineer can act on it without
+  asking questions. TRIGGER - read BEFORE writing any ticket title, description,
+  or acceptance criteria, and whenever the task mentions filing, ticket text,
+  issue body, repro steps, or acceptance criteria. Do NOT write a ticket from
+  memory of what tickets look like. SKIP only when no ticket text will be
+  produced.
+---
+
+# Writing the ticket
+
+The reader is an engineer who has not seen the finding, has four other tickets open, and will decide in about fifteen seconds whether this one is worth their attention. Write for them.
+
+## Title
+
+Name the **defect**, not the symptom, and not the location.
+
+- Bad: `Bug in orders.py` - names a file, says nothing
+- Bad: `Page is blank` - names a symptom, could be twenty causes
+- Good: `Order detail endpoint is not scoped to the caller's organization`
+- Good: `Place order does nothing when the cart holds a single item`
+
+Under 90 characters. A reader should be able to tell from the title alone whether it is their problem.
+
+## Body, in this order
+
+1. **What breaks, for whom, how often.** Two or three sentences. Lead with the user-visible consequence, not the code.
+2. **Reproduction.** FORGE's steps, verbatim. Do not paraphrase them, do not tidy them, do not renumber. They were minimised deliberately and every edit risks breaking the reproduction.
+3. **Evidence.** Links to the artifacts. Say what each one shows.
+4. **Acceptance criteria.** The failing test that must pass, named exactly. This is the contract: when that test is green the ticket is done, and there is nothing to argue about.
+5. **Suggested area** if you have one, clearly marked as a suggestion. You are not the person fixing it and you may be wrong about where.
+
+## Rules
+
+- **Never state a cause you have not verified.** "Probably a missing await" in a ticket becomes an hour spent looking at awaits. Say what was observed; leave diagnosis to whoever fixes it.
+- **Include what you ruled out.** "Reproduces for member and viewer roles but not admin" is worth more than three paragraphs of speculation.
+- **Say what you did not check.** A ticket that admits its own limits is trusted; one that overstates gets discounted entirely, including the parts that were right.
+- **No severity argument in the body.** The severity field carries it, scored by `severity-rubric`.

qaas/plugin/skills/verdict-reporting/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: verdict-reporting
+description: >
+  Write a verification verdict a human can act on without re-running the work.
+  TRIGGER - read BEFORE writing any verdict, verification comment, or ticket
+  transition note, and whenever the task mentions reporting a verdict, VERIFIED,
+  NOT_FIXED, REGRESSED, or verification results. Do NOT report a verdict without
+  saying what was actually run. SKIP only when no verdict is being written.
+---
+
+# Reporting the verdict
+
+## Structure
+
+1. **The verdict word**, alone and first: `VERIFIED`, `NOT_FIXED`, or `REGRESSED`.
+2. **What you ran** — the original test by name, how many affected tests, which journey.
+3. **What you observed** — pass counts, and every failure by name.
+4. **What you did not run**, and why.
+5. **Residual risk**, if any.
+
+## On NOT_FIXED, the delta is the deliverable
+
+The next agent works from this and nothing else. Give it: the exact assertion that failed, expected versus actual, and whether the behaviour changed at all from before the fix.
+
+"Still failing" is useless. "`test_orders_list_respects_limit` still fails: requested limit 5, received 30 rows. Unchanged from before the fix — the `.limit()` call is still absent from the query chain" is a fix in one reading.
+
+## On REGRESSED, name the casualty
+
+Which test, which behaviour, and whether it is related to the fix or coincidental. A regression report that does not identify what broke is an alarm with no address.
+
+## Never overstate
+
+If a step was skipped, say so. If the environment differed from the original in any way, say so. If a test passed on the second attempt after failing on the first, say so and treat it as flaky.
+
+The value of this verdict rests entirely on it being the one report in the system that is never optimistic. A single VERIFIED that turns out to be wrong costs more credibility than ten honest NOT_FIXEDs — because after that, every closed ticket has to be re-checked by hand, which is the exact work this system exists to remove.

qaas/plugin/skills/verification-protocol/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: verification-protocol
+description: >
+  Verify that a fix actually fixed the defect, in the right order, against the
+  original criterion. TRIGGER - read BEFORE verifying any fix or transitioning
+  any ticket toward done, and whenever the task mentions verification,
+  confirming a fix, closing a ticket, VERIFIED, or 'did this work'. Do NOT
+  declare anything verified without running the original failing test first.
+  SKIP only when nothing is being verified.
+---
+
+# Verifying a fix
+
+You are the closing authority. An incorrect VERIFIED puts a defect back in front of users with a ticket saying it was fixed — which is worse than never having filed it, because now nobody is looking.
+
+## The order is not negotiable
+
+1. **Same environment.** Bring up the patched build with the fixture, flags and role recorded in the original reproduction. A different environment proves nothing about this defect.
+2. **The original failing test, first.** It must now pass. If it does not, the verdict is `NOT_FIXED` and you are finished — do not continue, do not investigate, do not decide the test was wrong.
+3. **Regression suite for the affected area**, selected from the diff.
+4. **Re-walk the journey** if UI or realtime behaviour was touched. A passing unit test does not mean the button works.
+
+Running these out of order — regression suite first, or a fresh manual check before the original test — is how a fix that addressed a different symptom gets marked verified.
+
+## The original test is the criterion
+
+Do not write a new, more forgiving test. Do not edit the existing one. Do not accept "the test is outdated" as an argument — if you genuinely believe the acceptance criterion is wrong, that is an **escalation**, not a verdict, and certainly not an edit.
+
+## Three verdicts, no fourth
+
+- **VERIFIED** — original test passes, nothing else broke. Ticket to done, PR ready for a human to merge.
+- **NOT_FIXED** — original test still fails. Reopen with the exact delta between expected and observed. Be specific; the next agent works only from this.
+- **REGRESSED** — original passes, something else broke. Block and escalate, naming what broke.
+
+"Verified with caveats" is not a verdict. If there are caveats, it is one of the other two.
+
+## Re-run anything that smells flaky
+
+A test that passes intermittently has not passed. Run it again before calling VERIFIED, and if it is genuinely flaky say so rather than taking the pass.

qaas/prompts/ARBITER.md

@@ -0,0 +1,53 @@
+You are ARBITER, the review and risk gate.
+
+You read MENDER's diff as an adversarial reviewer. You did not write it, you have
+no stake in it, and your job is to find what is wrong with it — because a model
+reviewing its own work in the same context reliably talks itself into approving.
+That is the entire reason you exist as a separate agent.
+
+## What you judge
+
+**Root cause or symptom?** Does this change fix why the defect happens, or does
+it suppress how it shows? A handler that catches an exception the caller should
+never have triggered is a symptom fix. So is a special case for the exact input
+in the test.
+
+**Is the diff minimal?** Every line beyond the fix is scope creep. Refactoring
+carried along with a bug fix is a separate ticket, however sensible it looks.
+
+**Does it break anything?** Contracts, schemas, public API shape, response
+fields, status codes. Use `diff_openapi` where the change touches an endpoint.
+Check the call sites, not just the function.
+
+**Are the regression tests real?** A test that passes against the *unfixed* code
+tests nothing. Read the assertions: do they check the behaviour that was broken,
+or do they check that the function returns without raising? Asserted-to-pass
+tests are the most common way a bad fix looks good.
+
+**Is the rollback plan viable?** Can this actually be reverted cleanly, and does
+the note say what to watch afterwards?
+
+## Your verdict
+
+Record exactly one decision with `record_review`:
+
+- **APPROVE** — the fix is correct, minimal and safe. Say what you checked. Note
+  any residual concern even when approving; a reviewer who has no concerns has
+  usually not looked hard enough.
+- **REQUEST_CHANGES** — name the file, name what is wrong, and say what would
+  make it right. MENDER receives your words verbatim and cannot act on vagueness.
+  "Consider improving error handling" is not a review.
+- **ESCALATE_TO_HUMAN** — the change is outside what you can responsibly judge,
+  or the right fix is bigger than this ticket. Escalating is a legitimate
+  outcome, not a failure to decide.
+
+## How to be useful
+
+Do not approve because the tests pass. Tests passing is the floor, not the
+verdict — you are here to catch what the tests do not.
+
+Do not request changes on style, naming, or how you would have written it. You
+have one question: should this change ship? Everything else is noise that costs a
+round trip and teaches the system that your reviews can be skimmed.
+
+You have no write access to code. Your judgement is the whole deliverable.

qaas/prompts/CARTOGRAPHER.md

@@ -0,0 +1,46 @@
+You are CARTOGRAPHER, the system and product mapper.
+
+You build the shared ground truth every other agent in this system reads. They
+depend on your map so they do not each re-derive the codebase — accuracy here
+makes every downstream agent cheaper and more correct, and an error here
+propagates everywhere.
+
+## Your job
+
+Read the target application and produce one `system-map.json` describing what
+exists. You explore the repository with Read, Grep and Glob, then call
+`put_system_map` exactly once with the complete map.
+
+Map these, as far as the code actually supports:
+
+- **services** — each deployable unit: name, language, entry point, root path.
+- **routes** — every HTTP endpoint: method, path, handler file, auth requirement
+  as the code enforces it (not as a comment claims), and the service it belongs to.
+- **ui_routes** — every reachable page or view: path, component file, and whether
+  it requires authentication.
+- **schema** — tables, their columns with nullability, primary and foreign keys,
+  and indexes.
+- **events** — WebSocket or message topics: name, direction, payload shape.
+- **modules** — the internal dependency edges that matter, enough to spot a cycle
+  or a layering violation later.
+- **ownership** — map each area to a component and team from CODEOWNERS or an
+  equivalent file. Where no ownership is recorded, say so with `null` rather than
+  guessing a team name.
+- **task_graph** — the product's user-facing tasks ("place an order", "change
+  billing frequency") as a small graph of the UI routes and actions each needs.
+  This is what SURFACE uses to explore, so cover the primary journeys.
+
+## Rules
+
+Report what the code does, not what documentation says it does. Where the two
+disagree, record the code's behaviour and note the disagreement in `drift`.
+
+Never invent a field to make the map look complete. Missing is `null` or an
+empty list; a plausible guess is worse than an admitted gap because everything
+downstream will trust it.
+
+Prefer breadth over depth. Every route and table matters more than a deep read
+of any one handler.
+
+You emit no defect envelopes. You are read-only: finding a bug is not your job
+even when you see one — the map is what you owe.