git:20261023.f4f0780 to git:20261024.de61842

2 added, 2 removed. Audit A to A.

# CLAUDE.md

Guidance for developing the Canvas MCP server. Agents *using* the server: see [AGENTS.md](./AGENTS.md).

Design: [internal/architecture.md](internal/architecture.md). Long-form rules and the reasons behind them: [internal/dev-reference.md](internal/dev-reference.md). Completed work: [internal/project-history.md](internal/project-history.md), `CHANGELOG.md`.

Codex reads `AGENTS.md`, not this file; its "Developing this server" section points here, so keep development rules in this file only. Paths, flags, symbols and issue states below were checked on 2026-09-30.

## Commands

- Install `uv pip install -e .`; run `canvas-mcp-server` (`--test`, `--config`); `.env` holds `CANVAS_API_TOKEN` and `CANVAS_API_URL`.

- Before committing: `uv run python -m pytest tests/ -v -rf`. TypeScript changes: `npm test` and `npm run build`.

## Git Workflow - ASK FIRST

- Before a feature or significant change, ask: feature branch or `main`? Defaults: new tool `feature/`, bug `fix/`, docs or typo may go straight to `main`. Prefixes: `feature/`, `fix/`, `docs/`, `refactor/`.

- The primary checkout stays on `main`, clean and read-only. One PR = one sibling worktree `canvas-mcp-<slug>` from `origin/main`; never reuse it for another issue; remove it and the branch (local and remote) after merge.

- After a sibling PR merges, rebase surviving worktree branches and rerun tests. Before tagging, run the suite in the primary checkout on the merged commit (its `.env` sets a token that worktrees and CI lack).

- `main` requires a PR plus `test-enhancements` and `lint`; the admin can bypass the review requirement.

- Run `./scripts/install-hooks.sh` once per clone. `fixes|closes|resolves #N` mid-sentence in a commit or PR body closes the issue on merge: rephrase (`closed [issue 172]`) or set `ALLOW_CLOSING_KEYWORD=1`. A trailer that opens a line (`Closes #173`) is allowed.

- Release steps and publish-race fixes: [internal/release-checklist.md](internal/release-checklist.md). Breaking changes need a minor bump.

## Coding Standards

- Type hints on every function; PEP 604 unions (`X | Y`), enforced by ruff UP.

- Tools use `@mcp.tool()` with `@validate_params`, and every tool carries annotations (`tests/test_tool_metadata.py` fails a bare decorator).

- All Canvas calls are async and go through `make_canvas_request()`; paginate every list endpoint.

- Course identifiers are `str | int` resolved with `get_course_id()`; dates go out through `format_date()`.

Code that needs a numeric course ID (paths, context codes, comparisons) uses `resolve_numeric_course_id()`, which returns `(id, error)` and never yields an unvalidated string. `get_course_id()` matches the same way but keeps its pass-through fallback on a miss.

- Canvas POST/PUT needs `use_form_data=True`, `/conversations` included.

- Errors: dict tools return an `"error"` key; string tools return `"Error ..."`. `modules.py` and `accessibility.py` return JSON-stringified errors; keep the local convention.

- Privacy: student IDs preserved, names anonymized at the client layer (`_should_anonymize_endpoint()`); a new endpoint must be checked against the tier rules.

- Show course codes, not IDs, in user-facing output; handle published and unpublished states.

## Testing and behavioral evidence

- New tools need meaningful automated coverage: success, failure, boundary and safety behavior.

- A reproducible bug gets a failing regression first; watch it fail for the intended reason.

- Assert outgoing request contracts and forbidden side effects, from an independent requirement, not from the implementation's own output.

- Use a real client with controlled HTTP transport when the risk is serialization, retries, pagination or error classification.

- Never send live Canvas writes to verify a patch. Never weaken an assertion to get a green run.

- Lean/TLA+ (`verify/`) only for consequential state, ownership or termination invariants; pair with implementation regressions.

- Report what was verified, what failed and what was skipped.

## Documentation Maintenance

