claudecode-omc 5.6.5 → 5.6.7

package/.local/commands/prp-pr.md

@@ -0,0 +1,244 @@
+---
+description: "Create a PR/MR from current branch with unpushed commits (PRP-aware) — auto-detects GitHub vs GitLab (github.com / code.iflytek.com / generic GitLab)"
+argument-hint: "[base-branch] (default: main)"
+---
+
+# Create Pull Request / Merge Request (PRP variant)
+
+> Local override of upstream `ecc/commands/prp-pr.md`. Adds GitLab (incl. self-hosted
+> `code.iflytek.com`) support. Do not edit the upstream file — keep changes here.
+> Difference vs `/pr`: this variant references PRP artifacts (`.claude/PRPs/...`) and
+> suggests `/prp-commit` for staging.
+
+**Input**: `$ARGUMENTS` — optional, may contain a base branch name and/or flags (e.g., `--draft`).
+
+**Parse `$ARGUMENTS`**:
+- Extract any recognized flags (`--draft`)
+- Treat remaining non-flag text as the base branch name
+- Default base branch to `main` if none specified
+
+---
+
+## Phase 0 — DETECT PLATFORM
+
+```bash
+remote_url=$(git remote get-url origin 2>/dev/null)
+
+case "$remote_url" in
+  *github.com*)
+    platform=github; cli=gh ;;
+  *code.iflytek.com*)
+    platform=gitlab; cli=glab; gitlab_host=code.iflytek.com ;;
+  *gitlab*)
+    platform=gitlab; cli=glab
+    gitlab_host=$(echo "$remote_url" | sed -E 's#.*[@/]([^:/]+)[:/].*#\1#') ;;
+  *)
+    platform=unknown ;;
+esac
+```
+
+If `platform=unknown`: ask the user to confirm platform or fix `origin`.
+
+Auth check:
+- `github` → `gh auth status`
+- `gitlab` → `glab auth status --hostname "$gitlab_host"`
+
+For `code.iflytek.com` one-time login:
+```bash
+glab auth login --hostname code.iflytek.com
+# HTTPS + Personal Access Token (scope: api, read_repository, write_repository)
+# Token: https://code.iflytek.com/-/user_settings/personal_access_tokens
+```
+
+---
+
+## Phase 1 — VALIDATE
+
+```bash
+git branch --show-current
+git status --short
+git log origin/<base>..HEAD --oneline
+```
+
+| Check | Condition | Action if Failed |
+|---|---|---|
+| Not on base branch | Current branch ≠ base | Stop: "Switch to a feature branch first." |
+| Clean working directory | No uncommitted changes | Warn: "You have uncommitted changes. Commit or stash first. Use `/prp-commit` to commit." |
+| Has commits ahead | `git log origin/<base>..HEAD` not empty | Stop: "No commits ahead of `<base>`. Nothing to PR." |
+| No existing PR/MR | See platform-specific check below | Stop: "PR/MR already exists: #<number>." |
+
+**Existing PR/MR check:**
+
+| Platform | Command |
+|---|---|
+| GitHub | `gh pr list --head <branch> --json number,url --jq '.[0]'` |
+| GitLab | `glab mr list --source-branch <branch> --output json --per-page 1 \| jq '.[0]'` |
+
+If all checks pass, proceed.
+
+---
+
+## Phase 2 — DISCOVER
+
+### PR/MR Template
+
+**GitHub** (PR templates):
+1. `.github/PULL_REQUEST_TEMPLATE/` directory — list and let user choose
+2. `.github/PULL_REQUEST_TEMPLATE.md`
+3. `.github/pull_request_template.md`
+4. `docs/pull_request_template.md`
+
+**GitLab** (MR templates):
+1. `.gitlab/merge_request_templates/` directory — list and let user choose
+2. `.gitlab/merge_request_template.md`
+
+If found, use its structure.
+
+### Commit Analysis
+
+```bash
+git log origin/<base>..HEAD --format="%h %s" --reverse
+```
+
+- **Title**: Conventional commit format. Multiple types → dominant one. Single commit → use as-is.
+- **Summary**: Group commits by type/area.
+
+### File Analysis
+
+```bash
+git diff origin/<base>..HEAD --stat
+git diff origin/<base>..HEAD --name-only
+```
+
+Categorize: source, tests, docs, config, migrations.
+
+### PRP Artifacts
+
+Check for related PRP artifacts:
+- `.claude/PRPs/reports/` — Implementation reports
+- `.claude/PRPs/plans/` — Plans that were executed
+- `.claude/PRPs/prds/` — Related PRDs
+
+Reference these in the body if they exist.
+
+---
+
+## Phase 3 — PUSH
+
+```bash
+git push -u origin HEAD
+```
+
+If push fails due to divergence:
+```bash
+git fetch origin
+git rebase origin/<base>
+git push -u origin HEAD  # use --force-with-lease only after rebase
+```
+
+If rebase conflicts, stop and inform the user.
+
+---
+
+## Phase 4 — CREATE
+
+### With Template
+
+Fill each section using commit and file analysis. Preserve all sections — leave as "N/A" if not applicable.
+
+### Without Template
+
+```markdown
+## Summary
+<1-2 sentence description>
+
+## Changes
+<bulleted list grouped by area>
+
+## Files Changed
+<list with change type: Added/Modified/Deleted>
+
+## Testing
+<how changes were tested, or "Needs testing">
+
+## Related Issues
+<linked issues with Closes/Fixes/Relates to #N, or "None">
+```
+
+### Create the PR/MR
+
+**GitHub:**
+```bash
+gh pr create \
+  --title "<title>" \
+  --base <base-branch> \
+  --body "<body>"
+  # Add --draft if --draft was parsed
+```
+
+**GitLab:**
+```bash
+glab mr create \
+  --title "<title>" \
+  --target-branch <base-branch> \
+  --description "<body>" \
+  --source-branch "$(git branch --show-current)" \
+  --yes
+  # Add --draft if --draft was parsed
+```
+
+---
+
+## Phase 5 — VERIFY
+
+**GitHub:**
+```bash
+gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles
+gh pr checks --json name,status,conclusion 2>/dev/null || true
+```
+
+**GitLab:**
+```bash
+glab mr view --output json
+glab ci status 2>/dev/null || true
+```
+
+---
+
+## Phase 6 — OUTPUT
+
+```
+<PR|MR> #<number>: <title>
+Platform: <github|gitlab(host)>
+URL: <url>
+Branch: <head> → <base>
+Changes: +<additions> -<deletions> across <changedFiles> files
+
+CI Checks: <status summary or "pending" or "none configured">
+
+Artifacts referenced:
+  - <any PRP reports/plans linked in body>
+
+Next steps:
+  GitHub:
+    - gh pr view <N> --web        → open in browser
+    - /code-review <N>            → review the PR
+    - gh pr merge <N>             → merge when ready
+  GitLab:
+    - glab mr view <N> --web      → open in browser
+    - /code-review <N>            → review the MR
+    - glab mr merge <N>           → merge when ready
+```
+
+(Print only the section matching the detected platform.)
+
+---
+
+## Edge Cases
+
+- **No `gh`/`glab`**: Stop with install + auth instructions for the detected platform.
+- **Not authenticated**: Stop with `gh auth login` or `glab auth login --hostname <host>`.
+- **Force push needed**: After rebase, use `git push --force-with-lease` (never `--force`).
+- **Multiple templates**: List and ask user to choose.
+- **Large PR/MR (>20 files)**: Warn about scope. Suggest splitting if logically separable.
+- **Unknown platform**: Ask user to confirm or fix `origin`.

