AirCoding/AirPlan/docs/architecture/decisions-round-2.md

Architecture Decisions — Round 2

Date: 2026-05-26 Source: idea.md discussion, questions 19–30

D-021: Project Model Version Migration

• Decision: Backup before migrate, user confirmation required.
• Mechanism: On opening a project with old-version project.json, auto-detect and prompt user. Backup to ~/.air/projects/<id>/backups/ before migration. Migration failure → rollback to backup, notify user.

D-022: Scanner — Full Directory Tree, No Exclusions

• Decision: Scanner collects complete directory tree (file system metadata only — paths, extensions, file types), no recursion depth limit, no directory exclusions.
• Why: Directory tree traversal is fast (kernel inode walk), and the full tree provides useful structural information (e.g., detecting referenced components). File content is NOT read during scanning.
• Timeout: 15 seconds hard timeout as safety net. On timeout, return partial results with incomplete marker.
• Update strategy: First scan is full. Subsequent scans are incremental (mtime diff). On re-open, load project.json + quick check for top-level directory changes; trigger incremental scan only if changes detected.
• Informed by: Claude Code's zero-pre-scan approach (agentic search, no indexing), OpenCode's Tree-sitter AST + LLM hybrid.

D-023: Project Rules Format — Markdown + Frontmatter

• Decision: Claude Code style — Markdown body with YAML frontmatter for structured metadata. Human-readable, git diff friendly, LLM natively understands.
• Storage: ~/.air/projects/<id>/project-rules.md (project-authoritative). Export via air memory export --project-rules AIR.md.
• Informed by: Claude Code's CLAUDE.md format with frontmatter metadata.

D-024: ExperienceMiner — Mid-Session Trigger + Curator + Self-Patch

• Decision:
  • Triggers: DebugRecord produced + session end + N-turn interval (Hermes-style Nudge Engine counter, ~10 turns or 10 tool calls). Background sub-agent, never blocks Main Agent.
  • Scope: Full extraction, no range limits. LLM decides what's worth saving.
  • Validation: Non-debug experiences use occurrence count (N=3) as threshold for promotion prompt. Debug experiences use evidence (build/test pass) as confidence; no numeric score needed.
  • Deduplication: Curator Daemon runs periodically (weekly), identifies overlapping skills, suggests merges, marks stale entries, archives unused ones.
  • Self-patch: When agent finds existing skill/rules wrong during execution, forwards to ExperienceMiner to patch.
  • Data format: SKILL.md (YAML frontmatter + Markdown body) under ~/.air/skills/. Memories in ~/.air/projects/<id>/learned-memory.db.
• Informed by: Hermes Agent's Nudge Engine, Curator Daemon, self-patching mechanism, and SKILL.md format.

D-025: Context Compaction — Rule-File Driven, Copy-on-Write, Async

• Decision:
  • Trigger: 70% of context window capacity.
  • Strategy: Rule-file driven with three-tier inheritance (system default → user template at ~/.air/compaction-rules.yaml → project override at .air/compaction-rules.yaml). System default template ensures projects without custom rules work normally. Editing user template affects all future new projects.
  • Mechanism: Copy-on-Write. On trigger, snapshot current messages 1-N. Compression runs asynchronously (independent Compactor sub-agent). New messages continue appending to original chain. On completion, a compaction marker is inserted between the compressed summary and post-snapshot messages. LLM sees: summary + marker + new messages. Original messages preserved for explicit LLM backtracking.
  • Executor: Independent Compactor sub-agent (not ContextAssembler, not Main Agent).

D-026: Permission — Symlink Physical Resolution

• Decision: Symlinks resolved to physical path (follow realpath). This prevents project escape via symlink chains.

D-027: Permission — .git/ Write Protection

• Decision: .git/ directory write-protected by default (requires user confirmation). Can be overridden in .air/permissions.yaml project settings.

D-028: Permission — Build Directory Unrestricted

• Decision: Build directories (build/, out/, etc.) have no special restrictions. C++ packaging workflows require agent ability to manually organize runtime libraries (.so/.dll deployment, rpath, resource file organization), so build directory access must be unrestricted.

D-029: Permission — ~/.air/ System-Managed

• Decision: ~/.air/ and all contents are managed by AirCoding internally. PermissionEngine does not check AirCoding's own internal operations.

D-030: Backup — Git-Based Repo

• Decision: Project-external file backup is a git repository at ~/.air/projects/<id>/backups/. Each external file modification: cp to backups/ → git add && git commit (commit message: session_id, agent_type, reason). Version history, diff, compression all provided by git natively. air restore --list → git log; air restore --session <id> → git log --grep <id>. User manually deletes backups; no automatic cleanup.

D-031: High-Risk Action Detection — Static Path Whitelist + LLM Escape Hatch

• Decision: Static path whitelist covers clearly-system paths (/etc/fstab, /boot/, /etc/default/grub, Windows registry system hives). sudo is NOT treated as high-risk (development machines need it for routine operations). LLM judgment only used as escape hatch when path matching can't decide.

D-032: Restore Granularity

• Decision: Three levels — single file (most recent backup), specified time point, entire session. Git-backed storage makes all three straightforward.

D-033: Testing Strategy

• Decision: Three layers:
  • Unit tests (bun test, CI per push, <30s, no LLM): Tool schema validation, PermissionEngine, ContextAssembler token math, EventBus routing, build system detection, config loading priority.
  • Integration tests (CI per push, <1min, recorded LLM fixture replay): Agent Loop state machine, Scheduler dependency resolution, sub-agent spawn → IPC → WorkerResult, session persist/restore, compaction Copy-on-Write, worktree lifecycle.
  • E2E tests (Release gate, real LLM): Full C++ project scenarios — add function + test, fix build error, multi-task dependency order, session resume. Must pass before every release.

D-034: Distribution — Binary Tarball

• Decision: Binary distribution (Bun compile standalone executable, bundled Bun runtime). Distribution package = binary executable + Python scripts + default resource files (compaction rule templates, HUD presets, etc.). No public npm/channel until stable. Language-specific toolchains are first-class plugins, not bundled special treatment.

D-035: Logging — Dual-File, 7-Day Retention

• Decision:
  • air.log — User-readable. Records startup failures, exceptions, environment configuration issues. Helps users self-diagnose.
  • air.developer.log — Full debug log, encrypted (may contain user privacy data, only decryptable by development team). Performance metrics written here. 7-day retention, auto-rotated.
  • Crash diagnostics: air doctor command collects version info, system environment, recent logs, crash stack trace into diagnostic package. Auto-detect abnormal exit on next startup, prompt user.

D-036: Multi-Language Extension — Per-Language toolchain-* Packages

• Decision: Runtime (Agent Loop, Session, Scheduler, ToolRegistry, PermissionEngine) is language-agnostic. Each language is a toolchain-<lang> package + a LanguageDetector plugin implementing a common interface. Adding a new language = adding a toolchain-python/toolchain-rust etc. package, no core changes required. MVP ships with toolchain-cpp.

D-037: Compaction Rules — Three-Tier Inheritance

• Decision: System default (built-in, never deleted, always fallback) → User template (~/.air/compaction-rules.yaml, editable, affects all future new projects) → Project rules (.air/compaction-rules.yaml, project-specific, highest priority).