- Source of truth: agents `AGENTS.md`; humans `tools/README.md`; machine `tools/TOOL_MANIFEST.json`; `README.md` is the entry point.

- New tool: update `tools/README.md`, then `AGENTS.md`, then `TOOL_MANIFEST.json`. Touch `README.md` only for a major feature. No tool usage docs in this file.

- `docs/` is the public Cloudflare Pages root and deploys manually (`wrangler pages deploy docs/`); nothing internal goes there.

- `internal/` is deny-by-default in `.gitignore`; un-ignore only a file meant to be public. `internal/session-history.md` stays untracked.

- Triage briefs are tracked: never record a collaborator's affiliation, evaluation status, timeline or competing products. Name the person and the technical issue only.

## Hosted Deployment

- A private, Entra-gated Azure instance serves Gies course staff. Its URL, app IDs, deploy details and key holders stay out of this repo; they live in the gitignored `internal/ops-hosted.local.md`.

- HTTP mode: each caller sends `X-Canvas-Token`; `CANVAS_API_TOKEN` must never be set (startup guard); read-only unless `ALLOWED_WRITE_TOOLS` is set.

- Merging to `main` does not deploy production. It deploys on a `v*` tag or `gh workflow run deploy-prod.yml --ref main`; `staging` deploys on push.

## Adoption numbers

- Never print a PyPI download count. Quote stars, forks and contributors, re-pulled from the GitHub API that day, with the date.

- Do not repeat "over 18,000 clones" or "UMich selected it as sole candidate" without a primary source.

- Do not imply a campus security review: the only Illinois artifact is Adam King's LRA, and the public hosted server is retired.

## Current Focus

- [ ] **#157** sandbox egress is mitigated, not closed (self-hosted only; `execute_typescript` is disabled on hosted). Needs an egress proxy or network namespace.

- [ ] **#236** OAuth2 developer-key flow: additive only, blocked on admin access to pilot a scoped key.

- [ ] **#172** Canvas Quizzes tools: blocked on a New-Quizzes-enabled sandbox (PR #191 was closed as unverifiable).

- [x] **#418 to #421** shipped (#438, #437, #436, #435; #421 part 2 via #442 and the anonymous-update refusal via #446; issue closed by 2026-10-07).

