mustflow 2.108.3 → 2.112.1

package/templates/default/locales/en/.mustflow/skills/ui-state-resurrection-review/SKILL.md

@@ -0,0 +1,218 @@
+---
+mustflow_doc: skill.ui-state-resurrection-review
+locale: en
+canonical: true
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: ui-state-resurrection-review
+description: Apply this skill when frontend, desktop, mobile, chat, streaming, workspace, panel, tab, route, runtime, terminal, or session UI state that should be closed, completed, cleared, finalized, restarted, or deleted reappears after reload, restart, reconnect, route remount, SSR hydration, persisted-store rehydration, query-cache restore, service-worker cache restore, cloud sync, cross-tab broadcast, migration, crash recovery, or events such as message.complete, terminal-error, or old-generation stream replay; use it to prove whether the UI is rendering new state or resurrecting old persisted state.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.ui-state-resurrection-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# UI State Resurrection Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Debug resurrected UI state by tracing state provenance, persistence, hydration, and finalization before blaming rendering.
+
+The core question is: "Is this panel, message, tab, route, task view, or draft newly created, or did an old stored record regain authority?" If restart, reload, reconnect, or hydration brings back the same ID, title, position, selected tab, message run, or collapsed state, treat it as a stored-state resurrection until evidence proves otherwise.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A completed, closed, cleared, deleted, finalized, or dismissed UI surface reappears after app restart, browser reload, reconnect, route remount, tab focus, provider remount, workspace switch, user switch, tenant switch, schema migration, crash recovery, or cloud sync.
+- A chat, copilot, streaming response, draft response, task panel, workspace panel, active tab, sidebar item, layout slot, notification, toast, inbox item, modal, drawer, form draft, selected item, or route state returns after `message.complete`, finish, submit, close, clear, delete, archive, or done.
+- A streaming session mixes message lifecycle, runtime health, terminal health, restart state, hydration, persistence, or old-generation events through flat flags such as `isDone`, `isLoading`, `hasError`, or one handler that mutates both UI state and durable session storage.
+- Local or remote state sources may include memory stores, React Query, SWR, Apollo, Redux Persist, Zustand persist, Pinia, router loaders, SSR bootstrap data, localStorage, sessionStorage, IndexedDB, CacheStorage, service worker cache, BroadcastChannel, desktop user-data SQLite, JSON, LevelDB, preferences, workspace-state files, mobile shared preferences, mobile SQLite, restore state, server workspace layout, user session state, or cloud sync.
+- The symptom is being described as a render bug, component bug, memoization issue, or CSS issue, but the same identity or old timestamp survives a restart, reload, hydration, or sync boundary.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The UI is wrong only within one live render pass and no reload, restart, hydration, persistence, cache restore, replay, sync, or remount boundary is involved; use `frontend-state-ownership-review`, `frontend-render-stability`, or a framework-specific frontend skill first.
+- The task only reviews cache key correctness outside UI restoration; use `cache-integrity-review`.
+- The task only reviews generic async races without persisted or restored state; use `async-timing-boundary-review` or `race-condition-review`.
+- The task only reviews deletion lifecycle for domain data, database rows, or server records rather than UI/session restore state; use `deletion-lifecycle-review` or the relevant database skill.
+- The state is intentionally restored by an explicit product contract and the task is only to polish copy, layout, or accessibility.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Symptom timeline: before action, during action, completion or close moment, before shutdown or reload, after restart or reload, after reconnect or sync, and whether the same identity returns.
+- Identity ledger: user ID, workspace or tenant ID, route params, conversation ID, message ID, logical ID, instance ID, run ID, submission ID, stream ID, panel ID, tab key, task ID, event ID, event sequence, cursor, server version, message version, schema version, pending command ID, idempotency key, tombstone version, and process start time where relevant.
+- Source ledger: memory store, query cache, router state, URL state, persisted store, browser storage, service worker cache, desktop user-data files, mobile storage, server layout, cloud sync, crash recovery, migration, and cross-tab or cross-device channels.
+- Finalize ledger: close, clear, complete, delete, submit, archive, done, `message.complete`, or equivalent action; memory clear, persisted clear, query-cache update, pending write cancellation, hydration abort, server invalidation, tombstone or watermark write, and sync conflict policy.
+- Streaming ownership ledger: gateway or listener, envelope validator, event handler or processor, reducer or state machine, UI selector, persistence writer, hydration guard, cleanup owner, runtime generation owner, ack policy, and replay or resync policy.
+- Runtime health ledger: message status, terminal status, session health, restart-required state, runtime ID, generation ID, old-generation event rejection, terminal error archive, transcript retention, and active-runtime cleanup.
+- Read and write paths: store actions, reducers, selectors, query cache writes, persistence middleware, storage reads and writes, hydration callbacks, route loaders, app init effects, WebSocket or event replay handlers, HTTP refetch handlers, BroadcastChannel handlers, migrations, and save-last-session code.
+- Test or reproduction surface: delayed persist write, delayed HTTP snapshot, reconnect replay, route remount, store recreation, app restart, clean profile, copied app-data folder, cross-tab broadcast, cross-device sync, and schema migration where relevant.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Existing local patterns for persistence, hydration, cache restore, session restore, crash recovery, cross-tab sync, and server-side layout storage have been searched before adding another cleanup effect.
+- If the resurrected state affects auth, tenant isolation, privacy, payment, deletion, or server data correctness, also apply the narrower security, payment, deletion, database, or cache skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add source labels, identity keys, timestamps, versions, event sequences, debug logs, and bounded instrumentation that prove which path wrote or read the resurrected value.
+- Convert close, clear, complete, delete, archive, or done handlers into a single finalize action when state must be cleared across memory, persisted storage, query cache, inflight hydration, pending writes, server snapshots, and sync surfaces.
+- Add tombstones, watermarks, generation IDs, abort tokens, schema migrations, identity guards, persisted-state partialization, merge filters, and stale-payload rejection for completed or cleared UI state.
+- Split ephemeral in-progress state from committed history or durable layout state so a restored snapshot cannot recreate a completed run, closed panel, or cleared draft.
+- Replace authoritative `active` and `finished` stores with selectors over one lifecycle truth when both lists can drift, duplicate, or resurrect the same item.
+- Add lifecycle fields such as `logicalId`, `instanceId`, `status`, `version`, `eventCursor`, `pendingCommandId`, `idempotencyKey`, and `tombstone` when provenance shows projections are being stored as truth.
+- Split streaming gateway, event handler, state store, persistence writer, hydration guard, and cleanup into explicit owners when one handler mutates UI state, session state, and durable storage.
+- Add append-only event logs, snapshots, high-watermarks, durable-write acknowledgements, runtime or generation IDs, buffered hydration queues, and old-generation event rejection when streaming replay can cross restart or hydration boundaries.
+- Add focused tests for delayed writes after finalize, stale HTTP snapshots, reconnect replay, route remount, cross-tab stale broadcasts, cross-device sync overwrite, crash recovery priority, migration defaulting, `message.complete` versus `terminal-error`, restart generation changes, and stale old-generation stream events.
+- Do not fix resurrection by adding another render-time hide flag, CSS rule, duplicate cleanup effect, broad storage wipe, global cache clear, or product-state deletion unless provenance proves that scope is correct.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Prove whether the UI is new or restored.
+   - Compare IDs, route params, tab keys, titles, positions, collapsed state, selected tab, task IDs, message IDs, run IDs, timestamps, and schema versions before and after restart, reload, remount, reconnect, or sync.
+   - If the same old identity returns after memory should be gone, prioritize persistence, hydration, replay, sync, migration, or crash recovery over rendering.
+2. Snapshot every storage layer around the lifecycle.
+   - Capture state before the user action, during in-progress work, immediately after completion or close, before shutdown or reload, and immediately after restart or hydration.
+   - For web apps, inspect localStorage, sessionStorage, IndexedDB, CacheStorage, service worker cache, persisted query caches, and SSR bootstrap payloads.
+   - For desktop apps, inspect user-data SQLite, JSON, LevelDB, preferences, workspace-state files, crash recovery files, and cloud sync files.
+   - For mobile apps, inspect shared preferences, SQLite, key-value stores, sandbox restore state, and platform state restoration.
+   - Look for names such as `openPanels`, `activeTaskPanel`, `workspaceLayout`, `restoredTabs`, `lastSession`, `pendingTasks`, `taskViews`, `streamingMessage`, `pendingEvents`, `draftResponse`, `activeRun`, `completedStreamIds`, `lastCompletedEventSeq`, `clearedAt`, and `runFinalizedAt`.
+3. Add provenance to reads and writes.
+   - Label each value with source, action name, previous value, next value, stack or caller, route, tab, user, workspace, message, run, event sequence, created time, written time, rehydrated time, and persist version when safe.
+   - Instrument store actions, reducers, query cache `setQueryData`, persistence `setItem`, IndexedDB writes, server response application, hydration callbacks, route loaders, app init effects, replay handlers, and BroadcastChannel handlers.
+   - Keep logs bounded and scrub secrets or personal data according to repository policy.
+4. Reconstruct the timeline.
+   - The common failure is: stale in-progress state is scheduled for persistence, completion clears memory, a delayed write flushes the old snapshot, hydration later reads it, and the UI honestly renders it.
+   - Check whether `hydrate`, `restore`, `merge`, `sync`, `initialize`, `loadDraft`, `resumeSession`, `reconnect`, `onFocus`, `onMount`, or `saveLastSession` runs after finalize.
+   - Compare process start time with stored `createdAt` or `rehydratedAt`; old timestamps in post-start state are strong resurrection evidence.
+5. Inspect finalize semantics.
+   - Treat `message.complete`, close, clear, delete, done, and archive as finalization events, not only render cleanup.
+   - Finalize should clear memory, remove or update persisted state, remove ephemeral query-cache fields, cancel pending persisted writes, abort inflight hydration, invalidate or patch server snapshots, and record a tombstone or watermark when replay is possible.
+   - Persisting only `null` may be weaker than persisting "this run or panel was finalized at this sequence/time" when old payloads can arrive later.
+6. Review hydration merge policy.
+   - Reject blind shallow merges such as persisted state overriding current state without identity, version, and tombstone checks.
+   - Hydration should restore only if the persisted payload matches the current user, workspace, conversation, message, run, route, schema, and lifecycle, and is newer than the relevant clear or completion watermark.
+   - Drop streaming, draft, panel, and task-view fields from persisted state unless they have an explicit restoration contract.
+7. Review inbound event ordering.
+   - `message.delta`, `message.complete`, reconnect replay, snapshot refresh, and history load may arrive through different paths.
+   - Require event sequence, server version, message version, run ID, or generation ID checks so replayed or late payloads older than completion cannot rebuild ephemeral UI.
+   - Delayed HTTP snapshots and background refetches must not recreate streaming or panel state after finalize.
+8. Review streaming responsibility separation.
+   - Treat the gateway as a connection and envelope owner only: open the stream, parse chunks, validate `sessionId`, `streamId`, `eventId`, `seq`, `createdAt`, `type`, and `payload`, then hand off the event.
+   - Keep UI mutation and durable persistence out of the gateway. A listener that calls component setters and writes session storage in the same branch is a source-of-truth split.
+   - Let the event handler validate, deduplicate, order, and translate external events into internal commands. It should not decide component display policy or directly edit durable storage.
+   - Keep the state store as the only in-memory truth. Reducers or state machines should apply commands deterministically and update metadata such as `lastAppliedSeq`, `appliedEventIds`, `sessionStatus`, `messageIndex`, and `pendingToolCalls`.
+   - Make the persistence writer own event log, snapshots, high-watermark, schema version, migration, compaction, blob references, dirty markers, and durable-write success. Send server acknowledgements only through the durable boundary when acknowledgement means recoverability.
+   - Make the hydration guard buffer live events while snapshots or logs load, discard events older than the restored high-watermark, request replay or resync when a sequence gap appears, and reject late hydration from an obsolete runtime generation.
+   - Make cleanup dispose the runtime generation: abort streams, cancel readers, remove heartbeat and retry timers, stop new persistence writes, finish or mark short idempotent writes, drop buffered events, and require async callbacks to check `runtimeId` or generation tokens.
+9. Separate message lifecycle from runtime health.
+   - `message.complete` ends the message lifecycle only. It should not clear terminal errors, mark runtime health as clean, erase restart-required state, or turn old terminal failures into success.
+   - `terminal-error` changes terminal and session health. It should not rewrite already completed messages as failed messages, delete message content, or pretend a partial message completed successfully.
+   - Model message status, terminal status, session health, and restart state separately instead of flattening them into `isDone`, `isLoading`, or `hasError`.
+   - Allow states such as `completedWithTerminalError`: the user may have a complete assistant message and a broken terminal at the same time.
+   - On restart, create a new runtime generation. Preserve transcript history when the product contract requires it, clear or archive active terminal errors, cancel pending streams, and reject old-generation `message.complete`, `terminal-error`, stdout, stderr, delta, and tool events.
+10. Review identity boundaries.
+   - Persist and query keys must include every dimension that changes ownership: user, tenant, workspace, route, conversation, message, run, tab, and feature or locale dimensions when relevant.
+   - A key like `chat-state`, `workspace-layout`, or `activeMessage` is unsafe when more than one identity can share it.
+   - On logout, tenant switch, workspace switch, conversation switch, or route identity change, clear or reject state from the previous identity.
+11. Review active, finished, and pending as lifecycle projections.
+   - Treat `active` and `finished` as selectors over one lifecycle model, not two independent authoritative stores.
+   - Preserve user intent, externally confirmed facts, and unfinished retryable work; clear only UI posture such as selected tab, accordion open state, hover, scroll, temporary filters, or transient loading decorations without durable evidence.
+   - Keep active until a terminal event such as finished, cancelled, deleted, archived, or tombstoned is confirmed with a version, cursor, or event ID and can be replayed after restart.
+   - Keep finished as append-only or versioned history until a versioned delete, archive, purge, retention expiry, or tombstone event proves removal; do not let an old restored snapshot erase newer finished facts.
+   - Keep pending finish, submit, close, delete, or archive commands with a command ID or idempotency key until success or failure ack decides whether to clear, retry, or restore active state.
+   - If the same logical item can have a current attempt and past completed records, separate user-facing `logicalId` from lifecycle `instanceId`, `runId`, or `submissionId`.
+   - Use one reducer for persisted snapshots, realtime events, and local commands so version, cursor, event ID, tombstone, and pending-command rules arbitrate every input consistently.
+   - Snapshot restore is not truth. A restored active or finished value must lose to newer versions, later cursors, tombstones, and already-applied event IDs even when the snapshot came from local disk or server layout.
+12. Review async generation and remounts.
+   - Provider remount, StrictMode development double execution, HMR, route segment remount, auth context change, tab focus, and reconnect can run hydration more than once.
+   - Async hydration needs request tokens, generation IDs, or AbortController-style cancellation so late loads cannot overwrite current finalized state.
+13. Review local, server, and sync authority.
+    - Test a clean browser profile or OS user; if the issue disappears, local persisted state is likely.
+    - Test a clean device after login; if the issue returns, server layout, session state, or cloud sync is likely.
+    - Delete only the suspect stored record; if the UI disappears after restart, the stored record had authority.
+    - Inject the stored record into a clean environment; if it reproduces, the restore path is proven.
+    - Check multi-device conflict policy: an old open state from device B must not overwrite a newer close or complete from device A.
+14. Review migrations and crash recovery.
+    - Migration defaults must not convert old `closed: true`, `completed`, `done`, or missing lifecycle fields into open or active state.
+    - Crash recovery files must not outrank a normal session file that recorded a later finalize.
+    - Save-last-session code must save the latest state, not a stale captured snapshot from before completion.
+15. Add targeted regression evidence.
+   - Prefer tests that model delayed persisted writes, persisted-store rehydration after finalize, stale HTTP snapshot after complete, reconnect replay after complete, route remount after complete, cross-tab stale broadcast, cross-device stale sync, and migration of old session records.
+   - Assert that rendering follows store state honestly, and that the store refuses old restored state after finalization.
+   - Add active, finished, and pending tests where a stale snapshot, replayed realtime event, duplicate event ID, command retry, or tombstone competes for the same logical ID or instance ID.
+   - Add reducer tests for `message.delta` to `message.complete`, duplicate `message.complete`, `terminal-error` preserving message content, `terminal-error` then `message.complete`, `message.complete` then `terminal-error`, hydration idempotency, restart generation changes, and stale old-generation event rejection.
+   - Add integration tests for normal streaming completion, terminal error before message completion, terminal error after message completion, refresh hydration of `completedWithTerminalError`, restart from a hydrated error session, and old-generation events arriving after restart.
+   - Add transition-table tests for `ready`, `streaming`, `completed`, `terminalError`, `completedWithTerminalError`, `hydrating`, `restarting`, and `readyAfterRestart` when those states exist in the product model.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The resurrected UI is classified as newly created, restored from local persistence, restored from query or service-worker cache, restored from desktop or mobile app data, restored from server layout, restored from sync, restored by replay, restored by migration, restored by crash recovery, or not yet localized.
+- Finalize actions clear or tombstone memory, persistence, query cache, inflight hydration, pending writes, server snapshots, and sync inputs where relevant.
+- Hydration and replay paths reject stale, wrong-identity, wrong-schema, or older-than-watermark payloads.
+- Streaming event handling has one mutation pipeline from gateway to event handler, state store, persistence writer, hydration guard, cleanup, and UI selectors; handlers do not directly mutate both UI and durable storage.
+- `message.complete`, `terminal-error`, hydration, and restart are proven separate lifecycle concerns rather than competing flat flags.
+- `active`, `finished`, and `pending` are either proven projections from one lifecycle truth or the remaining multi-source drift is reported.
+- Tests or reproduction evidence cover the changed lifecycle boundary, or missing evidence is reported explicitly.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured frontend, unit, integration, docs, release, or mustflow intent that covers the persistence, hydration, replay, sync, migration, or finalize boundary. Do not infer raw browser, dev-server, storage-inspection, database, sync-service, or mobile commands outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If storage access, server layout, sync logs, or app-data files are unavailable, report which source remains unproven instead of claiming a render fix.
+- If the state source cannot be named, add bounded provenance before changing cleanup logic.
+- If a proposed fix only hides the component while the old record remains restorable, reject it as symptom masking.
+- If clearing all storage would hide the bug but delete user data, narrow the stored record, identity, tombstone, or migration rule first.
+- If tests need live browser, mobile, desktop, sync, or production telemetry not configured in `.mustflow/config/commands.toml`, run available local checks and report the manual evidence gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- UI state resurrection surface reviewed
+- New-versus-restored verdict and identity evidence
+- Source ledger: memory, query cache, persisted store, browser storage, desktop or mobile storage, server layout, sync, replay, migration, and crash recovery where relevant
+- Timeline: write, finalize, delayed write, read, hydrate, replay, remount, sync, and render order
+- Streaming ownership: gateway, event handler, state store, persistence writer, hydration guard, cleanup, ack, and UI selector boundary
+- Finalize, tombstone, watermark, merge, identity, lifecycle projection, runtime health, terminal health, pending command, generation, cache, and migration decisions
+- Fixes made or recommended
+- Tests or reproduction evidence
+- Command intents run
+- Skipped resurrection diagnostics and reasons
+- Remaining UI state resurrection risk

