mustflow 2.103.10 → 2.103.12

package/schemas/repo-deploy-surface-report.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/repo-deploy-surface-report.schema.json",
+  "title": "mustflow repo deploy-surface report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "input",
+    "input_hash",
+    "has_deploy_surface",
+    "summary",
+    "surfaces",
+    "required_verification",
+    "manual_gates",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "deploy-surface" },
+    "script_ref": { "const": "repo/deploy-surface" },
+    "action": { "const": "inspect" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scanned_paths", "max_file_bytes"],
+      "properties": {
+        "scanned_paths": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "max_file_bytes": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "has_deploy_surface": { "type": "boolean" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "surfaces": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/surface" }
+    },
+    "required_verification": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "manual_gates": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "has_deploy_surface",
+        "surface_count",
+        "workflow_count",
+        "package_script_count",
+        "config_file_count",
+        "package_metadata_count",
+        "manual_gate_count",
+        "required_verification_count"
+      ],
+      "properties": {
+        "has_deploy_surface": { "type": "boolean" },
+        "surface_count": { "type": "integer", "minimum": 0 },
+        "workflow_count": { "type": "integer", "minimum": 0 },
+        "package_script_count": { "type": "integer", "minimum": 0 },
+        "config_file_count": { "type": "integer", "minimum": 0 },
+        "package_metadata_count": { "type": "integer", "minimum": 0 },
+        "manual_gate_count": { "type": "integer", "minimum": 0 },
+        "required_verification_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "surface_type",
+        "path",
+        "line",
+        "trigger",
+        "confidence",
+        "evidence",
+        "required_verification",
+        "manual_gates"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": {
+          "enum": [
+            "deploy_config",
+            "github_actions_workflow",
+            "package_metadata",
+            "package_script"
+          ]
+        },
+        "surface_type": {
+          "enum": [
+            "cloudflare",
+            "container",
+            "generic_deploy",
+            "github_pages",
+            "github_release",
+            "netlify",
+            "npm_publish",
+            "package_release",
+            "vercel"
+          ]
+        },
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "trigger": { "type": ["string", "null"] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "evidence": { "$ref": "#/$defs/evidence" },
+        "required_verification": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "manual_gates": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "line", "match"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "match": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "severity",
+        "message",
+        "path",
+        "json_pointer",
+        "metric",
+        "actual",
+        "expected"
+      ],
+      "properties": {
+        "code": { "const": "deploy_surface_detected" },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string", "minLength": 1 },
+        "json_pointer": { "type": ["string", "null"] },
+        "metric": { "type": ["string", "null"] },
+        "actual": { "type": ["number", "null"] },
+        "expected": { "type": ["number", "null"] }
+      }
+    }
+  }
+}

package/schemas/security-pattern-scan-report.schema.json

