mustflow 2.85.4 → 2.99.1

package/templates/default/locales/en/.mustflow/skills/service-boundary-architecture/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.service-boundary-architecture
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: service-boundary-architecture
-description: Apply this skill when service boundaries, modular-monolith boundaries, data ownership, queue/event boundaries, multi-tenant isolation, failure flow, operational recovery, or large-scale architecture split decisions are designed, reviewed, or changed.
+description: Apply this skill when service boundaries, modular-monolith boundaries, data ownership, queue/event boundaries, multi-tenant isolation, failure flow, independent deployment, operational recovery, disaster recovery, service split evidence, team ownership, cost, toil, or large-scale architecture split decisions are designed, reviewed, or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,7 @@ This skill protects against the common failure mode where a system is split by n
 - A task designs, reviews, documents, or changes service boundaries, modular-monolith boundaries, bounded contexts, team ownership, API ownership, event ownership, queue ownership, or data ownership.
 - A monolith is being prepared for future split, a microservice split is proposed, or a service/module boundary is causing deploy, data, incident, or team coordination pain.
 - The task touches cross-service transactions, outbox/inbox patterns, idempotency, retries, timeouts, caches, read models, search models, shared databases, operational tools, manual correction, observability, tenancy, hot keys, or failure recovery.
+- A boundary claim needs proof from recent co-change history, independent deployability, dependency direction, database write ownership, synchronous call depth, queue backlog behavior, graceful shutdown, health probe correctness, version compatibility, restore or DR drills, least-privilege access, config blast radius, cost, toil, or team bottlenecks.
 - Architecture docs, decision records, onboarding docs, or skills need durable guidance for large-system design and operational readiness.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -57,6 +58,7 @@ This skill protects against the common failure mode where a system is split by n
 - Data ownership map: which module or service is the source of truth for each core fact, identifier, status, ledger, permission, tenant record, event, and read projection.
 - Current or proposed communication paths: direct calls, APIs, events, queues, shared databases, shared caches, batch jobs, search indexes, analytics stores, files, and admin tools.
 - Failure flows: duplicate requests, partial success, timeout, retry, consumer crash, queue backlog, dead-letter handling, external provider uncertainty, reconciliation, and manual correction.
+- Boundary proof ledger: last 3 months of PR co-change by repository, service, schema, deployment pipeline, and team; independent deploy test; dependency cycle map; table write ownership; synchronous call count; non-core dependency failure behavior; timeout and retry budget; queue oldest age; saturation curve; noisy-neighbor evidence; graceful shutdown; health probe split; old/new version compatibility; trace continuity; user-facing SLOs; local dev setup cost; ADR rationale; least-privilege access; config blast radius; restore and DR drill; cost per feature or customer; toil and approval bottlenecks.
 - Consistency expectations: strong consistency, eventual consistency, tolerated delay, stale reads, cache invalidation, read/write split, search delay, and deletion or retention rules.
 - Tenant, authorization, observability, deployment, migration, and operations requirements.
 - Configured verification intents and any existing architecture decision records or context files.
@@ -82,25 +84,32 @@ This skill protects against the common failure mode where a system is split by n
 
 1. Name the business capabilities and the facts each capability owns. For every core fact, identify exactly one source of truth and the owner responsible for correcting it.
 2. Split first by reason to change, not by noun. Keep code together when it changes together; split only when ownership, release cadence, scale, compliance, failure isolation, or team autonomy makes the boundary useful.
