Admin Mediation Layer — Why Open Paws Sits Between Students and Clients

[LarytheLord]

Related Issue

This discussion provides deep context for issue #105 (Admin QA Mediation Layer). Read this before building that issue.

---

The Problem Without Mediation

Without a mediation layer, the submission flow looks like this:

Student submits → Client sees it immediately

Problems with this:

• A bootcamp student's first real submission is often not client-ready
• The client has no way to know they're looking at a student's work
• One bad experience poisons the whole client relationship
• The student gets unfiltered negative feedback that may be demoralising
• Open Paws has no visibility until damage is already done

This is not hypothetical. Every training program that deploys learners on real client work without a QA layer has this problem.

---

The Solution: Open Paws in the Middle

Student submits
  → status: pending_admin_review
  → Admin QA queue lights up
  → Admin reviews the submission
  
  IF acceptable:
    → status: review
    → Client now sees it (looks like any normal submission to them)
  
  IF not ready:
    → status: needs_rework
    → revisionCount increments
    → Admin's notes go to student
    → Student revises and resubmits

The client never knows about pending_admin_review. From their perspective, submissions appear in the review queue when they are ready to be reviewed. The messy QA negotiation is invisible to them.

---

Who This Applies To

Track	Goes through pending_admin_review?
BOOTCAMP	Yes — always
INTERN	Yes — always
OPEN	No — goes direct to client review

Why does INTERN track also go through QA? Even experienced interns can produce work that needs mediation. Open Paws is still accountable to the client. The QA gate stays regardless of intern skill level.

Why does OPEN track skip it? OPEN track is the professional marketplace. Adventurers who reach D+ rank have already been vetted through multiple quest completions. They deal with clients directly. Adding a QA gate to OPEN track would undermine the trust-via-rank model.

---

The Admin QA Queue

Admin sees a real-time queue of all submissions waiting for review:

QA Queue (3 pending)

Quest              | Student       | Track    | Submitted  | Action
Fix navbar CSS     | Amir K [E]    | BOOTCAMP | 2h ago     | [Review]
Auth module        | Sara J [D]    | INTERN   | 5h ago     | [Review]
Write API tests    | Ben T [F]     | BOOTCAMP | 1d ago     | [Review]

Oldest first (FIFO) — prevents submissions from sitting indefinitely.

---

The Two QA Outcomes

Approve

Admin clicks Approve. Assignment moves from pending_admin_review → review. The company/client now sees the submission in their review queue and can approve/reject it with the normal review flow.

No notes required. The message to the client is implicit: "this is ready for your review."

Reject

Admin clicks Reject. Opens a notes modal. Notes are required — the student needs to know specifically what to fix.

Assignment moves to needs_rework. revisionCount increments (same as a client rejection).

The 2-revision cap still applies. If the student has already used up 2 admin rejections, admin sees the escalation path instead of the reject form.

---

What Admin Notes Look Like

Admin rejection notes are stored in submission.reviewNotes as a JSON array, same as company revision notes:

[
  {
    "id": "uuid",
    "timestamp": "2026-03-18T11:00:00Z",
    "author": "Admin",
    "note": "The CSS changes break on mobile. Test at 375px width. Also the PR is missing a description — add a summary of what you changed and why."
  }
]

The student sees this in their assignment detail view.

---

What the Adventurer Sees

The adventurer sees their assignment status as "Under QA Review" (not "Pending Admin Review" — the wording should not expose internal process).

Your Assignment: Fix navbar CSS
Status: Under QA Review
Submitted: 2 hours ago

"Your submission is being reviewed by the Open Paws team. You'll hear back soon."

If admin rejects: status changes to "Needs Revision" and the notes appear.

---

Why Admin Rejection Counts Against the Revision Cap

When admin rejects, revisionCount increments. This might seem harsh — the student never even got client feedback. But:

1. The revision cap protects students from infinite revision loops, not just from difficult clients
2. If a student has submitted poor work twice, the issue is a quality problem that needs escalation, not a third revision
3. The admin is acting as the quality arbiter — their rejection has the same weight as a client rejection

If this ever becomes a problem in practice (admin being too strict), the maxRevisions field on each quest can be increased by admin for specific quests.

---

Interaction with the Party System

When a squad (party) submits work, the pending_admin_review gate still applies. Admin sees one submission from the quest — not N submissions from N members. The party leader is responsible for ensuring the submission represents the whole party's work.

This is intentional: the party system is a delivery unit, and the delivery unit submits as one.

---

Phase 3 Consideration

In Phase 3, we may want to:

• Show admin average review turnaround time (so students know what to expect)
• Allow admin to escalate specific submissions to a senior reviewer
• Log all QA decisions in the EventLog (issue feat: Quest Event Audit Trail — EventLog model and admin quest timeline #108)

None of these are in scope for Phase 2 (issue #105). Build only what is described in the issue spec.