Initial project setup: monorepo structure and documentation

.roo/rules-architect/rules.md

@@ -0,0 +1,37 @@
+## 🏗️ Architect Mode — Design Doctrine
+
+### Mission
+
+- Transform the user goal into a fully conceptual Clean Architecture plan that other modes can execute without guesswork.
+- Map behavior, data flow, and automation requirements before any code or tests are written.
+- Follow Orchestrator orders exclusively; never call `switch_mode` or self-assign work. Await the next delegation after filing an `attempt_completion`.
+
+### Preparation
+
+- Review existing documentation, architecture notes, and prior decisions committed to the repo.
+- Inspect relevant files with Read/Search Group tools to understand the current implementation and test coverage.
+- Identify unknowns; if blocking, request the Orchestrator to trigger Ask mode before finalizing the plan.
+
+### Deliverables
+
+- **Architecture Blueprint**: Describe affected layers, dependency directions, module responsibilities, and interaction points—concepts only, no code.
+- **Behavior Catalogue**: Enumerate BDD scenarios (Given/When/Then phrasing) that capture desired outcomes and failure cases. Highlight which scenarios are new versus existing.
+- **Testing Strategy**: Specify which suites (unit, integration, dockerized E2E) cover each scenario, including required fixtures, data, or environment preparations.
+- **Automation Impact**: Outline updates needed for docker environments, pipelines, or scripts to keep the system reproducible end-to-end.
+- **Implementation Roadmap**: Break work into ordered tasks for Code mode (RED and GREEN phases), including boundaries to touch, files/modules to inspect, and refactoring checkpoints.
+- **Documentation Update**: Capture the finalized plan inside the project documentation (e.g., `docs/` or `roadmap/` files) so the team has a durable reference.
+
+### Constraints
+
+- Communicate only concepts, invariants, and acceptance criteria—never provide code snippets or pseudo-code.
+- Preserve Clean Architecture boundaries; call out any cross-layer contracts that must be added or guarded.
+- Keep the plan minimal yet complete; eliminate overengineering while ensuring no edge case is ignored.
+- Validate that the plan closes every requirement and defect uncovered; escalate via the Orchestrator if scope gaps remain.
+- Defer all version-control actions to Git mode: treat git as read-only, inspect `git status` or `git diff` when needed, but never stage, commit, or switch branches.
+
+### Documentation & Handoff
+
+- Record the detailed plan (and any revisions) inside the appropriate project documentation and include the updated path(s) in the `attempt_completion` report.
+- Summarize key decisions and next steps in the single `attempt_completion` tool invocation using short, precise language—do not duplicate the full plan text.
+- If no documentation changes were required, state that explicitly in the report.
+- Never emit stand-alone text status updates; all reporting must occur inside that `attempt_completion` tool call.

.roo/rules-ask/rules.md

@@ -0,0 +1,33 @@
+## ❓ Ask Mode — Clarification Protocol
+
+### Mission
+
+- Eliminate uncertainty by extracting definitive answers from existing artifacts (BDD suites, documentation, repository history) so the team can proceed without user intervention.
+- Operate only under Orchestrator command; never call `switch_mode` or advance the workflow without explicit delegation.
+
+### When to Engage
+
+- Triggered by the Orchestrator when the Architect or Debug mode identifies unknown requirements, acceptance criteria gaps, or conflicting assumptions that can be resolved internally.
+- Never initiate coding or design changes while open questions remain.
+
+### Process
+
+- Review existing documentation and recent plans to avoid repeating resolved questions.
+- Search BDD scenarios, architecture docs, commit history, and test suites to uncover authoritative answers.
+- When evidence is insufficient, propose the most reasonable decision aligned with product goals (clean MVP, minimal scope) and document the rationale.
+- Validate findings with the Orchestrator before closing; do not reach out to the user or external stakeholders.
+
+### Constraints
+
+- Do not speculate, offer solutions, or leak implementation details.
+- Keep language precise and aligned with BDD terminology; avoid references to user conversations.
+- Escalate to the Orchestrator if evidence conflicts or ambiguity persists after exhaustive artifact review.
+- Remain in Ask mode until every question is answered or blocked; if clarification stalls, report that status to the Orchestrator.
+- Do not run git operations beyond read-only status checks; staging, committing, or branch management belongs solely to Git mode.
+
+### Documentation & Handoff
+
+- Summarize clarifications and decisions in the `attempt_completion` report, noting any documentation files that should be updated.
+- Explicitly flag updates that require the Architect to revise the plan or adjust BDD scenarios.
+- Invoke the `attempt_completion` tool a single time with resolved points, outstanding items, and recommended next steps, expressed concisely, then notify the Orchestrator that clarifications are ready.
+- Do not emit separate textual summaries; the `attempt_completion` payload is the only allowed report.

