SPARC Instructional Cycle Specification

Approved no-repeat principle, October 28, 2026

Current source behavior; deployment is a separate operation. A user must not receive the same instructional content again in a new turn. This covers explanations, written support, questions, feedback, hints, summaries, other tutor messages, images and video segments, across lessons and sessions. Restoring an existing saved turn retains its original content. Shared library material remains available to other users who have not received it.

Check each component separately, including newly generated output. An instruction with a new record ID can still contain an old explanation or image. Reordered answer choices do not make an old question new. Links to the earlier material do not satisfy this requirement. Retrieval must select the best eligible unseen material, and durable acceptance must prevent stale-cache and simultaneous-tab duplicates. Historical presentations must contribute to eligibility; resetting progress must not silently erase that memory.

The existing saved decisions retain compact component identities. A bounded, restartable initialization adds missing metadata from original saved output while leaving the conversation's text and images intact. New-turn selection excludes used components; restoring the same accepted turn keeps its original decision. A missed save acknowledgement checks that decision before generating another draft, even when the used item has left the eligible browser index. Shared library content continues to serve other users who have not received it.

The server also checks directly generated tutor messages when saving their output. Usage and history commit together; a rejected duplicate is not displayed as a new accepted turn. Existing errors remain explicit. No conversation deletion, reset requirement, paraphrase detector or automatic provider retry is introduced.

The full implementation and acceptance requirements are maintained in the public repository's same-user no-repeat specification. This requirement supersedes the earlier reuse/highlight and unrestricted maximum selection descriptions below; it does not claim a production fix or deployment.

Lesson execution access, October 26, 2026

Execution uses server-verified lesson access for both dynamic-instruction policies. The existing enrollment, released-assignment and experiment-membership resolver owns access. Course execution uses the learner’s durable assignment context. Authentication alone, a client policy label or a retained history row does not grant execution access. Administrators retain author testing; participants are never promoted to administrators.

Runtime provider calls, own-history writes, shared retrieval/components and private/canonical media reads enforce that boundary. Editing, library inspection/curation/deletion, server credentials, unrelated private assets and other learners’ records retain their administrative or ownership restrictions. Fresh sessions resolve lesson credentials on the server without requiring an earlier history row; raw credential-returning permissions are not broadened.

Automatic demos and directly provisioned participants in server-marked demo lessons share 24-hour expiry and the existing 60 AI calls/hour per account and IP limit. Ordinary enrolled learners are not classified as demo accounts. Runtime failures dismiss the loading overlay and display an accessible retry message. The implementation is recorded in application commit 0235180948eb59d66dbe8a9c9139c93eb2282a25. Full Meteor verification on October 26 passed 803 server tests and 1,160 client tests, with 15 and 7 pending respectively. Production release evidence is tracked separately.

Conversation turn markers, October 25, 2026

Categorized SPARC conversations label instructional turns Turn 1, Turn 2, and so on using the interface locale. Feedback closes each turn; the next instruction or student choice begins the next one. Labels are presentation-only and reconstruct on resume without new saved fields or changes to assessment counts. Completed feedback does not create an empty trailing heading. The conversation reserves scrollbar space and applies resize-driven following and Progress clearance before paint to avoid intermediate scroll positions and width changes.

Saved-conversation restoration uses the retained-history snapshot to hold the initial conversation hidden and inert until content checks and image decoding settle. It then reveals the same mounted nodes after layout; the existing loading status is shown while preparing them. Failures remain inline and failed figures still block their questions. New tutor output retains progressive rendering. This also covers a saved first question with no learner answer and requires no stored-data changes.

Image generation model, October 29, 2026

New SPARC images are requested by GPT-6.1 Sol (openai/gpt-6.1-sol) through OpenRouter's Responses API and its openrouter:image_generation tool. The tool uses GPT Image 2.5 Sunburst (openai/gpt-image-2.5-sunburst) at Medium quality with PNG output. The controller request is pinned to OpenAI with provider fallback disabled, response storage disabled, and one tool call. The image boundary requires exactly one completed raster result and fails rather than substituting another model or text. Asset metadata records the image model and quality; the dialogue model remains account-configured.

