MacMonitor/AGENTS.md

AGENTS.md: Developer & AI Agent Operating Guide

Welcome to MacMonitor. This document serves as the authoritative operating manual for autonomous AI coding agents and human engineers contributing to this repository.

---

1. Non-Negotiable Architectural Rules

1. Architecture & Target OS:
   • The target architecture is Intel x86_64 exclusively. Do not introduce Apple Silicon ARM64-only assembly, intrinsics, or dependencies.
   • The minimum deployment target is macOS 14.0 (Sonoma). Do not downgrade deployment targets or use deprecated Carbon APIs.
2. Language Boundaries:
   • UI & Presentation: Modern SwiftUI with @Observable, @MainActor, and Swift Charts.
   • Kernel & Telemetry: Objective-C / C communicating directly with Mach kernel, IOKit, BSD sysctls, and CoreFoundation.
   • Bridging: All Objective-C headers exposed to Swift must be declared in Sources/Bridging/MacMonitor-Bridging-Header.h.
3. Gitea MCP Tool Usage:
   • Whenever performing repository operations, creating branches, reviewing issues, updating comments, or managing pull requests on git.i3omb.com, always use the available tools on the gitea MCP server (call_mcp_tool with ServerName: "gitea").
   • Never use raw shell scripts (curl, raw tokens) to interact with the Gitea API.

---

2. Deterministic Branching Strategy & Workflow

Every feature implementation must follow the branch taxonomy defined in BUILD-PLAN.md:

gitGraph
   commit id: "Initial commit"
   branch develop
   checkout develop
   commit id: "Docs & Build Plan"
   branch milestone/m1-foundation
   checkout milestone/m1-foundation
   branch feat/1-core-architecture
   checkout feat/1-core-architecture
   commit id: "MMTelemetryCoordinator"
   checkout milestone/m1-foundation
   merge feat/1-core-architecture id: "PR #1 Merged"
   branch feat/2-smc-client
   checkout feat/2-smc-client
   commit id: "AppleSMC IOKit client"
   checkout milestone/m1-foundation
   merge feat/2-smc-client id: "PR #2 Merged"
   checkout develop
   merge milestone/m1-foundation id: "M1 Complete"

2.1 Branch Naming Directory

When picking up an issue, you must use the exact branch name assigned to that issue:

• Issue #1: feat/1-core-architecture (branch from milestone/m1-foundation)
• Issue #2: feat/2-smc-client (branch from milestone/m1-foundation)
• Issue #25: feat/25-gitea-ci (branch from milestone/m1-foundation)
• Issue #3: feat/3-cpu-thermals (branch from milestone/m2-primary-telemetry)
• Issue #4: feat/4-fan-telemetry (branch from milestone/m2-primary-telemetry)
• Issue #5: feat/5-cpu-load (branch from milestone/m2-primary-telemetry)
• Issue #8: feat/8-ram-breakdown (branch from milestone/m2-primary-telemetry)
• Issue #9: feat/9-storage-volumes (branch from milestone/m2-primary-telemetry)
• Issue #18: feat/18-component-temps (branch from milestone/m2-primary-telemetry)
• Issue #19: feat/19-power-voltage (branch from milestone/m2-primary-telemetry)
• Issue #6: feat/6-kernel-counters (branch from milestone/m3-advanced-telemetry)
• Issue #7: feat/7-load-averages (branch from milestone/m3-advanced-telemetry)
• Issue #10: feat/10-disk-io (branch from milestone/m3-advanced-telemetry)
• Issue #11: feat/11-process-explorer (branch from milestone/m3-advanced-telemetry)
• Issue #12: feat/12-process-threads (branch from milestone/m3-advanced-telemetry)
• Issue #14: feat/14-gpu-telemetry (branch from milestone/m3-advanced-telemetry)
• Issue #15: feat/15-network-throughput (branch from milestone/m3-advanced-telemetry)
• Issue #16: feat/16-network-sockets (branch from milestone/m3-advanced-telemetry)
• Issue #17: feat/17-battery-telemetry (branch from milestone/m3-advanced-telemetry)
• Issue #20: feat/20-bus-topology (branch from milestone/m3-advanced-telemetry)
• Issue #21: feat/21-audio-status (branch from milestone/m3-advanced-telemetry)
• Issue #13: feat/13-display-brightness (branch from milestone/m4-presentation)
• Issue #22: feat/22-menubar-popover (branch from milestone/m4-presentation)
• Issue #23: feat/23-trend-charts (branch from milestone/m4-presentation)
• Issue #24: feat/24-threshold-alerts (branch from milestone/m5-alerts-hardening)

