SPARC Instructional Cycle Specification

SPARC Instructional Cycle Specification

The supported family contains 14 packages in 12 directories: ten base AutoTutor lessons using progressive-scaffolding-v1, and agent/student packages for categorized Confidence Interval and Species and Speciation using dynamic-instruction-agent-v2 / dynamic-instruction-student-v2. Categorized access remains admin-only. Legacy lessons keep the authored progressive policy for both account roles. Intermediate policies, seven source packages, and admin redirection are retired. Installed lessons and historical attempts are not migrated or deleted. See the current application contract and historical record.

This is the authoritative plan for the category-aware text-response and multiple-choice extension to SPARC dynamic instruction. It states the agreed design, inherited behavior, ownership, implementation sequence, and acceptance criteria. Earlier designs and dated test results are kept in a separate historical record; they are not additional instructions for this extension.

The user authorized implementation of this plan on October 14, 2026. Commit, push, deployment, and additional full Meteor test invocations still require their applicable authorization; this document is not a continuing grant of permission.

Shared move library extension: October 15, 2026

KC graph ownership, October 16: lesson packages cannot supply relationship weights or centrality. Package preflight rejects kcGraph.* facts anywhere in the JSON and the ordinary AutoTutor expectationRelationships / expectationRelationshipProvenance fields. These are omitted from current-package downloads and removed from the authoring schema. SPARC AutoTutor upload always embeds the expectation texts with the existing google/gemini-embedding-001 model and computes the graph through the shared cosine implementation. It does not accept complete supplied graphs, switch models, or copy parent weights. Internally generated graph facts still serve production selection and saved runtime state. Centrality remains mean outgoing strength.

Implementation in progress: the categorized policies gain shared reusable feedback, explanations, support, and questions. Each primitive looks up content by embedding before invoking generation. Production decisions, assistance, assessment, and numeric learner model updates retain their existing meaning. A library hit skips instructional generation, including the image brief for a retrieved figure.

Assessment descriptions retain demonstrated, incorrect, and unresolved authored requirements with stable learner-response citations. These are not additional KCs. Only changed evidence is journaled, atomically with the response assessment. Shown content has a durable learner-specific exposure record, separate from shared content. Resume restores accepted versions. Existing histories and canonical images are retained.

User-approved context scope, October 15: explanation, example, and question generation receives the selected target, its retained descriptive evidence, and the current move's components. Earlier questions remain for novelty; the full transcript, global planner data, other targets, and historical figures are omitted. Misconception moves receive only the selected misconception and its evidence. Embedding lookup uses the same focus; feedback also receives the answered question and learner answer. Assessment scope and production selection are unchanged. Citation mismatches warn without discarding scores or summaries; only exact quotations verified against learner responses are retained as citation spans with stable response identities.

Multiple-choice generation requires complete, concise, conceptually distinct plain-text labels within the existing 240-character bound. Shared wording belongs in the stem; options must be rewritten to fit rather than cut off. A defective library item can be excluded from future reuse without rewriting the saved learner conversation.

An explicitly authorized correction of an unanswered saved question appends a new canonical state transition with the same question node ID. The original question and its library version remain in the journal; the corrected version becomes active on display, answer binding, and dialogue-context replay. This does not rescore prior work.

After generation failure, reload continues an unfinished accepted instructional event under its original attempt and event identities. Assessment, feedback, and already saved components are reused. Completed events restore without further generation. Persisted instructional text must fit both 2,048 characters and 2,048 JSON UTF-8 bytes, including quotes and escaped line breaks.

Local browser acceptance, October 15: the agent-selected species/speciation lesson completed 24/24 expectations in 30 turns using response-confirmed Astra 6 medium. Reload restored the completed conversation across 1,055 history rows without a new model request; Continue returned to the menu, and relaunch was blocked as already completed. Conservative aggregate test accounting was $23.7777 against the authorized $25 total, including an earlier reserve rather than a reconciled provider bill. The shared library held 104 entries, 93 reusable. This continuation encountered no new retrieval hit, so browser highlighting and reuse speedup remain unverified by this run. The student-selected version was not taken through another complete biology lesson. Current changes passed 341 isolated tests, full application typecheck, and lint with zero errors and 28 existing warnings. No new full Meteor CI or deployment was run. The menu's generic "in progress" grouping includes completed used lessons; completion persistence itself was verified. Automatic validation-error retry remains undecided.

Retrieved support already shown in the same conversation is linked and highlighted instead of printed again, using the selected move's unchanged assistance level. Questions check this learner's accepted questions across attempts in the lesson. Repetition is checked by embedding the actual question text. There are no generated question descriptors, evidence/judgment rules, or additional AI reviews of candidates.

