mustflow 2.84.0 → 2.99.0

package/templates/default/locales/en/.mustflow/skills/rag-pipeline-triage/SKILL.md

@@ -0,0 +1,206 @@
+---
+mustflow_doc: skill.rag-pipeline-triage
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: rag-pipeline-triage
+description: Apply this skill when a RAG, knowledge-base answer, grounded chat, citation answer, retrieval-augmented support bot, or document QA flow is wrong, stale, unsupported, slow, leaking data, over-refusing, or not yet localized to ingestion, parsing, chunking, retrieval, filtering, reranking, context assembly, prompt construction, generation, citation validation, or answerability boundaries.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.rag-pipeline-triage
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# RAG Pipeline Triage
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Localize RAG failures by splitting ingestion, retrieval, context assembly, and answer generation
+before changing models, prompts, chunk sizes, or vector settings.
+
+The first question is not "is the model bad?" It is "did the correct evidence exist, get retrieved,
+survive filtering and context assembly, and constrain the answer?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A RAG answer, knowledge-base answer, grounded support bot, citation answer, document QA flow, or
+  retrieval-augmented agent is wrong, stale, unsupported, too slow, leaking data, citing the wrong
+  source, refusing answerable questions, or answering unanswerable questions.
+- The failure is not yet localized to source availability, parsing, chunking, embedding, indexing,
+  filters, vector or keyword retrieval, hybrid fusion, reranking, context packing, prompt assembly,
+  generation, validators, citations, answerability, or access control.
+- A review would otherwise tune the model, top-k, chunk size, reranker, or prompt before proving
+  which RAG layer failed.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The failure is already localized to retrieval mechanics, filters, ANN, embeddings, or vector DB
+  behavior; use `vector-search-integrity-review`.
+- The failure is already localized to unsupported claims, citations, answerability, evidence IDs, or
+  validators; use `llm-hallucination-control-review`.
+- The failure is already localized to prompt structure, tool policy, output schema, or model runtime
+  settings; use `prompt-contract-quality-review`.
+- The task asks for production document dumps, raw embeddings, private prompts, customer text, or
+  tenant-identifying data. Use ids, hashes, safe synthetic fixtures, aggregate metrics, and redacted
+  traces.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Symptom classification: missing correct document, correct document retrieved but unused, stale
+  answer, unsupported answer, wrong citation, access-control leak, over-refusal, under-refusal,
+  latency, cost, or nondeterministic result.
+- Trace ledger: trace id, original question, normalized question, rewritten query, user or tenant
+  context, filters, embedding model version, index version, candidate ids and scores, reranker
+  output, final context ids and order, prompt version, model version, answer, citations, validators,
+  latency, and cost when safe.
+- Source ledger: authoritative source availability, parsed text, chunk boundaries, metadata, title,
+  section path, version, effective dates, stale or deleted documents, duplicates, and conflicting
+  sources.
+- Comparison ledger: no-retrieval answer, retrieved-context answer, human-selected gold-context
+  answer, exact or keyword search result, vector search result, hybrid result, and expected
+  answerability state.
+- Eval ledger: real failed queries, unanswerable questions, stale-doc cases, conflicting-doc cases,
+  similar-name cases, IDs and error codes, multilingual or typo cases, multi-hop cases, and
+  unauthorized-doc cases.
+- Privacy ledger: raw text, prompts, embeddings, tenant ids, user ids, provider payloads, and which
+  evidence can be stored or reported safely.
+
+<!-- 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 documents, prompts, embeddings, user data, 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 trace fields, fixture queries, parsing checks, chunk metadata, duplicate or stale
+  source handling, retrieval comparisons, filter checks, context-packing rules, prompt source
+  separation, citation validators, answerability states, dirty eval fixtures, metrics, docs, and
+  directly synchronized templates.
+- Add safe synthetic fixtures for missing-doc, correct-doc-unused, stale-doc, conflicting-doc,
+  unauthorized-doc, exact-id, keyword, vector, hybrid, reranker, citation, and abstain behavior.
+- Do not change models, re-embed data, rebuild production indexes, widen access filters, disable
+  authorization, dump private corpora, or claim quality improvement before the failing layer is
+  localized.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the symptom. Separate no source, bad parsing, bad chunking, retrieval miss, filter miss,
+   reranker loss, context truncation, prompt misuse, generation drift, false citation, stale answer,
+   access leak, latency, cost, and answerability errors.
+2. Preserve one safe end-to-end trace. Keep ids, versions, scores, context order, prompt version,
+   model version, validator result, latency, and cost. Redact raw sensitive content.
+3. Prove the answer exists in the source of truth. Do not tune retrieval for an answer that is not in
+   the indexed corpus or an allowed tool.
+4. Inspect parsed text before original documents. Tables, PDFs, multi-column pages, code blocks,
+   headers, footers, and OCR can be broken even when the original file looks correct.
+5. Inspect chunk boundaries and metadata. Verify title, parent section, version, dates, audience,
+   product, source authority, and neighboring context survive into chunks or parent retrieval.
+6. Compare source versions and deletes. Duplicates, obsolete documents, tombstones, and conflicting
+   effective dates must not be silently mixed into one answer.
+7. Run the isolation comparison when evidence is available: no retrieval, current retrieved context,
+   and human-selected gold context. Gold-context failure points to generation or prompt; current
+   context failure with gold success points to retrieval or context assembly.
+8. Compare keyword, vector, hybrid, and exact-id retrieval by data shape. IDs, error codes, SKUs,
+   names, dates, and numbers need exact or lexical safeguards; semantic questions may need vector or
+   hybrid retrieval.
+9. Check filters before blaming embeddings. Record pre-filter candidate count, post-filter count,
+   tenant and permission filters, metadata types, time zones, empty arrays, case sensitivity, and
+   stale policy copies.
+10. Check reranker candidate starvation. If the correct source never enters the candidate set, the
+    reranker cannot fix it. If it enters and then drops, inspect reranker inputs and scoring.
+11. Check context assembly. Verify `top_k`, score thresholds, source order, truncation, deduping,
+    conflict handling, source authority, and whether important evidence is buried or cut off.
+12. Check prompt construction. User input, retrieved text, examples, tool observations, and system or
+    developer instructions must remain separated. Retrieved text is data, not authority.
+13. Check answerability and abstain behavior. Track no-evidence, low-confidence, conflicting-source,
+    stale-source, access-denied, tool-failed, and needs-human states separately.
+14. Validate citations claim-by-claim. A citation id proves nothing unless the cited chunk supports
+    the specific generated claim.
+15. Measure each layer separately. Track parsing success, index freshness, Recall@k, MRR or nDCG,
+    rerank survival, context token budget, answer accuracy, citation accuracy, abstain accuracy,
+    access leaks, and retrieval/rerank/generation latency and cost.
+16. Use dirty eval cases from real failures. Include typos, abbreviations, multilingual questions,
+    unanswerable questions, date-sensitive questions, similar names, product codes, multi-hop
+    questions, unauthorized documents, stale documents, and conflicting documents.
+17. Apply the smallest localized fix and switch to the narrower matching skill for retrieval,
+    hallucination control, prompt contract, token cost, latency, access control, or prompt-injection
+    defense once the boundary is known.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The RAG failure is localized to ingestion, parsing, chunking, indexing, retrieval, filters,
+  reranking, context assembly, prompt construction, generation, citation validation, answerability,
+  access control, or a named evidence gap.
+- Trace, source, comparison, eval, metric, and privacy ledgers are explicit where relevant.
+- Model, prompt, chunk, top-k, reranker, or index changes are justified by layer evidence rather than
+  by general "RAG quality" claims.
+
+<!-- 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 eval, fixture, schema, docs, package, or release check that proves
+the localized RAG boundary. Report missing retrieval, gold-context, citation, answerability,
+privacy, latency, or production-index evidence instead of inventing live diagnostics.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the end-to-end trace cannot be reconstructed, report the missing trace fields before tuning
+  models, prompts, chunks, filters, or retrieval parameters.
+- If evidence contains raw private text, embeddings, prompts, personal data, or tenant-identifying
+  data, redact to ids, hashes, dimensions, scores, snippets from safe fixtures, and aggregate
+  metrics.
+- If the fix requires model replacement, re-embedding, index rebuild, private corpus access, or live
+  provider calls outside the command contract, report the manual boundary.
+- If retrieved text can inject instructions, pause RAG quality work and apply
+  `external-prompt-injection-defense`.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- RAG pipeline triaged
+- Symptom classification and localized boundary
+- Trace, source, comparison, eval, metric, and privacy ledgers
+- Ingestion, parsing, chunking, retrieval, filter, rerank, context, prompt, generation, citation,
+  answerability, access-control, latency, and cost findings
+- Fix applied or recommended
+- Evidence level: end-to-end trace, gold-context comparison, configured-test evidence, static review
+  risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped diagnostics and reasons
+- Remaining RAG pipeline risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -78,6 +78,12 @@ route_type = "adjunct"
 priority = 85
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "mustflow_docs_change", "mustflow_config_change", "package_metadata_change", "release_risk"]
 
