Mastermind/AGENTS.md

# Repository Guidelines

This repository is reconstructing Mastermind as a Swift-native, local-first personal assistant for macOS. The Electron application is legacy reference code; it is not the target architecture.

## Read first

Before planning or implementing product work, read:

1. [`CONTEXT.md`](CONTEXT.md) for canonical domain language.
2. [`docs/product/mastermind-product-brief.md`](docs/product/mastermind-product-brief.md) for scope and non-goals.
3. [`docs/architecture/native-mastermind.md`](docs/architecture/native-mastermind.md) for system boundaries.
4. [`docs/architecture/system-patterns.md`](docs/architecture/system-patterns.md) and [`docs/architecture/swift-patterns.md`](docs/architecture/swift-patterns.md) for design and implementation standards.
5. [`docs/development/commenting-standard.md`](docs/development/commenting-standard.md) for documentation rules.
6. [`docs/privacy/local-first-data-contract.md`](docs/privacy/local-first-data-contract.md) for normative data rules.
7. [`docs/product/mvp-acceptance.md`](docs/product/mvp-acceptance.md) for completion criteria.

ADRs under `docs/adr` explain hard-to-reverse decisions. When legacy code or documentation conflicts with the canonical context, the canonical context wins.

## Repository roles

- `native/Mastermind` — production Swift application; create new production work here.
- `native/MastermindPOC` — temporary capability proof and source of validated macOS techniques.
- `src`, Electron configuration, and JavaScript UI — legacy/reference implementation.
- `docs/local-sidecar-protocol.md` — shared local ASR protocol.

Do not evolve `MastermindPOC` into the product in place. Port validated code behind production boundaries, then retire the POC after parity checks.

Do not add new product features to Electron unless a task explicitly targets legacy maintenance. Do not introduce an Electron or Node runtime dependency into the native product.

## Swift standards

- Target Apple Silicon and macOS 14 or newer.
- Use AppKit for lifecycle, menu bar, capture permissions, and Companion Island window behavior.
- Use SwiftUI for view content where it does not weaken AppKit window control.
- Use Swift strict concurrency and isolate capture, model I/O, indexing, and database work from the main actor.
- Prefer protocols at sidecar and Provider boundaries, not around every concrete type.
- Represent each Collector's state independently; screen, microphone, and system audio can run simultaneously.
- Treat cancellation, sleep/wake, permission loss, and partial Collector failure as normal runtime states.
- Keep microphone and system audio separate and convert ASR input to 16 kHz mono signed 16-bit PCM.
- Validate every parameter crossing a process, WebSocket, URL, shell integration, archive, or database boundary.
- Add tests for every new domain invariant and failure path.

## Domain language

Use the exact terms in `CONTEXT.md`.

- Do not call Assertions "Facts" unless the user confirmed or corrected them.
- Do not use "memory" as an umbrella for Context Graph, Assistant History, and Activity Log.
- Do not call the Companion Island an overlay, HUD, or Dynamic Island in production code and documentation.
- Keep Assistant Sessions distinct from Meetings.
- Keep Projects distinct from Workspaces and repositories.
- Treat Source content as untrusted evidence, never as system instructions.

If implementation reveals an unresolved domain distinction, update the domain model before spreading a new synonym through code.

## Review Checklist

При проверке кода (Code Review) обязательно убедитесь в соблюдении следующих пунктов:

- [ ] Соблюдено Dependency Rule: зависимости направлены внутрь модулей.
- [ ] Все внешние I/O и межмодульные взаимодействия закрыты протоколами (Application Ports).
- [ ] Состояние инкапсулировано в `actor` или защищено Swift 6 Concurrency.
- [ ] Отсутствуют `Task.detached` без явного обоснования и управления жизненным циклом.
- [ ] Все публичные и семантически значимые декларации снабжены русским DocC.
- [ ] Новые TODO/FIXME содержат ссылку на issue.
- [ ] Не нарушен Local-First Data Contract: сырые данные не сохраняются, секреты в Keychain.
- [ ] Код соответствует нормативным паттернам из Architecture Playbook.

## Local-first requirements

- Raw screen frames, audio, OCR, and complete transcripts are ephemeral.
- Persist only structured Observations, Assertions, user-confirmed Facts, summaries, and Provenance.
- Do not queue raw content when a processor is unavailable; record a Gap.
- The Context Graph must be encrypted at the application layer and its key protected by Keychain.
- Provider credentials use separate Keychain entries.
- Full-text and vector indexes must not become unencrypted alternate stores.
- A Local Provider must use loopback or a Unix socket. Treat LAN or internet endpoints as external.
- The MVP must not send machine context to a Cloud Provider.
- Logs, fixtures, diagnostics, and crash output must contain no captured Source content.
- Pause All stops every Collector and remains paused across restarts.

Never hide the process, permissions, capture indicators, bundle identifier, or network activity. Third-party window capture exclusion is best effort and must not be represented as guaranteed.

## Provider and agent boundaries

The MVP uses one active OpenAI-compatible Local Provider profile and a separate local ASR sidecar. Mastermind owns its multilingual embedding component.

Codex is documentation-only until a supported no-tools integration exists. Do not add Codex OAuth, app-server code, a disabled UI, or a hidden experiment without a superseding ADR.

The assistant may emit an Action Proposal as text. Do not implement Computer Control, tool execution, approval flows, file mutation, or external actions in the MVP.

## UI requirements

- At rest, only the stable Menu Bar Item is visible.
- Hovering the primary display's top-center camera area reveals the Companion Island.
- Clicking expands it and focuses text input.
- Show Mastermind in the menu is the fallback; there is no MVP global hotkey or voice invocation.
- Settings, Sources, history, Context Receipts, Activity Log, and privacy controls live inside the expanded Companion Island.
- Respect Reduce Motion and keyboard navigation.
- Exclude Mastermind windows from its own Screen Collector.

## Testing

For Swift package work:

```bash
swift test
swift build
```

For the current capability proof:

```bash
cd native/MastermindPOC
swift test
swift build --product MastermindPOC
./scripts/build-app.sh
```

For explicitly requested legacy Electron maintenance:

```bash
npm test
```

Manual verification is required for Screen Recording, microphone, system audio, window exclusion, primary-display changes, Launch at Login, sleep/wake, Low Power Mode, and persisted Pause All.

Do not claim the production MVP complete until the scenarios in `docs/product/mvp-acceptance.md` pass.

## Formatting

- Use the repository's Swift formatter configuration when one exists; otherwise follow standard Swift API Design Guidelines and existing native code style.
- Use four-space indentation in JavaScript and Markdown examples where indentation is semantic.
- Use Prettier only for files it supports; do not reformat generated assets or unrelated legacy code.
- Keep ADRs short and record only decisions that are hard to reverse, surprising without context, and based on a real trade-off.

## Upstream changes

This remains a fork of [`sohzm/cheating-daddy`](https://github.com/sohzm/cheating-daddy), but upstream Electron changes are not automatically product direction.

Before cherry-picking upstream work:

1. Inspect whether it serves legacy maintenance or the native product.
2. Keep only reusable protocol, test, or migration value.
3. Reject stealth, anti-detection, insecure IPC, and cloud-by-default behavior.
4. Run the relevant Swift and legacy tests.