mustflow 2.84.0 → 2.99.0

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.api-access-control-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 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.
+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, payment or refund API authorization, broken authentication, tenant isolation, effective permission decisions, 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
@@ -43,6 +43,10 @@ perform this action on this object, this field, and this tenant context?"
   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.
+- Payment, refund, transfer, payout, credit, entitlement, or subscription APIs need proof that the
+  requester may act on that specific object, amount-bearing operation, tenant, account, or current
+  resource state. Use `payment-integrity-review` for money-event correctness and this skill for the
+  API object, property, and function authorization proof.
 - 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.
@@ -73,6 +77,9 @@ perform this action on this object, this field, and this tenant context?"
 - 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.
+- Decision explanation ledger: effective permission, matched policy, explicit deny, inheritance
+  path, policy version, data revision, token issue time, and allow or deny reason when the product
+  has policy-engine or audit-log support.
 - 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.
@@ -135,101 +142,111 @@ perform this action on this object, this field, and this tenant context?"
    - `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.
+   - Prefer effective-permission evidence and policy decision explanations over a raw role list.
+6. Check default-deny and explicit-deny behavior.
+   - No matching policy, unknown role, unknown action, malformed id, parsing failure, policy server
+     timeout, and policy-cache miss should not silently allow access.
+   - When allow and deny policies both match, the product needs a documented and tested combination
+     rule.
+7. 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.
+8. 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.
+9. 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.
+10. 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.
+11. 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.
+12. 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.
+13. 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.
+14. 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.
+15. 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.
+16. 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.
+17. 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.
+18. 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.
+19. 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.
+20. 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.
+21. 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.
+22. 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.
+23. 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.
+24. Measure revocation and stale-permission windows.
+    - User removal, role demotion, organization leave, policy-version changes, subscription state
+      changes, and ownership transfers should say how quickly sessions, JWTs, caches, search
+      indexes, queued jobs, and signed URLs stop authorizing old access.
+25. 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.
+26. 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.
+27. 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.
+28. 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.
+29. 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.
+30. 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.
+31. 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.
+32. 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,
@@ -240,6 +257,8 @@ perform this action on this object, this field, and this tenant context?"
 
 - The API access-control decision names subject, object, action, field or property, tenant or owner,
   current state, and trusted context when those apply.
+- Effective permission, matched policy, explicit deny, inheritance path, policy version, data
+  revision, token issue time, and revocation window are checked or named as gaps when relevant.
 - 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
@@ -287,6 +306,8 @@ and account-enumeration response parity.
 
 - API access control reviewed
 - Subject, object, action, field, tenant or owner, state, and trusted context
+- Effective permission, decision explanation, policy version, data revision, token age, and
+  revocation-window findings
 - Object, property, and function authorization findings
 - Authentication, session, token, cookie, OAuth/OIDC, reset, reauthentication, enumeration, and
   automation findings

package/templates/default/locales/en/.mustflow/skills/api-failure-triage/SKILL.md

@@ -0,0 +1,270 @@
+---
+mustflow_doc: skill.api-failure-triage
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: api-failure-triage
+description: Apply this skill when an API request, SDK call, webhook callback, browser request, mobile call, gateway route, CORS preflight, CDN or load-balancer path, upstream dependency call, or OpenAPI-backed integration is failing, intermittent, slow, returning the wrong status or body, blocked by authentication or authorization, rate-limited, retried, cached incorrectly, or not yet localized to client, network, proxy, app, database, cache, provider, or deployment configuration. Use before api-request-performance-review when the first job is to preserve the failing wire evidence and cut the failure boundary.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.api-failure-triage
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# API Failure Triage
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Triage API failures by preserving the actual request and cutting the path boundary before editing
+code.
+
+The first question is not "which log looks suspicious?" It is "what bytes left the caller, what
+bytes came back, which boundary changed them, and what evidence would disprove each hypothesis?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A user reports that an API call, SDK request, browser request, mobile request, webhook callback,
+  backend-for-frontend path, gateway route, CDN path, load-balancer path, or provider integration is
+  failing or intermittent.
+- The failure is not yet localized to client code, DNS, TCP, TLS, proxy, CORS preflight, redirect,
+  gateway, app handler, database, cache, external provider, rate limiter, retry policy, auth,
+  deployment configuration, or OpenAPI drift.
+- Code or docs claim an API failure is a network issue, CORS issue, server issue, auth issue, cache
+  issue, provider issue, or retry issue without preserved wire evidence.
+- A fix might otherwise start from logs, framework assumptions, SDK behavior, browser console text,
+  or a broad search before one failing request is captured.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The failing request is already reproduced and the root cause is clear enough for a targeted fix;
+  use the narrower code, API contract, cache, retry, auth, database, or failure-integrity skill.
+- The task is only per-request latency optimization after the API path is known; use
+  `api-request-performance-review`.
+- The task is only public error wording or error-envelope cleanup; use
+  `error-message-integrity-review`.
+- The task is only observability design with no current API failure to localize; use
+  `observability-debuggability-review`.
+- Reproduction requires live production secrets, destructive calls, real payments, real user data,
+  private logs, or unconfigured external systems. Preserve available static evidence and report the
+  manual boundary instead.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Failure packet: observed time and timezone, request id or trace id when present, caller, client or
+  SDK version, API version, method, URL route template, sanitized headers, sanitized body shape,
+  status code, response headers, response body shape, total latency, and retry or redirect behavior.
+- Success comparator: a nearby successful request, previous working version, same request with one
+  dimension changed, or a documented expected request shape.
+- Boundary ledger: client, browser preflight, SDK middleware, DNS, TCP, TLS, proxy, CDN, WAF,
+  gateway, load balancer, app, queue, database, cache, external provider, and response serialization
+  boundaries relevant to the path.
+- Timing ledger: name lookup, connection, TLS, first byte, total transfer, app handler time, queue
+  time, pool wait, database time, cache time, external dependency time, serialization time, and
+  download time when evidence exists.
+- Contract ledger: HTTP method, redirect behavior, content negotiation, content type, encoding,
+  status code semantics, error envelope, retryability, idempotency, rate-limit headers, cache
+  headers, OpenAPI or generated-client contract, and deployment version.
+- Auth ledger: credential presence, token expiry and not-before time, signature timestamp, clock
+  skew, user or service principal, object authorization, tenant scope, and proxy header preservation.
+- Change ledger: deploy, config, secret, feature flag, routing rule, schema migration, provider
+  version, generated client, cache policy, rate-limit policy, and environment difference near the
+  first bad time.
+- 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.
+- Required request, response, boundary, timing, contract, auth, and change evidence is available or
+  can be reported as missing without guessing.
+- If the preserved evidence exposes secrets, tokens, cookies, personal data, payment data, private
+  URLs, raw bodies, or hidden reasoning, summarize and redact rather than copying it into docs,
+  tests, logs, commits, or final reports.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten request parsing, content-type handling, status mapping, Problem Details or local
+  error-envelope mapping, request ID propagation, trace context, auth checks, proxy header handling,
+  timeout classification, retry and idempotency classification, rate-limit response handling, cache
+  header handling, OpenAPI contract tests, deployment config comparison tests, and focused
+  reproduction fixtures.
+- Add focused tests that preserve the failing wire shape, success/failure comparator, status and
+  body contract, auth boundary, retryability, cache behavior, OpenAPI drift, or deployment config
+  difference.
+- Do not add broad retries, blanket cache bypasses, CORS wildcards, auth bypasses, status-code
+  remapping, proxy header trust, live provider calls, raw production log dumps, or speculative
+  framework rewrites before the failing boundary is localized.
+- Do not treat browser console text, SDK exception text, status code alone, or application logs alone
+  as the failing request evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Preserve one failing request packet.
+   - Record method, route template, sanitized headers, sanitized body shape, status, response
+     headers, response body shape, total latency, request id, trace id, caller version, API version,
+     and observed time basis.
+   - If the failure is intermittent, keep the first bad time and a small sample of failing and
+     successful packets rather than a raw log dump.
+2. Compare success and failure at the wire boundary.
+   - Compare actual transmitted method, URL encoding, query order and defaults, headers, cookies,
+     body shape, null versus empty string, array order, content type, accept header, charset, API
+     version, and redirect path.
+   - Do not compare only source code or SDK call arguments because middleware, retries, proxies,
+     redirects, and defaults can rewrite the request.
+3. Cut the path into boundaries.
+   - Check whether the request reaches each boundary: client, preflight, SDK, DNS, TCP, TLS, proxy,
+     CDN, WAF, gateway, load balancer, app handler, queue, database, cache, external provider, and
+     response serializer.
+   - Prefer evidence that halves the search space. If the app never sees the request, app logs are
+     not the first evidence source.
+4. Split timing before assigning blame.
+   - Separate name lookup, connection, TLS, first byte, total download, app handler time, queue time,
+     pool wait, database time, cache time, external dependency time, serialization time, and payload
+     transfer when available.
+   - Average latency is weak evidence. Use endpoint, status, region, client, API version, and
+     percentile slices when telemetry exists.
+5. Check browser-only failures separately.
+   - For browser-only symptoms, inspect preflight, allowed method, allowed headers, credentials
+     mode, redirect behavior, and whether the failing request happens before the real method is sent.
+   - For server-to-server failures, do not diagnose CORS unless a browser boundary is actually
+     involved.
+6. Check redirect and proxy mutation.
+   - Verify whether redirects change method, body, host, scheme, authorization, cookies, or signed
+     headers.
+   - Verify whether proxies preserve `Authorization`, `Host`, forwarded headers, request ids,
+     trace context, content length, idempotency keys, and rate-limit headers according to local
+     trust policy.
+7. Check status, body, and content-type consistency.
+   - A `200` response with an error body, a `500` for caller validation, a hidden `404` for auth,
+     or a JSON content type with an HTML error body can break clients and monitoring.
+   - Map API errors to stable codes, request IDs, invalid fields, retryability, and safe support
+     evidence when the local contract supports it.
+8. Split authentication from authorization.
+   - Verify credentials were sent, valid, not expired, and signed against the expected time basis.
+   - Separately verify whether the authenticated principal can access the target object, property,
+     tenant, or function.
+   - Treat "same token, different resource id returns another user's data" as an access-control
+     incident, not ordinary debugging.
+9. Check clock and signature time.
+   - Review token `exp` or `nbf`, signed request timestamps, webhook timestamps, cache expiry, rate
+     limit windows, and server/client clock skew when the failure is intermittent or boundary-time
+     sensitive.
+10. Check retry, timeout, rate limit, and idempotency.
+    - Separate connect, TLS, first-byte, read, write, dependency, pool, and total-deadline failures
+      when evidence exists.
+    - Confirm retries are bounded, jittered, scoped to one layer, and safe for the operation.
+    - For side-effecting requests, require a durable idempotency key and result replay or unknown
+      outcome reconciliation before retrying.
+    - Preserve `429`, rate-limit policy, and retry-after semantics instead of turning throttling into
+      generic server failure.
+11. Check cache and content negotiation.
+    - Compare cached and cache-bypassed behavior when allowed by the current command and environment
+      boundary.
+    - Inspect cache-control, validators, age, vary dimensions, authorization or cookie variance,
+      API version, language, query dimensions, and stale or negative-cache behavior.
+12. Check app-internal cost and dependency fan-out only after the request reaches the app.
+    - If the app receives the request, build a compact cost ledger for database, cache, external API,
+      serialization, compression, and response size.
+    - Use `api-request-performance-review`, database, cache, retry, queue, or observability skills
+      for the localized subproblem.
+13. Check OpenAPI and generated-client drift.
+    - Compare deployed behavior with the documented contract: required fields, nullability, enum
+      values, status codes, headers, content type, and error envelope.
+    - Treat generated client, SDK, or schema drift as a contract issue even when the server and
+      client each look locally correct.
+14. Check deployment and environment diffs.
+    - Near the first bad time, compare release id, config, secret names, routing rules, feature
+      flags, provider account, migration state, cache policy, rate-limit policy, and generated
+      artifacts.
+    - Do not blame code before environment and route changes are ruled in or out.
+15. Maintain a hypothesis table.
+    - For each hypothesis, write the expected evidence and the observation that would disprove it.
+    - Kill wrong hypotheses quickly. Long log reading without a falsifiable hypothesis is not
+      progress.
+16. Apply the smallest localized fix.
+    - Once the boundary is proven, switch to the specific skill for that boundary and edit only the
+      owning code, contract, test, doc, template, or config surface.
+    - Re-run the original reproduction path or the closest configured intent after the fix.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The failing request packet, success comparator, boundary ledger, timing ledger, contract ledger,
+  auth ledger, and change ledger are explicit or reported as missing.
+- The failure is localized to a boundary or left as a named evidence gap instead of a guessed cause.
+- Status/body/content-type, CORS/preflight, redirects, proxy headers, authn/authz, clock skew,
+  timeout/retry/rate-limit/idempotency, cache headers, OpenAPI drift, and deployment diffs are fixed
+  or reported where relevant.
+- Any follow-up skill is selected because the boundary is now localized, not because the first guess
+  sounded plausible.
+
+<!-- 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 test, build, docs, release, or mustflow intent that covers the
+localized API failure boundary. Do not infer raw servers, live providers, database shells, browser
+sessions, packet captures, production logs, load tests, profilers, or network probes outside the
+command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the failing request packet cannot be captured, stop speculative edits and report the closest
+  safe evidence plus the missing packet fields.
+- If evidence contains secrets or personal data, redact before storing or reporting it.
+- If boundary evidence requires live production access, private dashboards, external provider
+  consoles, or unconfigured network diagnostics, report the manual evidence boundary.
+- If a configured command fails, preserve the failing intent and output tail, then fix only the API
+  boundary or contract exercised by that failure.
+- If the root cause points to security, payment, rate limit, cache, retry, queue, or deployment risk,
+  switch to the narrower matching skill before editing that part.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- API failure triaged
+- Failing request packet and success comparator, with redactions
+- Boundary and timing ledger
+- Status/body/content-type, CORS/preflight, redirect/proxy, authn/authz, clock, retry/timeout,
+  rate-limit/idempotency, cache, OpenAPI, and deployment-diff findings
+- Hypotheses killed, still open, and selected localized boundary
+- Fix applied or recommended
+- Evidence level: reproduced packet, comparator evidence, configured-test evidence, static review
+  risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped diagnostics and reasons
+- Remaining API-failure risk

package/templates/default/locales/en/.mustflow/skills/architecture-deepening-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.architecture-deepening-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: architecture-deepening-review
-description: Apply this skill when architecture, module boundaries, or codebase structure need review before choosing a refactor or abstraction.
+description: Apply this skill when architecture, module boundaries, layered boundaries, or codebase structure need review before choosing a refactor or abstraction.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -36,7 +36,7 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- The user asks for architecture review, module boundaries, structural improvement, codebase deepening, maintainability review, or testability improvement.
+- The user asks for architecture review, layered architecture review, module boundaries, structural improvement, codebase deepening, maintainability review, or testability improvement.
 - The user asks where a design will break first as it grows, which responsibility boundary is most likely to blur, or whether a module, service, database owner, permission model, deployment unit, or failure boundary is still clear enough.
 - A file, module, service, handler, command, controller, or test suite looks broad enough that the next edit may add another responsibility.
 - Code exposes internal steps to many callers, repeats orchestration, or makes tests hard because policy, I/O, formatting, and dispatch are mixed.
@@ -58,6 +58,8 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 - Target area, current pain, and the user-facing or maintainer-facing reason to inspect architecture.
 - Relevant source files, call sites, exports, tests, fixtures, schemas, templates, or documentation that show current behavior and ownership.
 - Local patterns for modules, boundaries, naming, errors, dependency direction, and tests.
+- Current change-pressure evidence: which business rules, providers, data contracts, permissions, read paths, or operational demands are expected to change independently.
+- Current enforcement evidence: physical modules, package boundaries, import rules, architecture tests, public API surfaces, or reviewer-only conventions that allow or block boundary violations.
 - The data owner, write path, failure mode, and expected 3x, 10x, or 100x growth pressure when the review is about a design rather than only a file split.
 - Current changed-file list when the worktree is already dirty.
 - Relevant command-intent contract entries for verification.
@@ -87,39 +89,51 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 2. Inspect local evidence before judging.
    - Read imports, exports, public functions, call sites, related tests, and nearby module conventions.
    - Prefer evidence from current code and tests over generic architecture advice.
-3. Identify one to three candidate boundaries.
+3. Reject layer theater before proposing deeper structure.
+   - Do not treat `controller`, `service`, `repository`, `domain`, `infra`, or similar folder names
+     as architecture evidence by themselves.
+   - Check whether one business change forces edits across many technical folders. If yes, rank the
+     feature or capability boundary before adding another technical layer.
+   - Check whether dependency direction is enforced by modules, packages, import rules, architecture
+     tests, or build boundaries. Reviewer memory is weak evidence.
+   - Treat caller-owned ports, narrow use-case interfaces, adapter mappings, and explicit public
+     module surfaces as stronger boundary evidence than broad infrastructure-owned interfaces.
+   - Mark pass-through services, table-shaped repositories, generic CRUD bases, and `common`,
+     `shared`, or `utils` growth as smells unless they hide real policy, translation, transaction,
+     test, or provider complexity.
+4. Identify one to three candidate boundaries.
    - Each candidate must name the responsibility it would hide or clarify.
    - Reject candidates that only rename, wrap, or move code without lowering caller complexity or test cost.
-4. Force the design through the ownership and failure questions before scoring.
+5. Force the design through the ownership and failure questions before scoring.
    - Name the first likely mixed-responsibility boundary. Common early failures are business rules leaking into controllers, repositories, external adapters, UI components, or framework-specific handlers.
    - Name the final owner for important data. The owner is the module that protects the invariant, not necessarily the module that reads the value most often.
    - Separate original state from cache, search index, analytics, summary, AI output, provider response, or other derived state.
    - Identify every direct write path for high-impact fields such as status, role, permission, balance, quota, plan, entitlement, deleted state, payment state, or ownership.
    - Ask whether a failure creates a visible failure state or silently creates false success. High-impact paths such as authorization, payment, entitlement, deletion, and destructive administration should fail closed.
    - Ask whether duplicate requests, retries, webhook redelivery, queue replay, or worker restart can repeat a harmful effect. If yes, require an idempotency, ledger, outbox, or reconciliation boundary before calling the design safe.
-5. Check growth pressure in concrete stages.
+6. Check growth pressure in concrete stages.
    - At 3x scale, look first for implementation-quality failures: missing indexes, N+1 reads, large responses, synchronous file or image work, repeated external calls, and insufficient connection pools.
    - At 10x scale, look first for ownership and state failures: write hot spots, queue delay, cache invalidation, server-local files, scattered permission rules, external API rate limits, and deployment units that change for unrelated reasons.
    - At 100x scale, look first for partitioning and operational failures: data split boundaries, tenant or region hot spots, retry storms, external dependency isolation, long deploy recovery, missing observability, and manual-only recovery paths.
-6. Check scaling direction without forcing premature distribution.
+7. Check scaling direction without forcing premature distribution.
    - A small team may start with one larger server or a simple server set, but request handlers should not depend on process memory, local uploads, duplicate cron execution, in-transaction external calls, or server-specific job state.
    - Application servers should be able to become stateless. Databases may start with vertical scaling, but the design should not block read replicas, read models, queue-backed work, or future data partitioning.
    - Horizontal scaling is only real if any server can handle the same request, workers can safely duplicate or retry work, and database writes do not all converge on an uncontrolled hot spot.
-7. Score each candidate from 1 to 9.
+8. Score each candidate from 1 to 9.
    - User value: whether the structure protects a user-visible or public contract.
    - Maintenance value: whether future changes become smaller or less error-prone.
    - Blast radius: how many callers, files, schemas, templates, or docs would change.
    - Testability: whether behavior can be proven with existing or focused tests.
    - Reversibility: whether the change can be undone without a public migration.
    - Evidence confidence: whether the diagnosis is supported by local code, tests, or repeated change patterns.
-5. Choose the next action.
+9. Choose the next action.
    - Recommend one smallest structural move, or explicitly stop at analysis-only when the evidence is not strong enough.
    - If implementation proceeds, use the narrower matching skill before editing that boundary.
-6. Keep the structure move shallow-to-deep.
+10. Keep the structure move shallow-to-deep.
    - Start with caller simplification, naming, and responsibility boundaries.
    - Then extract a focused facade, policy, strategy, pure core, adapter, result type, or dependency boundary only when it clearly removes real complexity.
    - Avoid turning a broad file into many vague files with the same responsibilities.
-7. Verify and report.
+11. Verify and report.
    - Run the narrowest configured command intents that cover the changed surface.
    - Report skipped checks, unknown behavior evidence, and any candidate intentionally deferred.
 
@@ -128,6 +142,8 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 
 - The output contains a ranked architecture candidate list or one scoped structural change.
 - Any chosen change has a named reason tied to lower change cost, lower defect risk, or better testability.
+- Layered-architecture claims are backed by change-pressure, dependency-direction, public-surface,
+  and enforcement evidence rather than folder names alone.
 - Important data has a named owner, write path, original-or-derived classification, and failure behavior when the reviewed design touches durable state.
 - Growth pressure is either checked at 3x, 10x, and 100x or explicitly marked not relevant to the current architecture decision.
 - Behavior changes are excluded or explicitly moved to a separate follow-up.
@@ -164,6 +180,7 @@ Use documentation and release checks only when the review or chosen change touch
 
 - Review target and current pain
 - Evidence inspected
+- Layering, change-pressure, and boundary-enforcement evidence
 - Data owner, write path, and original-versus-derived state when relevant
 - Failure mode, idempotency, and recovery boundary when relevant
 - 3x, 10x, and 100x growth pressure when relevant