@@ -0,0 +1,196 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/security-pattern-scan-report.schema.json",
+  "title": "mustflow security-pattern-scan report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "policy",
+    "input_hash",
+    "targets",
+    "summary",
+    "truncated",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "security-pattern-scan" },
+    "script_ref": { "const": "repo/security-pattern-scan" },
+    "action": { "const": "scan" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "targets": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/target" }
+    },
+    "summary": { "$ref": "#/$defs/summary" },
+    "truncated": { "type": "boolean" },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "fingerprint": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{16}$"
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "max_file_bytes",
+        "max_files",
+        "max_findings",
+        "extensions",
+        "ignored_directories",
+        "evidence_mode"
+      ],
+      "properties": {
+        "max_file_bytes": { "type": "integer", "minimum": 1 },
+        "max_files": { "type": "integer", "minimum": 1 },
+        "max_findings": { "type": "integer", "minimum": 1 },
+        "extensions": { "$ref": "#/$defs/stringArray" },
+        "ignored_directories": { "$ref": "#/$defs/stringArray" },
+        "evidence_mode": { "const": "metadata_only" }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "path", "exists", "kind"],
+      "properties": {
+        "input": { "type": "string" },
+        "path": { "type": "string" },
+        "exists": { "type": ["boolean", "null"] },
+        "kind": { "enum": ["file", "directory", "missing", "other", "unknown"] }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target_count",
+        "file_count",
+        "finding_count",
+        "high_or_critical_count",
+        "category_count"
+      ],
+      "properties": {
+        "target_count": { "type": "integer", "minimum": 0 },
+        "file_count": { "type": "integer", "minimum": 0 },
+        "finding_count": { "type": "integer", "minimum": 0 },
+        "high_or_critical_count": { "type": "integer", "minimum": 0 },
+        "category_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "detector": {
+      "enum": [
+        "client_controlled_authority",
+        "cors_origin_reflection_with_credentials",
+        "dynamic_regex",
+        "eval_execution",
+        "fs_call_non_literal_path",
+        "insecure_cookie_options",
+        "local_storage_token",
+        "mass_assignment",
+        "native_deserialization",
+        "path_join_user_input",
+        "postmessage_missing_origin_check",
+        "postmessage_wildcard_target",
+        "raw_sensitive_request_logging",
+        "server_fetch_user_url",
+        "shell_true",
+        "sql_template_interpolation",
+        "tls_verification_disabled",
+        "unsafe_yaml_load"
+      ]
+    },
+    "category": {
+      "enum": [
+        "access_control",
+        "browser",
+        "command",
+        "crypto_transport",
+        "filesystem",
+        "injection",
+        "logging",
+        "parser",
+        "token_session"
+      ]
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path"],
+      "properties": {
+        "code": {
+          "enum": [
+            "security_pattern_client_controlled_authority",
+            "security_pattern_cors_origin_reflection_with_credentials",
+            "security_pattern_dynamic_regex",
+            "security_pattern_eval_execution",
+            "security_pattern_file_too_large",
+            "security_pattern_fs_call_non_literal_path",
+            "security_pattern_insecure_cookie_options",
+            "security_pattern_local_storage_token",
+            "security_pattern_mass_assignment",
+            "security_pattern_max_files_exceeded",
+            "security_pattern_max_findings_exceeded",
+            "security_pattern_native_deserialization",
+            "security_pattern_path_join_user_input",
+            "security_pattern_path_outside_root",
+            "security_pattern_postmessage_missing_origin_check",
+            "security_pattern_postmessage_wildcard_target",
+            "security_pattern_raw_sensitive_request_logging",
+            "security_pattern_server_fetch_user_url",
+            "security_pattern_shell_true",
+            "security_pattern_sql_template_interpolation",
+            "security_pattern_tls_verification_disabled",
+            "security_pattern_unreadable_path",
+            "security_pattern_unsafe_yaml_load"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "detector": { "$ref": "#/$defs/detector" },
+        "category": { "$ref": "#/$defs/category" },
+        "review_focus": { "type": "string" },
+        "fingerprint": { "$ref": "#/$defs/fingerprint" },
+        "json_pointer": { "type": ["string", "null"] },
+        "metric": { "type": ["string", "null"] },
+        "actual": { "type": ["number", "null"] },
+        "expected": { "type": ["number", "null"] }
+      }
+    }
+  }
+}

package/templates/default/i18n.toml

@@ -86,7 +86,7 @@ translations = {}
 [documents."skill.api-contract-change"]
 source = "locales/en/.mustflow/skills/api-contract-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.backend-reliability-change"]

package/templates/default/locales/en/.mustflow/skills/api-contract-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.api-contract-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: api-contract-change
-description: Apply this skill when HTTP, REST, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, API schemas, generated clients, SDKs, status codes, headers, content negotiation, cache headers, error envelopes, pagination, filtering, sorting, search, or public API examples are created or changed.
+description: Apply this skill when HTTP, REST, HTTP QUERY, Accept-Query, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, API schemas, generated clients, SDKs, status codes, headers, content negotiation, cache headers, error envelopes, pagination, filtering, sorting, search, or public API examples are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -29,7 +29,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Treat an API change as a contract change, not as a route or controller edit. The contract includes request schema, response schema, status code, headers, content negotiation, cache semantics, error shape, auth and permission behavior, pagination, filtering, sorting, search semantics, generated clients, SDKs, mocks, fixtures, examples, and documentation.
+Treat an API change as a contract change, not as a route or controller edit. The contract includes request method semantics, request schema, response schema, status code, headers, content negotiation, cache semantics, error shape, auth and permission behavior, pagination, filtering, sorting, search semantics, generated clients, SDKs, mocks, fixtures, examples, and documentation.
 
 The goal is to keep runtime behavior, type contracts, generated artifacts, callers, tests, and docs aligned.
 
