Repository navigation
Description
Outcome
The scaffold's infrastructure does what docs/design-principles.md says it does: services register reliably in any order, every lifecycle-aware service takes part in the lifecycle events it declares, exceptions never reach end users, the injector builds any valid object graph, views are safe by default, and the lifecycle points that production plugins needed (multisite, uninstall, WP-CLI, assets) exist as capability interfaces.
Why now
An architecture review on 2026-10-22, run when the design principles were written down, found that several parts of the infrastructure contradict them. At that review, live failures included a fatal sample on singular views and services skipped silently during registration. #19 is now closed through merged PR #63: the composition root supplies the current post and the view escapes its fields. The original sample fatal and #20 registration defect are now fixed; this paragraph records the review history, not live failures.
A comparison with three plugins built on this scaffold, including Google's AMP and Web Stories plugins, showed which of these bugs production use had already run into and fixed. It also showed which lifecycle points those plugins had to add themselves, and where their fixes introduced new problems. That gives a field-tested basis for each change.
Shared context
Source anchors at main 15cac4c2: src/Infrastructure/ServiceBasedPlugin.php:1242-1422 (registration/normalization), :414-524 (legacy/scoped activation/deactivation), src/Infrastructure/Injector/SimpleInjector.php:387-420 (named-type injection), and src/Infrastructure/View/SimpleView.php:119-175 (rendering).
docs/design-principles.mdis the specification. Each sub-issue names the principle it restores.- Most changes concentrate in
src/Infrastructure/ServiceBasedPlugin.php,src/Infrastructure/Injector/SimpleInjector.phpand the view classes insrc/Infrastructure/View/. - Fixes inspired by the AMP and Web Stories plugins are reimplemented, not copied. Those projects are licensed GPL-2.0 and Apache-2.0, and this scaffold is MIT.
- The maintainer declined providers in infrastructure: separate feature wiring from the kernel using providers #7; infrastructure: separate feature wiring from the kernel using providers #7 and exploratory PR Basic draft of how providers could be introduced #8 are closed without implementation. Keep the current composition-root configuration. No broader split of ServiceBasedPlugin is approved by this epic; its sub-issues fix behaviour within the current structure.
Constraints and non-goals
- PHP 7.4 stays the floor; Composer stays optional at runtime (principle 1).
- No static service locator. All three downstream plugins added one; this epic removes the need for it instead (sub-issue on injecting the injector).
- No lenient "silently drop invalid configuration" behaviour (principles 9 and 10).
- Interface changes that break generated plugins carry the
breakinglabel and need a ruling before code.
Breakdown
The native child list is the authoritative plan: 27 children, 22 closed and five open (#35, #37, #143, #149, #153). The original 22 children have 20 closed and two open (#35 and #37). Follow-ups #143, #149 and #153 remain unresolved; #156 and #173 are closed through #174 and #176, providing isolated template scopes and per-render presenters.
#38/#163 implemented optional registration history and Query Monitor. #37's asset capability is now merged through #177 and present on main, including sample assets. #37 remains open because #177 explicitly leaves the acceptance test for registration after the footer print pass unmet; its Refs #37 is deliberate. Do not treat it as missing asset infrastructure or close it from this reconciliation.
The scoped lifecycle interfaces (#34), view-failure policy (#27/#30), dependency/injector hardening and original architecture/testing fixes have landed. Scoped lifecycle failures deliberately propagate under the maintainer's #34 exception; the general callback boundary remains #143. No blanket "exceptions never escape" implementation is claimed.
Definition of done
- Every sub-issue is closed.
- The lifecycle table in
docs/design-principles.mdlists every capability interface the infrastructure orchestrates. - No statement in the design principles is contradicted by the infrastructure, re-checked by a fresh review of
src/Infrastructure/against the document.
Verification
For each implementation, run composer test and composer lint in the supported CI environment. On completion, review every sub-issue and re-check the lifecycle table and infrastructure against all design principles.
Impact on generated plugins
Behaviour fixes and approved capability additions propagate into generated plugins. Every changed public contract retains its own compatibility/migration ruling; this epic grants no additional exception. The tracker remains open for the five children above and never receives agent-ready. Original sample success/missing-post tests are in tests/php/Integration/SampleLoopServiceTest.php; the current sample now uses the per-render PostHeader presenter introduced by #173/#176.
Updated 2026-10-23: Reconciled original child completion and remaining work at 1133d65, repaired moved source anchors, and attached the general boundary and three concrete follow-up bugs. Preserved all prior policy rulings; 18/26 children closed, tracking epic remains open.
Updated 2026-10-23: Reconciled merged #38/#163 and #167 at main 61a9b00, repaired registration/lifecycle/sample anchors, and updated native child completion to 19/26. Seven children remain open; existing rulings are unchanged.
Updated 2026-10-24: #42 merged and closed #10 after PHP 7.4/8.3 tests, PHP 8.3 lint and both autoloading paths in WordPress passed. Updated completion to 20/26; six children remain open. Existing rulings are unchanged.
Updated 2026-10-24: Reconciled 27 native children (22 closed, five open), merged template/presenter and asset work, the deliberately unmet #37 footer-print test, and current source anchors. The epic remains open and never agent-ready. Reviewed origin/main 15cac4c2.
Activity
7 remaining items
schlessera commentedon Oct 22, 2026
Triage (2026-10-22): Checked all 22 native sub-issues and the existing parent links. Added source anchors, verification and generated-plugin impact. Retained p1 because the epic groups live failures already identified in its body; it remains a tracking epic, never agent-ready.
schlessera commentedon Oct 22, 2026
Triage (2026-10-22): Reconciled the declined providers ruling (#7 and exploratory PR #8 are closed) and verified all 22 native sub-issues. Runtime citations still match main; this remains a p1 tracking epic, never agent-ready.
schlessera commentedon Oct 23, 2026
Triage (2026-10-23): Verified #19 closed through merged PR #63 and checked the delegation, escaping and integration-test source in main. Removed the fixed sample fatal from current failures and recorded one closed plus 21 open sub-issues. Kept p1 and epic; no readiness change.
schlessera commentedon Oct 23, 2026
Triage (2026-10-23): Reconciled original child completion and remaining work at 1133d65, repaired moved source anchors, and attached the general boundary and three concrete follow-up bugs. Preserved all prior policy rulings; 18/26 children closed, tracking epic remains open.
schlessera commentedon Oct 23, 2026
Triage (2026-10-23): Reconciled merged #38/#163 and #167 at main 61a9b00, repaired registration/lifecycle/sample anchors, and updated native child completion to 19/26. Seven children remain open; existing rulings are unchanged.
schlessera commentedon Oct 24, 2026
Triage (2026-10-24): Reconciled 27 native children (22 closed, five open), merged template/presenter and asset work, the deliberately unmet #37 footer-print test, and current source anchors. The epic remains open and never agent-ready.