mustflow 2.112.13 → 2.112.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.112.13",
+  "version": "2.112.14",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 224
+revision = 226
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -565,19 +565,19 @@ translations = {}
 [documents."skill.search-index-integrity-review"]
 source = "locales/en/.mustflow/skills/search-index-integrity-review/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 3
 translations = {}
 
 [documents."skill.vector-search-integrity-review"]
 source = "locales/en/.mustflow/skills/vector-search-integrity-review/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 4
 translations = {}
 
 [documents."skill.rag-pipeline-triage"]
 source = "locales/en/.mustflow/skills/rag-pipeline-triage/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 3
 translations = {}
 
 [documents."skill.dependency-injection"]
@@ -1272,7 +1272,7 @@ translations = {}
 [documents."skill.llm-token-cost-control-review"]
 source = "locales/en/.mustflow/skills/llm-token-cost-control-review/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 4
 translations = {}
 
 [documents."skill.llm-response-latency-review"]

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 224
+revision: 226
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -76,7 +76,8 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   citations, claim maps, evidence IDs, answerability states, retrieval thresholds, validators,
   abstain behavior, or hallucination metrics need product-controlled grounding review.
 - Use `llm-token-cost-control-review` as a primary route when LLM request assembly, token budgets,
-  prompt caching, chat history, RAG context size, tool or schema payloads, model routing, reasoning
+  prompt caching, chat history, RAG context size, prompt packing, document metadata, source maps,
+  question-scoped compression, evidence cards, tool or schema payloads, model routing, reasoning
   budget, retries, Batch, Flex, predicted outputs, or cost-per-success telemetry need token spend
   review.
 - Use `llm-response-latency-review` as a primary route when LLM response speed, time to first
@@ -424,16 +425,18 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   index-defeating predicates, plan skew, or long transaction scope before live plan evidence.
 - Use `search-index-integrity-review` as a primary route when keyword search, full-text search,
   Elasticsearch, OpenSearch, Lucene-style indexing, aliases, bulk ingestion, refresh visibility,
-  analyzer, synonym, autocomplete, pagination, shard failure, search quality, or search
-  performance needs source-to-search and query-contract evidence.
+  analyzer, metadata taxonomy, negative metadata, exact keyword fields, source maps, synonym,
+  autocomplete, pagination, shard failure, search quality, or search performance needs
+  source-to-search and query-contract evidence.
 - Use `vector-search-integrity-review` as a primary route when vector search, semantic search, RAG
-  retrieval, embeddings, ANN indexes, exact-versus-approximate search, filters, metadata,
-  namespaces, tenants, hybrid search, reranking, recall, latency, or golden-set behavior needs
-  retrieval-contract review.
+  retrieval, embeddings, contextual headers, synthetic questions, chunk text variants, ANN indexes,
+  exact-versus-approximate search, filters, metadata, namespaces, tenants, hybrid search, reranking,
+  recall, latency, or golden-set behavior needs retrieval-contract review.
 - Use `rag-pipeline-triage` as a primary route when a RAG, knowledge-base answer, grounded chat,
   citation answer, document QA, or support bot failure is not yet localized to ingestion, parsing,
-  chunking, retrieval, filtering, reranking, context assembly, prompt construction, generation,
-  citation validation, answerability, access control, latency, or cost.
+  document metadata, frontmatter schema, source maps, heading paths, chunking, retrieval, filtering,
+  reranking, context assembly, prompt construction, generation, citation validation, answerability,
+  access control, latency, or cost.
 - Use `database-json-modeling-review` as an adjunct when database review needs to decide whether
   JSON, jsonb, metadata, settings, raw payload, or dynamic keys should become typed columns,
   child tables, generated/computed columns, JSON indexes, schema versions, or key registries
