@schilling.mark.a/software-methodology 1.0.0

package/cicd-pipeline/references/environment-promotion.md

@@ -0,0 +1,159 @@
+# Environment Promotion
+
+## What Is Environment Promotion?
+
+Code does not go directly from commit to production. It moves through a sequence of environments, each one closer to production and each one with stricter conditions. Promotion is the act of moving code from one environment to the next. Each promotion requires the previous environment's gates to have passed.
+
+This is not bureaucracy. It is risk reduction. Each environment catches a different class of failure. Production is the most expensive environment to fail in — so it is the last one code reaches, and only after it has survived every earlier environment.
+
+## The Environment Sequence
+
+```
+LOCAL  →  CI (ephemeral)  →  STAGING  →  PRODUCTION
+```
+
+Each environment below defines: what it is, what infrastructure it runs on, what tests run against it, and what must pass before code promotes to the next environment.
+
+---
+
+## Environment 1: Local
+
+**What it is:** The developer's machine. Code is written, tested locally, and committed here.
+
+**Infrastructure:** Developer's workstation. Local database, local dependencies.
+
+**Tests that run:** Unit tests and acceptance tests (developer runs these manually or via local test command before committing). The developer verifies green locally before pushing.
+
+**Promotion condition:** Developer pushes commit to the repository. This triggers the CI pipeline automatically — no manual promotion step.
+
+**What this environment catches:** Syntax errors. Logic errors the developer can see immediately. Failures that surface within seconds of writing the code.
+
+**What this environment does NOT catch:** Environment-specific failures (works on my machine). Integration failures between components. Security vulnerabilities. Anything that requires infrastructure the developer does not have locally.
+
+---
+
+## Environment 2: CI (Ephemeral)
+
+**What it is:** An automated, disposable environment spun up by the CI platform for every commit or pull request. It exists only for the duration of the pipeline run, then is destroyed.
+
+**Infrastructure:** CI platform (GitHub Actions runner, GitLab CI runner, Jenkins agent, etc.). Fresh OS image, clean dependency install, ephemeral database for integration tests.
+
+**Tests that run:** Stages 1–5 of the pipeline: Build, Unit Tests, Integration Tests, Acceptance Tests, Security Scan. (See pipeline-stages.md for detail on each.)
+
+**Promotion condition:** All Stages 1–5 pass. Code is merged to main (for pull requests) or proceeds to Staging Deploy (for main branch pushes).
+
+**What this environment catches:** Build failures. Regressions (tests that passed before this commit but fail now). Integration failures between components. Security vulnerabilities and secrets. Environment drift (code that works locally but fails in a clean environment).
+
+**What this environment does NOT catch:** Failures that only manifest under real infrastructure conditions (network latency, database at scale, real traffic patterns). Configuration differences between CI and production.
+
+---
+
+## Environment 3: Staging
+
+**What it is:** A persistent environment that mirrors production as closely as possible. It is the last environment before production — the final check before real users are affected.
+
+**Infrastructure:** Production-equivalent. Same OS, same database engine, same network topology, same deployment platform. Differs only in scale (fewer instances) and traffic source (no real user traffic — only automated tests and manual exploratory testing).
+
+**Tests that run:** Stages 6–7 of the pipeline: Staging Deploy and Smoke Tests. Additionally, QA or the team may perform manual exploratory testing in staging before approving production promotion.
+
+**Promotion condition:** Smoke tests pass. If manual approval is configured for production deploy, an authorized person approves. (See Approval Gates below.)
+
+**What this environment catches:** Configuration mismatches between CI and production infrastructure. Failures that only manifest against real infrastructure (database migrations at scale, network timeouts, TLS configuration). Integration failures with external services that are stubbed in CI but real in staging.
+
+**What this environment does NOT catch:** Failures caused by real user traffic patterns (load, concurrency, edge-case input from real users). Failures that only manifest over time (memory leaks, slow degradation).
+
+---
+
+## Environment 4: Production
+
+**What it is:** The live environment. Real users. Real traffic. Real consequences.
+
+**Infrastructure:** Production infrastructure. Full scale. Real external services. Real traffic.
+
+**Tests that run:** Stage 8 (Production Deploy) and Stage 9 (Health Check). Health check monitors error rates and response times against established baselines.
+
+**Promotion condition:** Health check passes for the configured observation period. If the deployment strategy is canary, the canary period completes without error rate increase before full rollout.
+
+**What this environment catches:** Everything the earlier environments missed. If something reaches production and fails, it is a production incident — continuous-improvement's root cause analysis investigates which earlier gate should have caught it.
+
+---
+
+## Approval Gates
+
+Most promotions are automatic — the pipeline moves forward when the gate passes. Some promotions require human approval. Approval gates slow the pipeline intentionally. They exist only where the risk of an automated promotion outweighs the cost of the delay.
+
+### When to Require Approval
+
+- **Production deploy for customer-facing changes:** If the release includes changes that users will see (new screens, changed behavior, pricing changes), require approval before production deploy.
+- **Production deploy after a recent production incident:** If a rollback occurred in the last N deployments, require approval until stability is confirmed.
+- **Infrastructure changes:** Changes to the deployment platform, database configuration, or network topology require approval regardless of test results.
+
+### When Approval Is NOT Required
+
+- **Hotfix deploys after a production incident:** Speed matters more than process. The hotfix goes through all automated gates but skips the manual approval gate. This is a conscious trade-off — document it.
+- **Internal tools with no external users:** The risk of a failed deploy is low. Automated gates are sufficient.
+
+### Approval Record
+
+Every approval is logged: who approved, when, and for which deployment. This is an audit trail — not optional.
+
+---
+
+## Environment Configuration Document
+
+Create: `/docs/cicd/environments.md`
+
+```markdown
+# Environment Configuration
+
+**Created:** [Date]
+**Last updated:** [Date]
+
+## Environment Inventory
+
+| Environment | Infrastructure | Persistent | Traffic source | Approval to promote |
+|---|---|---|---|---|
+| Local | Developer workstation | Yes | Developer | No — push triggers CI |
+| CI | [CI platform] ephemeral runners | No | Pipeline only | No — automatic on gate pass |
+| Staging | [Staging infrastructure] | Yes | Smoke tests + manual QA | [Yes / No] |
+| Production | [Production infrastructure] | Yes | Real users | [Yes / No] |
+
+## Approval Gates
+
+- **Staging → Production:** [Required / Not required]
+  - If required: [Who can approve — role or team]
+  - [Under what conditions approval is mandatory vs optional]
+- **Post-incident override:** [Policy for deploys after a recent rollback]
+
+## Environment Parity Rules
+
+Staging must match production on:
+- [ ] OS and runtime version
+- [ ] Database engine and version
+- [ ] Network topology (VPC, subnets, security groups)
+- [ ] Deployment platform (same container orchestrator, same serverless runtime)
+- [ ] TLS configuration
+- [ ] External service endpoints (staging may use staging versions of external APIs, but the integration pattern must be identical)
+
+Staging may differ on:
+- Scale (fewer instances)
+- Traffic volume (no real user traffic)
+- Data (synthetic or anonymized, not real user data)
+
+## Smoke Test Suite
+
+The smoke test suite is a curated subset of acceptance tests covering the highest-value user journeys.
+
+| Smoke test | Maps to scenario | Why it is critical-path |
+|---|---|---|
+| [Test name] | [Feature: scenario name] | [Why this is critical] |
+| [Test name] | [Feature: scenario name] | [Why this is critical] |
+```
+
+## Rules
+
+- Every environment exists for a reason. Do not add environments without a clear class of failure they are designed to catch.
+- Staging must mirror production infrastructure. Parity drift is the single most common cause of "works in staging, fails in production."
+- Approval gates are documented and logged. An undocumented approval is not an approval.
+- Ephemeral environments (CI) are rebuilt from scratch every time. This prevents state from accumulating and hiding failures.
+- The smoke test suite is maintained alongside the acceptance test suite. When a new critical-path feature ships, add its acceptance test to the smoke suite.

