Canvas Execute

Canvas Execute

Execute is the action half of the scan/execute boundary. It reads an existing student-reviewed plan; it never scans, invents, expands, or silently repairs a missing plan.

Plan approval authorizes local assignment work for the selected items only. It does not authorize a Canvas upload/submission or a quiz start/answer/complete action. Those mutations require a separate scoped authorization receipt validated and consumed by the shared runtime.

Hard rules

• Do not run canvas-scan inline or regenerate plan.json from Canvas.
• Do not execute unapproved items.
• Do not execute an item whose final user_decision is not approve or a valid swap:canvas-*.
• Do not expand a vague approval. Ambiguity stops before any plan write, marker, dispatch, or mutation.
• Do not do course work inside this dispatcher. Use sequential native Codex skill handoffs.
• Do not invent a route alias, draft path, verification result, result status, submission, score, or quiz diagnostic.
• A TODO, sentinel, skeleton, empty template, outline-only file, or placeholder is never draft_ready.
• Every assignment snapshot item must have one valid canonical result.json before finalization.
• Keep .claude/ read-only. Do not use the frozen Claude Skill tool or Claude session variables as active runtime mechanisms.
• Do not submit to Canvas from plan approval.

Phase 0: Preconditions and integrity

Before parsing approval, require:

1. runs/<today>/plan.json exists and parses as an object.
2. runs/<today>/assignments.json exists and parses as a list.
3. generated_at and expires_at are valid timezone-aware timestamps and the plan has not expired.
4. Plan indices are unique, contiguous, and 1-based.
5. Every plan item maps one-to-one to exactly one snapshot item by course and assignment identity; there are no extra or duplicate identities.
6. Each proposed_skill is the canonical canvas-* value produced by the shared route resolver.
7. The current conversation contains an explicit approval expression for this plan. Old approval from a prior plan or turn is not reusable.

If anything is missing, stale, malformed, or inconsistent, stop and tell the student to run canvas-scan again. Do not “fix” the plan by fetching Canvas and do not dispatch anything.

Call src.run_state.validate_plan_assignments(plan, assignments, run_dir=run_dir, require_current=True) for these checks. Do not maintain a second timestamp, identity, skill-name, or status validator in this skill.

After applying the complete decision set, compute src.run_state.plan_digest(updated_plan). Store that digest in the marker so a resumed run cannot silently switch identities, skills, timestamps, or approval decisions.

Phase 1: Deterministic approval grammar

Normalize Unicode whitespace, Chinese punctuation, and case, but do not remove unknown words and do not mine arbitrary numbers from prose. Match the whole approval expression against one of these forms:

Call src.approval.parse_approval(user_text, plan) for the actual parse and src.approval.apply_approval_to_plan for the complete decision set. The table below is the user-facing contract and regression oracle; it is not permission to rebuild an ad-hoc natural-language parser inside the agent.

Lists and ranges may be combined only with unambiguous separators, for example 1,3-5. Expand them deterministically, reject reversed ranges, and reject any index not present in the current plan. Deduplicate repeated indices.

An optional compound expression may contain one approve selector followed by targeted defer N or swap N to canvas-x clauses separated by semicolons. A targeted defer may narrow an explicit broad selector, so approve all; defer 2 means approve all except item 2. Reject a direct contradiction such as approve 1; defer 1 rather than guessing which instruction was later intent.

The following are ambiguous and must trigger one concise clarification without writing anything:

• do the important ones / 做重要的;
• do the first few;
• bare defer (no target);
• swap 1/2 (no target skill and unclear indices);
• cancel 2 (use defer 2 for a targeted decision);
• approve 1; defer 1, or another direct conflict not covered by the documented broad-selector/targeted-defer precedence;
• a skill swap that is not a discoverable canonical canvas-* skill after shared resolver validation.

Silence never means approval. A list such as bare 1,3 approves only 1 and 3; all other indices become defer.

After a successful parse, set every item to exactly one of:

• approve
• defer
• swap:canvas-<canonical-name>

Write the complete decision set to a temporary plan, validate it, then commit with os.replace. No decision may remain null once execute begins. Prefer src.run_state.write_plan/atomic helpers so the same validator used by the hooks protects the write.

Phase 2: Marker ownership and crash recovery

