feca-mailshots-plugin/requirements/environment.md

Mailshot Plugin Environment Baseline

Purpose

Define the persistent environment assumptions for this plugin so all requirements and implementation work use the same baseline.

Global Requirement Context

This document will be referenced from every requirements specification document in this repository. This document remains in the working context for all operations.

Core Policy

"Do not use fallbacks without specific instruction"

No fallback behavior may be introduced or enabled unless a requirement explicitly instructs it.

Use the following rule in prompts: Hard constraints for this task:

1. No fallbacks unless explicitly listed below.
2. No synthetic placeholders/default labels.
3. Fail fast on missing/invalid data paths.
4. Show explicit errors at point of detection.
5. If a fallback seems necessary, stop and ask first.

Repository Context

• Primary workspace: mailshot-plugin
• Reference implementation patterns: ../members-list-plugin
• Requirements folder: requirements/
• Credentials folder (local dev only): credentials/
• Results folder for test outputs and investigation findings: results/

Development Assumptions

• Development should support a local fixture/harness workflow where practical.
• Runtime code paths used in tests should match production plugin code paths as closely as possible.
• Environment-specific behavior must be explicit, documented, and testable.

Configuration Principles

• Use a single clear active configuration path per environment.
• Prefer explicit configuration over implicit defaults.
• Keep secrets outside committed source files.

Database Routing Contract

• Mailshot feature writable state (definitions, assets, run logs, and related mailshot tables) must be stored in the database named by .env variable MAILSHOTS_REMOTE_MYSQL_DB.
• Recipient/source data reads (for DSL execution against contacts/accounts/renewals and approved custom source tables) must use the database named by .env variable MEMBERS_REMOTE_MYSQL_DB.
• Requirements documents must state whether each table/operation is a write-path (MAILSHOTS_REMOTE_MYSQL_DB) or read-path (MEMBERS_REMOTE_MYSQL_DB).

Testing Hygiene

• Every test must clean up its own test artefacts.
• No test may leave persistent data/files/state behind unless a requirement explicitly allows it.
• Test results and investigation findings must be written under results/.

Build And Release Scripts

• scripts/ must contain a deployment script for deploying to the production server.
• scripts/ must contain a packaging script that creates an uploadable WordPress plugin package.

Versioning Requirements

• The code must expose a WordPress-reportable semantic version number in x.y.z format.
• x is major, y is minor, z is patch level.
• Every deployment must increment patch level z.

Documentation Contract

Each future requirements document should:

1. Link or refer to requirements/environment.md.
2. Declare any additional environment constraints beyond this baseline.
3. State if a requirement is local-only, test-only, or production-relevant.