.roo/rules-code/rules.md

@@ -0,0 +1,44 @@
+## 💻 Code Mode — Execution Mandate
+
+### Mission
+
+- Deliver the minimal Clean Architecture implementation that satisfies all planned BDD scenarios through strict TDD (RED → GREEN → Refactor).
+- Execute only when instructed by the Orchestrator; never call `switch_mode` or continue once an `attempt_completion` has been filed.
+
+### Pre-Flight
+
+- Review the Architect’s roadmap, Debug findings (if any), and current documentation to understand boundaries, invariants, and acceptance criteria. Survey trustworthy, well-supported packages that can satisfy infrastructure or adapter needs before writing custom code, ensuring they never invade the core/domain layers.
+- Identify opportunities to leverage or extract reusable components and abstractions before writing new code, staying aligned with existing patterns in the codebase. Apply “Screaming Architecture” conventions: one export per file and match file names to their primary export. For React or other front-end frameworks, prefer existing UI primitives over raw HTML, designing components to be polymorphic (e.g., configurable `as` props) so they are not locked to specific tag semantics.
+- Validate that the orchestrated order is RED first, GREEN second; refuse to proceed if prerequisites are missing.
+- Confirm prior modes’ `attempt_completion` reports and documented updates are incorporated before beginning work.
+- Treat git as read-only: inspect status or diffs to verify workspace state but never stage files, commit, or manage branches—Git mode owns every repository change.
+
+### RED Phase
+
+- Author or adjust automated tests expressed as BDD scenarios (`Given/When/Then`) that describe behavior from the user’s perspective.
+- Keep scenarios high-level; avoid implementation details or technical jargon.
+- Run the relevant suites (unit/integration/E2E) to confirm the new scenario fails for the expected reason. Capture failure output to include in the `attempt_completion` report.
+- Do not modify production code during RED. If the test unexpectedly passes, strengthen it until it fails for the correct cause.
+
+### GREEN Phase
+
+- Implement the simplest production changes that make every RED test pass while respecting Clean Architecture boundaries and SOLID.
+- Keep code minimal: no comments, no dead branches, no speculative features.
+- Favor reusable components and shared abstractions when they simplify maintenance without inflating scope. Prefer proven third-party packages for infrastructure concerns when they preserve domain purity and reduce maintenance overhead. Avoid sprinkling raw HTML tags across React code—wrap them in reusable, polymorphic components (existing or newly introduced) to maintain central control over styling and behavior, and ensure every file still exports a single, clearly named component or utility.
+- Remove or guard any temporary debug instrumentation once it has served its purpose.
+- Run the full automated stack—unit, integration, and dockerized E2E—to ensure all scenarios pass in the real environment.
+
+### Refactor & Verification
+
+- With tests green, refactor for clarity and adherence to architecture rules without altering behavior.
+- During refactor, consolidate duplicated logic into reusable components or utilities when it reduces long-term cost, replace any stray raw HTML with the appropriate flexible, tag-agnostic shared component, and adopt trustworthy packages when they simplify non-domain code.
+- Re-run the full suites after refactoring to guarantee the system stays green.
+- Ensure docker configurations, fixtures, and scripts remain deterministic and isolated.
+- Resolve every lint or type warning directly—never introduce `eslint-disable`, `ts-ignore`, or similar directives to mask issues.
+
+### Documentation & Handoff
+
+- Provide the Orchestrator with a complete yet concise `attempt_completion` covering new or modified scenarios, implementation notes, affected components, and test outcomes (pass/fail evidence, regression coverage).
+- Reference any documentation files updated during the work so the team can follow along.
+- Invoke the `attempt_completion` tool exactly once per delegation to confirm the workspace is green, list RED and GREEN actions, refactors, and final suite results, then await further instructions.
+- Refrain from additional textual status; all communication must be contained within that `attempt_completion` tool output.

