coding-os 0.3.2__py3-none-any.whl

core/skills/deployment-cicd/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: deployment-cicd
+tier: cross-cutting
+domain: [infra]
+description: Production-ready CI/CD pipelines, container images, and release patterns. Use when designing a CI pipeline, writing Dockerfiles, choosing between blue-green / canary / rolling, setting up semantic versioning, defining a rollback playbook, or migrating from manual deploys to GitOps. Stack-agnostic; recipes target GitHub Actions, Docker, Kubernetes, and the major cloud providers. Pairs with observability (deploy markers in metrics) and incident-response (rollback playbook).
+last_reviewed: "2026-05-11"
+---
+
+# Deployment + CI/CD — Ship Safely, Roll Back Fast
+
+A practical playbook for the deploy pipeline that gets a feature from "merged" to "in production" reliably. Stack-agnostic core; recipes assume Docker + GitHub Actions + Kubernetes (the 2026 industry default) with callouts for AWS / GCP / Fly.io specifics.
+
+## When to Use This Skill
+
+- Designing CI for a new service — the shape now sets the team's culture.
+- Writing or auditing a Dockerfile — bad layers cost minutes per build.
+- Choosing between rolling, blue-green, canary, or feature-flag deploys.
+- Defining the release process — who clicks deploy, when, and what's reversible.
+- Adding semantic versioning + automated changelogs.
+- Setting up secrets in CI without leaking them.
+- Writing a rollback playbook (preferably *before* you need it).
+- Migrating manual deploys → GitOps (Argo CD / Flux).
+
+Skip when: prototyping a script. Real services, real pipelines.
+
+## The Deployment Pipeline — Six Stages
+
+```
+commit → build → test → image → deploy(staging) → deploy(prod)
+   │       │      │       │           │                │
+   <1s    1-3m   1-5m    1-2m        1-5m         1-5m + verify
+```
+
+Every stage must be:
+
+- **Idempotent** — re-running produces the same result.
+- **Fast-failing** — break early, don't ship to staging if unit tests failed.
+- **Observable** — emit deploy markers to metrics so dashboards correlate "the spike" with "the deploy".
+- **Reversible** — every forward step has a documented backward step.
+
+**Hard target:** commit → prod within 30 minutes for non-DB-migration changes. Slower than that, the team batches and the per-batch risk skyrockets.
+
+## Dockerfile — the Five-Layer Rule
+
+A good Dockerfile produces a small, secure, cache-friendly image. Five layers, in this order:
+
+```dockerfile
+# 1. Base image — minimal, pinned, scanned
+FROM python:3.12-slim AS base
+
+# 2. System dependencies — change rarely
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 3. Language dependencies — change with lock file only
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev
+
+# 4. Application code — change every commit
+COPY src/ src/
+
+# 5. Runtime configuration — labels, user, entrypoint
+LABEL org.opencontainers.image.source="https://github.com/org/repo"
+RUN useradd --uid 1000 --no-create-home app
+USER 1000
+EXPOSE 8000
+CMD ["uv", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+**Hard rules:**
+
+- **Pin the base image by digest**, not tag (`python:3.12-slim@sha256:...`). Tags float; digests don't.
+- **Multi-stage builds** when you compile assets / TypeScript / Go binaries. Build stage has compilers; runtime stage doesn't.
+- **Non-root user** — `USER 1000`. Containers running as root in K8s are a security finding.
+- **No secrets in image layers.** `RUN curl -H "Bearer $TOKEN"` leaks the token in image history. Use BuildKit secrets or runtime env vars.
+- **Smallest viable base.** `alpine` < `slim` < `bullseye`. Trade-off: alpine has musl libc (occasional compat issues). For Python, `slim` is usually the sweet spot. For Go, `scratch` or `distroless`.
+- **HEALTHCHECK** — actively probe the app, not just process liveness.
+
+### Image hygiene checklist
+
+- [ ] Base image pinned by digest
+- [ ] Non-root `USER` set
+- [ ] Multi-stage build (if any compile step)
+- [ ] No secrets baked in (`docker history --no-trunc` reveals nothing sensitive)
+- [ ] OCI labels set (`org.opencontainers.image.*`)
+- [ ] HEALTHCHECK or K8s readiness/liveness probe defined
+- [ ] CVE-scanned by `trivy` / `grype` in CI
+
+## CI Pipeline — GitHub Actions Template
+
+```yaml
+# .github/workflows/ci.yml
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  packages: write  # for ghcr.io
+  id-token: write  # for OIDC to cloud
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install uv
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run pytest -q --cov=src --cov-report=xml
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  build-image:
+    needs: lint-and-test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: true
+          sbom: true
+      - uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          severity: CRITICAL,HIGH
+          exit-code: "1"
+```
+
+**Hard rules:**
+
+- **`concurrency` block** to cancel in-progress runs on the same branch — saves cost and time.
+- **OIDC to cloud**, not long-lived access keys. `id-token: write` plus a cloud-side trust policy.
+- **Pin actions by SHA** for security-critical workflows, not version tags (`uses: actions/checkout@8e5e7e5...`). Dependabot updates these.
+- **SBOM + provenance** on every image (`provenance: true`, `sbom: true`). Required for SLSA L2.
+- **CVE scan** as a gate — block merge if HIGH/CRITICAL CVEs present.
+- **Lint + test → build → push** stage order. Building a broken image wastes minutes.
+
+## Versioning — Semantic + Auto-Tag
+
+Use **semver** (MAJOR.MINOR.PATCH):
+
+- MAJOR — breaking change to the public API / contract.
+- MINOR — backwards-compatible feature add.
+- PATCH — backwards-compatible bug fix.
+
+Automate via [Conventional Commits](https://www.conventionalcommits.org) + `semantic-release` (Node), `python-semantic-release`, or `goreleaser`. The commit prefix (`feat:`, `fix:`, `chore:`, `feat!:`) drives the version bump.
+
+Tag the Docker image with all three: `:1.4.2`, `:1.4`, `:1`. Latest goes to mutable `latest`, but production never deploys `latest` — pin a specific digest.
+
+## Deploy Strategies — When to Pick Which
+
+| Strategy | How | Risk | Use For |
+|---|---|---|---|
+| **Rolling** | Replace pods N at a time | Mixed versions during rollout | Default for stateless services |
+| **Blue-green** | Spin up green, switch traffic instantly | Cutover bug = full outage | DB cutovers, critical migrations |
+| **Canary** | Send 1% → 5% → 25% → 100% | Need traffic-split + auto-rollback | High-traffic user-facing changes |
+| **Feature flag** | Deploy disabled, flip flag per cohort | Flag debt; testing combinatorial states | New features, A/B tests, kill-switches |
+| **Shadow** | Send mirror traffic, don't show result | Read-side only, no side effects | Validating perf of a rewrite |
+
+**Default for new services: rolling.** Move to canary when the service has paying users and an incident would matter.
+
+## Rollback — the most important playbook
+
+A deployment system without a rollback button is a system that goes down. Three rules:
+
+1. **One command to roll back.** `argocd app rollback <app> <revision>` or `helm rollback <release> <revision>` or `kubectl rollout undo deploy/<name>`. Practiced quarterly.
+2. **Old version warm** for at least 15 minutes after rollout. Don't terminate the old replicas immediately — keep them warm so rollback is instant.
+3. **Migrations are forward-compatible.** A rollback shouldn't break because the new code wrote a column the old code doesn't understand. Patterns: expand-contract (add column nullable → backfill → make non-null in next release → remove old column in release after that).
+
+### Forward-only migrations (the pattern)
+
+```
+Release 1: add new column `email_verified_at` (nullable)
+Release 2: backfill existing rows
+Release 3: switch reads to new column; writes still go to both
+Release 4: writes only to new column; remove old column reads
+Release 5: drop old column
+```
+
+Each release is independently rollback-safe.
+
+## Secrets — never in git, never in image
+
+- **Source of truth:** AWS Secrets Manager / GCP Secret Manager / HashiCorp Vault / Sealed Secrets / SOPS.
+- **Injection at runtime** via env var or mounted file — never baked into image.
+- **CI secrets:** GitHub Actions secrets / OIDC short-lived tokens. Never echo.
+- **Rotation:** all production secrets rotated quarterly. Auto-rotation if the system supports it.
+- **Pre-commit scan:** `gitleaks`, `trufflehog` run on every PR. Block merge if a secret pattern is found.
+
+## GitOps — the 2026 default
+
+For production K8s: don't `kubectl apply` from a laptop. Use **Argo CD** or **Flux** — the desired state is git, the operator reconciles. Benefits:
+
+- Audit trail (every change is a commit).
+- Drift detection (operator notices if someone hand-edited the cluster).
+- One-command rollback (`git revert HEAD`).
+- PR-based reviews of infra changes.
+
+## Anti-patterns (reject in review)
+
+- **`latest` tag in production manifests** — non-deterministic deploys. Pin digest.
+- **Building image inside the cluster** — slow, insecure. Build in CI, ship the image.
+- **`kubectl apply -f` from a laptop** — no audit, drifts from git. Use GitOps.
+- **Long-lived AWS access keys in GH secrets** — use OIDC.
+- **Manual database migrations during deploy** — auto via migration job + forward-compatible pattern.
+- **No rollback button** — system that can't be rolled back will go down.
+- **Skipping CVE scans because they're noisy** — fix the noise (allowlist with expiry), don't disable the scan.
+- **Branch deploys to prod** — only main → prod. Branches go to ephemeral environments.
+
+## Verification (project-specific for coding-os meta-repo)
+
+This skill applies to:
+- Container build pipelines that ship coding-os to PyPI / GHCR.
+- The `src/templates/<stack>/scaffold/.github/workflows/` files that propagate to consumer projects.
+- The release tooling around `uv tool install --editable .` → published wheel.
+
+Pre-merge checks:
+- `gh workflow list` shows expected workflows enabled.
+- `make verify` green.
+- No secret regex matches in the diff (`gitleaks detect --staged`).
+
+## Tooling
+
+Lint a GitHub Actions workflow (unpinned actions, echoed secrets, missing timeouts):
+`python3 scripts/lint_workflow.py .github/workflows/*.yml`
+
+## See also
+
+- [references/pipeline-and-release.md](references/pipeline-and-release.md) — CI stages, deploy strategies, rollback, versioning, migration ordering.
+- [assets/deploy-checklist.md](assets/deploy-checklist.md) — the pipeline gate.
+- [observability](../observability/SKILL.md) — deploy markers in dashboards.
+- [incident-response](../incident-response/SKILL.md) — rollback as runbook step.
+- [security-web](../security-web/SKILL.md) §A05 (Security Misconfig), §A06 (Vulnerable & Outdated Components), §A08 (Software & Data Integrity Failures).
+- [db-design](../db-design/SKILL.md) — expand/contract migration discipline.

core/skills/deployment-cicd/assets/deploy-checklist.md

@@ -0,0 +1,26 @@
+<!-- domain:INFRA | layer:asset | ssot:false | updated:2026-06-04 -->
+# Deploy Pipeline Checklist
+
+Run when building or reviewing a CI/CD pipeline or a release.
+
+## Pipeline
+- [ ] Stages ordered cheapest-first (lint → typecheck → unit → build → integration → e2e → scan → deploy).
+- [ ] Every action pinned to a tag/SHA — no `@main`/`@master`/`@latest`.
+- [ ] No secret echoed/printed in a step; secrets from the store, not in YAML.
+- [ ] `timeout-minutes` on every job (no hung-job billing).
+- [ ] Dependencies cached; independent stages parallel.
+- [ ] `python3 scripts/lint_workflow.py <workflow files>` → `clean`.
+
+## Release
+- [ ] Semantic version + tag; immutable artifact addressed by tag (never re-deploy `latest`).
+- [ ] Changelog generated from Conventional Commits.
+- [ ] Deploy strategy chosen (rolling / blue-green / canary) with the trade-off understood.
+
+## Safety
+- [ ] Rollback is one documented command, tested.
+- [ ] Migrations are backward-compatible with the running version (expand→contract).
+- [ ] Deploy marker emitted to metrics (correlate regressions to releases).
+- [ ] Health check / smoke test gates the traffic switch.
+
+## Verify
+- [ ] `make skills-check-versions` — Docker/k8s/action pins current (where pinned).

core/skills/deployment-cicd/references/pipeline-and-release.md

@@ -0,0 +1,54 @@
+<!-- domain:INFRA | layer:reference | ssot:true | updated:2026-06-04 -->
+# Pipeline & Release — CI Stages, Deploy Strategies, Rollback
+
+> P: Build a CI/CD pipeline that ships safely and rolls back fast.
+> R: Designing CI, choosing a deploy strategy, or defining a rollback path.
+> S: Container image craft — that's [docker](../../docker/SKILL.md). The host — [linux-sysadmin](../../linux-sysadmin/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [deploy-checklist.md](../assets/deploy-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## CI stages (fail fast, cheapest first)
+
+```
+lint → typecheck → unit → build → integration → e2e → security scan → deploy
+```
+
+Order cheapest/fastest checks first so a lint error fails in seconds, not after a
+10-minute test run. Cache dependencies; run independent stages in parallel. Pin
+every action to a tag or SHA (`actions/checkout@v4`, not `@main`) —
+`lint_workflow.py` flags moving refs, echoed secrets, and missing timeouts.
+
+## Deploy strategies
+
+| Strategy | How | Use when |
+|---|---|---|
+| rolling | replace instances batch by batch | default; some version overlap is fine |
+| blue-green | stand up new env, flip traffic, keep old | instant rollback (flip back), needs 2× capacity briefly |
+| canary | route a small % to the new version, watch, ramp | high-risk change; catch issues at 1% blast radius |
+
+Blue-green gives the fastest rollback (flip the router back); canary gives the
+smallest blast radius. Rolling is the simplest default. Whichever you pick, a
+**rollback** must be one documented command — rollback is the most-used incident
+action ([incident-response](../../incident-response/SKILL.md)).
+
+## Versioning + release
+
+Semantic versioning (`MAJOR.MINOR.PATCH`): breaking / feature / fix. Conventional
+Commits drive automated changelogs + version bumps (release-please/semantic-release
+parse the commit type). Tag the release; the image/artifact is immutable and
+addressable by that tag — never re-deploy `latest`.
+
+## Migrations + deploys (the ordering trap)
+
+Schema migrations must be **backward-compatible** with the currently-running code,
+because during a rolling deploy both versions run at once. Expand-then-contract:
+add the new column/table (old code ignores it) → deploy code that uses it →
+later, remove the old column. A migration that drops a column the old code still
+reads takes the site down mid-deploy.
+
+## Observability of the deploy itself
+
+Emit a deploy marker to metrics so a latency/error regression can be correlated to
+the release that caused it ([observability](../../observability/SKILL.md)). A deploy
+you can't see in the dashboards is a deploy you can't safely roll back.

core/skills/deployment-cicd/scripts/lint_workflow.py

@@ -0,0 +1,79 @@
+"""Lint a GitHub Actions workflow for supply-chain + reliability footguns.
+
+PURPOSE:      Flag unpinned actions, leaked secrets, and missing timeouts so a
+              pipeline is reproducible and not a supply-chain hole.
+INPUT:        one or more workflow .yml/.yaml paths. [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only (regex — no YAML parser needed, portable).
+NOTES:        Heuristic. Pure scan_text() is unit-testable. Spec:
+              docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# uses: owner/repo@<ref> — flag moving refs and missing refs.
+USES_MOVING = re.compile(r"uses:\s*[\w.-]+/[\w.-]+@(main|master|latest)\b")
+USES_NOREF = re.compile(r"uses:\s*[\w.-]+/[\w.-]+\s*$")
+# secret echoed into a run step (printed = exposed in logs)
+SECRET_ECHO = re.compile(r"(echo|print|cat)[^\n]*\$\{\{\s*secrets\.")
+RUN_CURL_BASH = re.compile(r"curl[^\n]*\|\s*(sudo\s+)?(bash|sh)\b")
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    has_timeout = "timeout-minutes" in text
+    has_job = re.search(r"^\s*jobs:\s*$", text, re.MULTILINE) is not None
+    for n, line in enumerate(text.splitlines(), 1):
+        if line.lstrip().startswith("#"):
+            continue
+        if USES_MOVING.search(line):
+            findings.append(
+                f"{filename}:{n}: action pinned to a moving ref (@main/master/latest) — pin a tag/SHA"
+            )
+        elif USES_NOREF.search(line):
+            findings.append(f"{filename}:{n}: action with no @version — pin a tag/SHA")
+        if SECRET_ECHO.search(line):
+            findings.append(f"{filename}:{n}: secret echoed into a step — leaks in logs")
+        if RUN_CURL_BASH.search(line):
+            findings.append(
+                f"{filename}:{n}: curl | bash from an unpinned source — supply-chain risk"
+            )
+    if has_job and not has_timeout:
+        findings.append(
+            f"{filename}: no timeout-minutes on any job — a hung job runs until the platform cap"
+        )
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/docker/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: docker
+tier: infra
+domain: [infra]
+description: Build small, secure, reproducible container images and compose stacks. Use when writing or reviewing a Dockerfile, debugging a bloated/slow image build, setting up docker-compose for local dev, adding a healthcheck, handling build secrets, or hardening a container (non-root, minimal base). Triggers — "Dockerfile", "docker build", "docker-compose", "containerize", "image is huge", "layer cache", "multi-stage", any `Dockerfile`/`compose.yaml`. Pairs with deployment-cicd (CI builds + registries + k8s — this skill is the image/compose craft), linux-sysadmin (the host), security-web (runtime hardening).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# Docker — Images & Compose
+
+An image is a liability proportional to its size and privilege: every MB ships, every package is attack surface, every root container is a host risk. The craft is small, reproducible, least-privilege images. CI/CD, registries, and orchestration belong to [deployment-cicd](../deployment-cicd/SKILL.md); this skill is the Dockerfile and compose itself.
+
+> Lint a Dockerfile against the rules below:
+> `bash scripts/lint_dockerfile.sh path/to/Dockerfile`
+
+## Multi-stage — build fat, ship thin
+
+```dockerfile
+# Wrong — toolchain + source + caches all ship; 1.2 GB; runs as root
+FROM node:26
+COPY . .
+RUN npm install && npm run build
+CMD ["node", "dist/server.js"]
+
+# Correct — build stage discarded; runtime carries only the artifact; ~180 MB
+FROM node:26-slim AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci                      # ci (not install) = reproducible, lockfile-exact
+COPY . .
+RUN npm run build
+
+FROM node:26-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node                       # never run as root
+EXPOSE 8080
+HEALTHCHECK CMD node healthcheck.js || exit 1
+CMD ["node", "dist/server.js"]
+```
+
+The build stage carries compilers and dev deps; the runtime stage copies only the artifact. Result is smaller, faster to pull, and has less attack surface. Full optimization → [references/dockerfile-optimization.md](references/dockerfile-optimization.md).
+
+## Layer cache — order from least to most volatile
+
+```dockerfile
+# Wrong — any source change busts the dependency layer; npm ci re-runs every build
+COPY . .
+RUN npm ci
+
+# Correct — deps cached until package*.json changes; source edits skip the install
+COPY package*.json ./
+RUN npm ci
+COPY . .                        # volatile source last
+```
+
+Docker caches per layer; a layer rebuilds when its inputs or any prior layer changes. Put rarely-changing things (dependency manifests, `RUN apt install`) **before** frequently-changing things (source). A `.dockerignore` (excluding `node_modules`, `.git`, `*.log`) keeps the build context — and the cache key — small.
+
+## Never bake secrets
+
+```dockerfile
+# Wrong — the secret is in the image history forever, readable by anyone who pulls it
+ARG API_KEY
+ENV API_KEY=$API_KEY
+
+# Correct — BuildKit secret mount: available during build, never in a layer
+RUN --mount=type=secret,id=npmtoken \
+    NPM_TOKEN="$(cat /run/secrets/npmtoken)" npm ci
+```
+
+`ARG`/`ENV` secrets persist in `docker history` and every pulled copy. Use BuildKit `--mount=type=secret` for build-time, and inject runtime secrets via the orchestrator's secret store (env from a vault, not the image). Runtime hardening (caps, read-only fs) → [security-web](../security-web/SKILL.md).
+
+## Compose for local dev
+
+```yaml
+# compose.yaml
+services:
+  api:
+    build: .
+    ports: ["8080:8080"]
+    environment: { DATABASE_URL: postgres://app:app@db:5432/app }
+    depends_on:
+      db: { condition: service_healthy }   # wait for db READY, not just started
+  db:
+    image: postgres:18
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      retries: 5
+```
+
+`depends_on: condition: service_healthy` is the fix for "app starts before the DB is ready" — a plain `depends_on` only waits for the container to *start*, not to be *usable*. Patterns → [references/compose-patterns.md](references/compose-patterns.md).
+
+## Anti-patterns (reject on sight)
+
+- `FROM ubuntu` / `FROM node` with no tag → pins to a moving `latest`; pin a version + `-slim`/`-alpine`.
+- No `USER` directive → container runs as root.
+- `ADD` for a local file → use `COPY` (`ADD` also fetches URLs + auto-extracts tarballs — surprising).
+- `RUN apt update` and `apt install` in separate layers → stale package index; combine + `rm -rf /var/lib/apt/lists/*`.
+- Secret in `ARG`/`ENV` → leaks in history.
+- `COPY . .` before installing deps → busts the cache every source edit.
+- No `.dockerignore` → ships `.git`, `node_modules`, secrets into the build context.
+
+## See also
+
+- [references/dockerfile-optimization.md](references/dockerfile-optimization.md) — multi-stage, cache, base images, size.
+- [references/compose-patterns.md](references/compose-patterns.md) — healthchecks, depends_on, networks, profiles.
+- [assets/dockerfile-checklist.md](assets/dockerfile-checklist.md) — the ship gate.
+- [deployment-cicd](../deployment-cicd/SKILL.md) · [linux-sysadmin](../linux-sysadmin/SKILL.md) · [security-web](../security-web/SKILL.md).

core/skills/docker/assets/dockerfile-checklist.md

@@ -0,0 +1,31 @@
+<!-- domain:INFRA | layer:asset | ssot:false | updated:2026-06-04 -->
+# Dockerfile Ship Checklist
+
+Run before committing a Dockerfile or compose stack.
+
+## Image
+- [ ] Base image pinned to an explicit version + `-slim`/`-alpine`/distroless — never `latest`.
+- [ ] Multi-stage: build tools/dev-deps in a build stage, runtime copies only the artifact.
+- [ ] `USER` set to a non-root user in the runtime stage.
+- [ ] `HEALTHCHECK` present for long-running services.
+- [ ] `.dockerignore` excludes `.git`, `node_modules`/build outputs, `.env`.
+
+## Cache & size
+- [ ] Layers ordered least-volatile → most-volatile (deps before source).
+- [ ] `apt/apk` install + cleanup in the same `RUN` (`rm -rf /var/lib/apt/lists/*`).
+- [ ] `COPY` (not `ADD`) for local files.
+- [ ] `docker history` reviewed — no fat layer leaking the build stage.
+
+## Secrets
+- [ ] No secret in `ARG`/`ENV`/layer — BuildKit `--mount=type=secret` for build-time.
+- [ ] Runtime secrets injected by the orchestrator, not baked.
+
+## Compose (if present)
+- [ ] `depends_on: condition: service_healthy` + real healthchecks (no start-order races).
+- [ ] Named volumes for data that must survive `down`.
+- [ ] Only necessary `ports:` exposed; services talk by service name.
+
+## Verify
+- [ ] `bash scripts/lint_dockerfile.sh <Dockerfile>` → `0 issue(s)`.
+- [ ] `docker build` succeeds; final image size sane for the stack.
+- [ ] `make skills-check-versions` — engine/compose pins current.

core/skills/docker/references/compose-patterns.md

@@ -0,0 +1,66 @@
+<!-- domain:INFRA | layer:reference | ssot:true | updated:2026-06-04 -->
+# Compose Patterns — Healthchecks, Dependencies, Profiles
+
+> P: Wire a multi-service local stack that starts in the right order and stays debuggable.
+> R: Writing `compose.yaml` for local dev or integration tests.
+> S: Production orchestration (k8s) — that's [deployment-cicd](../../deployment-cicd/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [dockerfile-optimization.md](dockerfile-optimization.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Wait for READY, not STARTED
+
+```yaml
+services:
+  api:
+    build: .
+    depends_on:
+      db: { condition: service_healthy }
+  db:
+    image: postgres:18
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+```
+
+Plain `depends_on: [db]` only waits for the db container to *start* — the app
+still races the database's own startup and crashes on "connection refused".
+`condition: service_healthy` + a real `healthcheck` blocks the app until the db
+answers. This single pattern removes most "works on the second `up`" flakiness.
+
+## Profiles — optional services
+
+```yaml
+services:
+  api: { build: . }
+  mailhog:
+    image: mailhog/mailhog
+    profiles: ["dev"]        # only starts with: docker compose --profile dev up
+```
+
+Keep heavy optional services (mail catchers, admin UIs) behind a profile so the
+default `up` is fast. Test-only fixtures go behind a `test` profile.
+
+## Named volumes + networks
+
+- **Named volume** for data that must survive `down` (`db-data:/var/lib/postgresql/data`);
+  a bind mount for source you edit live. `docker compose down -v` wipes volumes — know which.
+- Compose creates a default network; services reach each other by **service name**
+  (`postgres://db:5432`), not `localhost`. Only `ports:` you actually need exposed
+  to the host — internal services need none.
+
+## Env + secrets
+
+`environment:` for non-secret config; an `.env` file (git-ignored) for local
+values via `${VAR}`. Never commit real secrets — for anything sensitive use
+compose `secrets:` (file-backed) so it's mounted, not baked. Production secrets
+come from the orchestrator's store, not compose.
+
+## One command to reset
+
+`docker compose down -v --remove-orphans && docker compose up --build` is the
+clean-slate reset — fresh volumes, rebuilt images, no stale orphan containers.
+Document it so "it's broken locally" has a known cure.