mustflow 2.112.10 → 2.112.14

package/templates/default/locales/en/.mustflow/skills/race-condition-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.race-condition-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: race-condition-review
-description: Apply this skill when code is created, changed, reviewed, or reported and shared state can be observed across interleaving execution flows, including check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, tryLock, timeout or retry behavior, cache miss fill, lazy initialization, atomics and memory ordering, database transaction races, uniqueness, distributed locks, idempotency, atomic file creation, event or outbox ordering, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
+description: Apply this skill when code is created, changed, reviewed, or reported and shared state can be observed across interleaving execution flows, including check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, tryLock, timeout or retry behavior, cache miss fill, lazy initialization, atomics and memory ordering, database transaction races, uniqueness, distributed locks, fencing tokens, idempotency state records, atomic file creation, event or outbox ordering, inbox or dedupe consumers, per-key serialization, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -59,7 +59,9 @@ The review question is not "does this code use threads?" The stronger question i
 - Interleaving points: `await`, I/O, database calls, callbacks, hooks, plugin calls, event publish, queue insert, lock release, timer scheduling, retry, cancellation, shutdown, close, send, and other function calls after a state read.
 - Synchronization boundary: lock scope, atomic operation, compare-and-swap, transaction, row lock, unique constraint, conditional update, singleflight, idempotency record, outbox, or file atomic create/rename behavior.
 - Ordering and duplication rules: event order, queue delivery semantics, duplicate messages, same-user or same-resource concurrency, retry replay, cancellation timing, timer overlap, and shutdown drain behavior.
+- Idempotency and ownership rule: business idempotency key, processing/succeeded/failed record state, duplicate-in-progress behavior, fencing token or generation owner, and whether same-key work is serialized while unrelated keys can run concurrently.
 - Evidence surface: existing tests, fixtures, schema constraints, command intents, logs, metrics, sequence numbers, request ids, transaction ids, versions, or manual-only concurrency evidence.
+- Incident file when a concurrency failure was observed: test name, seed, worker or thread count, scheduler settings, timeout, input, build hash, OS/runtime version, environment slice, and exact failure time when available.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -82,61 +84,68 @@ The review question is not "does this code use threads?" The stronger question i
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Name the shared fact. State the exact value or invariant another execution flow could change: balance, status, cache entry, uniqueness, queue offset, file existence, socket state, collection membership, timer owner, shutdown flag, or object ownership.
-2. Build a stale-read ledger.
+1. Preserve the incident file before changing code when a race was observed.
+   - Capture the failing test or workflow name, random seed, worker or thread count, scheduler or CPU-affinity setting when relevant, timeout, input, build hash, OS/runtime version, environment variables that affect scheduling, and exact failure time.
+   - Do not replace a missing incident file with "ran many times"; repeated passing runs are weaker than one reproducible failing condition.
+2. Name the shared fact. State the exact value or invariant another execution flow could change: balance, status, cache entry, uniqueness, queue offset, file existence, socket state, collection membership, timer owner, shutdown flag, or object ownership.
+3. Build a stale-read ledger.
    - For each shared state read, mark every later `await`, I/O, DB call, callback, event publish, queue insertion, lock release, timer, retry, cancellation, shutdown, close, send, or function call before the action.
    - Ask whether the read is still true after each interleaving point. If the answer relies on hope, the path is not race-safe.
-3. Catch check-then-act.
+4. Catch check-then-act.
    - Treat patterns such as `if exists then create`, `if balance >= amount then withdraw`, `if status == pending then approve`, duplicate email checks, coupon redemption, order number generation, and filesystem `exists` then `open` as unsafe until proven atomic.
    - Prefer atomic conditional updates, atomic create, insert with unique constraint, compare-and-swap, row locks, or file creation modes that fail when the target already exists.
-4. Catch read-modify-write.
+5. Catch read-modify-write.
    - `++`, `+=`, `push`, `append`, `map[key] = value`, collection mutation, get-then-set, and counter updates are shared-state writes, not harmless syntax.
    - Use atomic operations only when the invariant is one variable. If the invariant spans fields, rows, objects, or messages, use a transaction, lock, state machine, or conditional write that protects the whole fact.
