qa-agent-kit 0.6.0__py3-none-any.whl

qakit/tools/prose_check.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""Deterministic checks for prose (a memo, a README, a paper draft) before a reviewer or a model reads it.
+
+  python3 tools/prose_check.py draft.md                 # findings, defects first; exit 1 when a DEFECT is found
+  python3 tools/prose_check.py draft.md --json          # the same as a list
+  python3 tools/prose_check.py draft.md --claims claims.csv   # also write the claims ledger skeleton (docs/prose-qa.md)
+
+Gates (each a function `gate_*` returning findings; tests/test_prose_check.py pins them):
+  outline     heading levels that skip (H1 to H3), a heading with no body, a document with one H2
+  sentences   sentences over --max-words (default 35), paragraphs over --max-sentences (default 7)
+  duplicates  the same sentence twice
+  claims      a number, percentage, year, currency or "study/report/survey" sentence with no source marker nearby
+  acronyms    an acronym used without its expansion on first use
+  links       a Markdown link with an empty target, a bare "http" in prose, two links with the same text and different targets
+  tells       em dashes, "In conclusion", "Firstly", sentences in a row that start with the same word (three or more)
+
+Markdown only; code blocks and front matter are skipped. Language-agnostic where it can be (sentence splits on . ! ? and
+the Korean/Japanese full stop); the lexical tells are English.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+DEFECT, WARN = "DEFECT", "WARN"
+SENTENCE_END = re.compile(r"(?<=[.!?。])\s+")
+NUMBER = re.compile(r"(?<![\w/.-])(\d{1,3}(,\d{3})+|\d+(\.\d+)?)\s*(%|percent|x\b|억|만|천|k\b|m\b|bn\b|million|billion|USD|KRW|\$|€|£)?", re.IGNORECASE)
+YEAR = re.compile(r"\b(19|20)\d{2}\b")
+CLAIM_WORDS = re.compile(r"\b(study|studies|report|survey|research|according to|data show|evidence|benchmark|measured)\b", re.IGNORECASE)
+SOURCE_MARKER = re.compile(r"\[\d+\]|\[\^[^\]]+\]|\]\(https?://|https?://|\(20\d\d\)|\bet al\.|\bsource:|\bper\s+[A-Z]|\baccording to\b|\bp\.\s?\d|\bTable\s+\d|\bFigure\s+\d|\bFig\.\s?\d", re.IGNORECASE)
+ACRONYM = re.compile(r"\(([A-Z]{3,6})\)|\b([A-Z]{3,6})s?\b")   # group 1: an expansion "(ACR)", group 2: a use
+ACRONYM_SKIP = {"README", "HTTP", "HTTPS", "JSON", "HTML", "CSS", "URL", "URLS", "API", "APIS", "PDF", "CSV", "IPA", "CLI", "USA", "UK", "EU", "AND", "THE", "FOR", "NOT", "TODO", "FIXME", "MIT", "ASCII", "UTF", "ISO", "IEEE", "ACM", "GPU", "CPU", "RAM", "SSD", "USB", "SDK", "IDE", "OSS", "FAQ", "LLM", "LLMS", "AI", "UI", "UX", "QA", "CEO", "CTO", "CFO", "OK"}
+LINK = re.compile(r"\[([^\]]+)\]\(([^)]*)\)")
+INLINE_CODE = re.compile(r"`[^`]*`")
+TELLS = [(re.compile(r"—"), "em dash"), (re.compile(r"\bIn conclusion\b", re.IGNORECASE), "'In conclusion'"),
+         (re.compile(r"\b(Firstly|Secondly|Thirdly)\b"), "'Firstly/Secondly/Thirdly'"),
+         (re.compile(r"\bIt is (worth noting|important to note)\b", re.IGNORECASE), "'It is worth noting'"),
+         (re.compile(r"\bdelve\b", re.IGNORECASE), "'delve'")]
+
+
+@dataclass
+class Finding:
+    gate: str
+    severity: str
+    line: int
+    message: str
+    excerpt: str = ""
+
+
+@dataclass
+class Block:
+    """A prose unit of the document: a heading or a paragraph, with the 1-based line of its first line."""
+    kind: str      # "heading" | "paragraph" | "code"
+    level: int     # heading level, 0 for a paragraph
+    line: int
+    text: str
+
+
+def parse(text: str) -> list[Block]:
+    """Headings and paragraphs; fenced code, front matter, tables, list markers and HTML comments are left out."""
+    blocks: list[Block] = []
+    lines = text.splitlines()
+    in_code = in_front = False
+    para: list[str] = []
+    start = 0
+    for number, raw in enumerate(lines, 1):
+        line = raw.rstrip()
+        if number == 1 and line == "---":
+            in_front = True
+            continue
+        if in_front:
+            in_front = line != "---"
+            continue
+        if line.startswith("```") or line.startswith("~~~"):
+            if not in_code:
+                if para:
+                    blocks.append(Block("paragraph", 0, start, " ".join(para)))
+                    para = []
+                blocks.append(Block("code", 0, number, ""))   # a code block is a body for the outline gate, nothing else
+            in_code = not in_code
+            continue
+        if in_code or line.startswith("|") or line.startswith("<!--"):
+            continue
+        heading = re.match(r"^(#{1,6})\s+(.*)$", line)
+        if heading or not line.strip():
+            if para:
+                blocks.append(Block("paragraph", 0, start, " ".join(para)))
+                para = []
+            if heading:
+                blocks.append(Block("heading", len(heading.group(1)), number, heading.group(2).strip()))
+            continue
+        if not para:
+            start = number
+        para.append(re.sub(r"^\s*([-*+]|\d+\.)\s+", "", line).strip())
+    if para:
+        blocks.append(Block("paragraph", 0, start, " ".join(para)))
+    return blocks
+
+
+def sentences(text: str) -> list[str]:
+    return [s.strip() for s in SENTENCE_END.split(text) if s.strip()]
+
+
+def words(sentence: str) -> int:
+    return len(sentence.split())
+
+
+# ---- gates ----
+
+def gate_outline(blocks: list[Block]) -> list[Finding]:
+    out = []
+    headings = [b for b in blocks if b.kind == "heading"]
+    previous = 0
+    for index, h in enumerate(headings):
+        if previous and h.level > previous + 1:
+            out.append(Finding("outline", WARN, h.line, f"heading level jumps from H{previous} to H{h.level}", h.text))
+        previous = h.level
+        position = blocks.index(h)
+        following = blocks[position + 1] if position + 1 < len(blocks) else None
+        if following is None or (following.kind == "heading" and following.level <= h.level):
+            out.append(Finding("outline", WARN, h.line, "heading with no body under it", h.text))
+    if sum(1 for h in headings if h.level == 2) == 1:
+        out.append(Finding("outline", WARN, headings[0].line, "only one H2: either drop the section or add the others", ""))
+    return out
+
+
+def gate_sentences(blocks: list[Block], max_words: int, max_sentences: int) -> list[Finding]:
+    out = []
+    for b in blocks:
+        if b.kind != "paragraph":
+            continue
+        parts = sentences(b.text)
+        if len(parts) > max_sentences:
+            out.append(Finding("sentences", WARN, b.line, f"paragraph has {len(parts)} sentences (> {max_sentences})", parts[0][:80]))
+        for s in parts:
+            n = words(s)
+            if n > max_words:
+                out.append(Finding("sentences", DEFECT if n > max_words * 1.5 else WARN, b.line, f"sentence has {n} words (> {max_words})", s[:100]))
+    return out
+
+
+def gate_duplicates(blocks: list[Block]) -> list[Finding]:
+    seen: dict[str, int] = {}
+    out = []
+    for b in blocks:
+        if b.kind != "paragraph":
+            continue
+        for s in sentences(b.text):
+            key = re.sub(r"\W+", " ", s.lower()).strip()
+            if words(s) < 6:
+                continue
+            if key in seen:
+                out.append(Finding("duplicates", DEFECT, b.line, f"sentence already said on line {seen[key]}", s[:100]))
+            else:
+                seen[key] = b.line
+    return out
+
+
+def is_claim(sentence: str) -> bool:
+    return bool(NUMBER.search(sentence) or YEAR.search(sentence) or CLAIM_WORDS.search(sentence))
+
+
+def claim_sentences(blocks: list[Block]) -> list[tuple[int, str, bool]]:
+    """(line, sentence, has_source) for every sentence that states a number, a year or cites evidence."""
+    found = []
+    for b in blocks:
+        if b.kind != "paragraph":
+            continue
+        parts = sentences(b.text)
+        for index, s in enumerate(parts):
+            if not is_claim(s):
+                continue
+            window = " ".join(parts[max(0, index - 1): index + 2])
+            found.append((b.line, s, bool(SOURCE_MARKER.search(window))))
+    return found
+
+
+def gate_claims(blocks: list[Block]) -> list[Finding]:
+    return [Finding("claims", WARN, line, "number or evidence with no source marker in this or the neighbouring sentence", s[:100])
+            for line, s, has_source in claim_sentences(blocks) if not has_source]
+
+
+def gate_acronyms(blocks: list[Block]) -> list[Finding]:
+    """In reading order: "(ACR)" expands ACR from there on; a use before that is reported once. Headings neither expand nor count."""
+    expanded: set[str] = set()
+    reported: set[str] = set()
+    out = []
+    for b in blocks:
+        if b.kind == "heading":
+            continue
+        text = INLINE_CODE.sub("", b.text)   # `AGENTS.md` in a code span is a file name, not an acronym
+        for m in ACRONYM.finditer(text):
+            if m.group(1):
+                expanded.add(m.group(1))
+                continue
+            token = m.group(2)
+            if token in ACRONYM_SKIP or token in expanded or token in reported:
+                continue
+            reported.add(token)
+            out.append(Finding("acronyms", WARN, b.line, f"{token} used before it is expanded", text[max(0, m.start() - 40): m.end() + 40]))
+    return out
+
+
+def gate_links(blocks: list[Block]) -> list[Finding]:
+    out = []
+    targets: dict[str, tuple[str, int]] = {}
+    for b in blocks:
+        for text, target in LINK.findall(b.text):
+            if not target.strip():
+                out.append(Finding("links", DEFECT, b.line, "link with an empty target", text))
+            earlier = targets.get(text.lower())
+            if earlier and earlier[0] != target:
+                out.append(Finding("links", WARN, b.line, f"link text '{text}' points at {target} here and {earlier[0]} on line {earlier[1]}", ""))
+            targets.setdefault(text.lower(), (target, b.line))
+        stripped = LINK.sub("", b.text)
+        if re.search(r"(?<!\()https?://\S+", stripped):
+            out.append(Finding("links", WARN, b.line, "bare URL in prose; give it link text or a footnote", stripped[:100]))
+    return out
+
+
+def gate_tells(blocks: list[Block]) -> list[Finding]:
+    out = []
+    for b in blocks:
+        if b.kind != "paragraph":
+            continue
+        for pattern, label in TELLS:
+            if pattern.search(b.text):
+                out.append(Finding("tells", WARN, b.line, f"{label} reads as machine-written", b.text[:100]))
+        starts = [s.split()[0].lower().strip(",.") for s in sentences(b.text) if s.split()]
+        run = 1
+        for a, c in zip(starts, starts[1:]):
+            run = run + 1 if a == c else 1
+            if run == 3:
+                out.append(Finding("tells", WARN, b.line, f"three sentences in a row start with '{a}'", b.text[:100]))
+                break
+    return out
+
+
+def run(text: str, max_words: int = 35, max_sentences: int = 7, gates: set[str] | None = None) -> list[Finding]:
+    blocks = parse(text)
+    table = {"outline": lambda: gate_outline(blocks), "sentences": lambda: gate_sentences(blocks, max_words, max_sentences),
+             "duplicates": lambda: gate_duplicates(blocks), "claims": lambda: gate_claims(blocks),
+             "acronyms": lambda: gate_acronyms(blocks), "links": lambda: gate_links(blocks), "tells": lambda: gate_tells(blocks)}
+    findings = [f for name, gate in table.items() if not gates or name in gates for f in gate()]
+    findings.sort(key=lambda f: (f.severity != DEFECT, f.line))
+    return findings
+
+
+def write_ledger(blocks: list[Block], path: Path) -> int:
+    """Claims ledger skeleton: one row per claim sentence, columns the reviewer fills (docs/prose-qa.md)."""
+    rows = claim_sentences(blocks)
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["line", "claim", "source_marker_nearby", "source", "quote", "verdict"])
+        for line, sentence, has_source in rows:
+            writer.writerow([line, sentence, "yes" if has_source else "no", "", "", ""])
+    return len(rows)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("file")
+    parser.add_argument("--max-words", type=int, default=35)
+    parser.add_argument("--max-sentences", type=int, default=7)
+    parser.add_argument("--gate", action="append", help="run only these gates (repeatable)")
+    parser.add_argument("--claims", help="write the claims ledger skeleton CSV here")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    text = Path(args.file).read_text(encoding="utf-8")
+    findings = run(text, args.max_words, args.max_sentences, set(args.gate) if args.gate else None)
+    if args.claims:
+        count = write_ledger(parse(text), Path(args.claims))
+        print(f"claims ledger: {count} rows -> {args.claims}", file=sys.stderr)
+    if args.json:
+        print(json.dumps([asdict(f) for f in findings], ensure_ascii=False, indent=2))
+    else:
+        for f in findings:
+            print(f"{f.severity:6} {f.gate:10} L{f.line:<4} {f.message}" + (f"  · {f.excerpt}" if f.excerpt else ""))
+        defects = sum(f.severity == DEFECT for f in findings)
+        print(f"{defects} DEFECT / {len(findings)} findings")
+    return 1 if any(f.severity == DEFECT for f in findings) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

