@openora/create 0.4.1-canary.34 → 0.4.1-canary.340

package/template/__dot__rulesync/skills/ship/SKILL.md.tpl

@@ -0,0 +1,157 @@
+---
+name: ship
+targets: ['*']
+description: >
+  Take one {{trackerKey}} ticket from plan to a green, reviewed MR with nobody in the loop: planner
+  plans it with test cases, builder builds it, tester attacks it, the reviewers review it, then it
+  pushes the ticket branch, opens the MR, moves the ticket and watches the MR until it is ready for a
+  person to review. Resumable: every run reads the ticket,
+  branch, MR and CI and does the next step, including fixing a red pipeline or new review comments.
+  Stops only on a question or a blocker. Use on "ship {{trackerKey}}-XXX", "add feature", "deliver
+  {{trackerKey}}-XXX", or /ship {{trackerKey}}-XXX [--ask].
+---
+
+# ship ({{name}})
+
+The orchestrator: one ticket key in, a green MR in Code Review out. You own the ticket's whole delivery, plan to review: you are done when the MR is ready for a person to review it (step 7), not when it is opened. You run in the main session and are the only one who delegates. You hand each step to its subagent, read its verdict, and pick the next step yourself - never wait for a person between steps. Every subagent you start is told it starts no subagents of its own; a domain question one of them returns comes back to you, you ask `expert`, and you pass the answer on.
+
+## Coordinates
+
+- Jira: per `docs/agents/issue-tracker.md`, project `{{trackerKey}}`. Code forge: `{{gitRemotePath}}`, target `{{mrTarget}}`, commands in `docs/agents/forge.md`.
+- `{{ossDir}}` (the linked OSS checkout) is read-only. Core-only work goes through `handoff.md`.
+
+## Arguments
+
+- `{{trackerKey}}-XXX` from `$ARGUMENTS`. None: ask for it, that is the one question this skill always asks.
+- `--ask`: stop for approval after the plan and before the push. Without it, invoking `/ship` is the authorization for every write below - and only those.
+
+## What ship may write without asking
+
+- Jira, on this ticket only: the Plan comment (and its test cases where the repo's `test-plan` skill keeps them), a questions comment, a blocker comment, the MR link comment, and the transitions to In Progress and to Code Review. Nothing else: no field edits, no other transitions, no other tickets.
+- Git: commits on the ticket branch `<type>/{{trackerKey}}-XXX/<slug>` and pushing it. Never a push to `{{mrTarget}}`, `stage`, `prod` or any shared branch.
+- Force-push: only `git push --force-with-lease` on the ticket branch, and only while every commit on the remote branch past `{{mrTarget}}` is your own (`git log --format=%ae origin/{{mrTarget}}..origin/<branch>` shows only your `git config user.email`). Someone else's commit there: merge, never push over it. Never a plain `--force`.
+- Merging: into a feature branch only (`{{mrTarget}}` merged into the ticket branch to clear conflicts, a stacked MR into its parent ticket branch). Never into `{{mrTarget}}`, `dev`, `develop`, `stage`, `staging`, `prod`, `production`, `main` or `master`.
+- The forge: opening the MR for that branch and replying on its review threads. Every comment you leave starts with `Agent:`, so `watch-pr.mjs` and other tools never take it for one to answer.
+- Slack: nothing. Announcing the MR is the forge integration's job, so ship never drafts a notice.
+
+## Do what the work needs, inside the worktree
+
+Never stop to ask for something local that deleting the worktree undoes: do it, and say what you did in the reply and the MR description.
+
+- Env: a variable the change needs goes into the worktree's `.env` with a local dev value, and into every place the repo declares one (env schema, `.env.example`, deploy docs) in the same commit. A value only a person has (a real API key, a prod URL): a dev placeholder or a mock locally, and a "Needs before deploy" line in the MR description. If no test can run without the real one, that is a blocker.
+- Dependencies: add what the plan needs with the repo's package manager and commit the lockfile. A repo rule that asks for a step first (unlink a locally linked package, then link it back) is followed, so the lockfile carries no local links; it is never a reason to stop.
+- Data: the worktree's own database and Redis db - create, migrate, seed and reset them freely. Migrations come from the repo's generator, generated files from its regen command.
+- Processes and tools: start what the tests need on the worktree's own ports and stop it before you report; install a local tool the repo's docs name (browsers for Playwright and the like).
+
+## Access outside the repo
+
+The plan's Access list names every account or session outside the repo the work needs (a cloud CLI profile, a provider's dashboard, a sandbox API), each with what it is for, a read-only check that proves the session works and the login a person runs. Before 2, every run runs each check:
+
+- One fails -> `Asked:` on its own line, then each missing login as the command a person runs (`! aws sso login --profile <p>`) or the page to log in to in the browser. Report it, stop; no ticket comment. `/ship {{trackerKey}}-XXX` again picks up from here.
+- All pass -> read what it names freely. A passing check is not consent to change anything there, and neither is an Access list built from the ticket. Before the first change outside the repo (create, configure, delete, issue a key): `Asked:`, then one line per change - account, resource, what changes - report it, stop. A person's yes in this session covers that exact list; anything not on it, or a new run, asks again. Then make the changes and put a dev key it issues in the worktree's `.env`.
+- Every change outside the repo goes in the reply and the MR description under "Outside the repo", one line each: where, what, how to undo it. A change to something that already existed records its old value.
+
+## Never, however blocked
+
+Anything shared, remote, or not undone by deleting the worktree, unless a person approved that exact change (see Access outside the repo):
+
+- Servers, ssh, cloud accounts, dashboards, deploys, stage and prod, and any database that is not the worktree's own.
+- CI/CD settings and variables, repo settings, other people's branches and MRs.
+- Anything this run did not create, in the repo or outside it: no drop, flush, kill or delete.
+- Secrets: never commit, print or invent a real-looking one; a `.env` with real values stays uncommitted.
+- Gates: no `--no-verify`, no skipped or loosened test, lint rule or guard hook, no hand edit to a generated file or `node_modules`.
+
+Blocked by one of these: `Blocked:` with what is needed and who can do it. Every subagent you start gets both lists.
+
+## Read the state, do the next step
+
+Every run starts here, so a run that died midway resumes where it stopped. Read the ticket per `docs/agents/issue-tracker.md`, then `git branch -a --list '*{{trackerKey}}-XXX*'`, then the MR for that branch and its CI per `docs/agents/forge.md`.
+
+| State                                       | Next step                                   |
+| ------------------------------------------- | ------------------------------------------- |
+| No Plan comment on the ticket               | 1. Plan                                     |
+| Plan, no branch                             | 2. Build                                    |
+| Branch, no MR                               | 3. Test, 4. Review, 4b. Evidence, 5. Open the MR |
+| MR open, CI red or conflicts                | 6. `fix-pipeline` skill                     |
+| MR open, review threads with no reply       | 6. `fix-review-comments` skill              |
+| MR open, CI running, or green and answered  | 7. Ready for review                         |
+| MR merged or closed                         | Report it, do nothing                       |
+
+A comment added to the ticket after the Plan comment that changes scope sends you back to 1.
+
+### 1. Plan
+
+Start `planner` with the ticket key. It returns either `Asked:` with questions, or the plan.
+
+- `Asked:` -> post the questions as one comment on the ticket, report them, stop.
+- A plan -> post it, without its Core-only section, as one comment titled "Plan" (test cases where the repo's `test-plan` skill keeps them, if it has one), move the ticket to In Progress. `--ask`: show it and stop for approval.
+- A Core-only section -> write the work order per `handoff.md` and drop that slice; ship the rest.
+
+### 2. Build
+
+Add a worktree for the ticket branch off the freshly fetched `{{mrTarget}}`, per the repo's worktree rules (its own database and Redis db). Start `builder` in it with the plan. Run the **create-plugin** skill's steps through it for each overlay, adapter or page slice.
+
+- `Blocked:` -> post the reason as one comment on the ticket, report it, stop.
+- Done -> check its reply holds the gate output from HEAD and `git status` is clean. Missing either: send it back once to run the gate, then treat it as blocked.
+
+### 3. Test
+
+Start `tester` in the worktree with the plan's test cases, for its verify pass: no videos yet. It returns an AC table.
+
+- Every row PASS -> 4.
+- Any FAIL -> back to `builder` with the failing rows only, then `tester` again.
+- UNCHECKED rows ride along to the MR description; they do not block, except a case or a mutation row on a money, KYC, responsible-gambling or authz path: back to `tester` once to run it, still UNCHECKED -> blocker comment, report it, stop.
+- A SURVIVED mutation row is a FAIL: back to `builder` with the row (the test that catches it, or the code that makes it testable), then `tester` again. A money, KYC, responsible-gambling or authz change with no mutation rows goes back to `tester` once to add them.
+- A failing spec called pre-existing without its run on the base commit -> back to `tester` once to run it there. Still unrun: it is a FAIL.
+
+### 4. Review
+
+Run the **review** skill on the branch against `{{mrTarget}}`, without `--post`: its precheck, risk tier, request trace and evidence gate run before any reviewer reads the diff. Hand its reviewers the tester's AC table, mutation rows included, so they dig where testing could not reach. This is the self-review the MR is opened on: people reviewing the MR later read it by hand and do not run an AI review again, so nothing goes out that this step has not passed.
+
+Every finding with a fix gets fixed, whatever its severity, but only once it holds. Dedupe across reviewers, then check each yourself before anything changes: open its `file:line` and confirm the evidence on this branch. One that doesn't hold (wrong line, the code already handles it, a claim the code doesn't show) is dropped and goes to the MR description with why. A product call the ticket doesn't settle goes to `expert`, then is fixed or rides along as an open question. Send the rest to `builder` in one go, then 3 for the cases they touch and 4 again. A later round of 4 reviews only the commits since the last one and whether each sent finding is fixed. Clean means the review skill says **APPROVED** and no finding is left that holds; only then 4b.
+
+Rounds of 3 and 4 share one budget: three. After the third with anything still failing, post a blocker comment naming what is left, report it, stop.
+
+### 4b. Record evidence
+
+The code is final now, so the videos are recorded once, here, never in an earlier round. Start `tester` for its evidence pass on HEAD: every browser spec that drives an AC, new or existing, runs once with video on, `playwright-cli` only for an AC no spec drives. It returns the clip paths per AC.
+
+- A spec that fails here -> back to `builder` with it, then 3 for the cases it touches, 4 on the new commits, 4b again. That round counts against the same budget of three.
+- Every AC that needs a clip has one -> 5.
+
+### 5. Open the MR
+
+`--ask`: report the SHA and stop for "yes push". Then run **create-pr** with the tester's AC table, the 4b videos and its Tests list. Comment the MR link on the ticket and move it to Code Review in the same turn. Then 7.
+
+### 6. Red CI and review comments
+
+Run the repo's `fix-pipeline` skill on a red pipeline or conflicts, `fix-review-comments` on unanswered threads from a person or a bot. No such skill in this repo: do the same per `docs/agents/forge.md`. Under `/ship` they run like this:
+
+- Each thread is checked against the code on this branch first: correct | already handled | wrong on this branch | out of scope. Only a correct one changes code; the rest get an answer.
+- A red job is reproduced locally first; `builder` fixes its cause. Never skip or loosen a test.
+- Every fix goes to `builder`. Then `tester` re-runs the cases the fix touches and leaves a test that fails without it, and 4 runs on the new commits. Then 4b records again only the ACs the fix touched, and their clips replace the old ones in the MR description. Nothing is pushed untested.
+- Push the ticket branch without asking (a force-push only as above). Reply per thread, in the thread itself, with what changed and the test that proves it, or why nothing changed. Resolve only a thread the fix addressed; a question or a disagreement stays open for the reviewer.
+
+Then 7.
+
+### 7. Ready for review
+
+Start `node <this skill's folder>/watch-pr.mjs <branch> --until-green` as a background command, never a sleep loop in the session. It prints one line and exits when there is work:
+
+- `failed` or `conflicts` -> 6, then watch again. Still red after three fixes -> blocker comment, report, stop.
+- `threads <ids>` (unanswered for two checks in a row, from a person or a bot) -> 6 for those, then watch again. A thread the forge's AI review opens is a blocker it found on this head: it counts like a person's.
+- `green` -> check the MR is ready (below), report "Ready for review:" and the MR URL, then watch again without `--until-green`.
+- `merged` or `closed` -> report it, drop the worktree's database and Redis db, stop. `error ...` -> report it, stop.
+
+Ready means: the pipeline on the last commit is green, no conflicts with `{{mrTarget}}`, every thread has an answer, no money, KYC, responsible-gambling or authz case or mutation row is UNCHECKED or SURVIVED, and the description holds the AC table, the screenshots and the UNCHECKED rows.
+
+Keep watching until the MR merges or closes, for as long as the session lives. You never merge it: who approves and who merges is in `docs/agents/forge.md`. A caller that says it watches the MR itself (a headless run) gets the report at `green`, and you stop there; it brings the ticket back through `/ship {{trackerKey}}-XXX`, which lands on 6.
+
+## Rules
+
+- One ticket, one branch, one MR.
+- You edit no code, commit nothing and run no gate yourself, however small the fix: every fix goes to `builder`. Code changed after 3 means 3 runs again for the cases it touches, and 4 for the new commits.
+- A subagent that stops short (no gate output, uncommitted work) goes back to it once, never finished by you.
+- Never claim a step passed without its output: the gate from HEAD, the AC table, the review findings.
+- A run you resume with a branch but no MR re-runs 3 and 4: verdicts from a dead run are gone.
+- Clean up what the run started: worktree databases and Redis dbs stay for the next round until the MR merges; processes you started stop before you report.

