qa-agent-kit 0.6.0__tar.gz

qa_agent_kit-0.6.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "younatics",
+  "description": "Plugins by younatics: QAKit, the QA agent kit",
+  "owner": {
+    "name": "younatics",
+    "url": "https://github.com/younatics"
+  },
+  "plugins": [
+    {
+      "name": "qakit",
+      "source": "./",
+      "description": "QA procedures for coding agents (qa-rigor, device-qa, prose-qa) and the kit's tools as an MCP server",
+      "category": "testing",
+      "tags": ["qa", "testing", "mutation-testing", "ios", "prose"]
+    }
+  ]
+}

qa_agent_kit-0.6.0/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "qakit",
+  "displayName": "QAKit",
+  "version": "0.5.1",
+  "description": "The QA agent kit: qa-rigor, device-qa and prose-qa procedures, and the kit's tools (real-device runs, release checks, mutation testing, prose gates, verdict ledger) as MCP tools",
+  "author": {
+    "name": "younatics",
+    "url": "https://github.com/younatics"
+  },
+  "homepage": "https://github.com/younatics/QAKit",
+  "repository": "https://github.com/younatics/QAKit",
+  "license": "MIT",
+  "keywords": ["qa", "testing", "mutation-testing", "ios", "xcuitest", "app-store", "prose"],
+  "skills": ["./skills/"],
+  "mcpServers": {
+    "qakit": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.py"]
+    }
+  }
+}

qa_agent_kit-0.6.0/.gitignore

@@ -0,0 +1,10 @@
+.build/
+.swiftpm/
+DerivedData/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.xcresult
+/artifacts/
+dist/
+*.egg-info/

qa_agent_kit-0.6.0/AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md: how an AI coding agent uses QAKit
+
+This file is read by agents that follow the `AGENTS.md` convention (Codex, Cursor, Aider, OpenHands, Gemini CLI and
+others). Claude Code reads it through `CLAUDE.md`. It says what the kit is and which procedure to load for which job.
+Copy or link it into the project that uses the kit, or point that project's own AGENTS.md here.
+
+## What this is
+
+QAKit is a QA agent kit: procedures (`skills/*/SKILL.md`), deterministic tools (`tools/*.py`, `Sources/QAKit`), and
+the evidence formats a verdict cites (`docs/report.md`). The agent is the QA team; the tools make its findings
+reproducible and its verdicts citable.
+
+## Pick the procedure
+
+| The job | Load | Run |
+|---|---|---|
+| Any code change before merge or release | `skills/qa-rigor/SKILL.md` | `python3 tools/mutate.py --config <mutation.json> --changed-since origin/main` |
+| An Apple app before TestFlight or App Review | `skills/device-qa/SKILL.md` and `docs/device-qa-protocol.md` | `python3 tools/device_qa.py doctor --manifest <device_qa.json>`, then `test`, then `python3 tools/release_checks.py` |
+| A memo, README, design doc, paper or post | `skills/prose-qa/SKILL.md` | `python3 tools/prose_check.py <file.md> --claims claims.csv` |
+
+Read the skill fully before running a tool. Each skill ends with the verdict format; produce it, including what you did
+not run and why.
+
+## Rules the kit assumes
+
+- Expected values are written before the test, the fix or the edit. Three values at every boundary.
+- Green tests are not a verdict. The verdict is the ledger: gates run, results, gates skipped with one line of risk each.
+- A survivor in a mutation report gets a test or a `mutation-ok: <reason>` on the line. Never an exclusion to lift a score.
+- On a phone, evidence goes into the result bundle (`QA.snap`, `QA.note`), never to a Mac path.
+- Submission to review, a release request or a destructive action waits for the owner's explicit word.
+- A gap in the kit (a tool that needs a workaround, a protocol row that is wrong) is fixed in the kit with a test and
+  released by tag (`RELEASING.md`), not patched in the consumer project.
+
+## Install the skills into your agent
+
+`python3 tools/install_skills.py --target claude --scope project` (or `codex`, `cursor`, `gemini`, `all`; `--scope user`
+for your home folder). It links `skills/*` into the folder each tool reads and writes a one-line rule file where the
+tool needs one. `skills/README.md` has the manual steps.
+
+## Layout
+
+```
+skills/        qa-rigor · device-qa · prose-qa
+tools/         mutate.py · device_qa.py · release_checks.py · prose_check.py · install_skills.py
+Sources/QAKit  Swift helpers for XCUITest targets (snap, audit, sweep, alerts, settle)
+docs/          protocol (en, ko), manifest, report, getting started, mutation testing, prose QA
+tests/         pytest; mutation.json measures the kit's own tests
+```

qa_agent_kit-0.6.0/CHANGELOG.md

