โ† Back to Roadmap

Review tool

17 features

๐Ÿ“‹ Description

The Review Tool streamlines collaboration by providing a focused, user-friendly space for subject-matter experts and stakeholders to comment on, annotate, and approve content. With clear version tracking and consolidated feedback, it enables structured workflows.

๐Ÿ’Ž Business Value

Accelerates review cycles, reduces confusion, and helps teams deliver accurate, high-quality documentation faster.
โœ“ Merged to main
๐Ÿ• Development time: 4d-00h-38mโฑ Time to deployment: 0d-00h-04m

๐Ÿ”ง API Changes (11 files)

  • M src/Aleido.Platform.API/Endpoints/HierarchyEndpoints.Comments.cs
  • M src/Aleido.Platform.API/Endpoints/ObjectCommentsEndpoints.cs
  • M src/Aleido.Platform.API/Helpers/ProblemDetailsFactory.cs
  • M src/Aleido.Platform.API/Mappers/ReviewRoundMapper.cs
  • M src/Aleido.Platform.API/Models/Requests/CollaborationRequests.cs
  • M src/Aleido.Platform.API/Models/Requests/CreateObjectRequest.cs
  • M src/Aleido.Platform.API/Models/Requests/ReviewRoundRequests.cs
  • M src/Aleido.Platform.API/Models/Responses/CollaborationResponses.cs
  • M src/Aleido.Platform.API/Models/Responses/ReviewRoundResponses.cs
  • M src/Aleido.Platform.API/Services/CollaborationService.cs
  • M src/Aleido.Platform.API/Services/ICollaborationService.cs

๐Ÿ“ Commit Log

95ecd8c40 Handle BI emitter failures with logging, not exceptions 7e6dd0c95 Propagate unexpected BI emitter exceptions cd1be99b1 Add robust error handling for audit and BI event failures 177a2966c Ensure BI/audit failures never break mutations b8e615fd6 Emit BI events for comments; update review comments docs 1e6612b54 Merge branch 'main' into 052-review-comments-enhancement 4fe1057ee feat: add orchestration for durable review-round lifecycle coordination 7626d0391 Merge branch 'main' into 052-review-comments-enhancement 8ec056cd4 Require If-Match header for comment delete APIs 82f6dc4de feat: complete review comments enhancement d4e83d21b Clarify audit trail criteria for review-round assignments 1a320f145 Update review comments plan/spec: clarify, expand coverage 456b46229 tasks.md now makes delete/discard handling traceable for both durable cleanup recovery and the delete-route concurrency contract. 4eb33fea8 - Draft discard is now explicit: Draft comments can be discarded anytime with the current eTag, and discard removes attachments too. - Concurrency scope is now unified: existing-comment mutations share one ETag rule set, with a clear concurrency matrix. - Attachment safety is now formalized in spec.md via FR-026 to FR-031, covering staged-file authorization, parent-comment concurrency, repair records, discriminators, and deterministic repair IDs. - Delete rules now use a concrete author delete-state matrix instead of vague โ€œworkflow state rulesโ€. - Status naming is normalized to InProgress everywhere. - Success-criteria coverage is now explicit in both plan.md and tasks.md, with added validation work for SC-001, SC-003, and SC-007. 1a61ca3c3 Migration/backfill is not relevant here. Since there are no existing comments, the migration/backfill path was unnecessary, so I removed it and restored a strict greenfield rule set. 194e5903d Enforce discriminators and deterministic repair records 145a1f3a7 Spec 052 now requires staged-file promotion to resolve stagedFileId only within the current workspaceId and authorize the current actor before promotion, and it no longer allows outstanding blob cleanup without a persisted durable repair record. 093ca30b1 Enforce dual-store consistency for comment attachments 9ff7293f7 Merge branch 'main' into 052-review-comments-enhancement 5653e850e Review Comments Enhancement: design & implementation plan 4ec773100 Merge branch 'main' into 052-review-comments-enhancement e3dbac688 feat: Add specification quality checklist and feature specification for review comments enhancement

Comment Domain and API Foundations

No description available

Anchored and Threaded Conversations

No description available

Comment Workflow, Scope, and Classification

No description available

Attachments, Deletion, and Delivery Assurance

No description available

Review participation foundations

No description available

API contract and handover documentation

No description available

Sign-off workflows and contextual visibility

No description available

Baseline capture and filtered review views

No description available

Scope resolution and review status

No description available

Review round foundation and lifecycle orchestration

No description available

Direct reviewer assignment and delegation

No description available

Review groups and criteria-based assignment

No description available

Authorization, contracts, and delivery assurance

No description available