-5. Do not trust a single event loop after `await`.
+6. Do not trust a single event loop after `await`.
    - In JavaScript, Python async, UI runtimes, and coroutine systems, a state read before `await` can be stale after the continuation resumes.
    - Re-read, validate a version, hold the correct synchronization boundary, or move the decision into an atomic operation.
-6. Review lock scope by invariant, not by field.
+7. Review lock scope by invariant, not by field.
    - A lock around one setter does not protect a multi-field or multi-row rule if reads and writes outside the lock can observe intermediate state.
    - Keep callbacks, hooks, events, plugin calls, external I/O, logging, JSON conversion, and long calculations outside locks unless the invariant truly requires them.
    - Define and follow a global lock order when more than one lock can be acquired.
-7. Treat `tryLock`, timeout, and retry as risk multipliers.
+8. Treat `tryLock`, timeout, and retry as risk multipliers.
    - Check what partial state remains when lock acquisition fails, times out, or is retried.
    - Verify rollback, idempotency, duplicate side-effect prevention, and retry budget. A retry can make a race rarer or louder, not correct.
-8. Review cache miss fill and lazy initialization.
+9. Review cache miss fill and lazy initialization.
    - Multiple misses for the same key should not all rebuild, fetch, insert, or publish the same value unless duplication is harmless and bounded.
    - Use singleflight, promise memoization with failure cleanup, once initialization, durable uniqueness, or explicit cache-authority rules.
    - Double-checked locking needs a memory-ordering story in runtimes where construction visibility is not automatically safe.
-9. Review atomics and memory ordering.
+10. Review atomics and memory ordering.
    - Atomics protect a specific operation on a specific value. They do not automatically make surrounding objects, arrays, maps, or multi-field invariants safe.
    - Check acquire/release or stronger memory ordering where the language exposes it, and report missing expertise or evidence instead of guessing.
-10. Review database races.
+11. Review database races.
     - A database transaction does not erase a race by itself. Check isolation level, row locks, predicate locks, uniqueness, conditional updates, and whether `SELECT` then `UPDATE` can be invalidated before commit.
     - Prefer `UPDATE ... WHERE status = ...`, insert-or-ignore/upsert with unique constraints, version columns, row locks, or serializable isolation when the invariant requires it.
     - Application-level duplicate checks are advisory only; unique facts belong in the database or another durable single-writer authority.
-11. Review distributed locks as debt.
-    - Lock expiry, process pauses, network delay, clock skew, and split ownership can let two workers believe they own the same work.
-    - Keep data correct if the distributed lock breaks: unique constraints, idempotency keys, fencing tokens, conditional writes, or state transitions should still reject stale owners.
-12. Review event, queue, and outbox ordering.
-    - Publishing an event before or after a state change can split the world unless a durable outbox or equivalent boundary ties them together.
-    - Queue consumers should assume duplicates, reordering, delayed delivery, redelivery after timeout, and concurrent work for the same user or resource.
-    - Use inbox deduplication, per-aggregate ordering, conditional state transitions, or idempotent side effects where needed.
-13. Review filesystem races.
+12. Review distributed locks as debt.
+   - Lock expiry, process pauses, network delay, clock skew, and split ownership can let two workers believe they own the same work.
+   - Keep data correct if the distributed lock breaks: unique constraints, idempotency keys, fencing tokens, conditional writes, or state transitions should still reject stale owners.
+13. Review event, queue, and outbox ordering.
+   - Publishing an event before or after a state change can split the world unless a durable outbox or equivalent boundary ties them together.
+   - Queue consumers should assume duplicates, reordering, delayed delivery, redelivery after timeout, and concurrent work for the same user or resource.
+   - Use inbox deduplication, per-aggregate ordering, per-key serialization, conditional state transitions, or idempotent side effects where needed.
+   - Same-key work should expose whether the current record is processing, succeeded, failed, cancelled, or dead. A duplicate arriving while the first attempt is still processing is not the same as replaying a completed result.
+   - Business idempotency keys should describe the intended operation, not just the transport request id, when retries or duplicate submissions must return the same logical result.
+14. Review filesystem races.
     - `exists` then `open`, temp file name selection, cleanup by path, and replace-in-place can race.
     - Prefer atomic create, safe temporary file APIs, same-directory temp files, fsync where durability matters, and atomic rename or replace semantics appropriate to the platform.
