docs: archive completed superpowers plans

2026-06-04 22:29:32 +07:00
parent e001b524d6
commit 0d34174a84
93 changed files with 88 additions and 10 deletions
@@ -0,0 +1,55 @@
+# Nested Authoring State Projection Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let `wf_authoring` project nested authored state schemas into the flat exact-path state-field index that `wf_core` now supports.
+
+**Architecture:** Keep authored JSON Schema nested for users and LLM clients. Add a focused flattening helper for state-field projection only, emitting both parent object paths and descendant paths. Resolve nested `BaseModel` metadata by authored path where available, while leaving non-`BaseModel` authored types schema-capable with default merge metadata.
+
+**Tech Stack:** Python, Pydantic, pytest, existing `wf_authoring` schema adapter.
+
+---
+
+## File Structure
+
+- Modify `src/wf_authoring/schemas.py`
+  - flatten nested schema properties into exact-path `StateField`s
+  - gather nested `BaseModel` metadata by authored path
+- Modify `tests/authoring/helpers.py`
+  - add nested state models used by tests
+- Modify `tests/authoring/test_schemas.py`
+  - pin nested projection behavior and nested metadata
+- Update `docs/core_state_mapping_and_merge.md`
+  - note that authoring now projects nested authored models into the flat core index
+
+## Tasks
+
+### Task 1: Pin Nested Projection
+
+- [ ] Add tests proving:
+  - nested authored state keeps parent and child declarations
+  - nested child metadata such as `append` lands on the exact child path
+  - parent object declaration remains independent from child declarations
+- [ ] Run the focused authoring tests and confirm they fail under current top-level-only projection.
+
+### Task 2: Implement Projection Helpers
+
+- [ ] Add a schema-walking helper that yields `(path, property_schema)` for parent and descendant properties.
+- [ ] Add nested `BaseModel` metadata traversal keyed by dotted path.
+- [ ] Update `state_schema_from()` to build `StateField`s from the flattened path stream.
+- [ ] Keep JSON Schema generation unchanged; flatten only the core `StateSchema.fields` index.
+- [ ] Run the focused authoring tests and confirm they pass.
+
+### Task 3: Document and Verify
+
+- [ ] Update the core state mapping doc with the authoring projection rule.
+- [ ] Run `uv run --with pytest pytest tests/authoring -q`
+- [ ] Run `uv run --with pytest pytest -q`
+- [ ] Run `uv run basedpyright --level error`
+
+## Non-Goals
+
+- custom metadata support for every Pydantic-supported type form
+- changing `SchemaRef` shape
+- reducer registries
+- automatic deep merge behavior