@@ -37,6 +37,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 ## Use When
 
 - HTTP, REST, RPC, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, AsyncAPI, webhook, callback, public endpoint, internal endpoint, generated client, SDK, schema, mock, fixture, or API docs behavior changes.
+- HTTP method choices change, including GET, POST, PUT, PATCH, DELETE, safe/idempotent operations, request-body semantics, HTTP QUERY, or Accept-Query support.
 - Request body, query parameters, path parameters, headers, cookies, response body, content negotiation, content coding, status codes, redirects, caching headers, rate-limit headers, error envelopes, validation errors, auth errors, or permission errors change.
 - SSE, streaming response, WebTransport handshake, WebSocket fallback, compression negotiation, or delivery headers become part of the API behavior that callers rely on.
 - Pagination, filtering, sorting, search, includes, field selection, sparse fields, expansions, cursor shape, or total-count semantics change.
@@ -54,7 +55,8 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 ## Required Inputs
 
 - Changed route, controller, resolver, handler, schema, validator, generated client, SDK, tests, fixtures, mocks, and docs.
-- Current request and response schema, status code map, headers, content negotiation, content coding, error envelope, auth and permission behavior, rate-limit behavior, cache behavior, streaming or reconnect behavior, pagination/filter/sort/search contract, and deprecation/versioning policy.
+- Current method semantics, request and response schema, status code map, headers, content negotiation, content coding, error envelope, auth and permission behavior, rate-limit behavior, cache behavior, streaming or reconnect behavior, pagination/filter/sort/search contract, and deprecation/versioning policy.
+- For body-bearing read operations, current GET, POST, and QUERY tradeoffs; request body media type; Accept-Query or Allow discovery; cache-key construction; client, proxy, CDN, browser, and server framework support; fallback behavior; and canonical GET URI strategy when present.
 - OpenAPI, GraphQL schema, tRPC router, Hono app type, Elysia Eden type surface, protobuf files, generated clients, SDK examples, frontend callers, mobile callers, integration tests, docs examples, and mock servers when present.
 - Current public consumers, backwards-compatibility expectations, supported client versions, and migration or deprecation policy.
 - Configured verification intents.
@@ -82,13 +84,13 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 
 1. Name the contract source of truth: OpenAPI, GraphQL schema, route validator, tRPC router, Hono `AppType`, Elysia app/Eden surface, protobuf definition, hand-written SDK type, or docs-backed public contract.
 2. Build a contract ledger for each changed endpoint or operation:
-   - method or operation name;
+   - method or operation name, including safe, idempotent, cacheable, and request-body semantics;
    - path or field name;
    - request path, query, header, cookie, and body shape;
    - auth and permission requirement;
    - response success status and body;
    - error status and body;
-   - relevant headers, content negotiation, content coding, and cache variance;
+   - relevant headers, content negotiation, content coding, cache variance, and request-content cache-key inputs;
    - pagination, filtering, sorting, and search semantics;
    - generated clients, SDK functions, mocks, fixtures, examples, and docs.
 3. Classify each change:
@@ -98,6 +100,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
    - response field removed, renamed, narrowed, widened, or made nullable;
    - status code changed;
    - header added, removed, or changed;
+   - method semantics changed, including safe/idempotent behavior or body-bearing read behavior;
    - content coding, compression negotiation, streaming, reconnect, or cache-variance behavior changed;
    - error code or envelope changed;
    - pagination cursor or total semantics changed;
@@ -113,6 +116,9 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 ## API Style Policy
 
 - REST and HTTP APIs must keep method semantics, status code meanings, headers, content type, content coding, cache behavior, redirects, streaming behavior, and error envelope stable.