@@ -533,8 +536,8 @@ routes. Event routes stay inactive until their event occurs.
 | AI product features, AI Gateways, provider/model integrations, prompt/RAG/tool paths, AI caches, fallback paths, streaming paths, evaluation gates, user-data flows, model registries, AI observability, incident runbooks, or model portability plans are created, changed, reviewed, or reported before the risk is narrow enough for one specialist LLM skill | `.mustflow/skills/ai-product-readiness-review/SKILL.md` | Product role ledger, harm model, gateway ledger, authority and action ledger, data ledger, cost and cache ledger, eval ledger, fallback and streaming ledger, model portability ledger, observability ledger, changed files, and command contract entries | AI Gateway boundaries, provider adapters, model registries, prompt registries, policy engines, tool proposal gates, quota guards, token budgets, cache keys, redaction, retry and fallback states, streaming validators, eval fixtures, observability fields, incident runbooks, tests, docs, route metadata, and directly synchronized templates | model-as-product shortcut, automatic high-risk decision, direct client provider call, prompt-only security, RAG permission leak, unvalidated model output, missing policy engine, cost budget gap, app cache tenant leak, eval theater, fallback-as-second-model, partial streaming disclosure, raw AI log retention, scattered model names, stale provider assumption, or missing kill switch | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `prompt_cache_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | AI product-readiness surface reviewed, AI role and harm model, gateway and policy boundaries, prompt-injection/data/output/permission/side-effect controls, cost/cache/eval/fallback/streaming/observability/model-portability decisions, specialist skills applied or deferred, verification, and remaining AI product-readiness risk |
 | Prompts, prompt builders, system or developer messages, RAG prompt assembly, few-shot examples, structured outputs, tool-use instructions, model selection, reasoning-effort settings, eval sets, refusal or fallback handling, prompt versioning, or AI feature completion criteria are created, changed, reviewed, or reported | `.mustflow/skills/prompt-contract-quality-review/SKILL.md` | Prompt contract ledger, input ledger, authority ledger, output schema, tool policy, model/runtime ledger, RAG evidence ledger, eval ledger, changed files, and command contract entries | Prompt builders, prompt templates, schemas, validators, eval fixtures, boundary examples, tool policies, fallback states, completion definitions, docs, tests, and directly synchronized templates | prompt-as-function gap, user input treated as authority, buried RAG evidence, happy-path-only examples, JSON-parse theater, unpinned production model, hidden prompt storage, raw chain-of-thought request, guessed tool parameters, missing failure state, unbounded reasoning/token cost, or vibe-based prompt improvement claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Prompt contract reviewed, function boundary, authority and source separation, eval and semantic validation status, model/runtime policy, RAG/tool/failure/completion states, verification, and remaining prompt-contract risk |
 | LLM answers, RAG responses, citations, source grounding, claim extraction, evidence IDs, answerability states, abstain behavior, retrieval thresholds, tool-backed facts, output validators, LLM judges, or hallucination-control metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-hallucination-control-review/SKILL.md` | Answer contract ledger, evidence ledger, claim ledger, tool ledger, validator ledger, eval ledger, observability ledger, changed files, and command contract entries | Answerability states, abstain states, missing-information states, source-coverage gates, claim maps, evidence-ID requirements, citation validators, retrieval thresholds, chunk metadata, tool-parameter ownership, deterministic calculators, domain validators, eval fixtures, tests, docs, route metadata, and directly synchronized templates | unsupported factual claim, fabricated citation, source ID invention, weak retrieval gate, noisy semantic-only retrieval, chunk context loss, summary-on-summary hallucination, guessed tool parameter, model arithmetic, source-priority conflict, LLM judge overtrust, low-temperature theater, missing abstain path, missing dirty eval, false citation metric gap, or unobservable grounding drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Hallucination-control surface reviewed, answerability and abstain states, evidence IDs, claim map, citations, source coverage, validators, retrieval thresholds, tool ownership, evals, metrics, verification, and remaining hallucination-control risk |