-3. Prefer a modular monolith with hard internal boundaries when the team is still discovering the domain. Draw future split lines early, but do not pay distributed-system costs before the boundary pressure is real.
-4. Reject shared database ownership. If another service or module needs data, choose an API, event, read projection, export, or explicitly owned query surface instead of direct table coupling.
-5. Design failure flows before the happy path. Cover partial success, duplicated requests, timeout, unknown external outcome, consumer crash, queue backlog, dead-letter handling, replay, reconciliation, and manual recovery.
-6. Require idempotency for commands that create, charge, reserve, approve, issue, grant, cancel, refund, redeem, or mutate durable state. Use stable request keys and return the previous result for duplicate keys.
-7. Treat queues as storage and backpressure, not magic. Define retry policy, exponential backoff or jitter, max attempts, retention, dead-letter ownership, consumer scaling, ordering expectations, replay safety, and loss tolerance.
-8. Every network call across the boundary needs a timeout, bounded retry policy, fallback or failure result, duplicate-safety story, and observability identifiers.
-9. Treat caches as a consistency tradeoff. Declare which stale values are acceptable, max staleness, invalidation owner, tenant and permission visibility, and whether the cache is allowed to become authority.
-10. Model authorization, tenant isolation, audit, and data visibility at the boundary. Tenant ID must travel through APIs, queues, caches, logs, files, reports, and admin tools when the system is multi-tenant.
-11. For event-driven boundaries, use past-tense fact events such as `OrderCreated` or `PaymentApproved`. Do not disguise commands as events. Include event ID, version, occurred time, publisher, subject, causation or request ID, correlation or trace ID, and compatible schema evolution rules.
-12. Separate transaction data from search, reporting, analytics, and screen-shaped read projections when their consistency, indexing, query, or retention needs diverge.
-13. Define tolerated delay with numbers. Replace vague "real-time" claims with accepted latency or freshness windows such as seconds, minutes, or batch cadence.
-14. Check hot keys and noisy neighbors. Define per-tenant, per-customer, per-room, per-campaign, or per-product limits, queue separation, worker pool separation, connection caps, and external API call caps when one key can dominate load.
-15. Keep domain rules in the owning domain layer. Do not scatter refund windows, cancellation rules, entitlement checks, inventory reservations, or admin overrides across controllers, UI, workers, and jobs.
-16. Plan migrations with expand, dual-write or compatibility, backfill, read switch, verification, and contract removal. Do not rename or remove shared fields in one deployment step.
-17. Plan deletion and retention before data is created. Identify legal retention, anonymization, log masking, backup retention, search/read-model cleanup, and audit exceptions.
-18. Make observability a product feature. Connect API, queue, worker, external provider, database, and admin operations with trace, request, correlation, causation, job, and tenant identifiers. Prefer p95, p99, error rate, queue age, backlog, dependency failure rate, and business success rate over averages.
-19. Make deployment and rollback a boundary decision. Use feature flags, canaries, partial exposure, compatibility windows, and kill switches for risky boundary changes.
-20. Provide operational tools for reality: reconcile external state, retry or quarantine failed messages, correct user/account/order state, revoke permissions, inspect provider responses, and undo manual changes with audit and approval when required.
-21. Record the decision: selected boundary, rejected alternatives, reason, assumptions, failure modes, data owner, operational owner, verification, and revisit triggers.
+3. Prove whether the proposed boundary is real.
+   - Mine recent PRs or change records when available: count repositories, services, DB schemas, deployment pipelines, and teams touched by one small requirement.
+   - Try the independent-deploy thought experiment: if one boundary cannot ship without another service version, shared library, DB migration, frontend deploy, or meeting, it is not independent yet.
+   - Draw dependency direction and cycles. Cycles usually mean the responsibility and data boundary is wrong, not merely that imports need cleaning.
+   - Count how many synchronous services and stores must succeed for one user action. If the answer is "many, or humans fix the database," the consistency boundary may be split in the wrong place.
+4. Prefer a modular monolith with hard internal boundaries when the team is still discovering the domain. Draw future split lines early, but do not pay distributed-system costs before the boundary pressure is real.
+5. Reject shared database ownership. If another service or module needs data, choose an API, event, read projection, export, or explicitly owned query surface instead of direct table coupling. Table write ownership should be explicit for every core fact.
+6. Design failure flows before the happy path. Cover partial success, duplicated requests, timeout, unknown external outcome, consumer crash, queue backlog, dead-letter handling, replay, reconciliation, and manual recovery.
+7. Require idempotency for commands that create, charge, reserve, approve, issue, grant, cancel, refund, redeem, or mutate durable state. Use stable request keys and return the previous result for duplicate keys.
+8. Treat queues as storage and backpressure, not magic. Define retry policy, exponential backoff or jitter, max attempts, retention, dead-letter ownership, consumer scaling, ordering expectations, replay safety, loss tolerance, oldest-message age, and catch-up rate.
+9. Every network call across the boundary needs a timeout, bounded retry policy, fallback or failure result, duplicate-safety story, observability identifiers, and a request-level budget so retries do not multiply across layers.
+10. Treat caches as a consistency tradeoff. Declare which stale values are acceptable, max staleness, invalidation owner, tenant and permission visibility, and whether the cache is allowed to become authority.
+11. Model authorization, tenant isolation, audit, and data visibility at the boundary. Tenant ID must travel through APIs, queues, caches, logs, files, reports, and admin tools when the system is multi-tenant. Service accounts should have only the DB, queue, storage, and API permissions the boundary needs.
+12. For event-driven boundaries, use past-tense fact events such as `OrderCreated` or `PaymentApproved`. Do not disguise commands as events. Include event ID, version, occurred time, publisher, subject, causation or request ID, correlation or trace ID, and compatible schema evolution rules.
+13. Separate transaction data from search, reporting, analytics, and screen-shaped read projections when their consistency, indexing, query, or retention needs diverge.
+14. Define tolerated delay with numbers. Replace vague "real-time" claims with accepted latency or freshness windows such as seconds, minutes, or batch cadence.
+15. Check hot keys and noisy neighbors. Define per-tenant, per-customer, per-room, per-campaign, or per-product limits, queue separation, worker pool separation, connection caps, and external API call caps when one key can dominate load.
+16. Check saturation and graceful degradation. Drive load past normal capacity in a bounded test plan when available, and identify the first bottleneck: worker pool, DB pool, locks, thread pool, queue, disk, external quota, or cache stampede.
+17. Keep domain rules in the owning domain layer. Do not scatter refund windows, cancellation rules, entitlement checks, inventory reservations, or admin overrides across controllers, UI, workers, and jobs.
+18. Plan migrations with expand, dual-write or compatibility, backfill, read switch, verification, and contract removal. Do not rename or remove shared fields in one deployment step. Old and new versions should tolerate unknown fields, missing fields, old messages, and new schema during rollout.
+19. Plan deletion and retention before data is created. Identify legal retention, anonymization, log masking, backup retention, search/read-model cleanup, and audit exceptions.
+20. Make observability a product feature. Connect API, queue, worker, external provider, database, and admin operations with trace, request, correlation, causation, job, and tenant identifiers. Prefer p95, p99, error rate, queue age, backlog, dependency failure rate, and business success rate over averages.
+21. Make deployment, rollback, shutdown, and health checks boundary decisions. Use feature flags, canaries, partial exposure, compatibility windows, kill switches, readiness/liveness/startup separation, graceful drain, and rollback-forward plans for risky boundary changes.
+22. Provide operational tools for reality: reconcile external state, retry or quarantine failed messages, correct user/account/order state, revoke permissions, inspect provider responses, and undo manual changes with audit and approval when required.
+23. Prove recovery, cost, and toil. A backup is not a boundary guarantee until it is restored in a clean environment. DR, config rollback, secret or certificate recovery, per-feature cost, repeated manual work, and single-team or single-person approval bottlenecks should be measured or reported.
+24. Record the decision: selected boundary, rejected alternatives, reason, assumptions, failure modes, data owner, operational owner, verification, cost, toil, and revisit triggers.
 
 <!-- mustflow-section: review-rejection-criteria -->
 ## Review Rejection Criteria