package/cicd-pipeline/references/pipeline-stages.md

@@ -0,0 +1,198 @@
+# Pipeline Stages
+
+## What Is a Pipeline Stage?
+
+A pipeline stage is a unit of automated work with a gate. The gate is a pass/fail condition. If the gate passes, code moves to the next stage. If it fails, the pipeline stops, notifies, and waits for a fix. No stage is skipped. No gate is bypassed in normal operation.
+
+The stages below are in fixed order. Every project uses all of them. The configuration within each stage (which tools, which commands) varies by project — but the sequence and the gate conditions do not.
+
+## Stage Sequence
+
+```
+COMMIT  →  BUILD  →  UNIT TEST  →  INTEGRATION TEST  →  ACCEPTANCE TEST
+    →  SECURITY SCAN  →  STAGING DEPLOY  →  SMOKE TEST  →  PRODUCTION DEPLOY  →  HEALTH CHECK
+```
+
+Each stage below defines: what runs, what the gate checks, what artifact it consumes from the methodology, and what failure looks like.
+
+---
+
+## Stage 1: Build
+
+**What runs:** Compile, transpile, or bundle the application. Resolve all dependencies. Produce a deployable artifact (container image, binary, bundle).
+
+**Gate:** Build succeeds with zero errors. All dependencies resolved. Artifact produced.
+
+**Consumes:** Source code from the commit that triggered the pipeline.
+
+**Failure means:** The code does not compile. A dependency is missing or incompatible. The artifact cannot be produced. This is typically a syntax error, a missing package, or a broken import — not a logic error.
+
+**Fix:** The developer who committed fixes the build error and pushes a new commit. The pipeline re-runs from Stage 1.
+
+---
+
+## Stage 2: Unit Tests
+
+**What runs:** All unit tests in the project. These are the tests written during the GREEN phase of atdd-workflow — fast, isolated, testing individual behaviors.
+
+**Gate:** All unit tests pass. Code coverage meets the project threshold (typically ≥90%, as defined in `/docs/test-strategy.md`).
+
+**Consumes:** The built artifact from Stage 1. The unit test suite from `tests/unit/`.
+
+**Failure means:** A unit test failed. Either the code introduced a regression, or a test expectation is wrong. Coverage dropped below threshold, meaning new code was added without corresponding tests — which should not happen if atdd-workflow RED phase was followed.
+
+**Fix:** The developer investigates the failing test. If the code is wrong, fix the code. If the test expectation is wrong (rare in ATDD — the test was written first), update the test. Push. Pipeline re-runs.
+
+**Connection to atdd-workflow:** Unit tests are the inner loop tests from RED-GREEN-REFACTOR. If they all passed locally during development but fail in the pipeline, the likely cause is an environment difference (dependency version, OS, configuration). Check that the pipeline build environment matches the developer's local environment.
+
+---
+
+## Stage 3: Integration Tests
+
+**What runs:** Tests that verify components work together — database interactions, API calls between services, message queue consumption. These tests require a running infrastructure (database, cache, external service stubs).
+
+**Gate:** All integration tests pass.
+
+**Consumes:** The built artifact. A test infrastructure environment spun up by the pipeline (ephemeral — destroyed after this stage).
+
+**Failure means:** Components do not communicate correctly. A database schema mismatch. An API contract violation between services. A message format incompatibility.
+
+**Fix:** The developer investigates the integration failure. Often a schema migration that was not included in the commit, or an API contract that changed without updating the consumer. Push fix. Pipeline re-runs.
+
+**Note:** If the project is a single-service application with no inter-service communication, this stage runs database integration tests only. If there are no external dependencies at all, this stage is a no-op gate (passes automatically) — do not remove it from the pipeline definition. It exists as a placeholder for when dependencies are added.
+
+---
+
+## Stage 4: Acceptance Tests
+
+**What runs:** The full acceptance test suite — the outer loop tests from atdd-workflow's RED phase. These are the tests that map directly to Gherkin scenarios in the feature files. They run against a fully assembled application.
+
+**Gate:** All acceptance tests pass. Every scenario in every feature file has a passing test.
+
+**Consumes:** The built artifact. A fully assembled test environment (application + database + any dependencies). The feature files from `features/` and the acceptance tests from `tests/acceptance/`.
+
+**Failure means:** A scenario that passed locally does not pass in the pipeline. The assembled application does not behave as the feature file specifies. This is the most important gate — it is the last line of defense before code reaches users.
+
+**Connection to atdd-workflow and bdd-specification:** Acceptance tests are the mechanized form of the Gherkin scenarios. If a scenario exists in a feature file but has no passing acceptance test, this gate will catch it. The traceability between feature files and acceptance tests is enforced here — not just locally.
+
+**Connection to ui-design-workflow:** Acceptance targets defined in screen flows become assertions in acceptance tests. If an acceptance target was defined but not tested, the coverage gap surfaces here.
+
+---
+
+## Stage 5: Security Scan
+
+**What runs:** Static analysis of source code for security vulnerabilities (OWASP Top 10). Dependency scanning for known CVEs in third-party libraries. Secret detection (API keys, credentials accidentally committed).
+
+**Gate:** No critical or high-severity vulnerabilities found. No secrets detected in the codebase.
+
+**Consumes:** The source code. The dependency manifest (package.json, requirements.txt, pom.xml, Gemfile, etc.).
+
+**Failure means:** A known vulnerability exists in a dependency. A security anti-pattern was introduced in the code. A credential was committed. Critical and high severity block the pipeline. Medium and low are logged but do not block.
+
+**Fix:** For dependency vulnerabilities: update or replace the vulnerable dependency. For code vulnerabilities: fix the anti-pattern. For secrets: remove the secret from the commit history (not just the latest commit — the secret is in git history), rotate the credential, and push. Pipeline re-runs.
+
+---
+
+## Stage 6: Staging Deploy
+
+**What runs:** Deploy the artifact to the staging environment. Staging mirrors production infrastructure as closely as possible — same OS, same database engine, same network topology. The only difference is scale and traffic source.
+
+**Gate:** Deployment completes successfully. The application starts and reports healthy.
+
+**Consumes:** The artifact from Stage 1. The staging environment configuration from `/docs/cicd/environments.md`.
+
+**Failure means:** The artifact does not run in the staging environment. A configuration difference between build and staging caused a crash. A database migration failed. An environment variable is missing.
+
+**Fix:** Compare staging configuration to build environment. Fix the mismatch. Push. Pipeline re-runs from Stage 1 (full pipeline — do not skip stages).
+
+---
+
+## Stage 7: Smoke Tests (Staging)
+
+**What runs:** A small, fast subset of critical-path tests against the live staging deployment. These are not the full acceptance suite — they are the 5–10 tests that verify the most critical user journeys actually work end-to-end against real infrastructure.
+
+**Gate:** All smoke tests pass against staging.
+
+**Consumes:** The running staging deployment. A curated smoke test suite (subset of acceptance tests, selected for critical-path coverage).
+
+**Failure means:** Something that passed in the isolated acceptance test environment does not work against real infrastructure. A timing issue. A network timeout. A configuration that acceptance tests did not exercise.
+
+**Fix:** Investigate the smoke test failure in staging. If it is an infrastructure issue, fix the environment configuration. If it is a code issue that only manifests under real conditions, fix the code. Push. Full pipeline re-runs.
+
+---
+
+## Stage 8: Production Deploy
+
+**What runs:** Deploy the artifact to production using the deployment strategy defined in `/docs/cicd/deployment.md` (blue-green, canary, rolling, or replace).
+
+**Gate:** Deployment completes. The production health check passes (Stage 9). If the deployment strategy is canary, the canary period passes without error rate increase before full rollout proceeds.
+
+**Consumes:** The artifact. The production environment configuration. The deployment strategy document.
+
+**Approval gate (optional):** For high-risk deployments, require manual approval before production deploy proceeds. The approval gate sits between Stage 7 (smoke tests pass) and Stage 8. Who can approve and under what conditions is defined in `/docs/cicd/environments.md`.
+
+---
+
+## Stage 9: Health Check (Production)
+
+**What runs:** Verify that production is healthy after deployment. Application responds to health endpoints. Error rates have not spiked. Key metrics are within normal range.
+
+**Gate:** Health check passes. Error rate is within baseline ±threshold (defined per project). Response time is within baseline ±threshold.
+
+**Consumes:** The running production deployment. Monitoring baselines established from previous deployments.
+
+**Failure means:** The deployment succeeded but production is unhealthy. This is the automatic rollback trigger — see `/docs/cicd/deployment.md` for rollback procedures.
+
+**Connection to continuous-improvement:** If the health check fails and rollback occurs, this is a production incident. continuous-improvement's root cause analysis runs. The investigation traces back through the pipeline to find which gate should have caught the problem but did not.
+
+---
+
+## Pipeline Configuration Document
+
+Create: `/docs/cicd/pipeline.md`
+
+```markdown
+# CI/CD Pipeline Configuration
+
+**Created:** [Date]
+**Last updated:** [Date]
+**Platform:** [GitHub Actions / GitLab CI / Jenkins / etc.]
+
+## Trigger
+- Push to `main` branch triggers the full pipeline
+- Pull request to `main` triggers Stages 1–5 only (no deploy)
+
+## Stages
+
+| Stage | Tool / Command | Gate | Blocks on failure |
+|---|---|---|---|
+| 1 — Build | [build command] | Zero errors, artifact produced | Yes |
+| 2 — Unit Tests | [test command] | All pass, coverage ≥[threshold]% | Yes |
+| 3 — Integration Tests | [test command] | All pass | Yes |
+| 4 — Acceptance Tests | [test command] | All pass | Yes |
+| 5 — Security Scan | [scan tool] | No critical/high CVEs, no secrets | Yes |
+| 6 — Staging Deploy | [deploy command] | Deployment succeeds | Yes |
+| 7 — Smoke Tests | [test command] | All pass | Yes |
+| 8 — Production Deploy | [deploy command] | See deployment.md | Yes |
+| 9 — Health Check | [health check command] | Error rate and latency within baseline | Yes (triggers rollback) |
+
+## Approval Gates
+- **Production deploy:** [Required / Not required]
+  - If required: [Who can approve] [Under what conditions]
+
+## Notification
+- Pipeline failure: [Notify channel/team]
+- Production deploy success: [Notify channel/team]
+- Rollback triggered: [Notify channel/team — this is urgent]
+
+## Test Strategy Reference
+All test commands and coverage thresholds are defined in `/docs/test-strategy.md`.
+```
+
+## Rules
+
+- Every stage runs in order. No stage is skipped in normal operation.
+- Every gate is a hard pass/fail. No "warnings only" for critical or high severity items.
+- Pull requests run Stages 1–5. Merges to main run the full pipeline. This means every piece of code is tested before it reaches the deploy stages.
+- The pipeline configuration is version-controlled alongside the application code. A change to the pipeline is a commit, reviewed the same way as any other code change.
+- If a stage consistently fails on valid code, the stage configuration is wrong — not the code. Investigate the stage, not the developer.

