Submit for Grade toggle with configurable point values

# Submit for Grade toggle with configurable point values

A "Submit for Grade" checkbox on the assignment creator that opts an assignment into formal grading, with a teacher-defined point value, and routes Daily Pages to a new holistic GA that grades engagement with ideas instead of mechanics.

## Problem

Today the Grading Assistant (GA) produces grades on a fixed 100-pt scale, and Daily Pages get graded the same way as thesis-driven essays. That breaks down in three ways:

- Teachers can't opt an assignment out of formal grading without disabling GA feedback entirely.
- Point values are locked to 100, so grades don't drop cleanly into a gradebook where assignments are weighted differently (a quiz might be 25 pts; a major essay might be 200).
- Daily Pages get penalized for grammar and syntax the same as a thesis essay, even though the pedagogical point of Daily Pages is exploratory thinking, not mechanics. Teachers work around this by ignoring GA grades on Daily Pages or not submitting them at all.

## Goals

- Let teachers mark an assignment as graded or ungraded at creation time.
- For graded assignments, let teachers set the point value and have GA's output scale proportionally.
- Route Daily Pages to a separate GA mode that rewards holistic engagement with ideas over mechanics.
- Preserve the existing teacher override path on any GA-produced grade or comment.

## Non-goals

- Changing the existing thesis-essay GA behavior at the 100-pt scale — that path is a regression check, not a redesign.
- Building the student-level insights surface itself — this spec is the foundation that makes that data structured; the insights view is its own scope.
- Letting teachers configure rubric weights per-assignment. Point value scales the final number; it does not change what the rubric measures.
- Cross-assignment grade weighting or category math inside Yawp. That stays in the teacher's gradebook of record.

## Domain notes

- **Assignment** — gains a `submit_for_grade` flag and a nullable `point_value`. When unchecked, no grade is written and no gradebook sync occurs; GA feedback still runs.
- **AssignmentType** — drives which GA pipeline runs. Thesis-driven essay uses the existing GA; Daily Pages routes to the new holistic GA.
- **Submission** — gains a displayed grade computed as `GA_percentage × point_value`, rounded to a sensible precision. The native GA percentage stays stored alongside the displayed grade so re-scaling is non-destructive if the teacher edits the point value.
- **Daily Pages GA (new)** — a separate prompt/scoring pipeline trained to score completion + idea engagement, not mechanics. Lives alongside the existing GA, selected by AssignmentType.
- **Teacher override** — existing behavior preserved: teacher can edit GA grade and comments before release. Overrides are logged.

## UX sketch

**Assignment creator — graded path:**

```
+----------------------------------------------------+
| New assignment                                     |
|                                                    |
| Title:        [ ____________________________ ]    |
| Type:         [ Thesis essay  ▾ ]                  |
| Due:          [ 2026-06-01 ]                       |
|                                                    |
| [x] Submit for Grade                               |
|     Point value: [ 100 ]                           |
|                                                    |
| [ Cancel ]              [ Create assignment ]      |
+----------------------------------------------------+
```

- Checkbox defaults to unchecked. Unchecked state hides the Point Value field entirely.
- Checking the box reveals the Point Value input inline (no modal, no page jump).
- Point Value defaults to 100 on first reveal; teacher can edit. Validation: positive integer, max 1000.
- Help text under the checkbox when checked: "Students will see this assignment in their gradebook. The Grading Assistant will produce a grade out of the point value you set."
- Help text when unchecked: "The Grading Assistant will still give feedback, but no grade is recorded."

**Grade display — graded path (teacher and student views):**

```
Submission: Macbeth essay — Period 3
Grade: 180 / 200       (GA: 90%)     [ Override ]
```

- Display format: `points_earned / point_value`. Native GA percentage shown in parentheses for transparency.
- Override button preserved exactly as today — opens the existing edit flow.

**Grade display — ungraded path:**

```
Submission: Daily Pages — 5/19
Feedback ready. No grade recorded.
```

- GA feedback panel renders normally; the grade slot is replaced with a single line indicating no grade was recorded.

## Data model implications

- New columns on `assignments`:
  - `submit_for_grade BOOLEAN NOT NULL DEFAULT FALSE`
  - `point_value INTEGER NULL` (only meaningful when `submit_for_grade = TRUE`)
- New columns on `submissions` (or wherever the graded snapshot lives):
  - `ga_percentage NUMERIC NULL` — the native GA score (0.0–1.0 or 0–100).
  - `displayed_grade NUMERIC NULL` — derived; `ga_percentage × point_value`, rounded.
- Backward compat: all new columns are nullable / default-false. Existing assignments without `submit_for_grade` set behave as ungraded by default, which preserves the workaround pattern teachers already use (ignore GA grades on Daily Pages). For thesis essays already in flight, a one-time backfill flips `submit_for_grade = TRUE, point_value = 100` so behavior matches today's expectations. Backfill is dual-write safe: existing read paths keep working while writes start populating the new columns.
- GA storage: existing GA result rows continue to store the native percentage; the displayed grade computation lives at read time so changes to point value re-scale cleanly without rewriting historical GA outputs.