-14. Review shutdown, cancellation, timers, close, and send.
+15. Review shutdown, cancellation, timers, close, and send.
     - Shutdown should define who stops accepting work, who drains, who cancels, and who owns in-flight side effects.
     - Cancellation must be idempotent and safe when completion happens at the same time.
     - Timers and schedulers need one current owner; old timers should not update new state.
     - WebSocket, channel, stream, socket, queue, and emitter paths need a clear rule for close/send races and double close.
-15. Review shared collections and object reuse.
+16. Review shared collections and object reuse.
     - Iteration over a collection that another flow can mutate needs a lock, snapshot, immutable copy, version check, or concurrent collection semantics.
     - Object pooling, buffer reuse, mutable DTO reuse, and reused request contexts are unsafe if async work can still hold references.
     - Fake immutable objects with mutable internals, getters, shared maps, or cached arrays should be treated as mutable shared state.
-16. Review tests and logs with suspicion.
+17. Review tests and logs with suspicion.
     - `sleep`-based race tests are usually probability tests. Prefer deterministic barriers, fake schedulers, controlled promises, version assertions, unique constraints, or repeated stress only as supplementary evidence.
+    - Shake the schedule, not only the load: widen context-switch windows with configured deterministic barriers, fake schedulers, controlled yields, delay injection, or repeated stress harnesses only when the repository command contract allows them.
     - Logging can hide or change a race. Log order is not event order across threads, processes, async tasks, buffers, or machines.
-    - Use monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
-17. Escalate broad status fields into state-machine review.
+    - Use happens-before logs at handoff points such as queue push/pop, mutex unlock/lock, atomic release/acquire, promise/future completion, channel send/receive, callback registration/execution, plus monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
+    - Treat race detectors, thread sanitizers, deterministic record/replay, profilers, kernel tracing, or stress tools as configured or manual diagnostics only; never infer raw commands from the tool names.
+18. Escalate broad status fields into state-machine review.
     - If values such as `pending`, `processing`, `done`, `failed`, `cancelled`, `closed`, or `deleted` drive behavior, draw allowed transitions and reject stale concurrent transitions.
     - Use `state-machine-pattern` when the race fix needs a transition table, event union, transition log, retry reconciliation, or effect ordering.
 
@@ -144,9 +153,11 @@ The review question is not "does this code use threads?" The stronger question i
 ## Postconditions
 
 - Shared state reads, interleaving points, and stale-read risks are identified or ruled out.
+- Observed concurrency failures preserve the incident file needed to reproduce the same timing envelope when available.
 - Check-then-act and read-modify-write paths are atomic, guarded, constrained, or explicitly reported as residual risk.
 - Locks protect whole invariants, have a clear ordering rule, and avoid slow or reentrant work where possible.
 - Database, cache, queue, event, filesystem, cancellation, shutdown, timer, close/send, collection, and object-reuse races are checked where relevant.
+- Idempotency processing states, duplicate-in-progress behavior, fencing tokens, outbox/inbox handoffs, and per-key serialization are checked where relevant.
 - Tests or configured verification cover the highest-risk concurrency invariant when feasible.
 
 <!-- mustflow-section: verification -->
@@ -178,9 +189,11 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 ## Output Format
 
 - Shared state and invariant reviewed
+- Incident file captured or reported missing
 - Interleaving points checked
 - Check-then-act and read-modify-write findings
 - Async stale-read, lock scope/order, tryLock/timeout/retry, cache/lazy init, atomic/memory ordering, database transaction, uniqueness, distributed lock, idempotency, filesystem, event/outbox, queue, shutdown, cancellation, timer, close/send, shared collection, object reuse, fake immutable, test, log, and state-machine checks where relevant
