mustflow 2.103.20 → 2.103.21

package/dist/cli/lib/option-parser.js

@@ -85,6 +85,32 @@ export function getParsedCliStringOption(parsed, name) {
     const value = parsed.values.get(name);
     return typeof value === 'string' ? value : null;
 }
+export function parsePositiveIntegerCliOption(value, option, invalidMessageKey, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    return { value: parsed };
+}
+export function parseNonNegativeIntegerCliOption(value, option, invalidMessageKey, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^(?:0|[1-9]\d*)$/u.test(value)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, invalidMessageKey, { option, value }) };
+    }
+    return { value: parsed };
+}
 export function formatCliOptionParseError(error, lang) {
     if (error.kind === 'missing_value') {
         return t(lang, 'cli.error.missingValue', { option: error.option });

package/dist/cli/script-packs/repo-env-contract.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { ENV_CONTRACT_SCRIPT_REF, inspectEnvContract } from '../../core/env-contract.js';
 const ENV_CONTRACT_OPTIONS = [
@@ -9,19 +9,6 @@ const ENV_CONTRACT_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-keys', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoEnvContractHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/env-contract scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseEnvContractOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, ENV_CONTRACT_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxKeys = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-keys'), '--max-keys', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'envContract.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'envContract.error.invalidPositiveInteger', lang);
+    const maxKeys = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-keys'), '--max-keys', 'envContract.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/dist/cli/script-packs/repo-secret-risk-scan.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { inspectSecretRiskScan, SECRET_RISK_SCAN_SCRIPT_REF } from '../../core/secret-risk-scan.js';
 const SECRET_RISK_SCAN_OPTIONS = [
@@ -9,19 +9,6 @@ const SECRET_RISK_SCAN_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-findings', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'secretRiskScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'secretRiskScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoSecretRiskScanHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/secret-risk-scan scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseSecretRiskScanOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, SECRET_RISK_SCAN_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxFindings = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'secretRiskScan.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'secretRiskScan.error.invalidPositiveInteger', lang);
+    const maxFindings = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', 'secretRiskScan.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/dist/cli/script-packs/repo-security-pattern-scan.js

@@ -1,6 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
-import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parsePositiveIntegerCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { inspectSecurityPatternScan, SECURITY_PATTERN_SCAN_SCRIPT_REF, } from '../../core/security-pattern-scan.js';
 const SECURITY_PATTERN_SCAN_OPTIONS = [
@@ -9,19 +9,6 @@ const SECURITY_PATTERN_SCAN_OPTIONS = [
     { name: '--max-file-bytes', kind: 'string' },
     { name: '--max-findings', kind: 'string' },
 ];
-function parsePositiveInteger(value, option, lang) {
-    if (value === null) {
-        return { value: null };
-    }
-    if (!/^[1-9]\d*$/u.test(value)) {
-        return { value: null, error: t(lang, 'securityPatternScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed)) {
-        return { value: null, error: t(lang, 'securityPatternScan.error.invalidPositiveInteger', { option, value }) };
-    }
-    return { value: parsed };
-}
 export function getRepoSecurityPatternScanHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf script-pack run repo/security-pattern-scan scan [path...] [options]',
@@ -48,9 +35,9 @@ function parseSecurityPatternScanOptions(args, lang) {
     const [action, ...rest] = args;
     const parsed = parseCliOptions(rest, SECURITY_PATTERN_SCAN_OPTIONS, { allowPositionals: true });
     const json = hasParsedCliOption(parsed, '--json');
-    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
-    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
-    const maxFindings = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', lang);
+    const maxFiles = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-files'), '--max-files', 'securityPatternScan.error.invalidPositiveInteger', lang);
+    const maxFileBytes = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', 'securityPatternScan.error.invalidPositiveInteger', lang);
+    const maxFindings = parsePositiveIntegerCliOption(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', 'securityPatternScan.error.invalidPositiveInteger', lang);
     if (action !== 'scan') {
         return {
             action: 'scan',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.103.20",
+  "version": "2.103.21",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 188
+revision = 189
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -89,6 +89,12 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.http-api-semantics-review"]
+source = "locales/en/.mustflow/skills/http-api-semantics-review/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.backend-reliability-change"]
 source = "locales/en/.mustflow/skills/backend-reliability-change/SKILL.md"
 source_locale = "en"

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 188
+revision: 189
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -106,6 +106,11 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   shapes, response shapes, pagination, idempotency, async jobs, versioning, deprecation, rate
   limits, retry rules, observability, or caller-facing docs need caller-ergonomics and misuse-risk
   review rather than only schema compatibility.
+- Use `http-api-semantics-review` as an adjunct when HTTP method choices, safe/idempotent/cacheable
+  claims, GET/HEAD bodies, 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 HTTP
+  semantics review rather than only schema compatibility.
 - Use `api-access-control-review` as an adjunct when API security review needs BOLA or IDOR,
   object, property, or function authorization, tenant isolation, request-supplied identity,
   mass assignment, signed URLs, queue revalidation, webhook ownership, token/session hardening,
@@ -471,6 +476,7 @@ routes. Event routes stay inactive until their event occurs.
 | Product, app, service, CLI, API, SDK, library, desktop app, automation tool, or developer tool work needs a decision about which user, developer, operator, automation, integration, recovery, upgrade, documentation, or observability surfaces are supported now, deferred, explicitly unsupported, or internal-only | `.mustflow/skills/support-surface-advisor/SKILL.md` | Product stage, primary actors, main usage path, integration need, maintenance capacity, public-contract willingness, explicit non-goals, recovery and observability expectations, and current repository evidence | Support-surface plan, selected implementation boundaries, docs, tests, route metadata, core-engine boundary, and directly synchronized templates when installed | support-contract bloat, accidental public API, UI/CLI/API duplicate core logic, hidden integration promise, unsupported automation route, unowned recovery path, stale compatibility promise, or implementation explanation leaking into user-facing UI copy | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Product stage, actors, recommended surfaces, deferred and unsupported surfaces, blocking questions, maintenance and compatibility risks, core engine versus shell boundary, staged plan, verification, and remaining support-surface risk |
 | A task chooses, migrates, rewrites, or justifies a primary language, runtime, framework, compile target, or execution environment | `.mustflow/skills/runtime-target-selection/SKILL.md` | Current runtime surfaces, target options, product or system need, environment constraints, migration boundary, smoke targets, and performance or reliability claims | Decision records, skill procedures, route metadata, migration plans, command-contract proposals, tests, fixtures, docs, and smallest selected migration scaffold | language-preference rewrite, unsupported runtime target, unusable build loop, cache or artifact blowup, missing smoke target, deployment drift, or false performance claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_related`, `test_release`, `mustflow_check` | Decision boundary, candidate targets, environment and build-loop evidence, smoke targets, migration boundary, calibrated claims, verification, and remaining runtime-target risk |
 | Non-trivial code work needs early structure decisions around domain rules, public contracts, external I/O, operational safety, failure handling, concurrency, data flow, or future change cost | `.mustflow/skills/structure-first-engineering/SKILL.md` | User request, target files, project context, core boundary, data flow, expected failures, public contracts, I/O surfaces, and verification contract | Risk block, focused boundaries, DTOs, adapters, pure functions, error models, tests, and directly synchronized docs or contracts | under-designed hard boundary, speculative abstraction, vague service layer, mixed I/O and domain rules, hidden partial failure, or untestable behavior | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Work risk, structure decision, data flow, failure model, I/O and concurrency boundaries, tests, verification, and remaining structure risk |
+| HTTP API method semantics, safe/idempotent/cacheable claims, GET or HEAD request-body assumptions, OPTIONS capability discovery, HTTP QUERY, POST versus PUT URI ownership, PUT replacement, PATCH document formats, DELETE behavior, conditional requests, status-code recovery, cache headers, CORS method discovery, retry behavior, or intermediary compatibility are created, changed, reviewed, or reported | `.mustflow/skills/http-api-semantics-review/SKILL.md` | Endpoint method ledger, method contract, concurrency contract, PATCH media type and atomicity, GET/QUERY/POST search contract, cache and capability headers, caller and intermediary support evidence, and configured command intents | Route handlers, method choices, validators, OpenAPI or docs, SDK examples, gateway rules, CORS rules, cache headers, conditional request handling, status-code maps, focused tests, and directly synchronized templates | hidden GET mutation, non-portable GET or HEAD body, PUT partial merge, ambiguous PATCH JSON, PATCH partial success, DELETE body dependency, duplicate DELETE side effect, POST search semantic blur, QUERY without media type or body-aware cache key, stale-client field loss, missing If-Match, confused Allow versus CORS methods, `no-cache` treated as `no-store`, collapsed status-code recovery, or proxy/CDN/client incompatibility | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | HTTP API semantics reviewed, endpoint method ledger, safe/idempotent/cache/header/status/conditional request findings, fixes or recommendations, synchronized API surfaces, verification, and remaining HTTP semantics risk |
 | HTTP, REST, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, request/response schema, status code, header, content negotiation, cache header, error envelope, pagination, filtering, sorting, search, generated client, SDK, mock, fixture, or API docs contract is created or changed | `.mustflow/skills/api-contract-change/SKILL.md` | API style, contract source of truth, changed operations, request and response schemas, status and headers, content negotiation, error envelope, auth and permission behavior, pagination/filter/sort/search semantics, generated clients, SDKs, mocks, fixtures, callers, docs, and command contract entries | Routes, handlers, resolvers, validators, schemas, generated clients, SDKs, mocks, fixtures, docs, tests, and directly synchronized examples | route-only change, schema drift, generated-client breakage, hidden breaking change, status or error drift, pagination/search semantic drift, auth/permission drift, cache/header drift, or stale docs examples | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | API contract source, changed operations, compatibility classification, synchronized client/schema/docs/tests surfaces, verification, and remaining API contract risk |
 | Backend APIs, workers, jobs, queues, caches, database write paths, external service calls, health checks, observability, feature flags, idempotency, retries, outbox/inbox processing, or operational failure handling are created, changed, reviewed, or reported | `.mustflow/skills/backend-reliability-change/SKILL.md` | Backend surface, trigger shape, idempotency boundary, external-call deadline and retry policy, persistence and transaction boundary, queue/cache behavior, observability fields, rollout gate, and command contract entries | Handlers, services, workers, retry policy, timeout policy, idempotency storage, outbox/inbox code, cache boundaries, health endpoints, observability fields, flags, tests, docs, and directly synchronized templates | duplicate side effects, retry storm, unbounded wait, DB uniqueness race, cache stampede, stale cache authority, poison message loop, missing outbox/inbox, raw ORM response, object-level authorization bypass, high-cardinality telemetry, secret or personal-data log leak, broken liveness/readiness, or missing kill switch | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Backend surface, idempotency and retry/timeout decisions, queue/cache/database notes, health-probe split, observability and auth/DTO notes, rollout gate, verification, and remaining backend reliability risk |
 | HTTP delivery, content coding, compression negotiation, CDN or proxy cache behavior, streaming responses, SSE, EventSource, WebTransport, WebSocket fallback, HTTP/2 or HTTP/3 transport behavior, browser transport clients, reverse-proxy buffering, reconnect behavior, or delivery observability is created, changed, reviewed, or reported | `.mustflow/skills/http-delivery-streaming/SKILL.md` | Delivery surface, routes or assets, headers, cache and proxy/CDN path, browser/API clients, fallback behavior, streaming lifecycle, compression or dictionary choice, and observability fields | Route handlers, response headers, CDN/proxy config, browser transport code, streaming adapters, fallback clients, docs, tests, and directly synchronized templates | wrong content decoding, cache poisoning, private data cached publicly, proxy buffering, lost events, reconnect gaps, unsupported transport, unreliable datagram misuse, false compression win, or fallback failure | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Delivery ledger, negotiated encodings, cache/proxy behavior, stream/reconnect/fallback behavior, verification, and remaining delivery risk |

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/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.20"
+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",