Repository navigation
Description
Context
At main 15cac4c2, ServiceBasedPlugin citations in docs still point away from the code they describe. For example, docs/design-principles.md:74-76 cites src/Infrastructure/ServiceBasedPlugin.php:90 for registration; line 90 is now a docblock beside DELEGATIONS_FILTER. The actual hook installation is ServiceBasedPlugin.php:1220-1227. The earlier report's claim that line 90 was INJECTOR_ID was specific to main 1228940 and has drifted too.
Other examples include the constructor references in docs/design-principles.md:135 and :156 (now ServiceBasedPlugin.php:362-406) and idempotence references at :537-538 (now register_services()'s guard at ServiceBasedPlugin.php:1255-1259 and maybe_register_service()'s guard at :1783-1791). docs/patterns.md has further full-path and shorthand citations requiring the same semantic review.
tests/php/Architecture/RepositoryStructureTest.php:46-79 and docs/architecture-rules.md:236 document that architecture.citationsResolve checks paths/ranges, not whether a line supports the prose. An existing line can therefore pass while describing the wrong method.
Out of scope
Runtime/API changes, rewriting unrelated documentation, bulk updates of other files' citations, weakening the existing citation gate, or implementing a new enforcement scheme in this issue.
Scope
Audit every ServiceBasedPlugin citation in docs/, including shorthand line references belonging to that file. Correct line/range anchors against the implementation and name the relevant method alongside the citation where that makes its meaning reviewable. Preserve documented behaviour and existing policy rulings. Record a short assessment of possible drift prevention (including costs/limits); a new automated gate is a separately scoped proposal, not required here.
Acceptance criteria
- Inventory the full-path and shorthand ServiceBasedPlugin citations in docs/ and verify each against the behaviour its paragraph claims.
- Correct every mismatched anchor at the implementation commit used for the change; identify the relevant method in prose where needed for clarity.
- Re-read the surrounding paragraphs to ensure the new anchors support the stated behaviour and do not silently alter policy.
- Record which references were corrected and a bounded assessment of method-name/automation options. File any concrete out-of-scope work rather than expanding this patch.
- The citation architecture checks, composer test and composer lint pass in the supported environment.
Verification
rg -n 'ServiceBasedPlugin\.php|`:[0-9]+' docs
composer test:architecture
composer test
composer lintThe search is an inventory aid; a reviewer must inspect the referenced methods and surrounding prose. Passing citationsResolve alone is insufficient evidence of semantic accuracy.
Impact on generated plugins
Documentation only: plugin authors receive usable implementation pointers; runtime and public contracts stay unchanged.
Priority p2: ordinary unscheduled documentation repair. The bounded correction work is ready without deciding a new architecture-rule design.
Updated 2026-10-24: Verified semantic citation drift, corrected the report’s now-stale INJECTOR_ID example and completed the documentation-only brief. Added p2 and agent-ready; prevention is an assessment, with new enforcement outside this patch. Reviewed origin/main 15cac4c2.
Activity
schlessera commentedon Oct 24, 2026
Triage (2026-10-24): Verified semantic citation drift, corrected the report’s now-stale INJECTOR_ID example and completed the documentation-only brief. Added p2 and agent-ready; prevention is an assessment, with new enforcement outside this patch.