AGENTS.md

1# PalmierPro
2 
3AI-native macOS video editor. Swift 6.2, SwiftUI + AppKit, AVFoundation. macOS 26 only, arm64 only. Non-sandboxed Developer ID app.
4 
5## Build
6 
7```bash
8swift build
9swift run
10swift test
11```
12 
13Use `swift build --traits BundledSpeech` for changes that touch MLX, speech analysis, transcription, or bundled speech resources.
14 
15## Engineering approach
16 
17- Understand the owning feature and existing abstractions before editing. Trace the complete call path, including UI, Agent tools, undo, persistence, and background work.
18- For nontrivial changes, identify the source of truth, state owner, isolation domain, invariants, failure behavior, cancellation behavior, and file placement before writing code.
19- Design the architecture before adding implementation details. Prefer a small coherent change over patches spread across unrelated layers.
20- Keep one authoritative owner for mutable state. Derived state must be computed or maintained by a cache with an explicit invalidation contract.
21- Reuse existing domain operations. Do not create a second implementation because the caller is a preview, SwiftUI view, AppKit controller, Agent tool, or test.
22- Preview, validation, execution, persistence, and undo must share the same eligibility rules, calculations, clamping, timing, placement, and mutation helpers.
23- Place code with the feature that owns it. Use `Utilities` only for infrastructure used by multiple independent features.
24- Split extensions by coherent capability, not arbitrary file length. File and type names must make ownership clear.
25- SwiftUI views render state and forward user intent. Keep domain mutations, filesystem work, media processing, and orchestration out of view bodies.
26- Follow the Swift API Design Guidelines. Optimize names for clarity at the call site and use established filmmaking and Apple-platform terminology.
27 
28## Code style
29 
30- Keep comments minimal. Write one only when the why, invariant, safety constraint, or framework workaround is non-obvious.
31- Comments are one short line maximum. Do not narrate code, restate names, describe the current patch, leave removal breadcrumbs, add commented-out code, or write paragraph docstrings for internal APIs.
32- Prefer precise names, small types, and extracted operations over explanatory comments.
33- Complex logic must have a single source of truth. Never copy a calculation or business rule into another file or surface.
34- Remove dead code, unused state, obsolete compatibility paths, and temporary diagnostics before finishing.
35- Do not add compatibility code for OS versions or architectures Palmier Pro does not support.
36 
37## Concurrency and the main actor
38 
39- Treat the main actor as a scarce UI resource. It may own UI state and lightweight coordination state, but it must not perform file I/O, media decoding, model inference, image processing, indexing, export work, blocking framework calls, or large collection transforms.
40- `@MainActor` provides isolation, not performance. Move expensive work out of a main-actor type instead of assuming an `async` method makes it safe.
41- `Task {}` inherits actor isolation. Never use it as evidence that synchronous work moved off the main actor.
42- `nonisolated` on a synchronous function does not switch threads. A call from the main thread still runs on the main thread.
43- Make executor changes explicit. Prefer an asynchronous system API; otherwise use a dedicated utility queue or service, an `@concurrent` async function, or a carefully bounded `Task.detached` over immutable `Sendable` snapshots.
44- Snapshot the minimum immutable input before leaving an actor. Return a value, then apply it on the owning actor after checking cancellation and confirming the result is still current.
45- At every `await`, assume actor-isolated state may have changed. Revalidate identity, generation, configuration, selection, lifecycle state, and preconditions before committing a result.
46- Prefer structured concurrency. Unstructured tasks must have a clear owner, stored handle when cancellation matters, and teardown behavior.
47- Cancellation is cooperative. Long operations and loops must check cancellation at useful boundaries, and cancellation must not commit partial or stale results.
48- Bound parallel work according to the actual scarce resource. Do not create one task per asset, frame, thumbnail, decoder, or model request without a concurrency limit.
49- Deduplicate identical in-flight work where multiple callers can request the same result.
50- Actors protect their own state only. Audit process-global state, C/C++ libraries, Metal resources, AVFoundation objects, caches, and third-party dependencies before allowing separate actors to call them concurrently.
51- Acquire and release gates in matched scopes. Install `defer` only after acquisition succeeds. Make cancellation while waiting safe.
52- Keep continuation state in one isolation domain and resume every continuation exactly once on success, failure, or cancellation.
53- Never block the main thread with `DispatchQueue.sync`, semaphore waits, group waits, locks, polling, or synchronous waits for async work.
54- Treat Objective-C and third-party callback isolation as untrusted unless documented. Hop explicitly to the correct actor and use `@Sendable` where a callback crosses isolation.
55- Avoid `nonisolated(unsafe)` and unchecked `Sendable`. Any use requires a concrete invariant and targeted coverage.
56 
57## File I/O and project packages
58 
59- Every filesystem operation must execute off the main actor and main thread. This includes reads, writes, encoding to or decoding from disk, existence checks, metadata and resource-value queries, directory enumeration, coordination, copying, moving, replacing, deleting, and directory creation.
60- Assume every volume can be slow, removable, externally modified, or network-backed. File size and a successful previous access do not make synchronous main-thread access safe.
61- Prefer asynchronous APIs. Run synchronous Foundation file APIs behind an explicit background boundary, preferably a dedicated serial utility queue for coordinated operations.
62- The synchronous `FileIO` helpers do not provide an execution hop. Callers are responsible for invoking them from an off-main context.
63- Snapshot actor-owned model data before file work. Do not capture a main-actor model or mutate observable state from the file-I/O executor.
64- Stage complete output outside the live project package, prepare replacements on the destination volume, and atomically install the finished item.
65- Route all live `.palmier` package media installs and removals through `ProjectPackageCoordinator`. Do not write directly into a live package from feature code.
66- Serialize operations that target the same package or destination. A save, import, generation result, thumbnail, removal, export, and close operation must not race each other.
67- Closing, Save As, and app termination must wait for admitted mutations, reject late commits, and preserve the latest successful state.
68- Use unique temporary paths and clean them on success, failure, and cancellation. Never delete or replace a destination until the complete replacement is ready.
69- Surface user-requested file failures. Do not hide them with `try?`, empty results, or success-shaped responses.
70 
71## Performance
72 
73- Treat rendering, playback, scrubbing, audio metering, timeline input, SwiftUI view updates, import, indexing, restore, save, and export as performance-sensitive paths.
74- Do not perform filesystem access, logging, JSON encoding, model setup, decoder or reader creation, audio-graph setup, LUT parsing, `CIContext` creation, or other blocking setup inside per-frame, per-sample, per-grain, per-item view, or repeated interaction paths.
75- Measure before claiming a performance improvement. Use the relevant Instruments template, signposts, a focused benchmark, or a performance test, then compare before and after under the same workload.
76- Fix algorithmic complexity and unnecessary work before applying low-level optimizations. Watch for nested scans, repeated sorting, copy-on-write mutation in loops, intermediate arrays, repeated actor hops, and repeated observation invalidation.
77- Batch and coalesce bulk mutations. Preserve explicit consistency boundaries by flushing pending state before save snapshots, undo snapshots, export, close, and reads that promise current data.
78- Load and hydrate media lazily. Do not decode thumbnails, waveforms, filmstrips, metadata, transcripts, or models until a consumer needs them.
79- Cache expensive reusable work only with an explicit key, capacity, invalidation rule, replacement rule, lifecycle behavior, and stale-result policy.
80- Reuse expensive AVFoundation, Core Image, Metal, audio, and model objects when their documented lifecycle permits it. Invalidate them on relevant configuration and application lifecycle changes.
81- Keep high-frequency observable state as narrow as possible. A progress counter, meter, or playhead update must not invalidate an entire panel or large media grid.
82- Keep SwiftUI `body` work fast and side-effect free. Precompute expensive derived data and observe the smallest state surface that can render the result.
83- Limit retained media and cache memory. Use bounded caches, release temporary buffers promptly, and use scoped autorelease pools for large Objective-C media loops when profiling shows retained temporaries.
84- Keep per-item success logging out of release hot paths. Production logs should preserve actionable warnings, failures, and batch summaries without evaluating verbose messages unnecessarily.
85 
86## Correctness and edge cases
87 
88- “Works on the happy path” is not sufficient. Before implementing, enumerate the applicable boundary, lifecycle, concurrency, and failure cases and decide which layer owns each behavior.
89- Validate empty, nil, zero, negative, maximum, overflowing, non-finite, malformed, duplicated, missing, stale, and unsupported inputs as applicable.
90- Validate before integer arithmetic, frame addition, duration multiplication, indexing, or numeric conversion. Never rely on a later `do`/`catch` to catch a Swift arithmetic trap.
91- Define exact rounding and clamping behavior. Do not silently clamp an invalid request unless tolerance is an intentional documented part of the contract.
92- Cover no-op and repeated operations. They must report accurately and must not create mutations, undo entries, duplicate work, or misleading success.
93- Consider cancellation before start, during each phase, after work completes but before commit, and while waiting for a gate or callback.
94- Consider stale completion after selection, timeline, project, asset URL, model, mix, generation, or configuration changes.
95- Consider close, quit, sleep, wake, app deactivation, device changes, Save As, and teardown while work is active.
96- Consider empty timelines, zero-duration media, missing tracks, corrupt or offline media, variable frame rates, non-integer speeds, time-scale conversion, and long-duration projects.
97- Consider linked clips, nested timelines, multicam groups, locked or sync-locked tracks, split clips, overlapping clips, and changes to a child timeline after a carrier was created.
98- Consider interaction combinations: keyboard modifiers, Escape, dismissal, mouse-up after cancellation, disabled controls, focus changes, selection changes, and overlapping gestures.
99- Consider partial filesystem failure, permissions, an existing destination, identical source and destination, external changes, low space, and cleanup failure.
100- Preserve project invariants on every failure path. Partial success must either be safely resumable and reported as such or rolled back.
101 
102## Editor mutations and undo
103 
104- Route UI and Agent edits through the same domain mutation operations and shared `EditorUndo` history.
105- One coherent user intent should produce one undoable action. Do not expose internal substeps as separate undo entries unless they are independently meaningful to the user.
106- Validate arguments and preconditions before opening an undo group. Failed, cancelled, refused, and unchanged operations must not create empty undo steps.
107- Nested implementation work must coalesce into the outer user action without closing groups owned by AppKit or another subsystem.
108- Undo must restore exact state without cumulative frame rounding, derived-state drift, orphaned linked clips, or stale selection.
109- Test interleaving between UI edits, Agent edits, automatic AppKit event grouping, project switching, and concurrent tool requests when the change touches undo.
110 
111## Agent tool design
112 
113- Design tools from user intent, not from internal APIs, database operations, view models, or service method boundaries.
114- Start with representative user requests and define the desired outcome, success criteria, warnings, failure behavior, cancellation behavior, retry behavior, idempotency, and undo semantics before defining the schema.
115- A tool should perform one coherent filmmaker action. One call should normally complete one atomic, understandable, and undoable workflow.
116- Do not force the Agent to reproduce application orchestration by chaining low-level tools when Palmier Pro can safely perform the workflow itself.
117- Do not create a broad “god tool” with unrelated modes. Group operations only when they share one user goal, validation model, and result shape.
118- Express parameters in filmmaking and user-facing domain concepts. Hide storage layout, framework objects, UI state, and incidental implementation details.
119- Use stable entity IDs for automation. Positional indexes and display labels may be returned for context but must not be the only durable identity after edits.
120- Treat every tool argument as untrusted. Require exact types, finite numbers, explicit bounds, valid identifiers, and supported combinations before mutation or arithmetic.
121- Resolve and validate the full request before mutating state. Apply multi-entity changes atomically and preserve all editor invariants.
122- Reuse the same domain operation as the UI. Agent tools must not duplicate timeline math, placement, linking, sync, media, export, or project logic.
123- Return structured receipts describing what changed, stable IDs, explicit no-op state, warnings, skipped items, and actionable errors. Do not return a success-shaped response when the requested outcome was adjusted or not achieved.
124- Do not silently clamp, retarget, reorder, fall back, or select a different entity unless the tool contract explicitly promises that behavior and reports it.
125- Long-running tools must expose a durable job or terminal result that the Agent can inspect. Asynchronous failure must not disappear after the initiating call returns.
126- Keep Agent and MCP protocol values stable and machine-facing. Localize UI copy separately; do not serialize localized labels, errors, statuses, or undo names into tool contracts.
127- Tool descriptions must explain when and why to use the tool, important constraints, and interactions with other tools. Do not merely restate parameter names.
128- Refactoring internal APIs must not require changing a well-designed tool contract unless the user-visible capability changes.
129 
130## AVFoundation and media processing
131 
132- Use AVFoundation asynchronous property loading. Do not access deprecated synchronous `AVAsset`, `AVAssetTrack`, or `AVMetadataItem` properties that may block the calling thread.
133- Keep exact media time in `CMTime` or frame-domain integers as long as possible. Convert to `Double` only at explicit UI or external-format boundaries.
134- Define and preserve time scale, rounding, source-versus-timeline time, speed, trim, transform, color, alpha, audio layout, and metadata semantics.
135- Keep potentially blocking AVFoundation and Core Audio setup and control calls off the main thread, even when the API does not advertise itself as file I/O.
136- Reuse readers, render contexts, audio graphs, and pipelines where appropriate. Do not rebuild them during continuous interaction unless invalidation requires it.
137- Bound concurrent decoders, readers, exports, model inference, thumbnail generation, and waveform extraction.
138- Propagate cancellation through decode, render, inference, export, and generation loops. Check between chunks when an underlying synchronous API cannot be cancelled.
139- Preserve source color attachments, transforms, frame timing, channel layout, and other media metadata unless the feature explicitly changes them.
140- Test with missing audio or video tracks, unusual containers, zero or indefinite duration, rotated media, alpha media, nonstandard sample rates, and cancellation.
141 
142## SwiftUI and AppKit
143 
144- Keep observable UI state on the main actor and make background results cross that boundary as immutable values.
145- Scope observation to the smallest view that needs the value. High-frequency progress, meter, hover, and playback state must not invalidate unrelated view trees.
146- Do not start persistent side effects from `body`. Use lifecycle-aware tasks or controllers with explicit cancellation and teardown.
147- Preserve native Mac behavior for keyboard focus, Escape, Return, menus, window restoration, undo, drag state, sheets, and close confirmation.
148- AppKit delegate and completion-handler contracts must complete exactly once on every success, failure, cancellation, and missing-target path.
149- Do not assume an AppKit or AVFoundation callback arrives on the main thread unless the API guarantees it.
150 
151## Design System
152 
153All UI styling MUST use `AppTheme` constants from `Sources/PalmierPro/UI/AppTheme.swift`. Never use hardcoded numeric values for:
154 
155- **Spacing/padding** → `AppTheme.Spacing.*` (xxs through xxl)
156- **Font sizes** → `AppTheme.FontSize.*` (xxs through display)
157- **Font weights** → `AppTheme.FontWeight.*` (regular, medium, semibold, bold)
158- **Corner radii** → `AppTheme.Radius.*` (xs through xl)
159- **Border widths** → `AppTheme.BorderWidth.*` (hairline, thin, medium, thick)
160- **Opacity** → `AppTheme.Opacity.*` (subtle, faint, muted, medium, strong, prominent)
161- **Icon frame sizes** → `AppTheme.IconSize.*` (xs through xl)
162- **Shadows** → `AppTheme.Shadow.*` (sm, md, lg) via `.shadow(AppTheme.Shadow.md)`
163- **Colors** → `AppTheme.Text.*`, `AppTheme.Border.*`, `AppTheme.Background.*`
164- **Animation durations** → `AppTheme.Anim.*`
165 
166If a needed value doesn't exist in AppTheme, add it there first — don't hardcode it.
167 
168## Drag and drop
169 
170SwiftUI `.onDrop` on a parent view shadows every drop target inside its layout area on macOS 26 — even AppKit `NSDraggingDestination` children registered directly with the window. Inner `.onDrop` modifiers silently never fire while a parent `.onDrop` is active.
171 
172Rule: **any drop target that spans an area containing other drop targets must use native AppKit** (see `MediaPanelDropArea` in `Sources/PalmierPro/MediaPanel/`). Inner / leaf drops can stay SwiftUI `.onDrop`. Do not stack SwiftUI `.onDrop` modifiers in parent/child layouts.
173 
174## Resources and configuration
175 
176- Resource lookup must work in the packaged app, `swift run`, and SwiftPM tests. Use the repository's shared resource lookup abstraction instead of inventing feature-specific probing.
177- Treat the main bundle, SwiftPM resource bundle, and test bundle layouts as distinct configurations that require verification.
178- Do not use `#if DEBUG` to select a fundamentally different resource path or user behavior unless the difference is intentional and tested.
179- When adding a bundled resource, update `Package.swift`, bundle scripts, and tests as required. Verify the final `.app` layout when packaging behavior changes.
180- Keep optional feature-trait code buildable both with and without the trait.
181 
182## Localization
183 
184- Localize fixed app-owned UI copy with `L10n.string`. Keep interpolation inside the localized value so translations can reorder it.
185- Register app-owned UI labels stored in models with `L10n.key`, then resolve them at the UI boundary with `L10n.string(key:)`.
186- Render user content, filenames, technical values, provider metadata, and other non-translatable values with `Text(verbatim:)` or an equivalent verbatim API.
187- Never localize Agent or MCP contracts, persistence values, stable identifiers, machine-readable errors, or analytics values.
188- Run `scripts/localization/sync.sh` after changing UI copy. CI requires complete coverage when a PR changes a non-English catalog.
189- The generated `en.lproj/Localizable.strings` file is the source inventory. Do not edit it manually.
190- A language PR must add only complete `<locale>.lproj` directories containing `Localizable.strings` and `InfoPlist.strings`. Translate values, never keys, and do not add production-code language lists.
191- Follow `docs/Localization.md` for source patterns, translation boundaries, and manual verification.
192 
193## Errors, logging, and observability
194 
195- Every user-initiated or Agent-initiated operation must reach an observable success, failure, refusal, or cancellation state.
196- Do not use `try?` at an interaction boundary when failure changes the outcome. Convert the error into UI state, a tool error, a job failure, or an actionable log as appropriate.
197- Fire-and-forget work is allowed only for explicitly best-effort behavior. It must not own required persistence or mutation, and failures must be safely ignorable or recorded.
198- Log failures with the operation, stable entity IDs, lifecycle phase, and useful dimensions. Avoid secrets, API keys, credentials, raw user prompts, and unnecessary filesystem details.
199- Preserve enough terminal diagnostics to distinguish cancellation, validation failure, unavailable media, framework failure, and internal invariant violation.
200- Use assertions for programmer invariants, not recoverable user input, external files, lifecycle races, or Agent requests.
201 
202## Tests
203 
204- Unit tests must be concise and focused on behavior. One test should establish one invariant or regression, with only the setup needed to make that behavior clear.
205- Prefer Swift Testing, `#expect`, and `#require` for new unit coverage unless an AppKit or XCTest-specific API requires XCTest.
206- Use descriptive test names that state the behavior. Do not add comments that narrate arrange, act, and assert steps.
207- Use parameterized tests for boundary matrices and repeated input/output cases instead of duplicating test bodies.
208- Reuse small fixture builders for timelines, clips, media, projects, and temporary packages. Do not copy large setup graphs across suites.
209- Test through the smallest stable public or internal seam that proves the behavior. Avoid tests coupled to private implementation details or incidental call counts.
210- Every bug fix needs a regression test that fails for the original defect when practical.
211- Test relevant negative paths: validation, no-op, partial failure, cancellation, stale completion, cleanup, and invariant preservation.
212- Concurrency tests must coordinate deterministically with gates, continuations, or injected hooks. Do not rely on sleeps, timing luck, repeated loops, or task scheduling order.
213- Tests run in parallel by default. Do not share mutable global state, fixed temporary filenames, ports, caches, defaults, or project directories between tests.
214- Use unique temporary directories and clean them up. File-I/O test helpers must follow the same off-main rule as app code.
215- Keep network, production credentials, external services, and the user's real files out of unit tests.
216- Use performance tests only with a stable representative workload and an assertion that can detect a meaningful regression.
217 
218### Test responsibilities
219 
220- **UI testing:** UI behavior requires manual user verification. The Agent must provide a short test plan with setup, actions, expected results, and relevant edge or lifecycle cases. Do not claim the UI passed until the user confirms it.
221- **Unit testing:** The Agent owns writing and running focused unit or regression tests. Run the smallest relevant suite while iterating and the broader affected suites before finishing.
222- **MCP/Agent testing:** Agent tool changes require end-to-end verification through the MCP boundary, not only direct calls to internal Swift methods. Use connected MCP tools directly when available, or run the MCP server and use a temporary script or client to exercise it.
223- MCP tests must verify the requested outcome independently by reading state back, inspecting the timeline or project, checking persistence, or exercising undo. Do not trust a success response as the sole proof.
224- Cover tool discovery and schema when they change, representative user-intent requests, validation failures, no-op receipts, multi-step invariants, cancellation or asynchronous completion, and stable IDs.
225- Use an isolated test project, temporary data, and a non-conflicting server port for MCP tests. Never mutate a user's real project as test setup.
226- If an environment prevents an end-to-end test, state the exact blocker and give the user a concrete manual verification plan. Do not substitute a narrower test while claiming end-to-end coverage.
227 
228## Code reviews
229 
230- Review for correctness before style. Trace the changed behavior through its callers, shared state, background work, persistence, undo, UI, and Agent surfaces.
231- Prioritize findings that can cause data loss, project corruption, crashes, hangs, races, security or privacy exposure, incorrect edits, broken undo, or misleading success. Then consider performance, maintainability, and polish.
232- Verify the change preserves the feature's invariants on success, failure, cancellation, no-op, retry, and teardown paths.
233- Look for main-actor work that can block: file access, media loading, synchronous framework calls, decoding, inference, export, indexing, large transforms, waits, and lock contention.
234- Do not accept `Task {}`, `async`, or synchronous `nonisolated` code as proof that work is off-main. Follow the executor path.
235- Look for concurrency mistakes: state read before an `await` and committed afterward without revalidation, unowned tasks, missing cancellation checks, unbounded fan-out, unbalanced gates, double-resumed continuations, callbacks on the wrong actor, and teardown racing active work.
236- Check whether separate actors still touch shared process-global or non-thread-safe framework state.
237- Review every filesystem mutation for staging, atomic replacement, same-destination serialization, cleanup, error propagation, package-save coordination, Save As, close, and termination behavior.
238- Look for duplicated domain logic. Preview, validation, commit, undo, UI, and Agent paths must not implement slightly different eligibility, timing, clamping, placement, linking, or mutation rules.
239- Check scaling against large projects and long timelines. Flag repeated filesystem metadata reads, nested scans, per-item observed mutations, eager hydration, repeated decoder setup, broad SwiftUI invalidation, unbounded caches, and excessive release logging.
240- Review caches for complete keys, capacity limits, invalidation, replacement races, lifecycle reset, stale-value selection, and behavior when the backing file or configuration changes.
241- Validate boundary arithmetic and conversions before use. Check zero, negative, maximum, overflow, non-finite, rounding, time-scale, index, and duration cases.
242- Review editor changes with linked clips, nested timelines, multicam groups, locked tracks, missing media, empty timelines, unusual track layouts, and current selection or focus changes.
243- Review UI interactions across mouse, keyboard modifiers, Escape, dismissal, disabled state, focus, app deactivation, sleep, and mouse-up after cancellation. Preview state must match committed state.
244- Review undo boundaries. Validation must happen before grouping; failed and unchanged operations must not add undo entries; one user intent must undo as one action without absorbing adjacent edits.
245- Review Agent tools from the user's requested outcome. Reject schemas that mirror internal APIs, require fragile low-level orchestration, use unstable positional identity, silently adjust requests, duplicate UI domain logic, or omit structured receipts and terminal failures.
246- Keep localized UI language separate from stable Agent and MCP contracts, serialized state, identifiers, and machine-readable errors.
247- Check AVFoundation work for asynchronous property loading, exact time math, cancellation, bounded readers or decoders, lifecycle invalidation, and preservation of source transforms, color, alpha, timing, and audio metadata.
248- Treat swallowed errors, recoverable-input assertions, `try?` at interaction boundaries, unchecked casts, `nonisolated(unsafe)`, and unchecked `Sendable` as review targets requiring proof.
249- Verify tests reproduce the defect or protect the invariant, cover the important negative or interleaving path, remain deterministic and parallel-safe, and avoid duplicative setup.
250- Verify stated build, test, runtime, and performance evidence matches what was actually run. Do not accept performance claims without comparable measurements.
251- Keep findings actionable and evidence-based. State the triggering scenario, violated invariant, user impact, and relevant code path. Distinguish correctness defects from optional improvements.
252- Review changed code and the directly affected system. Do not block a patch on unrelated pre-existing issues unless the change makes them reachable or more severe.
253 
254## Verification
255 
256- Run `swift build` after source changes.
257- Run focused tests for the changed behavior. Run `swift test` for core editor, persistence, undo, concurrency, shared infrastructure, or broad refactors.
258- Run `swift build --traits BundledSpeech` for speech, MLX, transcription, or bundled-model changes.
259- For concurrency changes, exercise cancellation and lifecycle paths and use Thread Sanitizer or concurrency diagnostics when applicable.
260- For responsiveness and performance changes, verify with Instruments or a focused measurement under a representative large workload.
261- For UI interaction changes, run the app and verify mouse, keyboard, Escape, focus, undo, disabled, and empty states relevant to the change.
262- For project-package changes, verify save, autosave, Save As, close, quit, failure, and concurrent media mutation paths.
263- Report exactly what was run and what was not. Do not claim a full build, test, package, or runtime verification when only a subset completed.
264 
265## Git and pull requests
266 
267- Commit and PR titles use a concise lowercase category prefix in brackets, followed by an imperative summary: `[fix] Prevent stale export completion`.
268- Use the narrowest accurate category, such as `[fix]`, `[perf]`, `[feat]`, `[agent]`, `[ui]`, `[refactor]`, `[test]`, `[docs]`, `[build]`, `[ci]`, `[telemetry]`, or `[cleanup]`. Combine categories only when both are essential, for example `[fix/perf]`.
269- Keep commits focused. Do not mix unrelated cleanup or formatting into a feature or fix commit.
270- PR bodies must include:
271  1. **Summary:** what changed, the issue or user impact, and why the change is needed.
272  2. **Approach:** important design decisions, technical details, invariants, tradeoffs, and alternatives rejected.
273  3. **Design:** for large architectural changes, Mermaid diagrams showing the relevant before and after data flow, ownership, or lifecycle.
274  4. **Testing:** exact automated commands and results, plus end-to-end UI or MCP scenarios, expected outcomes, and any verification not completed.
275  5. **Change statistics:** aggregate additions and deletions by category, including code logic and tests.
276- Describe the full resulting change, not the sequence of edits made while developing it. Remove stale investigation notes and unsupported claims.
277- Open substantial changes as draft PRs until automated checks pass and required manual UI verification is identified or completed.
278 
279## Voice
280 
281Palmier Pro speaks like a quietly capable native Mac app for filmmakers: direct, technical, calm, and confident. Prefer Apple HIG-style terseness over warmth. Never chatty or cute. Never marketing. When the product needs to ask for action, lead with the action verb; when it reports state, name the thing.
282 
283## Primary references
284 
285- [Improving app responsiveness](https://developer.apple.com/documentation/xcode/improving-app-responsiveness)
286- [Diagnosing performance issues early](https://developer.apple.com/documentation/xcode/diagnosing-performance-issues-early)
287- [Improving performance and stability when accessing the file system](https://developer.apple.com/documentation/foundation/improving-performance-and-stability-when-accessing-the-file-system)
288- [Swift 6.2 Released](https://www.swift.org/blog/swift-6.2-released/)
289- [Embracing Swift concurrency](https://developer.apple.com/videos/play/wwdc2025/268/)
290- [Swift concurrency data-race safety](https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/dataracesafety/)
291- [Task cancellation](https://developer.apple.com/documentation/swift/task/)
292- [Improving your app's performance](https://developer.apple.com/documentation/xcode/improving-your-app-s-performance)
293- [Optimize SwiftUI performance with Instruments](https://developer.apple.com/videos/play/wwdc2025/306/)
294- [Loading media data asynchronously](https://developer.apple.com/documentation/avfoundation/loading-media-data-asynchronously)
295- [Swift Testing](https://developer.apple.com/documentation/testing)
296- [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
297