mustflow 2.108.2 → 2.108.3

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

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/repo-dependency-surface-report.schema.json",
+  "title": "mustflow repo dependency-surface report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "input",
+    "input_hash",
+    "summary",
+    "surfaces",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "dependency-surface" },
+    "script_ref": { "const": "repo/dependency-surface" },
+    "action": { "const": "inspect" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "input": { "$ref": "#/$defs/input" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "surfaces": { "type": "array", "items": { "$ref": "#/$defs/surface" } },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "issues": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "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 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "surface_count",
+        "manifest_count",
+        "lockfile_count",
+        "update_config_count",
+        "audit_config_count",
+        "ecosystem_count",
+        "finding_count"
+      ],
+      "properties": {
+        "surface_count": { "type": "integer", "minimum": 0 },
+        "manifest_count": { "type": "integer", "minimum": 0 },
+        "lockfile_count": { "type": "integer", "minimum": 0 },
+        "update_config_count": { "type": "integer", "minimum": 0 },
+        "audit_config_count": { "type": "integer", "minimum": 0 },
+        "ecosystem_count": { "type": "integer", "minimum": 0 },
+        "finding_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "ecosystem", "kind", "path", "line", "name", "evidence"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "ecosystem": { "enum": ["go", "javascript", "python", "rust"] },
+        "kind": {
+          "enum": [
+            "audit_config",
+            "dependency_update_config",
+            "lockfile",
+            "manifest",
+            "package_manager_config",
+            "workspace_config"
+          ]
+        },
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path", "json_pointer", "metric", "actual", "expected"],
+      "properties": {
+        "code": {
+          "enum": [
+            "conflicting_javascript_lockfiles",
+            "manifest_without_lockfile",
+            "update_automation_without_policy",
+            "lockfile_without_manifest",
+            "dependency_surface_without_update_automation"
+          ]
+        },
+        "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/repo-toolchain-provenance-report.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/repo-toolchain-provenance-report.schema.json",
+  "title": "mustflow repo toolchain-provenance report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "input",
+    "input_hash",
+    "summary",
+    "sources",
+    "lockfiles",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "toolchain-provenance" },
+    "script_ref": { "const": "repo/toolchain-provenance" },
+    "action": { "const": "inspect" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "input": { "$ref": "#/$defs/input" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
+    "lockfiles": { "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}$" },
+    "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 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_count",
+        "runtime_count",
+        "package_manager_count",
+        "lockfile_count",
+        "ci_source_count",
+        "finding_count"
+      ],
+      "properties": {
+        "source_count": { "type": "integer", "minimum": 0 },
+        "runtime_count": { "type": "integer", "minimum": 0 },
+        "package_manager_count": { "type": "integer", "minimum": 0 },
+        "lockfile_count": { "type": "integer", "minimum": 0 },
+        "ci_source_count": { "type": "integer", "minimum": 0 },
+        "finding_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source_kind", "path", "line", "key", "value"],
+      "properties": {
+        "kind": { "enum": ["bun", "docker", "go", "node", "package_manager", "python", "rust"] },
+        "source_kind": {
+          "enum": [
+            "ci_workflow",
+            "dockerfile",
+            "go_mod",
+            "mise_toml",
+            "node_version_file",
+            "package_json",
+            "python_version_file",
+            "pyproject_toml",
+            "rust_toolchain",
+            "tool_versions"
+          ]
+        },
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "key": { "type": "string", "minLength": 1 },
+        "value": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path", "json_pointer", "metric", "actual", "expected"],
+      "properties": {
+        "code": {
+          "enum": [
+            "conflicting_node_version_sources",
+            "conflicting_package_manager_lockfiles",
+            "package_manager_without_lockfile",
+            "toolchain_declared_without_package_manager",
+            "runtime_declared_in_ci_only"
+          ]
+        },
+        "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/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 207
+revision = 211
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -709,7 +709,7 @@ translations = {}
 [documents."skill.go-code-change"]
 source = "locales/en/.mustflow/skills/go-code-change/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations = {}
 
 [documents."skill.godot-code-change"]
@@ -763,7 +763,7 @@ translations = {}
 [documents."skill.python-code-change"]
 source = "locales/en/.mustflow/skills/python-code-change/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations = {}
 
 [documents."skill.powershell-code-change"]
@@ -787,7 +787,7 @@ translations = {}
 [documents."skill.rust-code-change"]
 source = "locales/en/.mustflow/skills/rust-code-change/SKILL.md"
 source_locale = "en"
-revision = 6
+revision = 7
 translations = {}
 
 [documents."skill.runtime-target-selection"]
@@ -835,7 +835,7 @@ translations = {}
 [documents."skill.typescript-code-change"]
 source = "locales/en/.mustflow/skills/typescript-code-change/SKILL.md"
 source_locale = "en"
-revision = 6
+revision = 7
 translations = {}
 
 [documents."skill.unocss-code-change"]

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 207
+revision: 211
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -562,12 +562,12 @@ routes. Event routes stay inactive until their event occurs.
 | Node.js runtime code, package manager ownership, module format, package entry metadata, native dependencies, Node test runner behavior, TypeScript execution mode, or deployment runtime support is created or changed | `.mustflow/skills/node-code-change/SKILL.md` | Node version signals, package manager and lockfile owner, module/package metadata, TypeScript loader, test runner, native dependency, deployment target, and command contract entries | Node runtime code, package metadata, lockfiles, scripts, CI or Docker runtime declarations, test runner config, native dependency handling, docs examples, and directly synchronized package surfaces | newest-Node assumption, package manager drift, ESM/CJS break, blocked deep import, native dependency break, Node native TypeScript overclaim, test runner migration risk, deployment mismatch, or permission-model overclaim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Runtime and package manager decision, module/package entry notes, TypeScript/test runner notes, native/deployment risks, verification, and remaining Node.js risk |
 | Bun runtime code, `Bun.serve`, Elysia-on-Bun server behavior, Bun package manager behavior, `bun.lock`, `bunfig.toml`, Bun test runner behavior, Bun bundling, Bun compile, Bun TypeScript execution, Docker deployment, or Bun-specific APIs are created or changed | `.mustflow/skills/bun-code-change/SKILL.md` | Bun role signals, `package.json`, Bun and non-Bun lockfiles, `bunfig.toml`, CI/Docker Bun setup, TypeScript config, Bun APIs, server timeout and WebSocket settings, compile target, native dependency signals, and command contract entries | Bun runtime code, server config, package manager metadata, lockfiles, `bunfig.toml`, scripts, tests, bundler or compile config, TypeScript/declaration pipeline, Docker/deploy config, package metadata, and directly synchronized docs | Bun role confusion, lockfile drift, trusted dependency overgrant, runtime/package-manager conflation, Bun TypeScript typecheck overclaim, Bun build declaration gap, server timeout or WebSocket backpressure gap, compile target break, Node compatibility break, shebang mismatch, Docker/PORT drift, observability loss, or native binary break | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Bun role classification, lockfile/trust notes, runtime/type/build/test/deploy notes, Node compatibility risks, verification, and remaining Bun risk |
 | Dockerfiles, `.dockerignore`, Docker Compose files, BuildKit or buildx behavior, container image metadata, tags, entrypoints, health checks, Docker CI workflows, image security scanning, SBOM or provenance settings, registry publishing, or container runtime validation are created or changed | `.mustflow/skills/docker-code-change/SKILL.md` | Docker surfaces, project image shape, base image and platform signals, build context and cache signals, runtime contract, security and supply-chain contract, and command contract entries | Dockerfiles, `.dockerignore`, Compose files, container CI workflow snippets, image metadata, package tests, docs examples, template metadata, and directly synchronized skill routes | cache breakage, secret leak, root runtime, host access escape, dev dependency in final image, mutable tag drift, untrusted CI publish, missing SBOM/provenance, unverified runtime, or false production-readiness claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Docker surface classification, image/base/cache/stage decisions, secret/user/runtime/Compose/CI supply-chain notes, verification, and remaining Docker risk |
-| TypeScript source, declarations, tsconfig, package exports, module resolution, public API, compiler-version behavior, TypeScript 6-to-7 migration surfaces, TypeScript 7 RC or nightly tooling, or TypeScript tests are created or changed | `.mustflow/skills/typescript-code-change/SKILL.md` | TypeScript config, compiler track, package entry metadata, target runtime, changed files, declaration, TS6 API, TS7 RC, and optional TS7 nightly surfaces, and command contract entries | TypeScript source, declarations, compiler config, exports, tests, compiler-track comparison notes, and directly synchronized docs | weakened type safety, module drift, public API drift, unverified declaration output, TypeScript 6 deprecation suppression, TS7 RC over-adoption, TS7 nightly over-adoption, or compiler API track drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, module, type, public API, compiler-version, RC, nightly, and API-track boundary checked, changes made, verification, and remaining TypeScript risk |
+| TypeScript source, declarations, tsconfig, package exports, module resolution, project references, type-check performance, public API, compiler-version behavior, TypeScript 6-to-7 migration surfaces, TypeScript 7 RC or nightly tooling, runtime data validation, or TypeScript tests are created or changed | `.mustflow/skills/typescript-code-change/SKILL.md` | TypeScript config, compiler track, package entry metadata, target runtime, changed files, declaration, project references, package graph, TS6 API, TS7 RC, and optional TS7 nightly surfaces, and command contract entries | TypeScript source, declarations, compiler config, exports, tests, project-reference and type-graph notes, compiler-track comparison notes, and directly synchronized docs | weakened type safety, module drift, public API drift, DTO/domain drift, runtime validation gap, type-graph bloat, path alias boundary bypass, unverified declaration output, TypeScript 6 deprecation suppression, TS7 RC over-adoption, TS7 nightly over-adoption, or compiler API track drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, module, type, public API, project-reference, type-performance, compiler-version, RC, nightly, and API-track boundary checked, changes made, verification, and remaining TypeScript risk |
 | JavaScript source, module format, package entry, browser or Node runtime, dependency usage, Promise handling, bundler config, or JavaScript tests are created or changed | `.mustflow/skills/javascript-code-change/SKILL.md` | Package metadata, module system, runtime target, entrypoints, changed files, and command contract entries | JavaScript source, package exports, bundler config, dependencies, tests, and docs examples | runtime API leakage, ESM/CJS drift, discarded Promise, dependency bloat, or broken package entry | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime and module boundary checked, async and dependency notes, verification, and remaining JavaScript risk |
-| Python source, package metadata, runtime version, import layout, type checking, linting, CLI entry points, or tests are created or changed | `.mustflow/skills/python-code-change/SKILL.md` | Python version source, packaging files, import layout, lint/type/test config, changed files, and command contract entries | Python source, packaging metadata, imports, type hints, tests, and docs examples | unsupported syntax, import hacks, packaging drift, swallowed errors, or weakened lint/type checks | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, packaging, import, and type boundary checked, verification, and remaining Python risk |
+| Python source, package metadata, runtime version, import layout, architecture boundaries, type checking, async tasks, exception/logging/retry behavior, collection performance, pytest fixtures or mocks, linting, CLI entry points, or tests are created or changed | `.mustflow/skills/python-code-change/SKILL.md` | Python version source, packaging files, build backend or package-manager owner, import layout, architecture boundary, lint/type/test config, async/failure/performance surface, changed files, and command contract entries | Python source, packaging metadata, imports, type hints, adapters, async ownership, exception/logging/retry code, collection hot paths, tests, and docs examples | unsupported syntax, import hacks, packaging drift, framework or ORM leakage into domain code, false type safety, unowned task, swallowed cancellation, retry storm, hidden fallback, copy-heavy hot path, fixture state leak, bare mock lie, or weakened lint/type checks | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, packaging, import, architecture, type, async, failure, performance, and test boundary checked, verification, and remaining Python risk |
 | PowerShell scripts, modules, command examples, `pwsh` invocations, native-command wrappers, quoting, here-strings, splatting, regex, wildcard, replacement strings, or PowerShell argument passing are created or changed | `.mustflow/skills/powershell-code-change/SKILL.md` | PowerShell version and invocation path, parser layers, native-command boundary, dynamic input boundaries, changed files, and command contract entries | PowerShell scripts, modules, package scripts, CI snippets, docs examples, native-command wrappers, tests, and directly synchronized docs | parser-layer confusion, quote loss, variable over-expansion, metacharacter interpretation, native argv drift, command injection, `--%` overuse, or cross-shell `-Command` breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | PowerShell version and invocation boundary, parser ledger, string/here-string/regex/wildcard/replacement/native argv decisions, verification, and remaining PowerShell risk |
-| Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, benchmarks, tools, tests, or generated-code boundaries are created or changed | `.mustflow/skills/go-code-change/SKILL.md` | Module files, Go version support, full package files, tests, public API surface, concurrency owner, runtime/deployment context, changed files, and command contract entries | Go packages, module metadata, interfaces, errors, concurrency code, HTTP/proxy code, JSON encoding, filesystem and network helpers, runtime settings, tests, tools, and docs examples | unnecessary abstraction, unsupported Go feature, context loss, goroutine leak, missing timeout, JSON contract drift, filesystem traversal, IPv6 host-port bug, runtime tuning drift, error contract drift, or module drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Package, API, Go version, context, concurrency, runtime, HTTP, JSON, filesystem, tool, and error boundary checked, verification, and remaining Go risk |
-| Rust source, Cargo metadata, features, traits, errors, ownership, async runtime, unsafe code, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed | `.mustflow/skills/rust-code-change/SKILL.md` | Cargo metadata, feature flags, public exports, async runtime, unsafe invariants, `rust-version`, edition, toolchain, workspace policy, changed files, and command contract entries | Rust source, Cargo metadata, features, errors, traits, tests, examples, benchmarks, profiles, and docs | clone or lock bloat, unsupported Rust feature, feature drift, Cargo resolver drift, async runtime mixing, unsafe invariant loss, release-profile overclaim, or public API breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Ownership, MSRV, standard-library API, Cargo feature, async, unsafe, release-profile, and public API boundary checked, verification, and remaining Rust risk |
+| Go source, modules, workspaces, package APIs, package layout, `internal` boundaries, interfaces, structs, errors, goroutines, channels, context propagation, HTTP clients or servers, graceful shutdown, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, profiling, benchmarks, tools, tests, or generated-code boundaries are created or changed | `.mustflow/skills/go-code-change/SKILL.md` | Module files, workspace policy, Go version support, full package files, tests, public API surface, package ownership, concurrency owner, runtime/deployment context, changed files, and command contract entries | Go packages, module and workspace metadata, internal boundaries, interfaces, structs, errors, concurrency code, HTTP/shutdown/proxy code, JSON encoding, filesystem and network helpers, runtime settings, profiling and benchmarks, tests, tools, and docs examples | unnecessary abstraction, module boundary drift, unsupported Go feature, context loss, goroutine leak, missing timeout, unsafe shutdown, JSON contract drift, filesystem traversal, IPv6 host-port bug, runtime tuning drift, performance folklore, error contract drift, or dependency drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Package, API, module/workspace, Go version, context, concurrency, runtime, HTTP/shutdown, JSON, filesystem, profiling, tool, and error boundary checked, verification, and remaining Go risk |
+| Rust source, Cargo metadata, features, traits, errors, ownership, borrowing, lifetimes, `Clone`, `Rc`, `Arc`, `Mutex`, `RefCell`, async tasks, channels, cancellation, unsafe code, allocation, zero-copy, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed | `.mustflow/skills/rust-code-change/SKILL.md` | Cargo metadata, feature flags, public exports, ownership map, error convention, async runtime, task and channel policy, unsafe invariants, allocation or benchmark evidence, `rust-version`, edition, toolchain, workspace policy, changed files, and command contract entries | Rust source, Cargo metadata, features, errors, traits, ownership signatures, async task/channel code, tests, examples, benchmarks, profiles, and docs | clone or shared-state aliasing, lifetime debt, error opacity, unsupported Rust feature, feature drift, Cargo resolver drift, async runtime mixing, task or channel leak, zero-copy retention bug, allocation folklore, unsafe invariant loss, release-profile overclaim, or public API breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Ownership, MSRV, standard-library API, Cargo feature, error, async task/channel/cancellation, allocation, unsafe, release-profile, and public API boundary checked, verification, and remaining Rust risk |
 | Axum apps, routers, handlers, extractors, state, extensions, middleware, Tower or Tower-HTTP layers, CORS, cookies, headers, WebSockets, body limits, rejections, error responses, Tokio tasks or locks, SQLx pools, or Rust HTTP API tests are created, changed, reviewed, or upgraded | `.mustflow/skills/axum-code-change/SKILL.md` | Cargo and Axum-related crate version evidence, router ledger, handler and extractor contracts, state and extension owners, middleware and Tower stack, response envelope, Tokio runtime, SQLx pool and transaction boundaries, changed files, and command contract entries | Axum routers, handlers, extractors, state, extensions, middleware, Tower layers, CORS/cookie/header policy, error and rejection mapping, Tokio task and lock boundaries, SQLx pool setup, tests, and docs examples | stale Axum version claim, route syntax migration drift, auth or body-consuming extractor bug, `State` versus `Extension` leak, inconsistent error envelope, fallible Tower error not mapped to response, CORS-as-auth mistake, cookie confidentiality gap, sensitive header logging, body-limit bypass, unbounded spawn, lock contention, pool starvation, or transaction lifetime leak | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Axum version, route, handler, extractor, state, response, Tower middleware, CORS/cookie/header/body-limit, Tokio task/lock, SQLx pool, verification, and remaining Axum risk |
 | Godot projects, scenes, nodes, GDScript, C# scripts, Resources, Autoloads, signals, groups, save/load systems, rendering, physics, UI, input, exports, plugins, editor tools, or Godot version migrations are created, changed, reviewed, or upgraded | `.mustflow/skills/godot-code-change/SKILL.md` | Godot version, renderer, platform targets, project settings, input map, autoloads, addons, affected scenes, scripts, Resources, save/load participants, export presets, profiler evidence when performance is claimed, and command contract entries | Godot scenes, nodes, GDScript or C# scripts, Resources, Autoloads, signals, groups, save/load systems, rendering, physics, UI, input, exports, plugins, editor tools, tests, and docs examples | stale Godot version claim, scene-tree reach-through, global-state sprawl, shared Resource mutation, hidden signal flow, save corruption, thread-unsafe SceneTree access, renderer regression, target-device drift, export preset drift, or stale migration advice | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Godot version, renderer, scene, node, signal, Resource, Autoload, save/load, rendering, physics, UI, input, export, verification, and remaining Godot risk |
 | Dart source, pub package metadata, null safety, Futures, Streams, isolates, analyzer lints, tests, CLI entry points, or public package APIs are created or changed | `.mustflow/skills/dart-code-change/SKILL.md` | Pub metadata, analyzer config, public exports, async ownership, package layout, changed files, and command contract entries | Dart source, pub metadata, exports, async code, tests, examples, and docs | null-safety bypass, discarded Future, uncanceled Stream, isolate ownership drift, or public API breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Nullability, async, stream, isolate, and API boundary checked, verification, and remaining Dart risk |

package/templates/default/locales/en/.mustflow/skills/go-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.go-code-change
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: go-code-change
-description: Apply this skill when Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, benchmarks, tests, tools, or generated code boundaries are created or changed.
+description: Apply this skill when Go source, modules, workspaces, package APIs, package layout, internal boundaries, interfaces, structs, errors, goroutines, channels, context propagation, HTTP clients or servers, graceful shutdown, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, profiling, benchmarks, tests, tools, or generated code boundaries are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,13 +28,13 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JSON, filesystem, and test boundaries without adding needless abstraction.
+Preserve Go package, module, workspace, API, error, context, concurrency, runtime, HTTP, JSON, filesystem, performance, and test boundaries without adding needless abstraction.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem access, network addresses, runtime tuning, tools, or module dependencies change.
-- The task touches interfaces, error wrapping, package structure, concurrency ownership, cancellation, timeout policy, memory limits, race-sensitive code, benchmark measurement, or module dependencies.
+- `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, context propagation, HTTP clients or servers, graceful shutdown, reverse proxies, JSON encoding, filesystem access, network addresses, runtime tuning, profiling, tools, or module dependencies change.
+- The task touches interfaces, structs, zero-value behavior, error wrapping, package structure, `internal` boundaries, import direction, concurrency ownership, cancellation, timeout policy, memory limits, race-sensitive code, benchmark measurement, or module dependencies.
 - Code or docs use Go-version-gated features such as expression operands to `new`, range-over-function iterators, generic type aliases, reflect iterators, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root` or `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, experimental `GOEXPERIMENT` features, or newer runtime defaults.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -49,6 +49,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - `go.mod`, `go.sum`, `go.work`, build tooling, lint config, and CI hints.
 - All files in the changed package, including `_test.go`, build-tagged files, examples, and generated-file markers.
 - The public API surface when exported identifiers, errors, or package paths change.
+- Package ownership, import direction, `internal` visibility, module path, major-version suffix, workspace usage, and whether the project is an importable library, self-contained server, tool, or monorepo.
 - Runtime and deployment context when the change touches HTTP, goroutines, timers, memory, `GOMAXPROCS`, cgroups, race detection, PGO, profiling, or container behavior.
 - Minimum supported Go version, `go` directive, `toolchain` directive, `GOEXPERIMENT`, and whether the feature is stable, experimental, or repository-pinned.
 - Configured verification intents.
@@ -67,6 +68,9 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - Keep interfaces small and preferably owned by the consuming side.
 - Return concrete provider types from provider packages unless the package intentionally hides multiple implementations as its public API.
 - Keep domain and use-case packages free of SQL, HTTP transport, queue, cloud SDK, ORM, and vendor persistence types unless those types are the explicit public API.
+- Use `internal` to protect implementation freedom for server and tool packages that are not meant to be imported.
+- Keep structs, constructors, and zero values aligned with invariants: make the zero value useful, harmless, or impossible to misuse.
+- Split domain, storage, JSON, and transport DTO shapes when they have different owners, lifetimes, validation rules, or compatibility contracts.
 - Preserve context propagation across API and goroutine boundaries.
 - Return actionable errors and wrap causes when callers need `errors.Is` or `errors.As`.
 - Add table-driven tests when they clarify behavior.
@@ -76,43 +80,57 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 ## Procedure
 
 1. Read module files, package files, tests, build tags, and generated-code markers.
-2. Classify the change as package API, internal implementation, dependency, error behavior, context flow, concurrency, HTTP or proxy behavior, JSON encoding, filesystem safety, runtime or deployment behavior, benchmark, tooling, or test-only.
+2. Classify the change as module or workspace metadata, package API, package layout, internal implementation, dependency, error behavior, context flow, concurrency, HTTP or proxy behavior, JSON encoding, filesystem safety, runtime or deployment behavior, performance measurement, benchmark, tooling, or test-only.
 3. Check the Go version contract before using newer syntax or APIs:
    - treat the `go` directive as a language and module compatibility switch, not decoration;
    - do not use `new(expr)`, range-over-function iterators, generic type aliases, reflect iterator methods, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, or any `GOEXPERIMENT` feature unless the repository's supported Go version and build path allow it;
    - distinguish stable standard-library APIs from experimental APIs that require `GOEXPERIMENT`;
-   - when `go.mod` or `go.work` changes, report language-version, module-graph, toolchain, and downstream support impact.
+   - when `go.mod` or `go.work` changes, report language-version, module-graph, workspace, toolchain, and downstream support impact.
 4. Check package boundaries before adding a package or interface:
+   - treat a module as a release, version, and distribution boundary, not a folder-cleanup tool;
+   - treat `go.work` as a local multi-module development surface unless the repository explicitly supports committing and verifying workspace mode;
+   - keep module paths stable and use the required major-version suffix for v2+ modules;
+   - prefer `internal` for server implementation packages that are not intended as public imports;
+   - check import direction before function bodies: domain packages should not import HTTP status codes, ORM rows, SQL drivers, queues, cloud SDKs, or vendor transport shapes unless that dependency is the package's explicit contract;
    - reject shared bucket packages named `common`, `util`, `types`, `interfaces`, `api`, or `models` unless the repository already has a specific local convention with a narrower meaning;
    - put an interface in the package that consumes the methods, not in the package that merely implements them;
    - create an interface only after a real consumer needs that exact method set;
    - shrink an interface to the methods the immediate consumer calls;
    - reject provider-side interfaces that exist only for mocks;
    - reject provider constructors that return interfaces by default; prefer concrete exported types such as `*Client`, `*Store`, or `*Service`;
+   - use generics for reusable containers, algorithms, and type-safe plumbing, not as a substitute for clear domain boundaries;
    - verify that a package split reduces a real dependency direction problem or creates a coherent capability instead of hiding imports.
 5. If exported identifiers or package paths change, classify the public API impact:
    - treat exported functions, variables, constants, types, methods, struct fields, interfaces, interface method sets, sentinel errors, typed errors, module path, package import path, and minimum Go version as contracts;
    - assume exported symbols in a v1+ module are public API unless the package is internal or local evidence proves otherwise;
    - do not remove, rename, or change exported signatures, exported field types, exported interface methods, or observable error behavior without an explicit breaking-change plan;
-   - adding a method to an exported interface is breaking for external implementations even when adding a method to a concrete type would be safe.
+   - adding a method to an exported interface is breaking for external implementations even when adding a method to a concrete type would be safe;
+   - changing exported struct fields or JSON tags can be an API change even when function signatures stay stable.
 6. Preserve error contracts:
    - use `errors.Is` and `errors.As` semantics as observable API when documented or already tested;
    - do not compare error strings;
+   - do not rely on `err == sentinel` when callers may receive wrapped errors;
    - do not expose dependency sentinel or typed errors through wrapping unless the package intentionally supports them as API;
    - treat a change between observable wrapping and non-observable formatting as API-sensitive;
+   - classify context cancellation, context deadlines, dependency timeouts, and domain failures at package boundaries instead of letting infrastructure errors leak upward unchanged;
+   - keep typed error pointer/value behavior consistent and avoid typed-nil errors behind an `error` interface;
+   - use `errors.Join` or multiple `%w` only when callers are expected to use `errors.Is` or `errors.As` rather than simple unwrap behavior;
    - use `errors.AsType` only when the supported Go version allows it and the shorter form preserves the same typed-error contract;
    - add tests for documented sentinel or typed errors when the error behavior changes.
-7. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, close responsibility, and test synchronization.
+7. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, panic policy, close responsibility, backpressure boundary, and test synchronization.
 8. Choose the right goroutine primitive:
    - use `sync.WaitGroup.Go` only for tasks that do not return errors and must not panic;
+   - call manual `WaitGroup.Add` before starting the goroutine and do not copy a `WaitGroup` after first use;
    - use an errgroup-style boundary when work needs error propagation, context cancellation, or concurrency limits;
    - do not hand-roll `WaitGroup` plus error channel plus cancellation plus semaphore unless the local code already owns that exact pattern and tests cover it;
    - treat buffered-channel semaphores as semantic backpressure, not just a performance knob; changing capacity can change ordering and pressure;
+   - do not treat a channel as a data-race shield for maps, slices, pointers, or structs still shared across goroutines;
    - treat `TryLock` as suspicious unless skipping the work is genuinely correct and observable.
 9. Reject fire-and-forget goroutines unless they are owned by a long-lived object with a shutdown path, joined before return, managed by a group with a wait path, or explicitly documented as safely detached.
 10. Preserve context propagation:
    - request-scoped functions accept `ctx` first and pass it down;
    - do not store request context in structs;
+   - do not use `context.Value` as dependency injection, optional parameters, or a hidden configuration bag;
    - do not pass nil context;
    - do not introduce `context.Background()` inside request or operation depth unless it is a true process root with a documented owner;
    - derived contexts must release their cancel function on every path;
@@ -124,11 +142,20 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
    - the sender that knows all sends are complete closes the channel;
    - receivers do not close borrowed input channels;
    - multiple senders require a coordinator that closes only after all senders finish;
-   - cancellable pipelines must avoid permanently blocking upstream goroutines when downstream stops early.
+   - cancellable pipelines must avoid permanently blocking upstream goroutines when downstream stops early;
+   - buffered channels are not durable queues and must not hide unbounded producer or retry behavior;
+   - avoid busy-loop `select` statements with a `default` branch unless skipping work immediately is the intended behavior and CPU impact is bounded.
 12. Use iterator functions only for pull-style traversal, not hidden concurrency. Honor the `yield` return value immediately, call the `stop` function from pull iterators, keep resource ownership visible, and keep channels for actual concurrent communication or backpressure.
 13. Keep timeout policy at request, command, API, or operation boundaries. Do not hide arbitrary sleeps or timeouts in reusable helpers unless that helper explicitly owns the policy.
 14. Check HTTP and proxy defaults:
-   - set deliberate `http.Client` and `http.Server` timeouts for network-facing code; zero timeout means no limit in important cases;
+   - use an explicit `http.Server` for production-facing servers rather than bare convenience helpers;
+   - set deliberate `ReadHeaderTimeout`, request/body read policy, `WriteTimeout`, `IdleTimeout`, `MaxHeaderBytes`, `BaseContext`, `ConnState`, and `ErrorLog` where the server owns those behaviors; zero timeout means no limit in important cases;
+   - protect request bodies separately from headers with size limits and route-appropriate read deadlines;
+   - treat `WriteTimeout` carefully for SSE, long polling, chunked streaming, and large downloads; streaming paths need heartbeat, flush, per-write deadline, and disconnect behavior instead of a single short global timeout;
+   - do not treat `http.TimeoutHandler` as cancellation of the underlying business work; pass `r.Context()` through database, RPC, cache, queue, and outbound HTTP calls;
+   - do not use `ResponseWriter` or request bodies after `ServeHTTP` returns; background work must copy the needed payload and use a lifecycle context that is not the finished request context;
+   - design graceful shutdown as a state transition: drain readiness, stop new traffic, wait for `Shutdown`, fall back to `Close` only after the shutdown budget, and keep the main goroutine alive until shutdown completes;
+   - track WebSocket, hijacked, upgraded, or long-lived connections separately because ordinary `Shutdown` does not wait for them;
    - reuse clients and transports instead of creating them per request;
    - prefer reverse-proxy rewrite hooks over deprecated or unsafe director-style mutation when the supported Go version allows it;
    - keep hop-by-hop header, forwarded-host, scheme, cancellation, streaming, and error-mapping behavior explicit.
@@ -147,18 +174,30 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
    - use PGO only with representative profiles and keep `default.pgo` ownership clear;
    - treat goroutine leak profiling, SIMD, JSON v2, and other experiments as opt-in evidence-gathering, not default production assumptions;
    - remember that `-race` only finds races on executed paths and carries significant overhead.
-18. Keep tests and benchmarks deterministic:
+18. For performance changes, measure before simplifying or optimizing:
+   - require profile or benchmark evidence before accepting a more complex hot-path change;
+   - inspect CPU, heap, allocation, goroutine, block, and mutex evidence according to the symptom instead of assuming CPU is the bottleneck;
+   - treat allocation reduction as GC-pressure reduction only when benchmark or profile evidence supports it;
+   - use escape-analysis findings to explain heap movement instead of assuming pointers are faster than values;
+   - use `sync.Pool` only for disposable temporary objects that may vanish at any time, not as a durable cache or lifecycle owner.
+19. Keep tests and benchmarks deterministic:
    - do not use elapsed real time to wait for goroutine progress; use explicit synchronization, owned lifecycle waits, fake time, `testing/synctest` when supported, or the repository's established concurrency test helper;
    - prefer `testing.B.Loop` for new benchmarks when the supported Go version allows it, and keep setup, cleanup, allocation measurement, and compiler optimization boundaries honest;
+   - compare benchmark changes across repeated runs and include `B/op` and `allocs/op` when allocation behavior is part of the claim;
    - use test artifact directories for files that should survive a test run only when the supported Go version and test invocation preserve artifacts; otherwise use the repository's existing temporary-file or golden-output policy;
    - for deterministic crypto tests, prefer the standard cryptographic test hook when the supported Go version provides it instead of overriding global readers in production code paths.
-19. Keep Go tools and modernization explicit:
+20. Keep Go tools and modernization explicit:
    - prefer the `tool` directive over `tools.go` pinning only when the repository's supported Go version allows it;
    - use `go fix` modernizers as reviewed migrations, not silent drive-by rewrites;
    - update code generators, schema generators, lint helpers, and reflection-heavy tooling for generic aliases, alias node behavior, and reflect iterator methods only with fixture coverage;
    - prefer standard-library helpers such as `min`, `max`, `clear`, `slices`, `maps`, and `cmp` over new local utility packages when the supported Go version allows them.
-20. If dependency metadata changes, keep module files and dependent tests synchronized. Do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact.
-21. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
+21. If dependency metadata changes, keep module files and dependent tests synchronized:
+   - do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact;
+   - treat `go.sum` as checksum evidence, not a package lockfile and not disposable noise;
+   - treat `replace`, especially local-path `replace`, as temporary main-module or workspace-only wiring unless the repository documents a release plan for it;
+   - verify vendor output is regenerated by a configured intent when vendoring is part of the repository contract;
+   - check private module settings before adding private import paths so module names do not leak through public proxy or checksum lookups.
+22. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -166,7 +205,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - Package ownership and exported API impact are clear.
 - Context, goroutine, channel, and error ownership are explicit.
 - Go-version-gated syntax, standard-library APIs, runtime defaults, experiments, and module metadata are compatible with the repository's supported Go version.
-- HTTP timeout, proxy, JSON, filesystem, network address, runtime, test-time, benchmark, and tool decisions are explicit where touched.
+- HTTP timeout, graceful shutdown, proxy, JSON, filesystem, network address, runtime, profiling, test-time, benchmark, and tool decisions are explicit where touched.
 - Tests cover the changed behavior without sleeps as synchronization.
 - Module drift is reported when dependency verification cannot run.
 
@@ -206,7 +245,7 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - Boundary checked
 - Package and API impact
 - Context/concurrency/error notes
-- Go version, runtime, HTTP, JSON, filesystem, benchmark, and tool notes when relevant
+- Go version, module/workspace, runtime, HTTP/shutdown, JSON, filesystem, profiling, benchmark, and tool notes when relevant
 - Files changed
 - Command intents run
 - Skipped checks and reasons