Functional specification
Users and jobs to be done
| Persona | Job | Feature |
|---|---|---|
| DevOps engineer | "What did my change actually alter?" | analyze diff with file:line |
| Platform engineer | "Enforce guardrails" | rules, profiles, policy --fail-on |
| Release manager | "Can I defend this gate?" | gate + reasons, sealed reports |
| SRE | "Can we roll back?" | rollback evidence model |
| Security reviewer | "Did exposure or privilege change?" | DS-K8S-001..005, 012..015, RBAC rules |
| CI maintainer | "Fail the build, no secrets" | exit code 2, offline, no credentials |
Journeys
- Risky deployment: replicas, image, service account, host networking and privileged flags change. The review lists each change with line numbers and blocks.
- Public exposure: Service
ClusterIPtoLoadBalancerraises DS-K8S-001 and is worded as potential exposure, never verified reachability. - Plan import: exported OpenTofu/Terraform JSON becomes action counts per resource type. A destructive change on a data-bearing type blocks.
- Readiness packet: missing rollback evidence blocks even a clean manifest; fully declared evidence still yields
HUMAN_REVIEW_REQUIRED. - CI: run offline, exit 2 on BLOCKED, upload the HTML report as an artifact.
- Assistant use: ask an IDE agent to run the skills or the read-only MCP tools.
Functional requirements
| ID | Requirement | Status |
|---|---|---|
| F1 | Read YAML/JSON manifests, multi-document, <= 1 MiB, no symlinks, <= 200 documents | Implemented, tested |
| F2 | Fail loudly on unsupported YAML | Implemented, tested |
| F3 | Diff all fields semantically, match containers by name, redact sensitive values | Implemented, tested |
| F4 | 19 rules with stable IDs, severity, remediation, false-positive notes | Implemented, tested |
| F5 | Profiles with explicit selection recorded | Implemented, tested |
| F6 | Classify findings as new or persistent; both can block | Implemented, tested |
| F7 | Blast-radius questions and BlastMap with UNKNOWN | Implemented, tested |
| F8 | Rollback prerequisites; declarations are never verification | Implemented, tested |
| F9 | Plan action summary with no state, addresses or values; replacement and truncation flagged | Implemented, tested |
| F10 | JSON, Markdown, HTML reports; sealed; verify | Implemented, tested |
| F11 | Self-audit in all three formats | Implemented, tested |
| F12 | Read-only MCP server, loopback report API | Implemented, scripted-client tested |
| F13 | 25 skills / 20 agents, project-local installer for six IDE layouts | Implemented; native activation untested |
| F14 | Any deploy/apply/destroy/rollback command | Excluded by design |
Commands and exit codes
| Command | Purpose |
|---|---|
analyze | Compare two snapshots (--before, --after, --rollback, --profile, --out, --format) |
policy | Rules over one file (--fail-on LOW/MEDIUM/HIGH) |
rules / explain | List rules; why a rule exists, remediation, false positives |
tofu | Summarise a plan JSON |
verify | Check a report seal |
audit | Independent self-audit (--out, --skip-tests) |
doctor, --version | Environment facts |
install-skills | Copy skills into a project for an IDE |
serve, mcp | Loopback API, MCP over stdio |
Exit codes: 0 ok, 1 error, 2 BLOCKED (or --fail-on hit), 3 report failed verification.
Non-goals
Deploying, applying, rolling back, contacting clusters or clouds, scanning images, enforcing admission, certifying compliance, rendering Helm/Kustomize.
Acceptance criteria (all covered by tests)
A risky Deployment is detected with line evidence. ClusterIP to LoadBalancer raises a static finding. A missing restore test blocks a clean manifest. A fake secret in a plan never appears in JSON, Markdown or HTML. Unsupported YAML fails explicitly. Repeated runs give identical digests. Remote bind and missing token are refused by the report server.