mustflow 2.26.0 → 2.28.0

package/README.md

@@ -307,9 +307,9 @@ Runnable work is declared in `.mustflow/config/commands.toml` so agents do not g
 - `run_policy = "agent_allowed"`
 - `stdin = "closed"`
 
-Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly. `mf run` also rejects obvious long-running `argv` shapes, such as shell-wrapper background payloads, interpreter loops, package-manager development scripts, watchers, and development servers declared as one-shot commands.
+Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly. `mf run` also rejects obvious long-running `argv` shapes, such as shell-wrapper background payloads, interpreter loops, package-manager development scripts, watchers, and development servers declared as one-shot commands. If a bounded one-shot command has a name that matches a common long-running pattern, the intent can explicitly acknowledge that with `allow_long_running_command_patterns = true`; background shell patterns remain blocked.
 
-Command environments remove the project-local `node_modules/.bin` path from `PATH` by default. If an intent needs a project dependency binary such as `eslint`, `tsc`, or `vitest`, declare it through the package manager, for example `npm exec eslint -- ...`, `pnpm exec tsc -- --noEmit`, `bun x eslint ...`, or `yarn exec eslint ...`. `mf check --strict` warns when an agent-runnable intent uses a bare executable name that appears under the project-local `.bin` directory.
+Command environments remove the project-local `node_modules/.bin` path from `PATH` by default. If an intent needs a project dependency binary such as `eslint`, `tsc`, or `vitest`, declare it through the package manager, for example `npm exec eslint -- ...`, `pnpm exec tsc -- --noEmit`, `bun x eslint ...`, or `yarn exec eslint ...`. `mf check --strict` warns when an agent-runnable intent uses a bare executable name that appears under the project-local `.bin` directory, except for names listed in `defaults.allow_project_local_bin_bare_executables`. `mf run` may resolve those allowed names directly from the local `.bin` directory without exposing every local binary through `PATH`. The installed template allows `mf` and `mustflow` by default. Intent-level `allow_env_inheritance_risks = true` is available when a command intentionally uses `env_policy = "inherit"`.
 
 Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents, command eligibility, remaining gaps, and missing runnable coverage without executing commands. Use `mf run <intent> --dry-run --json` to inspect one resolved command intent without spawning a process or writing a run receipt. Plan-only verification includes a `decision_graph` that connects changed surfaces, classification reasons, command candidates, eligibility checks, effects, and gaps. When `.mustflow/cache/mustflow.sqlite` is fresh, scheduled entries also include read-only `effectGraph` metadata for write locks and lock conflicts. These graph rows are marked `explanation_only` and never grant command authority; `.mustflow/config/commands.toml` remains the only runnable command source.
 

package/dist/cli/lib/run-plan.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { isMustflowBinName } from '../../core/command-classification.js';
 import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
-import { resolveCommandEnv } from '../../core/command-env.js';
+import { readProjectLocalBinBareExecutableAllowlist, resolveAllowedProjectLocalBinExecutable, resolveCommandEnv, } from '../../core/command-env.js';
 import { getCommandMaxOutputBytesLimitDetail, readEffectiveCommandCwd, readEffectiveCommandMaxOutputBytes, } from '../../core/command-run-constraints.js';
 import { evaluateCommandIntentEligibility, } from '../../core/command-intent-eligibility.js';
 import { inspectActiveRunLocks, } from '../../core/active-run-locks.js';
@@ -56,7 +56,7 @@ function resolveCurrentCliEntrypoint() {
     const entrypoint = process.argv[1];
     return entrypoint ? path.resolve(entrypoint) : undefined;
 }