package/templates/default/locales/en/.mustflow/skills/version-freshness-check/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.version-freshness-check
 locale: en
 canonical: true
-revision: 8
+revision: 10
 lifecycle: mustflow-owned
 authority: procedure
 name: version-freshness-check
-description: Apply this skill when generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, Python standard-library/API references, TypeScript compiler-track references, Go release, toolchain, standard-library, runtime, or experiment references, Rust release, toolchain, standard-library, Cargo, edition, MSRV, lint, or target references, HTTP standard or browser-support references, or migration-sensitive snippets introduce explicit external version references that may be stale.
+description: Apply this skill when generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, Python standard-library/API references, TypeScript compiler-track references, Go release, toolchain, standard-library, runtime, experiment, framework, or dependency references such as Gin, Java or JDK release, GA, LTS, support, JEP, JVM flag, GC, virtual-thread, preview, incubator, or build-tool references, Rust release, toolchain, standard-library, Cargo, edition, MSRV, lint, or target references, HTTP standard or browser-support references, or migration-sensitive snippets introduce explicit external version references that may be stale.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -36,7 +36,8 @@ Prevent agents from writing stale external version references from memory, while
 - CI workflows, release workflows, Dockerfiles, package metadata, lockfiles, runtime files, framework configuration, README examples, docs, tests, fixtures, or templates mention external versions such as GitHub Actions refs, Node, Bun, Deno, Python, Rust, Tauri, Astro, Next, SvelteKit, Electron, Docker images, package managers, SDKs, plugins, or generators.
 - Python wording mentions current/stable/support status, Python 3.14+ or 3.15+ syntax, standard-library APIs, runtime flags, changed default behavior, security defaults, or examples that depend on `requires-python`.
 - TypeScript wording mentions current/stable/RC/nightly status for TypeScript 6, TypeScript 7, `@typescript/typescript6`, `tsc6`, `typescript@rc`, `@typescript/native-preview`, `tsgo`, compiler API compatibility, or migration readiness.
