TutorOS

• 

  Tutor sign-off — human review is the final boundary, and any later edit revokes approval.

• 

  Overview — the synthetic Maya workflow connects session evidence to the next decision and an honest parent update.

• 

  Architecture — evidence flows through deterministic decisions, optional drafting, the Honesty Gate, and tutor sign-off.

• 

  Evidence Integrity Benchmark — named synthetic fixtures exercise production mastery, reporting, and provenance logic.

• 

  Next-session brief — review target, support progression, mastery check, and exact source evidence.

• 

  Session evidence — editable outcomes, support levels, observations, and the lesson mastery check.

• 

  Learner trajectory — three sessions reveal the latest independent transfer gap instead of smoothing it away.

• 

  Parent update — editable wording cites the breakthrough and difficulty, then passes through the Honesty Gate.

Inspiration

Independent tutors leave every session with useful observations, then manually convert them into the next lesson, a review schedule, and a parent update. TutorOS is built from that real after-session workflow.

What TutorOS does

TutorOS turns observable tutoring evidence into one connected decision packet:

an editable 45-minute lesson plan; a transparent mastery score with decline and independent-miss overrides; a 3-, 7-, or 14-day review decision; a next-session brief carrying exact source observations; a three-session learner trajectory; an evidence-cited parent update; a deterministic Honesty Gate; and revocable tutor sign-off before copying.

The bundled Maya scenario is fictional. Judges can test the complete flow without an account, API key, installation, or rebuild at https://tutoros-sand.vercel.app.

Measured result

The checked-in Evidence Integrity Benchmark runs 12 named fixtures against the production mastery, report-integrity, and provenance functions. All 12 pass: 4/4 mastery scheduling, 4/4 report integrity, and 4/4 closed-loop provenance.

The repository also has 74/74 passing automated tests across 14 test files. The public health endpoint reports TutorOS 1.1.0 ready and exposes the measured 12/12 benchmark state.

These are software regression results using synthetic data. They do not claim educational efficacy or validated learning outcomes.

How Codex was used

The primary Codex task used gpt-5.6-sol from planning through implementation, testing, documentation, release, and submission preparation. Its organizer-verifiable /feedback Session ID is:

019f74c8-b8f0-7be3-bb77-d619e28f77cb

Codex implemented nine issue-to-PR slices covering the runnable foundation, GPT-5.6 structured lesson planning, session evidence and mastery, the parent-report Honesty Gate, judge walkthrough, closed-loop next-session provenance, benchmark, trajectory and tutor sign-off, and deployment hardening. It also implemented the 1.0 release, professional documentation, and 1.1 credential-free fallback.

Important decisions made with Codex

Keep mastery and review scheduling deterministic and inspectable. Treat attempt IDs and observations as structured provenance, not optional prose. Run a deterministic Honesty Gate after report drafting. Revoke tutor sign-off whenever evidence or wording changes. Keep API credentials server-only and make live generation optional. Give judges a complete credential-free path. Label every local fixture as a mock and never present it as GPT-5.6 output.

Precise GPT-5.6 contribution

GPT-5.6 Sol in Codex helped design and implement the deterministic evidence core, model-facing Zod schemas, OpenAI Responses API adapters, Honesty Gate, next-session provenance, Evidence Integrity Benchmark, three-session trajectory, tutor sign-off, release verification, and judge workflow.

TutorOS also contains optional server-only adapters that request gpt-5.6 for structured lesson plans and parent reports when OPENAI_API_KEY is configured. The public deployment has no API key. Its purple fallback responses are deterministic local fixtures with the same validated application shape. They are not ChatGPT responses and are not OpenAI API output.

Full evidence and artifact mapping: https://github.com/manojmallick/tutoros/blob/main/GPT56_EVIDENCE.md

Architecture

TutorOS separates optional generation from the decisions that need to stay inspectable. Validated lesson context and session evidence enter a deterministic core for mastery, review scheduling, trajectory, and next-session provenance. GPT-5.6 can create structured editable drafts when a server key is present; otherwise the public demo uses a clearly labeled local mock. The Honesty Gate and revocable tutor sign-off remain deterministic before any parent update is approved.

How it looks

Every view below uses the fictional Maya scenario. No real learner data is included.

1. Judge-ready overview

The value proposition and final evidence-grounded artifact are visible before interaction.

2. Evidence Integrity Benchmark

Named synthetic fixtures exercise the same production mastery, reporting, and provenance functions used by the demo.

3. Session evidence and mastery inputs

Tutors record outcomes, support levels, and concrete observations in an editable log.

4. Three-session learner trajectory

The latest evidence governs the decision, even when it interrupts an appealing upward trend.

5. Closed-loop next-session brief

Review target, support progression, and mastery check retain their source observations.

6. Evidence-grounded parent update

The editable report names the breakthrough and difficulty, then passes through the Honesty Gate.

7. Revocable tutor sign-off

Human review is the final boundary. Changing evidence or wording revokes approval.

Challenges

The hardest product problem was not generating fluent text. It was preventing apparently reasonable output from drifting away from observed evidence. TutorOS therefore had to handle an 83% average that still contains a recent independent miss, preserve exact attempt provenance across the next lesson and parent report, invalidate stale outputs after edits, and keep the public demo useful without an API credential.

Accomplishments

One closed loop connects lesson planning, evidence, mastery, retrieval, parent reporting, and human approval. The Honesty Gate blocks invented citations, generic praise, softened mastery language, and omitted difficulties. Any edit revokes stale sign-off. The complete judge path runs with fictional data and no external model call. CI, deployment checks, security headers, privacy guidance, 74 tests, and the 12-case benchmark are public and reproducible.

What I learned

Model output is most useful here as an editable draft inside deterministic boundaries. Evidence provenance needs to travel as data. Human sign-off only has meaning when it is tied to the current evidence version. A credential-free demo is stronger when it visibly explains what is simulated instead of hiding the runtime boundary.

How judges can test it

No credentials or installation are required:

Open https://tutoros-sand.vercel.app. Select Start 90-second demo. Open the 12/12 benchmark. Change Attempt 4 from Incorrect to Correct and update mastery. Confirm mastery, review date, trajectory, and next-session brief change together. Generate a plan or report and confirm the purple mock notice states that no API call occurred. Review and sign off the current packet; copying becomes available.

For a local verification:

pnpm install pnpm test pnpm benchmark pnpm build

Built with

Next.js 16, React 19, TypeScript, Zod, Vitest, OpenAI Responses API, GPT-5.6, Codex, GitHub Actions, and Vercel.

What's next

The next step is evaluation with working tutors before changing mastery boundaries. Consent, retention, deletion, access control, and safeguarding must be designed before adding persistence or real learner records.

Repository

Public source, tests, benchmark fixtures, methodology, evidence, MIT license, and setup instructions:

https://github.com/manojmallick/tutoros

Built With

• codex
• github-actions
• gpt-5.6
• next.js
• openai-responses-api
• react
• typescript
• vercel
• vitest
• zod