Design privileged work-item comment moderation

[ScottArbeit]

Design privileged work-item comment moderation

Objective

Define the smallest privileged content-moderation capability for work-item comments as standalone design work outside
the work-item coordination-surface epic.

This issue is a design boundary, not an implementation task. Implementation must not begin until the product and
storage decisions below are closed and converted into Plan-ready tracked work.

Why this matters

Grace comments are intended to remain a truthful, immutable collaboration history. Ordinary collaborators, including
the comment creator, therefore have no delete or hide operation and use explicit correction comments instead. Grace
still needs a way to handle unacceptable content without expanding the ordinary comment lifecycle or prescribing a
larger social-collaboration model.

Accepted context and evidence

• The canonical design is docs/Design concepts/Work-item coordination surface.md, DEC-012.
• Ordinary comment deletion and hiding are rejected for the coordination surface.
• Administrative moderation is required eventually but is explicitly deferred outside that epic.
• Comments are expected to reuse repository-scoped immutable TextContent storage delivered through Epic Epic: Implement blob-backed work-item descriptions #825.
• Grace has no production records requiring migration or compatibility behavior.

Decisions this issue must close

• The smallest moderation operation and its eligible administrative role or permission.
• Whether ordinary reads retain an explicit tombstone or omit the moderated entry.
• Whether original TextContent is retained, restricted, or physically destroyed.
• Whether administrators can retrieve the original content and whether moderation is reversible.
• Required reason, moderator identity, timestamp, and other audit facts.
• Persistence ordering, retry, restart, replay, missing-blob, and partial-failure behavior.
• Effects on activity, search, notifications, generated contracts, and usage accounting.

Explicit non-goals

• Do not add delete, hide, or restore commands to the ordinary comment interface.
• Do not implement moderation from this exploratory issue.
• Do not reopen replies, discussion resolution, direct comment editing, or edit history.
• Do not pull this work into the work-item coordination-surface epic.

Contract propagation to evaluate

• Shared DTOs, parameters, commands, events, and persisted projection state.
• HTTP route, permission check, error shape, and SDK facade.
• Any separate administrative CLI or operational interface.
• TextContent object storage and retained-content usage accounting.
• OpenAPI and generated clients.
• Activity, search, webhooks, SignalR, and documentation.
• Positive, denied-access, replay, retry, storage-failure, and cross-repository proof.

Owned paths

• docs/Design concepts/Work-item coordination surface.md
• A future focused moderation design or specification artifact if separation improves clarity.
• This GitHub issue.

Forbidden or sensitive paths

• All implementation paths until this issue reaches Design-ready and Plan-ready status.
• The active coordination-surface epic and its implementation branches.

Risk surfaces

• Product and domain design.
• Permissions and administrative access.
• Blob storage, durable actor events, retry, restart, and replay.
• Public and generated contracts.
• Content visibility, activity, search, and accounting.

Validation profile

Docs-only while exploratory: MarkdownLint for changed Markdown, any rendered-artifact validation for companion HTML,
and git diff --check. Later implementation issues must select their own focused profiles.

Definition of done

• Product decisions are accepted, deferred, or explicitly waived.
• The supported moderation flow and failure outcomes are unambiguous.
• The contract propagation map and proof classes are complete.
• The design reaches Plan-ready status or produces narrowly scoped implementation issues.
• No ordinary comment delete or hide capability is introduced.