@olegkoval/agent-skills 1.23.0 → 1.25.0

package/packages/software-development/pr-finalize/adapters/windsurf/rules/pr-finalize.md

@@ -0,0 +1,139 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
+---
+
+# PR Finalize
+
+One PR, taken all the way to merge-ready. The job is not "make the bots stop talking" — it is **land the change in a state a careful reviewer would sign off on**, with evidence for every claim.
+
+## Inputs
+
+- **PR number or URL** (optional): detect from the current branch if not given.
+- `--no-push` (optional): do everything except the final push. Use when the repo auto-merges and the user wants to eyeball first.
+
+## Non-negotiables
+
+These are the failure modes this skill exists to prevent. Violating one makes the whole run worthless:
+
+- **Never report a gate as passing without having run it.** Paste the real output. "Tests should pass" is not a result.
+- **Never resolve or claim-fix a finding you didn't actually fix.** Blocked is an honest outcome; a false "done" is not.
+- **Never `git add -A`.** Stage only the files your fixes touched. Start from a clean tree so that's safe.
+- **Never invent test coverage.** If the change has no browser-reachable surface, say so explicitly and name the suite that *is* the real gate. Do not add a hollow E2E test to look thorough.
+- **A green CI badge is not proof.** Many repos split their required check from the full suite (browser-free half only, etc.). Find out what the required check actually runs.
+
+## Instructions
+
+### 1. Establish the ground truth
+
+```bash
+gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup,url
+```
+
+Record four things before touching code:
+
+- **`mergeable`** — `CONFLICTING` means step 2 is mandatory.
+- **Which checks are failing**, and for each, whether it is *required*. Check branch protection (`gh api repos/{owner}/{repo}/branches/<base>/protection`) rather than assuming — a red optional job (a flaky bot-review runner, a nightly) is not a blocker, and burning the run waiting on one is a classic waste.
+- **Whether the repo auto-merges.** Look for a shepherd/automerge workflow in `.github/workflows/` and read its *gating conditions* (required labels, required checks). If pushing could trigger an immediate merge, decide deliberately: either satisfy the review sweep first, or tell the user before you push. Never let an auto-merge race a review you were asked to complete.
+- **Whether a bot review actually ran.** A `SUCCESS` status from a review bot can still mean "rate-limited, never reviewed" — read its comment body, not just the check state.
+
+### 2. Rebase onto the base branch
+
+Require a clean tree first (`git status --porcelain` empty), then:
+
+```bash
+git fetch origin <base>
+git rebase origin/<base>
+```
+
+Resolve conflicts by **understanding both sides**, not by picking one. Read the base-side commit that introduced the conflicting hunk (`git log -1 --format=%s <base> -- <file>`, then the diff) — a conflict usually means main changed an invariant your branch is unaware of, and blindly keeping "your" side silently reverts it. State in the PR comment which invariant you preserved and why.
+
+After resolving, re-run the tests before continuing — a rebase that compiles is not a rebase that works.
+
+### 3. Sweep every review source
+
+Collect findings from all of these; do not stop at the first:
+
+```bash
+# inline review threads (all bots + humans), with resolution state
+gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
+# rollup issue comments (where CodeRabbit/Qodo post summaries and rate-limit notices)
+gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
+# formal reviews
+gh pr view <PR> --json reviews
+```
+
+**Delegate to the dedicated loop skill when one exists** rather than reimplementing its bot's protocol — `qodoloop` for Qodo, `coderabbitloop` for CodeRabbit, `greploop` for Greptile. Each already encodes that bot's posting shape, its ready-made per-finding fix prompt, and its real terminal states. Use this skill's own sweep for human comments and for bots without a dedicated loop.
+
+Triage every finding into exactly one bucket:
+
+| Bucket | Action |
+|---|---|
+| **Real defect** | Fix it. This is the point of the exercise. |
+| **Legitimate improvement** | Fix it if it's in scope for this PR. |
+| **False positive** | Reply explaining *specifically* why the bot is wrong. Do not resolve silently. |
+| **Needs a human call** | Reply, leave open, surface in the final report. |
+
+Bot findings are suggestions from something that has not run the code. A "🐞 Bug" label is a hypothesis — verify it against the actual source before fixing, and against the actual behavior before dismissing.
+
+### 4. Close the coverage gap
+
+Ask, for the change as a whole, what would catch a regression here — then check whether the PR actually has it.
+
+- **Unit / integration tests:** does every new branch have a test that fails if you invert it? Bots frequently and correctly flag helper functions exercised only *indirectly* through a caller. A direct test per branch is cheap and is usually the right response.
+- **Browser / E2E tests:** determine whether the repo supports them (`playwright.config.*`, `cypress.config.*`, a `test:e2e` script) **and** whether this change has any surface they can reach. Then do one of exactly two things:
+  - it has a reachable surface → add or extend the E2E spec;
+  - it does not → **say so explicitly in the PR comment**, name why (e.g. "this is entirely inside a Durable Object alarm loop; the E2E harness only serves static assets"), and name the suite that is the real gate.
+
+  Silence here reads as an oversight. An explicit "not applicable, because X" reads as diligence — and is checkable.
+
+### 5. Run the real gates
+
+Discover them from the repo (`Makefile`, `package.json` scripts, CI workflow) — do not guess target names. Run, at minimum, the equivalents of:
+
+```bash
+<lint>        # e.g. make lint / npm run lint
+<format>      # check mode first; only write if it reports drift
+<tests>       # the suite covering the changed package
+```
+
+Capture exit codes, not just output. Repo-specific traps worth checking for before you burn a cycle: linters whose cache replays findings from deleted sibling worktrees, formatters whose local toolchain version outruns CI's (churning unrelated files), and test runners that hang when two runs overlap.
+
+If a gate fails, fix it. Do not push red.
+
+### 6. Push and explain
+
+Stage only the files you touched, commit, and push (`--force-with-lease` after a rebase — never bare `--force`).
+
+Then post **one** PR comment that a reviewer can audit without re-reading the diff:
+
+- what the rebase conflict was and which side won, with the reason;
+- each finding, and what you did about it (including the ones you rejected, with the argument);
+- the coverage decision from step 4, including the explicit not-applicable if that's the answer;
+- **verbatim** gate output — real numbers (`# pass 480 / # fail 0`, `0 issues.`), not adjectives.
+
+Re-trigger any bot that never actually reviewed (e.g. `@coderabbitai review`) so the PR gets the pass it was owed.
+
+### 7. Verify and report
+
+Re-read the PR state after the push — confirm `mergeable` flipped, checks went green, and clear now-stale labels (`needs-rebase`, etc.). Poll re-triggered bots for their new pass and handle anything it raises.
+
+```text
+PR #965 finalized.
+  Rebase:      1 conflict resolved (kept main's #834 D1-first ordering)
+  Findings:    2 addressed, 0 rejected, 0 blocked
+  Coverage:    +5 unit tests; E2E not applicable (no browser surface) — stated on the PR
+  Gates:       tests 480/480, lint 0 issues, format clean
+  State:       MERGEABLE, checks green
+  Needs human: none
+```
+
+If anything is left, say precisely what and why — an honest "blocked on X" is the deliverable when X is genuinely a human call.
+
+## Related skills
+
+- `qodoloop` — full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
+- `coderabbitloop` — full CodeRabbit protocol.
+- `greploop` — drives a PR to a 5/5 Greptile confidence score.
+- `ci-fix-loop` — when the blocker is a failing pipeline rather than review feedback.

