docs: add design and implementation revision documents

Revision docs correct original plans: schedule persistence via API
endpoints (not tree_structure), array-index reorder (no display_order),
store minimum-one-step invariant, accordion mode, ARIA requirements,
and two-stage save orchestration with failure handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/2026-02-19-procedural-editor-redesign-design-revisions.md

@@ -0,0 +1,155 @@
+# Procedural & Maintenance Editor Redesign - Design Revisions
+
+> **Date:** 2026-02-19
+> **Revises:** `docs/plans/2026-02-19-procedural-editor-redesign-design.md`
+> **Purpose:** Resolve implementation gaps and make the design decision-complete for engineering handoff
+
+## Summary
+
+This revision tightens the original design to match current architecture and APIs.
+It resolves contradictions around maintenance schedule persistence, aligns step-list behavior with store invariants, and defines concrete DnD/accessibility/test expectations.
+
+## Revision Decisions (Locked)
+
+1. Keep fixed-height editor layout with independent StepList scrolling.
+2. Use collapsible sections for Details, Intake Form, and Maintenance Schedule.
+3. Use existing installed `@dnd-kit/*` packages (no new dependency work).
+4. Keep `procedure_end` as non-draggable and always last.
+5. Keep schedule as optional for maintenance flows (manual batch launch remains valid).
+
+## Critical Corrections to Original Design
+
+1. **Maintenance schedule persistence**
+- Schedule is not embedded in `tree_structure`.
+- Schedule must be persisted through maintenance schedule endpoints.
+- New unsaved flow requires two-stage save:
+  1. Save tree (`treesApi.create` / `treesApi.update`)
+  2. Create/update schedule (`maintenanceSchedulesApi.create` or `maintenanceSchedulesApi.update`)
+- One schedule per tree (`uq_maintenance_schedules_tree_id`).
+
+2. **Step empty-state semantics**
+- Original "0 steps" state conflicts with current store minimum step behavior.
+- Revised behavior:
+  - If minimum-one-step invariant remains, remove "0 steps" UX language.
+  - Empty-state is only shown if invariant is intentionally changed in store.
+
+3. **DnD data model correction**
+- Do not mention recalculating `display_order` for procedural steps.
+- Reorder is array-index based only.
+- Explicitly block dragging `procedure_end`.
+
+4. **Dependencies section correction**
+- Replace "New Dependencies" with "Existing Dependencies Used" for `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`.
+
+5. **File impact correction**
+- Add API integration surfaces:
+  - `frontend/src/api/maintenanceSchedules.ts`
+  - target-list integration file(s) if inline list creation is in scope
+- Clarify interaction with `frontend/src/pages/MaintenanceFlowDetailPage.tsx` (retain schedule view/edit there or shift entirely to editor).
+
+6. **Collapsible behavior clarification**
+- Use single-open accordion mode by default.
+- Details defaults expanded for new flows.
+- Intake defaults collapsed.
+- Maintenance Schedule defaults:
+  - new maintenance flow: expanded
+  - existing with schedule: collapsed summary
+  - existing without schedule: collapsed with "Set Up" affordance
+
+7. **A11y + keyboard DnD acceptance**
+- Include keyboard reorder acceptance criteria.
+- Include focus order and ARIA labeling criteria for section toggles and drag handles.
+
+## Revised Maintenance Schedule Section Spec
+
+### New maintenance flow (tree not yet saved)
+
+1. Render schedule editor expanded.
+2. Keep schedule input in local UI draft state.
+3. On Save Draft / Publish:
+- Save tree first.
+- If tree save succeeds, create schedule with resulting `tree_id`.
+4. If schedule create fails:
+- Tree save remains successful.
+- Show actionable error ("Schedule not saved. Retry.").
+- Preserve schedule draft state.
+
+### Existing maintenance flow
+
+1. Load schedule via `maintenanceSchedulesApi.getForTree(treeId)`.
+2. Edit and persist via `maintenanceSchedulesApi.update(scheduleId, data)`.
+3. If no schedule exists, show collapsed "No schedule configured" summary + setup button.
+
+## Revised StepList Reorder Spec
+
+1. Draggable types:
+- `procedure_step`
+- `section_header`
+2. Non-draggable:
+- `procedure_end`
+3. Reorder behavior:
+- Move item by array index.
+- Preserve all step payload fields.
+- No implicit grouped movement under section headers.
+4. Keyboard behavior:
+- Drag handle focusable.
+- Enter/Space pick up + drop.
+- Arrow keys move while grabbed.
+- Escape cancels.
+
+## Acceptance Criteria
+
+1. **Layout**
+- Toolbar remains visible while StepList scrolls.
+- Details/Intake/Schedule sections collapse without shrinking StepList usability.
+
+2. **Steps**
+- New step auto-expands.
+- New step scrolls into view.
+- Reorder works by pointer and keyboard.
+- `procedure_end` remains last and fixed.
+
+3. **Maintenance schedule**
+- New unsaved maintenance flow can be saved without schedule.
+- Schedule can be created immediately after first tree save.
+- Existing schedule loads and updates in editor.
+- Schedule failure does not roll back successful tree save.
+
+4. **Accessibility**
+- Section toggles keyboard operable.
+- Drag handles have accessible labels.
+- Focus remains stable after reorder.
+
+5. **Build/Test**
+- `npm run build` succeeds.
+- Affected component/store tests pass.
+
+## Updated File Impact
+
+### Modified
+
+- `frontend/src/pages/ProceduralEditorPage.tsx`
+- `frontend/src/components/procedural-editor/StepList.tsx`
+- `frontend/src/components/procedural-editor/IntakeFormBuilder.tsx`
+- `frontend/src/store/proceduralEditorStore.ts`
+- `frontend/src/api/maintenanceSchedules.ts`
+- `frontend/src/pages/MaintenanceFlowDetailPage.tsx` (if schedule UX ownership changes)
+
+### New
+
+- `frontend/src/components/procedural-editor/CollapsibleEditorSection.tsx`
+- `frontend/src/components/procedural-editor/MaintenanceScheduleSection.tsx`
+
+### Existing dependencies used
+
+- `@dnd-kit/core`
+- `@dnd-kit/sortable`
+- `@dnd-kit/utilities`
+
+## Out of Scope (unchanged)
+
+1. Intake field DnD reorder.
+2. Procedural undo/redo parity.
+3. Step templates/presets.
+4. Bulk step operations.
+5. Backend schema/model changes for procedural steps.