appstore-precheck 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to this project are documented here. Versioning follows
 [SemVer](https://semver.org/). Released as git tags.
 
+## [Unreleased]
+
+## [1.6.0] - 2026-07-01
+
+Measurement release: structured findings, suppression, and a published
+precision/recall scorecard, plus a measurement-driven false-positive reduction
+round. Default text output stays byte-identical (verified across 11 fixtures);
+every behavior change is gated by TDD and the synthetic-corpus `--check`.
+
+### Added
+- **`scan.sh --format json`**: structured findings envelope (`{tool, version, verdict, summary{fail,warn,pass,suppressed}, findings[{rule_id, severity, guideline, message, file, line, suppressed}]}`) for tooling and measurement. Stable `rule_id` per vector via a 41-slug catalog. Default text output is unchanged.
+- **`.precheck-ignore` suppression**: repo-root rules (`<rule-id>`, `<rule-id> <path-glob>`, `<path-glob>`-exclude) and inline `# precheck:ignore [rule-id]` directives (`//`, `#`, `<!-- -->`). Suppression is emit-time — a suppressed FAIL no longer forces RED — and always transparent: suppressed findings stay in `findings[]` with `suppressed:true`, count in `summary.suppressed`, and a text footer reports the count only when non-zero (byte-identity preserved otherwise).
+- **Precision/recall scorecard**: `scripts/scorecard.sh` (`--check` / `--selftest` / default) over a synthetic labelled corpus (`corpus/synthetic/labels.json`), plus `scripts/scorecard-real.sh` over an 18-app commit-pinned open-source real panel (`corpus/real/`). Published to `docs/scorecard.md` with a mandatory honesty section (neither corpus claims agreement with Apple's actual decisions). Synthetic `--check` is a blocking CI gate; the real panel is non-blocking.
+- File/line threading into locatable checks (surfaced in JSON; text output unchanged).
+
+### Fixed
+- **False-positive reduction round** (measurement-driven; ~33 FP eliminated across the 18-app panel with zero true-positive loss, char-limit-excluded precision 0.37 → ~0.54):
+  - **Analytics detection** now requires an import/API-qualified form, so a bare `Segment` substring (e.g. `UISegmentedControl`) no longer trips 5.1.1.
+  - **IAP gate** requires a real purchase API, ignoring `SKStoreReviewController` / `SKAdNetwork` / the `AppStore.` namespace.
+  - **Usage-description checks** are capture-gated: playback-only AVFoundation / PhotosPicker no longer false-fire; mic matches `.playAndRecord`; video-only `AVCaptureDevice` no longer triggers the microphone check.
+  - **Minimum-functionality navigation** detects UIKit / `NavigationView` / React-Navigation repo-wide.
+  - **Screenshots-per-locale**: no in-repo screenshots directory is an advisory PASS (managed in App Store Connect), not a WARN.
+
+## [1.5.2] - 2026-06-30
+
+### Fixed
+
+- **§23 (1.6 ATS) false positive**: the App Transport Security check now anchors to the exact `NSAllowsArbitraryLoads` key, so the scoped exceptions `NSAllowsArbitraryLoadsInWebContent` / `NSAllowsArbitraryLoadsForMedia` — which do not disable ATS app-wide and are Apple's recommended alternative — no longer trip a spurious WARN.
+- **Kids-signal double-count (§27 ↔ §39)**: when a child-audience term and a third-party ads/analytics SDK are both present, only §39 (5.1.4) fires now; §27 (2.3.8) is cross-gated so one root signal no longer costs two WARNs against the 5-WARN YELLOW threshold.
+- **§33 (2.5.4) background-mode coverage**: `audio` now recognizes AVKit / `VideoPlayer` / `AVPlayerViewController` / MediaPlayer now-playing APIs, and `fetch` / `processing` recognize `BGTaskScheduler`, reducing "declared but unused" false positives.
+- Pierre deep-review docs: corrected the Tier A definition (22 = all 28 except the 6 Tier B items; previously implied 17), fixed the stale "22 checks" label and broken table-of-contents anchor in the methodology and example files.
+- §28 / §37 evidence now print the plist basename, matching the rest of the batch.
+
 ## [1.5.1] - 2026-06-30
 
 ### Changed

package/README.md

@@ -240,8 +240,14 @@ npx appstore-precheck --fail-on YELLOW
 
 ```bash
 bash skills/appstore-precheck/scripts/scan.sh   # from a clone of this repo
+bash skills/appstore-precheck/scripts/scan.sh --format json   # structured findings, for tooling
 ```
 
+`--format json` emits a structured findings envelope (`rule_id`, `severity`, `guideline`,
+`message`, and optional `file`/`line` per finding, plus the verdict summary) instead of the
+default text lines, for scripts and measurement tooling to consume. It's read-only and additive;
+the default text output is unchanged.
+
 ### CI
 
 Drop the static scan into a workflow with the bundled composite action. It fails the
@@ -320,6 +326,26 @@ and [Phase 2 `fastlane precheck`](examples/fastlane-precheck.md) results.
 | 🟡 **YELLOW** | 0 FAIL, 5+ WARN | not written | blocked; needs confirmation |
 | 🔴 **RED** | ≥1 FAIL | removed | blocked; shows the FAIL list |
 
+## Measured accuracy
+
+[`docs/scorecard.md`](docs/scorecard.md) is generated by `scripts/scorecard.sh` and tracks two
+independent measurements:
+
+- **Synthetic precision** — the project's own labelled fixtures (`corpus/synthetic/`), each tagging
+  the rule-ids it must fire and the rule-ids that must stay silent. This is a **CI-gated floor**:
+  `scripts/scorecard.sh --check` fails the build if precision drops below 0.80 or the doc goes stale.
+- **Real-panel FP rate** — a pinned, license-verified panel of permissively-licensed open-source
+  iOS/Swift/React-Native apps (`corpus/real/manifest.json`), scanned and joined against a one-time
+  human TP/FP labelling pass (`corpus/real/labels.json`). Every finding is reported `UNLABELED` until
+  a human reviews it, so **no unreviewed number is ever published**. Run it yourself with
+  `bash scripts/scorecard.sh --real`; CI runs it as a separate **non-blocking, informational** job
+  (`continue-on-error: true`) that never gates a PR.
+
+**Neither measurement claims agreement with Apple's actual review decisions.** Synthetic precision
+measures intended-behaviour fidelity against fixtures this project wrote; real-panel precision
+measures the false-positive rate on real, unrelated open-source code. See
+[`docs/scorecard.md`](docs/scorecard.md) for the current numbers and full methodology.
+
 ## Configuration
 
 Zero config for a standard fastlane + Xcode layout. The scanner auto-detects your source directory,
@@ -327,6 +353,37 @@ fastlane metadata, screenshots, String Catalog, paywall view, and locales. Overr
 `.appstore-precheck.json` at your repo root (copy
 [`config.example.json`](skills/appstore-precheck/config.example.json)).
 
+### Suppressing findings (`.precheck-ignore`)
+
+Drop a `.precheck-ignore` file at your repo root to suppress findings you've reviewed and accepted
+on purpose. One entry per line; `#` starts a trailing comment. Three grammar forms:
+
+| Form | Example | Effect |
+|------|---------|--------|
+| `<rule-id>` | `account-no-delete` | suppress that rule everywhere in the repo |
+| `<rule-id> <path-glob>` | `ats-arbitrary-loads ios/Legacy/` | suppress that rule only under the matching path |
+| `<path-glob>` | `vendor/` | exclude the matching path from scanning entirely |
+
+You can also suppress a single finding inline, with a `//`, `#`, or `<!-- -->` comment marker on the
+flagged line or the line directly above it:
+
+```swift
+let x = UIWebView() // precheck:ignore private-api
+```
+
+```html
+<!-- precheck:ignore -->
+<key>NSAllowsArbitraryLoads</key>
+```
+
+A bare `precheck:ignore` (no rule-id) suppresses **any** rule on that line; a scoped
+`precheck:ignore <rule-id>` only suppresses that one rule, leaving every other rule on the same line
+free to fire.
+
+**Suppressed findings are always counted, never silently hidden.** `scan.sh --format json` still
+emits them with `"suppressed": true`, and the text/summary output always states how many findings
+were suppressed.
+
 ## Cross-tool support
 
 `SKILL.md` follows the [Agent Skills open standard](https://agentskills.io), with no per-tool conversion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-precheck",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Read-only iOS App Store pre-submission check, packaged as a portable Agent Skill with native Claude Code, Cursor, and Codex plugins, plus an npx CLI.",
   "license": "MIT",
   "author": "Berkay Turk (https://github.com/berkayturk)",
@@ -25,7 +25,7 @@
   "scripts": {
     "test": "bash tests/all.sh",
     "check-versions": "bash scripts/check-versions.sh",
-    "lint": "node --check bin/cli.js && bash -n skills/appstore-precheck/scripts/scan.sh && bash -n skills/appstore-precheck/scripts/verdict.sh && bash -n skills/appstore-precheck/scripts/phase2-precheck.sh && bash -n hooks/fastlane-guard.sh && bash -n install.sh && bash -n tests/run.sh && bash -n tests/all.sh && bash -n tests/test-verdict.sh && bash -n tests/test-guard.sh && bash -n tests/test-config.sh && bash -n tests/test-install.sh && bash -n tests/test-phase2.sh && bash -n tests/test-cli.sh"
+    "lint": "node --check bin/cli.js && bash -n skills/appstore-precheck/scripts/scan.sh && bash -n skills/appstore-precheck/scripts/verdict.sh && bash -n skills/appstore-precheck/scripts/phase2-precheck.sh && bash -n skills/appstore-precheck/scripts/findings.sh && bash -n skills/appstore-precheck/scripts/suppress.sh && bash -n hooks/fastlane-guard.sh && bash -n install.sh && bash -n tests/run.sh && bash -n tests/all.sh && bash -n tests/test-verdict.sh && bash -n tests/test-guard.sh && bash -n tests/test-config.sh && bash -n tests/test-install.sh && bash -n tests/test-phase2.sh && bash -n tests/test-cli.sh && bash -n tests/test-findings.sh && bash -n tests/test-format-json.sh && bash -n tests/test-suppress.sh && bash -n tests/test-scorecard.sh && bash -n scripts/scorecard.sh && bash -n scripts/scorecard-real.sh"
   },
   "keywords": ["ios", "app-store", "fastlane", "agent-skill", "claude-code", "precheck"]
 }

package/skills/appstore-precheck/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only pre-submission check for an iOS app before App Store revi
 license: MIT
 metadata:
   author: Berkay Turk
-  version: 1.5.1
+  version: 1.6.0
 allowed-tools: Bash Read Grep Glob WebFetch
 ---
 
@@ -136,6 +136,11 @@ full check table is in
 The scanner is portable Bash, so you can also run it directly, outside any agent, for a quick CI
 or pre-commit check.
 
+`scan.sh --format json` emits a structured findings envelope (`rule_id`, `severity`, `guideline`,
+`message`, optional `file`/`line` per finding, plus the verdict summary) instead of the default
+text lines, for tooling and measurement to consume. It's read-only and additive; the default text
+output is unchanged.
+
 ### Phase 2: Apple's official `fastlane precheck`
 
 Requires `bundleId` in config (or pass `app_identifier` directly) and App Store Connect API

package/skills/appstore-precheck/references/methodology.md

@@ -8,7 +8,7 @@ whole file to run the skill.
 - [Phase 0: Guideline drift check](#phase-0-guideline-drift-check)
 - [Phase 1: Rejection vectors](#phase-1-rejection-vectors)
 - [Phase 3: Pierre explains every finding](#phase-3-pierre-explains-every-finding)
-- [Phase 4: Pierre deep review (22 checks)](#phase-4-pierre-deep-review-22-semantic-checks)
+- [Phase 4: Pierre deep review (28 checks)](#phase-4-pierre-deep-review-28-semantic-checks)
 - [Auto-detection rules](#auto-detection-rules)
 - [Verdict thresholds](#verdict-thresholds)
 - [Pre-submit manual checklist](#pre-submit-manual-checklist)

package/skills/appstore-precheck/references/pierre-deep-review.md

@@ -1,9 +1,10 @@
 # Phase 4: Pierre deep review (28 semantic checks)
 
 After Phase 3 (explaining every scan FAIL/WARN), Pierre runs a **read-only, project-wide
-semantic review** of 28 guideline areas the static scanner cannot fully judge. Checks **1–22**
-(minus Tier B items below) are high-confidence (Tier A); checks **4, 5, 7, 10, 15, and 28** are
-heuristic advisory (Tier B v1 — higher false-positive risk, still useful pre-submit signals).
+semantic review** of 28 guideline areas the static scanner cannot fully judge. The **22 Tier A**
+checks (all 28 except the Tier B items below) are high-confidence; the **6 Tier B v1** checks
+**4, 5, 7, 10, 15, and 28** are heuristic advisory (higher false-positive risk, still useful
+pre-submit signals).
 
 This is the **Review Simulator** layer: Pierre reads Swift, metadata, entitlements, screenshots,
 xcstrings, paywall views, review notes, and fetches live privacy/support URLs — then cross-checks

package/skills/appstore-precheck/scripts/findings.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# findings.sh — structured-findings layer for scan.sh.
+# Sourced by scan.sh. Adds a parallel machine-readable channel; text output is untouched.
+# Bash 3.2 compatible: NO associative arrays (catalog is a case lookup).
+
+# rule_slug <section-number> -> stable kebab-case slug, or "" if unknown.
+rule_slug() {
+  case "$1" in
+    1) echo privacy-manifest-parity ;;        2) echo usage-description-crosscheck ;;
+    3) echo att-usage ;;                       4) echo competitor-mentions ;;
+    5) echo metadata-char-limits ;;            6) echo locale-metadata-parity ;;
+    7) echo screenshots-per-locale ;;          8) echo trial-disclosure ;;
+    9) echo autorenew-disclosure ;;           10) echo subscription-links-restore ;;
+    11) echo private-api ;;                    12) echo min-functionality-nav ;;
+    13) echo screentime-justification ;;       14) echo siwa-parity ;;
+    15) echo external-purchase-link ;;         16) echo tracking-sdk-no-att ;;
+    17) echo export-compliance ;;              18) echo support-privacy-url ;;
+    19) echo analytics-privacyinfo-mismatch ;; 20) echo placeholder-metadata ;;
+    21) echo thirdparty-payment-sdk ;;         22) echo ugc-no-moderation ;;
+    23) echo ats-arbitrary-loads ;;            24) echo applepay-recurring-disclosure ;;
+    25) echo custom-review-prompt ;;           26) echo misleading-marketing ;;
+    27) echo kids-wording ;;                   28) echo keyboard-full-access ;;
+    29) echo health-icloud-sync ;;             30) echo vpn-networkextension ;;
+    31) echo demo-account ;;                   32) echo executable-code-download ;;
+    33) echo background-modes-unused ;;        34) echo crypto-wallet-mining ;;
+    35) echo webview-wrapper ;;                36) echo remote-desktop ;;
+    37) echo safari-extension ;;               38) echo account-no-delete ;;
+    39) echo kids-ads-analytics ;;             40) echo realmoney-gambling ;;
+    41) echo mdm ;;                            *) echo "" ;;
+  esac
+}
+
+_CURRENT_RULE=""
+set_rule() { _CURRENT_RULE="$1"; }
+
+: "${FINDINGS_TMP:=}"
+
+# _record <severity> <message> [<file>] [<line>]
+_record() {
+  [[ -z "$FINDINGS_TMP" ]] && return 0
+  local sev="$1" msg="$2" file="${3:-}" line="${4:-}" guideline
+  guideline="$(printf '%s' "$msg" | awk '{print $1}')"
+  jq -nc --arg r "$_CURRENT_RULE" --arg s "$sev" --arg g "$guideline" \
+        --arg m "$msg" --arg f "$file" --arg l "$line" \
+    '{rule_id:$r, severity:$s, guideline:$g, message:$m,
+      file:(if $f=="" then null else $f end),
+      line:(if $l=="" then null else ($l|tonumber) end),
+      suppressed:false}' >> "$FINDINGS_TMP"
+}
+
+: "${_SUPPRESSED_COUNT:=0}"
+
+# _record_suppressed <severity> <message> [<file>] [<line>]
+# Same JSONL record as _record but suppressed:true, and bumps the counter.
+_record_suppressed() {
+  [[ -z "$FINDINGS_TMP" ]] && { _SUPPRESSED_COUNT=$((_SUPPRESSED_COUNT + 1)); return 0; }
+  local sev="$1" msg="$2" file="${3:-}" line="${4:-}" guideline
+  guideline="$(printf '%s' "$msg" | awk '{print $1}')"
+  jq -nc --arg r "$_CURRENT_RULE" --arg s "$sev" --arg g "$guideline" \
+        --arg m "$msg" --arg f "$file" --arg l "$line" \
+    '{rule_id:$r, severity:$s, guideline:$g, message:$m,
+      file:(if $f=="" then null else $f end),
+      line:(if $l=="" then null else ($l|tonumber) end),
+      suppressed:true}' >> "$FINDINGS_TMP"
+  _SUPPRESSED_COUNT=$((_SUPPRESSED_COUNT + 1))
+}
+
+: "${PRECHECK_VERSION:=dev}"
+
+# render_json -> prints the structured envelope. Verdict reuses verdict.sh thresholds
+# (RED >=1 FAIL; YELLOW >=5 WARN; else GREEN), counting non-suppressed findings only.
+render_json() {
+  local buf="${FINDINGS_TMP:-/dev/null}"
+  [[ -s "$buf" ]] || { printf '%s\n' '{"findings":[]}' | jq \
+     --arg v "$PRECHECK_VERSION" '{tool:"appstore-precheck",version:$v,verdict:"GREEN",summary:{fail:0,warn:0,pass:0,suppressed:0},findings:[]}'; return 0; }
+  jq -s --arg v "$PRECHECK_VERSION" '
+    (map(select(.suppressed==false))) as $live
+    | ($live|map(select(.severity=="FAIL"))|length) as $f
+    | ($live|map(select(.severity=="WARN"))|length) as $w
+    | ($live|map(select(.severity=="PASS"))|length) as $p
+    | (map(select(.suppressed==true))|length) as $s
+    | (if $f>=1 then "RED" elif $w>=5 then "YELLOW" else "GREEN" end) as $verdict
+    | {tool:"appstore-precheck", version:$v, verdict:$verdict,
+       summary:{fail:$f, warn:$w, pass:$p, suppressed:$s},
+       findings: .}' "$buf"
+}