@@ -110,6 +119,9 @@ Reject or revise the design when:
 - A service or module boundary has no named data owner.
 - Two owners write the same core fact without a conflict rule.
 - A service reads another service's tables or cache as normal behavior.
+- A small requirement routinely changes many repositories, services, schemas, pipelines, or teams.
+- A service cannot be deployed, rolled back, or tested without synchronized changes in another boundary.
+- Dependency graphs contain cycles with no explicit ownership decision.
 - The design shows only the happy path.
 - Retries lack timeout, backoff, jitter, max attempts, idempotency, or failure ownership.
 - A queue has no dead-letter, retention, replay, ordering, or backlog policy.
@@ -117,6 +129,8 @@ Reject or revise the design when:
 - Events are imperative commands instead of past-tense facts.
 - Event schemas lack version, event ID, occurred time, publisher, and correlation or causation identifiers.
 - Tenant, permission, audit, or data-retention boundaries are added after the fact.
+- Health checks only prove process liveness, graceful shutdown is untested, or old and new versions cannot run together.
+- Backup, restore, DR, least privilege, config rollback, cost, or toil claims have no proof path.
 - Architecture choice is justified by tooling fashion instead of ownership, failure, scale, compliance, or team autonomy.
 - Manual operations can mutate critical state without audit, approval, and reversal or reconciliation path.
 
@@ -126,7 +140,7 @@ Reject or revise the design when:
 - Data ownership and source-of-truth boundaries are explicit.
 - Boundary split is justified by change reason, ownership, scale, compliance, failure isolation, or team autonomy.
 - Failure handling, idempotency, retry, queue, cache, event, and observability contracts are defined or explicitly deferred.
-- Tenant, authorization, deletion, retention, migration, deployment, and operational recovery risks are checked or reported.
+- Tenant, authorization, deletion, retention, migration, deployment, graceful shutdown, health checks, version compatibility, restore, DR, cost, toil, and operational recovery risks are checked or reported.
 - Decision records explain why this boundary was chosen, what alternatives were rejected, and when to revisit.
 
 <!-- mustflow-section: verification -->
@@ -160,7 +174,7 @@ Use broader configured checks when the boundary change affects templates, public
 - Boundary checked
 - Data owners and source-of-truth notes
 - Failure, idempotency, queue, cache, and event notes
-- Tenant, auth, retention, observability, deployment, and operations notes
+- Co-change, independent deploy, dependency, data ownership, sync-call, saturation, noisy-neighbor, tenant, auth, retention, observability, deployment, health, shutdown, version compatibility, restore, DR, cost, toil, and operations notes
 - Files changed
 - Command intents run
 - Skipped checks and reasons

package/templates/default/locales/en/.mustflow/skills/test-suite-performance-review/SKILL.md

@@ -121,6 +121,10 @@ resources are saturated, and what evidence keeps a faster path trustworthy?"
      shard tail, and idle-worker time.
    - Report p50 and p95 per test or file when available. Average-only timing hides the last slow
      shard, and the last slow shard decides CI wall time.
+   - When the command contract exposes `test_related_profile`, run it before policy changes that
+     depend on local verification timing. Then read the retained evidence with
+     `mf script-pack run test/performance-report summarize --json` before changing scheduling,
+     caching, timeout, worker, fixture, or selected-test behavior.
 2. Classify the bottleneck.
    - Discovery bottleneck: full tree scans, broad classpath scans, fixtures and generated files in
      search paths, or missing precomputed test manifests.
@@ -282,6 +286,11 @@ Use the narrowest configured test, build, docs, release, or mustflow intent that
 test-suite behavior. If the repository exposes a profiling or cached-test intent, use it only when
 the command contract marks it configured, oneshot, and agent-allowed.
 
+When a profiling intent has run, prefer the read-only `test/performance-report` script-pack as the
+first report surface. Its `next_actions` field should guide whether the next safe step is collecting
+profile evidence, resolving previous failures, inspecting slow intents or phases, reviewing timeout
+pressure, or investigating selected-test fallback behavior.
+
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
 

package/templates/default/locales/en/.mustflow/skills/typescript-code-change/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.typescript-code-change
 locale: en
 canonical: true
-revision: 5
+revision: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: typescript-code-change
@@ -95,18 +95,22 @@ Preserve TypeScript's type, runtime validation, module, build, and public API bo
 15. In TypeScript source that targets native Node ESM, write relative imports using the emitted runtime specifier, usually `.js`, such as `import { createApp } from "./app.js"` from `app.ts`. Do not write extensionless relative imports or `.ts` runtime specifiers unless a declared loader, bundler, or runtime explicitly owns that behavior.
 16. Use `moduleResolution: "Bundler"` only when a bundler such as Vite, esbuild, Rollup, or a framework build system owns final module resolution. Do not use bundler resolution to model code that Node will execute directly without that bundler.
 17. If ESM/CJS behavior changes, verify package `type`, `main`, `module`, `browser`, `exports`, condition order, extension rules, generated JS, and generated declaration files together.