package/packages/wearables/garmin-watchface/SKILL.md

@@ -25,6 +25,7 @@ looked like success first.
 | `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
 | `references/devices.md` | Adding device support, launcher icons, API levels |
 | `references/store.md` | Publishing, listing copy, IP questions |
+| `references/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
 
 ## Tools
 
@@ -37,8 +38,14 @@ Run these rather than reinventing them. All are standalone.
 <skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
 <skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
 <skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+<skill-dir>/scripts/ciq-release       # pre-submission check: package, screenshots, icon, keys, copy
 ```
 
+`<skill-dir>/scripts/ciq-release` is what you run before opening the store
+portal. Every check in it is something otherwise discovered halfway through the
+submission form -- a stale screenshot set, an icon still copied from the last
+project, or copy containing a character the description validator rejects.
+
 `<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
 a window: without a frontmost check it silently photographs whatever is on top,
 and the window moves between simulator restarts. Both failure modes produce a

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/SKILL.md

@@ -26,6 +26,7 @@ looked like success first.
 | `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
 | `references/devices.md` | Adding device support, launcher icons, API levels |
 | `references/store.md` | Publishing, listing copy, IP questions |
+| `references/publishing.md` | Driving the store portal in a browser; upload/update flow, validator rejections |
 
 ## Tools
 
@@ -38,8 +39,14 @@ Run these rather than reinventing them. All are standalone.
 <skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
 <skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
 <skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+<skill-dir>/scripts/ciq-release       # pre-submission check: package, screenshots, icon, keys, copy
 ```
 
