mustflow 1.18.16 → 1.31.0

package/templates/default/locales/es/.mustflow/skills/behavior-preserving-refactor/SKILL.md

@@ -1,182 +0,0 @@
----
-mustflow_doc: skill.behavior-preserving-refactor
-locale: es
-canonical: false
-revision: 11
-lifecycle: mustflow-owned
-authority: procedure
-name: behavior-preserving-refactor
-description: Apply this skill when refactoring should reduce change cost while preserving existing behavior and keeping behavior changes separate.
-metadata:
-  mustflow_schema: "1"
-  mustflow_kind: procedure
-  pack_id: mustflow.core
-  skill_id: mustflow.core.behavior-preserving-refactor
-  command_intents:
-    - changes_status
-    - changes_diff_summary
-    - test_related
-    - test
-    - docs_validate_fast
-    - test_release
-    - mustflow_check
----
-
-# Behavior-Preserving Refactor
-
-<!-- mustflow-section: purpose -->
-## Purpose
-
-Guide refactoring that lowers future change cost without silently changing runtime behavior.
-
-Refactoring is not cleanup for aesthetics. It is a controlled way to make code easier to understand, test, and change while keeping bug fixes, feature work, and behavior changes separate.
-
-<!-- mustflow-section: use-when -->
-## Use When
-
-- The user asks to refactor, clean up, reorganize, simplify, split, extract, rename, remove duplication, or improve structure.
-- A planned change risks mixing renames, moves, extractions, deduplication, bug fixes, and feature behavior in one diff.
-- Existing code is hard to change because responsibilities, names, branches, dependencies, or tests are unclear.
-- Existing inheritance, base classes, abstract classes, template methods, protected state, or subclass variants make behavior harder to test or change.
-- Existing handlers, repositories, adapters, jobs, or services mix business decisions with database access, network calls, logging, current time, generated identifiers, randomness, environment reads, or framework objects.
-- Existing controllers, handlers, jobs, or services mix one state-changing intent with authorization, transactions, idempotency, audit logs, outbox events, retries, concurrency checks, and external side effects.
-- Existing controllers, handlers, workers, command handlers, or services repeat the same multi-step subsystem sequence and should move behind a stable facade without changing behavior.
-- Existing lifecycle state changes are scattered across direct assignments, handlers, repositories, jobs, UI checks, SQL conditions, or provider callbacks.
-- Existing code repeats presence checks for optional collaborators such as loggers, analytics clients, caches, optional notifications, or no-op processors.
-- The task touches legacy or weakly tested code and needs a safer refactoring order.
-
-<!-- mustflow-section: do-not-use-when -->
-## Do Not Use When
-
-- The requested task is primarily a bug fix or failure diagnosis; use `repro-first-debug` first.
-- The change introduces new folders, modules, routing, data models, or external service boundaries before refactoring scope is clear; use `structure-discovery-gate`.
-- The task is only to review an already completed diff; use `diff-risk-review` or `code-review`.
-- The target code is about to be deleted, the requirement is still unclear, or the next step requires a product decision rather than a refactor.
-
-<!-- mustflow-section: required-inputs -->
-## Required Inputs
-
-- The refactoring goal, target files or area, and the concrete pain being reduced.
-- Current behavior evidence, such as tests, examples, fixtures, command output, or observed input and output cases.
-- Existing local patterns for naming, file boundaries, dependencies, and tests.
-- Current changed-file list when the worktree is already dirty.
-- Relevant command-intent contract entries for verification.
-
-<!-- mustflow-section: preconditions -->
-## Preconditions
-
-- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
-- The expected behavior to preserve is known, or the unknown behavior has been reported before edits begin.
-- If the area is unfamiliar, `codebase-orientation` or `pattern-scout` has been used to avoid inventing a parallel structure.
-- If tests are absent or weak, the first safe step is to add characterization coverage, capture input and output cases, or explicitly report the verification gap.
-
-<!-- mustflow-section: allowed-edits -->
-## Allowed Edits
-
-- Rename unclear identifiers when the rename improves call-site meaning without changing behavior.
-- Extract small functions, policies, or helpers when they have a clear concept, inputs, outputs, and test value.
-- Flatten conditional flow when it preserves the same guard conditions and error behavior.
-- Separate responsibilities, dependencies, or side effects in the smallest useful step.
-- Move domain decisions toward pure functions or narrow policy objects, and keep I/O, clocks, network calls, process spawning, persistence, and logging in the imperative edge.
-- Add or update tests that preserve current behavior or make the refactoring safe.
-- Do not mix behavior changes, bug fixes, new features, broad formatting churn, or unrelated cleanup into the refactor.
-
-<!-- mustflow-section: procedure -->
-## Procedure
-
-Before broad hotspot scans, compress candidates before reading files.
-
-- Exclude generated files, bundled files, lock files, dependency directories, large fixtures, snapshots, build outputs, minified files, and source maps before ranking candidates.
-- Use `[refactoring.hotspots]` preferences as scan limits: `large_file_candidate_kb` for the first size signal, `history_days` for recent change and bug-fix history, and the candidate limits for how many files to inspect at each depth.
-- Prefer overlapping low-cost signals over a single metric: size, recent change frequency, bug-fix history, import/export count, TODO/FIXME/HACK count, type or lint bypasses, missing nearby tests, and architecture-boundary imports.
-- Treat strong combinations as higher priority, such as large files with frequent changes and no tests, small security/payment/permission files with repeated bug fixes, large React client components with many effects, and API/controller files that mix validation, authorization, business logic, database access, and response formatting.
-- Do not read every candidate. Keep the first pass to the configured primary limit, narrow to the configured structure-review limit, and read full file contents only for the configured full-file limit.
-- When opening a candidate, inspect imports, exports, declarations, TODO or type-bypass neighborhoods, and the largest or most branch-heavy function before reading the full file.
-
-1. Diagnose whether refactoring is needed.
-   - Name the real problem: change cost, unclear responsibility, repeated bug risk, test difficulty, dependency coupling, or confusing flow.
-   - Do not refactor only because code looks long, old, or stylistically uneven.
-2. Identify behavior that must stay fixed.
-   - Prefer existing tests or examples.
-   - If coverage is missing, record representative input and output cases or add focused characterization tests before structural edits.
-   - Treat suspected bugs as separate follow-up fixes unless the user explicitly asks to change behavior.
-3. Choose the safest refactoring ladder.
-   - Start with names and local clarity.
-   - Then extract small concepts with clear inputs and outputs.
-   - Then flatten conditions or isolate policies.
-   - Then remove duplication only when the duplicated code changes for the same reason.
-   - Move files, introduce abstractions, or split modules only after local behavior is easier to see.
-4. Check duplication before merging code.
-   - Keep duplication when code only looks similar or will change for different reasons.
-   - Prefer common code only when it represents the same rule, simplifies call sites, and does not add parameter or branch complexity.
-   - Prefer explicit duplication over a misleading abstraction.
-5. Check extracted functions and names.
-   - Extract only concepts that can be named precisely.
-   - Avoid vague names such as `process`, `handle`, `do`, or `helper` unless they match established local style.
-   - Boolean functions should read naturally at call sites and reveal the condition being tested.
-6. Prefer the low-ceremony structural pattern that matches the pain:
-   - Dependency injection when direct construction, global lookup, or hidden imports of tools, clients, clocks, file systems, processes, loggers, configuration, random generators, identifiers, queues, or external SDKs makes behavior hard to test. Use `dependency-injection` before editing that boundary.
-   - Adapter or translator boundaries when external formats leak into core logic. Use `adapter-boundary` when provider data, protocols, errors, timeouts, retries, idempotency, security, or observability are part of the boundary.
-   - Composition over inheritance when behavior can be assembled from small explicit collaborators. Use `composition-over-inheritance` before editing `extends`, base classes, abstract classes, template methods, protected state, mixins, or subclass combinations.
-   - Command pattern when a state-changing user or system intent needs a traceable execution unit with explicit payload, context, authorization, transaction boundary, idempotency, outbox, audit, retry, or concurrency behavior. Use `command-pattern` before editing that execution unit.
-   - Pure core with an imperative shell when business decisions, validation, authorization, pricing, eligibility, state transitions, or domain events are mixed with I/O, time, generated identifiers, randomness, environment reads, or framework objects. Use `pure-core-imperative-shell` before editing that split.
-   - State machine pattern when status, state, phase, step, or stage controls allowed behavior and transitions are scattered or assigned directly. Use `state-machine-pattern` before editing lifecycle transitions.
-   - Strategy pattern when repeated branches choose among interchangeable algorithms, policies, pricing rules, scoring methods, provider choices, or feature variants that share one purpose. Use `strategy-pattern` before editing that strategy family.
-   - Result and Option values when expected failures, meaningful absence, null returns, thrown business failures, or ambiguous success flags make behavior hard to follow. Use `result-option` before editing that return-shape contract.
-   - Null Object pattern when repeated nullable checks around an optional collaborator can be replaced by a same-interface neutral implementation without hiding required failures. Use `null-object-pattern` before editing that optional dependency boundary.
-   - Injected time context when current time affects preserved behavior.
-7. Handle conditional complexity by finding the policy.
-   - Use early exits for simple guard conditions when they preserve behavior.
-   - Separate state, type, permission, and exceptional-rule branches when they are mixed.
-   - Avoid replacing clear branches with a strategy object, table, or abstraction before the policy boundary is proven.
-8. Keep commits and reports reviewable.
-   - Separate renames, moves, extractions, deduplication, tests, and behavior changes when possible.
-   - If behavior changes are discovered, stop and report them as a separate fix path.
-9. Verify with the narrowest configured command intents that cover the changed code and contract surfaces.
-
-<!-- mustflow-section: postconditions -->
-## Postconditions
-
-- Existing behavior is preserved or any behavior change is clearly separated and reported.
-- The refactor has a named purpose tied to lower change cost, lower defect risk, or better testability.
-- The diff is small enough for a reviewer to distinguish mechanical changes from semantic changes.
-- Tests or verification evidence cover the behavior most likely to regress.
-
-<!-- mustflow-section: verification -->
-## Verification
-
-Use configured oneshot command intents when available:
-
-- `changes_status`
-- `changes_diff_summary`
-- `test_related`
-- `test`
-- `docs_validate_fast`
-- `test_release`
-- `mustflow_check`
-
-Choose the narrowest configured test or build intent that proves the refactored behavior. Use documentation and release checks only when the refactor changes public docs, templates, schemas, package metadata, or release-sensitive surfaces.
-
-<!-- mustflow-section: failure-handling -->
-## Failure Handling
-
-- If current behavior cannot be observed, stop before broad restructuring and report the missing safety evidence.
-- If a refactor uncovers a bug, keep the refactor behavior-preserving and propose the fix as a separate change.
-- If deduplication creates more options, branches, or vague names, undo or postpone that abstraction.
-- If tests fail after a supposedly behavior-preserving edit, diagnose the behavior difference before continuing.
-- If the next useful step is a large module move or public boundary change, use `structure-discovery-gate` and `contract-sync-check` before proceeding.
-
-<!-- mustflow-section: output-format -->
-## Output Format
-
-- Refactoring goal
-- Behavior preservation evidence
-- Structural risk signals found
-- Facade extraction used or intentionally avoided
-- Refactoring ladder chosen
-- Structural pattern used or intentionally avoided
-- Changes made or analysis-only recommendation
-- Behavior changes intentionally excluded
-- Verification intents run
-- Skipped checks and reasons
-- Remaining risks or follow-up fix path

