Windsurf Project Rules

# Windsurf Project Rules

## 1. Running Tasks Tracking (`tasks.md`)
- All project tasks must be recorded in `tasks.md` using a clear, unique identifier (e.g., TASK-001).
- Each task entry must include:
  - Task ID and description
  - 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., `user_stories.md`), implementation, and test files
  - Date created and last updated (use ISO 8601 format: YYYY-MM-DD)
- When a new task is created, it must be appended to `tasks.md` with status `🟢 Open`.
- Status must be updated as work progresses. If a task is `🔴 Blocked`, the reason must be documented.
- For tasks spanning multiple codebases or repositories, provide cross-repo traceability links and document any special handling in the task entry.

## 1a. Documentation Standards: `docs/` Folder
- All supporting documentation (except `.windsurfrules.md`) 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 (e.g., prompts, traceability, architecture, security, user stories, etc.).
- Documentation files must be kept up to date as the project evolves.
- The only exception is `.windsurfrules.md`, which remains at the project root for visibility and enforcement.
- Any exceptions or process changes must be documented in `docs/process_exceptions.md` and referenced here.
- When creating architecture diagrams, always use Mermaid syntax for diagram blocks in markdown files (e.g., ```mermaid ... ```).

## 2. Automated Test Enforcement
- For every task, automated tests must be written before implementation (Test-Driven Development/TDD).
- Tests must:
  - Clearly map to the task (reference Task ID in comments)
  - Be located in the appropriate test file(s) and linked from `tasks.md`
  - Initially fail (to prove missing functionality), then pass after implementation
  - Follow project conventions for test file naming and organization (e.g., `tests/test_<module>.py` for Python)
- No task may be marked `Complete` in `tasks.md` unless all related tests pass in CI/CD (pytest for Python, bash for scripts, etc.).
- If a test fails after a task is marked `Complete`, the task status must revert to `🟡 In Progress` until fixed.
- Every project must use the `run.sh` script at the project root to run all tests. To execute all tests, use:

  ```bash
  bash run.sh --test
  ```

  This script:
  - Sets up a Python 3.11 virtual environment (if not already present)
  - Installs dependencies via `pip install -r requirements.txt`
  - Runs all automated tests (e.g., pytest)
  - Exits nonzero on failure and prints clear output
  - Mirrors the setup logic of `run.sh` for consistency and CI/CD compatibility
  - Is kept in sync with environment/dependency logic
- Before proceeding to any new implementation step, **all automated tests must be run and must pass using `bash run.sh --test`**. This applies to every code, documentation, or configuration change. If any test fails, the next implementation step must be blocked until the codebase is green.
- Before proceeding to any new implementation step, **all automated tests must be run and must pass using `bash run.sh --test`**. This applies to every code, documentation, or configuration change. If any test fails, the next implementation step must be blocked until the codebase is green.

## 3. Regression Test Enforcement Before Git Push
- Before every `git push`, all regression tests **must** be run and must pass with zero failures using `bash run.sh --test`.
  - If any test fails, the push must be blocked until all tests pass.
  - 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.

## 4. Traceability & Documentation
- All tasks must be traceable to user stories, implementation, and tests via links in `tasks.md` and the traceability matrix (`docs/traceability_matrix.md`).
- Contributors must update these links as work progresses.
- All changes to rules or process must be documented in this file and referenced in the project `README.md`.
- For tasks or documentation spanning multiple repositories, provide explicit cross-repo links and document any special coordination required.

## 5. Contributor & Automation Guidance
- Contributors must follow these rules for every code or documentation change.
- Automation tools/scripts must:
  - Parse `tasks.md` to enforce status and test requirements
  - Prevent marking tasks as `✅ Complete` if tests are missing or failing
  - Update timestamps and traceability links automatically where possible
  - Ensure the correct status icon is displayed for each task, in the same cell as the status
  - **Explicitly run all related tests and verify they pass before updating status to `✅ Complete` using `bash run.sh --test`**
  - Document any exceptions or edge cases in `docs/process_exceptions.md`.
- When the user requests a tag to be created, Cascade must:
  1. Prompt the user for a tag name and a detailed description of the release contents.
  2. Ask the user if they want to increment the latest/current version number before tagging.
  3. Ensure the tag includes both the version and a descriptive suffix, and is annotated with the full description.
  4. Only proceed with tag creation after explicit user confirmation of name, description, and version.
- When committing and pushing changes, always use a single terminal command combining `git add .`, `git commit`, and `git push` (e.g., `git add . && git commit -am "<message>" && git push`).
- For questions or exceptions, consult the project lead or open an issue, and document the exception in `docs/process_exceptions.md`.

---
_Last updated: 2025-04-23_