mustflow 2.85.4 → 2.99.0

package/templates/default/locales/en/.mustflow/skills/auth-permission-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.auth-permission-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: auth-permission-change
-description: Apply this skill when authentication, authorization, permissions, roles, tenants, sessions, JWTs, OAuth or OIDC, API keys, route guards, admin access, database policies, object-level access control, signed delivery URLs, credentialed event streams, or private cache behavior are created or changed.
+description: Apply this skill when authentication, authorization, permissions, roles, effective permissions, policy decisions, tenants, sessions, JWTs, OAuth or OIDC, API keys, route guards, admin access, database policies, object-level access control, signed delivery URLs, credentialed event streams, or private cache behavior are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -54,11 +54,20 @@ Authentication answers who the requester is. Authorization answers what that pri
 ## Required Inputs
 
 - Changed files, user goal, affected actors, protected resources, actions, tenants, roles, and status-code expectations.
+- Permission decision tuple for each changed protected action: subject, action, object, tenant or
+  organization, relationship path, request environment, policy version, data revision, token issue
+  time, and final allow or deny reason.
+- Effective-permission evidence, not only role names: computed capabilities, inherited
+  relationships, explicit denies, wildcard policies, policy-combination rules, and default-deny
+  behavior.
 - Auth middleware, framework hooks, gateway checks, session config, cookie config, JWT verifier, OAuth/OIDC callback, API key verifier, and logout or revocation code when relevant.
 - Route guards, client guards, server controllers, resolvers, command handlers, services, policy functions, role or permission tables, database queries, RLS, views, stored procedures, and ORM scopes.
 - Tenant, organization, workspace, project, membership, invite, suspension, ownership, sharing, and admin-support data models.
 - Background jobs, queue payloads, webhooks, import/export flows, search or autocomplete indexes, signed URL generation, storage keys, SSE or streaming channels, WebTransport sessions, WebSocket fallback, CDN cache, proxy cache, and permission caches when they can expose protected data.
 - Audit logs, admin action logs, impersonation records, denied-access logs, API docs, role matrix docs, migrations, and tests.
+- Revocation and cache evidence: token claim freshness, session lifetime, permission-cache key and
+  TTL, policy replication delay, search-index or export lag, stale queue payloads, and rollback or
+  shadow-evaluation behavior when policy changes.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -92,31 +101,58 @@ Authentication answers who the requester is. Authorization answers what that pri
    - database queries, tenant scopes, ownership joins, soft-delete filters, RLS, views, stored procedures, and ORM helpers;
    - background jobs, queues, webhooks, import/export, file storage, signed URLs, SSE or streaming channels, WebTransport sessions, WebSocket fallback, search, autocomplete, caches, CDN or proxy cache rules, audit logs, docs, migrations, and tests.
 3. Write the permission decision inputs for each protected action: principal, tenant, resource, action, and context.
-4. Separate identity from permission:
+4. Freeze the authorization decision tuple.
+   - Record subject, action, object, tenant, environment, policy version, data revision, token issue
+     time, matched policy, inheritance path, and final allow or deny reason.
+   - A role label is not the decision. Use effective permissions and relationship paths.
+5. Separate identity from permission:
    - `req.user`, a valid session, verified email, valid JWT, OAuth scope, or API key proves identity only;
    - owner, active member, org admin, global admin, support user, service account, API client, and shared-link viewer need separate authorization rules.
-5. Prefer one central policy shape, such as a `can(principal, action, resource, context)` function, over route-local `isAdmin`, `isOwner`, or `isMember` fragments.
-6. Enforce deny by default. New roles, actions, resource types, tenant types, sharing modes, and admin paths must deny until explicitly allowed.
-7. Validate every request. Do not rely on login-time checks, client guards, disabled buttons, hidden menus, generated types, OpenAPI docs, or mobile local checks.
-8. Load resources safely before final authorization:
+6. Prefer one central policy shape, such as a `can(principal, action, resource, context)` function, over route-local `isAdmin`, `isOwner`, or `isMember` fragments.
+7. Require explainable policy decisions.
+   - A production-supportable permission engine should expose which policy matched, which condition
+     failed, which inherited relationship granted access, and whether an explicit deny won.
+   - If the implementation cannot explain allow or deny decisions, report observability risk before
+     claiming the policy is maintainable.
+8. Enforce deny by default. New roles, actions, resource types, tenant types, sharing modes, and admin paths must deny until explicitly allowed.
+9. Define policy-combination semantics. Check whether multiple policies combine by union,
+   intersection, priority, explicit deny, boundary policy, or tenant override; write tests for
+   allow-plus-deny and no-match cases.
+10. Validate every request. Do not rely on login-time checks, client guards, disabled buttons, hidden menus, generated types, OpenAPI docs, or mobile local checks.
+11. Load resources safely before final authorization:
    - include tenant, membership, owner, sharing, and soft-delete constraints in the resource lookup when possible;
    - when existence must be hidden, keep wrong-tenant and missing-resource behavior consistent with the project's 404 policy.