package/templates/default/locales/es/.mustflow/skills/code-review/SKILL.md

@@ -1,115 +0,0 @@
----
-mustflow_doc: skill.code-review
-locale: es
-canonical: false
-revision: 3
-lifecycle: mustflow-owned
-authority: procedure
-name: code-review
-description: Aplica esta skill al revisar cambios de codigo, alcance, riesgos o brechas de verificacion.
-metadata:
-  mustflow_schema: "1"
-  mustflow_kind: procedure
-  pack_id: mustflow.core
-  skill_id: mustflow.core.code-review
-  command_intents:
-    - test
-    - test_related
-    - test_audit
-    - lint
----
-
-# Revision De Codigo
-
-<!-- mustflow-section: purpose -->
-## Proposito
-
-Verificar que un cambio se alinee con la solicitud y asegurar que no queden riesgos de comportamiento ni brechas de verificacion.
-
-<!-- mustflow-section: use-when -->
-## Usar Cuando
-
-- Cambios de codigo, diferencias, solicitudes de extraccion o riesgos potenciales de regresion requieran revision.
-- El objetivo principal sea evaluar riesgos en lugar de implementar comportamiento nuevo.
-
-<!-- mustflow-section: do-not-use-when -->
-## No Usar Cuando
-
-- La tarea solo implique cambios de redaccion, traduccion o formato.
-- No haya archivos cambiados ni diferencias disponibles para revisar.
-
-<!-- mustflow-section: required-inputs -->
-## Entradas Requeridas
-
-- Archivos modificados o diferencias
-- Criterios de revision especificados por el usuario
-- `AGENTS.md`
-- `.mustflow/docs/agent-workflow.md`
-- `.mustflow/config/commands.toml`
-
-<!-- mustflow-section: preconditions -->
-## Precondiciones
-
-- La tarea coincide con las condiciones de uso y no coincide con las exclusiones.
-- Las entradas requeridas estan disponibles, o las entradas faltantes pueden reportarse sin adivinar.
-- Las instrucciones de mayor prioridad y `.mustflow/config/commands.toml` se revisaron para el alcance actual.
-
-<!-- mustflow-section: allowed-edits -->
-## Ediciones Permitidas
-
-- Mantener las ediciones dentro del alcance descrito por esta skill, la solicitud del usuario y la ruta coincidente en `.mustflow/skills/INDEX.md`.
-- No ampliar permisos de comando, inventar hechos del proyecto ni cambiar archivos de workflow no relacionados.
-
-<!-- mustflow-section: procedure -->
-## Procedimiento
-
-1. Revisa la lista de archivos modificados.
-2. Identifica ediciones no relacionadas o sobrantes.
-3. Evalua el impacto sobre comportamiento, configuracion, comandos y documentacion.
-4. Revisa la relevancia de pruebas:
-   - pruebas faltantes para funcionalidad nueva
-   - pruebas obsoletas de funcionalidad eliminada
-   - pruebas redundantes que no cubren riesgos nuevos
-   - aserciones debilitadas o insuficientes
-   - actualizaciones de snapshots sin una justificacion clara
-   - pruebas que reintroducen comportamiento eliminado de forma inadvertida
-5. Verifica la existencia de command intents relevantes.
-6. Documenta hallazgos categorizados por severidad.
-
-<!-- mustflow-section: postconditions -->
-## Postcondiciones
-
-- La salida esperada puede producirse con evidencia clara, intentos de comando ejecutados, verificaciones omitidas y riesgos restantes.
-- Cualquier intento de comando faltante, entrada desconocida o conflicto de autoridad se reporta en lugar de ocultarse.
-
-<!-- mustflow-section: verification -->
-## Verificacion
-
-Sigue `.mustflow/docs/agent-workflow.md#command-execution-policy`.
-
-Command intents relacionados:
-
-- `test`
-- `test_related`
-- `test_audit`
-- `lint`
-
-Evita introducir comandos crudos de shell; referencia los nombres de command intent definidos en `.mustflow/config/commands.toml`.
-
-<!-- mustflow-section: failure-handling -->
-## Manejo De Fallos
-
-- Si un command intent falta, esta restringido a ejecucion manual, esta deshabilitado o es desconocido, reporta el estado en lugar de adivinar.
-- Documenta cualquier verificacion omitida y los riesgos remanentes asociados.
-- Deten el proceso de inmediato y reporta si se identifican datos sensibles o riesgos de comandos destructivos.
-
-<!-- mustflow-section: output-format -->
-## Formato De Salida
-
-- Resumen
-- Hallazgos categorizados por severidad
-- Lista de archivos revisados
-- Command intents ejecutados
-- Command intents omitidos y sus justificaciones
-- Notas sobre relevancia de pruebas
-- Riesgos remanentes identificados

