oh-my-opencode 5.1.47 → 5.1.51

package/packages/shared-skills/skills/frontend/references/design/design-system-architecture.md

@@ -16,7 +16,7 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
 
 ## DESIGN.md Structure
 
-The file has 8 sections plus a greenfield-only `## 0. Research Log`. Every section is mandatory. Skip nothing.
+The file has 8 sections plus a greenfield-only `## 0. Research Log`, and section 9 once `grounding.md` has run. Every section is mandatory. Skip nothing.
 
 ```markdown
 # [Project Name] Design System
@@ -201,8 +201,10 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 ## 8. Accessibility Constraints & Accepted Debt
 
 ### Constraints
-- WCAG target: [e.g. 2.2 AA] — contrast floor [4.5:1 body / 3:1 large text], visible focus on every
-  interactive element, full keyboard reachability, `prefers-reduced-motion` respected (Section 6).
+- WCAG 2.2 AA at minimum ([AAA items the brief raises]): contrast 4.5:1 body / 3:1 large text, icons and
+  control edges; visible focus on every interactive element, never entirely hidden by other content; pointer targets at least
+  24x24 CSS px; full keyboard reachability; reflow at 320 CSS px; `prefers-reduced-motion` respected (Section 6).
+  The per-criterion result is stated in every deliverable (`SKILL.md` Verify).
 
 ### Accepted Debt
 | Item | Location | Why accepted | Owner / Exit |
@@ -210,16 +212,27 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 | [debt] | [file/screen] | [reason + user sign-off] | [when it gets fixed] |
 
 New debt is recorded here at the moment it is accepted — never silently.
+
+## 9. Ideal State & Gap Ledger (after grounding)
+
+- Sources read in full: [source → URL, reader count]
+- Personas and journey steps: [persona → steps]
+- Ideal state: [one checkable line per journey step]
+
+| ID | Screen / state | Gap | Principle or rule broken | Evidence | Fix | Proof | Status |
+|----|----------------|-----|--------------------------|----------|-----|-------|--------|
 ```
 
 ## Creation Workflow
 
+Both paths start with `grounding.md`: the guideline source read in full, the ideal state, and the gap ledger in section 9.
+
 ### For New Projects
 
 1. **Select references before taste** — no visual reference means `_INDEX.md` shortlist of 2-3 Layer B candidates, then exactly one Layer A style skill and one Layer B brand/design-system reference. Use `open-design` only when the curated set has no fit.
 2. **Assemble from references** — extract tokens, layout grammar, component anatomy, states, motion, and taste decisions, then recombine them into project-specific primitives. Customize for the user's product; never copy logos, trademarked assets, or brand-specific copy.
