| name | foreman-swift-overlay-validation |
| description | Use when adding tests, fixtures, screenshot capture, fake foreman harnesses, or validation tasks for Foreman's Swift macOS overlay. |
Foreman Swift Overlay Validation
Use this skill when changing the Swift overlay validation lane or before calling
macOS overlay work done.
Load First
Read:
docs/macos-overlay/validation.mddocs/macos-overlay/architecture.mddocs/workflows.md
Validation Philosophy
Mirror Foreman's Rust validation ladder:
- fast pure tests first
- fake external seams before real external seams
- deterministic visual artifacts for UX review
- one focused real tmux smoke for integration confidence
- manual-only checks for global hotkeys and macOS permissions
Required Proof by Change Type
| Change | Minimum proof |
|---|
| Control API schema | Rust tests + Swift fixture decode once available |
| Swift model/filtering | Swift unit tests once test target exists |
| Process invocation | fake ProcessRunner or fake foreman call-log assertion |
| Visual/layout change | ./scripts/capture-macos-overlay.sh and screenshot review |
| Focus/send behavior | fake call log + real tmux smoke if adapter semantics changed |
| Hotkey/window behavior | local manual checklist; don't require CI hotkey synthesis |
Screenshot Capture
Use:
./scripts/capture-macos-overlay.sh
Artifacts land in:
.ai/validation/macos-overlay/
Do not use live tmux state for visual review fixtures. Use checked-in fixture JSON
under apps/macos-overlay/Fixtures/.
Current Known Gap
The prototype currently has build/manual/screenshot proof, but not Swift
XCTest/XCUITest proof. Do not claim Foreman-grade validation until those are
added.
