Public Exercise And Assessment Specification

This specification defines the public learner surface exported to soheylm-passport-sandbox/passport-exercises and the private authority exported to soheylm-passport-sandbox/onboarding-control.

Public Exercise Repository#

README.md
passport.example.json
passport-curriculum.json
missions/
submissions/
workspace/
.github/
  ISSUE_TEMPLATE/
  pull_request_template.md

The central repository contains only fictional fixtures, mission contracts, and non-secret metadata. It has no privileged workflow. After explicit consent, gh passport start creates a personal public fork and a background transport branch. Students do not need to understand that Git mechanism before the Git mission.

The managed .transport clone is separate from the visible practice folder. A browser submission stages only its generated submissions/<mission>.json and the mission's declared synthetic workspace/ files. It never runs git add . or stages unrelated learner content.

Private Authority#

The private control repository stores:

• active enrollment with immutable learner and reviewer GitHub IDs;
• fork, parent, base-repository, branch, and pull-request IDs;
• canonical platform, responsibilities, route, baseline, and protected hashes;
• per-mission attempt counts and exact-SHA controller state;
• minimal completion and lifecycle records.

It never stores credentials, research data, broad logs, AI transcripts, local paths, Euler job IDs, or student-authored free-form assessment answers.

Learning Contract#

Every mission follows Understand -> Example -> Do -> Check -> Submit -> Fix or continue. Knowledge is captured as structured choices or ordered actions. Practical competence is checked against a bounded local or remote operation. Markdown is an assessed artifact only when writing a real document is itself the competency, such as project handover.

The controller requires at least 80% and every safety-critical answer. It then checks the declared practical receipt and synthetic artifact independently. Routine missions pass automatically. operational_approval means that training can pass while a real access or ownership decision remains separate.

Deterministic Checks#

Trust And Isolation#

Registration accepts only one central draft transport PR whose author, public fork, direct parent, source/base, branch, route, and passport.json match an active private enrollment. Assessment resolves the exact head SHA before the isolated job and revalidates it before publishing.

Student-controlled repositories receive no organization secret. Do not use pull_request_target to execute learner content. The assessment checkout has no persisted credential; untrusted code runs read-only, without network, under CPU, memory, process, and time limits.

The public controller App is installed only on passport-exercises. The separate dispatch App has Actions write access only on private onboarding-control. A signed Cloudflare Worker validates the public webhook and forwards only repository, PR number, head SHA, and delivery ID.

Completion#

The trusted Check Run on the exact SHA is the learner-facing authority. When all training missions pass, the controller writes the minimal private completion record and closes the transport PR without merging it. The launcher can still reconstruct a completed passport from that closed, unmerged PR and its trusted Check Run.

A PR merge, local checkbox, browser history, or learner-edited JSON never grants completion or operational access.