@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/ios-simulator-guide.md

@@ -0,0 +1,378 @@
+# iOS Simulator Guide
+
+> Decision matrix and reference modules for driving the iOS Simulator
+> from the command line — `simctl`, `idb`, accessibility-driven
+> testing, and known troubleshooting paths.
+
+## Scope and audience
+
+- Reference material for any work touching the iOS Simulator on macOS
+  hosts: smoke tests, accessibility audits, visual regressions, bug
+  capture, multi-device test sweeps.
+- Intended companions: `react-native-setup` skill (environment),
+  `mobile-e2e-strategy` skill (framework selection), `playwright-testing`
+  / `/tests e2e-plan` command (cross-platform E2E strategy).
+- **macOS-only:** Xcode + simctl + (optional) idb require a macOS host.
+  On Linux/Windows this guideline is reference-only — no implementation
+  recipes are portable.
+
+## When to consult this guideline
+
+- Picking a simulator interaction surface (simctl vs idb vs xcodebuild).
+- Auditing iOS UI accessibility for a release.
+- Driving the simulator from CI for smoke or visual regression tests.
+- Diagnosing a stuck simulator, missing target, or empty accessibility tree.
+
+## Decision matrix — interaction surface
+
+| Surface | Use when | Avoid when |
+|---|---|---|
+| `xcrun simctl` | Boot/install/launch/screenshot/log capture; default for everything CLI-driven | Need accessibility tree or precise UI coordinates |
+| `idb` (Facebook iOS Debug Bridge) | Accessibility-tree dumps, coordinate taps/swipes/text input, point-level inspection | Plain boot/launch tasks (simctl is lighter) |
+| `xcodebuild` / `xcodebuild test` | Compile, sign, and run XCTest / XCUITest suites; CI integration | Ad-hoc scripted interaction (slow, heavyweight) |
+| Direct UI Automation (XCUITest) | Native iOS app E2E with full Apple toolchain support | Cross-platform E2E (use Detox / Appium / Maestro — see `mobile-e2e-strategy`) |
+
+**Rule of thumb:** start with `simctl`; reach for `idb` only when you
+need accessibility-tree introspection or coordinate-level UI control.
+
+## Authoritative upstream
+
+This guideline documents five reference modules drawn from an
+external reference. The Python helper scripts that ship with that
+reference (~8500 LOC, macOS- and Xcode-bound) are **not forked** —
+script references inside the modules below resolve against the
+external reference, not this suite.
+
+- Refresh trigger: quarterly review or sooner if any link 404s in CI.
+
+When you need an upstream Python helper (`accessibility_audit.py`,
+`visual_diff.py`, `app_state_capture.py`, `test_recorder`) clone the
+upstream repo at the pinned SHA, run the helper from there, do **not**
+copy it into a consumer project.
+
+---
+
+## Module 1 — iOS Accessibility Checklist
+
+_Verbatim from `references/accessibility_checklist.md` at the pinned SHA above._
+
+### Critical Rules (Must Fix)
+
+#### 1. Interactive elements need labels
+**Check:** `accessibilityLabel != nil`
+**Fix:** Add descriptive label
+
+#### 2. Buttons need text
+**Check:** `label || value != ""`
+**Fix:** Set button title or accessibilityLabel
+
+#### 3. Images need descriptions
+**Check:** `isImage && accessibilityLabel`
+**Fix:** Add alt text via accessibilityLabel
+
+### Warnings (Should Fix)
+
+#### 4. Complex controls need hints
+**Check:** `accessibilityHint for custom controls`
+**Fix:** Explain what happens on activation
+
+#### 5. Grouped elements need containers
+**Check:** `isAccessibilityElement on containers`
+**Fix:** Group related elements
+
+#### 6. Text fields need placeholders
+**Check:** `placeholder || accessibilityLabel`
+**Fix:** Add placeholder text
+
+### Info (Nice to Have)
+
+#### 7. Automation identifiers
+**Check:** `accessibilityIdentifier != nil`
+**Fix:** Add for UI testing
+
+#### 8. Trait specification
+**Check:** `accessibilityTraits set correctly`
+**Fix:** Use .button, .link, .header appropriately
+
+#### 9. Frame size adequate
+**Check:** `frame.width >= 44 && frame.height >= 44`
+**Fix:** Minimum touch target 44x44pt
+
+### Quick Audit Command
+
+```bash
+python scripts/accessibility_audit.py
+```
+
+### iOS Code Fixes
+
+```swift
+// Label
+button.accessibilityLabel = "Submit form"
+
+// Hint
+slider.accessibilityHint = "Adjusts volume"
+
+// Identifier
+view.accessibilityIdentifier = "login-button"
+
+// Traits
+label.accessibilityTraits = .header
+```
+
+---
+
+## Module 2 — IDB Quick Reference
+
+_Verbatim from `references/idb_quick.md` at the pinned SHA above._
+
+### UI Automation Commands
+
+#### ui describe-all
+**Usage:** `idb ui describe-all --json --nested`
+**Output:** Complete accessibility tree
+**Key:** Foundation for accessibility auditing
+
+#### ui tap
+**Usage:** `idb ui tap <x> <y>`
+**Output:** None (success) or error
+
+#### ui swipe
+**Usage:** `idb ui swipe <x1> <y1> <x2> <y2>`
+**Output:** None (success) or error
+
+#### ui text
+**Usage:** `idb ui text "<text>"`
+**Output:** None (success) or error
+
+#### ui describe-point
+**Usage:** `idb ui describe-point <x> <y> --json`
+**Output:** Element at coordinates
+
+### Other Essential Commands
+
+#### list-targets
+**Usage:** `idb list-targets`
+**Output:** Available simulators with UDIDs
+
+#### screenshot
+**Usage:** `idb screenshot --udid <udid> output.png`
+**Output:** PNG file saved
+
+#### list-apps
+**Usage:** `idb list-apps --udid <udid>`
+**Output:** Installed apps with bundle IDs
+
+### Common Patterns
+
+```bash
+# Get accessibility tree
+idb ui describe-all --json --nested > tree.json
+
+# Basic interaction
+idb ui tap 200 400
+idb ui text "username@example.com"
+idb ui tap 200 500  # Submit button
+```
+
+### Troubleshooting
+See Module 5 below.
+
+---
+
+## Module 3 — simctl Quick Reference
+
+_Verbatim from `references/simctl_quick.md` at the pinned SHA above._
+
+### Essential Commands Only
+
+#### list devices
+**Usage:** `xcrun simctl list devices`
+**Output:** Device list with UDIDs and states
+**Key:** Use `booted` as UDID for current device
+
+#### boot
+**Usage:** `xcrun simctl boot <device-udid>`
+**Output:** None (success) or error
+
+#### launch
+**Usage:** `xcrun simctl launch booted <bundle-id>`
+**Output:** PID of launched app
+
+#### install
+**Usage:** `xcrun simctl install booted <app-path>`
+**Output:** None (success) or error
+
+#### io screenshot
+**Usage:** `xcrun simctl io booted screenshot <file.png>`
+**Output:** PNG file saved
+**Options:** `--type=png|jpeg` (default: png)
+
+#### io recordVideo
+**Usage:** `xcrun simctl io booted recordVideo <file.mp4>`
+**Output:** Video file (Ctrl+C to stop)
+**Options:** `--codec=h264|hevc` (default: hevc)
+
+#### get_app_container
+**Usage:** `xcrun simctl get_app_container booted <bundle-id> data`
+**Output:** Path to app's data directory
+
+#### spawn log
+**Usage:** `xcrun simctl spawn booted log stream --predicate 'process == "<app>"'`
+**Output:** Live log stream
+
+### Common Patterns
+
+```bash
+# Get booted device UDID
+xcrun simctl list devices | grep Booted
+
+# Quick app test
+xcrun simctl boot <udid>
+xcrun simctl install booted app.app
+xcrun simctl launch booted com.example.app
+xcrun simctl io booted screenshot test.png
+```
+
+### Troubleshooting
+See Module 5 below.
+
+---
+
+## Module 4 — Test Patterns
+
+_Verbatim from `references/test_patterns.md` at the pinned SHA above._
+
+### Smoke Test
+```bash
+xcrun simctl boot <udid>
+xcrun simctl launch booted <bundle-id>
+python scripts/accessibility_audit.py
+xcrun simctl io booted screenshot smoke.png
+```
+
+### Visual Regression
+```bash
+# Baseline
+xcrun simctl io booted screenshot baseline.png
+
+# After changes
+xcrun simctl io booted screenshot current.png
+python scripts/visual_diff.py baseline.png current.png
+```
+
+### Full Accessibility Audit
+```bash
+# Each screen
+for screen in home login settings; do
+  # Navigate to screen (app-specific)
+  python scripts/accessibility_audit.py --output $screen.json
+done
+```
+
+### Bug Report Capture
+```bash
+python scripts/app_state_capture.py \
+  --app-bundle-id com.example.app \
+  --output bug-report/
+```
+
+### Multi-Device Test
+```bash
+for device in "iPhone 15" "iPad Pro"; do
+  udid=$(xcrun simctl create test-$device "$device")
+  xcrun simctl boot $udid
+  xcrun simctl install $udid app.app
+  xcrun simctl launch $udid com.example.app
+  xcrun simctl io $udid screenshot $device.png
+  xcrun simctl delete $udid
+done
+```
+
+### Performance Baseline
+```bash
+# Capture initial state
+xcrun simctl io booted screenshot perf-before.png
+# Run performance test
+xcrun simctl launch booted com.example.app
+sleep 5
+xcrun simctl io booted screenshot perf-after.png
+python scripts/visual_diff.py perf-before.png perf-after.png
+```
+
+### Login Flow Test
+```python
+from scripts.test_recorder import TestRecorder
+
+rec = TestRecorder("Login Test")
+rec.step("Launch app")
+# idb ui tap 200 400  # Login button
+rec.step("Enter credentials")
+# idb ui text "user@example.com"
+rec.step("Submit")
+# idb ui tap 200 500
+rec.generate_report()
+```
+
+---
+
+## Module 5 — Troubleshooting
+
+_Verbatim from `references/troubleshooting.md` at the pinned SHA above._
+
+### Problem → Solution Format
+
+#### Simulator won't boot
+**Fix:** `killall Simulator && xcrun simctl erase <udid>`
+
+#### IDB not connecting
+**Fix:** `idb kill && idb companion --boot-status-check`
+
+#### App won't launch
+**Fix:** `xcrun simctl terminate booted <bundle-id> && xcrun simctl launch booted <bundle-id>`
+
+#### Screenshot fails
+**Fix:** Ensure simulator booted: `xcrun simctl boot <udid>`
+
+#### "No booted devices"
+**Fix:** `open -a Simulator` or `xcrun simctl boot <udid>`
+
+#### IDB "Target not found"
+**Fix:** `idb list-targets` to verify UDID
+
+#### Permission denied
+**Fix:** `chmod +x scripts/*.sh`
+
+#### Python module not found
+**Fix:** `pip3 install pillow` (for visual_diff.py)
+
+#### Accessibility tree empty
+**Fix:** App must be in foreground: `xcrun simctl launch booted <bundle-id>`
+
+#### Video recording hangs
+**Fix:** Ctrl+C to stop recording, file saves on interrupt
+
+#### Logs not showing
+**Fix:** Use correct app name: `xcrun simctl spawn booted log stream --predicate 'process == "AppName"'`
+
+#### Device storage full
+**Fix:** `xcrun simctl erase <udid>` (warning: deletes all data)
+
+### Quick Diagnostics
+
+```bash
+# Check simulator state
+xcrun simctl list devices | grep Booted
+
+# Verify IDB connection
+idb list-targets
+
+# Test basic interaction
+xcrun simctl io booted screenshot test.png
+```
+
+## Source attribution
+
+Modules 1–5 above are drawn from an external reference. Header levels
+were demoted by one to integrate with this guideline's outline;
+module content (text, code, command examples) is unchanged.