+- Idempotency record states, fencing token, inbox or dedupe, per-key serialization, and duplicate-in-progress checks where relevant
 - Race fixes made or recommended
 - Tests or verification evidence
 - Command intents run

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.rag-pipeline-triage
 locale: en
 canonical: true
-revision: 1
+revision: 3
 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.
+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, document metadata, source maps, chunking, retrieval, filtering, reranking, context assembly, prompt construction, generation, citation validation, or answerability boundaries.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -46,6 +46,9 @@ survive filtering and context assembly, and constrain the answer?"
   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.
+- A document corpus, frontmatter contract, search index, chunk schema, ACL model, or prompt-packing
+  rule is being reviewed because token bloat, retrieval misses, stale context, or unsupported
+  citations may come from poor document structure rather than model behavior.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -70,9 +73,14 @@ survive filtering and context assembly, and constrain the answer?"
   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.
+- Source ledger: authoritative source availability, original text, parsed text, index text,
+  prompt text, source id, stable doc id, chunk id, parent document genealogy, chunk boundaries,
+  frontmatter or metadata schema, document type, status, authority, source-of-truth flag, title,
+  aliases, exact keywords, synthetic questions, negative metadata, heading path, breadcrumb ids or
+  text, source map, parent and adjacent chunks, section or document summaries, routing summaries,
+  lifecycle owner, version, revision, supersedes or superseded-by links, content hash, index
+  freshness, published and 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.
@@ -93,10 +101,11 @@ survive filtering and context assembly, and constrain the answer?"
 <!-- 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 or tighten trace fields, fixture queries, parsing checks, semantic or structure-aware chunking,
+  chunk metadata, frontmatter schemas, source maps, parent-child or adjacent chunk links,
+  ACL-prefilter checks, 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
@@ -117,34 +126,74 @@ survive filtering and context assembly, and constrain the answer?"
    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
+6. Check whether a single chunk can stand on its own. Each answerable chunk should carry enough
+   product, feature, version, lifecycle, and heading context that retrieval does not depend on the
+   model guessing the missing subject from a previous chunk.
+7. Review headings as coordinates. Generic headings such as overview, details, or notes are weak
+   retrieval features; heading paths and breadcrumbs should name the product, workflow, rule, and
+   exception boundary that make the chunk answerable.
+8. Separate original, index, and prompt text. The original span is evidence, enriched index text is
+   search bait, and prompt text is the compact model payload. Do not cite generated summaries,
+   aliases, or synonym-expanded text as if they were original source.
+9. Check source maps and chunk graph. Verify file path or URL, section anchor, line or page span,
+   content hash, parent chunk, previous chunk, next chunk, and summary layer can lead back to the
+   source without loading the whole corpus.
+10. Check document identity and lifecycle before merging evidence. Keep `source_id`, `doc_id`, and
+    `chunk_id` distinct; preserve rename-stable ids, `doc_type`, `status`, `authority`,
+    `source_of_truth`, `supersedes`, `superseded_by`, `valid_until`, and effective-date fields so
+    stale, draft, example, discussion, and canonical documents are not averaged into one answer.
+11. Treat summaries as routers, not proof. A summary should carry what the document can answer,
+    what it cannot answer, entities, decisions, exceptions, related docs, deprecated content,
+    conditions, actions, numbers, and exact source coordinates; if it ages separately from the
+    source, classify the failure as stale entrance metadata before changing retrieval settings.
+12. Check exact keywords and aliases. Error codes, SKU values, API paths, function names, legal
+    references, old product names, and user slang should be searchable without relying on embeddings.
+13. For code corpora, preserve structure. Function, class, import, caller, callee, type, test, and
+    config-key boundaries should guide chunks; fixed line-count slicing that cuts through symbols is
+    retrieval damage, not neutral preprocessing.
+14. For table, slide, and PDF corpora, preserve record shape. Row, column, unit, plan, page, and
+    figure context should be repeated in parsed/index text so a number is not retrieved without its
+    meaning.
+15. Check rules beside exceptions. If prohibitions, limits, or jurisdiction exclusions live far away
+    from the rule they modify, context assembly may retrieve only the rule and miss the exception.
+16. Check ACL before retrieval. Tenant, visibility, sensitivity, retention, and user or group access
+   must be inherited from documents to chunks and applied before candidate text reaches the model.
+17. 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,
+   Preserve conflicting sources with their priority, status, and effective date instead of
+   smoothing them into a synthesized rule.
+18. 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,
+19. 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,
+20. 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
+21. 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,
+22. 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
+23. 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,
+24. 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
+25. 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,
+26. Measure each layer separately. Track parsing success, metadata completeness, ACL inheritance,
+    index freshness, hit rate, Recall@k, MRR, precision, nDCG, rerank survival, context precision,
+    context recall, faithfulness, groundedness, answer relevance, context token budget, answer
+    accuracy, citation accuracy, abstain accuracy, access leaks, and retrieval/rerank/generation
+    latency and cost.
+27. Check the document graph for multi-hop questions. PRDs, ADRs, issues, code modules, runbooks,
+    changelogs, incidents, and meeting notes should link decisions, implementation, ownership,
+    exceptions, and follow-up operations instead of forcing retrieval to infer relationships from
+    nearby words.
+28. 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,
+29. 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.
 
