mustflow 2.112.10 → 2.112.14

package/templates/default/locales/en/.mustflow/skills/concurrency-invariant-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.concurrency-invariant-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: concurrency-invariant-review
@@ -59,6 +59,7 @@ The review question is not "is the code correct in this order?" The stronger que
 - Invariant: the business or data fact that must remain true across multiple fields, rows, messages, callbacks, operations, or lifecycle states.
 - Time-order points: `await`, I/O, DB calls, callbacks, event listeners, plugin hooks, logging, metrics, lock release, condition wait, notify, retry, timeout, queue ack, scheduler tick, cancellation, shutdown, close, send, and publication.
 - Synchronization evidence: exact lock identity, lock order, condition predicate, atomic memory-ordering story, transaction isolation, row lock, unique constraint, fencing token, idempotency record, queue dedupe, or deterministic test harness.
+- Failure evidence for timing bugs: incident file, wait-for graph, lock-order graph, happens-before handoff logs, generation counters, pool saturation, and configured or manual sanitizer, detector, record/replay, profiler, or kernel-tracing evidence when available.
 - Runtime and deployment shape: single thread, worker pool, process pool, multi-instance service, distributed cache, database, queue, scheduler, coroutine runtime, or reactive runtime.
 
 <!-- mustflow-section: preconditions -->
@@ -102,9 +103,11 @@ The review question is not "is the code correct in this order?" The stronger que
    - Record nested acquisition order such as `account lock -> ledger lock -> notification lock`.
    - Reject paths that acquire the same pair in reverse order unless the runtime and lock type make that impossible.
    - Check reentrant callbacks and external code called under a lock for hidden reacquisition.
+   - When local instrumentation exists, prefer a runtime lock-order graph that records edges from already-held locks to newly acquired locks and fails on cycles.
 7. Check condition variables and notifications by state, not signal.
     - A condition variable wait should be inside a loop that rechecks the predicate.
     - The loop must tolerate spurious wakeup, another waiter consuming the work first, and notifications that arrive before this worker starts waiting.
+    - Prefer generation counters or versioned predicates when the same event can be missed, duplicated, delayed, or consumed by another waiter.
     - `notify` and state changes should happen under the same synchronization boundary.
     - A lost notification is possible when code trusts the signal instead of a persistent state predicate.
 8. Check atomics, memory visibility, and CAS.
@@ -136,21 +139,27 @@ The review question is not "is the code correct in this order?" The stronger que
     - Shutdown should define stop-accepting, drain, cancel, flush, close, and in-flight side-effect ownership.
     - `closed = true` is not enough if futures, workers, sockets, buffers, queues, or async continuations keep running.
     - Mutexes, semaphores, read-write locks, connection checkouts, rate-limit tokens, and permits must release on every exception path.
-15. Check thread-local and async context.
+15. Check deadlocks and starvation as wait-for systems.
+    - A thread stack dump alone is not enough. Build a wait-for graph that connects threads, locks, condition variables, futures, queues, pool workers, callbacks, and external waits.
+    - Separate lock-order deadlock, lost notification, callback reentry, sync-over-async, and thread-pool starvation; a saturated pool can freeze progress without any mutex cycle.
+    - Record executor queue length, active worker count, blocked worker count, work-stealing or scheduler state, and blocking waits inside worker pools when local evidence exists.
+16. Check thread-local and async context.
     - Thread-local context is hidden global state in thread pools.
     - Clear request, tenant, auth, transaction, and locale context before the thread is reused.
     - Async, coroutine, virtual-thread, and reactive runtimes can break assumptions that thread-local state follows logical work.
     - Treat every `await` as a point where the world can change before the continuation resumes.
-16. Check concurrency tests as evidence, not decoration.
+17. Check concurrency tests as evidence, not decoration.
     - `Thread.sleep(100)` is not deterministic proof.
     - Prefer barriers, latches, fake schedulers, deterministic executors, controlled promises, transactional fixtures, version assertions, queue dedupe fixtures, and explicit interleaving tests.
     - Use stress or repeated tests only as supplementary evidence when deterministic ordering is unavailable.
+    - Treat sanitizer, detector, model-checker, record/replay, profiler, and kernel-scheduler diagnostics as configured or manual evidence only; report them when useful but unavailable.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Shared state, owners, invariants, and time-order points are named or missing evidence is reported.
 - Locks, atomics, conditions, transactions, distributed leases, queues, schedulers, shutdown, thread-local context, async yields, collections, caches, and tests are checked where relevant.
+- Deadlock, starvation, lost-notification, and lock-order claims are backed by wait-for, lock-order, generation, pool, or configured/manual diagnostic evidence when relevant.
 - The chosen fix or recommendation preserves the whole invariant, not just one field or one method call.
 - Deterministic evidence covers the highest-risk interleaving when the repository has a configured way to exercise it.
 
@@ -186,6 +195,7 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 - Invariant and time-order table reviewed
 - Check-then-act and read-modify-write findings
 - Lock identity, lock scope, lock order, condition variable, atomics, memory visibility, CAS ABA, publication, immutability, collections, cache, database, distributed lock, idempotency, queue duplicate, state transition, scheduler, shutdown, resource release, thread-local, async `await`, and test-evidence checks where relevant
+- Wait-for graph, lock-order graph, generation counter, pool-starvation, and configured/manual diagnostic evidence where relevant
 - Concurrency fixes made or recommended
 - Tests or verification evidence
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/cross-platform-filesystem-safety/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.cross-platform-filesystem-safety
 locale: en
 canonical: true
-revision: 6
+revision: 7
 lifecycle: mustflow-owned
 authority: procedure
 name: cross-platform-filesystem-safety
-description: Apply this skill when file paths, directories, symlinks, reparse points, real paths, path traversal, reserved names, null bytes, atomic file writes, temporary files, file copies, generated outputs, clone or checkout materialization, Windows/POSIX path behavior, line endings, file permissions, durable writes, failure classification, or filesystem cleanup are created, changed, reviewed, or reported.
+description: Apply this skill when file paths, directories, symlinks, reparse points, real paths, path traversal, reserved names, null bytes, NTFS alternate data streams, Windows 8.3 short names, Windows namespace prefixes, atomic file writes, temporary files, file copies, generated outputs, clone or checkout materialization, Windows/POSIX path behavior, line endings, file permissions, durable writes, failure classification, or filesystem cleanup are created, changed, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -35,6 +35,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 - A change handles user-provided paths, repository-relative paths, real paths, symlinks, Windows reparse points or junctions, temporary files, generated output, backups, manifests, locks, caches, or latest pointers.
 - Code materializes large or externally sourced trees such as Git checkouts, cloned repositories, project scaffolds, dependency trees, archive extractions, template installs, generated snapshots, or package artifacts.
 - Behavior must work on Windows and POSIX path separators, drive roots, case differences, reserved names, maximum path lengths, executable extensions, line endings, permissions, or rename semantics.