The existing model-specific retrieval selector restricts new image searches to Sunburst entries. Previously saved images and learner decisions remain readable without migration, deletion, or regeneration.

Joint instruction composition and durable stages, October 24, 2026

Assessment context and prompt-cache reuse

The assessor receives questions, learner answers, conversational feedback, and only the selected KC/misconception identities and proposition text, with their accumulated descriptive evidence. Explanation/support prose, media metadata and descriptions, library references, and lesson background are omitted from assessment requests. Durable lesson history and resume rendering retain the full instruction. Citation indexes use the compact history while source-span citations preserve the original learner response identity locally.

Fixed grading instructions and a fixed response schema preserve reusable prefixes across KCs and formats. Append-only assessment dialogue comes before changing target/evidence data. Unknown and duplicate evaluation identities remain rejected against the selected subset by the evidence reducer. The existing prefix-caching setting still controls session routing affinity; provider-reported cache reads/writes are the evidence of actual reuse. Provider cache requirements and expiry still apply, so stable prefixes do not guarantee hits. No model/provider setting is changed.

Instruction composition

Explanation and requested support are composed together in one structured AI response. Written support is finished in that response; visual support supplies the matching brief and description for the existing combined image/video search or image generation. The practice question remains a separate call using the completed explanation and actual support. This supersedes the separate support- then-explanation generation sequence described in older sections below.

The existing library stores an instruction entry as one matched unit: text is its explanation and optional support contains the companion text, heading, and media reference. Browser indexes distinguish instruction support types and use 0.95 for instruction and question reuse. Feedback uses 0.975; visual retrieval remains one local maximum at 0.95. Browser search and server acceptance use the same category-specific threshold. Old separate entries are not combined into pairs, migrated, or deleted.

The canonical event journals instruction:composed before media resolution, instruction:resolved after a requested visual succeeds, and instruction:accepted after library acceptance. The composed checkpoint holds the brief; resolved checkpoints hold the media; the accepted checkpoint appends both display nodes together and immediately refreshes the visible instruction, while the question is still generating and response controls remain disabled. Written instructions advance directly from composed to accepted. Each save is awaited before the next operation. Question persistence and cycle completion precede enabling learner input. The existing history owner provides idempotent writes; no new lock, polling, or automatic retry is added.

Retries and reloads use the last durable checkpoint, preserving the explanation and its brief instead of regenerating completed work. Lost publication acknowledgements use the existing accepted library decision. Old incomplete unpaired moves are not resumed as matched instructions. Historical completed nodes remain readable. Navigation guards discard late UI updates from another scope. Loading messages are Preparing instruction, optional Preparing visual support, and Preparing question; display order remains explanation, support, question. Client and server must be released together for the new instruction payload and checkpoint contract. No TDF authoring fields change.

Practice history and initialization lifecycle, October 23, 2026

Practice history saves do not rebuild dashboard or course summaries. Dashboard entry refreshes its history cache before reading dashboard or course snapshots; last-used unit and resume state still save during practice. Dashboard cache version 8 counts one assessed SPARC response, excluding intermediate checkpoints and per-KC evidence copies. Older cache totals rebuild on dashboard access.

Failed browser retrieval attempts stop their subscription and observer, clear partial vectors, and leave the category cache. A failed categorized-dialogue initialization exposes the existing localized Try again action. Each explicit attempt reinitializes the failed work; there is no automatic retry loop or substitution for invalid data. The learner cannot submit before initialization succeeds. Retired exposure and manifest records are not migrated or deleted by these changes; the existing user-deletion owner retains access to retired user-specific exposure records.

Practice round-trip reduction, October 23, 2026

A local cache miss returns its query and vector directly to generation without a server lookup or pending-request write. Publication validates this request under the authenticated account and saves its accepted decision. A hit still fetches and accepts the exact selected ID. Publication returns the already-held content when its decision wins; a concurrently accepted decision remains authoritative. Persisted history restores presented components. If publication succeeded but history did not, a repeated generation may produce a draft; publication returns the existing accepted content before that content is journaled.

