Canvas Scan

Canvas Scan

Scan is proposal only. It reads current Canvas state, creates a reviewable plan, and stops. The next user message is the architectural approval boundary.

Hard boundary

• MUST NOT execute or draft an assignment.
• MUST NOT dispatch a course skill or canvas-execute.
• MUST NOT write a per-assignment result.json or REPORT.md.
• MUST NOT create .scan_in_progress.
• MUST NOT upload, submit, or start/answer/complete a quiz.
• MUST NOT interpret authentication as work approval.
• MUST stop after rendering the plan. Never “helpfully” begin an urgent item.

Phase 0: Setup and route gate

Read local setup state before touching Canvas.

1. If .env is missing or the Canvas host/auth configuration is incomplete, hand off to canvas-setup and stop this scan when setup returns.

2. Read courses.yaml. Treat missing routes, routes: null, an empty mapping, and effectively all-commented routes as empty.

3. If routes are empty, hand off to canvas-skill-opportunity with this intent:

   Inspect recurring candidates read-only, inspect representative real specs and safe feedback-policy evidence, make a qualitative recommendation, write the private opportunity report, and stop for the student's numbered choice.

   Stop when opportunity analysis returns. Do not scan assignments and do not call canvas-bootstrap in the same turn. The student first chooses a candidate; a later Bootstrap invocation verifies it and creates one route.

4. Only non-empty usable routes proceed to the scan.

Phase 1: One enriched Canvas process

Run exactly one interactive scan command:

python -m src.router --scan-json

This single process owns connection/auth recovery, routed-course assignment listing, pending-window filtering, live submission reads (get_submission), due-time calculation, urgency buckets, unsupported-submission classification, and quiz LockDown metadata checks. It reuses one Canvas/browser session. The router delegates normalization/output safety to the shared src.scan_service and route resolver; this skill consumes those outputs rather than reimplementing their rules.

Do not restore the old interactive sequence of python -m src.canvas_client --probe, python -m src.router --dry-run, and separate per-item live-state calls. Those commands may remain for setup, cron, or debugging, but they are not the student-facing scan path.

Read runs/<today>/scan.json; do not reconstruct the payload from terminal prose. Expected top-level fields are:

{
  "generated_at": "<ISO local time>",
  "now_utc": "<ISO UTC time>",
  "items": [],
  "course_errors": []
}

Each item must already include the identifiers and display fields needed by the state protocol plus:

• canonical skill from src.routes.resolve_skill(route, assignment);
• live_state;
• hours_left;
• bucket;
• supported/unsupported classification;
• LockDown result or an explicit check failure.

Scan consumes the canonical canvas-* name emitted by the shared route resolver. Never embed or guess a legacy alias table in this skill.

Phase 2: Fail loudly on an incomplete scan

Handle command-level errors before writing any approval artifact:

Do not write or replace assignments.json or plan.json after a non-zero scan.

Treat a non-empty course_errors array as an incomplete scan even if the process exited zero. Name the affected course aliases, explain that the plan would be partial, and stop without replacing the prior approval plan. Do not hide a failed course in a “successful” plan. A later explicit product feature may authorize partial planning; ordinary scan does not.

Per-item live-state or LockDown lookup failures are different: the item remains visible with live_state: "unknown" or an explicit check-failed field, and the plan renders ?. A failed safety classification must never be treated as proof that an item is safe to mutate.

Phase 3: Normalize and fail closed

Validate scan.json before deduplication:

• top level is an object and items/course_errors are lists;
• every item has one stable course/assignment identity;
• no duplicate identity appears;
• live_state and bucket are in their documented enums;
• route skill is a canonical canvas-* name;
• dates and numeric fields are either valid or explicitly unknown.

Unsupported delivery types (for example on-paper work or an unsupported external tool) must be canonicalized to canvas-skip with a reason, never routed as ordinary draft work. LockDown-confirmed quizzes also route to canvas-skip. When LockDown status could not be checked, retain the item with a loud caveat; the quiz skill must re-check and fail closed before any attempt.

Phase 4: Deduplicate completed work

Use both layers:

1. Same-day result — derive the work directory using the shared run-state identity helper. Its stable shape is course-<course_id>__assignment-<assignment_id>; never recompute a directory from mutable course or assignment names. A valid result with terminal status draft_ready, submitted, or skipped means the item was handled today.
2. Cross-day ledger — read runs/_processed.json. Skip a matching terminal entry completed close enough to its due time to represent this assignment.

Exception: any ledger/result entry with deferred_to_next_run: true re-enters the plan. This is how skip, cancel, an explicit defer, and crash recovery get another approval opportunity.

Live Canvas state is defense in depth. Exclude confirmed submitted, graded, or pending_review items from new work even if local state drifted. Preserve unknown rather than inventing a submitted state.