-| 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 | `.mustflow/skills/rag-pipeline-triage/SKILL.md` | Symptom classification, trace ledger, source ledger, comparison ledger, eval ledger, privacy ledger, changed files, and command contract entries | End-to-end trace preservation, source availability and parsed-text checks, chunk metadata, duplicate and stale source checks, no-retrieval/current-context/gold-context comparison, keyword/vector/hybrid/retriever/reranker/context/prompt/generation/citation/answerability localization, safe synthetic fixtures, metrics, docs, and directly synchronized templates | model scapegoating, tuning top-k before source proof, original-document theater while parsed text is broken, stale source mixing, filter blamed as vector failure, reranker candidate starvation, critical evidence truncated or buried, retrieved text treated as instruction, citation decoration, answerability missing state, private corpus dump, access filter bypass, or single satisfaction score hiding layer failure | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | RAG pipeline triaged, localized boundary, trace/source/comparison/eval/metric/privacy ledgers, layer findings, fix or recommendation, evidence level, verification, and remaining RAG pipeline risk |
-| 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 | `.mustflow/skills/llm-token-cost-control-review/SKILL.md` | Cost surface ledger, request ledger, cache ledger, context ledger, output ledger, routing ledger, observability ledger, changed files, and command contract entries | Request builders, prompt prefix ordering, canonical serialization, prompt hashes, cache keys, token counters, budget guards, model routers, context trimming, RAG packing, tool and schema payloads, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates | prompt-cache prefix drift, volatile field before stable prefix, unmeasured token count, full transcript replay, RAG chunk bloat, oversized tool or JSON schema payload, expensive model default, unbounded reasoning, no visible output after token cap, full-output regeneration, full-context retry replay, app cache key leak, predicted-output cost confusion, image or file token surprise, or per-call cost hiding cost-per-success regression | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `prompt_cache_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM token-cost surface reviewed, cost unit and measurement source, stable prefix and cache behavior, app cache/history/RAG/tool/schema/input choices, routing/reasoning/output/retry/Batch/Flex/prediction choices, observability, verification, and remaining token-cost risk |
+| 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, frontmatter schema, source maps, heading paths, chunking, retrieval, filtering, reranking, context assembly, prompt construction, generation, citation validation, or answerability boundaries | `.mustflow/skills/rag-pipeline-triage/SKILL.md` | Symptom classification, trace ledger, source ledger with original/index/prompt text, stable source/doc/chunk ids, document type/status/authority, routing summaries, document graph links, comparison ledger, eval ledger, privacy ledger, changed files, and command contract entries | End-to-end trace preservation, source availability and parsed-text checks, metadata, source maps, ACL prefilters, heading paths, semantic code chunks, table record shape, chunk graph, source-of-truth and supersession checks, duplicate and stale source checks, no-retrieval/current-context/gold-context comparison, keyword/vector/hybrid/retriever/reranker/context/prompt/generation/citation/answerability localization, safe synthetic fixtures, metrics, docs, and directly synchronized templates | model scapegoating, tuning top-k before source proof, original-document theater while parsed text is broken, generic heading coordinates, generated summary cited as source, missing source map, source/doc/chunk id collapse, stale source mixing, draft or meeting-note evidence outranking canonical documents, ACL inherited after retrieval, filter blamed as vector failure, fixed line-count code slicing, table number without row or column meaning, reranker candidate starvation, critical evidence truncated or buried, retrieved text treated as instruction, citation decoration, answerability missing state, private corpus dump, access filter bypass, or single satisfaction score hiding layer failure | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | RAG pipeline triaged, localized boundary, trace/source/comparison/eval/metric/privacy ledgers, metadata/frontmatter/source-map/ACL/chunk-graph/document-graph findings, fix or recommendation, evidence level, verification, and remaining RAG pipeline risk |
+| LLM API calls, prompt assembly, chat history, RAG context, document metadata, chunk summaries, prompt packing, question-scoped compression, evidence cards, 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 | `.mustflow/skills/llm-token-cost-control-review/SKILL.md` | Cost surface ledger, request ledger with authority lanes, cache ledger, context ledger with inclusion tests, block role tags, filter-only versus LLM-visible metadata, source maps, state cards, and evidence cards, output ledger, routing ledger, observability ledger, changed files, and command contract entries | Request builders, prompt prefix ordering, canonical serialization, prompt hashes, cache keys, token counters, budget guards, model routers, context trimming, RAG packing, question-scoped compression, slot records, state snapshots, original/index/prompt text separation, source-map references, tool and schema payloads, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates | prompt-cache prefix drift, volatile field before stable prefix, unmeasured token count, full transcript replay, state delta without baseline, answer-irrelevant context hoarding, RAG chunk bloat, generated summary treated as original evidence, search-only metadata treated as answer text, missing source coordinate, missing token_count, compression not evaluated, oversized tool or JSON schema payload, expensive model default, unbounded reasoning, no visible output after token cap, full-output regeneration, full-context retry replay, app cache key leak, predicted-output cost confusion, image or file token surprise, or per-call cost hiding cost-per-success regression | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `prompt_cache_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM token-cost surface reviewed, cost unit and measurement source, stable prefix and cache behavior, authority lanes, app cache/history/RAG/metadata/source-map/prompt-packing/evidence-card/tool/schema/input choices, routing/reasoning/output/retry/Batch/Flex/prediction choices, observability, verification, and remaining token-cost risk |
 | LLM response latency, time to first token, first useful output, streaming, output length, LLM round trips, tool-call wait, prompt-cache latency, model routing, speculative or parallel execution, realtime continuation, priority tiers, predicted outputs, or user-perceived AI speed are created, changed, reviewed, or reported | `.mustflow/skills/llm-response-latency-review/SKILL.md` | Latency target ledger, request timeline ledger, call graph ledger, output ledger, cache ledger, routing ledger, observability ledger, changed files, and command contract entries | Streaming paths, first-useful-output contracts, request timeline metrics, call graph simplification, parallel or speculative work, model routers, fallback cascades, output caps, schema shortening, prompt-cache prefix ordering, cache keys, realtime continuation, priority-tier routing, timeout and cancellation behavior, tests, docs, route metadata, and directly synchronized templates | slow first token, useless streamed preamble, extra sequential LLM round trip, tool wait blocking first output, cache-prefix drift, unmeasured cache miss, verbose output drift, long JSON key or enum overhead, RAG chunk bloat, router escalation loop, prediction-token mismatch, priority-tier misuse, unsafe speculative work, missing cancellation, or raw prompt telemetry leak | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM response-latency surface reviewed, latency unit and request timeline, round trips, parallel/tool/stream/cancel behavior, output/schema/cache/history/RAG/routing/fallback/prediction/realtime/priority choices, observability, verification, and remaining response-latency risk |
 | Autonomous or semi-autonomous LLM agents, agentic workflows, planners, executors, verifiers, tool contracts, tool-call gates, human approval or interrupt flows, durable agent state, handoffs, guardrails, loop budgets, retry policies, trace evaluation, or agent outcome metrics are created, changed, reviewed, or reported | `.mustflow/skills/agent-execution-control-review/SKILL.md` | Autonomy ledger, stage gate ledger, role separation ledger, tool contract ledger, effect ledger, state and resume ledger, memory and context ledger, handoff and guardrail ledger, loop, retry, and budget ledger, trace and eval outcome ledger, changed files, and command contract entries | Workflow-versus-agent routing, stage gates, planner/executor/verifier boundaries, tool contracts, tool argument ownership, draft/execute separation, idempotency keys, approval records, durable checkpoints, state schema versions, memory partitions, handoff filters, guardrails, loop budgets, retry classification, trace spans, eval fixtures, tests, docs, route metadata, and directly synchronized templates | unnecessary autonomous agent, one model self-certifying success, ungated bad plan, ambiguous tool contract, guessed tool argument, relative-path trap, external effect before approval, missing idempotency key, interrupt replay side effect, stale state schema, over-shared handoff, misplaced guardrail, repeated tool loop, blind retry, final-answer-only eval, or unsafe trace data | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Agent execution-control surface reviewed, workflow-versus-agent decision, autonomy envelope, stage gates, role separation, tool contracts, approval and side-effect replay safety, state/resume/memory/handoff/guardrail/loop/retry/trace/eval checks, verification, and remaining agent execution-control risk |
 | Browser automation, UI automation, Playwright, Selenium, Puppeteer, WebDriver, computer-use or browser-driving agents, visual browser verification, flaky selectors, page readiness, authentication state, CAPTCHA or anti-bot handling, rate limits, screenshot checks, retry, timeout, human approval, or browser automation observability is created, changed, reviewed, triaged, or reported | `.mustflow/skills/browser-automation-reliability-review/SKILL.md` | Automation intent ledger, state ledger, readiness ledger, selector and action ledger, auth and identity ledger, external pressure ledger, verification ledger, agent and approval ledger, changed files, and command contract entries | Browser automation state machines, locator contracts, test IDs, accessible names, readiness assertions, frame and popup handlers, input verification, auth fixtures, per-worker account isolation, retry classification, timeout hierarchy, idempotency checks, rate-limit handling, approval gates, manual fallback states, traces, screenshots, redaction, cleanup, tests, docs, route metadata, and directly synchronized templates | sleep-as-readiness, `networkidle` faith, flaky selector string patch, hidden duplicate DOM, skeleton-as-content, stale element handle, force-click default, shared mutable account, CAPTCHA bypass, anti-bot evasion, retry storm, non-idempotent replay, timeout layer mismatch, screenshot-as-business-proof, unredacted trace data, page prompt injection, stale approval resume, coordinate click drift, or unverified browser success claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Browser automation surface reviewed, browser-versus-API boundary, automation owner, state/readiness/locator/actionability/auth/rate-limit/retry/timeout/idempotency decisions, screenshot and business-success evidence, agent page-content trust, approval and resume checks, verification, and remaining browser automation reliability risk |