The Instructional content library extends the original embedding-grouped browser to every instructional component, including images. Topics are the default: click a topic, then its subgroup, then inspect component thumbnails. Breadcrumbs return to either grouping level. All components pages the same repository. Images and text can share a topic group. Text inspection, immutable revisions, and exclusion coexist with image inspection, replacement, and version history. There are no separate image/content tabs.

One canonical content collection, sparc_instructional_library, serves both primitive and image retrieval. Existing per-learner requests/exposures, immutable image version metadata, and derived group snapshots remain distinct metadata stores. The former image and move collections transfer transactionally in bounded batches; equality is verified before source removal. Existing IDs, vectors, and asset references remain valid. A conflict fails startup and rolls back that batch; completed batches can be resumed without duplication. There is no old-store lookup fallback. Grouping retains the existing silhouette selection, singleton support, representative previews, and semantic assignment across compatible embedding spaces. That algorithm runs first for broad topics and then within each topic for subgroups, with at most 128 sampled vectors per fit. The hierarchy stops after two levels. A topic without a supported split has one subgroup. Only subgroup membership is stored, and counts at both levels cover each component once. Flat snapshots are replaced atomically using the two-level snapshot version; content and retrieval vectors are unchanged. Labels for both levels use the existing administrator model. Within a selected subgroup, thumbnails are sorted by component type: Explanation, Feedback, Image, Question, Support. Each type retains closest-to-center ordering, with component identity breaking similarity ties. Server-side keyset pagination includes the type so each type remains together across Show more pages. The type is read from the canonical component record; no new clustering, embeddings, or duplicate stored type field is required.

User correction, October 15: instructional matching uses embeddings alone. Testing started at cosine similarity 0.90. The user approved retaining primitive type and question response format as candidate restrictions. Exact-context matching and the calibration gate are removed. The highest-scoring eligible match is reused; otherwise the primitive is generated. After the shared-representation evaluation, reuse defaults to 0.992 for text and images. The user approved an independent question-repetition cutoff, currently 0.88 in the shared similarity settings, and specified that feedback must recognize correctness rather than merely repeat an accurate correction. That requirement guides evaluation of matches; no additional runtime matching rule enforces it. Images and text now share the instructional-need projection/serializer and primary vector representation. Reuse is 0.992 for both, with question repetition at 0.88; SPARC_LIBRARY_SIMILARITY owns these values. The separate image/text settings overrides have been removed. Feedback adds the answered question and learner answer in private request input; images add their illustration brief. IDs, full generation policies, and unrelated targets do not enter embeddings. Retrieval and grouping use this primary vector. The October 15 offline reindex converted 111 components and four unfinished requests, preserving content and accepted decisions; rollback and idempotent retry were verified. See the shared-representation section of the source contract for evaluation limits and replacement procedure. Source implementation and injected tests do not establish learning effectiveness or a live speedup. The app repository's docs/sparc-instructional-cycle.md contains the shared move-library transport, storage, resume, and verification contract.

At the final cutoffs, bounded localhost checks confirmed a feedback paraphrase hit, fresh feedback after a corrected answer, rejection of a paraphrased question, acceptance of a different question, and saved-content resume. The threshold sample retained three of four acceptable feedback paraphrases with zero inappropriate reuses among 28 negative comparisons. These small synthetic checks used Luna 6 medium for generation and Gemini Embedding 001 for matching; they are not a full browser lesson or a general reliability estimate. The stricter reuse cutoff also rejects an earlier acceptable explanation paraphrase. All 335 isolated tests, typecheck, and lint passed (28 existing vendor warnings).

Category-aware target differentiation: October 14, 2026

Status: implemented in source, with local acceptance and a passing full Meteor integration run in GitHub CI. The two new policies are dynamic-instruction-agent-v2 and dynamic-instruction-student-v2. Proposed primitive wording is in C:\dev\MoFaCTS\docs\sparc-primitive-instructions-proposal.xlsx, now expanded to 42 linked specifications. The workbook supplies editable authoring proposals, not executable configuration. Runtime behavior uses shared instruction blocks under learning-components/units/sparcsession/; the verification record below distinguishes isolated, live-generation, browser, and CI evidence.

Maximum-relationship KC progression

Set unit.sparcsession.startingKC to the exact expectation clusterKC identity. Canonical upload embeds expectation text using the existing model, generates the complete relationship graph, and computes a maximum-weight Hamiltonian path with that KC fixed as its first endpoint. There is no relationship cutoff. HiGHS solves integer weights at the graph's existing six-decimal precision and adds subtour cuts until it proves one optimal path. Solving runs in a disposable server worker. A failed or unproved solve stops upload; there is no heuristic substitute.

