# Plan: Multilingual Hello-World State Machine

## Context
The project is a fresh Python project with no existing source files. We need to build a
`StateMachine` class that cycles through language states (English → Spanish → English …),
printing "hello world" in the current language on each step, and a pytest test suite that
verifies the output of each language state.

---

## Files to Create

| Path | Purpose |
|------|---------|
| `state_machine.py` | `StateMachine` class + language state definitions |
| `tests/test_state_machine.py` | pytest unit tests |
| `pytest.ini` (or `pyproject.toml`) | minimal pytest config so `pytest` discovers `tests/` |

---

## Implementation Design

### `state_machine.py`

```python
class StateMachine:
    STATES = [
        {"name": "english", "greeting": "Hello, World!"},
        {"name": "spanish", "greeting": "¡Hola, Mundo!"},
    ]

    def __init__(self):
        self._index = 0

    @property
    def current_state(self) -> str:
        return self.STATES[self._index]["name"]

    def greet(self) -> str:
        """Return the greeting for the current state (does NOT advance)."""
        return self.STATES[self._index]["greeting"]

    def step(self) -> str:
        """Print the current greeting, then advance to the next state. Returns the greeting."""
        greeting = self.greet()
        print(greeting)
        self._index = (self._index + 1) % len(self.STATES)
        return greeting
```

Key design decisions:
- `STATES` list drives ordering — easy to extend later.
- `step()` both acts (print) and returns the greeting so tests can assert on the value.
- Cycling uses modulo arithmetic for clean wrap-around.

### `tests/test_state_machine.py`

Tests cover:
1. Initial state is English.
2. `greet()` returns correct English greeting without advancing.
3. `step()` returns English greeting and advances to Spanish.
4. `greet()` returns correct Spanish greeting.
5. `step()` returns Spanish greeting and wraps back to English.
6. Full cycle: two consecutive `step()` calls produce English then Spanish.
7. `capsys` fixture verifies `step()` actually prints the greeting to stdout.

### `pytest.ini`

```ini
[pytest]
testpaths = tests
```

---

## Audit Logging

Per `CLAUDE.md`, before implementing log a `plan_stated` event:
```bash
bash audit/agent-report.sh "$SESSION_ID" "plan_stated" \
  "Implementing multilingual hello-world state machine with English/Spanish states and pytest tests"
```

---

## Verification

```bash
# Run all tests
pytest

# Expected: all tests pass, output similar to:
# tests/test_state_machine.py ......   6 passed in 0.XXs
```