@@ -155,6 +204,11 @@ survive filtering and context assembly, and constrain the answer?"
   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.
+- Document metadata, frontmatter schema, stable source/doc/chunk ids, document type, status,
+  authority, source-of-truth, effective dates, supersession links, heading paths, source maps, ACL
+  inheritance, original/index/prompt text separation, exact keywords, aliases, negative metadata,
+  routing summaries, summary layers, chunk adjacency, document graph links, and index freshness 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.
 

package/templates/default/locales/en/.mustflow/skills/repro-first-debug/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.repro-first-debug
 locale: en
 canonical: true
-revision: 3
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: repro-first-debug
-description: Apply this skill when fixing a reported bug or confusing failure before the failure has a clear reproduction.
+description: Apply this skill when fixing, investigating, or instrumenting a reported bug, confusing failure, flaky symptom, production-only defect, unreproducible incident, or legacy-code failure before the failure has a clear reproduction.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -31,8 +31,9 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 ## Use When
 
 - A user reports a bug, broken behavior, confusing runtime result, or failed workflow.
-- A failure is visible, but the smallest reproduction path is not yet clear.
+- A failure is visible, intermittent, production-only, data-dependent, or reported from another environment, but the smallest reproduction path is not yet clear.
 - A fix could otherwise be based on speculation, stale assumptions, or a broad unrelated test run.
+- A safe temporary patch is needed to stop harm, but the change must also capture evidence for the next occurrence instead of only hiding the symptom.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -49,6 +50,8 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 - Any pasted error text, screenshot detail, failing command intent, route, or UI action.
 - Recently changed files or likely affected files.
 - Existing tests, command intents, or manual reproduction notes related to the failure.
+- Available diagnostic evidence such as trace id, span id, request id, job id, attempt, feature flag, deployment version, log query, normal-versus-failing trace comparison, profiler window, breakpoint or watchpoint condition, and safe DB/cache/external dependency facts.
+- Runtime state snapshot evidence when available: cache keys, DB row state, queue state, locks, in-flight work, timezone, environment/config values, server instance, feature flags, app version, browser/app version, region, release, and concurrent request count.
 - Any known flakiness, environment dependency, timing dependency, or unavailable reproduction requirement.
 
 <!-- mustflow-section: preconditions -->
@@ -81,13 +84,37 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
    - specific input, fixture, locale, path, or data shape;
    - external source, generated output, or stale build artifact.
    For each hypothesis, write the observation that would confirm or reject it before changing production code.