package/template/__dot__rulesync/skills/ship/handoff.md.tpl

@@ -0,0 +1,48 @@
+# OSS core handoff
+
+When a `ship` work item can only be fixed in `@openora/*` core, this consumer repo cannot edit it (the `guard-core.mjs` hook and `permissions.deny` block `{{ossDir}}/**`). Hand off to the platform-core twin skill instead of fighting the guard.
+
+## When to hand off
+
+- The fix requires changing a contract, schema, service, router, or platform seam in `@openora/*`.
+- An overlay plugin / adapter swap / UI provider override / config change genuinely cannot express the behavior.
+- Default bias: extend from the outside first; hand off only when you've confirmed the outside-in path doesn't exist. If unsure, the planner says so in the plan; without a clear core-only reason, build it from the outside.
+
+## Work-order template
+
+Write to `~/.claude/plans/<ticket-key>-oss.md` so both repos and future sessions can read it:
+
+```markdown
+# OSS work order - <ticket-key>: <title>
+
+## Goal
+
+<what core must do, 1-2 lines>
+
+## Unblocks
+
+{{name}} feature <ticket-key> - <which downstream slice depends on this>
+
+## Core surface to change
+
+- <package / module / contract / adapter token, as specific as possible>
+
+## Contract / schema impact
+
+- <new or changed oRPC contracts, Drizzle tables, events; or "none">
+
+## Acceptance
+
+- <observable outcomes that prove the core change is correct>
+
+## Dependency
+
+{{name}} MR <url-or-TBD> stays in draft until this merges and a new @openora/core/\* version is consumed.
+```
+
+## Protocol
+
+1. This consumer repo writes the work-order and **stops** that slice (keep delivering independent downstream slices meanwhile).
+2. The user runs `/ship` inside the platform OSS repo (`{{ossDir}}`, separate cwd/session). It reads the work-order, implements, and opens its own MR there.
+3. The consumer MR stays draft/blocked until the OSS MR merges and the consumer bumps the consumed `@openora/*` version. Link the two by the work-order path and the ticket key.
+4. Note the handoff in the Jira ticket and the consumer MR description so the dependency is visible.

