wp-agentic-writer/docs/architecture/PLUGIN_AUDIT_RETRACE_THIRTEENTH_PASS_2026-05-26.md

WP Agentic Writer Thirteenth Retrace Audit

Audit date: 2026-05-26
Baseline retraced: docs/architecture/PLUGIN_AUDIT_RETRACE_TWELFTH_PASS_2026-05-26.md
Scope: thirteenth pass after twelfth-retrace implementation, covering legacy chat migration, conversation context continuity, cost attribution, provider metadata coverage, model registry ownership, UI/UX readiness, and release verification.
Status: COMPLETE / RETRACED
Completion marker: 2026-05-26
Follow-up retrace: docs/architecture/PLUGIN_AUDIT_RETRACE_FOURTEENTH_PASS_2026-05-26.md

This thirteenth-pass report has been implemented and retraced. Keep this document as historical evidence only; use the fourteenth-pass report for current remaining work.

Executive Summary

The twelfth-pass implementation closed several items from the previous report:

• The canonical /conversation/{post_id} handler now attempts legacy _wpaw_chat_history migration.
• The specific keyword and improvement suggestion cost hooks called out in the twelfth report now pass the full hook contract.
• The missed frontend provider metadata calls at the previously listed generation/clarity branches were added.
• The deprecated chat-history docblock now describes migration behavior accurately.
• Backup JavaScript endpoint references were removed from assets/.

However, a new P0 runtime regression was found in the legacy migration implementation: the new /conversation/{post_id} migration branch directly instantiates WP_Agentic_Writer_Context_Service, but that service has a private constructor. This will fatal when a legacy post has _wpaw_chat_history and no existing conversation session.

Static syntax checks still pass, but PHP linting cannot detect this runtime visibility error.

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 twelfth-pass findings against current code.
• Static sweep of legacy chat migration, provider metadata propagation, raw cost hooks, model default ownership, stale backup files, and browser-verification evidence.
• No live WordPress editor/browser workflow was run in this pass.

Twelfth-Pass Status Trace

Twelfth-pass item	Current status	Evidence
/conversation/{post_id} should migrate legacy chat history	Implemented, but broken by P0	Migration branch exists at includes/class-gutenberg-sidebar.php:1411-1432, but calls a private constructor at line 1415.
Keyword suggestion cost attribution	Fixed for called-out path	includes/class-keyword-suggester.php:140-151 now passes provider/session/status fields.
Improvement suggestion cost attribution	Fixed for called-out path	includes/class-gutenberg-sidebar.php:6911-6922 now passes provider/session/status fields.
Provider metadata calls for listed frontend branches	Mostly fixed	applyProviderMetadata() is now present at the previously missed branches, including assets/js/sidebar.js:3698, 3932, and 4821.
Model preset/default ownership	Partially de-scoped	JS and legacy presets now document that they are curated, but duplicated hard-coded presets remain active.
Browser verification	Still open	Static checks passed; no live editor workflow evidence was found.
Stale chat-history comments and backup files	Fixed	Docblock updated at includes/class-gutenberg-sidebar.php:1346-1350; no *.bak or *.backup files remain under assets/.

Remaining Findings

P0: Legacy Chat Migration Path Can Fatal Due Private Singleton Constructor

The twelfth implementation added the needed migrate-on-read behavior to the canonical conversation endpoint:

• includes/class-gutenberg-sidebar.php:1411-1432 checks _wpaw_chat_history, attempts migration, then returns the newly created session.

But the migration branch instantiates the context service directly:

• includes/class-gutenberg-sidebar.php:1415 uses new WP_Agentic_Writer_Context_Service().

That class is explicitly a singleton:

• includes/class-context-service.php:41-45 exposes WP_Agentic_Writer_Context_Service::get_instance().
• includes/class-context-service.php:51-53 declares private function __construct().

Impact:

• A legacy post with _wpaw_chat_history and no existing conversation session can trigger a fatal error when the editor loads chat through /conversation/{post_id}.
• This is exactly the legacy continuity path the twelfth pass intended to repair.
• PHP syntax checks still pass because this is a runtime visibility error, not a parse error.

Recommended fix:

• Replace new WP_Agentic_Writer_Context_Service() with WP_Agentic_Writer_Context_Service::get_instance().
• After migration, prefer the returned $migrated_session_id when fetching/returning the session, with a fallback to get_session_by_post_id().
• Add a regression test or manual fixture for: post has _wpaw_chat_history, has no conversation row, editor loads /conversation/{post_id}.

P1: Raw Cost Hook Drift Still Leaves Provider Attribution Gaps

The two cost examples from the twelfth report were fixed, but a broader scan still found multiple seven-argument wp_aw_after_api_request calls in includes/class-gutenberg-sidebar.php. These calls still omit provider, session id, and status.