+- HTTP QUERY is for safe and idempotent read operations whose query input does not fit the URI cleanly. It is not a default replacement for GET or POST: keep GET for simple, shareable, bookmarkable, and widely cached URLs; avoid GET request bodies as portable API contracts; and call POST-as-search a semantic or compatibility fallback when QUERY support is unavailable.
+- A QUERY contract must define the query request media type with Content-Type, supported query formats with Accept-Query when advertised, Allow or fallback behavior for unsupported clients and intermediaries, CORS preflight expectations for browser callers, and whether Content-Location, Location, or 303 See Other lets callers repeat the operation with GET.
+- QUERY caching must include request content and relevant metadata in the cache key. Any cache-key normalization must match resource semantics; do not normalize the body only for convenience if that can merge distinct queries.
 - OpenAPI changes must include every status/body/header variant that callers rely on. A schema-only success response is not enough when errors are part of the contract.
 - GraphQL must not be forced into a REST envelope. Preserve GraphQL `data`, `errors`, `extensions`, partial response, nullability, and resolver error propagation semantics.
 - GraphQL nullable-to-non-null and non-null-to-null changes are contract changes. Nullability can change whether partial data survives an error.
@@ -131,7 +137,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 - Pagination must define cursor opacity, sort stability, page size limits, `next` and `previous` meaning, empty page behavior, total-count semantics, and whether filters affect counts.
 - Filtering and sorting must define allowed fields, default sort, null ordering, case sensitivity, timezone or locale behavior, invalid filter behavior, and whether unknown fields are rejected or ignored.
 - Search must define query normalization, tokenization, ranking stability expectations, highlight fields, typo tolerance, permissions, and private-data exclusion.
-- Headers such as content-type, content-encoding, vary, cache-control, etag, location, retry-after, rate-limit, pagination links, content-disposition, and deprecation headers are contract surfaces.
+- Headers such as content-type, accept-query, content-encoding, vary, cache-control, etag, location, content-location, retry-after, rate-limit, pagination links, content-disposition, and deprecation headers are contract surfaces.
 
 ## Dependent Surface Checklist
 
@@ -147,6 +153,7 @@ Check every relevant surface before finalizing:
 - API docs, README snippets, changelog, migration notes, deprecation notices, role matrix, and status-code docs;
 - auth and permission checks;
 - rate limits, cache keys, cache headers, search indexes, pagination cursors, and background jobs;
+- QUERY support, Accept-Query discovery, request-body cache-key logic, CORS preflight behavior, unsupported-method fallback, and GET-equivalent Location or Content-Location paths when body-bearing read operations are caller-visible;
 - streaming delivery, SSE event ids, reconnect behavior, proxy or CDN delivery settings, content-coding variants, and fallback clients when they are caller-visible;
 - observability dashboards, audit logs, analytics events, and alerting that parse status or error codes.
 
@@ -157,6 +164,8 @@ Check every relevant surface before finalizing:
 - Treating TypeScript inference as proof that runtime JSON is compatible.
 - Changing status codes without updating callers, docs, tests, and audit expectations.
 - Changing content encoding, streaming flush, reconnect, cache variance, or fallback behavior without updating callers, docs, tests, and delivery verification.
+- Treating GET request bodies as portable API contracts.
+- Switching complex read-only searches to QUERY without client/server/proxy/CDN support evidence, fallback behavior, Content-Type and Accept-Query policy, and request-content cache-key rules.
 - Treating generated clients as disposable when they are the public API.
 - Mixing GraphQL partial-response semantics with REST success/error envelopes.
 - Adding required request fields in a minor-compatible change without a default or compatibility path.
@@ -171,7 +180,7 @@ Check every relevant surface before finalizing:
 ## Postconditions
 
 - The API contract source of truth is known.
-- Request, response, status, header, content negotiation, cache, error, auth, permission, pagination, filtering, sorting, and search impacts are classified.
+- Request method semantics, response, status, header, content negotiation, cache, error, auth, permission, pagination, filtering, sorting, and search impacts are classified.
 - Breaking or compatibility-sensitive changes are named.
 - Generated clients, mocks, fixtures, tests, docs, and examples are synchronized or explicitly reported as skipped.
 - Framework-specific protocol semantics are preserved.
@@ -209,7 +218,7 @@ Prefer the narrowest configured checks that exercise the changed contract from a
 - API style and contract source of truth
 - Changed operations or endpoints
 - Compatibility classification
-- Request, response, status, header, content negotiation, cache, error, auth, permission, pagination, filter, sort, and search notes
+- Request method semantics, response, status, header, content negotiation, cache, error, auth, permission, pagination, filter, sort, search, and QUERY support notes when relevant
 - Generated client, SDK, mock, fixture, docs, and caller surfaces synchronized
 - Files changed
 - Command intents run

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.103.10"
+version = "2.103.12"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"