149 lines
7.9 KiB
Markdown
149 lines
7.9 KiB
Markdown
---
|
||
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>
|