qaas-python 0.1.0__py3-none-any.whl

qaas/paths.py

@@ -0,0 +1,317 @@
+"""Where qaas finds its own resources: config, prompts, skills, state.
+
+This module exists because the package used to assume it was running from its
+own git checkout. `config/` and `.claude/skills/` sat at the repo root, outside
+the wheel, and were looked up relative to the process CWD or by climbing
+`Path(__file__).parents[2]` -- which, once installed, lands in
+`site-packages/../..`. A `pip install` therefore produced a CLI where every
+command that needed config died, and `qaas validate` failed *always*, because
+none of the 30 skills it checks for were anywhere on disk.
+
+Three different ideas had been collapsed into `Path.cwd()`:
+
+  1. where qaas's own resources live      -> packaged, or overridden by the user
+  2. where the user's project state lives -> `.qaas/`
+  3. where the application under test is  -> the target profile's root
+
+This module owns the first two. The third belongs to `TargetProfile.root_path`.
+
+The precedence is the same for every kind of resource, and it is the ordinary
+one: an explicit flag beats the project, and the project beats what we shipped.
+
+    1. explicit  --config / QAAS_CONFIG_DIR
+    2. project   <project>/.qaas/config, and the source-checkout <project>/config
+    3. packaged  src/qaas/defaults/config, src/qaas/prompts, src/qaas/skills
+
+Layering granularity differs by kind, and that difference is deliberate:
+
+  * `system.yaml`   first hit wins **whole**. Merging run-mode dictionaries
+                    across layers produces a configuration nobody wrote and
+                    nobody can read back.
+  * `agents/*.yaml` union by filename, higher layer shadows. Someone who wants
+                    MENDER's budget raised drops in one file; they do not fork
+                    eight and freeze themselves on today's roster.
+  * prompts/skills  union by name, higher layer shadows, same reasoning.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+#: Overrides, in the order a reader will look for them.
+CONFIG_DIR_ENV = "QAAS_CONFIG_DIR"
+HOME_ENV = "QAAS_HOME"
+
+#: The state directory, and the config dir inside it. `.qaas/` holds both a
+#: user's committed config and their disposable run state, so `init` writes a
+#: `.gitignore` inside it -- otherwise the obvious `.gitignore` line for `.qaas/`
+#: would drop their configuration too.
+STATE_DIRNAME = ".qaas"
+PROJECT_CONFIG = "config"
+
+#: How far up to look for a project before giving up and using packaged defaults.
+MAX_WALK_UP = 24
+
+
+def package_root() -> Path:
+    """The installed package directory -- the one `__file__` seam in the codebase.
+
+    `Path(__file__).parent` rather than `importlib.resources.files("qaas")`,
+    which was tried first and is wrong here: under a src-layout editable install
+    the package resolves to a `MultiplexedPath`, and `Path(str(...))` on one of
+    those yields the literal string `MultiplexedPath('/...')` -- a path that
+    exists nowhere. Every resource lookup then silently found nothing, which is
+    the same failure shape as the bug this module was written to fix.
+
+    This file lives inside the package, so its parent *is* the package, in an
+    editable install and a wheel alike. Zip-safety is not a consideration: the
+    skills directory is handed to a subprocess as a real filesystem path.
+    """
+    return Path(__file__).resolve().parent
+
+
+def packaged_config() -> Path:
+    return package_root() / "defaults" / "config"
+
+
+def packaged_prompts() -> Path:
+    return package_root() / "prompts"
+
+
+def packaged_plugin() -> Path:
+    """The skills plugin that ships in the wheel.
+
+    Skills reach an agent as a Claude Code *plugin* (`--plugin-dir`), not through
+    filesystem settings, so they travel in the package instead of depending on a
+    `.claude/skills/` directory in whatever repository the user happens to be in.
+
+    The layout is not optional and was established by testing the CLI rather
+    than by reading about it. A directory of bare `<skill>/SKILL.md` folders
+    loads NOTHING -- silently. A directory containing `skills/<name>/SKILL.md`
+    loads, but takes its namespace from the directory name. Only
+    `.claude-plugin/plugin.json` + `skills/<name>/SKILL.md` gives a stable
+    namespace, and it comes from the manifest's `name`.
+    """
+    return package_root() / "plugin"
+
+
+def plugin_name(plugin_dir: Path) -> str:
+    """A plugin's namespace: its manifest name, else its directory name.
+
+    Skills load as `<plugin>:<skill>`, and that prefix is not cosmetic -- the
+    SDK matches skill names down two channels with different rules, so the name
+    used here has to be the one the CLI will actually register.
+    """
+    manifest = plugin_dir / ".claude-plugin" / "plugin.json"
+    if manifest.is_file():
+        try:
+            import json
+
+            declared = json.loads(manifest.read_text()).get("name")
+            if declared:
+                return str(declared)
+        except Exception:  # noqa: BLE001 - a broken manifest falls back, not crashes
+            pass
+    return plugin_dir.name
+
+
+def packaged_skills() -> Path:
+    """The skills themselves, inside the plugin."""
+    return packaged_plugin() / "skills"
+
+
+def find_project(start: Path | None = None) -> Path | None:
+    """Walk up looking for a qaas project. Returns None if there is not one.
+
+    Three shapes count:
+
+      * `<dir>/.qaas/config/`      what `qaas init` writes
+      * `<dir>/config/system.yaml` a user who keeps config at the top level
+      * `<dir>/config/targets/`    this repository, whose `system.yaml` now
+                                   ships inside the package and whose `config/`
+                                   holds only the bundled demo profile
+
+    The third looks incidental and is not: without it, developing qaas in its
+    own checkout stops finding the demo target the moment the defaults move
+    into the wheel.
+    """
+    here = (start or Path.cwd()).resolve()
+    for parent in [here, *here.parents][:MAX_WALK_UP]:
+        if (parent / STATE_DIRNAME / PROJECT_CONFIG).is_dir():
+            return parent
+        if (parent / PROJECT_CONFIG / "system.yaml").is_file():
+            return parent
+        if (parent / PROJECT_CONFIG / "targets").is_dir():
+            return parent
+    return None
+
+
+def project_root(start: Path | None = None) -> Path:
+    """The qaas project directory, falling back to the cwd when there is none.
+
+    This is the base a *relative* target root resolves against. It has to be the
+    project rather than the cwd: a profile says `root: target-app` because that
+    is where the application sits relative to the project that configures it,
+    and running `qaas run` from a subdirectory must not silently point the whole
+    system at a directory that does not exist.
+    """
+    here = (start or Path.cwd()).resolve()
+    return find_project(here) or here
+
+
+def _existing(*candidates: Path | None) -> tuple[Path, ...]:
+    """Keep the directories that exist, in order, without duplicates."""
+    seen: list[Path] = []
+    for c in candidates:
+        if c is None:
+            continue
+        r = c.resolve()
+        if r.is_dir() and r not in seen:
+            seen.append(r)
+    return tuple(seen)
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """Every directory qaas reads from, resolved once and passed down.
+
+    Frozen because half the codebase reads these; a value that can be mutated
+    mid-run is a value that will be.
+    """
+
+    project: Path | None
+    config_dirs: tuple[Path, ...]
+    prompt_dirs: tuple[Path, ...]
+    #: Plugin roots, as handed to `--plugin-dir`.
+    plugin_dirs: tuple[Path, ...]
+    #: The `skills/` inside each plugin, in the same order.
+    skill_dirs: tuple[Path, ...]
+    state_root: Path
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        config: Path | str | None = None,
+        state_root: Path | str | None = None,
+        cwd: Path | None = None,
+    ) -> "Workspace":
+        """Build the search paths. Never raises: a missing project is legitimate.
+
+        `pip install qaas-python` then `qaas --help` in an empty directory is a
+        supported state, and it resolves to packaged defaults only.
+        """
+        here = (cwd or Path.cwd()).resolve()
+        project = find_project(here)
+
+        explicit = config or os.environ.get(CONFIG_DIR_ENV) or None
+        explicit_path = Path(explicit).resolve() if explicit else None
+
+        home = os.environ.get(HOME_ENV)
+        home_path = Path(home).resolve() if home else None
+
+        proj_state = (project / STATE_DIRNAME) if project else None
+
+        config_dirs = _existing(
+            explicit_path,
+            home_path / PROJECT_CONFIG if home_path else None,
+            proj_state / PROJECT_CONFIG if proj_state else None,
+            project / PROJECT_CONFIG if project else None,
+            packaged_config(),
+        )
+        prompt_dirs = _existing(
+            home_path / "prompts" if home_path else None,
+            proj_state / "prompts" if proj_state else None,
+            packaged_prompts(),
+        )
+        # Plugin directories, highest precedence first. A project's own plugin
+        # shadows the packaged one for any skill it provides.
+        plugin_dirs = _existing(
+            home_path / "plugin" if home_path else None,
+            proj_state / "plugin" if proj_state else None,
+            packaged_plugin(),
+        )
+        skill_dirs = _existing(*(d / "skills" for d in plugin_dirs))
+
+        if state_root is not None:
+            state = Path(state_root).resolve()
+        elif proj_state is not None:
+            state = proj_state
+        else:
+            state = (here / STATE_DIRNAME).resolve()
+
+        return cls(
+            project=project,
+            config_dirs=config_dirs,
+            prompt_dirs=prompt_dirs,
+            plugin_dirs=plugin_dirs,
+            skill_dirs=skill_dirs,
+            state_root=state,
+        )
+
+    # -- lookups ----------------------------------------------------------
+
+    def find_file(self, dirs: Iterable[Path], relative: str) -> Path | None:
+        """First hit wins. Used for whole-file resources like `system.yaml`."""
+        for d in dirs:
+            candidate = d / relative
+            if candidate.is_file():
+                return candidate
+        return None
+
+    def config_file(self, relative: str) -> Path | None:
+        return self.find_file(self.config_dirs, relative)
+
+    def prompt_file(self, relative: str) -> Path | None:
+        return self.find_file(self.prompt_dirs, relative)
+
+    def merged(self, dirs: Iterable[Path], subdir: str, pattern: str) -> dict[str, Path]:
+        """Union by filename, earlier layers shadowing later ones.
+
+        For `agents/*.yaml`, `targets/*.yaml` and skills: a user shadows the one
+        file they care about and keeps receiving improvements to the rest.
+        Reversed iteration so the highest-precedence directory writes last.
+        """
+        found: dict[str, Path] = {}
+        for d in reversed(list(dirs)):
+            base = d / subdir if subdir else d
+            if not base.is_dir():
+                continue
+            for path in sorted(base.glob(pattern)):
+                found[path.stem] = path
+        return found
+
+    def skill_names(self) -> dict[str, Path]:
+        """Every skill directory visible, by name, nearest layer winning."""
+        found: dict[str, Path] = {}
+        for d in reversed(list(self.skill_dirs)):
+            if not d.is_dir():
+                continue
+            for skill in sorted(d.glob("*/SKILL.md")):
+                found[skill.parent.name] = skill.parent
+        return found
+
+    def qualify(self, skill: str) -> str | None:
+        """`severity-rubric` -> `qaas:severity-rubric`, from whichever plugin
+        provides it. None when nothing does -- which is a configuration error
+        worth reporting, not a name to pass on and hope."""
+        for plugin_dir in self.plugin_dirs:
+            if (plugin_dir / "skills" / skill / "SKILL.md").is_file():
+                return f"{plugin_name(plugin_dir)}:{skill}"
+        return None
+
+    def describe(self) -> str:
+        """One line per search path, for `qaas doctor` and error messages."""
+        where = str(self.project) if self.project else "(none -- packaged defaults only)"
+        lines = [f"project:  {where}", f"state:    {self.state_root}"]
+        for label, dirs in (
+            ("config", self.config_dirs),
+            ("prompts", self.prompt_dirs),
+            ("skills", self.skill_dirs),
+        ):
+            for i, d in enumerate(dirs):
+                lines.append(f"{label + ':':9} {'*' if i == 0 else ' '} {d}")
+        return "\n".join(lines)

qaas/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "qaas",
+  "description": "Procedures for the qaas QA agents: how to triage, reproduce, review and verify.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Alla Abdella"
+  },
+  "homepage": "https://github.com/allaabdella2-us/qa-multi-agent-system"
+}

qaas/plugin/skills/a11y-audit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: a11y-audit
+description: >
+  Check a rendered page against WCAG for failures that block or exclude users.
+  TRIGGER - read BEFORE reporting any accessibility issue, and whenever the task
+  mentions accessibility, a11y, WCAG, screen readers, contrast, keyboard
+  navigation, focus, or ARIA. Do NOT report an accessibility finding without
+  naming the specific success criterion it violates. SKIP only when no rendered
+  UI is in scope.
+---
+
+# Auditing accessibility
+
+These are real defects, scored on the normal severity scale. Major when they block someone from completing a task; minor when they inconvenience. Never dismissed as cosmetic, and never inflated past what the rubric supports.
+
+## What to check, in value order
+
+1. **Every input has an accessible name** (WCAG 1.3.1, 4.1.2). A `<label for>`, an `aria-label`, or `aria-labelledby`. **A placeholder is not a label** — it vanishes on focus and many screen readers skip it. An unlabelled search box is announced as "edit text, blank".
+2. **Contrast** (1.4.3). 4.5:1 for body text, 3:1 for large text and UI component boundaries. Compute the ratio and state it; "looks light" is not a finding.
+3. **Keyboard reachability** (2.1.1, 2.1.2). Tab through the whole task. Everything clickable must be reachable and operable, and you must be able to get back out of every widget. A focus trap is major — it strands the user with no recovery.
+4. **Visible focus** (2.4.7). If focus is invisible, keyboard navigation is guesswork.
+5. **Meaningful order** (1.3.2, 2.4.3). Tab order should follow the visual order.
+6. **Status messages announced** (4.1.3). An error shown only in red text, with no `role="alert"` or `aria-live`, does not exist for a screen reader user — they submit and hear nothing.
+7. **Images and icon buttons** (1.1.1). Decorative images `alt=""`; meaningful ones described. An icon-only button with no accessible name is unusable.
+
+## Name the criterion
+
+Every finding states the number and what a user experiences: "1.3.1 — the orders search input has only a placeholder, so screen reader users hear an unlabelled text field and cannot tell what it filters."
+
+The number makes it checkable. The consequence makes it worth fixing. A finding with only the number reads as compliance box-ticking; a finding with only the consequence is hard to verify.
+
+## Precision
+
+Check the specific element pair you are reporting, not the theme generally. A design where one button variant fails contrast and the rest pass is one finding, not a sweeping claim about the palette — and a sweeping claim will be dismissed along with the real instance inside it.

qaas/plugin/skills/adversarial-review/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: adversarial-review
+description: >
+  Review a fix as an adversary in a fixed order, reading for what the diff is
+  missing rather than what it contains. TRIGGER - read BEFORE looking at any
+  diff you are asked to judge and BEFORE recording any review decision, and
+  whenever the task mentions reviewing a fix, APPROVE, REQUEST_CHANGES,
+  ESCALATE_TO_HUMAN, scope creep, or 'does this change look right'. Do NOT
+  approve because the change looks reasonable and the tests pass; that is the
+  exact failure this agent exists to prevent. SKIP only when no review decision
+  will be recorded.
+---
+
+# Reviewing adversarially
+
+You did not write this diff, you have no stake in it, and your judgement is the entire deliverable — you have no write access to code. A model reviewing work in the same context reliably talks itself into approving; the order below exists so that you cannot.
+
+## The order
+
+Do these in sequence. Each step's value depends on not having already formed a verdict.
+
+**1. Read the criterion before the change.** The ticket, the reproduction, and the defining test named in `reproduction.failing_test`. You must know what "fixed" means before you see what was done, or you will judge the diff on its own terms and grade it against its own goal.
+
+*Prevents:* accepting the author's framing of the problem.
+
+**2. Get the diff yourself.** `pr_diff` for a PR number, or `list_changed_files` for the base/head pair. With the local vcs backend both are refused as remote-only — that refusal names the backend — so fall back to `diff` with `ref: main`. Never review from MENDER's summary of its own change.
+
+*Prevents:* reviewing a description instead of a patch. Descriptions omit the hunks their authors have stopped seeing.
+
+**3. Confirm the defining test was not touched.** Any hunk in that file is an immediate `REQUEST_CHANGES`, or `ESCALATE_TO_HUMAN` if the change was to weaken it. Check for the quiet versions too: a loosened assertion, a new `skip`/`xfail`, a changed parameter set, a renamed fixture.
+
+*Prevents:* the §10 symptom fix, in its most direct form.
+
+**4. Root cause.** Apply `root-cause-vs-symptom` in full. Require the PR body to state why the defect happens. Decide `root_cause_addressed` and be able to defend it.
+
+*Prevents:* approving a change that suppresses the failure and leaves the defect.
+
+**5. Read for what is missing.** The hardest step and the one with the most yield. For each changed function:
+
+- **Callers.** Grep the symbol across the repo; for an endpoint use `find_consumers` (heuristic — it matches literal path strings, so a client assembling URLs from fragments is missed). Does every caller still hold? Are any of them in the diff, and should they be?
+- **The other branch.** The fix handles the reproduced path. What about the error path, the empty case, the zero and the many, the unauthenticated caller, the second tenant?
+- **The symmetric site.** If a read was fixed, was the write? If create was fixed, what about update? A defect in one half of a pair is usually in both.
+- **Concurrency and ordering**, when shared state or async is involved.
+- **The test that is absent.** Is there a case the change obviously affects and no test asserts?
+
+*Prevents:* the single most common review outcome — every line present is correct, and the change is still wrong.
+
+**6. Test quality.** `test-quality-audit` in full. Do not treat the suite result as the answer to this step.
+
+**7. Blast radius.** `regression-risk-scoring`. Grade low, medium or high, and carry the grade into the verdict.
+
+**8. Rollback note.** `rollback-plan-authoring` lists what it must contain. A note with no signal to watch, or no irreversibility section, is `REQUEST_CHANGES` on its own — it is cheap to ask for and expensive to be without.
+
+**9. Scope.** Count files and lines against the budget (5 / 150). Then ask of each hunk not required by the fix: does it add risk? Unnecessary-and-risky is `REQUEST_CHANGES`. Unnecessary-and-inert is worth one line in `concerns`, not a round trip.
+
+## "The tests pass" is the floor
+
+A green suite tells you that the tests that were selected, and that actually ran, did not detect a problem. It does not tell you:
+
+- that the right tests were selected — `affected_tests` is documented as a heuristic, not coverage-derived;
+- that the new tests would fail against the unfixed code;
+- that the tests assert behaviour rather than that a function returned;
+- that anything at all covers the callers, the error branch, or the other tenant;
+- that the failures which remain are pre-existing rather than caused here.
+
+You are here to catch what the tests do not. If your review would have been identical without reading the diff, you have added nothing that CI did not already provide.
+
+## The failure of approving because it looks reasonable
+
+Plausible-looking diffs are the *default* output of a competent model, so plausibility carries almost no evidence about correctness in this system. The feeling of "this seems fine" arrives with equal strength for a correct fix and for a confident symptom fix, and it arrives before step 5 has been done.
+
+The countermeasure is mechanical. Before deciding, write one sentence of the form:
+
+> **This fix is wrong if \<X\>.**
+
+Then go and check X. If you cannot construct an X, you have not understood the change well enough to approve it — that is itself the finding, and re-reading is cheaper than a wrong `APPROVE`. Good Xs are specific: *"...if any other caller passes a null there"*, *"...if the list can be empty"*, *"...if two requests race on that cache key"*.
+
+## Never request a change the author is not permitted to make
+
+Before you write `REQUEST_CHANGES`, check that the author can actually perform
+the change you are asking for. Its write scope is declared in
+`config/agents/<agent>.yaml` under `write_paths`, and you can read that file.
+A path outside it will be refused by the guardrail no matter how right you are.
+
+This is not a formality. A review that demands a forbidden edit deadlocks the
+loop: the author tries, the guardrail refuses, the review repeats, and the two
+round trips are spent before anyone can see that the requirement and the
+permission contradict each other. It has happened here — a reviewer required a
+calibration file to be updated in the same commit while the fixing agent's
+sandbox excluded that file by design, and the ticket escalated twice with a
+correct one-line fix sitting on the branch the whole time.
+
+So when a change is genuinely needed but out of the author's reach:
+
+- **Do not withhold approval on it.** Judge the diff you were given on its own
+  merits. If the fix is sound, `APPROVE` and record the outside work under
+  `concerns`, naming who has to do it.
+- **If it is serious enough to block shipping**, `ESCALATE_TO_HUMAN` and say
+  plainly that it is out of the author's envelope — do not route it through
+  `REQUEST_CHANGES` first and burn a round trip discovering that.
+- **Artifacts an agent is deliberately barred from** — answer keys, calibration
+  corpora, scoring oracles — are barred so the measured cannot edit the measure.
+  Their maintenance is someone else's job by design, never a defect in the diff
+  in front of you.
+
+## The verdict
+
+`record_review` takes exactly one decision and rejects reasoning under 40 characters, because an approval with no reasoning is the shape a rubber stamp takes.
+
+| Situation | Decision |
+|---|---|
+| Cause addressed, diff minimal, tests discriminate, risk low or mitigated | `APPROVE` |
+| Something specific and nameable is wrong, and MENDER is permitted to change it — check `write_paths` | `REQUEST_CHANGES` |
+| Right fix is outside MENDER's envelope, risk is high and unmitigated, or you cannot responsibly judge it | `ESCALATE_TO_HUMAN` |
+
+- **Note a residual concern even when approving.** Use `concerns`. A reviewer with no concerns has usually not looked hard enough.
+- **`REQUEST_CHANGES` goes back to MENDER verbatim** and it cannot act on vagueness. Name the file, name what is wrong, say what would make it right. "Consider improving error handling" is not a review.
+- **Round trips are capped at two per ticket**, then the conductor escalates. A vague `REQUEST_CHANGES` spends half a ticket's remediation budget on a message nobody can act on.
+- **Do not request changes on style, naming, or how you would have written it.** You have one question: should this change ship? Everything else costs a round trip and teaches the system that your reviews can be skimmed.
+- Escalating is a legitimate outcome, not a failure to decide.

qaas/plugin/skills/api-surface-extraction/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: api-surface-extraction
+description: >
+  Extract every HTTP and WebSocket endpoint with its method, path, handler and
+  real auth requirement. TRIGGER - read BEFORE recording routes in a system map
+  or auditing an API surface, and whenever the task mentions endpoints, routes,
+  the API surface, handlers, or 'what does this service expose'. Do NOT trust a
+  spec file as the list of what exists. SKIP only when the route inventory is
+  already available from the system map.
+---
+
+# Extracting the API surface
+
+## Find routes three ways, then reconcile
+
+1. **The router.** Decorators, route tables, `include_router` calls. Follow prefixes — a router mounted under `/v1` means every path inside it is longer than it looks.
+2. **The declared spec.** OpenAPI, protobuf, GraphQL schema.
+3. **The generated spec**, if the framework produces one at runtime (`/openapi.json`). This is what the framework thinks it implements, which is a third and distinct thing.
+
+Reconciling these three is where the findings are. A route in the spec but not the router is a broken promise to consumers. A route in the router but not the spec is undocumented surface, often forgotten and unmaintained.
+
+## Record auth as the code enforces it
+
+This is the field most often recorded wrong, because it is the one people record from intent rather than observation.
+
+- A dependency that extracts a user is **authentication**. It says who you are.
+- A check on role, org, or ownership is **authorization**. It says what you may touch.
+- An endpoint with the first and not the second is authenticated and unguarded — a very common and very serious defect.
+
+Record what the handler actually checks, per endpoint, not what the router group implies. Middleware that "protects" a prefix must be verified to apply to each route under it, not assumed to.
+
+## Order-sensitive registration
+
+Where a literal path and a parameterised path overlap (`/orders/legacy` and `/orders/{id}`), **registration order decides which wins**. Record the order. A literal registered after a greedy parameterised route is unreachable — and reachability is not visible in a spec.
+
+## Also record
+
+Pagination parameters and whether they are actually applied; the error shape each endpoint returns; the status codes it can produce. Downstream agents test against these and cannot infer them.

qaas/plugin/skills/authz-matrix-check/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: authz-matrix-check
+description: >
+  Check every endpoint against the role matrix to find missing authorization.
+  TRIGGER - read BEFORE auditing any endpoint for permissions, and whenever the
+  task mentions authorization, roles, permissions, access control, IDOR,
+  tenancy, multi-tenant scoping, or 'who can call this'. Do NOT treat the
+  presence of an auth dependency as evidence that access is checked - that
+  confusion is the defect this skill exists to catch. SKIP only when no endpoint
+  has an access-control requirement.
+---
+
+# Auditing authorization
+
+## The distinction that produces the defect
+
+**Authentication** proves who you are. **Authorization** decides what you may touch. An endpoint with the first and not the second is the most common serious API defect there is, and it looks correct at a glance because there is clearly an auth dependency on the handler.
+
+Two questions per endpoint, always separately:
+
+1. Does it establish an identity?
+2. Does it check that *this* identity may act on *this* resource?
+
+## Build the matrix
+
+Rows are endpoints, columns are roles, plus a column for "resource belonging to another tenant". Fill each cell with what the code actually does, and compare against what the spec or product intent says it should. Every disagreement is a candidate finding.
+
+Do not fill a cell from the router group or a middleware prefix. Verify per handler — a route added later under a "protected" prefix very often misses the check that its neighbours have.
+
+## Three failure shapes
+
+- **Missing role check.** Handler requires a user, never inspects the role. A viewer can refund.
+- **Missing tenancy scope.** Lookup filters by resource id alone, not by the caller's organization. Any authenticated user reads any record by guessing an id. This is the highest-severity shape and the easiest to miss, because the endpoint behaves perfectly for the tester's own data.
+- **Check that cannot fail.** The check exists but reads a client-supplied value, or compares the resource's own org against itself.
+
+## Read the neighbours
+
+The strongest signal is inconsistency. When five handlers in a file filter on `org_id` and the sixth does not, that sixth is almost certainly a dropped clause rather than a deliberate exception. Symmetry-breaking is the cheapest defect detector available here.
+
+## Prove it, carefully
+
+Demonstrate with two accounts: create a resource as one, read it as the other, capture the response. That is proof.
+
+Do not escalate beyond demonstrating access. Do not extract data volume, do not chain into further systems, do not test how much you can reach. One captured cross-tenant read is complete evidence; anything past it is an incident of your own making.
+
+Everything found here is `security_relevant: true` and routes restricted. See `routing-rules`.

qaas/plugin/skills/console-error-triage/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: console-error-triage
+description: >
+  Decide which browser console output is a defect and which is noise. TRIGGER -
+  read BEFORE reporting anything seen in a browser console, and whenever the
+  task mentions console errors, warnings, unhandled rejections, or JavaScript
+  errors. Do NOT report console output without triaging it - warnings are not
+  defects and filing them destroys precision. SKIP only when no console output
+  is involved.
+---
+
+# Triaging console output
+
+## The classification
+
+| Seen | Verdict |
+|---|---|
+| **Unhandled promise rejection** | **Always a defect.** A code path with no error handling, running in production. |
+| **Uncaught exception during a normal journey** | **Defect.** Whatever came after it did not run. |
+| **Failed network request the UI does not surface** | **Defect.** The user sees a blank or stale page and no explanation. |
+| `console.error` from application code | Usually a defect — the developer marked it as one. |
+| React key warnings, deprecation notices | Tech debt at most. Not a bug. |
+| `console.warn` from application code | **Not a defect** unless it names a real failure. Often deliberate signposting. |
+| Dev-only output behind an environment check | **Not a defect.** Never reaches users. |
+| Extension noise, source map warnings, favicon 404 | Not a defect. Not even the app. |
+
+## Read before you act
+
+Capture the console **before** interacting. An error already present on load did not come from your click, and attributing it to your click sends someone hunting in the wrong handler.
+
+## Dev-only is the trap
+
+Output behind `if (import.meta.env.DEV)` or `NODE_ENV !== 'production'` is invisible to users by construction. Reporting it as a defect is a false positive, and a particularly damaging one because it signals the finder did not read the surrounding line.
+
+## Report the consequence, not the text
+
+A stack trace pasted into a ticket is not a finding. What did the user lose? "The orders list stays permanently blank after a failed request, with no error shown and no retry" is actionable. "TypeError: cannot read property 'map' of undefined" is a symptom that could arise ten ways.
+
+Attach the trace as evidence. Lead with what broke.

qaas/plugin/skills/contract-test-generation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: contract-test-generation
+description: >
+  Write a runnable test that asserts an endpoint's declared contract, to attach
+  as evidence. TRIGGER - read BEFORE producing any contract test or attaching
+  test evidence to an API finding, and whenever the task mentions contract
+  tests, evidence for an API defect, or proving a spec violation. Do NOT attach
+  a test you have not executed against both the violating and the conforming
+  behaviour. SKIP only when the finding is not a contract violation.
+---
+
+# Generating a contract test
+
+A contract test is the difference between a finding an engineer argues with and one they fix. It converts "the response is missing a field" into a red test with a name.
+
+## What it must do
+
+- **Fail now, for the stated reason.** Run it. A test that passes against the current implementation is not evidence of a defect — it is evidence you misread the code.
+- **Pass once fixed.** Assert the contract, not the current behaviour inverted. `assert "currency" in body` is a contract; `assert "currency" not in body` pins the bug in place permanently.
+- **Be readable by whoever picks up the ticket.** The test name states the contract: `test_invoice_response_includes_currency`, not `test_api_06`.
+
+## Assert exactly one thing
+
+One contract violation, one test. A test asserting status, shape, and auth together fails on whichever it hits first, and the reader learns one third of what you knew.
+
+## Include the setup
+
+Which fixture, which role, which token. A test that only passes on a machine where someone happened to log in first is not evidence, and it will be deleted the first time it fails in CI.
+
+## Assert the shape, not the payload
+
+Assert that `currency` is present and is a three-character string. Do not assert `currency == "USD"` unless the contract fixes that value — otherwise the test breaks on a legitimate data change and gets deleted, taking the real assertion with it.
+
+## Name the source
+
+A comment giving the spec path and the clause being asserted (`openapi.yaml: Invoice.required includes currency`) means the next reader can check whether the contract itself was wrong, which is sometimes the right answer.