package/dist/agent-src/guidelines/agent-infra/language-and-tone-examples.md

@@ -0,0 +1,141 @@
+# language-and-tone — examples and failure modes
+
+> Reference companion to [`dist/agent-src/rules/language-and-tone.md`](../../rules/language-and-tone.md).
+> Pulled out so the always-active rule stays under its character budget.
+> Linked from the rule via the **Examples** section; agents do not load this file
+> automatically, only when they want concrete demonstrations or are debugging a
+> language-mirroring drift.
+
+## Failure modes to watch for
+
+- Drafting reply in English first, then "translating the intro" → English
+  phrasing with German words. Draft in target language from the first token.
+- Copy-pasting English option labels from `.md` sources without translating.
+- Mixing languages inside a table or bullet list because "the technical term
+  is English" — surrounding prose must still mirror. Keep proper nouns and
+  code identifiers as-is; translate everything else.
+- Assuming English because "the codebase is English" — codebase language ≠
+  conversation language.
+- Mirroring the **open file** the IDE reports — open files are background
+  context, not chat messages.
+- Mirroring the **roadmap or ticket** being executed — artefacts are English
+  by `.md` rule; chat language is whatever the user wrote.
+
+## `.md` example labels — wrong vs correct
+
+The agent translates option labels to the user's language **at runtime**.
+The `.md` source files are the English blueprint — they define WHAT to say,
+not in which language.
+
+**Wrong** (German in `.md`):
+
+```
+> 1. Interaktiv — bei jedem Kommentar nachfragen
+> 2. Automatisch — alle selbstständig abarbeiten
+```
+
+**Correct** (English in `.md`):
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+Same rule applies to: example prompts and questions, template placeholders,
+ASCII art labels in formatted output blocks, table headers and content.
+
+## Quoted user-input examples — same rule, with one labeled exception
+
+Common drift pattern: a rule documents trigger phrases the agent should
+recognize and writes them as quoted German examples inside English prose.
+**Not allowed**, even when demonstrative.
+
+**Wrong** (DE quote embedded in EN prose):
+
+```md
+Single-decision delegation ("für diesen Schritt entscheide du") →
+handle that step autonomously.
+
+A standing "arbeite selbstständig" never lifts the floor.
+```
+
+**Correct** — two ways:
+
+1. **Translate to English.** Trigger recognition is semantic; the agent
+   matches intent across languages regardless of the example.
+   `("you decide for this step")` works as well as the German.
+2. **Use a labeled `DE: … · EN: …` anchor list** when the multilingual
+   nature of recognition is the point:
+
+   ```md
+   - DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+   - EN: "work autonomously" · "don't ask" · "just do it"
+   ```
+
+The labeled-anchor block is the **only** allowed location for German prose
+in an English `.md` file. Body text, example sentences, prompt templates,
+agent-rendered strings, and failure modes must be English. Reference
+established phrases abstractly later (e.g. "a standing autonomy directive")
+and link back to the anchor block.
+
+## Pre-send gate — filler-phrase blocklist
+
+The pre-send confirm step (Step 4 of the rule's gate) checks for
+language-of-target-mismatched opening phrases. The blocklist:
+
+- **English filler that must NOT open a German reply:** `Let me`,
+  `Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`.
+- **German filler that must NOT open an English reply:** `Lass mich`,
+  `Jetzt`, `Gefunden`, `Bestätigt`.
+
+If the first sentence starts with one of these in the wrong language,
+rewrite the whole reply.
+
+## CLI / icon spacing rules
+
+- Two spaces after `❌`, `✅`, `⚠️` in CLI output.
+- One space for other icons.
+- One blank line max; no double / triple blanks.
+- File ends with exactly one newline.
+
+## `.md` files — pre-save detection heuristic
+
+Before saving any `.md` under `.augment/`, `dist/agent-src/`,
+`.agent-src.uncondensed/`, or `agents/`, scan the body for:
+
+- Umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) **outside** fenced code,
+  paths, or `DE: … · EN: …` anchor blocks.
+- German function words: `für`, `nicht`, `dass`, `wenn`, `sollte`,
+  `werden`, `arbeite`, `selbstständig`, `jetzt`, `einfach`, `weiter`,
+  `lösche`, `frag`, `schreib`, `mach`.
+- Non-English quoted phrases in body text.
+
+Any hit → translate to English, OR move to a `DE: … · EN: …` anchor
+block (the only allowed German location).
+
+## Generated `.md` — fix the generator, never the page
+
+When a `.md` page is produced by a generator (e.g. `docs/value.md` from
+`scripts/render_value_md.ts`, the catalogs from the index/catalog
+generators), German lives in the **generator's source strings** or the
+data it reads — fix it there so the page regenerates English. Hand-edits
+to a generated page are overwritten on the next regen. If a generated
+page legitimately carries German (e.g. catalogs echoing skill-description
+**trigger-phrase examples**), the page belongs **outside** the docs
+language gate — scanning a derived artefact is the wrong layer; the source
+artefact is what the relevant linter checks.
+
+## Sanctioned escapes for genuinely-required German
+
+Two — and only two — escapes are allowed when a line must carry German:
+
+1. **Labeled `DE: … · EN: …` anchor** — the only location for German
+   *prose* (a translated passage shown alongside its English).
+2. **Per-line `<!-- md-language-check: ignore -->` marker** — for a single
+   line that quotes a German **trigger-phrase example** (illustrating
+   German-input handling) or a **verbatim provenance quote** (an
+   immutable historical citation, e.g. the original user ask in an ADR).
+
+The marker is line-scoped and auditable. Never scatter it through a
+generated file to silence the linter — fix the generator instead. Both
+escapes are recognized by `scripts/check_md_language.ts`.