Functional specification

Users and jobs to be done

PersonaJobFeature
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

  1. Risky deployment: replicas, image, service account, host networking and privileged flags change. The review lists each change with line numbers and blocks.
  2. Public exposure: Service ClusterIP to LoadBalancer raises DS-K8S-001 and is worded as potential exposure, never verified reachability.
  3. Plan import: exported OpenTofu/Terraform JSON becomes action counts per resource type. A destructive change on a data-bearing type blocks.
  4. Readiness packet: missing rollback evidence blocks even a clean manifest; fully declared evidence still yields HUMAN_REVIEW_REQUIRED.
  5. CI: run offline, exit 2 on BLOCKED, upload the HTML report as an artifact.
  6. Assistant use: ask an IDE agent to run the skills or the read-only MCP tools.

Functional requirements

IDRequirementStatus
F1Read YAML/JSON manifests, multi-document, <= 1 MiB, no symlinks, <= 200 documentsImplemented, tested
F2Fail loudly on unsupported YAMLImplemented, tested
F3Diff all fields semantically, match containers by name, redact sensitive valuesImplemented, tested
F419 rules with stable IDs, severity, remediation, false-positive notesImplemented, tested
F5Profiles with explicit selection recordedImplemented, tested
F6Classify findings as new or persistent; both can blockImplemented, tested
F7Blast-radius questions and BlastMap with UNKNOWNImplemented, tested
F8Rollback prerequisites; declarations are never verificationImplemented, tested
F9Plan action summary with no state, addresses or values; replacement and truncation flaggedImplemented, tested
F10JSON, Markdown, HTML reports; sealed; verifyImplemented, tested
F11Self-audit in all three formatsImplemented, tested
F12Read-only MCP server, loopback report APIImplemented, scripted-client tested
F1325 skills / 20 agents, project-local installer for six IDE layoutsImplemented; native activation untested
F14Any deploy/apply/destroy/rollback commandExcluded by design

Commands and exit codes

CommandPurpose
analyzeCompare two snapshots (--before, --after, --rollback, --profile, --out, --format)
policyRules over one file (--fail-on LOW/MEDIUM/HIGH)
rules / explainList rules; why a rule exists, remediation, false positives
tofuSummarise a plan JSON
verifyCheck a report seal
auditIndependent self-audit (--out, --skip-tests)
doctor, --versionEnvironment facts
install-skillsCopy skills into a project for an IDE
serve, mcpLoopback 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.