mustflow 2.115.16 → 2.116.0

package/templates/default/locales/en/.mustflow/skills/command-pattern/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.command-pattern
 locale: en
 canonical: true
-revision: 13
+revision: 14
 lifecycle: mustflow-owned
 authority: procedure
 name: command-pattern
@@ -29,7 +29,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Model a state-changing user or system intent as one clear execution unit.
+Model one accepted state-changing user or system intent and its local commit as one clear execution unit. This skill does not own the full durable lifecycle after acceptance.
 
 A command is not a decorative wrapper around a button handler or function. It is the application-level unit that gathers input validation, authorization, domain object loading, domain rule execution, state changes, transaction boundaries, idempotency, audit evidence, event recording, failure handling, retry decisions, and observability around one intent.
 
@@ -73,6 +73,9 @@ Use commands to make these questions answerable later:
 - The only problem is business logic mixed with I/O; use `pure-core-imperative-shell` first and let this skill shape the shell execution unit when state changes need command semantics.
 - The only problem is provider, SDK, database, file, webhook, queue, cache, or framework object leakage; use `adapter-boundary` and `dependency-injection`.
 - The only problem is that several already-owned subsystem steps need one stable caller-facing entry point; use `facade-pattern` unless the operation also needs command payload, context, idempotency, audit, retry, transaction, outbox, or queue semantics.
+- The work spans multiple durable steps, checkpoints, process loss, callbacks, or compensation; use `durable-workflow-orchestration`. The command may accept or start that workflow, but does not redefine its lifecycle.
+- The main contract is truthful run, attempt, checkpoint, or effect evidence across executions; use `execution-ledger-integrity-review`.
+- The main contract derives allow, deny, limit, downgrade, or obligation decisions; use `policy-decision-integrity-review`. The command consumes the decision.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
@@ -88,7 +91,7 @@ Use commands to make these questions answerable later:
 - Work-acceptance response policy, such as immediate success, queued status, processing status, or accepted response; job status vocabulary; deduplication key; attempt limit; next-run time; lock expiry; dead-letter handling; and worker ownership.
 - Queue contract details when work crosses a queue: queue name, business urgency, job id, job type, schema version, created time, run-after time, attempt count, idempotency key, request or trace context, safe payload reference, retry categories, timeout, dead-letter target, ordering requirement, and manual replay rule.
 - AI work accounting when relevant: feature key, model key, usage ledger entry, user request id, provider call id, pricing snapshot, cache-hit type, retry grouping, cost limit, and whether failed or unknown calls require reconciliation before retry.
-- AI policy decision when relevant: estimated cost, remaining budget, selected model, fallback model, blocked reason, maximum input tokens, maximum output tokens, maximum tool calls, maximum agent steps, timeout, and whether provider budgets are only secondary guardrails.
+- AI policy decision when relevant: the already-derived allow, deny, limit, downgrade, or obligation result that the command consumes without redefining policy.
 - Cost-bearing work accounting when relevant: value unit, cost unit, workspace or account quota, shared tenant credit pool, free-plan limit, user-action fan-out, usage event, rollup target, and whether retries or duplicate jobs can double-count cost.
 - Idempotency layers for request acceptance, job execution, provider calls, and incoming webhooks, including scope, request hash, duplicate result behavior, and different-payload conflict behavior.
 - Existing local conventions for result types, option types, domain errors, repositories, gateways, unit of work, outbox, audit logs, command buses, and tests.
@@ -173,9 +176,9 @@ Use commands to make these questions answerable later:
    - Schedule follow-up work only after the command decision is persisted.
    - For payment, point, credit, inventory, entitlement, subscription, coupon, and refund commands, prefer append-only ledgers or action records as the evidence source. Treat summary balances or statuses as derived or transactionally updated read state.
    - For ordinary content, account, and workflow commands, persist the core state and outbox or job records before triggering analytics, email, search indexing, AI processing, statistics, cache purge, or feed refresh work.
