mustflow 2.39.1 → 2.58.1

package/templates/default/locales/en/.mustflow/skills/api-access-control-review/SKILL.md

@@ -0,0 +1,298 @@
+---
+mustflow_doc: skill.api-access-control-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: api-access-control-review
+description: Apply this skill when code is created, changed, reviewed, or reported and API security needs access-control review for BOLA or IDOR, object-level authorization, object-property authorization, function-level authorization, broken authentication, tenant isolation, role and relationship checks, mass assignment, DTO exposure, admin or internal APIs, route ordering, GraphQL resolvers, batch APIs, exports, downloads, signed URLs, cache keys, async jobs, webhooks, OAuth or OIDC, JWTs, sessions, cookies, reauthentication, reset tokens, account enumeration, automation defense, or denial-case tests.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.api-access-control-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# API Access Control Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review API security as an access-control proof, not as a login check.
+
+The review question is not "is the user authenticated?" It is "may this principal, at this moment,
+perform this action on this object, this field, and this tenant context?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code review, implementation, or refactor work touches API routes, controllers, handlers,
+  resolvers, RPC procedures, service methods, repositories, database queries, storage signers,
+  exports, downloads, previews, batch APIs, background jobs, webhooks, auth middleware, sessions,
+  cookies, JWTs, OAuth or OIDC flows, password reset, MFA, admin APIs, internal APIs, cache keys,
+  DTO mapping, tests, or API docs.
+- A request, token, body, query string, path parameter, webhook payload, queue payload, or client
+  state supplies `userId`, `accountId`, `tenantId`, `orgId`, `workspaceId`, `projectId`, `role`,
+  `ownerId`, object id, file key, status, price, entitlement, plan, or other authority-bearing data.
+- A review needs API-specific authorization coverage for BOLA or IDOR, broken authentication,
+  object-property authorization, function-level authorization, mass assignment, object storage
+  access, tenant isolation, GraphQL resolver access, batch authorization, signed URLs, token
+  validation, session hardening, account enumeration, automation defense, or denial-case tests.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task changes the authorization model, role matrix, permission implementation, route guards, or
+  session/token code and needs implementation guidance; use `auth-permission-change` first and this
+  skill for API-specific review coverage.
+- The task is a broad security source-to-sink review beyond API access control; use
+  `security-flow-review`.
+- The task is only public API schema compatibility, pagination shape, status codes, or generated
+  client drift; use `api-contract-change` first.
+- The task is only caller ergonomics or API misuse risk without security boundary pressure; use
+  `api-misuse-resistance-review`.
+- The task asks for live exploitation, credential guessing, penetration testing traffic, or unsafe
+  payload collection. Stay within defensive local code review and tests.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, current diff or target files, API surface, and the access-control claim being reviewed.
+- Subject-object-action-context ledger: principal, session, token, API key, service account, tenant,
+  organization, workspace, role, relationship, resource, object id, field or property, action,
+  state, and request context.
+- Object authorization ledger: list, detail, count, search, export, download, preview, share,
+  update, delete, approve, invite, refund, transfer, admin, batch, worker, and webhook paths that
+  can reach the same object.
+- Property authorization ledger: request fields, response fields, updateable fields, hidden fields,
+  sensitive fields, computed fields, internal ids, storage keys, provider ids, and privileged
+  mutable fields.
+- Function authorization ledger: API route, resolver, RPC procedure, admin function, support tool,
+  internal endpoint, queue handler, webhook handler, and storage signer operations.
+- Authentication proof ledger: auth middleware, session store, cookie settings, JWT verifier,
+  OAuth/OIDC handling, API key verifier, reset tokens, reauthentication points, account enumeration
+  behavior, and automation controls.
+- Existing tests, denial cases, role matrices, API docs, security docs, and configured command
+  intents.
+
+<!-- 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 subject, object, action, tenant, field, token, cache, or
+  denial-test evidence can be reported without guessing.
+- Treat client-provided identity, tenant, role, ownership, status, plan, and entitlement values as
+  untrusted until server context and persisted relationships prove them.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten server-side object authorization, tenant-scoped lookups, relationship checks,
+  function-level checks, property allowlists, DTO mappers, signed URL scoping, cache-key dimensions,
+  worker revalidation, webhook ownership mapping, token verification, session hardening,
+  reauthentication gates, enumeration-safe responses, rate limits, audit logs, and denial-case tests.
+- Update route docs, API examples, role matrices, security docs, fixtures, SDK tests, and template
+  surfaces that describe the same access-control contract.
+- Keep changes scoped to the reviewed API boundary and its synchronized surfaces.
+- Do not add broad scanners, live external probes, offensive payload collections, unrelated
+  hardening, or new command authority under this skill.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Ask the full permission question.
+   - Do not stop at "logged in".
+   - Ask whether this requester can perform this action on this object, this field, in this tenant,
+     in this state, right now.
+2. Treat request-supplied identity as hostile.
+   - `userId`, `accountId`, `tenantId`, `orgId`, `workspaceId`, `role`, `ownerId`, `plan`, and
+     similar values from body, query, headers, path params, local storage, or token claims are leads,
+     not authority.
+   - Derive truth from server session, verified token context, database relationships, and current
+     persisted state.
+3. Bind authorization to the data lookup.
+   - Prefer lookups such as `findByIdAndOwner`, `where id = ? and tenant_id = ?`, or policy-scoped
+     repository methods over `findById` followed by a fragile caller-side check.
+   - If existence disclosure must be hidden, keep missing and unauthorized behavior consistent.
+4. Separate authentication from authorization.
+   - `isAuthenticated`, valid session, API key, or decoded JWT says who is calling.
+   - It does not say whether the object, field, tenant, or action is allowed.
+5. Replace role-only checks with relationship and context checks.
+   - `role === "admin"` is usually too small.
+   - Check whether the principal is admin for this organization, owner of this project, seller for
+     this order, billing admin for this account, or allowed to act in this resource state.
+6. Compare list and detail scopes.
+   - If list filters by current user or tenant but detail, count, search, analytics, export, or
+     download uses only object id, report the gap.
+7. Review write APIs harder than read APIs.
+   - `PUT`, `PATCH`, `DELETE`, approve, refund, invite, transfer, publish, restore, and role-change
+     operations need write-specific permission, state, amount, and audit checks.
+   - Read permission is not write permission.
+8. Stop mass assignment at the boundary.
+   - Flag request-body-to-entity binding, raw DTO persistence, GraphQL input passthrough, ORM update
+     data from raw body, and blind spread or object assignment.
+   - Privileged fields such as `role`, `status`, `ownerId`, `tenantId`, `isVerified`, `plan`,
+     `credit`, `deletedAt`, `price`, and `quota` must be derived, guarded, or allowlisted.
+9. Check response DTOs for property-level exposure.
+   - Entity-to-JSON responses can leak `passwordHash`, `mfaSecret`, `internalMemo`,
+     `billingCustomerId`, storage keys, provider IDs, deletion reasons, or admin-only fields later.
+   - Use public response mappers and role-aware field policies when field visibility differs.
+10. Treat client-side admin UI as decoration.
+    - Hidden buttons, disabled controls, frontend routes, mobile checks, and generated clients are
+      not access control.
+    - Admin and support operations need server-side scope, reason, audit, and denial tests.
+11. Search for temporary public holes.
+    - Inspect `permitAll`, `anonymous`, `skipAuth`, `bypassAuth`, `public`, `internalOnly`,
+      `devOnly`, `TODO auth`, debug endpoints, health endpoints with extra data, and test-only
+      switches that can reach real data or operations.
+12. Review router and middleware order.
+    - Dynamic routes like `/:id` can shadow `/me`, `/admin`, or `/settings`.
+    - Prefix middleware can leave sibling paths, nested routers, serverless functions, or framework
+      route groups unauthenticated.
+13. Review GraphQL per resolver.
+    - Endpoint-level auth is not enough.
+    - Check `node(id)`, nested fields, connections, edges, aggregates, mutations, and field
+      resolvers for object and property authorization.
+14. Review batch APIs per item.
+    - Bulk create, delete, export, import, and update endpoints must authorize every object.
+    - Define whether one denied item fails the whole request, returns per-item results, or produces
+      a retrievable failure report.
+15. Review export, download, preview, thumbnail, and share paths.
+    - CRUD may be protected while file delivery, generated previews, thumbnails, CSV exports, and
+      shared links bypass the same policy.
+16. Treat signed storage URLs as outputs of authorization.
+    - S3, GCS, R2, CDN, and private file URLs must be generated only after object authorization.
+    - Check key predictability, URL lifetime, scope, content disposition, cache behavior, revocation,
+      and whether direct object access bypasses policy.
+17. Enforce tenant boundaries in every query and cache.
+    - `WHERE id = ?` is weak in multi-tenant code; include tenant, membership, owner, sharing, or
+      database policy constraints.
+    - Cache keys for private data need tenant and permission dimensions, not just object id.
+18. Revalidate asynchronous jobs.
+    - Queue payloads with only `userId`, `tenantId`, or `fileId` can outlive permission changes.
+    - Workers, retries, admin reruns, scheduled tasks, and webhook-triggered jobs need actor,
+      tenant, resource, state, and current permission or service-principal checks at execution time.
+19. Separate webhook authenticity from authorization.
+    - Signature verification proves the provider sent the event.
+    - Ownership mapping proves the event belongs to this tenant, account, customer, installation,
+      repository, subscription, or resource.
+20. Keep OAuth and OIDC purposes distinct.
+    - OIDC ID tokens identify a user for login.
+    - OAuth access tokens authorize delegated API access.
+    - Do not use an ID token as an API permission token or an access token as a login proof without
+      the appropriate validation and intent.
+21. Verify JWTs completely.
+    - Decoding is not verification.
+    - Check signature, algorithm allowlist, issuer, audience, expiry, not-before when used, key
+      source, key rotation, subject, tenant binding, and stale authorization claims.
+22. Treat token claims as snapshots, not eternal truth.
+    - Long-lived `role`, `plan`, `tenantId`, and permission claims can survive demotion, removal,
+      subscription cancellation, suspension, or revocation.
+    - Important decisions should check current server-side state or use short-lived tokens with
+      revocation strategy.
+23. Regenerate session identity after privilege changes.
+    - Login, password change, MFA changes, role changes, user-to-admin transitions, and account
+      recovery should rotate session identifiers or refresh tokens according to local policy.
+24. Check authentication cookies.
+    - Cookies carrying session authority need `Secure`, `HttpOnly`, appropriate `SameSite`,
+      domain, path, lifetime, rotation, logout, revocation, and CSRF posture.
+    - Avoid URL-carried session identifiers.
+25. Require reauthentication for sensitive actions.
+    - Password change, email change, MFA disable, payment method change, organization ownership
+      transfer, API-key creation, and destructive admin actions should require fresh proof.
+26. Review reset and magic-link tokens.
+    - Tokens need strong randomness, one-time use, short expiration, purpose binding, user binding,
+      safe storage, link-preview protection, session invalidation where needed, and no reuse across
+      unrelated flows.
+27. Compare account-enumeration responses.
+    - Login, signup, password reset, magic link, invitation, and email verification should avoid
+      leaking account existence through message, status, timing, or email-sending behavior unless
+      product policy accepts that disclosure.
+28. Treat automation defense as part of authentication.
+    - Login, OTP, magic link, password reset, invite acceptance, coupon application, email
+      verification, and MFA attempts need rate limits, lockouts, challenge policy, IP/device/user
+      dimensions, and observability.
+29. Separate internal and external identity planes.
+    - Backoffice, operator, database, middleware, and support accounts should not flow through the
+      same customer login path unless the product intentionally models and audits that boundary.
+30. Test the denial matrix.
+    - Success tests prove little.
+    - For each protected resource, cover anonymous, normal user, other owner, same organization
+      different role, other tenant, admin wrong tenant, revoked user, suspended member, stale token,
+      read-only API key, and service account cases where relevant.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The API access-control decision names subject, object, action, field or property, tenant or owner,
+  current state, and trusted context when those apply.
+- Authentication, object authorization, property authorization, and function authorization are not
+  collapsed into one route guard.
+- Client-supplied identity and authority fields are either ignored, verified against server-side
+  state, or explicitly reported as risky.
+- List, detail, search, export, download, batch, worker, webhook, signed URL, cache, GraphQL, and
+  admin paths are checked or explicitly scoped out.
+- Token, session, cookie, OAuth/OIDC, reset, reauthentication, account-enumeration, and automation
+  defenses are checked when touched.
+- Denial-case tests or missing test gaps are named from the attacker's point of view.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured tests that prove denial behavior: wrong owner, wrong tenant, wrong
+role, revoked or suspended actor, stale token, forbidden field update, mass-assignment attempt,
+unauthorized export or download, unauthorized batch item, worker revalidation, webhook ownership,
+and account-enumeration response parity.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If subject, object, action, field, tenant, state, source of truth, or denial evidence is missing,
+  report the gap instead of claiming the API is safe.
+- If the fix requires broad auth model changes, use `auth-permission-change` before editing that
+  scope.
+- If a sensitive value appears in logs, diffs, fixtures, screenshots, command output, or final
+  reports, stop repeating it and use `secret-exposure-response` when it may be a real secret.
+- If a command fails, use `failure-triage` before further edits.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- API access control reviewed
+- Subject, object, action, field, tenant or owner, state, and trusted context
+- Object, property, and function authorization findings
+- Authentication, session, token, cookie, OAuth/OIDC, reset, reauthentication, enumeration, and
+  automation findings
+- List/detail/search/export/download/batch/worker/webhook/signed URL/cache/GraphQL/admin findings
+- Fixes made or recommendation
+- Denial tests or behavior evidence
+- Command intents run
+- Skipped checks and reasons
+- Remaining API access-control risk

