appstore-precheck 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ All notable changes to this project are documented here. Versioning follows
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-07-02
+
+Roadmap #5 (final roadmap item): an **optional, opt-in local dynamic simulator tier** —
+agent-mode, advisory, and off by default. It never changes the verdict and never runs
+in the offline CLI / npx / GitHub-Action path.
+
+When the user explicitly asks for a dynamic check and supplies a built app (or a booted
+simulator UDID + bundle id), the host model can run the app on a disposable simulator via
+`xcrun simctl` + Maestro MCP tools and observe real behavior a static scan cannot — launch
+without crashing (2.1), core screen reachable, paywall actually renders with terms (3.1.2),
+permission prompt matches its `Info.plist` purpose string (5.1.1), a demo/login path works
+(2.1), and live UI matches the marketing screenshots (2.3.5). It emits advisory
+`DYNAMIC-PASS:` / `DYNAMIC-FINDING:` lines, exactly like Pierre deep-review's `REVIEW-*`
+lines. It is the free/local alternative to a paid cloud device farm — a pre-submit local
+smoke signal, **not** a TestFlight / crash-reporter / QA replacement.
+
+### Added
+- **`skills/appstore-precheck/references/simulator-dynamic-review.md`** — the 6-check
+  agent-mode dynamic checklist (D1–D6) with advisory output format, modeled on the existing
+  deep-review reference docs.
+- **`SKILL.md`** — an optional "Phase 6" section (off by default) plus a scoped READ-ONLY
+  caveat and an updated "Known limits" note.
+- Methodology + README notes describing the tier.
+
+### Notes
+- Documentation-only: the offline scan path (`scan.sh`/`verdict.sh`/`bin/cli.js`/`action.yml`)
+  is byte-identical. READ-ONLY preserved — the tier touches only disposable simulator state,
+  never the user's repo. It is permanently local-only (macOS + Xcode + a simulator; it cannot
+  run in this project's `ubuntu-latest` CI). A deterministic `simulator-smoke.sh` and authored
+  Maestro flows are deliberately deferred (simulator crash-timing is too flaky to ship as an
+  unvalidated deterministic check).
+
+## [1.11.0] - 2026-07-02
+
+Roadmap #3: **rejection-outcome feedback loop** — a third, honestly-scoped measurement
+axis. Reporting layer only; the scan and GREEN/YELLOW/RED verdict are untouched.
+
+Alongside the synthetic and real-panel corpora, the tool now tracks **real App Store
+review outcomes** (approved / rejected + Apple's cited guideline) in a committed,
+human-reviewed ledger (`corpus/outcomes/ledger.json`, starts empty) and summarizes them
+in `docs/scorecard.md`. The summary is **honesty-floored**: below 10 recorded outcomes
+it shows only a raw tally and computes **no rate**; at/above the floor it may show a
+directional recall estimate with a permanent survivorship-bias caveat. Because the
+ledger is committed and read offline, the section is deterministic and covered by the
+existing `scorecard.sh --check` — no network, no new CI job.
+
+### Added
+- **`corpus/outcomes/ledger.json`** (empty `[]`) + **`corpus/outcomes/README.md`** —
+  record schema, anonymization/privacy rules (no verbatim Apple text, no real identity),
+  contribution/review process, and the sample-size floor.
+- **`scripts/scorecard-outcomes.sh`** — pure `bash`+`jq`, offline, deterministic; renders
+  the "Real App Store outcomes (n=N)" section with the honesty floor. Also
+  `scorecard.sh --outcomes`.
+- The outcomes section is baked into `docs/scorecard.md`; Methodology now describes three
+  measurements.
+- **`.github/ISSUE_TEMPLATE/app-store-outcome.md`** — anonymized outcome contribution that
+  funnels into a maintainer-reviewed PR.
+- Test: `tests/test-scorecard-outcomes.sh`.
+
+### Notes
+- Reporting/measurement only — outcome data never influences the verdict or which rules
+  fire (a future, human-only decision). No verbatim Apple Resolution Center text is stored.
+  The scan path (`scan.sh`/`verdict.sh`/`bin/cli.js`/`action.yml`) is unchanged.
+
 ## [1.10.0] - 2026-07-02
 
 Roadmap #4: **SARIF output + opt-in GitHub PR annotations** — read-only, no auto-fix.

package/README.md

@@ -468,8 +468,10 @@ CI runs ShellCheck, JSON validation, the version-consistency guard, and the fixt
 
 This is a static heuristic tool plus Pierre's semantic deep review. A GREEN result **lowers but does
 not eliminate** rejection risk; Apple's guidelines change frequently and reviewer decisions are
-judgment calls. `REVIEW-FINDING` lines are advisory and do not block the token by themselves. It
-performs no runtime crash testing; always do a final manual review before you submit. Not affiliated
+judgment calls. `REVIEW-FINDING` lines are advisory and do not block the token by themselves. The
+default flow performs no runtime crash testing; an optional, opt-in local simulator tier
+(Maestro and `xcrun simctl`) adds a pre-submit smoke signal but is not a TestFlight / crash-reporter
+/ QA replacement. Always do a final manual review before you submit. Not affiliated
 with Apple.
 
 ## Star History

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-precheck",
-  "version": "1.10.0",
+  "version": "1.12.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)",

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.10.0
+  version: 1.12.0
 allowed-tools: Bash Read Grep Glob WebFetch
 ---
 
@@ -92,7 +92,7 @@ Rules:
   **English** (Français + user lang, or just Français if they asked in French).
 - Keep each one-liner short (one sentence). Vary wording each run; stay in Pierre's dry critic voice.
 
-## Flow (6 phases: 0–5)
+## Flow (Phases 0–5; plus an optional opt-in Phase 6)
 
 ### Phase 0: Live guideline drift check
 
@@ -314,9 +314,27 @@ narrative; verdict.sh just pins the threshold arithmetic. `REVIEW-FINDING` lines
 7. Print the final manual checklist (see
    [`references/methodology.md`](references/methodology.md#pre-submit-manual-checklist)).
 
+### Phase 6: local dynamic simulator tier (optional, opt-in — off by default)
+
+**This phase does not run by default.** Run it ONLY when the user explicitly asks for a dynamic /
+simulator check AND supplies a built app (a simulator `.app` path, or a booted simulator UDID +
+bundle id). It uses `xcrun simctl` + Maestro MCP tools (`mcp__maestro__*`) to launch the app on a
+disposable simulator and observe real behavior — the free/local alternative to a paid cloud device
+farm.
+
+It emits advisory `DYNAMIC-PASS:` / `DYNAMIC-FINDING:` lines and **never changes the
+GREEN/YELLOW/RED verdict** (the verdict stays derived only from Phases 0–2). It is read-only w.r.t.
+the user's project — it touches only disposable simulator state, never the repo. It requires macOS +
+Xcode + a simulator runtime and is permanently local-only (it cannot run in CI). It is a pre-submit
+local smoke signal, not a TestFlight / crash-reporter / QA replacement.
+
+Follow [`references/simulator-dynamic-review.md`](references/simulator-dynamic-review.md) for the
+6-check dynamic checklist and output format.
+
 ## Rules
 
-- **READ-ONLY:** never change code or assets. Only report and write the token.
+- **READ-ONLY:** never change code or assets. Only report and write the token. (The optional Phase 6
+  simulator tier touches disposable simulator state only — never the user's project.)
 - **Speed > exhaustiveness:** `scan.sh` uses parallel grep/jq and finishes in seconds.
 - **No error swallowing:** if any scan command fails, that line is reported as FAIL and the scan continues.
 - **Token location:** `.precheck-pass` at the repo root; the guard tests it with an `mmin -60` filter.
@@ -324,7 +342,9 @@ narrative; verdict.sh just pins the threshold arithmetic. `REVIEW-FINDING` lines
 
 ## Known limits
 
-- No runtime crash testing; that's TestFlight + a crash reporter. Static analysis only.
+- The default flow is static analysis only. Runtime crash/behavior testing is available as an
+  optional, opt-in local simulator tier (Phase 6, `references/simulator-dynamic-review.md`); it is a
+  pre-submit local smoke signal, not a TestFlight / crash-reporter replacement.
 - Several checks are advisory WARNs gated on detected signals (Sign in with Apple 4.8,
   external-purchase 3.1.1(a), tracking/IDFA without ATT, analytics vs privacy manifest, metadata
   URLs and placeholder copy). The export-compliance key is flagged when absent, but the actual

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

@@ -12,6 +12,7 @@ whole file to run the skill.
 - [Auto-detection rules](#auto-detection-rules)
 - [Verdict thresholds](#verdict-thresholds)
 - [SARIF output](#sarif-output---format-sarif)
+- [Real App Store outcomes](#real-app-store-outcomes-corpusoutcomes)
 - [Pre-submit manual checklist](#pre-submit-manual-checklist)
 
 ---
@@ -234,6 +235,30 @@ emits inline `::error`/`::warning` annotations, both opt-in.
 
 ---
 
+### Real App Store outcomes (`corpus/outcomes/`)
+
+Beyond the synthetic and real-panel corpora, the tool tracks real Apple review outcomes (approved /
+rejected + cited guideline) in a committed, human-reviewed ledger (`corpus/outcomes/ledger.json`),
+summarized in `docs/scorecard.md` by `scripts/scorecard-outcomes.sh`. It is honesty-floored: no rate
+is computed below 10 records (raw tally only), and a permanent survivorship-bias caveat applies once
+a rate is shown. It is a reporting layer only — it never influences the GREEN/YELLOW/RED verdict or
+which rules fire. Contribute an outcome via the "App Store outcome" issue template.
+
+---
+
+### Optional local dynamic simulator tier
+
+Beyond the static scan and the agent-mode deep reviews, an **opt-in** local dynamic tier
+(`references/simulator-dynamic-review.md`, SKILL.md Phase 6) can run the app on a simulator
+(`xcrun simctl` + Maestro MCP) and emit advisory `DYNAMIC-PASS:` / `DYNAMIC-FINDING:` observations —
+launch/crash, paywall render, permission prompt vs purpose string, demo-login path, live UI vs
+marketing screenshots. It is off by default, never changes the verdict, is read-only w.r.t. the
+user's project (touches disposable simulator state only), and is permanently local-only (it cannot
+run in CI). It is a pre-submit local smoke signal, not a TestFlight / crash-reporter / QA
+replacement.
+
+---
+
 ## Pre-submit manual checklist
 
 Things the scanner cannot verify; confirm by hand before you submit:

package/skills/appstore-precheck/references/simulator-dynamic-review.md

@@ -0,0 +1,88 @@
+# Local dynamic simulator tier (agent-mode, opt-in, non-blocking)
+
+The fourth, opt-in tier: a **local dynamic** review that runs the app on a simulator and observes
+real behavior — the class of checks a static scan cannot make (does it launch without crashing, does
+the paywall actually render, does a permission prompt match its purpose string, does a demo login
+work, does the live UI match the marketing screenshots). It is the free/local alternative to a paid
+cloud device farm, built from `xcrun simctl` + Maestro MCP tools (`mcp__maestro__*`) already
+available on a Mac with Xcode.
+
+**Identity:** runs ONLY in agent-skill mode, ONLY when the user explicitly asks for it and supplies a
+built app (or a booted simulator UDID + bundle id). It is NOT part of the offline CLI / npx /
+GitHub-Action scan, and it never runs by default. Requires macOS + Xcode + a simulator runtime; it
+cannot run in this project's `ubuntu-latest` CI and is permanently local-only.
+
+**This tier never changes the verdict.** GREEN/YELLOW/RED comes only from the static scan counts
+(Phases 0–2). This tier emits advisory `DYNAMIC-PASS:` / `DYNAMIC-FINDING:` lines, like Pierre
+deep-review's `REVIEW-*` lines.
+
+**Read-only:** read-only w.r.t. the user's project — the tier installs/launches onto a **disposable
+simulator** only and never modifies the user's repo. Prefer a dedicated/disposable simulator device;
+do not disturb the user's everyday simulator state; leave teardown to the user unless the tier
+created the device itself.
+
+**Not a guarantee:** a pre-submit local smoke signal — NOT a replacement for TestFlight, a crash
+reporter, or real-device QA.
+
+## Rules
+
+- Advisory only: every check reports `DYNAMIC-PASS:` or `DYNAMIC-FINDING:` — never `FAIL`, never a
+  verdict contribution.
+- Evidence-based: cite a screenshot filename + what was observed. If a check cannot be driven (no
+  paywall in this app, a UI selector can't be found, no permissions declared), report
+  `DYNAMIC-PASS: … — not applicable` or `DYNAMIC-FINDING: … could not verify` — never invent a
+  failure.
+- All 6 checks, every run: report each as PASS / FINDING / not-applicable.
+- Boot a disposable simulator, launch the supplied app, and tear down cleanly.
+- Write Pierre's 2–3 sentence explanations in the user's conversation language.
+
+## The 6 checks
+
+| # | Guideline | Dynamic question |
+|---|-----------|------------------|
+| D1 | **2.1** | Does the app launch on a fresh simulator and stay foregrounded briefly without crashing / a crash alert? |
+| D2 | **2.1** | Does it reach a real first screen (not stuck on a splash, a blank screen, or an error alert)? |
+| D3 | **3.1.2** | If a paywall/subscription exists, does it render with price + trial/auto-renew/terms visible on-screen (not just present as strings)? |
+| D4 | **5.1.1(ii)/(iii)** | For each permission with an `Info.plist` purpose string, does the OS prompt appear at the right moment and match the declared string? |
+| D5 | **2.1** | For a login-gated app, is there a reachable guest/demo path, or do the declared review demo credentials actually log in? |
+| D6 | **2.3.5** | Do live screenshots of key screens match the submitted marketing screenshots (features shown match the running build)? |
+
+## Per-check procedure
+
+### D1 — Launch without crash
+1. `mcp__maestro__start_device` (or `xcrun simctl boot`) a disposable simulator; `launch_app` the supplied app/bundle id.
+2. Observe for a short window; if the app process disappears or a crash alert shows, `DYNAMIC-FINDING`.
+3. `take_screenshot` at launch as evidence.
+
+### D2 — Core screen reachable
+1. After launch, inspect the first real screen (`inspect_view_hierarchy` / `take_screenshot`).
+2. Flag if stuck on a splash, blank, or an error/"something went wrong" state.
+
+### D3 — Paywall renders
+1. If a paywall exists (per the static scan / app structure), navigate to it (`tap_on` / a flow).
+2. Confirm price + trial/auto-renew/cancel terms are visibly rendered; screenshot. Not applicable if no paywall.
+
+### D4 — Permission prompt vs purpose string
+1. For each `NS*UsageDescription` in `Info.plist`, trigger the feature that requests it.
+2. Confirm the OS prompt appears at the right moment and its text matches the declared purpose string; screenshot.
+
+### D5 — Demo / login path
+1. For a login-gated app, look for a guest/demo entry, or enter the declared review demo credentials.
+2. Confirm a reachable path to core features; `DYNAMIC-FINDING` if the only path is a wall with no working demo.
+
+### D6 — Live UI vs marketing screenshots
+1. Capture live screenshots of key screens.
+2. Compare to the submitted marketing screenshots; flag features shown in marketing but absent in the running build.
+
+## Output format
+
+```
+DYNAMIC-PASS: <guideline> — <one-line why it looks OK, with screenshot filename>
+```
+or
+```
+DYNAMIC-FINDING: <guideline> — <one-line concrete issue, with screenshot filename>
+Pierre: <2–3 sentences: why Apple cares, what you saw, what to fix or verify>
+```
+
+End with a summary table: 6 checks → count of `DYNAMIC-FINDING` vs `DYNAMIC-PASS` (note any not-applicable).