-6. If the symptom appears flaky, separate the reproducible behavior from the unstable trigger. Do not treat one passing broad rerun as proof that the issue is fixed.
-7. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
-8. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification.
-9. Apply the smallest fix that addresses the reproduced cause.
-10. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
-11. Add or keep a regression guard only when it is tied to the reproduced symptom or a directly observed boundary condition.
-12. Report the symptom, reproduction, hypotheses considered, observations, fix, original reproduction rerun, checks, and remaining risk.
+6. Reject symptom-cover patches before editing.
+   - A null check, timeout increase, expected-value tweak, broad retry, catch-and-ignore, or local-line-only patch is not acceptable until the broken invariant and first divergence are named.
+   - Before applying a patch, state which invariant failed, where the invariant first became false, and what no-patch observation proves that claim.
+   - List counterexamples that could still fail after the obvious patch, especially concurrency, cache, time zone, retry/idempotency, schema/wire compatibility, security, and performance cases.
+7. Build a diagnostic evidence packet when logs, traces, profiling, or breakpoints are involved.
+   - Prefer normal-versus-failing trace comparison before reading only the final error log.
+   - Tie evidence together with stable identifiers such as trace id, span id, request id, tenant id, job id, attempt, feature flag, and deployment version.
+   - If timing or ordering may matter, prefer profiler, trace duration, lock wait, allocation, queue age, or dependency latency evidence before stopping the process with a broad breakpoint.
+   - Use conditional instrumentation or breakpoints scoped to the failing id when configured or manually approved; do not leave those probes in committed code.
+8. If the symptom appears flaky, separate the reproducible behavior from the unstable trigger. Do not treat one passing broad rerun as proof that the issue is fixed.
+9. For unreproducible failures, switch from "make it fail locally" to "make the next failure leave evidence."
+   - Capture a state snapshot, not just the input payload: relevant memory/cache state, DB rows, locks, queue messages, time zone, deployment version, feature flags, environment/config values, server instance, dependency versions, and concurrency shape when safe and available.
+   - Prefer pre-failure ring buffers, bounded internal event trails, impossible-state assertions, invariant checks, DB constraints, background auditors, or sanity checkers that fire where the bad state is first created.
+   - Temporary mitigation should also add forensic evidence such as caller, retry header, idempotency key, first and second handling time, state before and after, or safe resource identifiers.
+10. Narrow production-only and legacy symptoms by evidence elimination.
+   - Split last-known-good and first-failed windows across code, config, data, migration, infra, dependency, external-provider, and traffic-pattern changes.
+   - Split mixed symptoms by error code, user cohort, browser, app version, region, server instance, time window, release, feature flag, and data shape before assuming one root cause.
+   - Search stable constants, error strings, DB column names, event names, queue topics, config keys, and external endpoint fragments before trusting function names.
+   - Start from exits and writers: DB writes, serialized responses, emitted events, emails, balance changes, files, queues, cron jobs, admin tools, and external side effects. Treat DB triggers, queues, cron, imports, and admin panels as code.
+   - Use blame, linked commits, PRs, and same-commit file changes for historical context, not for assigning fault.
+11. Stress hidden conditions deliberately when the repository has a configured or approved way to do so.
+   - Suspect time, randomness, and concurrency first for "sometimes" failures.
+   - Prefer fixed seeds, fake clocks, forced interleavings, latency injection, duplicate or reordered messages, worker kills, cache clears, slight time shifts, and concurrent requests over waiting for chance.
+   - Minimize production data into a safe fixture by removing unrelated rows or events until the trigger disappears, then restore the last removed condition.
+12. Inspect the source that controls the reproduced behavior and gather the smallest observation needed to choose between hypotheses.
+13. If temporary instrumentation is needed, give every probe a unique marker, keep it local to the suspect boundary, and remove it before final verification unless the user explicitly wants durable diagnostics.
+14. Apply the smallest fix that addresses the reproduced or instrumented cause. Keep behavior-preserving cleanup, characterization tests, bug fixes, and long-term refactors separate when the codebase is legacy or high-risk.
+15. Re-run the original reproduction path after the fix. If that path is unavailable or too broad, run the closest configured intent and report the limitation.
+16. For unreproducible fixes, define the "fixed" metric before claiming success: failure rate, invariant violation count, duplicate handling count, retry exhaustion count, DLQ growth, timeout rate, latency tail, or another symptom-specific measure.
+17. Add or keep a regression guard only when it is tied to the reproduced symptom, the instrumented invariant, or a directly observed boundary condition.
+18. Report the symptom, reproduction, hypotheses considered, observations, evidence packet, fix, original reproduction rerun, checks, and remaining risk.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -95,6 +122,10 @@ This skill keeps debugging anchored to symptom evidence, deterministic reproduct
 - The final report distinguishes reproduced evidence from assumptions.
 - Any added test or reproduction note is tied to the reported failure, not to general coverage growth.
 - Cause hypotheses are confirmed, rejected, or left explicitly unresolved instead of being implied by a passing broad check.