-- Go wording mentions current/stable/support status, Go release numbers, `go.mod` language version behavior, `toolchain` behavior, standard-library APIs, `GOEXPERIMENT`, runtime defaults, container behavior, JSON experiments, or examples that depend on a specific Go version.
+- Go wording mentions current/stable/support status, Go release numbers, `go.mod` language version behavior, `toolchain` behavior, standard-library APIs, `GOEXPERIMENT`, runtime defaults, container behavior, JSON experiments, third-party Go framework releases such as Gin, framework minimum-Go requirements, or examples that depend on a specific Go or framework version.
+- Java wording mentions current/stable/GA/LTS/support status, Java or JDK release numbers, Oracle/OpenJDK/vendor support tracks, JEP status, preview or incubator APIs, JVM flags, GC behavior, virtual-thread behavior, `ScopedValue`, structured concurrency, final-field reflection restrictions, applet removal, HTTP/3, AOT cache, Compact Object Headers, JFR, JMH, container memory or CPU behavior, Maven or Gradle toolchains, bytecode target, or examples that depend on a specific Java version.
 - Rust wording mentions current/stable/support status, Rust release numbers, `rust-version`, edition behavior, `rust-toolchain`, Cargo resolver or workspace behavior, standard-library APIs, compiler lints, target behavior, release profiles, or examples that depend on a specific Rust version.
 - HTTP delivery wording mentions current support, baseline status, default behavior, standard status, or compatibility for zstd content coding, compression dictionary transport, SSE/EventSource, WebTransport, WebSocket fallback, HTTP/2, HTTP/3, QUIC, CDN behavior, proxy buffering, or browser transport APIs.
 - An agent proposes a versioned dependency, tool, framework, action, image, or runtime based on memory, copied snippets, older project examples, or user-provided text that may be stale.