+- Code or config serves files to a browser, preview server, dev server, test UI, static asset server, attachment endpoint, snapshot endpoint, or package artifact where a denied path, filename alias, or platform-specific path form could expose private files.
 - A test or final report claims a path is inside the project, symlink-safe, traversal-safe, race-safe, atomic, idempotent, cleanup-safe, or cross-platform.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -49,7 +50,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 
 - Affected path inputs, output paths, base directory, trust boundary, and whether each path is user-controlled, template-controlled, generated, or repository-owned.
 - Current filesystem helpers, path validation rules, symlink policy, case-sensitivity policy, write strategy, cleanup strategy, temporary-file strategy, permission strategy, and platform expectations.
-- Expected behavior for missing paths, existing files, directories, symlinks, dangling symlinks, reparse points or junctions, path traversal, null bytes, Windows namespace prefixes, Windows reserved names, alternate data streams, trailing spaces or dots, collisions, long paths, large files, and permissions errors.
+- Expected behavior for missing paths, existing files, directories, symlinks, dangling symlinks, reparse points or junctions, path traversal, null bytes, Windows namespace prefixes, Windows reserved names, NTFS alternate data streams, Windows 8.3 short names, trailing spaces or dots, collisions, long paths, large files, and permissions errors.
 - Path-length, filename-length, collision, staging, promotion, and cleanup expectations for clone, checkout, scaffold, install, archive, and generated-tree flows, including the deepest known entry path when available.
 - Failure classification expectations for filesystem and platform errors such as Windows path length, POSIX `ENAMETOOLONG`, reserved names, case collisions, Unicode aliases, file locks, permissions, quota, cross-device moves, missing executable bits, line endings, watcher limits, and descriptor limits.
 - Whether atomicity requires best-effort rename, same-directory temporary files on the same volume, file fsync, parent directory fsync, Windows replacement behavior, or reader-safe latest pointers.
@@ -69,7 +70,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 - Prefer repository-local safe helpers over ad hoc path string checks.
 - Do not rely on string prefix checks alone when symlinks, drive roots, or real paths matter.
 - Do not lowercase paths as a universal containment strategy. Case-insensitive comparison may be appropriate for a specific platform boundary, but it must not collapse distinct POSIX paths or replace real containment checks.
-- Do not accept null bytes, Windows device names, namespace bypass prefixes, alternate data streams, or platform-invalid path segments as ordinary filenames.
+- Do not accept null bytes, Windows device names, namespace bypass prefixes, alternate data streams, 8.3 short-name aliases, or platform-invalid path segments as ordinary filenames.
 - Do not recursively delete, overwrite, or copy broad directories unless the target is resolved, bounded, and intentionally owned by the task.
 - Do not claim operating-system mitigations such as Windows RedirectionGuard unless the application actually enables and verifies the mitigation in the relevant process boundary.
 - Do not change system-wide or user-wide settings such as Windows registry long-path flags, global Git config, Developer Mode, WSL mount metadata, Linux sysctl limits, Docker Desktop storage backends, antivirus exclusions, or shell profile files from this skill. Report the missing prerequisite or require an explicit configured setup command.
@@ -78,7 +79,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 ## Procedure
 
 1. Classify each path as trusted repository path, user input, generated state, template source, package artifact, temporary file, external path, or unknown.
