Project-Specific Rules: .windsurfrules.md

# Project-Specific Rules: .windsurfrules.md

This file documents project-specific rules, exceptions, and implementation details for this repository. For organization-wide standards, see `global_rules.md`.

## 1. Task Management (`tasks.md`)


### 1.1. Task Tracking
- All project tasks must be recorded in `tasks.md` using a clear, unique identifier (e.g., `TASK-001`). The Windsurf AI IDE should provide tools for easy creation and management of these tasks.
- Each task entry must include:
  - Task ID and a concise, descriptive title.
  - Detailed description of the task.
  - Assignee: The person or team responsible (e.g., `@username` or "AI Cascade").
  - Status: One of [Open, In Progress, Blocked, Complete], with a status icon placed in the same cell as the status (e.g., `🟢 Open`, `✅ Complete`).
    - Status Icons:
      - 🟢 Open
      - 🟡 In Progress
      - 🔴 Blocked
      - ✅ Complete
  - Link(s) to related user stories (e.g., in `docs/user_stories.md`), implementation files, and test files. The IDE should facilitate creating these links.
  - Date created and last updated (use ISO 8601 format: `YYYY-MM-DD`).
  - (Optional) Estimated effort and actual effort (e.g., in hours or story points).
- When a new task is created, it must be appended to `tasks.md` with status `🟢 Open`. The Windsurf AI IDE may offer views to sort/filter tasks by priority, status, or assignee.
- Status must be updated as work progresses. If a task is `🔴 Blocked`, the reason must be documented clearly in the task description or a dedicated "Blocker Reason" field.
- For tasks spanning multiple codebases or repositories, provide cross-repo traceability links and document any special handling in the task entry.


## 2. Documentation Standards

- For comprehensive IAM role and policy authoring, review, and least-privilege best practices, see [.iamrolerules.md](.iamrolerules.md).
- **All contributors must follow the IAM role and policy authoring, review, and least-privilege best practices defined in [.iamrolerules.md](.iamrolerules.md), as well as the organization-wide CI/CD and automation best practices defined in [.cicdrules.md](.cicdrules.md).**

### 2.1. General Documentation (`docs/` Folder)
- All supporting documentation (except this `.windsurfrules.md` file) must be stored as markdown (`.md`) files in the `docs/` directory at the project root.
- Each markdown file in `docs/` should cover a specific topic. Recommended standard filenames include:
    - `architecture.md`
    - `security_practices.md`
    - `user_stories.md`
    - `development_workflow.md`
    - `onboarding.md`
    - `traceability_matrix.md`
    - `process_exceptions.md`
- A `README.md` within the `docs/` folder itself is recommended if the documentation structure becomes complex, explaining the purpose of key documents.
- **All code refactoring must follow the canonical rules and patterns defined in [.refactoringrules.md](.refactoringrules.md), which is based on Martin Fowler’s Refactoring Catalog and tailored for this project.**
- Documentation files must be kept up to date as the project evolves. Changes to documentation should be part of the regular review process. The Windsurf AI IDE may prompt for documentation updates when related code changes are detected.
- All documentation and diagrams must be accessible (e.g., include alt text for images/diagrams, use readable tables).
- When creating architecture or other diagrams, always use Mermaid syntax for diagram blocks in markdown files (e.g., ` ```mermaid ... ``` `). The IDE should offer a preview for Mermaid diagrams.


### 2.2. Rules and Exceptions
- This `.windsurfrules.md` file remains at the project root for visibility and enforcement.
- Any exceptions to these rules or project-specific process changes must be documented in `docs/process_exceptions.md`, referencing the rule number and justification. Approval for exceptions should come from the Project Lead.


## 3. Project Structure & Environment


### 3.1. Required Directory Structure
- The repository must always include `src/` (for source code) and `tests/` (for test code) directories at the project root, even if initially empty.
- Other common directories (e.g., `data/`, `scripts/`, `notebooks/`, `config/`) should be created as needed and their purpose documented in `docs/architecture.md`.
- **Empty required directories must be tracked in Git using a `.gitkeep` file.**
  - Use a `.gitkeep` file (an empty file named exactly `.gitkeep`) inside any directory that is required by project standards but would otherwise be empty, to ensure it is version-controlled.
  - This applies to `src/`, `tests/`, `.github/`, `.github/workflows/`, `infrastructure/`, and any other required directories.
  - `.gitkeep` files should not be used in directories that are expected to be populated immediately or are not required by project standards.
- **All scripts (including `run.sh` and CI/CD jobs) must automatically set up a Python virtual environment, install dependencies from `requirements.txt`, and activate the environment before running tests or Python apps. This should be the default and not require explicit user requests.**
- If a directory required by these rules is empty, a `.keep` file must be placed inside to ensure it is tracked by version control.


