@harness-engineering/cli 1.13.0 → 1.14.0

package/dist/agents/skills/gemini-cli/harness-compliance/SKILL.md

@@ -0,0 +1,303 @@
+# Harness Compliance
+
+> SOC2, HIPAA, GDPR compliance checks, audit trails, and regulatory checklists. Scans codebases for compliance-relevant patterns, classifies data by sensitivity, audits implementation against framework-specific controls, and generates gap analysis reports with remediation plans.
+
+## When to Use
+
+- At milestone boundaries to audit compliance posture before releases to regulated markets
+- On PRs that modify data handling, storage, logging, or user-facing privacy features
+- When preparing for external audits (SOC2 Type II, HIPAA assessment, GDPR DPA review)
+- NOT for runtime security scanning or vulnerability detection (use harness-security-scan)
+- NOT for authentication or authorization implementation (use harness-auth)
+- NOT for infrastructure security hardening (use harness-security-review)
+
+## Process
+
+### Phase 1: SCAN -- Detect Applicable Frameworks and Data Patterns
+
+1. **Identify applicable compliance frameworks.** Scan for indicators:
+   - SOC2: presence of `docs/compliance/soc2/`, audit logging implementation, access control patterns
+   - HIPAA: healthcare-related data models (patient, diagnosis, prescription), PHI field markers
+   - GDPR: EU user data handling, consent collection, cookie banners, privacy policy references
+   - PCI-DSS: payment processing, credit card fields, tokenization, PCI scope markers
+   - Detect from existing compliance documentation, data models, and configuration files
+
+2. **Inventory data stores.** Map all locations where user data is persisted:
+   - Databases: table schemas, column names, migration files
+   - Object storage: S3 buckets, GCS buckets, Azure Blob containers
+   - Caches: Redis keys, Memcached namespaces
+   - Log files: structured logging output, log aggregation configuration
+   - Third-party services: analytics (Segment, Mixpanel), CRM (Salesforce, HubSpot), email (SendGrid, Mailchimp)
+
+3. **Trace data flows.** Map how user data moves through the system:
+   - Ingestion: API endpoints that accept user input, form submissions, file uploads
+   - Processing: services that transform, aggregate, or enrich user data
+   - Storage: where processed data is persisted (primary database, cache, search index)
+   - Egress: data shared with third parties, exported, or displayed to other users
+   - Deletion: how data is removed when retention expires or deletion is requested
+
+4. **Check for existing compliance artifacts.** Look for:
+   - Privacy policy: `PRIVACY.md`, `privacy-policy.md`, or served via web route
+   - Security policy: `SECURITY.md`, security disclosure process
+   - Data processing agreements: `docs/compliance/dpa/`
+   - Audit trail implementation: `src/**/audit/**`, event sourcing patterns
+   - Consent management: cookie consent banners, preference centers
+
+5. **Detect sensitive data patterns.** Grep for fields and patterns that indicate regulated data:
+   - PII: email, phone, address, SSN, date of birth, government ID
+   - PHI: diagnosis, treatment, prescription, medical record number, insurance ID
+   - Financial: credit card number, bank account, routing number, transaction amount
+   - Authentication: password (even hashed), API key, secret, token
+
+---
+
+### Phase 2: CLASSIFY -- Data Sensitivity and Regulatory Scope
+
+1. **Classify data fields by sensitivity.** Apply a tiered classification:
+   - **Critical:** Data whose exposure triggers mandatory breach notification (SSN, credit card, PHI)
+   - **Sensitive:** PII that identifies individuals (email, phone, address, name + DOB)
+   - **Internal:** Business data not publicly available (order history, usage metrics, preferences)
+   - **Public:** Data intentionally shared (username, public profile, published content)
+
+2. **Map regulatory scope per data class.** Determine which frameworks apply to each data class:
+   - Critical financial data -> PCI-DSS scope
+   - PHI data -> HIPAA scope
+   - EU resident PII -> GDPR scope
+   - All customer data in a SOC2-audited system -> SOC2 scope
+
+3. **Identify cross-border data flows.** For GDPR compliance:
+   - Where are data stores physically located? (AWS region, GCP region, Azure region)
+   - Does data transfer to non-EU countries? (US servers, CDN nodes, third-party processors)
+   - Are Standard Contractual Clauses (SCCs) or adequacy decisions in place?
+   - Is data residency configurable per tenant?
+
+4. **Document data retention policies.** For each data class:
+   - What is the defined retention period?
+   - Is automatic deletion implemented (TTL, scheduled job, lifecycle policy)?
+   - What happens to data in backups after retention expires?
+   - Are retention policies documented and accessible?
+
+5. **Produce the data classification matrix.** Output a structured inventory:
+   - Data field, classification tier, applicable frameworks, storage location, retention policy, encryption status
+
+---
+
+### Phase 3: AUDIT -- Check Against Framework Controls
+
+1. **SOC2 Trust Services Criteria audit.** Check implementation against key controls:
+   - **CC6.1 (Logical Access):** Are all endpoints authenticated? Is RBAC/ABAC enforced?
+   - **CC6.2 (Credential Management):** Are passwords hashed with strong algorithms? Is MFA available?
+   - **CC6.3 (Encryption):** Is data encrypted at rest (database, file storage) and in transit (TLS)?
+   - **CC7.2 (System Monitoring):** Are security events logged? Are alerts configured for anomalies?
+   - **CC8.1 (Change Management):** Is there a code review process? Are deployments auditable?
+
+2. **HIPAA Security Rule audit.** If PHI is present:
+   - **164.312(a)(1) Access Control:** Unique user identification, emergency access, automatic logoff, encryption
+   - **164.312(b) Audit Controls:** Record and examine activity in information systems containing PHI
+   - **164.312(c)(1) Integrity:** Protect electronic PHI from improper alteration or destruction
+   - **164.312(d) Authentication:** Verify identity of person or entity seeking access to PHI
+   - **164.312(e)(1) Transmission Security:** Encrypt PHI during electronic transmission
+
+3. **GDPR compliance audit.** If EU data is processed:
+   - **Article 6 (Lawful Basis):** Is consent collected? Is legitimate interest documented?
+   - **Article 13/14 (Transparency):** Is a privacy notice provided at data collection points?
+   - **Article 15 (Right of Access):** Can users export their data? Is there a data export endpoint?
+   - **Article 17 (Right to Erasure):** Can users request deletion? Is it implemented across all stores?
+   - **Article 25 (Data Protection by Design):** Are privacy defaults enforced (minimal data collection)?
+   - **Article 30 (Records of Processing):** Is there a processing activities register?
+   - **Article 32 (Security of Processing):** Encryption, pseudonymization, resilience, regular testing
+   - **Article 33 (Breach Notification):** Is there a 72-hour breach notification process?
+
+4. **PCI-DSS audit.** If payment data is present:
+   - **Requirement 3:** Is cardholder data encrypted at rest? Is PAN masked in displays?
+   - **Requirement 4:** Is cardholder data encrypted in transit?
+   - **Requirement 6:** Are secure development practices followed? Is input validated?
+   - **Requirement 8:** Is access to cardholder data authenticated and authorized?
+   - **Requirement 10:** Are all access events to cardholder data logged?
+
+5. **Audit trail verification.** For all applicable frameworks:
+   - Are audit events immutable (append-only log, write-once storage)?
+   - Do audit records include who, what, when, where, and outcome?
+   - Is the audit log protected from tampering (separate access controls, checksums)?
+   - Is the audit log retained for the required period (SOC2: 1 year, HIPAA: 6 years, GDPR: varies)?
+
+---
+
+### Phase 4: REPORT -- Generate Gap Analysis and Remediation Plan
+
+1. **Score compliance posture per framework.** For each applicable framework:
+   - Total controls assessed
+   - Controls fully met, partially met, and not met
+   - Overall compliance percentage
+   - Risk rating: High (critical controls missing), Medium (non-critical gaps), Low (minor gaps)
+
+2. **Produce the gap analysis.** For each control not fully met:
+   - Control identifier and description
+   - Current implementation status (not started, partial, misconfigured)
+   - Specific code locations or configurations that need change
+   - Remediation steps with effort estimate (hours/days)
+   - Priority based on risk and audit timeline
+
+3. **Generate audit-ready checklists.** Produce framework-specific checklists:
+   - SOC2: Trust Services Criteria checklist with evidence references
+   - HIPAA: Security Rule safeguard checklist with implementation status
+   - GDPR: Article-by-article compliance checklist with data flow references
+   - PCI-DSS: Requirement checklist with scope boundaries
+
+4. **Create remediation plan.** Organize gaps into actionable work:
+   - **Phase 1 (Critical, 0-2 weeks):** Fix blocking gaps that would fail an audit
+   - **Phase 2 (Important, 2-6 weeks):** Address significant gaps that reduce compliance posture
+   - **Phase 3 (Improvement, 6-12 weeks):** Enhance documentation, monitoring, and process maturity
+   - Each item includes: description, affected control, owner placeholder, effort estimate
+
+5. **Output the compliance report.** Generate `docs/compliance/audit-report-YYYY-MM-DD.md`:
+
+   ```
+   Compliance Audit Report — YYYY-MM-DD
+
+   Frameworks Assessed: SOC2, GDPR
+   Data Classifications: 12 critical, 28 sensitive, 45 internal, 15 public
+
+   SOC2 Status: 78% (18/23 controls met, 3 partial, 2 not met)
+     NOT MET:
+       CC7.2 — No security event alerting configured
+       CC8.1 — No deployment audit trail
+     PARTIAL:
+       CC6.1 — RBAC exists but 4 endpoints lack authorization checks
+       CC6.3 — TLS in transit, but database encryption at rest not configured
+       CC6.2 — Passwords hashed, but no MFA available
+
+   GDPR Status: 65% (11/17 controls met, 4 partial, 2 not met)
+     NOT MET:
+       Article 17 — No data deletion endpoint implemented
+       Article 30 — No processing activities register
+     PARTIAL:
+       Article 15 — Data export exists but incomplete (missing analytics data)
+       ...
+
+   Remediation Plan: 7 items (2 critical, 3 important, 2 improvement)
+   Estimated total effort: 45 engineering-hours
+   ```
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-compliance`** -- Primary CLI entry point. Runs all four phases.
+- **`harness validate`** -- Run after generating compliance artifacts to verify project structure.
+- **`harness check-deps`** -- Verify that compliance-related dependencies (audit logging libraries, encryption modules) are declared.
+- **`emit_interaction`** -- Used at framework selection (checkpoint:decision) when multiple frameworks apply and the team wants to prioritize, and at remediation plan review (checkpoint:human-verify).
+- **`Glob`** -- Discover compliance documentation, audit trail implementations, privacy policies, and data models.
+- **`Grep`** -- Search for PII field patterns, encryption configurations, consent collection, logging patterns, and sensitive data handling.
+- **`Write`** -- Generate compliance reports, audit checklists, and remediation plans.
+- **`Edit`** -- Update existing compliance documentation with current audit status.
+
+## Success Criteria
+
+- All applicable compliance frameworks are identified with justification for inclusion
+- Data classification matrix covers all persisted user data fields with sensitivity tier and storage location
+- Audit checks reference specific framework control identifiers (SOC2 CC6.1, GDPR Article 17, etc.)
+- Gap analysis includes specific file locations and code references, not just abstract control descriptions
+- Remediation plan items have effort estimates and are prioritized by risk and audit timeline
+- Audit-ready checklists can be handed directly to an external auditor as evidence documentation
+
+## Examples
+
+### Example: SaaS Application with SOC2 and GDPR Requirements
+
+```
+Phase 1: SCAN
+  Frameworks detected:
+    - SOC2: docs/compliance/soc2/ directory exists, audit logging in src/audit/
+    - GDPR: EU customers present (detected from i18n locales and privacy policy)
+    - PCI-DSS: Not applicable (payments via Stripe, card data never touches servers)
+  Data stores: PostgreSQL (primary), Redis (cache/sessions), S3 (file uploads)
+  Third-party processors: Stripe, SendGrid, Segment, Datadog
+
+Phase 2: CLASSIFY
+  Critical: None (no SSN, card data handled by Stripe)
+  Sensitive: email, phone, address (users table), IP address (access_logs)
+  Internal: order_history, preferences, usage_metrics
+  Public: username, display_name, avatar_url
+  Cross-border: Primary DB in us-east-1, CDN globally, Segment data to US
+  GDPR gap: No SCCs documented for US-based sub-processors
+
+Phase 3: AUDIT
+  SOC2: 78% compliant (18/23)
+    CC6.3 — PostgreSQL not using column-level encryption for sensitive fields
+    CC7.2 — Datadog alerts exist but no security-specific monitors
+  GDPR: 65% compliant (11/17)
+    Article 17 — DELETE /api/users/:id exists but does not cascade to S3 files or Segment
+    Article 30 — No Records of Processing Activities document
+
+Phase 4: REPORT
+  Generated: docs/compliance/audit-report-2026-03-27.md
+  Remediation plan:
+    Critical (week 1-2):
+      1. Implement cascading deletion across PostgreSQL, S3, Segment, SendGrid
+      2. Create Records of Processing Activities document
+    Important (week 3-6):
+      3. Add column-level encryption for email, phone, address fields
+      4. Create security-specific Datadog monitors for auth failures
+      5. Document SCCs for all US-based sub-processors
+    Improvement (week 7-12):
+      6. Implement data export endpoint including Segment analytics data
+      7. Add automated retention enforcement with TTL-based cleanup jobs
+```
+
+### Example: Healthcare Platform with HIPAA Requirements
+
+```
+Phase 1: SCAN
+  Frameworks detected:
+    - HIPAA: patient, diagnosis, prescription models in src/models/
+    - SOC2: Required by enterprise customers, docs/compliance/soc2/ present
+  Data stores: PostgreSQL (primary), Redis (session cache), AWS S3 (medical records)
+  Third-party processors: Twilio (patient notifications), AWS (infrastructure)
+  BAA status: AWS BAA signed, Twilio BAA signed
+
+Phase 2: CLASSIFY
+  Critical (PHI):
+    - patient_records: name, DOB, SSN, diagnosis_code, treatment_plan
+    - prescriptions: medication, dosage, prescribing_physician
+    - medical_images: stored in S3 bucket 'patient-records-prod'
+  Sensitive: provider email, staff credentials, appointment schedules
+  PHI field count: 23 fields across 8 tables
+
+Phase 3: AUDIT
+  HIPAA Security Rule: 72% compliant
+    164.312(a)(1) — Access control exists but no automatic session logoff
+    164.312(b) — Audit log captures reads but not all PHI access events
+    164.312(c)(1) — No integrity checksums on medical records in S3
+    164.312(e)(1) — TLS 1.2 in transit, AES-256 at rest in PostgreSQL and S3
+  SOC2: 81% compliant
+    All findings overlap with HIPAA gaps
+
+Phase 4: REPORT
+  Generated: docs/compliance/hipaa-audit-2026-03-27.md
+  Remediation plan:
+    Critical (week 1-2):
+      1. Add automatic session timeout (15 min idle) for clinical users
+      2. Extend audit logging to capture all PHI read events with user context
+      3. Add SHA-256 integrity checksums to S3 medical record objects
+    Important (week 3-6):
+      4. Implement minimum necessary access — restrict PHI queries to treating providers
+      5. Add PHI access review report for compliance officer (monthly)
+    Improvement (week 7-12):
+      6. Implement emergency access ("break the glass") with post-access audit
+      7. Add automated HIPAA compliance regression tests to CI pipeline
+```
+
+## Gates
+
+- **No compliance report without data classification.** A compliance audit that does not inventory and classify data fields is incomplete. The classification matrix must be produced before controls can be meaningfully assessed. Without knowing what data exists and where, control checks are theoretical.
+- **No critical control gaps left without remediation plan.** Every control marked "not met" must have a corresponding remediation item with effort estimate and priority. Identifying gaps without a path to closure is shelf-ware.
+- **No PII/PHI field handling changes without re-audit.** When a PR adds or modifies fields classified as sensitive or critical, the compliance audit for affected frameworks must be re-run. Data handling changes can invalidate previous compliance assessments.
+- **No third-party data sharing without documented basis.** Every third-party that receives user data must have a documented lawful basis (GDPR), BAA (HIPAA), or be within scope boundaries (SOC2/PCI-DSS). Undocumented data sharing is a blocking compliance gap.
+
+## Escalation
+
+- **When compliance requirements conflict with business timelines:** Report: "The GDPR Article 17 implementation requires [N] engineering-hours and touches [M] services. If the audit deadline is [date], recommend prioritizing the critical controls and documenting a remediation timeline for the remaining gaps. Partial compliance with a credible plan is better than no plan."
+- **When legal interpretation is needed:** Report: "The application of [specific regulation article] to [specific data handling pattern] requires legal interpretation. This skill identifies technical implementation gaps but cannot determine legal applicability. Recommend consulting with legal counsel on [specific question]."
+- **When third-party processors lack required agreements:** Report: "[Processor] handles [data type] but no [BAA/DPA/SCC] is on file. This is a blocking compliance gap. Options: (1) execute the required agreement with the processor, (2) migrate to an alternative processor with agreements in place, (3) stop sending regulated data to this processor."
+- **When audit trail implementation requires significant architecture changes:** Report: "The current logging infrastructure does not support immutable, tamper-evident audit trails required by [framework]. Options: (1) add append-only audit table with separate write credentials, (2) use a dedicated audit service (e.g., AWS CloudTrail, custom event store), (3) adopt event sourcing for regulated data flows. Effort estimate: [N] weeks."

package/dist/agents/skills/gemini-cli/harness-compliance/skill.yaml

@@ -0,0 +1,78 @@
+name: harness-compliance
+version: "1.0.0"
+description: SOC2, HIPAA, GDPR compliance checks, audit trails, and regulatory checklists
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_milestone
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-compliance
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: framework
+      description: "Compliance framework: soc2, hipaa, gdpr, pci-dss, or all. Defaults to all detected."
+      required: false
+    - name: scope
+      description: "Audit scope: full, changed-only, or data-flows. Defaults to full."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-compliance
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - compliance
+  - SOC2
+  - HIPAA
+  - GDPR
+  - PCI-DSS
+  - audit trail
+  - data retention
+  - privacy
+  - PII
+  - data classification
+  - right to deletion
+  - consent
+  - DPA
+stack_signals:
+  - "docs/compliance/"
+  - "audit/"
+  - "src/**/audit/**"
+  - "src/**/*gdpr*"
+  - "src/**/*privacy*"
+  - "SECURITY.md"
+  - "PRIVACY.md"
+phases:
+  - name: scan
+    description: Detect applicable compliance frameworks and inventory data handling patterns
+    required: true
+  - name: classify
+    description: Classify data by sensitivity, identify PII flows, and map regulatory scope
+    required: true
+  - name: audit
+    description: Check implementation against framework-specific control requirements
+    required: true
+  - name: report
+    description: Generate compliance gap analysis, remediation plan, and audit-ready documentation
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/harness-containerization/SKILL.md

@@ -0,0 +1,284 @@
+# Harness Containerization
+
+> Dockerfile review, Kubernetes manifest validation, and container optimization. Smaller images, safer containers, correct orchestration.
+
+## When to Use
+
+- When reviewing Dockerfiles for image size, security, and layer efficiency
+- When auditing Kubernetes manifests, Helm charts, or docker-compose files
+- On PRs that modify container configuration files
+- NOT for CI/CD pipeline design (use harness-deployment)
+- NOT for infrastructure provisioning (use harness-infrastructure-as-code)
+- NOT for application-level security review (use harness-security-review)
+
+## Process
+
+### Phase 1: SCAN -- Discover Container Configuration
+
+1. **Locate container files.** Search the project for container-related configuration:
+   - `Dockerfile`, `Dockerfile.*` (multi-target builds)
+   - `docker-compose.yml`, `docker-compose.*.yml` (override files)
+   - `.dockerignore`
+   - `k8s/`, `kubernetes/`, `manifests/` directories
+   - `helm/`, `charts/` directories
+   - `skaffold.yaml`, `tilt.json` (dev tooling)
+
+2. **Identify base images.** Parse each Dockerfile for FROM directives:
+   - Record base image name, tag, and digest (if pinned)
+   - Flag images using `latest` tag
+   - Flag images from untrusted registries
+   - Note multi-stage build structure (builder vs. runtime stages)
+
+3. **Inventory Kubernetes resources.** Parse manifest files and record:
+   - Resource types (Deployment, Service, ConfigMap, Secret, Ingress, HPA)
+   - Namespaces used
+   - Image references in pod specs
+   - Resource requests and limits
+   - Volume mounts and persistent volume claims
+
+4. **Detect Helm usage.** If Helm charts exist:
+   - Parse `Chart.yaml` for version and dependencies
+   - Parse `values.yaml` for configurable parameters
+   - Identify template files and their output resource types
+
+5. **Present scan summary:**
+
+   ```
+   Container Scan:
+     Dockerfiles: 2 (app, worker)
+     Compose files: 1 (docker-compose.yml + docker-compose.dev.yml)
+     K8s manifests: 8 resources across 2 namespaces
+     Helm charts: 1 (app chart with 3 subcharts)
+     Base images: node:20-alpine, python:3.12-slim
+   ```
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Best Practices
+
+1. **Analyze Dockerfile layer efficiency.** Check each Dockerfile for:
+   - COPY/ADD placement relative to dependency installation (cache busting)
+   - Multi-stage builds separating build dependencies from runtime
+   - Layer count optimization (combining related RUN commands)
+   - Unnecessary files copied into the image (node_modules, .git, tests)
+   - `.dockerignore` completeness
+
+2. **Check container security posture.** Evaluate:
+   - Running as non-root user (USER directive present)
+   - No secrets in build args or environment variables
+   - Base image currency (is the tag reasonably current)
+   - HEALTHCHECK directive present
+   - Read-only filesystem where possible
+   - No privileged mode in compose or K8s specs
+   - Security contexts in Kubernetes pod specs (runAsNonRoot, readOnlyRootFilesystem)
+
+3. **Evaluate Kubernetes resource definitions.** For each Deployment/StatefulSet:
+   - Resource requests and limits are set (CPU and memory)
+   - Liveness and readiness probes are configured
+   - Pod disruption budgets exist for production workloads
+   - Horizontal pod autoscaler is configured where appropriate
+   - Image pull policy is set (Always for mutable tags, IfNotPresent for digests)
+
+4. **Analyze docker-compose configuration.** Check for:
+   - Service dependency ordering (depends_on with health checks)
+   - Volume mount correctness (host paths vs. named volumes)
+   - Network isolation between services
+   - Environment variable management (env_file vs. inline)
+   - Port mapping conflicts
+
+5. **Check image tag strategy.** Verify:
+   - Production images use immutable tags (semver or digest)
+   - Development images use descriptive tags (branch name, commit SHA)
+   - No `latest` tag in production manifests
+   - Registry URL is consistent across all references
+
+---
+
+### Phase 3: OPTIMIZE -- Recommend Improvements
+
+1. **Recommend image size reduction.** For each Dockerfile:
+   - Switch to minimal base images (alpine, distroless, scratch)
+   - Remove build-only dependencies in multi-stage builds
+   - Use `.dockerignore` to exclude test files, docs, and dev configs
+   - Estimate size savings for each recommendation
+
+2. **Recommend build performance improvements.**
+   - Reorder COPY directives to maximize layer cache hits
+   - Use BuildKit features (cache mounts for package managers)
+   - Split slow-changing layers (OS packages) from fast-changing layers (app code)
+   - Example for Node.js:
+
+     ```dockerfile
+     # Good: dependency layer cached separately
+     COPY package.json package-lock.json ./
+     RUN npm ci --production
+     COPY src/ ./src/
+     ```
+
+3. **Recommend Kubernetes improvements.**
+   - Add missing resource limits with reasonable defaults
+   - Configure probes with appropriate initial delays and periods
+   - Add pod anti-affinity for high-availability workloads
+   - Recommend namespace isolation for multi-tenant clusters
+   - Add network policies to restrict pod-to-pod communication
+
+4. **Recommend security hardening.**
+   - Add non-root USER directive with specific UID
+   - Add security context to Kubernetes pods
+   - Pin base images to digest for supply chain security
+   - Remove unnecessary capabilities (drop ALL, add only what is needed)
+
+5. **Generate optimization summary with estimated impact:**
+
+   ```
+   Optimization Summary:
+     Image size: 850MB -> ~180MB (switch to alpine + multi-stage)
+     Build time: ~4m -> ~2m (layer reordering + cache mounts)
+     Security: 3 findings (non-root, capabilities, image pinning)
+     K8s: 5 resources missing resource limits
+   ```
+
+---
+
+### Phase 4: VALIDATE -- Verify Configuration Correctness
+
+1. **Validate Dockerfile syntax.** Run `docker build --check` or parse for common errors:
+   - Invalid instruction ordering (e.g., CMD before COPY)
+   - Missing required arguments
+   - Deprecated instructions (MAINTAINER)
+   - Shell form vs. exec form for CMD/ENTRYPOINT
+
+2. **Validate Kubernetes manifests.** Check for:
+   - Valid YAML structure
+   - Required fields present (apiVersion, kind, metadata, spec)
+   - Label selectors match between Deployment and Service
+   - Port numbers are consistent across Service and container specs
+   - ConfigMap and Secret references resolve to existing resources
+
+3. **Validate Helm charts.** If Helm is used:
+   - `helm lint` passes
+   - Template rendering with default values produces valid manifests
+   - Values schema matches actual usage in templates
+   - Dependencies are declared and version-locked
+
+4. **Validate docker-compose.** Check for:
+   - Valid YAML and compose file version
+   - All referenced images exist or have build contexts
+   - Port mappings do not conflict
+   - Named volumes are declared in the top-level volumes section
+   - Networks are declared before use
+
+5. **Generate validation report:**
+
+   ```
+   Container Validation: [PASS/WARN/FAIL]
+
+   Dockerfiles: PASS (2/2 valid)
+   K8s manifests: WARN (label mismatch in worker-service.yaml)
+   Helm chart: PASS (lint clean)
+   Compose: PASS (valid structure)
+
+   Issues:
+     1. k8s/worker-service.yaml: selector "app: worker" does not match
+        deployment label "app: worker-v2" -- requests will not route
+   ```
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-containerization`** -- Primary invocation for container review.
+- **`harness validate`** -- Run after configuration changes to verify project health.
+- **`harness check-deps`** -- Verify container tooling dependencies are available.
+- **`emit_interaction`** -- Present optimization recommendations and gather decisions.
+
+## Success Criteria
+
+- All container configuration files in the project are discovered and cataloged
+- Dockerfiles are analyzed for layer efficiency, security, and size
+- Kubernetes manifests are validated for correctness and best practices
+- Resource requests and limits are verified for all production workloads
+- Image tag strategy is evaluated (no `latest` in production)
+- Optimization recommendations include estimated impact
+
+## Examples
+
+### Example: Node.js Monorepo with Docker and Kubernetes
+
+```
+Phase 1: SCAN
+  Found: Dockerfile (app), Dockerfile.worker, docker-compose.dev.yml
+  K8s: 12 manifests in k8s/ (2 Deployments, 2 Services, 2 ConfigMaps,
+       2 HPA, 2 Ingress, 2 PDB)
+  Base images: node:20 (not alpine), node:20 (worker)
+
+Phase 2: ANALYZE
+  Dockerfile issues:
+    - node:20 full image (940MB) -- use node:20-alpine (180MB)
+    - No .dockerignore -- node_modules and .git copied into image
+    - No USER directive -- running as root
+    - No HEALTHCHECK
+  K8s issues:
+    - worker deployment missing memory limits
+    - No network policies defined
+    - Liveness probe on /healthz but no readiness probe
+
+Phase 3: OPTIMIZE
+  1. Switch to node:20-alpine -- saves ~760MB per image
+  2. Add .dockerignore with node_modules, .git, tests, docs
+  3. Add multi-stage build: builder stage for npm ci, runtime for app
+  4. Add USER node (UID 1000) after COPY
+  5. Add readiness probe on /ready endpoint
+  6. Add memory limit of 512Mi to worker deployment
+
+Phase 4: VALIDATE
+  Dockerfiles: WARN (2 security findings, 1 size finding)
+  K8s manifests: WARN (missing limits, missing readiness probe)
+  Compose: PASS
+  Result: WARN -- 6 actionable improvements identified
+```
+
+### Example: Python FastAPI with Helm and Distroless
+
+```
+Phase 1: SCAN
+  Found: Dockerfile (multi-stage with distroless runtime)
+  Helm chart: charts/api/ with values.yaml
+  Base images: python:3.12-slim (builder), gcr.io/distroless/python3 (runtime)
+
+Phase 2: ANALYZE
+  Dockerfile: Well-structured multi-stage build
+    - Builder installs dependencies, runtime copies only venv
+    - Distroless base (no shell, minimal attack surface)
+    - Non-root user configured
+  Helm:
+    - Resource limits set in values.yaml
+    - Probes configured with appropriate timeouts
+    - HPA configured for 2-10 replicas
+
+Phase 3: OPTIMIZE
+  Minor recommendations only:
+    - Pin distroless image to digest for reproducibility
+    - Add --mount=type=cache for pip downloads in builder stage
+    - Add pod anti-affinity to spread replicas across nodes
+
+Phase 4: VALIDATE
+  Dockerfile: PASS
+  Helm lint: PASS
+  Template render: PASS (all values resolve)
+  Result: PASS -- well-configured container setup
+```
+
+## Gates
+
+- **No `latest` tag in production manifests.** Production Kubernetes manifests or compose files using `latest` image tags are blocking findings. Immutable tags or digests are required.
+- **No containers running as root in production.** Missing USER directive in Dockerfiles or missing security context in K8s pods targeting production are blocking findings.
+- **No missing resource limits in production.** Kubernetes Deployments without CPU and memory limits are blocking warnings for production namespaces.
+- **No invalid manifest references.** Label selector mismatches between Services and Deployments, or ConfigMap/Secret references to nonexistent resources, are blocking errors.
+
+## Escalation
+
+- **When base images have known CVEs:** Flag the specific CVEs and recommend upgrading to a patched version. If no patched version exists, recommend an alternative base image and document the migration path.
+- **When Kubernetes manifest complexity exceeds review scope:** For clusters with 50+ resources, recommend focusing on changed resources only (`--changed-only` flag) and scheduling a full audit separately.
+- **When Helm chart dependencies are outdated:** Report the version gap and recommend updating. If the update includes breaking changes, flag it as a decision point and present the changelog.
+- **When docker-compose is used for production:** Flag this as an architectural concern. Docker Compose is appropriate for development but production workloads should use an orchestrator (Kubernetes, ECS, Cloud Run). Present migration options.