@@ -0,0 +1,202 @@
+# Changelog
+
+All notable changes to QAKit. The format follows Keep a Changelog; versions follow SemVer (MAJOR: a tool flag, manifest
+key, Swift API or skill step removed or renamed; MINOR: added; PATCH: fixed).
+
+## [Unreleased]
+
+## [0.6.0] - 2026-10-29
+
+### Added
+
+- On PyPI as `qa-agent-kit` (PyPI refused `qakit` as too similar to the existing `qa-kit`); the import name and the
+  `qakit-*` commands are unchanged.
+
+- Swift: `QA.searchField(app, prompt:)` finds the search field wherever iOS 26 puts it: `searchFields`, the bottom bar's
+  text field, or behind the minimised Search button, which it taps. `QA.flip(toggle)` taps a SwiftUI Toggle's inner
+  switch, because a tap at the row's centre hits the label and changes nothing. `QA.tree(app, step, in:)` attaches the
+  element tree as text evidence when something cannot be found.
+- Explained audit class "system bar button": a Cancel, Save or Done drawn by iOS in any navigation bar or toolbar (a sheet's
+  own bar included) is measured by the audit against the content behind it and reported as low contrast, fixed size
+  ("Dynamic Type font sizes are partially unsupported") or clipped.
+- Swift: `QA.count(query, in: app)` counts the rows of a lazy list that keeps only the visible ones in the tree (pages down
+  until a page adds nothing, then back to the top).
+- `shots` index: Xcode 27.2's attachment manifest suffixes every readable name with `_<n>_<UUID>.<ext>`; the index shows
+  the step name alone again.
+- `doctor` names two more reasons a device run cannot start: a project pinned to manual App Store profiles (and the
+  manifest `xcodebuild_args` override that fixes it) and a login keychain locked for the session (`codesign
+  errSecInternalComponent`: run the phone commands from a GUI-session LaunchAgent). Both found on Daynest.
+
+### Fixed
+
+- `QA.reveal`: a lift from under a floating bar never starts in the bottom 12% of the screen. A press there dragged up is
+  the Home / app-switcher gesture, and it put the phone in the app switcher mid-walk on Daynest. An element whose centre
+  is past the screen's side edge (a horizontal carousel) is dragged in sideways instead of paged vertically forever.
+- `QA.closeInAppSafari` falls back to a live query for Safari's own Done button when the tree snapshot cannot be taken over a
+  heavy web page.
+- `device_qa.py` puts Xcode's `usr/bin` first on PATH so xcodebuild's own `xcrun` finds `devicectl` (the diagnostics step
+  failed on a Mac whose shell PATH lacked it).
+- `examples/Notes`: the walkthrough uses the helpers above; the stored-note count is a row (a section footer is reported
+  as fixed-size text), the About link is a plain row (a `Label` is reported as clippable text), the list body has no line
+  limit. Found on its first two device runs (iPhone 14 Pro, iOS 27.2).
+
+## [0.5.2] - 2026-10-29
+
+### Fixed
+
+- `device_qa.py`: a tool that does not answer within its timeout (an `xcrun devicectl` that hangs when CoreSimulator is older
+  than Xcode) comes back as a failed step with a one-line reason instead of a traceback; `doctor` prints that reason and still
+  validates the manifest when no phone answers.
+
+### Added
+
+- `examples/Notes`: a small SwiftUI app (three tabs, 538 lines) with a complete `NotesQAWalkthroughTests`, a `device_qa.json`,
+  a `NotesCore` package with a mutation config, and two deliberate defects (a 2.7:1 caption, a dead Help button) the walk is
+  meant to find. `examples/README.md` walks a newcomer through the whole loop.
+
+- `mcp/server.py`: a stdio MCP server with no third-party dependency (`device_doctor`, `device_test`, `device_shots`,
+  `device_crashes`, `device_traits`, `release_checks`, `mutation`, `prose_check`, `verdict`), and a Claude Code plugin
+  (`.claude-plugin/plugin.json`, `marketplace.json`: `claude plugin marketplace add younatics/QAKit`, then
+  `claude plugin install qakit@younatics`). `docs/agents.md` says how to attach the kit to each agent.
+- `tools/shots_gif.py`: a run's screenshots as one animated GIF in `index.md` order (needs Pillow), for demos and bug reports.
+
+- `pip install qakit`: `pyproject.toml` (hatchling, version from this file), `src/qakit/_cli.py` shims and five console
+  scripts (`qakit-mutate`, `qakit-prose`, `qakit-device`, `qakit-release-checks`, `qakit-install-skills`); the skills and docs
+  ship in the wheel so `qakit-install-skills` finds them (`docs/pypi.md`). The files landed in 0.5.1; not on PyPI yet.
+
+## [0.5.1] - 2026-10-29
+
+### Fixed
+
+- `release_checks.py` SUB-03: the file-timestamp pattern no longer matches `record.modificationDate` or `asset.creationDate`
+  (CKRecord and PHAsset properties, not file APIs); it keeps URL resource keys, attribute dictionaries, `attributesOfItem`,
+  `fileModificationDate`, `getattrlist` and the `stat` family. Found on the second app (Daynest's notification service).
+
+## [0.5.0] - 2026-10-29
+
+### Added
+
+- Protocol FEED-07: the production data path, with no fake-data flag, crosses its clock boundaries (midnight, the morning data job, cache expiry) with core data on screen at every instant. BUILD-01 now fails a cold launch that is alive but shows no core data. Both from Pawday's blank weather after midnight (2026-10-29).
+
+## [0.4.1] - 2026-10-28
+
+### Changed
+
+- `mutate.py` makes no mutants on typing-only Python (`TYPE_CHECKING = False`, the body of `if TYPE_CHECKING:`, `@overload`
+  stubs, the test of `if sys.version_info ...`) and no drop-call on a C-family call that continues the previous line
+  (`let x =`, an open `(`, a trailing `,` or operator). Both classes came from `docs/case-studies.md`: every one was
+  equivalent or an invalid build.
+
+## [0.4.0] - 2026-10-28
+
+### Added
+
+- Manifest `fingerprint_root`: the folder whose edits mark a round as mixed, for apps whose core sources live beside the project
+  folder (Elsewhen).
+- `QA.reveal(clearOf:)` lifts a covered element by the exact distance, slowly, from the margin at its height to a third of the
+  screen; a page fling overshot a cover strip narrower than the fling (Elsewhen, large text).
+
+### Fixed
+
+- The source fingerprint excludes the run's own DerivedData folders, so an app whose build folder is not gitignored no longer
+  reports every round as `sources_changed_during_run` (Elsewhen).
+
+## [0.3.1] - 2026-10-28
+
+### Fixed
+
+- `QA.settleAfterLaunch(app)` and `Use VoiceOver` / `VoiceOver 사용` in the allow labels: the first time `--variant voiceover`
+  switches VoiceOver on, iOS 27.2 shows a welcome prompt over the app and swallowed the smoke test's first tap (reported by the
+  Elsewhen session from a screen recording, 2026-10-28). The manifest and skill docs say where to call it.
+
+## [0.3.0] - 2026-10-28
+
+### Added
+
+- `QA.reveal(_:in:hittable:clearOf:)`: floating covers (a bottom bar, the tab bar) to drag clear of. On iOS 27 an element
+  under a floating bar still reports hittable and the tap lands on the bar (proposed by the Elsewhen session after a
+  large-text device run, 2026-10-28).
+
+### Fixed
+
+- `tests/test_install_skills.py` sandboxes HOME and `Path.home()`: a mutated `--scope` check in a mutation run linked
+  skills into the real `~/.claude/skills` and `~/.agents/skills` (dangling links to the scratch copy, 2026-10-28).
+
+## [0.2.0] - 2026-10-28
+
+The consumer monorepo had moved on while 0.1.0 was being cut: four sessions QA-ing four apps on one phone had grown the
+runner and the Swift helpers. This release ports all of it, generalized.
+
+### Added
+
+- `tools/device_qa.py` gained six commands and three options. `perf` runs with Time Profiler attached and reads
+  Instruments' potential hangs and hang risks. `upgrade` builds the previous release in a temporary worktree, seeds it,
+  installs this build over it and runs the check test with QA_UPGRADE=1. `release` exports the Release archive for the
+  phone and cold-launches it with no debugger. `traits` changes text size and dark mode on each screen, in front and in
+  the background, and the process must survive. `lock status` and `lock run` share the phone. `test --only` and
+  `--configuration Release` narrow a run, and a source-tree fingerprint fails a round whose sources changed mid-run
+  (`sources_changed_during_run`). Manifest keys `bundle_id`, `team_id`, `traits`, `upgrade`, `release.version`.
+- `tools/device_lock.py`: one phone, many sessions. flock on `~/.qakit/device-qa/<udid>.lock` plus arrival-order tickets;
+  `QAKIT_DEVICE_NOTE` names the holder, `QAKIT_DEVICE_HELD` lets a holder's children share its turn, `--no-wait` exits 75.
+- `tools/recording_frames.swift` (frames and a contact sheet from a UI-test screen recording, or screenshots tiled side by
+  side) and `tools/screenshot_contrast.swift` (the real WCAG contrast of text in a screenshot box).
+- Swift: `QA.walk` (snap, audit, sweep, scroll until the bottom), `QA.back`, `QA.closeInAppSafari`, `QA.exitSearch`,
+  `QA.onScreen`, `QA.reveal`, `QA.visibleButtons`, `QA.tap(frame)`, `QA.waitForStill`, `QA.tapUntilGone`, `QA.replaceText`,
+  `QA.switches(labelled:)`, `QA.waitForValue`, `QA.explainedReason`. `QA.audit` retries once on an audit timeout, attaches
+  Apple's detailed description and counts the classes the protocol explains (off screen, under the tab bar, empty-label
+  text field, nearly-passed secondary text) instead of failing them. `QA.sweepButtons` reads one snapshot of the tree and
+  taps coordinates (live queries by index kept the main thread busy and went stale), with `idPrefix`.
+  `QA.answerSystemAlert` only asks hosts that are in front (a suspended BusinessActionSheet cost 31 s per ask).
+- `tools/release_checks.py`: SUB-12 rejects markup in store text (App Store Connect refuses `<library>`), SUB-15 checks
+  the age-rating block carries `socialMedia`; `--ipa` without `codesign` on the machine is a WARN, not a crash.
+- `docs/case-studies.md`: the mutation layer measured on three public projects (80 to 86 percent scores; 7 of 15 sampled
+  survivors were real test gaps, 6 equivalent, 2 engine noise), with the engine improvements it points at.
+- Protocol: INT-06 (trait changes), SUITE-08 rewritten around mutation testing, BUILD-01, BUILD-04 and PERF-05 name the new
+  commands, step 6a and exit criterion 3a (the mutation gate), in both editions.
+
+### Fixed
+
+- `device_qa.py lock run --note <who> -- <command>`: `--note` was swallowed into the command (argparse REMAINDER) and the
+  holder showed up under the default name; found by the kit's own CLI test.
+
+### Changed
+
+- `QA.dismissTopmost(_:closers:rootTitle:onPushedPage:)` replaces the 0.1.0 `closeIdentifiers:` form and
+  `QA.settle` takes `closers:` and `rootTitle:`. `QA.sweepScrolling` is gone; `QA.walk` does its job.
+- `validate_manifest` reports `<key> must be a non-empty string` (0.1.0 said `missing <key>`) and requires `schema_version`.
+- `swift build` on macOS: the iOS-only `textClipped` audit type is guarded, so the package builds on a Mac host and in CI.
+
+
+## [0.1.0] - 2026-10-28
+
+First release, extracted from a private monorepo where the three layers had been in daily use.
+
+### Added
+
+- `skills/qa-rigor`: the nine principles, the mutation-testing procedure, the verdict ledger.
+- `tools/mutate.py`: mutation testing for Python (tokenize and ast) and C-family syntax (Swift, JS/TS, Kotlin, Go, Java,
+  C#); throwaway copies, coverage-aware uncovered reporting, `--changed-since`, `--resume`, seeded samples.
+- `skills/device-qa` and `docs/device-qa-protocol.md`: 24 areas, 180 checks with IDs, pass criteria, methods, severities
+  and sources; English and Korean editions.
+- `tools/device_qa.py`: `doctor`, `devmode`, `test` under device-wide variants (appearance, text size, location,
+  VoiceOver, language) with automatic restore, `shots` contact sheets, `crashes`; `--manifest` or `--app` resolution;
+  App Store Connect key signing from a `signing` block or an `appstore_config` file; `summary.json`
+  (`qakit.device-qa.summary.v1`).
+- `tools/release_checks.py`: store metadata limits and placeholders, first-release wording after 1.0, review note
+  length, localized purpose strings, required-reason API declarations per bundle, links, AASA on Apple's CDN, IPA
+  entitlements.
+- Swift package `QAKit` (iOS 17+): `snap`, `note`, `assertInFront`, `audit`, `answerSystemAlert`, `dismissTopmost`,
+  `settle`, `sweepButtons`, `sweepScrolling`; labels, alert hosts and locales configurable through `QA_*` environment.
+- `skills/prose-qa`, `docs/prose-qa.md` and `tools/prose_check.py`: outline, sentence length, duplicates, unsourced
+  claims, unexpanded acronyms, links, machine-writing tells; a claims ledger skeleton CSV.
+- `AGENTS.md` for any agent that reads the convention, and `tools/install_skills.py` that links the skills into Claude
+  Code, Codex, Cursor and Gemini CLI (project or user scope, idempotent, uninstall).
+- `examples/device_qa.json`, `docs/manifest.md`, `docs/report.md`, `docs/getting-started.md`, `docs/mutation-testing.md`.
+- `tests/`: 150 tests over the five Python tools, the installer and the mutation engine, including the command layer of
+  `device_qa.py` driven with a fake `run`; `mutation.json` measures the kit's own tests (first run: 47% with the command
+  layer untested, which is why the flow tests exist).
+
+### Fixed
+
+- `device_qa.py`: an empty `--json-output` file from a failed `devicectl` call raised instead of returning `{}`.
+- `release_checks.py --json`: the summary line went into stdout and broke JSON parsing; it goes to stderr now.

