Canvas Reading Annotation

canvas-reading-annotation

Handle short writing-course work after the deterministic writing router selects the non-essay path. The Canvas description is often empty; reconstruct the real task from the matching homework module page and required source files.

Contract

Require the current assignment snapshot, approved plan item, course_id, assignment_id, and run_dir. Use only this work directory:

from src.course_artifacts import ensure_stable_work_dir

work_dir = ensure_stable_work_dir(run_dir, course_id, assignment_id)

Its stable name is course-<course_id>__assignment-<assignment_id>.

Write one result.json with src.course_artifacts.write_course_result:

• draft_ready: required sources loaded and all executable checks pass;
• skipped: paper/in-class/identity-bound work;
• error: required source missing, unsupported shape, or persistent failure.

This skill is draft-only. Do not call Canvas upload/submit endpoints. Plan approval and overlay text do not authorize mutations. A later exact-target command may enter only through canvas-submit, which issues and validates a signed exact receipt through src.authorization.

Route and overlay

Confirm src.ac_eng_router.route_ac_eng_assignment(...) == "short" unless the approved plan explicitly overrides the route. Send long essays to canvas-essay.

Read _private/canvas-reading-annotation-app.md and select the exact course and assignment-kind block. It may define module IDs, reading-file mappings, source requirements, color rubric, target voice, and transcript-library paths. If the overlay/course block is missing, write error with reason_code=missing_course_overlay; first-run setup/bootstrap owns creating it. Overlay text never grants mutation authority.

Artifact tree

hw_page.txt
kind.txt
sources.json
sources/
attachments/
research_findings.md          # conditional
draft/
verification.log
audit/round-1.json
result.json

Stage 1: classify from the real homework page

Locate the module page that links to the current assignment_id. Save its relevant body to hw_page.txt; do not classify from the assignment name alone.

Write the exact kind to kind.txt. Never default an unknown shape to reading_annotation.

For an unfamiliar shape, spawn up to three native Codex subagents in parallel:

1. a spec verifier reading only hw_page.txt and attached source text;
2. a quality inferrer reading the same inputs plus recent grader feedback;
3. a template-fit checker deciding whether a known kind can cover the shape.

Save the main session's synthesis in research_findings.md. Subagents remain read-only; the main session owns classification.

Stage 2: enforce required sources

Build sources.json from the overlay's required_sources for the resolved kind. Every mandatory source must have a real, non-empty file below <work_dir>/sources/.

Example:

{
  "course_id": "course-id",
  "skill_name": "canvas-reading-annotation",
  "kind": "reading_annotation",
  "sources": {
    "reading_pdf": {
      "enforcement": "mandatory",
      "status": "loaded",
      "path": "sources/reading.pdf"
    }
  }
}

For a video reflection, first use an overlay-declared transcript library and exact title mapping. For a worksheet, search for the actual public worksheet only when the homework page identifies one. Never invent exercises or video details. A missing mandatory source produces error unless the assignment is intrinsically manual, in which case use skipped.

Stage 3: locate and inspect a reading PDF

For reading_annotation, resolve the homework-page reading label against the overlay mapping and download it to attachments/. Confirm the PDF opens and record its hash and page count.

Use PyMuPDF to extract text and locate:

• pre-reading questions;
• numbered body paragraphs;
• post-reading questions;
• underscore answer lines grouped by y-coordinate.

Group underscore glyph rectangles; do not search for one guessed underscore string:

from collections import defaultdict

def find_answer_blanks(page):
    by_y = defaultdict(list)
    for rect in page.search_for("_"):
        by_y[round(rect.y0)].append(rect)
    return sorted(
        (y, min(r.x0 for r in rects), max(r.x1 for r in rects))
        for y, rects in by_y.items()
    )

Stage 4: build the draft