@@ -660,8 +663,8 @@ routes. Event routes stay inactive until their event occurs.
 | PostgreSQL-specific schema, query, transaction, migration, indexing, extension, role, row-level security, connection pooling, replication, backup, restore, managed Postgres, or Postgres runtime behavior is created, changed, reviewed, or reported | `.mustflow/skills/postgresql-code-change/SKILL.md` | PostgreSQL role, version, provider, extension inventory, topology, pooler, schema/type rules, query-plan evidence, transaction/retry rules, migration and recovery needs, changed files, and command contract entries | PostgreSQL schema, queries, migrations, generated SQL, connection setup, pool settings, roles, RLS policies, extensions, tests, docs, and directly synchronized templates | version drift, provider constraint miss, connection storm, lock or rewrite surprise, unsafe online DDL claim, bad pooler assumption, RLS bypass, search-path risk, extension drift, stale replica read, query-plan overclaim, or unverified restore | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | PostgreSQL version/topology, pooling, lock/transaction, schema/type/RLS/role, query/index/statistics, backup/restore, verification, and remaining PostgreSQL risk |
 | ClickHouse-specific schema, MergeTree engine configuration, partition or sorting keys, primary keys, projections, materialized views, dictionaries, ingest, async inserts, deduplication, mutations, joins, CTEs, aggregate states, arrays, maps, window functions, distributed queries, or query performance behavior is created, changed, reviewed, or reported | `.mustflow/skills/clickhouse-code-change/SKILL.md` | ClickHouse role, version or Cloud track, topology, engine, table shape, ingest shape, query shape, operational evidence, changed files, and command contract entries | ClickHouse DDL, SQL, query builders, ingest code, backfill code, materialized views, projections, dictionaries, settings, fixtures, tests, docs, and synchronized templates | OLTP-shaped table design, high-cardinality partition part explosion, primary-key uniqueness myth, bad sorting locality, tiny insert parts, async insert durability overclaim, block dedup retry drift, MV trigger misunderstanding, stale dictionary lookup, aggregate-state merge bug, `arrayJoin` row explosion, default window-frame bug, `FINAL` cost patch, `OPTIMIZE FINAL` routine, mutation write amplification, JOIN fan-out, CTE rerun surprise, projection backfill miss, skip-index cargo cult, or unverified query-plan claim | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | ClickHouse role/version/topology, engine/storage, ingest/dedup/MV/backfill, aggregate/query/JOIN/distributed findings, evidence level, verification, and remaining ClickHouse risk |
 | DuckDB-specific embedded OLAP database use, `.duckdb` file ownership, concurrency, language bindings, Appender usage, CSV/Parquet/JSON ingestion, query determinism, timestamp behavior, memory and temp spill settings, profiling, indexes, CTEs, macros, or DuckDB runtime behavior is created, changed, reviewed, or reported | `.mustflow/skills/duckdb-code-change/SKILL.md` | DuckDB role, version or track, binding, extension inventory, file and process ownership, ingest/export shape, query shape, memory and temp spill settings, profiling evidence, changed files, and command contract entries | DuckDB SQL, schemas, query builders, connection setup, binding-specific code, ingest/export code, Appender code, settings, fixtures, tests, docs, and synchronized templates | SQLite-like OLTP assumption, native file multi-process write bug, hidden global connection, thread/process confusion, Appender visibility overclaim, CSV sampling loss, `ignore_errors` data loss, schema-drift memory spike, `SELECT *` Parquet scan, partition file explosion, missing `ORDER BY`, order-sensitive aggregate drift, TIMESTAMPTZ timezone surprise, memory-limit overclaim, temp spill disk-full, overwritten profiling output, ART-index theater, CTE materialization surprise, window memory spike, unsafe macro input, or unverified query-plan claim | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | DuckDB role/version/binding, file/process ownership, concurrency/Appender/import/export, deterministic SQL, memory/temp/profiling, query-plan evidence, verification, and remaining DuckDB risk |
