mustflow 1.18.0 → 1.18.14

package/schemas/explain-report.schema.json

@@ -111,6 +111,94 @@
           "type": "array",
           "items": { "type": "string" }
         },
+        "readModel": {
+          "$ref": "#/$defs/localPathSurfaceReadModel"
+        },
+        "surface": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "category",
+            "isPublicSurface",
+            "validationReasons",
+            "affectedContracts",
+            "updatePolicy",
+            "driftChecks"
+          ],
+          "properties": {
+            "kind": { "type": "string" },
+            "category": { "type": "string" },
+            "isPublicSurface": { "type": "boolean" },
+            "validationReasons": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "affectedContracts": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "updatePolicy": { "enum": ["update", "update_or_mark_stale", "not_applicable"] },
+            "driftChecks": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "localPathSurfaceReadModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "status",
+        "databasePath",
+        "indexFresh",
+        "stalePaths",
+        "inputPath",
+        "match",
+        "refreshHint"
+      ],
+      "properties": {
+        "source": { "const": "local_index" },
+        "status": { "enum": ["fresh", "missing", "stale", "unreadable"] },
+        "databasePath": { "type": "string" },
+        "indexFresh": { "type": "boolean" },
+        "stalePaths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "inputPath": { "type": ["string", "null"] },
+        "match": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/localPathSurfaceRuleMatch" }
+          ]
+        },
+        "refreshHint": { "type": ["string", "null"] }
+      }
+    },
+    "localPathSurfaceRuleMatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ruleId",
+        "patternKind",
+        "pattern",
+        "patternFlags",
+        "changeKinds",
+        "surface"
+      ],
+      "properties": {
+        "ruleId": { "type": "string" },
+        "patternKind": { "type": "string" },
+        "pattern": { "type": "string" },
+        "patternFlags": { "type": "string" },
+        "changeKinds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
         "surface": {
           "type": "object",
           "additionalProperties": false,
@@ -263,6 +351,109 @@
               "items": { "type": "string" }
             }
           }
+        },
+        "effectGraph": {
+          "$ref": "#/$defs/commandEffectGraph"
+        }
+      }
+    },
+    "commandEffectGraph": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "status",
+        "databasePath",
+        "indexFresh",
+        "stalePaths",
+        "writeLocks",
+        "lockConflicts",
+        "refreshHint"
+      ],
+      "properties": {
+        "source": { "const": "local_index" },
+        "status": { "enum": ["fresh", "missing", "stale", "unreadable"] },
+        "databasePath": { "type": "string" },
+        "indexFresh": { "type": "boolean" },
+        "stalePaths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "writeLocks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/commandWriteLock" }
+        },
+        "lockConflicts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/commandLockConflict" }
+        },
+        "refreshHint": { "type": ["string", "null"] }
+      }
+    },
+    "commandWriteLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lock", "paths", "modes", "sources", "concurrencies", "effectCount"],
+      "properties": {
+        "lock": { "type": "string" },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "modes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "sources": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "concurrencies": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "effectCount": { "type": "integer" }
+      }
+    },
+    "commandLockConflict": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "intent",
+        "lock",
+        "paths",
+        "modes",
+        "concurrencies",
+        "conflictingPaths",
+        "conflictingModes",
+        "conflictingConcurrencies"
+      ],
+      "properties": {
+        "intent": { "type": "string" },
+        "lock": { "type": "string" },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "modes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "concurrencies": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflictingPaths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflictingModes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflictingConcurrencies": {
+          "type": "array",
+          "items": { "type": "string" }
         }
       }
     },

package/templates/default/i18n.toml