-   - For cost-bearing AI commands, persist the accepted work, idempotency decision, usage-limit decision, and job or outbox record before a worker performs model calls. Record actual usage, retry grouping, cache-hit type, pricing snapshot, and provider outcome after the call.
-   - For agentic AI commands, persist the policy decision and hard caps before the first model call. Steps, tool calls, total tokens, elapsed time, and cost should be bounded by the command or job contract, not by provider defaults or operator memory.
-   - For any cost-bearing command, check plan, tenant, quota, credit, request-size, and rate limits before accepting the work when possible. Record usage intent or reserved quota before fan-out work starts, then reconcile actual usage after workers and provider calls complete.
+   - For cost-bearing AI commands, persist accepted work and reservation consumption before a worker performs model calls. `credit-ledger-integrity-review` owns prepaid or money-equivalent reserve, capture, and release invariants; `llm-token-cost-control-review` owns token estimates and caps.
+   - For agentic AI commands, consume and persist the policy decision and accepted-work limits before the first model call. Route policy derivation to `policy-decision-integrity-review` and multi-step resume or compensation to `durable-workflow-orchestration`.
+   - A command may consume an existing reservation or quota allocation, but it must not redefine credit-ledger balance invariants. Keep accepted-work reservation persistence here and reserve, capture, and release accounting in `credit-ledger-integrity-review`.
    - When one command creates many internal jobs, record the causation relationship so thumbnails, OCR, AI calls, embeddings, search indexing, notifications, logs, analytics exports, and webhooks can be attributed to the original user action without losing retry or cost detail.
    - For HTTP acceptance of long-running work, persist the command result, job row, or outbox row in the same local transaction, then return the created resource identifier and current status. Do not make the HTTP request wait for the worker's external side effect unless the product contract truly requires immediate completion.
    - For external API work, persist the internal intent before the provider call becomes the only record. Payment, email, map, AI, search, file, and webhook follow-up commands should leave enough local evidence to answer what was attempted, why, for whom, and how to retry or reconcile it later.
@@ -236,6 +239,7 @@ Use commands to make these questions answerable later:
    - Put exhausted or poison jobs into a dead-letter or manual-review state with safe error metadata instead of retrying forever.
    - Treat a queued failure as hidden until metrics, alerts, or operator review make it visible. Track queue depth, job age, retry count, failure rate, dead-letter growth, provider rate-limit pressure, and manual replay results for important queues.
    - Define the smallest operator actions that make the command recoverable at 03:00: resend a specific email, reprocess a specific webhook, retry a specific AI job, rebuild a specific search index, reconcile a specific payment attempt, or temporarily disable one provider-backed feature.
+   - When these steps must resume deterministically across process loss, callbacks, checkpoints, or compensation, hand the accepted command to `durable-workflow-orchestration`. When run, attempt, checkpoint, and effect receipts are the source of truth, use `execution-ledger-integrity-review`.
 17. Test command behavior.
     - Cover success, required input absence, invalid input, unauthorized actor, missing resource, state conflict, domain invariant failure, duplicate retry with same payload, duplicate key with different payload, transaction rollback, outbox creation, dependency failure, retryability, non-retryability, and concurrency conflicts.
     - Use fake repositories and gateways for handler unit tests.
@@ -250,7 +254,7 @@ Use commands to make these questions answerable later:
 - The handler has injected dependencies and handles one command.
 - Authorization, idempotency, transaction boundaries, outbox behavior, retry classification, concurrency protection, observability, and audit requirements are explicit where relevant.
 - Request, trace, command, job, cron, webhook, correlation, and causation identifiers are explicit where the command crosses asynchronous or external boundaries.
-- HTTP acceptance, durable job or outbox creation, worker ownership, queue separation, deduplication, retry budget, dead-letter behavior, and reconciliation rules are explicit when long-running or external work is involved.
+- HTTP acceptance and the local durable handoff are explicit; full multi-step resume, checkpoint, callback, and compensation semantics are owned by `durable-workflow-orchestration`.
 - Credit, quota, tenant-limit, usage-event, fan-out attribution, and retry-cost behavior are explicit when one command consumes high-cost resources or creates multiple internal jobs.
 - Expected command failures are returned as typed values.
 - External effects do not run inside local database transactions.

package/templates/default/locales/en/.mustflow/skills/concurrency-invariant-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.concurrency-invariant-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: concurrency-invariant-review
@@ -50,6 +50,7 @@ The review question is not "is the code correct in this order?" The stronger que
 - The task is only memory retention, listener cleanup, timer cleanup, or native resource lifetime; use `memory-lifetime-review` first unless cleanup can race with concurrent work.
 - The task is only backend retries, queues, idempotency, outbox, health, cache, or external-call deadlines; use `backend-reliability-change` first and this skill only for concurrent ownership and invariant timing.
 - The task is only error handling truthfulness; use `failure-integrity-review` first.
+- The main problem is parent-child task trees, join, cancellation propagation, deadlines, shutdown ownership, or orphan prevention rather than a shared-resource invariant; use `structured-concurrency-supervision-review`.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
@@ -139,6 +140,7 @@ The review question is not "is the code correct in this order?" The stronger que
     - Shutdown should define stop-accepting, drain, cancel, flush, close, and in-flight side-effect ownership.
     - `closed = true` is not enough if futures, workers, sockets, buffers, queues, or async continuations keep running.
     - Mutexes, semaphores, read-write locks, connection checkouts, rate-limit tokens, and permits must release on every exception path.
+    - Route parent-child join, cancellation propagation, deadline inheritance, and orphan prevention to `structured-concurrency-supervision-review`; keep shared-resource ownership and invariant timing here.
 15. Check deadlocks and starvation as wait-for systems.
     - A thread stack dump alone is not enough. Build a wait-for graph that connects threads, locks, condition variables, futures, queues, pool workers, callbacks, and external waits.
     - Separate lock-order deadlock, lost notification, callback reentry, sync-over-async, and thread-pool starvation; a saturated pool can freeze progress without any mutex cycle.

package/templates/default/locales/en/.mustflow/skills/credit-ledger-integrity-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.credit-ledger-integrity-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: credit-ledger-integrity-review
@@ -47,6 +47,7 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 - The task only reviews general business-rule placement without a balance, ledger, wallet, credit, point, or reconciliation surface; use `business-rule-leakage-review`.
 - The task only designs a generic lifecycle state machine with no ledger, amount, idempotency, balance, reservation, expiry, or reconciliation risk; use `state-machine-pattern`.
 - The task only reviews cache correctness for a non-balance value; use `cache-integrity-review`.
+- The task only reviews soft token, step, concurrency, request-count, or rate budgets that are not prepaid or money-equivalent; use the relevant LLM cost, agent execution, concurrency, or rate-limit skill.
 - The task requires production balance corrections, real refunds, data migrations, or direct database repair without explicit user approval and configured command support.
 
 <!-- mustflow-section: required-inputs -->
@@ -98,6 +99,7 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 16. Consume expiry lots deliberately. When credits expire, inspect FIFO, LIFO, earliest-expiry-first, or policy-specific lot allocation. Record lot-level consumption so later refund and audit can reconstruct the path.
 17. Race expiry and usage. Expiry batches must use the same ledger, lock, idempotency, and conditional update rules as user requests. Flag direct batch subtraction that bypasses wallet safeguards.
 18. Separate reservation from capture. Model reserved, captured, released, failed, expired, cancelled, and partially refunded states when credits are held before final purchase, fulfillment, or external payment completion.
+    - This ledger owns atomic reserve, capture, and release and the balance invariant. Commands and durable workflows may consume those operations but must not redefine balance availability, ownership, or accounting transitions.
 19. Draw allowed state transitions. Prevent arbitrary `status = REFUNDED`, `status = CAPTURED`, or `status = EXPIRED` writes. Each transition should have a guard, cause, effect, and idempotency rule.
 20. Preserve queue ordering or tolerate reordering. If deduction, cancellation, refund, or expiry events use a queue, prove user, wallet, or transaction-level ordering, or make each consumer robust to reordered events.
 21. Treat message redelivery as normal. Producers, queues, schedulers, and webhooks can duplicate events. Consumer-side ledger mutation must be idempotent with durable dedupe records.
@@ -117,6 +119,7 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 - The credit surface has balance, ledger-entry, source identity, atomicity, amount/unit, ownership, expiry/lot, reservation, queue/cache, audit, and reconciliation maps.
 - Any mutable-balance-only path, missing source key, weak idempotency comparison, non-atomic deduction, wrong lock target, float amount, hidden rounding policy, missing DB invariant, duplicate ledger risk, generic refund, expiry race, cache-trusted deduction, stale replica read, unaudited admin adjustment, or missing reconciliation is fixed or reported with evidence.
 - Tests or explicit verification cover the highest-risk concurrency, failure, duplicate, expiry, reservation, refund, cache, and reconciliation paths available in the current scope.
+- Soft operational budgets remain outside this ledger unless they represent prepaid or money-equivalent value.
 
 <!-- mustflow-section: verification -->
 ## Verification

package/templates/default/locales/en/.mustflow/skills/dual-write-consistency/SKILL.md

@@ -0,0 +1,170 @@
+---
+mustflow_doc: skill.dual-write-consistency
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: dual-write-consistency
+description: Apply this skill when one logical operation changes durable state and separately publishes, projects, calls, or writes to another independently committed system, including database-plus-broker outbox or inbox flows, CDC, relay workers, event application ledgers, split outcomes, eventual convergence, reconciliation, and crash-point verification.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.dual-write-consistency
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Dual Write Consistency
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep one logical result truthful when it crosses independently committed databases, brokers,
+indexes, files, or providers. Own the delivery and convergence protocol; do not pretend two commits
+are one transaction or that broker delivery alone proves business convergence.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A durable mutation and an event publish, projection update, webhook, provider mutation, or second
+  store write belong to one logical outcome but cannot commit atomically.
+- Code introduces an outbox, inbox, relay, CDC stream, publisher claim, applied-event ledger,
+  reconciliation worker, or eventual-convergence claim.
+- The path can crash between local commit, publish acceptance, publish recording, consumer effect,
+  consumer commit, and broker acknowledgement.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- One database transaction with no independent commit boundary owns the whole invariant; use
+  `transaction-boundary-integrity-review`.
+- The main failure is one logical request repeating; use `idempotency-integrity-review`.
+- The main failure is broker acknowledgement, visibility, prefetch, poison-message, or DLQ behavior;
+  use `queue-processing-integrity-review`.
+- The path is an old/new schema migration dual-write; use `migration-safety-check`.
+- The path is a multi-step resumable saga with waits or compensation; use
+  `durable-workflow-orchestration`.
+- Two writes happen in one local transaction, such as an order row and its audit row. That is not a
+  dual write merely because two tables changed.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Consistency-surface ledger: authoritative mutation, derived destinations, and every independent
+  commit boundary.
+- Identity ledger: operation, event, causation, correlation, aggregate, ordering, payload hash, and
+  schema-version identities.
+- Outbox and inbox ledger: unique keys, states, owner, claim lease, attempts, timestamps, and stale
+  claim recovery.
+- Delivery ledger: producer confirmation, consumer transaction, acknowledgement position,
+  duplication, ordering, and redelivery contract.
+- Convergence ledger: acceptable lag, drift detector, reconciliation owner, repair direction, and
+  operator-visible terminal or unresolved state.
+- Failure-injection ledger: expected durable state after every crash boundary.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read the nearest instructions, command contract, source-of-truth model, producer, consumer,
+  persistence schema, and retry or replay paths.
+- Name one authoritative fact and every derived fact. If authority is peer-to-peer or bidirectional,
+  define conflict resolution before implementation.
+- Treat provider, broker, and database guarantees as unverified until matched to the configured
+  code path and current deployment contract.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten outbox, inbox, applied-event, relay-claim, delivery-state, drift-detection,
+  reconciliation, repair-command, and focused crash-injection surfaces.
+- Synchronize event envelopes, schemas, migrations, tests, docs, metrics, and templates that own the
+  same convergence contract.
+- Do not hide split outcomes behind a broad transaction wrapper, memory-only flag, best-effort log,
+  or broker exactly-once marketing claim.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Draw the logical operation and every independent commit boundary.
+2. Choose the source of truth and label each destination authoritative, derived, cached, indexed,
+   externally owned, or observational.
+3. Put the authoritative mutation and outgoing intent record in one local transaction when that
+   store supports it. If not, name the unavoidable gap and repair protocol.
+4. Give each logical event a stable ID, causation ID, correlation ID, aggregate or ordering key,
+   payload hash, and schema version required by its consumers.
+5. Make relay claims durable and bounded. Record owner, lease or generation, attempt, next eligible
+   time, and stale-claim recovery; a process-local lock is not ownership proof.
+6. Treat a crash after publish but before publish-success recording as duplicate-possible. Resume by
+   identity and confirmation or reconciliation, not by assuming the publish failed.
+7. Put the consumer inbox or applied-event unique constraint and irreversible business effect in one
+   transaction when possible. An application-level `if exists` is not durable uniqueness.
+8. Separate per-aggregate ordering from globally unordered delivery. Reject or defer stale events
+   when state depends on sequence; make commutative consumers explicit when order is irrelevant.
+9. Preserve original identity through poison classification, schema rejection, DLQ transfer, and
+   replay. A replay creates a new attempt, not a new logical event.
+10. Define reconciliation for missing, duplicate, stale, unknown, and divergent states. State which
+    side wins, which repair command runs, who approves destructive repair, and how convergence is
+    rechecked.
+    - This skill owns delivery, consumer-application, and projection convergence across independent
+      commits. Route workflow-step, terminal-state, and compensation-state recovery to
+      `durable-workflow-orchestration`.
+11. Distinguish transport settlement, consumer commit, business convergence, and operator closure.
+    Do not report one as proof of the next.
+12. Inject crashes after local commit, before and after publish, after consumer effect, after consumer
+    commit, and before acknowledgement. Also test duplicate, reordered, poison, stale-lease, and DLQ
+    replay paths.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every crash point leaves the operation durably pending, duplicate-safe, reconciliable, or
+  explicitly unresolved; no state silently disappears.
+- Relay and consumer ownership, event application, and repair are protected by durable identities,
+  constraints, leases or generations, and bounded retries.
+- Outbox-only implementations do not claim completion without consumer duplicate control and a
+  reconciliation story.
+- Evidence distinguishes local commit, delivery, application, convergence, and closure.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+- Use configured `changes_status` and `changes_diff_summary` for scope evidence.
+- Use `lint`, `build`, and `test_related` for changed implementation and focused crash paths; use
+  `test` or `test_audit` when shared reliability coverage or test claims require it.
+- Use `docs_validate_fast`, `test_release`, and `mustflow_check` when contracts, templates, package
+  output, or Mustflow surfaces change.
+- Record unavailable broker, multi-process, chaos, or live-provider evidence instead of inventing
+  commands or approving a static claim as runtime proof.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the source of truth or repair direction is unknown, stop convergence edits and report the
+  conflicting authorities.
+- If one split outcome cannot be detected, preserve it as an explicit unknown state and add an
+  operator repair boundary before claiming safety.
+- If an implementation relies only on an outbox, broker exactly-once mode, Redis TTL, logs, or an
+  application check, report the missing durable consumer or reconciliation proof.
+- If verification fails, preserve the crash point and invariant, then use `failure-triage` before
+  broadening the change.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Logical operation, source of truth, and independent commit boundaries
+- Event identity, outbox, relay, inbox, ordering, settlement, and convergence decisions
+- Crash, duplicate, stale-owner, poison, replay, and reconciliation evidence
+- Files changed and compatibility impact
+- Command intents run, skipped checks, and reasons
+- Remaining split-brain or convergence risk

