Document the task-authoring contract: editable enforcement, non-logged actions, and load defaults #4
Description
Context
CodeSignal/maestro-templates generates graded learner practices for CosmoPlot. The generator writes three artifacts per practice: a learner-facing description, a cosmoplot/config.json, and acceptance criteria graded from the logs/activity.log line stream.
We are moving those generators away from hand-transcribed copies of this repo's docs and toward reading this repo directly at generation time (see maestro-templates#90). That makes README.md the contract, so gaps in it become wrong tasks.
The config reference and the five activity-log formats in README.md are accurate today — we verified them against client/components/expression-list.js. Three gaps remain.
Gap 1 — functions[].editable is documented but not enforced
README.md says of editable: "if set to false, the row is not meant to be edited in the UI." That reads as a lock.
In practice editable is applied to state in config-loader.js#L199 and then never read anywhere else under client/. Nothing prevents editing.
This matters directly: a practice that establishes a fixed reference curve and grades "the learner modified their own expression but left the reference untouched" would be relying on a guarantee the app does not provide.
Ask: either implement enforcement, or reword the README to say editable is currently advisory metadata with no UI effect.
Gap 2 — What is not observable in activity.log
There are exactly four Logger.logActivity call sites in the client: initial state (app.js#L94), create, modify (text and parameter), and delete (expression-list.js#L1096-L1113).
That means these learner actions produce no log evidence and cannot be graded:
- Toggling a row's visibility —
toggleVisibilitymutates state and logs nothing - Pan, zoom, and reset-view
- Switching between the
f(x)andθsidebar tabs - Derivative and secant overlays updating on mouse move
- Opening the help modal
Ask: an explicit "not logged" list next to the activity-log format list. This is the single highest-value addition for us — it is what stops a generator from writing an ungradeable criterion.
Gap 3 — Defaults applied at load
ConfigLoader applies defaults for colors and visibility flags before the app initializes, but the README does not say what they are. Authors need to know the state a learner sees before their first action — including what Initial state: will contain for a given config.
Ask: document the defaults ConfigLoader fills in, and note that the Initial state: line reflects the post-default config.
Gap 4 — The parameter log example in README.md is wrong
Confirmed by dry run, not inference. README.md documents the slider-commit line as values only:
Modified expression expr_1 (parameter: a): 1 -> 2
The app writes the full assignment on both sides. createSliderChangeHandler builds oldExpr as `${pName} = ${formatParameterValue(oldValue, step)}`, and syncSliderAssignmentExpression returns the new assignment in the same shape:
So the real line for a center parameter moving from 0.0 to -5.0 is:
Modified expression center_parameter (parameter: center): center = 0.0 -> center = -5.0
Any acceptance criterion written against the README's format would never match. This is the one item in this issue that makes existing documentation actively misleading rather than merely incomplete, so it is worth fixing even if the rest waits.
Ask: correct the example, and note that formatParameterValue renders to the parameter's step precision (default step 0.1, so 0.0 rather than 0).
Gap 5 — Discrete versus drag slider changes are logged differently
Related, and it affects how gradeable a slider practice is. A drag emits a single line spanning the whole gesture, because onChange fires once at drag end using the drag-start value. Keyboard and track-click changes are discrete and emit one line each, per step.
So "move the slider from 0 to -5" produces one line for a learner who drags it in one motion, and roughly fifty lines for a learner who holds the arrow key — with no single line spanning 0.0 -> -5.0. Task authors need to know this, or they write criteria that only one input method can satisfy.
Ask: document both logging paths and note that only the end state is reliable across input methods.
Suggested shape
A single ## Task Authoring Contract section in README.md, right after "Activity Logging and Grading", covering the points above. Roughly 40 lines. Happy to open the PR if you'd prefer — just let us know whether you want it in README.md or a separate docs/ file.
Activity