-9. Check multi-tenant risks:
+12. Check multi-tenant risks:
    - body, query, header, path, JWT claim, or local storage tenant ids must not become trusted tenant context;
    - tenant-scoped queries must include tenant or membership constraints;
    - pending, suspended, removed, revoked, deleted, disabled, and invited states must not be treated as active access;
    - shared links, exports, signed URLs, previews, search, cache, and CDN entries must stay inside the permission model.
    - event streams, WebTransport sessions, WebSocket fallback channels, private downloads, and reconnect URLs must not bypass tenant, resource, role, token expiry, or revocation policy.
-10. Check session, JWT, OAuth/OIDC, and API key contracts when touched:
+13. Check session, JWT, OAuth/OIDC, and API key contracts when touched:
    - sessions need expiry, refresh, rotation, logout, revocation, cookie flags, and CSRF posture;
    - JWTs need signature verification, algorithm allowlist, issuer, audience, subject, expiry, not-before, key rotation, and stale-claim handling;
    - OAuth/OIDC needs exact redirect binding, state, nonce, PKCE when relevant, provider account binding, and safe account linking;
    - API keys need hashing, prefix-only display, owner type, scope, tenant/resource constraints, expiry, rotation, revocation, last-used, rate limit, and audit.
-11. Check dependent surfaces: API routes, controllers, services, DB schema, DB queries, RLS, UI navigation, UI actions, API clients, audit logs, notifications, jobs, webhooks, search, file storage, docs, migrations, monitoring, and tests.
+14. Check permission creators more strictly than ordinary permissions.
+    - Role creation, role assignment, invitation, service-account issuance, API-key creation,
+      impersonation, support access, and token minting are privilege factories.
+    - A low-privilege actor that can attach a high privilege to itself collapses the whole model.
+15. Check revocation time.
+    - Demotion, removal, suspension, role deletion, membership expiry, subscription cancellation,
+      and ownership transfer should say how long old sessions, JWT claims, caches, search indexes,
+      queued jobs, and replicas can keep authorizing the old state.
+    - Sensitive actions need server-side recheck, short-lived tokens, revocation lists, or policy
+      version gates when stale tokens would be harmful.
+16. Check dependent surfaces: API routes, controllers, services, DB schema, DB queries, RLS, UI navigation, UI actions, API clients, audit logs, notifications, jobs, webhooks, search, file storage, docs, migrations, monitoring, and tests.
     - For credentialed delivery surfaces, check whether EventSource can supply the intended credentials, whether CORS and cookies match the policy, whether signed URLs expire and scope correctly, and whether caches vary on auth, tenant, and private response dimensions.
-12. Require denial-first tests for changed protected actions when the project has a usable test surface. Cover anonymous, expired, revoked, no role, wrong tenant, wrong owner, suspended or removed member, stale cache, shared-link, read-only API key, org admin, global admin, and impersonating admin cases as applicable.
-13. Update docs and role matrices when external behavior, status codes, role names, permission names, admin scope, or API errors change.
-14. Report the policy source of truth, server/database enforcement, client UX-only guards, test coverage, skipped checks, and remaining permission risk.
+17. Require denial-first tests for changed protected actions when the project has a usable test surface. Cover anonymous, expired, revoked, no role, wrong tenant, wrong owner, suspended or removed member, stale token, stale cache, unknown role, unknown action, wildcard policy, explicit deny, shared-link, read-only API key, org admin, global admin, and impersonating admin cases as applicable.
+18. When changing policies, consider shadow evaluation.
+    - Compute old and new decisions side by side for representative requests before flipping broad
+      policy changes when the product has the infrastructure to do so.
+    - Log policy version and data revision for both decisions without exposing secrets or sensitive
+      object contents.
+19. Update docs and role matrices when external behavior, status codes, role names, permission names, admin scope, or API errors change.
+20. Report the policy source of truth, effective-permission evidence, decision explanation, server/database enforcement, client UX-only guards, revocation window, test coverage, skipped checks, and remaining permission risk.
 
 ## Boundary Rules
 
@@ -127,6 +163,10 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Admin is scoped. Global admin, org admin, project admin, billing admin, support, and impersonating admin are different roles and need different audit and action rules.
 - Owner is not a wildcard permission. Owners may still lack delete, export, invite, transfer, billing, or admin powers.
 - API keys are principals with scopes and owners, not user sessions with unlimited power.
+- Wildcard permissions are future permissions. Adding a new action under an old wildcard should be
+  treated as a permission expansion and reviewed accordingly.
+- Unknown roles, unknown actions, malformed identifiers, and missing relationship data deny by
+  default; they are not normalized into a normal user path.
 
 ## Strongly Forbidden Patterns
 
@@ -142,6 +182,9 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Changing 403 to 404, or 404 to 403, without naming the information-disclosure policy.
 - Relaxing permissions without denial-case tests or a written migration and audit plan.
 - Letting role changes ship without permission-cache or token-staleness handling.
