vibe64 0.1.36 → 0.1.37

package/docs/training-content.md

@@ -120,17 +120,133 @@ topic with every step kind; the copyable template is `docs/templates/learn-topic
   - `choice` — `question` (at most 2000 characters), 2–8 `options` and
     `answer`, a non-empty list of unique option indexes (0-based, in range).
     The learner passes by selecting exactly the answer indexes.
+  - `review` — the learner's own AI reviews their practice work against the
+    author's `rubric` (at most 600 characters, shown to the learner as the
+    step's check line) when the learner presses **Check my work**. It needs
+    the lesson's `exercise`. `evidence` (optional, default `["changes"]`) is
+    `["changes"]` or `["changes", "conversation"]`; see
+    [Review checks](#review-checks).
   - `self` — the learner ticks **Done** after doing the step.
   - `none` — reading only; cannot be `required`. The learner may press
     **Mark as done**, which records a learner-origin `read` pass (a bonus that
     never counts toward completion).
   A kind declares only its own fields; anything else is rejected.
 
-**Check verdicts are final.** v2 has no rubric and no AI grader: an automatic
-check or the choice comparator decides, otherwise the learner ticks a `self`
-step (or marks a `none` step read). Colleague teaches and explains but never passes a step. Write step bodies
+### Beats: the step bar walks the learner through a step
+
+A step may end its body Markdown with a fenced `beats` block. The lesson step
+bar (yellow, above the page in Learn mode) plays the beats one line at a time
+while the learner stays where they are; the reader never shows the block.
+
+````md
+```beats
+show preview: This is your app, running.
+show chat: This is the coding chat. You ask for changes here.
+do send-message: Ask it: "Make the heading green"
+do agent-finished: Wait while the agent works.
+do reload-preview: Press Reload preview to see the change.
+check done: Press Done when the heading is green.
+```
+````
+
+One beat per line: `<show|do|check> <target>[ <path>]: <text>`.
+
+- `show <place>` points at a place and moves on by itself after 5–12 seconds
+  (longer text stays longer; never with reduced motion, where the learner
+  presses Next). Text is at most 160 characters.
+- `do <place|action>` waits for the learner: to be at a place, or to do an
+  action (`send-message`, `agent-finished`, `file-opened <path>`,
+  `app-pressed`, `colleague-minimised`). `do send-message` text holds exactly one quoted prompt (at
+  most 500 characters). Only `file-opened` takes an argument, a relative
+  practice project path without `..`. A do beat completes when the page shows
+  its place, or when its activity happens in the lesson's practice project
+  after the beat began (`send-message`: a message accepted in the chat;
+  `agent-finished`: the agent's turn ends; `file-opened`: that file opens in
+  Files; `app-pressed`: the practice App's button; `colleague`, `save`,
+  `reload-preview`: Colleague opens, a Save succeeds, the Preview reloads;
+  `learning`: the learner presses **L**, which counts when they are back in
+  Learn; `colleague-minimised`: Colleague closes or minimises).
+  **Do it for me** does it for the learner (sending a `send-message` prompt as
+  the learner's Main chat message, stored as sent by the lesson), except Save,
+  `agent-finished`, `app-pressed`, `colleague-minimised` and `learning` (which
+  it only points at). A `check done` step whose do beats were
+  all detected is recorded done without a press.
+- `check <auto|done>: <text>` is the step's own check (`auto` for
+  `check.kind:"auto"`, `done` for `self`): at most one, and the last line.
+  `check review` (for `check.kind:"review"`) takes no text: the bar shows the
+  step's `check.rubric` from `lesson.json`, its single source.
+- Places: `preview`, `dashboard`, `database-erd`, `database-data`, `files`,
+  `changes`, `git-log`, `session-info`, `architecture`, `learning` (the **L**
+  button), `lesson` (the Lesson tab), `chat` (the coding chat), `colleague`,
+  `courses`, `lesson-bar` (the bar itself), `save` and `reload-preview`.
+  `dashboard` and `lesson-bar` can only be shown.
+- 1–8 beats. Only `lesson`, `lesson-bar`, `courses`, `learning`,
+  `colleague`, `colleague-minimised` and `check done` work in a lesson without an `exercise`; every
+  other beat needs the practice project.
+- A step with beats has no `guide`; **Show me** plays its beats from the first.
+
+`vibe64 training validate` rejects an unknown kind, place or action, an
+argument other than a `file-opened` path, a check that does not match the
+step's check kind, a second or non-final check, a block that is not closed or
+does not end the body, and beats together with a `guide`. Back and Next in the
+bar move by beat into the neighbouring steps; after the last beat the bar shows
+the step's own verdict control (Done, Mark as done, Check my work, or Answer in
+Step for a choice) and Next step. **Step** (≡) on the bar opens the whole step
+text under it in one click, so a beat never needs to repeat the body. Steps never advance by themselves.
+
+**Check verdicts are final.** Verdicts come from the step's declared check: an
+automatic check, the choice comparator, a review check (the learner's own AI
+judging their work against the author's rubric), or the learner's tick on a
+`self` step (or mark on a `none` step). A pass is never replaced. Colleague
+teaches and explains but never passes a step and never runs a review. Prefer
+an automatic check where a deterministic check can decide; write step bodies
 so a learner can follow them without AI.
 
+### Review checks
+
+A review step judges work that a deterministic check cannot, for example "the
+heading is green and nothing else broke":
+
+```json
+{ "id": "green-heading", "title": "Make the heading green",
+  "body": "steps/green-heading.md",
+  "check": { "kind": "review", "rubric": "The heading is green and nothing else broke.",
+             "evidence": ["changes", "conversation"] },
+  "required": true }
+```
+
+- The rubric is the only requirement. Write it as what the finished work
+  shows, in words the learner understands; it is shown to the learner and to
+  Colleague.
+- Evidence `changes` is the practice session's work against the commit the
+  lesson started from, uncommitted work included: the changed files with
+  added/removed line counts and their diff, at most 60,000 characters (20,000
+  per file). Binary files, larger files and files beyond that budget are
+  listed without their text; agent guidance folders (`.agents`, `.claude`,
+  `.codex`, `.opencode`) are left out. `conversation` adds the last 20 turns
+  of the session's Main chat (the learner's and the agent's text, at most
+  40,000 characters). Work the coding agent did at the learner's request
+  counts unless the rubric says the learner must do it themselves.
+- **Check my work** runs only from the learner's own browser, on the
+  learner's own AI account: the Helper route of their workflow in **AI
+  Accounts → Model routing** (workload `lesson_review`, input at most 160,000
+  characters, 180 seconds). Vibe64 never pays for or resells it.
+- The reviewer returns Passed or Not yet, a comment (at most 600
+  characters), a hint for Not yet (at most 300) and up to six rubric points.
+  The result is saved as a `review` step result; Passed is final.
+- Nothing is recorded, and nothing runs, while the coding agent is working
+  ("Wait until the agent finishes") or when there are no changes yet ("No
+  changes yet"). Pressing again with unchanged evidence returns the saved
+  review without another AI call. A missing Helper route, a provider error or
+  timeout, a reply outside the fixed output schema or unreadable evidence
+  records nothing; the learner tries again.
+- The evidence is data, never instructions: the reviewer is told to follow
+  only the rubric, so a prompt injected into the learner's project can at most
+  pass the learner's own practice step.
+- Only lessons started after a review-capable release record the commit their
+  practice session started from; an older attempt is asked to restart before
+  its work can be reviewed.
+
 Choice answers stay on the server. The lesson descriptor is never served to a
 browser: a step body, `notes`, visual SVG/controller/asset or exercise file
 cannot be any v2 lesson descriptor of the topic (for example, an exercise
@@ -584,11 +700,20 @@ is the one in progress, `lessonTitle` is filled only with `includeTitle`, and
 
 Step results (`step-progress.json`, schema version 3) belong to the attempt in
 progress: `{learnerId,revision,attemptId,lesson,results,receipts}`, at most 64
-results. A result's `kind` is `auto`, `choice`, `self` or `read` (a `none`
-step the learner marked done), matching the pinned step's check. A new attempt
-starts with none. `readStepProgress({actor,attemptId?})`
+results. A result's `kind` is `auto`, `choice`, `review`, `self` or `read` (a
+`none` step the learner marked done), matching the pinned step's check. A
+`review` result has origin `check`, evidence `{reviewId,evidenceHash}` and
+`review:{comment,hint?,points?}` (single-line text; only a review result has
+it). A new attempt starts with none. `readStepProgress({actor,attemptId?})`
 and `readAttemptRecord({actor,attemptId})` read them.
 
+`runReviewExclusive({actor},operation)` serializes one learner's reviews with
+`review.lock` (a second review while one runs is refused with
+`VIBE64_TRAINING_REVIEW_BUSY`). It gives the review owner its private Helper
+root `review-helpers/` and the retained Helper receipt `review-helper.json`
+`{schemaVersion:1,learnerId,helper}` (`helper` is `null` once cleaned up), so a
+review that stopped part-way is cleaned before the next one starts.
+
 The published `20261008-learning-practice-history` upgrade reads vibe64 0.1.35
 version 1 progress through the frozen `practiceHistoryReader.js`
 (`readState`, `readExerciseProjectScope`), moved unchanged from the earlier
@@ -596,10 +721,19 @@ learner state; the live store no longer reads that format.
 
 The same internal store adds `beginPreparation({actor,attemptId,expectedRevision})`,
 `recordPreparationReady({actor,attemptId,initialSessionId,expectedRevision})` and
-`recordPreparationFailure({actor,attemptId,initialSessionId,expectedRevision,stage,code,message})`.
+`recordPreparationFailure({actor,attemptId,initialSessionId,expectedRevision,stage,code,message})`
+and `recordPreparationStart({actor,attemptId,initialSessionId,expectedRevision,startCommit})`.
 These are observation writers, not a provisioner, learner action or authority to
 create an arbitrary project. Only an admitted server caller may compose them.
 
+When the session owner refuses the practice session because the learner has no
+usable AI yet (`vibe64_assistant_workflow_unavailable` or
+`vibe64_assistant_role_unconfigured`), preparation records and throws
+`VIBE64_TRAINING_PRACTICE_AI_REQUIRED` (409) with learner wording that asks them
+to set up their AI and continue the same lesson. `lesson.read` and
+`learning.read` return the saved failure's `code` and `message`, so the step bar
+and Courses offer the AI setup instead of beats or a generic error.
+
 An untouched `{phase:"reserved"}` remains valid and contains no session identity.
 Explicit begin atomically saves `{phase:"preparing",initialSessionId}` before any
 external effects. The immutable ID is `training-<attempt-UUID>`, validated by the
@@ -617,6 +751,11 @@ A failure records `preparing` with `failure:{stage,code,message}`; stages are
 `project`, `session` or `setup`, code is at most 64 characters and the single-line
 recovery message at most 512. It retains the ID and removes any old ready time.
 Begin replays do not clear failures. A fresh successful observation can clear one.
+Preparation records the verified exercise commit as `startCommit` (a 40- or
+64-character Git object ID) just before it creates the practice session from
+it; a retry before the session exists records it again, a ready attempt keeps
+it, and every later phase carries it. A review check reads the learner's
+changes against it. Attempts prepared before this field existed have none.
 Matching observation replays precede revision checking and return `replayed:true`
 without writing; a different stale observation conflicts rather than overriding
 newer state. No project/session effect executes inside the user-state lock.

package/node_modules/@local/vibe64-execution/src/server/hostProfile.js

@@ -0,0 +1,12 @@
+import { createRequire as __vibe64CreateRequire } from 'node:module';const require=__vibe64CreateRequire(import.meta.url);
+import h from"node:path";import l from"node:process";import{isMainThread as u}from"node:worker_threads";var n=Symbol.for(
+"vibe64.hostProfile"),t=Symbol.for("vibe64.hostProfile.previousUmask"),b=["runtimePackRoot","sharedCacheRoot","execHelpe\
+rPath"],s=Object.freeze({runtimePackRoot:"",sharedCacheRoot:"",execHelperPath:"",sharedGroupAccess:!1});function a(e){u&&
+(e&&!(t in globalThis)?globalThis[t]=l.umask(7):!e&&t in globalThis&&(l.umask(globalThis[t]),delete globalThis[t]))}function T(e=null){
+if(e===null)return delete globalThis[n],a(!1),s;let c=Object.keys(e).filter(o=>!(o in s));if(c.length)throw new TypeError(
+`Unknown host profile setting: ${c.join(", ")}.`);let r={...s,...e};for(let o of b)if(typeof r[o]!="string"||r[o]&&!h.isAbsolute(
+r[o]))throw new TypeError(`Host profile ${o} must be an absolute path or empty.`);if(typeof r.sharedGroupAccess!="boolea\
+n")throw new TypeError("Host profile sharedGroupAccess must be true or false.");let i=Object.freeze(r);return globalThis[n]=
+i,a(i.sharedGroupAccess),i}function f(){return globalThis[n]||s}function g(){return f().sharedGroupAccess?{inheritingDirectory:1528,
+directory:504,file:432}:{inheritingDirectory:448,directory:448,file:384}}function y(){return f().sharedGroupAccess?"0007":
+""}export{T as configureVibe64Host,f as vibe64Host,y as vibe64ProcessUmask,g as vibe64SharedModes};

package/node_modules/@local/vibe64-terminals/package.json

@@ -18,6 +18,7 @@
     "./shared/launchPreviewProtocol": "./src/shared/launchPreviewProtocol.js",
     "./shared/assistantWorkPlan": "./src/shared/assistantWorkPlan.js",
     "./server/retainedConversationHelper": "./src/server/retainedConversationHelper.js",
+    "./server/practiceAgentGuidance": "./src/server/practiceAgentGuidance.js",
     "./server/assistantClaudeCommandUpgrade": "./src/server/assistantClaudeCommandUpgrade.js",
     "./server/assistantClaudeDeliveryUpgrade": "./src/server/assistantClaudeDeliveryUpgrade.js",
     "./server/assistantPlanProgressUpgrade": "./src/server/assistantPlanProgressUpgrade.js"

package/node_modules/@local/vibe64-training/package.json

@@ -21,6 +21,8 @@
     "./server/installed-catalogue": "./src/server/installedCatalogue.js",
     "./server/routes": "./src/server/registerRoutes.js",
     "./server/step-checks": "./src/server/stepChecks.js",
+    "./server/step-evidence": "./src/server/stepEvidence.js",
+    "./server/step-review": "./src/server/stepReview.js",
     "./server/code-authorship": "./src/server/codeAuthorship.js",
     "./server/code-save-owner": "./src/server/codeEditorActions.js",
     "./server/step-actions": "./src/server/stepActions.js",
@@ -33,6 +35,7 @@
     "./shared/presentation-schemas": "./src/shared/presentationSchemas.js",
     "./shared/learning-guidance": "./src/shared/learningGuidance.js",
     "./shared/guide-targets": "./src/shared/guideTargets.js",
+    "./shared/beats": "./src/shared/beats.js",
     "./client/guide-overlay": "./src/client/TrainingGuideOverlay.vue",
     "./client/guide": "./src/client/trainingGuide.js",
     "./client/course-progress": "./src/client/courseProgress.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe64",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "private": false,
   "description": "Run Vibe64 against the current project.",
   "type": "module",
@@ -126,8 +126,8 @@
     "figures": "6.1.0",
     "find-my-way": "9.9.0",
     "flatted": "3.4.4",
-    "genesis-compiler": "1.9.3",
-    "genesis-stack": "1.2.1",
+    "genesis-compiler": "1.10.0",
+    "genesis-stack": "1.3.0",
     "get-port": "7.2.0",
     "get-stream": "9.0.1",
     "glob": "13.0.6",