Canonical history is the sole record of presented components. Obsolete exposure and move-manifest projections and the separate presentSparcPrimitive method have been removed. Assessment batches retain atomic, idempotent persistence. Component persistence is still awaited and failures propagate. Excluding provider calls, a new generated component now uses publication plus history persistence (two calls rather than lookup, publication, history, presentation); a retrieved component uses selected-ID lookup plus history persistence (two rather than three).

Visual primitives skip both primitive search and query embedding before their brief is generated. The later combined image/video search remains the only visual search. When storing the visual component, the server reuses the selected media's existing vector for catalog browsing; it never stores an empty placeholder vector. Authored assessment target vectors, when more than four misconceptions require selection, are prepared alongside library caches during initialization. Scoring uses the same completed-vector cache. Component generation order, provider retry policy, and cache retention policy are unchanged. No stored learner data is rewritten, and no TDF fields change. Client and server must use the updated structured publication-ticket contract together.

October 23 browser retrieval revision

Practice search and vector caches are browser-owned. An admin-only live vector publication initializes the category indexes before the first learner response, transferring IDs and vectors only. Database selectors define category membership; the local search computes one exact maximum among that user's eligible unseen items and applies the category threshold. No candidate sorting or semantic novelty evaluation occurs. Feedback reuse uses 0.975; other text uses 0.95. Images and authored-language videos compete in one search at 0.95. Missing authored language excludes videos; interface locale does not supply it. Changes and removals update the local index; account changes clear cached vectors.

Query embeddings are cached locally after completion. The server proxies only secret-bearing provider operations and handles content/decision/history persistence and exact-ID content reads. Independent misses independently generate copies: practice uses no generation locks, 500 ms polling, cross-call promises, video-first search or second image search. Existing saved decisions still restore the content already presented to that learner. Administrative curation and browsing locks are separate maintenance operations. No TDF or learner-history migration is needed.

October 23 durable submission revision

Categorized SPARC saves the student's submitted answer before assessment starts. The existing response event binds the answer to its question and saved instructional context. Its submission checkpoint adds the learner utterance and locks the response controls, but does not award credit or advance the assessed-turn count.

Reload restores the accepted answer even if scoring failed or never finished, and continues assessment from the saved response and pre-response context. Once assessment is saved, resume reuses it and finishes only missing feedback or instructional work. Saved questions, support, and decisions retain their existing identities. Retries do not create another accepted answer; conflicting concurrent writes fail explicitly.

Older assessment-owned answers remain readable without rewriting learner history. No migration, new TDF setting, or separate recovery store is required. This guarantee begins when the server stores the submission; it does not cover unsubmitted typing or a request that never reached the server.

October 23 cumulative requirement reassessment

The evaluator receives the exact retained demonstrated and unresolved requirement lists that guide question generation through the existing priorEvidence context. It reassesses those KC requirements, carries earlier demonstrations forward, and adds newly resolved requirements to cumulative coverage. The latest answer need not repeat earlier demonstrations. Requirements do not become unresolved again solely through omission, and the evaluator must not invent a new decomposition on every turn. An initial decomposition is inferred only when no retained one exists. No new validator, provider pass, TDF field, or history migration is introduced.

October 22 sparse assessment revision

Assessment output omits unaddressed KCs and misconceptions. Missing entries preserve existing scores and evidence; returned entries must support or contradict selected targets and cite learner evidence. The current KC plus three strongest neighbors and the separate four-misconception budget are unchanged. KC summaries contain demonstrated and unresolved requirements; incorrect claims belong only to misconception summaries. Subsequent scoring and instruction exclude incorrect-claim fields from KC evidence. Saved history keeps its existing shape, with an empty incorrect-claims list for new KC summaries; no history migration is needed. Quotations verify learner-source attribution and become retained response/character-span references when summaries change. Teaching uses the summaries rather than these references.

Generated instructional content is parsed from Markdown, sanitized, and presented under the central application theme. Instruction containers are not separately collected as messages alongside their primitives: grouping produces one displayed instruction, including one comparison/support region. The rendered surface test uses the real node renderer to verify one semantic table and its themed container for flat, grouped, and reloaded instruction nodes.

October 20 efficiency revision