The server saves kcGraph.chain facts keyed by starting KC beside the graph. Distinct unit starts on the same page receive separate generated paths. Packages cannot supply any kcGraph.* facts, and exports omit them. The TDF parameter is the sole authored start; page resolution carries it into the runtime selection policy. An absent, incomplete, or mismatched generated chain fails explicitly.

Practice selects the first KC in that path whose coverage is below the existing criterion (normally 0.8). Incidental credit skips already covered KCs. An active unfinished cycle stays active; misconception repair retains its priority. The centrality/frontier/coherence formula does not rank targets in these units. Move and assistance competition, assessment, and stopping criteria are unchanged. Student next-KC navigation follows chain order. Resume restores coverage from existing history and scans the same saved chain; accepted decisions are replayed unchanged, with no additional progression counter or history rewrite.

KC-led startup

Categorized v2 units with sparcsession.startingKC begin at the first uncovered KC in the generated chain. Units without it begin with the most central expectation, without the fixed 42–50 scenario or a permanent focal-question heading. A document-loaded event enables the existing expectation-start productions. For units without a configured starting KC, initial target selection uses generated graph centrality alone, retaining the stable target-ID tie break; automatic move competition is restricted to that target. For the confidence-interval test package, KC a and e2 tie at 0.616667, so KC a starts.

The automatic condition generates its selected move. The student condition offers the existing six move choices and next-KC navigation before generating the chosen move. No learner response, assessment, feedback, or model update is invented, and the turn count stays zero until an answer is submitted. The normal evaluation → feedback → selection cycle follows each answer.

After startup, automatic next-KC ranking uses the preceding KC as its relationship anchor. The shared controller derives it from the saved expectation cycle, even when that KC has just met the coverage goal. A misconception interruption retains the most recent KC from saved tutor instruction. The configured frontier (0.5), coherence (0.3), and centrality (0.2) terms then contribute to the structural score, from which remaining instructional need is subtracted. An existing active target continues under the normal cycle rules, and eligible misconceptions retain their priority. The student’s explicit next-KC button retains its authored-list behavior. Resume rebuilds the anchor from existing saved state; it requires no migration and does not change already accepted decisions.

Use the existing authored dialogue.source.topic as lesson context; categorized upload/runtime validation requires exactly one such source with a nonempty topic. Questions include their own necessary givens. A starting explanation briefly establishes the selected concept's basis or purpose, for example “When first thinking about …”; continuation moves need no repeated introduction. The existing lesson title remains. Progress, expectation coverage, misconceptions, and turn count sit in a compact disclosure at the upper right of the instructional surface. It starts closed; opening it overlays the conversation and reserves no header row or extra horizontal space. It remains open through responses and selections until the user closes it, and resets to closed when a new view mounts. Native keyboard activation, Escape from the toggle, visible focus, and reduced-motion handling are retained.

Canonical history saves startup decisions and components. Reloading resumes partial generation from its accepted production or restores an established conversation without another opening move. Histories are preserved; no migration or automatic practice reset is required. These changes apply to categorized policies; the intentional v1/reference opening paths remain.

Startup verification on October 14: full application typecheck and lint passed (lint retains existing vendor warnings); 55 focused instruction-cycle, dialogue-node, and content-contract checks passed. Both revised packages were uploaded privately to localhost. In the browser, automatic instruction began at KC a with zero turns, survived reload unchanged, credited one correct answer, and then started KC e2. The student condition began with its six move choices and next-KC navigation at zero turns, then generated the chosen explanation and question on KC a. The earlier CI results below precede this startup change; no new full Meteor invocation was run. The new provider-prompt regression requires the supported Meteor environment and remains for the next authorized CI run.

Assessment change history and full resume

Instructional-cycle assessments save one history row per changed KC coverage or misconception-support value. Unchanged scores carry forward when history is replayed; an absent score has the existing zero baseline. Returning an active misconception to zero is a change and is saved. A separate assessment marker retains the learner response and turn/controller facts. The score changes and marker commit together in one Mongo transaction, so an assessment cannot be partially accepted. Stable transition identities make identical retries idempotent and conflicting retries fail explicitly.

Loading reconstructs the current score state alongside conversation, selections, controller state, and model state. Existing bundled assessment histories remain readable without rewriting them. If a later model update or generation step is interrupted, resume reuses the accepted assessment without another scoring call or duplicate model gains. The existing per-record limits remain: 16 KiB per component extension and 32 KiB wire payload. Assessment batches are bounded at 256 rows and 1 MiB and require the configured Mongo replica set; no sequential-write substitute is used. Technical ownership is documented in the main repository's docs/sparc-instructional-cycle.md.