package/skills/appstore-precheck/scripts/scan.sh

@@ -12,6 +12,28 @@ set -u
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="$(pwd)"
 cd "$ROOT" || { echo "FAIL: repo-root — could not enter repository root"; exit 0; }
 
+source "$(dirname "${BASH_SOURCE[0]}")/findings.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/suppress.sh"
+FINDINGS_TMP="$(mktemp)"; export FINDINGS_TMP
+trap 'rm -f "$FINDINGS_TMP"' EXIT
+FORMAT="text"
+# The envelope `version` is the appstore-precheck TOOL's own version (from this
+# skill's SKILL.md), never the scanned repo's — $ROOT above is the SCANNED app's
+# git root, so reading its package.json here would leak the wrong version.
+PRECHECK_VERSION="$(grep -m1 -E '^[[:space:]]*version:' "$(dirname "${BASH_SOURCE[0]}")/../SKILL.md" 2>/dev/null | sed -E 's/.*version:[[:space:]]*//; s/[[:space:]]*$//')"
+[[ -z "$PRECHECK_VERSION" ]] && PRECHECK_VERSION="dev"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --format)
+      if [[ $# -lt 2 ]]; then echo "scan.sh: --format needs a value (text|json)" >&2; exit 64; fi
+      FORMAT="$2"; shift 2 ;;
+    --format=*) FORMAT="${1#*=}"; shift ;;
+    *) shift ;;
+  esac
+done
+[[ "$FORMAT" == json || "$FORMAT" == text ]] || { echo "scan.sh: --format must be text|json" >&2; exit 64; }
+
 CONFIG="${APPSTORE_PRECHECK_CONFIG:-.appstore-precheck.json}"
 have_jq() { command -v jq >/dev/null 2>&1; }
 