## File paths in `yawp-2.0` likely to change

- `services/web-app/app/routes/app.my-classes.$courseId.assignments.new/route.tsx` — checkbox + point value input in the assignment creator form.
- `services/web-app/app/components/assignment-form/...` — form schema + validation for the new fields.
- `services/web-app/app/routes/app.submissions.$submissionId/...` — grade display logic for graded vs. ungraded paths.
- `services/grading-assistant/...` — branch on AssignmentType to route Daily Pages to the new holistic GA pipeline.
- `services/grading-assistant/prompts/daily-pages.ts` (new) — holistic GA prompt focused on idea engagement.
- `packages/db/migrations/...` — additive migration for the new columns + backfill script.
- Gradebook integration layer (wherever grade sync to external gradebooks lives) — confirm non-100 point scales pass through cleanly.

## Open questions

- [ ] Brian: Rounding precision on the displayed grade — whole points, or one decimal (e.g., 90.5 / 100)?
- [ ] Bryant: Confirm gradebook integration handles non-100 point scales without special-casing.
- [ ] Owner for the Daily Pages holistic GA prompt + training pass. Prerequisite for the Daily Pages path of this spec.
- [ ] Should the Point Value input remember the teacher's last-used value per AssignmentType, or always default to 100?
- [ ] If a teacher unchecks "Submit for Grade" on an assignment that already has graded submissions, what happens to the existing grades — preserved, hidden, or blocked with a confirmation?
- [ ] Where does the override log live and who can view it? (Teacher-only? Admin audit trail?)

## Edge cases

- Teacher toggles "Submit for Grade" off → on after some students have submitted: GA feedback already exists; the displayed grade backfills from stored GA percentage × the new point value. No re-grading required.
- Teacher changes point value after grades are released: existing graded submissions re-scale automatically because `displayed_grade` is derived. Released grades visible to students update on next view — surface a teacher-facing warning before saving the change.
- Daily Pages assignment created before the new holistic GA ships: falls back to ungraded mode (no grade produced) regardless of the checkbox, with a help-text note explaining the holistic grading mode isn't available yet.
- Point value of 0 or negative: blocked by form validation.
- Point value of 1000 (max): allowed; values above 1000 blocked with inline validation message.
- Teacher overrides grade, then changes point value: override is preserved verbatim (not re-scaled). Spec assumption — confirm with Brian if this is correct.
- AssignmentType doesn't match a known GA pipeline (e.g., a future custom type): default to thesis-essay GA, log a warning.

## Test plan

- Unit: assignment creator form validates point value (positive integer, ≤ 1000); hides input when unchecked.
- Unit: displayed grade computation = `ga_percentage × point_value`, rounded per the agreed precision.
- Unit: ungraded assignments produce GA feedback but write no grade and trigger no gradebook sync.
- Unit: AssignmentType = Daily Pages routes to the holistic GA pipeline; AssignmentType = thesis essay routes to the existing GA.
- Integration: creating a graded assignment, submitting student work, and viewing the submission shows `points / point_value` plus native GA percentage.
- Integration: changing point value on an assignment with existing graded submissions re-scales the displayed grade without a re-grade.
- Integration: teacher override edits persist through point-value changes per the resolved policy.
- Regression: existing thesis-essay GA behavior at 100 pts is byte-identical to today's output where feasible.
- Manual QA (UA professor flow): create a Daily Pages assignment ungraded; create a Daily Pages assignment graded at 10 pts; create a thesis essay at 200 pts. Verify gradebook export.

## Rollout

Feature flag (`submit_for_grade_toggle`). Default OFF.

Staged path:

1. Ship the checkbox + point-value scaling for thesis essays first, flag-gated to UA professor. This is the lower-risk half — existing GA pipeline, just scaled.
2. After UA validates and the Daily Pages holistic GA is trained and reviewed, enable the Daily Pages path of the flag — same UA cohort first.
3. Expand to Washington and Birmingham City after Brian signoff on the Daily Pages GA output quality.
4. Default ON for all schools after pilot validation.

The Daily Pages holistic GA is a hard prerequisite for step 2 and beyond. If it slips, steps 1 and 3-as-thesis-only can still ship.

## North star context

This grading split is a foundation move. Routing Daily Pages GA toward idea engagement (and away from mechanics) turns every Daily Pages submission into structured signal about what a student is thinking about — the raw material for the student-level insights work that's coming. Building this cleanly now avoids a destructive rework when insights layer on top.

Related: [features/assignment-level-feedback.md](assignment-level-feedback.md) covers the class-level summary of graded work. This spec is about the input side — making sure the right kind of grade and feedback is being produced in the first place.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed
- [x] Data model implications spelled out, including backward-compat plan
- [x] UX sketch in prose
- [x] Edge cases enumerated
- [x] Test plan written
- [x] Rollout plan decided
- [ ] Brian signoff on rounding precision
- [ ] Owner assigned for Daily Pages holistic GA training
- [ ] Confirm gradebook integration handles non-100 point scales