-2. Reject impossible or dangerous path text early. Check null bytes, empty segments, absolute paths where relative paths are required, Windows device names such as `CON` or `NUL`, namespace prefixes such as `\\?\`, alternate data streams using colon segments, trailing dots or spaces when Windows compatibility matters, and platform-invalid characters before writing.
+2. Reject impossible or dangerous path text early. Check null bytes, empty segments, absolute paths where relative paths are required, Windows device names such as `CON` or `NUL`, namespace prefixes such as `\\?\`, alternate data streams using colon segments, 8.3 short-name aliases such as generated `PROGRA~1`-style names, trailing dots or spaces when Windows compatibility matters, and platform-invalid characters before writing.
 3. Establish the base boundary. Use normalized repository-relative paths for storage and real-path checks for filesystem safety when symlinks may be present.
 4. Use Unicode normalization for validation only when detecting platform aliases such as superscript Windows device-name variants. Do not rewrite or persist normalized filenames unless the repository policy explicitly says so.
 5. For externally sourced trees, use a `preflight -> dangerous operation -> classifier -> safe cleanup` pipeline. Estimate the materialized path budget before writing, including destination root, project directory, generated subdirectories, deepest known repository or archive entry, Windows path-length behavior, POSIX path and component limits, byte limits, case collisions, reserved names, and safety headroom.
@@ -86,13 +87,13 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 7. For Windows Git checkout or clone materialization, prefer a per-invocation `core.longpaths=true` setting when product code invokes Git. Do not mutate global Git config from application code unless the user explicitly chose that setup action. Long-path support still depends on operating-system, Git, filesystem, and downstream tool behavior, so checkout failures must remain classifiable.
 8. For symlink-heavy repositories on Windows, detect whether checkout produced real links or plain-text symlink stubs before running build logic. Report missing Developer Mode, `core.symlinks`, or native symlink support as an environment prerequisite; do not silently replace file symlinks with junctions or copies unless the repository contract explicitly supports that compatibility mode.
 9. For POSIX, do not assume that forward slashes make paths safe. Check `ENAMETOOLONG`, byte-based per-component name limits, mount permissions, executable bits, case-sensitive import paths, symlink loops, file descriptor limits, watcher limits, quota, and cross-device rename behavior.
-10. Check containment with path-aware logic. Prefer relative-path or resolved-path containment helpers over raw string prefixes, and include a path-separator boundary so partial path traversal cannot let sibling names masquerade as children.
+10. Check containment with path-aware logic. Prefer relative-path or resolved-path containment helpers over raw string prefixes, and include a path-separator boundary so partial path traversal cannot let sibling names masquerade as children. Apply deny rules to the same canonical path form that will be opened, not to a raw URL or display path that the operating system may reinterpret.
 11. Check case behavior explicitly. Windows and many macOS volumes preserve case but compare case-insensitively by default; POSIX commonly compares case-sensitively. State whether the code preserves spelling, rejects conflicting names, or relies on the host filesystem.
 12. Check collisions before materializing Git trees, archives, generated files, uploaded names, or dependency trees. Include case-only collisions, Unicode normalization aliases, reserved Windows names with extensions, trailing dot or space aliases, duplicate archive entries, and byte-limit collisions from multibyte names.
 13. Check symlink, reparse point, and junction behavior explicitly. Decide whether they are rejected, followed only within the root, or treated as ordinary path entries. Test dangling, outside-target, loop, text-stub, and junction-like cases when relevant.
 14. Close time-of-check to time-of-use gaps where practical. Prefer opening or writing through safe helpers that reject symlinks at the final operation, then verify the opened target when the platform and helper support it.
 15. Treat high-level path APIs as incomplete defenses when the runtime cannot expose descriptor-relative open, no-follow, or opened-file verification. Do not claim race-free behavior from resolve-then-open code alone.
-16. Check traversal and root handling across platforms. Account for absolute paths, drive letters, UNC-like paths, mixed separators, empty paths, dot segments, reserved names, long paths, and case sensitivity where relevant.
+16. Check traversal and root handling across platforms. Account for absolute paths, drive letters, UNC-like paths, mixed separators, empty paths, dot segments, reserved names, long paths, case sensitivity, NTFS alternate data streams, 8.3 short names, and Windows namespace prefixes where relevant.
 17. Classify filesystem failures before generic network, auth, or unknown failures. Use stable categories such as `path_too_long`, `filename_too_long`, `byte_limit_exceeded`, `invalid_path`, `reserved_name`, `case_collision`, `unicode_collision`, `symlink_escape`, `permission_denied`, `file_locked`, `cross_device_move`, `disk_full_or_quota`, `executable_bit_missing`, `line_ending_mismatch`, `watcher_limit`, and `descriptor_limit`.
 18. For writes, prefer same-directory temporary-file then rename or replace behavior when readers may observe the file. Keep the temporary file on the same volume, use unpredictable names, least-privilege creation permissions, and safe no-follow writes when the project already has that helper.
 19. Treat atomic writes as platform-specific. POSIX rename semantics, Windows replacement behavior, cross-filesystem moves, network filesystems, fsync availability, and directory fsync support differ; report best-effort guarantees honestly.
@@ -136,7 +137,7 @@ Use release checks when template files, package artifacts, or installed workflow
 - If root containment is unclear, stop before writing or deleting and report the ambiguous path owner.
 - If the platform cannot prove symlink-safe behavior, fail closed or document the exact remaining gap.
 - If atomic replace, file fsync, parent directory fsync, no-follow open, or final-target verification is not available on the platform, downgrade the claim to best-effort and keep the write boundary narrow.
-- If Unicode normalization, Windows namespace prefixes, alternate data streams, or reparse points could change the effective target, fail closed or report the exact unhandled path class.
+- If Unicode normalization, Windows namespace prefixes, alternate data streams, 8.3 short names, or reparse points could change the effective target, fail closed or report the exact unhandled path class.
 - If clone, checkout, scaffold, install, extraction, or generated-tree materialization fails, classify filesystem and platform causes before reporting network, token, auth, dependency, or unknown causes.
 - If a fix requires elevated host settings or global user configuration, stop at a clear prerequisite report unless an explicit configured command intent and user request authorize the setup.
 - If a test depends on platform-specific symlink support or permissions, state the platform boundary and keep assertions narrow.
@@ -147,7 +148,7 @@ Use release checks when template files, package artifacts, or installed workflow
 
 - Filesystem surface reviewed
 - Path trust classes, invalid-name handling, case policy, and root boundary
-- Null byte, reserved-name, Unicode normalization, namespace prefix, alternate data stream, symlink, reparse-point, traversal, race, atomic write, durability, permission, copy, delete, scan, and cleanup decisions
+- Null byte, reserved-name, Unicode normalization, namespace prefix, alternate data stream, 8.3 short-name, symlink, reparse-point, traversal, race, atomic write, durability, permission, copy, delete, scan, and cleanup decisions
 - Clone, checkout, scaffold, install, extraction, preflight, staging, promotion, path-length, collision, failure-taxonomy, and diagnostic-preservation decisions
 - Host-setting prerequisites reported or deferred
 - Windows/POSIX assumptions and skipped platform checks

package/templates/default/locales/en/.mustflow/skills/dependency-upgrade-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.dependency-upgrade-review
 locale: en
 canonical: true
-revision: 5
+revision: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: dependency-upgrade-review
-description: Apply this skill when dependency versions, lockfiles, package manager metadata, security advisory fixes, generated dependency outputs, runtime engine constraints, Python runtime support, peer dependency contracts, framework plugins, TypeScript compiler tracks, CI actions, Docker base images, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported.
+description: Apply this skill when dependency versions, lockfiles, package manager metadata, security advisory fixes, vulnerability scanner alerts, generated dependency outputs, runtime engine constraints, Python runtime support, peer dependency contracts, framework plugins, dev servers, test runners, TypeScript compiler tracks, CI actions, Docker base images, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -56,6 +56,7 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 - Ecosystem and package manager: JavaScript or TypeScript, Python, Go, Rust, JVM, .NET, Ruby, PHP, Swift, Docker, CI actions, or another declared system.
 - Package declarations, lockfiles, workspace files, runtime-version files, package-manager config, toolchain files, CI/Docker files, generated outputs, and command contract entries.
 - Release notes, migration notes, changelog, advisory range, fixed range, compatibility notes, or local issue evidence when available from approved context.
+- Advisory exploit preconditions, including operating system, host binding, public network exposure, dev-server mode, privileged UI/API flags, protocol peer role, unauthenticated reachability, and whether the affected package runs in production, CI, development, containers, or remote workspaces.
 - Impacted runtime paths, build paths, test paths, generated clients, mocks, fixtures, docs examples, deployment images, and package publish output.
 
 <!-- mustflow-section: preconditions -->
@@ -93,9 +94,11 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 8. For security upgrades, keep the patch narrow. Identify advisory id, affected range, fixed range, direct or transitive path, exploit-relevant code path, minimum patched version, scanner recheck, and whether stricter validation, escaping, TLS, redirect, auth, or parser behavior can break callers.
    - For lockfile-only or transitive vulnerability alerts, do not treat the lockfile line as the root cause. Trace the vulnerable package back to the direct dependency or framework plugin that resolves it, then update the narrowest parent version, override, or package-manager resolution that satisfies the fixed range.
    - After regenerating the lockfile, confirm the old vulnerable version is absent from the resolved graph and that any override is recorded in the manifest rather than hidden as unexplained lockfile churn.
+   - For devDependency advisories, decide whether the affected tool ever binds to a non-localhost host, runs in a container with published ports, serves worktree files, exposes a browser or test UI, accepts remote API tokens, writes source or snapshot files, reruns tests, or executes project code. A devDependency can still be security-sensitive when it is reachable from another machine or CI/preview surface.
+   - For protocol and crypto dependency advisories, classify whether the package acts as client, server, agent, parser, verifier, or keyring. Check unauthenticated reachability, panic or assertion behavior, attacker-controlled key sizes, packet or frame ordering, unsolicited responses, and resource exhaustion before reducing the finding to "DoS only".
 9. Review the lockfile as a graph, not a blob. Check direct and transitive replacements, newly introduced packages, removed packages, optional/platform packages, source URLs, integrity or checksum changes, peer resolution, engine requirements, native prebuilds, and postinstall or lifecycle scripts.
 10. Review runtime boundaries that dependency upgrades commonly break: ESM/CJS and package `type`, `exports` and conditional exports, browser/node/edge conditions, Node engine support, Python dependency markers and extras, Go module path changes, Cargo feature unification, native builds, SSR/client split, WebView/native split, and generated client or SDK types.
-11. Treat framework, plugin, code generator, formatter, linter, bundler, ORM, protobuf, OpenAPI, GraphQL, database driver, and test-runner upgrades as behavior changes when their output, config schema, plugin API, CLI flags, or generated code can change.
+11. Treat framework, plugin, code generator, formatter, linter, bundler, ORM, protobuf, OpenAPI, GraphQL, database driver, dev-server, browser-test, and test-runner upgrades as behavior changes when their output, config schema, plugin API, CLI flags, file-serving policy, privileged UI gates, or generated code can change.
 12. For Python runtime upgrades, treat `requires-python`, CI matrices, base images, dependency markers, wheels, packaging output, standard-library API availability, and security-default changes as one compatibility contract. Review version-gated standard-library usage and changed defaults before assuming the upgrade is only a dependency resolution change.
 13. For Python upgrades that adopt newer standard-library behavior, call out affected paths such as archive extraction, subprocess handling, async lifecycle, import/resource loading, typing surfaces, data-class shapes, and diagnostic flags. Keep fallbacks or compatibility wording when the repository still supports older interpreters.
 14. For TypeScript upgrades, classify the compiler track explicitly: TS6 stable API track through `@typescript/typescript6` and `tsc6`, TS7 RC compiler track through `typescript@rc` and `tsc`, TS7 nightly track through `@typescript/native-preview` and `tsgo`, future TS7 stable track through the stable `typescript` package, editor extension preview, or framework-owned wrapper. Do not treat a nightly package as a stable replacement for the `typescript` package unless the repository policy says so.
@@ -116,6 +119,7 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 - Python runtime upgrades classify standard-library availability, changed defaults, packaging output, and security-behavior impact.
 - TypeScript compiler-track changes distinguish TS6 stable API compatibility, TS7 RC compiler verification, TS7 nightly comparison work, and future TS7 stable adoption.
 - Security fixes are narrow unless the user explicitly accepted a broader modernization.
+- Advisory exploit preconditions are checked against local scripts, config, CI, containers, remote workspaces, and docs before an alert is dismissed as development-only or unreachable.
 - Tests and scanners were not weakened to pass the upgrade.
 
 <!-- mustflow-section: verification -->
@@ -158,6 +162,7 @@ Prefer the narrowest configured intent that proves the actual upgraded dependenc
 - Python runtime, standard-library, packaging, and changed-default risks when relevant
 - TypeScript compiler-track, RC, nightly, and API compatibility risks when relevant
 - Security advisory and fixed-range notes when relevant
+- Exploit preconditions, dev-server exposure, protocol role, and scanner recheck notes when relevant
 - Surfaces synchronized
 - Command intents run
 - Skipped dependency checks and reasons

package/templates/default/locales/en/.mustflow/skills/llm-token-cost-control-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.llm-token-cost-control-review
 locale: en
 canonical: true
-revision: 2
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: llm-token-cost-control-review
-description: Apply this skill when LLM API calls, prompt assembly, chat history, RAG context, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported and the risk is token spend or cost-per-success drifting out of control.
+description: Apply this skill when LLM API calls, prompt assembly, chat history, RAG context, document metadata, chunk summaries, prompt packing, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported and the risk is token spend or cost-per-success drifting out of control.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -35,7 +35,7 @@ Review LLM cost as a product and systems contract, not as prompt brevity. A cost
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- A change adds, edits, reviews, or reports an LLM request builder, prompt prefix, system or developer message, chat history assembly, memory compaction, RAG context, retrieved chunk packing, few-shot examples, tool definitions, structured output schema, image or file input, model selector, reasoning-effort setting, output limit, retry path, streaming or prediction path, batch processing path, flex or low-priority processing path, cache key, token counter, usage logger, cost dashboard, or LLM quota guard.
+- A change adds, edits, reviews, or reports an LLM request builder, prompt prefix, system or developer message, chat history assembly, memory compaction, RAG context, retrieved chunk packing, document metadata, source maps, summary layers, few-shot examples, tool definitions, structured output schema, image or file input, model selector, reasoning-effort setting, output limit, retry path, streaming or prediction path, batch processing path, flex or low-priority processing path, cache key, token counter, usage logger, cost dashboard, or LLM quota guard.
 - A task asks to reduce token cost, improve provider prompt-cache hit rate, lower cost per successful task, shrink context, split realtime and offline LLM work, route small tasks away from expensive models, or prevent a token bill spike.
 - The product sends repeated instructions, examples, tool schemas, output schemas, documents, policies, conversation history, screenshots, files, or retrieved context to an LLM.
 - The system records total tokens but cannot explain which feature, endpoint, model, prompt version, tool schema version, retry, or validation failure caused the spend.
@@ -55,9 +55,15 @@ Review LLM cost as a product and systems contract, not as prompt brevity. A cost
 ## Required Inputs
 
 - Cost surface ledger: feature, endpoint, caller, model, provider, sync or async path, expected traffic shape, success definition, and current or target budget.
-- Request ledger: stable instructions, examples, tools, schemas, user input, retrieved context, memory, history, files, images, runtime metadata, volatile IDs, dates, locale, and personalization fields.
+- Request ledger: stable instructions, examples, tools, schemas, authority lane for each block,
+  user input, retrieved context, memory, history, files, images, runtime metadata, volatile IDs,
+  dates, locale, and personalization fields.
 - Cache ledger: provider prompt-cache eligibility, stable prefix boundary, canonical serialization, prompt version hash, tool and schema version, cache key policy, app-level response cache key, TTL, invalidation rule, and permission boundary.
-- Context ledger: conversation-window rule, memory summary rule, RAG top-k, chunk size, chunk ordering, evidence span policy, deduplication, compression, and current input-token measurement.
+- Context ledger: conversation-window rule, state-card fields, delta rule, inclusion test,
+  block role tags, document ids, frontmatter or metadata fields split by filter-only versus
+  LLM-visible use, summary layers, source maps, question-specific evidence cards, RAG top-k, chunk
+  size, chunk token counts, chunk ordering, evidence span policy, deduplication, compression,
+  prompt-packing rule, and current input-token measurement.
 - Output ledger: output schema size, repeated key length, patch versus full-output policy, `max_output_tokens`, reasoning budget, retry repair inputs, validator errors, and incomplete-response handling.
 - Routing ledger: deterministic prefilters, small-model router, expensive-model escalation rule, batch or flex eligibility, predicted-output eligibility, image or file preprocessing, and fallback behavior.
 - Observability ledger: input tokens, cached tokens when exposed by the provider, output tokens, reasoning tokens when exposed or billable, retry count, validation failure count, cache hit rate, cost per successful task, model, endpoint, prompt version, tool version, schema version, and budget breach events.
@@ -75,7 +81,7 @@ Review LLM cost as a product and systems contract, not as prompt brevity. A cost
 ## Allowed Edits
 
 - Refactor request assembly so stable instructions, examples, tool schemas, and output schemas are serialized before volatile user input, timestamps, request IDs, search results, personalization, and runtime metadata.
-- Add or refine prompt version hashes, canonical serialization, provider cache keys, app-level cache keys, token counters, budget guards, model routers, context trimming, RAG chunk packing, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates.
+- Add or refine prompt version hashes, canonical serialization, provider cache keys, app-level cache keys, token counters, token-budget metadata, budget guards, model routers, context trimming, RAG chunk packing, source-map references, original/index/prompt text separation, question-scoped compression, slot records, canonical block references, state snapshots, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates.
 - Move deterministic work such as validation, parsing, enum mapping, deduplication, sorting, formatting, arithmetic, date math, and permission checks out of LLM calls when code can perform it.
 - Add focused fixtures for cost-sensitive boundaries: cache-prefix drift, history growth, RAG chunk bloat, retry replay, oversized schema, full-file regeneration, image input size, and expensive-model routing.
 - Do not rely on "make the prompt shorter" as the primary fix when repeated static payload, history replay, RAG bloat, retries, or output shape causes the spend.
@@ -88,29 +94,61 @@ Review LLM cost as a product and systems contract, not as prompt brevity. A cost
 
 1. Name the cost unit. Decide whether the system optimizes per request, per successful task, per workflow, per user session, per batch job, or per tenant.
 2. Measure before cutting. Prefer provider token-counting APIs, usage fields, or repository-local token accounting over character estimates, especially when tools, schemas, images, files, or reasoning models are involved.
-3. Split stable prefix from volatile suffix. Keep system and developer instructions, policy, examples, tool schemas, structured output schemas, and other repeated static context in a canonical stable order before user input, request IDs, dates, session IDs, retrieved snippets, and personalization.
-4. Hash the expensive prefix. Record or derive a prompt version hash from canonical instructions, examples, tools, schemas, model settings, and output contract. If the hash varies per user without intent, treat it as cache-prefix drift.
-5. Review provider prompt caching. Use provider cache keys only for requests that share the same stable prefix, distribute hot keys according to provider guidance, and log cached-token evidence when the provider exposes it.
-6. Add app-level caching where identical normalized inputs can safely skip the model call. Include tenant, permission, locale, source version, policy version, and TTL in the cache key when they affect correctness.
-7. Trim chat history by state, not by vibes. Keep recent turns, durable memory, active task state, confirmed user preferences, and unresolved tool results; avoid replaying full raw transcripts when a compact state is enough.
-8. Shrink RAG by evidence span. Search broadly if needed, but pass the smallest source-backed spans that answer the question, deduplicate near-identical chunks, preserve source metadata, and use stable ordering when repeated workloads benefit from cache reuse.
-9. Keep tool and schema payloads boring. Tool descriptions and JSON schemas should be long enough for correct routing and validation but not narrative prose. If permissions differ by user, keep schema stable and enforce permission at tool execution.
-10. Route before calling the expensive model. Use deterministic code, regexes, database lookups, small models, or cheap classifiers for tasks that do not need a large reasoning model; escalate only ambiguous, high-value, or failed cases.
-11. Budget reasoning and output together. Set reasoning effort and output limits according to task value; leave enough room for visible output, and handle incomplete responses instead of silently retrying the full expensive request.
-12. Prefer patches over full regeneration when the product already owns most of the output. Use unified diff, JSON Patch, line-range replacement, IDs, labels, scores, or reason codes when downstream code can merge the result.
-13. Repair failures without full replay. For parse failures, enum mismatches, missing fields, or validator errors, retry with previous output, validator error, and schema summary when safe instead of resending the entire original context.
-14. Separate realtime and offline work. Move evals, bulk classification, enrichment, embeddings, report backfills, and log analysis to configured async, batch, or low-priority processing when user latency does not matter.
-15. Treat predicted outputs as a latency tool unless current provider docs and usage evidence show cost behavior for the exact model and endpoint. Use `llm-response-latency-review` when the main goal is faster completion rather than cost control. Watch rejected prediction tokens or equivalent fields when exposed.
-16. Reduce image and file input before the model. Crop screenshots, downsample where acceptable, extract DOM text or OCR first, and count the actual payload tokens when the provider supports it.
-17. Instrument cost per success. Track endpoint, model, prompt version, tool version, schema version, input tokens, cached tokens, output tokens, reasoning tokens, retry count, validation failure rate, cache hit rate, and successful-task denominator.
-18. When prompt-cache layout changes, run the configured prompt-cache audit intent if available and treat byte or token estimates as static layout evidence rather than provider billing proof.
-19. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, cache keys, budget guards, routing, retry repair, telemetry, and installed skill surfaces.
+3. Apply the output-changing test before packing context. If removing a document, transcript slice,
+   metadata field, example, or log would not change the answer, code, decision, citation, or
+   refusal state, keep it out of the model payload and preserve only a reference, count, or hash
+   when needed for traceability.
+4. Keep authority lanes explicit. Stable rules, policies, and output contracts belong in
+   instruction blocks; user input, retrieved documents, examples, and tool observations belong in
+   tagged data blocks. Do not let retrieved text, examples, or summaries become equal-authority
+   instructions.
+5. Split stable prefix from volatile suffix. Keep system and developer instructions, policy, examples, tool schemas, structured output schemas, and other repeated static context in a canonical stable order before user input, request IDs, dates, session IDs, retrieved snippets, and personalization.
+6. Hash the expensive prefix. Record or derive a prompt version hash from canonical instructions, examples, tools, schemas, model settings, and output contract. If the hash varies per user without intent, treat it as cache-prefix drift.
+7. Review provider prompt caching. Use provider cache keys only for requests that share the same stable prefix, distribute hot keys according to provider guidance, and log cached-token evidence when the provider exposes it.
+8. Add app-level caching where identical normalized inputs can safely skip the model call. Include tenant, permission, locale, source version, policy version, and TTL in the cache key when they affect correctness.
+9. Trim chat history by state, not by vibes. Keep recent turns, durable memory, active task state, confirmed user preferences, and unresolved tool results; avoid replaying full raw transcripts when a compact state is enough.
+10. Shrink RAG by evidence span. Search broadly if needed, but pass the smallest source-backed spans that answer the question, deduplicate near-identical chunks, preserve source metadata, and use stable ordering when repeated workloads benefit from cache reuse.
+   Preserve conflicts with source, status, effective date, and authority instead of merging them into
+   one smooth but false summary.
+11. Compress for the current question, not for the whole document. A refund-policy, implementation,
+   legal, and support answer may need different evidence from the same source; store the compression
+   goal, retained fields, dropped fields, and source coordinates.
+12. Use evidence cards before raw chunks when the product can validate them. Include claim,
+    conditions, exceptions, numbers, source ids, section or line span, quote hash, and token count.
+    Expand the original source only when the answer, citation, or validator needs it.
+13. Convert repetitive prose to structured slots. Prefer `condition`, `action`, `limit`,
+    `exception`, `source_ref`, and `confidence` fields over sentence-shaped padding when downstream
+    code or prompts consume rules.
+14. Use state snapshots plus deltas. Carry the compact current state and the newest change rather
+    than replaying the full transcript or sending only a delta that has lost its baseline.
+15. Put critical evidence where the model will see it. Do not bury the only decisive constraint in
+    the middle of a long context; put key evidence early and restate final hard constraints near the
+    end when the prompt shape is long.
+16. Separate original, index, and prompt text. Keep original spans for evidence, enriched `index_text` for search recall, and compact `prompt_text` for model input. Do not let search-only synonyms or generated summaries look like original quoted evidence.
+    Keep search/filter metadata separate from LLM-visible metadata; tags, IDs, ACL fields, and
+    operational paths should reach the model only when they change the output or citation.
+17. Pack by references before raw text. Prefer stable document ids, chunk ids, section anchors, source maps, block refs, and token counts when choosing context. Expand only the needed source spans instead of replaying a whole corpus or full document list.
+18. Keep tool and schema payloads boring. Tool descriptions and JSON schemas should be long enough for correct routing and validation but not narrative prose. If permissions differ by user, keep schema stable and enforce permission at tool execution.
+19. Route before calling the expensive model. Use deterministic code, regexes, database lookups, small models, or cheap classifiers for tasks that do not need a large reasoning model; escalate only ambiguous, high-value, or failed cases.
+20. Budget reasoning and output together. Set reasoning effort and output limits according to task value; leave enough room for visible output, and handle incomplete responses instead of silently retrying the full expensive request.
+21. Prefer patches over full regeneration when the product already owns most of the output. Use unified diff, JSON Patch, line-range replacement, IDs, labels, scores, or reason codes when downstream code can merge the result.
+22. Repair failures without full replay. For parse failures, enum mismatches, missing fields, or validator errors, retry with previous output, validator error, and schema summary when safe instead of resending the entire original context.
+23. Separate realtime and offline work. Move evals, bulk classification, enrichment, embeddings, report backfills, and log analysis to configured async, batch, or low-priority processing when user latency does not matter.
+24. Treat predicted outputs as a latency tool unless current provider docs and usage evidence show cost behavior for the exact model and endpoint. Use `llm-response-latency-review` when the main goal is faster completion rather than cost control. Watch rejected prediction tokens or equivalent fields when exposed.
+25. Reduce image and file input before the model. Crop screenshots, downsample where acceptable, extract DOM text or OCR first, and count the actual payload tokens when the provider supports it.
+26. Evaluate compression as loss, not as style. Compare compressed and uncompressed answers on
+    answer exactness, citation recall, numeric accuracy, constraint violations, and correct refusals.
+27. Instrument cost per success. Track endpoint, model, prompt version, tool version, schema version, corpus version, index version, source hash, input tokens, cached tokens, output tokens, reasoning tokens, retry count, validation failure rate, cache hit rate, and successful-task denominator.
+28. When prompt-cache layout changes, run the configured prompt-cache audit intent if available and treat byte or token estimates as static layout evidence rather than provider billing proof.
+29. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, cache keys, budget guards, routing, retry repair, telemetry, and installed skill surfaces.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Stable LLM payload is separated from volatile data, hashed or versioned where useful, and cacheable by design when the provider supports prompt caching.
 - Long context, chat history, RAG evidence, tools, schemas, files, images, reasoning, output, retries, and routing each have an explicit budget or reduction rule where relevant.
+- Retrieved context distinguishes original evidence, enriched index text, prompt-ready text, question-specific evidence cards, source-map references, token counts, block references, and summary layers.
+- Compression quality is evaluated against answer, citation, numeric, constraint, and refusal behavior rather than judged by shorter text alone.
 - Deterministic work is handled outside the model unless language judgment is required.
 - Metrics can explain cost per successful task, cache-prefix drift, retry cost, validation failures, and model routing decisions without leaking sensitive prompt or user data.
 - Final reports distinguish proven cost-control evidence from assumed provider behavior, anecdotal token savings, and latency-only optimizations.
@@ -149,7 +187,7 @@ Use the narrowest configured fixture, unit, integration, telemetry, docs, packag
 - LLM token-cost surface reviewed
 - Cost unit, budget, and measurement source
 - Stable prefix, volatile suffix, prompt hash, and provider cache behavior checked
-- App cache, history, RAG, tool schema, structured schema, image or file input, and deterministic prefilter choices checked
+- App cache, history, RAG, metadata, source-map, prompt-packing, tool schema, structured schema, image or file input, and deterministic prefilter choices checked
 - Model routing, reasoning effort, output limit, patch-output, retry repair, Batch, Flex, and prediction choices checked
 - Cost observability fields and sensitive-data redaction checked
 - Files changed

package/templates/default/locales/en/.mustflow/skills/memory-lifetime-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.memory-lifetime-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: memory-lifetime-review
@@ -59,6 +59,7 @@ The question is not only "where was it allocated?" The stronger review question
 - Retainer graph: the longer-lived owner, the shorter-lived object, the reference path between them, and the expected point where that reference should be severed.
 - Repetition path: repeated requests, screen open/close, route changes, tab switches, reconnects, retries, scheduled runs, test cases, or long-running sessions that can accumulate retained state.
 - Error and success paths: normal completion, early return, partial read, cancellation, timeout, retry, exception, unmount, shutdown, and dependency failure behavior.
+- Diagnostic evidence for native or low-level memory faults: first sanitizer or memory-checker report, invalid write/read address, watchpoint condition, allocator or quarantine behavior, fuzzing input, core dump, symbols, build id, shared library list, and configured or manual diagnostic boundary.
 - Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow validation.
 
 <!-- mustflow-section: preconditions -->
@@ -116,8 +117,21 @@ The question is not only "where was it allocated?" The stronger review question
     - C and C++: ownership transfer must be explicit across raw pointers, containers, callbacks, and failure paths; `shared_ptr` cycles need `weak_ptr` or a different ownership shape.
     - Rust: `Rc`, `Arc`, `RefCell`, task handles, channels, and cycles can leak even when memory safety is preserved; use weak ownership or explicit shutdown when ownership is not truly shared.
     - Python: weak references are useful for caches and observer maps, but not as a substitute for a clear lifetime owner; check global dicts, LRU caches, callbacks, generators, files, and async tasks.
-11. Reject finalizers as the main plan. Finalizers, destructors, drop hooks, or weak callbacks can be last-resort diagnostics or safety nets, but the review should still identify deterministic cleanup for resources and reference removal.
-12. Add a repeated-lifecycle proof when feasible. Prefer a focused test or probe that repeats the risky lifecycle, then asserts listener count, registry size, cache size, goroutine/task completion, handle closure, queue depth, or retained object count. If heap snapshots, leak profilers, sanitizer runs, or platform-specific diagnostics are not configured intents, report them as manual evidence gaps instead of running raw commands.
+11. For native or low-level memory corruption, chase the first invalid access instead of the crash line.
+    - Treat the crash line as a victim until the first invalid write, invalid read, use-after-free, double free, uninitialized value, or ownership violation is identified.
+    - Prefer the first sanitizer, memory-checker, or watchpoint report over later cascade failures.
+    - Use watchpoint, reverse-debugging, core dump, symbol, build-id, allocator, quarantine, or memory-poison evidence only through configured or manual diagnostics; do not infer raw commands from tool names.
+12. Separate diagnostic build axes when they exist.
+    - ASan/UBSan/LSan, TSan, MSan, release-with-asserts, debug allocator, guard-page allocator, hardware tagging, and fuzzing-with-sanitizers expose different bug classes and usually should be reported as separate configured or manual evidence surfaces.
+    - Do not claim memory-corruption proof from a normal unit test unless it actually exercises the ownership and lifetime boundary.
+13. Treat dangling references as ownership failures.
+    - Ask which owner promised the object would remain alive across async callbacks, observer lists, event buses, lambda captures, coroutines, workers, caches, intrusive lists, and queues.
+    - Prefer stable handles, owner id plus generation id, unregister-on-drop or RAII boundaries, weak-reference lock windows, and queueing copied identifiers instead of raw object pointers or references when local style supports them.
+14. Preserve production crash evidence when reproduction is unavailable.
+    - Core dump, exact binary, symbols, build id, shared library list, process maps, allocator state, failing input, and deployment version can be the only evidence for a memory fault.
+    - If those artifacts are unavailable or manual-only, report that boundary instead of implying the crash was diagnosed from logs alone.
+15. Reject finalizers as the main plan. Finalizers, destructors, drop hooks, or weak callbacks can be last-resort diagnostics or safety nets, but the review should still identify deterministic cleanup for resources and reference removal.
+16. Add a repeated-lifecycle proof when feasible. Prefer a focused test or probe that repeats the risky lifecycle, then asserts listener count, registry size, cache size, goroutine/task completion, handle closure, queue depth, or retained object count. If heap snapshots, leak profilers, sanitizer runs, memory-checker runs, fuzzers, core dump inspection, or platform-specific diagnostics are not configured intents, report them as manual evidence gaps instead of running raw commands.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -126,6 +140,7 @@ The question is not only "where was it allocated?" The stronger review question
 - Long-lived owners no longer retain short-lived objects beyond their intended lifecycle, or the remaining retention is intentional and bounded.
 - Caches, queues, registries, debug stores, and logging or telemetry buffers have capacity, eviction, truncation, or copied-value boundaries where they can grow.
 - Async, stream, worker, goroutine, thread, and native-resource paths have deterministic cancellation, close, shutdown, or release behavior where the platform supports it.
+- Native or low-level memory fault analysis names the first invalid access evidence or reports the missing diagnostic boundary instead of blaming the final crash line.
 - Tests or configured verification cover the highest-risk repeated lifecycle when feasible.
 
 <!-- mustflow-section: verification -->
@@ -162,6 +177,7 @@ Use the narrowest configured test, build, docs, release, or mustflow intent that
 - Retainer paths found or ruled out
 - Long-lived owners and short-lived objects checked
 - Timers, listeners, subscriptions, streams, workers, goroutines, threads, native handles, caches, queues, registries, closures, and logs checked where relevant
+- First invalid access, diagnostic build axis, dangling ownership, fuzzing or core-dump evidence where relevant
 - Cleanup symmetry changes made or recommended
 - Repeated-lifecycle proof: configured, manual-only, missing, or not applicable
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/observability-debuggability-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.observability-debuggability-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: observability-debuggability-review
@@ -94,79 +94,88 @@ The review question is not "does the code emit telemetry?" It is "when this path
    - List logs, metrics, traces, spans, events, audit entries, alerts, dashboards, runbooks, and exporter self-metrics touched by the path.
    - Mark each signal as symptom, cause evidence, correlation evidence, saturation evidence, recovery evidence, or noise.
    - A success-only log is not enough; failure classification and missing-work evidence matter more.
-3. Check metrics for numerator and denominator.
+3. Prefer trace-first diagnosis for distributed or cross-boundary failures.
+   - Compare normal and failing trace trees before reading only the final error log.
+   - Look for the first divergence in span order, missing span, retry branch, cache hit or miss, DB call count, dependency latency, worker shard, feature flag, release id, queue age, or pool wait.
+   - Logs should explain branch decisions inside that trace; metrics should show whether the incident is isolated or systemic.
+4. Align trace, log, and profiler evidence on one time axis when timing or ordering may matter.
+   - Trace evidence identifies the affected request, job, message, or operation.
+   - Profiler evidence identifies what the process was doing during the same window: CPU, wall wait, lock contention, allocation, GC, or pool wait.
+   - Do not treat a slow span as self-explanatory until the same window's process, pool, dependency, and queue evidence have been checked where available.
+5. Check metrics for numerator and denominator.
    - Error counters need total attempt counters so an operator can compute rates.
    - Cache hits need total lookups, fill errors, stale-served counts, origin latency, and eviction or lock-wait evidence when cache correctness matters.
    - Rate limits need allowed, blocked, shadow-blocked, delayed, retry-after, policy, and key-type evidence rather than only `rate_limited_total`.
-4. Reject average-only latency.
+6. Reject average-only latency.
    - Prefer histograms or equivalent distribution evidence for p95, p99, and tail behavior.
    - Separate success latency from error latency; fast failures should not make the service look healthy.
    - Label outcome and status class with bounded cardinality where the local metric system supports it.
-5. Protect metric cardinality.
+7. Protect metric cardinality.
    - Do not put raw URL paths, query strings, user ids, order ids, emails, message ids, idempotency keys, exception messages, SQL text, or arbitrary provider codes into metric labels.
    - Use route templates, dependency names, operation names, status classes, bounded reason enums, policy names, and feature flag names.
    - Keep high-cardinality fields in traces, structured events, audit records, or sampled logs when they are safe and needed for narrowing.
-6. Check trace and log correlation.
+8. Check trace and log correlation.
    - Logs should include trace id and span id, or the local equivalent, when distributed tracing exists.
    - Spans should include dependency name, operation name, route template, outcome, safe error type, retry attempt, timeout or cancellation class, and release or environment attributes when useful.
    - If a log line cannot be joined to a request, job, message, or batch run, it is weak incident evidence.
-7. Check async and queue context propagation.
+9. Check async and queue context propagation.
    - HTTP to worker, queue, stream, pub/sub, webhook, cron, and batch boundaries should propagate or intentionally fork trace context.
    - Producers should inject safe context into messages when the system needs end-to-end diagnosis; consumers should extract it before doing work.
    - A new trace at the worker boundary can be correct only when the handoff is intentionally modeled and linked by message, job, or causation id.
-8. Separate attempt from operation.
+10. Separate attempt from operation.
    - Retries should expose each dependency attempt and the final logical operation result.
    - A final success after two failed attempts is a business success and a dependency warning.
    - Record attempt number, max attempts, retry decision, delay, retry-after use, dependency name, and final exhaustion reason with bounded labels.
-9. Classify timeout, cancellation, and deadline.
+11. Classify timeout, cancellation, and deadline.
    - User cancellation, upstream deadline, server timeout, dependency timeout, pool acquire timeout, queue visibility expiry, and shutdown cancellation are different events.
    - Do not merge all of them into one generic error metric or log reason.
    - Preserve cancellation semantics without turning intentional caller cancellation into a dependency incident.
-10. Review external dependency spans and metrics.
+12. Review external dependency spans and metrics.
     - `GET https://api.vendor.example` is not enough; add a stable dependency name and operation name.
     - Track attempts, latency distribution, status class, retryable decision, timeout class, circuit-open decisions, and provider request id when safe.
     - Keep provider host, endpoint, and response details out of metric labels when they are unbounded or sensitive.
