@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/docker/checks/compose-no-host-bind-for-data.json

@@ -0,0 +1,18 @@
+{
+  "id": "compose-no-host-bind-for-data",
+  "why": "A host-path bind mount breaks the moment the container lands on another node. App data lives in a named volume; a bind mount is for a read-only config in dev.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": [
+    "compose"
+  ],
+  "exclude": [
+    "**/*dev*",
+    "**/*local*",
+    "**/*override*"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s+-\\s*['\\\"]?(?:\\.{1,2}/|/(?!var/run/docker\\.sock))[^:\\n]*:/[^:\\n]*['\\\"]?\\s*$",
+  "bad": "    volumes:\n      - ./data:/data/db",
+  "good": "    volumes:\n      - mongo-data:/data/db\n      - ./nginx.conf:/etc/nginx/nginx.conf:ro"
+}

package/packs/docker/checks/compose-no-plaintext-secret.json

@@ -0,0 +1,13 @@
+{
+  "id": "compose-no-plaintext-secret",
+  "why": "A password, token or key as a literal in compose `environment:` is readable in the file, in `docker inspect` and in the repo. Use ${VAR} substitution, env_file, or Docker secrets.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": [
+    "compose"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s+-?\\s*[A-Z0-9_]*(?:PASSWORD|PASSWD|SECRET|API_?KEY|TOKEN|PRIVATE_KEY|ACCESS_KEY|MONGODB_URI)[A-Z0-9_]*\\s*[:=]\\s*(?!\\$\\{?\\w)(?!['\\\"]?\\$)['\\\"]?[^\\s'\\\"$][^\\n]*",
+  "bad": "      MONGO_INITDB_ROOT_PASSWORD: hunter2\n      - API_TOKEN=abc123",
+  "good": "      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD}\n      - API_TOKEN=${API_TOKEN:?set it}\n    secrets: [mongo_root_password]"
+}

package/packs/docker/checks/compose-no-swarm-ignored-keys.json

@@ -0,0 +1,13 @@
+{
+  "id": "compose-no-swarm-ignored-keys",
+  "why": "docker stack deploy silently ignores restart, container_name, depends_on, links and network_mode. Use deploy.restart_policy, service names, and retry-with-backoff in the app.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": [
+    "compose"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s{2,}(restart|container_name|depends_on|links|network_mode|ipv4_address):",
+  "bad": "  api:\n    restart: always\n    depends_on: [mongo]",
+  "good": "  api:\n    deploy:\n      restart_policy:\n        condition: on-failure"
+}

package/packs/docker/checks/compose-overlay-not-bridge.json

@@ -0,0 +1,13 @@
+{
+  "id": "compose-overlay-not-bridge",
+  "why": "bridge networks are single-host; Swarm needs overlay. Write the compose file for the multi-node world from day one.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": [
+    "compose"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s+driver:\\s*bridge\\b",
+  "bad": "networks:\n  app:\n    driver: bridge",
+  "good": "networks:\n  app:\n    driver: overlay\n    attachable: true"
+}

package/packs/docker/checks/compose-service-needs-healthcheck.json

@@ -0,0 +1,11 @@
+{
+  "id": "compose-service-needs-healthcheck",
+  "why": "This service has no healthcheck: it is 'healthy' while serving errors, and rolling update, rollback and restart_policy have nothing to decide on.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": ["compose"],
+  "code": false,
+  "flags": "m",
+  "pattern": "^  [\\w.-]+:[ \\t]*\\n(?:(?:    (?!healthcheck:)[^\\n]*|[ \\t]*)(?:\\n|(?![\\s\\S])))*?    (?:image|build):[^\\n]*(?:\\n|(?![\\s\\S]))(?:(?:    (?!healthcheck:)[^\\n]*|[ \\t]*)(?:\\n|(?![\\s\\S])))*(?=^  \\S|(?![\\s\\S]))",
+  "bad": "services:\n  mongo:\n    image: mongo:8.2.3\n    healthcheck:\n      test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n  api:\n    image: registry/api:1.2.3\n    init: true\n",
+  "good": "services:\n  api:\n    image: registry/api:1.2.3\n    init: true\n    healthcheck:\n      test: [\"CMD\", \"node\", \"dist/healthcheck.js\"]\n      start_period: 20s\n"
+}

package/packs/docker/checks/compose-service-needs-init.json

@@ -0,0 +1,11 @@
+{
+  "id": "compose-service-needs-init",
+  "why": "This service has no `init: true`: the app is PID 1 with no signal forwarding or zombie reaping, so docker stop waits 10 s then SIGKILLs it mid-request. Every service gets init: true.",
+  "rule": ".claude/rules/compose-swarm-safe.md",
+  "concepts": ["compose"],
+  "code": false,
+  "flags": "m",
+  "pattern": "^  [\\w.-]+:[ \\t]*\\n(?:(?:    (?!init:\\s*true\\b)[^\\n]*|[ \\t]*)(?:\\n|(?![\\s\\S])))*?    (?:image|build):[^\\n]*(?:\\n|(?![\\s\\S]))(?:(?:    (?!init:\\s*true\\b)[^\\n]*|[ \\t]*)(?:\\n|(?![\\s\\S])))*(?=^  \\S|(?![\\s\\S]))",
+  "bad": "services:\n  mongo:\n    image: mongo:8.2.3\n    init: true\n  api:\n    image: registry/api:1.2.3\n    ports: ['3000']\n",
+  "good": "services:\n  mongo:\n    image: mongo:8.2.3\n    init: true\n  api:\n    image: registry/api:1.2.3\n    init: true\n    stop_grace_period: 15s\n    healthcheck:\n      test: [\"CMD\", \"true\"]\n"
+}

package/packs/docker/checks/copy-needs-chown-with-user.json

@@ -0,0 +1,17 @@
+{
+  "id": "copy-needs-chown-with-user",
+  "why": "Files copied as root are unwritable by the USER the app runs as; the first write to a cache or temp dir fails with EACCES. COPY --chown=node:node when USER is set.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "mode": "needs",
+  "pattern": "^\\s*USER\\s+(?!root\\b)\\S+",
+  "needs": [
+    "--chown=|\\bchown\\b"
+  ],
+  "bad": "COPY --from=build /app/dist ./dist\nUSER node",
+  "good": "COPY --chown=node:node --from=build /app/dist ./dist\nUSER node"
+}

package/packs/docker/checks/copy-source-before-deps.json

@@ -0,0 +1,13 @@
+{
+  "id": "copy-source-before-deps",
+  "why": "COPY . . before the package-file copy means a one-line code change reinstalls every dependency. Copy package.json + lockfile, install, then copy source.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s*COPY\\s+(?:--\\S+\\s+)*\\.\\/?\\s+\\.\\/?\\s*$[\\s\\S]*?^\\s*(?:COPY\\s+[^\\n]*package|RUN\\s+[^\\n]*npm\\s+ci)",
+  "bad": "COPY . .\nRUN npm ci",
+  "good": "COPY package.json package-lock.json ./\nRUN npm ci\nCOPY . ."
+}

package/packs/docker/checks/docker-exec-form.json

@@ -0,0 +1,16 @@
+{
+  "id": "docker-exec-form",
+  "why": "Shell-form CMD/ENTRYPOINT runs the app under sh -c: sh is PID 1, swallows SIGTERM, and the app never shuts down cleanly. Use the JSON-array form.",
+  "rule": ".claude/rules/docker-exec-form.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "exclude": [
+    "**/node_modules/**"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "(?<!\\\\\\s*\\n)^\\s*(CMD|ENTRYPOINT)\\s+(?!\\[)\\S",
+  "bad": "CMD node dist/index.js",
+  "good": "ENTRYPOINT [\"node\", \"dist/index.js\"]\nHEALTHCHECK --interval=30s \\\n  CMD curl -f http://localhost/ || exit 1\n"
+}

package/packs/docker/checks/dockerfile-needs-healthcheck.json

@@ -0,0 +1,17 @@
+{
+  "id": "dockerfile-needs-healthcheck",
+  "why": "Without a HEALTHCHECK, rolling updates and rollback have nothing to decide on and a dead service stays in rotation.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "mode": "needs",
+  "pattern": "^\\s*(CMD|ENTRYPOINT)\\s",
+  "needs": [
+    "^\\s*HEALTHCHECK\\s"
+  ],
+  "bad": "FROM node:24.11.0-slim\nUSER node\nCMD [\"node\", \"dist/index.js\"]",
+  "good": "FROM node:24.11.0-slim\nHEALTHCHECK --interval=30s CMD node dist/healthcheck.js\nUSER node\nCMD [\"node\", \"dist/index.js\"]"
+}

package/packs/docker/checks/dockerfile-needs-user.json

@@ -0,0 +1,21 @@
+{
+  "id": "dockerfile-needs-user",
+  "why": "A container running as root is a root shell one escape away. Add USER node (or another non-root user) before the entrypoint.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "mode": "needs",
+  "pattern": "^\\s*(CMD|ENTRYPOINT)\\s",
+  "needs": [
+    "^\\s*USER\\s+(?!root\\b)\\S+"
+  ],
+  "bad": "FROM node:24.11.0-slim\nENTRYPOINT [\"node\", \"dist/index.js\"]",
+  "good": "FROM node:24.11.0-slim\nUSER node\nENTRYPOINT [\"node\", \"dist/index.js\"]",
+  "exclude": [
+    "**/fixtures/**",
+    "**/e2e/**"
+  ]
+}

package/packs/docker/checks/dockerignore-has-the-basics.json

@@ -0,0 +1,21 @@
+{
+  "id": "dockerignore-has-the-basics",
+  "why": "Without node_modules, .git, .env and dist in .dockerignore the build context is huge and the host's node_modules, secrets and stale builds land in the image.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "globs": [
+    "**/.dockerignore"
+  ],
+  "code": false,
+  "flags": "m",
+  "mode": "needs",
+  "pattern": "[\\s\\S]",
+  "needs": [
+    "^\\**/?node_modules",
+    "^\\**/?\\.git\\b",
+    "^\\**/?\\.env",
+    "^\\**/?dist\\b",
+    "^\\**/?coverage\\b"
+  ],
+  "bad": "node_modules\n",
+  "good": "node_modules\n.git\n.env*\ndist\ncoverage\n.claude\n"
+}

package/packs/docker/checks/gitattributes-forces-lf.json

@@ -0,0 +1,17 @@
+{
+  "id": "gitattributes-forces-lf",
+  "why": "Without `* text=auto eol=lf` a Windows checkout converts scripts and Dockerfiles to CRLF and the container cannot run them.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "globs": [
+    "**/.gitattributes"
+  ],
+  "code": false,
+  "flags": "m",
+  "mode": "needs",
+  "pattern": "[\\s\\S]",
+  "needs": [
+    "eol=lf"
+  ],
+  "bad": "*.png binary\n",
+  "good": "* text=auto eol=lf\n*.png binary\n"
+}

package/packs/docker/checks/health-checks-nothing.json

@@ -0,0 +1,25 @@
+{
+  "id": "health-checks-nothing",
+  "why": "A health check that always says ok keeps a broken service in rotation.",
+  "rule": ".claude/rules/compose-pinned-and-closed.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "res\\.json\\(\\{\\s*status:\\s*'ok',\\s*service\\b",
+  "bad": "res.json({ status: 'ok', service: name });",
+  "good": "const ok = await pingDb();\nres.json({ status: ok ? 'ok' : 'degraded', service: name });"
+}

package/packs/docker/checks/no-crlf-in-scripts.json

@@ -0,0 +1,15 @@
+{
+  "id": "no-crlf-in-scripts",
+  "why": "A shell script with CRLF endings fails inside Linux containers with 'no such file or directory' on the shebang. LF only; .gitattributes enforces it for everyone.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "docker-scripts",
+    "dockerfile",
+    "compose"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "\\r$",
+  "bad": "#!/bin/sh\r\necho hi\r\n",
+  "good": "#!/bin/sh\necho hi\n"
+}

package/packs/docker/checks/no-latest-base.json

@@ -0,0 +1,13 @@
+{
+  "id": "no-latest-base",
+  "why": "An unpinned or :latest base image changes under you between builds. Pin the exact tag (latest-versions tells you which).",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s*FROM\\s+(?:--platform=\\S+\\s+)?(?!scratch\\b)(?![\\w./-]+:\\S*\\d)[\\w./-]+(?::latest)?(?:\\s+AS\\s+\\w+)?\\s*$",
+  "bad": "FROM node:latest\nFROM node AS build\nFROM --platform=linux/amd64 node:latest AS build\n",
+  "good": "FROM node:24.11.0-slim AS build\nFROM scratch"
+}

package/packs/docker/checks/no-secret-in-image.json

@@ -0,0 +1,13 @@
+{
+  "id": "no-secret-in-image",
+  "why": "ENV/ARG values live in image layers and show in `docker history`. Build secrets use RUN --mount=type=secret; runtime secrets are injected at run time.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "mi",
+  "pattern": "^\\s*(ENV|ARG)\\s+\\w*(SECRET|PASSWORD|PASSWD|TOKEN|API_KEY|APIKEY|PRIVATE_KEY|MONGODB_URI|DATABASE_URL)\\w*\\s*=?\\s*\\S",
+  "bad": "ENV MONGODB_URI=mongodb+srv://x\nARG NPM_TOKEN",
+  "good": "RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci\nENV NODE_ENV=production"
+}

package/packs/docker/checks/no-sensitive-file-copy.json

@@ -0,0 +1,13 @@
+{
+  "id": "no-sensitive-file-copy",
+  "why": "COPY of .env, .npmrc, keys or credentials bakes the secret into a layer. Exclude them in .dockerignore and mount at build (--mount=type=secret) or run time.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s*(?:COPY|ADD)\\s+[^\\n]*(?:\\.env\\b|\\.npmrc\\b|\\.pem\\b|\\.key\\b|id_rsa|id_ed25519|id_ecdsa|\\bcredentials\\b|\\.aws/|\\.ssh/)",
+  "bad": "COPY .env .npmrc ./",
+  "good": "RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci"
+}

package/packs/docker/checks/node-env-before-install.json

@@ -0,0 +1,13 @@
+{
+  "id": "node-env-before-install",
+  "why": "NODE_ENV=production set before npm ci skips devDependencies, so the TypeScript build in the same stage fails or ships untranspiled. Set it after the build, in the runtime stage.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s*ENV\\s+NODE_ENV[\\s=]+production\\b[\\s\\S]*?^\\s*RUN\\s+[^\\n]*\\bnpm\\s+(?:ci|install)\\b(?![^\\n]*(?:--omit=dev|--production|--only=prod))",
+  "bad": "ENV NODE_ENV=production\nRUN npm ci\nRUN npm run build",
+  "good": "RUN npm ci\nRUN npm run build\nFROM node:24.11.0-slim\nENV NODE_ENV=production\nRUN npm ci --omit=dev"
+}

package/packs/docker/checks/npm-ci-not-install.json

@@ -0,0 +1,13 @@
+{
+  "id": "npm-ci-not-install",
+  "why": "npm install can rewrite the lockfile and resolve different versions per build. npm ci installs exactly the lockfile or fails.",
+  "rule": ".claude/rules/dockerfile-production.md",
+  "concepts": [
+    "dockerfile"
+  ],
+  "code": false,
+  "flags": "m",
+  "pattern": "^\\s*RUN\\s+[^\\n]*\\bnpm\\s+(?:install|i)\\b(?![^\\n]*-g\\b)",
+  "bad": "RUN npm install --production",
+  "good": "RUN npm ci --omit=dev\nRUN npm install -g pnpm"
+}

package/packs/docker/pack.json

@@ -0,0 +1,46 @@
+{
+  "name": "docker",
+  "version": "1.0.0",
+  "description": "Dockerfiles, Compose and Swarm: exec form, init, non-root, pinned bases, healthchecks, secrets, swarm-safe compose.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/docker"
+  },
+  "keywords": [
+    "docker",
+    "compose",
+    "swarm"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "dockerfile": [
+      "**/Dockerfile",
+      "**/Dockerfile.*",
+      "**/*.Dockerfile",
+      "**/.dockerignore"
+    ],
+    "compose": [
+      "**/compose*.yml",
+      "**/compose*.yaml",
+      "**/docker-compose*.yml",
+      "**/docker-compose*.yaml",
+      "**/stack*.yml",
+      "**/stack*.yaml"
+    ],
+    "docker-scripts": [
+      "**/docker/**/*.sh",
+      "**/entrypoint*.sh",
+      "**/.gitattributes"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/docker/rules/compose-pinned-and-closed.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "**/*compose*.yml"
+  - "**/*compose*.yaml"
+---
+
+# Compose: images are pinned, and a database has auth
+
+<constraints>
+Always do:
+- Pin every image to a version.
+- Start a database with auth on, even on a private network.
+- Make a health check test what the service needs.
+
+Never do:
+- Use `:latest`, or a major tag alone.
+- Write a health route that always says ok.
+</constraints>
+
+## Check
+`compose-image-pinned`, `compose-db-needs-auth`, `health-checks-nothing`.

package/packs/docker/rules/compose-swarm-safe.md

@@ -0,0 +1,26 @@
+---
+# concepts: compose
+paths:
+  - "placeholder"
+---
+
+# Compose files are written for Swarm from day one
+
+Compose and Swarm read the same file and interpret it differently, and Swarm fails **silently**: `docker stack deploy` skips `build`, `container_name`, `depends_on`, `links`, `restart`, `network_mode`, `cap_add`, `devices`, `tmpfs`, `extra_hosts`, `sysctls`, `security_opt` with no error.
+
+<constraints>
+Always do:
+- `init: true` on every service: tini as PID 1 forwards signals and reaps zombies. The one always missed (`compose-service-needs-init`).
+- `stop_grace_period` at least as long as the app's shutdown hard timeout (`process-lifecycle`); default is 10 s.
+- `deploy:` block on every service: `replicas`, `resources.limits` **and** `resources.reservations`, `restart_policy: { condition: on-failure }`, `update_config: { order: start-first, failure_action: rollback }`, `rollback_config`, paired with a `healthcheck` that has a `start_period`.
+- Connect by service name (`mongodb://mongo:27017`), never by IP: container IPs change on every restart, scale and update.
+- Named volumes, never host bind mounts for app data; `overlay` networks, not `bridge`.
+- Publish the container port only and let the routing mesh assign; a MongoDB replica set publishes 27017 with `mode: host`, pinned per node with placement labels.
+- Env with defaults: `image: registry/app:${BUILD_VERSION:-latest}`. Secrets through `secrets:`, non-sensitive files through `configs:`.
+- The app retries its dependencies with backoff: there is no `depends_on` on Swarm.
+
+Never do:
+- `restart:` (Swarm ignores it; use `deploy.restart_policy`), `container_name:`, `depends_on:`, `links:`, `network_mode:` (`compose-no-swarm-ignored-keys`).
+- A hardcoded IP or `ipv4_address`.
+- `exit(0)` on a crash in the app: `restart_policy: on-failure` only restarts non-zero.
+</constraints>

package/packs/docker/rules/docker-exec-form.md

@@ -0,0 +1,19 @@
+---
+# concepts: dockerfile
+paths:
+  - "placeholder"
+---
+
+# Node is PID 1 in exec form, with init, or it never hears SIGTERM
+
+<constraints>
+Always do:
+- `ENTRYPOINT ["node", "dist/index.js"]` / `CMD [...]`: exec form, a JSON array. Shell form runs `sh -c`, so `sh` is PID 1, swallows SIGTERM, and the app never shuts down cleanly or reports its exit code.
+- `init: true` in compose (or `docker run --init`) so zombies are reaped and signals forwarded.
+- `STOPSIGNAL SIGTERM` and a `stop_grace_period` at least as long as the app's shutdown hard timeout (`process-lifecycle`).
+- Run as a non-root `USER`; copy `package.json` + lockfile first and `npm ci --omit=dev` before copying source, so the dependency layer caches.
+
+Never do:
+- `CMD node dist/index.js` or `CMD npm start` (shell form, and npm adds a second process between Docker and Node). The `docker-exec-form` check refuses shell form.
+- Secrets in `ENV` or build args; they land in the image history.
+</constraints>

package/packs/docker/rules/dockerfile-multistage.md

@@ -0,0 +1,13 @@
+---
+# concepts: dockerfile
+---
+# The image is built in stages: dependencies and build, then a small runtime with production modules only
+
+<constraints>
+Always do:
+- Build in a first stage (install, compile), and copy only the output and production dependencies into a slim final stage that runs as a non-root user.
+- Pin the base images by version, and copy the lockfile before the source so the dependency layer caches.
+
+Never do:
+- Ship dev dependencies, the source tree, `.env` or the build tools in the final image.
+</constraints>

package/packs/docker/rules/dockerfile-production.md

@@ -0,0 +1,25 @@
+---
+# concepts: dockerfile
+paths:
+  - "placeholder"
+---
+
+# The image is small, pinned, non-root, and shuts down cleanly
+
+<constraints>
+Always do:
+- Multi-stage: build in a stage with the compilers, `COPY --from=build` only the artifacts into a slim runtime (`node:<exact>-slim` or `-alpine`).
+- Stable layers first: copy `package.json` + lockfile, `npm ci --omit=dev`, **then** copy source. A one-line code change must not reinstall every dependency.
+- Pin the base image to an exact version (`node:24.11.0-slim`), checked with `latest-versions`. `no-latest-base` refuses `:latest` and an unpinned tag.
+- `USER node` (or another non-root user) before the entrypoint (`dockerfile-needs-user`).
+- `HEALTHCHECK` that verifies a real dependency, not a route that always returns 200; it is what makes rolling update and rollback work.
+- `ENTRYPOINT ["node", "dist/index.js"]`: exec form, no `npm start` in between (`docker-exec-form`).
+- One `RUN apt-get update && apt-get install -y --no-install-recommends … && rm -rf /var/lib/apt/lists/*`.
+- A `.dockerignore` with `node_modules`, `.git`, `.env*`, `dist`, `coverage`, `.claude`.
+- Logs to stdout/stderr only.
+
+Never do:
+- Secrets in `ENV` or `ARG`: they live in the layers and show in `docker history` (`no-secret-in-image`). Build-time secrets use `RUN --mount=type=secret`; runtime secrets use Docker secrets or env injected at run time.
+- `COPY . .` before the dependency install.
+- Run as root, use `:latest`, or write files inside the container that must survive a restart (named volume or object storage).
+</constraints>

package/packs/docker/skills/docker-diagnose/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: docker-diagnose
+description: Use when a container will not start, exits non-zero, is OOM-killed, cannot reach another service, a port conflicts, a build fails, an image is bloated, or Docker disk is full. Runs dockerdoctor and acts on its report.
+---
+
+# docker-diagnose
+
+One thing: get the measured diagnosis from `dockerdoctor` (The Decipherist's own tool, 50 checks: 25 static, 25 runtime) and fix what it names. No guessing from the symptom.
+
+<constraints>
+Always do:
+1. `npx dockerdoctor@latest --json > .claude/state/dockerdoctor.json` from the project root (Docker must be running for the runtime checks; static ones work without it). Check the current version with `latest-versions` once per session.
+2. Read the JSON. Fix **errors** first, then warnings, in the order dockerdoctor lists them. Each result carries a `fixes[]` with a description and often code; apply the fix in the file it names.
+3. Re-run until the error count is 0. Paste the before/after counts as the evidence line (`done-means-fresh-evidence`).
+4. For a runtime finding (exit code, OOM, DNS, port conflict), quote the measured value dockerdoctor reports (the exit code, the memory limit, the resolved address) in the fix commit.
+
+Never do:
+- Edit the Dockerfile or compose file from the symptom before running dockerdoctor.
+- Apply `--fix` blindly on a compose file that is deployed to Swarm; read each fix first.
+- Disable a check instead of fixing the cause.
+</constraints>
+
+The static checks are also enforced at edit time by this pack's lesson checks (exec form, pinned base, USER, HEALTHCHECK, npm ci, layer order, secrets, init, swarm-ignored keys), so dockerdoctor should mostly report runtime findings here.

package/packs/dynamic-data/checks/draft-on-the-server.json

@@ -0,0 +1,27 @@
+{
+  "id": "draft-on-the-server",
+  "why": "A draft in localStorage is a second truth on one device. Keep it on the server, per user, so it follows them.",
+  "rule": ".claude/rules/saves-are-patches.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\b(?:localStorage|sessionStorage)\\.setItem\\([^)\\n]*(?:draft|unsaved|autosave|filters?)\\b",
+  "bad": "localStorage.setItem('draft:' + id, JSON.stringify(doc));",
+  "good": "await saveDraft(id, patch);\nsessionStorage.setItem('tab', tab);",
+  "kind": "quality",
+  "flags": "i"
+}

package/packs/dynamic-data/checks/guard-does-its-job.json

@@ -0,0 +1,28 @@
+{
+  "id": "guard-does-its-job",
+  "why": "A guard whose first line returns true lets everything through, with the real check left dead below it.",
+  "rule": ".claude/rules/rules-live-in-the-engine.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\b(?:function\\s+|(?:const|let)\\s+)(?:check|can|allow|verify|authori[sz]e|validate|has[A-Z]|is[A-Z])\\w*\\s*(?:=\\s*(?:async\\s*)?)?\\([^)]*\\)[^{;]*\\{\\s*return\\s+true\\s*;",
+  "bad": "function checkCollection(name) {\n  return true;\n  if (!ALLOWED.includes(name)) throw new Error(name);\n}",
+  "good": "function checkCollection(name) {\n  if (!ALLOWED.includes(name)) throw new Error(name);\n  return true;\n}",
+  "kind": "security",
+  "code": true
+}

package/packs/dynamic-data/checks/key-is-not-a-display-name.json

@@ -0,0 +1,28 @@
+{
+  "id": "key-is-not-a-display-name",
+  "why": "A display name as a tenant key orphans the data on a rename. Key on an immutable id.",
+  "rule": ".claude/rules/one-fact-one-place.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\b(?:brand|tenant|company|org|organization|account|client)(?:Name)?\\s*:\\s*[\\w.]+\\.(?:name|title|displayName|label)\\b",
+  "bad": "const row = { brand: tenant.name, sku };",
+  "good": "const row = { tenantId: tenant._id, sku };",
+  "kind": "quality",
+  "code": true
+}

package/packs/dynamic-data/checks/no-code-from-data.json

@@ -0,0 +1,29 @@
+{
+  "id": "no-code-from-data",
+  "why": "Text run as code turns a stored value or a request into code execution. Conditions belong in a closed language that nothing executes.",
+  "rule": ".claude/rules/every-dynamic-surface-has-a-boundary.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/data/**"
+  ],
+  "pattern": "\\bnew\\s+Function\\s*\\(|(?<![\\w.])eval\\s*\\(",
+  "bad": "const filters = new Function(\"return [\" + req.query.filters + \"];\")();",
+  "good": "const filters = FilterTree.parse(req.body.filters);",
+  "kind": "security",
+  "code": true
+}