<!-- Sync Impact Report
Version change: N/A → 1.0.0 (initial)
Added sections: All (5 principles, Security Standards, Development Workflow, Governance)
Templates requiring updates: N/A (initial creation)
Follow-up TODOs: None
-->

# gemma-deployment-security Constitution

## Core Principles

### I. Read-Only Auditing
All audit skills MUST be non-destructive. Skills read files and produce reports — they MUST NOT modify client repositories, server configurations, or any deployment artifacts. The audit output is a Markdown report file written to the working directory. If a skill cannot determine a finding without making changes, it MUST skip the check and note it in the audit scope section.

### II. Reference-Checklist Architecture
Every audit skill MUST derive its checks from a `references/checklist.md` file, not from inline logic in SKILL.md. The checklist is the single source of truth for what is checked, at what severity, and how to remediate. SKILL.md provides execution instructions only. This separation allows checklist updates without changing skill behavior.

### III. Prioritized, Actionable Findings
Every finding MUST include: a severity level (Critical/Important/Recommended/Nice-to-have), the exact file and location where the issue was found, a description of the risk, and a concrete remediation snippet showing before/after code. Vague advisories ("consider improving security") are prohibited. If a check cannot produce an actionable finding, it should not be in the checklist.

### IV. Graceful Degradation
Skills MUST work with whatever access is available. If SSH is unavailable, the server audit falls back to a guided checklist. If no Dockerfile exists, the Dockerfile audit is skipped (not errored). If GitHub Actions workflows are absent, the CI/CD audit is skipped. The report generator MUST document which skills ran and which were skipped, and why.

### V. Checklist Provenance
Every check in every `references/checklist.md` MUST trace back to a source: the internal security research report (2026-03-17), a specific CIS benchmark, an OWASP guideline, or a real finding from a client deployment. Checks without provenance MUST NOT be added. This prevents checklist bloat and ensures every check has a reason.

## Security Standards

- **Data protection**: Skills run on Anthropic API. They MUST NOT read `.env` files, credentials, private keys, or any file with "secret" in its path. If a check requires inspecting secret content (e.g., verifying fernet key is not a default value), the skill MUST check for the *pattern* (hardcoded in source code, present in Dockerfile ENV) without reading the actual secret value.
- **Client confidentiality**: Audit reports may contain client-specific file paths, hostnames, and configuration details. Reports MUST NOT be committed to the agentic toolkit repo or any shared location. They are written to the client repo or the engineer's local working directory only.
- **No credential echoing**: Skills MUST NOT echo, log, or include actual secret values (API keys, passwords, connection strings) in findings or reports. Refer to them by type ("the fernet key is hardcoded at Dockerfile:14") not by value.

## Development Workflow

- **Skill creation**: Use `skill-creator:skill-creator` to write and validate each skill. Each SKILL.md MUST be under 500 lines; detailed checks go in `references/checklist.md`.
- **Checklist format**: Each check in `references/checklist.md` follows this structure:
  ```markdown
  ## Check: [Short name]
  - **Priority**: Critical | Important | Recommended | Nice-to-have
  - **What to look for**: [Pattern or condition to detect]
  - **Pass condition**: [What "good" looks like]
  - **Fail example**: [Concrete bad pattern]
  - **Remediation**: [How to fix, with code snippet]
  - **Source**: [Section reference from security report or other source]
  ```
- **Testing**: Each skill is tested by running it against a known-insecure reference (e.g., `airflow3-demo/docker-compose.yaml`, `gemma-airflow/Dockerfile`) and verifying it catches expected findings.
- **Plugin conventions**: Follow all conventions in `gemma-agentic-toolkit/CLAUDE.md` — kebab-case names, YAML frontmatter, `${CLAUDE_SKILL_DIR}` references, conventional commits.

## Governance

- This constitution governs all development of the `gemma-deployment-security` plugin.
- Amendments require updating this file, incrementing the version, and documenting changes in the Sync Impact Report header.
- All skills MUST be reviewed against these principles before merge.
- Checklist additions MUST cite their source (Principle V).
- Version follows semver: MAJOR for principle changes, MINOR for new sections, PATCH for clarifications.

**Version**: 1.0.0 | **Ratified**: 2026-04-15 | **Last Amended**: 2026-04-15