@@ -93,21 +94,25 @@ Prevent agents from writing stale external version references from memory, while
 9. For existing projects, do not cross a major, migration-required, engine, framework, CI-image, or generated-output boundary without user approval or explicit repository policy.
 10. For patch, security-minimum, and low-risk minor differences, update only when the declaration, examples, lockfile policy, and verification surface can stay aligned. Otherwise report the proposed change and leave the pinned value unchanged.
 11. For GitHub Actions and CI tools, review the action source, major tag policy, runtime support, cache behavior, permissions, and organization pinning rule. Do not assume a newer major is safe only because it exists.
-12. For framework and runtime majors such as Astro, Tauri, Electron, Next, SvelteKit, Node, Bun, Deno, Python, Rust, or Java, check migration notes, config schema, plugin and adapter compatibility, generated files, security model, deployment target, and rollback path before recommending a major change.
+12. For framework and runtime majors such as Astro, Tauri, Electron, Next, SvelteKit, Node, Bun, Deno, Python, Go, Java, Rust, or JavaScript runtimes, check migration notes, config schema, plugin and adapter compatibility, generated files, security model, deployment target, and rollback path before recommending a major change.
 13. For Python standard-library or runtime-behavior claims, refresh official Python documentation before writing durable wording. Check `requires-python`, CI/runtime matrices, and container images before using or recommending Python 3.14+ standard-library APIs or version-gated features such as template string literals, `annotationlib`, Python 3.14+ `map(strict=True)`, `functools.Placeholder`, `heapq` max-heap helpers, import-timing flag behavior, `finally` flow-control warnings, or changed security defaults.
 14. For Python examples that use newer standard-library APIs, either keep the example behind an explicit runtime floor or provide a supported fallback. Do not call a Python 3.14-only API a general Python best practice when the repository declares lower support.
 15. For Python 3.15+ claims, keep beta, release-candidate, and stable tracks separate. Refresh official docs before using explicit lazy imports, built-in `frozendict`, built-in `sentinel`, unpacking comprehensions, typed `TypedDict` extra items, startup configuration files, or changed encoding behavior in durable examples.
 16. For TypeScript 6 and 7 claims, refresh official TypeScript sources before writing durable wording. Treat TS6 stable API track (`@typescript/typescript6`, `tsc6`), TS7 RC compiler track (`typescript@rc`, `tsc`), TS7 nightly track (`@typescript/native-preview`, `tsgo`), and future TS7 stable `typescript` behavior as distinct tracks. Do not call RC or nightly output "latest stable TypeScript" just because it is newer.
 17. For TypeScript examples, make the selected track explicit: TS6 API compatibility, TS7 RC compiler verification, TS7 nightly comparison, editor preview, or repository adoption. If the project has compiler API consumers, transformers, framework wrappers, or declaration snapshots, classify the reference as migration-sensitive and keep API consumers on the TS6 API track until support is explicit. Check exact support before relying on `rootDir` defaults, ambient `types` defaults, import attributes, subpath imports, `import defer`, `using`, or `await using`.
 18. For Go release, toolchain, standard-library, runtime, or experiment claims, refresh official Go release notes or package documentation before writing durable wording. Check the repository's `go` directive, `toolchain` directive, CI/runtime matrix, and container target before using or recommending version-gated features such as expression operands to `new`, range-over-function iterators, generic type aliases, reflect iterator methods, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `ReverseProxy.Rewrite`, container-aware `GOMAXPROCS`, goroutine leak profiles, `encoding/json/v2`, or `GOEXPERIMENT` APIs.
