appstore-precheck 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here. Versioning follows
+[SemVer](https://semver.org/). Released as git tags.
+
+## [1.1.0] - 2026-06-28
+
+### Added
+- `npx appstore-precheck` CLI (`bin/cli.js`): run the static scan with no clone and no install.
+  It scans the current directory (or `--dir <path>`), prints the scan output and the verdict
+  verbatim, and exits non-zero on RED (or on YELLOW with `--fail-on YELLOW`), mirroring the
+  GitHub Action. A thin wrapper over the bundled `scan.sh` / `verdict.sh`; it adds no new checks.
+- Published to npm under the package name `appstore-precheck`.
+- `tests/test-cli.sh`: covers the CLI's verdict mapping and exit codes (GREEN/RED/YELLOW,
+  `--fail-on`, `--version`, `--help`, bad-usage), wired into the suite and `npm run lint`.
+
+## [1.0.0] - 2026-06-28
+
+Initial release.
+
+### Added
+- `appstore-precheck` Agent Skill: read-only iOS App Store pre-submission gate.
+- `scripts/scan.sh`: portable Bash scanner for 20 rejection vectors (including advisory Sign in
+  with Apple parity and external-purchase-link checks) with zero-config
+  auto-detection of a standard fastlane + Xcode layout, plus `.appstore-precheck.json` overrides.
+- Five more signal-gated advisory checks (15 → 20): tracking/IDFA SDK shipped without an ATT
+  prompt (5.1.2, the reverse of the existing ATT check), the export-compliance key
+  (`ITSAppUsesNonExemptEncryption`), support/privacy URL presence in fastlane metadata (2.3),
+  analytics SDK vs `PrivacyInfo.xcprivacy` data-type declarations (5.1.1), and placeholder/dummy
+  copy in store metadata (2.1). All WARN-only, with a `tracking-app` fixture that exercises them.
+- `scripts/verdict.sh`: deterministic GREEN/YELLOW/RED verdict and `.precheck-pass` token
+  action from the scan output, so the verdict is machine-testable, not just an agent judgement.
+- 5-phase flow: guideline-drift check, static scan, Apple `fastlane precheck` wrapper,
+  adversarial reviewer pass, consolidation + `.precheck-pass` token.
+- Optional Claude Code upload-guard hook (`hooks/fastlane-guard.sh`) that blocks
+  `fastlane deliver/pilot/release` without a fresh token.
+- Cross-tool support: native `SKILL.md` for Claude Code / Codex / Cursor / Gemini CLI,
+  root `AGENTS.md`, and an `install.sh` multi-host installer. Claude Code and Codex CLI runs
+  verified end-to-end (`docs/cross-tool-verification.md`).
+- Claude Code plugin + single-plugin marketplace manifests.
+- Test suite (`tests/`): fixture scans plus unit tests for verdict thresholds, the upload-guard
+  hook, config overrides, and the installer. CI runs ShellCheck, JSON validation, a
+  version-consistency guard, and the full suite on every push and PR.
+- Documentation: methodology reference, a how-to-add-a-check guide, an agent-portability note,
+  real Phase 0 drift-check and Phase 2 `fastlane precheck` examples, and a field-test report
+  from dogfooding real App Store apps (`docs/`).
+- Community health files: contributing guide, security policy, code of conduct, and issue/PR
+  templates.
+- Behavioral eval suite (`skills/appstore-precheck/evals/`) in the Agent Skills format: RED /
+  GREEN / no-IAP cases with self-contained inputs and assertions.
+- Branding: logo, social preview, and **Pierre**, the French App Review critic mascot whose
+  voice drives the Phase 3 adversarial review.
+
+### Fixed
+- More reliable app-target auto-detection: resolve the iOS source dir via the app entry point
+  (`@main` / `AppDelegate`), not Info.plist position alone, so a Watch app, extension, or
+  framework is no longer mistaken for the main target. Required-link checks now scan the whole
+  paywall cluster instead of a single auto-picked file. (Found by dogfooding Pocket Casts,
+  Wikipedia, and DuckDuckGo.)
+- Portable empty-array handling under `set -u` on stock macOS bash 3.2 and modern bash.