qa_agent_kit-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thank you for looking. QAKit is small on purpose: three Python tools, one Swift file, three skills and a protocol.
+
+## Ground rules
+
+- **Every check comes from a defect.** A new gate, operator or protocol row names the defect it would have caught, in its
+  docstring or its table row. Checks without a story get removed.
+- **Deterministic tools, bare interpreters.** `tools/*.py` run on Python 3.11+ with the standard library; `pytest` is the
+  only test dependency. The Swift package depends on XCTest only.
+- **Tests before merge.** A change to a tool comes with a test that fails without it. Run `python3 -m pytest -q tests`,
+  `python3 -m pyflakes tools tests`, `swift build`, and the mutation gate from `RELEASING.md`.
+- **Docs in the same commit.** A tool flag, a manifest key or a Swift API appears in `docs/` and in the skill that uses it
+  in the commit that adds it. Both protocol editions (`docs/device-qa-protocol.md`, `docs/ko/device-qa-protocol.md`)
+  move together.
+- **Plain prose.** Short sentences, no em dashes, no "Firstly". `python3 tools/prose_check.py` on what you wrote.
+
+## Layout
+
+```
+Sources/QAKit/QAKit.swift   Swift helpers for XCUITest targets
+tools/                      device_qa.py · release_checks.py · mutate.py · prose_check.py
+tests/                      pytest for the tools and the mutation engine
+skills/                     qa-rigor · device-qa · prose-qa (SKILL.md each)
+docs/                       protocol (en, ko), manifest, report, getting started, mutation testing, prose QA
+examples/                   a complete device_qa.json
+```
+
+## Reporting a gap
+
+Open an issue with: the tool and version, the command, what happened, what you expected, and the evidence folder's
+`summary.json` or the mutation report when it applies. A failing test is the best report.