+- Shipping a permission engine that cannot explain why a request was allowed or denied.
+- Treating an effective-permission bug as solved because the `role` column looks correct.
+- Treating token-embedded roles as fresh after demotion, removal, or policy version changes.
 - Creating shared links, signed URLs, exports, search results, or CDN responses outside tenant and resource policy.
 - Creating credentialed event streams, WebTransport sessions, WebSocket fallback channels, signed delivery URLs, or private caches outside tenant and resource policy.
 - Logging impersonation without separate actor and subject.
@@ -153,6 +196,8 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Authentication and authorization are separated in code and report language.
 - Every changed protected action has a server-side or database-side permission boundary.
 - Tenant isolation, resource ownership, sharing, admin scope, and status-code behavior are explicit.
+- Effective permissions, policy-combination rules, decision explanation, policy version, data
+  revision, and revocation window are explicit when relevant.
 - Client guards are described as UX only.
 - Session, token, OAuth/OIDC, API key, cache, audit, docs, migration, and tests are synchronized when touched.
 - Signed URL, event-stream, WebTransport, WebSocket fallback, CORS, cookie, CDN/proxy cache, and reconnect behavior remains inside the permission model when touched.
@@ -190,6 +235,7 @@ Prefer the narrowest configured test intent that covers the changed protected ac
 - Authentication versus authorization classification
 - Principal, tenant, resource, action, and context affected
 - Policy source of truth
+- Effective permission, policy version, data revision, decision explanation, and revocation window
 - Server/database enforcement notes
 - Client guard UX-only notes
 - Tenant, ownership, sharing, admin, token/session/API-key, cache, and audit notes

package/templates/default/locales/en/.mustflow/skills/backend-log-evidence-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.backend-log-evidence-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: backend-log-evidence-review
-description: Apply this skill when backend code is created, changed, reviewed, or reported and request logs, error logs, structured event names, log schema versions, trace/span/request IDs, correlation and causation IDs, outcome or reason fields, external API logs, database write logs, transaction or state-transition logs, retry or timeout logs, queue or batch logs, audit logs, auth or validation logs, cache or lock logs, release/config/feature-flag logs, log levels, duplicate logs, redaction, log-injection safety, sampling, or log searchability need review for whether an operator can reconstruct why a backend request, job, or data change reached its final state.
+description: Apply this skill when backend code is created, changed, reviewed, or reported and request logs, error logs, structured event names, log schema versions, trace/span/request IDs, correlation and causation IDs, outcome or reason fields, external API logs, database write logs, transaction or state-transition logs, retry or timeout logs, queue or batch logs, audit logs, auth or validation logs, cache or lock logs, release/config/feature-flag logs, log pipeline canaries, collector accepted/sent/stored counts, timestamp versus observed timestamp, parser or mapping failures, log levels, duplicate logs, redaction, log-injection safety, sampling, or log searchability need review for whether an operator can reconstruct why a backend request, job, or data change reached its final state and whether the evidence actually survived the logging pipeline.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,7 @@ The review question is: "If this backend path fails, times out, retries, silentl
 - Backend handlers, services, repositories, adapters, workers, schedulers, webhooks, migrations, scripts, or batch jobs add, remove, review, or depend on logs.
 - A change claims that a path is logged, traceable, easy to debug, auditable, operationally safe, or diagnosable from logs.
 - Request start or finish logs, event names, schema versions, severity fields, trace or span IDs, error handling, error wrapping, external API calls, DB writes, transactions, status transitions, early returns, retries, timeouts, queues, async jobs, batches, audit events, auth, validation, cache, distributed locks, idempotency, feature flags, configuration, releases, migrations, or background promises are involved.
+- Log ingestion, parsing, buffering, shipping, storage, searchability, retention, rotation, multiline parsing, canary logs, dropped-log counters, timestamp skew, or log sink visibility affects whether backend evidence can be trusted.
 - A review needs to decide whether logs explain why the system reached a state, not only where the exception was thrown.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -60,6 +61,7 @@ The review question is: "If this backend path fails, times out, retries, silentl
 - Error evidence: thrown errors, catches, wrappers, causes, stack preservation, error categories, public versus internal messages, and log boundary ownership.
 - Decision evidence: branches, early returns, validation failures, auth decisions, feature flags, state transitions, cache paths, retry decisions, timeout classes, and fallback decisions.
 - Side-effect evidence: external API calls with dependency name, operation, timeout, latency, status class, retry count, circuit state, and provider request id; DB affected rows; transaction begin/commit/rollback evidence; queue enqueue and consume; idempotency decisions; locks; migrations; batch summaries; release/config/feature-flag events; and configuration snapshots.