Round Detail, Scope, Content, and Manager Oversight

This feature delivers the deeper round participation experience once a user opens a review: understanding assigned versus contextual scope, navigating recipe-based structure, opening content in the right reviewer-safe context, comparing what changed, signing off, and for round managers, overseeing reviewer-by-reviewer progress including terminal rounds. It solves the core execution problem of helping participants understand exactly what is in scope now, what changed from baselines or prior rounds, what is complete, and where attention is still needed. The implementation spans API aliases for round detail, scope, content, and sign-off actions; Azure service projections for assignment summaries, scope summaries, recipe navigation nodes, compare references, sign-off history, context labels, and profile-preserving content views; and DTO and mapper updates that expose only participant-safe metadata. It also adds manager-only projections for reviewer progress rows, unassigned coverage, warnings, and terminal-round access, while preserving capability metadata and integrating with existing scope-status and workflow behavior from specs 049 and 051. Important constraints include rejecting context-only sign-off, resolving completion and invalidation against the current in-scope revision identity rather than historical buckets, preserving read-only participation rules, supporting latest-subversion review without content editing, and keeping manager-only breakdowns hidden from ordinary reviewers. Acceptance comes from broad unit and integration coverage across scope aliases, navigation, content access, comparisons, sign-off invalidation, manager oversight, and final regression journeys.

Participant Surface Foundations

This feature establishes the dedicated review surface that reviewers and round managers use to enter review work without exposing authoring or management-only complexity. It solves the baseline discovery and contract problem by creating the participant-specific routes, DTOs, mappings, service contracts, and shared infrastructure needed for every later review participation flow. The implementation spans shared test fixtures, API request and response scaffolding, endpoint anchors, projection models, mapper and service contract extensions, repository interfaces, DI wiring, ProblemDetails behavior, OpenAPI coverage, and core access/progress helper utilities. It introduces the participant inbox route, enforces read-only response shaping, removes management-only fields from participant DTOs, supports participant-safe delegation aliases, and adds the canonical foundations for reminder-aware due-date context, audit constants, and repository lookups that later features rely on. The main constraints are the guardrails around participant safety: reviewer-facing payloads must avoid raw Work Package metadata where prohibited, preserve reviewer read-only behavior, and keep delegation and access semantics aligned with spec 049. Acceptance is signaled by endpoint capability coverage, empty-state and dedicated-surface integration tests, contract validation, build and test completion, and quickstart/NFR verification including latency and freshness checks.

Feedback Continuity and Cross-Cycle Comment Handling

This feature delivers the feedback workflow for reviewers by preserving their ability to comment safely in review context, see historical discussion across cycles, and retain useful comment links even when rounds are cancelled or draft targets change. It solves the continuity problem that would otherwise fragment review feedback across revisions, rounds, and rebinding events. The implementation extends the canonical comment aggregate with cancelled-draft provenance metadata, adds repository and service behavior for exact workspace/object/language draft rebinding, and updates collaboration and round services to return participant-safe comment context metadata, historical round visibility, sign-off and comment continuity, and orphan-anchor fallback cues. It also emits audit and BI events for rebinding while preserving existing spec 052 lifecycle rules around permissions, classification, attachments, delete behavior, and round-filtered querying. Critical constraints are the exact qualification rule for rebinding, the distinction between single-target rebind and ambiguous-target retention, and the need to preserve reviewer-safe visibility into current and historical comments without granting content mutation capabilities. Acceptance is shown through unit and integration coverage for lifecycle restrictions, historical visibility, rebinding behavior, audit emission, cross-cycle continuity, and missing-anchor fallback behavior.

Inbox Discovery and Progress Tracking

This feature delivers the participant inbox experience for discovering assigned review work, understanding urgency, and tracking completion at both personal and aggregate levels. It solves the day-to-day reviewer and round-manager need to find active rounds quickly, understand delegation and due dates, and see progress that stays correct when scope or current revisions change. The implementation builds inbox projection models, reviewer-safe DTOs, service logic for active-round filtering and row shaping, reminder-aware due-date context, delegated-assignment summaries, and progress calculations resolved against the current in-scope revision identity. It also adds visibility controls so ordinary reviewers see only aggregate progress while round managers can later consume the same underlying calculations, and it wires reminder-related tests into notification and scheduling journeys to keep inbox-visible deadlines aligned with platform scheduling behavior. Key edge cases include context-only rows, delegated origin and handoff metadata, empty states, and invalidation semantics where newly current revisions push previously completed items back to pending without losing invalidation visibility. Acceptance is demonstrated through unit and integration coverage for multi-round discovery, reminders, personal progress recalculation, and aggregate progress behavior.