Disciplines · Decisions (ADRs)

ADR-0034: OSHUN Studio Commenting and Annotation System

Studio teams need structured collaboration feedback tied to exact entities, timelines, and decision points.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN Security
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio teams need structured collaboration feedback tied to exact entities, timelines, and decision points. Existing feedback loops are fragmented across chat, tickets, and ad hoc notes, which disconnects commentary from execution context and slows production decisions.

Without a canonical commenting/annotation system, OSHUN risks:

  • loss of review context and weak decision traceability
  • duplicated or contradictory feedback across teams
  • delayed remediation due unclear ownership/resolution state
  • poor auditability for moderation, governance, and compliance review

Decision Drivers#

  • Contextual precision: comments must bind to concrete entities/selections.
  • Traceability: every annotation lifecycle state must be auditable.
  • Determinism: predictable threading, ordering, and resolution semantics.
  • Security: policy-aware visibility, moderation, and redaction behavior.
  • Interoperability: common model across Yemaya/Isis/Hathor/Aja/Bellona.

Considered Options#

Option 1: External Tool-Only Feedback#

Rely on external issue trackers/chat without in-product annotations.

Pros:

  • Minimal implementation inside Studio surfaces.

Cons:

  • Context fragmentation and weak operational continuity.
  • High reconciliation overhead for teams and compliance.

Option 2: Domain-Local Comment Models#

Allow each domain to define local comment/annotation semantics.

Pros:

  • Fast local implementation for individual domains.

Cons:

  • Inconsistent threading, moderation, and resolution semantics.
  • Poor cross-domain governance and portability.

Option 3: Canonical Studio Commenting and Annotation Contracts (Chosen)#

Adopt one policy-aware annotation model with typed envelopes, threading, resolution lifecycle, moderation controls, and audit contracts.

Pros:

  • Consistent collaboration feedback and ownership tracking.
  • Strong moderation/compliance and lifecycle traceability.
  • Better cross-domain decision alignment.

Cons:

  • Requires governance coordination and schema discipline.

Decision Outcome#

Chosen option: Option 3.

Commenting/annotation requirements:

  1. Canonical annotation envelope with actor/target/location context.
  2. Threading contract for deterministic parent/reply ordering.
  3. Resolution lifecycle contract for open/acknowledged/resolved states.
  4. Moderation and policy contract for visibility, redaction, and abuse controls.
  5. Audit and governance contract for retention and evidence integrity.

Normative Rules#

Canonical Annotation Envelope Contract#

  • Every annotation must include annotationId, targetRef, actorId, content, and occurredAt.
  • Rich location metadata (frame, token range, object coordinates) must be structured in extension fields.
  • Invalid annotation envelopes must be rejected before persistence.

Threading Contract#

  • Parent-child relationships must be explicit and immutable.
  • Thread ordering must remain deterministic for identical query parameters.
  • Deleted or redacted comments must preserve thread continuity markers.

Resolution Lifecycle Contract#

  • Annotation states must transition via explicit lifecycle actions.
  • Resolution requires owner attribution and resolution rationale metadata.
  • Reopen actions must preserve prior resolution evidence and timestamps.

Moderation and Policy Contract#

  • Visibility scope must enforce role/tenant/data policy boundaries.
  • Moderation actions (hide/redact/lock) must be policy-gated and auditable.
  • Sensitive content handling must apply redaction and retention requirements.

Audit and Governance Contract#

  • Annotation lifecycle events must emit structured audit records.
  • Retention/classification tags must be attached to governance exports.
  • Audit event loss or corruption must surface explicit degraded-state warnings.

Release Validity Contract#

A commenting/annotation release is valid only when all are true:

  • envelope compatibility validation passes
  • thread ordering and continuity tests pass
  • lifecycle transition tests pass
  • moderation/policy enforcement tests pass
  • telemetry/audit integrity checks pass
  • rollback plan and owner handoff are documented

Architecture Implications#

  • Studio surfaces share one annotation envelope and thread model.
  • BFF persists annotation lifecycle state with moderation guardrails.
  • Domain adapters attach target/location context to canonical annotations.
  • Analytics pipelines measure annotation throughput, resolution health, and moderation outcomes.

Acceptance Criteria (OST-00169)#

OST-00169 is complete only when:

  1. ADR exists at docs/adr/ADR-0040-oshun-studio-commenting-and-annotation-system.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines annotation envelope, threading, lifecycle, moderation/policy, audit/governance, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0033, especially ADR-0012, ADR-0032, and ADR-0033.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/analytics, and libs/oshun/domain-registry.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Faster contextual collaboration and clearer decision histories.
  • Stronger moderation and compliance posture for collaboration feedback.
  • Better cross-domain accountability for resolution workflows.

Negative#

  • Increased lifecycle and moderation governance complexity.
  • Requires consistent adapter and tooling integration across domains.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0038-oshun-studio-real-time-collaboration-substrate.md
  • docs/adr/ADR-0039-oshun-studio-presence-and-cursor-systems.md

References#

  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/design/ux-principles.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md