+`<skill-dir>/scripts/ciq-release` is what you run before opening the store
+portal. Every check in it is something otherwise discovered halfway through the
+submission form -- a stale screenshot set, an icon still copied from the last
+project, or copy containing a character the description validator rejects.
+
 `<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
 a window: without a frontmost check it silently photographs whatever is on top,
 and the window moves between simulator restarts. Both failure modes produce a

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/references/publishing.md

@@ -0,0 +1,145 @@
+# Publishing through the browser
+
+`references/store.md` covers *what* the listing needs. This covers *driving the
+portal*, which is the only way in — Garmin publishes no submission API.
+
+Run `scripts/ciq-release` before opening a browser. Everything it checks is
+something you would otherwise discover halfway through the form.
+
+## The portal is automatable
+
+The obvious conclusion is that it is not: `apps.garmin.com/developer/dashboard`
+sits behind Garmin SSO *and* Cloudflare bot protection, and a headless browser
+lands on a "Performing security verification" interstitial. That is what you see
+if you navigate cold.
+
+It works anyway, because the session is already sitting in your own browser.
+Import the cookies:
+
+```bash
+B=~/.claude/skills/gstack/browse/dist/browse
+
+$B cookie-import-browser comet --domain .garmin.com     # note the LEADING DOT
+$B goto https://apps.garmin.com/                        # host-scoped cookies
+$B cookie-import-browser comet --domain apps.garmin.com #   need you to be on
+$B goto https://sso.garmin.com/                         #   the host first
+$B cookie-import-browser comet --domain sso.garmin.com
+
+$B goto https://apps.garmin.com/developer/dashboard     # no SSO redirect
+```
+
+Three separate traps in that block:
+
+- **`garmin.com` imports nothing. `.garmin.com` imports everything.** The cookie
+  is stored under the dotted domain and the filter is an exact match, so the
+  obvious spelling silently returns `Imported 0 cookies` and looks like "not
+  logged in".
+- **Host-scoped cookies need you on that host first**, or the import refuses
+  with *"does not match current page domain"*. The `.garmin.com` set alone is
+  NOT enough to authenticate — the session only holds once
+  `apps.` and `sso.` are imported too.
+- **Substitute your browser.** `comet`, `chrome`, `brave`, `arc`, `edge`,
+  `chromium` are supported. Whichever one you actually signed into.
+
+Verify by checking the URL after `goto`: an unauthenticated session is bounced
+to `sso.garmin.com/portal/sso/...`, an authenticated one stays put.
+
+## "The Connect IQ store is currently in maintenance mode"
+
+This string is in the DOM of the dashboard and of every app page, next to
+*Upload New Version*, *Edit Details* and *Remove*. Reading the page text makes
+it look like every action is blocked.
+
+**It is pre-rendered hidden markup, not an active block.** Click the button and
+the real form loads. Do not report the store as down on the strength of a text
+dump — click first, then check for a *visible* dialog:
+
+```bash
+$B js "(function(){var o=[];document.querySelectorAll('[role=dialog],.modal').forEach(function(x){if(x.offsetParent!==null)o.push(x.innerText.slice(0,120))});return o.join('|')||'no visible modal'})()"
+```
+
+## The two-step update flow
+
+*Upload New Version* → `/apps/<uuid>/update`, which is two steps.
+
+**Step 1 — attach.** A file input and an *App Version* textbox. Publish stays
+disabled until both are set; the page shows the current version so you can pick
+the next one.
+
+```bash
+$B upload "input[type=file]" "$(pwd)/bin/<name>.iq"
+$B fill "input[id*='version'],input[name*='version']" "2.0"
+$B click "button:has-text('Upload and publish')"
+```
+
+On success the page reports **Status: Verified, Signature: Verified** and
+expands the product list — a manifest naming one product can resolve to several
+store devices (`fenix6pro` becomes fēnix 6 Pro, 6 Pro Dual Power, 6 Pro Solar
+and quatix 6).
+
+**Step 2 — details.** Title, description, What's New, images, category, contact
+email. Ends in *Submit*.
+
+The description arrives pre-filled with the copy from the PREVIOUS version.
+After a redesign it describes a face that no longer exists, and nothing prompts
+you about it. Re-paste from `docs/store/listing.md` every time.
+
+## Image slots, in DOM order
+
+There are seven `input[type=file]` elements and none of them carry a name, id
+or label. Order is the only way to tell them apart, so confirm it before
+uploading rather than trusting this table:
+
+```bash
+$B js "(function(){var f=document.querySelectorAll('input[type=file]');var o=[];f.forEach(function(x,i){var n=x,c='';for(var k=0;k<8&&n;k++){n=n.parentElement;if(n&&n.innerText.trim().length>25){c=n.innerText.replace(/\s+/g,' ').slice(0,60);break}}o.push(i+' >> '+c)});return o.join('\n')})()"
+```
+
+| # | Slot | Size | Limit |
+| --- | --- | --- | --- |
+| 0 | Hero image | **1440×720** | 2048 KB |
+| 1 | Cover image | **500×500** | 300 KB |
+| 2–6 | Screen images | any | **150 KB each** |
+
+Getting the order wrong puts a 260px screenshot where the hero belongs, and the
+form accepts it.
+
+## The description validator
+
+Two rejections, both discovered only after filling the entire form and pressing
+Submit:
+
+- `Illegal characters found: <, >.` — an ASCII `->` arrow is enough to trip it.
+- `The app description is invalid. It should not contain emojis.` — **U+2699
+  GEAR counts**, which is exactly the character you reach for when writing
+  "tap the gear icon". U+2192 RIGHTWARDS ARROW passes today but lives in the
+  same symbol space.
+
+Write settings paths in words: *"Garmin Connect app, then: your device, Connect
+IQ Apps, Watch Faces, the app name, settings"*. `scripts/ciq-release` checks the fenced
+blocks of `listing.md` for both classes before you open a browser.
+
+The error text renders as a leaf node with no `aria-invalid` anywhere, so find
+it by scanning for childless visible elements rather than by form state:
+
+```bash
+$B js "(function(){var o=[];document.querySelectorAll('*').forEach(function(x){if(!x.children.length&&x.offsetParent!==null&&/invalid|illegal/i.test(x.innerText))o.push(x.innerText.trim())});return Array.from(new Set(o)).join(' || ')})()"
+```
+
+Success is a redirect to `apps.garmin.com/apps/<uuid>`. Staying on `/update`
+means a validation failure.
+
+## Things not to click
+
+**Remove** sits between *Edit Details* and *Download* in the same button row.
+Never target buttons by index in that row.
+
+**Upload and publish** and **Submit** are outward-facing: they push to a public
+listing and accept the Developer License Agreement on the account holder's
+behalf. Confirm with the human before either, even when they have asked for the
+release — version number and stale copy are both worth one question.
+
+## Account state
+
+A developer account pending identity verification can still upload; approval
+gates public visibility, not submission. A newly submitted app sits in preview
+mode, visible only to its owner, for up to three days.

package/packages/wearables/garmin-watchface/adapters/claude/skills/garmin-watchface/scripts/ciq-release

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Pre-submission check for a Connect IQ project.
+
+Everything that can be verified WITHOUT logging into the store, verified here,
+so the browser session is spent on the form rather than on discovering that the
+package is stale.
+
+    ciq-release              # check ./ and print the verdict
+    ciq-release path/to/proj
+    ciq-release --quiet      # exit code only
+
+Exit 0 when submittable, 1 when something is wrong.
+
+The checks are the ones that have actually gone wrong, not a generic lint:
+
+  * screenshots older than the package they claim to show. store.md calls stale
+    screenshots the most common thing to forget after a redesign, and they
+    misrepresent the version under review -- which is a review rejection, not a
+    cosmetic slip.
+  * a launcher icon that is byte-identical to another project's. Copying a
+    scaffold and forgetting the icon ships someone else's mark.
+  * signing keys inside the project. The key signs your app id: commit it and
+    anyone can impersonate the app; lose it and you can never update the
+    listing.
+  * a package older than the sources it was built from.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+RESET = "\033[0m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+
+
+class Report:
+    def __init__(self, quiet: bool) -> None:
+        self.quiet = quiet
+        self.failed = 0
+        self.warned = 0
+
+    def _line(self, colour: str, tag: str, msg: str, detail: str) -> None:
+        if self.quiet:
+            return
+        pad = f"  {colour}{tag}{RESET}   {msg}"
+        print(pad if not detail else f"{pad}\n         {detail}")
+
+    def ok(self, msg: str, detail: str = "") -> None:
+        self._line(GREEN, "ok  ", msg, detail)
+
+    def warn(self, msg: str, detail: str = "") -> None:
+        self.warned += 1
+        self._line(YELLOW, "warn", msg, detail)
+
+    def fail(self, msg: str, detail: str = "") -> None:
+        self.failed += 1
+        self._line(RED, "FAIL", msg, detail)
+
+
+def newest(paths) -> float:
+    stamps = [p.stat().st_mtime for p in paths if p.is_file()]
+    return max(stamps) if stamps else 0.0
+
+
+def check_manifest(root: Path, r: Report) -> None:
+    manifest = root / "manifest.xml"
+    if not manifest.is_file():
+        r.fail("no manifest.xml", f"looked in {root}")
+        return
+    text = manifest.read_text(encoding="utf-8", errors="replace")
+
+    app_id = re.search(r'id="([0-9a-fA-F]{32})"', text)
+    if not app_id:
+        r.fail("manifest has no 32-hex application id")
+    else:
+        r.ok(f"app id {app_id.group(1)}")
+
+    products = re.findall(r'<iq:product\s+id="([^"]+)"', text)
+    if not products:
+        r.fail("manifest declares no products")
+    else:
+        r.ok(f"{len(products)} product(s): {', '.join(products)}")
+
+    # A watch face that forgot its permissions still builds, then reads null
+    # from every sensor on the watch and nowhere else.
+    perms = re.findall(r'uses-permission\s+id="([^"]+)"', text)
+    r.ok(f"permissions: {', '.join(perms) if perms else 'none'}")
+
+
+def check_package(root: Path, r: Report) -> Path | None:
+    packages = list((root / "bin").glob("*.iq")) if (root / "bin").is_dir() else []
+    if not packages:
+        r.fail("no .iq package", "run: make package")
+        return None
+    iq = max(packages, key=lambda p: p.stat().st_mtime)
+    built = iq.stat().st_mtime
+
+    sources = list((root / "source").rglob("*.mc"))
+    sources += list((root / "resources").rglob("*"))
+    if newest(sources) > built:
+        r.fail(
+            f"{iq.name} is older than the sources it was built from",
+            "run: make package",
+        )
+    else:
+        r.ok(f"{iq.name} ({iq.stat().st_size // 1024} KB) is current")
+    return iq
+
+
+def check_screenshots(root: Path, _iq: Path | None, r: Report) -> None:
+    store = root / "docs" / "store"
+    shots = sorted(store.glob("*.png")) if store.is_dir() else []
+    if not shots:
+        r.warn("no screenshots in docs/store/", "the listing form needs at least one")
+        return
+
+    # Screenshots are checked against their source files (source/*.mc and
+    # resources/*) rather than the package they claim to show. The question is
+    # "do these images show the current face?", and only a source or resource
+    # change can make them stale. Stale screenshots misrepresent the version
+    # under review, which is a review rejection, not a cosmetic slip.
+    sources = list((root / "source").rglob("*.mc"))
+    sources += [p for p in (root / "resources").rglob("*") if p.is_file()]
+    changed = newest(sources)
+    newest_shot = newest(shots)
+    if changed > newest_shot:
+        stale = [p.name for p in sources if p.stat().st_mtime > newest_shot]
+        r.fail(
+            f"{len(shots)} screenshot(s) predate the current sources",
+            "changed since capture: " + ", ".join(sorted(stale)[:4])
+            + ("..." if len(stale) > 4 else ""),
+        )
+    else:
+        r.ok(f"{len(shots)} screenshot(s), current with the sources")
+
+
+def check_icon(root: Path, r: Report) -> None:
+    icons = list((root / "resources").rglob("launcher_icon.png"))
+    if not icons:
+        r.warn("no launcher_icon.png found")
+        return
+
+    digest = hashlib.sha256(icons[0].read_bytes()).hexdigest()
+
+    # Compare against every sibling project. A scaffold copied from the last
+    # face keeps its icon, and nothing in the build complains.
+    for sibling in root.parent.iterdir():
+        if not sibling.is_dir() or sibling.resolve() == root.resolve():
+            continue
+        for other in sibling.rglob("launcher_icon.png"):
+            if hashlib.sha256(other.read_bytes()).hexdigest() == digest:
+                r.fail(
+                    "launcher icon is byte-identical to another project's",
+                    f"same file as {other}",
+                )
+                return
+    r.ok("launcher icon is unique to this project")
+
+
+def check_keys(root: Path, r: Report) -> None:
+    candidates = [p for p in root.rglob("*") if p.suffix in (".der", ".pem") and p.is_file()]
+
+    # Inspect file contents to confirm they contain private key material
+    private_keys = []
+    for p in candidates:
+        if p.suffix == ".pem":
+            try:
+                content = p.read_text(errors="replace")
+                # Check for private key PEM headers
+                if any(marker in content for marker in [
+                    "BEGIN PRIVATE KEY",
+                    "BEGIN RSA PRIVATE KEY",
+                    "BEGIN EC PRIVATE KEY",
+                    "BEGIN ENCRYPTED PRIVATE KEY",
+                ]):
+                    private_keys.append(p)
+            except Exception:
+                pass
+        elif p.suffix == ".der":
+            # DER files are binary; use a simple heuristic: assume .der files
+            # in typical key locations are keys unless they're obviously certs
+            # (this is a best-effort check; DER format inspection is complex)
+            try:
+                data = p.read_bytes()
+                # Very basic heuristic: if file is small and doesn't contain
+                # obvious certificate markers, treat as potential private key
+                # This is imperfect but better than blanket rejection
+                if len(data) < 10000:  # Private keys are typically smaller than cert bundles
+                    private_keys.append(p)
+            except Exception:
+                pass
+
+    if private_keys:
+        r.fail(
+            "signing key material inside the project",
+            "\n         ".join(str(p) for p in private_keys),
+        )
+        return
+
+    gitignore = root / ".gitignore"
+    ignored = gitignore.read_text(errors="replace") if gitignore.is_file() else ""
+    if "*.der" not in ignored or "*.pem" not in ignored:
+        r.warn(".gitignore does not cover *.der / *.pem")
+    else:
+        r.ok("no keys in the tree, and both extensions are ignored")
+
+
+def check_tests(root: Path, r: Report) -> None:
+    log = root / "bin" / "test.log"
+    if not log.is_file():
+        r.warn("no bin/test.log", "run: make test")
+        return
+    text = log.read_text(errors="replace")
+    if re.search(r"^PASSED \(passed=\d+, failed=0, errors=0\)", text, re.M):
+        count = re.search(r"passed=(\d+)", text)
+        r.ok(f"{count.group(1) if count else '?'} tests passed")
+    else:
+        r.fail("bin/test.log does not end in a clean PASSED line")
+
+
+def check_listing(root: Path, r: Report) -> None:
+    listing = root / "docs" / "store" / "listing.md"
+    if not listing.is_file():
+        r.warn("no docs/store/listing.md", "the form wants copy ready to paste")
+        return
+    doc = listing.read_text(errors="replace")
+
+    # Only the FENCED blocks are checked -- those are what gets pasted into the
+    # store form. The surrounding prose is notes for a human and legitimately
+    # contains things the store would reject, like an autolinked <https://...>
+    # portal URL. Scanning the whole file flags the documentation.
+    raw = "\n".join(re.findall(r"^```\n(.*?)^```", doc, re.S | re.M))
+    if not raw:
+        r.warn("listing.md has no fenced copy blocks to check")
+        return
+
+    # The store's description validator rejects two things, and both are
+    # discovered the slow way -- by filling the whole form and being bounced:
+    #
+    #   "Illegal characters found: <, >."
+    #   "The app description is invalid. It should not contain emojis."
+    #
+    # A GEAR (U+2699) counts as an emoji, which is easy to reach for when
+    # writing "tap the gear icon". Arrows (U+2192) pass today, but they sit in
+    # the same symbol space and cost nothing to avoid.
+    if "<" in raw or ">" in raw:
+        r.fail(
+            "listing copy contains < or >",
+            "the store rejects them: \"Illegal characters found\"",
+        )
+    else:
+        r.ok("no angle brackets in the copy")
+
+    # Explicit emoji Unicode ranges (common blocks that Garmin store rejects)
+    def is_emoji(c: str) -> bool:
+        o = ord(c)
+        return (
+            (0x1F300 <= o <= 0x1F9FF) or  # Miscellaneous Symbols and Pictographs, Emoticons, etc.
+            (0x2600 <= o <= 0x27BF) or    # Miscellaneous Symbols, Dingbats
+            (0x2300 <= o <= 0x23FF) or    # Miscellaneous Technical (includes gear U+2699)
+            (0x2190 <= o <= 0x21FF) or    # Arrows (includes U+2192)
+            (0x2900 <= o <= 0x297F) or    # Supplemental Arrows-B
+            (0x2B00 <= o <= 0x2BFF) or    # Miscellaneous Symbols and Arrows
+            (0x3030 <= o <= 0x303F) or    # CJK Symbols and Punctuation (wavy dash, etc.)
+            (0xFE00 <= o <= 0xFE0F)       # Variation Selectors
+        )
+    emoji = sorted({c for c in raw if is_emoji(c)})
+    if emoji:
+        r.fail(
+            "listing copy contains symbols the store reads as emoji",
+            " ".join(f"{c!r} (U+{ord(c):04X})" for c in emoji),
+        )
+    else:
+        r.ok("no emoji in the copy")
+
+    text = doc.lower()
+    # Watch face settings are unreachable from the watch. Omitting this reads as
+    # a missing feature to every reviewer and every user.
+    if "garmin connect" not in text:
+        r.warn(
+            "listing never mentions the Garmin Connect app",
+            "watch face settings are not reachable from the watch; say so or "
+            "it reads as a missing feature",
+        )
+    else:
+        r.ok("listing explains where settings live")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument("project", nargs="?", default=".")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    root = Path(args.project).resolve()
+    r = Report(args.quiet)
+
+    if not args.quiet:
+        print(f"Connect IQ release check\n  {root}\n")
+
+    check_manifest(root, r)
+    iq = check_package(root, r)
+    check_screenshots(root, iq, r)
+    check_icon(root, r)
+    check_keys(root, r)
+    check_tests(root, r)
+    check_listing(root, r)
+
+    if not args.quiet:
+        print()
+        if r.failed:
+            print(f"  {RED}{r.failed} blocking problem(s){RESET}, {r.warned} warning(s)")
+        elif r.warned:
+            print(f"  {YELLOW}submittable, {r.warned} warning(s){RESET}")
+        else:
+            print(f"  {GREEN}submittable{RESET}")
+        if not r.failed:
+            print(
+                "\n  Upload: apps.garmin.com/developer/dashboard\n"
+                "  The portal IS drivable headlessly once the session cookies are\n"
+                "  imported from a signed-in browser. See references/publishing.md."
+            )
+    return 1 if r.failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())