-18. Inspect generated declarations when package surfaces change. Declaration files must not leak source-only aliases, private paths, workspace-only package names, unpublished internal paths, or accidental public re-exports.
-19. For TypeScript 6 migration work, treat deprecation warnings as future TypeScript 7 removal risk. `ignoreDeprecations` is a temporary compatibility valve, not proof that the project is ready for 7.0. Prefer removing deprecated options and updating resolver or module choices to match the project runtime.
-20. Treat TypeScript 6 `--stableTypeOrdering` as a migration comparison tool for declaration and error-order differences, not as a permanent performance-neutral default. If it changes errors or declaration output, look for inference or declaration-stability issues instead of snapshotting noise.
-21. For TypeScript 7 migration work, keep the tracks separate:
+18. For `tsconfig` updates, make defaults explicit when they affect emitted shape, ambient types, or module semantics. Check `rootDir`, `include`, `exclude`, `types`, `lib`, `target`, `module`, `moduleResolution`, `verbatimModuleSyntax`, `noUncheckedSideEffectImports`, declaration output, and framework wrapper defaults together instead of relying on a compiler-major default.
+19. Treat `types` as an ambient-global allowlist. Add only the runtime or test environment globals the project actually uses, such as Node, Bun, DOM, Vitest, Jest, or Playwright. Do not restore broad ambient discovery just to hide missing imports or environment drift.
+20. Use import attributes, subpath imports, and deferred module evaluation only when the runtime, bundler, and compiler track all support the exact syntax. `import defer` is a side-effect and startup-order choice, not a generic lazy-loading trick; use it only for namespace imports whose module evaluation can safely wait until first export access.
+21. Use `using` or `await using` only when the target runtime or transform path supports explicit resource management and the object really owns a disposable resource. Do not replace visible `try/finally`, context-manager, or framework cleanup contracts with `using` if the surrounding lifecycle, error propagation, or generated JS cannot be verified.
+22. Inspect generated declarations when package surfaces change. Declaration files must not leak source-only aliases, private paths, workspace-only package names, unpublished internal paths, or accidental public re-exports.
+23. For TypeScript 6 migration work, treat deprecation warnings as future TypeScript 7 removal risk. `ignoreDeprecations` is a temporary compatibility valve, not proof that the project is ready for 7.0. Prefer removing deprecated options and updating resolver or module choices to match the project runtime.
+24. Treat TypeScript 6 `--stableTypeOrdering` as a migration comparison tool for declaration and error-order differences, not as a permanent performance-neutral default. If it changes errors or declaration output, look for inference or declaration-stability issues instead of snapshotting noise.
+25. For TypeScript 7 migration work, keep the tracks separate:
    - TS6 stable API track: `@typescript/typescript6` and `tsc6` for compiler API, transformer, ESLint, framework wrapper, and peer-dependency compatibility.
    - TS7 RC compiler track: `typescript@rc` and `tsc` for RC compiler verification.
    - TS7 nightly track: `@typescript/native-preview` and `tsgo` for nightly diagnostics only.
    - Future TS7 stable track: stable `typescript` once upstream publishes TypeScript 7 on the normal stable path.
-22. Keep compiler API consumers, language-service plugins, custom transformers, and framework typecheck wrappers on the TS6 API track until their owners explicitly support the TS7 API surface. Treat TS7 RC `tsc` as compiler verification, not proof that JavaScript compiler API consumers can migrate.
-23. When comparing TS6 `tsc6`, TS7 RC `tsc`, and optional TS7 nightly `tsgo`, classify differences before editing code: real type error, declaration emit order or printback noise, unsupported option, unsupported API, watch or incremental behavior gap, language-service gap, generated-output drift, or framework wrapper mismatch.
-24. Do not treat faster TS7 RC or nightly results as sufficient verification. Keep the repository's existing `tsc`, `tsc6`, or framework typecheck as the compatibility baseline until repository policy explicitly adopts a different compiler track.
-25. Choose the narrowest configured verification intents that cover typecheck, lint, tests, build output, declarations, package contract risk, and downstream-style consumer risk.
+26. Keep compiler API consumers, language-service plugins, custom transformers, and framework typecheck wrappers on the TS6 API track until their owners explicitly support the TS7 API surface. Treat TS7 RC `tsc` as compiler verification, not proof that JavaScript compiler API consumers can migrate.
+27. When comparing TS6 `tsc6`, TS7 RC `tsc`, and optional TS7 nightly `tsgo`, classify differences before editing code: real type error, declaration emit order or printback noise, unsupported option, unsupported API, watch or incremental behavior gap, language-service gap, generated-output drift, or framework wrapper mismatch.
+28. Do not treat faster TS7 RC or nightly results as sufficient verification. Keep the repository's existing `tsc`, `tsc6`, or framework typecheck as the compatibility baseline until repository policy explicitly adopts a different compiler track.
+29. Choose the narrowest configured verification intents that cover typecheck, lint, tests, build output, declarations, package contract risk, and downstream-style consumer risk.
 
 <!-- mustflow-section: assertion-policy -->
 ## Assertion Policy