package/.local/guidelines/CLAUDE.md

@@ -29,3 +29,50 @@ These are always-on guardrails for non-trivial coding work.
 - Verify behavior with tests or explicit checks whenever practical.
 - Tie multi-step work to validation at each step.
 - Do not claim completion without fresh evidence from the workspace.
+
+## Platform Routing (GitHub vs GitLab)
+
+Before running any remote-collaboration command (PR/MR view/diff/create/comment/approve/merge), **first detect the platform from the active repo's `origin` remote**, then pick the matching CLI. Never hardcode `gh` or `glab`.
+
+```bash
+remote=$(git remote get-url origin 2>/dev/null)
+case "$remote" in
+  *github.com*)       platform=github; cli=gh ;;
+  *code.iflytek.com*) platform=gitlab; cli=glab; host=code.iflytek.com ;;
+  *gitlab*)           platform=gitlab; cli=glab
+                      host=$(echo "$remote" | sed -E 's#.*[@/]([^:/]+)[:/].*#\1#') ;;
+  *)                  platform=unknown ;;
+esac
+```
+
+If `platform=unknown`: ask the user to confirm before continuing.
+
+**Authoritative `gh ↔ glab` mapping** (apply this translation whenever an instruction or upstream skill uses `gh` but the active repo is GitLab):
+
+| Action | GitHub (`gh`) | GitLab (`glab`) |
+|---|---|---|
+| View PR/MR | `gh pr view <N>` | `glab mr view <N>` |
+| Diff | `gh pr diff <N>` | `glab mr diff <N>` |
+| List by branch | `gh pr list --head <b>` | `glab mr list --source-branch <b>` |
+| Create | `gh pr create --title ... --body ...` | `glab mr create --title ... --description ... --source-branch ... --target-branch ... --yes` |
+| Approve | `gh pr review <N> --approve` | `glab mr approve <N>` |
+| Request changes | `gh pr review <N> --request-changes` | `glab mr revoke <N>` + `glab mr note <N> --message "..."` |
+| Comment | `gh pr review <N> --comment` | `glab mr note <N> --message "..."` |
+| Merge | `gh pr merge <N>` | `glab mr merge <N>` |
+| CI status | `gh pr checks` | `glab ci status` |
+| Raw API | `gh api ...` | `glab api ... --hostname <host>` |
+| Auth check | `gh auth status` | `glab auth status --hostname <host>` |
+| PR template path | `.github/PULL_REQUEST_TEMPLATE*` | `.gitlab/merge_request_template*` |
+| File link path | `/blob/<ref>/<path>` | `/-/blob/<ref>/<path>` |
+
+For inline review comments on GitLab, use the GitLab discussions API with `diff_refs.base_sha/start_sha/head_sha` and `position[position_type]=text` (see `.local/commands/code-review.md` Phase 7 for the full call).
+
+When the upstream skill or command names a fixed CLI command, treat that as a *template*: substitute the matching command from the table above based on the detected platform. The hard-overridden commands in `.local/commands/` (`code-review.md`, `pr.md`, `prp-pr.md`) already route correctly; this rule covers everything else.
+
+**Self-hosted iflytek GitLab one-time setup** (only needed once per machine):
+
+```bash
+glab auth login --hostname code.iflytek.com
+# HTTPS + Personal Access Token (scope: api, read_repository, write_repository)
+# Token: https://code.iflytek.com/-/user_settings/personal_access_tokens
+```