-11. Review database and transaction evidence.
+13. Review database and transaction evidence.
     - Avoid raw SQL in logs and telemetry where it can contain personal data or secrets.
     - Prefer query name, table or collection, operation, rows returned, rows affected, duration, timeout class, and safe error category.
     - Transaction flows should expose begin, commit, rollback, retry, after-commit side effects, external-call-before-commit risk, and compensation or reconciliation evidence when relevant.
-12. Review idempotency and partial-success evidence.
+14. Review idempotency and partial-success evidence.
     - Payment, order, entitlement, file, webhook, queue, and batch paths need idempotency key, dedupe key, message id, request id, attempt, side-effect state, and unknown-outcome markers where safe.
     - Ask where evidence remains when DB write succeeds but event publish fails, provider call succeeds but local state fails, cache write succeeds but origin rollback happens, or compensation fails.
     - Metrics and logs should distinguish attempt, success, failure, compensation, retry exhausted, and unknown outcome.
-13. Review queue, stream, and batch signals.
+15. Review queue, stream, and batch signals.
     - Consumers need queue delay or message age, processing duration, inflight count, ack or commit failures, redelivery count, retry count, DLQ count, poison reason, and oldest message age where supported.
     - Batch jobs need last success timestamp, last completion timestamp, duration, processed count, failed count, skipped count, and stale-job alert evidence.
     - Silent pipelines need heartbeat or synthetic item evidence when "no input" can look like success.