+- Symptom-cover patches are rejected unless they repair the named invariant and survive relevant counterexamples.
+- Trace, log, profiler, breakpoint, DB, cache, and dependency evidence is correlated by stable identifiers when that evidence exists.
+- Unreproducible defects are handled with next-failure evidence capture, state snapshots, bounded event trails, impossible-state monitors, and pre-declared fix metrics rather than a speculative local patch.
+- Legacy-code investigations start from symptom exits, writers, stable strings, data flow, history, and code-outside-code surfaces before broad call-graph reading or cleanup.
 - Temporary instrumentation and debug output are removed before final verification unless intentionally retained.
 - Missing command intents, unavailable tools, or unsafe reproduction requirements are reported instead of hidden.
 
@@ -125,6 +156,8 @@ Prefer the original failing intent when it is narrower than the defaults above.
 - Symptom and expected behavior
 - Reproduction path or reproduction gap
 - Hypotheses considered and observations
+- Diagnostic evidence packet and counterexamples considered
+- State snapshot, next-failure capture, last-good or first-failed window, symptom split, and legacy narrowing evidence where relevant
 - Probable cause, confidence, and evidence
 - Fix applied
 - Original reproduction rerun result

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

@@ -790,7 +790,7 @@ applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_
 category = "data_external"
 route_type = "primary"
 priority = 75