---

3. Telemetry Provider Implementation Invariants

Every low-level telemetry provider created by an agent must conform to the following contract:

3.1 Contract Interface

@protocol MMTelemetryProvider <NSObject>
@property (nonatomic, readonly) MMTelemetryDomain domain;
@property (nonatomic, readonly, copy) NSString *providerIdentifier;
@property (nonatomic, readonly, getter=isAvailable) BOOL available;

- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error;
@optional
- (void)startMonitoring;
- (void)stopMonitoring;
@end

3.2 Critical Memory Management Rules

• Mach Pointer Deallocation: Any call to host_processor_info allocates a Mach virtual memory buffer. Always invoke vm_deallocate(mach_task_self(), (vm_address_t)ptr, size) on previous iterations.
• IOKit Registry Release: Every io_registry_entry_t or io_iterator_t returned by IOServiceGetMatchingServices or IOIteratorNext must be balanced with IOObjectRelease().
• IOKit Connection Cleanup: Close user clients using IOServiceClose() in dealloc or sleep handlers.
• Autorelease Pool Scoping: Wrap sampling logic inside @autoreleasepool { ... } blocks to reclaim temporary CoreFoundation/Objective-C allocations immediately on each timer tick.

---

4. Concurrency & Thread-Safety Invariants

1. Zero UI Blocking: Under no circumstances may low-level C calls (IOKit, Mach, sysctl) be invoked directly on the main thread (@MainActor). All sampling occurs exclusively on com.i3omb.macmonitor.telemetry (QOS_CLASS_UTILITY).
2. Value-Type Boundaries: Data passed from Objective-C to Swift view models must be immutable snapshot copies (primitive scalars, strings, or Sendable structs). Never pass mutable Objective-C object references into SwiftUI views.
3. Fast Mutex Synchronization: For shared state (such as SMC key caches or ring buffers), use os_unfair_lock or NSLock. Do not use @synchronized(self).

---

5. Testing & Verification Requirements

5.1 Synthetic Hardware Mocking in CI

When writing unit tests for Gitea Actions runners (which may execute in headless virtual machines without physical SMC chips):

• Never assert that physical hardware calls return live metrics in unit tests.
• Structure providers with dependency injection to accept synthetic binary test buffers:

  // Test mock SMC byte decoding
  uint8_t mockTempBytes[2] = { 0x36, 0x80 }; // 54.5°C in sp78 format
  float temp = [MMSMCParser decodeSP78:mockTempBytes];
  XCTAssertEqualWithAccuracy(temp, 54.5, 0.01);
  

• Mock Mach host statistics using recorded structs to verify delta load calculation algorithms.

5.2 Build Command Verification

Before opening any Pull Request, ensure that the project compiles cleanly for Intel x86_64:

xcodebuild build test \
  -scheme MacMonitor \
  -destination 'platform=macOS,arch=x86_64' \
  CODE_SIGNING_ALLOWED=NO

---

6. Label & Issue Conventions on Gitea

• Tagging: Every issue, PR, and milestone must carry the Project/Antigravity label.
• Components: Tag issues with functional area labels:
  • Feature/Architecture or Bug/Architecture
  • Feature/Backend or Bug/Backend
  • Feature/UI or Bug/UI
  • Feature/DevOps or Bug/DevOps
• Priorities: Must accurately reflect system value (Priority/Critical, Priority/High, Priority/Medium, Priority/Low).
• Dependencies: Keep cross-references updated in the issue body under ### Dependencies.