mustflow 2.116.1 → 2.116.3

package/templates/default/locales/en/.mustflow/skills/modal-loop-reentrancy-review/references/nested-modal-state-lifetime-checklist.md

@@ -0,0 +1,297 @@
+# Nested Modal State and Lifetime Checklist
+
+Use this checklist when a modal or secondary event loop can mutate the caller, owner, collection,
+input generation, completion path, or destruction schedule before the blocking API returns.
+
+## Contents
+
+1. [Execution model](#execution-model)
+2. [Session admission](#session-admission)
+3. [Invariant snapshot](#invariant-snapshot)
+4. [Non-user reentry](#non-user-reentry)
+5. [Object and collection lifetime](#object-and-collection-lifetime)
+6. [Completion and commit authority](#completion-and-commit-authority)
+7. [Nested ownership](#nested-ownership)
+8. [Focus, capture, and input generation](#focus-capture-and-input-generation)
+9. [Hidden, closed, and reused dialogs](#hidden-closed-and-reused-dialogs)
+10. [Deferred destruction and shutdown](#deferred-destruction-and-shutdown)
+11. [Async continuation ordering](#async-continuation-ordering)
+12. [Fault matrix](#fault-matrix)
+13. [Invariants](#invariants)
+14. [Skill handoffs](#skill-handoffs)
+
+## Execution model
+
+Keep these facts separate:
+
+- a blocking API can delay its caller's return while the same UI thread continues executing;
+- a nested loop is another dispatch frame on the same thread, not a new UI thread;
+- modality usually restricts user input to selected owners, not timers, IPC, automation, tray,
+  network, accessibility, callbacks or programmatic commands;
+- posted work can run inside the nested loop before the blocking call returns;
+- synchronous or nonqueued calls can bypass assumptions derived from posted-message FIFO;
+- active modes, contexts, priorities and filters decide which source classes make progress;
+- nested sessions form a depth stack and outer callers normally cannot resume through a live inner
+  session;
+- application shutdown and modal-session exit are separate protocols;
+- deferred destruction follows event-loop and framework rules, not lexical scope alone.
+
+Thread-affinity checks can all pass while the same logical state machine is active recursively.
+
+## Session admission
+
+Create modal session state before the first API that can pump or invoke callbacks:
+
+- session ID and generation;
+- parent session and modal depth;
+- owner ID and owner-lifecycle generation;
+- dialog or interaction ID;
+- loop object and session-specific exit token;
+- request state and completion authority;
+- owner-disable lease and capture snapshot;
+- input generation;
+- cancellation source and cleanup owner;
+- commit authority;
+- creation call site and expected result.
+
+A guard set after the blocking call returns provides no admission protection.
+
+Avoid one global `currentLoop`, `isModal` or `isBusy`. Nested sessions overwrite global identity
+and let an old completion close or mutate the wrong current session.
+
+## Invariant snapshot
+
+Before pumping:
+
+1. complete the current multi-field state transition or roll it back;
+2. publish one coherent snapshot;
+3. release application locks;
+4. stop holding mutable iterators and indexes;
+5. record stable entity IDs and expected revisions;
+6. mark the command session active;
+7. define which reentrant commands are coalesced, rejected or queued.
+
+Do not expose combinations such as new document state with old selection and undo history.
+
+If mutation must remain provisional, isolate it in a private draft that reentrant readers cannot
+mistake for committed state.
+
+## Non-user reentry
+
+Disabling the owner window does not block:
+
+- timers and idle callbacks;
+- queued signals and dispatcher work;
+- tray or menu callbacks;
+- automation and accessibility commands;
+- message-only or service windows;
+- IPC, COM, D-Bus or plugin callbacks;
+- background completion;
+- auto-save and synchronization;
+- programmatic command dispatch.
+
+Protect the domain command or request state, not only its button. Repeated save, delete, close,
+apply or submit intent must join, reject or idempotently observe the existing session.
+
+## Object and collection lifetime
+
+After nested dispatch, revalidate:
+
+- owner and dialog still exist;
+- weak reference resolves to the same lifecycle generation;
+- native peer or handle was not recreated;
+- parent, scene or visual-tree attachment is current;
+- entity still exists at the expected revision;
+- collection generation is unchanged;
+- iterator or index remains valid;
+- cancellation and terminal state still permit continuation.
+
+Prefer immutable collection snapshots or defer mutations until the outer frame is gone. A single
+thread prevents data races, not iterator invalidation or logical reentrancy.
+
+A blocking call's return is not proof that `this`, its parent, or captured raw pointers survived.
+
+## Completion and commit authority
+
+Route all terminal contenders through one operation:
+
+`TryComplete(sessionId, expectedGeneration, result)`
+
+Contenders can include:
+
+- user accept or cancel;
+- window close;
+- cancellation callback;
+- worker success or failure;
+- timeout;
+- owner disposal;
+- application shutdown;
+- provider or portal response.
+
+Only one wins. Losers are observable idempotent no-ops.
+
+Choose one model commit owner:
+
+- completion callback or signal commits; the synchronous return path only observes terminal state;
+  or
+- the synchronous return path commits; completion callbacks only stop the loop and store result.
+
+Never commit in both a finished callback and code after the blocking return.
+
+Cleanup belongs to one owner and is idempotent. Inner close callbacks and outer `finally` must not
+double-release native handles, registrations, subscriptions, owner-disable leases or cancellation
+resources.
+
+## Nested ownership
+
+Model owner disable, capture and session depth as owned resources.
+
+For each owner record which session actually disabled it. A session re-enables only the owner state
+it acquired. Nested dialogs must not wake a window still blocked by an outer session.
+
+A Boolean cannot represent multiple modal owners. Use framework ownership or explicit session leases
+or counts with identity.
+
+Bind loop exit to the exact session. A completion for outer A cannot terminate inner B merely because
+B is now the globally visible loop object.
+
+## Focus, capture, and input generation
+
+Modal creation can trigger capture cancellation, owner disable, activation, focus loss, validation,
+auto-save and close callbacks before construction or presentation finishes.
+
+Treat those callbacks as reentrant state transitions. Guard initialization and define which
+validation or save work can run during presentation.
+
+When modal entry or exit changes focus, capture, enabled windows or visual targets:
+
+- increment or transfer input generation;
+- cancel active gestures when required;
+- reject deferred input from the prior generation;
+- separate activation click from command activation;
+- process dialog navigation keys exactly once;
+- do not replay input deferred by filters into an unrelated post-modal target.
+
+Input disappearing during the modal and stale input applying after it closes are two sides of the
+same ownership error.
+
+## Hidden, closed, and reused dialogs
+
+Define lifecycle states explicitly:
+
+- constructed;
+- presenting;
+- visible;
+- hidden with reusable state;
+- closing;
+- closed or disposed;
+- destroyed.
+
+A framework may hide a modal instance rather than destroy it. Reuse requires:
+
+- new display-session generation;
+- reset result and request state;
+- fresh cancellation ownership;
+- cleared or deliberately retained fields;
+- subscription dedupe;
+- no old worker or progress producer;
+- new input and owner generation;
+- stale callback rejection.
+
+Object equality does not distinguish two presentations of the same instance.
+
+## Deferred destruction and shutdown
+
+Do not infer exact destruction time from a deferred-delete API name. Record:
+
+- which loop or context accepted the delete;
+- current nested depth;
+- when control returns to the owning loop;
+- whether deeper loops can trigger earlier processing;
+- weak-reference invalidation;
+- cleanup and completion ordering.
+
+Shutdown must preserve both protocols:
+
+- session-specific loops receive their own exit or cancellation;
+- outer application quit remains visible to the owning main loop;
+- dialogs and owners are not destroyed before local requests terminate;
+- manual loops do not swallow global shutdown;
+- callbacks arriving during shutdown observe terminal generations.
+
+A general quit signal is not a substitute for dialog result completion.
+
+## Async continuation ordering
+
+Task, future, promise or queued completion does not imply another thread. The continuation may run
+inside the nested loop before code after the blocking call.
+
+Do not use blocking source order as an async fence:
+
+`post work -> show modal -> code after modal`
+
+The posted work may execute during the modal. Record causal request and session state explicitly.
+
+Avoid sync-over-async waits. Spinning a secondary loop until a task completes trades deadlock for
+full UI reentrancy.
+
+For progress streams:
+
+- keep only latest current-session value;
+- cap update rate and queue age;
+- invalidate progress at terminal completion;
+- preserve boundary states;
+- reject old-session updates after reuse;
+- ensure the final result cannot be followed by stale progress.
+
+## Fault matrix
+
+Cover applicable schedules:
+
+| Schedule or fault | Required result |
+| --- | --- |
+| same command reenters before guard assignment | admission occurs before pumping |
+| inner callback reads half-updated model | only coherent state is visible |
+| timer or IPC repeats disabled-button command | domain request rejects or joins |
+| owner deletes itself during nested loop | post-return continuation rejects weak generation |
+| collection mutates during outer iteration | snapshot or generation guard prevents invalid access |
+| signal and return path both observe accept | model commits once |
+| cancel and success race | one TryComplete winner |
+| nested B closes while A remains | owner stays disabled for A |
+| old completion exits current loop | session token rejects it |
+| focus callback fires during dialog construction | initialization invariant holds |
+| modal hides rather than destroys | next presentation receives new generation |
+| inner cleanup and outer finally both run | cleanup remains idempotent |
+| deferred delete runs at surprising depth | weak lifetime guard prevents access |
+| global shutdown occurs inside modal | inner and outer protocols both terminate correctly |
+| queued click survives filtered modal input | old input generation cannot affect new target |
+| continuation runs before modal return | explicit state permits it |
+| progress floods the nested loop | input, render and terminal state retain bounded progress |
+
+## Invariants
+
+Choose applicable executable invariants:
+
+- session admission precedes every pumping API;
+- no partial application invariant or lock crosses nested dispatch;
+- one logical command has one active session or explicit duplicate policy;
+- every loop exit token closes only its session;
+- every modal result commits at most once;
+- every owned disable, capture and cleanup resource releases exactly once by its owner;
+- caller, owner and collection generations are validated after nested return;
+- hidden dialog reuse cannot accept old-session callbacks;
+- deferred destruction cannot leave a usable strong pointer in resumed outer code;
+- old input generation cannot execute against the post-modal target;
+- progress cannot follow terminal state;
+- shutdown cannot lose either inner session exit or outer application quit.
+
+## Skill handoffs
+
+- Use `ui-dispatch-lifecycle-review` for stale queued callbacks, view epochs, close state and progress
+  when no nested loop is primary.
+- Use `input-event-synchronization-review` for capture, gesture and input-generation semantics.
+- Use `idempotency-integrity-review` when repeated modal commands have durable side effects.
+- Use `race-condition-review` for parallel interleavings beyond single-thread reentrancy.
+- Use `state-machine-pattern` to implement modal session and completion transitions.
+- Use `memory-lifetime-review` when raw pointers, native handles or use-after-free dominate.
+

package/templates/default/locales/en/.mustflow/skills/name-resolution-integrity-review/SKILL.md

@@ -0,0 +1,252 @@
+---
+mustflow_doc: skill.name-resolution-integrity-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: name-resolution-integrity-review
+description: Apply this skill when the same name, hostname, variable, function, type, module, package, class, repository label, dependency coordinate, or import resolves differently by process, execution space, resolver API, scope, namespace, lookup phase, search path, route, condition, variant, loader, proxy, cache, or platform; including NSS status actions, split DNS, recursive versus authoritative DNS, delegation or glue, DoH, search suffixes, proxy-side DNS, negative caching, address selection, connection reuse, language shadowing or delayed lookup, macro hygiene, conditional exports, duplicate module instances, class-loader identity, peer contexts, package-manager resolution, build-system variants, and stale resolver caches.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.name-resolution-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Name Resolution Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Diagnose name-resolution defects as disagreements about the resolver, context, candidate graph,
+precedence, cache, and resulting identity rather than as spelling mistakes.
+
+For every disputed name, trace:
+
+`requester -> execution space -> input form -> candidate expansion -> search or routing graph ->
+filters and precedence -> cache layer -> selected result -> loaded or contacted identity`
+
+Keep successful lookup, selected identity, reachability, compatibility, authorization, and usable
+behavior as separate claims. A name can resolve successfully to the wrong object, or resolve to the
+right object and fail at the next boundary.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A hostname works in one application, shell, container, VPN, proxy mode, browser, network namespace,
+  or resolver but fails or selects another address in a different one.
+- Resolver APIs, NSS status actions, split DNS, route-only domains, search suffixes, absolute names,
+  mDNS or LLMNR, hosts files, recursive or authoritative DNS, delegation, glue, DoH, DNSSEC, DNS64,
+  CDN selection, negative caching, address racing, connection pools, stale answers, or proxy-side
+  resolution is involved.
+- A variable, function, type, macro, label, extension method, overload, import, or module changes
+  meaning because of scope, namespace, shadowing, hygiene, lookup phase, or candidate precedence.
+- A module or package name maps to a different physical file, export condition, peer context,
+  feature set, variant, class loader, workspace replacement, repository mapping, or cache entry.
+- A lockfile, dependency coordinate, source spelling, or direct DNS query appears correct but does
+  not prove the identity used by the failing process.
+- A resolver, loader, package manager, build system, compiler, interpreter, proxy, browser, or runtime
+  needs evidence that explains both the selected result and rejected candidates.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The incident boundary is still unknown and name resolution is only one of many hypotheses; use
+  `incident-triage-review` first and this skill after resolver evidence appears.
+- The task changes parser grammar, tokens, CST, or syntax recovery without binding or lookup changes;
+  use `parser-engineering-review`.
+- The task changes compiler or interpreter semantics beyond binding, lookup, scope, module identity,
+  or resolver caching; use `compiler-engineering-review` or `interpreter-engineering-review` as owner.
+- The task adds, upgrades, removes, audits, or approves a dependency rather than diagnosing how an
+  existing coordinate resolves; use `dependency-reality-check` or `dependency-upgrade-review`.
+- The task changes architecture import direction or public package boundaries without a disputed
+  resolver result; use `module-boundary-review`.
+- The task concerns linker symbol selection, mangling, relocation, or loader-visible binary symbols;
+  use `compiler-engineering-review`.
+- The task concerns path containment, symlink traversal, file identity, SSRF rebinding, or remote-file
+  authorization as the primary security boundary; use the matching filesystem, SSRF, or upload skill.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Exact original spelling, normalized spelling, absolute or qualified form, namespace or record kind,
+  and every generated candidate actually considered.
+- Requester identity: process, executable, runtime, source location, module, class loader, thread or
+  task context, user, container, pod, network namespace, working directory, and environment.
+- Resolver identity and mode: application or runtime API, implementation, build mode, platform,
+  configuration source, name-service modules and status actions, lookup phase, active conditions,
+  search roots, routing domains, server-selection state, precedence, fallback, and policy overlays.
+- Resolution trace: candidate order, candidate origin, acceptance tests, rejection reasons, selected
+  result, stop condition, fallback, and error taxonomy.
+- Identity evidence after resolution: canonical path or realpath, package and version, export target,
+  peer or feature context, loader identity, module cache key, address family, DNS answer source,
+  selected and actually contacted endpoint, connection generation or reuse state, or other
+  domain-specific object identity.
+- Cache ledger: layer owner, key, positive or negative value, freshness or TTL, invalidation event,
+  stale-serving policy, process lifetime, and whether the failing request hit or bypassed it.
+- Comparison evidence from the failing execution space and a controlled working space, captured before
+  configuration changes, cache flushes, restarts, reinstalls, or clean builds erase the difference.
+- Expected resolution contract, supported platform or language semantics, compatibility window,
+  deterministic oracle, and exact failure class.
+- Configured command intents for the selected repository.
+
+Read [DNS and Network Resolution Checklist](references/dns-network-resolution-checklist.md) when
+hostnames, split DNS, VPNs, proxies, containers, DNSSEC, transport, CDN answers, or resolver caches are
+in scope.
+
+Read [Language and Symbol Resolution Checklist](references/language-symbol-resolution-checklist.md)
+when lexical binding, shadowing, overload lookup, namespaces, macros, extension methods, generated
+code, or language lookup phases are in scope.
+
+Read [Module, Package, and Loader Resolution Checklist](references/module-package-loader-resolution-checklist.md)
+when imports, package exports, module instances, class loaders, package-manager graphs, build variants,
+workspace mappings, feature unification, or build-system search caches are in scope.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the exclusions.
+- The failing requester and execution space are identified, or the result is explicitly limited to a
+  hypothesis about another environment.
+- Repository instructions and configured command intents have been checked.
+- External command recipes are treated as manual evidence ideas, not command authority.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add bounded resolver tracing, structured resolution diagnostics, provenance fields, cache-key
+  visibility, candidate and rejection evidence, and directly related tests or runbook guidance.
+- Fix lookup configuration, explicit qualification, import aliases, resolver conditions, loader
+  ownership, cache invalidation, package declarations, or generated-code names when current evidence
+  proves that surface owns the mismatch.
+- Add positive and negative fixtures that vary one resolver dimension at a time.
+- Do not flush caches, reinstall dependencies, delete build directories, restart services, disable
+  validation, rewrite network policy, or change global resolver settings before preserving evidence.
+- Do not add raw diagnostic commands to the skill or claim this procedure authorizes live systems,
+  production packet capture, tracing, namespace entry, dependency installation, or cache deletion.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. State the resolution claim precisely. Name the requester, original input, expected object, actual
+   object or error, execution space, and observation time. Separate not found, ambiguous, forbidden,
+   invalid, stale, incompatible, unreachable, and wrong-identity outcomes.
+2. Reproduce from the failing boundary before changing it. Preserve resolver configuration, search
+   roots, environment, route state, active conditions, loader identity, caches visible without
+   mutation, and actual selected object. A host-shell success is not container or application proof.
+3. Build a resolution ledger. For each stage, record input, actor, namespace, phase, candidate set,
+   ordering rule, filter, cache, output, and stop reason. Do not jump from source spelling directly to
+   final behavior.
+4. Distinguish four identities:
+   - textual identity: the spelling or coordinate supplied;
+   - resolved identity: the selected path, symbol, address, variant, or definition;
+   - loaded identity: the module instance, class loader, process object, or runtime endpoint used;
+   - behavioral identity: the API, state, route, or service behavior actually observed.
+5. Enumerate candidates before choosing a fix. Include expanded search-suffix names, lexical scopes,
+   associated namespaces, import roots, conditional exports, peer contexts, variants, repositories,
+   aliases, mappings, and fallbacks. Record rejected candidates and reasons, not only the winner.
+6. Make precedence executable or observable. Test one controlled perturbation at a time: qualification,
+   search-root order, route specificity, import mode, loader, active condition, feature, variant,
+   working directory, or cache bypass. Preserve all other dimensions.
+7. Treat cache as part of semantics. Locate positive, negative, failure, compiled-code, module,
+   package, build, resolver, proxy, and browser caches. Capture key, owner, value, age, and provenance
+   before considering invalidation. A restart that fixes the symptom without naming the stale layer
+   has not localized the defect.
+8. Compare like with like. The control and failing probes must use the same requester class, execution
+   space, name form, query or namespace kind, resolver path, active options, credentials, and time
+   window unless one of those is the isolated variable.
+9. Prove the selected result independently. For files and modules, record canonical origin and loader
+   or cache identity. For language symbols, record declaration and lookup phase. For DNS, record the
+   actual resolver API, QNAME, record kind, response source, recursive and authoritative boundary,
+   flags, TTL, route, candidate address set, and address selected by the client.
+10. Continue one boundary beyond resolution. Verify the endpoint actually contacted, whether a prior
+    connection or pool entry bypassed fresh lookup, route, TLS or protocol authority identity,
+    authorization, initialization state, and type or API compatibility as applicable. Do not relabel
+    a post-resolution or connection-reuse failure as lookup failure.
+11. Add structured observability at the narrowest stable boundary. Prefer low-cardinality reason codes,
+    resolver mode, selected origin, candidate count, cache status, and stable identity fingerprints.
+    Redact private names, paths, addresses, search domains, and user-controlled text.
+12. Convert the defect into a differential fixture. Vary the proven trigger while keeping the expected
+    selected identity and rejection reasons explicit. Include the wrong-but-successful resolution case,
+    not only lookup failure.
+13. Hand off ownership after localization:
+    - DNS or network resolver implementation and runbooks to the relevant operations or incident skill;
+    - language binding semantics to compiler or interpreter engineering;
+    - package declarations and supported dependency contracts to `dependency-reality-check`;
+    - architecture import direction to `module-boundary-review`;
+    - cache behavior to `cache-integrity-review`;
+    - security-sensitive rebinding or traversal to the matching security skill.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The failing requester, execution space, resolver API and path, input form, namespace, phase,
+  candidate order, cache layer, selected result, actual connection identity, and final loaded or
+  contacted identity are explicit.
+- Success, wrong identity, ambiguity, policy rejection, stale result, incompatibility, reachability,
+  and downstream behavior remain distinct outcomes.
+- The first divergent resolver stage is identified or the missing trace boundary is reported.
+- Evidence was preserved before destructive cache, dependency, build, or network resets.
+- Any fix is tied to the stage that owns the wrong candidate, precedence, identity, or stale cache.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer narrow configured resolver, module, package, compiler, interpreter, container, DNS, network,
+cache, or runbook checks. Do not infer raw lookup, tracing, packet-capture, namespace, package-manager,
+build-system, browser, or cache-flush commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If only a direct resolver probe succeeds, report that boundary; do not claim the application path.
+- If the failing process cannot be inspected, preserve the environmental delta and mark resolver,
+  cache, and loaded identity as unverified.
+- If a cache flush or restart already erased the state, reproduce under a controlled fixture or report
+  the missing pre-reset evidence instead of declaring the cache guilty.
+- If multiple dimensions differ, reduce them one at a time; do not select a cause from a bundle of
+  changed environment, resolver, path, loader, and cache state.
+- If the name resolves correctly but the object is unreachable, incompatible, unauthorized, or
+  misconfigured, hand off at that next boundary and retain the successful resolution evidence.
+- If required live diagnostics are manual-only or unconfigured, stop at a repository-owned evidence
+  plan and report the missing execution proof.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Resolution claim and exact failure class
+- Requester and execution-space capsule
+- Original, normalized, expanded, qualified, and selected names
+- Resolver API, stages, namespaces, phases, candidate order, filters, and rejection reasons
+- Cache layers, keys, freshness, negative or stale state, and invalidation evidence
+- Resolved, selected-address, connection-reuse, loaded, and behavioral identity evidence
+- First divergent stage and owning skill or subsystem
+- Files changed
+- Configured command intents run
+- Skipped or manual-only resolver checks
+- Remaining identity, cache, environment, or downstream-boundary risk