Evaluation rules belong to the selected production rule set. For the agent and student instructional-cycle rule sets, this revision supersedes earlier full-target assessment and feedback-before-selection descriptions below. Assessment uses the current expectation KC plus its three strongest graph neighbors. Up to four misconceptions are ranked by embedding similarity to that KC, with an active misconception retained within the budget. The provider caches up to four sets of authored-text embeddings in memory, keyed by account, lesson, model, and exact text. No learner answers enter these vectors. Unassessed scores and evidence carry forward; distant transfer may therefore be detected later rather than on the current turn.

AutoTutor's progressive-scaffolding production rules retain full authored-rubric evaluation in one assessment request, without a current-KC prerequisite or assessment embeddings. The shared SPARC scoring adapter follows the runtime's rule-set selection; the bounded evaluation above is not a framework-wide SPARC rule.

Agent feedback and instruction generation overlap after durable assessment. Authorized SPARC provider calls release the connection's DDP queue before awaiting provider output, after authentication, quota, and policy-role checks. A transient instructional.feedbackStarted fact permits selection, while the cycle owner gates instructional persistence/display and turn completion on saved feedback. Student menus still follow feedback. Resume retains accepted decisions and content. Unchanged model gains/OET and untouched default expectations create no model-history records; comparison against model observations preserves recovery after an interrupted write.

Library retrieval reads bounded vector/metadata pages and checks question repetition in descending similarity order, stopping at the first acceptable candidate. Repetition remains enabled. Exposure/manifest ownership is unchanged. Joint explanation/question generation remains disabled because question lookup depends on the realized explanation.

Video search uses plain teaching-target text against transcript vectors at a provisional 0.80 cutoff; image search uses the complete need at 0.95 after a video miss. The controlled same-meaning passage test supports the change, but broader precision remains unmeasured. No catalog reindex, history rewrite, or model-setting change is required.

Accepted learner answers retain their review colors during practice and after reload. Only the selected multiple-choice or true/false option is green for a keyed correct answer or pink-red for an incorrect one. Text and cloze responses are green if that response's saved assessment increased any expectation coverage or reduced any misconception support; otherwise they are pink-red. Any positive gain qualifies, independently of the controller's meaningful-gain threshold. Pending or unassessed answers remain neutral. Colors come from each response's own saved assessment; later progress does not recolor earlier answers, and review never rescores history.

Text-response controls appear inline after the current tutor content only when the active move requires a typed answer, including cloze. Multiple-choice and true/false questions end with their answer options. The text field and Submit are hidden during initialization, generation, instructional menus, recovery, and completion. A newly active text field receives keyboard focus while the learner is following the latest content; completion Continue and recovery controls remain within the conversation. The Progress caption includes the localized turn count, followed by the expectation and misconception meter rows.

Instructional components arrive in the move's prescribed reading order: explanation, support, question, omitting components not requested by the selected move. Preparation and durable saving may occur in another order. Only the available prefix is visible; ready pieces may appear together without a timed pause. New administrative-removal checks do not hide already checked components. Removal receipts and earlier-content links retain their places in the sequence.

The explanation and a figure-loading status may appear while the image loads. The question and response controls wait until the actual image loads and decodes. Inline image or content-check failures block later pieces. Video support needs its checked player shell rendered, not playback or completion. Generation, assessment, saved identities, and retry/resume checkpoints are unchanged; no migration is required.

Automatic scrolling follows additions and media resizing while the learner is within 48 CSS pixels of the conversation bottom. Scrolling farther up preserves reading position and keyboard focus; following resumes on return to the bottom. Observers and scheduled callbacks are cleaned up on unmount. See the current application contract for the isolated and synthetic-browser regression commands and their limits.

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.

Shared reusable content: categorized policies retrieve feedback, explanations, written support, and questions by embedding before generating new text. A new visual request generates a brief and resolves it through video search, image search, then image generation as specified below. Accepted decisions replay their saved resource. Production decisions, assistance selection, assessment persistence, and numeric update ownership remain with their existing runtime components.

Local verification, October 19, 2026: the authorized full Meteor suite passed its 16 harness checks, 810 server tests (15 pending), and 1,122 browser tests (7 pending), with zero failures. Full-app typecheck and lint also passed. The consolidated assessment prompt was compared with its predecessor on 15 synthetic cases using the locally configured openai/gpt-6.1-sol model with medium reasoning: the predecessor met 14 of 15 predefined expectations and the revised prompt met 15 of 15 after relational wording was refined. These single-evaluation fixture results are initial acceptance evidence, not a student reliability estimate, mastery calibration, or production deployment.