package/.local/skills/h5-to-swiftui/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: h5-to-swiftui
+version: 1.0.0
+description: >-
+  Convert an H5 / web app's source into a native SwiftUI iOS app by native
+  rewrite (NOT a WebView shell, NOT a transpiler). Use when the user wants to
+  port, re-implement, or migrate a web/H5 frontend to native SwiftUI with
+  high visual fidelity, asks to "turn this web app into a real iOS app", or
+  wants a measured render-diff convergence loop against a browser baseline.
+  Auto-detects the web stack (v1: vanilla + React; other stacks are detected
+  then gated, not guessed), extracts design tokens, calibrates a
+  cross-renderer fidelity floor, rewrites per component, and drives a bounded
+  render→diff→correct loop that reports a quantified visual residual plus an
+  independent judge verdict. It does NOT promise literal pixel-identity:
+  cross-renderer differences impose a measured floor it reports honestly.
+  Triages canvas/WebGL/complex-animation/3rd-party-SDK/backend surfaces
+  instead of silently emitting wrong code.
+argument-hint: "<path-to-h5-source> [--ios-floor 17] [--device 'iPhone 15 Pro'] [--max-iter 3]"
+disable-model-invocation: false
+user-invocable: true
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Write
+  - Edit
+  - Agent
+model: sonnet
+---
+
+# H5 → Native SwiftUI (perceptually-convergent, residual-quantified)
+
+Convert a web/H5 app to a **native SwiftUI** iOS app by reading the source and
+**re-implementing** UI + logic in idiomatic SwiftUI. This is a native rewrite,
+**not** a WebView wrapper and **not** a mechanical transpiler — those cannot
+reach native fidelity (see `references/stack-detection.md` for why).
+
+## Honest promise (read this first)
+
+Literal pixel-identity is **physically unreachable** for any text-bearing
+screen: H5 renders in WebKit/Skia, SwiftUI in CoreText/Core Animation;
+per-glyph subpixel/hinting and sRGB-vs-Display-P3 differences impose a
+**non-zero residual** even when the SwiftUI is perfectly correct. This skill
+therefore does **not** claim "pixel-perfect". It:
+
+1. **measures** the achievable cross-renderer floor for the current toolchain
+   (Stage 2.5 calibration),
+2. drives a render→diff→correct loop that **strictly reduces** visual delta
+   toward that measured floor,
+3. stops with a **quantified residual**, an **independent adversarial judge**
+   verdict, and a tiered outcome: `converged` / `close` / `needs-human`,
+4. **triages** anything it cannot safely convert — never silently emits
+   plausible-wrong code.
+
+Never describe output as "pixel-accurate/perfect" in any report.
+
+## When to use / not use
+
+Use for: porting a web/H5 frontend to native SwiftUI; "make this a real iOS
+app (not a webview)"; measured visual migration. Not for: building a webview
+wrapper (decline — out of scope); generic SwiftUI feature work (use normal
+dev flow); design-mock→code with no source app (different problem).
+
+## Inputs
+
+- `<path-to-h5-source>` (required)
+- `--ios-floor` (default `17`; changes API availability + risk tiers)
+- `--device` (default `iPhone 15 Pro`; sets logical viewport + safe-area)
+- `--max-iter` (default `3`; Stage 5 per-component iteration cap)
+- `--thresholds` (optional override; default = **calibrated**, not asserted)
+
+## Environment reality (hard gate)
+
+Stage 5 needs macOS + Xcode + iOS Simulator. If absent OR the generated
+project fails to build, the affected component is `needs-human`/`blocked`
+and is **never counted converged**. The skill must not fabricate
+convergence. Stages 0–4 + triage still run and produce value.
+
+## Pipeline (Stage 0–7) — product contracts
+
+All stage products go under the *target project*'s `.h5-to-swiftui/` work
+dir (inspectable, resumable). Every convergence artifact header pins
+`sim_runtime`, `browser_version`, `model_id`, `temperature:0` — re-runs must
+reproduce the same **verdict** (not the same pixels).
+
+| Stage | Does | Key output |
+|---|---|---|
+| 0 Intake + detect + **v1 gate** | `scripts/detect-stack.mjs`; framework ∉ {vanilla,React} ⇒ write report & **STOP** (no guess) | `stack-report.json` |
+| 1 Static analysis + facts + risk | inventory; `scripts/extract-tokens.mjs` (static∪runtime DTCG); risk triage pass *before* any generation; token-miss ⇒ `token-gaps.json` (never inline) | `pages/components/state-model/api/tokens/token-gaps/risk-triage.json` |
+| 2 Reference capture | `scripts/capture-reference.mjs` (Playwright, iOS viewport, animations frozen, webfont/async settle, masks, browser pinned) | `reference/**`, `reference/manifest.json` |
+| 2.5 **Render-equivalence calibration** | `scripts/calibrate-render.mjs` on bundled known-correct pair → normalization + **measured floor**; unmeasurable ⇒ `blocked.json` | `calibration.json` → see `references/render-equivalence-calibration.md` |
+| 3 Scaffold | Xcode skeleton; `DesignTokens` (DTCG→Color/Font/spacing/radius + `.colorset` dark); router→`NavigationStack`; state skeleton | compiling skeleton |
+| 4 Per-component rewrite | LLM rewrites each component using **only** token vocab + `references/css-to-swiftui-map.md`; **each component MUST emit a snapshot host** (isolated render entry); idiomatic-lint rejects `.position/.offset`-pinned layouts; Tier-3 ⇒ non-compiling `fatalError` stub | per-component `.swift` + host |
+| 5 **Convergence loop** ★ | per component: host-render→normalize(calibration)→cascade diff (`pixel-diff.mjs`)→feedback payload→structured patch→recompile→re-measure; cap `--max-iter`. **The verdict is emitted ONLY by `scripts/evaluate-convergence.mjs`** — it mechanically enforces every anti-gaming guard and exits non-zero on any violation; the LLM never hand-writes `convergence/<component>.json` | `convergence/<component>.json` (written by `evaluate-convergence.mjs`) → see `references/visual-diff-loop-protocol.md` |
+| 6 Behavioral parity | port `URLSession` async / Keychain tokens / ATS-flag `http://` / state / models; equivalence checks | `parity-report.json` |
+| 7 Assemble + honest report | build; aggregate; summary leads with `needs-human` if it dominates | Xcode project + `conversion-report.json` + `convergence-summary.json` |
+
+## Hard rules (non-negotiable)
+
+- **No silent failure.** Tier-3 surfaces (WebGL/WebGPU, RAF physics, WebRTC,
+  payments/secrets, analytics/ATT) ⇒ non-compiling `fatalError` stub +
+  machine-readable entry in `conversion-report.json`. See
+  `references/high-risk-triage.md`.
+- **Anti-gaming (Stage 5) — ENFORCED IN CODE by
+  `scripts/evaluate-convergence.mjs`** (the sole thing that may emit the
+  verdict; it exits non-zero on any violation so a pipeline cannot ignore a
+  failed gate): the calibration gate is **recomputed from `calib.floor`** and
+  a hand-loosened gate is rejected (`gate-floor-mismatch`, exit 1 — this binds
+  the *gate to the floor*, not the floor's value); the **identity of the
+  bundled twin source files** (excluding build output/dotfiles) is bound via
+  `calibration_source` source-tree hashes recomputed from
+  `assets/calibration/{h5-twin,swiftui-twin}` (`calibration-twin-mismatch`,
+  exit 1 — binds the twin *source identity*, not the measured floor value);
+  the `floor` *value* is asserted to satisfy `calibrate-render.mjs`'s own
+  sanity envelope via the shared `scripts/_calib-consts.mjs`
+  (`floor-implausible`, exit 1 — a floor calibrate-render could not have
+  emitted is rejected, killing the absurd-floor attack; a floor *within* that
+  envelope but looser than the true measured one is a disclosed residual, see
+  below); the judge **negative control is bound** to the shipped, hash-pinned
+  `assets/calibration/swiftui-twin-divergent` source files (structured
+  `{stimulus_source_hash,rejected,differences}` under **forced-difference-3**;
+  the legacy bare string is rejected and an unbound control VOIDs any `YES`);
+  mask budget ≤10% with a non-empty reason per mask; the structured gate is
+  evaluated per iteration (a text-region `iou` of `null` is a FAIL; pHash is
+  necessary-not-sufficient and never short-circuits); best-of-N retains
+  **only built + gate-passing iterations** chosen by the script
+  (monotone-or-fail; caller's pick ignored); a present `blocked.json` or no
+  built+passing iteration ⇒ never converged. **Named irreducible residuals
+  (honest, §1.1) — BOTH disclosed:** (1) the grader cannot re-run the
+  simulator, so it trusts the per-iteration `pixel-diff.mjs` JSONs were
+  produced by the real `pixel-diff.mjs` on real `sim-screenshot.sh` renders
+  (bounded by that script's no-fake spine); (2) the grader cannot re-measure
+  the calibration floor — it asserts the supplied `floor` is within
+  `calibrate-render.mjs`'s own sanity envelope and recomputes the gate from
+  it, but a floor *within* that envelope yet looser than the true measured
+  floor is trusted, mitigated by the orchestrator's obligation to run the
+  real, sanity-spined `calibrate-render.mjs` and the recorded
+  `calibration_provenance`. Maximally provenance-bound, not zero-trust. The
+  **whole-assembled-screen SSIM-trend check is NOT an automated Stage-5
+  guard** — see the known limitation below; it is a documented **Stage-7
+  manual** cross-check.
+- **Calibrated, not asserted.** Stage 5 gates against the **measured** floor
+  from `calibration.json`, never a hardcoded SSIM constant.
+- **v1 scope.** Mapping authored for vanilla + React only; other detected
+  stacks stop at Stage 0 with an explicit report.
+- **Compile-failure branch.** Non-building patch ⇒ revert to best
+  gate-passing iteration, consume an iteration; terminal ⇒ `needs-human`.
+
+## References (read on demand — progressive disclosure)
+
+- `references/stack-detection.md` — detection heuristics, why rewrite > webview/transpile, v1 gate
+- `references/design-token-extraction.md` — static∪runtime DTCG pipeline, token-gap rule
+- `references/css-to-swiftui-map.md` — flex/grid/positioning/box-model tables, custom-`Layout` triggers
+- `references/render-equivalence-calibration.md` — Stage 2.5 normalization + floor measurement + `calibration.json` schema
+- `references/visual-diff-loop-protocol.md` — Stage 5 mechanism, payload + artifact schemas, tiered verdict, anti-gaming
+- `references/high-risk-triage.md` — Tier 1/2/3 catalog, stub format, `conversion-report.json` schema
+
+## Scripts
+
+`detect-stack.mjs` `extract-tokens.mjs` `capture-reference.mjs`
+`calibrate-render.mjs` `pixel-diff.mjs` `mark-overlay.mjs`
+`evaluate-convergence.mjs` `sim-screenshot.sh` — each supports `--help`;
+capability/build probes degrade to an explicit block, never a fake success.
+
+`scripts/evaluate-convergence.mjs` is the **sole executable convergence
+authority**: it consumes the per-iteration `pixel-diff.mjs` JSON, the
+structured `calibration.json` gate, the masks, and the judge result, then
+mechanically decides the tier and **exits non-zero** (3 = needs-human/guard
+violation, 4 = blocked) so the verdict cannot be faked or ignored. The
+orchestrator MUST call it and MUST NOT hand-write `convergence/<component>.json`.
+
+### Known limitation (honest)
+
+The **whole-assembled-screen SSIM-trend check** described in `spec.md` is
+**not** an automated Stage-5 guard — there is no executable component that
+diffs the assembled screen during the loop, so advertising it as active
+would be a prose-only claim. It is instead a **Stage-7 manual cross-check**:
+after assembly, a human (or a separate verification pass) compares the
+assembled-screen capture against the reference so per-component `converged`
+results cannot mask a broken composition. Treat per-component verdicts as
+authoritative only at component granularity until that Stage-7 check is done.
+
+## Assets
+
+`assets/calibration/` — known-correct SwiftUI screen (`swiftui-twin/`) + H5
+twin (`h5-twin/`) for Stage 2.5, plus a deliberately-wrong
+`swiftui-twin-divergent/` used as the Stage-5 judge **negative control**.
+Calibration content is **textured** (text + a 4-stripe multi-color region),
+never flat solids, so SSIM is meaningful (`calibrate-render.mjs` blocks a
+flat pair). `assets/sample-h5-vanilla/` + `assets/sample-h5-react/` are the
+dry-run fixtures (the React one is the text-heavy / custom-`Layout` / Tier-3
+hard path).
+
+## Done = evidence
+
+A run is complete only with: `stack-report.json`, `calibration.json` (finite
+floor), per-component `convergence/*.json` (pinned-version header, iteration
+history, masks, negative-control result, tiered verdict),
+`conversion-report.json`, and an honest `convergence-summary.json`. No
+success claim without these.

package/.local/skills/h5-to-swiftui/assets/calibration/README.md

@@ -0,0 +1,176 @@
+# Stage 2.5 Calibration Pair
+
+This directory contains a **hand-built, known-correct calibration pair** for
+the `h5-to-swiftui` skill's render-equivalence calibration stage. The two
+sides (`h5-twin/` and `swiftui-twin/`) render the **same intended design** on
+an iPhone 15 Pro logical viewport (393×852 pt).
+
+> **Key principle:** any measured rendering difference between these two sides
+> is the **irreducible cross-renderer floor** — not a defect. The pair is
+> equivalent by construction, so the floor reflects only the unavoidable
+> divergence between WebKit/Skia glyph rasterization and CoreText/Metal
+> rendering, color-space pipeline differences (sRGB vs Display-P3), and
+> sub-pixel sampling. Never grade real conversion screens against a tighter
+> bound than this measured floor.
+
+---
+
+## Contents
+
+| Path | Description |
+|---|---|
+| `h5-twin/index.html` | Static H5 page — open directly, no build step |
+| `h5-twin/style.css` | All design tokens as CSS custom properties (`--*`) |
+| `swiftui-twin/Package.swift` | Swift Package manifest (Swift 5.9+, iOS 17+) |
+| `swiftui-twin/Sources/CalibrationScreen/CalibrationScreen.swift` | `CalibrationScreenView` + `#Preview` — the **known-correct** SwiftUI side |
+| `swiftui-twin-divergent/Package.swift` | Swift Package manifest for the negative control |
+| `swiftui-twin-divergent/Sources/CalibrationScreenDivergent/CalibrationScreenDivergent.swift` | **Deliberately WRONG** SwiftUI screen — the Stage 5 judge **negative control** |
+| `tokens.json` | Ground-truth DTCG-style token map — the single source of truth |
+| `.gitignore` | Ignores Swift Package `.build/` (never commit build output) |
+| `README.md` | This file |
+
+### The divergent twin (negative control)
+
+`swiftui-twin-divergent/` is **intentionally wrong** versus the H5 twin:
+wrong colors (green background, blue circle, recolored stripes, inverted text
+colors), shifted layout (much larger top inset, doubled section gap, circle
+moved to the trailing edge, near-square taller card), and different copy.
+
+Its role: the Stage 5 **independent judge must REJECT** the pair
+(`h5-twin` vs `swiftui-twin-divergent`) under the adversarial
+forced-difference-3 framing. If the judge instead calls them equivalent, the
+run's `judge.negative_control` is recorded as **`failed`** and any `YES`
+verdict is **VOID** for that run. This is enforced mechanically — not by
+prose — in `scripts/evaluate-convergence.mjs` (guard 4).
+
+### Textured-content requirement (NOT flat solids)
+
+The bundled calibration content **must be textured** — text plus a
+multi-color structured region. Flat solid blocks make SSIM **insensitive to a
+uniform mean shift**: a clearly-divergent solid pair can still score ~0.95,
+yielding a falsely-high floor. The card is therefore a **4-stripe multi-color
+region** (blue/purple/teal/amber), not a single solid block, on every side
+(`h5-twin`, `swiftui-twin`, `swiftui-twin-divergent`).
+`scripts/calibrate-render.mjs` additionally **blocks** (writes `blocked.json`,
+exits 1) if BOTH normalized images are effectively flat (near-zero luma
+variance) — so a flat calibration pair can never produce a trusted floor.
+
+---
+
+## Design Tokens
+
+All values are shared across both sides. `tokens.json` is the authoritative
+source; `style.css` and `CalibrationScreen.swift` must match it exactly.
+
+### Colors
+
+| Token | Hex | CSS var | Swift `Color(red:green:blue:)` |
+|---|---|---|---|
+| `color.background`  | `#F2F2F7` | `--color-background`   | `r=0.9490 g=0.9490 b=0.9686` |
+| `color.card`        | `#4A90D9` | `--color-card`         | `r=0.2902 g=0.5647 b=0.8510` |
+| `color.circle`      | `#E8744F` | `--color-circle`       | `r=0.9098 g=0.4549 b=0.3098` |
+| `color.textHeading` | `#1C1C1E` | `--color-text-heading` | `r=0.1098 g=0.1098 b=0.1176` |
+| `color.textBody`    | `#636366` | `--color-text-body`    | `r=0.3882 g=0.3882 b=0.4000` |
+| `color.stripeA`     | `#4A90D9` | `--color-stripe-a`     | `r=0.2902 g=0.5647 b=0.8510` |
+| `color.stripeB`     | `#7E57C2` | `--color-stripe-b`     | `r=0.4941 g=0.3412 b=0.7608` |
+| `color.stripeC`     | `#26A69A` | `--color-stripe-c`     | `r=0.1490 g=0.6510 b=0.6039` |
+| `color.stripeD`     | `#F4B400` | `--color-stripe-d`     | `r=0.9569 g=0.7059 b=0.0000` |
+
+The card is a **4 equal-width vertical stripe** region (A→D, left to right),
+not a flat solid — see the textured-content requirement above.
+
+### Spacing (CSS px = Swift pt at 1× logical scale)
+
+| Token | Value | CSS var | Swift constant |
+|---|---|---|---|
+| `space.safeTop`     | 59 px/pt | `--space-safe-top`    | `spaceSafeTop = 59` |
+| `space.pageH`       | 20 px/pt | `--space-page-h`      | `spacePageH = 20` |
+| `space.sectionGap`  | 24 px/pt | `--space-section-gap` | `spaceSectionGap = 24` |
+| `space.cardPadding` | 20 px/pt | `--space-card-padding`| `spaceCardPadding = 20` |
+| `space.cardGap`     | 16 px/pt | `--space-card-gap`    | `spaceCardGap = 16` |
+
+### Radii
+
+| Token | Value | CSS var | Swift constant |
+|---|---|---|---|
+| `radius.card` | 16 px/pt | `--radius-card` | `radiusCard = 16` |
+
+### Typography
+
+| Token | Value | CSS | Swift |
+|---|---|---|---|
+| `font.family`            | `-apple-system` | `font-family: -apple-system, system-ui` | `.system(size:weight:)` |
+| `font.sizeHeading`       | 22 px/pt | `font-size: 22px` | `.system(size: 22, weight: .semibold)` |
+| `font.weightHeading`     | 600 / semibold | `font-weight: 600` | `.semibold` |
+| `font.lineHeightHeading` | 1.27× | `line-height: 1.27` | `lineSpacing: 22 × 0.27 ≈ 5.9 pt` |
+| `font.sizeBody`          | 15 px/pt | `font-size: 15px` | `.system(size: 15, weight: .regular)` |
+| `font.weightBody`        | 400 / regular | `font-weight: 400` | `.regular` |
+| `font.lineHeightBody`    | 1.47× | `line-height: 1.47` | `lineSpacing: 15 × 0.47 ≈ 7.1 pt` |
+
+### Shape
+
+| Token | Value | CSS var | Swift constant |
+|---|---|---|---|
+| `shape.circleSize` | 64 px/pt | `--size-circle` | `sizeCircle = 64` |
+
+---
+
+## Screen layout (both sides)
+
+```
+┌─────────────── 393 pt ───────────────┐
+│                                       │
+│  ← 59 pt top safe-area inset →       │
+│                                       │
+│  ┌─ 20pt padding ──────────────────┐ │
+│  │  Calibration Screen             │ │  ← heading 22pt semibold #1C1C1E
+│  │  This screen is the known-…     │ │  ← body 15pt regular #636366
+│  └─────────────────────────────────┘ │
+│                                       │  ← 24pt gap
+│  ┌─ 20pt padding ──────────────────┐ │
+│  │  ┃A┃B┃C┃D┃ 4-stripe card r=16pt │ │  ← stripes #4A90D9 #7E57C2
+│  │  ┗━┻━┻━┻━┛  (textured, 40pt h)  │ │     #26A69A #F4B400
+│  │  ●  ← #E8744F circle 64×64pt   │ │  ← 16pt gap below card
+│  └─────────────────────────────────┘ │
+│                                       │
+└───────────────────────────────────────┘
+  total height: 852 pt
+```
+
+---
+
+## How to run
+
+**H5 twin** — open `h5-twin/index.html` directly in a browser. No build step.
+Set browser viewport to 393×852. (Playwright capture uses `--viewport 393x852`.)
+
+**SwiftUI twin** (known-correct) — requires Xcode 15+ or Swift 5.9+ with iOS SDK:
+
+```bash
+cd swiftui-twin && swift build
+```
+
+**Divergent twin** (negative control) — same toolchain:
+
+```bash
+cd swiftui-twin-divergent && swift build
+```
+
+Preview in Xcode: open either package; the `#Preview` renders the screen in
+an iPhone 15 Pro simulator. `.build/` is gitignored — never commit it.
+
+---
+
+## Updating this pair
+
+If any token value is changed:
+1. Update `tokens.json`.
+2. Update the matching `--*` custom property in `h5-twin/style.css`.
+3. Update the matching constant in `swiftui-twin/.../CalibrationScreen.swift`.
+4. Re-run Stage 2.5 calibration to re-measure the floor.
+
+The known-correct trio (`tokens.json`, `h5-twin/style.css`,
+`swiftui-twin/.../CalibrationScreen.swift`) must stay in sync; `tokens.json`
+is the single source of truth. The **divergent twin is intentionally NOT in
+sync** — its job is to differ; only keep it textured (text + stripes) and
+buildable.