qakit/tools/recording_frames.swift

@@ -0,0 +1,78 @@
+// Pull still frames out of a UI-test screen recording (.mp4 attachment in an xcresult / device_qa *-shots folder)
+// and tile them into one contact sheet, so a reviewer can see what the phone actually did between two assertions.
+// The Mac that holds the phone may have no ffmpeg; AVFoundation is enough.
+//
+//   DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift tools/recording_frames.swift <video.mp4> <out-dir> [frames=12] [width=500]
+//   -> <out-dir>/f00_0.0.png ... and <out-dir>/contact-sheet.png (6 columns)
+//   swift tools/recording_frames.swift <a.png> <b.png> ... <out-dir> [width=500]
+//   -> the screenshots side by side in <out-dir>/contact-sheet.png (every page of a scrolled walk on one image)
+//
+// Why it exists (2026-10-28): twice a device UI failure was read as an app defect before anyone
+// looked at the recording (댕오늘 date chips; Elsewhen "rename loses the name", which was the test re-tapping a focused
+// field so the edit menu covered Done). Look at the frames before deciding app vs test.
+import AVFoundation
+import AppKit
+
+let args = Array(CommandLine.arguments.dropFirst())
+let shots = args.filter { $0.lowercased().hasSuffix(".png") }, rest = args.filter { !$0.lowercased().hasSuffix(".png") }
+guard rest.count >= (shots.isEmpty ? 2 : 1) else {
+    print("usage: recording_frames.swift <video.mp4> <out-dir> [frames] [width] | <a.png> <b.png> ... <out-dir> [width]"); exit(2)
+}
+let outDir = URL(fileURLWithPath: rest[shots.isEmpty ? 1 : 0], isDirectory: true)
+let options = Array(rest.dropFirst(shots.isEmpty ? 2 : 1))
+let count = shots.isEmpty && !options.isEmpty ? max(Int(options[0]) ?? 12, 1) : 12
+let widthArg = shots.isEmpty ? options.dropFirst().first : options.first
+let width = CGFloat(Double(widthArg ?? "") ?? 500)
+try FileManager.default.createDirectory(at: outDir, withIntermediateDirectories: true)
+
+/// `cg` drawn at `width` points wide.
+func scaled(_ cg: CGImage) -> NSImage {
+    let size = NSSize(width: width, height: CGFloat(cg.height) * width / CGFloat(cg.width))
+    let image = NSImage(size: size)
+    image.lockFocus()
+    NSImage(cgImage: cg, size: NSSize(width: cg.width, height: cg.height)).draw(in: NSRect(origin: .zero, size: size))
+    image.unlockFocus()
+    return image
+}
+
+var tiles: [NSImage] = []
+if !shots.isEmpty {
+    for path in shots {
+        guard let cg = NSImage(contentsOfFile: path)?.cgImage(forProposedRect: nil, context: nil, hints: nil) else { print("unreadable: \(path)"); continue }
+        tiles.append(scaled(cg))
+    }
+} else {
+    let video = URL(fileURLWithPath: args[0])
+    let asset = AVURLAsset(url: video)
+    let generator = AVAssetImageGenerator(asset: asset)
+    generator.appliesPreferredTrackTransform = true
+    generator.requestedTimeToleranceBefore = .zero
+    generator.requestedTimeToleranceAfter = .zero
+    let duration = CMTimeGetSeconds(asset.duration)
+    guard duration.isFinite, duration > 0 else { print("no video track or zero length: \(video.path)"); exit(1) }
+    for index in 0..<count {
+        let seconds = duration * Double(index) / Double(count)
+        guard let cg = try? generator.copyCGImage(at: CMTime(seconds: seconds, preferredTimescale: 600), actualTime: nil) else { continue }
+        let image = scaled(cg)
+        let name = String(format: "f%02d_%.1f.png", index, seconds)
+        if let tiff = image.tiffRepresentation, let png = NSBitmapImageRep(data: tiff)?.representation(using: .png, properties: [:]) {
+            try png.write(to: outDir.appendingPathComponent(name))
+        }
+        tiles.append(image)
+    }
+}
+guard let first = tiles.first else { print("no frames decoded"); exit(1) }
+let columns = shots.isEmpty ? 6 : min(tiles.count, 8), rows = (tiles.count + columns - 1) / columns
+let tile = first.size
+let sheet = NSImage(size: NSSize(width: tile.width * CGFloat(min(columns, tiles.count)), height: tile.height * CGFloat(rows)))
+sheet.lockFocus()
+for (index, image) in tiles.enumerated() {
+    let x = CGFloat(index % columns) * tile.width
+    let y = CGFloat(rows - 1 - index / columns) * tile.height
+    image.draw(in: NSRect(x: x, y: y, width: tile.width, height: tile.height))
+}
+sheet.unlockFocus()
+if let tiff = sheet.tiffRepresentation, let png = NSBitmapImageRep(data: tiff)?.representation(using: .png, properties: [:]) {
+    try png.write(to: outDir.appendingPathComponent("contact-sheet.png"))
+}
+print("\(tiles.count) frames -> \(outDir.path)/contact-sheet.png")

