docs: archive completed superpowers plans

AGENTS.md

@@ -1,11 +1,18 @@
-# pitfalls
+# pitfalls / guide
 
 prefer asserts actual['field'] == expected['field'] over assert actual == expected unless we know better (eg. no extra fields allowed)
 
 Prefer pytest `tmp_path` for test-local filesystem state. Avoid fixed paths under `local_temp_root()` for tests that create durable files unless the test explicitly cleans or needs cross-process persistence; stale files there can change later test runs.
 
+Now that pytest-asyncio is installed, prefer `async def test_x()`
+instead of `def test_x(): async def scenario(): ...; asyncio.run(scenario())`
+
 more later
 
+## Docs mgmt
+
+read docs/AGENTS.md
+
 # Test suite
 
 ```bash

docs/AGENTS.md

@@ -0,0 +1,60 @@
+# docs management
+
+its the age old problem. code changes, but i dont bother fixing docs. its been here before me, before chatgpt, and after chatgpt.
+
+## lets improve this
+
+check [README.md](README.md) as pointers. they point to live evolving docs.
+
+a good docs pass, searching for kw, changing the documents that have them. cool. dedicated docs pass after a Thing done. great.
+
+ACTIVE (planned, running) implementation plans and specs sit in their folders.
+`superpowers/plans/` is only for executable handoff plans that are active or in
+progress.
+
+DONE docs go straight to [`historical/`](historical/). Prefer keeping the OG
+path shape under `docs/historical/`, for example
+`docs/superpowers/plans/foo.md` -> `docs/historical/superpowers/plans/foo.md`.
+You can edit the top of the file to state that its historical, but just being
+in the folder is enough.
+
+superpowers skills say to tick those boxes; do tick those boxes.
+
+stale docs, even at docs/, go to historical/ or git rm.
+
+user facing docs need updates too. User facing docs include [/skills](../skills/)
+
+## roadmap plans?
+
+in superpowers plans there are now suddenly some big plans, like roadmaps, with multiple slices that turn into dedicated implementation plans.
+
+Those need linking, active or done. Since any done plans go to `historical/**`,
+live docs must point to `historical/**` when they cite old slice plans.
+
+`current_roadmap.md` is the live roadmap. Roadmap-shaped plan files are
+historical context unless they are actively being used to drive this exact next
+slice.
+
+## superpowers specs? (generalize to docs/)
+
+Any specs files in that folder represent the current state of the code. Ok
+anything at docs/ do. Hence, if a Thing replaces another, something has to go to
+the historical/.
+
+as i said before. readme points to LIVE, Evolving docs. cant have stale/superseded stuff in here.
+
+Same stuff for skills!
+
+If a spec is still a useful design contract, update it in place. If it is only
+"how we got here", move it to `historical/**`. Do not leave two docs claiming
+different current behavior.
+
+## Important rules
+
+When moving or retiring docs, search for the old filename and update live links:
+`docs/README.md`, `docs/current_roadmap.md`, skills, and nearby architecture
+docs are the usual places.
+
+If code has a partial implementation and docs mention the limitation, add a
+short comment or docstring at the code seam too. Future agents see code before
+they see old plans.

docs/README.md

@@ -78,9 +78,9 @@ implementation plans are kept for context, not as active instructions.
   design notes.
 - [`historical/path_mapping_scratch.md`](historical/path_mapping_scratch.md):
   older path and mapping design thread.
-- [`superpowers/plans/`](superpowers/plans/): mostly completed implementation
+- [`superpowers/plans/`](superpowers/plans/): active executable handoff plans
-  plans and execution records. Use them for context, not as the primary source
+  only. Completed or stale plans are archived under
-  of truth.
+  [`historical/superpowers/plans/`](historical/superpowers/plans/).
 - [`superpowers/specs/`](superpowers/specs/): design specs produced during
   planning sessions.
 

docs/current_roadmap.md

@@ -134,8 +134,8 @@ implementation state.
       connections: `locked` entries stay operator-owned, while `seed` entries
       bootstrap missing store entries and then let the store own later admin
       changes.
-   - Next source registry slices are planned in
+   - Historical source registry slice planning is archived in
-      [2026-06-03 source registry next slices](./superpowers/plans/2026-06-03-source-registry-next-slices.md):
+      [2026-06-03 source registry next slices](./historical/superpowers/plans/2026-06-03-source-registry-next-slices.md):
       desired-registry admin reads and safe mutation commands are complete;
       concrete MCP-backed `WorkflowServer` construction remains future work.
    - Completed: desired-registry admin read plumbing is available through
@@ -239,8 +239,8 @@ implementation state.
   `wf.workflow.run_deployment` remains the dependable front door.
 - **Dashboard/source controls**: future UI should consume the same source
   inventory and deployment metadata instead of reverse-engineering MCP tools.
-- **Workflow API extraction**: continue the staged extraction in
+- **Workflow API extraction**: completed staged extraction context is archived in
-  [wf_api extraction roadmap](./superpowers/plans/2026-06-01-wf-api-extraction-roadmap.md).
+  [wf_api extraction roadmap](./historical/superpowers/plans/2026-06-01-wf-api-extraction-roadmap.md).
   Protocol-neutral operation context and domain services now exist behind
   `wf_api`; MCP tool schemas and tool registration stay in `wf_mcp`.
   - Workflow store ownership is explicit: entrypoints construct/inject `WorkflowStores`; `WfMcpService` no longer guesses stores from the MCP store root.

docs/superpowers/plans/README.md

@@ -0,0 +1,11 @@
+# Active Implementation Plans
+
+This directory is for executable agent handoff plans only.
+
+Keep a plan here only while it is active or in progress. When the work is
+complete, stale, invalid, or only useful as background context, move the file to
+`docs/historical/superpowers/plans/`.
+
+Roadmap-shaped planning docs should not live here as the source of truth. Use
+`docs/current_roadmap.md` for active direction, and archive older roadmap plans
+under `docs/historical/`.

docs/superpowers/research/2026-06-02-wfmcpservice-remaining-responsibilities.md

@@ -52,7 +52,7 @@ Extract a resource/prompt access service, tentatively named
 
 **Done:** `ContentAccessService` now owns `read_resource` and `render_prompt`.
 `WfMcpService` delegates both methods. See plan:
-`docs/superpowers/plans/2026-06-02-wfmcpservice-resource-prompt-access-extraction.md`.
+`docs/historical/superpowers/plans/2026-06-02-wfmcpservice-resource-prompt-access-extraction.md`.
 
 Keep out of scope for that slice:
 

docs/wf_mcp_architecture.md

@@ -148,7 +148,7 @@ working around locally and which should stay upstream-dependent for now, lives
 in [`wf_mcp_proxy_reality_and_roadmap.md`](wf_mcp_proxy_reality_and_roadmap.md).
 
 The public MCP mode split has been retired. The execution plan is
-[`superpowers/plans/2026-05-16-retire-legacy-mcp-modes.md`](superpowers/plans/2026-05-16-retire-legacy-mcp-modes.md):
+[`historical/superpowers/plans/2026-05-16-retire-legacy-mcp-modes.md`](historical/superpowers/plans/2026-05-16-retire-legacy-mcp-modes.md):
 `broker` and `proxy` were legacy public launch surfaces, while the ordinary
 server now exposes both local capabilities and proxied upstream capabilities.
 Internal concern packages remain useful even though the public mode choices are