-| Keyword search, full-text search, Elasticsearch, OpenSearch, Lucene-style indexing, 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 | `.mustflow/skills/search-index-integrity-review/SKILL.md` | Symptom classification, source-to-search ledger, query contract ledger, index contract ledger, quality ledger, performance ledger, privacy ledger, changed files, and command contract entries | Search canaries, indexing ledgers, bulk item error handling, alias checks, mapping and analyzer fixtures, exact-versus-full-text tests, tenant and permission filters, golden-set tests, synonym regression tests, pagination guards, query metrics, docs, and directly synchronized templates | cluster-green theater, batch-level bulk success, source/index count illusion, write alias drift, partial shard result, direct/API/UI mismatch, wrong keyword/text field, analyzer drift, synonym regression, rank eyeballing, profile misuse, query fingerprint leak, shard fan-out, cache-only benchmark, refresh overuse, segment merge backlog, disk watermark write block, deep pagination, oversized fetch, or private query/document leak | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Search index integrity reviewed, source-to-search/query/index/quality/performance/privacy ledgers, search findings, fix or recommendation, evidence level, verification, and remaining search-index risk |
-| Vector search, semantic search, RAG retrieval, embedding generation, preprocessing, chunking, vector schema, collection, namespace, tenant, named vector, metadata payload, filter, ANN index, exact-versus-approximate search, hybrid search, reranking, recall, latency, quantization, HNSW, IVF, pgvector, Qdrant, Milvus, Weaviate, OpenSearch kNN, or retrieval golden-set behavior is created, changed, reviewed, or failing | `.mustflow/skills/vector-search-integrity-review/SKILL.md` | Retrieval symptom, query contract ledger, ingestion ledger, quality ledger, performance ledger, privacy ledger, changed files, and command contract entries | Embedding and preprocessing versioning, vector validation, deterministic ids, namespace and tenant selection, metadata indexes, filter construction, exact-search checks, ANN parameters, reranker candidates, golden-set tests, synthetic fixtures, metrics, docs, and directly synchronized templates | vector-DB scapegoating, wrong embedding dimension, model revision drift, filter post-candidate loss, metadata type drift, tenant leak, duplicate chunk ids, stale deletes, metric or normalization mismatch, ANN tuning before exact-search proof, quantization recall loss, reranker candidate starvation, hybrid score misuse, deep ANN pagination, raw vector or document leak, or unmeasured p95 latency | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Vector search integrity reviewed, retrieval/query/ingestion/quality/performance/privacy ledgers, exact-versus-ANN and filter findings, fix or recommendation, evidence level, verification, and remaining vector-search risk |
+| Keyword search, full-text search, Elasticsearch, OpenSearch, Lucene-style indexing, search APIs, indexing pipelines, source maps, metadata taxonomy, negative metadata, exact keyword fields, aliases, bulk indexing, refresh visibility, analyzers, mappings, synonyms, autocomplete, pagination, shard failures, search quality, or search performance are created, changed, reviewed, or failing | `.mustflow/skills/search-index-integrity-review/SKILL.md` | Symptom classification, source-to-search ledger, query contract ledger, index contract ledger with taxonomy/source-map fields, metadata key budget, stable source/doc/chunk ids, lifecycle and effective-date fields, quality ledger, performance ledger, privacy ledger, changed files, and command contract entries | 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, filter-only versus LLM-visible metadata checks, exact-versus-full-text tests, tenant and permission filters, golden-set tests, synonym regression tests, pagination guards, query and miss-log metrics, docs, and directly synchronized templates | cluster-green theater, batch-level bulk success, source/index count illusion, write alias drift, partial shard result, direct/API/UI mismatch, wrong keyword/text field, analyzer drift, uncontrolled tag vocabulary, unbounded metadata keys, file path treated as status, synonym regression, negative metadata ignored, missing source map, stale index hash, rank eyeballing, profile misuse, query fingerprint leak, shard fan-out, cache-only benchmark, refresh overuse, segment merge backlog, disk watermark write block, deep pagination, oversized fetch, or private query/document leak | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Search index integrity reviewed, source-to-search/query/index/quality/performance/privacy ledgers, taxonomy/metadata-budget/exact-keyword/source-map/query-log findings, fix or recommendation, evidence level, verification, and remaining search-index risk |
+| Vector search, semantic search, RAG retrieval, embedding generation, preprocessing, chunking, contextual headers, synthetic questions, chunk text variants, vector schema, collection, namespace, tenant, named vector, metadata payload, filter, ANN index, exact-versus-approximate search, hybrid search, reranking, recall, latency, quantization, HNSW, IVF, pgvector, Qdrant, Milvus, Weaviate, OpenSearch kNN, or retrieval golden-set behavior is created, changed, reviewed, or failing | `.mustflow/skills/vector-search-integrity-review/SKILL.md` | Retrieval symptom, query contract ledger, ingestion ledger with stable source/doc/chunk ids, parent document genealogy, text variants and hashes, quality ledger, performance ledger, privacy ledger, changed files, and command contract entries | Embedding, preprocessing, and chunker versioning, vector validation, deterministic ids, contextual retrieval headers, synthetic question fields, original/index/prompt/embedding text separation, namespace and tenant selection, metadata payload field typing, metadata indexes, ACL prefilters, filter construction, exact-search checks, ANN parameters, lexical safeguards for exact identifiers, hybrid score ledgers, RRF or MMR settings, reranker candidates, golden-set tests, synthetic fixtures, metrics, docs, and directly synchronized templates | vector-DB scapegoating, wrong embedding dimension, model revision drift, contextual retrieval text treated as source, synthetic question cited as evidence, unstable source/doc/chunk lineage, tiny chunk subject loss, huge chunk semantic averaging, overlap top-k duplication, filter post-candidate loss, metadata type drift, ACL applied after retrieval, tenant leak, duplicate chunk ids, stale deletes, content hash or embedding hash drift, metric or normalization mismatch, ANN tuning before exact-search proof, quantization recall loss, reranker candidate starvation, hybrid score misuse, exact identifiers smoothed into embedding-only text, deep ANN pagination, raw vector or document leak, or unmeasured p95 latency | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Vector search integrity reviewed, retrieval/query/ingestion/quality/performance/privacy ledgers, exact-versus-ANN/filter/text-variant/contextual-header/lineage/hybrid/rerank findings, fix or recommendation, evidence level, verification, and remaining vector-search risk |
 | Dependency versions, lockfiles, package-manager metadata, workspace constraints, runtime engines, peer dependencies, optional dependencies, security advisory fixes, vulnerability scanner alerts, generated dependency output, framework plugins, dev servers, test runners, TypeScript compiler tracks, CI actions, Docker base images, package manager behavior, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported | `.mustflow/skills/dependency-upgrade-review/SKILL.md` | Dependency name, old and new versions or ranges, direct or transitive path, ecosystem and package manager, declaration files, lockfiles, runtime or toolchain files, advisory or release-note evidence, exploit preconditions, generated outputs, callers, docs, package output, Docker, CI, dev-server or test-UI exposure, protocol role, or TypeScript compiler-track surfaces, and command contract entries | Package declarations, lockfiles, generated outputs, compatibility code, tests, docs, package metadata, Docker or CI files, dev-server/test-runner config notes, TypeScript compiler-track notes, and directly synchronized examples | lockfile churn, hidden transitive replacement, peer or engine break, module-format drift, native or optional package break, framework or generator output drift, devDependency advisory dismissed despite exposure, unsafe broad security update, weakened tests, Docker or CI runtime drift, protocol DoS misclassified, TS7 RC over-adoption, TS7 nightly over-adoption, or unreviewed supply-chain change | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Upgrade reason, ecosystem surface, direct and transitive graph changes, compatibility classification, runtime/peer/engine/module/feature/platform/generated-output/compiler-track risks, advisory exploit preconditions, synchronized surfaces, verification, and remaining dependency-upgrade risk |
 | Dependency, package, runtime, framework, tool, command, plugin, service, platform capability, supported-version policy, security patch path, ecosystem maturity claim, maintainer-risk assumption, runtime portability claim, edge or serverless compatibility claim, critical-path library choice, package script, lifecycle hook, binary download, lockfile, audit result, or supply-chain-sensitive dependency surface is assumed, added, removed, imported, invoked, installed, audited, or documented | `.mustflow/skills/dependency-reality-check/SKILL.md` | Assumed dependency or capability, declaration files, version or feature expectation, role criticality, supported-version or end-of-life evidence, patchability expectation, runtime compatibility boundary, maintainer and ecosystem evidence when available, lockfile entry, package script or lifecycle hook, audit or provenance evidence, and relevant command intents | Package metadata, lockfiles, imports, scripts, command contracts, docs, tests, runtime policy notes, portability notes, and reports | unavailable dependency, hallucinated or lookalike package, fragile single-maintainer core dependency, experimental technology in a survival path, unsupported runtime, unclear security patch path, runtime-specific API leakage into core logic, stale version claim, lifecycle script risk, audit suppression, lockfile drift, or install guidance mismatch | `changes_status`, `changes_diff_summary`, `build`, `test_release`, `mustflow_check` | Dependency checked, ecosystem and maintainer-risk boundary reviewed, supported-version, patchability, and runtime-portability boundary reviewed, supply-chain surface reviewed, declarations synchronized, verification, and remaining dependency risk |
 | Generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, TypeScript compiler-track references, Go release or framework references, Java/JDK GA, LTS, JEP, JVM, GC, or toolchain references, Rust release or MSRV references, or migration-sensitive snippets introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, or scaffold commands that may be stale | `.mustflow/skills/version-freshness-check/SKILL.md` | Versioned reference, owning files, repository version policy, approved freshness source, compatibility context, migration risk, TypeScript compiler track, Go toolchain/framework track, Java JDK/toolchain/bytecode/JEP track, or Rust MSRV/toolchain track when relevant, and command contract entries | Package metadata, lockfiles, CI workflows, Dockerfiles, runtime files, framework config, docs, examples, templates, tests, and version-decision reports | stale default version, false latest claim, accidental major migration, repository policy mismatch, unsupported generated example, TypeScript RC/nightly/API-track confusion, Java latest-GA/LTS/runtime/JEP/preview/incubator confusion, Rust stable/nightly/MSRV confusion, floating-tag drift, or unverified security/support claim | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Versioned surfaces checked, repository policy and freshness source, selected version track, compatibility classification, TypeScript stable/RC/nightly/API-track, Go runtime/framework, Java GA/LTS/runtime/JEP/toolchain, and Rust stable/nightly/MSRV split when relevant, approval need, synchronized surfaces, verification, and remaining version-freshness risk |

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/vector-search-integrity-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.vector-search-integrity-review
 locale: en
 canonical: true