package/LICENSE

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

package/README.md

@@ -0,0 +1,219 @@
+<p align="center">
+  <img src="assets/social-preview.png" width="840" alt="appstore-precheck, a French critic reviews your build before Apple does">
+</p>
+
+<p align="center">
+  <a href="https://github.com/berkayturk/appstore-precheck/actions/workflows/ci.yml"><img src="https://github.com/berkayturk/appstore-precheck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/platform-iOS-lightgrey.svg" alt="Platform: iOS">
+  <img src="https://img.shields.io/badge/Agent%20Skill-open%20standard-1F6FEB.svg" alt="Agent Skill">
+  <img src="https://img.shields.io/badge/works%20with-Claude%20Code%20·%20Codex%20·%20Cursor%20·%20Gemini-2563EB.svg" alt="Works with Claude Code, Codex, Cursor, Gemini">
+</p>
+
+<p align="center"><strong>Catch App Store rejections before a reviewer does.</strong></p>
+
+---
+
+`appstore-precheck` is a read-only, pre-submission gate for iOS apps. It statically scans the most
+common rejection vectors, runs Apple's own metadata linter, watches the App Store Review Guidelines
+for drift, and finishes with an adversarial review pass, then hands you a single **GREEN / YELLOW /
+RED** verdict. It never edits your code.
+
+It ships as a portable [Agent Skill](https://agentskills.io): the same `SKILL.md` runs natively in
+Claude Code, OpenAI Codex, Cursor, and Gemini CLI. The scanner is plain Bash, so you can also run it
+by hand or wire it into CI.
+
+## Meet Pierre
+
+<img src="assets/mascot.png" align="right" width="124" alt="Pierre, the French app reviewer">
+
+Your verdict is delivered by **Pierre**, a French critic who has seen ten thousand rejections and is
+impressed by none of them. He reviews your build harder than Apple would, in private. A GREEN from
+Pierre means Apple will wave you through.
+
+- 🔴 **RED**: *"Non. Restore Purchases, absent. Guideline 3.1.2. Suivant."*
+- 🟡 **YELLOW**: *"A few small uglinesses. I would not reject. But I noticed."*
+- 🟢 **GREEN**: *"Hmf. I find nothing. Acceptable. Do not make me regret this."*
+
+The verdict line is in Pierre's voice. The breakdown beneath it, every `file:line` and fix, stays
+plain and surgical.
+
+## What it checks
+
+20 rejection vectors across code, fastlane metadata, screenshots, `PrivacyInfo.xcprivacy`, and the paywall:
+
+| Guideline | Check |
+|-----------|-------|
+| **5.1.1(v)** | Privacy Manifest ↔ Required Reason API parity |
+| **5.1.1** | A non-empty purpose string for every sensitive framework |
+| **5.1.2** | ATT usage ↔ `NSUserTrackingUsageDescription` |
+| **2.3.10** | No other-platform / competitor names in metadata |
+| **2.3.1** | Metadata length limits (name, subtitle, keywords, promo, description) |
+| **2.3.7** | Localized metadata parity across every locale |
+| **2.3.3** | At least one screenshot per locale |
+| **3.1.2** | Trial & auto-renew subscription disclosures |
+| **3.1.2** | Restore Purchases + Terms (EULA) + Privacy Policy on the paywall |
+| **2.5.1** | No private / banned APIs |
+| **4.0** | Minimum functionality (real navigation) |
+| **4.8** | Sign in with Apple offered when a third-party social login is used |
+| **3.1.1(a)** | External purchase link entitlement + disclosure, when external purchase APIs are used |
+| **5.1.5** | Sensitive-API justification *(opt-in)* |
+| **5.1.2** | Tracking / IDFA SDK (AdMob, AppLovin, AppsFlyer, Adjust, …) shipped without an ATT prompt |
+| **encryption** | `ITSAppUsesNonExemptEncryption` set, so App Store Connect skips the export-compliance question |
+| **2.3** | A working support URL and a privacy URL in fastlane metadata (no placeholders) |
+| **5.1.1** | Analytics SDK present ↔ `PrivacyInfo.xcprivacy` declares collected data / tracking domains |
+| **2.1** | No placeholder / dummy copy (lorem ipsum, TODO, `example.com`) in store metadata |
+
+Paywall checks are skipped automatically when no in-app-purchase signals are present.
+
+## Quick start
+
+**Claude Code**: install as a plugin:
+
+```
+/plugin marketplace add berkayturk/appstore-precheck
+/plugin install appstore-precheck@appstore-precheck
+```
+
+**Run instantly with npx** (no clone, no install):
+
+```bash
+npx appstore-precheck            # scans the current directory, prints the verdict
+npx appstore-precheck --fail-on YELLOW
+```
+
+It runs the static scan over the current directory and exits non-zero on RED (or on YELLOW with
+`--fail-on YELLOW`). Read-only, like everything else here.
+
+**Codex, Cursor, Gemini, Claude**: clone, then run the installer from inside your iOS project:
+
+```bash
+git clone https://github.com/berkayturk/appstore-precheck.git
+/path/to/appstore-precheck/install.sh        # → ./.claude/skills and ./.agents/skills
+```
+
+**Standalone**: the scanner is just Bash:
+
+```bash
+bash skills/appstore-precheck/scripts/scan.sh
+```
+
+**CI**: drop the static scan into a workflow with the bundled composite action. It fails the
+job on a RED verdict; set `fail-on: YELLOW` to be stricter:
+
+```yaml
+- uses: berkayturk/appstore-precheck@v1.0.0
+  with:
+    working-directory: .   # optional
+    fail-on: RED           # optional (RED | YELLOW)
+```
+
+## How it works
+
+| Phase | Step |
+|-------|------|
+| **0** | **Guideline drift**: diff the live App Store Review Guidelines against a tracked baseline. Never blocks. |
+| **1** | **Static scan**: `scan.sh` over the 20 vectors above. |
+| **2** | **`fastlane precheck`**: Apple's own metadata rule engine. |
+| **3** | **Adversarial review**: Pierre role-plays a skeptical reviewer and drafts realistic rejection notices. |
+| **4** | **Verdict**: GREEN / YELLOW / RED, and a `.precheck-pass` token the upload guard gates on. |
+
+## Demo
+
+<p align="center">
+  <img src="assets/demo.gif" width="760" alt="appstore-precheck running: a clean app passes GREEN, an app with rejection vectors is blocked RED">
+</p>
+
+A clean app passes **GREEN**; an app with rejection vectors is blocked **RED**. The verdict and
+counts are deterministic ([`verdict.sh`](skills/appstore-precheck/scripts/verdict.sh)).
+
+## Example
+
+```
+🔴 Pierre: "Non. Three faults. Apple would have found one. Suivant."
+
+RED: 3 FAIL
+• 3.1.2 Restore Purchases missing    SubscriptionView.swift:14 → add restorePurchases()
+• 2.3.10 "Android" in metadata        en-US/description.txt:1 → remove the reference
+• 5.1.1(v) FileTimestamp undeclared   PrivacyInfo.xcprivacy → declare the reason
+Submission blocked.
+```
+
+See [`examples/`](examples/) for full [GREEN](examples/green-pass.md) and [RED](examples/red-reject.md) runs,
+plus real [Phase 0 drift-check](examples/drift-check.md) and [Phase 2 `fastlane precheck`](examples/fastlane-precheck.md) results.
+
+## Output
+
+| State | Meaning | Token | Upload guard |
+|-------|---------|-------|--------------|
+| 🟢 **GREEN** | 0 FAIL, ≤2 WARN | written (60 min) | allowed |
+| 🟡 **YELLOW** | 0 FAIL, 3+ WARN | not written | blocked; needs confirmation |
+| 🔴 **RED** | ≥1 FAIL | removed | blocked; shows the FAIL list |
+
+## Configuration
+
+Zero config for a standard fastlane + Xcode layout. The scanner auto-detects your source directory,
+fastlane metadata, screenshots, String Catalog, paywall view, and locales. Override any of it with a
+`.appstore-precheck.json` at your repo root (copy
+[`config.example.json`](skills/appstore-precheck/config.example.json)).
+
+## Cross-tool support
+
+`SKILL.md` follows the [Agent Skills open standard](https://agentskills.io), with no per-tool conversion.
+Hosts differ only in the directory they scan:
+
+| Host | Reads from |
+|------|-----------|
+| Claude Code | `.claude/skills/` · `~/.claude/skills/` |
+| OpenAI Codex | `.agents/skills/` · `~/.agents/skills/` |
+| Cursor | `.agents/skills/`, `.cursor/skills/`, also `.claude/skills/` |
+| Gemini CLI | `.agents/skills/`, `.gemini/skills/` |
+
+A root [`AGENTS.md`](AGENTS.md) covers hosts that read always-on context instead of on-demand skills.
+[`docs/cross-tool-verification.md`](docs/cross-tool-verification.md) records real per-host runs
+(all four hosts verified end-to-end: Claude Code, Codex, Gemini, and Cursor), and
+[`docs/field-tests.md`](docs/field-tests.md) records dogfooding the scanner against real
+App Store apps (DuckDuckGo, Pocket Casts, Wikipedia).
+
+## Requirements
+
+`bash`, `git`, `grep`, `find` · `jq` (config + String Catalog checks) · `python3` (exact Unicode
+length counts) · `fastlane` + an App Store Connect API key for Phase 2 only.
+
+**Secrets**: the ASC API key is read from your environment at runtime and deleted immediately after
+`fastlane precheck`. Never commit it; `.gitignore` blocks `*asc-key*.json` and `.env`.
+
+## Uninstall
+
+```bash
+/plugin uninstall appstore-precheck@appstore-precheck                        # Claude Code plugin
+rm -rf .claude/skills/appstore-precheck .agents/skills/appstore-precheck     # manual install
+rm -f .precheck-pass                                                         # runtime token
+```
+
+## Development
+
+```bash
+npm run lint            # bash -n on every script
+npm run check-versions  # plugin.json / package.json / SKILL.md in lockstep
+npm test                # run scan.sh against fixture projects and assert
+claude plugin validate .
+```
+
+CI runs ShellCheck, JSON validation, the version-consistency guard, and the fixture tests on every push.
+
+## Disclaimer
+
+This is a static heuristic tool. A GREEN result **lowers but does not eliminate** rejection risk;
+Apple's guidelines change frequently and reviewer decisions are judgment calls. It performs no runtime
+crash testing; always do a final manual review before you submit. Not affiliated with Apple.
+
+## Star History
+
+<a href="https://star-history.com/#berkayturk/appstore-precheck&Date">
+  <img src="https://api.star-history.com/svg?repos=berkayturk/appstore-precheck&type=Date" alt="Star History Chart" width="600">
+</a>
+
+## License
+
+[MIT](LICENSE) © Berkay Turk

package/bin/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+// appstore-precheck CLI: a thin Node wrapper so the scanner runs with no clone,
+// via `npx appstore-precheck`. It shells out to the bundled scan.sh + verdict.sh,
+// prints their output verbatim, and maps the verdict to an exit code (mirroring
+// the GitHub Action). It does not reimplement any check; the Bash scripts are the
+// single source of truth.
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SCAN = path.join(PKG_ROOT, 'skills', 'appstore-precheck', 'scripts', 'scan.sh');
+const VERDICT = path.join(PKG_ROOT, 'skills', 'appstore-precheck', 'scripts', 'verdict.sh');
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+function printHelp() {
+  process.stdout.write(
+    `appstore-precheck ${pkgVersion()} - read-only iOS App Store pre-submission scan\n` +
+    `\n` +
+    `Usage:\n` +
+    `  npx appstore-precheck [options]\n` +
+    `\n` +
+    `Runs the static scanner over the current directory and prints a\n` +
+    `GREEN / YELLOW / RED verdict. Read-only: it never edits your files.\n` +
+    `\n` +
+    `Options:\n` +
+    `  --dir <path>        Directory to scan (default: current directory)\n` +
+    `  --fail-on <level>   Exit non-zero at RED (default) or YELLOW\n` +
+    `  -v, --version       Print the version and exit\n` +
+    `  -h, --help          Show this help and exit\n` +
+    `\n` +
+    `Exit codes: 0 ok, 1 verdict at or past --fail-on, 64 bad usage,\n` +
+    `70 environment error (bash or scanner not available).\n` +
+    `\n` +
+    `Requires bash, git, grep, and find on PATH (macOS / Linux; on Windows\n` +
+    `use WSL or Git Bash). jq and python3 unlock the config + exact-length checks.\n`
+  );
+}
+
+function fail(message, code) {
+  process.stderr.write(`appstore-precheck: ${message}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const opts = { dir: process.cwd(), failOn: 'RED' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { printHelp(); process.exit(0); }
+    if (a === '-v' || a === '--version') { process.stdout.write(pkgVersion() + '\n'); process.exit(0); }
+    if (a === '--dir') {
+      opts.dir = argv[++i];
+      if (!opts.dir) fail('--dir requires a path', 64);
+      continue;
+    }
+    if (a === '--fail-on') {
+      const v = (argv[++i] || '').toUpperCase();
+      if (v !== 'RED' && v !== 'YELLOW') fail('--fail-on must be RED or YELLOW', 64);
+      opts.failOn = v;
+      continue;
+    }
+    fail(`unknown option: ${a} (try --help)`, 64);
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (!fs.existsSync(SCAN) || !fs.existsSync(VERDICT)) {
+    fail('bundled scanner scripts are missing from the package', 70);
+  }
+  if (!fs.existsSync(opts.dir) || !fs.statSync(opts.dir).isDirectory()) {
+    fail(`not a directory: ${opts.dir}`, 64);
+  }
+
+  const scan = spawnSync('bash', [SCAN], {
+    cwd: opts.dir,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (scan.error && scan.error.code === 'ENOENT') {
+    fail('bash is required to run the scanner (install bash, or use WSL / Git Bash on Windows)', 70);
+  }
+  if (scan.error) fail(`failed to run the scanner: ${scan.error.message}`, 70);
+
+  const scanOut = scan.stdout || '';
+  process.stdout.write(scanOut);
+
+  const verdict = spawnSync('bash', [VERDICT], { input: scanOut, encoding: 'utf8' });
+  if (verdict.error) fail(`failed to compute the verdict: ${verdict.error.message}`, 70);
+  const summary = verdict.stdout || '';
+
+  process.stdout.write('----------------------------------------\n');
+  process.stdout.write(summary.endsWith('\n') ? summary : summary + '\n');
+
+  const m = summary.match(/^VERDICT:\s*(\w+)/m);
+  const v = m ? m[1] : 'UNKNOWN';
+
+  let code = 0;
+  if (opts.failOn === 'YELLOW') {
+    code = v === 'GREEN' ? 0 : 1;
+  } else {
+    code = v === 'RED' ? 1 : 0;
+  }
+  process.exit(code);
+}
+
+main();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "appstore-precheck",
+  "version": "1.1.0",
+  "description": "Read-only iOS App Store pre-submission check, packaged as a portable Agent Skill / Claude Code plugin and an npx CLI.",
+  "license": "MIT",
+  "author": "Berkay Turk (https://github.com/berkayturk)",
+  "homepage": "https://github.com/berkayturk/appstore-precheck",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/berkayturk/appstore-precheck.git"
+  },
+  "bin": {
+    "appstore-precheck": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/appstore-precheck/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "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"
+  },
+  "keywords": ["ios", "app-store", "fastlane", "agent-skill", "claude-code", "precheck"]
+}

package/skills/appstore-precheck/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: appstore-precheck
+description: Read-only pre-submission check for an iOS app before App Store review. Scans Swift code, fastlane metadata, screenshots, PrivacyInfo.xcprivacy, and the paywall for 20 rejection vectors, wraps Apple's official `fastlane precheck`, watches for live App Store Review Guideline drift, and runs an adversarial reviewer pass. Emits a GREEN/YELLOW/RED verdict and a `.precheck-pass` token an upload guard can gate on. Use when preparing an iOS App Store submission (before Archive, before "Submit for Review", before TestFlight, or before any `fastlane deliver/pilot/release`), or when the user mentions App Store rejection, app review, or fastlane upload.
+license: MIT
+metadata:
+  author: Berkay Turk
+  version: 1.1.0
+allowed-tools: Bash Read Grep Glob WebFetch
+---
+
+# App Store Precheck
+
+A one-command gate to run before every iOS App Store submission. It minimizes the risk of
+rejection by statically scanning the most common rejection vectors, running Apple's own
+metadata linter, watching for guideline drift, and simulating an adversarial review pass.
+
+**This skill is read-only.** It never edits code, metadata, or assets. It only reports and
+writes a pass token. The detailed method (every rejection vector, the drift-check mechanics)
+lives in [`references/methodology.md`](references/methodology.md); read it when you need the
+specifics behind a check.
+
+## When to run
+
+- **Before** archiving for TestFlight.
+- **Before** pressing "Submit for Review" in App Store Connect.
+- **Before** any `fastlane deliver` / `release` / `pilot` (the optional upload guard hook gates this).
+- On every point release.
+
+Run it deliberately. This is a human-triggered gate, not an automatic background step.
+
+## Configuration (optional)
+
+The scanner auto-detects a standard fastlane + Xcode layout, so most projects need **zero
+configuration**. To override detection, copy [`config.example.json`](config.example.json) to
+`.appstore-precheck.json` at the repo root. Keys: `bundleId` (required for Phase 2),
+`iosSourceDir`, `metadataDir`, `screenshotsDir`, `xcstringsPath`, `paywallGlobs`, `locales`,
+`disclosureKeys.{subscription,trial}`, `optionalChecks.familyControls`, `reviewPrepNotes`.
+See `config.example.json` for the full annotated list.
+
+## Output contract
+
+The skill reaches one of three terminal states:
+
+| State | Meaning | `.precheck-pass` token | Guard behavior |
+|-------|---------|------------------------|----------------|
+| **GREEN** | No FAIL, ≤2 WARN | Written (valid 60 min) | Upload allowed |
+| **YELLOW** | No FAIL but 3+ WARN | Not written | Guard blocks; ask for explicit confirmation |
+| **RED** | At least 1 FAIL | Removed | Guard blocks; show the FAIL list |
+
+When you present the verdict to the user, open with a **single in-character line from Pierre**
+(the French App Review critic, see Phase 3), then drop straight into the plain, surgical
+breakdown. The voice is a thin wrapper. The data underneath, the FAIL/WARN list, `file:line`
+references, and fixes, stays clean and machine-faithful. **Never rewrite or paraphrase
+`scan.sh` output**, and keep Pierre to one line.
+
+## Flow (5 phases: 0–4)
+
+### Phase 0: Live guideline drift check
+
+Diff the live [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/)
+section numbers against `guidelines-baseline.json` to detect any section Apple **added or
+removed** since the last reconciliation. **Always non-blocking (WARN at most).** Drift is a gap
+in *our* coverage, never a fault of the build. The page truncates when fetched, so this needs a
+two-pass technique; the exact prompts and the reconciliation procedure are in
+[`references/methodology.md`](references/methodology.md#phase-0-guideline-drift-check). The
+baseline is **never auto-updated**. Reconciliation is a deliberate human step.
+
+### Phase 1: Static scan
+
+```bash
+bash skills/appstore-precheck/scripts/scan.sh
+```
+
+Emits `FAIL:` / `WARN:` / `PASS:` lines covering 20 rejection vectors: Privacy Manifest parity
+(5.1.1(v)), purpose strings (5.1.1), ATT (5.1.2), other-platform mentions (2.3.10), metadata
+limits (2.3.1), localized parity (2.3.7), screenshots (2.3.3), trial & auto-renew disclosures
+(3.1.2), Restore/Terms/Privacy links (3.1.2), private API (2.5.1), minimum functionality (4.0),
+Sign in with Apple parity (4.8), external purchase links (3.1.1(a)), an opt-in Screen Time /
+FamilyControls justification (5.1.5), tracking/IDFA SDK without an ATT prompt (5.1.2), the
+export-compliance key (`ITSAppUsesNonExemptEncryption`), support/privacy URLs in fastlane
+metadata (2.3), analytics SDK vs PrivacyInfo data-types (5.1.1), and placeholder/dummy metadata
+copy (2.1). The IAP checks (8–10) are
+skipped automatically when no in-app-purchase signals are present. The full check table is in
+[`references/methodology.md`](references/methodology.md#phase-1-rejection-vectors).
+
+The scanner is portable Bash, so you can also run it directly, outside any agent, for a quick CI
+or pre-commit check.
+
+### Phase 2: Apple's official `fastlane precheck`
+
+Requires `bundleId` in config (or pass `app_identifier` directly) and App Store Connect API
+credentials. **Never commit the key.** The bundled wrapper builds the ASC API key JSON from your
+environment, runs precheck, and deletes the key on exit (use `--dry-run` to preview the command
+with no credentials and no network):
+
+```bash
+ASC_KEY_ID=… ASC_ISSUER_ID=… ASC_P8_PATH=/path/AuthKey.p8 \
+  bash skills/appstore-precheck/scripts/phase2-precheck.sh com.example.app
+```
+
+Or run it by hand: generate the key JSON from your environment, run precheck, then delete it.
+
+```bash
+fastlane run precheck \
+  app_identifier:"<YOUR_BUNDLE_ID>" \
+  api_key_path:"/tmp/asc-key.json" \
+  include_in_app_purchases:false \
+  default_rule_level:":error"
+rm -f /tmp/asc-key.json   # delete the secret immediately
+```
+
+Apple's own rule engine checks URLs, GitHub mentions, profanity, Apple trademarks, pricing
+language, and beta keywords. `Result: true` → PASS; any violation line → FAIL. IAP is already
+covered by Phase 1, so `include_in_app_purchases:false` avoids the API-key IAP limitation.
+
+### Phase 3: Adversarial review (most important)
+
+Dispatch a subagent that role-plays **Pierre**, a skeptical Apple App Reviewer with the exacting
+palate of a French critic. Use this prompt verbatim, filling in the app's specifics:
+
+> You are **Pierre**, a veteran Apple App Reviewer who critiques like a French critic. You have
+> seen ten thousand rejections and are impressed by none of them. A new submission just landed on
+> your desk. Your job is to **realistically try to reject it**, with no approval bias. Pick **5 random
+> guideline items** with a spread across sections (one 2.x, two 3.x weighted toward paywall,
+> one 4.x, one 5.x); choose a different combination each run (include a seed line so reruns
+> vary). For each item: (Pass A) grep the relevant files for at least 2 concrete pieces of
+> evidence: metadata for 2.3.x; the paywall view + String Catalog for 3.1.x; Core/navigation
+> for 4.x; Info.plist + PrivacyInfo for 5.1.x. (Pass B) ask "as a reviewer, on what basis would
+> I flag this?" (Pass C) write a rejection draft in Apple's real voice (Guideline X.Y.Z –
+> Category / We noticed… / Specifically… / Next Steps… / Resources…). Assign each item a risk:
+> REJECT-CERTAIN / REJECT-RISK / WARN / PASS. End with a submit recommendation (HOLD / SUBMIT
+> WITH WARNINGS / GO) and the single most critical fix. Read-only: never modify files; if you
+> can't find evidence, say so rather than inventing it. Keep it under 500 words. Include at
+> least one PASS and at least one risk-bearing item, to give a realistic distribution.
+
+### Phase 4: Consolidation + token
+
+The GREEN/YELLOW/RED decision and token action are **deterministic**, derived purely from the
+FAIL/WARN counts. [`scripts/verdict.sh`](scripts/verdict.sh) computes them so the verdict is
+machine-testable, not just an agent judgement; pipe the scan into it:
+
+```bash
+bash skills/appstore-precheck/scripts/verdict.sh < scan-output.txt   # prints VERDICT / COUNTS / TOKEN
+```
+
+It exits 0 GREEN / 1 RED / 2 YELLOW, and with `--apply` writes or removes `.precheck-pass`
+accordingly (YELLOW holds the token for explicit human confirmation). Phase 0–3 still produce the
+narrative; verdict.sh just pins the threshold arithmetic.
+
+1. Gather Phase 0–3 output; tally FAIL + WARN + PASS into the output-contract table.
+2. For each FAIL, give a `file:line` reference and a suggested fix.
+3. Open the verdict with **one** line in Pierre's voice (vary the wording each run; keep it short
+   and in his deadpan French-critic register), then drop into the plain breakdown. Decide:
+   - **GREEN:** Pierre, grudgingly: *"Hmf. I find nothing. Acceptable. Do not make me regret this."*
+     then `date +%s > .precheck-pass && echo "token written"` (valid 60 min).
+   - **YELLOW:** Pierre: *"A few small uglinesses. I would not reject, but I noticed."* List the
+     WARNs plainly, ask the user "confirm and submit anyway?", write the token only on confirmation.
+   - **RED:** Pierre: *"Non. {n} faults. Apple would have found fewer. Suivant."* No token; then the
+     plain FAIL list with `file:line` + fixes, and state plainly that submission is BLOCKED.
+   The Pierre line is flavor only. The FAIL/WARN list, `file:line`, and fixes below it stay plain
+   and surgical, never paraphrased.
+4. Print the final manual checklist (see
+   [`references/methodology.md`](references/methodology.md#pre-submit-manual-checklist)).
+
+## Rules
+
+- **READ-ONLY:** never change code or assets. Only report and write the token.
+- **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.
+- **Local-only:** designed for manual, local runs; keep it out of CI to avoid false signals.
+
+## Known limits
+
+- No runtime crash testing; that's TestFlight + a crash reporter. Static analysis only.
+- 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
+  encryption answer still belongs in App Store Connect.
+- The adversarial reviewer is a heuristic simulation, not a guarantee of Apple's decision.
+- iOS only. Android / Play Console is out of scope.
+- Phase 0 detects only **structural** drift (added/removed section numbers); see the reference for why.
+
+## Optional: upload guard hook
+
+`hooks/fastlane-guard.sh` blocks `fastlane deliver/pilot/release` unless a fresh `.precheck-pass`
+token exists. In Claude Code it auto-wires via `hooks/hooks.json`. In other environments, wire it
+as a pre-command check yourself, or treat the token as a manual go/no-go signal.

package/skills/appstore-precheck/config.example.json

@@ -0,0 +1,25 @@
+{
+  "_comment": "Copy to your repo root as .appstore-precheck.json. Every key is OPTIONAL; the scanner auto-detects a standard fastlane + Xcode layout. Use 'auto' or omit a key to keep auto-detection.",
+
+  "bundleId": "com.example.app",
+
+  "iosSourceDir": "auto",
+  "metadataDir": "auto",
+  "screenshotsDir": "auto",
+  "xcstringsPath": "auto",
+
+  "paywallGlobs": ["*ubscription*.swift", "*paywall*.swift", "*purchase*.swift"],
+
+  "locales": "auto",
+
+  "disclosureKeys": {
+    "subscription": "subscription_disclosure",
+    "trial": "subscription_trial_disclosure"
+  },
+
+  "optionalChecks": {
+    "familyControls": false
+  },
+
+  "reviewPrepNotes": ""
+}