@@ -154,6 +158,7 @@ Reject or revise the patch when any of these appear without explicit evidence an
 - Validator schemas and exported types are duplicated without a single source of truth.
 - Generated declarations expose source-only aliases, internal module paths, workspace-only packages, or accidental barrel exports.
 - Package entry metadata changes without checking runtime entry, type entry, declaration output, and supported resolver modes.
+- `tsconfig` defaults, ambient `types`, import attributes, `import defer`, or explicit resource management syntax are adopted without runtime, bundler, compiler-track, and generated-output evidence.
 - `skipLibCheck` or weakened strictness is used as release validation for a library/package.
 - TypeScript 6-to-7 migration warnings are silenced instead of classified and either fixed or reported.
 - TS7 RC or nightly output differences are accepted as harmless without classification.

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

@@ -0,0 +1,209 @@
+---
+mustflow_doc: skill.vector-search-integrity-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: vector-search-integrity-review
+description: Apply this skill when vector search, semantic search, RAG retrieval mechanics, embeddings, vector databases, ANN indexes, exact versus approximate search, filters, metadata payloads, namespaces, tenants, named vectors, hybrid search, reranking, recall, latency, quantization, HNSW, IVF, pgvector, Qdrant, Milvus, Weaviate, OpenSearch kNN, or retrieval golden-set behavior is created, changed, reviewed, or failing. Use rag-pipeline-triage first when a RAG failure is not yet localized to retrieval versus parsing, context assembly, prompt, generation, citation, or answerability.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.vector-search-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Vector Search Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review vector and semantic search as a retrieval contract, not as "the vector database is good or
+bad."
+
+The core question is whether ingestion, embedding, storage, exact search, approximate search,
+filters, reranking, and latency evidence all agree for the same query contract.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates or changes embedding generation, preprocessing, chunking, vector schema, collection
+  names, namespaces, tenants, named vectors, metadata payloads, filters, search parameters, ANN
+  indexes, hybrid search, reranking, retrieval metrics, RAG context selection, or vector DB clients.
+- Search is missing documents, returning wrong results, returning empty filtered results, duplicating
+  chunks, leaking tenants, becoming slow, changing quality after model or index changes, or behaving
+  differently across replicas.
+- A review needs recall, MRR, golden-set, exact-versus-ANN, filter, metadata index, quantization,
+  compaction, shard, consistency, reranker, or embedding-model-version evidence.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only generic database schema or query performance with no vector, embedding, semantic
+  retrieval, or RAG boundary; use the database or performance skill.
+- The task is only LLM answer grounding after retrieval is already proven; use
+  `llm-hallucination-control-review`.
+- The task is an end-to-end RAG failure and it is not yet clear whether ingestion, retrieval,
+  context assembly, prompt construction, generation, citation validation, or answerability failed;
+  use `rag-pipeline-triage` first.
+- The task is only API transport or SDK failure before search boundaries are known; use
+  `api-failure-triage`.
+- The task asks for live production vector dumps containing sensitive text, embeddings, customer
+  documents, or private prompts. Use redacted hashes, ids, dimensions, norms, and aggregate metrics.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Retrieval symptom classification: ingestion missing, write not visible, wrong results, empty
+  results, low recall, tenant leak, duplicate chunks, stale deletes, slow search, reranker drift, or
+  generated answer drift.
+- Query contract ledger: query text or safe fixture id, embedding model and revision, preprocessing
+  version, vector dimension, vector norm, metric, collection, namespace, tenant, named vector,
+  filters, `top_k`, candidate count, consistency level, ANN parameters, hybrid weights, and reranker
+  settings.
+- Ingestion ledger: source id, chunk id, deterministic vector id, embedding version, payload shape,
+  write count, unique id count, direct lookup count, indexed count, deleted or tombstoned count, and
+  visibility lag.
+- Quality ledger: golden queries, expected ids, acceptable alternatives, exact-search result,
+  ANN result, recall at k, MRR, empty rate, duplicate rate, filtered result count, and before/after
+  comparison.
+- Performance ledger: cold versus warm latency, p50, p95, p99, queue wait, DB search time, reranker
+  time, payload size, filter selectivity, shard distribution, compaction or indexing work, memory,
+  disk, and retry behavior.
+- Privacy ledger: raw text, vectors, prompts, document ids, tenant ids, provider payloads, and
+  whether evidence can be safely stored as ids, hashes, summaries, or aggregate metrics.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked.
+- Raw embeddings, raw document text, prompts, and tenant-identifying payloads are not copied into
+  docs, tests, commits, or reports unless they are safe synthetic fixtures.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten embedding versioning, preprocessing versioning, vector validation, deterministic
+  IDs, namespace or tenant selection, metadata indexes, filter construction, exact-search checks,
+  ANN parameters, reranker candidate counts, golden-set tests, metrics, docs, fixtures, and
+  retrieval contract tests.
+- Add focused synthetic fixtures that encode expected retrieval behavior, filtered retrieval,
+  tenant separation, duplicate handling, and exact-versus-ANN comparison.
+- Do not change embedding models, rebuild large indexes, tune ANN parameters, disable filters, widen
+  tenants, bypass authorization, or dump production vectors without explicit scope and evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the symptom first: ingestion missing, write-not-visible, wrong result, empty result,
+   stale delete, duplicate chunks, tenant leak, slow search, reranker drift, or answer generation.
+2. Build the query contract ledger before tuning. Include model revision, preprocessing, dimension,
+   norm, metric, collection, namespace, named vector, filters, `top_k`, ANN parameters, hybrid
+   weights, reranker settings, and consistency level.
+3. Validate vector shape at ingestion and query time. Reject wrong dimension, NaN, infinities,
+   all-zero vectors, extreme norms, and model or preprocessing version mismatches.
+4. Keep embedding model identity exact. Model name alone is not enough; include revision, tokenizer,
+   pooling, prefix policy, max length, HTML cleanup, chunking, and normalization.
+5. Compare exact search with approximate search on the same query and filter. If exact search is
+   wrong, stop tuning ANN and inspect embeddings, preprocessing, metric, payload, and expectations.
+6. Compare filter-free search, filter-only count, filtered exact search, and filtered ANN search.
+   Empty filtered results often mean filter construction, metadata typing, payload indexing, or
+   post-filter candidate loss rather than bad embeddings.
+7. Confirm collection, namespace, tenant, alias, and named vector. Directly inspect the problem id
+   or safe synthetic id in the same search surface the app uses.
+8. Check deterministic upsert ids. Source id, chunk index, tenant, and embedding version should not
+   accidentally duplicate chunks or overwrite all chunks with one id.
+9. Separate write success from search visibility. Check direct lookup, exact search, ANN search,
+   indexed count, consistency, segment state, and visibility lag.
+10. Check deletes and updates. Deletion marks, tombstones, compaction, vacuum, stale segments, and
+    old chunks can keep appearing after API success.
+11. Review metric and normalization. Cosine, dot product, and L2 are different contracts unless
+    the vectors are intentionally normalized and the index operator matches.
+12. Tune ANN only after the exact and filter contracts are correct. Evaluate recall and p95 latency
+    across parameter sweeps instead of changing one value blindly.
+13. Treat build-time index parameters as recall ceilings. If search-time parameters cannot recover
+    recall, the index may need rebuild policy, not a larger query knob.
+14. Review quantization and rescoring. Compare full-precision exact results with compressed-index
+    candidates and confirm enough candidates reach full-precision reranking.
+15. For hybrid search, store dense score, sparse or keyword score, normalized score, fusion method,
+    and final score. Do not add incompatible raw scores directly without a deliberate combiner.
+16. For reranking, record pre-rerank and post-rerank ids and ranks. If the right document never
+    enters the candidate set, the reranker cannot recover it.
+17. Avoid deep ANN pagination as a product contract. Use cursor, filters, grouping, or ordinary
+    sorted indexes for deep browsing instead of pretending vector search has cheap random offsets.
+18. Split cold and warm latency, server search time and client wait, vector DB time and reranker
+    time, and single-query latency from concurrent load.
+19. Inspect shard, replica, segment, compaction, flush, indexing, memory, disk, and cache state when
+    p99 or intermittent quality varies across nodes.
+20. Add a golden-set gate when the project has a test surface. Include easy, hard, filtered,
+    tenant-scoped, rare-name, synonym, short-query, long-query, and sparse-data cases.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The retrieval symptom, query contract, ingestion contract, quality ledger, performance ledger, and
+  privacy boundary are explicit.
+- Exact search, ANN, filters, metadata, namespaces, tenants, named vectors, IDs, deletes, metric,
+  normalization, quantization, hybrid search, reranking, shards, consistency, and latency are fixed
+  or reported where relevant.
+- Search quality claims are backed by golden-set, exact-versus-ANN, configured-test, static review,
+  or manual-only evidence.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured tests that cover retrieval contract, tenant isolation, filters,
+golden-set metrics, deterministic ids, and docs or template surfaces. Report missing vector DB,
+embedding provider, exact-search, ANN recall, reranker, load, or production-index evidence instead
+of inventing live diagnostics.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the query contract cannot be reconstructed, report the missing fields before changing model,
+  filter, or ANN settings.
+- If evidence contains raw text, embeddings, prompts, personal data, or tenant-identifying data,
+  redact to ids, hashes, dimensions, norms, and aggregate metrics.
+- If the fix requires model replacement, re-embedding, index rebuild, production data dump, or live
+  vector DB access outside the command contract, report the manual boundary.
+- If configured verification fails, preserve the failing intent and output tail, then fix only the
+  localized retrieval contract or test expectation.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Vector search integrity reviewed
+- Retrieval symptom, query contract, ingestion ledger, quality ledger, performance ledger, and
+  privacy boundary
+- Exact versus ANN, filter, metadata, namespace, tenant, id, delete, metric, normalization,
+  quantization, hybrid, reranker, shard, consistency, and latency findings
+- Fix applied or recommended
+- Evidence level: golden-set evidence, configured-test evidence, static review risk, manual-only,
+  missing, or not applicable
+- Command intents run
+- Skipped vector diagnostics and reasons
+- Remaining vector search risk

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.version-freshness-check
 locale: en
 canonical: true
