feat: consolidate docs, backend/session infra, and settings updates

docs/architecture/PLUGIN_AUDIT_RETRACE_SIXTEENTH_PASS_2026-05-26.md

@@ -0,0 +1,106 @@
+# WP Agentic Writer Sixteenth Retrace Audit
+
+Audit date: 2026-05-26  
+Baseline retraced: `docs/architecture/PLUGIN_AUDIT_RETRACE_FIFTEENTH_PASS_2026-05-26.md`  
+Scope: sixteenth pass after fifteenth-retrace implementation, covering final static audit state, live editor readiness, provider/cost/context contracts, model preset ownership, and remaining release gate.
+
+## Executive Summary
+
+The fifteenth-pass implementation closed the remaining static cleanup items:
+
+- The duplicate `applyProviderMetadata(data)` call in the normal generation completion branch is removed; the branch now calls it once at `assets/js/sidebar.js:1039-1042`.
+- Settings V2 no longer keeps a hard-coded JavaScript preset map; it uses localized PHP presets with an empty fallback at `assets/js/settings-v2.js:32-35`.
+- Legacy settings presets are still inline, but are explicitly documented as manually kept in sync with `WP_Agentic_Writer_Settings_V2::get_model_presets()` at `includes/class-settings.php:1025-1028`.
+- The cost hook contract remains clean: static scan finds only the central helper hook and the keyword suggester full-contract hook.
+- The legacy chat migration P0 remains fixed: no direct `new WP_Agentic_Writer_Context_Service` references were found.
+- PHP and JavaScript syntax checks pass.
+
+No new P0, P1, or P2 static implementation defect was found.
+
+The audit chain is now effectively static-clean for the repeatedly retraced areas: chat/context continuity, legacy migration, provider metadata propagation, cost attribution, model registry/default ownership, and syntax. The only remaining gate is live WordPress editor/browser verification.
+
+## Verification Performed
+
+- PHP syntax check across plugin PHP files: passed.
+- `node -c assets/js/sidebar.js`: passed.
+- `node -c assets/js/settings-v2.js`: passed.
+- `node -c assets/js/sidebar-utils.js`: passed.
+- Static retrace of fifteenth-pass findings against current code.
+- Static scan for short-form `wp_aw_after_api_request` calls.
+- Static scan for direct `new WP_Agentic_Writer_Context_Service`.
+- Static scan for provider metadata completion branches.
+- Static scan for model preset ownership and duplication.
+- Static scan for live browser verification evidence.
+- No live WordPress editor/browser workflow was run in this pass.
+
+## Fifteenth-Pass Status Trace
+
+| Fifteenth-pass item | Current status | Evidence |
+|---|---:|---|
+| Live editor/browser verification | Still open | No new verification note or browser evidence was found. |
+| Settings V2 JS fallback preset duplication | Fixed | `assets/js/settings-v2.js:35` now falls back to `{}` instead of duplicating the preset map. |
+| Legacy settings preset duplication | Accepted/owned | `includes/class-settings.php:1025-1028` says the legacy map is manually kept in sync with Settings V2 presets. |
+| Duplicate provider metadata call | Fixed | `assets/js/sidebar.js:1039-1042` contains one `applyProviderMetadata(data)` call before cost update. |
+
+## Static Contract State
+
+### Chat And Context
+
+- Canonical conversation loading remains on `/conversation/{post_id}`.
+- Legacy `_wpaw_chat_history` migration uses `WP_Agentic_Writer_Context_Service::get_instance()`.
+- No direct construction of `WP_Agentic_Writer_Context_Service` was found.
+
+### Provider Metadata
+
+- Retry chat applies provider metadata on completion.
+- Normal stream completion branches apply provider metadata.
+- Provider-backed backend responses and stream completions include metadata in the previously retraced paths.
+
+### Cost Tracking
+
+- `includes/class-gutenberg-sidebar.php` routes cost tracking through `track_ai_cost()`.
+- `includes/class-keyword-suggester.php` uses the full provider/session/status hook contract.
+- Static scan found no short-form seven-argument provider-backed cost hooks.
+
+### Models And Presets
+
+- Registry-backed defaults remain in the active PHP settings/provider paths.
+- Settings V2 presets are centralized in `WP_Agentic_Writer_Settings_V2::get_model_presets()`.
+- Legacy settings retains an inline preset map, now explicitly marked as manually synchronized legacy behavior.
+
+## Remaining Finding
+
+### P2: Live WordPress Editor/Browser Verification Is Still Required
+
+Static audit is clean, but live editor behavior is still unproven.
+
+Required verification:
+
+- Legacy `_wpaw_chat_history` migrates through `/conversation/{post_id}` without fatal error.
+- Sidebar chat persists after editor reload.
+- Retry chat updates the provider/fallback badge.
+- Provider badge updates after chat, clarity, planning, generation, block refinement, chat refinement, meta, keyword, intent, and improvement actions.
+- Cost log rows include provider/session/status for the same actions.
+- Model setting changes affect generated requests.
+- Unauthorized REST access remains denied.
+
+Impact:
+
+- Without this pass, static code contracts are checked, but WordPress editor UI behavior, persistence, permissions, and rendered state updates are not proven.
+
+Recommended fix:
+
+- Run a live editor verification pass and record the evidence in a short document.
+- Suggested document: `docs/architecture/PLUGIN_AUDIT_BROWSER_VERIFICATION_2026-05-26.md`.
+- Include post IDs used, actions tested, observed provider badge/cost log behavior, reload behavior, and any screenshots or console/log notes.
+
+## Priority Queue
+
+1. P2: Run live WordPress editor/browser verification and record evidence.
+
+## Completion Criteria For Next Pass
+
+The next retrace can mark this pass complete when:
+
+- A live editor/browser verification note exists for migration, persistence, provider badge updates, cost attribution, model settings, retry chat, and auth denial.
+- Any browser-discovered defects are either fixed or moved into a new targeted report.