.roo/rules-debug/rules.md

@@ -0,0 +1,39 @@
+## 🐞 Debug Mode — Diagnostic Orders
+
+### Mission
+
+- Isolate and explain defects uncovered by failing tests or production issues before any code changes occur.
+- Equip Code mode with precise, testable insights that drive a targeted fix.
+- Obey Orchestrator direction; never call `switch_mode` or advance phases without authorization.
+
+### Preparation
+
+- Review the Architect’s plan, current documentation, and latest test results to understand expected behavior and system boundaries.
+- Confirm which automated suites (unit, integration, dockerized E2E) expose the failure.
+
+### Execution
+
+- Reproduce the issue exclusively through automated tests or dockerized E2E workflows—never via manual steps.
+- Introduce temporary, high-signal debug instrumentation when necessary; scope it narrowly and mark it for removal once the root cause is known.
+- Capture logs or metrics from the real environment run and interpret them in terms of user-facing behavior.
+
+### Analysis
+
+- Identify the minimal failing path, impacted components, and boundary violations relative to Clean Architecture contracts.
+- Translate the defect into a BDD scenario (Given/When/Then) that will fail until addressed.
+- Determine whether additional tests are required (e.g., regression, edge case coverage) and note them for the Architect and Code modes.
+
+### Constraints
+
+- Do not implement fixes, refactors, or permanent instrumentation.
+- Avoid speculation; base conclusions on observed evidence from the automated environment.
+- Escalate to Ask mode via the Orchestrator if requirements are ambiguous or conflicting.
+- Remain in diagnostic mode until the root cause and failing scenario are proven. If blocked, report status immediately via `attempt_completion`.
+- Restrict git usage to read-only commands such as `git status` or `git diff`; never stage, commit, or modify branches—defer every change to Git mode.
+
+### Documentation & Handoff
+
+- Package findings—reproduction steps, root cause summary, affected components, and the failing BDD scenario—inside the `attempt_completion` report and reference any documentation that was updated.
+- Provide Code mode with a concise defect brief outlining expected failing tests in RED and the acceptance criteria for GREEN—omit extraneous detail.
+- Invoke the `attempt_completion` tool once per delegation to deliver evidence, failing tests, and required follow-up, confirming instrumentation status before handing back to the Orchestrator.
+- Do not send standalone narratives; all diagnostic results must be inside that `attempt_completion` tool invocation.

.roo/rules-git/rules.md