-revision: 2
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: vector-search-integrity-review
-description: Apply this skill when vector search, semantic search, RAG retrieval mechanics, embeddings, vector databases, ANN indexes, exact versus approximate search, filters, metadata payloads, namespaces, tenants, named vectors, hybrid search, reranking, recall, latency, quantization, HNSW, IVF, pgvector, Qdrant, Milvus, Weaviate, OpenSearch kNN, or retrieval golden-set behavior is created, changed, reviewed, or failing. Use rag-pipeline-triage first when a RAG failure is not yet localized to retrieval versus parsing, context assembly, prompt, generation, citation, or answerability.
+description: Apply this skill when vector search, semantic search, RAG retrieval mechanics, embeddings, vector databases, ANN indexes, exact versus approximate search, filters, metadata payloads, chunk text variants, namespaces, tenants, named vectors, hybrid search, reranking, recall, latency, quantization, HNSW, IVF, pgvector, Qdrant, Milvus, Weaviate, OpenSearch kNN, or retrieval golden-set behavior is created, changed, reviewed, or failing. Use rag-pipeline-triage first when a RAG failure is not yet localized to retrieval versus parsing, context assembly, prompt, generation, citation, or answerability.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -68,13 +68,16 @@ filters, reranking, and latency evidence all agree for the same query contract.
 - Retrieval symptom classification: ingestion missing, write not visible, wrong results, empty
   results, low recall, tenant leak, duplicate chunks, stale deletes, slow search, reranker drift, or
   generated answer drift.
