---
phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
  - adapter/matrix/reset.py
  - tests/adapter/matrix/test_reset.py
  - README.md
autonomous: true
requirements: []

must_haves:
  truths:
    - "Developers have an explicit dev-only reset command instead of relying on memory or ad hoc shell history."
    - "The default reset mode clears only local Matrix state and explains the manual Matrix-client cleanup that may still be needed."
    - "Optional server cleanup is clearly named around leave/forget semantics and supports dry-run output."
  artifacts:
    - path: "adapter/matrix/reset.py"
      provides: "Dev reset CLI for local-only, server-leave-forget, and dry-run workflows."
    - path: "tests/adapter/matrix/test_reset.py"
      provides: "CLI coverage for local reset behavior and printed operator guidance."
    - path: "README.md"
      provides: "Updated developer instructions for normal restart vs explicit reset."
  key_links:
    - from: "adapter/matrix/reset.py"
      to: "README.md"
      via: "documented invocation and manual Matrix cleanup guidance"
      pattern: "adapter\\.matrix\\.reset"
---

<objective>
Ship the dev reset workflow that complements normal restart reconciliation.

Purpose: D-08 through D-10 require a repeatable, explicit reset path for clean-room QA without making destructive cleanup the default restart flow. This plan creates the tool and updates the runbook developers actually use.
Output: `adapter/matrix/reset.py`, pytest coverage, and README instructions that replace the old `rm -f lambda_matrix.db` ritual.
</objective>

<execution_context>
@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
@/Users/a/.codex/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md
@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md
@README.md
@adapter/matrix/bot.py
@core/store.py

<interfaces>
From `adapter/matrix/bot.py` env usage:

```python
db_path = os.environ.get("MATRIX_DB_PATH", "lambda_matrix.db")
store_path = os.environ.get("MATRIX_STORE_PATH", "matrix_store")
homeserver = os.environ.get("MATRIX_HOMESERVER")
user_id = os.environ.get("MATRIX_USER_ID")
```

From `core/store.py`:

```python
class SQLiteStore:
    def __init__(self, db_path: str) -> None: ...
```
</interfaces>
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Add a dev-only Matrix reset CLI with explicit modes</name>
  <files>adapter/matrix/reset.py, tests/adapter/matrix/test_reset.py</files>
  <read_first>adapter/matrix/bot.py, core/store.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md</read_first>
  <behavior>
    - Test 1: `--mode local-only` deletes the configured local DB/store paths or reports what would be deleted in dry-run mode.
    - Test 2: `--mode server-leave-forget --dry-run` prints the exact rooms it would leave/forget and does not mutate local files.
    - Test 3: when server cleanup is not executed, the command prints the manual Matrix-client steps required by D-10.
  </behavior>
  <action>
Create `adapter/matrix/reset.py` as a CLI entrypoint runnable via `uv run python -m adapter.matrix.reset`. Use `argparse` and keep the tool explicitly dev-only in its help text and logs.

Implement the following modes from research and locked decisions:
- `local-only` (default destructive mode for local QA): remove `MATRIX_DB_PATH` and `MATRIX_STORE_PATH` if they exist; if not, report that they were already absent
- `server-leave-forget`: for the bot account only, log in using the same Matrix env vars as `adapter/matrix/bot.py`, inspect joined rooms, and call `room_leave()` + `room_forget()` for each joined room; support `--dry-run` so the operator can inspect the target set before mutation
- `--dry-run` must work with both modes and print a structured summary instead of mutating files or Matrix membership

Always print a post-run summary that distinguishes:
- what local files/directories were deleted or would be deleted
- what server-side leave/forget actions were executed or would be executed
- the manual Matrix client steps still required for a true clean-room QA rerun (leave/archive old rooms or Space in Element, accept fresh invites, etc.) when those actions are outside this phase

Write `tests/adapter/matrix/test_reset.py` to cover local-only deletion, dry-run output, and server-leave-forget dry-run behavior with fake clients/temporary directories. Follow the repo’s existing lightweight async test style.
  </action>
  <verify>
    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_reset.py -q</automated>
  </verify>
  <acceptance_criteria>
  - `adapter/matrix/reset.py` supports `local-only`, `server-leave-forget`, and `--dry-run`.
  - `local-only` reset targets both `lambda_matrix.db` and `matrix_store` via env-aware paths per D-09.
  - The tool never claims to globally delete Matrix rooms; it uses leave/forget semantics or prints manual cleanup instructions per D-10.
  - `tests/adapter/matrix/test_reset.py` proves dry-run mode is non-destructive.
  </acceptance_criteria>
  <done>The repository contains a repeatable dev reset tool that replaces the undocumented shell ritual and names server-side cleanup honestly.</done>
</task>

<task type="auto">
  <name>Task 2: Replace the README reset ritual with the new restart and reset workflow</name>
  <files>README.md</files>
  <read_first>README.md, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md</read_first>
  <action>
Update `README.md` so Matrix development instructions reflect Phase 01.1 instead of the old destructive reset ritual. Replace the current manual QA block that tells developers to `rm -f lambda_matrix.db` with a short, explicit split:
- normal restart: `PYTHONPATH=. uv run python -m adapter.matrix.bot` now performs reconciliation automatically
- explicit clean-room reset: `PYTHONPATH=. uv run python -m adapter.matrix.reset --mode local-only`
- optional server cleanup preview: `PYTHONPATH=. uv run python -m adapter.matrix.reset --mode server-leave-forget --dry-run`

State clearly that normal restart is the default path per D-05, and that full server-side cleanup may still require manual steps in the Matrix client. Keep the README concise; do not add production guidance or Phase 2 SDK content.
  </action>
  <verify>
    <automated>cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m adapter.matrix.reset --help >/tmp/matrix-reset-help.txt && rg -n "adapter.matrix.reset|local-only|server-leave-forget|reconciliation" README.md /tmp/matrix-reset-help.txt</automated>
  </verify>
  <acceptance_criteria>
  - `README.md` no longer recommends raw `rm -f lambda_matrix.db` as the default Matrix restart workflow.
  - `README.md` documents the normal restart path and the explicit reset path separately.
  - The documented reset commands match the CLI implemented in `adapter/matrix/reset.py`.
  </acceptance_criteria>
  <done>Developers can follow a repeatable README workflow for ordinary restart and clean-room QA reset without relying on tribal knowledge.</done>
</task>

</tasks>

<verification>
Run `pytest tests/adapter/matrix/test_reset.py -q` and `python -m adapter.matrix.reset --help`, then confirm the README commands and help text stay aligned.
</verification>

<success_criteria>
- Dev reset is an explicit tool, not a remembered shell sequence.
- Local-only reset is automated and documented.
- Server cleanup semantics are honest, dry-runnable, and accompanied by manual Matrix-client guidance where needed.
</success_criteria>

<output>
After completion, create `.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-SUMMARY.md`
</output>