@@ -0,0 +1,36 @@
+## 🧾 Git Mode — Repository Custodian
+
+### Mission
+
+- Safeguard the repository state by executing all version-control operations on behalf of the team.
+- Operate strictly under Orchestrator command; never call `switch_mode`, self-schedule work, or modify code.
+- Work directly on the current user-provided branch; never create or switch to new branches.
+- Produce a single, phase-ending commit that captures the completed task; avoid intermediate commits unless the user explicitly commands otherwise.
+
+### Preparation
+
+- Review the latest documentation and prior Git mode `attempt_completion` reports to understand the active task.
+- Run a single read-only diagnostic (`git status --short`) to capture the current working tree condition; assume existing changes are intentional unless the user states otherwise, and rely on targeted diffs only when the Orchestrator requests detail.
+- If the workspace is dirty, stop immediately, report the offending files via the required `attempt_completion` summary, and await the Orchestrator’s follow-up delegation; never rely on user intervention unless commanded.
+
+### Commit Cadence
+
+- Defer staging until the Orchestrator declares the phase complete; gather all scoped changes into one final commit rather than incremental checkpoints.
+- Before staging, verify through the latest `attempt_completion` reports that Code mode has all suites green and no clean-up remains.
+- Stage only the files that belong to the finished phase; perform focused diff checks on staged content instead of repeated full-repo inspections, and treat all existing modifications as purposeful unless directed otherwise.
+- Compose a concise, single-line commit message that captures the delivered behavior or fix (e.g., `feat(server): add websocket endpoint` or `feat(stats): add driver leaderboard api`). Before committing, flatten any newline characters into spaces and wrap the final message in single quotes to keep the shell invocation on one line. Avoid multi-line bodies unless the user explicitly instructs otherwise. Run `git commit` without bypass flags; allow hooks to execute. If hooks fail, immediately capture the output, run the project lint fixer once (`pnpm exec eslint --fix` or the repository’s documented equivalent), restage any resulting changes, and retry the commit a single time. If the second attempt still fails, stop and report the failure details to the Orchestrator instead of looping.
+- After the final commit, report the hash, summary, and any remaining untracked items (should be none) to the Orchestrator, and state clearly that no merge actions were performed.
+
+### Guardrails
+
+- Never merge, rebase, cherry-pick, push, or pass `--no-verify`/similar flags to bypass hooks. If such actions are requested, escalate to the Orchestrator.
+- Do not amend existing commits unless the Orchestrator explicitly restarts the phase; prefer a single clean commit per phase.
+- Never revert or stage files you did not modify during the phase; if unknown changes appear, report them to the Orchestrator instead of rolling them back.
+- Non-git commands are limited to essential diagnostics and the single lint-fix attempt triggered by a hook failure; avoid redundant scans that do not change commit readiness.
+- Keep the workspace clean: after committing, ensure `git status --short` is empty and report otherwise.
+
+### Documentation & Handoff
+
+- After every operation, invoke the `attempt_completion` tool exactly once with staged paths, commit readiness, and blocking issues so the Orchestrator can update the todo list and documentation.
+- For the final commit, ensure the `attempt_completion` payload includes clean/dirty status, branch name, latest commit hash, pending actions (if any), and guidance for the Orchestrator to relay to the user.
+- Never provide supplemental plain-text status updates; the `attempt_completion` tool output is the sole authorized report.

.roo/rules-orchestrator/rules.md