October 14 local acceptance for the 24-KC/20-misconception Species and Speciation lesson: the agent condition saved two scored answers and continued after reload; the student condition saved partial coverage, an active misconception, and a repair back to zero across three scored answers, restoring matching state after reload. The final agent reload created no additional history rows. The largest observed extensions were 4,767 bytes (agent) and 5,924 bytes (student). There were 214 passing focused checks covering transaction failure/retry, authorization, history loading, interruption, and replay; full app type checking and lint passed. No new full Meteor/CI invocation or production deployment was performed for this repair. Complete live chapter traversal and graduation remain unverified.

Before commit, the two stale provider-prompt assertions were aligned with the implemented lesson-context wording. The combined client/history suite then passed all 241 checks, with full app type checking and lint passing again. This closes the earlier local prompt-assertion failures; full Meteor/CI verification remains a separate run.

Instructional Markdown and theme integration

Instructional prose, comparisons, and tables render as sanitized Markdown, including GFM tables, in both new and resumed conversations. A whole-document md or markdown fence is treated as a Markdown envelope; other fenced code remains a code block. Saved content is rendered without rewriting history or rescoring answers. Learner responses and answer-option labels remain plain text. Text cannot load embedded media or interactive controls; figures continue through the saved-asset renderer.

Conversation tables, lists, headings, and code use the theme's rich-text styling. Buttons follow theme button dimensions and action states, with primary action colors for Submit, visible keyboard focus, a separate selected-answer outline, and disabled styling that does not react to hover.

Tutor outputs now allow tables and comparisons to use the conversation width, while prose and answer lists keep a comfortable reading measure. Options are start-aligned and normal-weight with increased line spacing. Tables scroll locally on small screens instead of squeezing their columns. Nested borders are reduced in favor of spacing and subtle support backgrounds.

For administrators, each production output has a closed Details disclosure below it. Clicking the toggle slides its production and selection information into view. Keyboard toggling, Escape from the toggle, and reduced motion are supported. Ordinary learners do not receive the disclosure. It does not modify saved learning state.

Seven target categories

Use three basic content labels: fact, model, and rule. A principle is the combination model + rule, not a fourth independent label. The seven categories are all nonempty combinations:

1. Fact
2. Model
3. Rule
4. Fact + model
5. Fact + rule
6. Model + rule (principle)
7. Fact + model + rule

These categories describe the intended learning demands of the target. For a misconception, they describe the understanding or application needed to correct it. Do not add “fact” merely because an explanation contains factual statements, or “model” merely because a procedural rule could be explained; the category reflects what the learner is expected to demonstrate.

Production eligibility decision

The selected target's category must be an explicit condition in the production's IF part. Category differentiation must not be left solely to a generation prompt after selection. Each category-specific production matches the target's complete combination; a fact + model target does not also qualify for the fact-only or model-only versions by subset membership.

Retain all five existing target-transition groups: start expectation, continue expectation, start misconception, continue misconception, and interrupt an expectation with a misconception. Retain three instructional compositions: question; explanation and question; explanation with worked example or figure and question. Each composition has a text-response and a multiple-choice version, giving six move versions. Differentiate them by the seven target categories, giving 5 groups × 3 compositions × 2 response formats × 7 categories = 210 planned automatic instructional productions. Evaluation, feedback, and stop productions are excluded. Categories are reusable across KCs; do not create a separate production family for each KC. Shared rule construction and primitive implementations should remain shared where their behavior is the same.

Response formats and assistance

The question primitive may request either the current text response or a multiple-choice response. Select the response format as part of the move before generating its content. Reuse the existing multiple-choice primitive after tracing and verifying its integration with this instructional cycle; its existence does not establish that the new path already works.

Use the following assistance values, all in logits for the complete move, not per-component additions:

Instructional composition	Current baseline	Planned text response (baseline − 0.25)	Planned multiple choice (baseline + 0.25)
Question	0.00	−0.25	0.25
Explanation + question	1.80	1.55	2.05
Explanation + worked example or figure + question	2.77	2.52	3.02

These six settings apply across all seven content categories and all five transition groups. “Baseline” refers to instructional composition, not to fact/model/rule category. The negative text-question value is intentional; do not clamp it to zero. The multiple-choice variant is 0.50 logits above the corresponding text-response variant. No OET, temperature, or learner-expectation floor change follows from this assistance change.

Presentation of instructional support

Shared presentation requirement, implemented for the new policies. Apply consistently across the seven category combinations and three move forms when supporting material is present.