package/clean-code/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: clean-code
+description: Design principles and design patterns for writing clean, maintainable code. Use during the GREEN phase when writing implementation code and during the REFACTOR phase when improving code structure. Provides decision guidance on which SOLID principles apply, when to extract abstractions, and which Gang of Four or enterprise patterns fit the current problem. Works alongside atdd-workflow skill — tests must stay green throughout.
+---
+
+# Clean Code — Design Principles and Patterns
+
+## Overview
+
+Decision guide for applying design principles and patterns during GREEN and REFACTOR phases. Does not replace atdd-workflow — tests must remain green at every step. This skill answers: "What principle or pattern applies here, and how?"
+
+## When to Read This Skill
+
+**During GREEN phase:** When minimal code feels structurally wrong even as a stepping stone — read `references/solid.md` to check if a principle is being violated that will make the next RED-GREEN cycle impossible.
+
+**During REFACTOR phase:** Always. Read the decision tree below, then load only the relevant reference file.
+
+## Decision Tree — Which Reference to Load
+
+### "I have duplication"
+→ Read `references/solid.md` — DRY and SRP will guide the extraction
+
+### "I have an if/else or switch that keeps growing"
+→ Read `references/behavioral-patterns.md` — Strategy, Command, or State will eliminate the branching
+
+### "I have a class doing too many things"
+→ Read `references/solid.md` — SRP first. Then read `references/structural-patterns.md` if the class needs to be decomposed into a hierarchy
+
+### "I need to add a new behavior without changing existing code"
+→ Read `references/solid.md` — OCP. Then read `references/behavioral-patterns.md` for the pattern that enables it
+
+### "I have concrete dependencies that make testing hard"
+→ Read `references/solid.md` — DIP. Then read `references/structural-patterns.md` for Adapter or Facade if wrapping external systems
+
+### "I have a complex object that requires a specific construction sequence"
+→ Read `references/creational-patterns.md`
+
+### "I need to compose behaviors at runtime"
+→ Read `references/behavioral-patterns.md` — Strategy or Decorator
+
+### "I have a thin wrapper around an external system"
+→ Read `references/structural-patterns.md` — Adapter or Facade
+
+### "I have a complex subsystem I want to hide behind a simple interface"
+→ Read `references/structural-patterns.md` — Facade
+
+### "I have a tree structure or nested hierarchy"
+→ Read `references/structural-patterns.md` — Composite
+
+### "I have enterprise-scale concerns: repositories, services, event handling"
+→ Read `references/enterprise-patterns.md`
+
+## Constraints
+
+- **Tests must stay green.** Every refactoring step is followed by a test run. If tests break, revert and take a smaller step.
+- **Don't over-engineer.** Apply a pattern only when the code currently requires it. A second occurrence of the same problem (Rule of Three) is the signal to extract.
+- **Use ubiquitous language.** All class names, method names, and interfaces must use terms from `/docs/ubiquitous-language.md`.
+- **Patterns serve the domain.** Name pattern implementations after domain concepts, not after the pattern. A Strategy for tax calculation is called `TaxCalculator`, not `TaxStrategy`.
+
+## Rule of Three
+
+Do not extract a pattern on first occurrence. Wait until:
+1. The same problem appears a second time — now you have two concrete examples
+2. You can see the abstraction that unifies both
+3. Extract — the abstraction is now grounded in reality, not speculation
+
+## Integration with atdd-workflow
+
+```
+🔴 RED   → Write failing test (atdd-workflow)
+🟢 GREEN → Write minimal code. If a SOLID violation makes the next cycle
+           impossible, consult references/solid.md before proceeding.
+           (clean-code)
+♻️ REFACTOR → Identify smell from decision tree above. Load relevant
+              reference. Apply pattern. Run tests. Commit when green.
+              (clean-code + atdd-workflow)
+```