package/template/__dot__rulesync/skills/ship/watch-pr.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// Watches the MR or PR of a branch and prints one line, then exits, when ship has work on it:
+//   failed | conflicts | threads <ids> | green (only with --until-green) | merged | closed | error <message>
+// A thread waits for an answer until its last comment is an "Agent:" reply from the account this runs as
+// (anyone can type the prefix); it is reported once it stayed the same for two checks, so a review with
+// ten comments is one line. Run it in the background:
+//   node watch-pr.mjs <branch> [--until-green]        WATCH_DEBUG=1 prints every check to stderr
+// --once checks one time, for a caller that polls on its own (a scheduler): threads are reported at
+// once, and `none` means nothing to do.
+import { execFileSync } from 'node:child_process';
+
+const EVERY_MS = 120_000;
+// ponytail: a repo with no CI on the last commit reads green after this; a head-SHA match on checks if it matters
+const NO_CI_MS = 10 * 60_000;
+const MAX_ERRORS = 5;
+const AGENT_REPLY = 'Agent:';
+const FAILED = [
+  'FAILURE',
+  'ERROR',
+  'CANCELLED',
+  'TIMED_OUT',
+  'ACTION_REQUIRED',
+  'STARTUP_FAILURE',
+  'failed',
+  'canceled',
+];
+
+const [branch, ...flags] = process.argv.slice(2);
+if (!branch) {
+  console.error('usage: watch-pr.mjs <branch> [--until-green | --once]');
+  process.exit(2);
+}
+const untilGreen = flags.includes('--until-green');
+const once = flags.includes('--once');
+
+const run = (cmd, args) =>
+  execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const json = (cmd, args) => JSON.parse(run(cmd, args));
+const unansweredIds = (lastComments, me) =>
+  lastComments
+    .filter(
+      (comment) => !(comment.author === me && comment.body.trimStart().startsWith(AGENT_REPLY)),
+    )
+    .map((comment) => String(comment.id))
+    .sort();
+
+const THREADS = `query($owner: String!, $name: String!, $number: Int!, $endCursor: String) {
+  viewer { login }
+  repository(owner: $owner, name: $name) { pullRequest(number: $number) {
+    reviewThreads(first: 100, after: $endCursor) {
+      nodes { isResolved comments(last: 1) { nodes { id body author { login } } } }
+      pageInfo { hasNextPage endCursor }
+    }
+    comments(last: 1) { nodes { id body author { login } } }
+  } }
+}`;
+
+function github() {
+  const pr = json('gh', [
+    'pr',
+    'view',
+    branch,
+    '--json',
+    'number,url,state,mergeable,statusCheckRollup',
+  ]);
+  const [, owner, name] = new URL(pr.url).pathname.split('/');
+  const args = [
+    'api',
+    'graphql',
+    '--paginate',
+    '--slurp',
+    '-f',
+    `query=${THREADS}`,
+    '-f',
+    `owner=${owner}`,
+    '-f',
+    `name=${name}`,
+    '-F',
+    `number=${pr.number}`,
+  ];
+  const pages = json('gh', args).map((page) => page.data);
+  const open = pages
+    .flatMap(({ repository }) => repository.pullRequest.reviewThreads.nodes)
+    .filter((thread) => !thread.isResolved)
+    .flatMap((thread) => thread.comments.nodes)
+    .concat(pages[0].repository.pullRequest.comments.nodes)
+    .map((comment) => ({ ...comment, author: comment.author?.login }));
+  const checks = pr.statusCheckRollup ?? [];
+  const ci = !checks.length
+    ? null
+    : checks.some((check) => FAILED.includes(check.conclusion || check.state))
+      ? 'failed'
+      : checks.some((check) =>
+            check.status
+              ? check.status !== 'COMPLETED'
+              : check.state === 'PENDING' || check.state === 'EXPECTED',
+          )
+        ? 'running'
+        : 'passed';
+  return {
+    state: pr.state.toLowerCase(),
+    conflicts: pr.mergeable === 'CONFLICTING',
+    ci,
+    unanswered: unansweredIds(open, pages[0].viewer.login),
+  };
+}
+
+function gitlab() {
+  const mr = json('glab', ['mr', 'view', branch, '-F', 'json']);
+  const discussions = run('glab', [
+    'api',
+    '--paginate',
+    '--output',
+    'ndjson',
+    `projects/${mr.project_id}/merge_requests/${mr.iid}/discussions?per_page=100`,
+  ])
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  const open = discussions
+    .map((discussion) => discussion.notes.filter((note) => !note.system))
+    .filter(
+      (notes) =>
+        notes.length &&
+        !(
+          notes.some((note) => note.resolvable) &&
+          notes.every((note) => !note.resolvable || note.resolved)
+        ),
+    )
+    .map((notes) => notes.at(-1))
+    .map((note) => ({ ...note, author: note.author?.username }));
+  const pipeline = mr.head_pipeline?.sha === mr.sha ? mr.head_pipeline.status : null;
+  const ci = !pipeline
+    ? null
+    : FAILED.includes(pipeline)
+      ? 'failed'
+      : ['success', 'skipped', 'manual'].includes(pipeline)
+        ? 'passed'
+        : 'running';
+  const state = mr.state === 'opened' ? 'open' : mr.state === 'merged' ? 'merged' : 'closed';
+  const me = json('glab', ['api', 'user']).username;
+  return { state, conflicts: mr.has_conflicts === true, ci, unanswered: unansweredIds(open, me) };
+}
+
+const say = (line) => {
+  console.log(line);
+  process.exit(0);
+};
+const status = /github\.com/.test(run('git', ['remote', 'get-url', 'origin'])) ? github : gitlab;
+const started = Date.now();
+let seen = null;
+let errors = 0;
+for (;;) {
+  try {
+    const now = status();
+    errors = 0;
+    if (process.env.WATCH_DEBUG) console.error(JSON.stringify(now));
+    if (now.state !== 'open') say(now.state);
+    if (now.conflicts) say('conflicts');
+    if (now.ci === 'failed') say('failed');
+    const ids = now.unanswered.join(' ');
+    if (ids && (once || ids === seen)) say(`threads ${ids}`);
+    seen = ids;
+    const green = now.ci === 'passed' || (now.ci === null && Date.now() - started >= NO_CI_MS);
+    if (untilGreen && green && !ids) say('green');
+    if (once) say('none');
+  } catch (reason) {
+    if (once || ++errors >= MAX_ERRORS)
+      say(`error ${reason instanceof Error ? reason.message.split('\n')[0] : reason}`);
+  }
+  await new Promise((resolve) => setTimeout(resolve, EVERY_MS));
+}