+[routes."next-action-menu"]
+category = "workflow_contracts"
+route_type = "adjunct"
+priority = 72
+applies_to_reasons = ["unknown_change", "docs_change", "workflow_change", "mustflow_docs_change", "package_metadata_change"]
+
 [routes."proactive-risk-surfacing"]
 category = "workflow_contracts"
 route_type = "event"
@@ -234,6 +240,30 @@ route_type = "adjunct"
 priority = 73
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change"]
 
+[routes."api-failure-triage"]
+category = "bug_failure"
+route_type = "primary"
+priority = 72
+applies_to_reasons = ["unknown_change", "command_failure", "behavior_change", "public_api_change", "performance_change", "data_change", "docs_change"]
+
+[routes."auth-flow-triage"]
+category = "bug_failure"
+route_type = "primary"
+priority = 74
+applies_to_reasons = ["unknown_change", "command_failure", "behavior_change", "security_change", "privacy_change", "data_change", "docs_change"]
+
+[routes."docker-runtime-triage"]
+category = "bug_failure"
+route_type = "primary"
+priority = 73
+applies_to_reasons = ["unknown_change", "command_failure", "behavior_change", "performance_change", "data_change", "docs_change"]
+
+[routes."ci-pipeline-triage"]
+category = "bug_failure"
+route_type = "primary"
+priority = 75
+applies_to_reasons = ["unknown_change", "command_failure", "workflow_change", "mustflow_config_change", "docs_change", "test_change", "package_metadata_change", "release_risk", "performance_change", "security_change"]
+
 [routes."app-startup-performance-review"]
 category = "general_code"
 route_type = "adjunct"
