docs(native): harden #332 lifecycle and Qt killer gates

[qnbs]

User description

Summary

• reconcile the live [Bug]: Sluggishness? (.deb) #332/Stability issues with Local AI, Gemini API keys, LM Studio and UI + workflow suggestions #333 performance ledger with merged main and current issue states
• define the transitional Tauri maintenance boundary without a PWA-only pivot
• promote the [Bug]: Sluggishness? (.deb) #332 Alt-Tab scenario into explicit Qt hang/lifecycle/recovery killer-gate evidence

Evidence and scope

• [Bug]: Sluggishness? (.deb) #332 remains open: packaged v1.28.0 Alt-Tab hard hang and intra-page latency are unresolved
• [Bug]: AI Writing Studio text is unreadable #341 remains open: readability reappearance is not claimed fixed
• Stability issues with Local AI, Gemini API keys, LM Studio and UI + workflow suggestions #333 is closed as superseded/fully triaged; its canonical unresolved evidence remains represented in [Bug]: Sluggishness? (.deb) #332/Dedicated Scenario / Screenplay workspace #347/Plugin install / marketplace UI #348/Collaboration invite links with expiry/permissions #349
• no production behavior, thresholds, security policy, or branch-protection rule changed
• no packaged Linux environment is available here, so this PR makes no packaged closure claim

Refs #332
Refs #341
Refs #333
Refs #347
Refs #348
Refs #349

Summary by Sourcery

Formalize transitional Tauri support and require packaged desktop lifecycle evidence for Qt qualification without changing production behavior or making a PWA-only transition.

New Features:

• Define a transitional Tauri maintenance policy that preserves security, update, startup, editing, recovery, and user-blocking support while limiting new Tauri-specific investment.
• Introduce the GOLDEN-DESKTOP-LIFECYCLE-332 scenario as required evidence for Qt lifecycle and hang qualification.

Enhancements:

• Reconcile the performance ledger with current issue states and distinguish code-level fixes awaiting packaged-runtime verification from unresolved evidence.
• Expand native qualification requirements to cover hang, lifecycle, diagnostic, recovery, responsiveness, data preservation, and packaged-environment evidence.

Documentation:

• Document Tauri maintenance classes, investment gates, safe diagnostics, runtime limitations, and retirement conditions.
• Document mandatory Qt lifecycle killer-gate outcomes and evidence maturity requirements for Alt-Tab and background-recovery scenarios.

---

CodeAnt-AI Description

Define transitional Tauri support and formalize Qt lifecycle qualification

What Changed

• Establishes a transitional Tauri support boundary covering security, updates, data integrity, startup, editing, recovery, and user-blocking failures while limiting new Tauri-only investment
• Adds severity-based guidance for fixing, diagnosing, mitigating, or deferring Tauri issues, including privacy-safe diagnostics and restrictions on global graphics workarounds
• Defines a required desktop lifecycle scenario covering autosave, Alt-Tab, background recovery, editing, close, relaunch, and large projects, with explicit requirements for responsive input, preserved edits, and no hangs or corruption
• Updates the performance ledger to reflect current issue status and identify shipped fixes that still require packaged-runtime verification

Impact

✅ Clearer Tauri support expectations
✅ Fewer unverified lifecycle and data-loss claims
✅ Consistent Qt acceptance evidence for Alt-Tab hangs

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Reviewed your PR	01fd379	Aug 22, 2026 · 16:40	16:40

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldscript-studio	Ready	Preview	Aug 22, 2026 5:09pm

[sourcery-ai]

Sorry @qnbs, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your current included review allowance is based on your included PR review attempts over the past 7 days.

Next review available in:21 minutes

Limit details: You’ve used the included review currently available. Your 88 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cbbcb2a6-2c0f-4a4b-99dc-1d90f6314900

📥 Commits

Reviewing files that changed from the base of the PR and between a6e22e5 and c91a333.

📒 Files selected for processing (4)

• docs/ISSUES-332-333-PERFORMANCE-LEDGER.md
• docs/native/QT-EARLY-KILLER-GATES.md
• docs/native/ROADMAP-QT-GPUI-DESKTOP.md
• docs/native/TAURI-TRANSITIONAL-MAINTENANCE.md

---

_{Comment @coderabbitai help to get the list of available commands.}

[codeant-ai]

🏁 CodeAnt Quality Gate Results

Commit:c91a3333
Scan Time: 2026-08-22 17:39:10 UTC

✅ Overall Status: PASSED

Quality Gate Details

Quality Gate	Status	Details
Secrets	✅ PASSED	0 secrets found
Duplicate Code	✅ PASSED	0.0% duplicated
SAST	✅ PASSED	No security issues
Bugs	✅ PASSED	Rating S: No bugs
IAC	✅ PASSED	No IAC issues

View Full Results

[sourcery-ai]

Reviewer's Guide

Documents and formalizes the current performance and lifecycle evidence for issues #332/#333, tightens Qt crash/hang killer-gate requirements, and introduces a Tauri transitional maintenance policy that constrains new native investment while preserving support and diagnostic obligations.

