mustflow 2.39.1 → 2.58.1

package/templates/default/locales/en/.mustflow/skills/database-query-bottleneck-review/SKILL.md

@@ -0,0 +1,194 @@
+---
+mustflow_doc: skill.database-query-bottleneck-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: database-query-bottleneck-review
+description: Apply this skill when code is created, changed, reviewed, or reported and database query performance risk can be spotted from the diff, including join fan-out, N+1 calls, over-eager loading, SELECT *, unstable LIMIT, OFFSET pagination, composite index fit, range predicates, functions on indexed columns, parameter type mismatch, wildcard search, OR predicates, large IN lists, COUNT for existence, NOT IN with NULL, LEFT JOIN filters, pre-aggregation, latest-row queries, wide sort/group/distinct, JSON filters, tenant and soft-delete scope, estimated-versus-actual row drift, statistics, plan-cache skew, missing-index recommendations, plan forcing, and long transactions.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.database-query-bottleneck-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Database Query Bottleneck Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Find database bottleneck candidates from code shape before reaching for live execution plans.
+
+The review question is: "How many rows can this request touch, how many times can it repeat, and can the available indexes follow the same path as the query?" Execution plans are evidence, but PR diffs often already reveal cardinality explosion, unbounded scans, index defeat, N+1 access, unstable pagination, and long transaction waits.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code is created, changed, reviewed, or reported and the risk is database query latency, row explosion, index mismatch, ORM query shape, resolver fan-out, transaction wait, pagination cost, or plan instability.
+- A list, feed, search, report, dashboard, export, admin table, GraphQL resolver, serializer, worker, queue consumer, background sync, import, API endpoint, repository, ORM model, query builder, raw SQL, stored procedure, or database-backed cache path is introduced or changed.
+- Code or docs claim a query is indexed, fast, paginated, batched, preloaded, eager-loaded, tenant-scoped, safe for large data, or covered by an execution plan.
+- The database engine is unknown or mixed, and the review must stay engine-agnostic while preserving hooks for PostgreSQL, SQLite, MySQL, SQL Server, or ORM-specific follow-up.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task changes database ownership, schema, migrations, persistence boundaries, data lifecycle, restore, export, or cache-as-store behavior; use `database-change-safety` or `database-migration-change` first and this skill only for query bottleneck adjunct review.
+- The task is PostgreSQL-specific, SQLite-specific, MySQL-specific, SQL Server-specific, or engine-feature-specific; use the matching engine skill first and this skill only for generic query-shape checks.
+- The task is a full measurement, benchmark, profiling, p95 or p99 performance budget, or production-tuning project; use `performance-budget-check` first.
+- The only database path is a tiny hard-capped lookup table, static seed list, or one-off admin maintenance query whose bounded size and manual nature are explicit.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Query surface: raw SQL, ORM call, query builder, repository method, resolver, serializer, worker, import/export path, report, dashboard, or transaction block under review.
+- Cardinality shape: starting rows, join fan-out, relation counts, tenant or user scope, filter selectivity, sort/group/distinct width, pagination depth, and data skew assumptions when known.
+- Repetition shape: loops, resolvers, serializers, lazy relations, per-item queries, queue consumers, retries, workers, pages, tenants, or nested calls that multiply query count.
+- Index and plan evidence when available: indexes, constraints, query plans, estimated and actual rows, loops, buffers, temp files, statistics freshness, extended statistics, covering-index expectations, plan-cache behavior, and missing-index recommendations.
+- Database and ORM context: engine, version when known, ORM eager or lazy loading behavior, generated SQL, parameter binding types, transaction defaults, connection pool limits, and read replica or plan cache behavior.
+- Correctness boundaries: tenant isolation, authorization, soft delete, retention, stable ordering, duplicate handling, null semantics, consistency, stale data, partial failure, and transaction semantics.
+- Relevant command-intent contract entries for build, tests, 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.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Required inputs are available, or missing row-count, index, ORM, or engine evidence can be reported without guessing.
+- If the query changes persisted behavior, migrations, authorization, tenant scope, privacy, or public API output, also apply the relevant database, security, migration, or API skill.
+- If engine-specific claims are made, use the matching engine skill before claiming feature support or plan behavior.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Narrow projection, add stable ordering, convert offset pagination to keyset or cursor pagination, batch per-item queries, replace lazy relation access with explicit loading, push joins and aggregation to the database, pre-aggregate before joining, and shorten transactions when semantics are clear.
+- Add or adjust index declarations, generated columns, expression indexes, partial indexes, composite index order, query hints, statistics notes, or plan evidence only when the repository owns that surface and the engine-specific skill supports the change.
+- Add focused tests or fixtures for query count, stable ordering, tenant scope, authorization, pagination, null semantics, duplicate handling, and generated SQL when local patterns support them.
+- Do not add speculative indexes, caches, denormalization, materialized views, plan forcing, read replicas, or search infrastructure without workload evidence and ownership of write cost, freshness, and invalidation.
+- Do not trade correctness, tenant isolation, authorization, null semantics, stable pagination, or transaction safety for a faster-looking query.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Start with cardinality, not SQL prettiness. Multiply parent rows by child rows and joined relation counts. A path like user to orders to items to options can explode before any single predicate looks suspicious.
+2. Count query repetition.
+   - Treat DB calls inside `for`, `map`, `forEach`, streams, serializers, resolvers, template rendering, and queue consumers as N+1 candidates.
+   - Open helper and ORM relation bodies; property access can be a query when lazy loading is enabled.
+3. Check eager loading with suspicion.
+   - Eager loading, `includes`, `preload`, `join fetch`, and `select_related` can replace N+1 with overfetching.
+   - Verify the screen, API, worker, or report needs the loaded relations and columns.
+4. Check projection width.
+   - Flag unbounded `SELECT *`, full entity hydration, wide DTOs, large JSON, TEXT, BLOB, image, metadata, and audit columns in list or sort paths.
+   - Prefer thin keys and required columns first, then fetch detail columns only after narrowing the row set.
+5. Check deterministic ordering.
+   - `LIMIT` without stable `ORDER BY` is not a real pagination contract.
+   - `ORDER BY` with `LIMIT` needs an index-compatible ordering or the database may sort a large working set to return a few rows.
+6. Check offset pagination.
+   - Large `OFFSET ... LIMIT ...` usually means the database counts and discards earlier rows.
+   - Prefer keyset or cursor pagination with a stable tie-breaker such as `(created_at, id)` when arbitrary page jumps are not a product requirement.
+7. Match composite indexes to query shape.
+   - Review equality predicates, range predicates, join keys, sort keys, and grouping keys in order.
+   - Do not assume "all WHERE columns are in the index" means the index is useful.
+   - Identify where the index stops narrowing and starts scanning, especially after range predicates.
+8. Look for index defeat.
+   - Functions or casts around columns, such as `LOWER(email)`, `DATE(created_at)`, `CAST(id AS text)`, timezone conversion, arithmetic, or JSON extraction can prevent ordinary index use.
+   - Use normalized stored values, generated columns, expression indexes, or query rewrites when the engine and workload justify them.
+9. Check parameter and type mismatch.
+   - UUID versus text, integer versus string, timezone-aware versus local timestamp, decimal versus float, collation mismatch, and enum/string mismatch can distort plans or force casts.
+   - Bind parameters in the column's native type where the driver and ORM allow it.
+10. Classify search patterns.
+    - Prefix search and contains search are different workloads.
+    - Leading wildcard `LIKE '%term%'`, case-insensitive search, trigram, full-text, search-engine, and separate search-table paths need explicit ownership.
+11. Check `OR`, `IN`, and existence shapes.
+    - `OR` across different columns can confuse index choice; consider separate queries or `UNION ALL` only when duplicate and ordering semantics are clear.
+    - Very large `IN` lists can hurt parsing, planning, network transfer, and cache behavior; consider temp tables, array parameters, table-valued parameters, bulk insert plus join, or batching.
+    - Use `EXISTS` for existence checks instead of `COUNT(*) > 0` when exact counts are unnecessary.
+12. Check negative logic and null semantics.
+    - `NOT IN` with NULLs can return surprising results; prefer `NOT EXISTS` or explicit NULL policy.
+    - `LEFT JOIN` followed by `WHERE right_table.col = ...` often turns into an inner join. Decide whether null-preserving behavior belongs in the join condition or the result filter.
+13. Aggregate before join fan-out.
+    - Avoid joining several one-to-many tables and grouping only at the end when each table can be pre-aggregated to the needed grain first.
+    - Check whether `DISTINCT` is hiding accidental duplicate multiplication instead of solving the query shape.
+14. Check latest-row and per-parent subqueries.
+    - A correlated subquery that asks for the latest child row per parent can become one lookup per parent.
+    - Prefer window functions, `DISTINCT ON`, lateral joins, grouped max joins, or precomputed current rows when the engine and semantics support them.
+15. Keep sorts, groups, and distinct narrow.
+    - Sorting, grouping, or de-duplicating wide rows with large text, JSON, or blob columns burns memory and temp storage.
+    - Narrow to keys first, then join or fetch large columns after the winning rows are known.
+16. Treat JSON filters as schema decisions.
+    - A frequently queried JSON path is no longer "just metadata".
+    - Promote it to a real column, generated column, expression index, GIN-style index, or search surface when query volume and engine support justify it.
+17. Check tenant and soft-delete scope.
+    - Multi-tenant reads, updates, deletes, counts, and background jobs need tenant or account scope unless a cross-tenant operation is explicit and bounded.
+    - Soft-delete predicates such as `deleted_at IS NULL` often belong in partial indexes, default scopes, and tests, but default scopes must not hide admin or retention semantics.
+18. Separate planner evidence from wishful thinking.
+    - Compare estimated rows and actual rows when plan evidence exists; large gaps point to stale statistics, missing extended statistics, correlation mistakes, or data-skew problems, not only missing indexes.
+    - Treat `EXPLAIN` without runtime evidence as a hypothesis. Prefer representative runtime evidence such as PostgreSQL `EXPLAIN ANALYZE`, MySQL `EXPLAIN ANALYZE`, SQL Server actual execution plans, Query Store history, ORM query-count traces, or production telemetry when the repository has safe access to it.
+    - Check loops, rows examined, rows returned, buffers, temp files, sort method, lock waits, pool waits, and query count when available.
+19. Treat plan cache, parameter skew, and missing-index advice carefully.
+    - Prepared statements and cached plans can regress when parameter values are skewed by tenant, status, country, or time.
+    - Missing-index recommendations are candidates, not commands; check overlap with existing indexes, write amplification, sort coverage, filtered or partial-index fit, and composite merge opportunities.
+    - Plan forcing is a last resort with monitoring and fallback, not proof that the query shape is healthy. It can freeze yesterday's good plan into tomorrow's outage when data shape changes.
+20. Check transaction scope.
+    - Long transactions, row locks, `SELECT FOR UPDATE`, external API calls, file upload waits, network calls, serialization, logging, and user-controlled waits inside a transaction can make a fast query produce slow service behavior.
+    - Shorten the transaction and move external effects after commit through outbox, job, or reconciliation patterns when needed.
+21. Label evidence honestly.
+    - Static diff review can identify likely bottlenecks but cannot prove actual latency.
+    - Use plan or production evidence only when representative parameters, data size, cache state, and engine version are known.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Query cardinality, repetition count, projection width, pagination shape, index-fit assumptions, and transaction scope are explicit.
+- N+1 access, over-eager loading, `SELECT *`, unstable `LIMIT`, large offset pagination, join fan-out, wide sort/group/distinct, bad existence checks, null-sensitive negative logic, unbounded `IN`, and long transactions are fixed or reported.
+- Index, statistics, extended-statistics, plan-cache, search, JSON, tenant, soft-delete, plan-forcing, and engine-specific claims are tied to evidence or marked as unverified.
+- Correctness, tenant isolation, authorization, ordering, null semantics, duplicates, stale data, and partial failure remain intact or are reported as tradeoffs.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured test, build, docs, release, or mustflow intent that covers the changed query path. Do not infer raw database shells, live query plans, migrations, profilers, load tests, or package-manager commands outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If row counts, index definitions, generated SQL, or ORM loading behavior are unknown, report static risk rather than claiming a query is safe or slow.
+- If a query change needs engine-specific feature support, stop at the generic recommendation and use the matching engine skill before editing.
+- If an index would improve reads but hurt writes or migrations, report the tradeoff and require workload evidence.
+- If the safe fix requires live database access, destructive migration, provider console action, or unconfigured plan commands, report the manual boundary instead of running raw commands.
+- If a configured test or build fails, preserve the failing intent and output tail, then fix only the query behavior or contract exercised by the failure.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Query path reviewed
+- Cardinality and repetition ledger
+- Projection, ordering, pagination, join fan-out, eager or lazy loading, index fit, search, JSON, tenant or soft-delete, plan evidence, estimated-versus-actual rows, statistics, plan-cache, missing-index, plan-forcing, and transaction checks where relevant
+- Query, index, batching, pagination, projection, aggregation, or transaction change made or recommended
+- Evidence level: static diff risk, configured-test evidence, plan evidence, measured production evidence, manual-only, missing, or not applicable
+- Command intents run
+- Skipped database measurements and reasons
+- Remaining database bottleneck risk