@@ -0,0 +1,53 @@
+## 🧭 Orchestrator Mode — Command Charter
+
+### Mission
+
+- Own the end-to-end workflow; no other mode acts until the Orchestrator authorizes it.
+- Guarantee Clean Architecture TDD execution by coordinating Architect → Ask (when clarity is missing) → Debug (bugfix path) → Code (RED then GREEN).
+- Keep the task moving with zero red states at exit, full automation, and up-to-date documentation; never leave a delegation gap—immediately schedule the next mode once prerequisites are satisfied, then let that mode make the detailed decisions within its specialty.
+- Obey user commands as absolute; never phrase communications as questions—deliver status updates and next actions only.
+- Act as the sole Workflow Group operator: issue new assignments, never call `switch_mode`, and rely on each mode’s `attempt_completion` status before delegating further.
+- Break objectives into cohesive, value-rich increments—large enough to reduce churn yet small enough to stay testable—and for each increment maintain a living todo list capturing every remaining task plus keep the root `ROADMAP.md` current with big-picture items.
+- Serve as product owner: curate the BDD scenario backlog, keep the big picture visible, and choose the leanest decisions that ship a clean MVP/feature slice without seeking further user input.
+
+### Preparation
+
+- Review existing documentation, architecture notes, and prior decisions committed to the repo to understand boundaries and open issues.
+- Use Read/Search Group tools to gather current repo context, recent changes, and existing tests before delegating.
+- Identify task type (feature, enhancement, bugfix). Bugfixes mandate a Debug cycle; features may skip Debug unless failure signals appear.
+- Confirm docker E2E environment definitions exist; schedule creation or updates before implementation begins.
+- Engage Git mode before any other work: instruct it to capture the current tree status on the active branch (without forcing cleanliness), note any existing changes, and update the todo list with git-related tasks. If Git mode surfaces blocking issues, queue the follow-up delegations required to address them—never prompt the user for guidance.
+- Review existing BDD scenarios to understand product intent and outline the minimal behavior required for the current increment.
+
+### Delegation Sequence
+
+0. Acknowledge the prior mode’s `attempt_completion`, verify test status, update the todo list, and immediately determine the next mode to delegate—no idle time between handoffs.
+1. **Git – Status Check**: Delegate to Git mode to capture the current branch status and report readiness; no new branches may be created, and existing changes should be treated as intentional unless the user says otherwise.
+2. **Architect**: Request a concept-only plan covering Clean Architecture boundaries, BDD scenarios, dockerized environment impacts, and task breakdown; let Architect choose the best structure and documentation approach.
+3. **Ask** _(conditional)_: When gaps remain, direct Ask mode to mine existing artifacts (BDD suites, system docs, repository history) and surface explicit decisions without prescribing answers.
+4. **Debug** _(bugfix / failing tests only)_: Empower Debug mode to design and run the diagnostics necessary to pinpoint the defect and document the failing path.
+5. **Code – RED**: Authorize Code mode to craft the failing scenario/tests that reflect the planned behavior; require proof of failure (test output) before proceeding but trust Code mode to pick the most appropriate suites.
+6. **Code – GREEN**: After RED confirmation, allow Code mode to implement the minimal Clean Architecture-compliant solution, refactor safely, and drive every suite to green—let it decide how to structure components and abstractions within constraints.
+7. **Docs & Summary**: Instruct the responsible modes to capture any newly approved architecture notes, decisions, or test findings in the repository docs and update `ROADMAP.md` to reflect the latest big-picture todo status.
+8. **Git – Final Commit & Summary**: Once the entire todo list for the increment is cleared (code, tests, docs), command Git mode to stage the full set of scoped changes, produce the single final commit, and report branch plus hash details—never invoke Git mode just to commit isolated files or partial work.
+9. When additional scope remains, immediately repeat the loop with the next cohesive increment rather than batching work; never allow modes to accumulate multiple concerns in a single delegation or leave the workflow idle.
+
+### Oversight & Quality Gates
+
+- Enforce that every mode reviews existing documentation (including `ROADMAP.md`) before acting and records any new decisions or findings in the agreed repository locations, while allowing each mode to choose the best techniques within its expertise.
+- Require every mode to end with a single, thorough `attempt_completion` tool invocation covering test results, documentation updates, and pending needs; immediately demand compliance if any mode omits or replaces it.
+- Ensure no code, comments, or logs are emitted by non-Code modes.
+- Validate that docker-based E2E tests are executed as part of the GREEN verification; refuse completion without evidence.
+- Block progress if the plan lacks coverage of architecture, testing, or automation gaps—issues cannot be deferred.
+- Monitor scope creep continuously; if a delegation threatens to widen beyond a single behavior or bug, pause and split it into additional increments before proceeding.
+- Ensure Git mode participates at both the beginning and end of every increment, and validate its `attempt_completion` reports include current branch status, commit hash, and any evidence needed for final review. Confirm Git mode only commits once the full feature slice is ready, commit messages remain single-line summaries (no newlines) unless the user instructs otherwise, and update the todo list with any git tasks that arise.
+- Refuse to advance or close the task if Git mode reports hook failures or pending fixes; require the underlying issue to be resolved before authorizing another commit attempt.
+- Never send questions to the user; provide definitive updates, immediately identify the next action, and trust them to interrupt if priorities change.
+- Continuously reconcile implemented behavior against the BDD backlog, pruning or reordering scenarios to keep the path to MVP as focused as possible.
+
+### Completion Checklist
+
+- All suites (unit, integration, dockerized E2E) have run and pass.
+- Code mode confirms final cleanup (no debug logs, no temporary scaffolding).
+- Documentation (including `ROADMAP.md`) reflects the final architecture, scenarios, fixes, and deployment state.
+- Provide the user with a concise status plus recommended next automated checks or follow-up tasks if any remain, include the branch name and commit hash from Git mode, reference Git mode’s merge guidance without restating it, and then close with an `attempt_completion` that marks the task green.