Assessment descriptions retain demonstrated, incorrect, and unresolved authored requirements with stable learner-response citations. These are not additional KCs. The evaluator infers which authored requirements the actual question elicits and credits the full tested meaning of a correct contextual answer, respecting response format. It does not demand an unrequested justification or infer untested parts of the KC. Unresolved descriptions identify specific remaining authored meaning a follow-up could elicit, using the existing evidence fields and whole-KC coverage rubric. The assessment prompt consolidates its safeguards into five responsibilities: interpret the answer in question context; assess accumulated student evidence; distinguish student evidence from supplied information; report direction and coverage; cite evidence and identify remaining requirements. Coverage is the represented fraction of the minimum distinct substantive authored requirements, weighted equally, with 0 none, 0.5 half, and 1 all. A relation retains its participants, roles, and direction as one requirement; an unresolved defining connection is unaddressed rather than partial support for naming a participant. Examples and restatements add no requirements. Response-format safeguards are included only when that format occurs in the current response or retained dialogue. This makes the judgment explicit without claiming an empirically calibrated measure. 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.

The earlier link/highlight and lesson-only question repetition policy is superseded by the approved same-user no-repeat requirement above. Existing saved turns retain their original artifacts; new turns require eligible unseen content for every component.

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 through text links that wrap on narrow screens. Images and text can share a topic group. Administrators can inspect, revise in place, or permanently delete components. There are no retained content versions or exclusion controls; deleted content displays Administrative removal when a saved lesson is reloaded. There are no separate image/content tabs.

Thumbnails and expanded inspections display each saved component independently using the shared learner renderer. Learner sequence-readiness gates do not apply to catalog previews: questions and support remain visible without sibling explanations. Preview controls are read-only and cannot submit learner responses.

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. Following the October 24 production trial, feedback reuse uses 0.975; other text and images use 0.95. 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. SPARC_LIBRARY_SIMILARITY owns the reuse cutoffs, and sparcLibraryMinimumSimilarity selects the same primitive threshold for browser search and server acceptance. User correction, October 20: the question-repetition cutoff applies only to library retrieval. On a retrieval miss, generate the question once. The initial prompt uses earlier questions as reference context and asks for a different task or case through changed givens, relationships, conditions, or learner decisions, rather than paraphrasing or renaming. Preserve the selected target, assistance, response format, and alignment with actual support. Generated questions are accepted without a semantic-similarity veto or automatic regeneration. Content validation and administrative-removal checks remain enforced; publication rejection reports its actual reason. 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 presents the sixteen combinations through three compact columns: Same/Next KC, move composition, and question type. Same KC is the only default. Completing the other two choices generates the selected move directly on the selected KC. 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

The progress card updates scores and turn count as soon as the assessment batch is durably accepted, while feedback and the next instruction may still be in preparation. Failed assessment writes do not publish credit. Response controls and completion navigation continue to wait for the pending tutor turn to finish.

An interrupted instructional decision restores its accepted assessment context and candidate diagnostics before generating remaining components. Its decision checkpoint owns the decision state, and generated completion records do not repeat that state. Original and resumed executions therefore write identical component and completion records when they overlap; genuinely conflicting history remains rejected. Completed saved cycles are reused without rewriting them, and no history migration or learner reset is required.

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.

Consecutive outputs from the same speaker share one Tutor or Learner label. For administrators, each production output has a small asterisk inside its lower trailing edge. Hover, keyboard focus, or a tap shows its production and selection information in an overlay; Escape or clicking outside dismisses it. There is no separate Details row or added vertical padding. Ordinary learners do not receive these diagnostics. This presentation does not modify saved learning state.

Administrators can inspect sparc.staleQuestion in the Recoverable Warning Log after a rejected outdated choice. The record includes submitted/current/displayed question identifiers, the clicked node and cycle identifiers, the stale-state flags, and the button's presence/disabled/selected state captured before submission becomes pending. It contains no answer or instructional text. Existing authentication, rate limits, bounded validation, and administrator-only reads apply. Diagnostic delivery failure does not change the original rejection or saved progress. Reports are client-reported.

