WP-LIT-MCP/docs/superpowers/notes/2026-09-26-etappe-1b-rulings.md

# Etappe 1b – Entscheidungen (Rulings) und offene Kleinigkeiten

Aus dem SDD-Ledger übernommen, 2026-09-26.

 - Q1 (B1): T1 test expects sorted order ['logo','photo'] (code sorts) — fix the test.
 - Q2 (B2/B4): every task that adds/changes a direct tool updates docs/guides/overview.md "Direkt sichtbar:" in the same task; T13 keeps the exact heading "Direkt sichtbar:" (ToolNamingTest regex).
 - Q3 (B3): indirect tools are always written lit/<name> in descriptions/hints (ToolNamingTest).
 - Q4 (R1/C1/C3): media writes reuse 1a building blocks: ChangeLog via FollowUp (or PostChangeResult-style helper), failures after irreversible steps → WriteFailed (clean → write_failed, file kept but meta failed → partial_write with attachment id), server-side failures → Errors::writeFailed not validation_failed/unsupported; one shared helper for both upload abilities (no duplicated permission/result code).
 - Q5 (R2/C4): URL import passes limit_response_size (Limits upload MB) to the download and rejects early on Content-Length; upload MIME list = intersect(filter result, get_allowed_mime_types()); SVG only if WordPress itself allows it for the user.
 - Q6 (R3): lit/media-download is a DIRECT tool (embedded resource only works for direct tools); overview updated.
 - Q7 (R4/C6): usage finder covers featured image, [gallery ids], Divi gallery_ids, block "ids"/"id", wp-image-<id> classes, custom_logo/site_icon, Divi image attrs, file-name URL matches in content, Pods/ACF meta ids; uncertain → "möglicherweise verwendet" (blocks delete without force); usages list only titles of posts the user can read (else "(nicht lesbar)").
 - Q8 (R5): unused search caps work per call (small candidate batch, max N isUsed checks, then next_cursor) — no multi-hundred full scans per request.
 - Q9 (R6): multisite: Access tab lists/revokes only users that belong to the current site; a non-super-admin cannot revoke super admins' connections.
 - Q10 (R7): add Task 14 at the end: 1a deferred items (menu rev for menu-set-items, lit_mcp_guides filter per spec §9.2, warnings: trashing front page / menu-linked page, menu location unassign needs confirm, scheduling a private entry makes it public, divi hint wording; missedSchedule +60s window and zero-GMT fallback; write_failed wording mentions kept backup/revision).
 - Q11 (R8): server instructions (dynamic) list the currently direct tools; hints use the neutral form "lit/<name>" plus "(direkt als lit-<name>, falls freigeschaltet, sonst über mcp-adapter-execute-ability)"; guides state that direct visibility depends on the settings.
 - Q12 (C2): MediaGuard refuses trashed attachments unless opted in; delete of trashed attachment refuses (would be permanent).
 - Q13 (C5): log tab links objects by object_type (post types → edit link, attachment → media, nav_menu → menus screen, settings → none).
 - Q14 (C7): Site Health test async or transient-cached; (C8) readme wording per 1a (which tools are revertible how); (C9) tempnam in tests; (C10) media-update uses per-item post_modified_gmt as optimistic lock via optional `modified` in input — accepted if cheap, else ruling "no lock for media metadata" documented; (C11) no duplicate notice, refuse removing the current user's own role; (C12) add the client-name app-password test.
 - Task 1: Ruling Q7b: usage search also covers widgets, header_image_data, background_image; uncovered (term/user meta, Pods tables, ACF, CSV id lists in meta, other plugins' options) documented and must be repeated in media-delete description (T5)
 - Task 3: minor (deferred): failure branches (editor WP_Error, resize/save fail, missing file) untested; preview/download refuse trashed while media-get allows (intentional: trashed media not served)
 - Task 4: accepted deviation: Content-Length only checked after capped download (Q5 "early" not feasible without HEAD)
 - Task 4: minor (deferred): M1 filter keeps last sideload path (guard $moved === null); IPv4 pin only for cURL transport; DNS rebinding residual (core)
 - Task 5: minor (deferred): docblock misplacement MediaUsageFinder constructor; guides must mention media tools (T13)
 - Task 6: Ruling Q11b: remaining Q11 parts (hints naming direct-by-default tools written neutrally "lit/<name> (direkt: lit-<name>, falls freigeschaltet)", guides state that direct visibility is configurable) are carried into Task 10 (settings UI makes overrides possible) — cost if wrong: stale tool names in hints after an admin override
 - Task 9: minor (deferred, final wave): nonce bind user+uuid; is_string guard for uuid; JS confirm on revoke; own-role warning only on change; cache_users before loop; heading "Verbindungen" (may include expired sessions)
 - Task 10: Ruling Q11c: neutral tool naming applied to error hints only; ability descriptions/schemas keep default names (instructions list the current direct tools, so Claude can map) — cost if wrong: descriptions name a tool form that is not listed after an override
 - Task 10: minor (deferred): ExposurePolicy::sanitize keeps unknown-but-wellformed ability names (dead data)
 - Task 11: minor (deferred): filters()/extraFilters() split; date shape-only validation; JS-only clear confirm
 - Task 12: minor (deferred): Uninstaller::removeSiteData public but internal
 - Ruling Q15: Task 14 (deferred 1a items, brief written by controller) runs BEFORE Task 13 so docs/E2E cover it — cost if wrong: none
 - Task 14: accepted: Errors::writeFailed ?$state + WriteFailed::$rolledBackState added (existing params couldn't replace the sentence)
 - Task 14: minor (deferred, final wave): schedule test asserts 'öffentlich' substring (use 'ÖFFENTLICH'); numeric guide topics from filter dropped; Rev::ofMenu docblock; menu-get→set-items unit round trip; Pods textdomain notices noise check
 - Task 13: minor (deferred): readme doesn't mention lit_mcp_upload_mimes filter
 - Final review 1b: with fixes. Ruling Q16: fix wave = I1 download hard cap 10 MB + upload bound max 32 MB (tab label), I2 filename search via wp_allow_query_attachment_by_filename, M3 edit_user in manageable(), M4 mcp.public=false for DIRECT_ONLY, M5 wp_slash alt/title on upload, M6 neutral sideload error (log detail), M7 menu-assign-location destructive:true, M8 readme corrections (MEDIA_TRASH constant, site filters, super admins), M9 neutral hint in preview, deferred cheap: MediaUsageFinder docblock, Task 9 is_string uuid guard, Task 14 'ÖFFENTLICH' assertion, Rev::ofMenu docblock. Etappe-2 notes (requiresDirect flag, tree_rev, direct tool count) → Etappe 2 planning.