mustflow 2.103.16 → 2.103.21

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.database-migration-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: database-migration-change
-description: Apply this skill when database migration files, schema migration history, ORM schema migrations, generated clients, schema dumps, SQL snapshots, online DDL, large indexes, constraints, backfills, rolling deploy compatibility, expand-and-contract changes, destructive database changes, migration rollback or roll-forward claims, cut-over plans, lock or timeout policy, replication lag risk, migration observability, or production database migration procedures are created, changed, reviewed, or reported.
+description: Apply this skill when database migration files, schema migration history, ORM schema migrations, generated clients, schema dumps, SQL snapshots, online DDL, large indexes, constraints, state-dependent CHECK constraints, backfills, rolling deploy compatibility, expand-and-contract changes, destructive database changes, migration rollback or roll-forward claims, cut-over plans, lock or timeout policy, replication lag risk, migration observability, or production database migration procedures are created, changed, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -58,6 +58,9 @@ Migration incidents usually happen in the interval where old code, new code, old
 - Deployment shape: single-step deploy, rolling deploy, blue-green, multiple app versions, background workers, read replicas, multiple services, serverless functions, mobile clients, or external integrations.
 - Database engine and operational surface: PostgreSQL, MySQL, SQLite, SQL Server, managed database, migration lock behavior, DDL transaction behavior, online DDL options, table size, write load, long-running transactions, replication or CDC topology, expected lock time, statement timeout, lock timeout, and restore capability when known.
 - Data preservation needs, compatibility window, backfill size, batch strategy, cursor or checkpoint marker, validation query, observability query, rollback or roll-forward type, cut-over control, and whether old code can run after the new schema lands.
+- State and timestamp invariant matrix when a migration introduces lifecycle statuses, terminal
+  timestamps, retry or dead-letter states, delivery states, soft-delete states, approval states, or
+  other columns whose valid nullability depends on status.
 - Relevant command-intent entries for build, generated-output checks, tests, docs, release, and mustflow validation.
 
 <!-- mustflow-section: preconditions -->
@@ -114,6 +117,14 @@ Migration incidents usually happen in the interval where old code, new code, old
 11. For constraints and foreign keys, use staged validation when the database supports it.
     - PostgreSQL `NOT VALID` constraints and later `VALIDATE CONSTRAINT` can avoid validating old rows during the first lock-sensitive change while still protecting new writes.
     - Foreign keys on large or hot tables need separate add, repair/backfill, validate, and fallback planning rather than one heroic migration.
+    - CHECK constraints must reject impossible domain states, not only prove column types. For
+      lifecycle tables, build a status matrix before writing the constraint: each status should name
+      which timestamps or reason fields are required, forbidden, or still pending. For example,
+      a delivered row should not also have a dead-letter timestamp, and a dead-lettered row should
+      not also look delivered unless the domain explicitly has a separate correction state.
+    - When existing rows may already violate the new matrix, split the change into repair, add
+      unvalidated constraint where supported, validate, and then rely on the constraint as the last
+      gate. Do not let application comments or happy-path tests stand in for the database invariant.
 12. For indexes, check table size, write load, lock behavior, concurrent or online index support, uniqueness validation, existing duplicates, and whether generated ORM queries will use the index.
     - PostgreSQL `CREATE INDEX CONCURRENTLY` avoids blocking ordinary writes but still scans more than once, waits for old transactions, consumes I/O, and cannot run inside a transaction block.
     - MySQL online DDL and `ALGORITHM=INSTANT` have version, row-format, index, row-size, and operation limits; specify `ALGORITHM=INSTANT` or `LOCK=NONE` only when unsupported fallback should fail instead of silently rebuilding a table.
@@ -170,6 +181,8 @@ Migration incidents usually happen in the interval where old code, new code, old
 - Expand, backfill, switch, and contract phases are separated or explicitly proven unnecessary.
 - Old-code/new-schema and new-code/expanded-schema compatibility is classified.
 - Backfill and validation behavior is cursor-based or otherwise bounded, restartable, idempotent, observable, and checkable where relevant.
