surfaces/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
01.1-matrix-restart-reconciliation-and-dev-reset-workflow	03	execute	1		adapter/matrix/reset.py tests/adapter/matrix/test_reset.py README.md	true		truths artifacts key_links 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. path provides adapter/matrix/reset.py Dev reset CLI for local-only, server-leave-forget, and dry-run workflows. path provides tests/adapter/matrix/test_reset.py CLI coverage for local reset behavior and printed operator guidance. path provides README.md Updated developer instructions for normal restart vs explicit reset. from to via pattern adapter/matrix/reset.py README.md documented invocation and manual Matrix cleanup guidance adapter.matrix.reset

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.

<execution_context> @/Users/a/.codex/get-shit-done/workflows/execute-plan.md @/Users/a/.codex/get-shit-done/templates/summary.md </execution_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 From `adapter/matrix/bot.py` env usage:

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:

class SQLiteStore:
    def __init__(self, db_path: str) -> None: ...

Task 1: Add a dev-only Matrix reset CLI with explicit modes adapter/matrix/reset.py, tests/adapter/matrix/test_reset.py adapter/matrix/bot.py, core/store.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md - 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. 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. cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_reset.py -q <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> The repository contains a repeatable dev reset tool that replaces the undocumented shell ritual and names server-side cleanup honestly.

Task 2: Replace the README reset ritual with the new restart and reset workflow README.md 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 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. 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 <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> Developers can follow a repeatable README workflow for ordinary restart and clean-room QA reset without relying on tribal knowledge.

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.

<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>

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