-revision: 7
+revision: 8
 lifecycle: mustflow-owned
 authority: procedure
 name: version-freshness-check
@@ -34,7 +34,7 @@ Prevent agents from writing stale external version references from memory, while
 
 - Generated or edited files introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, toolchain versions, setup actions, scaffold commands, install commands, or migration examples.
 - CI workflows, release workflows, Dockerfiles, package metadata, lockfiles, runtime files, framework configuration, README examples, docs, tests, fixtures, or templates mention external versions such as GitHub Actions refs, Node, Bun, Deno, Python, Rust, Tauri, Astro, Next, SvelteKit, Electron, Docker images, package managers, SDKs, plugins, or generators.
-- Python wording mentions current/stable/support status, Python 3.14+ standard-library APIs, runtime flags, changed default behavior, security defaults, or examples that depend on `requires-python`.
+- Python wording mentions current/stable/support status, Python 3.14+ or 3.15+ syntax, standard-library APIs, runtime flags, changed default behavior, security defaults, or examples that depend on `requires-python`.
 - TypeScript wording mentions current/stable/RC/nightly status for TypeScript 6, TypeScript 7, `@typescript/typescript6`, `tsc6`, `typescript@rc`, `@typescript/native-preview`, `tsgo`, compiler API compatibility, or migration readiness.
 - Go wording mentions current/stable/support status, Go release numbers, `go.mod` language version behavior, `toolchain` behavior, standard-library APIs, `GOEXPERIMENT`, runtime defaults, container behavior, JSON experiments, or examples that depend on a specific Go version.
 - Rust wording mentions current/stable/support status, Rust release numbers, `rust-version`, edition behavior, `rust-toolchain`, Cargo resolver or workspace behavior, standard-library APIs, compiler lints, target behavior, release profiles, or examples that depend on a specific Rust version.