@@ -406,7 +436,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "packag
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "migration_change", "security_change", "package_metadata_change", "release_risk"]
 
 [routes."docker-code-change"]
 category = "general_code"
@@ -418,7 +448,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "securi
 category = "general_code"
 route_type = "primary"
 priority = 82
-applies_to_reasons = ["code_change", "public_api_change", "docs_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "docs_change", "test_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change"]
 
 [routes."backend-reliability-change"]
 category = "general_code"
@@ -436,7 +466,7 @@ applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "pe
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "package_metadata_change"]
 
 [routes."javascript-code-change"]
 category = "general_code"
@@ -522,6 +552,12 @@ route_type = "primary"
 priority = 67
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
+[routes."rag-pipeline-triage"]
+category = "general_code"
+route_type = "primary"
+priority = 72
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
+
 [routes."llm-token-cost-control-review"]
 category = "general_code"
 route_type = "primary"
@@ -618,6 +654,18 @@ route_type = "primary"
 priority = 86
 applies_to_reasons = ["code_change", "data_change", "migration_change", "behavior_change", "public_api_change", "test_change", "docs_change", "security_change", "performance_change"]
 
+[routes."search-index-integrity-review"]
+category = "data_external"
+route_type = "primary"
+priority = 74
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "data_change", "docs_change", "package_metadata_change", "release_risk"]
+
+[routes."vector-search-integrity-review"]
+category = "data_external"
+route_type = "primary"
+priority = 73
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "data_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."dependency-upgrade-review"]
 category = "data_external"
 route_type = "primary"