@@ -32,9 +54,13 @@ cfg_bool() { # cfg_bool <json-path> — echoes "true"/"false"
   echo "false"
 }
 
-fail() { echo "FAIL: $1"; }
-warn() { echo "WARN: $1"; }
-pass() { echo "PASS: $1"; }
+_LAST_SUPPRESSED=0
+fail() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed FAIL "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "FAIL: $1"; _record FAIL "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+warn() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed WARN "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "WARN: $1"; _record WARN "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+pass() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed PASS "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "PASS: $1"; _record PASS "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+
+# detail <text> — indented evidence under the previous finding; skipped when it was suppressed.
+detail() { [[ "${_LAST_SUPPRESSED:-0}" == 1 ]] || printf '%s\n' "$1" | sed 's/^/      /'; }
 
 # ===================================================================
 # Auto-detection of the project layout
@@ -55,6 +81,17 @@ GREP_PRUNE=( --exclude-dir=.git --exclude-dir=Pods --exclude-dir=Carthage
             --exclude-dir=.claude --exclude-dir=worktrees
             --exclude-dir=node_modules --exclude-dir=vendor )
 
+# Load .precheck-ignore path exclusions (Task 2 suppress.sh) and extend both
+# prune sets so a suppressed path is skipped by detection AND grep passes.
+load_precheck_ignore "$ROOT"
+while IFS= read -r _g; do
+  [[ -z "$_g" ]] && continue
+  PRUNE+=( -not -path "*/$_g/*" -not -path "$_g/*" )
+  GREP_PRUNE+=( --exclude-dir="${_g##*/}" )
+done <<PRUNE_GLOBS
+$(precheck_prune_globs)
+PRUNE_GLOBS
+
 # Reads newline-separated paths on stdin, prints the one with the fewest path
 # segments (the shallowest, i.e. the real project copy rather than a nested one).
 pick_shallowest() { awk '{ n=gsub(/\//,"/"); print n"\t"$0 }' | sort -n | head -1 | cut -f2-; }
@@ -150,6 +187,8 @@ SUB_KEY="$(cfg '.disclosureKeys.subscription' 'subscription_disclosure')"
 TRIAL_KEY="$(cfg '.disclosureKeys.trial' 'subscription_trial_disclosure')"
 CHECK_FAMILY="$(cfg_bool '.optionalChecks.familyControls')"
 
+if [[ "$FORMAT" == json ]]; then exec 4>&1 1>/dev/null; fi
+
 echo "PASS: layout — ios='${IOS_DIR:-?}' metadata='${META_DIR:-?}' xcstrings='${XCSTRINGS:-?}' locales=${#LOCALES[@]}"
 
 # ===================================================================
@@ -159,14 +198,15 @@ echo "PASS: layout — ios='${IOS_DIR:-?}' metadata='${META_DIR:-?}' xcstrings='
 # (v) "Account Sign-In" is a different rule — its account-deletion requirement is
 # checked separately in §38.
 # ===================================================================