+- State-dependent CHECK constraints, terminal timestamp exclusivity, and valid nullability matrices
+  are explicit where status columns can otherwise contradict timestamp or reason columns.
 - Lock levels, online DDL support, long-running transaction waits, replication lag, cut-over control, timeout policy, and observability queries are explicit where production data may be affected.
 - Rollback claims distinguish schema rollback, data rollback, app rollback, roll-forward, forward-fix, and restore-required cases.
 - Destructive changes and production lock risks are either deferred, measured, guarded, or reported as remaining risk.
@@ -212,6 +225,7 @@ Prefer configured migration dry-run, generated-output, schema-diff, or database
 - Old-code/new-schema and new-code/expanded-schema compatibility
 - Expand/backfill/switch/contract plan and destructive cleanup timing
 - Backfill cursor, idempotency, throttle, pause/resume, validation, lock, timeout, replication, cut-over, and observability classification
+- Status, timestamp, CHECK constraint, and existing-row validation matrix where relevant
 - Rollback, app rollback, roll-forward, forward-fix, and restore-required classification
 - ORM/generated client/schema dump/snapshot surfaces synchronized
 - Dependent surfaces checked

package/templates/default/locales/en/.mustflow/skills/http-api-semantics-review/SKILL.md

@@ -0,0 +1,286 @@
+---
+mustflow_doc: skill.http-api-semantics-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: http-api-semantics-review
+description: Apply this skill when HTTP API method semantics, safe or idempotent behavior, GET or HEAD request-body assumptions, OPTIONS or Allow discovery, HTTP QUERY, POST versus PUT URI ownership, PUT replacement, PATCH document formats, DELETE behavior, conditional requests, status codes, cache headers, CORS method discovery, retry behavior, or intermediary compatibility need review.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.http-api-semantics-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# HTTP API Semantics Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review HTTP APIs as method, status, header, cache, retry, and intermediary contracts, not as CRUD
+labels or controller naming preferences.
+
+The review question is not "does this route work in the current framework?" It is "will browsers,
+crawlers, caches, gateways, SDKs, retries, stale clients, and concurrent callers interpret this
+request the same way the server does?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- HTTP or REST routes, handlers, OpenAPI documents, API docs, SDKs, gateways, middleware, CORS
+  policy, cache policy, status-code maps, or request/response headers are created, changed,
+  reviewed, or reported.
+- A change chooses or changes GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE, QUERY, or fallback
+  behavior.
+- A review claims that an endpoint is safe, idempotent, cacheable, retry-safe, crawler-safe,
+  prefetch-safe, proxy-safe, CDN-compatible, or portable across HTTP clients.
+- The task involves PUT full replacement, PATCH document semantics, DELETE bodies, POST search,
+  GET or HEAD request bodies, HTTP QUERY, Accept-Patch, Accept-Query, Allow, ETag, If-Match,
+  If-None-Match, Cache-Control, Vary, Location, Content-Location, Retry-After, or CORS method
+  discovery.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main work is broad API source-of-truth synchronization, generated clients, schema drift, or
+  compatibility classification; use `api-contract-change` first and this skill only for HTTP
+  method semantics.
+- The main work is caller ergonomics, ambiguous DTOs, hidden operation modes, or SDK usability; use
+  `api-misuse-resistance-review`.
+- The main work is duplicate business side effects or retry delivery; use
+  `idempotency-integrity-review`.
+- The main work is cache key truth, stale data, invalidation, Redis, or cache outage behavior; use
+  `cache-integrity-review`.
+- The main work is response streaming, compression, proxy buffering, SSE, WebTransport, or delivery
+  transport behavior; use `http-delivery-streaming`.
+- The API is not HTTP-facing and no HTTP method, status, header, cache, CORS, retry, or
+  intermediary behavior is part of the contract.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Endpoint ledger: method, path, request body meaning, success statuses, error statuses, headers,
+  auth and permission requirement, cacheability, caller types, and fallback paths.
+- Method contract: whether the caller requests a safe operation, an idempotent operation, a full
+  representation replacement, a patch document application, a server-selected creation, a
+  client-selected target URI, a delete/unlink operation, or a safe body-bearing query.
+- Concurrency contract: ETag or version source, conditional request requirements, lost-update
+  behavior, conflict behavior, and retry behavior after unknown outcomes.
+- Patch contract when PATCH is used: media type, patch grammar, null and omission semantics,
+  atomicity boundary, validation timing, Accept-Patch discovery, and status-code recovery map.
+- Query contract when GET, QUERY, or POST search is used: canonical GET strategy, query body media
+  type, Accept-Query or Allow discovery, fallback behavior, cache-key inputs, canonicalization,
+  Location or Content-Location behavior, and sensitive-data handling.
+- Cache and capability contract: Cache-Control, Vary, ETag, Last-Modified, Location,
+  Content-Location, Allow, Access-Control-Allow-Methods, Accept-Patch, Accept-Query, Retry-After,
+  and RateLimit header behavior when relevant.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
+  validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- The current contract source of truth is known, such as OpenAPI, route validators, handler tests,
+  API docs, gateway config, or SDK examples.
+- If HTTP semantics changes affect request or response shapes, generated clients, auth, permission,
+  cache correctness, duplicate side effects, or streaming delivery, also apply the narrower matching
+  skill before finalizing that part.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update route handlers, method choices, validators, OpenAPI or API docs, SDK examples, gateway
+  rules, CORS rules, cache headers, conditional request handling, status-code maps, and focused
+  tests tied to the changed HTTP contract.
+- Add explicit support or rejection for GET or HEAD bodies, DELETE bodies, unsupported methods,
+  unsupported patch media types, missing preconditions, and body-bearing safe queries.
+- Add capability discovery through Allow, Accept-Patch, Accept-Query, and documented fallback
+  behavior when the API exposes those capabilities.
+- Do not silently convert PUT into partial merge, PATCH into ambiguous JSON merge, GET into a
+  command, POST search into a safe operation without naming fallback semantics, or cache policy into
+  prose-only behavior.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a method semantics ledger for every endpoint under review:
+   - method;
+   - target URI ownership;
+   - whether the method is safe, idempotent, and cacheable for this operation;
+   - request body meaning;
+   - expected automatic retry behavior;
+   - success, conflict, validation, unsupported-media, precondition, rate-limit, and overload
+     statuses.
+2. Check safe methods first.
+   - GET, HEAD, and OPTIONS must not request business mutations.
+   - Safe does not mean unauthenticated, cheap, unmetered, or cache-public.
+   - Crawlers, link previews, browser prefetch, health checks, and monitoring can trigger safe
+     methods.
+3. Reject public GET and HEAD request-body semantics unless the API intentionally documents a
+   non-portable private contract.
+   - Prefer GET query parameters for small, shareable, cacheable, non-sensitive reads.
+   - Prefer QUERY for safe, idempotent, body-bearing queries when clients, gateways, servers, and
+     docs can support it.
+   - Use POST as a compatibility fallback or state-changing processing request, not as an unnamed
+     safe query.
+4. Review OPTIONS as capability discovery.
+   - OPTIONS is not only a CORS preflight shortcut.
+   - Keep `Allow` for HTTP method support separate from `Access-Control-Allow-Methods` for CORS.
+   - Ensure 405 responses include an accurate `Allow` header.
+5. Review POST versus PUT URI ownership.
+   - Use POST when the server chooses the new resource URI or processes a resource-specific command.
+   - Use PUT when the client knows the target URI and wants that target representation created or
+     replaced.
+   - Do not let PUT write to a different URI without redirect or explicit contract.
+6. Review PUT as replacement.
+   - A PUT body is the new representation for the target URI, not a partial DTO by default.
+   - Reject incomplete replacement bodies, require full client-owned representations, or choose
+     PATCH or a command resource instead.
+   - For create-only PUT, require `If-None-Match: *` where concurrent creation matters.
+   - For update-only PUT, require `If-Match` or another version precondition where lost updates
+     matter.
+7. Review PATCH as patch document application.
+   - Pick and document the patch media type, such as `application/merge-patch+json`,
+     `application/json-patch+json`, or a domain-specific media type.
+   - Do not use bare `application/json` when null, omission, delete, array, and command semantics
+     are ambiguous.
+   - Advertise supported patch formats with `Accept-Patch` where capability discovery matters.
+   - Apply the whole patch atomically. Partial patch success is a contract failure.
+   - Validate the resulting resource, not only the patch document syntax.
+8. Review DELETE as target-resource unlinking, not necessarily physical storage deletion.
+   - Do not require identical repeat response statuses for idempotency; require identical intended
+     effect and duplicate-safe side effects.
+   - Avoid DELETE request bodies for portable bulk or filtered deletes. Prefer item DELETE calls or
+     POST command resources such as deletion jobs.
+   - Document soft-delete, tombstone, retention, restore, and audit behavior when callers rely on
+     lifecycle outcomes.
+9. Review conditional requests and lost-update protection.
+   - Use strong ETags or equivalent version tokens when concurrent writers can overwrite one
+     another.
+   - Use `If-Match` for update preconditions and `If-None-Match: *` for create-if-absent.
+   - Return `412 Precondition Failed` for failed preconditions and `428 Precondition Required` when
+     the API refuses unsafe writes without preconditions.
+10. Review QUERY and search design.
+    - Keep simple, bookmarkable, shareable, cacheable searches on GET where possible.
+    - Use QUERY for safe, idempotent, body-bearing queries whose inputs do not belong cleanly in the
+      URI.
+    - Define the request media type and reject missing or inconsistent Content-Type.
+    - Expose support through `Allow` and supported query formats through `Accept-Query` when
+      clients need discovery.
+    - Build cache keys from request content plus relevant metadata, and canonicalize only
+      semantically insignificant differences.
+    - Decide whether `Content-Location`, `Location`, or `303 See Other` gives callers a GET-able
+      result, equivalent query, or stored job/resource.
+    - Use POST fallback only as a compatibility shell over the same internal query model.
+11. Review status codes as recovery instructions.
+    - Use `201` plus `Location` and preferably `ETag` when a resource is created.
+    - Use `202` plus a status resource when work is accepted but unfinished.
+    - Use `204` for successful no-body responses, `206` for partial content, and `304` for
+      conditional cache validation.
+    - Separate malformed input (`400`), unsupported media (`415`), current-state conflict (`409`),
+      failed precondition (`412`), missing precondition (`428`), valid-but-unprocessable content
+      (`422`), method unsupported for the resource (`405` with `Allow`), method unknown (`501`),
+      rate limit (`429` with `Retry-After` where useful), and overload (`503` with `Retry-After`
+      where useful).
+12. Review HTTP cache semantics.
+    - `no-cache` means revalidate before reuse. `no-store` means do not store.
+    - Use `private`, `public`, `s-maxage`, validators, and `Vary` according to viewer, auth,
+      language, encoding, content negotiation, and tenant dimensions.
+    - Do not assume a successful unsafe method invalidates every list, search, feed, recommendation,
+      CDN tag, or read model that can include the changed resource.
+13. Check synchronized surfaces before finalizing.
+    - Route code, validators, OpenAPI or docs, generated clients, SDK examples, gateway and CORS
+      config, cache config, status-code fixtures, retry docs, tests, monitoring, and release notes
+      should agree with the HTTP method contract.
+    - If deterministic proxy, CDN, browser, or gateway evidence is unavailable, report that gap
+      instead of claiming portability.
+
+## Strongly Forbidden Patterns
+
+- GET, HEAD, or OPTIONS hidden business mutations.
+- Public GET or HEAD request bodies as if they were portable HTTP contracts.
+- PUT partial update merge without an explicit non-PUT contract.
+- PATCH with ambiguous `application/json` semantics.
+- PATCH partial success.
+- DELETE request bodies for portable bulk or filtered operations.
+- Treating DELETE idempotency as identical status codes while duplicate side effects replay.
+- Treating `no-cache` as `no-store`.
+- Mixing `Allow` with `Access-Control-Allow-Methods`.
+- POST search without naming safe-query fallback and cache behavior.
+- QUERY without media type, support discovery, body-aware cache key, and intermediary support plan.
+- Collapsing status codes so clients cannot tell whether to fix input, refresh state, retry later,
+  update ETags, or change media type.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Method semantics, request body meaning, URI ownership, retry expectations, status-code recovery,
+  conditional requests, capability discovery, cache semantics, and intermediary assumptions are
+  explicit or reported as missing.
+- PUT, PATCH, DELETE, GET, HEAD, OPTIONS, POST, and QUERY behavior is either aligned with HTTP
+  semantics or intentionally documented as a narrow non-portable contract.
+- API docs, tests, SDKs, generated clients, gateways, CORS rules, cache headers, and observability
+  agree with the chosen HTTP contract where relevant.
+
+<!-- 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`
+
+Prefer the narrowest configured tests or docs checks that exercise the HTTP method, status, header,
+cache, conditional request, QUERY, fallback, or generated-client contract from a caller's
+perspective. Do not infer raw browser, proxy, CDN, gateway, load-test, or live-network commands
+outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the contract source of truth is unclear, stop and report the competing route, schema, gateway,
+  docs, and SDK sources instead of editing only one surface.
+- If a method choice conflicts with existing callers, classify the compatibility risk and use
+  `api-contract-change` before changing public behavior.
+- If duplicate side effects, cache sharing, security, or streaming delivery risks are found, switch
+  to the narrower matching skill before finalizing that part.
+- If deterministic HTTP interoperability proof requires browser, gateway, CDN, proxy, or production
+  telemetry not configured in `.mustflow/config/commands.toml`, complete available local checks and
+  report the manual evidence gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- HTTP API semantics reviewed
+- Endpoint method ledger
+- Safe, idempotent, cacheable, request-body, URI-ownership, PUT, PATCH, DELETE, QUERY, conditional
+  request, status-code, header discovery, CORS, cache, retry, and intermediary findings
+- Fixes made or recommendations
+- Synchronized docs, tests, SDK, generated client, gateway, and cache surfaces
+- Evidence level: configured-test evidence, docs evidence, static review risk, manual-only,
+  missing, or not applicable
+- Command intents run
+- Skipped HTTP interoperability checks and reasons
+- Remaining HTTP semantics risk

package/templates/default/locales/en/.mustflow/skills/module-boundary-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.module-boundary-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: module-boundary-review
@@ -76,6 +76,9 @@ who must change, who owns the data, who owns the failure, and who should not nee
   history showing files that usually move together.
 - Module graph evidence: imports, exports, public APIs, call sites, dependency direction, cycles,
   shared helpers, DTO flow, and configuration reads.
+- Configured guardrail evidence when available: `code/module-boundary` results for
+  `.mustflow/config/module-boundaries.toml` layer deny rules, public entrypoints, feature imports,
+  shared budgets, and import cycles.
 - Ownership evidence: source of truth for data, owner of policy decisions, owner of failure handling,
   owner of cache invalidation, owner of time and config interpretation, and owner of authorization.
 - Test evidence: number and kind of mocks, pure-domain tests, integration tests, worker or batch
@@ -131,6 +134,9 @@ who must change, who owns the data, who owns the failure, and who should not nee
    - If A imports B and B imports A, identify the missing concept, ownership decision, event, port, or
      data-flow direction.
    - Do not accept "they need each other" without naming the invariant that forces the cycle.
+   - When the repository declares `.mustflow/config/module-boundaries.toml`, use the read-only
+     `code/module-boundary` script-pack report as executable evidence before relying on prose-only
+     boundary claims.
 5. Trace DTO infection.
    - API response DTOs, request DTOs, ORM rows, provider payloads, and UI view models should not
      become domain, repository, batch, worker, or event models by default.
@@ -250,6 +256,11 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 module boundary. Use release or docs checks when templates, public docs, package metadata, public APIs,
 schemas, generated clients, or install surfaces change.
 
+When the command contract and script-pack metadata expose it, `code/module-boundary` may provide
+read-only evidence for configured import-boundary rules. A missing module-boundary config is
+non-blocking evidence that no executable boundary rules were enforced, not proof that the module
+design is clean.
+
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
 

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.payment-integrity-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: payment-integrity-review
-description: Apply this skill when payment, checkout, authorization, capture, refund, partial refund, subscription, invoice, trial, grace period, coupon, promotion, inventory reservation, fulfillment, entitlement, settlement, fee, chargeback, dispute, provider webhook, payment session, payment link, payment-provider integration, admin manual payment operation, payment logs, PCI-sensitive data handling, or payment-related tests need review for money-event integrity, idempotency, ordering, ownership, amount, currency, retry, reconciliation, ledger, or audit risk.
+description: Apply this skill when payment, checkout, authorization, capture, refund, partial refund, subscription, invoice, trial, grace period, coupon, promotion, inventory reservation, fulfillment, entitlement, settlement, fee, chargeback, dispute, provider webhook, payment outbox, payment session, payment link, payment-provider integration, admin manual payment operation, payment logs, PCI-sensitive data handling, or payment-related tests need review for money-event integrity, idempotency, ordering, ownership, amount, currency, retry, reconciliation, ledger, or audit risk.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -36,7 +36,7 @@ Review payment code as money-event integrity, not provider API success. The core
 ## Use When
 
 - Payment, checkout, payment-session, payment-link, authorization, capture, refund, partial refund, dispute, chargeback, settlement, fee, receipt, entitlement, fulfillment, subscription, invoice, trial, grace period, coupon, promotion, or inventory reservation logic is created, changed, reviewed, or reported.
-- Provider webhook handling, provider callback handling, payment retry handling, timeout handling, provider reconciliation, or async payment method handling can change internal money state.
+- Provider webhook handling, provider callback handling, payment outbox records, payment retry handling, timeout handling, provider reconciliation, or async payment method handling can change internal money state.
 - Client-supplied amount, currency, quantity, product, discount, shipping, tax, order, subscription, refund, or customer identifiers can influence a payment action.
 - Manual admin payment operations, payment logs, audit trails, or payment-related tests need review.
 
@@ -59,9 +59,12 @@ Review payment code as money-event integrity, not provider API success. The core
 - State-transition ledger: internal states, provider states, allowed transitions, terminal states,
   retry states, async states, hold states, kill-switch states, and transition owners.
 - Event log ledger: request submission, provider response, redirect, webhook receipt, webhook
-  application, state transition, queue handoff, reconciliation decision, fulfillment, refund,
-  dispute, admin override, and correction events with ordering, actor, reason, and immutable
-  evidence.
+  application, state transition, outbox event, queue handoff, reconciliation decision, fulfillment,
+  refund, dispute, admin override, and correction events with ordering, actor, reason, event type,
+  and immutable evidence.
+- Outbox event-type ledger: allowed internal event type vocabulary, enum or constant registry,
+  parser or validator, database constraint when available, and the rejection path for unknown,
+  stale, misspelled, or provider-shaped event types.
 - Idempotency and uniqueness ledger: logical operation IDs, provider idempotency keys, database uniqueness constraints, webhook event dedupe keys, fulfillment dedupe keys, and retry behavior.
 - Amount and currency ledger: product/cart snapshot, server-side calculation path, quantity, discounts, coupons, tax, shipping, minor-unit representation, currency, provider amount, internal ledger amount, receipt amount, and settlement amount.
 - Ownership ledger: user, tenant, account, order, payment session, refund, subscription, invoice, entitlement, admin actor, and provider customer ownership checks.
@@ -81,7 +84,7 @@ Review payment code as money-event integrity, not provider API success. The core
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Tighten payment state machines, server-side amount calculation, minor-unit money handling, ownership checks, idempotency keys, provider-ID uniqueness, webhook signature verification, webhook dedupe, queue handoff, one-time fulfillment, async payment handling, authorization/capture distinction, refund/dispute/subscription transitions, inventory and coupon reservation, timeout and retry classification, append-only ledgers, secret and card-data redaction, admin audit trails, stale payment endpoint cleanup notes, focused nightmare-path tests, and directly synchronized docs or templates.
+- Tighten payment state machines, server-side amount calculation, minor-unit money handling, ownership checks, idempotency keys, provider-ID uniqueness, webhook signature verification, webhook dedupe, outbox event-type validation, queue handoff, one-time fulfillment, async payment handling, authorization/capture distinction, refund/dispute/subscription transitions, inventory and coupon reservation, timeout and retry classification, append-only ledgers, secret and card-data redaction, admin audit trails, stale payment endpoint cleanup notes, focused nightmare-path tests, and directly synchronized docs or templates.
 - Do not replace a focused payment-integrity fix with a broad payment platform rewrite unless the current code cannot preserve money correctness with a smaller boundary.
 - Do not add live payment secrets, real card data, real refunds, real charges, or live-provider side effects.
 
@@ -96,6 +99,10 @@ Review payment code as money-event integrity, not provider API success. The core
 3. Keep an immutable event trail. Store request submission, provider response, redirect, webhook,
    state transition, queue handoff, reconciliation, fulfillment, refund, dispute, and admin override
    events with actor, reason, timestamp, provider reference, and before/after state when relevant.
+   - For internal outbox rows, validate `event_type` against the owned payment event vocabulary
+     before deriving idempotency keys, publishing, or persisting follow-up work. Do not let free-form
+     strings, provider event names, stale constants, or user-controlled values become trusted outbox
+     operation types.
 4. Calculate amount on the server. Treat client-supplied amount, currency, quantity, discount, coupon, tax, shipping, product ID, plan ID, or cart totals as input claims only; rebuild the payable total from trusted product, cart, account, and policy snapshots.
 5. Bind every payment object to its owner. Verify user, tenant, order, payment session, refund, subscription, invoice, provider customer, and admin actor ownership before read, write, refund, cancel, fulfillment, or entitlement changes.
 6. Compare every amount ledger. Trace order amount, provider request amount, provider response amount, internal money ledger, receipt, settlement, fee, refund, and entitlement amount. Flag any path where one amount can drift without reconciliation.
@@ -136,8 +143,8 @@ Review payment code as money-event integrity, not provider API success. The core
 
 - The payment surface has a money-event map, provider interaction map, identifier map,
   state-transition map, immutable event log, idempotency and uniqueness map, amount and currency map,
-  ownership map, fulfillment and entitlement map, webhook/retry map, reconciliation and hold-state
-  map, and audit/sensitive-data map.
+  ownership map, fulfillment and entitlement map, webhook/retry map, outbox event-type validation
+  map, reconciliation and hold-state map, and audit/sensitive-data map.
 - Any false success, duplicate money movement, duplicate fulfillment, wrong-owner action, wrong amount, wrong currency, stale event overwrite, timeout misclassification, or missing reconciliation is fixed or reported with evidence.
 - Tests or explicit verification cover the highest-risk nightmare paths available in the current scope.
 
@@ -172,7 +179,7 @@ Prefer focused tests for duplicate operations, webhook replay, out-of-order even
 ## Output Format
 
 - Payment surface and provider boundary reviewed
-- Money-event, provider, identifier, state, event-log, idempotency, amount, ownership, fulfillment, webhook, retry, reconciliation, hold-state, audit, and sensitive-data ledgers
+- Money-event, provider, identifier, state, event-log, outbox event-type, idempotency, amount, ownership, fulfillment, webhook, retry, reconciliation, hold-state, audit, and sensitive-data ledgers
 - Findings or fixes for duplicate, late, out-of-order, wrong-actor, wrong-amount, wrong-currency, timeout, retry, reconciliation, and audit risks
 - Nightmare-path tests or evidence added, run, skipped, or still missing
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -216,6 +216,12 @@ route_type = "adjunct"
 priority = 69
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change", "package_metadata_change"]
 
+[routes."http-api-semantics-review"]
+category = "general_code"
+route_type = "adjunct"
+priority = 81
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "performance_change", "security_change", "privacy_change", "data_change", "package_metadata_change", "release_risk"]
+
 [routes."error-message-integrity-review"]
 category = "general_code"
 route_type = "adjunct"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.103.16"
+version = "2.103.21"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -14,6 +14,7 @@ creates = [
   ".mustflow/skills/routes.toml",
   ".mustflow/skills/adapter-boundary/SKILL.md",
   ".mustflow/skills/api-contract-change/SKILL.md",
+  ".mustflow/skills/http-api-semantics-review/SKILL.md",
   ".mustflow/skills/backend-reliability-change/SKILL.md",
   ".mustflow/skills/http-delivery-streaming/SKILL.md",
   ".mustflow/skills/artifact-integrity-check/SKILL.md",
@@ -226,6 +227,7 @@ available = ["minimal", "patterns", "oss", "team", "product", "library"]
 minimal = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -373,6 +375,7 @@ patterns = [
   "architecture-deepening-review",
   "service-boundary-architecture",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -528,6 +531,7 @@ patterns = [
 oss = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "artifact-integrity-check",
@@ -705,6 +709,7 @@ team = [
   "architecture-deepening-review",
   "service-boundary-architecture",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "auth-permission-change",
@@ -864,6 +869,7 @@ team = [
 product = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "service-boundary-architecture",
@@ -1028,6 +1034,7 @@ product = [
 library = [
   "adapter-boundary",
   "api-contract-change",
+  "http-api-semantics-review",
   "backend-reliability-change",
   "http-delivery-streaming",
   "artifact-integrity-check",