+- Pipeline integrity evidence when logs leave the process: generated count, collector accepted count, exporter sent count, stored count, searchable count, canary event id, sequence gaps, duplicate rate, timestamp and observed timestamp drift, queue oldest age, DLQ oldest age, parser failures, mapping conflicts, dropped or sampled counts, rotation or restart boundary, multiline grouping, and storage retention boundary.
 - Safety constraints: secrets, tokens, cookies, auth headers, passwords, raw payloads, personal data, payment data, provider response bodies, full SQL, log injection through control characters or ANSI escapes, high-cardinality indexing cost, sampling policy, and retention policy.
 - Local conventions: logger API, structured field names, severity levels, redaction helpers, error serialization, test helpers, snapshots or fixtures, and configured command intents.
 
@@ -161,7 +163,14 @@ The review question is: "If this backend path fails, times out, retries, silentl
     - Normalize or escape user-controlled strings such as filenames, user agents, nicknames, referers, and queries so newlines, tabs, control characters, and ANSI escapes cannot forge log entries.
     - Sink-side masking is not enough when sensitive data has already crossed the process boundary.
     - Tests or static guards should cover sensitive log fields when feasible.
-18. Require evidence.
+18. Review log pipeline survival when the task depends on searchable logs.
+    - Compare generated, accepted, sent, stored, and searchable counts by service, environment, version, and event family instead of trusting one total.
+    - A synthetic canary log with a unique id and increasing sequence can expose loss, duplication, reorder, and search visibility lag.
+    - Distinguish event timestamp from observed timestamp; large drift points to clock skew, buffer delay, backpressure, or collector backlog.
+    - Queue size alone is weak. Check queue utilization, oldest queued event age, enqueue failures, exporter failures, receiver refusals, DLQ size, and DLQ oldest age.
+    - Parser failures, mapping conflicts, multiline splits, log rotation, container restart, pod deletion, disk buffer exhaustion, and retention or rollover drift can silently erase the evidence operators think they have.
+    - If pipeline checks require live collectors, sinks, dashboards, or production search, report them as manual-only instead of claiming log evidence survived.
+19. Require evidence.
     - Prefer focused tests, log fixtures, snapshot assertions, redaction tests, source-level guards, or local logger contract tests for stable event names and fields.
     - Prefer tests that pin `event_name`, schema version, required fields, redaction, bounded reason codes, and message-independent query fields rather than exact prose.
     - If logs depend on runtime middleware, production log routing, sink configuration, or manual log search outside the repository, report that evidence as manual-only.
@@ -170,7 +179,7 @@ The review question is: "If this backend path fails, times out, retries, silentl
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- The reviewed backend path has a reconstruction question, event contract, request lifecycle evidence, correlation and causation model, decision evidence, side-effect evidence, error and cause preservation, redaction boundary, level ownership, sampling boundary, and evidence level.
+- The reviewed backend path has a reconstruction question, event contract, request lifecycle evidence, correlation and causation model, decision evidence, side-effect evidence, error and cause preservation, pipeline survival boundary, redaction boundary, level ownership, sampling boundary, and evidence level.
 - Missing start or finish logs, message-only contracts, unstable event names, missing schema version, missing trace or span id, missing correlation or causation id, string-only errors, lost causes, missing external-call before and after logs, raw provider body logs, missing affected-row counts, invisible transaction or state transitions, silent early returns, attempt-free retries, duration-free timeouts, enqueue or consume gaps, broken async correlation, empty batch summaries, missing auth or validation reasons, ordinary logs for audit events, cache or lock blind spots, idempotency ambiguity, feature flag opacity, release or config opacity, secret-bearing config logs, migration `done` logs, swallowed async errors, all-info or all-error severity, duplicate error spam, prose-only messages, high-cardinality indexed fields, log injection exposure, unsafe sampling, and missing identifiers are fixed or reported.
 - Named review smells such as broken async request id, auth or validation failures, cache hits or misses, lock acquisition, idempotency outcomes, config startup summaries, release and migration event gaps, migration dry-run and apply logs, message-based dashboards, prose-only log, and sink-side-only masking are fixed or reported when present.
 - Log changes are backed by local logger conventions, tests, fixtures, source review evidence, or labeled as manual-only or missing.
@@ -205,7 +214,7 @@ Prefer the narrowest configured checks that cover the changed logging contract a
 ## Output Format
 
 - Backend log boundary reviewed
