# ADR-003: Workspace Isolation\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning required a clear strategy for managing user-specific data, configurations,\nand customizations separate from system-wide installations. Key challenges included:\n\n1. **Configuration Conflicts**: User settings mixed with system defaults, causing unclear precedence\n2. **State Management**: User state (cache, logs, temporary files) scattered across filesystem\n3. **Customization Isolation**: User extensions and customizations affecting system behavior\n4. **Multi-User Support**: Multiple users on same system interfering with each other\n5. **Development vs Production**: Developer needs different from end-user needs\n6. **Path Resolution Complexity**: Complex logic to locate user-specific resources\n7. **Backup and Migration**: Difficulty backing up and migrating user-specific settings\n8. **Security Boundaries**: Need clear separation between system and user-writable areas\n\nThe system needed workspace isolation that provides:\n\n- Clear separation of user data from system installation\n- Predictable configuration precedence and inheritance\n- User-specific customization without system impact\n- Multi-user support on shared systems\n- Easy backup and migration of user settings\n- Security isolation between system and user areas\n\n## Decision\n\nImplement **isolated user workspaces** with clear boundaries and hierarchical configuration:\n\n### Workspace Structure\n\n```\n~/workspace/provisioning/ # User workspace root\n├── config/\n│ ├── user.toml # User preferences and overrides\n│ ├── environments/ # Environment-specific configs\n│ │ ├── dev.toml\n│ │ ├── test.toml\n│ │ └── prod.toml\n│ └── secrets/ # User-specific encrypted secrets\n├── infra/ # User infrastructure definitions\n│ ├── personal/ # Personal infrastructure\n│ ├── work/ # Work-related infrastructure\n│ └── shared/ # Shared infrastructure definitions\n├── extensions/ # User-installed extensions\n│ ├── providers/ # Custom providers\n│ ├── taskservs/ # Custom task services\n│ └── plugins/ # User plugins\n├── templates/ # User-specific templates\n├── cache/ # Local cache and temporary data\n│ ├── provider-cache/ # Provider API cache\n│ ├── version-cache/ # Version information cache\n│ └── build-cache/ # Build and generation cache\n├── logs/ # User-specific logs\n├── state/ # Local state files\n└── backups/ # Automatic workspace backups\n```\n\n### Configuration Hierarchy (Precedence Order)\n\n1. **Runtime Parameters** (command line, environment variables)\n2. **Environment Configuration** (`config/environments/{env}.toml`)\n3. **Infrastructure Configuration** (`infra/{name}/config.toml`)\n4. **Project Configuration** (project-specific settings)\n5. **User Configuration** (`config/user.toml`)\n6. **System Defaults** (system-wide defaults)\n\n### Key Isolation Principles\n\n1. **Complete Isolation**: User workspace completely independent of system installation\n2. **Hierarchical Inheritance**: Clear configuration inheritance with user overrides\n3. **Security Boundaries**: User workspace in user-writable area only\n4. **Multi-User Safe**: Multiple users can have independent workspaces\n5. **Portable**: Entire user workspace can be backed up and restored\n6. **Version Independent**: Workspace compatible across system version upgrades\n7. **Extension Safe**: User extensions cannot affect system behavior\n8. **State Isolation**: All user state contained within workspace\n\n## Consequences\n\n### Positive\n\n- **User Inde
