# IPZ Feature Flags

Audience: AI coding agents first.

## Outcome

Add PHP-only canonical feature-flag primitive. One WordPress option envelope: `ipz_feature_flags`. Stable keys: `ipz_localized_routing`, `ipz_site_content`. No behavior activation.

## Status

IDLE — implementation committed; no activation or deployment requested.

## Task IDs

No task tracker ID assigned.

## Source request

2026-08-13 owner request: create smallest independent canonical server-side flag primitive. Scope only `FeatureFlags.php`, focused unit test, this plan, plan index. Other files owned by other worker.

## Acceptance criteria

1. PHP authority uses only `ipz_feature_flags` envelope.
2. Registry hardcodes stable keys with `owner`, `purpose`, `rollout_state`, `kill_switch`, `removal_task`.
3. `isEnabled(string $key): bool` and `definition(string $key): array` are public static APIs.
4. Unknown, absent, malformed, unreadable, non-array, non-boolean values return OFF.
5. Only literal `true` enables known key.
6. No environment override, writes, UI, REST, activation hook, direct consumer check, or feature activation.
7. Focused test covers defaults, invalid input, literal `true`, stable keys, metadata completeness.
8. Syntax, focused PHPUnit, candidate-aware PHPCS/PHPStan, diff check, and commit hook pass cleanly.

## Preserved WIP

Worktree: `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/ipz-feature-flags`.

Owned paths:

- `plugins/international-press-zone/includes/Core/FeatureFlags.php`
- `plugins/international-press-zone/tests/Unit/Core/FeatureFlagsTest.php`
- `docs/plans/2026-08-13-ipz-feature-flags.md`
- `docs/plans/INDEX.md`

## Constraints

No edits outside owned paths. No consumer integration. No option writes. No activation behavior.

## Execution steps

1. Define immutable registry and fail-closed option read.
2. Add isolated PHPUnit stubs and contract tests.
3. Run focused validation and resolve every owned signal.
4. Commit only owned paths.

## Current receipt

2026-08-13: created isolated worktree from fresh `origin/master`. Added PHP-only `FeatureFlags` registry and isolated test-only `get_option()` stub. Validation passed:

- `php -l includes/Core/FeatureFlags.php` → no syntax errors.
- `php -l tests/Unit/Core/FeatureFlagsTest.php` → no syntax errors.
- `./vendor/bin/phpunit --no-configuration tests/Unit/Core/FeatureFlagsTest.php` → `OK (6 tests, 40 assertions)`.
- `./vendor/bin/phpcs --standard=WordPress --exclude=WordPress.Files.FileName includes/Core/FeatureFlags.php` → clean; requested `FeatureFlags.php` canonical path is the only excluded filename rule. `isEnabled` has a narrow PHPCS suppression because its camelCase spelling is a required public API contract.
- `./vendor/bin/phpstan analyse --configuration=phpstan.neon.dist includes/Core/FeatureFlags.php --no-progress` → `No errors`.
- `git diff --check` → clean.
- Commit `48c261105` created through pre-commit hook → every applicable staged gate passed; hook noted non-applicable root JS/TS, out-of-scope plugin test file, Trivy unavailable, and root Composer audit unavailable.

Initial WordPress PHPCS reported filename/class naming requirements incompatible with the requested canonical `FeatureFlags.php` path and `isEnabled` public API contract. Both are narrowly addressed in source or candidate command; all other WordPress rules pass. Composer dependencies were installed locally in ignored `plugins/international-press-zone/vendor/` to run the focused gates.

## Next executable action

Integrate commit `48c261105` when release owner selects this independent slice. Do not activate either flag as part of integration.

## Inactive activation state

Both registered flags remain inactive unless the existing `ipz_feature_flags` option contains literal boolean `true` for a known key. This task adds no consumer behavior, writes, hooks, UI, REST endpoint, or activation path.

## Rollback

Remove this task commit. With option absent, all flags remain OFF.