# HVAC Role Manager - Decision Log

## [2025-04-14 18:58] - Initial Role Manager Design Decisions

### Role Inheritance Architecture
- **Decision**: Implement hierarchical role inheritance with multiple parent support
- **Rationale**: 
  - Allows flexible permission structures
  - Supports complex organizational hierarchies
  - Enables granular permission management
- **Implementation Details**:
  - Roles can inherit from multiple parent roles
  - Capabilities are merged from all parent roles
  - Conflicts are detected and managed explicitly

### Capability Management Approach
- **Decision**: Use WordPress capability system with custom extensions
- **Rationale**:
  - Maintains compatibility with WordPress core
  - Leverages existing security mechanisms
  - Allows seamless integration with plugins
- **Implementation Details**:
  - Extended capability checking for complex scenarios
  - Transaction-based role modifications
  - Automatic capability cleanup

### TEC Integration Strategy
- **Decision**: Implement lightweight TEC capability integration
- **Rationale**:
  - Maintains separation of concerns
  - Ensures compatibility with TEC updates
  - Simplifies maintenance
- **Implementation Details**:
  - Support for TEC-specific capabilities
  - Integration examples in documentation
  - Clear separation between core and TEC functionality

### Security Considerations
- **Decision**: Implement comprehensive security measures
- **Rationale**:
  - Protect WordPress core roles
  - Prevent capability escalation
  - Ensure proper cleanup
- **Implementation Details**:
  - Core role protection
  - Capability validation
  - Transaction role management
  - Automatic cleanup mechanisms

## [2025-04-14 18:58] - Documentation Structure
- **Decision**: Create comprehensive, well-organized documentation
- **Rationale**:
  - Ensures maintainability
  - Facilitates adoption
  - Supports future development
- **Implementation Details**:
  - API reference documentation
  - Integration examples
  - Best practices guide
[2025-04-23 13:19:25] - Debugging MVP integration tests: Identified that Playwright E2E tests fail due to login failure on the staging environment via the custom community login page. The page redirects to wp-login.php instead of the dashboard after submission, without displaying an explicit error. Likely causes are issues with the custom login page's backend processing or redirection logic on staging. Documentation regarding Playwright test execution command and location (`./tests/run-tests.sh pw`) was found to be outdated and has been updated in relevant files (`docs/mvp-integration-testing-plan.md`, `docs/REQUIREMENTS.md`, `wordpress-dev/README.md`, `memory-bank/playwright-test-plan.md`). Further server-side debugging is needed to fix the login issue.
[2025-04-23 16:19:18] - Debugging MVP integration tests: Confirmed that the `test_trainer` user does not exist on the staging environment via WP-CLI. This is the root cause of the Playwright E2E test login failures. Investigation into existing scripts and documentation (`wordpress-dev/bin/`, `tests/`, `docs/testing.md`) did not reveal an automated script for creating these test users on staging. Manual creation or development of a new setup script is required.
  - Testing guidelines

[2025-04-23 19:01:29] - Migration from Docker to Cloudways Staging: Completed the transition from Docker-based local development to using the Cloudways staging server as the primary development and testing environment. This decision was made to simplify the development workflow, ensure consistent testing environments, and reduce setup complexity. All documentation has been updated to remove Docker references and replace them with Cloudways staging server directives. Key benefits include: 1) Consistent environment for all developers, 2) Simplified setup process, 3) Production-like testing environment, 4) Reduced local resource requirements, and 5) Improved collaboration through shared staging environment. Implementation involved updating README.md, MIGRATION_GUIDE.md, and productContext.md to reflect the new workflow.

[2025-04-23 23:16:32] - Decided to modify `deploy-plugin.sh` and `deploy_config.sh` to correct rsync source path interpretation and successfully deploy plugin files to staging.
[2025-04-23 23:16:32] - Identified and corrected role name mismatch in `setup-staging-test-users.sh` (`trainer` to `hvac_trainer`) to enable successful test user creation.
[2025-04-23 23:16:32] - Modified `run-tests.sh` to replace Docker commands with SSH commands targeting staging and explicitly pass `UPSKILL_STAGING_URL` to Playwright.
[2025-04-23 23:16:32] - Increased Playwright timeout and enabled retries in `playwright.config.ts` to address test failures and obtain debugging artifacts.
[2025-04-23 19:12:11] - Deprecated all Docker-based configuration and scripts. Removed Docker variables from dev-env.conf and replaced wp-config-docker.php with a deprecation notice. Cloudways Staging is now the sole supported development and testing environment. This change eliminates confusion, ensures consistency, and aligns all workflows with the current staging infrastructure.