qakit/tools/release_checks.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Static pre-submission checks for an App Store app (the `script` rows of docs/device-qa-protocol.md).
+
+Reads the "release" block of the app's device_qa.json manifest (docs/manifest.md). Each check prints PASS, WARN or FAIL
+with the evidence; any FAIL exits 1. Network checks (links, Apple's AASA CDN) are skipped with --offline.
+
+  python3 tools/release_checks.py --app myapp                         # <apps-root>/myapp/release/testing/device_qa.json
+  python3 tools/release_checks.py --manifest path/to/device_qa.json --ipa /tmp/Export/MyApp.ipa   # + exported entitlements
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import plistlib
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from device_qa import add_manifest_args, manifest_path_for   # same folder: on sys.path as a script and through the tests
+
+# Field limits App Store Connect enforces (characters).
+LIMITS = {"Name": 30, "Subtitle": 30, "Promotional Text": 170, "Description": 4000, "Keywords": 100, "What's New": 4000}
+REVIEW_NOTES_LIMIT = 4000   # ASC rejects longer notes with 409 (2026-10-26, Pawday build 35)
+FIRST_RELEASE_WORDS = re.compile(r"첫 버전|첫 출시|first release|initial release|first version", re.IGNORECASE)
+PLACEHOLDERS = re.compile(r"lorem ipsum|placeholder|\bTODO\b|\bFIXME\b|\bTBD\b|example\.com|localhost|127\.0\.0\.1|test@test", re.IGNORECASE)
+MARKUP = re.compile(r"<[^<>\n]+>")   # ASC refuses What's New / description text "that contains markup language" — even `<library>` (2026-10-28, MotionBook 3.8)
+AGE_RATING_REQUIRED = ("socialMedia",)   # PATCH ageRatingDeclarations → 409 ENTITY_ERROR.ATTRIBUTE.REQUIRED without it (2026-10-28: Elsewhen, HanyakNote, MotionBook)
+# Required-reason API families (Apple TN "Describing use of required reason API"): source pattern -> manifest category.
+REASON_APIS = {
+    "NSPrivacyAccessedAPICategoryUserDefaults": re.compile(r"\bUserDefaults\b|@AppStorage|NSUserDefaults"),
+    # File timestamps only: URL resource keys, attribute dictionaries, FileManager, the libc calls. A bare `.modificationDate`
+    # also matches CKRecord and PHAsset properties, which are not file APIs (Daynest's notification service, 2026-10-29).
+    "NSPrivacyAccessedAPICategoryFileTimestamp": re.compile(r"\.(creationDate|modificationDate|contentModificationDate|attributeModificationDate)Key\b|attributesOfItem\(|\bfileModificationDate\b|\[\.(creationDate|modificationDate)\]|getattrlist|\b[fl]?stat\("),
+    "NSPrivacyAccessedAPICategorySystemBootTime": re.compile(r"systemUptime|mach_absolute_time|kern\.boottime"),
+    "NSPrivacyAccessedAPICategoryDiskSpace": re.compile(r"volumeAvailableCapacity|systemFreeSize|systemSize\b|statfs"),
+    "NSPrivacyAccessedAPICategoryActiveKeyboards": re.compile(r"activeInputModes"),
+}
+# Protected resources: source pattern -> Info.plist purpose key.
+PURPOSE_APIS = {
+    "NSLocationWhenInUseUsageDescription": re.compile(r"requestWhenInUseAuthorization|CLLocationUpdate|CLServiceSession"),
+    "NSLocationAlwaysAndWhenInUseUsageDescription": re.compile(r"requestAlwaysAuthorization"),
+    "NSCalendarsFullAccessUsageDescription": re.compile(r"requestFullAccessToEvents"),
+    "NSCalendarsWriteOnlyAccessUsageDescription": re.compile(r"requestWriteOnlyAccessToEvents"),
+    "NSCameraUsageDescription": re.compile(r"AVCaptureDevice\.requestAccess\(for: *\.video|UIImagePickerController\.SourceType\.camera"),
+    "NSPhotoLibraryAddUsageDescription": re.compile(r"UIImageWriteToSavedPhotosAlbum|PHAccessLevel\.addOnly"),
+    "NSMicrophoneUsageDescription": re.compile(r"requestRecordPermission|AVAudioApplication\.requestRecordPermission"),
+    "NSContactsUsageDescription": re.compile(r"CNContactStore\(\)\.requestAccess"),
+    "NSMotionUsageDescription": re.compile(r"CMMotionActivityManager|CMPedometer"),
+}
+
+
+def result(check: str, status: str, detail: str) -> dict[str, str]:
+    return {"check": check, "status": status, "detail": detail}
+
+
+def swift_files(dirs: list[Path]) -> list[Path]:
+    return [p for d in dirs if d.exists() for p in sorted(d.rglob("*.swift")) if "/Tests/" not in str(p) and "Tests/" not in p.parent.name]
+
+
+def metadata_sections(text: str) -> dict[str, str]:
+    """`## Field` sections of a store metadata/<locale>.md file, bodies stripped."""
+    sections: dict[str, str] = {}
+    current = None
+    for line in text.splitlines():
+        if line.startswith("## "):
+            current = line[3:].strip()
+            sections[current] = ""
+        elif current is not None:
+            sections[current] += line + "\n"
+    return {k: v.strip() for k, v in sections.items()}
+
+
+# ---- checks (pure where possible; tests/test_release_checks.py) ----
+
+def check_metadata(locale: str, text: str, version: str) -> list[dict[str, str]]:
+    out = []
+    sections = metadata_sections(text)
+    for field, limit in LIMITS.items():
+        body = sections.get(field, "")
+        if field in ("Name", "Description", "What's New", "Keywords") and not body:
+            out.append(result("SUB-12", "FAIL", f"{locale}: {field} is empty"))
+        elif len(body) > limit:
+            out.append(result("SUB-12", "FAIL", f"{locale}: {field} is {len(body)} chars > {limit}"))
+    whats_new = sections.get("What's New", "")
+    if version not in ("1.0", "1.0.0") and FIRST_RELEASE_WORDS.search(whats_new):
+        out.append(result("SUB-10", "FAIL", f"{locale}: What's New for {version} still announces a first release: {whats_new[:80]}"))
+    for field, body in sections.items():
+        if PLACEHOLDERS.search(body) and "Review" not in field:
+            out.append(result("SUB-01", "FAIL", f"{locale}: placeholder text in {field}: {PLACEHOLDERS.search(body).group(0)}"))
+        if field in LIMITS and MARKUP.search(body):
+            out.append(result("SUB-12", "FAIL", f"{locale}: {field} contains markup App Store Connect rejects: {MARKUP.search(body).group(0)}"))
+    return out or [result("SUB-12", "PASS", f"{locale}: field limits, What's New, placeholders and markup ok")]
+
+
+def check_age_rating(config: dict[str, Any]) -> dict[str, str]:
+    """SUB-15: a per-app `age_rating` block must carry every attribute App Store Connect now requires; a block with only a
+    `note` means the runner sends its defaults (which include them)."""
+    block = config.get("age_rating") or {}
+    answers = {k: v for k, v in block.items() if k != "note"}
+    if not answers:
+        return result("SUB-15", "PASS", "age rating: runner defaults")
+    missing = [k for k in AGE_RATING_REQUIRED if k not in answers]
+    return result("SUB-15", "FAIL" if missing else "PASS",
+                  f"age rating block lacks {', '.join(missing)} (ASC answers 409)" if missing else f"age rating block has {', '.join(AGE_RATING_REQUIRED)}")
+
+
+def check_review_notes(text: str) -> dict[str, str]:
+    n = len(text)
+    return result("SUB-08", "PASS" if n <= REVIEW_NOTES_LIMIT else "FAIL", f"review notes {n}/{REVIEW_NOTES_LIMIT} chars")
+
+
+def check_purpose_strings(info: dict[str, Any], strings: dict[str, dict[str, str]], sources: dict[str, str]) -> list[dict[str, str]]:
+    """Every protected API in the sources has its purpose key, and every listed localization translates every purpose key."""
+    out = []
+    corpus = "\n".join(sources.values())
+    for key, pattern in PURPOSE_APIS.items():
+        if pattern.search(corpus) and not info.get(key):
+            out.append(result("PERM-04", "FAIL", f"{key} missing but the code calls {pattern.pattern.split('|')[0]}"))
+    purpose_keys = [k for k in info if k.endswith("UsageDescription")]
+    development = str(info.get("CFBundleDevelopmentRegion", "")).replace("$(DEVELOPMENT_LANGUAGE)", "")
+    for lang in info.get("CFBundleLocalizations", []):
+        if lang == development or (not development and lang == info.get("CFBundleLocalizations", [lang])[0]):
+            continue
+        missing = [k for k in purpose_keys if k not in strings.get(lang, {})]
+        if missing:
+            out.append(result("PERM-04", "FAIL", f"{lang}: no translated {', '.join(missing)} (add {lang}.lproj/InfoPlist.strings); "
+                                                 f"{lang} devices see the {development or 'development'} text"))
+    return out or [result("PERM-04", "PASS", f"purpose strings: {', '.join(purpose_keys) or 'none needed'}")]
+
+
+def check_required_reasons(bundle: str, sources: dict[str, str], declared: set[str]) -> list[dict[str, str]]:
+    out = []
+    for category, pattern in REASON_APIS.items():
+        hits = [f"{Path(p).name}:{text[:m.start()].count(chr(10)) + 1}" for p, text in sources.items() for m in [pattern.search(text)] if m]
+        if hits and category not in declared:
+            out.append(result("SUB-03", "FAIL", f"{bundle}: {category} used ({', '.join(hits[:4])}) but not declared in its PrivacyInfo.xcprivacy"))
+    return out or [result("SUB-03", "PASS", f"{bundle}: required-reason APIs declared ({', '.join(sorted(declared)) or 'none used'})")]
+
+
+def check_aasa(payload: dict[str, Any], app_id: str, paths: list[str]) -> dict[str, str]:
+    details = payload.get("applinks", {}).get("details", [])
+    for item in details:
+        ids = item.get("appIDs") or ([item["appID"]] if "appID" in item else [])
+        if app_id in ids:
+            served = {c.get("/") for c in item.get("components", [])} | set(item.get("paths", []))
+            missing = [p for p in paths if p not in served]
+            return result("ENTRY-02", "FAIL" if missing else "PASS", f"{app_id}: " + (f"paths missing {missing}" if missing else f"serves {paths}"))
+    return result("ENTRY-02", "FAIL", f"{app_id} not in the AASA Apple's CDN serves")
+
+
+def check_entitlements(ents: dict[str, Any]) -> list[dict[str, str]]:
+    out = []
+    if ents.get("get-task-allow"):
+        out.append(result("BUILD-07", "FAIL", "get-task-allow is true: a development-signed binary"))
+    env = ents.get("com.apple.developer.icloud-container-environment")
+    if ents.get("com.apple.developer.icloud-services") and env not in ("Production", ["Production"]):
+        out.append(result("BUILD-07", "FAIL", f"CloudKit environment is {env!r}, expected Production"))
+    if "aps-environment" in ents and ents["aps-environment"] != "production":
+        out.append(result("BUILD-07", "FAIL", f"aps-environment is {ents['aps-environment']}"))
+    return out or [result("BUILD-07", "PASS", "exported entitlements are production")]
+
+
+# ---- I/O ----
+
+def load_strings(resources: Path) -> dict[str, dict[str, str]]:
+    found: dict[str, dict[str, str]] = {}
+    for strings in resources.glob("*.lproj/InfoPlist.strings"):
+        text = strings.read_text(encoding="utf-8", errors="replace")
+        found[strings.parent.stem] = dict(re.findall(r'"?([A-Za-z0-9_]+)"?\s*=\s*"((?:[^"\\]|\\.)*)"\s*;', text))
+    for catalog in resources.glob("InfoPlist.xcstrings"):
+        data = json.loads(catalog.read_text(encoding="utf-8"))
+        for key, entry in data.get("strings", {}).items():
+            for lang in entry.get("localizations", {}):
+                found.setdefault(lang, {})[key] = "x"
+    return found
+
+
+def fetch(url: str, timeout: float = 15) -> tuple[int, bytes]:
+    request = urllib.request.Request(url, headers={"User-Agent": "qakit-release-checks"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, b""
+    except (urllib.error.URLError, TimeoutError) as error:
+        return 0, str(error).encode()
+
+
+def link_urls(texts: dict[str, str], ignore: list[str]) -> list[str]:
+    """User-reachable https URLs: interpolated strings and `ignore` prefixes (API bases, folders the app appends to) left out."""
+    found = {u.rstrip(").,") for text in texts.values() for u in re.findall(r"https://[^\s\"'<>)\]`]+", text)}
+    return sorted(u for u in found if "\\(" not in u and "{" not in u and not any(u.startswith(p) for p in ignore))
+
+
+def check_links(texts: dict[str, str], ignore: list[str]) -> list[dict[str, str]]:
+    urls = link_urls(texts, ignore)
+    bad, pending = [], []
+    for url in urls:
+        status, _ = fetch(url)
+        if 200 <= status < 400:
+            continue
+        # The store page 404s until the first version is released; everything else must answer.
+        (pending if url.startswith("https://apps.apple.com/") and status == 404 else bad).append(f"{status} {url}")
+    out = [result("SUB-02", "FAIL" if bad else "PASS", f"{len(urls)} links; " + ("; ".join(bad[:8]) if bad else "all reachable"))]
+    if pending:
+        out.append(result("SUB-02", "WARN", "store page not live yet: " + "; ".join(pending)))
+    return out
+
+
+def ipa_entitlements(ipa: Path) -> dict[str, Any]:
+    with tempfile.TemporaryDirectory() as tmp:
+        with zipfile.ZipFile(ipa) as archive:
+            archive.extractall(tmp)
+        app = next(Path(tmp, "Payload").glob("*.app"))
+        raw = subprocess.run(["codesign", "-d", "--entitlements", "-", "--xml", str(app)], capture_output=True, check=False).stdout
+        return plistlib.loads(raw) if raw.strip() else {}
+
+
+def run(manifest_path: Path, offline: bool, ipa: str | None) -> list[dict[str, str]]:
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if "release" not in manifest:
+        raise SystemExit(f"{manifest_path}: no \"release\" block (docs/manifest.md)")
+    cfg = manifest["release"]
+    at = lambda rel: (manifest_path.parent / rel).resolve()   # noqa: E731
+    config = json.loads((manifest_path.parent / manifest["appstore_config"]).resolve().read_text(encoding="utf-8")) if manifest.get("appstore_config") else {}
+    version = str(cfg.get("version") or config.get("app_store_version", ""))
+    out: list[dict[str, str]] = []
+    for md in sorted(at(cfg["metadata_dir"]).glob("*.md")):
+        out += check_metadata(md.stem, md.read_text(encoding="utf-8"), version)
+    notes = at(cfg["review_notes"]).read_text(encoding="utf-8")
+    out.append(check_review_notes(notes))
+    out.append(check_age_rating(config))
+    info = plistlib.loads(at(cfg["info_plist"]).read_bytes())
+    all_sources = {str(p): p.read_text(encoding="utf-8", errors="replace") for p in swift_files([at(d) for d in cfg["source_dirs"]])}
+    out += check_purpose_strings(info, load_strings(at(cfg["resources_dir"])), all_sources)
+    for bundle in cfg["bundles"]:
+        sources = {str(p): p.read_text(encoding="utf-8", errors="replace") for p in swift_files([at(d) for d in bundle["sources"]])}
+        privacy = at(bundle["privacy"]) if bundle.get("privacy") else None
+        declared = set()
+        if privacy and privacy.is_file():
+            data = plistlib.loads(privacy.read_bytes())
+            declared = {item.get("NSPrivacyAccessedAPIType", "") for item in data.get("NSPrivacyAccessedAPITypes", [])}
+        out += check_required_reasons(bundle["name"], sources, declared)
+    if not offline:
+        texts = {md.name: md.read_text(encoding="utf-8") for md in at(cfg["metadata_dir"]).glob("*.md")}
+        texts["review-notes"] = notes
+        texts.update({k: v for k, v in all_sources.items() if "https://" in v})
+        out += check_links(texts, cfg.get("link_ignore", []))
+        if cfg.get("aasa_domain"):
+            status, body = fetch(f"https://app-site-association.cdn-apple.com/a/v1/{cfg['aasa_domain']}")
+            out.append(check_aasa(json.loads(body or b"{}"), cfg["app_id"], cfg.get("aasa_paths", [])) if status == 200
+                       else result("ENTRY-02", "FAIL", f"Apple CDN returned {status} for {cfg['aasa_domain']}"))
+    if ipa and not shutil.which("codesign"):
+        out.append(result("BUILD-07", "WARN", "codesign is not on this machine; the IPA's entitlements were not checked"))
+    elif ipa:
+        out += check_entitlements(ipa_entitlements(Path(ipa)))
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    add_manifest_args(parser)
+    parser.add_argument("--offline", action="store_true", help="skip link and AASA checks")
+    parser.add_argument("--ipa", help="exported .ipa to check production entitlements")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    results = run(manifest_path_for(args), args.offline, args.ipa)
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        for r in results:
+            print(f"{r['status']:4} {r['check']:9} {r['detail']}")
+    failed = sum(r["status"] == "FAIL" for r in results)
+    print(f"{failed} FAIL / {len(results)} checks", file=sys.stderr if args.json else sys.stdout)   # keep --json output parseable
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())   # mutation-ok: entry point, pytest calls main() directly