Skip to content

docs: ServiceBasedPlugin citations point at the wrong lines #181

Open

Description

@schlessera

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 lint

The 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

  1. added
    area: docsREADME, AGENTS.md, docs/ and inline documentation meant for plugin authors.
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    on Oct 24, 2026
  2. schlessera commented on Oct 24, 2026

    @schlessera
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.area: docsREADME, AGENTS.md, docs/ and inline documentation meant for plugin authors.priority: p2Wanted, not scheduled.type: docsDocumentation only.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions