What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.
- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
place of the site's Session), scripts (corpus pipeline, play, the
exercise and probe starters, engines export/diff), and its docs
(engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
index.html, "imports" in package.json for node, core's declarations for
tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
quarto-export and quarto-css read core/dist and core/mojo; quarto-css
copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
describe the split (checkout with submodules; core's tests and corpus
status run against the pinned commit).
Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
7.6 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
The engine core (the languages, translators, Mojo checker and interpreter, prover, fuzzer, machine model and the Mojo corpus) is pplus-core, the git submodule core/, with its own rules in core/AGENTS.md. This file is for the site.
pixi run test # build core, then the site, then every test of the site
pixi run core-test # core's own tests, at the pinned commit
Without pixi (a sandbox with only Node and Python):
npm install && npm test
(cd core && node --test tests/*.test.mjs && python3 scripts/mojo/corpus.py status --strict)
Finish every change with the gate green, both commands. 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 site's suite takes under a minute. While iterating, build and run one file: npm run build && node --test tests/state.test.mjs.
Hard rules
- A change to what programs mean belongs in core. A translator, the checker, the interpreter, the prover, the fuzzer, the machine model, the catalog's problems, the Mojo corpus: change them in pplus-core under its rules (its own commit, its own gate), then move the
corepointer here in a commit that says what it brings. Never editcore/from a site change without that. The site imports core only as#core/<path>.js(the import map inindex.html,importsinpackage.json), from its builtcore/dist/. - Do not edit generated files by hand.
quarto/_extensions/pplus/pplus-views.csscomes fromstyles.css,pplus-hw.cssandcourse/*.cssbeside it fromstyles/course/, andsyntax/mojo.xmlfrom core'score/syntax/mojo.xml(pixi run quarto-css; a test fails while they are out of date, so run it after changing a rule the views use). Core's generated files are listed in its AGENTS.md. - Never claim Mojo compiles, runs, or prints something without the real compiler's answer. Mojo is pinned to 1.1.0 by core. What the app shows about Mojo comes from core's checker and interpreter and from godbolt's answers (stored in
core/mojo/golden/, or asked live by Compile & run); the site never invents a verdict, and every Mojo construct written into the app must passcheckMojo. - Never show "proved" for something that is not a proof. The badges and verdicts are in core/docs/trust.md; the site shows what core decided and does not soften or upgrade it.
- No new dependencies. TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency. CodeMirror is vendored as one built module (
src/vendor/), rebuilt only byscripts/vendor/codemirror.sh. - You have no network in most sandboxes. Godbolt (Compile & run) needs one, and so do core's network tasks. Never fake their results; leave those steps to the owner and list them.
- 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, deployment in docs/deploy.md, and the Quarto extension in quarto/README.md. Exercises, the Mojo corpus, the engines and the prover's soundness are core's documents (
core/docs/). Update the document a change belongs in, in the same commit. - Tests run against
dist/with no DOM. Logic about programs belongs in core; the site's own DOM-free logic (src/core/,src/quarto/) is tested here. A test that needs a piece of work uses aSession(src/core/session.ts), which extends core'sWorkspace. 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, a probe, a stress program, a corpus or prover regression, a language | in core (core/AGENTS.md), then move the core pointer here; a problem's area comes from defaultAreaFor in src/core/catalog.ts |
| A command | a task in pixi.toml and a row in the README's Commands table |
| 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, the core commit the site is pinned to if it moved, anything you could not verify (network steps, manual UI checks), and anything you noticed but left alone.