reviews

Layerline Reviews

Workflow for the review/approval flow (mcp__layerline__* tools, review domain).

Lifecycle

draft → submitted → in_review → decided (approved | changes_requested | rejected)
                                ↓
                              reopened → in_review → …
                                ↓
                            superseded by newer review

A review hangs off either an asset or a task (provide one of asset_id / task_id), inside a project. It lists file versions, has reviewers with roles, collects comments and per-reviewer decisions, and can carry checklists.

Read tools

list_reviews(projectId, asset_id?, status_id?, decision?, reviewer_id?, due_before?, due_after?, page?, limit?)
get_review(projectId, reviewId)
list_review_comments(projectId, reviewId, status?, type?, severity?, author_id?, review_file_id?)
list_review_decisions(projectId, reviewId)
get_reviewers(projectId, reviewId)
get_review_checklists(reviewId)

Create / lifecycle

create_review(projectId, asset_id? | task_id?, title?, description?, review_type?, due_at?, file_version_ids?[])
update_review(projectId, reviewId, title?, description?, due_at?)   // due_at: null clears it
delete_review(projectId, reviewId)                                  // soft delete

submit_for_review(projectId, reviewId)              // draft → submitted
start_review(projectId, reviewId)                    // submitted → in_review
change_review_status(projectId, reviewId, statusId)  // jump to any project review status
reopen_review(projectId, reviewId)                   // decided → in_review (clears decision)
supersede_review(projectId, reviewId, newReviewId)   // close old; reference newer

file_version_ids shape:

[{ file_id: <ls fileId>, file_version_id: <ls versionId>, compare_version_id?: <ls versionId> }]

Resolve file ids via the storage tools (ls_list_files, ls_find_file_by_path, ls_get_version_history).

Files in a review

add_files_to_review(projectId, reviewId, file_version_ids[])
remove_file_from_review(projectId, reviewId, reviewFileId)

reviewFileId is the junction id (returned by add_files_to_review / get_review), not the underlying file id.

Reviewers

assign_reviewers(projectId, reviewId, reviewers[])
   // reviewers: [{ user_id, role: "reviewer"|"approver"|"final_approver"|"observer" }]
remove_reviewer(projectId, reviewId, reviewerUserId)
get_reviewers(projectId, reviewId)

Roles, briefly:

• reviewer — leaves comments, no formal decision.
• approver — submits a decision; counts toward approval.
• final_approver — same as approver; their decision is the gate.
• observer — read-only; cannot submit decisions.

Comments

Threaded with parent_id; can be attached to a specific reviewed file via review_file_id.

create_review_comment(projectId, reviewId, body, type?, severity?, parent_id?, review_file_id?)
   // type: "general" | "blocker" | "suggestion" | "question" | "praise"
list_review_comments(projectId, reviewId, status?, type?, severity?, author_id?, review_file_id?)
update_review_comment(projectId, reviewId, commentId, body?, type?, severity?)
delete_review_comment(projectId, reviewId, commentId)
resolve_review_comment(projectId, reviewId, commentId)
reopen_review_comment(projectId, reviewId, commentId)

type: "blocker" is special — open blockers prevent approval and trigger warnings in pre_submit_check.

Decisions

submit_review_decision(projectId, reviewId, decision, reason?)
   // decision: "approved" | "changes_requested" | "rejected"
list_review_decisions(projectId, reviewId)

submit_file_decision(projectId, reviewId, reviewFileId, decision, reason?)

The authenticated user must already be an assigned reviewer (not observer) to submit a decision. Per-file decisions live alongside per-reviewer decisions — useful when a review covers multiple files and one is fine but another needs changes.

Checklists

get_review_checklists(reviewId)
attach_checklist(reviewId, template_id? | (name + items[]))
update_checklist_item(itemId, result, notes?)
   // result: "pass" | "fail" | "na" | null (null = clear)

Either pass a template_id (org-wide saved checklist) or pass a custom name + items[] (array of label strings) for a one-off.

AI helpers

generate_review_change_summary(reviewId)
   // Cached summary of file diffs; returns structured payload for AI consumption.

summarize_review_comments(reviewId)
   // Counts, blockers, type/severity breakdown, suggestedAction.

rewrite_feedback_actionable(originalText, reviewId?)
   // Returns instruction to rewrite vague feedback into { area, problem, desired_outcome, severity }.

estimate_approval_readiness(reviewId)
   // Score 0–1, verdict (likely_approved | likely_needs_changes | unlikely_to_approve | blocked).

pre_submit_check(reviewId)
   // Checks unresolved blockers, unchecked checklist items, failed checklist items.
   // Returns { passed: boolean, warnings[], recommendation }.

These are great when the user says "is this ready to ship?" or "summarise the feedback" — they avoid you needing to read every comment.

Common workflows

"Open a review on Hero Knight's modeling pass"

1. Resolve projectId, assetId (Hero Knight).
2. ls_find_file_by_path(projectId, "Characters/Hero Knight/Modeling/hero_v05.fbx") → get fileId.
3. ls_get_version_history(fileId) → grab the latest version.id.
4. create_review(projectId, asset_id=heroId, title="Hero Knight modeling pass v05", file_version_ids=[{ file_id, file_version_id }]).
5. assign_reviewers(projectId, reviewId, [{ user_id: artLeadId, role: "approver" }]).
6. submit_for_review(projectId, reviewId).

"Is review X ready to submit?"

1. pre_submit_check(reviewId).
2. If passed: false, list the warnings to the user and stop. Don't auto-fix.

"Approve review X"

1. get_reviewers(projectId, reviewId) → confirm the user is an assigned approver.
2. submit_review_decision(projectId, reviewId, decision="approved", reason?).

"Summarise the feedback on review X"

1. summarize_review_comments(reviewId) — gives counts + blockers.
2. If the user wants more, list_review_comments(projectId, reviewId, status="open").

"Add a checklist 'Animation QA' to this review"

1. attach_checklist(reviewId, name="Animation QA", items=["Foot sliding fixed","Loop seamless","No clipping","FPS stable"]).
2. As reviewers go, they call update_checklist_item(itemId, result="pass"|"fail"|"na", notes?).

Pairings

• File version IDs come from layerline:storage (ls_* tools).
• Reviews on tasks rather than assets? Pass task_id instead of asset_id to create_review.
• AI rewriting of vague feedback into actionable form is rewrite_feedback_actionable — pair with update_review_comment to actually replace the text.