package/templates/default/locales/en/.mustflow/skills/durable-workflow-orchestration/SKILL.md

@@ -0,0 +1,167 @@
+---
+mustflow_doc: skill.durable-workflow-orchestration
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: durable-workflow-orchestration
+description: Apply this skill when one business outcome spans multiple commands, persisted entities, services, callbacks, timers, approvals, retries, or compensations and must resume after process loss or deployment through a versioned durable workflow instance.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.durable-workflow-orchestration
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Durable Workflow Orchestration
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Own long-running progress across several transaction and resource boundaries. Make workflow state,
+waits, retries, compensation, forward recovery, resume compatibility, and operator intervention
+durable without pretending external effects can be rolled back like one database transaction.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- One business goal crosses two or more commands, persisted entities, services, or providers.
+- The flow waits for callbacks, timers, approvals, retries, leases, or human intervention.
+- A process restart or deployment must resume the exact safe step without repeating completed
+  external effects.
+- The design uses a saga, process manager, workflow instance, durable checkpoint, compensation, or
+  manual-recovery state.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- One accepted intent and local commit boundary is the whole operation; use `command-pattern`.
+- One entity transition table owns the lifecycle; use `state-machine-pattern`.
+- The main failure is a database-and-publish split; use `dual-write-consistency`.
+- The main failure is queue settlement, duplicate logical delivery, or child-task lifetime; use
+  `queue-processing-integrity-review`, `idempotency-integrity-review`, or
+  `structured-concurrency-supervision-review` respectively.
+- LLM autonomy, tool choice, or approval of model-directed work is the main concern; use
+  `agent-execution-control-review` and apply this skill only to the durable workflow underneath it.
+- An order with one local `PENDING -> PAID -> SHIPPED` transition table is not automatically a
+  durable workflow. A callback-driven payment and fulfillment process across checkpoints is.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Workflow identity and definition-version ledger.
+- Step ledger: input snapshot, command ID, dependency, deadline, attempt, owner, allowed next events,
+  and durable completion evidence.
+- Effect classification ledger: `reversible`, `compensatable`, `forward-recovery-only`, or
+  `manual-intervention`.
+- Checkpoint and resume-compatibility ledger for code, state schema, configuration, and policy.
+- Compensation ledger linking each compensating command to its original effect and idempotency key.
+- Timer, lease, cancellation, late-event, terminal-state, and reconciliation ledgers.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read the nearest instructions, command contract, participating commands and state machines,
+  persistence model, queue or timer path, external effects, operator tools, and current tests.
+- Name the business outcome and every independently owned participant before designing the workflow.
+- Treat a compensation as a new effect with its own failure modes, never as time reversal.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten workflow instances, step records, checkpoints, timers, leases, compensation
+  commands, resume compatibility, cancellation, manual-intervention, reconciliation, tests, metrics,
+  docs, and directly synchronized templates.
+- Keep individual command payloads and entity transition rules in their owning command and state
+  machine layers.
+- Do not serialize arbitrary runtime objects, closures, clients, credentials, hidden reasoning, or
+  raw conversations as workflow state.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. State the business outcome and list each participant, transaction boundary, external effect, wait,
+   callback, timer, and operator decision.
+2. Check whether one command or one entity state machine is sufficient. Do not introduce a durable
+   workflow for a local sequence that cannot survive or need process loss.
+3. Create a stable workflow instance ID and pin the workflow definition, state schema, code,
+   configuration, and policy versions required for safe resume.
+4. Record each step's normalized input snapshot, command identity, dependency, deadline, attempt,
+   owner, next permitted events, and durable completion evidence.
+5. Persist step completion and the next durable work request atomically where possible. Route any
+   independent commit split through `dual-write-consistency`.
+6. Classify every effect as reversible, compensatable, forward-recovery-only, or
+   manual-intervention. Do not label email, payment, published data, or external user-visible effects
+   rollback-safe without provider-specific proof.
+7. Model compensation as a separate idempotent command tied to the original command, resource,
+   amount or scope, workflow instance, and reason. Give compensation its own retry and terminal state.
+   Use a distinct operation type and idempotency namespace or key for the compensation; never reuse
+   the original effect key without an explicit operation discriminator.
+8. Store semantic workflow state and ledger positions in checkpoints. Rebuild runtime clients and
+   transient caches on resume instead of serializing them.
+9. On resume, verify workflow definition, schema, code, configuration, and policy compatibility.
+   Migrate, continue under the pinned version, or stop for intervention; never guess through drift.
+10. Fence stale owners and reject late callbacks, timers, or completions from an older workflow
+    generation or already-closed step.
+11. Define cancellation separately from compensation. State which pending work stops, which accepted
+    external effects continue, which compensations start, and when cancellation becomes terminal.
+12. Preserve partial completion and compensation failure as observable outcomes such as
+    `FORWARD_RECOVERY_REQUIRED` or `MANUAL_INTERVENTION`, not generic failure or false rollback.
+13. Test restart before and after every step, duplicate and late completion, version drift, timer
+    expiry, stale owner, cancellation, compensation failure, reconciliation, and manual resume.
+    - This skill owns workflow-step, terminal-state, and compensation-state recovery. Route
+      delivery, consumer-application, and projection convergence across independent commits to
+      `dual-write-consistency`.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every step has durable identity, owner, state, version, and completion evidence.
+- Resume does not silently replay an already completed external effect.
+- Every reachable branch terminates as succeeded, compensated, forward-recovery-required,
+  cancelled with declared residual effects, or manual-intervention.
+- Workflow orchestration does not replace command, state-machine, delivery, ledger, or policy owners.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+- Use configured `changes_status` and `changes_diff_summary` for scope evidence.
+- Use `lint`, `build`, and `test_related` for implementation and restart fixtures; use `test` or
+  `test_audit` when orchestration is shared or test coverage claims are broad.
+- Use `docs_validate_fast`, `test_release`, and `mustflow_check` for public, package, template, or
+  Mustflow changes.
+- Report unavailable multi-process, deployment-resume, clock, provider, or operator evidence rather
+  than replacing it with raw commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If participant ownership or compensation semantics are unknown, stop workflow expansion and list
+  the missing business decisions.
+- If resume compatibility is unprovable, preserve the run under manual intervention rather than
+  loading it into new code optimistically.
+- If compensation can fail without a terminal recovery path, report the workflow as incomplete.
+- If a configured check fails, preserve the workflow state and failure boundary, then use
+  `failure-triage` before broadening the edit.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Workflow goal, instance identity, definition version, participants, and boundaries
+- Step, checkpoint, timer, lease, cancellation, and resume decisions
+- Effect classifications, compensation commands, and terminal outcomes
+- Restart, duplicate, late-event, drift, compensation, and manual-recovery evidence
+- Files changed and compatibility impact
+- Command intents run, skipped checks, and remaining durable-workflow risk

