Skip to main content

Feature Specification: aws-sandbox npm Package Release v0.3.18

Status: APPROVED Created: 2026-02-01 Updated: 2026-02-02 Version: 0.3.18 ADLC Framework: v3.1.0 Constitutional Compliance: CHK049 (Agentic Behavior Spec), CHK050 (SOPs Defined)

1. Executive Summary​

1.1 Feature Overview​

Release the aws-sandbox npm package (v0.3.18) - an Enterprise AWS account vending solution with self-service sandbox provisioning, implementing the ADLC 6+1 phase lifecycle with Consumer E2E validation (Phase 3.5) as the primary quality gate.

1.2 Business Value​

MetricValueEvidence
Risk MitigationPrevent 100% broken npm publishesv0.3.3-v0.3.9 incident (7 broken versions)
Time Savings70-80% automation via CDKManual vs IaC comparison
Cost Control$0 testing (Tier 1+2 on LocalStack)No AWS charges for validation

1.3 Target Users​

  • Developers: Self-service sandbox provisioning
  • Cloud Architects: AWS Organizations integration
  • Platform Engineers: Enterprise account vending automation

2. Problem Statement​

2.1 Current State​

The aws-sandbox npm package (v0.3.18) has:

  • 29/29 Tier 1 snapshot tests PASS (5.38s, $0)
  • 11/11 Tier 2 LocalStack tests PASS (1.28s, $0)
  • 58/58 Constitutional checkpoints PASS

Gap Identified: Phase 3.5 Consumer E2E Deploy validation has never been executed. Historical evidence from v0.3.3-v0.3.9 shows that developer mode tests can pass while consumer mode (npm package installation) fails at runtime.

2.2 Root Cause Analysis​

VersionIssueRoot Cause
v0.3.3Package failed to installMissing files in package.json
v0.3.4-v0.3.7CLI not executableBroken shebang in bin/cli.js
v0.3.8Consumer mode not detectedapp.cjs not bundled
v0.3.9LocalStack deploy failedLambda bundles missing

2.3 Target State​

  • Phase 3.5 Consumer E2E Deploy executed and PASS
  • 5-layer validation strategy per ADR-005
  • Evidence captured to tmp/cdk/release-logs/
  • npm publish only after Phase 3.5 PASS gate

3. Requirements​

3.1 Functional Requirements​

FR-001: Phase 3.5 Consumer E2E Deploy​

Priority: P0 (BLOCKING) Description: Execute Consumer E2E validation before npm publish

Acceptance Criteria:

IDGivenWhenThen
AC-1[email protected] tarball creatednpm pack executedValid .tgz file generated
AC-2Fresh consumer environmentnpm install aws-sandbox-0.3.18.tgzPackage installs successfully
AC-3Package installednpx aws-sandbox --versionReturns "0.3.18"
AC-4Consumer mode activenpx aws-sandbox synth --allCloudFormation templates generated
AC-5LocalStack runningnpx aws-sandbox deploy --localstackAll stacks CREATE_COMPLETE

FR-002: 3-Tier Testing​

Priority: P0 (Required) Description: Validate package quality through 3-tier testing strategy

TierTestsDurationCostCoverage
Tier 129/295.38s$070-80%
Tier 211/111.28s$0+15-20%
Tier 3Deferred5-10min~$50/mo+5-10%

FR-003: npm Package Contents​

Priority: P0 (Required) Description: Package must include all required files

