Whether the engines' changes went back to the course or the course took them from here was an open question (docs/engines.md). Soundness fixes to the prover cannot wait for a round trip through a repository with no engine tests, so this repository now owns the engines. - pixi run engines-export <course>/static builds and writes every engine module into the course's static/js/: JavaScript modules as written, TypeScript ones (logic, solver, vcgen) as built, without source maps. - pixi run engines-diff now shows what the course has not taken yet, comparing the file the course would receive with its copy. Both scripts share the list of modules in scripts/engines-files.mjs. - docs/engines.md describes the ownership, the prover's three modules and its number model, the soundness tests and the bugs found so far, the changes the course receives with the next export, and how to export. - AGENTS.md gains a hard rule: never let the prover call something proved that a run breaks, with how to add a soundness regression first. - docs/app.md's Known limits no longer sends engine fixes upstream. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
8.5 KiB
8.5 KiB
AGENTS.md
Instructions for coding agents (and people) changing Programming+. Read this first, then the README for what the app is and where things are. When this file and a task's instructions disagree, the task wins; say so in your summary.
Build, test, and the gate
pixi run test # build, then every test (node --test against dist/, the corpus pipeline's Python tests included)
pixi run ci # the gate: every test, and no Mojo program of ours failing
Without pixi (a sandbox with only Node and Python):
tsc -p tsconfig.json && node --test tests/*.test.mjs
python3 scripts/mojo/corpus.py status --strict
Finish every change with the gate green. The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.
The full suite takes about two minutes. While iterating, build and run one file: tsc -p tsconfig.json && node --test tests/state.test.mjs.
Hard rules
- Do not edit generated files by hand.
src/mojo/generated/*andquarto/_extensions/pplus/syntax/mojo.xmlcome from the corpus pipeline (pixi run mojo-emit,mojo-status,play).quarto/_extensions/pplus/pplus-views.csscomes fromstyles.css, andpplus-hw.cssandcourse/*.cssbeside it fromstyles/course/(pixi run quarto-css; a test fails while they are out of date, so run it after changing a rule the views use).mojo/corpus/comes frommojo-harvest.mojo/golden/holds godbolt's answers and comes only frommojo-verify. - Do not edit a
.mojofile's text unless the task needs it. A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needspixi run mojo-verify-item '<corpus>/<name>'. - Never claim Mojo compiles, runs, or prints something without the real compiler's answer. Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline;
tests/mojo-check.test.mjsandtests/mojo-run.test.mjshold them to that. Every Mojo construct you write into the app must passcheckMojo, and every standard-library name must exist insrc/mojo/generated/stdlib.tsortypes.ts. - No new dependencies. TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency; the corpus pipeline is Python's standard library only. CodeMirror is vendored as one built module (
src/vendor/), rebuilt only byscripts/vendor/codemirror.sh. - You have no network in most sandboxes. Godbolt (
mojo-verify, Compile & run) and GitHub (mojo-harvest,mojo-fetch) need one. Never fake their results; leave those steps to the owner and list them. - Never let the prover call something proved that a run breaks. "Proved" in the app must be a proof. A change to
src/engines/pseudo/logic.ts,solver.tsorvcgen.tskeepstests/prover-soundness.test.mjsandtests/engine-solver.test.mjsgreen, and a fact the prover assumes must hold for every value a run can produce, or be guarded by an obligation. When you find a soundness bug, add the program that shows it totests/prover/with a// MUST-NOT-PROVE:(or// RUN-STOPS:) header first, see the test fail, then fix the rule (docs/engines.md). - Keep the workspace working while you change it. Code panes are always the CodeMirror editor (
Editorinsrc/ui/editor.ts, over the vendoredsrc/vendor/codemirror.js), never a<textarea>;tests/editor.test.mjschecks it. Keep the workspace's parts as they are unless the task changes them: the pane tabs over one editor, the stepper docked under the editor, the side column (the inspect panel, whose first tab is the Run view), and the dock; in the Hardware area, the code on the left and the arrangeable board on the right. Restyle or rearrange them only when asked, and after any UI change open the app (pixi run dev) and check that the editor has line numbers and highlighting, the stepper steps, and the styles loaded.
Conventions
- Commands are pixi tasks. Name them as
pixi run <task>in docs, comments, and messages. A new command is a task inpixi.tomlwith adescriptionand a row in the README's Commands table;tests/tasks.test.mjsfails otherwise, and also fails on anypixi run <name>that names no task.package.jsonkeeps onlybuild,watch,check,dev,test(what CI uses). - Docs. The README is the front door: keep it short. Put behavior in docs/app.md, exercises in docs/exercises.md, Mojo of our own and the pipeline in docs/mojo-corpus.md, the engines and the prover's soundness in docs/engines.md, deployment in docs/deploy.md, and the Quarto extension in quarto/README.md. Update the document a change belongs in, in the same commit.
- Tests run against
dist/with no DOM. Put logic in DOM-free modules (src/core/,src/services/,src/mojo/,src/quarto/) and test it there. The views insrc/ui/views/also run outside a browser, under the small document ofsrc/quarto/dom.ts, when the Quarto extension renders them: a view may use the selectors that document knows (compound selectors and the descendant combinator) and must not need layout to produce its markup. When a test needslocalStorage, install a fake onglobalThisand remove it infinally, astests/state.test.mjsdoes. For a UI change, write a short manual check list in the commit message. - TypeScript. Strict mode, ES modules, imports with the
.jssuffix (from './state.js'). Indent like the file you are editing (some files use two spaces, some four). - Stable ids. Diagnostic ids (
matho-refused,reserved-name, ...) and reference section ids are asserted by tests and linked from guides. Change one only on purpose, and update every test and link that names it. - Saved state.
PlayStateinsrc/core/state.tsis what share links,localStorage, and.pplus.jsonfiles hold, andnormalize()reads it. A new field goes intonormalize(); a field the student edits goes intoEDITS(it driveseditedFrom()andeditsFingerprint()). - Writing. User-facing copy is US English (color, behavior, optimized, labeled). Plain sentences; say what a thing does, not how good it is.
Adding things
| To add | Do |
|---|---|
| A catalog problem | pixi run new-exercise <id> for one built around a Mojo program, or copy src/exercises/_template.ts (docs/exercises.md) |
| A question about the compiler | pixi run new-probe <name> "<question>" |
| Realistic Mojo for the interpreter | pixi run new-stress <name> "<what it exercises>", with the output you predict in # expect-stdout: lines |
| A pseudo regression program | a file in tests/corpus/ whose // EXPECT: lines are the output it must print |
| A prover soundness regression | a file in tests/prover/ whose // MUST-NOT-PROVE: <kind>@<line> names an obligation a run breaks, or // RUN-STOPS: <kind>@<line> where a run must stop |
| A command | a task in pixi.toml and a row in the README's Commands table |
| A language | a LanguageService (src/core/types.ts) in src/services/, registered in src/services/index.ts |
| A Quarto shortcode | a function in the table quarto/_extensions/pplus/pplus.lua returns, a row in SHORTCODES (src/quarto/shortcodes.ts) and in scripts/check-pages.mjs, a sample in the gallery (src/ui/quarto.ts) and a use in quarto/example/; a rendered view is a case of renderStatic (src/quarto/render.ts); a view of the machine is a name in HW_NAMES (src/quarto/machine.ts), HW_VIEWS in pplus.lua and HW_VIEWS in scripts/check-pages.mjs |
Delivering work
- One logical change per commit, with a message that says what changed and why: the problem first, then what each part of the change does.
- When the owner asks for patches, export them with
git format-patch -o patches/ <base>(thepatches/folder is ignored by git) and do not paste whole files into chat. If the tree you were given has no.git, rungit initand commit it unchanged first, so the patches have a base. - End with a summary: what you changed, the gate's result, anything you could not verify (network steps, manual UI checks), and anything you noticed but left alone.