@@ -94,19 +94,20 @@ Prevent agents from writing stale external version references from memory, while
 10. For patch, security-minimum, and low-risk minor differences, update only when the declaration, examples, lockfile policy, and verification surface can stay aligned. Otherwise report the proposed change and leave the pinned value unchanged.
 11. For GitHub Actions and CI tools, review the action source, major tag policy, runtime support, cache behavior, permissions, and organization pinning rule. Do not assume a newer major is safe only because it exists.
 12. For framework and runtime majors such as Astro, Tauri, Electron, Next, SvelteKit, Node, Bun, Deno, Python, Rust, or Java, check migration notes, config schema, plugin and adapter compatibility, generated files, security model, deployment target, and rollback path before recommending a major change.
-13. For Python standard-library or runtime-behavior claims, refresh official Python documentation before writing durable wording. Check `requires-python`, CI/runtime matrices, and container images before using or recommending version-gated features such as Python 3.14+ `map(strict=True)`, `functools.Placeholder`, `heapq` max-heap helpers, import-timing flag behavior, or changed security defaults.
+13. For Python standard-library or runtime-behavior claims, refresh official Python documentation before writing durable wording. Check `requires-python`, CI/runtime matrices, and container images before using or recommending Python 3.14+ standard-library APIs or version-gated features such as template string literals, `annotationlib`, Python 3.14+ `map(strict=True)`, `functools.Placeholder`, `heapq` max-heap helpers, import-timing flag behavior, `finally` flow-control warnings, or changed security defaults.
 14. For Python examples that use newer standard-library APIs, either keep the example behind an explicit runtime floor or provide a supported fallback. Do not call a Python 3.14-only API a general Python best practice when the repository declares lower support.
