Document production hardening boundaries

README.md

@@ -538,6 +538,14 @@ The emphasis is on doing a smaller set of backend/platform concerns properly:
 - AWS deployment fundamentals
 - CI discipline
 
+### Commercial production boundary
+
+This repository demonstrates a production-representative AWS backend/platform slice, not a fully operated commercial production environment.
+
+The implemented slice shows the core responsibilities expected of a small real-world AWS service: private ECS task networking, RDS persistence, runtime secret injection, CloudWatch logging, CI, manual CD, smoke testing, and auditable policy enforcement.
+
+A real client production deployment would normally add further controls such as remote Terraform state, HTTPS/ACM, environment separation, monitoring and alerting, restore testing, migration version tracking, and a production credential-administration workflow. Those items are tracked as deliberate hardening boundaries rather than treated as forgotten requirements.
+
 ## Engineering roadmap
 
 Planned hardening should remain tied to production-relevant gaps.

docs/TRACKER.md

@@ -285,9 +285,14 @@ Deferred AWS hardening:
 
 - HTTPS listener with ACM certificate
 - optional HTTP-to-HTTPS redirect
-- Terraform remote state backend
+- Terraform remote state backend with locking
+- separate Terraform state/configuration for dev, staging, and production
+- fuller CloudWatch alarms, dashboards, and alerting
+- documented RDS backup/restore verification
 - migration version tracking
-- production-grade credential registration/rotation workflow
+- production-grade registered-agent credential registration and rotation workflow
+- formal IAM/security review evidence
+- fuller post-deploy MCP smoke checks in the CD/runbook flow
 
 ---
 

docs/aws_deployment_target.md

@@ -48,6 +48,34 @@ The application code should continue reading configuration through the existing
 
 The current AWS deployment runs the existing service using RDS-backed configuration, CloudWatch logging, private ECS task networking, and VPC endpoints for required AWS-service access.
 
+## Production completeness boundary
+
+This AWS deployment is production-representative, not production-complete.
+
+It demonstrates the core infrastructure pattern required for a small real-world Python backend service:
+
+- public Application Load Balancer as the controlled ingress point
+- ECS/Fargate app tasks running in private app subnets
+- RDS PostgreSQL running in private DB subnets
+- private AWS-service access through VPC endpoints
+- runtime secrets injected from Secrets Manager
+- CloudWatch log capture
+- Terraform-managed infrastructure
+- manual GitHub Actions CD into ECS
+
+A commercial production deployment would normally add further operational controls, including:
+
+- HTTPS with ACM certificate and optional HTTP-to-HTTPS redirect
+- remote Terraform state with locking
+- separate environment/state management for dev, staging, and production
+- fuller monitoring, alarms, and operational alerting
+- documented backup and restore testing
+- migration version tracking
+- production-grade credential registration and rotation workflow
+- formal IAM/security review evidence
+
+These items are deliberately documented as production-hardening boundaries rather than implemented immediately. The project focuses on a complete, auditable AWS runtime slice that demonstrates the main backend/platform responsibilities without expanding into full enterprise operations.
+
 ## Deferred scope
 
 Credential brokerage, STS-based tool credentials, S3-backed document reads, admin API, and advanced concurrency testing are deferred until the baseline deployment is working.

docs/aws_operator_runbook.md

@@ -447,8 +447,12 @@ The current AWS environment is a development/portfolio deployment.
 Known non-production limitations:
 
 - HTTP only; HTTPS/ACM is not yet configured.
-- Terraform state is currently local, not remote S3-backed state.
+- Terraform state is currently local, not remote S3-backed state with locking.
+- The deployment is single-environment rather than separated into dev, staging, and production.
 - RDS migration version tracking is not yet implemented.
+- RDS backups are configured through the database service, but restore testing is not documented as part of this project.
+- CloudWatch logging is implemented, but production alarms, dashboards, and alerting are not yet configured.
 - Dev credential registration is operational-script based, not a production admin workflow.
 - No NAT Gateway is currently deployed; this is acceptable for the current AWS-service-only egress model, but would need revisiting if the app calls external APIs.
-- Post-deploy smoke testing currently checks `/health`; fuller MCP smoke checks remain manual.
+- Post-deploy smoke testing currently checks `/health`; fuller MCP smoke checks remain manual.
+- Formal IAM/security review evidence is not packaged in the repo.

docs/aws_terraform_deployment_sequence.md

@@ -953,4 +953,16 @@ The infrastructure must explicitly define:
 
 The Mermaid diagram shows the bones.
 
-The Terraform resources define the tissue, routes, attachment points, permissions, and runtime wiring that make the architecture actually work.
+The Terraform resources define the tissue, routes, attachment points, permissions, and runtime wiring that make the architecture actually work.
+
+## Production hardening deliberately deferred
+
+This deployment sequence records the implemented AWS/Terraform build path for the current production-representative portfolio slice.
+
+The sequence does not claim to implement every control expected in a full commercial production environment. Production hardening items such as HTTPS/ACM, Terraform remote state, multi-environment state separation, restore testing, monitoring/alerting, migration version tracking, and production credential administration are documented as deliberate boundaries in:
+
+- `docs/aws_deployment_target.md`
+- `docs/production_secret_and_state_security.md`
+- `docs/aws_operator_runbook.md`
+
+This keeps the deployment sequence focused on what was actually built, while making the remaining commercial hardening boundary explicit.

docs/production_secret_and_state_security.md

@@ -6,7 +6,7 @@ This document defines the production security approach for Terraform state and r
 
 The project rule is:
 
-> Terraform manages infrastructure.  
+> Terraform manages infrastructure.
 > Secret values are created, owned, rotated, and administered outside Terraform.
 
 This keeps the infrastructure-as-code layer separate from the sensitive runtime credential layer.
@@ -153,6 +153,14 @@ They may contain:
 
 Even without secret values, state should not be public or committed to Git.
 
+### Current project boundary
+
+Remote Terraform state is documented here as the production recommendation, but it is not currently implemented for this portfolio/dev environment.
+
+The current project remains a single-operator deployment using local Terraform state, with the strict rule that local state files must not be committed to Git.
+
+Remote state should be added if the project moves beyond single-developer demonstration into shared infrastructure management, client handover, or a more production-like multi-environment workflow.
+
 ---
 
 ## Repository rules