Apply Dockerfile-specific judgment only when the task materially depends on a
Dockerfile. Establish task authority, repository policy, the selected
Dockerfile frontend and builder, target platforms, context, stage target, and
validation boundary before relying on instruction behavior. Use the highest
justified Green — routine, Yellow — caution, Orange — warning, or
Red — crisis / stop response for the current coherent decision.
Own parser directives, stages, Dockerfile instruction forms, argument and environment scope, build context and ignore rules, copies and additions, BuildKit mounts, cache consequences, file ownership, platform-specific Dockerfile behavior, generated image defaults, and Dockerfile-specific structural warnings. Preserve image selection, dependency policy, live operations, runtime orchestration, release policy, and external mutation authority with their existing owners.
Do not use this profile for:
This profile does not grant authority to perform a Docker operation.
syntax, escape,
and version-supported check behavior; do not infer support from spelling.FROM starts a stage. Record stage names,
inheritance, base references, requested platform, project-selected target,
and every COPY --from or mount source. A global ARG may parameterize
FROM but remains outside ordinary stage scope and must be redeclared
inside a stage before later stage instructions consume it.ARG and ENV declaration, scope, inheritance, persistence, and use.
Distinguish shell form from exec form: exec form supplies a JSON argument
vector without implicit shell expansion, while shell form uses the selected
platform shell. SHELL changes later shell-form RUN, CMD, and
ENTRYPOINT behavior. When the chosen shell’s quoting, pipeline, trap, or
process semantics are independently material, pair
bash-language-profile or the applicable language profile rather than
duplicating it here..dockerignore, and any Dockerfile-specific ignore file. A
Dockerfile-specific ignore file takes precedence over the root ignore file;
within the applicable rules, the final matching rule wins. Confirm that
intended sources remain available and that protected or unrelated material
is absent from builder inputs or explicitly governed. The Dockerfile and
applicable ignore file remain builder inputs even when ignore rules exclude
them, although they cannot then be copied or bind-mounted from the ordinary
context. Local-context source paths in COPY and ADD cannot escape the
context root. Remote ADD, named contexts, images, and COPY --from stages
use separately governed roots and trust boundaries.COPY when it completely expresses a local, named-context, image, or
stage-owned transfer. Treat remote ADD, Git sources, and automatic local
archive extraction as materially broader behavior. Require project
authority, source immutability or update policy, verification, ownership,
mode, platform support, and rollback; do not rewrite automatically.RUN --mount by type, source, target, identity, ownership,
sharing, lifetime, output path, and fallback. Bind writes are not ordinary
output layers, cache contents are not correctness guarantees, tmpfs is
transient, and secret or SSH mounts create temporary access boundaries. A
secret mount does not prove the command avoided copying, printing,
transforming, persisting, or exporting the value.COPY, ADD, and bind-mounted
sources use metadata checksums that exclude modification time. An ordinary
RUN cache match does not inspect changed external package state or files
created inside the prior result. A secret value does not participate in the
cache key, although secret identity and target properties can. Require a
project-owned invalidation and clean-build path where correctness depends on
mutable inputs or caches.WORKDIR chaining,
source metadata, COPY or ADD ownership and mode, platform support,
USER transitions, build-time effective user, final image user, and
permission requirements. Do not infer final non-root behavior from an
intermediate stage or from copied artifacts.EXPOSE, VOLUME, STOPSIGNAL, HEALTHCHECK,
ENTRYPOINT, CMD, ONBUILD, labels, environment, working directory,
and user configuration. Establish forms, override behavior, signal
forwarding, health status and output, volume initialization and mutation,
and deferred downstream triggers. Runtime and orchestrator policy can
replace or merge defaults and remains project-owned.implementing-with-test-discipline primary; acceptance can keep
reviewing-and-verifying-repository-work primary. This profile adds only
materially Dockerfile-specific judgment.These defaults apply mainly to maintained hand-written Dockerfiles. They are guidance signals, not Docker policy, architecture selection, base-image selection, linter output, automatic enforcement, or build authority.
| Signal | Green — routine | Yellow — caution | Orange — warning | Red — crisis / stop |
|---|---|---|---|---|
| Physical lines per Dockerfile | <= 150 |
151–300 |
301–500 |
>= 501 |
| Logical Dockerfile instructions | <= 20 |
21–40 |
41–70 |
>= 71 |
| Build stages | 1–3 |
4–6 |
7–10 |
>= 11 |
Commands in one shell-form RUN |
<= 5 |
6–10 |
11–20 |
>= 21 |
Distinct ARG and ENV names |
<= 6 |
7–12 |
13–20 |
>= 21 |
Distinct COPY and ADD source domains |
0–2 |
3–4 |
5–7 |
>= 8 |
| Bind, cache, tmpfs, secret, or SSH mount families | 0–1 |
2–3 |
4–6 |
>= 7 |
| Instructions executing as root after the last explicit user transition | 0–2 |
3–5 |
6–10 |
>= 11 |
| Platform-conditional behavior families | 0–1 |
2–3 |
4–6 |
>= 7 |
| Independent responsibility families | 1 |
2 |
3 |
>= 4 |
Count physical lines after universal-newline decoding. Blank lines, comments, parser directives, continuations, heredoc delimiters, and heredoc payload count. A continued instruction counts once; directives, comments, and blank lines do not count as logical instructions.
Count commands within shell-form RUN only when the selected interpreter and
complete static text can be parsed truthfully. Count independently sequenced,
conditional, subshell, and pipeline responsibility families rather than raw
tokens. If heredoc, interpolation, generated text, or an unknown interpreter
prevents a truthful consequential bound, classify the unknown as Orange;
representing it as verified is Red.
Count each distinct ARG and ENV name once while mapping scope separately.
Count independently governed source domains: local context family, named
context, named stage, external image, remote URL, Git source, local
archive-extraction family, and inline heredoc. A heredoc-backed COPY is one
instruction and one inline-source domain. Count each ONBUILD registration
once and also disclose its downstream responsibility.
Count mount families by independently governed contents, sharing, lifetime,
and purpose, not repeated syntax. For the root-execution signal, resolve the
selected target and stages statically reachable through inheritance,
COPY --from, or a stage-backed mount. Each FROM resets user state to its
base configuration. Count stage-local RUN instructions executed with
effective root identity after the latest stage-local USER transition,
starting from verified base-image user state. Measure each reachable stage
separately and use the maximum; do not sum stages. A final-stage non-root
transition cannot erase root work in a reachable build stage. If no target is
selected, measure each statically selectable maintained target and use the
maximum. Report maintained unreachable stages separately. An unknown
consequential base user, target, or reachability edge is Orange; representing
it as verified is Red. Disclose final image user separately.
For statically bounded platform variants, measure each variant and use the maximum rather than summing mutually exclusive duplicates. Count platform divergence separately. Dynamic consequential behavior that cannot be bounded is Orange; representing unverified platform support or success as established is Red.
One responsibility family is one independently accepted build-definition outcome with its own change and rollback lifecycle, not each Dockerfile mechanism. A conventional builder stage, one governed toolchain input, one copied application artifact, and one runtime stage with defaults are one cohesive responsibility family, not four, when they share one product owner and lifecycle. Count separately when images, selectable targets, independently released artifacts, external-input policies, platform branches, or runtime-default contracts can change and roll back independently. Generated, vendored, compatibility, fixture, and policy artifacts retain their producer or repository ownership. A repository-accepted cohesive generated or vendor matrix may lower only the physical-line response by one level; it cannot relax a semantic Red stop.
A six-instruction, two-stage application Dockerfile with one governed toolchain image, one build step, one cross-stage application copy, and one fixed runtime entrypoint is one cohesive responsibility family and remains structurally Green when its other signals are Green. An application image plus an independently operated migration target is two families and Yellow on this signal. Four independently released target images with distinct owners or rollback lifecycles are four families and Red even if line, instruction, and stage counts are otherwise Green.
A reachable build stage with three root-executed RUN instructions has a
root span of three even when the final runtime stage selects a non-root user.
The stages are not summed, and the final transition does not erase the
build-stage count. Unknown base-user or target reachability remains Orange
until established.
Three materially coupled Yellow signals normally justify Orange. Two materially coupled Orange signals affecting the same owner are presumptively Red unless a cohesive-artifact rationale, repository acceptance, evidence, validation, growth bound, and rollback justify retaining Orange. One Red signal remains Red. Do not aggregate unrelated findings into a score. Physical-line, instruction, and stage counts are often correlated and do not stack automatically.
An existing Red legacy Dockerfile may receive the smallest safe authorized fix when it adds no independent responsibility or meaningful structural growth and records a decomposition or follow-up boundary. New responsibility remains Red. A bounded exception requires repository acceptance, evidence, validation, an owner, growth limit, refresh condition, and rollback. It cannot relax protected-data, support, truthfulness, or authority stops.
Rollback restores the prior authorized Dockerfile or generator output, context and ignore assumptions, stage graph, variables, mounts, user transitions, and platform branches, then remeasures the static contract. It grants no live Docker authority.
docker/dockerfile:1 is mutable because it selects
the latest stable 1.x frontend at build time. Exact stable pins, labs
channels, and prereleases have different update and support boundaries.ARG may precede the first FROM. A global ARG can parameterize
FROM but must be redeclared inside a stage for ordinary later use.
ARG starts at declaration and follows stage inheritance; ENV persists in
image configuration and descendant stages. ARG and ENV are not
protected-value transports.COPY --from ownership is Red until resolved. Unnecessary stage
proliferation begins at least Yellow.COPY preference does not authorize
restructuring.ADD is Red without source authority, immutability or update policy,
verification, and rollback. Deliberate local archive extraction is Yellow or
Orange according to ownership and adverse-case evidence.RUN chain is Orange when it obscures
command failure or responsibility ownership.WORKDIR affects later build and runtime-default instructions and relative
paths can chain. USER affects later build execution and image runtime
defaults; one group can suppress supplementary groups. Resolve stage,
platform, source metadata, ownership, mode, and permissions together.EXPOSE records intended port metadata but does not publish a host port.
VOLUME declares a runtime mount point and has builder-dependent
post-declaration mutation behavior. STOPSIGNAL supplies a default that
runtime configuration can override.HEALTHCHECK applies. A false-pass, unsafe timeout, or
protected diagnostic output is Red. ONBUILD stores downstream triggers
whose context, source, ordering, and mutation ownership must be explicit;
hidden consequential downstream behavior is at least Orange.ENTRYPOINT receives runtime arguments and can pair with exec-form
CMD defaults. Shell-form entrypoints normally interpose a shell and can
discard CMD or runtime arguments and fail to forward signals. Establish
the exact form and override matrix rather than inferring runtime behavior.ONBUILD, SHELL, layer
production, exporter behavior, attestations, registry policy, signing, and
runtime override remain separately owned.This profile was inspected on 2026-07-24 against the Apache-2.0 Docker documentation and BuildKit sources associated with stable Dockerfile frontend 1.25.0 and BuildKit 0.31.2, plus the Apache-2.0 OCI Image Spec 1.1.1. These are calibration facts, not project-selected versions or proof of a supported combination. APG copies or adapts no upstream prose, source, example, or table; this procedure is independently written synthesis.
Refresh before a behavior-bearing correction, maturity review, or publication when the stable frontend, builder behavior, instruction set, build checks, context or ignore rules, cache, mount, Windows, platform, provenance, OCI configuration, licensing, or representative false-escalation evidence materially changes.
Removal is candidate-independent. It must delete the leaf, flat projection,
catalog and capability-map entries, current-development release policy, strict
test inventory, focused test, and public scenario fixture while preserving
evaluation and exit history. The project-scoped projection owner and its
fixtures must remove only dockerfile-profile, preserve every other live
skill, and recompute all surviving skill, catalog, projection, route, fixture,
and test counts. Derive counts from the resulting live inventories. A raw
APG33 commit revert is not valid rollback because it would restore historical
counts and integration state. No private guidance was migrated, so rollback
restores none of it.
The target repository owns whether to use Docker and a Dockerfile; Dockerfile path or generator; base image, registry, tag, digest, update policy, and provenance; frontend, builder, Engine, Buildx, and BuildKit versions; Linux or Windows containers; build and target platforms; context roots, ignore files, named or remote contexts; target stages; shell and package manager; dependency sources and exact commands; user, group, ownership, mode, ports, volumes, health, signal, entrypoint, command, and runtime policy; mount identities and sharing; network, cache, secret, SSH, and entitlement policy; scanners, exporters, SBOM, attestations, signing, registries, CI, publication, rollback, protected data, external mutation, release, and destructive-action authority.
When material, report the Dockerfile profile level; exact frontend, builder, platform, context, target, and policy basis; parser directives; stage and source graph; argument and environment scope; shell and exec forms; ignore rules; copy and add ownership; mounts, cache, protected-data flow, and clean-build fallback; work directory, user, permissions, and runtime metadata; structural and semantic signals; project checks actually run; unsupported or unverified boundaries; accepted exception if any; and rollback.
Green needs project checks. Yellow needs focused inspection. Orange needs an accepted local decision and adverse-case validation. Red records the stopped unsupported claim, ambiguity, mutable or unverified input, wrong artifact, protected-data path, unsafe runtime default, false completion claim, unauthorized mutation, or growth and the condition required before reconsideration. Static review, a parser, lint, or build checks do not become build, artifact, runtime, or publication evidence.
Stop or escalate when effective frontend, parser, builder, platform, or feature support is unverified; stage, context, source, ignore, copy, user, ownership, or target behavior can produce the wrong artifact; mutable or remote input lacks required authority and verification; untrusted data reaches a shell; protected data can enter image configuration, history, layers, cache, provenance, logs, health output, or exported artifacts; cache or mount behavior can silently control correctness; final-root, entrypoint, signal, health, volume, or downstream-trigger behavior remains unsafe; source or lint evidence is represented as build or runtime success; a Dockerfile can mutate destructive or consequential external state without exact authority; or meaningful Red growth lacks decomposition or an accepted bounded exception.
ARG is available throughout every stage..dockerignore.ADD without project authority and immutable verification.