SPARC units omit the left practice-tools menu. The top row keeps the return button on one line at its natural width. Long lesson titles wrap in the remaining space, with at most two visible lines, within the header above the learning canvas.

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 adapted categories identify the knowledge and supply the instructional learning-process focuses. For a misconception, they describe the corrective knowledge. Do not add “fact” merely because an explanation contains factual statements, or “model” merely because a procedural rule could be explained; use the selected KC's assigned category rather than reclassifying it during generation.

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. Use four instructional compositions: question; explanation and question; explanation with written example/comparison and question; explanation with visual support and question. Each composition has text, cloze, multiple-choice, and true/false versions, giving sixteen move versions. Differentiate them by the seven target categories, giving 5 groups × 4 compositions × 4 response formats × 7 categories = 560 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 text, a single typed cloze completion, multiple choice, or a true/false judgment. 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:

These twelve distinct assistance settings, shared by the written and visual support compositions, apply across all seven content categories and all five transition groups. They are explicit complete-move values for each composition and response format. The multiple-choice variant is 0.50 logits above the corresponding text-response variant. OET and the learner-expectation floor are unchanged. Selection temperature was separately doubled to 0.2. These calibrations were approved October 18, 2026.

The library service randomizes multiple-choice option order for each assignment using stable hash ranks of the assignment identity and option IDs. This applies to generated and retrieved questions and reproduces the same order after an interrupted first save. Learner history and exposure records retain the ordered option list, including its stable IDs, labels, and answer key; the shared catalog's original list is unchanged. Reloads preserve the saved order, including for questions saved before this change. Answer submission remains bound to the option ID rather than its display position.

Cloze and true/false question writing and assessment

Cloze uses the existing text response box without a word bank or exact-match key. Require exactly one uniform _____ blank for a substantive word or short phrase. The completion must require understanding the statement, not merely grammar, word shape, or a familiar phrase. Supply clear context, avoid grammatical and answer-length clues, prefer an end-position blank when natural, and specify numerical units/precision when needed.

A correct meaningful completion can demonstrate understanding of the entire statement and its associations, relationships, or conditions. Award the semantic coverage demonstrated in context rather than crediting only the isolated missing word. Distinguish this from independently constructing or explaining the statement. Preserve and cite the actual typed response; the supplied stem is context, not learner-authored text. Accept equivalent wording and ordinary typos. Do not add a fixed cloze ceiling, multiplier, or automatic full-credit rule.

True/false asks for one clear proposition judged with exactly two buttons: true/True then false/False. This order is fixed and is exempt from MC assignment shuffling. Avoid compound claims, double negatives, ambiguous qualifiers, trivia, and wording tricks. Use plausible conceptual errors for false statements and request varied truth values without predictable alternation; no new truth-balancing controller or correction stage is introduced. False rejects the displayed statement rather than endorsing it or establishing every possible alternative. Correctness remains separate from semantic KC coverage.

The shared instructions use original wording informed by Waterloo's assessment guidance and the true/false and completion sections of the Kansas Curriculum Center guide. Structural validation enforces the single blank and exact binary answer structure; it does not certify substantive item quality.

Saved move identities identify the format. Typed and selected responses bind to the saved question and retain their actual format in scoring history. Generated and retrieved questions use the same format-specific validation and exact-format matching. Existing saved text and MC questions retain their content and order; this extension adds no required authored TDF fields, new unit type, or data migration.

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 84 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 112 reusable primitive specifications: four compositions × four 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 KC text identifies the knowledge; its assigned KLI category supplies the learning-process focuses. Do not infer a separate recall-only, recognition-only, application-only, or explanation-only classification from the KC wording. Those can be overlapping ways to practice and demonstrate the same knowledge. The approved mapping is:

This mapping is the MoFaCTS adaptation of KLI Table 4 and its discussion, not an assertion that our seven combinations are the seven rows in the paper's Table 3. Each constituent contributes its focus. Combine the focuses into one coherent move within the selected composition and response format, rather than separate mini-lessons or every possible method on each turn. A principle combines a rule with its explanatory model. Do not add category assignments merely because instructional prose includes factual statements or could include a rationale; broad fact–model–rule assignment is not required.