-- Reconstruction question, event contract, request lifecycle, correlation and causation, error and cause preservation, external API, database write, transaction, state transition, early return, retry, timeout, queue or async handoff, batch or migration, audit, auth, validation, cache, lock, idempotency, feature flag, release, config, level ownership, structure, cardinality, sampling, log-injection safety, redaction, and test evidence findings
+- Reconstruction question, event contract, request lifecycle, correlation and causation, error and cause preservation, external API, database write, transaction, state transition, early return, retry, timeout, queue or async handoff, batch or migration, audit, auth, validation, cache, lock, idempotency, feature flag, release, config, pipeline survival, level ownership, structure, cardinality, sampling, log-injection safety, redaction, and test evidence findings
 - Log fixes made or recommended
 - Evidence level: configured-test evidence, log fixture evidence, source review evidence, manual-only, missing, or not applicable
 - Command intents run

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.cache-integrity-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: cache-integrity-review
-description: Apply this skill when code is created, changed, reviewed, or reported and cache behavior can spread stale, wrong, private, overbroad, tenant-crossing, permission-wrong, version-incompatible, or source-overloading values through cache keys, query normalization, key versions, TTL and jitter, soft and hard TTL, stale-while-revalidate, stampede protection, request coalescing, negative caching, invalidation order, list or page caches, tag invalidation, L1/L2 cache layers, Redis fallback, hit/miss observability, value size, eviction policy, TTL-less keys, KEYS/SCAN use, hot keys, Redis Cluster hash tags, HTTP Vary/no-cache/no-store semantics, permission caches, cache warming, or failure-path cache tests.
+description: Apply this skill when code is created, changed, reviewed, or reported and cache behavior can spread stale, wrong, private, overbroad, tenant-crossing, permission-wrong, version-incompatible, or source-overloading values through cache keys, query normalization, key versions, TTL and jitter, soft and hard TTL, stale-while-revalidate, stampede protection, request coalescing, negative caching, invalidation order, list or page caches, tag invalidation, L1/L2 cache layers, Redis fallback, cache-status ledgers such as hit, miss, bypass, stale, refresh, error, set-failed, evicted, or expired, origin-cost observability, value size, eviction policy, TTL-less keys, KEYS/SCAN use, hot keys, Redis Cluster hash tags, replica lag, Redis latency, HTTP Vary/no-cache/no-store semantics, permission caches, cache warming, or failure-path cache tests.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -81,9 +81,11 @@ and what happens to the source system when the cache misses or fails?"
 - Failure and concurrency contract: miss behavior, concurrent miss behavior, source timeout, Redis
   failure, source failure, negative cache policy, update race behavior, invalidation ordering, and
   stale serve policy.
-- Observability evidence: hit and miss metrics, miss cost, value size, key count, eviction, expiry,
-  tenant or endpoint breakdown, status-code breakdown, source query time, source call count, and set
-  success.
+- Observability evidence: hit, miss, bypass, stale, refresh, negative-hit, set-failed, error,
+  eviction, expiry, and fallback metrics; miss cost; hit-rate cost by endpoint or tenant; value
+  size; key count; source query time; source call count; origin saturation; Redis client wait,
+  round-trip latency, command latency, serialization cost, Slow Log limits, replica lag, shard
+  imbalance, and set success.
 - Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
   validation.
 
@@ -180,6 +182,8 @@ and what happens to the source system when the cache misses or fails?"
       shedding, stale serve, circuit breaker, bulkhead, or another source-protection mechanism.
     - Decide whether cache failure is disposable or correctness-sensitive. Sessions, permissions,
       rate limits, inventory, idempotency, and dedupe caches are not ordinary performance caches.
+    - Compare normal cached traffic with an allowed bypass path or known miss path when evidence is
+      available. If bypass is faster, fresher, or more correct, the cache policy itself is suspect.
 13. Check Redis keyspace and memory behavior.
     - Review value size, key size, key schema, bounded key cardinality, max memory, eviction policy,
       expired keys, evicted keys, and whether TTL-less keys are turning cache into state storage.
@@ -187,43 +191,54 @@ and what happens to the source system when the cache misses or fails?"
       so TTL-less keys can crowd out real cache behavior.
     - `KEYS *` in application code is a production bomb. Use `SCAN` only from bounded admin or
       maintenance paths with explicit limits.
-14. Check hot keys and Redis Cluster distribution.
+14. Check Redis latency, replication, and distribution.
+    - Redis Slow Log does not include client round-trip time, connection wait, serialization,
+      application loop overhead, DNS, TLS, or network path time. Do not use it as the only latency
+      proof.
+    - Review replica lag, failover behavior, cold replica warmup, persistence spikes, memory
+      fragmentation, client connection pools, shard imbalance, and command mix when a cache incident
+      is operational rather than semantic.
+15. Check hot keys and Redis Cluster distribution.
     - Sharding does not save one hot key. Use replicas, local L1, request coalescing, prewarm,
       chunking, or workload-specific splitting where semantics allow it.
     - Redis Cluster hash tags are useful for intentional multi-key locality, but overusing the same
       tag can force too many keys into one slot.
-15. Check HTTP cache semantics.
+16. Check HTTP cache semantics.
     - If responses vary by `Authorization`, `Cookie`, `Accept-Language`, `Accept-Encoding`, content
       negotiation, or user context, verify `Vary` and cache-control behavior.
     - `no-cache` means revalidate before reuse. `no-store` means do not store. Do not use one when
       the other is required.
     - Check freshness, validation, private versus public cacheability, CDN behavior, browser behavior,
       and generated-client or proxy expectations.