package/templates/default/locales/en/.mustflow/skills/api-misuse-resistance-review/SKILL.md

@@ -0,0 +1,297 @@
+---
+mustflow_doc: skill.api-misuse-resistance-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: api-misuse-resistance-review
+description: Apply this skill when code is created, changed, reviewed, or reported and an API, SDK, function boundary, service method, endpoint, command method, DTO, request shape, response shape, pagination contract, idempotency behavior, async job boundary, versioning policy, deprecation path, rate-limit rule, retry rule, observability surface, or caller-facing contract needs review for caller ergonomics, misuse resistance, hidden state machines, ambiguous parameters, internal model leakage, and operation-centered design.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.api-misuse-resistance-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# API Misuse Resistance Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review APIs from the caller's side, not from the implementer's convenience.
+
+The review question is not "does this endpoint or method work?" It is "can a tired caller use this
+API without memorizing hidden order, internal tables, boolean meanings, null folklore, retry traps,
+or Slack-thread failure semantics?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code review, implementation, or refactor work touches public or internal APIs, service methods,
+  SDKs, generated clients, controller methods, RPC procedures, command methods, function signatures,
+  request schemas, response DTOs, error envelopes, pagination, filtering, sorting, idempotency,
+  retries, async jobs, bulk operations, cache headers, versioning, deprecation, rate limits,
+  observability fields, or caller-facing documentation.
+- An API appears technically compatible but may invite caller mistakes through implementation-leaking
+  names, ordering requirements, boolean flags, broad options objects, nullable semantics, raw table
+  fields, status mutation, PATCH-as-command behavior, time or money primitives, closed enum
+  assumptions, overlarge responses, overfragmented calls, internal/external API mixing, or untested
+  failure cases.
+- A review needs to decide whether to apply `api-contract-change`, `type-state-modeling-review`,
+  `business-rule-leakage-review`, `error-message-integrity-review`, `backend-reliability-change`,
+  `cache-integrity-review`, `security-flow-review`, `result-option`, or `state-machine-pattern`.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main task is API source-of-truth synchronization, status/schema compatibility, generated
+  client drift, OpenAPI or protobuf compatibility, or endpoint migration; use `api-contract-change`
+  first and this skill only for caller misuse traps.
+- The main task is making impossible domain states unrepresentable in types; use
+  `type-state-modeling-review` first.
+- The main task is failure content quality; use `error-message-integrity-review`.
+- The main task is false success, partial state, retry exhaustion, or failure integrity; use
+  `failure-integrity-review` or `backend-reliability-change`.
+- The API is private implementation glue with no stable caller, no reusable boundary, no docs, and
+  no expected independent evolution.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, current diff or target files, and every changed caller-facing boundary.
+- Caller ledger: human caller, frontend, mobile app, CLI, worker, SDK user, partner integration,
+  internal service, batch job, webhook sender, support tool, or generated client.
+- Operation ledger: what the caller is trying to accomplish, the minimal operation name, required
+  inputs, optional inputs, side effects, ordering constraints, sync or async completion, and retry
+  or cancellation expectations.
+- Shape ledger: names, parameters, option objects, DTO fields, status fields, null and empty values,
+  error shape, pagination fields, sorting and filtering fields, money and time units, enum values,
+  bulk result shape, cache headers, versioning, deprecation, rate-limit hints, and observability
+  identifiers.
+- Existing contract source, local API style, SDK conventions, generated client behavior, docs,
+  examples, tests, and configured command intents.
+
+<!-- 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 caller, operation, shape, or compatibility evidence can
+  be reported without guessing.
+- If the review finds concrete schema compatibility, security, state-machine, result-type, cache,
+  failure-integrity, or backend reliability risk, use the narrower skill before editing that part.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Rename APIs toward caller intent, split hidden modes into separate operations, replace ambiguous
+  booleans with named options or distinct methods, narrow option bags, clarify null and patch
+  semantics, separate internal and public DTOs, add stable error codes, add idempotency or retry
+  metadata, expose async job resources, represent partial failures, tighten pagination, add cache
+  and rate-limit hints, and add focused contract tests.
+- Update docs, examples, SDK wrappers, generated client fixtures, API schemas, mocks, changelog
+  notes, deprecation notes, and tests that describe the same caller contract.
+- Keep changes scoped to the boundary under review and its synchronized surfaces.
+- Do not silently break existing public callers, widen responses with internal data, turn every
+  helper into a public API, or hide a breaking design change behind naming polish.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read the call site aloud.
+   - If the call reads like a wiring diagram, the API is leaking implementation.
+   - `createUserWithValidationAndEmailSend` tells the caller to remember internal steps.
+   - Prefer operation intent such as `registerUser`, `inviteUser`, `payOrder`, or `startReport`.
+2. Separate purpose from mechanism in names.
+   - Names should say what the caller wants, not DB, Redis, Kafka, email, validation, batch, cache,
+     queue, or storage details.
+   - Keep implementation details in internals, logs, or diagnostics unless the caller genuinely
+     controls that mechanism.
+3. Expose hidden state machines.
+   - APIs that require `init`, `setConfig`, `connect`, `start`, `flush`, and `close` in one exact
+     sequence are unsafe unless the type, builder, lifecycle object, or command model enforces the
+     sequence.
+   - Ask what happens if a caller skips, repeats, or reorders each step.
+4. Hunt boolean parameters.
+   - `getUsers(true)`, `sendEmail(false)`, and `createOrder(order, true, false)` are call-site
+     riddles.
+   - Replace with named options, separate operations, or domain variants when the boolean changes
+     behavior.
+5. Audit option objects as mode bags.
+   - `skipValidation`, `sendWelcomeEmail`, `createdByAdmin`, `importMode`, `dryRun`, and
+     `temporaryPassword` in one object often means several workflows share one unsafe door.
+   - Split by use case when options describe different business operations instead of incidental
+     configuration.
+6. Give absence one meaning per boundary.
+   - Count `null`, `undefined`, empty string, empty array, omitted field, and default value.
+   - If they mean delete, keep, clear, unknown, not loaded, or not applicable differently, model that
+     with explicit types, commands, or patch operations.
+7. Stop leaking storage rows as response DTOs.
+   - Fields like `deleted_at`, `status_code`, `type_flag`, raw foreign keys, provider IDs, and
+     internal timestamps can freeze database design into the API contract.
+   - Public DTOs should represent caller concepts, not table plumbing.
+8. Treat error shape as part of usability.
+   - A string-only error blocks client branching, retry decisions, localization, support, and
+     monitoring.
+   - Ensure stable code, readable message, cause category, retryability, and safe request or support
+     ID exist where callers need them.
+9. Model failure as carefully as success.
+   - Include permission denied, duplicate request, already processed, missing resource, conflict,
+     provider timeout, cancelled resource, partial success, and validation failure where relevant.
+   - If the response model cannot describe these states, the API will lie later.
+10. Require idempotency for networked creation with side effects.
+    - Orders, payments, invites, subscriptions, refunds, and external writes need duplicate-request
+      safety because clients cannot know whether a timeout happened before or after commit.
+    - Button disabling is not an idempotency strategy.
+11. Make pagination stable under moving data.
+    - Offset pagination is unsafe for feeds, orders, notifications, logs, and any list that changes
+      while the user pages through it.
+    - Cursor pagination still needs an immutable or stable sort key, tie-breaker, page limit, and
+      empty-page semantics.
+12. Define sorting and filtering as contracts.
+    - A list without default order, tie-breaker, max size, allowed filter set, unknown-filter
+      behavior, null ordering, case sensitivity, timezone, and locale behavior is a random API.
+13. Show authorization shape in the API.
+    - `updateUser(userId, payload)` hides whether the caller edits self, a team member, or any user
+      as an admin.
+    - Prefer operation or route shapes that make permission mode visible, such as `updateMyProfile`
+      versus `adminUpdateUser`.
+14. Review state changes as commands.
+    - `updateOrderStatus(orderId, status)` lets callers request illegal transitions.
+    - Prefer command operations such as `payOrder`, `cancelOrder`, `shipOrder`, and `refundOrder`
+      where guards and effects have a home.
+15. Keep PATCH from becoming a command bus.
+    - Partial field updates should not secretly perform account closure, email verification,
+      payment cancellation, invitation acceptance, permission changes, or lifecycle transitions.
+    - Important behavior deserves an operation name.
+16. Specify time values fully.
+    - Time values need UTC basis or explicit timezone, ISO format, precision, server clock behavior,
+      expiration semantics, and display responsibility.
+    - Local strings without timezone are delayed bugs.
+17. Keep money out of floating-point shapes.
+    - Use minor-unit integers or decimal-safe representations plus currency.
+    - Include rounding, tax, fee, discount, and precision rules where the API participates in money
+      movement.
+18. Treat external enums as open.
+    - Public or provider-facing clients must survive unknown future values.
+    - Internal closed enums still need a boundary decision for unknown, deprecated, or provider-only
+      statuses.
+19. Draw the sync or async boundary.
+    - Image processing, reports, email delivery, bulk imports, external settlement, and long-running
+      work need job ID, state query, completion signal, cancellation semantics, timeout behavior,
+      and failure reason.
+    - `200 OK` must not imply finished when the work only started.
+20. Represent partial failure honestly.
+    - Bulk APIs need item-level results and aggregate summary.
+    - "All failed" can duplicate successful items on retry; "all succeeded" loses failed items.
+21. Ask whether the response can be cached.
+    - GET APIs should define freshness, cache key, user or tenant variance, ETag or Last-Modified,
+      cache-control, and invalidation boundaries when the response is expensive or frequently read.
+22. Balance response size and call count by caller task.
+    - Overfriendly list APIs that include every relation become slow.
+    - Overfragmented APIs that force the frontend to assemble one screen from many calls move backend
+      workflow into the client.
+    - Shape endpoints around caller tasks, with explicit includes or field selection when useful.
+23. Separate internal and external APIs.
+    - Internal APIs can change faster and carry richer operational context.
+    - External APIs need slower evolution, compatibility, documentation, and deprecation policy.
+    - One shared shape usually damages both.
+24. Treat version labels as policy, not decoration.
+    - `/v1` does not protect callers if field meanings, enum behavior, pagination, or errors change
+      under the same version.
+    - Define what counts as breaking, how long old versions live, how usage is monitored, and how
+      migration is communicated.
+25. Make deprecation measurable.
+    - A deprecated field or endpoint without usage tracking cannot be removed safely.
+    - Capture client, field, endpoint, version, and volume evidence where privacy policy allows.
+26. Define rate limits and retry hints.
+    - Limits without `Retry-After`, reset time, retryable classification, and client guidance punish
+      well-behaved callers.
+    - No limits lets buggy clients harm everyone else.
+27. Make the API observable.
+    - Request ID, caller ID, operation, latency, status, error code, downstream result, retry count,
+      cache hit, and job ID should be traceable where relevant.
+    - If operations cannot be traced, the API cannot be operated.
+28. Test through the caller contract.
+    - Success examples alone do not prove an API design.
+    - Cover duplicate request, missing resource, permission denied, unknown enum, invalid cursor,
+      large page size, timeout, retry, partial success, already processed, and deprecation behavior
+      where relevant.
+29. Check SDK ergonomics.
+    - If a typed SDK method name, input type, return type, or error handling becomes awkward, the
+      original HTTP, RPC, or service shape may be wrong.
+    - Generated types should reduce mistakes, not require callers to memorize transport details.
+30. Finish with the first-time caller question.
+    - What will a new caller misunderstand?
+    - If the likely mistake costs money, permissions, data, duplicate work, broken pagination, stale
+      cache, or unretryable failure, fix the API shape instead of adding prose warnings.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The API expresses caller intent rather than internal implementation sequence.
+- Ordering requirements, lifecycle states, side effects, retries, idempotency, async completion,
+  permission modes, cacheability, pagination, filtering, sorting, and deprecation rules are explicit.
+- Parameter shapes, option objects, null semantics, DTO boundaries, time values, money values, enums,
+  errors, bulk results, and job states resist common caller mistakes.
+- Internal and external API needs are separated or intentionally aligned with compatibility evidence.
+- Tests, examples, SDKs, schemas, mocks, docs, and observability fields cover the changed caller
+  contract where relevant.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer tests that exercise the API from the caller's perspective: SDK calls, generated clients,
+contract fixtures, request/response examples, failure states, pagination behavior, duplicate
+requests, rate limits, async job transitions, and docs examples that callers copy.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the caller, compatibility promise, version policy, or source of truth is unknown, report the
+  missing contract instead of guessing.
+- If fixing misuse resistance would break current callers, classify the break and use
+  `api-contract-change` before editing the public shape.
+- If a command fails, use `failure-triage` before further edits.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- API misuse resistance reviewed
+- Caller and operation ledger
+- Names, order requirements, parameters, options, absence semantics, DTO leakage, errors,
+  idempotency, pagination, sorting, filtering, auth shape, state commands, PATCH semantics, time,
+  money, enum, async, bulk, cache, response size, internal/external, version, deprecation, rate
+  limit, observability, SDK, and test findings
+- Fixes made or recommendation
+- Compatibility and synchronized surface notes
+- Tests or behavior evidence
+- Command intents run
+- Skipped checks and reasons
+- Remaining API misuse risk