aws-sandbox-0.3.18.tgz
├── bin/cli.js                                    # CLI entrypoint
├── lib/                                          # Compiled TypeScript
│   ├── index.js
│   ├── stacks/
│   └── helpers/
├── source/infrastructure/dist/
│   └── infrastructure/bin/app.cjs               # Pre-bundled consumer app (~58MB)
├── source/lambdas-bundled/
│   ├── accounts-api/*.zip                       # Lambda bundles
│   └── lease-manager/*.zip
└── source/frontend/dist/                        # React frontend build

3.2 Non-Functional Requirements​

NFR-001: Performance​

MetricTargetActual
Tier 1 execution≤10s5.38s
Tier 2 execution≤60s1.28s
npm install time≤30sTBD
Consumer deploy time≤5minTBD

NFR-002: Reliability​

MetricTarget
Tier 1 pass rate100%
Tier 2 pass rate100% (with 25 documented skips per ADR-003)
Consumer deploy success100%

NFR-003: Security​

  • Apache-2.0 license compliance
  • npm audit: ≤5 high vulnerabilities (current: 54)
  • No secrets in package

4. INVEST User Stories​

US-001: Phase 3.5 Consumer E2E Deploy (P0)​

Independent: Can execute after Tier 1+2 PASS Negotiable: 5-layer strategy per ADR-005 Valuable: Prevents 100% of broken npm publishes Estimable: 0.75 days effort Small: Single validation workflow Testable: Binary PASS/FAIL with evidence

As a release-manager
I want Consumer E2E deploy to succeed on LocalStack
So that npm publish doesn't ship broken packages

WSJF Score: 20.0 (highest priority)

US-002: Tier 3 AWS E2E Tests (P1)​

Deferred: To v0.4.0 cycle with documented exemption

As a cloud-architect
I want real AWS deployment validation
So that AWS-specific behaviors are verified

WSJF Score: 6.5

US-003: npm Vulnerabilities Remediation (P2)​

Deferred: To v0.4.0 cycle

As a security-engineer
I want npm audit vulnerabilities reduced
So that published package meets enterprise standards

WSJF Score: 8.0

5. Architecture Decisions​

ADRTitleStatus
ADR-001LocalStack Services ConfigurationApproved
ADR-005Consumer E2E StrategyApproved
ADR-006Tier 3 Testing ArchitectureApproved
ADR-007npm Publish PipelineApproved

5.2 Deployment Targets​

  • LocalStack (Tier 2): $0, 85% coverage
  • AWS Sandbox (Tier 3): ~$50/mo, 100% coverage (deferred)

5.3 CDK Stacks​

StackResourcesLocalStackAWS
InnovationSandbox-Data19FullFull
InnovationSandbox-Compute2685%100%
InnovationSandbox-AccountPool-NoYes (Organizations)
InnovationSandbox-IDC-NoYes (Identity Center)

6. Risk Assessment​

6.1 Technical Risks​

RiskProbabilityImpactMitigation
Consumer deploy failsMEDIUMHIGH5-layer validation (ADR-005)
LocalStack parity gapsHIGHMEDIUMTier 3 deferred with exemption
app.cjs bundling failsLOWHIGHBuild step in Phase 2

6.2 Business Risks​

RiskProbabilityImpactMitigation
Broken npm publishHIGH (without Phase 3.5)HIGHPhase 3.5 BLOCKING gate
User adoption failureLOWMEDIUMCLI UX validation in Phase 3.5

7. Success Criteria​

7.1 Definition of Done​

  • Phase 3.5 Consumer E2E Deploy: PASS
  • Evidence captured: tmp/cdk/release-logs/phase3.5-consumer-*.log
  • 0 deploy errors in evidence log
  • npm pack creates valid tarball
  • CLI commands work in consumer mode
  • HITL approval obtained for npm publish

7.2 KPIs​

KPITargetBaseline
Phase 3.5 pass rate100%N/A (first execution)
Consumer install success100%Unknown
npm download increase+10%Current downloads

8. Constraints​

8.1 Technical Constraints​

  • LocalStack Free tier limitations (Lambda Layers require Pro)
  • Docker required for LocalStack testing
  • Node.js ≥18 for ESM support

8.2 Business Constraints​

  • HITL required for npm publish (Phase 5+)
  • Tier 3 testing deferred (cost: ~$50/mo)
  • Constitutional compliance required (58 checkpoints)

8.3 Assumptions (RQ3 Upgrade)​

IDAssumptionRisk if InvalidValidation Method
A-001LocalStack provides ≥85% AWS service parity for CDK stacksPhase 3.5 may fail on unsupported servicesTier 2 test coverage analysis
A-002Consumer environment has Docker available for LocalStackUsers cannot run Phase 3.5 locallyREADME prerequisites check
A-003npm package structure remains stable (no breaking changes)Consumer imports failSemantic versioning (0.3.x)
A-004app.cjs bundling captures all runtime dependenciesConsumer synth fails with missing modulesPhase 3.5 Layer 3 validation
A-005Lambda bundles are architecture-agnostic (x86_64 + arm64)Deploy fails on ARM-based LocalStackMulti-arch build verification
A-006ADLC agents (product-owner, cloud-architect) are invoked FIRSTSTANDALONE_EXECUTION violationCoordination logs in tmp/

9. Out of Scope​

  • Tier 3 AWS E2E testing (deferred to v0.4.0)
  • npm vulnerability remediation (deferred to v0.4.0)
  • AccountPool and IDC stack validation (requires AWS Organizations)
  • Breaking API changes

10. References​

10.1 Evidence Files​

FilePurpose
tmp/cdk/coordination-logs/product-owner-2026-02-01.jsonBusiness validation
tmp/cdk/coordination-logs/cloud-architect-2026-02-01.jsonTechnical design
tmp/cdk/architecture-decisions/ADR-005-consumer-e2e-strategy.mdPhase 3.5 strategy
tmp/cdk/test-results/tier1-2026-02-01-081221.logTier 1 results
tmp/cdk/test-results/tier2-2026-02-01-081151.logTier 2 results

10.2 Constitutional Checkpoints​

  • CHK049: Agentic behavior specification - PASS
  • CHK050: SOPs defined - PASS
  • CHK051: Prompt design - PASS
  • CHK052: Agent orchestration - PASS
  • CHK053: Evaluation framework - PARTIAL (Phase 3.5 pending)

11. Approval​

RoleNameDateStatus
Product Ownerproduct-owner agent2026-02-01APPROVED
Cloud Architectcloud-architect agent2026-02-01APPROVED
HITL Manager@nnthanh101PENDINGPENDING

12. Open Questions (RQ3 Upgrade)​

IDQuestionOwnerStatusResolution
Q-001Should Phase 3.5 run in CI/CD or only locally?cloud-architectOPENRecommend: Local-first, then GitHub Actions
Q-002What is the npm audit threshold for publish approval?security-engineerOPENCurrent: 54 high vulns, Target: ≤5
Q-003Should we support ARM64 Lambda bundles?infrastructure-engineerOPENDeferred to v0.4.0
Q-004Is LocalStack Pro required for full Phase 3.5 coverage?qa-engineerRESOLVEDNo - Free tier covers 85% (ADR-001)
Q-005Should HITL approval be automated via GitHub PR review?product-ownerOPENRecommend: PR approval = HITL approval

13. Architecture Diagrams (RQ4 Cross-Reference)​

13.1 Draw.io Diagrams (SVG)​

DiagramPurposeLocation
High-Level ArchitectureSystem context (C4 Level 1)cdk/docs/diagrams/architecture/high-level.drawio.svg
In-Depth ArchitectureContainer view (C4 Level 2)cdk/docs/diagrams/architecture/in-depth.drawio.svg
Stack DependenciesCDK stack relationshipscdk/docs/diagrams/architecture/stack-dependencies.drawio.svg
Stack RelationshipsInter-stack data flowcdk/docs/diagrams/architecture/stack-relationships.drawio.svg
Software LayersApplication architecturecdk/docs/diagrams/architecture/software-architecture-layers.drawio.svg
Account CleanerCleanup workflowcdk/docs/diagrams/architecture/account-cleaner.drawio.svg
Event InfrastructureEventBridge patternscdk/docs/diagrams/architecture/event-infrastructure.drawio.svg
Organizational UnitsAWS Organizations structurecdk/docs/diagrams/architecture/organizational-units.drawio.svg
Web AppFrontend architecturecdk/docs/diagrams/architecture/web-app.drawio.svg

13.2 Mermaid Diagrams (Docusaurus-Ready)​

DiagramPurposeLocation
AWS 4-Stack Architecturearchitecture-beta + flowchartcdk/docs/ARCHITECTURE-DIAGRAMS.md#1
Consumer E2E Flow5-layer validation pipelinecdk/docs/ARCHITECTURE-DIAGRAMS.md#2
3-Tier Testing PipelineTier 1 → Tier 2 → Phase 3.5 → Tier 3cdk/docs/ARCHITECTURE-DIAGRAMS.md#3
Deployment SequencePhase-based stack deploymentcdk/docs/ARCHITECTURE-DIAGRAMS.md#4
npm Package StructureTarball contents → consumer usagecdk/docs/ARCHITECTURE-DIAGRAMS.md#5
ADLC 6+1 LifecycleRelease workflow phasescdk/docs/ARCHITECTURE-DIAGRAMS.md#6
Stack Resource MappingDataStack + ComputeStack resourcescdk/docs/ARCHITECTURE-DIAGRAMS.md#7

Specification Version: 1.1.0 ADLC Phase: 1.1 (Business Context & KPI Definition) Updated: 2026-02-02 (RQ3+RQ4 Upgrades Applied) Next Action: Execute Phase 3.5 Consumer E2E Deploy