-19. For Go examples that use newer standard-library APIs or runtime defaults, either keep the example behind an explicit Go version floor or provide a supported fallback. Do not call an experimental `GOEXPERIMENT` feature or a newer `go` directive behavior a general Go best practice when the repository declares lower support.
-20. For Rust release, toolchain, standard-library, Cargo, edition, lint, target, or MSRV claims, refresh official Rust release notes, standard-library docs, the Cargo Book, Rust Reference, or rustc book before writing durable wording. Check `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, docs.rs metadata, and crate publish policy before using or recommending version-gated features such as let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `resolver = "2"`, Rust 2024 `unsafe extern`, unsafe attributes, Rust 2024 `unsafe_op_in_unsafe_fn`, temporary drop-scope changes, macro fragment behavior, or release-profile defaults.
-21. For Rust examples that use newer language or standard-library APIs, either keep the example behind an explicit Rust version floor or provide a supported fallback. Use an API-by-API MSRV ledger for features such as `cfg_select!`, match `if let` guards, `core::range` items, `Vec::push_mut`, `assert_matches!`, and `debug_assert_matches!`; do not collapse them into a single "latest Rust" bucket, and do not treat nightly-only behavior or target-specific linker behavior as stable without explicit evidence.
-22. For HTTP standards, browser APIs, proxy defaults, CDN defaults, and transport support claims, prefer official RFCs, standards bodies, MDN or browser vendor docs, and vendor-owned proxy/CDN documentation. Keep WebTransport, compression dictionary transport, zstd content coding, SSE/EventSource, HTTP/2, HTTP/3, QUIC, and proxy-buffering claims track-specific and dated when support is changing.
-23. For HTTP delivery examples that depend on newer or unevenly supported behavior, require feature detection, fallback behavior, or explicit deployment constraints. Do not present WebTransport, dictionary compression, or zstd negotiation as a universal default when the project still needs browsers, proxies, CDNs, or networks that may not support it.
-24. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
-25. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
-26. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, TypeScript compiler-track, Go toolchain or runtime support, Rust toolchain or MSRV support, HTTP delivery compatibility, or security-sensitive changes.
+19. For Go framework and dependency release claims, refresh the source that owns the artifact before writing durable wording. For Gin, prefer official Gin release notes, pkg.go.dev module metadata, and the upstream repository release or source files for claims about latest stable version, minimum Go version, HTTP/3 support, BSON support, binding behavior, router options, logger options, trusted proxy behavior, or `Context` APIs. Keep framework upgrade advice separate from repository adoption, because a framework minor can still require a Go toolchain, CI image, Docker base, middleware, route, or binding migration.
+20. For Go examples that use newer standard-library APIs, framework APIs, or runtime defaults, either keep the example behind an explicit Go or framework version floor or provide a supported fallback. Do not call an experimental `GOEXPERIMENT` feature, a newer `go` directive behavior, or a newly added framework method a general Go best practice when the repository declares lower support.
+21. For Java or JDK release, support, JEP, standard-library, JVM flag, GC, virtual-thread, preview, incubator, or build-tool claims, refresh official Java, OpenJDK, vendor, Maven, or Gradle sources before writing durable wording. Check the repository's source and target release, Maven or Gradle toolchain, wrapper, CI runtime matrix, container image, JDK vendor policy, and bytecode compatibility before using or recommending version-gated features such as module import declarations, compact source files, instance main methods, flexible constructor bodies, `ScopedValue`, structured concurrency, primitive pattern matching, final-field reflection restrictions, applet API removal, `java.net.http.HttpClient` HTTP/3, AOT cache or method profiling, Compact Object Headers, Generational Shenandoah, JFR method timing, KDF APIs, PEM APIs, Lazy Constants, or Vector API.
+22. For Java examples that use newer language, standard-library, JVM, or build-tool behavior, either keep the example behind an explicit Java and toolchain version floor or provide a supported fallback. Do not collapse latest GA, latest LTS, repository runtime, vendor support, delivered JEP, preview JEP, incubator API, product feature, and default-enabled behavior into one "latest Java" bucket. Treat JVM AOT cache as startup or warmup optimization, not Native Image, and treat Java HTTP/3 as client-side opt-in unless current official docs say otherwise.
+23. For Java performance and JVM tuning claims, refresh official JVM, GC, JFR, JMH, and vendor documentation before writing durable wording. Keep G1 pause targets as goals rather than SLAs, ZGC and Shenandoah as CPU and headroom tradeoffs rather than free latency switches, Compact Object Headers and Generational Shenandoah as enablement-specific when applicable, and container memory claims separate across heap, direct buffers, metaspace, code cache, thread stacks, native memory, `MaxRAMPercentage`, `MaxDirectMemorySize`, and `ActiveProcessorCount`.
+24. For Rust release, toolchain, standard-library, Cargo, edition, lint, target, or MSRV claims, refresh official Rust release notes, standard-library docs, the Cargo Book, Rust Reference, or rustc book before writing durable wording. Check `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, docs.rs metadata, and crate publish policy before using or recommending version-gated features such as let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `resolver = "2"`, Rust 2024 `unsafe extern`, unsafe attributes, Rust 2024 `unsafe_op_in_unsafe_fn`, temporary drop-scope changes, macro fragment behavior, or release-profile defaults.
+25. For Rust examples that use newer language or standard-library APIs, either keep the example behind an explicit Rust version floor or provide a supported fallback. Use an API-by-API MSRV ledger for features such as `cfg_select!`, match `if let` guards, `core::range` items, `Vec::push_mut`, `assert_matches!`, and `debug_assert_matches!`; do not collapse them into a single "latest Rust" bucket, and do not treat nightly-only behavior or target-specific linker behavior as stable without explicit evidence.
+26. For HTTP standards, browser APIs, proxy defaults, CDN defaults, and transport support claims, prefer official RFCs, standards bodies, MDN or browser vendor docs, and vendor-owned proxy/CDN documentation. Keep WebTransport, compression dictionary transport, zstd content coding, SSE/EventSource, HTTP/2, HTTP/3, QUIC, and proxy-buffering claims track-specific and dated when support is changing.
+27. For HTTP delivery examples that depend on newer or unevenly supported behavior, require feature detection, fallback behavior, or explicit deployment constraints. Do not present WebTransport, dictionary compression, or zstd negotiation as a universal default when the project still needs browsers, proxies, CDNs, or networks that may not support it.
+28. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
+29. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
+30. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, TypeScript compiler-track, Go toolchain or runtime support, Go framework runtime support, Java JDK/toolchain/bytecode/runtime support, JVM tuning, Rust toolchain or MSRV support, HTTP delivery compatibility, or security-sensitive changes.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -119,7 +124,8 @@ Prevent agents from writing stale external version references from memory, while
 - Python standard-library examples and runtime-default claims match the declared Python support matrix or name the required runtime floor.
 - Python template strings, annotation inspection, explicit lazy imports, immutable mappings, sentinels, and advanced `TypedDict` shape claims are either official-source checked or omitted.
 - TypeScript 6 stable API, TypeScript 7 RC compiler, TypeScript 7 nightly, and future stable TypeScript tracks are not collapsed into one generic "latest TypeScript" claim.