-14. Review pools and saturation.
+16. Review pools and saturation.
     - CPU can be low while worker, thread, DB connection, HTTP connection, queue, semaphore, or rate-limit pools are saturated.
     - Track active, max, queued, queue wait, acquire duration, timeout count, rejection count, and per-dependency pool names with bounded labels.
     - Missing saturation evidence should downgrade performance and reliability claims.
-15. Review feature, config, release, and migration attribution.
+17. Review feature, config, release, and migration attribution.
     - Logs, traces, and metrics should carry service version, git sha or release id, deployment environment, region, schema or migration version, config version, and relevant feature flag or experiment variant when local policy allows.
     - If a 5 percent feature flag cohort can fail separately, the telemetry must let operators split healthy and broken cohorts.
-16. Check alert and runbook usefulness.
+18. Check alert and runbook usefulness.
     - Every new critical metric should answer what panel, alert, or runbook sentence it supports.
     - Pager alerts should indicate user impact or clear operator action, not only "a counter changed."
     - Logs that page humans should have matching counters or rates so operators can see when the event started and how fast it is happening.
-17. Check telemetry self-observability.
+19. Check telemetry self-observability.
     - Exporters, collectors, custom metric collectors, log sinks, trace queues, and sampling pipelines need dropped, failed, queued, scrape error, and export latency evidence when they can blind operators.
     - If telemetry failure can hide product failure, treat missing self-metrics as an operational risk.