package/templates/default/locales/es/.mustflow/skills/codebase-orientation/SKILL.md

@@ -1,115 +0,0 @@
----
-mustflow_doc: skill.codebase-orientation
-locale: es
-canonical: false
-revision: 1
-lifecycle: mustflow-owned
-authority: procedure
-name: codebase-orientation
-description: Apply this skill when a task needs a grounded map of an unfamiliar codebase area before planning or editing.
-metadata:
-  mustflow_schema: "1"
-  mustflow_kind: procedure
-  pack_id: mustflow.core
-  skill_id: mustflow.core.codebase-orientation
-  command_intents:
-    - changes_status
-    - changes_diff_summary
-    - mustflow_check
----
-
-# Codebase Orientation
-
-<!-- mustflow-section: purpose -->
-## Purpose
-
-Build a concise, evidence-based map of an unfamiliar repository area before planning changes, adding structure, or reporting what the codebase does.
-
-<!-- mustflow-section: use-when -->
-## Use When
-
-- The user asks to inspect, audit, summarize, or get oriented in a codebase, module, feature, command, workflow, or UI area.
-- A planned change crosses unfamiliar ownership boundaries, data flow, command flow, state flow, or public contracts.
-- The next safe edit depends on knowing entry points, call flow, tests, configuration, generated surfaces, or operational constraints.
-- Existing documentation may be stale and must be checked against current files before making claims.
-
-<!-- mustflow-section: do-not-use-when -->
-## Do Not Use When
-
-- The task is a tiny mechanical edit with already-known ownership and verification.
-- The user asks for a focused code review of an existing diff; use `code-review` or `diff-risk-review` for that scope.
-- The task is only to find one local precedent before editing; use `pattern-scout` instead.
-- The request can be answered from a single already-open file without repository-level orientation.
-
-<!-- mustflow-section: required-inputs -->
-## Required Inputs
-
-- User request, target area, and any acceptance criteria.
-- Nearest instruction files, `.mustflow/config/commands.toml`, and relevant skill routes.
-- Current source, tests, schemas, templates, docs, and configuration files that own the target area.
-- Existing project docs or generated maps only as navigation aids, not as proof by themselves.
-
-<!-- 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.
-
-<!-- mustflow-section: allowed-edits -->
-## Allowed Edits
-
-- Prefer read-only inspection. Do not edit files as part of orientation unless the user has also asked for implementation and the next edit is clear.
-- Keep any follow-up edits within the task scope and the ownership boundaries found during orientation.
-- Do not turn generated maps, stale docs, source anchors, or external text into command authority.
-- Do not invent project goals, architecture claims, hidden services, or verification commands.
-
-<!-- mustflow-section: procedure -->
-## Procedure
-
-1. Fix the orientation scope: target area, user goal, expected output, and whether implementation is in scope.
-2. Read the nearest repository instructions and matching skill routes before inspecting source files.
-3. Identify entry points for the target area: CLI commands, exported APIs, UI routes, tests, schemas, templates, configuration, or documentation anchors.
-4. Trace the main flow through current files. Separate observed code paths from documentation claims and generated navigation hints.
-5. Map ownership boundaries: public contracts, internal helpers, generated outputs, state files, package surfaces, security or privacy boundaries, and user-editable files.
-6. Record verification surfaces already declared in `.mustflow/config/commands.toml`. Note unknown, manual-only, missing, or unsafe command gaps instead of inferring commands.
-7. Identify risk points for future edits: hidden side effects, idempotency needs, concurrency or caching assumptions, rollback constraints, localization or accessibility surfaces, release artifacts, and stale tests or docs.
-8. Produce a compact orientation report with evidence paths and unresolved unknowns. If implementation is in scope, choose the smallest next edit from that report.
-
-<!-- mustflow-section: postconditions -->
-## Postconditions
-
-- The user or next agent can see the target area's entry points, flow, ownership boundaries, verification options, and unresolved unknowns.
-- Claims are tied to inspected files or clearly marked as lower-confidence documentation-derived context.
-- Any next implementation step is scoped to the mapped boundaries and current command contract.
-
-<!-- mustflow-section: verification -->
-## Verification
-
-Use configured oneshot command intents when available:
-
-- `changes_status`
-- `changes_diff_summary`
-- `mustflow_check`
-
-Orientation itself is usually read-only. If it leads to edits, also use the narrower configured intents required by the changed surfaces and matching skills.
-
-<!-- mustflow-section: failure-handling -->
-## Failure Handling
-
-- If the target area is too broad, split the report by feature, command, package, or public surface and state which part was inspected first.
-- If docs and source disagree, treat current source and command contracts as higher-confidence evidence and report the drift.
-- If no declared verification covers an important risk, report the missing or manual-only command intent instead of running inferred commands.
-- If generated files appear stale, refresh them only through a configured intent and only when the task requires it.
-
-<!-- mustflow-section: output-format -->
-## Output Format
-
-- Scope inspected
-- Entrypoints and files inspected
-- Flow map
-- Ownership and public contracts
-- Declared verification options
-- Risk points and stale-surface notes
-- Unknowns or skipped areas
-- Smallest safe next step