package/templates/default/locales/en/.mustflow/skills/execution-ledger-integrity-review/SKILL.md

@@ -0,0 +1,161 @@
+---
+mustflow_doc: skill.execution-ledger-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: execution-ledger-integrity-review
+description: Apply this skill when runs, attempts, leases, approvals, checkpoints, tool or provider effects, receipts, terminal outcomes, resume, reconciliation, or replay depend on an append-only execution ledger rather than ordinary logs or session handoff summaries.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.execution-ledger-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Execution Ledger Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep execution history truthful enough to explain, resume, reconcile, and safely replay decisions.
+Record observable inputs, actions, approvals, attempts, effects, checkpoints, and outcomes without
+turning hidden reasoning, secrets, raw conversations, or full logs into durable authority.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A system must later prove which run, attempt, lease owner, checkpoint, approval, effect, or terminal
+  outcome happened.
+- Resume or reconciliation depends on an operation ledger, execution ledger, semantic checkpoint,
+  effect receipt, result digest, provenance, or replay record.
+- A reliability claim depends on durable execution facts rather than ordinary trace or log lines.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is ordinary logging or trace-field quality; use `backend-log-evidence-review` or
+  `observability-debuggability-review`.
+- The record is a coding-session handoff; use `restricted-handoff-resume`.
+- The record is a credit, payment, accounting, or business balance ledger; use the corresponding
+  ledger-integrity skill.
+- The main concern is duplicate acceptance, workflow step order, compensation, or policy evaluation;
+  use `idempotency-integrity-review`, `durable-workflow-orchestration`, or
+  `policy-decision-integrity-review` respectively.
+- A request ID in logs is not an execution ledger, and an idempotency key alone does not prove which
+  attempt performed an external effect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Execution identity ledger: run, parent run, logical action, attempt, causation, and correlation.
+- Input and version ledger: safe input digest plus code, configuration, policy, model, provider,
+  tool, and schema versions required to interpret the result.
+- Action and effect ledger: selected action, safe argument digest, approval, effect identity, and
+  pre-effect intent record.
+- Attempt and outcome ledger: owner or lease, start, result digest, receipt, unknown or partial
+  outcome, terminal classification, and supersession.
+- Checkpoint, integrity, retention, privacy, replay, and reconciliation ledgers.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read the nearest instructions, command contract, execution path, persistence schema, checkpoint
+  and resume code, effect boundaries, privacy policy, replay path, and current tests.
+- Separate audit, resume, reconciliation, and replay requirements. Do not add an event-sourced domain
+  model when only execution evidence is needed.
+- Treat stored summaries and traces as derived evidence below current source, policy, and durable
+  receipts.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten execution identities, append-only entries, sequence or hash links, lease generations,
+  semantic checkpoints, effect receipts, terminal outcomes, replay inputs, reconciliation, retention,
+  redaction, focused tests, docs, and directly synchronized templates.
+- Add public projections or exports only with their owning public-contract procedure.
+- Do not store hidden reasoning, raw prompts, raw conversations, full terminal output, credentials,
+  secret-bearing tool payloads, or unbounded provider responses as ledger evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. State whether the ledger supports audit, resume, reconciliation, replay, or a bounded combination.
+2. Define stable run, parent, logical action, attempt, causation, correlation, approval, and effect
+   identities. Do not collapse a retry attempt into a new logical action.
+3. Record safe input digests and every code, configuration, policy, model, provider, tool, and schema
+   version needed to interpret the decision and result.
+4. Keep model, provider, and tool content minimal: safe normalized fields, evidence pointers, and
+   digests. Redact or omit raw sensitive payloads before persistence.
+5. Bind approval to the exact actor, resource, action, arguments or digest, policy decision, version,
+   expiry, and effect that it permits.
+6. Append an accepted intent before an external effect and append the observed outcome afterward.
+   Preserve a gap or unknown outcome if the process dies between them.
+7. Separate logical action state from attempts. Record owner, lease or generation, attempt number,
+   deadline, retry reason, supersession, and the terminal attempt that owns the outcome.
+8. Treat timeout or missing response as unknown, not failed, until provider lookup, durable receipt,
+   or reconciliation establishes the result.
+9. Store semantic state and the last committed ledger position in a checkpoint. Reconstruct runtime
+   objects and verify pending effects on resume.
+10. Enforce append-only ordering with unique identities, monotonic sequence or equivalent causal
+    links, durable constraints, and tamper or truncation detection appropriate to the threat model.
+11. Make terminal outcomes monotonic. A late attempt cannot overwrite a succeeded, cancelled,
+    superseded, or manual-review result without an explicit corrective entry.
+12. Replay pure decisions against pinned inputs and inject recorded observations for external calls.
+    Never make replay re-send email, charge money, mutate providers, or publish events implicitly.
+13. Test missing entries, partial append, duplicate outcome, stale lease, late attempt, version drift,
+    unknown provider result, checkpoint gap, tampering, retention expiry, and replay side-effect blocks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every observable effect links to a logical action, attempt, owner, approval when required, and
+  result or explicit unknown outcome.
+- Resume cannot skip a ledger gap, stale lease, version mismatch, or unresolved effect silently.
+- Replay does not execute external mutations and reports version drift instead of false equivalence.
+- Retained evidence is bounded and privacy-safe without relying on hidden reasoning or raw logs.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+- Use configured `changes_status` and `changes_diff_summary` for scope evidence.
+- Use `lint`, `build`, and `test_related` for implementation and ledger failure fixtures; use `test`
+  or `test_audit` for shared ledger or coverage claims.
+- Use `docs_validate_fast`, `test_release`, and `mustflow_check` for public exports, package, template,
+  or Mustflow changes.
+- Report unavailable database fault injection, provider reconciliation, tamper testing, or retention
+  expiry evidence rather than inventing commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If run, action, attempt, or effect identity cannot be separated, stop replay or resume claims and
+  report the ambiguous identity.
+- If a ledger gap or unknown effect cannot be reconciled, preserve manual-review state; do not mark
+  the run failed and retry automatically.
+- If safe evidence requires storing secrets or raw transcripts, redesign the evidence pointer or
+  digest before persistence.
+- If verification fails, preserve the ledger invariant and use `failure-triage` before changing
+  unrelated runtime code.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Audit, resume, reconciliation, and replay purposes reviewed
+- Run, action, attempt, version, approval, effect, checkpoint, and terminal-outcome decisions
+- Append-only, privacy, retention, unknown-outcome, and replay protections
+- Failure-injection and drift evidence
+- Files changed and public-contract impact
+- Command intents run, skipped checks, and remaining ledger-integrity risk