docs: moderation foundation — design, staged plan, executable slice-1 plan #52

Merged

starsetbyte merged 3 commits from docs/moderation-foundation into main

2026-07-05 12:41:40 +00:00

starsetbyte commented

2026-07-04 23:21:02 +00:00

Owner

Archaeology + architecture for the moderation rebuild. Docs only — no code changes (plus stale-fact fixes in CLAUDE.md). Implementation is explicitly deferred to a follow-up feat/moderation-core branch.

What's in here

docs/superpowers/specs/2026-07-04-moderation-foundation-design.md — the design spec:

Current-main architecture map of every moderation touchpoint (verified against df53b08): labels barely enter the app today, viewer.muted/blockedBy are destroyed at the Room layer, threads silently drop blocked items, no mute/block APIs exist.
Salvage report for the old feat/moderation branch (PR #11). That branch is reference-only and must never merge: it carries a conflicting v9 schema, its fatal default-Show label bug (unconfigured labels did nothing — matching the "labels do not apply consistently" comment on #11), and UI written against a pre-PostCardStyle PostCard. Salvageable: the engine's snapshot/lambda test pattern, ~44 test cases, and the verified API/DTO layer.
Official Bluesky/ATProto moderation semantics (label spec, @atproto/api decision model, lexicons) as source of truth — including the 8-level cause precedence, adult-content gating, subject targeting, and the fact that hydrated views pre-resolve neg labels.
Proposed architecture: one pure resolver in data/moderation/, raw DTOs separated from internal types, verdicts computed at mapping time, media "blur" implemented as a don't-compose-the-image cover (hot-path contract-test safe), single serialized putPreferences writer.

docs/superpowers/plans/2026-07-04-moderation-foundation.md — seven-stage roadmap: data model → resolver+tests → UI wrappers → timeline/thread/profile/quote/search/notification integration → preference sync (incl. the PreferencesGateway refactor guarding against the PR #25 race class) → reviewed salvage copies → parity backlog.

docs/superpowers/plans/2026-07-04-moderation-core.md — the full executable TDD plan for slice 1: 8 tasks, complete code in every step, ~60 new tests. Shared Label DTO (+neg), labels on post/author/profile/quote views, ViewerState.blocking, Room v10 additive migration, mapper round-trips, and the pure ModerationResolver with official semantics. Zero user-visible behavior change; zero new dependencies.

CLAUDE.md — fixed stale facts: schema is v9 with additive-only migrations (not "v8, destructive"), and the moderation status row now points at these docs instead of the abandoned branch.

Housekeeping done alongside (local only)

Deleted the stale .claude/worktrees/feat+moderation worktree (304MB of build artifacts) and the local worktree-feat+moderation branch — all content is preserved on origin/feat/moderation.

Next step after merge

Execute docs/superpowers/plans/2026-07-04-moderation-core.md on a fresh feat/moderation-core branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XDX1FHPfYkKucU5NYvZRsH

Archaeology + architecture for the moderation rebuild. **Docs only — no code changes** (plus stale-fact fixes in CLAUDE.md). Implementation is explicitly deferred to a follow-up `feat/moderation-core` branch. ## What's in here **`docs/superpowers/specs/2026-07-04-moderation-foundation-design.md`** — the design spec: - Current-main architecture map of every moderation touchpoint (verified against `df53b08`): labels barely enter the app today, `viewer.muted`/`blockedBy` are destroyed at the Room layer, threads silently drop blocked items, no mute/block APIs exist. - Salvage report for the old `feat/moderation` branch (PR #11). **That branch is reference-only and must never merge**: it carries a conflicting v9 schema, its fatal default-Show label bug (unconfigured labels did nothing — matching the "labels do not apply consistently" comment on #11), and UI written against a pre-`PostCardStyle` PostCard. Salvageable: the engine's snapshot/lambda test pattern, ~44 test cases, and the verified API/DTO layer. - Official Bluesky/ATProto moderation semantics (label spec, `@atproto/api` decision model, lexicons) as source of truth — including the 8-level cause precedence, adult-content gating, subject targeting, and the fact that hydrated views pre-resolve `neg` labels. - Proposed architecture: one pure resolver in `data/moderation/`, raw DTOs separated from internal types, verdicts computed at mapping time, media "blur" implemented as a don't-compose-the-image cover (hot-path contract-test safe), single serialized `putPreferences` writer. **`docs/superpowers/plans/2026-07-04-moderation-foundation.md`** — seven-stage roadmap: data model → resolver+tests → UI wrappers → timeline/thread/profile/quote/search/notification integration → preference sync (incl. the `PreferencesGateway` refactor guarding against the PR #25 race class) → reviewed salvage copies → parity backlog. **`docs/superpowers/plans/2026-07-04-moderation-core.md`** — the full executable TDD plan for slice 1: 8 tasks, complete code in every step, ~60 new tests. Shared `Label` DTO (+`neg`), `labels` on post/author/profile/quote views, `ViewerState.blocking`, Room v10 additive migration, mapper round-trips, and the pure `ModerationResolver` with official semantics. Zero user-visible behavior change; zero new dependencies. **`CLAUDE.md`** — fixed stale facts: schema is v9 with additive-only migrations (not "v8, destructive"), and the moderation status row now points at these docs instead of the abandoned branch. ## Housekeeping done alongside (local only) - Deleted the stale `.claude/worktrees/feat+moderation` worktree (304MB of build artifacts) and the local `worktree-feat+moderation` branch — all content is preserved on `origin/feat/moderation`. ## Next step after merge Execute `docs/superpowers/plans/2026-07-04-moderation-core.md` on a fresh `feat/moderation-core` branch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01XDX1FHPfYkKucU5NYvZRsH

starsetbyte added 1 commit

2026-07-04 23:21:02 +00:00

docs: moderation foundation — design spec, staged plan, executable slice-1 plan

peregrine-ci / assembleDebug Build succeeded (19s)

Details

fb4a30ffd8

Archaeology + architecture for the moderation rebuild:

- specs/2026-07-04-moderation-foundation-design.md: current-main
  architecture map (verified), salvage report for the abandoned
  feat/moderation branch (PR #11 — reference only, never merge),
  official Bluesky/ATProto moderation semantics, and the proposed
  central-resolver architecture.
- plans/2026-07-04-moderation-foundation.md: seven-stage roadmap
  (data model -> resolver -> UI wrappers -> surface integration ->
  preference sync -> reviewed salvage -> parity backlog).
- plans/2026-07-04-moderation-core.md: full executable TDD plan for
  slice 1 (feat/moderation-core): shared Label DTO, Room v10 additive
  migration, mapper round-trips, and the pure data/moderation resolver
  with ~60 tests. No implementation in this PR.
- CLAUDE.md: fix stale schema notes (v9, additive migrations) and
  point moderation status at the new docs.

Also cleaned up locally: stale .claude/worktrees/feat+moderation
worktree and worktree-feat+moderation branch (content preserved on
origin/feat/moderation).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XDX1FHPfYkKucU5NYvZRsH

starsetbyte added 1 commit

2026-07-05 12:38:27 +00:00

Merge branch 'main' into docs/moderation-foundation

peregrine-ci / assembleDebug Build succeeded (3s)

Details

464e40c7c2

starsetbyte added 1 commit

2026-07-05 12:40:48 +00:00

Merge branch 'main' into docs/moderation-foundation

peregrine-ci / assembleDebug Build succeeded (2s)

Details

a345084046