-- Go release, `go.mod` language version, standard-library API, runtime-default, and `GOEXPERIMENT` claims match the declared Go support matrix or name the required runtime floor.
+- Go release, `go.mod` language version, standard-library API, framework dependency API such as Gin, runtime-default, and `GOEXPERIMENT` claims match the declared Go support matrix or name the required runtime or framework floor.
+- Java release, JDK vendor, source or target release, bytecode target, JEP status, standard-library API, virtual-thread behavior, preview or incubator API, build-tool support, JVM flag, GC behavior, and container-runtime claims match the declared Java support matrix or name the required runtime, toolchain, and feature floor.
 - Rust release, `rust-version`, edition, standard-library API, Cargo resolver, lint-default, target, and nightly/stable claims match the declared Rust support matrix or name the required API-specific runtime floor.
 - HTTP standard, browser-support, proxy-default, CDN-default, and transport-support claims are not written from stale memory and keep feature detection or fallback boundaries explicit where support varies.
 - Docs and examples do not make unverifiable current-version claims.
@@ -147,7 +153,8 @@ Choose the narrowest configured intent that proves the changed versioned surface
 - If a freshness check requires network, credentials, or a connector that is not available, report the boundary and avoid current-version claims.
 - If a proposed major or migration-required version is better for greenfield work but risky for the existing project, present both choices and ask before changing the project.
 - If TypeScript 7 RC, nightly, or stable freshness changes during the task, update wording to a dated or track-specific claim and keep repository adoption separate from comparison-only checks.
-- If Go release or experiment freshness changes during the task, update wording to a dated or track-specific claim and keep official release status, `go` directive adoption, CI support, and `GOEXPERIMENT` adoption separate.
+- If Go release, framework release, or experiment freshness changes during the task, update wording to a dated or track-specific claim and keep official release status, `go` directive adoption, framework adoption, CI support, and `GOEXPERIMENT` adoption separate.
+- If Java release, JEP, JVM flag, GC, or toolchain freshness changes during the task, update wording to a dated or track-specific claim and keep latest GA, latest LTS, repository runtime, vendor support, preview or incubator status, product feature status, default-enabled behavior, build-tool support, and CI or container adoption separate.
 - If Rust release or toolchain freshness changes during the task, update wording to a dated or track-specific claim and keep official release status, MSRV adoption, edition adoption, CI support, target support, and nightly or unstable features separate.
 - If HTTP delivery support changes during the task, update wording to a dated or track-specific claim and keep standards, browser support, CDN behavior, proxy defaults, and repository adoption separate.
 - If verification fails after a freshness update, do not weaken tests, lower type checks, delete lockfiles, or widen ranges to make the update pass. Revert or narrow the version decision unless the behavior change is intentional.

package/templates/default/locales/en/.mustflow/skills/writing-elegance/SKILL.md