-15. For TypeScript 6 and 7 claims, refresh official TypeScript sources before writing durable wording. Treat TS6 stable API track (`@typescript/typescript6`, `tsc6`), TS7 RC compiler track (`typescript@rc`, `tsc`), TS7 nightly track (`@typescript/native-preview`, `tsgo`), and future TS7 stable `typescript` behavior as distinct tracks. Do not call RC or nightly output "latest stable TypeScript" just because it is newer.
-16. For TypeScript examples, make the selected track explicit: TS6 API compatibility, TS7 RC compiler verification, TS7 nightly comparison, editor preview, or repository adoption. If the project has compiler API consumers, transformers, framework wrappers, or declaration snapshots, classify the reference as migration-sensitive and keep API consumers on the TS6 API track until support is explicit.
-17. For Go release, toolchain, standard-library, runtime, or experiment claims, refresh official Go release notes or package documentation before writing durable wording. Check the repository's `go` directive, `toolchain` directive, CI/runtime matrix, and container target before using or recommending version-gated features such as expression operands to `new`, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `ReverseProxy.Rewrite`, container-aware `GOMAXPROCS`, goroutine leak profiles, `encoding/json/v2`, or `GOEXPERIMENT` APIs.
-18. For Go examples that use newer standard-library APIs or runtime defaults, either keep the example behind an explicit Go version floor or provide a supported fallback. Do not call an experimental `GOEXPERIMENT` feature or a newer `go` directive behavior a general Go best practice when the repository declares lower support.
-19. For Rust release, toolchain, standard-library, Cargo, edition, lint, target, or MSRV claims, refresh official Rust release notes, standard-library docs, the Cargo Book, Rust Reference, or rustc book before writing durable wording. Check `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, docs.rs metadata, and crate publish policy before using or recommending version-gated features such as let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `resolver = "2"`, Rust 2024 `unsafe_op_in_unsafe_fn`, or release-profile defaults.
-20. For Rust examples that use newer language or standard-library APIs, either keep the example behind an explicit Rust version floor or provide a supported fallback. Use an API-by-API MSRV ledger for features such as `cfg_select!`, match `if let` guards, `core::range` items, `Vec::push_mut`, `assert_matches!`, and `debug_assert_matches!`; do not collapse them into a single "latest Rust" bucket, and do not treat nightly-only behavior or target-specific linker behavior as stable without explicit evidence.
-21. For HTTP standards, browser APIs, proxy defaults, CDN defaults, and transport support claims, prefer official RFCs, standards bodies, MDN or browser vendor docs, and vendor-owned proxy/CDN documentation. Keep WebTransport, compression dictionary transport, zstd content coding, SSE/EventSource, HTTP/2, HTTP/3, QUIC, and proxy-buffering claims track-specific and dated when support is changing.
-22. For HTTP delivery examples that depend on newer or unevenly supported behavior, require feature detection, fallback behavior, or explicit deployment constraints. Do not present WebTransport, dictionary compression, or zstd negotiation as a universal default when the project still needs browsers, proxies, CDNs, or networks that may not support it.
-23. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
-24. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
-25. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, TypeScript compiler-track, Go toolchain or runtime support, Rust toolchain or MSRV support, HTTP delivery compatibility, or security-sensitive changes.
+15. For Python 3.15+ claims, keep beta, release-candidate, and stable tracks separate. Refresh official docs before using explicit lazy imports, built-in `frozendict`, built-in `sentinel`, unpacking comprehensions, typed `TypedDict` extra items, startup configuration files, or changed encoding behavior in durable examples.
+16. For TypeScript 6 and 7 claims, refresh official TypeScript sources before writing durable wording. Treat TS6 stable API track (`@typescript/typescript6`, `tsc6`), TS7 RC compiler track (`typescript@rc`, `tsc`), TS7 nightly track (`@typescript/native-preview`, `tsgo`), and future TS7 stable `typescript` behavior as distinct tracks. Do not call RC or nightly output "latest stable TypeScript" just because it is newer.
+17. For TypeScript examples, make the selected track explicit: TS6 API compatibility, TS7 RC compiler verification, TS7 nightly comparison, editor preview, or repository adoption. If the project has compiler API consumers, transformers, framework wrappers, or declaration snapshots, classify the reference as migration-sensitive and keep API consumers on the TS6 API track until support is explicit. Check exact support before relying on `rootDir` defaults, ambient `types` defaults, import attributes, subpath imports, `import defer`, `using`, or `await using`.
+18. For Go release, toolchain, standard-library, runtime, or experiment claims, refresh official Go release notes or package documentation before writing durable wording. Check the repository's `go` directive, `toolchain` directive, CI/runtime matrix, and container target before using or recommending version-gated features such as expression operands to `new`, range-over-function iterators, generic type aliases, reflect iterator methods, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `ReverseProxy.Rewrite`, container-aware `GOMAXPROCS`, goroutine leak profiles, `encoding/json/v2`, or `GOEXPERIMENT` APIs.
+19. For Go examples that use newer standard-library APIs or runtime defaults, either keep the example behind an explicit Go version floor or provide a supported fallback. Do not call an experimental `GOEXPERIMENT` feature or a newer `go` directive behavior a general Go best practice when the repository declares lower support.
+20. For Rust release, toolchain, standard-library, Cargo, edition, lint, target, or MSRV claims, refresh official Rust release notes, standard-library docs, the Cargo Book, Rust Reference, or rustc book before writing durable wording. Check `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, docs.rs metadata, and crate publish policy before using or recommending version-gated features such as let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `resolver = "2"`, Rust 2024 `unsafe extern`, unsafe attributes, Rust 2024 `unsafe_op_in_unsafe_fn`, temporary drop-scope changes, macro fragment behavior, or release-profile defaults.
+21. For Rust examples that use newer language or standard-library APIs, either keep the example behind an explicit Rust version floor or provide a supported fallback. Use an API-by-API MSRV ledger for features such as `cfg_select!`, match `if let` guards, `core::range` items, `Vec::push_mut`, `assert_matches!`, and `debug_assert_matches!`; do not collapse them into a single "latest Rust" bucket, and do not treat nightly-only behavior or target-specific linker behavior as stable without explicit evidence.
+22. For HTTP standards, browser APIs, proxy defaults, CDN defaults, and transport support claims, prefer official RFCs, standards bodies, MDN or browser vendor docs, and vendor-owned proxy/CDN documentation. Keep WebTransport, compression dictionary transport, zstd content coding, SSE/EventSource, HTTP/2, HTTP/3, QUIC, and proxy-buffering claims track-specific and dated when support is changing.
+23. For HTTP delivery examples that depend on newer or unevenly supported behavior, require feature detection, fallback behavior, or explicit deployment constraints. Do not present WebTransport, dictionary compression, or zstd negotiation as a universal default when the project still needs browsers, proxies, CDNs, or networks that may not support it.
+24. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
+25. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
+26. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, TypeScript compiler-track, Go toolchain or runtime support, Rust toolchain or MSRV support, HTTP delivery compatibility, or security-sensitive changes.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -116,6 +117,7 @@ Prevent agents from writing stale external version references from memory, while
 - Repository-pinned versions are preserved unless the task, policy, and compatibility classification support changing them.
 - Major or migration-required changes are either explicitly approved, deferred with a recommendation, or left unchanged with the risk reported.
 - Python standard-library examples and runtime-default claims match the declared Python support matrix or name the required runtime floor.
+- Python template strings, annotation inspection, explicit lazy imports, immutable mappings, sentinels, and advanced `TypedDict` shape claims are either official-source checked or omitted.
 - TypeScript 6 stable API, TypeScript 7 RC compiler, TypeScript 7 nightly, and future stable TypeScript tracks are not collapsed into one generic "latest TypeScript" claim.
 - Go release, `go.mod` language version, standard-library API, runtime-default, and `GOEXPERIMENT` claims match the declared Go support matrix or name the required runtime floor.
 - Rust release, `rust-version`, edition, standard-library API, Cargo resolver, lint-default, target, and nightly/stable claims match the declared Rust support matrix or name the required API-specific runtime floor.