-- Query contract ledger: query text or safe fixture id, embedding model and revision, preprocessing
-  version, vector dimension, vector norm, metric, collection, namespace, tenant, named vector,
-  filters, `top_k`, candidate count, consistency level, ANN parameters, hybrid weights, and reranker
-  settings.
-- Ingestion ledger: source id, chunk id, deterministic vector id, embedding version, payload shape,
-  write count, unique id count, direct lookup count, indexed count, deleted or tombstoned count, and
-  visibility lag.
+- Query contract ledger: query text or safe fixture id, query family, embedding model and revision,
+  preprocessing version, chunker version, contextual header policy, synthetic question policy,
+  vector dimension, vector norm, metric, collection, namespace, tenant, named vector, metadata
+  payload fields and types, ACL prefilter, filters, `top_k`, candidate count, consistency level,
+  ANN parameters, hybrid weights, MMR or fusion settings, and reranker settings.
+- Ingestion ledger: source id, stable doc id, chunk id, parent document genealogy, deterministic
+  vector id, original text hash, index text, prompt text, embedding text, contextual header, title,
+  heading path, document type, status, authority, aliases, exact keywords, synthetic questions,
+  embedding version, content hash, embedding hash, payload shape, write count, unique id count,
+  direct lookup count, indexed count, deleted or tombstoned count, and visibility lag.
 - Quality ledger: golden queries, expected ids, acceptable alternatives, exact-search result,
   ANN result, recall at k, MRR, empty rate, duplicate rate, filtered result count, and before/after
   comparison.
@@ -95,10 +98,12 @@ filters, reranking, and latency evidence all agree for the same query contract.
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Add or tighten embedding versioning, preprocessing versioning, vector validation, deterministic
-  IDs, namespace or tenant selection, metadata indexes, filter construction, exact-search checks,
-  ANN parameters, reranker candidate counts, golden-set tests, metrics, docs, fixtures, and
-  retrieval contract tests.
+- Add or tighten embedding versioning, preprocessing and chunker versioning, vector validation,
+  deterministic IDs, contextual retrieval headers, synthetic question fields,
+  original/index/prompt/embedding text separation, namespace or tenant selection, metadata payload
+  field typing, metadata indexes, ACL prefilter construction, exact-search checks, ANN parameters,
+  hybrid score ledgers, RRF or MMR settings, reranker candidate counts, golden-set tests, metrics,
+  docs, fixtures, and retrieval contract tests.
 - Add focused synthetic fixtures that encode expected retrieval behavior, filtered retrieval,
   tenant separation, duplicate handling, and exact-versus-ANN comparison.
 - Do not change embedding models, rebuild large indexes, tune ANN parameters, disable filters, widen
@@ -116,38 +121,56 @@ filters, reranking, and latency evidence all agree for the same query contract.
    all-zero vectors, extreme norms, and model or preprocessing version mismatches.
 4. Keep embedding model identity exact. Model name alone is not enough; include revision, tokenizer,
    pooling, prefix policy, max length, HTML cleanup, chunking, and normalization.
-5. Compare exact search with approximate search on the same query and filter. If exact search is
+5. Separate original, index, prompt, and embedding text. Original text is the citation source,
+   index text may include titles, aliases, contextual retrieval summaries, and generated questions,
+   prompt text is the compact model payload, and embedding text is the vector input. Do not collapse
+   these fields unless the product intentionally accepts that tradeoff.
+6. Check chunk graph and recursive retrieval shape. Source ids, parent document ids, parent chunk
+   ids, previous and next chunk ids, section paths, summary layers, and contextual retrieval
+   headers should be available when small chunks need larger context for answer generation. Stable
+   ids must survive renames, storage moves, and reindex jobs so citations, deletes, feedback logs,
+   and eval sets keep the same lineage.
+7. Check chunk size and overlap as quality levers, not defaults. Tiny chunks that lose the subject,
+   huge chunks that average unrelated meanings, and large overlap that fills top-k with duplicates
+   each need separate recall and diversity evidence.
+8. Validate contextual headers and synthetic questions. Headers should disambiguate product,
+   version, document status, authority, section, and entity; synthetic questions should reflect real
+   user phrasing without being cited as original source. Keep original, enriched retrieval text, and
+   LLM-visible metadata distinct so search bait does not become generated evidence.
+9. Compare exact search with approximate search on the same query and filter. If exact search is
    wrong, stop tuning ANN and inspect embeddings, preprocessing, metric, payload, and expectations.