-16. Check permission and entitlement caches as security boundaries.
+17. Check permission and entitlement caches as security boundaries.
     - A permission cache, role cache, organization-membership cache, subscription cache, admin cache,
       or entitlement cache must be invalidated by revocation, role change, organization move,
       subscription expiry, ownership change, and emergency access changes.
     - Short TTL alone is not enough for decisions that should fail closed or revoke promptly.
-17. Check cache warming and cold-start behavior.
+18. Check cache warming and cold-start behavior.
     - Deployment, autoscale, failover, and rollback can create synchronized cold caches that push
       traffic to the source.
     - Prewarm only keys with clear ownership and backpressure. Do not build an unbounded warming job
       that becomes the outage.
-18. Check observability.
-    - Hit rate alone lies. Break down hits, misses, stale serves, negative hits, refresh failures,
-      evictions, expirations, and set failures by endpoint, key-pattern, tenant, status-code, and
-      cache layer where useful.
+    - Load-test or smoke the cold, warm, failover, replica-lag, source-slow, and cache-down scenarios
+      when the repository has configured evidence. Otherwise report those as manual operational gaps.
+19. Check observability.
+    - Hit rate alone lies. Break down hits, misses, bypasses, stale serves, refreshes, negative hits,
+      refresh failures, evictions, expirations, fallback serves, Redis errors, and set failures by
+      endpoint, key-pattern, tenant, status-code, and cache layer where useful.
     - Log or measure miss cost: source query time, source call count, value size, generation time,
       and set success.
+    - Track hit-rate cost: origin load avoided, origin load caused by misses, miss amplification,
+      cache write failures, and whether a high hit rate hides a small set of expensive miss paths.
     - Keep cache metrics labels bounded; put high-cardinality keys in logs or traces only when the
       repository privacy rules allow it.
-19. Check tests beyond the happy path.
+20. Check tests beyond the happy path.
     - "Second call is faster" is not enough.
     - Cover concurrent misses, update during read, delete then recreate, source failure, Redis
       failure, synchronized TTL expiry, old-version cached value, permission change, tenant
       separation, list invalidation, negative-cache classification, deploy rollback, and cache-layer
       bypass when those risks exist.
-20. Label evidence honestly. If the repository lacks deterministic cache, Redis, CDN, HTTP, browser,
+21. Label evidence honestly. If the repository lacks deterministic cache, Redis, CDN, HTTP, browser,
     or load tests, report the missing evidence instead of claiming the cache is safe.
 
 <!-- mustflow-section: postconditions -->

package/templates/default/locales/en/.mustflow/skills/change-blast-radius-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.change-blast-radius-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: change-blast-radius-review
-description: Apply this skill when code is created, changed, reviewed, or reported and maintainability needs review by predicting the next-change blast radius, deletion path, policy owner, workflow owner, controller or service responsibility, boolean and option-mode sprawl, scattered domain rules, scattered authorization, state-transition ownership, direct time or randomness, transaction and external-call coupling, retry idempotency, cache-as-truth decisions, config flag combinations, tenant or partner hardcoding, legacy branch isolation, DTO/entity/view model mixing, nullable meaning, swallowed exceptions, low-context logs, implementation-coupled tests, mock-heavy tests, decorative abstraction, premature DRY, hidden ordering dependency, event contract visibility, migration/runtime compatibility, or feature removal boundary.
+description: Apply this skill when code is created, changed, reviewed, or reported and maintainability needs review by predicting the next-change blast radius, historical co-change spread, deletion path, policy owner, workflow owner, controller or service responsibility, boolean and option-mode sprawl, scattered domain rules, scattered authorization, state-transition ownership, direct time or randomness, transaction and external-call coupling, retry idempotency, cache-as-truth decisions, config flag combinations, tenant or partner hardcoding, legacy branch isolation, DTO/entity/view model mixing, nullable meaning, swallowed exceptions, low-context logs, implementation-coupled tests, mock-heavy tests, decorative abstraction, premature DRY, hidden ordering dependency, event contract visibility, migration/runtime compatibility, or feature removal boundary.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -46,6 +46,8 @@ feature is removed, what can I delete?"
   logging, tests, abstractions, helpers, or legacy compatibility.
 - A single requirement would force edits across several files, layers, modules, frontend code, SQL,
   jobs, events, cache keys, tests, or docs.
+- Recent PRs, commits, work orders, or review history show that small requirements routinely
+  co-change many repositories, services, schemas, pipelines, teams, tests, or docs.
 - A file or service has several unrelated reasons to change under one broad noun such as `Manager`,
   `Helper`, `Processor`, `Handler`, or `Service`.
 - A review needs to decide whether to use `module-boundary-review`, `structure-first-engineering`,
@@ -72,6 +74,10 @@ feature is removed, what can I delete?"
 - User goal, current diff or target files, and the requirement or policy that caused the change.
 - Change-reason ledger: which business rule, user flow, data shape, failure path, compatibility
   rule, tenant exception, or operational behavior would make this code change next.
