@event4u/agent-config 1.25.0 → 1.27.0

package/docs/guidelines/agent-infra/ios-simulator-guide.md

@@ -0,0 +1,383 @@
+# 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`
+  / `e2e-plan` skills (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 inlines five reference modules **verbatim** from the
+upstream `conorluddy/ios-simulator-skill` repository. The 21 Python
+helper scripts that ship with the upstream skill (~8500 LOC, macOS-
+and Xcode-bound) are **not forked** — script references inside the
+modules below resolve against the upstream tree, not this suite.
+
+- Upstream repo: `https://github.com/conorluddy/ios-simulator-skill`
+- Pinned SHA: `3acd0717a1b571b1d051559c01ff230d6da28a05`
+- Last checked: 2026-05-08
+- 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 reproduced verbatim from
+`conorluddy/ios-simulator-skill` (MIT License) at SHA
+`3acd0717a1b571b1d051559c01ff230d6da28a05`. Header levels were
+demoted by one to integrate with this guideline's outline; module
+content (text, code, command examples) is unchanged.

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -33,10 +33,14 @@ Size is a signal — not the goal.
 - Acceptable: **< 100–120 lines**
 - Hard limit: **< 200 lines**
 
-Linter (council review 2026-05-06): the > 40 / > 60 line warnings are
-**density-gated** — rules with ≥ 30 % fenced content (verbatim Iron-Law
-blocks, worked-example fences) are exempt from the line-count warning.
-The 200-line hard error stays unconditional.
+Linter (structural model, 2026-05-08 — see
+[`docs/contracts/linter-structural-model.md`](../../contracts/linter-structural-model.md)):
+the long-rule warning fires only when the rule is **> 60 non-empty
+lines AND density < 0.50 AND ships no Iron-Law block**. Rules whose
+body is a verbatim ALL-CAPS imperative (`commit-policy`,
+`ask-when-uncertain`, `direct-answers`) are auto-exempt — no
+frontmatter flag required. The 200-line hard error stays
+unconditional.
 
 Reason:
 - Loaded frequently
@@ -48,10 +52,11 @@ Reason:
 ## Skills
 
 - Target: **300–900 words**
-- Warning: **> 400 lines** (raised from 300, council review 2026-05-06)
-- Strong split signal: reference-rich skills (analyzer, quality-tool
-  catalog, council orchestration) may legitimately sit between 300 and
-  400 lines without being split-candidates
+- Warning: **> 400 lines AND (density < 0.60 OR ≥ 2 `## Procedure`
+  blocks)** — structural model, 2026-05-08
+- Reference-rich skills with high density (`quality-tools` at 0.83,
+  catalogue-style skills) pass without splitting; the multi-procedure
+  trigger flags genuine cluster-split candidates regardless of size
 
 Focus:
 - scanability
@@ -64,10 +69,11 @@ Focus:
 
 - Target: **200–600 words**
 - Acceptable: **up to ~1000 words**
-- Warning: **> 1000 words AND lacks delegation structure** (< 5
-  sub-sections OR < 3 code blocks). Well-factored orchestrators with ≥ 5
-  sub-sections AND ≥ 3 code blocks are exempt — the size reflects
-  dispatch breadth, not bloat (council review 2026-05-06).
+- Warning: **> 1000 words AND no delegation signal AND density < 0.65**
+  — structural model, 2026-05-08. A delegation signal is either
+  frontmatter (`cluster:` / `routes_to:`) OR ≥ 3 markdown links to
+  other `.md` files. Well-factored orchestrators pass automatically;
+  inlined logic in a non-orchestrator command warns.
 
 Commands orchestrate — not implement.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.25.0",
+    "version": "1.27.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/measure_density.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Measure structural density across the artifact corpus.
+
+Phase 1.1 of `agents/roadmaps/road-to-structural-linter-reform.md`.
+
+Density score = structured_lines / total_lines, where structured_lines
+sum lines inside fenced blocks + markdown-table rows + bullet lines +
+numbered/ordered-list lines + section-heading lines. Higher = more
+structured (catalogue, orchestrator, Iron-Law block); lower = prose-
+dominant.
+
+Companion signals collected per artifact (consumed by Phases 1.2-1.4):
+
+- ``multi_workflow``  ≥ 2 ``## Procedure`` (or ``## Procedure: …``)
+                     blocks in a skill — candidate for cluster split.
+- ``delegation``     command frontmatter has ``cluster:`` or
+                     ``routes_to:``, or the body links to ≥ 3 other
+                     commands/skills via ``](...md)``.
+- ``iron_law_block`` ≥ 1 fenced block whose body is ≥ 60 % ALL-CAPS
+                     across ≥ 3 non-empty lines.
+
+Output:
+- Default stdout: per-type distribution buckets + tail (lowest density).
+- ``--json`` deterministic JSON of every artifact.
+- ``--snapshot`` writes JSONL to ``agents/.density-snapshot.jsonl``.
+
+Stdlib only; no network. Re-runnable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from skill_linter import (  # noqa: E402
+    detect_artifact_type,
+    extract_frontmatter,
+    gather_all_candidate_files,
+)
+
+SNAPSHOT_FILE = REPO_ROOT / "agents" / ".density-snapshot.jsonl"
+
+_TABLE_ROW = re.compile(r"^\s*\|.*\|\s*$")
+_BULLET = re.compile(r"^\s*[-*]\s+\S")
+_NUMBERED = re.compile(r"^\s*\d+\.\s+\S")
+_HEADING = re.compile(r"^\s{0,3}#{1,6}\s+\S")
+_PROCEDURE = re.compile(r"^##\s+Procedure(\s*:.*)?\s*$", re.MULTILINE)
+_LINK_MD = re.compile(r"\]\([^)]+\.md[^)]*\)")
+_FRONTMATTER_KEY = re.compile(r"^(cluster|routes_to)\s*:", re.MULTILINE)
+_ALLCAPS_LINE = re.compile(r"[A-Z]")
+
+
+def _classify_lines(text: str) -> Dict[str, int]:
+    """Bucket every non-blank line into one structural category."""
+    inside_fence = False
+    counts = {
+        "total": 0,
+        "fenced": 0,
+        "table": 0,
+        "bullet": 0,
+        "numbered": 0,
+        "heading": 0,
+        "prose": 0,
+    }
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if stripped.startswith("```"):
+            inside_fence = not inside_fence
+            counts["total"] += 1
+            counts["fenced"] += 1
+            continue
+        if not stripped:
+            continue
+        counts["total"] += 1
+        if inside_fence:
+            counts["fenced"] += 1
+        elif _TABLE_ROW.match(raw):
+            counts["table"] += 1
+        elif _HEADING.match(raw):
+            counts["heading"] += 1
+        elif _BULLET.match(raw):
+            counts["bullet"] += 1
+        elif _NUMBERED.match(raw):
+            counts["numbered"] += 1
+        else:
+            counts["prose"] += 1
+    return counts
+
+
+def _detect_iron_law_blocks(text: str) -> int:
+    """Count fenced blocks that look like verbatim Iron-Law imperatives.
+
+    Heuristic: fenced block with ≥ 1 non-empty line whose alphabetical
+    body is ≥ 60 % uppercase AND has ≥ 30 letters total (filters single
+    short ALL-CAPS markers like ``OK``). Also matches blockquote-style
+    Iron Laws (``> NEVER COMMIT``).
+    """
+    blocks = 0
+    inside = False
+    body: list[str] = []
+    for raw in text.splitlines():
+        if raw.strip().startswith("```"):
+            if inside and body:
+                non_empty = [b for b in body if b.strip()]
+                letters = "".join(non_empty)
+                upper = sum(1 for c in letters if c.isalpha() and c.isupper())
+                total = sum(1 for c in letters if c.isalpha())
+                if total >= 30 and upper / total >= 0.6 and non_empty:
+                    blocks += 1
+            inside = not inside
+            body = []
+            continue
+        if inside:
+            body.append(raw)
+    return blocks
+
+
+def _count_procedures(text: str) -> int:
+    return len(_PROCEDURE.findall(text))
+
+
+def _delegation_signal(text: str, frontmatter: str | None) -> Dict[str, Any]:
+    fm_keys = bool(frontmatter and _FRONTMATTER_KEY.search(frontmatter))
+    md_links = len(_LINK_MD.findall(text))
+    return {"frontmatter_routes": fm_keys, "md_links": md_links,
+            "has_signal": fm_keys or md_links >= 3}
+
+
+def measure(path: Path) -> Dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    rel = path.relative_to(REPO_ROOT) if path.is_absolute() else path
+    artifact_type = detect_artifact_type(rel, text)
+    frontmatter = extract_frontmatter(text)
+    counts = _classify_lines(text)
+    structured = counts["fenced"] + counts["table"] + counts["bullet"] + \
+        counts["numbered"] + counts["heading"]
+    density = structured / counts["total"] if counts["total"] else 0.0
+    return {
+        "file": str(rel),
+        "type": artifact_type,
+        "lines": counts["total"],
+        "words": len(text.split()),
+        "density": round(density, 3),
+        "fenced": counts["fenced"],
+        "table": counts["table"],
+        "bullet": counts["bullet"],
+        "numbered": counts["numbered"],
+        "heading": counts["heading"],
+        "prose": counts["prose"],
+        "iron_law_blocks": _detect_iron_law_blocks(text),
+        "procedures": _count_procedures(text),
+        "delegation": _delegation_signal(text, frontmatter),
+    }
+
+
+def collect() -> List[Dict[str, Any]]:
+    paths = gather_all_candidate_files(REPO_ROOT)
+    return [measure(p) for p in paths]
+
+
+def _bucketize(values: List[float]) -> Dict[str, int]:
+    buckets = {"0.0-0.2": 0, "0.2-0.4": 0, "0.4-0.6": 0,
+               "0.6-0.8": 0, "0.8-1.0": 0}
+    for v in values:
+        if v < 0.2:
+            buckets["0.0-0.2"] += 1
+        elif v < 0.4:
+            buckets["0.2-0.4"] += 1
+        elif v < 0.6:
+            buckets["0.4-0.6"] += 1
+        elif v < 0.8:
+            buckets["0.6-0.8"] += 1
+        else:
+            buckets["0.8-1.0"] += 1
+    return buckets
+
+
+def report(results: List[Dict[str, Any]]) -> str:
+    by_type: Dict[str, List[Dict[str, Any]]] = {}
+    for r in results:
+        by_type.setdefault(r["type"], []).append(r)
+    lines: List[str] = ["# Structural Density Snapshot", "",
+                        f"Total artifacts: {len(results)}", ""]
+    for t in sorted(by_type):
+        rows = by_type[t]
+        densities = [r["density"] for r in rows]
+        avg = sum(densities) / len(densities) if densities else 0.0
+        med = sorted(densities)[len(densities) // 2] if densities else 0.0
+        buckets = _bucketize(densities)
+        lines.append(f"## {t} ({len(rows)} artifacts)")
+        lines.append(f"avg density={avg:.2f} median={med:.2f}")
+        lines.append("buckets " + " ".join(
+            f"[{k}]={v}" for k, v in buckets.items()))
+        tail = sorted(rows, key=lambda r: r["density"])[:5]
+        lines.append("lowest density:")
+        for r in tail:
+            lines.append(f"  {r['density']:.2f} {r['lines']:>4}L "
+                         f"proc={r['procedures']} "
+                         f"iron={r['iron_law_blocks']} "
+                         f"deleg={int(r['delegation']['has_signal'])} "
+                         f"{r['file']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--snapshot", action="store_true",
+                   help=f"write JSONL to {SNAPSHOT_FILE.relative_to(REPO_ROOT)}")
+    args = p.parse_args()
+    results = collect()
+    if args.snapshot:
+        SNAPSHOT_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with SNAPSHOT_FILE.open("w", encoding="utf-8") as fh:
+            for r in sorted(results, key=lambda x: x["file"]):
+                fh.write(json.dumps(r, sort_keys=True) + "\n")
+    if args.json:
+        print(json.dumps(results, sort_keys=True, indent=2))
+    else:
+        print(report(results))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())