• Ordinary text explanations remain unframed. Frame other instructional support, including images, worked examples, comparisons, and tables. A worked example or comparison is framed even when its content is text.
• Images stand alone inside their frame, with no displayed caption or title. This does not remove labels within the image that are necessary to understand its content.
• Worked examples have the heading Worked Example within the frame.
• Comparisons may have the heading Comparison. For tables and other labeled support, the AI may choose a concise heading identifying the kind of information or instructional form presented.
• Headings identify the form, not the subject matter. Assume the surrounding question establishes the topic; avoid repeating that topic in a decorative title.
• Keep frames compact, with modest internal spacing and a small, centered heading where a heading is appropriate, consistent with the existing worked-example presentation.

This is a shared presentation contract, not wording to repeat in all 42 primitive specifications. It does not by itself introduce additional move types or change production eligibility.

No displayed image caption or title does not mean no accessible description. Preserve a meaningful accessible alternative through the existing image/node contract, and retain the saved description used by generation and replay. Preserve keyboard operation, visible focus, semantic labels, readable contrast, and screen-reader announcements for choices, submission, and feedback. Keep interface, authored-content, learner-response, speech-recognition, and text-to-speech languages distinct; this extension does not change their contracts.

Authored categories and composable instructions

Assign one of the seven categories to each expectation and misconception during lesson authoring and store it with that target in the lesson package. Keep that assignment fixed during instruction. The implemented field is category on each autoTutorTargets.expectations or .misconceptions entry. The corresponding autotutor.expectation or autotutor.misconception fact retains the same field for exact production matching. The initial Confidence Interval package's seven expectation and three misconception assignments are recorded in its README and the workbook.

For the new category-aware package family, app-owned upload validation must reject a missing or invalid category with an actionable target-specific error. Runtime validation must also reject an invalid category before selection or generation. Do not default to fact, select a generic production, or ask the LLM to infer or repair the assignment. Scope this required contract to the new family; do not impose it on unrelated working packages. Search both application and config contracts before choosing a field, and use the existing policy/version and attempt identities to prevent a saved attempt from being reinterpreted under a different contract.

Use 42 reusable primitive specifications: three compositions × two response formats × seven categories, shared across all five transition groups. Compose their instructions from the selected fact, model, and rule blocks, the selected move's instructions, its response-format instructions, and one shared synthesis instruction. Maintain the shared blocks once. The workbook displays the synthesis once at the top rather than repeating it in every row. Extend the current 21 proposals with the multiple-choice variants; do not create independent copies of all shared instruction text.

The authored KC determines the question's demands: recall, recognition, application, and/or explanation. Explicitly allow multiple demands. Strategically integrate as many of the demands as feasible that it specifies and elicit them. Do not force every possible demand into one response, or automatically turn a recall or recognition KC into an application problem. The constant/variable distinctions discussed in KLI can be represented through the authored KCs and their demands; they do not add categories or multiply the 210 productions. Both response formats must respect these requirements; multiple-choice wording and response interpretation need explicit review rather than assuming they are identical to free-text generation and evaluation.

Generation knows the selected move

The production selects the move and response format before content generation. Every component-generation call receives the selected move, response format, target, category, and applicable composed instructions, as well as the component it is being asked to produce. Generate the text portion for that move with enough context and coherent references to make the nature and use of its support clear. Do not generate generic text without knowing the move and attach a support type afterward.

For the rich move, retain the existing dependency that realizes support before generating explanation and question. Those later components receive the actual worked example or figure and refer to its actual content. A diagram, table, or example should make its instructional role evident through its content and the surrounding text, subject to the framing and heading requirements above. No additional synthesis LLM call is required by this design. The precise instructions remain a reviewable proposal; this planning decision does not create 42 independent copies of generation or persistence code.

Student choice and initial package scope

Students continue choosing the instructional move, not the target category. The authored category determines which of the same 42 specifications is used. Include the text-response and multiple-choice move versions in the student-choice wiring; settle concise option labels and presentation during implementation planning. Retain separate next-KC navigation; do not add a category-selection menu.

Start with separate new versions of the one Confidence Interval test package for the automatic and student-selected conditions, so initial work does not overwrite important existing content. These new test versions may be updated as development proceeds. There is no requirement to preserve every previous test version indefinitely or to build a broad compatibility or migration project. Do not deliberately break existing working behavior or overwrite learner histories. Keep initial implementation focused on this test package and the shared code it needs.

Inherited cycle and numerical contract