### 3.2. Python Project Specifics (`src/` and `tests/` Imports)
- *This section applies to Python-based projects.*
- When using a `src/` layout, Python does not automatically add `src/` to `sys.path` when running tests or applications from the project root. This can cause `ModuleNotFoundError`.
- **Rule:** All test scripts and application entry points must be run with `PYTHONPATH=src` set, e.g.:
  ```bash
  PYTHONPATH=src pytest
  PYTHONPATH=src python src/main_app.py
  ```
- The `run.sh` script (see Section 4.4) and CI/CD pipelines must enforce this for all test invocations and application executions.
- Contributors must NOT use `sys.path` manipulation hacks in test files or application code; rely on `PYTHONPATH` instead.
- The `tests/` directory MUST contain an empty `__init__.py` file. This ensures pytest and Python treat it as a package, preventing import errors and test discovery issues in src-layout projects.
- **Example for specific libraries (e.g., Streamlit):** If using APIs that might be unavailable in certain environments (like Streamlit's widget testing API in a headless CI), tests relying on them must be gracefully skipped.
  ```python
  # In a conftest.py or relevant test file
  import pytest
  try:
      from streamlit.testing.v1 import AppTest
  except ImportError:
      AppTest = None

  # In your test file
  @pytest.mark.skipif(AppTest is None, reason="Streamlit AppTest API not available")
  def test_streamlit_widget():
      # ... your test using AppTest
      pass
  ```
- This ensures consistent import behavior and test discovery across local, CI, and Windsurf AI IDE environments.


## 4. Testing & Quality Assurance


### 4.1. Test-Driven Development (TDD)
- For every task involving new functionality or bug fixes, automated tests must be written *before* implementation begins.
- Tests must:
  - Clearly map to the task (reference Task ID in comments or test names).
  - Be located in the appropriate test file(s) (e.g., `tests/test_<module>.py` for Python) and linked from the corresponding entry in `tasks.md`.
  - Initially fail (to prove the absence of the functionality or presence of the bug).
  - Pass after the implementation is complete.
  - Follow project conventions for test file naming and organization.
- Consider different types of tests (unit, integration, E2E). All types are encouraged and should be runnable via the project's test script.


### 4.2. Test Coverage
- Strive for high test coverage. While a specific percentage is not mandated here (can be project-specific in `docs/architecture.md`), coverage should be regularly reviewed. The Windsurf AI IDE may provide tools to visualize test coverage.


### 4.3. Task Completion Criteria
- No task may be marked `✅ Complete` in `tasks.md` unless all related automated tests pass in the CI/CD pipeline (or locally using `bash run.sh --test`).
- If a test related to a `✅ Complete` task fails subsequently (e.g., due to a regression), the task status must revert to `🟡 In Progress` until the test is fixed and passes.


### 4.4. Centralized Test Execution (`run.sh`)
- Every project must use a `run.sh` script at the project root to run all essential checks.
- To execute all tests, use:
  ```bash
  bash run.sh --test
  ```
- This script must:
  - Set up the necessary environment (e.g., Python virtual environment, install dependencies). For Python, it should respect a specific version (e.g., Python 3.11, potentially managed via `.python-version` and `pyenv`).
  - Install dependencies (e.g., `pip install -r requirements.txt`).
  - Run all automated tests (e.g., using `pytest` for Python, `bash` for shell scripts).
  - (Recommended) Include linting (`bash run.sh --lint`) and formatting checks (`bash run.sh --format`).
  - Exit with a non-zero status code on any failure and print clear, actionable output.
  - Mirror the setup and execution logic used in CI/CD for consistency.
  - Be kept in sync with environment and dependency changes.
- **Golden Rule:** Before proceeding to any new implementation step or pushing code, **all automated tests and checks must be run and must pass using `bash run.sh --test` (and ideally `--lint`, `--format`)**. If any check fails, the next step is blocked until the codebase is green.


## 5. Version Control & CI/CD


### 5.1. Regression Test Enforcement Before Git Push
- Before every `git push`, all automated tests defined in `bash run.sh --test` **must** be run locally and must pass with zero failures.
  - If any test fails, the push must be blocked until all tests pass. This can be automated using local pre-push git hooks, which the Windsurf AI IDE may help configure.
  - This ensures that all previous and current tasks have automated test coverage and remain in a working state.
  - This policy applies to local development, CI/CD, and any automated or manual pushes.


### 5.2. CI/CD Integration
- Continuous Integration/Continuous Deployment (CI/CD) workflows (e.g., using GitHub Actions, GitLab CI, Jenkins) must be implemented.
- CI/CD pipelines must automatically run all tests (`bash run.sh --test`) and other checks (`--lint`, `--format`) on every push and pull/merge request.
- All CI/CD checks must pass before merging changes to the main development branch or deploying.
- The specific CI/CD setup should be documented in `docs/development_workflow.md`.


### 5.3. Branching Strategy
- A consistent branching strategy (e.g., GitFlow, GitHub Flow, Trunk-Based Development) must be followed.
- The chosen strategy must be documented in `docs/development_workflow.md`.
- Feature branches should be named descriptively, often referencing the Task ID (e.g., `feature/TASK-123-add-user-login`).


### 5.4. Commit Message Conventions
- Commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
  - Example: `feat(auth): implement OTP login (resolves TASK-042)`
- This aids in changelog generation and semantic versioning. Cascade may assist in drafting or validating commit messages based on `tasks.md` and staged changes.


### 5.5. Code Review Process
- All code and significant documentation changes must be reviewed and approved by at least one other contributor (not the author) before being merged into the main development branch.
- The Windsurf AI IDE may offer tools to facilitate code reviews, potentially including preliminary automated checks against these rules.
- The review process specifics should be documented in `docs/development_workflow.md`.


### 5.6. Tagging and Versioning
- All tags must follow semantic versioning: `vX.Y.Z` or `vX.Y.Z-description`.
- When the user requests a tag to be created, Cascade (the Windsurf AI assistant) must:
  1. Prompt the user for a tag name and a detailed description of the release contents (changelog).
  2. Ask the user if they want to increment the latest/current version number (major, minor, patch) before tagging, consistent with Semantic Versioning principles.
  3. Ensure the tag includes both the version and, if applicable, a descriptive suffix (e.g., `v1.2.3-beta1`).
  4. Ensure the tag is an annotated tag (`git tag -a`) containing the full description/changelog.
  5. Only proceed with tag creation after explicit user confirmation of the tag name, version, and description.


### 5.7. Pushing Changes
- For atomic changes related to a single logical unit of work, prefer combining `git add`, `git commit`, and `git push` into a sequence that ensures all parts are handled.
- A recommended pattern for focused changes:
  1. Review changes with `git status` and `git diff`.
  2. Stage precisely with `git add <specific files>` or `git add -p`.
  3. Commit with a conventional message: `git commit -m "type(scope): message"`
  4. Push: `git push`
- Avoid broad `git add .` unless all unstaged changes are verified. The Windsurf AI IDE may offer a guided commit-and-push workflow.


## 6. Contributor & Automation Guidance


### 6.1. Adherence to Rules
- All contributors (human or AI) must follow these rules for every code or documentation change.
- An `docs/onboarding.md` guide should be maintained to help new contributors understand these rules and project setup.


### 6.2. Automation and AI (Cascade) Interaction
- Automation tools and scripts, including the Windsurf AI IDE and Cascade, must:
  - Parse `tasks.md` to enforce status, assignee, and test requirements.
  - Prevent marking tasks as `✅ Complete` if related tests are missing or failing.
  - Update timestamps and traceability links automatically where possible. The Windsurf AI IDE should assist in maintaining `docs/traceability_matrix.md`.
  - Maintain a markdown log file (e.g., `.cascade_interactions.md`) at the repository root capturing every user prompt and Cascade response. Update this log on each interaction to preserve conversational history and for audit purposes.
  - Ensure the correct status icon is displayed for each task in `tasks.md`.
  - **Explicitly run all related tests (`bash run.sh --test`) and verify they pass before suggesting or applying a status update to `✅ Complete`.**
  - Document any exceptions or edge cases encountered during automation in `docs/process_exceptions.md`.
  - Reference automation scripts by filename/location where applicable.
  - Assist in maintaining `docs/traceability_matrix.md` by linking tasks, code, tests, and user stories.
  - **For any non-trivial or multi-step CLI logic in CI/CD workflows, contributors and automation must move the logic into dedicated scripts (e.g., Bash or Python) and invoke those scripts from the workflow file. This improves maintainability, testability, and robustness. Reference this as a best practice for all future workflow development.**


### 6.3. Security Practices
- All code and documentation must comply with project security best practices, as outlined in `docs/security_practices.md`.
- **No sensitive credentials, API keys, or secrets may be committed to the repository.**
  - Use secure secret management solutions (e.g., AWS Secrets Manager, HashiCorp Vault, environment variables injected at runtime).
  - Ensure `.gitignore` is properly configured to exclude secrets, local configuration files, and build artifacts.
- Regularly scan dependencies for vulnerabilities.
- The Windsurf AI IDE may offer tools to scan for accidental secret exposure or vulnerable patterns.


### 6.4. Linting and Formatting
- Code must be consistently formatted and free of linting errors.
- Linters (e.g., Flake8 for Python, ESLint for JavaScript) and formatters (e.g., Black for Python, Prettier for JavaScript/TypeScript) must be configured for the project.
- These checks should be runnable via `bash run.sh --lint` and `bash run.sh --format` and integrated into pre-commit hooks and CI/CD pipelines. The Windsurf AI IDE should support or run these tools automatically.


## 7. Rule Exceptions & Queries
- For questions, clarifications, or proposed exceptions to these rules, consult the Project Lead or open an issue in the project's issue tracker.
- Approved exceptions must be documented in `docs/process_exceptions.md`, including the rationale and approval details.


---

_Last updated: 2025-06-07_