-3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
-4. **Document initial primitives** — only components you are about to build, including variants and states.
+3. **Define the system** — colour roles first (both themes), then atmosphere, typography, spacing, and one depth strategy, grounded in the selected references and product semantics. Sanity-check the palette and type pairing with one `ui-ux-db` domain search (CLI in `references/ui-ux-db/README.md`).
+4. **Document initial primitives** — only components you are about to build, including variants and states, starting from shadcn/ui anatomy (or the project's own kit) restyled with the tokens.
 5. **Write it to `DESIGN.md`** at project root.
 6. **Build a primitive showcase first** — exercise each primitive's default, hover, active, focus, disabled, loading, empty, and error states at mobile/tablet/desktop widths before composing product screens.
 
@@ -239,7 +252,7 @@ After every component implementation, check:
 - [ ] All colors reference tokens from Section 2. No raw hex outside `DESIGN.md`.
 - [ ] All font sizes match Section 3 scale. No arbitrary sizes.
 - [ ] Spacing intent maps to a token (Section 4); browser mechanics (`clamp()`, intrinsic sizing, container units) stay raw. No arbitrary px.
-- [ ] Interactive elements have all required states from Section 5 and Section 6.
+- [ ] Interactive elements have all required states from Section 5 and Section 6, and keep one box across them: width and height match in every state, and no padding appears for a spinner or arrow.
 - [ ] Depth treatment matches the chosen strategy from Section 7.
 - [ ] Component reused 2+ times? Documented in Section 5.
 - [ ] Motion follows the timing and feedback-threshold tables, and every animation has its reduced-motion path.

package/packages/shared-skills/skills/frontend/references/design/grounding.md

@@ -0,0 +1,29 @@
+# Grounding: guideline source, ideal state, gap ledger
+
+Run this before the brief for a new screen or flow, a redesign ("this looks bad", "make it better", "rework the design system"), and any design-system creation or rework. It replaces taste guesses with a written bar: what a good interface does for its users, and every place the work falls short of it. A small change skips the run and reads the ledger in `DESIGN.md` section 9 when one exists.
+
+The output is `DESIGN.md` section 9 (`design-system-architecture.md` gives the template), or the change description when the project has no `DESIGN.md`.
+
+## 1. Guideline source, read in full
+
+Pick the authoritative sources for the platform and the domain: the platform's guidelines (Apple Human Interface Guidelines, Material 3, Fluent 2), WCAG 2.2, and the project's own `DESIGN.md`. Read every page. If a source is too large for one context (the Apple HIG runs to hundreds of pages), split it across parallel readers with `/mass-ulw`, or with parallel subagents where it is unavailable. Each reader returns the principles from its pages with their URLs. A skimmed or sampled source counts as unread.
+
+## 2. Universal principles
+
+Drop the platform idioms: named materials, system icon sets, platform control chrome, and vendor elevation and motion names. Keep what holds for any interface: hierarchy, feedback, consistency, error prevention and recovery, input effort, density, legibility, and accessibility. Tie each principle to a persona and a journey step. Name who uses the product and what they are trying to get done. Then name the step where the principle decides the experience: first visit, daily use, recovery from an error, or a return after time away.
+
+## 3. Ideal state
+
+For each journey step, write what the product does at its best: what the user sees first, the one action, the feedback after it, and the way back from a mistake. Write it so a reviewer can check it on a screenshot: "the run's status and its one next action are the first thing on the screen" is checkable; "clean and intuitive" is not.
+
+## 4. Gap ledger
+
+Capture the surface under work through `/visual-qa` (on a new screen, the first draft, built after the brief; the ledger then grows as the draft is checked) (every state at 390 and 1440, both themes) and list every difference from the ideal state. Do not rank the small ones away. Then read the rule sources in full and add every violation of each: `SKILL.md`'s build rules and draft guard (plus `check-draft-guard.ts` output), the `/visual-qa` checklist, every reference this request routed to, and the WCAG 2.2 AA items in `SKILL.md` Verify. Capture a screenshot for each row and keep the ledger in a durable record (the `/ulw-loop` ledger when it runs) so no finding lives only in context. One row per gap:
+
+| ID | Screen / state | Gap | Principle or rule broken | Evidence | Fix | Proof | Status |
+|---|---|---|---|---|---|---|---|
+| G1 | Settings / save | Save button widens from 96 to 128 px when its spinner appears | State-stable controls | `before/settings-save-loading.png` | Spinner overlays the hidden label in a fixed-width slot | Width probe equal across idle/loading/done; `/visual-qa` before/after pair | open |
+
+## 5. Close the ledger
+
+Plan the fixes before the first edit (`/ulw-plan` for a large ledger): each row names its fix and, in advance, the `/visual-qa` item or probe that will prove it. Then execute without stopping to ask between rows: independent rows run in parallel (`/mass-ulw`, `/ulw-execute`), each fix is a scoped pass (`SKILL.md` Verify), and a large ledger ships as several PRs grouped by screen or rule. A row closes only with its before/after pair and the passing proof, and the pairs go in the PR body. Report progress often as closed/total ledger rows, naming what closed since the last report.

package/packages/shared-skills/skills/frontend/references/ui-ux-db/scripts/design_system.py

@@ -18,6 +18,8 @@ import json
 import os
 from datetime import datetime
 from pathlib import Path
+import sys
+sys.dont_write_bytecode = True
 from core import search, DATA_DIR
 
 

package/packages/shared-skills/skills/frontend/references/ui-ux-db/scripts/search.py

@@ -17,6 +17,8 @@ Persistence (Master + Overrides pattern):
 import argparse
 import sys
 import io
+import sys
+sys.dont_write_bytecode = True
 from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
 from design_system import generate_design_system, persist_design_system
 

package/packages/shared-skills/skills/ultimate-browsing/SKILL.md

@@ -38,8 +38,9 @@ Read the matching reference before acting: [`references/insane-search/README.md`
 **Why first**: ~10x faster than a browser, no process spin-up; handles most "fetch this blocked page" requests via curl_cffi TLS impersonation, yt-dlp (1858 sites), official public APIs, mobile URL transforms, **Phase-2.5 surrogate archives** (Wayback / archive.today snapshots, provenance-tagged — see [`references/insane-search/cache-archive.md`](references/insane-search/cache-archive.md)), a key-gated Jina Reader (`JINA_API_KEY`), and a Playwright real-Chrome fallback. The engine lives **inside this skill** at `engine/` and is invoked as a module. Surrogate results are dated COPIES: a result whose `provenance` is `snapshot` must be reported with its `snapshot_timestamp`, never presented as the live page.
 
 ```bash
-# Core command — auto-detects WAF, runs the full fetch grid (run from the skill dir):
-python3 -m engine "https://example.com/blocked-page"
+# Core command — auto-detects WAF, runs the full fetch grid (run from the skill dir).
+# Keep -B: this skill can live inside a signed app bundle, and bytecode caches written into engine/ break its signature.
+python3 -B -m engine "https://example.com/blocked-page"
 #   add --selector "<CSS>" for positive-proof validation, --device auto|desktop|mobile,
 #   --trace to inspect every attempt, --json for machine-readable output.
 
@@ -119,9 +120,9 @@ When the blocked flow needs the user's account, drive the browser they are alrea
 ```bash
 # Extract cookies to a file:
 mkdir -p ~/.local/state/omo-cookies
-python3 scripts/extract_cookies.py --browser chrome --domain youtube.com --output ~/.local/state/omo-cookies/youtube.cookies.json
+python3 -B scripts/extract_cookies.py --browser chrome --domain youtube.com --output ~/.local/state/omo-cookies/youtube.cookies.json
 # Extract and inject into the running CDP session:
-python3 scripts/extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
+python3 -B scripts/extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
 ```
 
 Cookie export files are written with owner-only `0600` permissions. Do not place live auth cookies in shared temp directories or commit them to a repo. Cookie injection sends values to CDP over stdin rather than argv. Cookies apply on next navigation — reload after injecting. Google services use fingerprint-bound tokens that may not transfer across browser profiles. Limits in [references/chrome-stealth.md](references/chrome-stealth.md).

package/packages/shared-skills/skills/ultimate-browsing/engine/AGENTS.md

@@ -115,7 +115,7 @@ Any future upstream sync preserves BOTH sides. Concretely:
 
 ## OVERVIEW
 
-A 17-module Python package embedded in the `ultimate-browsing` skill: a site-agnostic fetch chain that escalates from a cheap curl probe to a real browser, with declarative WAF and surrogate registries. Not "optional scripts" — it has its own CLI entry (`python3 -m engine URL`), two YAML config schemas, a 4-file test suite, and a standalone CI guard. Package exports (`__init__.py`): `fetch`, `FetchResult`, `Attempt`, `Verdict`, `ValidationResult`, `validate`, `CHALLENGE_MARKERS`, `detect`, `TRANSFORMS`, `apply_transform`.
+A 17-module Python package embedded in the `ultimate-browsing` skill: a site-agnostic fetch chain that escalates from a cheap curl probe to a real browser, with declarative WAF and surrogate registries. Not "optional scripts" — it has its own CLI entry (`python3 -B -m engine URL`; `-B` keeps bytecode caches out of a signed app bundle, #11373), two YAML config schemas, a 4-file test suite, and a standalone CI guard. Package exports (`__init__.py`): `fetch`, `FetchResult`, `Attempt`, `Verdict`, `ValidationResult`, `validate`, `CHALLENGE_MARKERS`, `detect`, `TRANSFORMS`, `apply_transform`.
 
 ## THE NO-SITE-NAME RULE (enforced in CI)
 
@@ -163,7 +163,7 @@ L3+   content checks
 ## CLI
 
 ```bash
-python3 -m engine URL [--selector S] [--device auto|desktop|mobile]
+python3 -B -m engine URL [--selector S] [--device auto|desktop|mobile]
                       [--timeout 25] [--max-attempts 12]
                       [--no-playwright] [--allow-proxy] [--json] [--trace]
 ```

package/packages/shared-skills/skills/ultimate-browsing/engine/__main__.py

@@ -2,13 +2,16 @@
 """CLI entrypoint for the insane-search engine.
 
 Usage:
-    python3 -m engine URL [--selector CSS] [--device auto|desktop|mobile]
-                          [--timeout N] [--max-attempts N] [--json] [--trace]
+    python3 -B -m engine URL [--selector CSS] [--device auto|desktop|mobile]
+                             [--timeout N] [--max-attempts N] [--json] [--trace]
+
+`-B` is required: `-m` compiles the package before any engine code runs, so only
+the interpreter flag keeps bytecode caches out of a signed app bundle.
 
 Examples:
-    python3 -m engine "https://example.com/" --selector "h1"
-    python3 -m engine "https://example.com/" --json
-    python3 -m engine "https://example.com/" --device mobile --trace
+    python3 -B -m engine "https://example.com/" --selector "h1"
+    python3 -B -m engine "https://example.com/" --json
+    python3 -B -m engine "https://example.com/" --device mobile --trace
 
 Exit codes:
     0   strong_ok or weak_ok
@@ -25,7 +28,7 @@ from . import fetch
 
 
 def build_parser() -> argparse.ArgumentParser:
-    p = argparse.ArgumentParser(prog="python3 -m engine",
+    p = argparse.ArgumentParser(prog="python3 -B -m engine",
                                 description="Generic WAF-profile fetch chain.")
     p.add_argument("url", help="URL to fetch.")
     p.add_argument("--selector", "-s", action="append", default=None,

package/packages/shared-skills/skills/ultimate-browsing/engine/summary.py

@@ -19,7 +19,7 @@ R7_HINT = (
     "💡 R7 API-first 권장: WAF가 HTML 경로를 차단 중. "
     "Playwright MCP 사용 → browser_navigate → browser_network_requests "
     "→ `/api/`·`/graphql`·`\\.json` 필터로 내부 엔드포인트 탐지 → "
-    "해당 URL을 `python3 -m engine <API_URL>`로 재호출. 대부분 API 레이어는 "
+    "해당 URL을 `python3 -B -m engine <API_URL>`로 재호출. 대부분 API 레이어는 "
     "WAF 방어가 얕아 curl_cffi만으로 수집됨."
 )
 

package/packages/shared-skills/skills/ultimate-browsing/references/insane-search/README.md

@@ -2,7 +2,7 @@
 # Insane Search
 
 > Part of the **ultimate-browsing** skill (Tier 1). Routing and tier-escalation live in [../../SKILL.md](../../SKILL.md).
-> The engine package it drives is at [../../engine/](../../engine/), invoked from the skill directory as `python3 -m engine "<URL>"`.
+> The engine package it drives is at [../../engine/](../../engine/), invoked from the skill directory as `python3 -B -m engine "<URL>"` (`-B` keeps bytecode caches out of a signed app bundle).
 > Deep-dives in this folder: TLS impersonation, Playwright routing, fallback, metadata, Jina, cache/archive, RSS, JSON/public APIs, Twitter, Naver, media.
 
 
@@ -16,7 +16,7 @@
 1. WebFetch, 즉흥 curl, 수동 헤더 조합 **시도 금지**
 2. 즉시 다음을 실행:
    ```bash
-   python3 -m engine "<URL>" [--selector "<CSS>"] [--device auto|desktop|mobile] [--trace] \
+   python3 -B -m engine "<URL>" [--selector "<CSS>"] [--device auto|desktop|mobile] [--trace] \
                               [--no-retry] [--no-extract]
    ```
 3. 종료코드 0(ok) 또는 1(fail) 받은 뒤 판단. trace를 먼저 읽고 재시도 결정.
@@ -49,7 +49,7 @@
 **MCP 정찰 루트**:
 1. `mcp__playwright__browser_navigate` → 대상 페이지 로드 (브라우저 렌더링)
 2. `mcp__playwright__browser_network_requests` → XHR/fetch 호출 목록 수집, `/api/`·`/graphql`·`\.json` 필터로 내부 엔드포인트 식별
-3. 식별된 JSON API URL을 `python3 -m engine <API_URL>`로 재호출 (백그라운드 engine과는 별개 호출). 대부분 API 레이어는 페이지 HTML보다 WAF 보호가 얕아 curl_cffi로 바로 수집됨
+3. 식별된 JSON API URL을 `python3 -B -m engine <API_URL>`로 재호출 (백그라운드 engine과는 별개 호출). 대부분 API 레이어는 페이지 HTML보다 WAF 보호가 얕아 curl_cffi로 바로 수집됨
 4. 응답 스키마 파악 후 pagination / query parameter 조합해 반복 수집
 
 **왜**: SPA + WAF 사이트(쇼핑몰·커머스 다수)는 마케팅 페이지(HTML)만 WAF로 중투자하고 내부 API는 gateway 레벨 기본 방어만 쓰는 경우가 많다. HTML 격자 전수 낭비(50회 × 0.5s + Playwright fallback 40s ≈ 65초)보다 **MCP 정찰 1회(5~10초) + API 재호출(0.5초)**가 훨씬 경제적이고 성공률 높음.
@@ -62,7 +62,7 @@
 
 이 스킬의 핵심 불변식:
 
-- **단일 진입점**: 일반 웹 페이지는 항상 `python3 -m engine <URL>` 또는 `from engine import fetch; fetch(...)`.
+- **단일 진입점**: 일반 웹 페이지는 항상 `python3 -B -m engine <URL>` 또는 `from engine import fetch; fetch(...)`.
 - **편향 금지**: `engine/**`, `waf_profiles.yaml`에 특정 사이트 하드코딩 금지.
 - **힌트는 런타임에만**: 사이트 고유 정보는 CLI/`user_hint` 경유.
 

package/packages/shared-skills/skills/ultimate-browsing/scripts/extract_cookies.py

@@ -7,8 +7,8 @@ with synthetic fixtures on any OS. This module wires them to a real browser DB
 and a local Chrome CDP session controlled by playwright-core scripts.
 
 Usage:
-    python extract_cookies.py --browser chrome --domain youtube.com --output /tmp/cookies.json
-    python extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
+    python -B extract_cookies.py --browser chrome --domain youtube.com --output /tmp/cookies.json
+    python -B extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
 """
 from __future__ import annotations
 
@@ -23,6 +23,8 @@ import tempfile
 from pathlib import Path
 from typing import Callable, NotRequired, TypedDict
 
+sys.dont_write_bytecode = True
+
 from cookie_crypto import (
     decrypt_chromium_value,
     derive_key,

package/packages/shared-skills/skills/ulw-research/AGENTS.md

@@ -23,11 +23,11 @@ ulw-research/
     ├── report-tools-commands.mjs    # one function per subcommand
     ├── cli-support.mjs / entry-guard.mjs   # flags, CliError, exit codes, atomic JSON, symlink-safe entry check
     ├── contracts.mjs                # frozen vocabulary: DEFECT_CODES (severity lives only here), FIDELITY_CODES, enums, manifest + repair-state validators
-    ├── outcome.mjs                  # outcome.json manifest, deliverable state, verify, closing briefing
+    ├── outcome.mjs / outcome-start.mjs # manifest lifecycle + the run clock outcome init records (--started-at, metadata, dir-name fallback)
     ├── repair-tracker.mjs           # bounded repair decisions (attempts, plateau, oscillation, wall clock, integrity codes)
     ├── html-lite.mjs / entities.mjs # HTML tokenizer, selector paths, prose text
     ├── css-lite.mjs / design-spec.mjs      # CSS scanning, palette + lineage parsing, design-spec rendering
-    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G17
+    ├── gates-static.mjs + gates-text.mjs / gates-figures.mjs / gates-structure.mjs   # static gates G1-G17; sources-citation.mjs is the one Sources predicate (claim segments vs citation fields)
     ├── layout-probe.mjs / gates-layout.mjs # in-page probe source + layout gates L1-L5 over its output
     ├── format-extract.mjs / format-extract-css.mjs   # design-spec draft from a pointed-at HTML or Markdown document
     ├── fact-ledger.mjs              # fact ledger IO and writers (addRow, retractRow, supersedeRow, --view table)
@@ -43,14 +43,18 @@ ulw-research/
     ├── fact-commands.mjs            # `fact add|quote|retract|export|fill|derive` (lazy-loaded by report-tools)
     ├── fact-commands-verify.mjs     # `fact verify` and the Markdown projection it checks
     ├── fidelity-records.mjs         # FIDELITY_RECORDS table + the delivery barrier of outcome verify/finish (fidelity_unresolved, edition_unverified)
-    ├── source-commands.mjs          # `source snapshot`, `claims index`, snapshot readers
+    ├── source-commands.mjs          # `source snapshot`, `claims index`, snapshot readers; `source refresh` is source-refresh.mjs
+    ├── source-view.mjs / raw-decode.mjs / html-text-map.mjs   # the one snapshot reading: locator text, charset decode, byte map, visible-text extraction
+    ├── css-hiding.mjs               # whether inline styles and the page's <style> rules hide an element from every reader (cascade, conditional at-rules)
+    ├── conversion-probe.mjs / number-grammar.mjs   # `source probe-conversion` (numeric diff of a conversion); the one grouped-number grammar (shared with numerals.mjs)
+    ├── markdown-closers.mjs         # CommonMark closer runs (titled/parenthesised link and image targets, references, escapes) for the probe's sign reading and link spans
     ├── *.test.ts                    # co-located bun tests, one per module (unshipped)
     └── tests/fixtures/              # good/bad reports, boxes.json, reference docs (unshipped)
 ```
 
 ## SURFACE
 
-`node "$SKILL_DIR/scripts/report-tools.mjs" <command>`: `check`, `layout-probe`, `repair decide`, `outcome init`, `outcome set`, `outcome gate`, `outcome render`, `outcome state`, `outcome verify`, `outcome finish`, `outcome briefing`, `format-extract`, `fact add`, `fact quote`, `fact retract`, `fact export`, `fact fill`, `fact verify`, `fact derive`, `source snapshot`, `claims index`, `--help --json`. Gates recorded by `outcome gate`, in order: `static`, `fidelity`, `layout`, `visual`, `proofread` (`fidelity` is `fact verify` on every reader-facing edition; HTML only in this stage). Exit codes: `0` pass, `1` semantic failure (blockers, a failed verify, a blocked repair), `2` usage or IO. JSON on stdout, one summary line on stderr. Flags per command: `references/deliverable-phase.md` section 10.
+`node "$SKILL_DIR/scripts/report-tools.mjs" <command>`: `check`, `layout-probe`, `repair decide`, `outcome init`, `outcome set`, `outcome gate`, `outcome render`, `outcome state`, `outcome verify`, `outcome finish`, `outcome briefing`, `format-extract`, `fact add`, `fact quote`, `fact retract`, `fact export`, `fact fill`, `fact verify`, `fact derive`, `source snapshot`, `source refresh`, `claims index`, `--help --json`. Gates recorded by `outcome gate`, in order: `static`, `fidelity`, `layout`, `visual`, `proofread` (`fidelity` is `fact verify` on every reader-facing edition; HTML, or Markdown with its fill map). Exit codes: `0` pass, `1` semantic failure (blockers, a failed verify, a blocked repair), `2` usage or IO. JSON on stdout, one summary line on stderr. Flags per command: `references/deliverable-phase.md` section 10.
 
 ## CONVENTIONS