Examples:

• Section execution cost at includes/class-gutenberg-sidebar.php:3034-3042.
• Write-from-outline section cost at includes/class-gutenberg-sidebar.php:3675-3683.
• Block refinement cost at includes/class-gutenberg-sidebar.php:4590-4598.
• Streaming block refinement cost at includes/class-gutenberg-sidebar.php:4718-4726.
• Chat refinement planning/streaming costs at includes/class-gutenberg-sidebar.php:5360-5368 and 5516-5524.
• Meta description cost at includes/class-gutenberg-sidebar.php:6316-6324.
• Intent detection cost at includes/class-gutenberg-sidebar.php:6708-6716.

Impact:

• The cost ledger can still show unknown provider for several real AI workflows.
• Provider/fallback transparency can differ between UI responses and persisted cost rows.
• Future fixes remain fragile while some paths use track_ai_cost() and others manually fire a shorter hook contract.

Recommended fix:

• Convert all internal AI cost tracking in class-gutenberg-sidebar.php to track_ai_cost() where the provider result is in scope.
• Where provider result is not currently in scope, pass it through with the generated response, or explicitly document why attribution is unavailable.
• Add a static guard that fails when do_action( 'wp_aw_after_api_request' ) is called without the full provider/session/status contract outside the central helper.

P2: Provider Metadata Coverage Still Has Stream Completion Gaps

The frontend now applies provider metadata in the branches called out by the twelfth pass:

• assets/js/sidebar.js:3698
• assets/js/sidebar.js:3932
• assets/js/sidebar.js:4821

Remaining gaps:

• assets/js/sidebar.js:4222-4224 handles another stream complete event and updates cost without calling applyProviderMetadata(data).
• Some backend stream completion payloads still include only completion/cost fields and no provider metadata, including includes/class-gutenberg-sidebar.php:3730-3732, 4824-4827, and 5552-5555.

Impact:

• Even when the frontend calls applyProviderMetadata(), some completion payloads do not contain metadata to apply.
• Provider badges can remain stale after specific streaming generation/refinement flows.

Recommended fix:

• Include provider_metadata on every stream complete payload that follows a provider call.
• Call applyProviderMetadata(data) in every frontend data.type === 'complete' branch that can receive provider-backed output.
• For completion events that are intentionally non-provider events, add a short comment so future audits do not treat them as missing.

P2: Live Browser Verification Is Still Required

Static checks passed, but no live WordPress editor workflow evidence was found.

The next browser pass should verify:

• Legacy _wpaw_chat_history migrates through /conversation/{post_id} without fatal error.
• Sidebar conversation state persists after editor reload.
• 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 settings changes affect generated requests.
• Unauthorized REST access remains denied.

P3: Model Presets Are Documented As Curated, But Still Duplicated

The twelfth criteria allowed model presets/default ownership to be centralized or documented as intentional. The implementation chose documentation:

• assets/js/settings-v2.js:32-34 says presets are curated product decisions, not registry-derived.
• includes/class-settings.php:1026 says the legacy inline presets are curated, not registry-derived.

This is acceptable as a product decision, but it leaves duplicated preset data in active code:

• Active Settings V2 presets are hard-coded at assets/js/settings-v2.js:35-59.
• Legacy settings presets are hard-coded at includes/class-settings.php:1027-1051.
• The legacy settings class can still be instantiated at wp-agentic-writer.php:100-104.

Impact:

• Presets can drift between Settings V2 and legacy settings.
• Model updates still require edits in more than one place.

Recommended fix:

• If curated presets remain intentional, centralize them in one PHP source and localize them into both UIs.
• If legacy settings is only a fallback, add a deprecation note and a smaller test surface for preset parity.

Priority Queue

1. P0: Replace direct new WP_Agentic_Writer_Context_Service() with WP_Agentic_Writer_Context_Service::get_instance() in the canonical conversation migration path.
2. P1: Convert remaining seven-argument cost hooks to the full provider/session/status contract or track_ai_cost().
3. P2: Finish provider metadata coverage for every stream complete branch and payload.
4. P2: Run the live WordPress editor browser verification pass.
5. P3: Centralize curated model presets or document legacy preset parity ownership.

Completion Criteria For Next Pass

The next retrace can mark this pass complete when:

• Legacy chat migration through /conversation/{post_id} cannot fatal on the context service constructor.
• Static scan finds no short-form wp_aw_after_api_request calls in provider-backed workflows.
• Provider-backed stream completion payloads include metadata, and frontend completion branches apply it or explicitly de-scope it.
• Browser verification evidence exists for chat persistence, migration, provider badge updates, cost log attribution, model settings, and auth denial.