qa_agent_kit-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeungYoun Yi (younatics)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qa_agent_kit-0.6.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: qa-agent-kit
+Version: 0.6.0
+Summary: The QA agent kit: mutation testing for any repo, prose gates with a claims ledger, and real-device QA for Apple apps, with the procedures an AI coding agent follows.
+Project-URL: Homepage, https://github.com/younatics/QAKit
+Project-URL: Changelog, https://github.com/younatics/QAKit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/younatics/QAKit/blob/main/docs/getting-started.md
+Author: younatics
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,codex,ios,mutation-testing,prose,qa,xcuitest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pyflakes; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/banner.svg" alt="QAKit: the QA agent kit" width="100%">
+</p>
+
+# QAKit
+
+**The QA agent kit.** Procedures an AI coding agent follows to test like a QA engineer, the tools that run the checks,
+and the evidence format a release verdict cites. Three layers, one repo:
+
+| Layer | For | Skill | Tools |
+|---|---|---|---|
+| Code | any repo with tests | `skills/qa-rigor` | `tools/mutate.py` (mutation testing, Python and C-family syntax) |
+| Real device | Apple apps | `skills/device-qa` | `tools/device_qa.py` (test, traits, perf, upgrade, release, one lock per phone), `tools/release_checks.py`, `recording_frames.swift`, `screenshot_contrast.swift`, Swift package `QAKit` for XCUITest |
+| Prose | memos, READMEs, papers | `skills/prose-qa` | `tools/prose_check.py` (gates and a claims ledger) |
+
+QAKit grew out of shipping several App Store apps as a solo developer whose QA team is an agent. Every check in it was
+added after a defect that green tests let through: a `>=` that became `>` at every grading boundary with 13 mutants
+surviving, a review note over the 4,000-character limit, a clipped caption nobody looked at, a What's New that still
+announced the first release in version 1.1.
+
+## See it
+
+<p align="center"><img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/demo-walk.gif" alt="An agent walking an app on a real iPhone: onboarding, the home screen at every scroll position, each button tapped once" width="300"></p>
+
+`QA.walk` on a real iPhone: the onboarding pages, the home screen at every scroll position, every visible button tapped once
+and screenshotted, the accessibility audit per screen. These 29 frames are one walkthrough test's attachments, assembled by
+`tools/shots_gif.py` from the result bundle (the app is the author's, live on the App Store).
+
+<p align="center"><img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/demo-variants.gif" alt="The Notes example app's list, settings and search screens in the default, dark and large-text variants, one phone, one command" width="300"></p>
+
+The same walk in three variants: `device_qa.py test --variant default --variant dark --variant large-text` switches the
+phone's appearance and text size between runs. These nine frames are the `examples/Notes` app's list, settings and
+search screens from one such run.
+
+## What makes it different
+
+- **Systematic, not random.** `QA.sweepButtons` taps every visible button on every screen at every scroll position,
+  screenshots what opened, checks the app is still in front and goes back. Monkey testers tap at random; agents reviewing a
+  contact sheet need every control seen once.
+- **The whole phone changes, not the app.** `device_qa.py test --variant dark` switches the device to dark mode, large
+  accessibility text, a simulated location or VoiceOver through Xcode 27's `devicectl`, runs the suite, and restores iOS
+  defaults. System alerts and other apps render the same way the user will see them.
+- **Apple's accessibility audit on every screen,** collected into one report per screen instead of stopping at the first
+  issue, with an allow list for reviewed exceptions.
+- **Test strength is measured.** Coverage says a line ran. Mutation testing says whether a test would notice if the
+  line were wrong. The gate is "every mutant on a changed line is dead or explained".
+- **Prose gets the same treatment.** Deterministic gates, then a claims ledger where every number is traced to a quote,
+  then a cold read by a reader who did not write it.
+- **Written for agents.** The skills are `SKILL.md` files a coding agent loads. The protocol has 180 checks with IDs,
+  pass criteria, methods and sources, so an agent can cite what it did and what it skipped.
+
+## Quick start
+
+```bash
+pip install qa-agent-kit                           # qakit-mutate, qakit-prose, qakit-device, qakit-release-checks, qakit-install-skills
+# or from source
+git clone https://github.com/younatics/QAKit.git
+cd QAKit && python3 -m pytest -q tests          # 150 tests, no dependency beyond pytest
+
+# mutation testing on any project
+python3 tools/mutate.py --root ../myproject --source 'src/**/*.py' --test '{orig}/.venv/bin/python -m pytest -x -q'
+
+# prose
+python3 tools/prose_check.py ../memo.md --claims claims.csv
+
+# an Apple app on a USB-attached test iPhone (macOS, Xcode 27)
+python3 tools/device_qa.py doctor --manifest ../myapp/release/testing/device_qa.json
+python3 tools/device_qa.py test --manifest ../myapp/release/testing/device_qa.json --suite qa --variant dark
+```
+
+Give the procedures to your agent, whichever one you use:
+
+```bash
+claude plugin marketplace add younatics/QAKit && claude plugin install qakit@younatics   # Claude Code: skills + MCP tools
+python3 tools/install_skills.py --target claude --scope project      # or codex, cursor, gemini, all; --scope user
+claude mcp add qakit -- python3 /path/to/qakit/mcp/server.py        # any MCP client: doctor, test, shots, crashes, release checks, mutation, prose, verdict
+```
+
+Then read [docs/getting-started.md](docs/getting-started.md). [AGENTS.md](AGENTS.md) tells any agent which skill to load
+for which job.
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | Installing, linking the Swift package, the first walkthrough test, the first device run |
+| [docs/device-qa-protocol.md](docs/device-qa-protocol.md) | The protocol: 24 areas, 180 checks with IDs, exit criteria, what only a human can do ([한국어판](docs/ko/device-qa-protocol.md)) |
+| [docs/manifest.md](docs/manifest.md) | Every key of the `device_qa.json` manifest |
+| [docs/report.md](docs/report.md) | What a run leaves behind: `summary.json`, contact sheets, crash reports |
+| [docs/mutation-testing.md](docs/mutation-testing.md) | `mutate.py` operators, config, reports, how to read a score |
+| [docs/prose-qa.md](docs/prose-qa.md) | The prose gates and the claims ledger |
+| [docs/case-studies.md](docs/case-studies.md) | Does the mutation layer find real gaps? Measured on humanize, tenacity and swift-argument-parser |
+| [docs/pypi.md](docs/pypi.md) | The pip package: the five commands, where the skills land, the release procedure |
+| [examples/README.md](examples/README.md) | The Notes example app: build it, walk it, see the two planted defects reported |
+| [docs/agents.md](docs/agents.md) | Attaching the kit to Claude Code (plugin), Codex, Cursor, Gemini CLI and any MCP client |
+| [mcp/README.md](mcp/README.md) | The MCP server: nine tools, one stdio process, no dependencies |
+| [skills/README.md](skills/README.md) | Installing the skills by hand |
+| [ROADMAP.md](ROADMAP.md) | What comes next and the loop that keeps the kit honest |
+| [RELEASING.md](RELEASING.md) | How a change becomes a tagged release |
+
+## The Swift package
+
+```swift
+import XCTest
+import QAKit
+
+QA.snap("settings", in: self)                       // screenshot into the result bundle, named by variant
+QA.audit(app, "settings", in: self)                 // Apple's accessibility audit, every issue in one report
+QA.walk(app, "settings", in: self, deny: ["Delete"]) { QA.dismissTopmost(app) }   // snap, audit, sweep, scroll
+QA.answerSystemAlert()                              // permission prompts, in the phone's language
+QA.settle(app, on: screen, in: self) { relaunch() } // get back to a known screen, relaunch as the last resort
+```
+
+Requirements: iOS 17 or later for the accessibility audit, Xcode 15 or later to build, Xcode 27 or later for the
+device variants in `device_qa.py`.
+
+## Who runs it
+
+- The author's app monorepo pins the kit as a submodule and runs every layer on a USB-attached test iPhone.
+- [forge](https://github.com/younatics/forge), the multi-agent coding loop, runs the mutation and prose gates as merge
+  authority on every task and gives its reviewer the qa-rigor principles.
+- Gaps either of them hits come back here as a fix with a test and a tag (`RELEASING.md`).
+
+## Status
+
+Private beta. The three layers are in daily use on the author's apps and documents; the API and the manifest keys may
+still change between minor versions until 1.0. See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

qa_agent_kit-0.6.0/README.md

@@ -0,0 +1,131 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/banner.svg" alt="QAKit: the QA agent kit" width="100%">
+</p>
+
+# QAKit
+
+**The QA agent kit.** Procedures an AI coding agent follows to test like a QA engineer, the tools that run the checks,
+and the evidence format a release verdict cites. Three layers, one repo:
+
+| Layer | For | Skill | Tools |
+|---|---|---|---|
+| Code | any repo with tests | `skills/qa-rigor` | `tools/mutate.py` (mutation testing, Python and C-family syntax) |
+| Real device | Apple apps | `skills/device-qa` | `tools/device_qa.py` (test, traits, perf, upgrade, release, one lock per phone), `tools/release_checks.py`, `recording_frames.swift`, `screenshot_contrast.swift`, Swift package `QAKit` for XCUITest |
+| Prose | memos, READMEs, papers | `skills/prose-qa` | `tools/prose_check.py` (gates and a claims ledger) |
+
+QAKit grew out of shipping several App Store apps as a solo developer whose QA team is an agent. Every check in it was
+added after a defect that green tests let through: a `>=` that became `>` at every grading boundary with 13 mutants
+surviving, a review note over the 4,000-character limit, a clipped caption nobody looked at, a What's New that still
+announced the first release in version 1.1.
+
+## See it
+
+<p align="center"><img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/demo-walk.gif" alt="An agent walking an app on a real iPhone: onboarding, the home screen at every scroll position, each button tapped once" width="300"></p>
+
+`QA.walk` on a real iPhone: the onboarding pages, the home screen at every scroll position, every visible button tapped once
+and screenshotted, the accessibility audit per screen. These 29 frames are one walkthrough test's attachments, assembled by
+`tools/shots_gif.py` from the result bundle (the app is the author's, live on the App Store).
+
+<p align="center"><img src="https://raw.githubusercontent.com/younatics/QAKit/main/assets/demo-variants.gif" alt="The Notes example app's list, settings and search screens in the default, dark and large-text variants, one phone, one command" width="300"></p>
+
+The same walk in three variants: `device_qa.py test --variant default --variant dark --variant large-text` switches the
+phone's appearance and text size between runs. These nine frames are the `examples/Notes` app's list, settings and
+search screens from one such run.
+
+## What makes it different
+
+- **Systematic, not random.** `QA.sweepButtons` taps every visible button on every screen at every scroll position,
+  screenshots what opened, checks the app is still in front and goes back. Monkey testers tap at random; agents reviewing a
+  contact sheet need every control seen once.
+- **The whole phone changes, not the app.** `device_qa.py test --variant dark` switches the device to dark mode, large
+  accessibility text, a simulated location or VoiceOver through Xcode 27's `devicectl`, runs the suite, and restores iOS
+  defaults. System alerts and other apps render the same way the user will see them.
+- **Apple's accessibility audit on every screen,** collected into one report per screen instead of stopping at the first
+  issue, with an allow list for reviewed exceptions.
+- **Test strength is measured.** Coverage says a line ran. Mutation testing says whether a test would notice if the
+  line were wrong. The gate is "every mutant on a changed line is dead or explained".
+- **Prose gets the same treatment.** Deterministic gates, then a claims ledger where every number is traced to a quote,
+  then a cold read by a reader who did not write it.
+- **Written for agents.** The skills are `SKILL.md` files a coding agent loads. The protocol has 180 checks with IDs,
+  pass criteria, methods and sources, so an agent can cite what it did and what it skipped.
+
+## Quick start
+
+```bash
+pip install qa-agent-kit                           # qakit-mutate, qakit-prose, qakit-device, qakit-release-checks, qakit-install-skills
+# or from source
+git clone https://github.com/younatics/QAKit.git
+cd QAKit && python3 -m pytest -q tests          # 150 tests, no dependency beyond pytest
+
+# mutation testing on any project
+python3 tools/mutate.py --root ../myproject --source 'src/**/*.py' --test '{orig}/.venv/bin/python -m pytest -x -q'
+
+# prose
+python3 tools/prose_check.py ../memo.md --claims claims.csv
+
+# an Apple app on a USB-attached test iPhone (macOS, Xcode 27)
+python3 tools/device_qa.py doctor --manifest ../myapp/release/testing/device_qa.json
+python3 tools/device_qa.py test --manifest ../myapp/release/testing/device_qa.json --suite qa --variant dark
+```
+
+Give the procedures to your agent, whichever one you use:
+
+```bash
+claude plugin marketplace add younatics/QAKit && claude plugin install qakit@younatics   # Claude Code: skills + MCP tools
+python3 tools/install_skills.py --target claude --scope project      # or codex, cursor, gemini, all; --scope user
+claude mcp add qakit -- python3 /path/to/qakit/mcp/server.py        # any MCP client: doctor, test, shots, crashes, release checks, mutation, prose, verdict
+```
+
+Then read [docs/getting-started.md](docs/getting-started.md). [AGENTS.md](AGENTS.md) tells any agent which skill to load
+for which job.
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | Installing, linking the Swift package, the first walkthrough test, the first device run |
+| [docs/device-qa-protocol.md](docs/device-qa-protocol.md) | The protocol: 24 areas, 180 checks with IDs, exit criteria, what only a human can do ([한국어판](docs/ko/device-qa-protocol.md)) |
+| [docs/manifest.md](docs/manifest.md) | Every key of the `device_qa.json` manifest |
+| [docs/report.md](docs/report.md) | What a run leaves behind: `summary.json`, contact sheets, crash reports |
+| [docs/mutation-testing.md](docs/mutation-testing.md) | `mutate.py` operators, config, reports, how to read a score |
+| [docs/prose-qa.md](docs/prose-qa.md) | The prose gates and the claims ledger |
+| [docs/case-studies.md](docs/case-studies.md) | Does the mutation layer find real gaps? Measured on humanize, tenacity and swift-argument-parser |
+| [docs/pypi.md](docs/pypi.md) | The pip package: the five commands, where the skills land, the release procedure |
+| [examples/README.md](examples/README.md) | The Notes example app: build it, walk it, see the two planted defects reported |
+| [docs/agents.md](docs/agents.md) | Attaching the kit to Claude Code (plugin), Codex, Cursor, Gemini CLI and any MCP client |
+| [mcp/README.md](mcp/README.md) | The MCP server: nine tools, one stdio process, no dependencies |
+| [skills/README.md](skills/README.md) | Installing the skills by hand |
+| [ROADMAP.md](ROADMAP.md) | What comes next and the loop that keeps the kit honest |
+| [RELEASING.md](RELEASING.md) | How a change becomes a tagged release |
+
+## The Swift package
+
+```swift
+import XCTest
+import QAKit
+
+QA.snap("settings", in: self)                       // screenshot into the result bundle, named by variant
+QA.audit(app, "settings", in: self)                 // Apple's accessibility audit, every issue in one report
+QA.walk(app, "settings", in: self, deny: ["Delete"]) { QA.dismissTopmost(app) }   // snap, audit, sweep, scroll
+QA.answerSystemAlert()                              // permission prompts, in the phone's language
+QA.settle(app, on: screen, in: self) { relaunch() } // get back to a known screen, relaunch as the last resort
+```
+
+Requirements: iOS 17 or later for the accessibility audit, Xcode 15 or later to build, Xcode 27 or later for the
+device variants in `device_qa.py`.
+
+## Who runs it
+
+- The author's app monorepo pins the kit as a submodule and runs every layer on a USB-attached test iPhone.
+- [forge](https://github.com/younatics/forge), the multi-agent coding loop, runs the mutation and prose gates as merge
+  authority on every task and gives its reviewer the qa-rigor principles.
+- Gaps either of them hits come back here as a fix with a test and a tag (`RELEASING.md`).
+
+## Status
+
+Private beta. The three layers are in daily use on the author's apps and documents; the API and the manifest keys may
+still change between minor versions until 1.0. See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).