@@ -652,13 +700,13 @@ applies_to_reasons = ["code_change", "security_change", "migration_change"]
 category = "data_external"
 route_type = "primary"
 priority = 55
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "cross_cutting_code_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "cross_cutting_code_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change"]
 
 [routes."tauri-code-change"]
 category = "data_external"
 route_type = "primary"
 priority = 90
-applies_to_reasons = ["code_change", "security_change", "public_api_change"]
+applies_to_reasons = ["code_change", "behavior_change", "ui_change", "security_change", "privacy_change", "data_change", "public_api_change", "package_metadata_change", "release_risk"]
 
 [routes."process-execution-safety"]
 category = "data_external"
@@ -696,6 +744,12 @@ route_type = "adjunct"
 priority = 40
 applies_to_reasons = ["test_change", "behavior_change"]
 
+[routes."test-suite-performance-review"]
+category = "tests"
+route_type = "primary"
+priority = 58
+applies_to_reasons = ["performance_change", "test_change", "workflow_change", "mustflow_config_change", "package_metadata_change", "unknown_change"]
+
 [routes."test-maintenance"]
 category = "tests"
 route_type = "primary"
@@ -828,6 +882,12 @@ route_type = "adjunct"
 priority = 81
 applies_to_reasons = ["ui_change", "performance_change", "behavior_change", "code_change", "web_asset_change"]
 
+[routes."motion-system-contract-review"]
+category = "ui_assets"
+route_type = "adjunct"
+priority = 83
+applies_to_reasons = ["ui_change", "behavior_change", "code_change", "performance_change", "test_change", "docs_change", "web_asset_change"]
+
 [routes."frontend-state-ownership-review"]
 category = "ui_assets"
 route_type = "adjunct"