The four rows determine support: question alone, explanation plus question, explanation plus written support plus question, or explanation plus visual support plus question. For rules, practice on structurally analogous new cases supports induction/refinement; for models, elicit reasoning about the represented relationships; for facts, retrieve the selected association without merely copying visible wording. Multiple-choice and true/false express the selected focuses through judgments or discrimination; they do not establish independently generated explanations. Cloze retains whole-statement semantic interpretation. Naming a model alone does not establish relational understanding, reciting a rule alone does not establish generalization, and one correct answer does not establish fluency. These instructions introduce no new scoring dimension, fixed credit rule, assistance adjustment, authored field, or production family. Existing semantic evidence scoring and assistance values remain in force.

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 the saved figure description as text and refer to that content. Dialogue requests do not fetch or attach image pixels; private image rendering and the system-owned image-generation endpoint remain separate. References to labeled support use its actual visible heading, such as "the comparison" for Comparison, rather than a scenario-based name. "Below" is optional when the heading identifies the support clearly; any positional reference follows the learner's reading order of explanation, support, then question. 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 112 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 112 specifications is used. Keep all sixteen composition/format versions in the student-choice wiring, displayed through separate move and question-type columns. The question types are text answer, fill in the blank, multiple choice, and true/false. Place the independent Same/Next KC choice first, defaulting to Same KC. Completing the move and question-type choices starts that move on the selected KC in one event; do not add a target-category 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. Authorize execution through server-verified lesson membership for enrolled students and demo participants; client visibility is not authorization. Keep library administration, credentials, unrelated private assets and other-user records restricted. 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; the KC remains independently selectable before completing the instructional choices. A combined Next KC submission binds the selected move to the saved offered next target without an intervening menu or assessment, 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 is 0.2. 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 is retrieved or generated before dependent explanation/question generation, which uses its saved description as text without sending image pixels to the dialogue model. 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

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

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

At the October 14 acceptance, the two new policies used the existing rule engine, target progression, history-derived model, feedback stage, component generators, and server figure library. That version contained 210 automatic instructional productions plus evaluation, feedback, and stop (213 total); the student set contained three shared productions, five target-transition menus, 84 category-specific instructional choices, and two next-KC productions (94 total). Its six move definitions and seven categories supplied 42 shared specifications. These are historical counts; the current visual-support extension and four response formats are specified above.

Both fresh Confidence Interval ZIPs are saved under C:\dev\mofacts_config\SPARC 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.

Optional catalog-based video support

The production can select a visual-support move, separately from written examples, comparisons, and tables. All four response formats remain available. Written and visual support use the same complete-move assistance values. The video stays on YouTube; SPARC stores its transcript and a start/end interval without downloading its media.

Catalog preparation is an explicit administrator action: choose a package in Content and click Build video catalog. The build action and KC-limit control appear only for a selected SPARC package or condition with an authored AutoTutor page; other lesson types are rejected by the server as well. First KCs (blank = all) can limit preparation to the first N authored targets; failed targets count toward this limit. It is never performed automatically on upload, package update, or lesson startup. For the initial version, each authored expectation and misconception seeds one search using its complete authored KC text unchanged, yielding only the top captioned, embeddable video. Package titles and condition labels are omitted from the query; KCs are not summarized or screened. Repeated videos share a transcript. Supadata fetches existing captions only; unavailable captions, empty searches, and transcripts without useful passages are reported as failures for the current build without trying another video. They are not persistent exclusions and may be tried again by a later explicit build. Successful preparation checkpoints remain reusable.

Before instruction, the configured dialogue model identifies coherent passages of at most 30 seconds through caption IDs. Code determines their timestamps and stores their embeddings in the shared instructional library, with originating package/KC provenance. Video passages are included in library listings and topic/subgroup browsing. Their thumbnails use YouTube poster images, and playback opens at the saved snippet interval. These browsing groups do not restrict instructional retrieval. Those origins do not permanently assign clips to KCs. Saved preparation checkpoints allow the explicit action to resume without repeating completed downloads or embeddings.