+- Historical co-change ledger when available: recent PRs or commits touching the same requirement
+  family, repositories touched, services touched, DB schemas touched, deployment pipelines touched,
+  teams or reviewers involved, tests changed, docs changed, and whether the current design reduced
+  or repeated that spread.
 - Blast-radius ledger: controllers, services, repositories, entities, DTOs, frontend conditions,
   SQL, migrations, batches, events, caches, config, tests, docs, and templates touched by one reason.
 - Ownership ledger: source of truth for domain rule, authorization rule, state transition, retry
@@ -115,123 +121,128 @@ feature is removed, what can I delete?"
    - Ask: "If this requirement changes next month, which files move?"
    - If one policy edit needs controller, service, repository, SQL, frontend, batch, cache, and test
      edits, the code is a puzzle, not a boundary.
-2. Count reasons to change, not lines.
+2. Check historical co-change when evidence exists.
+   - Look for recent PRs, commits, or work items in the same feature or policy family.
+   - Count repositories, services, schemas, pipelines, test suites, docs, and teams touched by small changes.
+   - Treat repeated cross-boundary co-change as stronger evidence than a clean-looking folder tree.
+   - If history is unavailable or too expensive for the task, report the review as prediction-only instead of pretending the boundary was proven.
+3. Count reasons to change, not lines.
    - A short file can still hold signup, login, points, notification, referral, admin blocking, and
      reporting rules.
    - Split by different change reasons, not by noun labels.
-3. Keep controllers as doors, not bosses.
+4. Keep controllers as doors, not bosses.
    - Controllers should parse requests, call an application boundary, and map the result.
    - Treat controller `if`, `for`, state mutation, external API calls, discount logic, inventory
      checks, or notification orchestration as workflow leakage.
-4. Reject junk-drawer services.
+5. Reject junk-drawer services.
    - Broad names such as `OrderService`, `UserService`, `Manager`, `Helper`, `Processor`, and
      `Handler` often hide unrelated workflows.
    - Name the actual responsibility or split by workflow owner when changes would not arrive
      together.
-5. Decode boolean mode flags.
+6. Decode boolean mode flags.
    - `createUser(user, true)` and `sendNotification(user, true, false)` mean one function already
      has hidden modes.
    - Replace modes with named variants, policy objects, strategy objects, or separate functions when
      behavior contracts differ.
-6. Inspect option objects for combinatorial behavior.
+7. Inspect option objects for combinatorial behavior.
    - Fields such as `skipValidation`, `dryRun`, `force`, `source`, `mode`, `type`, `retry`,
      `legacy`, and `includeInactive` can turn one call into many products.
    - If field combinations change behavior, use explicit mode types or separate boundaries.
-7. Find the policy source of truth.
+8. Find the policy source of truth.
    - Repeated rules such as "VIP gets free shipping" across backend, frontend, SQL, batch, and
      cache code are not harmless duplication.
    - Name one owner and make other layers consume facts or capabilities from that owner.
-8. Centralize authorization policy.
+9. Centralize authorization policy.
    - Scattered checks such as `role == admin`, `ownerId == user.id`, or membership scans make policy
      changes scary.
    - Use `auth-permission-change` when action permission needs one policy source and denial tests.
-9. Make state transitions visible.
+10. Make state transitions visible.
    - Status values are not enough. Review where `status = ...` happens and which transitions are
      legal.
    - Use `state-machine-pattern` when allowed transitions need to be represented explicitly.
-10. Pull time, randomness, and generated IDs to a boundary.
+11. Pull time, randomness, and generated IDs to a boundary.
     - Direct `new Date()`, `Date.now()`, `LocalDateTime.now()`, UUIDs, random order numbers, random
       filenames, and generated referral codes hide reproducibility and future policy changes.
     - Use explicit time, generator, or identifier inputs from the shell.
-11. Draw the transaction boundary.
+12. Draw the transaction boundary.
     - When several saves happen, ask what remains if the middle save fails.
     - If the answer is unclear, use `failure-integrity-review` or the relevant database skill before
       changing behavior.
-12. Separate external calls from committed state.
+13. Separate external calls from committed state.
     - DB save, payment API, DB save, notification API in one flow creates timeout, retry, and
       duplicate-effect traps.
     - Prefer local state plus outbox, idempotency keys, or effect descriptions when the operation
       must survive partial failure.
-13. Check retry idempotency.
+14. Check retry idempotency.
     - `retry(3)`, queues, webhooks, schedulers, and manual replays are dangerous without a duplicate
       rule.
     - Ask what happens when the same event arrives twice.
-14. Reject cache-as-truth for important decisions.
+15. Reject cache-as-truth for important decisions.
     - Cache can speed reads, but it should not become the source of truth for authorization, payment
       eligibility, inventory, or other critical decisions.
     - Use `cache-integrity-review` when cache freshness or fallback can mislead the decision.
-15. Count config flag combinations.
+16. Count config flag combinations.
     - Flags such as `enableNewPolicy`, `useLegacyFlow`, `skipValidationForPartner`, and
       `specialCaseTenantIds` can create untested products inside one code path.
     - Name the supported combinations or isolate the variation behind a policy boundary.