@@ -880,13 +940,13 @@ applies_to_reasons = ["ui_change", "docs_change", "code_change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "public_api_change", "migration_change", "package_metadata_change"]
 
 [routes."unocss-code-change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "migration_change", "performance_change", "package_metadata_change"]
 
 [routes."flutter-code-change"]
 category = "ui_assets"
@@ -898,13 +958,13 @@ applies_to_reasons = ["ui_change", "code_change", "public_api_change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "migration_change", "package_metadata_change"]
 
 [routes."svelte-code-change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "code_change", "public_api_change"]
+applies_to_reasons = ["ui_change", "code_change", "behavior_change", "public_api_change", "data_change", "security_change", "privacy_change", "test_change", "package_metadata_change"]
 
 [routes."pattern-scout"]
 category = "architecture_patterns"

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.rust-code-change
 locale: en
 canonical: true
-revision: 5
+revision: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: rust-code-change
@@ -101,9 +101,14 @@ instead of treated as incidental.
    - before using newer APIs, build an API-specific MSRV ledger instead of relying on a broad release bucket. Examples that need exact checking include `cfg_select!`, match `if let` guards, `core::range` items, `Vec::push_mut`, `assert_matches!`, and `debug_assert_matches!`;
    - do not use any newer API unless the declared MSRV, edition, CI matrix, docs.rs metadata, and toolchain path support that exact API;
    - keep experimental, nightly-only, target-specific, or edition-specific behavior behind explicit gates or fallbacks instead of calling it general Rust advice.
-5. Prefer flatter control flow when the MSRV supports it: use `let else` for early validation, let chains for related optional/result guards, and match `if let` guards for state-machine refinements. Remember that guard patterns do not satisfy match exhaustiveness; keep the fallback arm meaningful.
-6. In tests, prefer `assert_matches!` over `assert!(matches!(...))` when the MSRV supports it and the failed value has useful `Debug` output. Import it explicitly from `std` or `core`; do not assume it is in the prelude.
-7. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
+5. For Rust 2024 or edition migration work, review semantics instead of treating the edition as formatting:
+   - inspect `unsafe extern` blocks, unsafe attributes such as exported symbols or custom sections, `unsafe_op_in_unsafe_fn`, and public unsafe docs together;
+   - check `if let` scrutinee temporaries and tail-expression temporaries around locks, `RefCell`, guards, files, network handles, and other `Drop` values;
+   - review macro fragment specifiers, especially expression fragments whose accepted syntax changes by edition, and use older-edition fragments only when the macro intentionally rejects newer forms;
+   - treat automatic edition rewrites as candidate diffs that still need human review of unsafe, macro, pattern, temporary lifetime, docs, and examples.
+6. Prefer flatter control flow when the MSRV supports it: use `let else` for early validation, let chains for related optional/result guards, and match `if let` guards for state-machine refinements. Remember that guard patterns do not satisfy match exhaustiveness; keep the fallback arm meaningful.
+7. In tests, prefer `assert_matches!` over `assert!(matches!(...))` when the MSRV supports it and the failed value has useful `Debug` output. Import it explicitly from `std` or `core`; do not assume it is in the prelude.
+8. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
 8. Before adding `clone`, verify it is a cheap handle clone such as `Arc`, `Rc`, or `Bytes`, a small intentional value clone, or a true independent ownership split. Reject large collection clones, loop clones, clone-then-borrow code, and whole-state clones made only to satisfy `spawn`.
 9. Before adding `Arc<Mutex<_>>`, verify multiple owners truly need shared mutable state. For read-mostly snapshots, prefer ownership-preserving choices such as `Arc::make_mut`, immutable swaps, or explicit reload boundaries. Keep critical sections short, document lock order when relevant, and do not hold a lock guard across `.await`, I/O, callbacks, or user code.
 10. Choose initialization primitives by input and failure semantics: use `LazyLock` for no-argument static lazy values that may poison permanently on panic, and `OnceLock` when boot-time or test-time code supplies the value or panic poisoning must not become the recovery policy.
@@ -135,6 +140,7 @@ Reject or revise the patch when any of these appear without strong local justifi
 - New large `clone()` calls, clone-then-borrow code, loop clones, or state clones used only to appease ownership errors.
 - New `Arc<Mutex<AppState>>`-style shared bags, locks held across `.await`, or async I/O resources shared mainly by mutex.
 - New version-gated Rust API usage without API-specific MSRV, `rust-version`, edition, toolchain, CI, or fallback evidence.
+- Rust 2024 edition changes accepted without reviewing unsafe extern blocks, unsafe attributes, `unsafe_op_in_unsafe_fn`, temporary drop scopes, and macro fragment behavior where those surfaces exist.
 - New `LazyLock` initialization for recoverable runtime configuration where permanent panic poisoning would be the wrong failure policy.
 - New `spare_capacity_mut` plus `set_len` without a narrow, proven initialization invariant.
 - New public `impl Trait`, `Deref`, GAT, workspace resolver, feature, or `rust-version` change without public API and compatibility review.

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

@@ -0,0 +1,181 @@
+---
+mustflow_doc: skill.search-index-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: search-index-integrity-review
+description: Apply this skill when keyword search, full-text search, Elasticsearch, OpenSearch, Lucene-style indexes, search APIs, indexing pipelines, aliases, bulk indexing, refresh visibility, analyzers, mappings, synonyms, autocomplete, pagination, shard failures, search quality, or search performance are created, changed, reviewed, or failing. Use vector-search-integrity-review first for vector-only or semantic retrieval mechanics, and use rag-pipeline-triage first when a RAG failure is not yet localized to search retrieval.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.search-index-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Search Index Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review search as an end-to-end index and query contract, not as "the cluster is green."
+
+The core question is whether a source record can be changed, accepted by the indexing path, become visible through the same API users call, rank as expected, stay isolated by tenant and filters, and remain fast under realistic query shapes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates or changes search ingestion, indexing jobs, bulk writes, index aliases, refresh policy, index templates, mappings, analyzers, keyword or text fields, synonyms, autocomplete, query builders, filters, sort, pagination, highlighting, source filtering, result shaping, search caches, or search observability.
+- Search is missing documents, returning stale data, returning partial results, ranking the wrong document, showing zero results, leaking tenant data, slowing down, timing out, rejecting writes, or behaving differently through direct search, backend API, and UI.
+- A review needs index visibility, read/write alias, bulk item errors, shard failure, mapping drift, analyzer, synonym, golden-set, p95 or p99 latency, slow-log, query fingerprint, shard fan-out, cache, refresh, segment merge, disk watermark, or search SLO evidence.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only vector, semantic, embedding, ANN, reranking, or vector hybrid mechanics; use `vector-search-integrity-review` first.
+- 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, CORS, SDK, gateway, auth, or cache failure before the search boundary is known; use `api-failure-triage`.
+- The task is ordinary database query performance with no search index, analyzer, ranking, alias, or indexing path.
+- The requested evidence would require dumping private queries, customer documents, raw personal data, or production result pages into docs, tests, commits, or reports. Use safe IDs, hashes, synthetic fixtures, aggregate counts, or redacted examples.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Symptom classification: source not indexed, write not visible, wrong alias, partial shard result, wrong exact match, wrong full-text match, ranking drift, zero results, stale delete, tenant leak, autocomplete failure, deep-page failure, slow query, bulk rejection, mapping conflict, or UI/API mismatch.
+- Source-to-search ledger: source id, tenant, category, status, update time, indexing request time, bulk item result, indexed document id, direct lookup result, first search-visible time, rank, delete or tombstone state, and visibility lag.
+- Query contract ledger: user-facing API path, direct search request, API-transformed request, UI result shaping, index or alias, tenant and permission filters, analyzed fields, exact fields, sort, pagination mode, source fields, highlight fields, cache state, and expected result ids.
+- Index contract ledger: read alias, write alias, index templates, mappings, analyzers, normalizers, synonym sets, dynamic mapping policy, refresh policy, shard and replica plan, segment or merge state, disk watermark risk, and rollover or reindex status.
+- Quality ledger: representative queries, expected results, acceptable alternatives, zero-result expectations, Precision@K, Recall@K, MRR or ranking metric, before/after comparison, click or behavior metric limitations, and golden-set fixture status.
+- Performance ledger: cold and warm latency, p50, p95, p99, search server time, API time, UI time, query phase, fetch phase, response size, shard fan-out, thread-pool active/queue/rejected, slow-log or query-profile evidence, cache hit or miss, and retry behavior.
+- Privacy ledger: raw query text, document text, tenant ids, user ids, behavior analytics, search logs, highlights, and whether evidence can be stored safely as synthetic fixtures, 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.
+- Existing search adapters, query builders, index templates, mapping fixtures, golden sets, telemetry, and tests have been searched before changing search behavior.
+- Raw private document text, queries, user behavior, and tenant-identifying payloads are not copied into repository artifacts unless they are safe synthetic fixtures.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten search canaries, indexing ledgers, bulk item error handling, alias checks, mapping and analyzer fixtures, exact-versus-full-text tests, tenant and permission filter tests, golden-set tests, synonym regression tests, pagination guards, query fingerprint metrics, search latency metrics, docs, and directly synchronized templates.
+- Add focused synthetic fixtures that encode expected exact search, full-text search, analyzer behavior, synonym behavior, filtered search, tenant isolation, zero-result behavior, pagination stability, and ranking order.
+- Do not change analyzer, synonym, refresh, alias, shard, cache, or ranking settings blindly. First preserve source-to-search, query-contract, quality, and performance evidence.
+- Do not force every write to refresh immediately unless the product contract explicitly needs synchronous visibility and the indexing cost is accepted.
+- Do not treat search metrics as permission checks. Authorization and tenant filters must remain enforced outside and inside the search query path as the product requires.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the failure before tuning.
+   - Separate source missing, indexing rejected, write not visible, wrong alias, direct lookup mismatch, exact-search mismatch, full-text mismatch, ranking drift, partial shard result, API/UI transformation, stale cache, and slow query.
+   - If the symptom is only "cluster green but users cannot find it," require source-to-search evidence.
+2. Add or inspect a search canary when the system supports it.
+   - A unique canary document should pass through the same write path and user-facing search API as real data.
+   - Record accepted time, first visible time, rank, index or alias, tenant or filter context, and not-found evidence.
+3. Check bulk and ingestion outcomes per item.
+   - A batch-level success is insufficient. Inspect item-level errors, mapping conflicts, version conflicts, rejected writes, shard failures, retries, and failed ids.
+   - Preserve failed source ids or safe hashes so reindex and reconciliation can target real misses.
+4. Reconcile source and index by slices.
+   - Compare counts and checksums by tenant, date, category, status, or other ownership boundary.
+   - Total count equality can hide one tenant missing and another duplicated.
+5. Split direct lookup, exact search, and full-text search.
+   - Direct lookup success with search failure points toward refresh, alias, mapping, analyzer, filter, query, or API transformation.
+   - Exact keyword failure and full-text failure are different contracts.
+6. Check read and write aliases.
+   - Expand aliases to concrete indexes, write index, filters, routing, rollover state, and reindex targets.
+   - A new index receiving writes while search reads the old alias is an indexing visibility bug, not a ranking bug.
+7. Treat partial shard results as correctness evidence.
+   - Record `timed_out`, total shards, successful shards, failed shards, and partial-result policy.
+   - If partial results are not a valid product state, fail the request instead of silently returning incomplete search.
+8. Compare direct search, backend API, and UI output.
+   - Direct search isolates engine behavior.
+   - Backend API adds query builders, permission filters, caches, response shaping, and pagination.
+   - UI adds sorting, dedupe, local cache, page state, and display filtering.
+9. Inspect mappings and analyzers before changing queries.
+   - IDs, emails, status codes, tags, and exact filters usually need keyword-like fields.
+   - Human text usually needs text analysis. Use analyzer evidence or fixtures to prove tokenization for punctuation, case, hyphen, Korean spacing, product codes, and mixed alphanumeric text.
+10. Review synonym and ranking changes against a golden set.
+    - Synonyms can improve one query and break many others.
+    - Compare representative queries before and after; include zero-result, typo, ambiguous, category, brand, long natural-language, and high-value queries.
+11. Explain surprising ranks only for bounded cases.
+    - Inspect why one expected document ranked below another for a small failing sample.
+    - Do not enable expensive explain or profile behavior for broad production traffic.
+12. Separate query, fetch, API, and UI latency.
+    - p50, p95, and p99 must be grouped by search type, index, route, role, tenant class, and query fingerprint where safe.
+    - Fetch time, source size, highlight fields, nested fields, and response shaping can dominate score calculation.
+13. Fingerprint query shapes.
+    - Remove raw IDs, dates, user text, and tenant secrets before grouping.
+    - Store query family, index, role, shard count, cache state, source fields, sort, and filter shape so one feature cannot hide across millions of unique queries.
+14. Check shard fan-out, thread pools, segments, cache, and disk.
+    - Search across hundreds of tiny shards, stale segments, merge backlog, cold caches, search queue rejections, hot shards, and disk watermarks can look like application bugs.
+    - Separate cold and warm measurements; cached benchmarks are not full search evidence.
+15. Review refresh and visibility policy.
+    - Indexing success is not search visibility.
+    - Use synchronous visibility only for writes whose user contract needs it; otherwise define acceptable visibility lag and measure it.
+16. Review pagination and result payloads.
+    - Avoid deep offset pagination as a default product contract.
+    - Use stable tie-breakers for cursor-like pagination, and limit source fields and highlights to what the UI needs.
+17. Keep vector and hybrid boundaries explicit.
+    - If dense vectors, ANN, reranking, hybrid score fusion, or Recall@K drives the failure, switch to `vector-search-integrity-review` for that slice.
+    - If the bug is ordinary keyword indexing, alias, analyzer, source filtering, or shard partials, keep this skill as the primary route.
+18. Define numeric SLOs and destructive drills when in scope.
+    - Useful examples include indexing-to-search-visible p95, search p99, zero-result rate, partial shard failure rate, top-result duplication, golden-set metric, bulk item failure rate, and reindex reconciliation lag.
+    - Live node kills, disk pressure, alias mistakes, mapping conflicts, and mass reindex drills are manual unless the command contract declares them.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The search symptom, source-to-search ledger, query contract, index contract, quality ledger, performance ledger, and privacy boundary are explicit.
+- Bulk item errors, source/index reconciliation, direct lookup, exact search, full-text search, aliases, partial shards, API/UI transformation, mappings, analyzers, synonyms, ranking, pagination, source payload, shard fan-out, thread-pool pressure, cache state, refresh visibility, segments, disk, and SLO evidence are fixed or reported where relevant.
+- Search claims are backed by configured tests, fixtures, golden-set evidence, static review, safe canary evidence, or labeled manual-only or missing.
+
+<!-- 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 search contract, tenant isolation, filters, mappings, analyzer fixtures, golden-set metrics, docs, or template surfaces. Report missing live search cluster, slow-log, reindex, canary, 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 source, alias, filter, analyzer, ranking, or API transformation evidence before changing search settings.
+- If evidence contains raw private query text, document text, personal data, behavior analytics, or tenant-identifying data, redact to synthetic fixtures, ids, hashes, safe summaries, or aggregate metrics.
+- If the fix requires live index rebuild, production reindex, alias flip, cluster setting change, slow-log enablement, profile API on real traffic, or destructive drill outside the command contract, report the manual boundary.
+- If configured verification fails, preserve the failing intent and output tail, then fix only the localized search contract or test expectation.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Search index integrity reviewed
+- Symptom, source-to-search ledger, query contract, index contract, quality ledger, performance ledger, and privacy boundary
+- Bulk, reconciliation, lookup, exact/full-text, alias, shard, API/UI, mapping, analyzer, synonym, ranking, pagination, payload, shard fan-out, thread-pool, cache, refresh, segment, disk, and SLO findings
+- Fix applied or recommended
+- Evidence level: canary evidence, golden-set evidence, configured-test evidence, static review risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped search diagnostics and reasons
+- Remaining search-index risk

package/templates/default/locales/en/.mustflow/skills/security-privacy-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.security-privacy-review
 locale: en
 canonical: true
-revision: 22
+revision: 23
 lifecycle: mustflow-owned
 authority: procedure
 name: security-privacy-review
@@ -193,9 +193,11 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 32. For filesystem changes, distinguish lexical containment from the real target. Check symlinks, generated state, package contents, and file APIs that may follow links before claiming a path stays inside the repository.
 33. For code-scanning alerts, group findings by root cause and rule. Fix the underlying pattern, not only the exact flagged line, and separate repository-setting alerts such as branch protection or maintainer activity from code changes.
     - For incomplete escaping or encoding findings, search the same sink class for adjacent ad hoc sanitizer patterns such as first-occurrence `.replace`, non-global replacement, hand-escaped slashes, quotes, backslashes, path separators, or mixed URL encoders. Replace the pattern with a domain-owned transformation and add a regression test or narrow source-pattern guard when the behavior is release-sensitive.
+    - For ReDoS or inefficient-regular-expression findings, identify whether attacker-controlled text, repository files, generated output, logs, Markdown, YAML, or source code can reach the expression. Prefer a bounded parser, token scanner, structured parser, or anchored non-overlapping expression over nested quantifiers, repeated alternatives that can match the same prefix, or optional whitespace loops. Add a long malformed input case or equivalent static guard before claiming the backtracking risk is fixed.
 34. For workflow scanner alerts, check action pinning, `persist-credentials`, job-level permissions, reusable workflow permissions, fork pull-request secret exposure, artifact upload boundaries, and privileged identity timing before treating the warning as cosmetic.
 35. For pinned action references, distinguish tag objects from the commit that implements the tag. Verify pinned SHAs against the action repository so scanner tooling does not report an imposter or non-member commit.
 36. For dependency scanner alerts, separate production dependency manifests from fixtures, examples, generated test repositories, and intentionally vulnerable samples. Narrow the scan scope before treating fixture-only alerts as product vulnerabilities.
+    - For lockfile CVEs, inspect the manifest and lockfile together. Identify the direct parent that keeps the vulnerable transitive package in the graph, update the narrowest direct dependency or override needed to reach the fixed range, and confirm the vulnerable package version no longer appears in the resolved graph before claiming the alert is fixed.
 37. For deployment settings, check debug mode, sample admin accounts, default credentials, public admin panels, open metrics endpoints, public storage, root container users, HTTPS enforcement, and exposed GraphQL or development consoles.
 38. For runtime and framework security updates, check that supported versions are documented, end-of-life versions are rejected, dependency locks exist where appropriate, security patches can be tested and deployed quickly, and rollback or redeploy can happen without manual dashboard memory. Do not treat a fashionable or high-performance runtime as safe unless the patch path is operationally credible.
 39. For transport security, check HTTPS/TLS requirements, certificate validation, insecure HTTP downgrade paths, disabled verification flags, and whether sensitive traffic can bypass the secure channel.