During instruction, the visual content call describes what the learner needs to see. The system embeds teaching-target prose for video search, then the complete instructional need including the reusable visual brief for image search after a video miss, and generates an image only when both searches complete successfully without an eligible match at or above the configured relevance cutoff (video 0.80 provisionally, image 0.95). Both searches use the same embedding model with separate query representations. Video eligibility retains the existing explicitly authored contentLanguage match: packages omitting that optional metadata have no eligible videos, without inferring a language or changing their package files. Missing packages, malformed language, and catalog read failures remain errors. Video source vectors describe saved transcript passages; image source vectors retain their saved instructional needs. Service, storage, validation, and embedding errors stop the sequence and are never treated as empty results. The dialogue model returns no video ID and never chooses among catalog resources.

The actual returned resource grounds the explanation and question. A video transcript cannot establish unseen visual details. New visual requests follow this ordering even when cached rich primitives exist. Accepted learner decisions resume their original resource; an interrupted image generation retains its saved brief. The lesson-authorized visual resolver shares the authenticated OpenRouter rate limit. No live video search, transcript segmentation, visual inspection, or frame-analysis pipeline runs in instruction. Private incomplete supported prompts retain their image-only behavior.

The player presents the stored interval in a themed frame with native captions and controls. History retains the selected clip and question; administrative deletion prevents reuse and displays Administrative removal on reload without rewriting learner records. A playback failure is reported inline and does not silently replace the clip or advance the lesson.

Catalog preparation, browsing and curation remain admin-only. Authorized lesson participants may use saved video resources through the runtime resolver. Credential-free contracts and app checks are separate from live catalog/playback acceptance. See the repository's video setup and implementation contract for server-only keys, preparation behavior, operating bounds, and verification commands.

Generated instructional-text size thresholds are advisory. Responses exceeding them are retained unchanged and produce text-free diagnostic entries in the Recoverable Warning Log. Size checks do not fail the move, regenerate content, or present a preparation/retry message. The first generated explanation proceeds using the selected KC and saved support description.

Compact learner presentation

Mobile image gestures use the browser's native scrolling, panning, and zooming. A swipe can start on the image to scroll the conversation, and an enlarged image can be panned left and right. The shared theme must not restrict images to pinch-only gestures.

Learner reply bubbles preserve the response's line breaks without rendering template whitespace as extra lines. While the tutor works, a compact spinner displays its current activity: assessment, feedback, instructional support, explanation, question, or visual support. The progress card overlays the conversation with transparency around its opaque card in both open and closed states. The conversation owns scrolling and the positioning of its descendants, including visually hidden accessibility text; focusing an answer must leave the outer surface stationary, Progress visible in the top right, and the conversation at its available height. Touch devices automatically focus the response region; the learner taps the text field to open the keyboard. Multiple-choice and true/false selections show answer-key correctness immediately while the tutor prepares its assessment and feedback. This immediate review does not write assessment scores or alter instructional progression.

Generated text reading level (2026-10-21)

Source now supports unit.sparcsession.readingLevel: unbiased (also the default when omitted), junior-high-freshman (grade 6), high-school-freshman (grade 9), or college-freshman (first year). The biased options add audience directions to learner-facing text production, including feedback, explanations, questions/choices, written support, and figure descriptions. They simplify vocabulary and sentence structure while preserving concepts, qualifications, reasoning, and assistance. Scoring and instructional control do not receive the directions; image generation, existing media, and authored content are unchanged. Prompt guidance does not guarantee a measured reading grade.

Shared instructional text is reused only within the same reading level; stored entries lacking this field remain unbiased. Saved decisions continue to replay accepted content. Use a separately titled lesson for comparisons. See the public repository's docs/sparc-instructional-cycle.md for the implementation contract. This source change alone does not establish production deployment or learner verification.

Library inspection when an image cannot load

The instructional library keeps an entry's existing inspection control available while its image is loading or its authorized file read fails. The loading/error remains visible, and inspection exposes the same revision and permanent-deletion controls as a successfully loaded image. Selection does not depend on image bytes. Administrative removal notices and saved learner histories retain their existing contracts.