@@ -56,12 +56,12 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 43
-translations.ko = { path = "locales/ko/.mustflow/skills/INDEX.md", source_revision = 43, status = "needs_review" }
-translations.zh = { path = "locales/zh/.mustflow/skills/INDEX.md", source_revision = 43, status = "needs_review" }
-translations.es = { path = "locales/es/.mustflow/skills/INDEX.md", source_revision = 43, status = "needs_review" }
-translations.fr = { path = "locales/fr/.mustflow/skills/INDEX.md", source_revision = 43, status = "needs_review" }
-translations.hi = { path = "locales/hi/.mustflow/skills/INDEX.md", source_revision = 43, status = "needs_review" }
+revision = 44
+translations.ko = { path = "locales/ko/.mustflow/skills/INDEX.md", source_revision = 44, status = "needs_review" }
+translations.zh = { path = "locales/zh/.mustflow/skills/INDEX.md", source_revision = 44, status = "needs_review" }
+translations.es = { path = "locales/es/.mustflow/skills/INDEX.md", source_revision = 44, status = "needs_review" }
+translations.fr = { path = "locales/fr/.mustflow/skills/INDEX.md", source_revision = 44, status = "needs_review" }
+translations.hi = { path = "locales/hi/.mustflow/skills/INDEX.md", source_revision = 44, status = "needs_review" }
 
 [documents."skill.adapter-boundary"]
 source = "locales/en/.mustflow/skills/adapter-boundary/SKILL.md"
