mustflow 2.112.13 → 2.113.0

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

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

package/templates/default/locales/en/.mustflow/skills/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/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

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: 24
+revision: 25
 lifecycle: mustflow-owned
 authority: procedure
 name: security-privacy-review
@@ -200,6 +200,9 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 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.
+    - For object merge, defaulting, or configuration merge advisories, trace whether parsed request bodies, database records, uploaded JSON, repository config, or provider payloads can become the first or highest-priority merge input. Treat `__proto__`, `constructor`, and `prototype` keys, inherited polluted values, and default-overwrite behavior as prototype-pollution sinks; prove the patched dependency is resolved or add a regression payload that cannot override trusted defaults.
+    - For ORM or SQL-builder advisories around identifiers, aliases, dynamic sorting, report columns, CTE names, or `.as()`-style APIs, remember that value parameter binding does not protect identifier positions. Runtime input must map through an allowlist of known columns or aliases, and dialect quote delimiters inside identifiers must be escaped by the library before the identifier is wrapped.
+    - For serializer or deserializer advisories, treat sparse arrays, giant indexes, deep objects, cyclic references, and attacker-controlled serialized payloads as allocation and CPU sinks. Bound serialized size, array length or highest index, nesting depth, and parse source trust before claiming a parser-only upgrade removes the availability risk.
     - For advisories involving development tools such as Vite, Vitest UI, browser-mode test servers, Storybook, docs preview, asset servers, or framework dev servers, do not dismiss the issue merely because the package is a devDependency. Check whether scripts, docs, Docker, Codespaces, CI previews, tunnels, or config bind the server to a non-localhost host, widen file-serving roots, disable deny lists, or expose privileged read, write, rerun, snapshot, attachment, or execute APIs.
 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.