package/templates/default/locales/en/.mustflow/skills/deletion-lifecycle-review/SKILL.md

@@ -0,0 +1,171 @@
+---
+mustflow_doc: skill.deletion-lifecycle-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: deletion-lifecycle-review
+description: Apply this skill when code, schema, migrations, APIs, admin tools, jobs, storage, caches, search indexes, analytics, logs, backups, docs, tests, or reviews introduce, change, or assess delete, soft delete, hard delete, purge, restore, undelete, account deletion, tenant deletion, retention, legal hold, erasure, anonymization, pseudonymization, tombstone, backup recovery, PITR, WAL, binlog, transaction-log, downstream deletion, or deletion audit behavior.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.deletion-lifecycle-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Deletion Lifecycle Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep deletion behavior from pretending that hiding a row, flipping a boolean, or running `DELETE FROM` is the whole contract.
+
+The review question is: "Which kind of deletion is this, who can reverse it, what must survive for law or operations, what must disappear from every user-visible surface, and what evidence proves each downstream system caught up?" Treat deletion as a lifecycle with state, events, retention windows, recovery evidence, irreversible purge boundaries, backup residue, and audit limits.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code, schema, migrations, repositories, APIs, admin tools, UI actions, jobs, workers, tests, docs, or reviews create or change delete, soft delete, hard delete, purge, restore, undelete, account deletion, tenant deletion, data retention, legal hold, erasure, anonymization, pseudonymization, or tombstone behavior.
+- A table, model, or query adds or depends on `is_deleted`, `deleted_at`, `deleted_by`, `delete_reason`, `delete_source`, `restore_deadline_at`, `restored_at`, `restored_by`, `purged_at`, `scheduled_for_purge_at`, `legal_hold`, `retention_until`, or similar fields.
+- A feature must remove data from search indexes, caches, object storage, generated files, data warehouses, analytics tools, email tools, CRM, billing providers, webhooks, queues, exports, or backups.
+- A delete flow interacts with PITR, backup retention, WAL, binlog, transaction logs, object-lock storage, restore drills, partition drops, bulk delete jobs, tenant offboarding, or operational dry-run approval.
+- A task claims that data is deleted, recoverable, irreversible, anonymized, retained for legal reasons, hidden from users, removed from downstream systems, or safe to restore.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only removes source code, files, feature flags, dead branches, or generated artifacts from the repository and no product data, persisted state, user data, audit record, backup, or downstream store is involved.
+- The task only changes queue message settlement terms such as ack, nack, reject, or delete with no data deletion lifecycle; use `queue-processing-integrity-review`.
+- The task only changes database query performance around soft-delete predicates; use `database-query-bottleneck-review` first and this skill only when lifecycle, restore, purge, retention, or downstream deletion semantics are present.
+- The task only changes generic schema ownership with no deletion, retention, restore, purge, or legal-hold behavior; use `database-change-safety`.
+- The task is only a migration rollout question; use `database-migration-change` or `migration-safety-check` first and this skill as an adjunct for delete-state compatibility.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Deletion class: hide from normal views, user-restorable soft delete, operator-restorable recovery, legal-retention hold, anonymization or pseudonymization, cryptographic erasure, hard purge, tenant offboarding, or bulk retention purge.
+- Entity and dependency graph: parent rows, child rows, ownership relationships, business records, audit logs, files, search documents, caches, analytics, warehouse tables, external services, exports, backups, and public identifiers.
+- State model: allowed states, allowed transitions, actor, source, reason, request id, timestamp policy, restore deadline, purge deadline, legal hold rules, and terminal states.
+- Query and uniqueness model: default visibility, admin visibility, global scopes, row-level security, repository filters, partial unique indexes, active-only indexes, deleted-id reuse policy, and public URL or webhook identity rules.
+- Recovery model: who can restore, restore scope, point-in-time recovery assumptions, sidecar restore instance workflow, related rows and external resources to revive, audit evidence, and restore drill expectations.
+- Purge and retention model: hard-delete timing, legal basis for retention, backup residue window, tombstone shape, downstream delete events, idempotent workers, retries, dry-run approval, batch size, partition strategy, and observability.
+- Privacy and audit model: personal data separation, anonymization or pseudonymization, sensitive audit redaction, append-only logs, legal hold ownership, and cryptographic erase key ownership where relevant.
+- Relevant command-intent contract entries for tests, 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 deletion class, dependency graph, restore, purge, legal, backup, or downstream evidence can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If deletion affects personal data, authentication, authorization, tenant scope, audit logs, security events, backups, or legal claims, also use the relevant security, privacy, database, adapter, or migration skill.
+- If deletion behavior is a state machine, also use `state-machine-pattern` when editing executable state-transition code.
+- If deletion is asynchronous or crosses external systems, also use idempotency, queue, observability, or transaction-boundary skills as needed for the changed path.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or change deletion states, columns, constraints, partial indexes, repositories, scopes, policies, tombstone tables, purge jobs, restore jobs, downstream deletion events, audit records, tests, fixtures, docs, and directly synchronized template surfaces tied to the task.
+- Replace a lone `is_deleted` or unscoped `deleted_at` behavior with explicit lifecycle fields when the changed surface justifies it.
+- Add dry-run, batch cursor, idempotency key, legal-hold guard, restore ledger, purge ledger, and downstream progress tracking when required by the changed deletion path.
+- Do not use `ON DELETE CASCADE` for business records unless ownership is proven and audit, retention, restore, and legal obligations are unaffected.
+- Do not store sensitive pre-delete values in audit logs solely to prove deletion happened.
+- Do not claim irreversible erasure while backups, logs, downstream stores, exports, or encryption keys can still reconstruct the data unless that residual window is explicit.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the deletion.
+   - Hidden from ordinary views: data remains current enough for admin or recovery paths but must not appear in user-facing lists, search, recommendations, exports, or APIs.
+   - User-restorable soft delete: the user can undo within a defined window.
+   - Operator recovery: staff can recover from mistake, compromise, or incident with stronger audit and approval.
+   - Legal hold or mandatory retention: data must stay for a legal, financial, security, or dispute reason even when user-facing identity is removed.
+   - Anonymization or pseudonymization: personal identifiers are detached while required business facts remain.
+   - Hard purge or cryptographic erasure: data is made unrecoverable within a stated operational and backup boundary.
+2. Build the deletion graph.
+   - List parent rows, child rows, join rows, files, generated artifacts, cache entries, search documents, analytics rows, warehouse rows, webhook states, provider ids, exports, and backups.
+   - Separate true owned children from business records that must survive, such as orders, invoices, ledger entries, tax records, audit logs, usage records, and security events.
+   - Reject broad cascade deletes when ownership, restore, legal retention, and audit survival are unclear.
+3. Check the state machine.
+   - Prefer explicit states such as `active`, `pending_deletion`, `soft_deleted`, `restore_requested`, `scheduled_for_purge`, `legal_hold`, `purging`, and `purged` when more than one delete outcome exists.
+   - Record delete and restore events with actor, source, reason, request id, server UTC timestamp, and any user-local timestamp needed for support.
+   - Keep restore events distinct from clearing `deleted_at`; preserve who restored, why, and which deletion event was reversed.
+   - Prevent contradictory states such as restored and purged at the same time, legal hold plus purge, or deleted rows still eligible for normal workflow actions.
+4. Check query, identity, and uniqueness behavior.
+   - Do not rely on every caller remembering `deleted_at IS NULL`. Use repository boundaries, global scopes, views, row-level policies, or other local enforcement patterns.
+   - Add active-only unique indexes or equivalent constraints when soft-deleted rows should not block future active records.
+   - Never reuse exposed ids, order numbers, account ids, tenant ids, webhook ids, or storage keys after deletion.
+   - Keep tombstones for hard-deleted entities when duplicate webhooks, retries, imports, sync jobs, caches, or external providers need to know the entity used to exist.
+5. Check restore semantics.
+   - Define what is restored: core row only, permissions, memberships, subscriptions, files, search visibility, notification settings, tokens, provider mappings, generated records, and external-service state.
+   - Do not treat PITR as a single-record undo button. If point-in-time recovery is relevant, define whether it restores a separate instance, extracts rows, reconciles relationships, and replays current-state differences.
+   - Store enough recovery anchors, such as UTC event time, request id, transaction id, logical sequence, or provider event id, without leaking sensitive data.
+6. Check purge, retention, and legal boundaries.
+   - Define `scheduled_for_purge_at`, `purged_at`, purge actor or job id, legal hold owner, retention basis, backup residue window, and downstream completion criteria.
+   - Separate personal data from business facts so legal retention does not force keeping unnecessary identifiers.
+   - Consider cryptographic erase only when key ownership, key scope, backup copies, and remaining metadata are explicit.
+   - Make backup and log retention honest: operational deletion can be immediate while backups age out later.
+7. Check downstream deletion.
+   - Emit or record deletion work for search, cache, object storage, generated files, analytics, warehouses, email tools, CRM, billing providers, external integrations, exports, and webhooks where relevant.
+   - Make workers idempotent, resumable, observable, and safe to retry.
+   - Track per-system pending, success, failure, skipped, and blocked states when deletion crosses systems.
+8. Check bulk and tenant deletion.
+   - Use dry-run counts and approval for admin deletion tools.
+   - Process large deletes in bounded batches with a stable cursor and resume point.
+   - Prefer partition drop or detach for date-retention logs when the schema supports it.
+   - For tenant deletion, verify `tenant_id` leading indexes, partition strategy, cross-tenant references, shared resources, and rate limits before deleting large populations.
+9. Check audit and privacy.
+   - Keep deletion audit append-only and separate from rows that may be purged.
+   - Log decisions, actor, request id, result, and reason codes without copying full personal data into audit logs.
+   - Redact or hash sensitive identifiers when audit evidence does not require raw values.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The deletion class, state transitions, restore path, purge path, retention boundary, legal hold behavior, and backup residue window are explicit.
+- Deleted data cannot leak through ordinary queries, admin views, search, caches, generated artifacts, exports, or downstream systems without that exception being intentional and documented.
+- Hard purge and erasure claims are tied to tombstones, audit survival, downstream completion, backup/log age-out, or cryptographic erase evidence.
+- Existing rows, old/new writers, migrations, batch jobs, restore drills, and operator dry-runs are addressed when affected.
+- Remaining deletion lifecycle risk is named instead of hidden behind `is_deleted`.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+- Run the narrowest configured tests covering deletion states, default visibility, restore, purge, legal hold, partial unique indexes, cascade boundaries, tombstones, downstream deletion jobs, idempotency, batch resume, audit redaction, and template packaging changed by the task.
+- Use configured docs and release checks when skill text, routes, templates, package metadata, or user-facing docs change.
+- Prefer tests that prove deleted rows stay hidden from ordinary paths, active uniqueness still works, restores rebuild expected relationships, purges keep tombstones, legal holds block purge, and downstream deletion work is resumable.
+- If backup, PITR, object-lock, legal, or external-provider behavior cannot be exercised locally, report that evidence as manual-only or missing instead of claiming it passed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the deletion class is unknown, stop before implementing hard delete or purge and report the missing policy.
+- If legal retention conflicts with user erasure, preserve the legal boundary, remove unnecessary personal identifiers, and report the policy decision needed.
+- If a broad cascade would delete business records or audit evidence, block the cascade and require an explicit per-entity deletion plan.
+- If downstream systems cannot confirm deletion, record pending or failed state and avoid claiming completion.
+- If a configured test or build fails, preserve the failing intent and output tail, then fix only the deletion lifecycle contract or synchronized surface exercised by the failure.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+Report:
+
+- Deletion surface reviewed
+- Deletion class and state model
+- Entity, file, cache, search, analytics, external-service, export, backup, and tombstone graph
+- Visibility, uniqueness, identity reuse, cascade, legal hold, audit, restore, purge, backup, and downstream deletion decisions
+- Batch, tenant, partition, dry-run, idempotency, and observability notes
+- Tests and command intents run
+- Evidence level: static diff risk, configured-test evidence, migration evidence, restore drill evidence, external-system evidence, manual-only, missing, or not applicable
+- Remaining deletion lifecycle risk