Use runs/<today>/.scan_in_progress as an execute-owned marker. The marker is a JSON object, not an empty touch file:

{
  "session_id": "<current Codex thread/session identifier>",
  "owner_kind": "codex",
  "created_at": "<ISO time>",
  "plan_digest": "<validated digest>"
}

Resolve the identifier with src.authorization.current_authorization_session(). In current Codex this is normally CODEX_THREAD_ID; the helper supports CODEX_SESSION_ID only as a runtime compatibility fallback. Do not read Claude variables, invent a UUID, or stamp a marker the Stop guard cannot associate with this session. If the shared helper returns no reliable identifier, fail closed before creating the marker or dispatching.

Before creating today's marker, inspect existing markers:

• past-date marker: validate that day's snapshot, write canonical skipped/deferred error-recovery results for unfinished items, update its ledger/report, then remove only that recovered marker;
• today, same session and same plan digest: resume by reconciling existing valid results and continuing the recorded decisions;
• today, different owner: do not steal or delete it; report that another execute session owns the run and stop;
• malformed marker or digest mismatch: do not dispatch; retain it for inspection and report the mismatch.

Create today's marker atomically only after approval was parsed, plan decisions were committed, and the final plan digest was computed. Use src.run_state.validate_execute_marker on resume and before finalization. While the marker exists, the Stop guard requires a canonical result for every snapshot item and recomputes the digest against plan.json.

Immediately after creating or resuming the owned marker, and before reading, reconciling, or dispatching any assignment result, run the shared preparation gate:

python -m src.run_state prepare-results --run-dir runs/<today>

prepare-results validates the marker owner and final plan, recoverably moves each approved item's pre-existing result.json into its deterministic result-history/ path, and stamps results_prepared_at, results_archive_count, and the exact prepared_approved_result_keys list into the marker. It is idempotent after that stamp: a resume must call it again, but it must never manually move or reuse a result around this gate. If the command fails, do not dispatch or reconcile anything; retain the marker and report the exact error. The shared run validator and Stop guard require that prepared key list to match the current plan exactly. Because each approved slot was empty when the marker was stamped, any approved result.json accepted afterward must have been written by the current execute; an error or draft from a previous run is never current-run evidence. Deferred results are not archived by this gate.

Phase 3: Resolve the dispatch skill

For each approved item in plan order:

1. approve uses the canonical proposed_skill already written by scan.
2. swap:canvas-x is validated through src.routes.resolve_skill(route, assignment) and must resolve to a discoverable canonical Codex skill.
3. Use the shared resolver's result exactly. Do not maintain an inline mapping for legacy names such as old quiz/code/writing aliases.
4. When a shared deterministic sub-router is documented for a task family, call that shared runtime helper and consume its canonical canvas-* result; do not recreate its heuristics in prose.

If the target skill is missing or still contains UNFILLED_SKELETON, write a canonical error result for the item, defer all not-yet-run items, and proceed to safe closeout. Never perform the homework inline as a fallback.

Phase 4: Separate local-work approval from mutation authority

Before every handoff, construct execution context with local drafting enabled and Canvas mutation disabled by default.

The approval recorded in plan.json is never an authorization receipt. The following actions require a separate receipt validated and consumed by the shared runtime immediately before the exact action:

• upload an assignment file;
• submit an assignment or submission comment that changes Canvas state;
• start a quiz attempt;
• answer/save a quiz question;
• complete/submit a quiz attempt;
• take a retake or any additional attempt.

The receipt must be scoped to the exact local user, course, assignment, action set, and validity window, and must be single-use or consumption-tracked. A standing environment flag, route value, plan approval, skill prose, or prior conversation statement is not a substitute. Execute must pass only a receipt that the shared runtime has already validated for this item and action. Use src.authorization.require_mutation_authorization at the mutation boundary; do not validate signatures or scope in skill prose.

Without a valid receipt:

• ordinary course skills produce verified local drafts only;
• upload/submission branches remain disabled;
• a quiz skill that cannot even read questions without starting an attempt fails closed with skipped or error and a clear authorization next step;
• no start/answer/complete call is made.

Even when a receipt exists, the course skill must pass its verification gate before the shared runtime consumes it. Never infer mutation authority from the words all, 1,3, urgent only, or a swap.