Sequence diagram for the GOLDEN-DESKTOP-LIFECYCLE-332 killer gate

sequenceDiagram
participant User
participant Desktop as Packaged desktop
participant Core as Rust Core
participant Diagnostics
User->>Desktop: Edit representative project
Desktop->>Core: Save acknowledged edit
Desktop->>Diagnostics: Record lifecycle event
User->>Desktop: Background window for 5 seconds
Desktop->>Diagnostics: Record blur and background
User->>Desktop: Return and edit immediately
Desktop->>Core: Persist newer edit generation
Desktop->>Diagnostics: Record focus and resume
loop 20 Alt-Tab cycles
User->>Desktop: Switch away and return
Desktop->>Diagnostics: Record heartbeat and lifecycle state
User->>Desktop: Edit and use keyboard input
Desktop->>Core: Persist acknowledged edit
end
User->>Desktop: Minimize, restore, relaunch, and close
Desktop->>Diagnostics: Emit privacy-safe diagnostic bundle
Diagnostics-->>User: Report maturity and packaged result

Loading

File-Level Changes

Change	Details	Files
Update the #332/#333 performance ledger to reflect current main, issue states, and packaged verification status.	Clarify ledger role as an authoritative evidence record for active responsiveness portions. Refresh the tracked main commit SHA to the current value. Mark issue Stability issues with Local AI, Gemini API keys, LM Studio and UI + workflow suggestions #333 as closed while [Bug]: Sluggishness? (.deb) #332 remains open. Refine PERF-333-004 and PERF-333-005 rows to note code paths shipped in fix: harden desktop AI integrations #336 and reclassify them as fixed-in-code awaiting packaged verification. Keep v1.28.0 closure language emphasizing that CI/browser responsiveness alone is insufficient for performance closure.	docs/ISSUES-332-333-PERFORMANCE-LEDGER.md
Strengthen Qt native killer-gate documentation to explicitly include hangs and lifecycle behavior and tie in #332’s golden desktop lifecycle scenario.	Expand the crash diagnostics probe lane to cover crash, hang, and lifecycle diagnostics and recovery feasibility. Add a new section describing crash, hang, and lifecycle hardening requirements derived from [Bug]: Sluggishness? (.deb) #332. Define diagnostic expectations for distinguishing different failure modes (crash, panic, GUI stall, Core task stall, renderer/compositor failure) without weakening isolation. Specify required UI heartbeat, lifecycle events, correlation IDs, cancellation/timeout bounds, and privacy-safe diagnostic bundle contents and exclusions. Introduce the GOLDEN-DESKTOP-LIFECYCLE-332 scenario and its required outcomes as mandatory input for later Qt qualification, with maturity levels and environment-context requirements.	docs/native/QT-EARLY-KILLER-GATES.md
Add a Tauri transitional maintenance policy to constrain future Tauri investment while keeping the current desktop runtime supported and safe.	Define support boundaries for Tauri during the Qt transition, including security, persistence, basic usability, and triage obligations. Introduce maintenance classes TM-0 through TM-3 with clear criteria for mandatory fixes, user-blocking issues, high-ROI-only changes, and work that must not start. Add an investment gate checklist for evaluating non-trivial Tauri changes, including severity, root-cause ownership, renderer-neutral value, coupling, mitigation options, and decision outcomes. Document [Bug]: Sluggishness? (.deb) #332 lifecycle evidence expectations, safe diagnostics constraints, and guardrails against unsafe global WebKit/GPU environment overrides. Specify the GOLDEN-DESKTOP-LIFECYCLE-332 scenario as a renderer-neutral diagnostic target with required outcomes and packaged evidence metadata requirements. Define exit and retirement conditions for Tauri debugging and removal, tying unresolved runtime/environment-limited scenarios into Qt killer-gate evidence rather than a PWA-only pivot.	docs/native/TAURI-TRANSITIONAL-MAINTENANCE.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[amazon-q-developer]

Summary

This PR documents the #332/#333 performance investigation status and establishes critical native desktop development policies. The evidence ledger correctly tracks unresolved packaged desktop issues without premature closure claims, and the new Tauri maintenance policy properly gates investment without abandoning current users.

Critical Issue

Documentation formatting error in QT-EARLY-KILLER-GATES.md where literal \n escape sequences prevent proper rendering of the #332 lifecycle hardening section. This must be fixed to ensure the section displays as formatted paragraphs rather than a single line with visible escape characters.

Changes Reviewed

• Performance ledger updates accurately reflect that code changes exist but packaged verification remains pending
• Qt killer-gate document correctly expands crash diagnostics to include hang and lifecycle scenarios
• New Tauri maintenance policy appropriately balances ongoing support obligations with strategic Qt direction
• All status transitions (ROOT_CAUSE_CONFIRMED_FIX_PENDING → FIXED_CODE_ONLY_AWAITING_PACKAGED_VERIFICATION) align with the stated measurement contract requiring packaged desktop validation

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qnbs]

Fixed in commit c728fbd. Amazon Q correctly identified literal \\n sequences in the appended Qt killer-gate section; the section now contains real Markdown line breaks. No content or gate semantics were weakened.