The supported categorized policies are dynamic-instruction-student-v2 and dynamic-instruction-agent-v2, implemented in learning-components/units/sparcsession/sparcDynamicInstructionRules.ts. Retain its admin-only delivery and server authorization; client visibility is not authorization. Resolve new version identities through existing contracts without reinterpreting saved attempts. Inherit the family's evaluation, separate feedback production, target transitions, and completion behavior. Feedback for the accepted response precedes either instructional selection or terminal handling, using the existing assessment without a second scoring call. Feedback may explain the correction but does not ask another learner question or choose the instructional move. Its accepted node supplies readiness through existing production conditions; no additional feedback state machine is introduced. Both conditions stop under their existing dynamic completion conditions; student next-KC navigation remains separate from instructional choices and does not introduce indefinite completed-target practice.

Initial operational knowledge and the expectation floor remain 0.2, OET remains fixed at probability 0.8, and selection temperature remains 0.1. For an eligible move on the already selected target, utility = -abs(expectancyLogit + assistance - logit(0.8)), and its Boltzmann probability is exp(utility / T) / sum(exp(eligibleUtility / T)), evaluated with numerically stable softmax. Here expectancyLogit is the existing history-derived, floored learner estimate, assistance is the complete-move logit value in the approved table, and T is selection temperature, separate from LLM generation temperature. Exact utility ties receive equal probability. There is no OET ramp or salience term in this extension.

Production conditions determine the target before instructional moves compete. Preserve current-target continuation and detected-misconception interruption/resolution; do not make unfinished KCs compete by instructional utility. Match the complete authored category, then compare only the eligible move/format variants for that target. Duplicate matches must not give a move extra probability. Student selection invokes the chosen eligible variant without Boltzmann substitution. Retain existing history-derived model calculations and raw evaluation meanings; this extension changes neither scoring scales nor durable model ownership.

Shared figure-library dependency

Reuse the existing server-owned teaching-figure library, similarity retrieval, canonical assets, and per-learner saved decisions. Preserve current provider, embedding, similarity, access-control, and storage settings; this extension does not redesign retrieval or select a new provider. New support uses the actual retrieved or generated figure and its saved description before dependent explanation/question generation. Provider or storage failure remains explicit, with retry of the same accepted decision.

A saved learner decision retains its original asset even when an administrator later deprecates or replaces a library image. Removing visible captions in the new presentation must not remove stored descriptions, accessible alternatives, or the image context supplied to generation. Keep library data access bounded and authorized, and do not expose embeddings or learner histories in learner output. Current service ownership is documented in the app's docs/sparc-instructional-cycle.md; the dated service details and checks are retained in the historical record.

Multiple-choice events, evaluation, and durability

• A student choosing an instructional move emits a menu-selection event, not a scored response. A student answering the resulting multiple-choice question emits a learner-response event. Keep those meanings distinct even though both involve clicking an option.
• Bind a menu selection to its saved offered option and target. Reject stale or modified options through the existing acceptance boundary. Selecting a move reuses the prior assessment and cannot rescore the preceding answer.
• Before implementing MC evaluation, trace the existing primitive's option identities, answer key, submitted-value representation, and scoring adapter. Specify how the selected option reaches the existing learner-evaluation contract and test correct and incorrect answers. Do not invent a new scoring model or treat the option's display position as its meaning.
• Persist and restore the accepted question, option identities and displayed order, answer interpretation, selected response, generated support, and effective policy through existing node/history contracts. Reuse any existing representation; this is not a requirement for duplicate fields or another store. Reload must not reshuffle options or generate a different question after acceptance.
• Reuse existing event, decision, transition, and node identities for idempotent acceptance. Duplicate submissions and uncertain writes cannot add a second assessment or model update. Competing menu choices contend on the same pending decision, and an accepted choice cannot be replaced by another sample.
• Retry failed generation using the accepted decision and already saved components. Keep failure explicit; do not substitute another format, move, category, worked example, or figure. Preserve saved learner figure decisions through the existing server image/library services.

The implemented MC response sends the selected saved option's label to the existing semantic evaluator. Its canonical response event records questionId, choiceId, and answer-key correctness; the key does not directly set KC coverage. The scorer receives the actual question context and a response-format annotation derived from canonical events, distinguishing endorsement of supplied wording from independently produced recall or explanation. Unselected distractors are not learner beliefs. No second model or accumulator is introduced.

Implementation ownership and change boundaries