@@ -123,6 +123,16 @@ translations.es = { path = "locales/es/.mustflow/skills/date-number-audit/SKILL.
 translations.fr = { path = "locales/fr/.mustflow/skills/date-number-audit/SKILL.md", source_revision = 1, status = "needs_review" }
 translations.hi = { path = "locales/hi/.mustflow/skills/date-number-audit/SKILL.md", source_revision = 1, status = "needs_review" }
 
+[documents."skill.database-change-safety"]
+source = "locales/en/.mustflow/skills/database-change-safety/SKILL.md"
+source_locale = "en"
+revision = 1
+translations.ko = { path = "locales/ko/.mustflow/skills/database-change-safety/SKILL.md", source_revision = 1, status = "needs_review" }
+translations.zh = { path = "locales/zh/.mustflow/skills/database-change-safety/SKILL.md", source_revision = 1, status = "needs_review" }
+translations.es = { path = "locales/es/.mustflow/skills/database-change-safety/SKILL.md", source_revision = 1, status = "needs_review" }
+translations.fr = { path = "locales/fr/.mustflow/skills/database-change-safety/SKILL.md", source_revision = 1, status = "needs_review" }
+translations.hi = { path = "locales/hi/.mustflow/skills/database-change-safety/SKILL.md", source_revision = 1, status = "needs_review" }
+
 [documents."skill.dependency-injection"]
 source = "locales/en/.mustflow/skills/dependency-injection/SKILL.md"
 source_locale = "en"

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 43
+revision: 44
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -49,6 +49,7 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
 | Changed files need risk classification and verification selection | `.mustflow/skills/diff-risk-review/SKILL.md` | Changed-file list, diff summary, and task goal | Changed surfaces and verification report | under- or over-verification | `changes_status`, `changes_diff_summary`, `test`, `test_related`, `test_audit`, `lint`, `build`, `docs_validate`, `mustflow_check` | Risk level, verification choice, rollback notes |
 | Declared behavior must stay aligned across code, schemas, templates, tests, and docs | `.mustflow/skills/contract-sync-check/SKILL.md` | Changed files, intended behavior, source of truth, derived surfaces, and command contract entries | Contract source and required synchronized surfaces | contract drift | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Contract source, synchronized surfaces, deferred surfaces, verification, and drift risk |
 | Dates, versions, counts, durations, limits, metrics, benchmarks, prices, percentages, or other numeric facts are created, edited, or reported | `.mustflow/skills/date-number-audit/SKILL.md` | Date or numeric fact, source of truth, dependent surfaces, precision expectation, and command contract entries | Numeric statements, metadata, tests, docs, templates, and reports | invented, stale, or mismatched numeric claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Audited values, source of truth, synchronized surfaces, skipped checks, and remaining numeric risk |
+| Database schema, query, transaction, ORM model, repository/store, index, cache-backed read model, data retention, pagination, concurrency, idempotency, audit log, or persistence boundary is introduced, changed, reviewed, or reported | `.mustflow/skills/database-change-safety/SKILL.md` | Data role, affected tables or stores, read/write path, transaction boundary, migration or rollback expectations, local DB or ORM patterns, changed files, and command contract entries | Schema, migrations, repositories, stores, queries, transactions, indexes, read models, fixtures, tests, docs, and directly synchronized templates | data loss, stale cache, authorization leak, transaction bug, duplicate side effect, slow query, or unverified migration claim | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Data role, schema/query/transaction review, migration and rollback status, index/performance notes, security/retention checks, tests, verification, and remaining database risk |
 | Packages, runtimes, tools, commands, services, or platform capabilities are assumed, added, invoked, or documented | `.mustflow/skills/dependency-reality-check/SKILL.md` | Dependency or capability, repository declarations, version or capability claim, and command contract entries | Dependency declarations, imports, command metadata, tests, and docs | invented or unavailable dependency | `changes_status`, `changes_diff_summary`, `build`, `test_release`, `mustflow_check` | Dependency status, synchronized surfaces, verification, and remaining dependency risk |
 | External systems, protocols, SDKs, databases, webhooks, queues, files, caches, framework requests or responses, AI models, browser storage, or provider data cross the core boundary or need port/adapter translation, error mapping, retry, idempotency, security, or observability handling | `.mustflow/skills/adapter-boundary/SKILL.md` | External system or protocol, inbound/outbound direction, internal use case, local port/adapter patterns, provider risk, changed files, and command contract entries | Ports, adapters, mappers, controllers, workers, stores, gateways, tests, fixtures, assembly wiring, and directly synchronized docs or templates | provider leakage, pass-through wrapper, unclassified external failure, duplicate side effect, unsafe retry, missing timeout, secret or personal-data leak, or untested integration drift | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Boundary classification, internal port, provider containment, validation and mapping, timeout/retry/idempotency handling, security notes, verification, and remaining provider risk |
 | Core or application logic creates, imports, resolves, or hides external dependencies such as databases, SDKs, clocks, random generators, configuration, loggers, framework objects, filesystems, queues, AI clients, or payment/email providers | `.mustflow/skills/dependency-injection/SKILL.md` | Target code area, hidden dependency, intended business capability, layer ownership, local port/adapter patterns, changed files, and command contract entries | Core logic signatures, ports, adapters, assembly roots, tests, and directly synchronized docs or templates | hidden global state, untestable business logic, provider leakage, lifecycle drift, or service-locator coupling | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Dependency boundary, direct dependencies found, injection style, ports/adapters, assembly boundary, tests or fakes, verification, and remaining dependency leakage |

package/templates/default/locales/en/.mustflow/skills/database-change-safety/SKILL.md

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.database-change-safety
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: database-change-safety
+description: Apply this skill when database schema, queries, transactions, ORM models, repositories, stores, indexes, cache-backed read models, retention, pagination, concurrency, idempotency, audit logs, or persistence boundaries are introduced, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.database-change-safety
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Database Change Safety
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep database-backed behavior explicit, scoped, recoverable where possible, and verifiable without treating database rows, ORM models, generated caches, or read models as domain truth.
+
+Use the smallest persistence boundary that proves the risk. Do not introduce repositories, services, transactions, migrations, outbox machinery, or read models when a direct scoped query or fixture update is enough.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A schema, migration, table, collection, ORM model, query, repository, store, transaction, index, cache, read model, audit log, or retention rule is introduced or changed.
+- Code reads from or writes to a database, browser storage, cache, local SQLite file, external database, or generated data store.
+- A task changes authorization, tenant scoping, pagination, sorting, soft delete, status filters, idempotency, duplicate handling, retry, or concurrency behavior around persisted data.
+- Documentation, tests, or final reports claim that a database change is safe, fast, indexed, migrated, reversible, idempotent, or verified.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is pure in-memory logic with no persisted, cached, indexed, or generated state.
+- The task only changes external protocol mapping and no database-backed state; use `adapter-boundary`.
+- The task only changes file or template migration behavior and no database or persistence surface; use `migration-safety-check`.
+- The change only documents general database advice without touching or claiming project behavior.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Database role: source of truth, rebuildable cache, read model, runtime state, analytics store, external provider, or browser storage.
+- Data owner and affected tables, collections, stores, indexes, caches, generated files, or read models.
+- Read and write paths, query or ORM behavior, authorization scope, tenant or user scope, and retention expectations.
+- Transaction boundary, idempotency, retry, duplicate-delivery, concurrency, migration, rollback, or rebuild expectations.
+- Local database, ORM, repository, fixture, migration, cache, and test patterns.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If database clients, ORM types, rows, browser storage, cache values, or provider data cross into core logic, also use `adapter-boundary`.
+- If hidden construction or global lookup creates the database dependency, also use `dependency-injection`.
+- If schema, data, cache, or generated state changes must move from an old state to a new state, also use `migration-safety-check`.
+- If personal data, authentication, authorization, retention, logs, telemetry, or secret-like values are involved, also use `security-privacy-review`.
+- If index, query-time, startup, package-size, search, count, or read-model performance claims are involved, also use `performance-budget-check`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update schema, query, repository, store, transaction, index, cache, read-model, fixture, test, documentation, and directly synchronized template surfaces tied to the task.
+- Add or tighten constraints, scoping, pagination, ordering, idempotency keys, concurrency guards, retention checks, and redaction behavior when the changed surface justifies it.
+- Mark rollback, migration, performance, privacy, or concurrency gaps as unverified when they cannot be proven.
+- Do not expose database rows, ORM models, query builders, or provider clients as domain objects.
+- Do not treat generated caches or read models as source of truth.
+- Do not add broad repository methods that accept arbitrary filters unless authorization, tenant scope, and caller ownership are explicit.
+- Do not call external APIs inside a database transaction unless a local rule explicitly accepts the coupling and a recovery path exists.
+- Do not store raw logs, secrets, hidden reasoning, full transcripts, unnecessary provider payloads, or unbounded personal data in local state or caches.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the database role.
+   - Source of truth: owns current business state.
+   - Rebuildable cache: can be deleted and regenerated from files, provider data, or another source.
+   - Read model: derived for lookup, search, reporting, or dashboard use.
+   - Runtime state: coordinates in-flight work, locks, sessions, jobs, or retries.
+   - Analytics store, external provider, or browser storage: owned outside the core domain boundary.
+2. Identify the data owner and derived surfaces. Name which table, file, provider, event log, configuration, or generated artifact owns each value.
+3. Check schema shape: primary keys, foreign keys, unique constraints, nullable fields, defaults, check constraints, status values, timestamps, soft delete fields, tenant scope, audit fields, and retention rules.
+4. Check query semantics: authorization scope, tenant or user scope, role or visibility filters, deleted or archived rows, draft or unpublished rows, effective dates, null handling, stale-data behavior, and error or absence handling.
+5. Check pagination and ordering. Lists need deterministic ordering; cursor pagination needs a stable tie breaker such as a unique id in addition to a timestamp.
+6. Check transaction boundaries. Keep database writes and external side effects separate by default; use explicit states, an outbox, an action ledger, or reconciliation when both must be coordinated.
+7. Check idempotency, retries, duplicate delivery, and concurrency. Look for webhook duplicates, job retries, import reruns, payment callbacks, optimistic locks, compare-and-swap updates, unique-constraint races, and double state transitions.
+8. Check indexes and workload cost. Match indexes to `WHERE`, `JOIN`, `ORDER BY`, and `GROUP BY` behavior, but account for write cost. Look for N+1 queries, expensive counts, full scans, materialized read-model needs, and search-index boundaries.
+9. Check privacy and retention. Prefer omission or bounded metadata over storing raw payloads. Do not persist secrets, hidden reasoning, full transcripts, unbounded logs, or personal data without a clear product rule and retention path.
+10. Check migration, rollback, and rebuild paths. If a migration claim exists, prove idempotency and recovery with `migration-safety-check` or report the gap. If the store is a cache, name the rebuild source and stale-index detection.
+11. Check tests and fixtures. Reuse or add repository/store tests, migration fixtures, query fixtures, adapter fixtures, permission regressions, idempotency or concurrency regressions, and cache rebuild checks as justified by the risk.
+12. Verify and report. Separate proven behavior from unverified rollback, migration, privacy, performance, live-data, or concurrency risks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The database role and source of truth are explicit.
+- Database rows, ORM models, generated caches, and read models do not leak into domain truth unless the local architecture intentionally owns that boundary.
+- Queries preserve authorization, tenant or user scope, deterministic ordering, expected absence behavior, and retention rules.
+- Transaction, external side effect, idempotency, duplicate, retry, and concurrency decisions are intentional and reported.
+- Index, query-cost, migration, rollback, rebuild, privacy, and verification claims are tied to evidence or marked as unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that proves the changed persistence surface. Do not infer raw database, migration, package, or benchmark commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the source of truth is unclear, stop changing persistence behavior and report the competing owners.
+- If authorization, tenant scope, soft delete, or retention behavior cannot be confirmed, fail closed or report the missing project rule.
+- If rollback, migration idempotency, rebuild, or stale-cache detection cannot be proven, avoid claiming safety and name the remaining recovery risk.
+- If a performance claim lacks a configured measurement path, report it as unmeasured instead of inventing a budget.
+- If sensitive data appears in queries, fixtures, logs, generated state, package contents, or final output, route that surface through `security-privacy-review` before continuing.
+- If the safest fix would require live data access, destructive migration, dependency installation, or unavailable credentials, stop at that boundary and report the skipped check.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Database role and owner
+- Affected read and write paths
+- Schema, constraint, and query semantics reviewed
+- Authorization, tenant scope, retention, and privacy checks
+- Transaction, idempotency, retry, and concurrency decisions
+- Index, pagination, and performance notes
+- Migration, rollback, dry-run, rebuild, or compatibility status
+- Tests, fixtures, or verification command intents run
+- Skipped checks and reasons
+- Remaining database risk

package/templates/default/locales/en/AGENTS.md

@@ -39,7 +39,7 @@ mustflow-managed details are under `.mustflow/`.
   intent is still running, especially when an intent declares non-empty `writes` such as `dist/`.
 - Choose the narrowest configured verification intent that covers the risk. Prefer related or
   fast checks over broad suites when the command contract exposes them, and report missing
-  narrower intents instead of defaulting silently to slow full-suite tests.
+  narrower intents instead of silently defaulting to slow full-suite tests.
 - Do not directly start development servers, watchers, browser interfaces, interactive prompts,
   or background processes.
 - Do not start autonomous loops, worker processes, persona systems, or long-running harness
@@ -66,7 +66,7 @@ mustflow-managed details are under `.mustflow/`.
 - Before creating or modifying any file, use `.mustflow/skills/INDEX.md` to decide whether one or more skills apply.
   This skill-selection gate is mandatory even for small or seemingly obvious tasks.
 - `mf doctor`, `mf check`, and other health checks do not satisfy the skill-selection gate. They
-  confirm repository health; they do not decide which task procedure applies.
+  confirm repository health; they do not determine which task procedure applies.
 - If a matching skill applies, read the matching `SKILL.md` before editing that scope. After
   creating or modifying files, include a concise skill-selection note in the final report: name the
   skills used, state that no matching installed skill was found, or report that a plausible skill is
@@ -80,7 +80,7 @@ mustflow-managed details are under `.mustflow/`.
 
 ## Parent and Child Rule Priority
 
-- The nearest `AGENTS.md` to the edited files is the more specific rule.
+- The `AGENTS.md` closest to the edited files takes precedence.
 - If workflow, style, tests, or command rules conflict, follow the child repository's `AGENTS.md`
   and `.mustflow/config/commands.toml`.
 - Safety rules for secrets, privacy, destructive commands, and permitted edit paths are cumulative.
@@ -94,14 +94,14 @@ mustflow-managed details are under `.mustflow/`.
 Some coding hosts may read additional host-specific instruction files or enforce their own
 approval, sandbox, checkpoint, and command execution policies.
 
-Treat those host policies as additive safety and execution constraints. They do not replace this
+Treat those host policies as additional safety and execution constraints. They do not replace this
 repository's mustflow command contract. When host instructions conflict with mustflow rules:
 
 - Direct user instructions define the task goal unless unsafe.
 - Host safety and approval gates remain binding.
 - Repository work rules come from the nearest `AGENTS.md` and `.mustflow/config/*.toml`.
 - Project verification commands must use configured mustflow intents.
-- Stricter privacy, secret, destructive-command, and Git push rules win.
+- Stricter privacy, secret, destructive-command, and Git push rules take precedence.
 - Generated state, summaries, and caches never override current files or current user instructions.
 
 When the effective rule is unclear, stop and report the conflict instead of guessing.

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: es
 canonical: false
-revision: 43
+revision: 44
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -43,6 +43,7 @@ Consulta únicamente el documento de la skill correspondiente a la tarea actual.
 | Los archivos modificados requieren clasificación de riesgo y selección de verificación | `.mustflow/skills/diff-risk-review/SKILL.md` | Lista de archivos modificados, resumen de diferencias y objetivo de la tarea | Superficies modificadas e informe de verificación | Verificación insuficiente o excesiva | `changes_status`, `changes_diff_summary`, `test`, `test_related`, `test_audit`, `lint`, `build`, `docs_validate`, `mustflow_check` | Nivel de riesgo, elección de verificación, notas de rollback |
 | El comportamiento declarado debe mantenerse alineado entre código, esquemas, plantillas, pruebas y documentación | `.mustflow/skills/contract-sync-check/SKILL.md` | Archivos modificados, comportamiento previsto, fuente de verdad, superficies derivadas y entradas de contrato de comando | Fuente del contrato y superficies sincronizadas requeridas | Deriva del contrato | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Fuente del contrato, superficies sincronizadas, superficies diferidas, verificación y riesgo de deriva |
 | Se crean, editan o reportan fechas, versiones, conteos, duraciones, límites, métricas, benchmarks, precios, porcentajes u otros hechos numéricos | `.mustflow/skills/date-number-audit/SKILL.md` | Hecho numérico o fecha, fuente de verdad, superficies dependientes, expectativa de precisión y entradas de contrato de comando | Declaraciones numéricas, metadatos, pruebas, documentación, plantillas e informes | Afirmación numérica inventada, obsoleta o desajustada | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Valores auditados, fuente de verdad, superficies sincronizadas, chequeos omitidos y riesgo numérico restante |
+| Database schema, query, transaction, ORM model, repository/store, index, cache-backed read model, data retention, pagination, concurrency, idempotency, audit log, or persistence boundary is introduced, changed, reviewed, or reported | `.mustflow/skills/database-change-safety/SKILL.md` | Data role, affected tables or stores, read/write path, transaction boundary, migration or rollback expectations, local DB or ORM patterns, changed files, and command contract entries | Schema, migrations, repositories, stores, queries, transactions, indexes, read models, fixtures, tests, docs, and directly synchronized templates | data loss, stale cache, authorization leak, transaction bug, duplicate side effect, slow query, or unverified migration claim | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Data role, schema/query/transaction review, migration and rollback status, index/performance notes, security/retention checks, tests, verification, and remaining database risk |
 | Se asumen, agregan, invocan o documentan paquetes, runtimes, herramientas, comandos, servicios o capacidades de plataforma | `.mustflow/skills/dependency-reality-check/SKILL.md` | Dependencia o capacidad, declaraciones del repositorio, versión o afirmación de capacidad y entradas de contrato de comando | Declaraciones de dependencia, importaciones, metadatos de comando, pruebas y documentación | Dependencia inventada o no disponible | `changes_status`, `changes_diff_summary`, `build`, `test_release`, `mustflow_check` | Estado de dependencia, superficies sincronizadas, verificación y riesgo restante de dependencia |
 
 | Sistemas externos, protocolos, SDKs, bases de datos, webhooks, colas, archivos, cachés, solicitudes o respuestas del framework, modelos de IA, almacenamiento del navegador o datos del proveedor que cruzan el límite del núcleo o requieren traducción de puerto/adaptador, mapeo de errores, reintentos, idempotencia, seguridad o manejo de observabilidad | `.mustflow/skills/adapter-boundary/SKILL.md` | Sistema o protocolo externo, dirección entrante/saliente, caso de uso interno, patrones locales de puerto/adaptador, riesgo del proveedor, archivos modificados y entradas del contrato de comandos | Puertos, adaptadores, mapeadores, controladores, trabajadores, almacenes, gateways, pruebas, fixtures, cableado de ensamblaje y documentación o plantillas sincronizadas directamente | Fuga del proveedor, wrapper de paso, fallo externo no clasificado, efecto secundario duplicado, reintento inseguro, falta de timeout, fuga de secretos o datos personales, o deriva de integración no probada | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Clasificación del límite, puerto interno, contención del proveedor, validación y mapeo, manejo de timeout/reintentos/idempotencia, notas de seguridad, verificación y riesgo residual del proveedor |

package/templates/default/locales/es/.mustflow/skills/database-change-safety/SKILL.md

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.database-change-safety
+locale: es
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: database-change-safety
+description: Apply this skill when database schema, queries, transactions, ORM models, repositories, stores, indexes, cache-backed read models, retention, pagination, concurrency, idempotency, audit logs, or persistence boundaries are introduced, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.database-change-safety
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Database Change Safety
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep database-backed behavior explicit, scoped, recoverable where possible, and verifiable without treating database rows, ORM models, generated caches, or read models as domain truth.
+
+Use the smallest persistence boundary that proves the risk. Do not introduce repositories, services, transactions, migrations, outbox machinery, or read models when a direct scoped query or fixture update is enough.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A schema, migration, table, collection, ORM model, query, repository, store, transaction, index, cache, read model, audit log, or retention rule is introduced or changed.
+- Code reads from or writes to a database, browser storage, cache, local SQLite file, external database, or generated data store.
+- A task changes authorization, tenant scoping, pagination, sorting, soft delete, status filters, idempotency, duplicate handling, retry, or concurrency behavior around persisted data.
+- Documentation, tests, or final reports claim that a database change is safe, fast, indexed, migrated, reversible, idempotent, or verified.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is pure in-memory logic with no persisted, cached, indexed, or generated state.
+- The task only changes external protocol mapping and no database-backed state; use `adapter-boundary`.
+- The task only changes file or template migration behavior and no database or persistence surface; use `migration-safety-check`.
+- The change only documents general database advice without touching or claiming project behavior.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Database role: source of truth, rebuildable cache, read model, runtime state, analytics store, external provider, or browser storage.
+- Data owner and affected tables, collections, stores, indexes, caches, generated files, or read models.
+- Read and write paths, query or ORM behavior, authorization scope, tenant or user scope, and retention expectations.
+- Transaction boundary, idempotency, retry, duplicate-delivery, concurrency, migration, rollback, or rebuild expectations.
+- Local database, ORM, repository, fixture, migration, cache, and test patterns.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If database clients, ORM types, rows, browser storage, cache values, or provider data cross into core logic, also use `adapter-boundary`.
+- If hidden construction or global lookup creates the database dependency, also use `dependency-injection`.
+- If schema, data, cache, or generated state changes must move from an old state to a new state, also use `migration-safety-check`.
+- If personal data, authentication, authorization, retention, logs, telemetry, or secret-like values are involved, also use `security-privacy-review`.
+- If index, query-time, startup, package-size, search, count, or read-model performance claims are involved, also use `performance-budget-check`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update schema, query, repository, store, transaction, index, cache, read-model, fixture, test, documentation, and directly synchronized template surfaces tied to the task.
+- Add or tighten constraints, scoping, pagination, ordering, idempotency keys, concurrency guards, retention checks, and redaction behavior when the changed surface justifies it.
+- Mark rollback, migration, performance, privacy, or concurrency gaps as unverified when they cannot be proven.
+- Do not expose database rows, ORM models, query builders, or provider clients as domain objects.
+- Do not treat generated caches or read models as source of truth.
+- Do not add broad repository methods that accept arbitrary filters unless authorization, tenant scope, and caller ownership are explicit.
+- Do not call external APIs inside a database transaction unless a local rule explicitly accepts the coupling and a recovery path exists.
+- Do not store raw logs, secrets, hidden reasoning, full transcripts, unnecessary provider payloads, or unbounded personal data in local state or caches.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the database role.
+   - Source of truth: owns current business state.
+   - Rebuildable cache: can be deleted and regenerated from files, provider data, or another source.
+   - Read model: derived for lookup, search, reporting, or dashboard use.
+   - Runtime state: coordinates in-flight work, locks, sessions, jobs, or retries.
+   - Analytics store, external provider, or browser storage: owned outside the core domain boundary.
+2. Identify the data owner and derived surfaces. Name which table, file, provider, event log, configuration, or generated artifact owns each value.
+3. Check schema shape: primary keys, foreign keys, unique constraints, nullable fields, defaults, check constraints, status values, timestamps, soft delete fields, tenant scope, audit fields, and retention rules.
+4. Check query semantics: authorization scope, tenant or user scope, role or visibility filters, deleted or archived rows, draft or unpublished rows, effective dates, null handling, stale-data behavior, and error or absence handling.
+5. Check pagination and ordering. Lists need deterministic ordering; cursor pagination needs a stable tie breaker such as a unique id in addition to a timestamp.
+6. Check transaction boundaries. Keep database writes and external side effects separate by default; use explicit states, an outbox, an action ledger, or reconciliation when both must be coordinated.
+7. Check idempotency, retries, duplicate delivery, and concurrency. Look for webhook duplicates, job retries, import reruns, payment callbacks, optimistic locks, compare-and-swap updates, unique-constraint races, and double state transitions.
+8. Check indexes and workload cost. Match indexes to `WHERE`, `JOIN`, `ORDER BY`, and `GROUP BY` behavior, but account for write cost. Look for N+1 queries, expensive counts, full scans, materialized read-model needs, and search-index boundaries.
+9. Check privacy and retention. Prefer omission or bounded metadata over storing raw payloads. Do not persist secrets, hidden reasoning, full transcripts, unbounded logs, or personal data without a clear product rule and retention path.
+10. Check migration, rollback, and rebuild paths. If a migration claim exists, prove idempotency and recovery with `migration-safety-check` or report the gap. If the store is a cache, name the rebuild source and stale-index detection.
+11. Check tests and fixtures. Reuse or add repository/store tests, migration fixtures, query fixtures, adapter fixtures, permission regressions, idempotency or concurrency regressions, and cache rebuild checks as justified by the risk.
+12. Verify and report. Separate proven behavior from unverified rollback, migration, privacy, performance, live-data, or concurrency risks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The database role and source of truth are explicit.
+- Database rows, ORM models, generated caches, and read models do not leak into domain truth unless the local architecture intentionally owns that boundary.
+- Queries preserve authorization, tenant or user scope, deterministic ordering, expected absence behavior, and retention rules.
+- Transaction, external side effect, idempotency, duplicate, retry, and concurrency decisions are intentional and reported.
+- Index, query-cost, migration, rollback, rebuild, privacy, and verification claims are tied to evidence or marked as unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that proves the changed persistence surface. Do not infer raw database, migration, package, or benchmark commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the source of truth is unclear, stop changing persistence behavior and report the competing owners.
+- If authorization, tenant scope, soft delete, or retention behavior cannot be confirmed, fail closed or report the missing project rule.
+- If rollback, migration idempotency, rebuild, or stale-cache detection cannot be proven, avoid claiming safety and name the remaining recovery risk.
+- If a performance claim lacks a configured measurement path, report it as unmeasured instead of inventing a budget.
+- If sensitive data appears in queries, fixtures, logs, generated state, package contents, or final output, route that surface through `security-privacy-review` before continuing.
+- If the safest fix would require live data access, destructive migration, dependency installation, or unavailable credentials, stop at that boundary and report the skipped check.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Database role and owner
+- Affected read and write paths
+- Schema, constraint, and query semantics reviewed
+- Authorization, tenant scope, retention, and privacy checks
+- Transaction, idempotency, retry, and concurrency decisions
+- Index, pagination, and performance notes
+- Migration, rollback, dry-run, rebuild, or compatibility status
+- Tests, fixtures, or verification command intents run
+- Skipped checks and reasons
+- Remaining database risk