package/template/__dot__rulesync/skills/ui-verify/SKILL.md.tpl

@@ -0,0 +1,120 @@
+---
+name: ui-verify
+targets: ['*']
+description: >
+  Verify a UI change in a real browser with the global `playwright-cli`: cheap checks first,
+  then four screenshots per changed screen read for spacing, overlap, cut text and contrast,
+  then the per-AC videos for the PR. Use after any change to a page, component, style or
+  player/operator flow, on "check it looks right", "verify the UI", "does it render", "take a
+  screenshot", "record a video", and to reproduce a UI bug before fixing it.
+claudecode:
+  context: fork
+  model: sonnet
+  effort: medium
+---
+
+# ui-verify ({{name}})
+
+Global `playwright-cli` (`npm i -g @playwright/cli` if missing), never a browser MCP: it costs a
+fraction of the tokens. Do not spawn subagents. Return text only. A subagent (`tester`, `builder`) does not
+invoke this skill, which forks one of its own: it reads this file and follows it itself.
+
+## Stack
+
+- Player app :3000, backoffice :3002, API :3001, unless the repo's rules name other ports (a
+  worktree slot, say). Ports held by another checkout: never kill it, ask.
+- Accounts: the seed's (`admin@oss.dev` / `password1234` after `pnpm db:seed`). Save a login once
+  with `state-save /tmp/ui-verify/<app>.json`, `state-load` it after.
+- Theme: switch with the app's own toggle in a video; for a still, set what the toggle sets
+  (a cookie or `localStorage`) with `eval`, then reload.
+
+## Cost ladder
+
+Deterministic checks first, reading pixels last. Write each check as an assertion with an
+expected value (`[data-testid=balance]` text matches `/\d+(\.\d+)? USDT/`) and stop at the
+first rung that answers it.
+
+1. **Shell.** The route serves: `curl -s -o /dev/null -w '%{http_code}' <url>`.
+2. **Browser, one value.** `eval` for existence, text, count, computed style; `console error`
+   and `requests` grepped for `4\d\d|5\d\d`; `find "<text>"` for one node.
+3. **Structure.** `snapshot <target>` scoped to the changed component; a full-page `snapshot`
+   only with `--depth` or `--filename` + `grep`.
+4. **Pixels.** The screenshot review below.
+
+Batch commands in one bash call. Output over ~50 lines goes to `/tmp/ui-verify/` and gets
+`grep`, not read whole. One named session per run (`-s=<name>`), `close` at the end.
+
+## Screenshot review
+
+Screenshots are for you, videos for the reviewer: nobody reads a video back, so layout defects
+are caught here. Every changed screen, after the checks pass and before the videos. Four shots:
+mobile and desktop, light and dark (backoffice: desktop only).
+
+- Sizes: never shrink a shot, halving it halves every padding you judge. Mobile 390x844 at 2x
+  device pixels (780x1688), desktop 1440x900 at 1x: both under the 2000 px per-image cap a
+  session with over 20 images gets, about 1.7k tokens each.
+- Tall screens: one shot per viewport height (`eval "() => scrollTo(0, <y>)"`, then shoot),
+  never `--full-page`, which downscales a long page until its text is unreadable.
+- Before reading, run `layout-check.js` in each of the four. It lists overlapping, clipped,
+  truncated and off-screen text and a page that scrolls sideways; every line it returns is a
+  check to settle on the shot. `sh .claude/skills/ui-verify/layout-check.check.sh` is its self-test.
+- Read each shot for: spacing consistent with its neighbours, alignment, overlapping or cut text,
+  anything off-screen or out of its container, contrast in dark, and the ticket's designs. Every
+  shot gets a report line, a clean one too. A defect is a FAIL with the png path; it gets fixed
+  and shot again.
+
+```bash
+mkdir -p /tmp/ui-verify
+echo '{"browser":{"contextOptions":{"deviceScaleFactor":2}}}' > /tmp/ui-verify/2x.json
+playwright-cli -s=m open <url> --config=/tmp/ui-verify/2x.json && playwright-cli -s=m resize 390 844
+playwright-cli -s=m eval "$(cat .claude/skills/ui-verify/layout-check.js)"
+playwright-cli -s=m screenshot --hires --filename=/tmp/ui-verify/<screen>-mobile-dark.png
+# switch theme, reload, repeat as -light; desktop in its own session:
+# no --config, resize 1440 900, no --hires
+```
+
+In the PR, after the Videos section, collapsed per screen (upload as in `docs/agents/forge.md`):
+
+```markdown
+<details><summary>Screenshots: <screen></summary>
+
+|         | Light                    | Dark                    |
+| ------- | ------------------------ | ----------------------- |
+| Mobile  | ![mobile light](upload)  | ![mobile dark](upload)  |
+| Desktop | ![desktop light](upload) | ![desktop dark](upload) |
+
+</details>
+```
+
+## Video evidence
+
+Last, once, on the final commit after the tests are green and review is clean (`ship` step 4b):
+a clip taken earlier is thrown away by the next fix round. One clip per acceptance criterion
+(`docs/standards/testing.md`), recorded on the local stack. The one early clip is a fix's
+"before", taken when the bug is reproduced; its "after" twin comes here. Never read a video back.
+
+ACs a spec drives come first: every spec that drives one, new or existing, in one run with video
+on (the repo's record switch, or `test.use({ video: 'on' })`); copy each
+`test-results/<test>/video.webm` to `<ac>-<slug>-{desktop,mobile}.webm`. Only an AC no spec
+drives gets `playwright-cli`, one at mobile size (`resize 390 844`) and one at desktop
+(`resize 1440 900`), each switching theme with the app's toggle partway through:
+
+```bash
+playwright-cli -s=v video-start /tmp/ui-verify/ac1-<slug>-mobile.webm
+playwright-cli -s=v video-show-actions
+playwright-cli -s=v video-chapter "AC1: <criterion in a few words>" --duration=1500
+# drive the AC ... toggle the theme ... until its outcome is on screen
+playwright-cli -s=v video-stop
+```
+
+## Report
+
+One line per check: `PASS|FAIL - <check> - rung <n> - expected <x>, got <y> - <artifact path>`,
+plus the failure detail for each FAIL. A pixel claim neither a measurement nor the shot can
+settle is `UNSURE - <check> - <what is ambiguous> - <png path>`, never a guess. Return every shot
+and clip path.
+
+## Bugs
+
+Reproduce here first, as close to real use as possible, then fix, then rerun the same checks.
+A fix without a before and after run is unverified.

package/template/__dot__rulesync/skills/ui-verify/layout-check.check.sh

@@ -0,0 +1,58 @@
+#!/bin/sh
+# Self-check for layout-check.js: the page below plants 5 defects next to 5 look-alikes that are fine.
+set -e
+dir=$(dirname "$0")
+fixture=$(cat <<'HTML'
+<!doctype html>
+<html>
+  <body style="margin: 0; font: 16px sans-serif; width: 390px">
+    <p>
+      Clean wrapped paragraph that wraps across lines with a <a href="#">link inside</a> and more
+      text after it.
+    </p>
+    <div data-testid="overlap-card" style="position: relative; height: 40px">
+      <span>Balance</span><span style="position: absolute; left: 20px; top: 0">USDT 12.50</span>
+    </div>
+    <div data-testid="clip-box" style="height: 18px; overflow: hidden">
+      <p style="margin: 0">Line one<br />Line two cut off</p>
+    </div>
+    <div
+      data-testid="ellipsis"
+      style="width: 80px; overflow: hidden; white-space: nowrap; text-overflow: ellipsis"
+    >
+      A very long game title
+    </div>
+    <span style="position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0)"
+      >Screen reader only</span
+    >
+    <div style="overflow: hidden; width: 200px; white-space: nowrap">
+      <div style="display: inline-block; width: 200px">Slide one</div>
+      <div style="display: inline-block; width: 200px">Slide two parked</div>
+    </div>
+    <div data-testid="wide" style="white-space: nowrap">
+      This label is far too wide for a mobile viewport and runs out
+    </div>
+    <div style="overflow-x: auto; white-space: nowrap; width: 200px">
+      Scrollable chips row that is wider than its box on purpose
+    </div>
+    <p style="position: relative">Under the modal text</p>
+    <div style="position: fixed; top: 0; left: 0; width: 390px; height: 60px; background: #fff">
+      <p style="margin: 4px">Modal title over page text</p>
+    </div>
+  </body>
+</html>
+HTML
+)
+url="data:text/html;base64,$(printf '%s' "$fixture" | base64 | tr -d '\n')"
+playwright-cli -s=layout-check open "$url" >/dev/null 2>&1
+playwright-cli -s=layout-check resize 390 844 >/dev/null
+out=$(playwright-cli -s=layout-check eval "$(cat "$dir/layout-check.js")")
+playwright-cli -s=layout-check close >/dev/null
+for expected in PAGE-SCROLLS-X 'CLIPPED.*clip-box' 'TRUNCATED.*ellipsis' 'OFFSCREEN.*wide' 'OVERLAP.*overlap-card.*with.*overlap-card'; do
+  echo "$out" | grep -q "$expected" || { echo "FAIL: missing $expected"; echo "$out"; exit 1; }
+done
+# Findings never carry page text: a real screen can show player data.
+! echo "$out" | grep -qE 'Balance|USDT|Line two|game title|too wide' || { echo "FAIL: page text in findings"; echo "$out"; exit 1; }
+count=$(echo "$out" | grep -cE '^  "(PAGE|CLIPPED|TRUNCATED|OFFSCREEN|OVERLAP)')
+[ "$count" -eq 5 ] || { echo "FAIL: $count findings, expected 5"; echo "$out"; exit 1; }
+echo PASS