-function resolveArgvCommand(intent, commandArgv) {
+function resolveArgvCommand(projectRoot, contract, intent, commandArgv) {
     const [command = '', ...args] = commandArgv;
     if (isMustflowBuiltinIntent(intent) && isMustflowBinName(command)) {
         const entrypoint = resolveCurrentCliEntrypoint();
@@ -68,6 +68,14 @@ function resolveArgvCommand(intent, commandArgv) {
             };
         }
     }
+    const localBinExecutable = resolveAllowedProjectLocalBinExecutable(projectRoot, command, readProjectLocalBinBareExecutableAllowlist(contract));
+    if (localBinExecutable) {
+        return {
+            executable: localBinExecutable,
+            args,
+            shell: shouldUseShellForArgvExecutable(localBinExecutable),
+        };
+    }
     return {
         executable: command,
         args,
@@ -212,7 +220,7 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         commandArgv,
         shellCommand: metadata.shellCommand,
         mode: metadata.mode,
-        argvCommand: commandArgv ? resolveArgvCommand(rawIntent, commandArgv) : undefined,
+        argvCommand: commandArgv ? resolveArgvCommand(projectRoot, contract, rawIntent, commandArgv) : undefined,
         writes: metadata.writes,
         effects: metadata.effects,
         network: metadata.network,

package/dist/core/command-contract-validation.js

@@ -1,7 +1,6 @@
-import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readStringArray, } from './config-loading.js';
-import { COMMAND_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY } from './command-env.js';
+import { COMMAND_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, normalizeCommandExecutableName, readProjectLocalBinBareExecutableAllowlist, resolveAllowedProjectLocalBinExecutable, } from './command-env.js';
 import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
 import { COMMAND_PRECONDITION_KINDS } from './command-preconditions.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
@@ -13,6 +12,8 @@ const COMMAND_ARGV_PLACEHOLDER_PATTERN = /^\{([a-z][a-z0-9_]*)\}$/u;
 const COMMAND_ARGV_MIXED_PLACEHOLDER_PATTERN = /\{([a-z][a-z0-9_]*)\}/u;
 const WINDOWS_RESERVED_PATH_SEGMENTS = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
 const SAFE_PATH_EXTENSION_PATTERN = /^\.[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const ALLOW_ENV_INHERITANCE_RISKS_KEY = 'allow_env_inheritance_risks';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function commandContractIssue(message, id) {
     return id ? { id, message } : { message };
 }
@@ -257,6 +258,7 @@ function validateCommandDefaults(commandsToml, issues) {
     validateStringField(defaults, 'on_timeout', '[commands.defaults].on_timeout', issues);
     validateAllowedStringField(defaults, 'env_policy', '[commands.defaults].env_policy', COMMAND_ENV_POLICIES, issues);
     validateStringArrayField(defaults, 'env_allowlist', '[commands.defaults].env_allowlist', issues);
+    validateStringArrayField(defaults, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, `[commands.defaults].${PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY}`, issues);
     validatePositiveIntegerField(defaults, 'default_timeout_seconds', '[commands.defaults].default_timeout_seconds', issues);
     validateMaxOutputBytesField(defaults, 'max_output_bytes', '[commands.defaults].max_output_bytes', issues);
     validatePositiveIntegerField(defaults, 'kill_after_seconds', '[commands.defaults].kill_after_seconds', issues);
@@ -337,6 +339,8 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
     validateBooleanField(intent, 'allow_shell', `[commands.intents.${intentName}].allow_shell`, issues);
     validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
+    validateBooleanField(intent, ALLOW_ENV_INHERITANCE_RISKS_KEY, `[commands.intents.${intentName}].${ALLOW_ENV_INHERITANCE_RISKS_KEY}`, issues);
+    validateBooleanField(intent, ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY, `[commands.intents.${intentName}].${ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY}`, issues);
     validateMaxOutputBytesField(intent, 'max_output_bytes', `[commands.intents.${intentName}].max_output_bytes`, issues);
     validatePositiveIntegerField(intent, 'kill_after_seconds', `[commands.intents.${intentName}].kill_after_seconds`, issues);
     validateCommandIntentSelection(intentName, intent, issues);
@@ -375,7 +379,7 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`, 'mustflow.command_contract.shell_background_pattern'));
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && intent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`, 'mustflow.command_contract.long_running_command_pattern'));
     }
     if (hasOwn(intent, 'success_exit_codes')) {
@@ -419,6 +423,9 @@ export function findCommandEnvInheritanceWarnings(commandsToml) {
         if (envPolicy.policy !== 'inherit') {
             continue;
         }
+        if (intent[ALLOW_ENV_INHERITANCE_RISKS_KEY] === true) {
+            continue;
+        }
         const reasons = readCommandEnvInheritanceRiskReasons(intent);
         warnings.push({
             intentName,
@@ -465,21 +472,14 @@ function validateCommandEnvInheritanceWarnings(commandsToml) {
     return issues;
 }
 function projectLocalBinExecutableExists(projectRoot, executable) {
-    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
-    const executableName = path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '');
-    const candidates = [
-        executableName,
-        `${executableName}.cmd`,
-        `${executableName}.exe`,
-        `${executableName}.ps1`,
-    ];
-    return candidates.some((candidate) => existsSync(path.join(localBinPath, candidate)));
+    return resolveAllowedProjectLocalBinExecutable(projectRoot, executable, new Set([normalizeCommandExecutableName(executable)])) !== null;
 }
 function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
     const issues = [];
     if (!isRecord(commandsToml?.intents)) {
         return issues;
     }
+    const allowedBareExecutables = readProjectLocalBinBareExecutableAllowlist(commandsToml);
     for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
         if (!isRecord(intent)) {
             continue;
@@ -492,6 +492,9 @@ function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
         if (!executable || executable.includes('/') || executable.includes('\\')) {
             continue;
         }
+        if (allowedBareExecutables.has(normalizeCommandExecutableName(executable))) {
+            continue;
+        }
         if (!projectLocalBinExecutableExists(projectRoot, executable)) {
             continue;
         }

package/dist/core/command-env.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { readString, readStringArray } from './config-loading.js';
 export const COMMAND_ENV_POLICIES = new Set(['inherit', 'minimal', 'allowlist']);
@@ -25,6 +26,8 @@ const BASE_MINIMAL_ENV_KEYS = [
     'WINDIR',
     'windir',
 ];
+export const PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY = 'allow_project_local_bin_bare_executables';
+export const DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST = new Set(['mf', 'mustflow']);
 function getPathEnvKey(env) {
     return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
 }
@@ -48,6 +51,46 @@ function readEnvPolicy(table) {
 function readEnvAllowlist(table) {
     return table ? (readStringArray(table, 'env_allowlist') ?? []) : [];
 }
+export function normalizeCommandExecutableName(executable) {
+    return path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '').toLowerCase();
+}
+export function readProjectLocalBinBareExecutableAllowlist(contractOrCommands) {
+    const defaults = contractOrCommands && typeof contractOrCommands === 'object' && 'defaults' in contractOrCommands
+        ? contractOrCommands.defaults
+        : undefined;
+    const configuredAllowlist = defaults && typeof defaults === 'object'
+        ? defaults[PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY]
+        : undefined;
+    if (!Array.isArray(configuredAllowlist)) {
+        return DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST;
+    }
+    return new Set(configuredAllowlist
+        .filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+        .map((entry) => normalizeCommandExecutableName(entry)));
+}
+export function resolveAllowedProjectLocalBinExecutable(projectRoot, executable, allowlist) {
+    if (executable.includes('/') || executable.includes('\\')) {
+        return null;
+    }
+    const executableName = normalizeCommandExecutableName(executable);
+    if (!allowlist.has(executableName)) {
+        return null;
+    }
+    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
+    const candidates = [
+        executableName,
+        `${executableName}.cmd`,
+        `${executableName}.exe`,
+        `${executableName}.ps1`,
+    ];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(localBinPath, candidate);
+        if (existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
 function pickEnv(source, names) {
     const output = {};
     for (const name of names) {

package/dist/core/command-intent-eligibility.js

@@ -1,5 +1,6 @@
 import { isRecord, readString } from './config-loading.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 export const COMMAND_INTENT_INELIGIBILITY_CODES = [
     'intent_not_table',
     'status_not_configured',
@@ -83,7 +84,7 @@ export function evaluateCommandIntentEligibility(intentName, rawIntent) {
             detail: blockedPattern.detail,
         };
     }
-    if (blockedPattern?.code === 'long_running_command_pattern') {
+    if (blockedPattern?.code === 'long_running_command_pattern' && rawIntent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         return {
             ok: false,
             code: 'blocked_long_running_command_pattern',

package/dist/core/contract-lint.js

@@ -58,6 +58,7 @@ const AGENT_WORKFLOW_PATH = '.mustflow/docs/agent-workflow.md';
 const PACKAGE_SCRIPT_RUNNERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
 const MAKEFILE_CANDIDATES = ['Makefile', 'makefile'];
 const JUSTFILE_CANDIDATES = ['justfile', 'Justfile'];
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -333,7 +334,7 @@ function lintIntent(name, value, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         pushIssue(issues, 'error', 'shell_background_pattern', name, `Shell intent ${name} contains a blocked long-running or background pattern.`);
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && value[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         pushIssue(issues, 'error', 'long_running_command_pattern', name, `Intent ${name} contains a blocked long-running or background command pattern.`);
     }
     if (!successExitCodesAreValid(value)) {

package/package.json

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

package/schemas/commands.schema.json

@@ -36,7 +36,8 @@
         "on_timeout": { "type": "string" },
         "kill_after_seconds": { "type": "integer" },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
-        "env_allowlist": { "$ref": "#/$defs/stringArray" }
+        "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_project_local_bin_bare_executables": { "$ref": "#/$defs/stringArray" }
       }
     },
     "intents": {
@@ -172,6 +173,7 @@
         },
         "cmd": { "type": "string" },
         "allow_shell": { "type": "boolean" },
+        "allow_long_running_command_patterns": { "type": "boolean" },
         "cwd": { "type": "string" },
         "timeout_seconds": { "type": "integer" },
         "kill_after_seconds": { "type": "integer" },
@@ -185,6 +187,7 @@
         },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
         "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_env_inheritance_risks": { "type": "boolean" },
         "manual_start_hint": { "type": "string" },
         "health_check_url": { "type": "string" },
         "stop_instruction": { "type": "string" },

package/templates/default/common/.mustflow/config/commands.toml

@@ -18,6 +18,7 @@ on_timeout = "terminate_process_tree"
 kill_after_seconds = 5
 env_policy = "minimal"
 env_allowlist = []
+allow_project_local_bin_bare_executables = ["mf", "mustflow"]
 
 [resources.local_index_cache]
 description = "Generated mustflow SQLite local index under .mustflow/cache/."

package/templates/default/i18n.toml

@@ -56,7 +56,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 88
+revision = 89
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -209,6 +209,12 @@ source_locale = "en"
 revision = 2
 translations = {}
 
+[documents."skill.docker-code-change"]
+source = "locales/en/.mustflow/skills/docker-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.elysia-code-change"]
 source = "locales/en/.mustflow/skills/elysia-code-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: 88
+revision: 89
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -103,6 +103,7 @@ routes. Event routes stay inactive until their event occurs.
 | C++ source, headers, modules, native build metadata, toolchains, package managers, public headers, shared or static libraries, ABI surfaces, generated bindings, FFI, tests, or benchmarks are created or changed | `.mustflow/skills/cpp-code-change/SKILL.md` | Owning target, compilation identity, build front door, changed consumed surface, public API/ABI/FFI/binding surfaces, ownership and lifetime contracts, and command contract entries | C++ source, headers, modules, build metadata, package metadata, generated bindings, FFI code, tests, benchmarks, and directly synchronized docs | target drift, source API break, binary ABI break, undefined behavior, lifetime bug, build-graph drift, generated-binding drift, FFI memory bug, unverified modern C++ feature, or false performance claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Owning target, compilation identity, highest compatibility risk, ownership/lifetime/UB/concurrency notes, public API/ABI/FFI/binding impact, verification, and remaining C++ risk |
 | 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 package manager behavior, `bun.lock`, `bunfig.toml`, Bun test runner behavior, Bun bundling, Bun TypeScript execution, 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, native dependency signals, and command contract entries | Bun runtime code, Bun package manager metadata, lockfiles, `bunfig.toml`, scripts, tests, bundler config, TypeScript/declaration pipeline, 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, Node compatibility break, shebang mismatch, 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 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, or TypeScript tests are created or changed | `.mustflow/skills/typescript-code-change/SKILL.md` | TypeScript config, package entry metadata, target runtime, changed files, and command contract entries | TypeScript source, declarations, compiler config, exports, tests, and directly synchronized docs | weakened type safety, module drift, public API drift, or unverified declaration output | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, module, type, and public API 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 |

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

@@ -0,0 +1,262 @@
+---
+mustflow_doc: skill.docker-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: docker-code-change
+description: Apply this skill when Dockerfiles, .dockerignore files, Docker Compose files, BuildKit or buildx behavior, container image metadata, image tags, container entrypoints, health checks, Docker-based CI workflows, image security scanning, SBOM or provenance settings, registry publishing, or container runtime validation are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.docker-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Docker Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent container image accidents by preserving reproducibility, secret safety, cache behavior,
+runtime correctness, development and production separation, and supply-chain evidence.
+
+This skill is not a Docker syntax guide. It is a safety procedure for changing Docker-based
+application images and local container workflows without silently weakening build, runtime, CI,
+or security contracts.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `Dockerfile`, `Dockerfile.*`, `.dockerignore`, `compose.yaml`, `compose.yml`,
+  `docker-compose*.yml`, or Compose override files are created or changed.
+- Base images, image tags, digest pinning, package-manager install layers, build contexts,
+  multi-stage boundaries, `ENTRYPOINT`, `CMD`, `USER`, `HEALTHCHECK`, `EXPOSE`, labels,
+  environment variables, or build arguments change.
+- BuildKit, buildx, build targets, cache mounts, external cache, multi-platform image builds,
+  Docker-based CI workflows, image publish behavior, registry tags, SBOM, provenance,
+  signing, or image vulnerability scanning changes.
+- Local development Compose services such as databases, Redis, queues, object stores,
+  mail capture, optional debug tools, profiles, volumes, networks, env files, init scripts,
+  or migration jobs change.
+- A language-specific runtime skill mentions Docker base images, native dependency image
+  behavior, container deployment support, or Docker runtime declarations.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes application code that happens to run inside an unchanged container;
+  use the matching language or framework skill.
+- The task only changes generic environment variables, secrets, or deployment settings
+  outside Docker or Compose; use `config-env-change` or the narrower deployment skill.
+- The task designs Kubernetes, ECS, Cloud Run, Nomad, service mesh, registry administration,
+  autoscaling, backup, ingress, TLS, or cloud platform resources beyond verifying that an
+  image is deployable.
+- The task only addresses shell process execution or filesystem path handling outside
+  container files; use `process-execution-safety`, `file-path-cross-platform-change`, or
+  `cross-platform-filesystem-safety`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Container surfaces: Dockerfiles, `.dockerignore`, Compose files, CI workflow files,
+  build scripts or command-contract entries, release workflow files, and registry metadata
+  touched by the change.
+- Project classification: runtime-source app, compiled artifact app, JVM artifact app,
+  static frontend, multi-service app, or mixed image set, with language examples such as
+  Node, Bun, Python, PHP, Go, Rust, C++, and Java.
+- Base image and platform signals: image names, tags, digests, OS family, libc expectations,
+  CPU architecture, native dependencies, required CA certificates, time zone, shell, package
+  manager, and runtime user needs.
+- Build and cache signals: build context, `.dockerignore`, lockfiles, package-manager cache
+  paths, BuildKit mount needs, stage names, build targets, external cache ownership, and
+  CI event or branch conditions.
+- Runtime contract: `USER`, file ownership, writable paths, `ENTRYPOINT`, `CMD`, signal
+  handling, health checks, ports, logs, config injection, read-only filesystem expectations,
+  volumes, and smoke-test path.
+- Security and supply-chain contract: secrets, SSH keys, private registry tokens, Docker socket
+  access, privileged mode, host namespace or host path access, capabilities, security options,
+  vulnerability scan gate, SBOM, provenance, signing, and digest reporting.
+- Configured command intents that can validate syntax, build output, tests, docs, release
+  packaging, and mustflow workflow alignment. Report missing Docker-specific verification
+  intents instead of inventing raw Docker commands.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Classify whether the change affects local development only, CI validation, release images,
+  registry publishing, or deployable runtime behavior before editing.
+- Do not optimize a Dockerfile by blindly minimizing line count or image size. Preserve
+  reproducibility, secret safety, cache behavior, runtime correctness, and dev/prod separation
+  first.
+- Treat Dockerfiles, Compose files, and Docker CI workflows as security-sensitive when they
+  can alter credentials, registry writes, host access, runtime privileges, or supply-chain
+  attestations.
+- Do not assume Docker, buildx, Compose, Scout, Trivy, Grype, or registry credentials are
+  available unless the repository exposes a configured one-shot command intent or the user
+  explicitly accepts an unverified manual path.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update Dockerfiles, `.dockerignore`, Compose files, container-related CI workflow snippets,
+  image metadata, package tests, docs examples, template metadata, and directly synchronized
+  skill routes required by the container contract.
+- Add or tighten non-root runtime users, stage names, `.dockerignore` exclusions, cache-safe
+  copy order, BuildKit secret or cache requirements, health checks, labels, and Compose local
+  dependency wiring when the current project evidence supports the change.
+- Add focused tests or assertions only when they encode the changed container, template,
+  package, or workflow contract.
+- Do not add broad deployment platform design, registry administration, long-running server
+  instructions, raw publish commands, credential material, or command permission to a skill
+  document.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the changed surface: Dockerfile, `.dockerignore`, Compose, CI build workflow,
+   image publish workflow, image metadata, security scan, SBOM/provenance, or runtime smoke
+   path. If several surfaces changed, name the source of truth for each.
+2. Classify the image shape before choosing structure:
+   - Runtime-source apps keep source plus production runtime dependencies.
+   - Compiled artifact apps should usually copy only the binary and required runtime files.
+   - JVM artifact apps should build with a JDK and run with a JRE or equivalent runtime image.
+   - Static frontends should copy only built assets into the serving image when applicable.
+3. Choose base images deliberately. Prefer trusted versioned images over mutable `latest`.
+   Use Debian slim as a conservative default for native dependency compatibility; use Alpine
+   only after libc and native package behavior are verified; use distroless or `scratch` only
+   when CA certificates, time zone, passwd or non-root identity, shell absence, and debugging
+   tradeoffs are explicit.
+4. Treat digest pinning as a reproducibility choice with an update obligation. If a production
+   sample pins a digest, also report the need for an update mechanism such as dependency update
+   automation, base-image rebuild checks, or a scanner policy.
+5. Preserve build cache boundaries. Keep build context small, copy dependency manifests and
+   lockfiles before application source, avoid copying host dependency directories, and keep
+   package-manager caches out of final images. Do not move `COPY . .` above dependency install
+   layers unless the project has no cache-sensitive dependency step.
+6. Check `.dockerignore` whenever build context changes. Exclude VCS metadata, local dependency
+   directories, virtual environments, build output, coverage, caches, local databases, `.env`,
+   credential files, keys, and other files not required by the build.
+7. Use multi-stage boundaries only when they buy cache, artifact, security, or test-target value.
+   Name stages instead of relying on numeric indexes. Remove stages that merely rename the same
+   base without changing cache behavior, artifact flow, runtime base, or verification target.
+8. Ensure final images contain only runtime requirements. Do not leave compilers, package managers,
+   test fixtures, source maps, caches, `git`, `curl`, shell tools, or dev dependencies in final
+   images unless the runtime contract explicitly requires them.
+9. Handle secrets as a hard boundary. Do not put tokens, passwords, SSH keys, cloud credentials,
+   `.npmrc`, `.pypirc`, `.env`, or private registry credentials into `ARG`, `ENV`, labels,
+   image layers, build logs, copied files, or command history. Prefer BuildKit secret or SSH
+   mounts when a configured workflow supports them, and report missing secret-mount verification
+   when it does not.
+10. Preserve runtime correctness. Verify non-root user intent, file ownership, writable paths,
+   entrypoint and command shape, PID 1 signal handling, exposed and published ports, logs to
+   stdout or stderr, health check command availability, required environment variables, and
+   read-only filesystem expectations.
+11. Treat `USER` as a runtime proof obligation, not a text check. If the final image runs as
+   non-root, make sure copied files and runtime write paths are owned or writable by that user.
+   If that cannot be verified, report the missing run evidence.
+12. Keep Compose scoped. Use Compose for local development, integration tests, and narrow
+   production-like checks. Do not turn Compose into a full orchestrator design for TLS,
+   autoscaling, backups, ingress, secret rotation, or platform rollout strategy.
+13. For Compose dependencies, distinguish container start from service readiness. Prefer
+   health checks for databases and queues, app-level retry for runtime dependency loss, named
+   volumes for persistent local data, bind mounts for editable source, profiles for optional
+   tools, and one-shot migration services rather than hiding app migrations inside database
+   image entrypoints.
+14. Review Compose trust and host access. Treat `privileged`, Docker socket mounts, host
+   networking, host PID or IPC namespaces, broad host-path mounts, root users, broad port
+   binding, unconfined security profiles, and missing resource limits as high-risk changes
+   requiring explicit justification.
+15. For CI, separate test builds from publish builds. PR and fork events should not push images,
+   receive registry credentials, write production caches, sign artifacts, or use deployment
+   secrets. Release tags or protected default-branch jobs may publish only after the configured
+   verification path succeeds.
+16. Keep cache ownership safe in CI. Do not let untrusted PRs overwrite default-branch cache
+   refs. Use branch- or event-scoped cache references when the workflow supports external cache.
+   Report cache poisoning risk when the workflow writes shared caches from untrusted code.
+17. Keep image tags traceable. Use immutable commit or digest evidence for deployable artifacts.
+   Treat `latest` as a moving pointer, not a release identity. Release workflows should record
+   the pushed digest and update floating tags only from release or protected branch events.
+18. For release images, require SBOM and provenance when the configured workflow supports them.
+   Report when local-only image loads cannot carry registry attestations and when final published
+   digests were not rechecked after push.
+19. Choose verification through configured intents first. If Docker-specific syntax, build,
+   smoke, inspect, history, vulnerability scan, SBOM, provenance, multi-arch, or registry-pull
+   verification is needed but not configured, report the missing intent instead of running an
+   inferred command.
+20. When reporting completion, separate source edits, image-build evidence, runtime evidence,
+   security scan evidence, supply-chain evidence, registry evidence, and skipped checks. Do not
+   claim a container image is production-ready from source inspection or a successful build alone.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The image shape, base image choice, cache order, stage boundaries, and build context are
+  deliberate and aligned with the language or runtime contract.
+- Secrets are not introduced into Dockerfile instructions, Compose environment, image layers,
+  command history, logs, SBOM, or provenance metadata.
+- Final runtime images avoid root execution and unnecessary build tools unless explicitly justified.
+- Compose remains local or narrowly production-like, with host access and privileged settings
+  justified or rejected.
+- CI image builds separate test, cache, publish, tag, SBOM, provenance, and registry credentials
+  according to event trust.
+- Docker-specific verification evidence is recorded, or missing configured intents are reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Report missing Dockerfile lint, Compose config validation, buildx check, image build, container
+start, health or smoke test, image inspect, history secret scan, vulnerability scan, SBOM,
+provenance, multi-platform manifest, registry push, registry pull, or digest verification intents
+when those surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a build succeeds but runtime start, health, smoke, or non-root write behavior is unverified,
+  report the image as built but not runtime-verified.
+- If a secret appears in `ARG`, `ENV`, copied files, image history, logs, or attestation metadata,
+  remove the leak path before optimizing cache or image size.
+- If Alpine, distroless, or `scratch` breaks native dependencies, CA certificates, time zones,
+  shell availability, or non-root identity, restore a compatible runtime base or report the
+  missing runtime requirement.
+- If Compose uses Docker socket, privileged mode, host namespaces, broad host mounts, root users,
+  or broad port exposure without explicit justification, treat the change as unsafe.
+- If CI publish behavior is triggered from untrusted events, forks, or ordinary PRs, fail closed
+  by disabling push or credentials for that path and report the publish boundary.
+- If Docker-specific tools or registries are unavailable under the command contract, do not invent
+  manual commands; report the missing verification intent and remaining risk.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Docker surface classification
+- Image shape, base image, cache, and stage decisions
+- `.dockerignore`, secret, user, entrypoint, health, port, and runtime notes
+- Compose trust, volume, network, env, readiness, and migration notes
+- CI cache, tag, publish, SBOM, provenance, registry, and event-trust notes
+- Files changed
+- Command intents run
+- Skipped Docker-specific checks and reasons
+- Remaining Docker risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -132,6 +132,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
 
+[routes."docker-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "public_api_change", "test_change", "security_change", "package_metadata_change", "release_risk"]
+
 [routes."api-contract-change"]
 category = "general_code"
 route_type = "primary"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.26.0"
+version = "2.28.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -25,6 +25,7 @@ creates = [
   ".mustflow/skills/css-code-change/SKILL.md",
   ".mustflow/skills/cpp-code-change/SKILL.md",
   ".mustflow/skills/dart-code-change/SKILL.md",
+  ".mustflow/skills/docker-code-change/SKILL.md",
   ".mustflow/skills/elysia-code-change/SKILL.md",
   ".mustflow/skills/flutter-code-change/SKILL.md",
   ".mustflow/skills/go-code-change/SKILL.md",
@@ -135,6 +136,7 @@ minimal = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",
@@ -190,6 +192,7 @@ patterns = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",
@@ -256,6 +259,7 @@ oss = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",
@@ -335,6 +339,7 @@ team = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",
@@ -402,6 +407,7 @@ product = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",
@@ -474,6 +480,7 @@ library = [
   "css-code-change",
   "cpp-code-change",
   "dart-code-change",
+  "docker-code-change",
   "elysia-code-change",
   "flutter-code-change",
   "go-code-change",