Responsibility	Owner and reuse requirement
Production eligibility, target transitions, composed pedagogical instructions, and response interpretation	Existing learning-components/ SPARC unit, primitive, and trial-display contracts. Extend shared rule construction; do not hand-maintain 210 independent prompt implementations or add another eligibility service.
Upload validation and schema exposure	Existing app-owned TDF/SPARC authoring contracts in mofacts/, aligned with the learning-component contract.
UI, rendering, event delivery, canonical persistence, authorization, and external-provider boundaries	Existing app modules in mofacts/. Keep pedagogical computation in learning components behind explicit interfaces; do not introduce pure-compute server methods.
Figure retrieval, generation decisions, and asset persistence	Existing server image/library services. Reuse their durable decisions and canonical assets; no parallel image store or retrieval pipeline.
Authored targets, categories, and the two new test-package versions	C:\dev\mofacts_config, as passive content storage. MoFaCTS owns upload validation; no config-repository validation service or manifest system.
Public contracts and detailed explanation	Concise app docs plus this wiki page, updated with implementation. The workbook remains an authoring proposal, not runtime configuration.

Before adding fields or helpers, search the owning and adjacent modules and the config repository for existing concepts. Resolve any pre-existing duplication before building on it. Preserve the intentional deterministic AutoTutor reference without copying its engine or routing failed new requests into it. No new dependencies, destructive migrations, additional learner controls, or broad compatibility layer are included. Trace affected readers and writers before extending durable contracts; deliver runtime and package changes in compatible order.

Implementation sequence and acceptance

1. Expand the prompt table to 42 composed instruction proposals, review the text-response and multiple-choice variants, and review the ten authored target-category assignments.
2. Resolve the existing category/schema and policy/version boundaries, then implement target storage, app-owned upload validation, and production facts. Verify rejection of missing/invalid categories and compatibility with dependent content before proceeding.
3. Trace the existing multiple-choice primitive through generation, rendering, answer submission, evaluation, feedback, persistence, and progression. Establish its answer interpretation using the event and durability contract above, integrate it coherently, and preserve the text-response path.
4. Extend production IF matching and THEN selection to route the selected category, composition, and response format into the shared component-generation path, including student choice. Apply the six approved assistance values and shared support framing/heading requirements.
5. Verify all 210 automatic instructional productions structurally, including exact category eligibility, both response formats, the six assistance settings, duplicate-match handling, and preserved target-transition behavior. Verify that student choices reach the corresponding shared specifications. Check duplicate submissions, competing/stale menu choices, failed generation, uncertain writes, and restoration of identical MC content/options and accepted responses using the existing appropriate test runners.
6. Review an initial live generated example for each of the 42 combinations, using several subjects where necessary for meaningful category coverage without expanding the initial package rollout. Exercise correct and incorrect multiple-choice answers, response interpretation, feedback, misconception handling, student choice, progression, completion, and resume. Confirm saved choices and generated support remain coherent after reload; review image alternatives, keyboard operation, focus, labels, and feedback announcements. Repeat cases that reveal problems. This is initial acceptance coverage, not proof of consistent generation quality.

Each implementation step must leave its touched writers, readers, and interfaces coherent and pass applicable checks before the next step relies on them. The response-format assistance adjustments above are approved; no fact/model/rule-category-specific assistance changes or general scoring redesign are approved here.

Required verification and handoff

Change or claim	Required verification
TypeScript-bearing application changes	Full npm run typecheck from C:\dev\MoFaCTS\mofacts; no per-file substitute.
Lintable TypeScript, JavaScript, or Svelte changes	npm run lint from the same directory. Review authorization and update the security-surface contract if server interfaces change.
TDF field registry or schema changes	npm run generate:schemas, inspect generated diffs, and exercise both new packages through app-owned upload/load validation. Check dependent content contracts without turning config storage into a validation service.
Production, generation, and replay contracts	Extend existing relevant runners with the current acceptance cases; injected providers and writers establish isolated contracts, not live database concurrency or generation quality.
Meteor integration and database acceptance	Use CI or another supported Meteor test environment. Every npm run test:ci invocation needs fresh explicit user authorization. Confirm test-driver resolutions are cleaned from .meteor/versions.
Learner presentation and behavior	Observe both conditions, both formats, compact support framing, accessible operation, progression/completion, and reload. Record generated content separately from rendered and persisted evidence.
Reference behavior and final review	Check touched shared paths against the deterministic reference. Review diffs for duplicate state, silent substitutes, leaked data, unwanted generated files, and unapproved dependencies.

Historical test results do not verify this extension. Required failures block staging, commit, and push unless the user explicitly accepts the reported failure and risk. If a required check cannot run, report its reason and the supported next verification path. This plan does not authorize Docker build, deployment, data migration, or code publication. At handoff, identify changes, exact verification results and gaps, compatibility/documentation impact, preserved unrelated changes, and remaining decisions. Use synthetic or minimized test data and keep credentials and learner records out of artifacts.