-applies_to_reasons = ["code_change", "docs_change", "security_change", "package_metadata_change", "release_risk"]
+applies_to_reasons = ["code_change", "docs_change", "security_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."dependency-reality-check"]
 category = "data_external"
@@ -814,7 +814,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "docs_c
 category = "data_external"
 route_type = "adjunct"
 priority = 65
-applies_to_reasons = ["code_change", "security_change", "migration_change"]
+applies_to_reasons = ["code_change", "security_change", "migration_change", "package_metadata_change", "release_risk"]
 
 [routes."adapter-boundary"]
 category = "data_external"
@@ -886,7 +886,7 @@ applies_to_reasons = ["test_change"]
 category = "security_privacy"
 route_type = "primary"
 priority = 30
-applies_to_reasons = ["security_change", "privacy_change"]
+applies_to_reasons = ["security_change", "privacy_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."secret-exposure-response"]
 category = "security_privacy"
@@ -934,7 +934,7 @@ applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "publi
 category = "security_privacy"
 route_type = "adjunct"
 priority = 76
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "package_metadata_change", "release_risk"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "docs_change", "package_metadata_change", "release_risk", "unknown_change"]
 
 [routes."security-regression-tests"]
 category = "security_privacy"

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.search-index-integrity-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 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.
+description: Apply this skill when keyword search, full-text search, Elasticsearch, OpenSearch, Lucene-style indexes, search APIs, indexing pipelines, source maps, metadata taxonomy, 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
@@ -55,7 +55,13 @@ The core question is whether a source record can be changed, accepted by the ind
 - 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.
+- Index contract ledger: read alias, write alias, index templates, mappings, analyzers, normalizers,
+  exact id fields, exact keyword fields, facet fields, filter-only metadata, embedding-header
+  metadata, citation metadata, negative metadata, taxonomy fields, controlled vocabulary, metadata
+  key budget, stable source id, document id, chunk id when applicable, alias or synonym tables,
+  source-map fields, published/effective/indexed/verified dates, version fields, content hash,
+  schema version, index version, 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.
@@ -71,7 +77,12 @@ The core question is whether a source record can be changed, accepted by the ind
 <!-- 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 or tighten search canaries, indexing ledgers, bulk item error handling, alias checks, mapping
+  and analyzer fixtures, metadata taxonomy checks, frontmatter schema checks,
+  controlled-vocabulary fixtures, exact-keyword fixtures, negative-metadata filters,
+  exact-versus-full-text tests, tenant and permission filter tests, golden-set tests, synonym
+  regression tests, pagination guards, query and miss-log 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.
@@ -108,31 +119,64 @@ The core question is whether a source record can be changed, accepted by the ind
 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.
+10. Review metadata taxonomy and controlled vocabulary.
+    - Distinguish filter fields, facet fields, ranking fields, display fields, and source-map fields.
+    - Canonical keys, aliases, synonyms, old names, and related terms should be explicit so free-form tags do not become five spellings of the same concept.
+    - Treat tags as filter conditions, not vibes. Reject values such as important, misc, final, or
+      reference unless they have a controlled, queryable meaning.
+    - Keep the metadata key set small enough that writers can fill it consistently; separate a
+      core filter set from optional enrichment instead of accepting unbounded ad hoc keys.
+11. Split metadata by job.
+    - Filter metadata should be typed and exact; context headers should help lexical and semantic
+      recall; citation metadata should point back to source spans.
+    - Do not put every metadata key into analyzed text. Select title, section, entity, date, type,
+      and other disambiguators; keep volatile, private, or filter-only fields out of recall text.
+    - Keep LLM-visible metadata separate from search/filter metadata when the index feeds RAG.
+      Operational paths, ACL fields, tenant IDs, and internal ids should not become answer text
+      unless they change citation, permission, or disambiguation.
+12. Separate path hints from state fields.
+    - Paths may encode tenant, visibility, lifecycle, source, language, or date for operations, but
+      `status`, `is_current`, `effective_from`, `effective_to`, `published_at`, `indexed_at`,
+      `last_verified_at`, `version`, and `revision` should remain first-class filter fields.
+    - File names are human hints; stable ids are machine keys. Renames, storage moves, and reindex
+      jobs should not break citations, deletes, feedback logs, or eval sets.
+13. Review negative metadata and lifecycle filters.
+    - Visibility, audience, jurisdiction exclusions, draft/deprecated state, retention, and security
+      class are search correctness gates, not decoration.
+    - A good search result that should not have been eligible is a security or product bug.
+14. Preserve source maps and freshness fields.
+    - Store document id, chunk id when applicable, file or URL, section anchor, line or page span, content hash, schema or index version, and last indexed time so stale or unsupported results can be traced.
+15. Review exact keyword fields separately from analyzed text.
+    - Error codes, API paths, legal references, ticket ids, SKU values, class or function names, and
+      deprecated names need exact or keyword search coverage even when semantic retrieval exists.
+16. 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.
+17. Use query, miss, and click logs as improvement evidence without leaking raw private text.
+    - Track query family, normalized terms, filters, zero-result rate, clicked ids, used chunks, fallback reason, and answer success where safe.
+    - Do not turn private queries or highlights into fixtures unless they are redacted or synthetic.
+18. 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.
+19. 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.
+20. 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.
+21. 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.
+22. 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.
+23. 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.
+24. 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.
+25. 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.
 
@@ -140,6 +184,10 @@ The core question is whether a source record can be changed, accepted by the ind
 ## Postconditions
 
 - The search symptom, source-to-search ledger, query contract, index contract, quality ledger, performance ledger, and privacy boundary are explicit.
+- Metadata taxonomy, metadata key budget, schema versions, stable source/doc/chunk ids, canonical
+  keys, aliases, exact keyword fields, filter-only versus LLM-visible metadata, lifecycle and
+  effective-date fields, negative metadata, source maps, index version, content hash, query logs,
+  and miss logs are explicit where relevant.
 - 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.
 
@@ -173,7 +221,9 @@ Prefer the narrowest configured tests that cover search contract, tenant isolati
 
 - 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
+- Bulk, reconciliation, lookup, exact/full-text, alias, shard, API/UI, mapping, analyzer, taxonomy,
+  source-map, synonym, ranking, pagination, payload, query-log, 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