feat: consolidate docs, backend/session infra, and settings updates
This commit is contained in:
Dwindi Ramadhana
@@ -0,0 +1,197 @@
|
||||
# WP Agentic Writer Twelfth Retrace Audit
|
||||
|
||||
Audit date: 2026-05-26
|
||||
Baseline retraced: `docs/architecture/PLUGIN_AUDIT_RETRACE_ELEVENTH_PASS_2026-05-26.md`
|
||||
Scope: twelfth pass after eleventh-retrace implementation, covering chat/context continuity, provider transparency, model registry adoption, cost attribution, UI/UX readiness, and release verification.
|
||||
Status: COMPLETE / RETRACED
|
||||
Completion marker: 2026-05-26
|
||||
Follow-up retrace: `docs/architecture/PLUGIN_AUDIT_RETRACE_THIRTEENTH_PASS_2026-05-26.md`
|
||||
|
||||
> This twelfth-pass report has been implemented and retraced. Keep this document as historical evidence only; use the thirteenth-pass report for current remaining work.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The eleventh-pass implementation closed several meaningful items:
|
||||
|
||||
- The sidebar now uses the canonical `/conversation/{post_id}` endpoint instead of the deprecated `/chat-history/{post_id}` endpoint.
|
||||
- `applyProviderMetadata()` is now called from many previously missed frontend paths, including meta generation, summarization, intent detection, reformat blocks, and refine-from-chat completion.
|
||||
- Model registry adoption is broader: Settings V2 fallback labels/defaults, OpenRouter constructor defaults, and image manager defaults now draw from `WPAW_Model_Registry`.
|
||||
- PHP and JavaScript syntax checks pass.
|
||||
|
||||
No new P0 blocker was found.
|
||||
|
||||
The remaining risk is narrower, but one new regression-class issue appeared during retrace: moving the sidebar to `/conversation` bypasses the legacy chat migration path that still lives under the deprecated chat-history compatibility method. That can make old post-meta chat history disappear from the editor UI for legacy posts that have not yet been migrated into conversation sessions.
|
||||
|
||||
## 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 eleventh-pass findings against current code.
|
||||
- Static sweep of provider metadata coverage, model registry usage, chat/context hydration, cost hook contracts, and stale compatibility code.
|
||||
- No live WordPress editor/browser workflow was run in this pass.
|
||||
|
||||
## Eleventh-Pass Status Trace
|
||||
|
||||
| Eleventh-pass item | Current status | Evidence |
|
||||
|---|---:|---|
|
||||
| Sidebar still used deprecated `/chat-history` | Fixed in active sidebar | `assets/js/sidebar.js:673` now fetches `/conversation/${postId}`. |
|
||||
| Provider metadata missing in meta/summarize/intent/reformat/refine paths | Mostly fixed | `applyProviderMetadata()` is now called at `assets/js/sidebar.js:596`, `1603`, `1647`, `2195`, and `2836`. |
|
||||
| Model registry not adopted in Settings V2 fallbacks/OpenRouter/image defaults | Improved | Settings V2 and provider/image defaults now use registry-backed defaults; residual hard-coded presets remain. |
|
||||
| Raw cost hook drift | Still open | Direct `do_action( 'wp_aw_after_api_request', ... )` calls remain, including seven-argument calls that lose provider attribution. |
|
||||
| Browser verification | Still open | Syntax checks passed, but live editor workflows were not verified. |
|
||||
|
||||
## Remaining Findings
|
||||
|
||||
### P1: Canonical `/conversation` Endpoint Bypasses Legacy Chat Migration
|
||||
|
||||
The active sidebar moved to the canonical endpoint:
|
||||
|
||||
- `assets/js/sidebar.js:673` fetches `/conversation/${postId}`.
|
||||
|
||||
However, the canonical backend handler only reads an existing conversation session:
|
||||
|
||||
- `includes/class-gutenberg-sidebar.php:1408-1418` calls `get_session_by_post_id()` and returns an empty message list when no session exists.
|
||||
- `includes/class-conversation-manager.php:200-218` returns `null` when no active session is found.
|
||||
|
||||
The legacy migration behavior still exists, but only in the deprecated compatibility path:
|
||||
|
||||
- `includes/class-gutenberg-sidebar.php:1479-1492` reads `_wpaw_chat_history`, calls `migrate_legacy_chat_history()`, and returns migrated messages.
|
||||
|
||||
Impact:
|
||||
|
||||
- Legacy posts that still have `_wpaw_chat_history` but no conversation session can now hydrate as empty in the sidebar.
|
||||
- This can look like conversation loss after the eleventh-pass fix, even though the data still exists in post meta.
|
||||
- The deprecated endpoint has the safer migrate-on-read behavior, while the canonical endpoint does not.
|
||||
|
||||
Recommended fix:
|
||||
|
||||
- Make `handle_get_conversation_by_post()` use the same migrate-on-read behavior when no session exists and `_wpaw_chat_history` is present.
|
||||
- Return the migrated `session_id`, `post_id`, `has_session: true`, and messages after migration.
|
||||
- Add a regression test or fixture for a post with only `_wpaw_chat_history` and no `wpaw_conversations` row.
|
||||
|
||||
### P1: Cost Ledger Still Loses Provider Attribution For Some AI Actions
|
||||
|
||||
The centralized `track_ai_cost()` helper exists, but some AI actions still use the raw hook with the old seven-argument shape.
|
||||
|
||||
Examples:
|
||||
|
||||
- `includes/class-keyword-suggester.php:32-34` obtains a provider result, but `includes/class-keyword-suggester.php:121-129` fires `wp_aw_after_api_request` without provider, session, or status arguments.
|
||||
- `includes/class-gutenberg-sidebar.php:6862-6864` obtains the provider for improvement analysis, but `includes/class-gutenberg-sidebar.php:6871-6879` also fires a seven-argument cost hook.
|
||||
- `includes/class-cost-tracker.php:50` registers the listener with nine accepted arguments, so omitted provider fields fall back to `unknown`.
|
||||
|
||||
Impact:
|
||||
|
||||
- Cost rows for keyword suggestions and improvement suggestions can under-report provider and fallback status.
|
||||
- Provider/cost dashboards can show `unknown` for actions where provider metadata was actually available.
|
||||
- This weakens the new provider transparency work because the UI response and ledger do not always agree.
|
||||
|
||||
Recommended fix:
|
||||
|
||||
- Replace these raw hook calls with `track_ai_cost()` or a shared public cost helper.
|
||||
- Where the helper is not accessible, pass the full nine-argument hook contract, including provider result, session id when available, and status.
|
||||
- Add a static check for seven-argument `wp_aw_after_api_request` calls.
|
||||
|
||||
### P2: Provider Metadata UI Coverage Is Much Better, But Not Exhaustive
|
||||
|
||||
The eleventh-pass implementation fixed the major previously listed misses:
|
||||
|
||||
- Meta generation calls `applyProviderMetadata(data)` at `assets/js/sidebar.js:596`.
|
||||
- Summarization calls it at `assets/js/sidebar.js:1603`.
|
||||
- Intent detection calls it at `assets/js/sidebar.js:1647`.
|
||||
- Reformat blocks calls it at `assets/js/sidebar.js:2195`.
|
||||
- Refine-from-chat completion calls it at `assets/js/sidebar.js:2836`.
|
||||
|
||||
Remaining missed or duplicate paths:
|
||||
|
||||
- One stream completion branch at `assets/js/sidebar.js:3697-3710` emits a completion payload with `totalCost` only, so the frontend has no provider metadata to apply.
|
||||
- Another completion handler at `assets/js/sidebar.js:3930-3945` updates cost/timeline without applying provider metadata.
|
||||
- The clarity check path at `assets/js/sidebar.js:4818-4825` parses `clarityData` but does not apply provider metadata from the response.
|
||||
|
||||
Impact:
|
||||
|
||||
- The provider badge is now reliable for many common flows, but can still remain stale after some generation or clarity workflows.
|
||||
- Users may see correct cost movement while the provider/fallback display still reflects a previous request.
|
||||
|
||||
Recommended fix:
|
||||
|
||||
- Ensure every backend AI response and stream completion payload includes `provider_metadata` when a provider was involved.
|
||||
- Call `applyProviderMetadata(data)` immediately after every AI JSON response parse and every stream `complete` event that can carry metadata.
|
||||
- For endpoints intentionally without provider metadata, document that in code next to the parse/complete branch.
|
||||
|
||||
### P2: Model Registry Still Has Residual Hard-Coded Defaults And Presets
|
||||
|
||||
Registry adoption is now strong in the active PHP defaults, but not complete:
|
||||
|
||||
- `assets/js/settings-v2.js:32-58` still defines budget/balanced/premium presets with hard-coded model IDs.
|
||||
- `includes/class-settings.php:72-78`, `98-117`, `138-140`, `197`, and `1029-1049` still contain legacy settings defaults and presets with hard-coded model IDs.
|
||||
- `wp-agentic-writer.php:100-104` can still instantiate the legacy settings class if Settings V2 is unavailable.
|
||||
|
||||
Some hard-coded model strings are acceptable when they are display labels, compatibility checks, pricing keys, or provider-specific suggestions. The remaining concern is default/preset ownership.
|
||||
|
||||
Impact:
|
||||
|
||||
- The registry is not yet the only source of model defaults users can activate.
|
||||
- JS presets and legacy settings can drift from the PHP registry.
|
||||
- Future model migrations still require edits in more than one place.
|
||||
|
||||
Recommended fix:
|
||||
|
||||
- Localize presets from `WPAW_Model_Registry::get_frontend_data()` or add explicit registry preset support.
|
||||
- Either retire the legacy `WP_Agentic_Writer_Settings` path or make it read registry defaults.
|
||||
- Keep provider suggestion maps and pricing tables separate, but name them as suggestions/pricing rather than defaults.
|
||||
|
||||
### P2: Live Browser Verification Is Still The Final Release Gate
|
||||
|
||||
Static checks passed, but the plugin still needs a live editor pass before calling the audit chain fully complete.
|
||||
|
||||
Manual verification should cover:
|
||||
|
||||
- Sidebar opens in the block editor and survives page reload.
|
||||
- Existing legacy post-meta chat history migrates and appears through `/conversation/{post_id}`.
|
||||
- New chat messages persist, reload, and retain session id continuity.
|
||||
- Provider/fallback badges update after chat, clarity, planning, generation, refinement, summarize, reformat, meta, keyword, and improvement actions.
|
||||
- Cost totals update in the UI and cost ledger with provider/session/status fields populated.
|
||||
- Model setting changes affect generated requests and visible provider metadata.
|
||||
- Unauthorized REST access remains denied.
|
||||
|
||||
### P3: Stale Compatibility Comments And Backup Files Can Create Audit Noise
|
||||
|
||||
The deprecated chat-history docblock is now stale:
|
||||
|
||||
- `includes/class-gutenberg-sidebar.php:1349-1350` says the endpoint does not use the conversations table, but the implementation delegates through conversation/session migration behavior.
|
||||
|
||||
Also, backup JavaScript files still reference old endpoint behavior:
|
||||
|
||||
- `assets/js/sidebar.js.backup`
|
||||
- `assets/js/sidebar.js.bak`
|
||||
|
||||
Impact:
|
||||
|
||||
- Future retraces can mistake backup files or stale comments for active behavior.
|
||||
- If backup files are accidentally packaged, old endpoint usage can leak into distribution artifacts.
|
||||
|
||||
Recommended fix:
|
||||
|
||||
- Update the deprecated endpoint docblock to describe the actual compatibility behavior.
|
||||
- Exclude backup files from packaging or remove them after confirming they are not needed.
|
||||
|
||||
## Priority Queue
|
||||
|
||||
1. P1: Add migrate-on-read behavior to `/conversation/{post_id}` for legacy `_wpaw_chat_history`.
|
||||
2. P1: Fix seven-argument cost hooks for keyword and improvement suggestions so provider attribution is preserved.
|
||||
3. P2: Finish provider metadata propagation for remaining stream completion and clarity branches.
|
||||
4. P2: Move active JS presets and legacy settings defaults under the model registry, or explicitly retire/de-scope legacy settings.
|
||||
5. P2: Run live WordPress editor browser verification.
|
||||
6. P3: Clean stale chat-history comments and backup endpoint references.
|
||||
|
||||
## Completion Criteria For Next Pass
|
||||
|
||||
The next retrace can mark this pass complete when:
|
||||
|
||||
- `/conversation/{post_id}` migrates legacy chat history when no session exists.
|
||||
- Keyword and improvement suggestion cost rows include provider, fallback, session/status where available.
|
||||
- Provider metadata is applied or explicitly de-scoped for every AI response path.
|
||||
- Remaining model preset/default ownership is either centralized in the registry or documented as intentional.
|
||||
- A live editor verification note exists with the exact workflows checked.
|
||||
Reference in New Issue
Block a user