test: pin polydock app discovery set (spike)

[dan2k3k4]

Adds a characterization test pinning the discovered Polydock app set and refreshes a stale docblock. Tests/docs only.

Greptile Summary

This PR is tests/docs only: it adds a characterization test that pins the exact set of six concrete PolydockAppInterface classes returned by PolydockAppClassDiscovery, refreshes a stale class-level docblock to describe the actual filesystem-scan mechanism, and adds spike notes documenting the investigation.

• Characterization test (test_characterization_pins_exact_discovered_app_set): imports the three previously unimported app classes, builds the expected FQCN list, sorts it with sort() to match the service's ksort() output, and asserts exact equality — giving a loud failure gate if the discovered set ever changes unintentionally.
• Docblock update: removes references to "Composer classmap" and "pre-filter scans for Polydock" that described a pre-inlining version of the service; replaces with accurate description of the current directory-scan approach.
• Spike notes (plans/notes/013-app-discovery-approach.md): documents why no mechanism refactor is needed and flags two future-cleanup candidates (NAMESPACE_FILTERS and the misleading getClassMap() method name).

Confidence Score: 5/5

Safe to merge — all three files are test/doc changes with zero production logic touched.

The service file has only a docblock change; the new test correctly mirrors the service's ksort ordering by using sort() on the same string type; the notes file is inert documentation. No runtime code path was modified.

No files require special attention.

Important Files Changed

Filename	Overview
app/Services/PolydockAppClassDiscovery.php	Docblock-only refresh: replaces stale Composer-classmap description with accurate filesystem-scan description. No logic, behavior, or signature changes.
tests/Unit/Services/PolydockAppClassDiscoveryTest.php	Adds test_characterization_pins_exact_discovered_app_set and the corresponding imports for 3 previously unlisted app classes. Test logic is sound: sort($expected) and ksort() in the service both use standard lexicographic comparison, so ordering is consistent.
plans/notes/013-app-discovery-approach.md	New spike notes document: records the discovery findings, lists the pinned app set, and explains what was deliberately left unchanged. Documentation only, no runtime effect.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[getAvailableAppClasses] --> B{cache !== null?}
    B -- Yes --> C[return cached result]
    B -- No --> D[getClassMap]
    D --> E[File::allFiles\napp/Polydock/Apps]
    E --> F[Map relative path\n→ App\\Polydock\\Apps\\... FQCN]
    F --> G[matchesNamespaceFilter\ncontains 'Polydock'?]
    G -- No --> H[skip]
    G -- Yes --> I[class_exists + ReflectionClass]
    I --> J{isAbstract\nor isInterface?}
    J -- Yes --> H
    J -- No --> K{implementsInterface\nPolydockAppInterface?}
    K -- No --> H
    K -- Yes --> L[buildLabel\nattribute or fallback]
    L --> M[classes map]
    M --> N[ksort]
    N --> O[cache & return]

    style O fill:#4caf50,color:#fff
    style C fill:#4caf50,color:#fff

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[getAvailableAppClasses] --> B{cache !== null?}
    B -- Yes --> C[return cached result]
    B -- No --> D[getClassMap]
    D --> E[File::allFiles\napp/Polydock/Apps]
    E --> F[Map relative path\n→ App\\Polydock\\Apps\\... FQCN]
    F --> G[matchesNamespaceFilter\ncontains 'Polydock'?]
    G -- No --> H[skip]
    G -- Yes --> I[class_exists + ReflectionClass]
    I --> J{isAbstract\nor isInterface?}
    J -- Yes --> H
    J -- No --> K{implementsInterface\nPolydockAppInterface?}
    K -- No --> H
    K -- Yes --> L[buildLabel\nattribute or fallback]
    L --> M[classes map]
    M --> N[ksort]
    N --> O[cache & return]

    style O fill:#4caf50,color:#fff
    style C fill:#4caf50,color:#fff

Loading

_{Reviews (1): Last reviewed commit: "test: pin polydock app discovery set (sp..." | Re-trigger Greptile}