-18. Check signal pipeline loss and read-path visibility.
+20. Check signal pipeline loss and read-path visibility.
     - Compare produced, accepted, exported, stored, and query-visible signal counts when the path depends on logs, metrics, traces, or events for diagnosis.
     - Use canary events or synthetic heartbeats when "no telemetry" could mean no traffic, collector failure, broken parser, dropped queue, retention gap, or dashboard read failure.
     - Track event timestamp versus observed timestamp, queue oldest age, DLQ oldest age, parser or mapping failures by service and version, and duplicate or sequence-gap evidence.
     - Separate telemetry write-path health from read-path health. A sink can store data that dashboards cannot query, and dashboards can be healthy while new signals are not arriving.
     - If collector, sink, dashboard, or production telemetry checks are outside repository commands, report the manual-only boundary.
-19. Check sampling policy.
+21. Check sampling policy.
     - Head sampling can drop rare errors and slow traces.
     - Error, slow, retry-exhausted, high-latency, partial-success, DLQ, and compensation-failure traces often need keep rules, tail sampling, or explicit event evidence.
+    - If a rare failure can be sampled out, require fallback event logs for key span boundaries, duration, outcome, reason, tenant or job slice, feature flag, and deployment version.
     - If sampling is outside the repository, report the manual-only evidence boundary instead of assuming critical traces are retained.
-20. Check privacy before telemetry leaves the process.
+22. Check privacy before telemetry leaves the process.
     - Redact or classify tokens, passwords, authorization headers, cookies, raw bodies, emails, phone numbers, payment data, personal identifiers, prompt text, confidential document text, provider payloads, and full SQL before logger, metric, trace, baggage, or exporter entry.
     - Baggage should be small, safe, low-lifetime, and intentional. Do not use it as a general request metadata bag.
     - Report sink-side masking as insufficient when sensitive data can already leave the process unredacted.
-21. Require telemetry tests or contract evidence where feasible.
+23. Require telemetry tests or contract evidence where feasible.
     - Good tests assert stable event names, bounded label values, denominator counters, trace-context propagation, redaction, sampling flags, feature flag attributes, release attributes, and failure-category mapping.
     - Source-level guards can prevent raw URL or user id metric labels when runtime telemetry tests are not available.
     - If dashboards, alerts, production traces, or load evidence are manual-only, complete available checks and report the evidence gap.
@@ -176,6 +185,7 @@ The review question is not "does the code emit telemetry?" It is "when this path
 
 - The changed path has an incident question, signal ledger, metric model, trace and log correlation model, telemetry pipeline survival boundary, cardinality boundary, privacy boundary, and evidence level.
 - Missing denominators, average-only latency, success-only logs, uncorrelated logs, raw URL labels, raw user labels, raw SQL telemetry, lost async trace context, attempt and operation collapse, generic timeout or cancellation buckets, missing dependency names, missing queue age, missing batch last-success timestamp, missing pool saturation, missing release attribution, decorative metrics, unsafe baggage, telemetry self-blindness, and sampling that drops critical failures are fixed or reported.
+- Normal-versus-failing trace comparisons and trace/log/profiler time-axis alignment are used or reported as unavailable when timing, ordering, retry, queue, pool, or dependency behavior is the likely cause.
 - Observability claims are backed by configured tests, schema or fixture evidence, local telemetry conventions, dashboard or alert files, static review evidence, or labeled as manual-only or missing.
 
 <!-- mustflow-section: verification -->
@@ -208,7 +218,7 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 ## Output Format
 
 - Observability boundary reviewed
-- Incident question, signal ledger, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, signal pipeline survival, sampling, privacy, and test evidence findings
+- Incident question, signal ledger, normal-versus-failing trace comparison, trace/log/profiler time-axis alignment, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, signal pipeline survival, sampling, privacy, and test evidence findings
 - Observability fixes made or recommended
 - Evidence level: configured-test evidence, telemetry fixture evidence, dashboard or alert file evidence, static review risk, manual-only, missing, or not applicable
 - Command intents run