@@ -0,0 +1,193 @@
+---
+mustflow_doc: skill.writing-elegance
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: writing-elegance
+description: Apply this skill when a user provides Korean or English prose and asks to extract reusable elegant wording candidates, collect selected phrase fragments into a phrase bank, or polish writing with previously selected modular expressions. Also apply it as a style-polish adjunct for report-style answers, final reports, GitHub issue bodies, pull request descriptions, review replies, maintainer-facing comments, release or update notes, documentation prose, summaries, and explanatory writing when facts are already established and the goal is clearer, more graceful wording.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.writing-elegance
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Writing Elegance
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Build and use a small phrase bank of reusable wording patterns that make prose, documentation,
+answers, summaries, issue or pull-request text, reports, and narrative explanations more graceful
+without locking the agent into over-specific sentences.
+
+This skill is not a generic rewrite machine. It collects modular fragments that can survive across
+contexts, languages, subjects, and genres.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The user provides Korean or English prose and asks for elegant words, expressions, phrasing, or
+  sentence patterns that could be reused later.
+- The user asks for seven numbered candidate expressions from a supplied text and intends to choose
+  which candidates should be stored.
+- The user selects candidate numbers to keep, reject, or revise for future skill guidance.
+- The task is to polish a document, answer, report, comment, or explanation using a curated phrase
+  bank rather than inventing style from scratch.
+- The task is to improve the wording of a final report, implementation summary, GitHub issue body,
+  pull request description, review reply, maintainer-facing comment, release note, update note, or
+  Markdown report after the factual evidence and owning workflow skill have already set the content.
+- The work needs Korean source fragments translated into English guidance for a reusable skill.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a documentation review queue entry or AI-slop cleanup for a mustflow document. Use
+  `docs-prose-review` first.
+- The task changes technical facts, commands, API contracts, code snippets, schema text, legal text,
+  safety instructions, or release/change history where correctness, evidence, or repository policy
+  still needs the owning skill before any style polish.
+- The user asks for one-off translation, summarization, grammar correction, or copy editing with no
+  reusable phrase-bank goal.
+- The candidate expression depends on a proper noun, character name, unique setting, private event,
+  or one-time plot situation that would not transfer to other writing.
+- The phrase only sounds ornate but does not improve precision, tone control, rhythm, or emotional
+  framing.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Source text in Korean or English.
+- The intended mode: candidate extraction, selected-candidate storage, phrase-bank application, or
+  phrase-bank cleanup.
+- The target register when known: literary, technical, explanatory, product, support, review,
+  maintainer-facing, casual, formal, or emotionally restrained.
+- The target surface when relevant: chat answer, final report, Markdown report, GitHub issue, pull
+  request description, review reply, release note, update note, documentation page, or comment.
+- Any user feedback about what to keep, reject, generalize, split, shorten, or rewrite.
+- The current phrase bank when storing or applying selected expressions.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Candidate extraction can preserve the original meaning without copying long source passages.
+- Phrase-bank entries can be generalized without retaining private names, narrow plot facts, or
+  one-off circumstances.
+- If repository files will be edited, higher-priority instructions and command contracts have been
+  checked first.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- For ordinary chat rounds, make no file edits. Return only a numbered candidate table.
+- When the user asks to preserve selected candidates, update the phrase bank and only directly
+  synchronized skill/template metadata needed for that stored expression.
+- Keep `SKILL.md` procedural and short. Store accumulated expressions in `references/phrase-bank.md`
+  or a split reference file when the bank grows.
+- Do not store raw source excerpts beyond the short fragment needed to identify the pattern.
+- Do not store private names, unique character names, narrow plot facts, or whole paragraphs in the
+  phrase bank.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the round:
+   - `candidate_extraction`: the user supplied prose and needs seven numbered candidates;
+   - `selection_storage`: the user selected candidate numbers to keep or discard;
+   - `application`: the user wants existing phrase-bank patterns applied to a text;
+   - `cleanup`: the phrase bank needs deduplication, splitting, or reorganization.
+2. For candidate extraction, read the supplied text and choose exactly seven candidates unless the
+   user asks for a different count.
+3. Prefer reusable fragments over finished sentences:
+   - keep fragments that can attach to many nouns, scenes, arguments, or explanations;
+   - split before a proper noun, unique event, one-time setting, or over-specific object;
+   - keep the smallest phrase that carries the style value.
+4. For Korean source text, include the Korean source fragment and translate the reusable guidance
+   into English.
+5. For English source text, preserve the short source fragment, include a concise Korean
+   translation column in candidate tables, and derive a generalized English pattern.
+6. Reject candidates that are:
+   - tied to a named person, place, product, fictional setting, or unique incident;
+   - too complete to recombine;
+   - too vague to guide future writing;
+   - decorative without improving meaning;
+   - likely to overwrite the writer's actual register.
+7. Return a numbered table with these columns:
+   - `No.`
+   - `Source Fragment`
+   - `Korean Translation` when the source text is English
+   - `Reusable English Pattern`
+   - `Reusable Range`
+   - `Skill Note`
+8. When the user selects entries, store only those entries. Preserve rejected numbers as absent, not
+   as negative examples, unless the user explicitly asks to record a rejection rule.
+9. Store entries as compact rows with:
+   - source language;
+   - source fragment;
+   - reusable English pattern;
+   - use guidance;
+   - avoid guidance when a common misuse is known.
+10. When applying the phrase bank, use entries as taste constraints, not mandatory substitutions.
+    Preserve technical facts, evidence, legal meaning, safety warnings, user intent, and the original
+    level of certainty.
+11. When polishing GitHub, release, verification, or final-report content, apply the owning skill
+    first for evidence, repository rules, version facts, and verification scope. Use this skill only
+    to make the already-correct wording clearer, smoother, or more elegant.
+12. When the phrase bank grows too large, split it by usage type such as emotional framing,
+    restrained technical polish, transitions, softening, emphasis, scene atmosphere, or answer tone.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Candidate tables contain reusable fragments rather than narrow finished sentences.
+- Stored entries are in English guidance even when the source text was Korean.
+- Proper nouns, private details, unique plot facts, and one-off situations are excluded or
+  generalized.
+- The phrase bank remains compact enough to load only when needed.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when repository files are changed:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Do not infer raw validation commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the source text is too long, extract candidates from the most style-dense sections and report
+  that the pass was selective.
+- If all appealing phrases are too situation-specific, return fewer strong candidates or ask for a
+  different sample instead of padding the table.
+- If the user rejects a candidate for being too narrow, split it into a smaller reusable fragment
+  and avoid storing the rejected broad form.
+- If a phrase-bank entry starts to duplicate another entry, merge the guidance instead of adding a
+  near-copy.
+- If applying a phrase would make a technical or factual answer less clear, preserve clarity and
+  report that the phrase was skipped.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Mode: candidate extraction, selection storage, application, or cleanup
+- Candidate table or stored entries
+- Entries kept and rejected when relevant
+- Phrase-bank file changed when relevant
+- Command intents run when repository files changed
+- Skipped checks and reasons
+- Remaining style, specificity, or privacy risk