Implementation and local acceptance: October 14, 2026

The two new policies use the existing rule engine, target progression, history-derived model, feedback stage, component generators, and server figure library. The automatic set contains 210 instructional productions plus evaluation, feedback, and stop (213 total). The student set contains those three shared productions, five target-transition menu productions, 84 category-specific instructional-choice productions, and two next-KC productions (94 total). The six move definitions and seven composed categories supply the 42 shared specifications; there are no 42 separate generation engines.

Both fresh Confidence Interval ZIPs are saved under C:\dev\mofacts_config\SPARC Categorized Confidence Interval, with their matching TDF/stimulus files and target-category README. Both passed application-owned upload/load validation and were uploaded privately to localhost. The workbook now contains 42 linked specifications, a single synthesis reference, shared editable instruction blocks, and the ten category assignments. Formula recalculation and rendered review were completed.

Verification completed:

• Full application npm run typecheck passed. npm run lint passed with zero errors and 28 existing vendor warnings; server algorithm ownership, the 318-surface security contract, and absence of Meteor test-driver manifest artifacts passed.
• npm run generate:schemas passed. The inspected stimulus-schema diff exposes the shared category enum; no TDF schema change was generated.
• node scripts/sparcAutoTutorRules.test.cjs --include-general-rules --include-client-contracts passed all 266 tests in 25 suites. Coverage includes package preparation retaining categories, exact production matching, all 42 student instruction routes, model/target boundaries, correct and incorrect MC answer interpretation, blocked free-text submissions at menus/MC questions, stale/tampered answers, duplicate acceptance, interrupted persistence, feedback order, and chronological replay. This is isolated contract evidence, not real-database concurrency coverage.
• Live generation through the actual authorized localhost provider methods completed all 42 category/composition/format combinations using openai/gpt-6-luna. Examples used biology, evolution, compound interest, reinforcement/punishment, and statistics. Four deficient cases were repeated after tightening question-answer leakage, selected-KC scope, and duplicate-heading instructions. This is initial generation coverage, not a reliability estimate. The saved synthetic results and PNGs are local ignored artifacts under C:\dev\MoFaCTS\tmp\primitive-proposal-20261014; live-generated-examples.json retains each target, category, move, and generated output.
• The student browser walkthrough exercised all six move options, incorrect MC misconception detection and subsequent resolution, keyboard answer submission, separate next-KC navigation without rescoring, return to text answers, compact Worked Example/Comparison frames, identical MC order after reload, and unchanged saved support after reload. It reached 7/7 expectations and 0/3 active misconceptions in seven turns, resumed that completed state, and returned to /home through Continue.
• The automatic browser walkthrough used weak, incorrect, and correct responses, with no student move-choice menu. It selected an expectation/rule worked example, interrupted that target for M1 with a model teaching figure, resolved M1, and progressed to model-rule and fact-rule targets. It used both text and MC variants and continued the current KC while cumulative evidence was below threshold. It reached 7/7 expectations and 0/3 active misconceptions in seven turns, delivered final feedback, and returned to the practice menu through Continue. The image rendered inside its frame without an external caption/heading and retained its accessible description. Screenshots and the synthetic automatic conversation are saved with the local acceptance artifacts.

An earlier authorized local npm run test:ci invocation passed 16 harness checks, then exited with Refusing to run Meteor CI tests outside CI; it did not execute Meteor server/client tests. No CI environment override was used.

After fresh authorization to commit, push, and run the integration tests, app commit 620d3ea2 started GitHub CI run 38590386435. Its lint-and-test job passed: 16 harness checks, 812 server tests, and 1,109 client/browser tests; SERVER FAILURES: 0 and CLIENT FAILURES: 0. The suites reported 15 server and 7 client tests as pending. Full application and vendor typechecks, lint, and captured-source verification also passed. The runner removed transient Meteor test-driver resolutions, verified the tested source after execution, and cleaned its disposable MongoDB and captured workspace. This is one supported CI integration invocation; it does not claim production deployment. The separate Security workflow also passed on the same commit.

The generation batch and browser work reached the existing authenticated OpenRouter DDP limit. At the user's request, that existing limit was increased from 120 to 600 requests per hour. It remains bounded and shared by ordinary authenticated OpenRouter methods; method authorization and public-demo quotas are unchanged. The automatic browser retry then succeeded using the same opening response.

No existing learner history, source lesson package, or deterministic reference was overwritten. There is no destructive migration or new dependency. Earlier unrelated wiki edits were preserved. This record establishes source implementation and local acceptance; production upload, deployment, and release qualification are separate actions.