-16. Isolate tenant, partner, country, product, and app-version exceptions.
+17. Isolate tenant, partner, country, product, and app-version exceptions.
     - Hardcoded `tenantId`, `partnerCode`, country code, app version, or product ID branches are
       product debt, not just conditionals.
     - Prefer configured capabilities, adapters, policy tables, or explicit exceptions with removal
       owners.
-17. Keep legacy compatibility out of the new core.
+18. Keep legacy compatibility out of the new core.
     - `legacy`, `old`, `v1`, `deprecated`, and `temp` branches inside the main path pull old rules
       into new code.
     - Put compatibility in adapters, translators, migration paths, or isolated old-entry boundaries.
-18. Separate data-object languages.
+19. Separate data-object languages.
     - DB entities, API DTOs, view models, external provider payloads, and domain objects should not
       quietly become the same object.
     - If one side changes and another side must follow, name the mapping owner.
-19. Give nullable values a reason.
+20. Give nullable values a reason.
     - `null` must not mean absence, unknown, failed calculation, forbidden access, and provider
       timeout at the same time.
     - Use variants, result types, or explicit fields that tell callers why a value is missing.
-20. Do not hide exceptions as normal data.
+21. Do not hide exceptions as normal data.
     - `catch (e) { return null }`, `catch (e) { log.warn(...) }`, and empty catches make the system
       lie far from the failure.
     - Use visible failure values, typed errors, or explicit degraded modes.
-21. Make logs traceable, not decorative.
+22. Make logs traceable, not decorative.
     - Logs like `start` and `failed` without order ID, user ID, request ID, external call ID, tenant,
       or operation name do not help future maintainers.
     - Add safe correlation context when it is the only way to connect the failure path.
-22. Keep tests attached to behavior.
+23. Keep tests attached to behavior.
     - Tests that assert private methods, mock call order, or internal collaborator choreography make
       refactors expensive.
     - Prefer outcomes, state transitions, persisted commands, emitted events, or public results.
-23. Treat mock count as a change-impact sensor.
+24. Treat mock count as a change-impact sensor.
     - More than three mocks deserves a responsibility review.
     - Five or more mocks usually means the class absorbs too many change directions.
-24. Validate abstraction against real volatility.
+25. Validate abstraction against real volatility.
     - Interfaces, factories, strategies, and abstract classes help only when the variation axis is
       real.
     - Ask whether there are two real implementations now or a known future swap along this exact
       axis.
-25. Do not DRY together different futures.
+26. Do not DRY together different futures.
     - Removing duplication is harmful when two similar blocks change for different reasons.
     - Keep duplication when it preserves independent policy evolution.
-26. Make required ordering explicit.
+27. Make required ordering explicit.
     - Initialization, validation, save, event publication, cache invalidation, notification, and
       cleanup steps can be order-sensitive.
     - If swapping two lines would break correctness, encode the sequence in a named workflow,
       transaction, state transition, or command object.
-27. Treat events as invisible function calls until proven otherwise.
+28. Treat events as invisible function calls until proven otherwise.
     - `publish(Event)` hides subscribers, failure behavior, ordering, duplicate delivery, and
       compatibility.
     - Name the event contract, listener expectations, idempotency, and failure handling.
-28. Pair migrations with runtime compatibility.
+29. Pair migrations with runtime compatibility.
     - Schema changes, enum additions, defaults, indexes, and backfills must be checked against old
       code on new schema and new code on old data.
     - Use `database-migration-change` when deploy order or data backfill matters.
-29. Run the deletion test.
+30. Run the deletion test.
     - Ask: "If this feature disappears, what do I delete?"
     - If flags, columns, conditions, events, caches, batch jobs, UI checks, and tests are scattered,
       the feature is already rooted too deeply.
-30. Pick the smallest boundary repair.
+31. Pick the smallest boundary repair.
     - If one owner is missing, introduce that owner.
     - If one mode is hidden, name that mode.
     - If the risk is too broad for the current task, report the exact next-change or deletion path
@@ -240,7 +251,8 @@ feature is removed, what can I delete?"
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- The next likely policy or workflow change has a named owner and a predictable edit path, or the
+- The next likely policy or workflow change has a named owner, historical co-change evidence when
+  available, and a predictable edit path, or the
   unpredictable spread is explicitly reported.
 - Important side effects, transactions, retries, events, caches, config flags, migrations, and logs
   have clear owners or remaining risks.
@@ -287,6 +299,7 @@ public contract.
 
 - Change blast radius reviewed
 - Next likely change and owner
+- Historical co-change evidence, or prediction-only note when unavailable
 - Files, layers, jobs, caches, events, tests, docs, or migrations in the blast radius
 - Policy, authorization, state, transaction, retry, cache, config, tenant, legacy, DTO, nullable,
   log, test, abstraction, ordering, event, migration, or deletion findings