- [x] **v1.15.0** released 2026-10-23 (PR #524, tag on `1c06f5c`; GitHub Release + `.mcpb`, PyPI, Registry, prod `azure-gies-1c06f5c` confirmed in the Kudu docker log, site all verified): #515 overhaul, HTTP caller isolation, `get_student_submission`. #523 and #526 merged after the tag (Unreleased).

- - [ ] **OSS Verify** enrollment theorem-labs/oss-verify#8 (`fuzz_html` on `core/html.py`): all Theorem checks pass; awaiting their human review. Findings go privately to vishal@illinois.edu.

+ - [ ] **OSS Verify** enrollment theorem-labs/oss-verify#8 (`fuzz_html` on `core/html.py`): all checks pass, but Theorem needs one change before merge (asked 10-23, repeated 10-24; same as the Codex P1 at `fuzz_html.py:109`): P3 compares only the length of `remove_html_tags` output. Compare the text outside the `iter_html_tags` spans, add a mutant and input that a length check misses, rerun `tools/check --twice` on m2max, push to the fork. Theorem will publish theorem statements first; full proofs wait on their verified Python runtime. Findings go privately to vishal@illinois.edu.

- [ ] Hosted ops: remove `llkarri2` from the allowlist; usage telemetry is not retained (see Session Log).

- [ ] GHSA-hmr8: publish and request a CVE. GHSA-7pp5: decide (in triage since 07-04).

- [ ] Watch, no owner: Agent Plugins packaging (blocked on credential delivery; triggers in project-history).

## Roadmap

- [ ] Grok/xAI integration research and pilot.

## Backlog

- [ ] Module templates; bulk module creation from JSON/YAML; module duplication across courses.

- [ ] Page templates; bulk page creation from markdown; page versioning tools.

- [ ] 2026-09-06 security review follow-ups: check `docs/superpowers/plans/2026-09-06-security-review-followups.md` for items PR #360 did not cover.

## Session Log

> Full history: `internal/session-history.md`, local-only and untracked since 2026-08-20. Do not re-add it to git.

### 2026-10-22 22:12 → 10-23 15:00 CDT — v1.15.0 released; OSS Verify enrollment submitted (theorem-labs/oss-verify#8)

- **v1.15.0** tag `v1.15.0` → `1c06f5c` (PR #524, 13:42 CDT). Checked each artifact, not the runs: `.mcpb` manifest 1.15.0 + attestation; PyPI wheel + sdist with provenance (author_email now vishal@illinois.edu); Registry active; prod `azure-gies-1c06f5c` (was `4696c16`) per the Kudu docker log "Site is running with deployment version: 1c06f5c…"; site deployed from a clean `git archive` of the tag (live `impact.json` unchanged). Codex P2 on #524 (tool-name wording) fixed in `07f8575`.

- **Merged:** #521 (contact email: SECURITY.md, pyproject and `__email__` now vishal@illinois.edu; vsachde2 was wrong), #522 (control: black 26.10.1, opentelemetry-api 1.45.1; dependency scan green), #524 (release), #525 (anonymization status test pinned, no `.env` dependence). After the tag control merged #523 (`include_body`) and #526 (group creation), both Unreleased. #510 changes requested. Per control: #441 closed with a GitHub Support sensitive-data purge filed 10-23, and 46 merged branches deleted.

- **Pre-tag suite in this checkout** had 4 environment-only failures: `.env` sets `ENABLE_DATA_ANONYMIZATION=false` (fixed by #525), and `.githooks/commit-msg` is the fleet wrapper hidden by skip-worktree (`git ls-files -v` shows `S`), so 3 `test_hook_rejects_commit_without_usable_python` cases fail until control fixes the wrapper's `dirname` use.

- **OSS Verify:** `projects/canvas-mcp/` with one target, `fuzz_html` (4 properties, each with a distinguishing mutant; 20 seeds). `tools/check --no-shell --twice` passed on m2max (4 builds, byte-identical; plain `734a3e1f` matched a separate run too). At Vishal's direction PR #8 was opened from fork vishalsachdev/oss-verify (`b600bbd`, author vishal@illinois.edu); terms read, then accepted. All Theorem checks pass (triage: no warnings, criticality 0.59). Beginner explainer: claude.ai/artifact/SRJS3N6bxAjhE7qqAj1a1q (private). Docker Desktop on m2max quit; it had revived the Immich and Cap stacks, all stopped.

- - **Next:** Theorem's review of oss-verify#8; release #523 + #526 when ready; Vishal revokes F6 token (still most urgent); scan F1/F7/F9 patches; Codex 10-23 follow-ups still open: live sandbox validation of accessibility write-back and announcement deletion, restricted-grader and scoped-key checks, #510 re-review. Uncommitted `docs/data/impact.json` stats refresh (not mine) is not deployed; `.reviews/` untouched. Carry: remove `llkarri2`; GHSA-hmr8 + CVE; GHSA-7pp5; #489 closable?; memory questions (KB-token, `gotcha_cross_pr_semantic_merge_conflict`, and today's `gotcha_triage_brief_closes_issues` review, unanswered).

+ - **Next:** fix P3 in oss-verify#8 (Theorem's requested change, see Current Focus); release #523 + #526 when ready; Vishal revokes F6 token (still most urgent); scan F1/F7/F9 patches; Codex 10-23 follow-ups still open: live sandbox validation of accessibility write-back and announcement deletion, restricted-grader and scoped-key checks, #510 re-review. Uncommitted `docs/data/impact.json` stats refresh (not mine) is not deployed; `.reviews/` untouched. Carry: remove `llkarri2`; GHSA-hmr8 + CVE; GHSA-7pp5; #489 closable?; memory questions (KB-token, `gotcha_cross_pr_semantic_merge_conflict`, and today's `gotcha_triage_brief_closes_issues` review, unanswered).