-6. Compare filter-free search, filter-only count, filtered exact search, and filtered ANN search.
+10. Compare filter-free search, filter-only count, filtered exact search, and filtered ANN search.
    Empty filtered results often mean filter construction, metadata typing, payload indexing, or
    post-filter candidate loss rather than bad embeddings.
-7. Confirm collection, namespace, tenant, alias, and named vector. Directly inspect the problem id
+11. Confirm collection, namespace, tenant, alias, and named vector. Directly inspect the problem id
    or safe synthetic id in the same search surface the app uses.
-8. Check deterministic upsert ids. Source id, chunk index, tenant, and embedding version should not
+12. Check deterministic upsert ids. Source id, chunk index, tenant, and embedding version should not
    accidentally duplicate chunks or overwrite all chunks with one id.
-9. Separate write success from search visibility. Check direct lookup, exact search, ANN search,
+13. Separate write success from search visibility. Check direct lookup, exact search, ANN search,
    indexed count, consistency, segment state, and visibility lag.
-10. Check deletes and updates. Deletion marks, tombstones, compaction, vacuum, stale segments, and
+14. Check deletes and updates. Deletion marks, tombstones, compaction, vacuum, stale segments, and
     old chunks can keep appearing after API success.
-11. Review metric and normalization. Cosine, dot product, and L2 are different contracts unless
+15. Review metric and normalization. Cosine, dot product, and L2 are different contracts unless
     the vectors are intentionally normalized and the index operator matches.
-12. Tune ANN only after the exact and filter contracts are correct. Evaluate recall and p95 latency
+16. Tune ANN only after the exact and filter contracts are correct. Evaluate recall and p95 latency
     across parameter sweeps instead of changing one value blindly.
-13. Treat build-time index parameters as recall ceilings. If search-time parameters cannot recover
+17. Treat build-time index parameters as recall ceilings. If search-time parameters cannot recover
     recall, the index may need rebuild policy, not a larger query knob.
-14. Review quantization and rescoring. Compare full-precision exact results with compressed-index
+18. Review quantization and rescoring. Compare full-precision exact results with compressed-index
     candidates and confirm enough candidates reach full-precision reranking.
-15. For hybrid search, store dense score, sparse or keyword score, normalized score, fusion method,
-    and final score. Do not add incompatible raw scores directly without a deliberate combiner.
-16. For reranking, record pre-rerank and post-rerank ids and ranks. If the right document never
+19. For hybrid search, store dense score, sparse or keyword score, normalized score, fusion method,
+    RRF or MMR settings when used, and final score. Do not add incompatible raw scores directly
+    without a deliberate combiner. Preserve exact product codes, API names, error codes, ticket IDs,
+    and dates in lexical fields instead of smoothing them into natural-language embedding text.
+20. For reranking, record pre-rerank and post-rerank ids and ranks. If the right document never
     enters the candidate set, the reranker cannot recover it.
-17. Avoid deep ANN pagination as a product contract. Use cursor, filters, grouping, or ordinary
+21. Avoid deep ANN pagination as a product contract. Use cursor, filters, grouping, or ordinary
     sorted indexes for deep browsing instead of pretending vector search has cheap random offsets.
-18. Split cold and warm latency, server search time and client wait, vector DB time and reranker
+22. Split cold and warm latency, server search time and client wait, vector DB time and reranker
     time, and single-query latency from concurrent load.
-19. Inspect shard, replica, segment, compaction, flush, indexing, memory, disk, and cache state when
+23. Inspect shard, replica, segment, compaction, flush, indexing, memory, disk, and cache state when
     p99 or intermittent quality varies across nodes.
-20. Add a golden-set gate when the project has a test surface. Include easy, hard, filtered,
+24. Add a golden-set gate when the project has a test surface. Include easy, hard, filtered,
     tenant-scoped, rare-name, synonym, short-query, long-query, and sparse-data cases.
 
 <!-- mustflow-section: postconditions -->
@@ -155,6 +178,10 @@ filters, reranking, and latency evidence all agree for the same query contract.
 
 - The retrieval symptom, query contract, ingestion contract, quality ledger, performance ledger, and
   privacy boundary are explicit.
+- Original/index/prompt/embedding text separation, stable source/doc/chunk ids, parent document
+  genealogy, payload field typing, ACL prefiltering, contextual headers, synthetic questions,
+  chunk graph, content hashes, embedding hashes, exact lexical safeguards, and hybrid or rerank
+  ledgers are explicit where relevant.
 - Exact search, ANN, filters, metadata, namespaces, tenants, named vectors, IDs, deletes, metric,
   normalization, quantization, hybrid search, reranking, shards, consistency, and latency are fixed
   or reported where relevant.
@@ -199,8 +226,8 @@ of inventing live diagnostics.
 - Vector search integrity reviewed
 - Retrieval symptom, query contract, ingestion ledger, quality ledger, performance ledger, and
   privacy boundary
-- Exact versus ANN, filter, metadata, namespace, tenant, id, delete, metric, normalization,
-  quantization, hybrid, reranker, shard, consistency, and latency findings
+- Exact versus ANN, filter, metadata, text-variant, namespace, tenant, id, delete, metric,
+  normalization, quantization, hybrid, MMR, reranker, shard, consistency, and latency findings
 - Fix applied or recommended
 - Evidence level: golden-set evidence, configured-test evidence, static review risk, manual-only,
   missing, or not applicable

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.112.13"
+version = "2.112.14"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"