+set_rule "privacy-manifest-parity"
 check_required_reason_api() {
   local cat="$1" pattern="$2" hits declared
   hits=$(grep -rEl "$pattern" "$IOS_DIR" --include="*.swift" 2>/dev/null | head -3)
   declared=$(grep -c "NSPrivacyAccessedAPICategory${cat}" "$PRIVACY_FILE" 2>/dev/null)
   if [[ -n "$hits" && "${declared:-0}" -eq 0 ]]; then
-    fail "5.1.1 Required Reason API — '$cat' used in code (e.g. $(echo "$hits" | head -1)) but not declared in PrivacyInfo.xcprivacy"
+    fail "5.1.1 Required Reason API — '$cat' used in code (e.g. $(echo "$hits" | head -1)) but not declared in PrivacyInfo.xcprivacy" "$PRIVACY_FILE"
   elif [[ -z "$hits" && "${declared:-0}" -gt 0 ]]; then
-    warn "5.1.1 PrivacyInfo — '$cat' declared but no code usage grepped (may be a false positive, verify manually)"
+    warn "5.1.1 PrivacyInfo — '$cat' declared but no code usage grepped (may be a false positive, verify manually)" "$PRIVACY_FILE"
   elif [[ -n "$hits" && "${declared:-0}" -gt 0 ]]; then
     pass "5.1.1 Required Reason API — '$cat' parity OK"
   fi
@@ -174,7 +214,7 @@ check_required_reason_api() {
 if [[ -z "$IOS_DIR" ]]; then
   warn "layout — could not auto-detect iOS source dir; set .iosSourceDir in $CONFIG"
 elif [[ -z "$PRIVACY_FILE" ]]; then
-  fail "5.1.1 Required Reason API — PrivacyInfo.xcprivacy not found (required since May 2024 for apps using Required Reason APIs)"
+  fail "5.1.1 Required Reason API — PrivacyInfo.xcprivacy not found (required since May 2024 for apps using Required Reason APIs)" "$INFO_PLIST"
 else
   check_required_reason_api "UserDefaults"   'UserDefaults|@AppStorage'
   check_required_reason_api "FileTimestamp"  'attributesOfItem|creationDate|modificationDate|\.fileCreationDate|\.fileModificationDate'
@@ -186,26 +226,52 @@ fi
 # ===================================================================
 # §2 — 5.1.1 NSUsageDescription cross-check (Info.plist)
 # ===================================================================
+set_rule "usage-description-crosscheck"
 if [[ ! -f "$INFO_PLIST" ]]; then
-  [[ -n "$IOS_DIR" ]] && warn "5.1.1 Info.plist not found at $INFO_PLIST (modern Xcode may auto-generate it; verify purpose strings in build settings)"
+  [[ -n "$IOS_DIR" ]] && warn "5.1.1 Info.plist not found at $INFO_PLIST (modern Xcode may auto-generate it; verify purpose strings in build settings)" "$INFO_PLIST"
 else
   awk '/NS[A-Za-z]+UsageDescription/{key=$0; getline; if($0 ~ /<string>[[:space:]]*<\/string>/) print "EMPTY:"key}' "$INFO_PLIST" | while read -r line; do
-    [[ -n "$line" ]] && fail "5.1.1 Purpose String — $line (empty usage description is rejected by App Review)"
+    [[ -n "$line" ]] && fail "5.1.1 Purpose String — $line (empty usage description is rejected by App Review)" "$INFO_PLIST"
   done
   for fw in \
     "FamilyControls|ManagedSettings|DeviceActivity:NSFamilyControlsUsageDescription" \
     "CoreLocation:NSLocationWhenInUseUsageDescription" \
-    "AVFoundation:NSCameraUsageDescription|NSMicrophoneUsageDescription" \
-    "Photos:NSPhotoLibraryUsageDescription" \
     "Contacts:NSContactsUsageDescription" \
     "HealthKit:NSHealthShareUsageDescription"; do
     framework="${fw%%:*}"; needed_key="${fw##*:}"
     if grep -rqE "import ($framework)|($framework)\." "$IOS_DIR" --include="*.swift" 2>/dev/null; then
       if ! grep -qE "$needed_key" "$INFO_PLIST" 2>/dev/null; then
-        fail "5.1.1 framework '${framework%%|*}' imported but Info.plist is missing '${needed_key%%|*}'"
+        fail "5.1.1 framework '${framework%%|*}' imported but Info.plist is missing '${needed_key%%|*}'" "$INFO_PLIST"
       fi
     fi
   done
+  # AVFoundation and Photos are gated on real capture/read APIs, not bare
+  # imports: an import only signals framework linkage, not camera/mic/library
+  # access (e.g. AVFoundation is commonly imported for playback-only use via
+  # AVAudioPlayer/AVPlayer, and Photos/PhotosUI's PhotosPicker/PHPickerViewController
+  # run out-of-process and need no Info.plist key at all).
+  # Camera: purpose string required only when a capture API is actually used.
+  if grep -rqE 'AVCaptureDevice|AVCaptureSession|UIImagePickerController' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSCameraUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 camera capture API used but Info.plist is missing 'NSCameraUsageDescription'" "$INFO_PLIST"
+  fi
+  # Microphone: required only for recording/capture, not playback. Matched
+  # separately from the camera check above: a bare AVCaptureDevice only
+  # implies microphone use when it is audio-typed (`.audio` device/media
+  # type), not for a video-only capture device.
+  if grep -rqE 'AVAudioRecorder|installTap\(|AVAudioEngine\(|AVAudioSession[^;]*\.(playAndRecord|record)|AVCaptureDevice[^;)]*\.audio|for:[[:space:]]*\.audio' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSMicrophoneUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 microphone/recording API used but Info.plist is missing 'NSMicrophoneUsageDescription'" "$INFO_PLIST"
+  fi
+  # Photo library READ: PhotosPicker/PHPicker need no key; only true read/fetch APIs do.
+  if grep -rqE 'PHAsset\b|PHFetchResult|PHImageManager|fetchAssets|PHAssetCollection' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSPhotoLibraryUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 Photos read API used but Info.plist is missing 'NSPhotoLibraryUsageDescription'" "$INFO_PLIST"
+  elif grep -rqE 'PHAssetCreationRequest|UIImageWriteToSavedPhotosAlbum|performChanges' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    # Add-only save: covered by the add-only key.
+    grep -qE 'NSPhotoLibraryAddUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 Photos add-only API used but Info.plist is missing 'NSPhotoLibraryAddUsageDescription'" "$INFO_PLIST"
+  fi
 fi
 
 # ===================================================================
@@ -214,13 +280,14 @@ fi
 # Ad / attribution / IDFA SDK signal, shared with §16. The reverse of §3: §3 fires
 # when the ATT framework IS imported; §16 fires when a tracking SDK is present but
 # the ATT prompt is NOT. Computed once here so the two checks never contradict.
+set_rule "att-usage"
 tracking_sdk=$(grep -rlE 'advertisingIdentifier|ASIdentifierManager|GADMobileAds|GoogleMobileAds|AppLovinSDK|ALSdk|AppsFlyerLib|import Adjust|Adjust\.|FBAudienceNetwork|BranchSDK|IronSource' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 att_used=$(grep -rlE 'AppTrackingTransparency|ATTrackingManager' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 if [[ -n "$att_used" ]]; then
   if grep -q "NSUserTrackingUsageDescription" "$INFO_PLIST" 2>/dev/null; then
     pass "5.1.2 ATT — used + NSUserTrackingUsageDescription present"
   else
-    fail "5.1.2 ATT framework imported but NSUserTrackingUsageDescription missing in Info.plist ($att_used)"
+    fail "5.1.2 ATT framework imported but NSUserTrackingUsageDescription missing in Info.plist ($att_used)" "$INFO_PLIST"
   fi
 elif [[ -z "$tracking_sdk" ]]; then
   pass "5.1.2 ATT — not used (no tracking)"
@@ -231,12 +298,13 @@ fi
 # ===================================================================
 # §4 — 2.3.10 Other-platform / competitor mentions in metadata
 # ===================================================================
+set_rule "competitor-mentions"
 if [[ -d "$META_DIR" ]]; then
   banned_re='Android|Google[[:space:]]?Play|Play[[:space:]]?Store|Windows[[:space:]]?Phone|Samsung Galaxy|Huawei AppGallery|F-Droid'
   hits=$(grep -rEnI "$banned_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -30)
   if [[ -n "$hits" ]]; then
     fail "2.3.10 Other-platform mention — banned reference in metadata:"
-    echo "$hits" | sed 's/^/      /'
+    detail "$hits"
   else
     pass "2.3.10 Other-platform mentions — metadata clean"
   fi
@@ -245,6 +313,7 @@ fi
 # ===================================================================
 # §5 — 2.3.1 Metadata character limits (Unicode codepoints, like ASC)
 # ===================================================================
+set_rule "metadata-char-limits"
 check_len() {
   local file="$1" limit="$2" label="$3" len
   [[ -f "$file" ]] || return
@@ -254,7 +323,7 @@ check_len() {
     len=$(wc -m < "$file" | tr -d ' ')
   fi
   [[ -z "$len" ]] && return
-  (( len > limit )) && fail "2.3.1 $label — $file ${len} chars (limit ${limit})"
+  (( len > limit )) && fail "2.3.1 $label — $file ${len} chars (limit ${limit})" "$file"
 }
 for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
   d="$META_DIR/$loc"; [[ -d "$d" ]] || continue
@@ -268,6 +337,7 @@ done
 # ===================================================================
 # §6 — 2.3.7 Localized metadata parity across all detected locales
 # ===================================================================
+set_rule "locale-metadata-parity"
 if (( ${#LOCALES[@]} > 0 )); then
   expected_files=(name.txt subtitle.txt description.txt keywords.txt)
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
@@ -294,6 +364,7 @@ fi
 # ===================================================================
 # §7 — 2.3.3 Screenshots per locale
 # ===================================================================
+set_rule "screenshots-per-locale"
 if [[ -n "$SCREEN_DIR" && -d "$SCREEN_DIR" ]]; then
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
     d="$SCREEN_DIR/$loc"
@@ -307,20 +378,24 @@ if [[ -n "$SCREEN_DIR" && -d "$SCREEN_DIR" ]]; then
   done
   pass "2.3.3 Screenshots — checked ${#LOCALES[@]} locales under $SCREEN_DIR"
 else
-  warn "2.3.3 Screenshots — screenshots dir not found (set .screenshotsDir if you manage them in-repo)"
+  pass "2.3.3 Screenshots — no in-repo screenshots dir; assumed managed in App Store Connect (set .screenshotsDir to check in-repo)"
 fi
 
 # ===================================================================
 # In-app purchase gate — only run 3.1.2 checks if IAP signals exist
 # ===================================================================
 iap_detected=""
-grep -rqE 'import StoreKit|RevenueCat|Purchases\.|Product\(for:|AppStore\.|SKProduct|StoreKit2' "$IOS_DIR" --include="*.swift" 2>/dev/null && iap_detected=1
+grep -rqE 'SKPaymentQueue|SKProduct|SKMutablePayment|Product\.products|Product\(for:|Product\(id:|\.purchase\(|Transaction\.currentEntitlements|Transaction\.updates|RevenueCat|Purchases\.(shared|configure|logIn|getProducts)|Adapty|Glassfy|import Qonversion' "$IOS_DIR" --include="*.swift" 2>/dev/null && iap_detected=1
 [[ -n "$SUB_VIEW" ]] && iap_detected=1
 
 if [[ -z "$iap_detected" ]]; then
+  # Not one of the 41 catalog sections — clear the rule_id so this PASS doesn't
+  # inherit §7's "screenshots-per-locale" slug in the JSON output.
+  set_rule ""
   pass "3.1.2 IAP — no in-app purchase / subscription signals detected, skipping paywall checks"
 else
   # ---- §8 3.1.2 Trial disclosure -------------------------------------------------
+  set_rule "trial-disclosure"
   trial_re='free[[:space:]]?trial|trial[[:space:]]?period|ücretsiz[[:space:]]?dene|kostenlos[[:space:]]?test|essai[[:space:]]?gratuit|prueba[[:space:]]?grat|無料.*トライアル|무료[[:space:]]?체험'
   if [[ -n "$XCSTRINGS" ]] && grep -EqI "$trial_re" "$XCSTRINGS" 2>/dev/null; then
     if grep -q "$TRIAL_KEY" "$XCSTRINGS" 2>/dev/null; then
@@ -333,6 +408,7 @@ else
   fi
 
   # ---- §9 3.1.2 Auto-renew subscription disclosure -------------------------------
+  set_rule "autorenew-disclosure"
   if [[ -n "$XCSTRINGS" ]]; then
     if have_jq && jq -e ".strings | has(\"$SUB_KEY\")" "$XCSTRINGS" >/dev/null 2>&1; then
       pass "3.1.2 subscription disclosure key '$SUB_KEY' present"
@@ -353,6 +429,7 @@ else
   # Grep across the whole paywall cluster: a link present in ANY paywall view satisfies
   # the requirement; only its absence from ALL of them is a FAIL. SUB_VIEW names the
   # representative file in messages.
+  set_rule "subscription-links-restore"
   if (( ${#PAYWALL_FILES[@]} > 0 )); then
     if grep -qE 'restore|restorePurchases' "${PAYWALL_FILES[@]}"; then
       pass "3.1.2 Restore Purchases — present in $(basename "$SUB_VIEW")"
@@ -377,11 +454,15 @@ fi
 # ===================================================================
 # §11 — 2.5.1 Private / banned API
 # ===================================================================
+set_rule "private-api"
 banned_api='UIWebView|setSelectionIndicatorImage|_UIBackdropView|NSURLConnection[^a-zA-Z]|UIAlertView[^Q]|UIActionSheet[^Q]'
 banned_hits=$(grep -rEnI "$banned_api" "$IOS_DIR" --include="*.swift" --include="*.m" --include="*.h" 2>/dev/null | head -5)
 if [[ -n "$banned_hits" ]]; then
-  fail "2.5.1 Private/Deprecated API:"
-  echo "$banned_hits" | sed 's/^/      /'
+  pa_first="$(printf '%s\n' "$banned_hits" | head -1)"   # "path:line:match"
+  pa_file="${pa_first%%:*}"
+  pa_rest="${pa_first#*:}"; pa_line="${pa_rest%%:*}"
+  fail "2.5.1 Private/Deprecated API:" "$pa_file" "$pa_line"
+  detail "$banned_hits"
 else
   pass "2.5.1 Private API — clean"
 fi
@@ -389,7 +470,8 @@ fi
 # ===================================================================
 # §12 — 4.2 Minimum functionality — navigation hubs
 # ===================================================================
-tab_count=$(grep -rcE 'TabView|NavigationStack|NavigationSplitView' "$IOS_DIR" --include="*.swift" 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+set_rule "min-functionality-nav"
+tab_count=$(grep -rcE 'TabView|NavigationStack|NavigationSplitView|NavigationView|UITabBarController|UINavigationController|createBottomTabNavigator|createStackNavigator|createNativeStackNavigator' . "${GREP_PRUNE[@]}" --include='*.swift' --include='*.m' --include='*.js' --include='*.jsx' --include='*.ts' --include='*.tsx' 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
 if (( tab_count < 1 )); then
   warn "4.2 Minimum functionality — no TabView/NavigationStack found (heuristic, may be a false positive)"
 else
@@ -399,6 +481,7 @@ fi
 # ===================================================================
 # §13 — 5.1.5 Screen Time / sensitive-API justification (optional, opt-in)
 # ===================================================================
+set_rule "screentime-justification"
 if [[ "$CHECK_FAMILY" == "true" ]] && grep -q "NSFamilyControlsUsageDescription" "$INFO_PLIST" 2>/dev/null; then
   if [[ -n "$REVIEW_PREP" && -f "$REVIEW_PREP" ]] && grep -qiE 'family|screen[[:space:]]?time' "$REVIEW_PREP" 2>/dev/null; then
     pass "5.1.5 Screen Time API — reviewer-prep justification note present"
@@ -410,6 +493,7 @@ fi
 # ===================================================================
 # §14 — 4.8 Sign in with Apple parity (only when a third-party social login is used)
 # ===================================================================
+set_rule "siwa-parity"
 if [[ -n "$IOS_DIR" ]]; then
   social_login=$(grep -rlE 'GIDSignIn|import GoogleSignIn|FBSDKLoginKit|FBSDKLoginManager|FacebookLogin|import Auth0|LineSDK|VKSdkAuthorization' "$IOS_DIR" --include='*.swift' 2>/dev/null | head -1)
   if [[ -n "$social_login" ]]; then
@@ -424,6 +508,7 @@ fi
 # ===================================================================
 # §15 — 3.1.1(a) External purchase link (StoreKit External Purchase)
 # ===================================================================
+set_rule "external-purchase-link"
 ext_purchase=""
 grep -rqE 'ExternalPurchase|ExternalPurchaseLink|ExternalPurchaseCustomLink' "${IOS_DIR:-.}" --include='*.swift' 2>/dev/null && ext_purchase=1
 grep -rqE 'external-purchase' "${IOS_DIR:-.}" --include='*.entitlements' 2>/dev/null && ext_purchase=1
@@ -437,6 +522,7 @@ fi
 # §3 catches "ATT framework imported but no usage string". This catches the more
 # common rejection: shipping an ad / attribution SDK (or touching the IDFA) without
 # ever presenting the ATT prompt. `tracking_sdk` and `att_used` are computed in §3.
+set_rule "tracking-sdk-no-att"
 if [[ -n "$tracking_sdk" ]]; then
   att_present=""
   [[ -n "$att_used" ]] && att_present=1
@@ -455,11 +541,12 @@ fi
 # submission. Setting it (true/false) removes that friction. Only checked when an
 # Info.plist exists; a modern app may auto-generate it, in which case the key lives
 # in build settings, so we stay silent rather than nag.
+set_rule "export-compliance"
 if [[ -f "$INFO_PLIST" ]]; then
   if grep -q "ITSAppUsesNonExemptEncryption" "$INFO_PLIST" 2>/dev/null; then
     pass "export-compliance — ITSAppUsesNonExemptEncryption set in Info.plist"
   else
-    warn "export-compliance — Info.plist has no ITSAppUsesNonExemptEncryption; set it (true/false) to skip the App Store Connect encryption-export prompt every submission"
+    warn "export-compliance — Info.plist has no ITSAppUsesNonExemptEncryption; set it (true/false) to skip the App Store Connect encryption-export prompt every submission" "$INFO_PLIST"
   fi
 fi
 
@@ -470,6 +557,7 @@ fi
 # support_url.txt / privacy_url.txt / marketing_url.txt. Apple requires a working
 # support URL, and a privacy policy URL for apps with accounts or IAP. Flag when
 # they are absent across every locale, or contain an obvious placeholder.
+set_rule "support-privacy-url"
 if [[ -d "$META_DIR" ]]; then
   support_found="" privacy_found=""
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
@@ -482,8 +570,9 @@ if [[ -d "$META_DIR" ]]; then
   fi
   url_ph=$(grep -rEnI 'example\.com|localhost|\bTODO\b|\bchangeme\b' "$META_DIR" --include='*_url.txt' 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$url_ph" ]]; then
-    warn "2.3 Metadata URL — placeholder URL in fastlane metadata (replace before submitting):"
-    echo "$url_ph" | sed 's/^/      /'
+    url_ph_file="$(printf '%s\n' "$url_ph" | head -1 | cut -d: -f1)"
+    warn "2.3 Metadata URL — placeholder URL in fastlane metadata (replace before submitting):" "$url_ph_file"
+    detail "$url_ph"
   fi
 fi
 
@@ -495,7 +584,8 @@ fi
 # domains, the privacy manifest and the App Privacy nutrition labels are probably
 # incomplete. Soft "verify" wording (a crash-only Sentry may genuinely collect
 # nothing), so WARN, never FAIL.
-analytics_sdk=$(grep -rlE 'FirebaseAnalytics|import Firebase|Amplitude|Mixpanel|import Sentry|Segment|Bugsnag|AppCenterAnalytics|Datadog' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
+set_rule "analytics-privacyinfo-mismatch"
+analytics_sdk=$(grep -rlE 'FirebaseAnalytics|import Firebase|import Amplitude|Amplitude\(|import Mixpanel|Mixpanel\.|import Sentry|SentrySDK|import Segment|SEGAnalytics|Analytics\.shared\(|import Bugsnag|Bugsnag\.|AppCenterAnalytics|import Datadog|DatadogCore' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 if [[ -n "$analytics_sdk" ]]; then
   declared_data=""
   if [[ -n "$PRIVACY_FILE" && -f "$PRIVACY_FILE" ]]; then
@@ -507,7 +597,7 @@ if [[ -n "$analytics_sdk" ]]; then
   if [[ -n "$declared_data" ]]; then
     pass "5.1.1 Privacy manifest — analytics SDK present and PrivacyInfo declares collected data"
   else
-    warn "5.1.1 Privacy manifest — analytics SDK detected (e.g. $(basename "$analytics_sdk")) but PrivacyInfo declares no collected data types or tracking domains; verify your privacy manifest and App Privacy nutrition labels"
+    warn "5.1.1 Privacy manifest — analytics SDK detected (e.g. $(basename "$analytics_sdk")) but PrivacyInfo declares no collected data types or tracking domains; verify your privacy manifest and App Privacy nutrition labels" "$PRIVACY_FILE"
   fi
 fi
 
@@ -518,12 +608,14 @@ fi
 # get rejected under 2.1 and look unfinished. Conservative, specific patterns to
 # avoid flagging legitimate words. Overlaps the Phase 2 precheck "No placeholder
 # text" rule, but this one is local and runs before any network call.
+set_rule "placeholder-metadata"
 if [[ -d "$META_DIR" ]]; then
   ph_re='lorem ipsum|Lorem ipsum|\bTODO\b|\bFIXME\b|example\.com|placeholder|insert .* here|\bchangeme\b'
   ph_hits=$(grep -rEnI "$ph_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -20)
   if [[ -n "$ph_hits" ]]; then
-    warn "2.1 Metadata content — placeholder/dummy text in store metadata (looks unfinished; rejected under 2.1):"
-    echo "$ph_hits" | sed 's/^/      /'
+    ph_file="$(printf '%s\n' "$ph_hits" | head -1 | cut -d: -f1)"
+    warn "2.1 Metadata content — placeholder/dummy text in store metadata (looks unfinished; rejected under 2.1):" "$ph_file"
+    detail "$ph_hits"
   fi
 fi
 
@@ -534,6 +626,7 @@ fi
 # third-party payment SDK (Stripe, Braintree, PayPal, …) is legitimate for
 # PHYSICAL goods/services but a frequent rejection when used to sell digital
 # content. We can't tell digital from physical statically, so this is advisory.
+set_rule "thirdparty-payment-sdk"
 if [[ -n "$IOS_DIR" ]]; then
   payment_sdk=$(grep -rlE 'import Stripe|StripePaymentSheet|StripeApplePay|import Braintree|BTPaymentFlow|import PayPal|PayPalCheckout|PayPalNativeCheckout|import Square|SquareInAppPayments|import Adyen|AdyenComponents|RazorpaySDK|import Paddle' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$payment_sdk" ]]; then
@@ -547,6 +640,7 @@ fi
 # Apps with UGC must provide: a content filter, a report mechanism, the ability
 # to block abusive users, and published contact info. We detect a UGC signal and
 # warn when no report/block/moderation affordance is found anywhere in the source.
+set_rule "ugc-no-moderation"
 if [[ -n "$IOS_DIR" ]]; then
   ugc_signal=$(grep -rlE 'userGeneratedContent|\bUGC\b|StreamChat|MessageKit|SendbirdSDK|PubNub|postComment|submitComment|createPost|publishPost|uploadUserPhoto|uploadVideo' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$ugc_signal" ]]; then
@@ -563,9 +657,13 @@ fi
 # ===================================================================
 # NSAllowsArbitraryLoads=true turns off ATS for the whole app, weakening
 # data-in-transit security and inviting a 1.6 / data-security question at review.
+set_rule "ats-arbitrary-loads"
 if [[ -f "$INFO_PLIST" ]]; then
-  if awk '/NSAllowsArbitraryLoads/{getline; if ($0 ~ /<true/) print "ON"}' "$INFO_PLIST" 2>/dev/null | grep -q ON; then
-    warn "1.6 App Transport Security — NSAllowsArbitraryLoads=true in Info.plist disables ATS app-wide; prefer per-domain exceptions, and expect a data-security justification request at review (1.6)"
+  # Anchor to the exact key: `NSAllowsArbitraryLoads</key>` (followed by `<`), so the
+  # narrower scoped exceptions NSAllowsArbitraryLoadsInWebContent / ...ForMedia — which
+  # do NOT disable ATS app-wide and are the recommended alternative — don't false-fire.
+  if awk '/NSAllowsArbitraryLoads</{getline; if ($0 ~ /<true/) print "ON"}' "$INFO_PLIST" 2>/dev/null | grep -q ON; then
+    warn "1.6 App Transport Security — NSAllowsArbitraryLoads=true in Info.plist disables ATS app-wide; prefer per-domain exceptions, and expect a data-security justification request at review (1.6)" "$INFO_PLIST"
   fi
 fi
 
@@ -577,6 +675,7 @@ fi
 # Pay recurring API (PKRecurringPaymentRequest) so it does NOT conflate StoreKit
 # auto-renew copy or a one-time PassKit payment with recurring Apple Pay. We don't
 # try to detect the disclosure text (too noisy) — we flag it for manual verify.
+set_rule "applepay-recurring-disclosure"
 if [[ -n "$IOS_DIR" ]] && grep -rqE 'PKRecurringPaymentRequest' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
   warn "4.9 Apple Pay — recurring Apple Pay (PKRecurringPaymentRequest) detected; verify you disclose the renewal term, what's provided, the charges, and how to cancel before purchase (4.9)"
 fi
@@ -586,6 +685,7 @@ fi
 # ===================================================================
 # Apple disallows custom review prompts and direct write-review links — apps must
 # use the system SKStoreReviewController / requestReview API.
+set_rule "custom-review-prompt"
 if [[ -n "$IOS_DIR" ]]; then
   review_link=$(grep -rlE 'write-review|action=write-review|itms-apps[^"]*review' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$review_link" ]]; then
@@ -602,12 +702,14 @@ fi
 # ===================================================================
 # Marketing the app for things iOS apps can't actually do (virus/malware
 # scanners, fake speed boosters) is a 2.3.1 removal vector.
+set_rule "misleading-marketing"
 if [[ -d "$META_DIR" ]]; then
   mislead_re='virus scan|virus scanner|antivirus|anti-virus|malware (scan|remov|clean)|spyware remov|clean your (iphone|device)|speed booster|boost.*(speed|ram)|free money|guaranteed.*(win|prize)'
   mislead_hits=$(grep -rEniI "$mislead_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$mislead_hits" ]]; then
-    warn "2.3.1 Misleading marketing — claims that often violate 2.3.1 (e.g. iOS virus/malware scanners, fake speed boosters) in metadata; verify the app truly delivers them or remove the claim:"
-    echo "$mislead_hits" | sed 's/^/      /'
+    mislead_file="$(printf '%s\n' "$mislead_hits" | head -1 | cut -d: -f1)"
+    warn "2.3.1 Misleading marketing — claims that often violate 2.3.1 (e.g. iOS virus/malware scanners, fake speed boosters) in metadata; verify the app truly delivers them or remove the claim:" "$mislead_file"
+    detail "$mislead_hits"
   fi
 fi
 
@@ -616,12 +718,17 @@ fi
 # ===================================================================
 # Terms implying a child audience in name/subtitle/keywords/description are
 # reserved for the Kids Category (2.3.8 / 5.1.4).
+set_rule "kids-wording"
 if [[ -d "$META_DIR" ]]; then
   kids_re='for kids|for children|for your (kid|child)|kids[[:space:]]?app|für kinder|para niños|pour enfants'
   kids_hits=$(grep -rEniI "$kids_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
-  if [[ -n "$kids_hits" ]]; then
-    warn "2.3.8 'For Kids/Children' wording — terms implying a child audience are reserved for the Kids Category (2.3.8); if not enrolled, remove them from name/subtitle/keywords/description:"
-    echo "$kids_hits" | sed 's/^/      /'
+  # Cross-gate with §39 (5.1.4): when an ads/analytics SDK is also linked, §39 fires the
+  # more specific Kids finding for the same wording signal — don't double-count it here
+  # (one root signal must not cost two WARNs against the 5-WARN YELLOW threshold).
+  if [[ -n "$kids_hits" && -z "${tracking_sdk:-}" && -z "${analytics_sdk:-}" ]]; then
+    kids_file="$(printf '%s\n' "$kids_hits" | head -1 | cut -d: -f1)"
+    warn "2.3.8 'For Kids/Children' wording — terms implying a child audience are reserved for the Kids Category (2.3.8); if not enrolled, remove them from name/subtitle/keywords/description:" "$kids_file"
+    detail "$kids_hits"
   fi
 fi
 
@@ -630,10 +737,11 @@ fi
 # ===================================================================
 # Keyboards must stay functional without full network access / "full access",
 # and may only collect data to enhance the keyboard.
+set_rule "keyboard-full-access"
 kb_plist=$(grep -rlE 'com\.apple\.keyboard-service' --include='Info.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
 if [[ -n "$kb_plist" ]]; then
   if grep -A1 'RequestsOpenAccess' "$kb_plist" 2>/dev/null | grep -q '<true'; then
-    warn "4.4.1 Keyboard extension — RequestsOpenAccess=true in $kb_plist; keyboards must remain functional without full access and may only collect data to enhance the keyboard (4.4.1). Justify full access in your review notes."
+    warn "4.4.1 Keyboard extension — RequestsOpenAccess=true in $(basename "$kb_plist"); keyboards must remain functional without full access and may only collect data to enhance the keyboard (4.4.1). Justify full access in your review notes."
   else
     pass "4.4.1 Keyboard extension — present without requiring full access"
   fi
@@ -644,6 +752,7 @@ fi
 # ===================================================================
 # Personal health information must not be stored in iCloud, and HealthKit data
 # may not be used for advertising/marketing.
+set_rule "health-icloud-sync"
 if [[ -n "$IOS_DIR" ]] && grep -rqE 'import HealthKit|HKHealthStore' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
   if grep -rqE 'import CloudKit|CKRecord|CKContainer|NSUbiquitousKeyValueStore|NSUbiquitousContainer' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
     warn "5.1.3 Health data — HealthKit and iCloud/CloudKit are both used; personal health information must not be stored in iCloud (5.1.3). Verify HealthKit data is not synced to iCloud."
@@ -657,6 +766,7 @@ fi
 # ===================================================================
 # VPN apps must be offered by an organization account, declare data collection
 # on-screen before use, and may not sell/share data.
+set_rule "vpn-networkextension"
 if [[ -n "$IOS_DIR" ]]; then
   vpn_use=$(grep -rlE 'NEVPNManager|NETunnelProviderManager|NEPacketTunnelProvider|NEVPNProtocol' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$vpn_use" ]]; then
@@ -671,6 +781,7 @@ fi
 # or notes). We fire only on a credential-login signal (a password field or a
 # Login/SignIn view), then look for demo creds in fastlane review_information or
 # the reviewer-prep notes. Social-only logins are not gated here (too noisy).
+set_rule "demo-account"
 if [[ -n "$IOS_DIR" ]]; then
   auth_signal=$(grep -rlE 'SecureField' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   [[ -z "$auth_signal" ]] && auth_signal=$(find "$IOS_DIR" "${PRUNE[@]}" \( -name '*Login*View*.swift' -o -name '*SignIn*View*.swift' \) 2>/dev/null | head -1)
@@ -697,6 +808,7 @@ fi
 # Apps must be self-contained; native hot-patching frameworks (JSPatch, Rollout,
 # DynamicCocoa) download code that changes features and are a removal vector.
 # JS-bundle OTA for React Native (CodePush) is allowed, so we do NOT flag it.
+set_rule "executable-code-download"
 if [[ -n "$IOS_DIR" ]]; then
   hotcode=$(grep -rlE 'import JSPatch|JSPatch\.|[Jj][Ss][Pp]atch|import Rollout|Rollout\.|rollout\.io|DynamicCocoa|import SwiftPatch' "$IOS_DIR" --include="*.swift" --include="*.m" --include="*.h" 2>/dev/null | head -1)
   if [[ -n "$hotcode" ]]; then
@@ -710,6 +822,7 @@ fi
 # Declare only the UIBackgroundModes the app actually uses; a mode declared with
 # no matching API is a frequent rejection. We parse the array and check each
 # declared mode against its framework/API in Swift.
+set_rule "background-modes-unused"
 if [[ -f "$INFO_PLIST" && -n "$IOS_DIR" ]]; then
   modes=$(awk '/<key>UIBackgroundModes<\/key>/{f=1;next} f&&/<\/array>/{f=0} f&&/<string>/{gsub(/.*<string>|<\/string>.*/,""); print}' "$INFO_PLIST" 2>/dev/null)
   if [[ -n "$modes" ]]; then
@@ -718,16 +831,16 @@ if [[ -f "$INFO_PLIST" && -n "$IOS_DIR" ]]; then
       [[ -z "$m" ]] && continue
       case "$m" in
         location) grep -rqE 'CLLocationManager|CoreLocation' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused location" ;;
-        audio) grep -rqE 'AVAudioSession|AVPlayer|AVAudioPlayer|AVQueuePlayer|AVAudioEngine' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused audio" ;;
+        audio) grep -rqE 'AVAudioSession|AVPlayer|AVAudioPlayer|AVQueuePlayer|AVAudioEngine|AVKit|VideoPlayer|AVPlayerViewController|MPMusicPlayerController|MPNowPlayingInfoCenter' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused audio" ;;
         voip) grep -rqE 'PushKit|PKPushRegistry|CallKit|CXProvider' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused voip" ;;
-        fetch) grep -rqE 'BGAppRefreshTask|BackgroundTasks|setMinimumBackgroundFetchInterval|performFetchWithCompletionHandler' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused fetch" ;;
-        processing) grep -rqE 'BGProcessingTask|BackgroundTasks' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused processing" ;;
+        fetch) grep -rqE 'BGAppRefreshTask|BGTaskScheduler|BackgroundTasks|setMinimumBackgroundFetchInterval|performFetchWithCompletionHandler' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused fetch" ;;
+        processing) grep -rqE 'BGProcessingTask|BGTaskScheduler|BackgroundTasks' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused processing" ;;
         bluetooth-central|bluetooth-peripheral) grep -rqE 'CoreBluetooth|CBCentralManager|CBPeripheralManager' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused $m" ;;
         remote-notification) grep -rqE 'didReceiveRemoteNotification|UNUserNotificationCenter|registerForRemoteNotifications' "$IOS_DIR" --include="*.swift" 2>/dev/null || unused="$unused remote-notification" ;;
       esac
     done <<< "$modes"
     if [[ -n "$unused" ]]; then
-      warn "2.5.4 Background modes —$unused declared in UIBackgroundModes but no matching API usage found in Swift; declare only the background modes the app actually uses (2.5.4)"
+      warn "2.5.4 Background modes —$unused declared in UIBackgroundModes but no matching API usage found in Swift; declare only the background modes the app actually uses (2.5.4)" "$INFO_PLIST"
     else
       pass "2.5.4 Background modes — declared modes have matching API usage"
     fi
@@ -737,6 +850,7 @@ fi
 # ===================================================================
 # §34 — 3.1.5(a) Cryptocurrency wallet / exchange / mining
 # ===================================================================
+set_rule "crypto-wallet-mining"
 if [[ -n "$IOS_DIR" ]]; then
   crypto_sdk=$(grep -rlE 'import Web3|web3swift|Web3Swift|WalletConnect|TrustWalletCore|CoinbaseWalletSDK|SolanaSwift|CryptoMining|coinhive|MoneroMiner' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$crypto_sdk" ]]; then
@@ -750,6 +864,7 @@ fi
 # A thin WKWebView wrapper around a website is rejected under minimum
 # functionality. Heuristic: WKWebView present in a project with very few Swift
 # files. WARN (verify) — this is the most false-positive-prone of the batch.
+set_rule "webview-wrapper"
 if [[ -n "$IOS_DIR" ]]; then
   if grep -rqE 'WKWebView' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
     swift_n=$(find "$IOS_DIR" "${PRUNE[@]}" -name '*.swift' 2>/dev/null | wc -l | tr -d ' ')
@@ -762,6 +877,7 @@ fi
 # ===================================================================
 # §36 — 4.2.7 Remote desktop / host-mirroring
 # ===================================================================
+set_rule "remote-desktop"
 if [[ -n "$IOS_DIR" ]]; then
   remote_desktop=$(grep -rlE 'import libvncclient|LibVNC|VNCClient|RDPSession|RDPKit|RemoteDesktopClient|import FreeRDP|JumpDesktop' "$IOS_DIR" --include="*.swift" --include="*.m" 2>/dev/null | head -1)
   if [[ -n "$remote_desktop" ]]; then
@@ -772,9 +888,10 @@ fi
 # ===================================================================
 # §37 — 4.4.2 Safari extension / content blocker
 # ===================================================================
+set_rule "safari-extension"
 safari_ext=$(grep -rlE 'com\.apple\.Safari\.(content-blocker|web-extension|extension)' --include='Info.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
 if [[ -n "$safari_ext" ]]; then
-  warn "4.4.2 Safari extension — a Safari content-blocker / web extension was detected ($safari_ext); it must use the extension APIs as intended, do only what it declares, and not include hidden analytics/ads or track without consent (4.4.2). Verify."
+  warn "4.4.2 Safari extension — a Safari content-blocker / web extension was detected ($(basename "$safari_ext")); it must use the extension APIs as intended, do only what it declares, and not include hidden analytics/ads or track without consent (4.4.2). Verify."
 fi
 
 # ===================================================================
@@ -783,6 +900,7 @@ fi
 # Apple 5.1.1(v): apps that support account creation must also let users delete
 # their account from within the app. Detect account-creation signals, then look
 # for an in-app deletion path. Deletion via a web page is missed → WARN, not FAIL.
+set_rule "account-no-delete"
 if [[ -n "$IOS_DIR" ]]; then
   signup=$(grep -rlE 'createUser|signUp|signup|createAccount|registerUser|registerNewUser|Auth\.auth\(\)\.createUser' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$signup" ]]; then
@@ -801,6 +919,7 @@ fi
 # must include a parental gate. We fire when the metadata targets a child
 # audience AND an ad/analytics SDK is linked. tracking_sdk/analytics_sdk come
 # from §3/§19.
+set_rule "kids-ads-analytics"
 if [[ -d "$META_DIR" && -n "$IOS_DIR" ]]; then
   if grep -rqEiI 'for kids|for children|kids[[:space:]]?app|für kinder|para niños|pour enfants' "$META_DIR" 2>/dev/null; then
     if [[ -n "$tracking_sdk" || -n "$analytics_sdk" ]]; then
@@ -812,18 +931,23 @@ fi
 # ===================================================================
 # §40 — 5.3.4 Real-money gambling
 # ===================================================================
+set_rule "realmoney-gambling"
 if [[ -d "$META_DIR" ]]; then
   gamble_re='real[ -]?money|gambling|casino|sportsbook|sports[ -]?betting|place[ -].*bets|wager(ing)?|roulette.*real'
   gamble_hits=$(grep -rEniI "$gamble_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$gamble_hits" ]]; then
-    warn "5.3.4 Gambling — real-money gaming language in metadata; real-money gambling/lotteries need the proper licenses, must be geo-restricted to permitted regions, and must be free on the App Store (5.3.4):"
-    echo "$gamble_hits" | sed 's/^/      /'
+    gamble_first="$(printf '%s\n' "$gamble_hits" | head -1)"   # "path:line:match"
+    gamble_file="${gamble_first%%:*}"
+    gamble_rest="${gamble_first#*:}"; gamble_line="${gamble_rest%%:*}"
+    warn "5.3.4 Gambling — real-money gaming language in metadata; real-money gambling/lotteries need the proper licenses, must be geo-restricted to permitted regions, and must be free on the App Store (5.3.4):" "$gamble_file" "$gamble_line"
+    detail "$gamble_hits"
   fi
 fi
 
 # ===================================================================
 # §41 — 5.5 Mobile Device Management
 # ===================================================================
+set_rule "mdm"
 if [[ -n "$IOS_DIR" ]]; then
   mdm_sig=$(grep -rlE 'import DeviceManagement|MDMConfiguration|ManagedAppConfiguration|com\.apple\.mdm' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   [[ -z "$mdm_sig" ]] && mdm_sig=$(grep -rlE 'com\.apple\.configuration\.managed' --include='*.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
@@ -833,3 +957,7 @@ if [[ -n "$IOS_DIR" ]]; then
 fi
 
 echo "---END-OF-SCAN---"
+if [[ "$FORMAT" == text && "${_SUPPRESSED_COUNT:-0}" -gt 0 ]]; then
+  printf '(%s finding(s) suppressed via .precheck-ignore)\n' "$_SUPPRESSED_COUNT"
+fi
+if [[ "$FORMAT" == json ]]; then exec 1>&4 4>&-; render_json; fi

package/skills/appstore-precheck/scripts/suppress.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# suppress.sh — .precheck-ignore + inline suppression for scan.sh.
+# Sourced by scan.sh AFTER findings.sh (needs rule_slug). Bash 3.2: no associative arrays.
+
+_SUPP_RULES=""        # rule-ids suppressed everywhere, one per line
+_SUPP_RULE_PATH=""    # "rule<TAB>glob" per line
+_SUPP_PATHS=""        # path globs excluded from scanning, one per line (trailing / stripped)
+_SUPP_REASON=""       # set by is_suppressed on a hit
+
+# _is_catalog_rule <token> -> 0 if token is a known rule slug.
+_is_catalog_rule() {
+  local n s
+  n=1
+  while [[ $n -le 41 ]]; do
+    s="$(rule_slug "$n")"
+    [[ "$s" == "$1" ]] && return 0
+    n=$((n + 1))
+  done
+  return 1
+}
+
+# load_precheck_ignore [root]
+load_precheck_ignore() {
+  local root="${1:-.}" file line t1 t2
+  file="$root/.precheck-ignore"
+  _SUPP_RULES=""; _SUPP_RULE_PATH=""; _SUPP_PATHS=""
+  [[ -f "$file" ]] || return 0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%#*}"                                   # strip trailing comment
+    line="$(printf '%s' "$line" | awk '{$1=$1;print}')"  # trim ends, collapse ws
+    [[ -z "$line" ]] && continue
+    t1="$(printf '%s' "$line" | awk '{print $1}')"
+    t2="$(printf '%s' "$line" | awk '{print $2}')"
+    if _is_catalog_rule "$t1"; then
+      if [[ -n "$t2" ]]; then
+        _SUPP_RULE_PATH="${_SUPP_RULE_PATH}${t1}	${t2%/}
+"
+      else
+        _SUPP_RULES="${_SUPP_RULES}${t1}
+"
+      fi
+    elif [[ "$t1" == */* || "$t1" == *.* || "$t1" == *"*"* ]]; then
+      _SUPP_PATHS="${_SUPP_PATHS}${t1%/}
+"
+    else
+      printf 'suppress: unknown rule-id %s in .precheck-ignore (ignored)\n' "$t1" >&2
+    fi
+  done < "$file"
+}
+
+# precheck_prune_globs -> one path glob per line (for scan.sh PRUNE/GREP_PRUNE).
+precheck_prune_globs() { printf '%s' "$_SUPP_PATHS"; }
+
+# _inline_marker <line-text> <rule> -> 0 if a real comment marker suppresses <rule>.
+_inline_marker() {
+  local text="$1" rule="$2" spec
+  printf '%s' "$text" | grep -qE '(//|#|<!--)[[:space:]]*precheck:ignore' || return 1
+  spec="$(printf '%s' "$text" | sed -nE 's/.*precheck:ignore[[:space:]]*([a-z][a-z0-9-]*).*/\1/p')"
+  [[ -z "$spec" ]] && return 0        # bare marker suppresses any rule
+  [[ "$spec" == "$rule" ]]            # scoped marker must match
+}
+
+# is_suppressed <rule> <file> <line> -> 0 if suppressed (+ _SUPP_REASON), else 1.
+is_suppressed() {
+  local rule="$1" file="${2:-}" line="${3:-}" r g target
+  _SUPP_REASON=""
+  if [[ -n "$rule" ]] && printf '%s\n' "$_SUPP_RULES" | grep -qxF "$rule"; then
+    _SUPP_REASON="rule:$rule"; return 0
+  fi
+  if [[ -n "$rule" && -n "$file" && -n "$_SUPP_RULE_PATH" ]]; then
+    while IFS='	' read -r r g; do
+      [[ -z "$r" ]] && continue
+      if [[ "$r" == "$rule" ]]; then
+        # shellcheck disable=SC2254
+        case "$file" in
+          $g|*/$g|$g/*|*/$g/*) _SUPP_REASON="rule-path:$rule:$g"; return 0 ;;
+        esac
+      fi
+    done <<INNER
+$_SUPP_RULE_PATH
+INNER
+  fi
+  if [[ -n "$file" && -n "$line" && -f "$file" ]]; then
+    target="$(sed -n "${line}p" "$file" 2>/dev/null)"
+    if _inline_marker "$target" "$rule"; then _SUPP_REASON="inline"; return 0; fi
+    if [[ "$line" -gt 1 ]]; then
+      target="$(sed -n "$((line - 1))p" "$file" 2>/dev/null)"
+      if _inline_marker "$target" "$rule"; then _SUPP_REASON="inline-above"; return 0; fi
+    fi
+  fi
+  return 1
+}