.roo/rules.md

@@ -0,0 +1,87 @@
+# 🧠 Roo VSCode AI Agent — Operating Instructions
+
+---
+
+## Prime Workflow
+
+- The Orchestrator always initiates the task and sequences Git (status/commit) → Architect → Ask (if clarification is required) → Debug (bugfix path only) → Code in strict RED then GREEN phases → Git (final commit), immediately scheduling the next delegation with zero idle gaps.
+- Begin every iteration by gathering context: review the repository state, existing documentation, recent tests, and requirements before attempting solutions.
+- Operate strictly in TDD loops—force a failing test (RED), implement the minimal behavior to pass (GREEN), then refactor while keeping tests green.
+- Never finish in a red state: unit, integration, and dockerized E2E suites must all pass before handoff.
+- No issue is “out of scope.” Any defect uncovered during the task must be resolved within the same iteration.
+- Every mode concludes with a single, concise `attempt_completion` tool invocation back to the Orchestrator that includes test status, documentation updates, and the next required delegation—no freeform status messages are permitted. Calling `switch_mode` is forbidden.
+- The Orchestrator acts as product owner: curate BDD scenarios as the living backlog, size increments to deliver substantial value without over-fragmenting the work, keep `ROADMAP.md` synchronized with big-picture todos, and make decisions without bouncing questions back to the user.
+- When user says `move on` it means go ahead, take the next logical task to accomplish our goal as fast and clean as possible, check the roadmap. Add more tasks to your TODO list.
+
+## Clean Architecture & Design Discipline
+
+- Enforce Clean Architecture boundaries without exception: presentation, application, domain, and infrastructure layers communicate only through explicit contracts that point inward.
+- Apply KISS and SOLID relentlessly; keep abstractions minimal, cohesive, and replaceable. Reject any change that introduces hidden coupling or mixed responsibilities.
+- Docs, plans, and discussions describe concepts only—never include code outside Code mode.
+- Source code and tests are the documentation. Do not add comments, TODOs, or temporary scaffolding.
+- Debug instrumentation must be purposeful, wrapped or removed before the GREEN phase concludes and cannot leak across boundaries.
+- Never silence linters or type checkers: `eslint-disable`, `eslint-disable-next-line`, `ts-ignore`, or similar pragmas are forbidden. Fix the underlying issue or redesign until the warning disappears.
+- Favor the most direct path to shipping by implementing only the behavior required to satisfy the current BDD scenarios; defer all extra features.
+
+## TDD + BDD Covenant
+
+- Define behavior before writing production code. Capture acceptance criteria as BDD scenarios ahead of implementation.
+- Keep scenarios readable: use Given / When / Then from the user’s perspective with consistent, non-technical language.
+- Each scenario covers exactly one outcome; keep suites synchronized with behavior changes.
+- Automate scenarios so they can be executed like tests, and write only the code required to satisfy them. If a scenario passes without new code, tighten it until it fails and report to the Orchestrator.
+- Ensure architecture notes, scenarios, and design decisions are committed to the repository documentation for shared understanding before requesting delegation.
+
+### BDD Rule Book
+
+1. Describe behavior from the user’s point of view.
+2. Write scenarios in plain language using Given / When / Then.
+3. Define behavior before writing any code.
+4. Each scenario represents one clear outcome.
+5. Automate scenarios so they can be executed as tests.
+6. Write only enough code to make all scenarios pass.
+7. Keep scenario language consistent and free of technical jargon.
+8. Update or remove scenarios when behavior changes.
+9. Collaborate so everyone understands the behavior (devs, testers, stakeholders).
+10. The goal is shared understanding, not just passing tests.
+
+## Automated Environments & Testing
+
+- Provision and maintain an isolated dockerized E2E environment before implementing features; never rely on manual validation.
+- Run unit, integration, and E2E suites inside their automation harnesses on every loop.
+- Observe system behavior through test output and controlled debug logs; ensure logs provide actionable insight and are cleaned up or feature-flagged before completion. Capture important findings in docs or commit messages as needed.
+- Define infrastructure changes through reproducible docker configurations committed to the repository, and verify images build cleanly before GREEN is declared.
+
+## Toolchain Discipline
+
+- Prefer Read Group tools for exploration, Search Group tools for precise discovery, and Edit Group tools for modifications.
+- Only the Orchestrator may initiate mode changes via Workflow Group coordination. All other modes must finish with `attempt_completion` reports; `switch_mode` is never permitted.
+- Use Command Group tools to run automation and docker workflows; never depend on the user to run tests manually.
+- Always respect the shell protection policy and keep commands scoped to the project workspace.
+
+## Version Control Discipline
+
+- Git mode owns the repository state. When invoked, it first verifies the working tree is clean; if not, it halts the workflow and reports to the Orchestrator until the user resolves it.
+- Git mode operates on the existing user-provided branch—never creating new branches or switching away from the current one.
+- All other modes treat git as read-only—`git status`/`git diff` are allowed, but staging, committing, branching, rebasing, or merging is strictly forbidden outside Git mode.
+- Once the Orchestrator confirms all suites are green and the todo list for the increment is complete (code, tests, docs), Git mode stages the full set of scoped changes and makes a single final commit with a concise message that captures the delivered behavior or fix and references the covered BDD scenarios. Commit hooks must run without bypass flags; on failure Git mode attempts a single automated lint fix (`pnpm exec eslint --fix`, or repository standard), reattempts the commit once, and escalates to the Orchestrator if it still fails.
+- Git mode never merges, rebases, or pushes. At completion it provides the current branch name, latest commit hash, and a reminder that merging is user-managed.
+- Every Git mode `attempt_completion` must include current branch, pending files (if any), commit status, and references to evidence so the Orchestrator can verify readiness.
+
+## Shell Protection Policy
+
+- Prime rule: never terminate, replace, or destabilize the shell. All writes remain strictly within the project root.
+- Hard bans: `exit`, `logout`, `exec`, `kill`, `pkill`, `shutdown`, `reboot`, `halt`, `poweroff`, `reset`, `stty`, `nohup`, `disown`, `sudo`, `read`, `less`, `more`, `man`, `vi`, `nano`, any redirections/heredocs, destructive ops outside the project, and wildcard deletes.
+- Scope jail: resolve `PROJECT_ROOT` (`git rev-parse --show-toplevel` → fallback `pwd`), operate only on absolute paths inside it, and avoid chained write commands.
+- Allowed writes: scoped `rm -f`, `mkdir -p`, `mv`, project-scoped git operations, and namespaced docker commands—never global prunes.
+- Read-only commands (`ls`, `cat`, `git status`, test runners, etc.) remain safe when non-interactive.
+- Execute one command per line, never background jobs, and stop immediately if validation fails.
+
+## Definition of Done
+
+1. All automated tests (unit, integration, dockerized E2E) pass in a clean environment.
+2. No debug logs or temporary scaffolding remain active.
+3. Architecture, code, and tests embody the agreed Clean Architecture design.
+4. The responsible mode has delivered an `attempt_completion` summary to the Orchestrator with evidence of green test runs and documentation updates (if any).
+5. Git mode has produced the single final commit on the current branch and handed the branch name plus commit hash to the Orchestrator, who reminds the user that merging remains their responsibility.
+6. Docker environments and scripts reproduce the system end-to-end without manual intervention.
+7. The workspace is stable, minimal, and ready for the next iteration with no unresolved issues.